<:s><:#284,9360>Creating user controls- not for the faint of heart
<:s><:#284,9360>
<:s><:#1136,9360>There are two basic types of user controls, simple and complex. The simple type does not require one to create any screens, as Gpf supplies a default. The tougher one has the "extended" feature of the default screen turned on, and one must create the entire
infrastructure to display and make use of such a dialogue.
<:s><:#284,9360>
In both cases the developer is responsible for the entire behavior of the user control, which can be very simple for static-like entities, or a real pain for interactive objects (for example, building a genuine multi-column list box, or formatted data entry
fields, or SQL-wise controls, etc.)
<:s><:#284,9360>
<:s><:#284,9360>This package contains:
<:s><:#568,9360> a. a minimal user control, similar to STATIC TEXT controls, but auto sizing and with fancy shadowing. No extended dialog is required.
<:s><:#568,9360> b. the same control with an extended dialog, permitting the Gpf developer to specify some extra properties.
<:s><:#284,9360>
<:s><:#284,9360>A. The Minimal Control
<:s><:#289,9360>We will call this control<+!> "SHADOW"<-!>. You will need the following files:
<:#284,9360> GPFUC.H do not write, included with the Gpf product
<:#284,9360> SHADOW.H you write this, though not strictly required
<:#852,9360> SHADOW.C includes GPFUC.H, SHADOW.H, and is the driver code. It must contain at least (2) entry points expected by Gpf, and an entire window procedure for the control. This window procedure will be fairly simple.
<:#284,9360> SHADOW.DEF linker information, and exports the required entry points
<:#284,9360> SHADOW.MAK a makefile, necessary if you hate to type a lot
<:s><:#284,9360>
<:s><:#284,9360>When all is said and done you will have created:
<:#284,9360> SHADOW.DLL this will need to be moved to one of your LIBPATH locations
<:#284,9360> SHADOW.LIB IMPLIBed, nice to make, but again not strictly necessary
<:#284,9360> SHADOW.OBJ which can be discarded after the DLL is generated
<:s><:#284,9360>
<:s><:#568,9360>For this simple example we will not use a SHADOW.H, all source will be in SHADOW.C. What is required in this file?
<:s><:#284,9360>For the purposes of Gpf, two and only two exported functions
<:s><:#240,9360><:f,QCourier,>DESCRIPTION 'any text you want'
<:#240,9360><:f,QCourier,>PROTMODE<:f>
<:#284,9360>DATA PRELOAD MULTIPLE NONSHARED
<:s><:#240,9360><:f,QCourier,>CODE PRELOAD
<:s><:#240,9360><:f,QCourier,>EXPORTS
<:s><:#240,9360><:f,QCourier,> RegisterShadow @1
<:s><:#240,9360><:f,QCourier,> fnwpShadow @2<:f>
<:s><:#284,9360>
<:#568,9360>SHADOW.DEF is now complete, so now let's write and file away SHADOW.MAK. <[>In this example we are using IBM C\SET 2 in "c" mode]. The entire text follows
<:s><:#284,9360>Nothing left to do except the "C" file.
<:s><:#284,9360>Notes about the two exported functions:
<:s><:#284,9360>1. RegisterShadow()
<:s><:#284,9360>Three major things are done here:
<:#284,9360> - get a HAB
<:s><:#568,9360> - register this class, including its name and window procedure (fnwpShadow). The last parameter reserves some extra storage which is to be tacked on to each instance.
- fill in the fields in struct "Ucc", typedef'd in GPFUC.H. In this file there are several 'defines' of the form GPF_CAPS_wxzy. These are used to control the capabilities which are enabled during the presentation of the default User Control dialog. Since w
e want the developer to define text, we enable the text entry field this way:
<:#240,9360><:f,QCourier,> /* more stuff could be ORed in */<:f>
<:s><:#284,9360>
<:s><:#284,9360>2. fnwpShadow()
<:#1988,9360>Each instance of this control will need some storage in which we can store, as a minimum, the text defined by the developer during control creation. In this case it will be of type PSZ, for which memory will be allocated during the WM_CREATE message. <[>Not
e that the call to WM_CREATE will be made from Gpf, after the CREATESTRUCT fields have been filled in. The text specified by the developer will be pointed to by the "pszText" field of this structure.] Once allocated we will place a pointer to this area into
the first slot of the EXTRAWORDS asked for during class registration.
<:#284,9360>This storage will be free(d) during the WM_DESTROY message.
<:s><:#1136,9360>Now jump back to the start of fnwpShadow and notice that we initially try to retrieve the pointer stored with the instance. If it is NULL we know the WM_CREATE function has not been processed (or invoked) as of yet, hence we immediately return unless the me
ssage is WM_CREATE! It is usually safe to ignore any messages flying around before WM_CREATE.
<:s><:#284,9360>
<:#1988,9360>The other message of real interest is WM_PAINT. The pointer to the instance text has already been retrieved, so an HPS is opened, and along with the PSZ and HWND, is passed to a helper function called Paint(). The details of what Paint() does will not be ex
plained here, kindly look at the source code. In fact, modify it to your heart's content.... but don't call me if it blows up after your 'improvements' are installed. Many optimizations are possible, such as re-sizing the control to exactly fit the passed-
in text. But that would obscure the point of this AppNote. The next control, having an extended dialog, will indeed have some obfuscating code.
<:s><:#284,9360>
<:s><:#284,9360>How does one use this control?
<:s><:#284,9360>1. From Gpf click on menu "Objects- User Controls"
<:s><:#284,9360>2. In new dialog, press "Add"
<:s><:#284,9360>3. In new dialog
<:s><:#284,9360> enter "shadow" in name field
<:s><:#284,9360> enter "shadow" in DLL name field
<:s><:#284,9360> the link via should be left at "import"
<:#568,9360>4. press Ok. If Gpf is unable to find it, move SHADOW.DLL to a directory seen by the LIBPATH variable in CONFIG.SYS, then repeat the above
<:s><:#284,9360>5. exit to top level
<:s><:#284,9360>6. open or create a window
<:s><:#284,9360>7. click on the "Create- User Control" menu
<:s><:#284,9360>8. drop the tracking rectangle anywhere on the client area.
<:s><:#568,9360>9. the User Control default dialog should come up (if you have this turned off, simply double click anywhere within the tracking rectangle for this control)
<:#284,9360>10. enter the desired text and return with OK
<:s><:#284,9360>11. drag/drop or re-size as desired
<:s><:#284,9360>12. if you want to modify the SHADOW.DLL sources, close Gpf so that it releases the DLL!
<:#852,9360>Examining file "Gpfuc.h" reveals a definition of GPF_CAPS_EXTENDED. Including this bit during the registration phase enables the "Extended..." pushbutton in the User Control default dialog. Simple enough, but a bunch of extra baggage must be generated to s
upport this capability:
<:#568,9360> - one or more dialog templates must be made, using the toolkit dialog editor, and (resource) compiled.
<:s><:#568,9360> - an extra registration procedure must be written, with a specific format, for the extended dialog
<:s><:#284,9360> - a complete window procedure must be written for each and every new dialog
<:#568,9360> - a parameter/data collection and passing stategy must be implemented within the new procedures, and made known to the two original procedures (made in the simple case).
<:#289,9360> - the .<+!>DEF<-!> and <+!>MAK<-!> files need to be expanded a bit.
<:#573,9360> - for general ease, an .<+!>RC<-!> file is made; its only function is to pull in the .<+!>DLG<-!> file created for the extended dialogs.
<:s><:#284,9360>
<:#857,9360>Sounds a bit messy, but it all becomes perfectly clear after making a few dozen of these beasts. In this example we will create a User Control with the name
<+!>"SHADOWX"<-!>, since it is derived from the previous control but with a few bells and whistles thrown in.
<:s><:#284,9360>
<:s><:#284,9360>As before, let's talk about the bare minimums:
<:s><:#284,9360> - you must create source code for these functions
<:s><:#284,9360> <:f200,QCourier,>/* the next two are just as in the simple example */
<:#284,9360> /* the new prefixes, 'Extended' and 'fnwpExt' must be exact, even their case !! */
<:#284,9360> /* and the suffix for all (4) functions must be the name of this control: Shadowx */
<:#852,9360> - invoke the dialog editor (not Gpf!!) and create a .DLG and .H file. In this example I created SHADEXT.DLG and SHADEXT.H. No instructions for using this particular editor will be provided here, except an admonition to specify useful ID names.
<:s><:#284,9360>
<:#568,9360>As before we can immediately write the complete .DEF file, and we'll call it SHADOWX.DEF. The entire source follows:
<:s><:#284,9360><:f,QCourier,><:f,2Times New Roman,>
<:#2272,9360><:f,2Times New Roman,>For no particular reason, except perhaps to keep all source files on the small side, I chose to split my code into two "C" files. SHADOWX.C contains the same functions as in the simple example, and SHADEXT.C contains the required new f
unctions which support the extended dialog. Aside from ensuring the compile/link of two source files, the only real addition to the .MAK file is some extra processing for the resource compiler. SHADEXT.DLG and SHADEXT.H files were generated by the Dialog Ed
itor, and then a simple .RC file was created which simply does an 'RCINCLUDE' of these two. With the production details out of the way it is time to discuss the source changes and additions.
<:s><:#284,9360><:f,2Times New Roman,>
<:s><:#284,9360><:f,2Times New Roman,>What are the new features of this control?
<:s><:#852,9360><:f,2Times New Roman,> - Presentation Parameters, familiar to most Gpf users, can now be specified for this control in the same fashion. Note: only foreground/background colors have any effect. Font specifications are ignored, as the source code is hard-wir
ed to 'Times New Roman".
<:s><:#284,9360><:f,2Times New Roman,> - the "Extended..." pushbutton is enabled, leading to a dialog in which we can
<:s><:#284,9360><:f,2Times New Roman,> a. specify a left or right tilt to our text, 0-30 degrees from vertical.
<:s><:#284,9360><:f,2Times New Roman,> b. specify the left shadow color
<:s><:#284,9360><:f,2Times New Roman,> c. specify the right shadow color
<:s><:#284,9360><:f,2Times New Roman,> d. override the background color
<:s><:#284,9360><:f,2Times New Roman,> e. override the foreground color
<:s><:#284,9360><:f,2Times New Roman,>
<:#1704,9360><:f,2Times New Roman,>The only change to the registration procedure was the addition of two bits to 'Ucc.capability', turning ON the PresParams and Extended pushbutton in the default User Control dialog. The changes to the window procedure are a bit more in
volved, and depend on what happens in the extended dialog (if anything; the user should not be required to invoke it). The key to understanding this code is knowing what, and when, gets passed between our four required functions.
<:#284,9360><:f,2Times New Roman,>All Gpf User Controls make use of a structure of type UCC, contained in GPFUC.H:
<:s><:#284,9360><:f,2Times New Roman,>
<:#202,9360><:f200,QCourier,>#pragma pack(1) /* force structure alignment packing */
<:#202,9360><:f200,QCourier,> LONG Reserved<[>60]; /* Reserved */
<:s><:#202,9360><:f200,QCourier,> } UCC;
<:#202,9360><:f200,QCourier,>typedef UCC FAR *PUCC; /* Far Pointer */<:f200,,><:f>
<:s><:#284,9360><:f,2Times New Roman,>
<:#1420,9360><:f,2Times New Roman,>Previously we used the first four members of this structure and now we will use the fifth in addition. We can define any structure we wish, provided it is 'packed' and does not exceed 60 bytes in length. Gpf will be providing us with a
pointer to the 'Reserved' member at appropriate times, and we can type cast it to suit our needs. So I created a structure to hold the information this control will be interested in retaining. In file SHADOWX.H:
<:#568,9360>Member 'cBytes' will be used as a test of whether or not the structure has been initialized. After initialization the sizeof(UCPARAMS) number will be placed here.
<:#852,9360>All members suffixed with 'Color' will contain the OS/2 PM definition for a color, such as CLR_BLACK. All colors known to this control are in structure 'Colors', found at the top of file SHADEXT.C.
<:s><:#852,9360>All members suffixed with 'Index' are used to hold the offset into the 'Colors' structure for the related 'Color' member. This is for convenience only, and comes in handy when communicating with the combo boxes which display the current and the available ch
oices.
<:#284,9360>Member 'sAngle' will contain the tilt angle, read from a spin button having a range of +/- 30.
<:#852,9360>Member 'fOverride' will follow a check button in the extended dialog, and when true will cause the WM_PAINT procedure to ignore Presentation Parameters and use the colors specified by the user from the extended dialog.
<:s><:#284,9360>
<:#1420,9360>It is important to understand that Gpf itself will know nothing about this structure, and will care even less. But it will maintain a pointer, set to NULL or to the enclosing area (UCC.Reserved). A NULL value is the initial value and will stay that way unle
ss and until the extended dialog is invoked at least once. Then it will be fixed to point to the reserved block. This pointer is available at these times:
<:#284,9360> - for Gpf's default User Control dialog functions
<:#284,9360> In RegisterShadowx one can, if one really desires, derive &Ucc.Reserved
<:#568,9360> In fnwpShadowx, message WM_CREATE, it is passed in as 'mp1'. It may or may not be NULL, subject to the explanation above.
<:s><:#284,9360> - for the extended dialog functions
<:#1704,9360> In fnwpExtShadowx, message WM_INITDLG, it is passed in as 'mp2'. Here it is never NULL and we will immediately capture it into a static variable, available then to all other messages including any further WM_INITDLG. Keep in mind that the entire UCC struc
ture is primarily for the use of Gpf, and we will keep a local copy of the reserved area in the 'window words' of each control instance. How? Let's examine the modifications to WM_CREATE in fnwpShadowx().
<:#3124,9360>As in the simple case, 'mp2' is a pointer to a CREATESTRUCT defined by OS/2 PM header files. The member of interest to us is 'pszText', into which Gpf will stuff any text entered by the Gpf user during the default dialog. The pointer to the reserved block w
ill be in 'mp1', providing that the extended dialog has been invoked at least once. The first time that WM_CREATE is called there is no possibility of having gone through the extended dialog, hence Gpf will have set this to NULL. Meanwhile, we allocate stor
age for a UCPARAMS structure and initialize a pointer to this block. Next we check 'mp1', here type cast to a PUCPARAMS. If it is NULL we init two of the color fields in our local structure; if it is non-NULL, we copy the entire contents into our local inst
ance. The text is then copied, in both cases, to the newly allocated structure. It is then tucked away for future use with the WinSetWindowPtr() function. WM_PAINT will have access to this pointer, and will modify itself according to the information. Now to
the extended dialog...
<:s><:#284,9360><:f,2Times New Roman,>
<:f,2Times New Roman,>The window procedure, fnwpExtShadowx, will always be given a true and valid<:f><:f,2Times New Roman,> pointer to the reserved, 60-byte area (via 'mp2'). As this window is constantly<:f><:f,2Times New Roman,> being created and destroyed
, we must implement a mechanism to determine the validity of the structure contents. It would be nice, for example, to set all the controls to their last-invoked state. But testing for a NULL pointer will not work, as it is never NULL. Hence we do something
else, we set member 'cBytes' to a certain value at the first opportunity. Now we can test the contents of 'cBytes' for this value. If it is incorrect we know this is the first time it is seen by our window procedure, and we initialize ALL relevant members
to desired values. <:f><:f,2Times New Roman,>The remaining controls can then be initialized with respect to the structure contents, new or existing, and this completes our WM_INITDLG phase.
<:s><:#284,9360><:f,2Times New Roman,>
<:#1420,9360><:f,2Times New Roman,>The only remaining job is to catch user interactions with the extended dialog controls. Since they will all generate a WM_COMMAND message, that is where we lump them. Parameter 'mp1' tells us the control ID and the nature of the messag
e. A big switch statement is built to take care of all possibilities of interest to us. Those of no interest should not be ignored, but rather passed to WinDefDlgProc(). Bizarre things can happen if you forget to do this.
<:s><:#284,9360><:f,2Times New Roman,>
<:f,2Times New Roman,>Using this control is similar to the simple example, except that you must change the name to 'shadowx'. Obviously nothing prevents you from using both types of control, in the same application.
<:s><:#284,9360><:f,2Times New Roman,>
<:s><:#284,9360><:f,2Times New Roman,>Alexander Charov,
