═══ 1. Introduction ═══ This document is the programmer's reference for the User Customizable Menu (UCMenu) PM control. For more information on programming with this control, see OS/2 Developer Magazine, Jan/Feb 1995, page 50. Acknowledgments This control was originally conceived at the IBM Yorktown Research laboratory by Gennaro Cuomo and Juerg VonKaenel for use in EPM (the OS/2 enhanced system editor) with subsequent development contributions from Guillaume Le Stum, John Ponzo, Alan Warren and Alex Bertrand. Mark McMillan of IBM Research Triangle Park developed the sample code, frame control utility functions, and initiated improvements in the architecture. Description The User Customizable Menu is a very powerful, new user interface component, designed to overcome the problems with current menu and toolbar designs. It allows the user to define the ordering of menu items and visual representation (artwork and text) of menu items. New items, like "macro assignments" can be added dynamically. A user customizable menu can be saved in its present state for later use. The UCMenu changes itself into a "scrolling" mode when the number of selectable items exceeds the allotted window size. Aside from the good graphical presentation, the most significant features of this control are the easy user customization methods it provides (thus its name, UCMenus). Customizing a UCMenu is made easy for the user by extensive use of direct manipulation techniques. For example, to delete an item from the toolbar the user can drag the item to the system shredder. Reordering the items is as easy as dragging the item to a new position and dropping it. Many direct manipulation functions are provided by the control. There are two basic customization methods for which UCMenus provides direct support: 1. Free Form Customization: Using this method, the user can alter any aspect of any menu item, including the bitmap (graphical presentation), the application function associated with the item, etc. An OS/2 notebook control provides easy customization of all aspects of the menu items. This is the default method if not overridden by the application. 2. Buffet Style Customization: Using this method, the application provides a fixed set ("buffet") of supported menu items. The user can only select from the buffet and cannot modify the application functions associated with the menu items. They cannot specify alternate or custom bitmaps for the graphical presentation. This is the easiest form of customization method for novice users or for applications with a fixed set of toolbar items. All customization is encapsulated in the UCMenu control itself. The control and the application cooperate via messages to provide application specific information during customization. Using the built-in customization methods the user can: o Modify styles related to visual effects. o Add and delete items and submenu items. o Replace bitmaps with .BMP files or application supplied bitmaps. o Edit the text under the bitmap. o Associate application functions with menu items (the application supplying the list of valid functions). o Move/copy menu items within a menu or between menus. o Restore the entire menu to an application-defined default state. The application can restrict what customization functions are allowed through the use of style flags. ═══ 2. Programming Concepts ═══ There are several key concepts which need to be understood to make effective use of UCMenu controls in an application program. As its name implies, the basic paradigm of a UCMenu control is that of a normal PM text menu; the control contains selectable items, submenus, separators, item attributes, etc. (The current implementation is limited to a single level of submenus.) The developers view of this control is also similar to that of a PM menu control. This similarity is by design and allows anyone familiar with PM menus to grasp the terminology, concepts, and messages involved with UCMenu controls. It is important to recognize that there are some key differences, many of which we will cover in this article. The UCMenu control uses many of the same menu-related messages and data structures as its PM menu counterpart. For example, a MM_QUERYITEM message can be sent to the UCMenu window to obtain a MENUITEM structure which describes a particular item in the menu. The application will receive all the standard PM menu notification messages except WM_DRAWITEM and WM_MEASUREITEM which are used internally by the UCMenu, and WM_COMMAND which is replaced with a WM_CONTROL message. Because of its added visual and interactive complexity, the standard PM menu structures and messages are not sufficient to implement a customizable graphical menu bar. Thus, UCMenus add another layer of messages and data structures on top of the PM menu architecture. It is important to understand the new concepts that UCMenus brings to the existing menu architecture and how the PM menu architecture has been extended to accommodate them. The following sections describe some of these extensions. ═══ 2.1. UCMenu Action Strings ═══ One of the most important new concepts that UCMenus brings to a menu is that of actions. An action is a textual description of the function assigned to a particular menu item. It is an arbitrary string defined by the application and seen by the user when customizing a UCMenu. For example, a text editor might define action strings like: "Copy to Clipboard" "Paste from Clipboard" "Left Justify" "Select Fonts" ...etc... When a user creates a new UCMenu item or modifies an existing item, they will select from a list of actions supplied by the application. For a UCMenu control, the menu item IDs are arbitrary and can change during execution of the program. An application cannot know ahead of time what the item IDs are going to be for any particular menu item. When a user adds a new menu item to an existing UCMenu toolbar the UCMenu control supplies all the user interface necessary for the user to choose a bitmap, text, and an application-specific action for the new item. When the new item is added to the menu, the UCMenu control will choose an arbitrary item ID which is unique throughout the menu and all submenus. Likewise, items can be moved and copied between UCMenu toolbars. The resulting (new) menu items are assigned arbitrary IDs that do not conflict with any existing items. Therefore, an application cannot depend on using item IDs to determine what function was selected on a UCMenu toobar. Instead, the application must use the action string associated with the menu item to determine what function has been selected. A UCMenu control will send a WM_CONTROL message with a notification code of UCN_ITEMSELECTED when an item is selected. The application will not receive a WM_COMMAND message from a UCMenu control. The application must associate the action string of the selected menu item with an application function. The toolkit sample program (SAMP1.C) uses a table which maps action strings to fixed ID values. The action of the selected item is looked up in the table and then a simple switch can be used to select the correct application function. The ID values chosen for the table purposefully match the fixed item IDs used in the applications standard PM menu bar (the application has both UCMenu toolbars and a standard PM menu bar). Thus, the same switch can be used to process WM_COMMAND messages from the PM menu and WM_CONTROL messages from the UCMenus. This reduces code size and keeps application specific function from being duplicated. ═══ 2.2. Data Structures ═══ There are two primary data structures related to UCMenu controls. Associated with each UCMenu window is a set of data which describes various aspects of the overall toolbar appearance and behavior. This includes information such as style flags, menu colors and text font. This is the UCMINFO structure. It is filled in by the application and used during creation of a UCMenu control. Associated with each item of the menu are two linked data structures. The first is the standard PM MENUITEM structure. That structure contains an 'item handle' which is generally reserved for application use. A UCMenu uses the item handle to point to a UCMITEM structure which provides UCMenu specific item information. In effect, the MENUITEM structure is extended for UCMenu specific data. It should be noted that any of the string pointers in the UCMITEM structure can be null. These data structures are used extensively in the processing of messages to and from the UCMenu control. ═══ 2.3. Checkable Menu Items ═══ The fact that a UCMenu can be extensively customized by the user has some important implications for applications with 'checkable' style menu items. Like a PM menu, any item in a UCMenu can be checked simply by setting the MIA_CHECKED attribute for that item. A menu item should be checkable if the action associated with it represents the toggling of some application state. A checked menu item is indicated in a UCMenu by drawing a thick border around it. When a UCMenu item is created by the user the MIA_CHECKED attribute is not set. Thus, if the action selected by the user for the new item is a toggle function, the application should update the current state of the item with the current state of the application. Likewise, when a menu item is modified and assigned a new action, the current attributes are not changed. If the new action is a toggle function, the item attribute must be updated to reflect the current application state. If the action is not a toggle function, the MIA_CHECKED attribute should be cleared since the previous action may have been checked. The UCMenu control will send a WM_CONTROL message with a notification code of UCN_ADDEDITEM or UCN_ACTION when a new item is added or an action is changed. When these messages are received, the application must examine the new action and set or clear the MIA_CHECKED attribute. When the application is notified of a selection on a checkable UCMenu item, the application must toggle the check state. In a standard PM menu it is sufficient to toggle the state of just the menu item selected. Since a UCMenu may have the same (toggle) action on different items in the same menu, the check state of all items with the toggle action must be updated. This function has been incorporated into the UCMenu API set with the function UCMenuSetActionAttr. This API will set the attributes of all items in the UCMenu with the specified action string. If the application has multiple UCMenu toolbars, all must be updated since the action may exist in any of them. ═══ 2.4. Customization Messages ═══ Easy customization of the toolbar is one of the most useful and powerful features of this control. It gives the user complete flexibility to add and delete menu items, rearrange the order, create submenus, and move and copy items between toolbars. Encapsulation of these functions into the UCMenu control means that there is very little application code required to support customization. Although most of the customization function is encapsulated in the control itself, there are several messages to which the application must respond for customization to work properly. The UCMenu control will send WM_CONTROL messages to its owner when it needs certain types of information. Depending on what type of customization the application allows (free-form or 'buffet' style), some of these message may not be generated. The WM_CONTROL notification codes for customization are as follows: o UCN_QRYDEFTEMPLATEID: This is sent when the user selects the Load default context menu item to restore the entire UCMenu to its default configuration. The application responds by supplying the resource ID of the menu template to be loaded. o UCN_QRYTEMPLATEMODULE: This is also sent when the Load default context menu item is selected. The application must supply the handle of the module in which the UCN_QRYDEFTEMPLATEID resource is to be found. o UCN_QRYRESBMP: This message is sent when the user wants to display a list of application-supplied bitmaps from which to choose. The application must allocate and construct an array of bitmap resource IDs. This message is generated by the free-form customization method. o UCN_QRYACTIONLIST: This message is sent when the user has requested a list of actions from which to choose. The application responds by sending a series of UCMENU_INSERTACTION messages, each with a pointer to an action string and descriptive help text. After the last action has been inserted, the application must send UCMENU_ACTIONSINSERTED to indicate the list is complete. This message is generated by the free-form customization method. o UCN_HLP_*: This is a set of messages sent when the UCS_CUSTOMHLP menu style is used and the user requests help on a customization dialog. By default the UCMenu control will supply the needed help text. The handling of all these messages is demonstrated in the SAMP3.C sample program in the toolkit. ═══ 2.5. Control of Customization ═══ The highly flexible customization built-in to the UCMenu control may not be desirable for all applications or situations. For example, the ability to move items from one menu to another within an application may not make semantic sense. An application with multiple windows performing different functions may not want to allow the user to drag items from the toolbar in one window to the toolbar in another. The result might be 'actions' which make no sense in the context of the window. The application may also want to provide its own customization methods to replace or supplement those of UCMenus. By default, all the direct manipulations and all the context menu options are allowed. No buffet dialog is displayed unless explicitly called using the UCMenuXXXXBuffetDlg() APIs. Various style flags (UCS_*) can be used by the application to control which direct manipulation and context menu functions are supported for that instance of the menu. At the extreme, the application can set a style of UCS_STATIC to prevent any customization at all. This style will disable all direct manipulation functions and the context menu. Other style flags allow selective disabling of specific customization functions, such as disabling drag/drop between menus (but allowing it within a menu), disabling drops to the system shredder, removing the 'Edit item...' context menu option, etc. An application can also supply its own customization functions via the UCMenu context menu. By sending the control a UCMENU_ADDITEMSTOCM message the application can add its own options to the context menu. The UCMenu control will send a WM_CONTROL message with a notify code of UCN_CMITEM when such an option is selected. A sample of adding an application customization function to the context menu is shown in the SAMP3.C toolkit sample. ═══ 3. Version Notice ═══ This document describes Version 2.11 of the UCMenus control. Version 2.11 is not binary-compatible with applications written for Version 1 or Version 2.0. This version is source compatible with Version 2.0. The size of some data structures were changed in this version so applications must be recompiled. Version 2.11 contains the following major changes from Version 2.1: o Two new styles, CMS_MATRIX_VERT and CMS_MATRIX_HORZ allow matrix style menus be scrollable in the vertical or horizontal direction. SAMP1 of the toolkit uses this style for the tool palette menu. o The frame is now activated when a button is pressed on a UCMenu control. This prevents UCMenu context menus from appearing in a non-active frame. o Fixed memory leaks. o Improved scrolling such that UCMenus does not always return to a scroll position of zero when items are inserted, deleted, or modified. Version 2.1 contains the following major changes from Version 2.0: o Improved UCN_MOUSEMOVE message generation. o Added support for bubble-help (cartoon-like bubble with extended description text). o Added following APIs: - UCMenuStrdup - UCMenuItemDup - UCMenuItemFree o Added support for application-supplied context menu. o Added compile-time UCMUI define statement. Removing this statement produces a UCMenus control with no user-interface (customization) code. o Submenus are now dismissed when the application window becomes inactive (application must send new UCMENU_ACTIVECHG messages). o Changed item sizing algorithms such that item text is never truncated even for UCS_FORCESIZE style menus. Item width is always set to larger of the bitmap width and the text width. o Added UCMENU_DISABLEUPDATE message to improve performance during large number of item insert/delete/modify. o The pszDefaultBitmap field of the UCMINFO structure can now be a resource ID (in string form) or a filename. o Changed UCMENUS.RCH to UCMLOCAL.H since some build systems require header to have .H extension. o Fixed bug that caused application to hang if application had its own drag/drop functions in addition to the toolbar. o Improved handing of bitmap background colors: - New style UCS_CHNGBMPBG_AUTO will use the lower leftmost pixel of the bitmap to determine the background color (the BmpBg field of UCMINFO is ignored). This allows different bitmaps of the toolbar to have different transparent colors. - Improved algorithms to not assume 256-color bitmaps (less memory, faster execution). - Improved algorithms such that background colors are mapped only when the bitmap is first loaded (instead of every time the toolbar is painted). - All bitmaps are reloaded (and color mapped) when the background color is changed. This prevents valid colors in the bitmap from getting set to the background when several color changes are made in sequence. - Removed lCurBmpBgColor from UCMITEM structure since it is no longer needed. o Fixed stray-pixel problems when a partially-obscured button is pressed. o Many minor bug fixes and code changes to improve performance (in particular, store often-used window handles in UCMDATA to avoid lots of WinQueryWindow() calls). ═══ 4. Limitations and Known Problems ═══ o A bug in OS/2 Warp 3.0 can cause random bitmap corruption to occure during drag/drop operations. Usually seen as the toolbar changing size unexpectedly and one or more toolbar bitmaps being corrupted. Bug was reported to OS/2 development as APAR PJ17913. This APAR is reported to be fixed in Warp fixpack #7. This problem does not occure in OS/2 Version 2.X. o A bug in PM prevents support of MIS_BREAK on submenus (MM_QUERYITEMRECT can return wrong coordinates when an owner-draw submenu has MIS_BREAK style items). Any MIS_BREAK style flags are removed when the UCMenu is created. o Bubble help is not implemented for submenus. ═══ 5. Direct Manipulations ═══ UCMenus support the following direct manipulation functions: o Move menu items: drag and drop menu items from one position to another. New position will be insertion point nearest the mouse cursor when the item is dropped. MIS_SPACER items can also be moved. Items may be moved from one toobar to another. o Copy menu items: drag and drop menu items with the CTRL key pressed. Items may be copied from one toolbar to another. o Copy to submenu: drag menu item with ALT key pressed and drop on another menu item. If the target item is not a submenu it will be changed to be one. The dropped item is inserted after the last item already in the submenu. Submenu items can be copied from one toolbar to another. o Delete menu items: drag menu item to system shredder. o Create new items: drag .BMP file type from desktop or drives folder onto a toolbar. A new item with the supplied bitmap will be created. The item will not have any text or action associated with it until provided with the context menu 'Edit item' option. o Render bitmap to file: a menu item which has file-supplied bitmap (the bitmap specification is a file name, not an application resource) can be dragged to the OS/2 desktop or a folder to create a .BMP file. The bitmap can also be dropped on the OS/2 Icon Editor desktop object to open and edit the source bitmap file. o Change colors: a color can be dragged from the system color palette onto the toolbar background or the item background. All items will have the same background color. o Change font: a font can be dragged from the system font palette onto the toolbar. The dropped font will be used for the text under the bitmaps. Items can also be created, deleted and edited with the context menu which may be displayed by positioning the cursor on a menu item and pressing the right mouse button (if the 'Edit' context menu item is enabled by the application). ═══ 6. Submenus ═══ UCMenus supports graphical submenus in a similar fashion to normal PM submenus. Visually, a submenu is a vertical UCMenu which is invoked by selecting from a primary UCMenu item (the submenu 'placeholder'): Only one level of submenu is supported. A submenu cannot contain multiple columns (e.g. the MIS_BREAK style flag is ignored). A submenu can be customized like the main menu by drag/drop reordering of items, adding items by dropping from other menu or submenus, using the context menu to insert, delete, or modify items, etc. Submenus inheret style settings from the parent (main) menu, including background colors, fonts for text, etc. Limitations: o A submenu cannot use the MIS_BREAK style to have multiple columns of selectable items. o An attribute of MIA_NODISMISS on a submenu placeholder is ignored. To prevent a submenu from being dismissed when an item is selected, the item itself must have the MIA_NODISMISS attribute. Submenu items without this attribute will cause the submenu to be dismissed when the item is selected. ═══ 7. Styles ═══ The visual appearance of a UCMenu can be modified through the use of 'style' flags. UCMenu toolbars can have a vertical, horizontal, or matrix layout: o CMS_HORZ The traditional horizontal menu bar style. If the number of items do not fit, scrolling indicators are shown. This is contrary to the style of menu bars which would wrap. Horizontal arrangement o CMS_VERT Display as a vertical column. This is a very useful arrangement to display a small set of tools to the left or right of a window. Vertical arrangement o CMS_MATRIX A matrix arrangement, as it is typically used for tool palettes. The matrix may free-form (application defines height and width), or it may have an orientation in which case it becomes scrollable in that direction (CMS_MATRIX_HORZ, or CMS_MATRIX_VERT). Matrix arrangement. The bitmap items can be drawn with or without 3D frames, text underneath, and with a fixed or automatic sizing. Individual items can be highlighted with a 'checkmark' attribute and are drawn with thick dark borders. Background colors of the menu items and empty toolbar spaces can also be controlled. When required by window size, scrollbar controls will automatically appear at each end of the toolbar. A UCMenu can have a number of different styles that can be set on creation in the UCMINFO structure and changed dynamically through the context menu: UCS_NOTEXT The text associated with the item is not displayed on the screen. UCS_FRAMED When this is set, a frame is drawn around each item so that it looks like a 3-D button. UCS_FORCESIZE The size of all items can be forced to a certain rectangle. If this is set, the size has to be specified in the UCMINFO structure (UCMInfo.cx and UCMInfo.cx) UCS_SHRINK_BLEND When set, either BBO_OR or BBO_AND is used to shrink the bitmaps, else BBO_IGNORE is used UCS_SHRINK_OR Used when BBO_IGNORE not selected. If set BBO_OR is used, else BBO_AND UCS_NO_DM_ALT No drag and drop copy to a submenu when doing an Alt-drop over the UCMenu UCS_NO_DM_M_TO_OTHER No drag and drop move to another UCMenu UCS_NO_DM_M_FROM_OTHER No drag and drop move from another UCMenu UCS_NO_DM_M_INSIDE No drag and drop move inside this UCMenu UCS_NO_DM_C_TO_OTHER No drag and drop copy to another UCMenu UCS_NO_DM_C_FROM_OTHER No drag and drop copy from another UCMenu UCS_NO_DM_C_INSIDE No drag and drop copy inside this UCMenu UCS_NO_DM_DISCARD No drag and drop to the shredder UCS_NO_DM_RENDER_TO_BMP No drag and drop rendering as a BMP file UCS_NO_DM_RENDER_FROM_BMP No drag and drop from a BMP file UCS_NO_DM No direct manipulation at all UCS_NO_CM_MENU_STYLE No "change style" in the context menu UCS_NO_CM_MENU_IMPORT No "import" in the context menu UCS_NO_CM_MENU_EXPORT No "export" in the context menu UCS_NO_CM_MENU_DEFAULT No "load default" in the context menu UCS_NO_CM_ITEM_EDIT No "edit item" in the context menu UCS_NO_CM_ITEM_CREATE No "create item" in the context menu UCS_NO_CM_ITEM_DELETE No "delete item" in the context menu UCS_NO_CM_SEPARATOR No "delete item" in the context menu UCS_NO_CM No context menu UCS_CHNGBMPBG When this style is used the background color of the bitmaps is mapped to the background color of the toolbar. The background color of the bitmaps is defined as the BgBmp color in the UCMINFO structure. All pixels in all bitmaps which match that color will be changed to the toolbar background color. This style should not be used with UCS_CHNGBMPBG_AUTO. UCS_CHNGBMPBG_AUTO When this style is used the background color of the bitmaps is mapped to the background color of the toolbar. The background color of the bitmaps is defined as the color of the pixel in the lower leftmost corner of the bitmap. All pixels of that same color in the bitmap are changed to the toolbar background color. The BgBmp field of the UCMINFO structure is ignored. This style should not be used with UCS_CHNGBMPBG. UCS_CUSTOMHLP The help is provided by the user. UCS_PROMPTING UCN_MOUSEMOVE notifications are sent to the owner. UCS_NODEFAULTACTION The list of actions does not include executeprogram by default. UCS_BUBBLEHELP Enables the display of cartoon-style bubble help. When the pointer hovers on a single menu item for a defined period of time (BubbleDelay in UCMINFO) the toolbar will query the application for the help text to be displayed in the bubble window (UCN_QRYBUBBLEHELP). If the application supplies help text, it will be displayed in a cartoon-like window near the menu item. The bubble window is removed when the pointer leaves the toolbar, or when the BubbleRead time period expires, whichever occures first. The application must send UCMENU_ACTIVECHG messages for the bubble window to work properly. The UCM text font and background color can be set on creation, through the UCMINFO structure. The default font is Helv 8. Note that the color corresponds to the RGB index and can look different on different types of displays and adapters. You should use the index returned by WinQuerySysColor(). #define UCM_DEFAULTCOLOR 0x00C9C9C9L // -- light grey on 8514 #define UCM_DEFAULTFONT "8.Helv" ═══ 8. Creating a UCMenu Control ═══ Conceptually, creating a UCMenu control is the same as creating a PM menu control. The menu structure and items are defined in textual form in a resource file (.RC) using MENU, MENUITEM, and SUBMENU statements. The resource file is compiled with the resource compiler into binary resource format and appended to the application executable (or a DLL). The application calls an API to read the binary resource and create the visual PM windows and underlaying data structures. Finally, the window is placed and sized on a parent window. ═══ 8.1. Resource Files ═══ The textual resource file (.RC) specifies the complete structure of the menu and the contents of the menu items. However, the MENUITEM resource statement does not have the syntactic flexibility to allow complete specification of all the data associated with a UCMenu item. Therefore, the text field of the MENUITEM statement is interpreted to contain four extra fields of information not found on standard PM menu items: the bitmap specification, action string, parameter string, and a data string. Each of these fields is separated by a single character defined as the first character of the string. A typical resource file for a UCMenu might be: BITMAP 6 "new.bmp" BITMAP 1 "open.bmp" BITMAP 2 "save.bmp" BITMAP 62 "styles.bmp" BITMAP 63 "bold.bmp" BITMAP 64 "italic.bmp" BITMAP 8 "help.bmp" /* Text strings are interpreted as: */ /* */ /* "TextBitmapIDActionStrParamStrDataStr" */ /* */ /* where is any character that does not appear in */ /* the strings. */ /* */ /* Item style MIS_SPACER produces a gap in the menu bar. */ MENU ID_COMMANDBAR LOADONCALL MOVEABLE DISCARDABLE BEGIN MENUITEM "/New/6/New", 1, MIS_TEXT MENUITEM "/Open/1/Open File", 2, MIS_TEXT MENUITEM "/Save/2/Save File", 3, MIS_TEXT MENUITEM "", 4, MIS_SPACER SUBMENU "/Styles/62/Styles Submenu", 5, MIS_TEXT BEGIN /* Use a different delim here so we can use "/" in the strings */ MENUITEM "!Bold!63!Bold/Style", 6, MIS_TEXT │ MIS_CHECKABLE MENUITEM "!Italic!64!Italic/Style", 7, MIS_TEXT │ MIS_CHECKABLE END MENUITEM "", 8, MIS_SPACER MENUITEM "/Help/8/Show Help", 9, MIS_TEXT END The format for the text field is the following: "[#Text]#BitmapID[#Action][#Parameters][#Data]". The first character of the string (here #) is used as a delimiter and can be any character that does not appear in the string itself. Text The text displayed in or under the bitmap BitmapID Bitmap identifier or file name Action Information about the action associated with the item , for example the name of a macro. Parameters Parameters associated to the action. Data Some text associated with the item , for example the parameters of a macro. Some notes on UCMenu resource files: o The menu item IDs specified in the resource file are arbitrary. Sequential numbering is used to help keep menu items unique but is not necessary. o A new menu item style MIS_SPACER is defined for UCMenus. It produces a blank space in the menu to separate menu items into groups. o The 'Data' field is not seen by the user and is for application use. Note that new items created by customization will have no 'data' value. o The bitmap items have to be declared with the MIS_TEXT style even though they will (from a PM viewpoint) be OWNERDRAW items. o The MIS_BREAK style is not effective for the first level UCMenu items, but it works for the submenu items. o Only one level of submenus is supported. ═══ 8.2. Completing the UCMINFO Structure ═══ To complete the process of creating a UCMenu, the application must construct a UCMINFO data structure and fill in all the relevant fields. The RGB values of the structure are used for color mapping the bitmap background pixels. UCMenus supplies a means for bitmap background pixels to be automatically mapped to the current UCMenu background color. The BgBmp value of UCMINFO tells UCMenus what background color was used in the design of the bitmaps. That color will be replaced with the ItemBgColor before the bitmaps are displayed wherever that color appears in the bitmap. The ItemBgColor should be set to the SYSCLR_MENU color returned by WinQuerySysColor(). A different color may be specified in the BgColor field. This will be the color used wherever there are no items on the toolbar. Once the UCMINFO structure is filled in, the function UCMenuCreateFromTemplate or UCMenuCreateFromResource is called. The template version is used if the application has manually loaded a previously saved UCMenu template. The resource version will create a UCMenu from a menu template in the applications resources. The creation functions return two window handles. The function result is the window handle of interest for the application, the other may be ignored. ═══ 8.3. Placement and Sizing of a UCMenu ═══ Toolbars are generally placed along one edge of the application window frame. Toolbars may be attached to the top, bottom, left or right edge of the window. The toolkit sample SAMP1.C shows toolbars on all four edges of the frame. It is possible to simply place and size the toolbar into the client window of a standard PM window. However, this simple approach introduces a lot of complexity when the application must properly scale and paint the client window. If the frame window is a dialog, proper size and placement is even more complex since the application does not paint, and there is no separate client window. The proper solution to toolbar placement is to make the toolbar a frame control. Making a window into a frame control requires a thorough knowledge of how PM frame windows and message protocols work. Adding a frame control to a dialog window is even more complex since it may require the movement of all the dialog controls. All the function necessary to make UCMenu windows into frame controls is supplied in a set of utility routines in the toolkit. These routines are not a formal part of the UCMenu control, but allow an application to easily place UCMenu controls along any edge of a frame or dialog window. By using these utilities an application can be completely removed from any sizing or positioning considerations for the toolbars. The frame control utilities consist of two functions, one to add a UCMenu to a frame or dialog window, the other to remove it. The utilities support up to four toolbars per frame or dialog window (one each at the top, bottom, left, and right edges). By calling the add/remove frame control utilities, a toolbar can be toggled on and off. The UCMUtils() functions encapsulate all the complexity of frame control management freeing the application from that task. With just a simple function call, the toolbar can be positioned in the frame and will maintain its proper position as the frame is sized and moved. Source code for the utilities is provided in the toolkit. ═══ 9. A Dynamic Status Bar ═══ A dynamic status bar can be implemented by the application to automatically show a description of each menu item as the mouse pointer is moved on the toolbar. To help the application implement this feature, a UCMenu with the UCS_PROMPTING style will send WM_CONTROL messages with a notify code of UCN_MOUSEMOVE when the pointer moves on the menu bar. The message supplies the menu item ID of the item under the mouse pointer. Using this item ID, the application can obtain the item data structures and determine the action string associated with that item. The action string string may be displayed directly, or it may be used to lookup a more complete description for display to the user. The SAMP3.C sample program uses the lookup method to display a longer description of the menu items action. ═══ 10. Saving/Restoring UCMenus ═══ The UCMenus API provides several function to aid the application in saving and restoring the customized state of UCMenu toolbars. The function UCMenuMakeTemplate will create a binary in-storage representation of the complete UCMenu item structure. The binary image will include all text, bitmaps, action strings, and arrangements of menu items. The corresponding APIs, UCMenuCreateFromTemplate and UCMenuNew, create and replace UCMenu controls from an in-storage binary template. It should be noted that these binary templates are in a special format used by UCMenus. UCMenu templates are not usable as standard PM menu templates. The SAMP3.C toolkit sample shows the processing of WM_SAVEAPPLICATION. The UCMenu style, colors, and font, as well as the binary templates, are stored in the application .INI file. During initialization, the styles, colors, font and templates are read from the .INI file and are used to recreate the customized toolbars. ═══ 11. Data Structures Reference ═══ This section contains a list of all the structures used by a UCMenus application. ═══ 11.1. UCMITEM (UCMenu Item Structure) ═══ This structure is used to store data related to a UCMenus menu item, such as its bitmap handle, identifier, text and an action strings. For each menu item, this structure is accessed from the hItem component of the standard PM MENUITEM structure (which can be obtained with the MM_QUERYITEM message). typedef struct { LONG hBmp; // Bitmap handle PSZ pszBmp; // Bitmap Identifier or file name PSZ pszText; // Bitmap Text PSZ pszAction; // Action : for instance the name of a macro PSZ pszParameters; // Parameters for the action PSZ pszData; // Data associated to the item, not visible for the user USHORT usId; // Id of the item LONG lCurBmpBgRGB; // Current background color set for the bmp (if any) ULONG ulFlags; } UCMITEM, *PUCMITEM; #define ITEM(a,b) ((PUCMITEM)((a)->hItem))->b ulFlags can include : UCMI_BMPFROMFILE Set if the bitmap comes from a file, not set if it comes from the resources. ═══ 11.2. CMITEMS (Context Menu items) ═══ This structure is used to add items to the UCMenu's context menu. It contains the identifier and text of the item. typedef struct { ULONG ID; PSZ pszItemText; } CMITEMS, *PCMITEMS; ═══ 11.3. UCMINFO (UCMenu Initialization Structure) ═══ This structure is used to create a UCMenu. It must be passed to the UCMCreateXXXX() APIs when creating a UCMenu. If a matrix UCMenu is created with a null width, NbOfCols must contain the number of menu items per line. If it's created with a null height, NbOfRows must contain the number of items per column. typedef struct { ULONG cb; // size of this structure HMODULE hModule; // Module where the bitmaps are USHORT NbOfCols; // Number of Columns (used for a matrix UCM) USHORT NbOfRows; // Number of Rows (used for a matrix UCM) PSZ pszBitmapSearchPath; // Path(s) to search for bitmap files. // Environment variables separated by spaces. PSZ pszDefaultBitmap; // Bitmap to use if bitmap specified for // a menu item can't be resolved or loaded. ULONG Style; // Style of item (combination of UCS_ flags ) ULONG cx; // Size to give to all the items if UCS_FORCESIZE ULONG cy; // LONG BgBmp; // RGB value of the color of the bmp which has to be replaced with ItemBgColor LONG BgColor; // RGB color of the UCMenu background LONG ItemBgColor; // RGB color of the UCMenu items background PSZ pszFontNameSize; // String describing the font of the UCMenu (such as used } UCMINFO, *PUCMINFO; // in WinSetPresParam), if NULL, UCM_DEFAULTFONT is used ═══ 11.4. QBUBBLEDATA (Query Bubble Data) ═══ This structure is passed to the application by the UCN_QRYBUBBLEHELP message. typedef struct { MENUITEM *MenuItem ; // Item information supplied by UCMenus char *BubbleText ; // Bubble text supplied by application (freed by UCMenus) } QBUBBLEDATA, *PQBUBBLEDATA; ═══ 12. WM_CONTROL Message Reference ═══ This section describes all the WM_CONTROL messages generated by a UCMenu control and sent to the control owner. ═══ 12.1. UCN_ITEMSELECTED ═══ This WM_CONTROL notification is sent by the UCMenu to its owner when a UCMenu menu item is selected by the user. Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_ITEMSELECTED Param2 pUCMitem (UCMITEM *) Pointer to the UCMenu item structure for the selected item. Returns Nothing Remarks Default Processing Related ═══ 12.2. UCN_QRYTEMPLATEMODULE ═══ This WM_CONTROL notification is sent by the UCMenu to its owner when the default template is loaded ("Load default option" in the popup context menu). The owner has to return the module handle where we can look for the default template. Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_QRYTEMPLATEMODULE Param2 pHModule (HMODULE *) Pointer to the module to be filled by the owner. Returns Processed (BOOL) TRUE if processed, FALSE else. Remarks Default Processing Related UCN_QRYDEFTEMPLATEID ═══ 12.3. UCN_QRYDEFTEMPLATEID ═══ This WM_CONTROL notification is sent by the UCMenu to its owner when the default template is loaded ("Load default option" in the popup context menu). The owner has to return the ID of the menu in the resource. Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_QRYDEFTEMPLATEID Param2 pID (PUSHORT) Pointer to the ID to be filled by the owner. Returns Processed (BOOL) TRUE if processed, FALSE else. Remarks Default Processing Related UCN_QRYTEMPLATEMODULE ═══ 12.4. UCN_QRYDEFTEMPLATE ═══ This WM_CONTROL notification is sent by the UCMenu to its owner when the default template has to be loaded ("Load default option" in the popup context menu). The owner has to return a pointer to the template of the default toolbar, allocated with UCMenuAlloc. Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_QRYDEFTEMPLATE Param2 ppTemplate (PVOID*) Pointer to the pointer to the template. Returns Processed (BOOL) TRUE if processed, FALSE else. Remarks If processed, the template has to be allocated with UCMenuAlloc(). The UCMenus will free it with UCMenuFree(). Default Processing Related ═══ 12.5. UCN_QRYACTIONLIST ═══ This WM_CONTROL notification is sentthe UCMenu to its owner when the settings dialog for the action is popped up so that he can fill in the list of actions. The owner has to send UCMENU_INSERTACTION messages and to post back a UCMENU_ACTIONSINSERTED when it is done. Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_QRYACTIONSLIST Param2 hwndUCMenu (HWND) Handle of the UCMenu. Returns nothing Remarks Default Processing Related UCMENU_INSERTACTION ═══ 12.6. UCN_SIZE ═══ This WM_CONTROL notification is sent by the UCMenu to its owner when its size has changed. Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_SIZE Param2 param2 (ULONG) reserved Returns Nothing Remarks After receiving this message, further information can be obtained by using the UCMENU_QUERY* messages. Default Processing Related ═══ 12.7. UCN_STYLE ═══ This WM_CONTROL notification is sent by the UCMenu to its owner when its style has changed. Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_STYLE Param2 param2 (ULONG) reserved Returns Nothing Remarks After receiving this message, further information can be obtained by using the UCMENU_QUERY* messages. Default Processing Related ═══ 12.8. UCN_FONT ═══ This WM_CONTROL notification is sent by the UCMenu to its owner when its font has changed (eg when a font has been dropped from the palette over the UCMenu ). Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_FONT Param2 param2 (ULONG) reserved Returns Nothing Remarks After receiving this message, further information can be obtained by using the UCMENU_QUERY* messages. Default Processing Related ═══ 12.9. UCN_COLOR ═══ This WM_CONTROL notification is sent by the UCMenu to its owner when its color has changed (eg when a color has been dropped from the palette over the UCMenu ). Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_COLOR Param2 param2 (ULONG) reserved Returns Nothing Remarks After receiving this message, further information can be obtained by using the UCMENU_QUERY* messages. Default Processing Related ═══ 12.10. UCN_ADDEDITEM ═══ This WM_CONTROL notification is sent by the UCMenu to its owner when an item has been added. Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_ADDEDITEM Param2 ItemID (USHORT) ID of the added item. Returns Nothing Remarks After receiving this message, further information can be obtained by using the UCMENU_QUERY* messages. Default Processing Related ═══ 12.11. UCN_DELETEDITEM ═══ This WM_CONTROL notification is sent by the UCMenu to its owner when an item has been deleted. Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_DELETEDITEM Param2 ItemID (USHORT) ID of the added item. Returns Nothing Remarks After receiving this message, further information can be obtained by using the UCMENU_QUERY* messages. Default Processing Related ═══ 12.12. UCN_BITMAP ═══ This WM_CONTROL notification is sent by the UCMenu to its owner when the bitmap of an item has been changed. Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_BITMAP Param2 ItemID (USHORT) ID of the changed item. Returns Nothing Remarks Default Processing Related ═══ 12.13. UCN_TEXT ═══ This WM_CONTROL notification is sent by the UCMenu to its owner when the text of an item has been changed. Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_TEXT Param2 ItemID (USHORT) ID of the changed item. Returns Nothing Remarks Default Processing Related ═══ 12.14. UCN_QRYRESBMP ═══ This WM_CONTROL notification message is sent by the UCMenu to its owner when the list of bmp id is needed. ("Predefined..." on the "general" notebook page ) Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_QRYRESBMP Param2 pArrayId (PULONG *) The owner has to return in this pointer an array of the bitmap IDs, allocated with UCMenuAlloc. Returns nbItems (ULONG) The number of elements in the returned array or zero. Remarks The array will be freed by the UCMenu. Default Processing Related ═══ 12.15. UCN_ACTION ═══ This WM_CONTROL notification is sent by the UCMenu to its owner when the action of an item has been changed. Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_ACTION Param2 ItemID (USHORT) ID of the changed item. Returns Nothing Remarks Default Processing Related ═══ 12.16. UCN_CMITEM ═══ This WM_CONTROL notification is sent to the owner of the UCMenu when the context menu receives a WM_COMMAND message for one of the items added with UCMENU_ADDITEMSTOCM. Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_CMITEM Param2 CMItemID (USHORT) ID of the context menu item selected. ItemID (USHORT) ID of item over which the context menu was popped up. Remarks The owner should process this message by executing the function associated to the item he added. Default Processing No default processing Related See CMITEMS type. See UCMENU_ADDITEMSTOCM See UCMENU_DELETECMITEM ═══ 12.17. UCN_MOUSEMOVE ═══ This WM_CONTROL notification code is sent by the UCMenu to its owner when the mouse is moved over its menu or submenu. Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_MOUSEMOVE Param2 ItemID (USHORT) ID of the item over which the pointer is Returns Nothing. Remarks Default Processing No default processing Related ═══ 12.18. UCN_HLP_NB_BMP ═══ This WM_CONTROL notification is sent by the UCMenu to its owner when custom help is required for the general page of the notebook. Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_HLP_NB_BMP Param2 param2 (ULONG) Reserved Returns Nothing. Remarks Default Processing No default processing Related UCS_CUSTOMHLP ═══ 12.19. UCN_HLP_NB_CREATE ═══ This WM_CONTROL notification is sent by the UCMenu to its owner when custom help is required for the create page of the notebook. Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_HLP_NB_CREATE Param2 param2 (ULONG) Reserved Returns Nothing. Remarks Default Processing No default processing Related UCS_CUSTOMHLP ═══ 12.20. UCN_HLP_NB_ACTION ═══ This WM_CONTROL notification is sent by the UCMenu to its owner when custom help is required for the action page of the notebook. Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_HLP_NB_ACTION Param2 param2 (ULONG) Reserved Returns Nothing. Remarks Default Processing No default processing Related UCS_CUSTOMHLP ═══ 12.21. UCN_HLP_STYLE ═══ This WM_CONTROL notification is sent by the UCMenu to its owner when custom help is required for the style dialog. Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_HLP_NB_STYLE Param2 param2 (ULONG) Reserved Returns Nothing. Remarks Default Processing No default processing Related UCS_CUSTOMHLP ═══ 12.22. UCN_HLP_DM ═══ This WM_CONTROL notification is sent by the UCMenu to its owner when custom help is required for the drag and drop. Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_HLP_NB_DM Param2 param2 (ULONG) Reserved Returns Nothing. Remarks Default Processing No default processing Related UCS_CUSTOMHLP ═══ 12.23. UCN_HLP_BUFFET ═══ This WM_CONTROL notification is sent by the UCMenu to its owner when custom help is required for the buffet toolbar dialog. Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_HLP_NB_BUFFET Param2 param2 (ULONG) Reserved Returns Nothing. Remarks Default Processing No default processing Related UCS_CUSTOMHLP ═══ 12.24. UCN_QRYBUBBLEHELP ═══ This WM_CONTROL notification is sent by the UCMenu to its owner to obtain the bubble-help text associated with a particular menu item. Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_QRYBUBBLEHELP Param2 QueryData (QBUBBLEDATA *) Pointer to QBUBBLEDATA structure. The MenuItem field will contain a pointer to the MENUITEM structure. Returns Nothing. Remarks The application should fill in the BubbleText pointer of the QBUBBLEDATA structure. Note: This text string will be freed by UCMenus so it must be a dynamically allocated string. If the BubbleText field is NULL then no bubble help window will be displayed. Default Processing No default processing Related ═══ 12.25. UCN_QRYCONTEXTHWND ═══ This WM_CONTROL notification is sent by the UCMenu to its owner to obtain the handle of an application-supplied context menu. Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_QRYCONTEXTHWND Param2 MenuItem (MENUITEM *) Pointer to MENUITEM structure describing the item on which the context menu was requested. This structure will contain all binary zero values if the pointer was not over a menu item when the context menu was requested. Returns Nothing. Remarks The application can ignore this message if the UCMenus built-in context menu is to be used. Otherwise it should supply the handle of a context menu to be displayed. Selections on the context menu will generate UCN_CMITEM messages. Default Processing No default processing Related ═══ 12.26. UCN_CHANGEDITEM ═══ This WM_CONTROL notification is sent by the UCMenu to its owner when a menu item has been changed and it is not possible to determine which parts of the item were modified. Param1 UCMenuID (USHORT) ID of the UCMenu NotifCode (USHORT) UCN_CHANGEDITEM Param2 ItemID (USHORT) ID of the menu item that changed. Returns Nothing. Remarks In general the application will get notification messages for specific changes to menu items such as UCN_ACTION. However, when the MM_SETITEM message is used to update a menu item it is not possible to determine exactly what components of the item were changed and this message is generated. Idefproc. No default processing Related ═══ 13. UCMenu Message Reference ═══ This section describes all the messages an application can send to a UCMenu control to set and query various options. ═══ 13.1. UCMENU_QUERYSIZE ═══ This message is sent to the UCMenu to query the size it needs to be be fully displayed. Param1 pCx (PULONG) Pointer to a ULONG in which the width will be put. Param2 pCy (PULONG) Pointer to a ULONG in which the height will be put. Returns Success (BOOL) TRUE Query successful FALSE Query Unsuccessful Remarks Default Processing Related ═══ 13.2. UCMENU_QUERYCOLOR ═══ This message is sent to the UCMenu to query its color. Param1 pRGBColor (LONG *) Pointer to a LONG in which the RGB value of the UCMenu background color will be put. Param2 pItemRGBColor (LONG *) Pointer to a LONG in which the RGB value of the UCMenu items background color will be put. Returns Success (BOOL) TRUE Query successful FALSE Query Unsuccessful Remarks Default Processing Related ═══ 13.3. UCMENU_QUERYFONT ═══ This message is sent to the UCMenu to query its font. Param1 pszFontNameSize (PSZ) String in which the font name and size will be put, allocated by the sender. The string returned has the format used in WinSetPresParam. Param2 Size (ULONG) Size of the string allocated by the sender Returns Success (BOOL) TRUE Query successful FALSE Query Unsuccessful Remarks Default Processing Related WinSetPresParam, WinQueryPresParam. ═══ 13.4. UCMENU_QUERYSTYLE ═══ This message is sent to the UCMenu to query its style. Param1 pStyle (PULONG) Pointer to a ULONG in which the style will be put. The style is a combination of the UCS_* values. Returns Success (BOOL) TRUE Query successful FALSE Query Unsuccessful Param2 param2 (ULONG) reserved Remarks Default Processing Related ═══ 13.5. UCMENU_QUERYFORCEDSIZE ═══ This message is sent to the UCMenu to query the value of its forced size Param1 pCx (PULONG) Pointer to a ULONG in which the width will be put. Param2 pCy (PULONG) Pointer to a ULONG in which the height will be put. Returns Success (BOOL) TRUE Query successful FALSE Query Unsuccessful Remarks Default Processing Related ═══ 13.6. UCMENU_ADDITEMSTOCM ═══ This user message can be sent to the UCMenu to add items to its context menu Param1 NbOfItems (ULONG) Number of items to add Param2 pCMItems (PCMITEMS) Pointer to a CMITEMS structure. It contains an ID and pszText for each item added Returns nothing () Remarks This message should be sent, since the caller has to free pszItemText in the CMITEMS structure. Default Processing No default processing Related See CMITEMS type. See UCMENU_DELETECMITEM ═══ 13.7. UCMENU_DELETECMITEM ═══ This user message can be sent to the UCMenu to delete items from its context menu Param1 NbOfItems (ULONG) Number of items to delete. Param2 pItemId (PULONG) Array of items ids. Returns nothing Remarks By default, the context menu has the following items : Edit... IDM_UCM_EDIT Create... IDM_UCM_CREATE Delete IDM_UCM_DELETE Separator line IDM_UCM_SEPARATOR Style... IDM_UCM_STYLE Load Default IDM_UCM_DEFAULT Import... IDM_UCM_LOAD Export... IDM_UCM_SAVEAS Default Processing No default processing Related See CMITEMS type See UCMENU_ADDITEMSTOCM See UCN_CMITEM ═══ 13.8. UCMENU_QUERYVERSION ═══ This user message is sent to the UCMenu to query the version of the UCMenus dll Param1 param1 (ULONG) Reserved Param2 param2 (ULONG) Reserved Returns version (ULONG) Version number of the dll, eg 2 for 0.02 and 100 for 1.00. Remarks Default Processing No default processing Related ═══ 13.9. UCMENU_SETSTYLE ═══ This message is sent to the UCMenu to set the style flags and the associated width and height values. Param1 StyleFlags (ULONG) Combination of UCS_* flags. Param2 cx (USHORT) The width of the items if UCS_FORCESIZE is set. cy (USHORT) The height of the items if UCS_FORCESIZE is set. Returns Success (BOOL) TRUE if successful, FALSE else. Remarks A UCMENU_UPDATE message must be issued in order to reflect the changes. Default Processing Related UCMENU_UPDATE ═══ 13.10. UCMENU_QUERYUCMINFO ═══ This message is sent to the UCMenu to retrieve the UCMINFO structure Param1 pUCMInfo (PUCMINFO) Pointer to the UCMINFO structure to fill. Param2 param2 (ULONG) reserved. Returns Success (BOOL) TRUE if successful, FALSE else. Remarks If the PSZ fields are not null, they have been allocated by the UCMenu and have to be freed with UCMenuFree by the sender. Default Processing No default processing Related ═══ 13.11. UCMENU_UPDATE ═══ This message is sent to the UCMenu to display the changes made. Param1 param1 (ULONG) reserved. Param2 param2 (ULONG) reserved. Returns Success (BOOL) TRUE if successful, FALSE else. Remarks Default Processing No default processing Related UCMENU_SETSTYLE UCMENU_SETBGCOLOR ═══ 13.12. UCMENU_SETBGCOLOR ═══ This message is sent to the UCMenu to set the UCMenu background color Param1 BgColor (ULONG) The RGB color which will be used for the UCMenu background. Param2 ItemBgColor (ULONG) The RGB color which will be used for the items background. Returns Success (BOOL) TRUE if successful, FALSE else. Remarks Default Processing No default processing Related ═══ 13.13. UCMENU_SETFONT ═══ This message is sent to the UCMenu to set the UCMenu font. Param1 FontNameSize (PSZ) Font name, such as used in WinSetPresParam. Param2 - (ULONG) Reserved. Returns Success (BOOL) TRUE if successful, FALSE else. Remarks Default Processing No default processing Related ═══ 13.14. UCMENU_ACTIONSINSERTED ═══ This message is posted to the UCMenu by its owner when it has filled the list of actions Param1 param1 (ULONG) Reserved. Param2 param2 (ULONG) Reserved Returns nothing Remarks Default Processing Related UCMENU_INSERTACTION ═══ 13.15. UCMENU_INSERTACTION ═══ This message is sent to the UCMenu by its owner after it received UCN_QRYACTIONLIST. Param1 Action (PSZ) String including the name of the action eventually followed by parameters. Param2 Description (PSZ) A description of the action. Returns nothing Remarks This message has to be sent, not posted to the UCMenus control. Default Processing Related UCN_QRYACTIONLIST ═══ 13.16. UCMENU_SETBUBBLETIMERS ═══ This message is sent to the UCMenu by its owner to set the time delays associated with the bubble-help feature (UCS_BUBBLEHELP style). Param1 HoverDelay (ULONG) Number of msec pointer must hover over the same menu item before the bubble help is displayed. Maximum of 65000 msec (65 seconds). Param2 ReadTime (ULONG) Number of msec bubble help will be visible while pointer remains over the same menu item. Bubble help is removed when the pointer leaves the UCMenu toolbar if this time has not expired yet. Maximum of 65000 msec (65 seconds). Returns nothing Remarks Default Processing Related ═══ 13.17. UCMENU_ACTIVECHG ═══ This message is sent to the UCMenu by its owner whenever the frame window in which the menu exists becomes active or inactive. Param1 Activated (BOOL) TRUE if the window is being activated, FALSE if being deactivated. Param2 Reserved. Returns Nothing Remarks The owner must send this message whenever the window frame in which the toolbar exists becomes active or inactive. Example // Owner must notify toolbar on active status changes: case WM_ACTIVATE: /* Tell toolbar we are becoming active or inactive */ WinSendMsg(ToolHwnd, UCMENU_ACTIVECHG, mp1, MPVOID); break; Related ═══ 13.18. UCMENU_DISABLEUPDATE ═══ This message is sent to the UCMenu by its owner to disable updates to the toolbar window while items are inserted, deleted, or modified. Param1 Disable (BOOL) TRUE if updates are to be disabled, FALSE if they are to be shown. Param2 Reserved. Returns Nothing Remarks This message can be used to improve performance when more than one menu item will be inserted, deleted, or modified. The menu will not be visually updated when Disable is TRUE. Updates will be shown when Disable is FALSE. Note that a UCMENU_UPDATE message must be sent after the menu is disabled and then enabled to insure proper update if the window. Related ═══ 14. Programming Interfaces (API) ═══ This section describes each of the callable UCMenu programming interfaces. ═══ 14.1. UCMenuCreateFromResource ═══ This function creates a UCMenu using a menu template stored in the resources. Syntax: hUCMenu UCMenuCreateFromResource(hab hParent hOwner ulStyle x y cx cy hInsertBehind ulID hmodResource usMenuID pUCMInfo phTextMenu) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hab │HAB │input │Handle of the anchor-block. │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hParent │HWND │input │Handle of the parent window │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hOwner │HWND │input │Handle of the owner window │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │flStyle │ULONG │input │Style flags of the UCMenu window, combination of │ │ │ │ │WS_ flags and CMS_VERT, CMS_HORZ, CMS_MATRIX, │ │ │ │ │CMS_MATRIX_VERT, CMS_MATRIX_HORZ │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │x │ULONG │input │x coordinate of UCMenu window position │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │y │ULONG │input │y coordinate of UCMenu window position │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │cx │ULONG │input │width of the UCMenu window, ignored if vertical or│ │ │ │ │matrix UCMenu │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │cy │ULONG │input │height of the UCMenu window, ignored if horizontal│ │ │ │ │or matrix UCMenu │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hInsertBehind │ULONG │input │Sibling window behind which the UCMenu is placed, │ │ │ │ │can also be HWND_TOP or HWND_BOTTOM. │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │ulID │ULONG │input │ID given to the UCMenu. │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hmodResource │HMODULE │input │Handle of the module where the menu resource is to│ │ │ │ │be found. │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │usMenuID │USHORT │input │ID of the resource menu used as a template to │ │ │ │ │create the UCMenu. │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pUCMInfo │PUCMINFO │input │Pointer to the UCMINFO UCMenu creation structure │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │phTextMenu │PHWND │output │Handle of the menu loaded from the resource. It │ │ │ │ │should normally not be used. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │hUCMenu │PSZ │return │Handle of the UCMenu or NULLHANDLE if the creation│ │ │ │ │failed. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks Related UCMINFO data structure ═══ 14.2. UCMenuCreateFromHMenu ═══ This function creates a UCMenu using an already loaded or created PM text menu. Syntax: hUCMenu UCMenuCreateFromHMenu(hab hParent hOwner ulStyle x y cx cy hInsertBehind ulID hMenu pUCMInfo) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hab │HAB │input │Handle of the anchor-block. │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hParent │HWND │input │Handle of the parent window │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hOwner │HWND │input │Handle of the owner window │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │flStyle │ULONG │input │Style flags of the UCMenu window, combination of │ │ │ │ │WS_ flags and CMS_VERT, CMS_HORZ, CMS_MATRIX, │ │ │ │ │CMS_MATRIX_VERT, CMS_MATRIX_HORZ │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │x │ULONG │input │x coordinate of UCMenu window position │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │y │ULONG │input │y coordinate of UCMenu window position │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │cx │ULONG │input │width of the UCMenu window, ignored if vertical or│ │ │ │ │matrix UCMenu │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │cy │ULONG │input │height of the UCMenu window, ignored if horizontal│ │ │ │ │or matrix UCMenu │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hInsertBehind │ULONG │input │Sibling window behind which the UCMenu is placed, │ │ │ │ │can also be HWND_TOP or HWND_BOTTOM. │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │ulID │ULONG │input │ID given to the UCMenu. │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hMenu │HWND │input │Handle of the PM menu used as a template to create│ │ │ │ │the UCMenu │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pUCMInfo │PUCMINFO │input │Pointer to the UCMINFO UCMenu creation structure │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │hUCMenu │PSZ │return │Handle of the UCMenu or zero if the creation │ │ │ │ │failed. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks Note that the passed menu handle is the handle of a standard PM menu, not a UCMenu. This function can be used to create an empty UCMenu by first creating an empty PM menu as shown in the example below. Example // Create empty UCMenu from an empty PM menu PMMenu = WinCreateWindow(hwnd, // parent WC_MENU, // PM menu class "", // no window text MS_ACTIONBAR, // window style 0,0,0,0, // UCMenu will set size hwnd, // owner HWND_TOP, // top of siblings 0, // ID of the control NULL, // No ctl data -> empty menu NULL); // No pres parms UCMenu = UCMenuCreateFromHMenu(hab, hwnd, // parent hwnd, // owner to get msgs CMS_HORZ, // Orientation (CMS_* flags) 0,0,0,0, // Sizing will be done by UCMenu HWND_TOP, // Put on top of siblings ID_COPYMENU, // ID new menu will have PMMenu, // Handle of menu to use for template &UCMInfo); // Initialization data structure Related UCMINFO data structure ═══ 14.3. UCMenuCreateFromTemplate ═══ This function creates a UCMenu using an already loaded UCMenu template previously created by the UCMenuMakeTemplate function. Syntax: hUCMenu UCMenuCreateFromTemplate(hab hParent hOwner ulStyle x y cx cy hInsertBehind ulID pMenuTemplate pUCMInfo phTextMenu) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hab │HAB │input │Handle of the anchor-block. │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hParent │HWND │input │Handle of the parent window │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hOwner │HWND │input │Handle of the owner window │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │flStyle │ULONG │input │Style flags of the UCMenu window, combination of │ │ │ │ │WS_ flags and CMS_VERT, CMS_HORZ, CMS_MATRIX, │ │ │ │ │CMS_MATRIX_VERT, CMS_MATRIX_HORZ │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │x │ULONG │input │x coordinate of UCMenu window position │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │y │ULONG │input │y coordinate of UCMenu window position │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │cx │ULONG │input │width of the UCMenu window, ignored if vertical or│ │ │ │ │matrix UCMenu │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │cy │ULONG │input │height of the UCMenu window, ignored if horizontal│ │ │ │ │or matrix UCMenu │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hInsertBehind │ULONG │input │Sibling window behind which the UCMenu is placed, │ │ │ │ │can also be HWND_TOP or HWND_BOTTOM. │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │ulID │ULONG │input │ID given to the UCMenu. │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pmtMenuTemplate│PVOID │input │Pointer to the menu template in binary format │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pUCMInfo │PUCMINFO │input │Pointer to the UCMINFO UCMenu creation structure │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │phTextMenu │PHWND │output │Handle of the menu loaded from the resource. It │ │ │ │ │should normally not be used. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │hUCMenu │PSZ │return │Handle of the UCMenu or NULLHANDLE if the creation│ │ │ │ │failed. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks Note that the template is a UCMenu template which is not the same as a PM menu template. The templated passed in much have been created by a UCMenu template-creation function such as UCMenuMakeTemplate. Related UCMINFO data structure UCMenuMakeTemplate UCMenuSaveTemplate UCMenuLoadTemplate UCMenuSaveTemplateIni UCMenuLoadTemplateIni ═══ 14.4. UCMenuLoadBitmap ═══ This function loads a bitmap from a file and returns its handle. Syntax: hBitmap UCMenuLoadBitmap(pszFileName) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pszFileName │PSZ │input │Name of the file to load. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │hBitmap │LONG │return │Bit-map handle (0 if error) │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks If the bitmap file contains multiple resolutions, the bitmap the most appropriate to the current display will be chosen. Related ═══ 14.5. UCMenuMakeTemplate ═══ This function builds the UCMenu menu template associated with a specified UCMenu. Note that a UCMenu menu template is a binary data structure whose internal format is known and understood only by UCMenus. UCMenus templates should not be used to create standard PM menus, and PM menu templates cannot be used to create a UCMenu. Syntax: pBuffer UCMenuMakeTemplate(hwndUCMenu, pBufLen) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hwndUCMenu │HWND │input │UCMenu window handle. │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pBufLen │PULONG │output │Pointer to the UCMenu template buffer length. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │pBuffer │PVOID │return │Pointer to the template (NULL if error), has to be│ │ │ │ │freed by the caller with UCMenuFree. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks Related UCMenuCreateFromTemplate UCMenuSaveTemplate UCMenuLoadTemplate UCMenuSaveTemplateIni UCMenuLoadTemplateIni ═══ 14.6. UCMenuSaveTemplate ═══ This function builds and saves a UCMenu menu template. Note that a UCMenu menu template is a binary data structure whose internal format is known and understood only by UCMenus. UCMenus templates should not be used to create standard PM menus, and PM menu templates cannot be used to create a UCMenu. Syntax: bRc UCMenuSaveTemplate(hwndUCMenu, pszFileName) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hwndUCMenu │HWND │input │UCMenu window handle. │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pszFileName │PSZ │input │File name (NULL-terminated string) │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │bRc │BOOL │return │FALSE if an error occurred. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks Related UCMenuCreateFromTemplate UCMenuMakeTemplate UCMenuLoadTemplate UCMenuSaveTemplateIni UCMenuLoadTemplateIni ═══ 14.7. UCMenuLoadTemplate ═══ This function loads a UCMenu menu template from a file. Note that a UCMenu menu template is a binary data structure whose internal format is known and understood only by UCMenus. UCMenus templates should not be used to create standard PM menus, and PM menu templates cannot be used to create a UCMenu. Syntax: pBuffer UCMenuLoadTemplate(pszFileName, pBufLen) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pszFileName │PSZ │input │File name (NULL-terminated string) │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pBufLen │PULONG │output │Pointer to the length of the allocated buffer. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │pBuffer │PVOID │input │Pointer to a buffer (NULL if error). Note: The │ │ │ │ │buffer must be freed by the caller using the │ │ │ │ │UCMenuFree() function. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks Related UCMenuCreateFromTemplate UCMenuMakeTemplate UCMenuSaveTemplate UCMenuSaveTemplateIni UCMenuLoadTemplateIni ═══ 14.8. UCMenuSaveTemplateIni ═══ This function builds and saves a UCMenu menu template in an ini file. Note that a UCMenu menu template is a binary data structure whose internal format is known and understood only by UCMenus. UCMenus templates should not be used to create standard PM menus, and PM menu templates cannot be used to create a UCMenu. Syntax: bRc UCMenuSaveTemplateIni(hwndUCMenu, pszFileName, pszKeyName) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hwndUCMenu │HWND │input │UCMenu window handle. │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pszFileName │PSZ │input │File name (NULL-terminated string) │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pszKeyName │PSZ │input │Template name (NULL-terminated string) │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │bRc │BOOL │return │FALSE if an error occurred. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks Related UCMenuCreateFromTemplate UCMenuMakeTemplate UCMenuSaveTemplate UCMenuLoadTemplate UCMenuLoadTemplateIni ═══ 14.9. UCMenuLoadTemplateIni ═══ This function loads a UCMenu menu template from an ini file. Note that a UCMenu menu template is a binary data structure whose internal format is known and understood only by UCMenus. UCMenus templates should not be used to create standard PM menus, and PM menu templates cannot be used to create a UCMenu. Syntax: pBuffer UCMenuLoadTemplateIni(pszFileName, pszKeyName, pBufLen) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pszFileName │PSZ │input │Ini File name (NULL-terminated string) │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pszKeyName │PSZ │input │Template name (NULL-terminated string) │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pBufLen │PULONG │output │Pointer to the length of the allocated buffer. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │pBuffer │PVOID │input │Pointer to a buffer (NULL if error). Note: The │ │ │ │ │buffer must be freed by the caller using the │ │ │ │ │UCMenuFree() function. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks Related UCMenuCreateFromTemplate UCMenuMakeTemplate UCMenuSaveTemplate UCMenuLoadTemplate UCMenuSaveTemplateIni ═══ 14.10. UCMenuSaveStyle ═══ This function saves various UCMenu style-related information to a file. Syntax: bRC UCMenuSaveStyle(hwndMenu, pszFileName) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hwndUCMenu │HWND │input │UCMenu window handle. │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pszFileName │PSZ │input │File name (NULL-terminated string) │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │bRC │BOOL │return │FALSE if an error occurred. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks The following items are saved in the file: o Style flags o Current size (cx, cy) o Background color o Button face background color o Font name and size Related UCMenuLoadStyle UCMenuLoadStyleIni UCMenuSaveStyleIni ═══ 14.11. UCMenuLoadStyle ═══ This function loads a menu style from a file into a UCMINFO UCMenu creation structure. Syntax: bSuccess UCMenuLoadStyle(pszFileName, pUCMInfo) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pszFileName │PSZ │input │File name (NULL-terminated string) │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pUCMInfo │UCMINFO * │output │Pointer to the UCMINFO structure in which to load │ │ │ │ │the style │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │bSuccess │BOOL │return │FALSE if an error occurred. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks Related UCMenuSaveStyle UCMenuLoadStyleIni UCMenuSaveStyleIni ═══ 14.12. UCMenuSaveStyleIni ═══ This function saves the information relative to the style of a UCMenu in an ini file. Syntax: bRC UCMenuSaveStyleIni(hwndMenu, pszFileName, pszKeyName) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hwndUCMenu │HWND │input │UCMenu window handle. │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pszFileName │PSZ │input │File name (NULL-terminated string) │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pszKeyName │PSZ │input │Style name (NULL-terminated string) │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │bRC │BOOL │return │FALSE if an error occurred. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks The following items are saved: o Style flags o Current size (cx, cy) o Background color o Button face background color o Font name and size Related UCMenuLoadStyle UCMenuSaveStyle UCMenuLoadStyleIni ═══ 14.13. UCMenuLoadStyleIni ═══ This function loads a menu style from an ini file into a UCMInfo UCMenu creation structure. Syntax: bSuccess UCMenuLoadStyleIni(pszFileName, pszKeyName, pUCMInfo) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pszFileName │PSZ │input │File name (NULL-terminated string) │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pszKeyName │PSZ │input │Style name (NULL-terminated string) │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pUCMInfo │UCMINFO * │output │Pointer to the UCMInfo structure in which to load │ │ │ │ │the style │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │bSuccess │BOOL │return │FALSE if an error occurred. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks Related UCMenuLoadStyle UCMenuSaveStyle UCMenuSaveStyleIni ═══ 14.14. UCMenuFreeMenuData ═══ This function frees the data associated with the OWNERDRAW items of a menu. Syntax: - UCMenuFreeMenuData(hwndMenu) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hwndMenu │HWND │input │Menu window handle. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │- │VOID │- │Nothing. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks This function parses the whole menu (including submenus). It frees the data structure associated with every OWNERDRAW item. This function requires the owner of the menu to be the UCMenu. Note: This function is automatically executed when a UCMenu receives a WM_DESTROY message. Related ═══ 14.15. UCMenuIdFromCoord ═══ This function returns the id of the menu item that is at a specified position. Syntax: ItemID UCMenuIdFromCoord(hwndMenu, pptrPos) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hwndMenu │HWND │input │Menu window handle. │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pptrPos │PPOINTL │input │Position │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │ItemID │USHORT │return │The item Identifier. 0 if not found. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks This function doesn't check the submenus. However, you can identify an item in a submenu if you pass the hwnd of the submenu. Related ═══ 14.16. UCMenuGetActionID ═══ This function returns the ID of the item with a pszAction action, starting at the item sStart. Syntax: FoundID UCMenuGetActionID(hwndUCM, pszAction, , bSubmenus, sStart ) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hwndUCM │HWND │input │UCMenu window handle. │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pszAction │PSZ │input │Action string to look for │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │bSubmenus │BOOL │input │Look in submenus or not. │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │Start │SHORT │input │Item ID to start with, MIT_FIRST for the │ │ │ │ │beginning. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │FoundID │SHORT │return │Item ID found, or MIT_NONE │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks Note that more than one item in the menu may have the same action string. This function can be used to enumerate all the items in the menu with a particular action string. Related ═══ 14.17. UCMenuSetActionAttr ═══ This function sets the attributes of the items with the given action string. Syntax: void UCMenuSetActionAttr(hwndUCM, pszAction, usAttrMask, usAttrValue) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hwndUCM │HWND │input │UCMenu window handle. │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pszAction │PSZ │input │Action string to look for │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │usAttrMask │USHORT │input │Attribute mask to use │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │usAttrValue │USHORT │input │Attribute value to set │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │- │VOID │return │Nothing │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks A UCMenu may have more than one item with the same action string. This function will set the given attribte on all items in the menu with the given action string. Related ═══ 14.18. UCMenuLoadDefault ═══ This function updates the UCMenu with the default template. Syntax: bSuccess UCMenuLoadDefault(hwndUCMenu) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hwndUCMenu │HWND │input │Handle of the UCMenu │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │bSuccess │BOOL │return │True if successful, FALSE else │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks This call will cause the UCMenu to send a UCN_QRYDEFTEMPLATE or UCN_QRYDEFTEMPLATEID message to the owner to get the default template to be loaded. Related ═══ 14.19. UCMenuNew ═══ This function updates the UCMenu with a new template. Note that the template is a UCMenus template created with one of the UCMenu template functions (such as UCMenuMakeTemplate). A PM menu template may not be used. Syntax: bSuccess UCMenuNew(hwndUCMenu, pTemplate) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hwndUCMenu │HWND │input │Handle of the UCMenu │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pTemplate │PVOID │input │Template of the new menu. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │bSuccess │BOOL │return │True if successful, FALSE else │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks Related ═══ 14.20. UCMenuResourceBuffetDlg ═══ This dialog let the user pick items from a buffet toolbar coming from a resource. Syntax: - UCMenuResourceBuffetDlg(hParent, hUCMenu, ulBuffetID, hmodBuffet) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hParent │HWND │input │Parent of the dialog. │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hUCMenu │HWND │input │Handle of the UCMenu to modify. │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │ulBuffetID │ULONG │input │ID of the buffet menu. │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hmodBuffet │HMODULE │input │Module where the buffet menu is. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │ulResult │ULONG │return │result of WinDglBox │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks The purpose of this call is to allow easy drag-and-drop customization of a UCMenu. A dialog will be displayed which contains two UCMenus (the buffet menu and the menu to be customized). The user can drag items from the buffet and add them to the menu, and they can drag items from the menu to a shredder icon to delete them. The application supplies (via the ulBuffetID menu) the list of menu items the user can choose from. The user cannot change the bitmaps or action strings of the menu items, nor can they add new items not supplied by the application. When the user selects the OK button on the buffet dialog, the UCMenu represented by hUCMenu is updated. If the user cancels, the menu is not affected. When a menu is updated via the buffet dialog, all the current items of the menu will be deleted, followed by insertion of the new items. Applications which monitor the insert and delete of menu items should be prepared to handle this mass-delete and mass-insert which occurs when the menu is updated via the buffet dialog. Related ═══ 14.21. UCMenuTemplateBuffetDlg ═══ This dialog let the user pick items from a buffet toolbar coming from a template. Note that this template is a UCMenus template created by one of the UCMenu template functions. It is not a PM menu template. Syntax: - UCMenuTemplateBuffetDlg(hParent, hUCMenu, pTemplate) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hParent │HWND │input │Parent of the dialog. │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │hUCMenu │HWND │input │Handle of the UCMenu to modify. │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pTemplate │PVOID │input │Template of the buffet menu │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │ulResult │ULONG │return │result of WinDglBox │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks Related ═══ 14.22. UCMenuGetVersion ═══ This function returns the version of the UCMenus code. Syntax: ulVersion UCMenuGetVersion(-) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │ulVersion │ULONG │return │version of the UCMenus. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks Related ═══ 14.23. UCMenuAlloc ═══ External entry point to the allocation routine used by the UCMenus. Syntax: PVOID UCMenuAlloc(size) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │size │size_t │input │Size to allocate. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │pMem │PVOID │return │Pointer to the allocated memory or 0 if failure. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks Strings and structures which may passed to UCMenus should use the UCMenu memory allocation functions. Related UCMenuFree UCMenuStrdup ═══ 14.24. UCMenuStrdup ═══ Allocates and copies string using UCMenu memory allocation. Syntax: PSZ UCMenuStrdup(string) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │string │PSZ │input │String to be copied. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │copy │PSZ │return │Pointer to the copied string or 0 if failure. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks Strings and structures which may passed to UCMenus should use the UCMenu memory allocation functions. Related UCMenuFree UCMenuAlloc ═══ 14.25. UCMenuFree ═══ External entry point to the freeing routine used by the UCMenus. Syntax: - UCMenuFree(pMem) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │pMem │PVOID │input │Pointer to free. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │- │VOID │- │Nothing. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks Related UCMenuAlloc UCMenuStrdup ═══ 14.26. UCMenuItemDup ═══ Allocate storage for, and copy a UCMITEM structure including the strings it contains. Any of the string pointers may be NULL. Syntax: UCMITEM * UCMenuItemDup(UCMItem) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │UCMItem │UCMITEM * │input │Pointer to UCMITEM structure which is to be │ │ │ │ │duplicated. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │NewItem │UCMITEM * │returns │Returns a pointer to the new UCMITEM structure. │ │ │ │ │The structure will be filled with strings │ │ │ │ │duplicated from the original UCMITEM structure. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks Note that the structure as well as the string pointes are duplicated by this function. Related UCMenuAlloc UCMenuStrdup ═══ 14.27. UCMenuItemFree ═══ Free all strings in a UCMITEM structure and then free the storage for the structure itself. Any of the string pointers may be NULL. Syntax: void UCMenuItemFree(UCMItem) ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │Name │Type │In/Out │Description │ ├───────────────┼──────────┼──────────┼──────────────────────────────────────────────────┤ │UCMItem │UCMITEM * │input │Pointer to UCMITEM structure which contains │ │ │ │ │pointers to strings to be freed. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Returns ┌───────────────┬──────────┬──────────┬──────────────────────────────────────────────────┐ │- │VOID │- │Nothing. │ └───────────────┴──────────┴──────────┴──────────────────────────────────────────────────┘ Remarks Note that the structure as well as the string pointes are freed by this function. Related UCMenuAlloc UCMenuStrdup