Introduction to PM Programming 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().