Introduction to PM Programming - Oct 1994

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 curiosity, 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 finished up the WC_LISTBOX class and we shall begin looking at the WC_BUTTON class.

The Button Control
The button control is an interesting one. While there is one constant (WC_BUTTON) for the class, there are in reality five different classes.

Listed below are the five types of buttons.
 * 1) Push button class (BS_PUSHBUTTON) - this type of button is used to send a command to the application, e.g. "Ok" (continue), "Cancel", etc. It is used by clicking on it with the mouse or by pressing the spacebar while it has the input focus.
 * 2) Radio button class (BS_RADIOBUTTON, BS_AUTORADIOBUTTON) - this type of button is used to allow the user to select a single item in a set of choices. It is used by clicking on it with the mouse or by using the arrow keys when any item in the set has the input focus.
 * 3) Check box class (BS_CHECKBOX, BS_AUTOCHECKBOX) - this type of button is used to allow the user to select one or more items in a set of choices. It is used by clicking on it with the mouse or by pressing the spacebar while it has the input focus.
 * 4) Tri-state button class (BS_3STATE, BS_AUTO3STATE) - this type of button is similar to the check box class except that it has a third state which is "undefined". It is used in the same manner as the check box class.
 * 5) Ownerdraw button class (BS_USERBUTTON) - this type of button is really a push button except that the application controls its appearance. It is used in the same manner as the pushbutton class.

Listed below is some terminology that applies to button controls. WS_GROUP. The end of the group is marked by the beginning of the next group or by the end of the z-order for the siblings under a parent (usually a dialog). The first control in the z-order has an implied WS_GROUP style.
 * Control group:A control group is a group of buttons, the first of which has the style
 * Control groups are used for button controls only and specifically for radio buttons only. Since radio buttons are used to allow the user to select a single item in a group, a way was provided to find out which item was selected instead of having to send a BM_QUERYCHECK message to each button in the group.


 * Auto buttons:For radio buttons, check boxes, and tri-state controls, the application is notified whenever the user clicks on it using the mouse or keyboard. If the default action to be taken by the application is to check or uncheck the button, you should create the button as an auto button; this tells the button control to check or uncheck itself automatically instead of relying upon the application to send the appropriate messages to do this.
 * Ownerdraw controls:As we have mentioned previously, an ownerdraw control is a special type of a control which allowed the application to paint it. There are a few classes that support this feature, some more than others.

Button Messages
Below are the five messages that are specific to button controls.
 * BM_CLICK:Purpose - This message simulates a mouse click on the button, causing any WM_CONTROL messages to be sent.
 * Applies to - This message can be sent to all button types.
 * Parameters - This message takes no parameters.
 * Returns - This message returns no value.


 * BM_QUERYCHECK:Purpose - This message returns the check state of the button
 * Applies to - This message can be sent to radio buttons, check boxes, and tri-state buttons.
 * Parameters - This message takes no parameters.
 * Returns - LONGFROMMR(mrResult):

-0 = Unchecked -1 = Checked -2 = For tri-state buttons only, the "undetermined" state. -
 * BM_QUERYCHECKINDEX:Purpose - This message returns the index of the checked button in a button group.
 * Applies to - This message can be sent to radio buttons only.
 * Parameters - This message takes no parameters.
 * Returns - LONGFROMMR(mrResult) - zero-based index from the first button in the group that is checked, or -1 if no button is checked or an error occurred.


 * BM_SETCHECK - Set the check state:Purpose - This message sets the checked state of a button.
 * Applies to - This message can be sent to radio buttons, check boxes, and tri-state buttons.
 * Parameters - LONGFROMMP(mpParm1) - the new check state. See the return values from BM_QUERYCHECK for the interpretation of the values.
 * Returns - LONGFROMMR(mrResult) - the previous check state.


 * BM_SETDEFAULT:Purpose - This message sets a button as the default button.
 * Applies to - This message can be sent to pushbuttons and ownerdraw buttons.
 * Parameters - LONGFROMMP(mpParm1) - a BOOL which specifies the new default state.
 * Returns - LONGFROMMR(mrResult) - a BOOL which specifies if the state changed from its previous state.

Control Notifications
The button control can send three different notifications to its owner via the WM_CONTROL message.
 * BN_CLICKED:Purpose - This notification is sent whenever the button was clicked on with the mouse or via the keyboard.
 * Parameters - No parameters are sent in mpParm2.


 * BN_DBLCLICKED:Purpose - This notification is sent whenever the button was double clicked on with the mouse.
 * Parameters - No parameters are sent in mpParm2.


 * BN_PAINT:Purpose - This notification is sent whenever the button control needs to be repainted.
 * Parameters - mpParm2 points to an USERBUTTON structure. Ownerdraw buttons will be looked at in more detail next issue.

Next Month
This month we took a good look at the button control from a purely referential standpoint. Next month, we will look at the code for a dialog box that contains each of these button types and will also look extensively at ownerdraw buttons.