Introduction to PM Programming - Apr 1995

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 me via email and I will do my best to answer them in a timely fashion.

The Menu Class
The menu class (WC_MENU) provides the most widely used functionality of any of the window classes, save the frame window. It is, simply put, a user-interface for a tree structure that is defined by the application. Each node on the tree, whether a leaf or branch node, has various characteristics, such as text and display attributes.

Some definitions need to be noted:

Leaf nodes (menu items) are end-selectable, a term I'll use to describe that the selecting action is terminated after the selection is made, and the identifier representing the menu item is returned to the application via the appropriate message.

Branch nodes differ from leaf nodes in that they lead to other parts of the tree. In PM parlance, branch nodes are items with sub menus associated with them and are not end-selectable.

Menu item - a single entity within the menu tree. This term is used to describe leaf nodes.

Submenu - a single entity within the menu tree. This term is used to describe branch nodes.

Pulldown - another term for submenu, since they (typically) are "pulled-down".

Pullright - another term for submenus that exist within submenus, since they (typically) are "pulled-right".

Menu item button - a menu item with the MIS_BUTTONSEPARATOR style that acts like a button on the action bar.

Action bar - this is a horizontal bar that usually is as wide as its parent. On this bar are menu items which may or may not contain submenus. To the right of the action bar there may be one or two menu item buttons.

Popup menu - this term describes a menu without an action bar which is accessed by a mouse action or keystroke. The menu "pops up" and looks like a pulldown with one or more pullrights.

Each node has a set of styles and attributes associated with it. Styles differ from attributes in that they describe what the "type" of the node is are not meant to be changed once set. Examples of styles are "submenu", "text", and "bitmap". Attributes, on the other hand, also describe appearance characteristics, but may vary from time-to-time and are frequently changed by the application in response to the state of the application. Examples of attributes are "checked" and "disabled".

Styles and Attributes
Menu item styles (MIS_) are listed below:

Menu item attributes (MIA_) are listed below:

From the Resource File
The general form of the menu template within a resource file is shown below: menuitem:= MENUITEM "text", id [, style [, attribute ]]

menublock:= menublock | submenu | menuitem

submenu:= SUBMENU "text", id  BEGIN menublock END

menu:= MENU id  BEGIN menublock END

My compiler teacher would kill me for writing a recursive grammar like that, but at least she can't flunk me anymore.

You can see that the top level items do not have to be submenus, even though this is not a common occurrence.

Using Menus
Menus are typically loaded in one of two fashions, depending on their purpose. Action bar menus are loaded by the WinCreateStdWindow function. All that you need to do is specify the FCF_MENU flag in the third parameter and insure that the id of the MENU itself matches the value specified by the eighth parameter. Popup menus are loaded using the WinLoadMenu function: (HWND)WinLoadMenu(HWND hwndParent,HMODULE hmModule,ULONG ulId)

hwndParent, although the documentation states that this must be a frame window, is the window to own the menu. For action bar menus, it should indeed be a frame, but for popup menus, you should specify HWND_OBJECT. This is because the function automatically attaches the menu to the window specified which would display an action bar on the frame even though you were going to use it as a popup menu. hmModule is the handle of the DLL containing the menu resource. ulId specifies the id of the menu resource to be loaded.

Menu items send to the client either a WM_COMMAND, WM_SYSCOMMAND, or WM_HELP message depending on the style of the item. After receiving one of these messages, you perform the action associated with the menu item. Why would you use WM_SYSCOMMAND or WM_HELP instead of WM_COMMAND? WM_SYSCOMMAND is a "system command" such as "close the window" or "size the window" and is sent by the system menu (FCF_SYSMENU). WM_HELP is used by help related items such as "general help" or "help index".

Conclusion
This month we began looking at the menu control and the basic things that we need to know before moving onto the messages that the menu control accepts and sends. This will be the topic of the next column or two which will be accompanied by a sample program (or two).