Introduction to PM Programming - Jun 1994

From EDM2
Jump to: navigation, search

Written by Larry Salomon Jr.

Introduction

The purpose of this column is to provide the readers out there who are not familiar with PM application development the information necessary to satisfy their curiousity, educate themselves, and give them an advantage over the documentation supplied by IBM. Of course, much of this stuff could probably be found in one of the many books out there, but the problem with books in general is that they don't answer the questions you have after you read the book the first time through.

I will gladly entertain feedback from the readers about what was "glossed over" or what was detailed well, what tangential topics need to be covered and what superfluous crap should have been removed. This feedback is essential in guaranteeing that you get what you pay for. :)

It should be said that you must not depend solely on this column to teach you how to develop PM applications; instead, this should be viewed as a supplement to your other information storehouses (books, the network conferences, etc.). Because this column must take a general approach, there will be some topics that you would like to see discussed that really do not belong here. Specific questions can be directed to the Scratch Patch, where an attempt to answer them will be made.

Last Month

Last month, we explored more of the PM APIs and began looking into the WC_ENTRYFIELD window class. This month, we will continue where we left off, and will continue in directions unknown; unknown, that is, unless you continue reading.

More Messages

Let us first begin by looking at the remaining entryfield messages.

Message and Purpose Parameters Returns
EM_CLEAR

Send to delete the selected text in the entryfield

param1

ulReserved (ULONG)

Reserved, 0

param2

ulReserved (ULONG)

Reserved, 0

Returns

bSuccess (BOOL)

TRUE - successful completion

FALSE - an error occurred

EM_COPY

Send to copy the selected text to the clipboard

param1

ulReserved (ULONG)

Reserved, 0

param2

ulReserved (ULONG)

Reserved, 0

Returns

bSuccess (BOOL)

TRUE - successful completion

FALSE - an error occurred

EM_CUT

Send to copy the selected text to the clipboard and then delete it. This is equivalent to sending an EM_COPY message followed by an EM_CLEAR message

param1

ulReserved (ULONG)

Reserved, 0

param2

ulReserved (ULONG)

Reserved, 0

Returns

bSuccess (BOOL)

TRUE - successful completion

FALSE - an error occurred

EM_PASTE

Send to paste text from the clipboard into the entryfield. If there is selected text, it is replaced with the pasted contents; otherwise, the text is inserted at the current cursor position

param1

ulReserved (ULONG)

Reserved, 0

param2

ulReserved (ULONG)

Reserved, 0

Returns

bSuccess (BOOL)

TRUE - successful completion

FALSE - an error occurred

EM_SETFIRSTCHAR

Send to set the zero-based index of the first character visible in the entryfield

param1

sFirstChar (SHORT)

0 - based index of the first visible character

param2

ulReserved (ULONG)

Reserved, 0

Returns

bSuccess (BOOL)

TRUE - successful completion

FALSE - an error occurred

EM_SETINSERTMODE

Send to set the insert mode of the entryfield

param1

bInsert (BOOL)

TRUE - insert mode

FALSE - overwrite mode

param2

ulReserved (ULONG)

Reserved, 0

Returns

bOldState (BOOL)

TRUE - the entryfield was previously in insert mode

FALSE - the entryfield was previously in overwrite mode

EM_SETREADONLY

Send to set the read-only state of the entryfield

param1

ubReadOnly (BOOL)

TRUE -the entryfield should be read-only

FALSE -the entryfield should be editable

param2

ulReserved (ULONG)

Reserved, 0

Returns

bOldState (BOOL)

TRUE - the entryfield was previously read-only

FALSE - the entryfield was previously editable

EM_SETSEL

Send to set the current selection of the entryfield

param1

sMinSel (SHORT)

The first 0-based point of selection

sMaxSel (SHORT)

The last 0-based point of selection

param2

ulReserved (ULONG)

Reserved, 0

Returns

bSuccess (BOOL)

TRUE - successful completion

FALSE - an error occurred

EM_SETTEXTLIMIT

Send to set the maximum number of characters the entryfield can contain

param1

usLimit (USHORT)

maximum number of characters allowed

param2

ulReserved (ULONG)

Reserved, 0

Returns

bSuccess (BOOL)

TRUE - successful completion

FALSE - an error occurred

Conceptually Speaking

Of Selections, Anchor Points, and Cursor Points

What is a selection? A selection is an area that is defined by the user. Any "objects" (defined by the context of the selection) that are contained within the selected area are defined to be selected. Any selection consists of two things: an anchor point, which is defined to be the point where the selection was started and is fixed, and a cursor point, which is defined to the be place where the cursor/pointer currently is and moves with the cursor/pointer. A selection is performed, according to CUA guidelines, using either the mouse or the keyboard. Using the mouse requires the user to press one of the buttons (usually the first) and hold the button while moving the mouse. When the selection has been made, the button is released. Using the keyboard, the user presses the Shift key while moving the cursor with the arrow keys. When the Shift key is released, the selection is completed.

There are other semantics associated with selections when using the mouse, but we will not discuss them here. The point of these definitions is to allow you to understand the purpose of the EM_SETSEL message. Its two parameters are slightly different that what was discussed above; if the anchor point is always before the cursor point ("before" is used, since the entryfield can be considered as being a one-dimensional stream of characters), then sMinSel is the anchor point and sMaxSel is the cursor point, otherwise the two are reversed.

Clipboard

For those of you who have no GUI experience, the clipboard is a temporary storage place for placing items to be used later in the same or other applications. Items of predefined, or application-defined formats, may be placed on the clipboard.

Its capabilities and interfaces are beyond the scope of this discussion, but it is important that you know what it is.

Text Limits

When you create an entryfield, by default it allows up to 32 characters maximum to be entered. If, however, you need more (or less) than this amount, you must first send it an EM_SETTEXTLIMIT message, which tells the entryfield to allocate more or less memory for its use.

Notifications

The entryfield also sends notifications to its owner. These notifications are listed below.

  • EN_CHANGE - this is sent whenever the entryfield's contents have changed.
  • EN_KILLFOCUS - this is sent whenever the entryfield is losing the input focus.
  • EN_MEMERROR - this is sent whenever the entryfield cannot allocate memory in response to an EM_SETTEXTLIMIT message.
  • EN_OVERFLOW - this is sent whenever an attempt to insert or paste more text than is allowed by the text limit is made.
  • EN_SCROLL - this is sent whenever the entryfield has scrolled from a call to WinScrollWindow(), the cursor moving beyond the visible area, or when the text has changed.
  • EN_SETFOCUS - this is sent whenever the entryfield is gaining the input

focus.

The notifications you will use the most often are the EN_CHANGE, EN_SETFOCUS, and EN_KILLFOCUS ones, although the others have their uses.

Summary

This month, we finished looking at the entryfield messages, the notifications sent by the entryfield, and the concepts associated with the new messages. Next month, we will begin looking at the WC_LISTBOX class, and will continue with nameDlgProc().