home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / ucmenu.zip / UCMENUS.PAK / HELP / UCMREF.IPF < prev   
Text File  |  1995-09-28  |  113KB  |  2,904 lines
  1. .***************************************************************************
  2. .* UCMenus toolkit online reference.
  3. .*
  4. .* NOTE: The IPFC pre-processor utility (IPFCPREP) is required to
  5. .* process this document.
  6. .***************************************************************************
  7. .***************************************************************************
  8. .***************************************************************************
  9. .*                        DISCLAIMER OF WARRANTIES.                        *
  10. .***************************************************************************
  11. .***************************************************************************
  12. .*                                                                         *
  13. .*  Copyright (C) 1995 IBM Corporation                                     *
  14. .*                                                                         *
  15. .*      DISCLAIMER OF WARRANTIES.  The following [enclosed] code is        *
  16. .*      sample code created by IBM Corporation. This sample code is not    *
  17. .*      part of any standard or IBM product and is provided to you solely  *
  18. .*      for  the purpose of assisting you in the development of your       *
  19. .*      applications.  The code is provided "AS IS", without               *
  20. .*      warranty of any kind.  IBM shall not be liable for any damages     *
  21. .*      arising out of your use of the sample code, even if they have been *
  22. .*      advised of the possibility of such damages.                        *
  23. .***************************************************************************
  24. :userdoc.
  25. .********* Useful IPFC macros *********
  26. .dm UCMINFO on
  27. :link reftype=hd res=101.UCMINFO:elink.
  28. .dm off
  29. .dm UCMITEM on
  30. :link reftype=hd res=102.UCMITEM:elink.
  31. .dm off
  32. .dm CMITEMS on
  33. :link reftype=hd res=103.CMITEMS:elink.
  34. .dm off
  35. .dm WM_CONTROL on
  36. :link reftype=hd res=500.WM_CONTROL:elink.
  37. .dm off
  38. .dm QBUBBLEDATA on
  39. :link reftype=hd res=104.QBUBBLEDATA:elink.
  40. .dm off
  41.  
  42. .dm UCMenuItemFree on
  43. :link reftype=hd res=236.UCMenuItemFree:elink.
  44. .dm off
  45. .dm UCMenuItemDup on
  46. :link reftype=hd res=235.UCMenuItemDup:elink.
  47. .dm off
  48. .dm UCMenuFree on 
  49. :link reftype=hd res=234.UCMenuFree:elink.
  50. .dm off
  51. .dm UCMenuStrdup on
  52. :link reftype=hd res=233.UCMenuStrdup:elink.
  53. .dm off
  54. .dm UCMenuAlloc on
  55. :link reftype=hd res=232.UCMenuAlloc:elink.
  56. .dm off
  57. .dm UCMenuGetVersion on
  58. :link reftype=hd res=231.UCMenuGetVersion:elink.
  59. .dm off
  60. .dm UCMenuTemplateBuffetDlg on
  61. :link reftype=hd res=230.UCMenuTemplateBuffetDlg:elink.
  62. .dm off
  63. .dm UCMenuResourceBuffetDlg on
  64. :link reftype=hd res=219.UCMenuResourceBuffetDlg:elink.
  65. .dm off
  66. .dm UCMenuNew on
  67. :link reftype=hd res=218.UCMenuNew:elink.
  68. .dm off
  69. .dm UCMenuLoadDefault on
  70. :link reftype=hd res=217.UCMenuLoadDefault:elink.
  71. .dm off
  72. .dm UCMenuSetActionAttr on
  73. :link reftype=hd res=216.UCMenuSetActionAttr:elink.
  74. .dm off
  75. .dm UCMenuGetActionID on
  76. :link reftype=hd res=215.UCMenuGetActionID:elink.
  77. .dm off
  78. .dm UCMenuIdFromCoord on
  79. :link reftype=hd res=214.UCMenuIdFromCoord:elink.
  80. .dm off
  81. .dm UCMenuFreeMenuData on
  82. :link reftype=hd res=213.UCMenuFreeMenuData:elink.
  83. .dm off
  84. .dm UCMenuLoadStyleIni on
  85. :link reftype=hd res=212.UCMenuLoadStyleIni:elink.
  86. .dm off
  87. .dm UCMenuSaveStyleIni on
  88. :link reftype=hd res=211.UCMenuSaveStyleIni:elink.
  89. .dm off
  90. .dm UCMenuLoadStyle on
  91. :link reftype=hd res=210.UCMenuLoadStyle:elink.
  92. .dm off
  93. .dm UCMenuSaveStyle on
  94. :link reftype=hd res=209.UCMenuSaveStyle:elink.
  95. .dm off
  96. .dm UCMenuLoadTemplateIni on
  97. :link reftype=hd res=208.UCMenuLoadTemplateIni:elink.
  98. .dm off
  99. .dm UCMenuSaveTemplateIni on
  100. :link reftype=hd res=207.UCMenuSaveTemplateIni:elink.
  101. .dm off
  102. .dm UCMenuLoadTemplate on
  103. :link reftype=hd res=206.UCMenuLoadTemplate:elink.
  104. .dm off
  105. .dm UCMenuSaveTemplate on
  106. :link reftype=hd res=205.UCMenuSaveTemplate:elink.
  107. .dm off
  108. .dm UCMenuMakeTemplate on
  109. :link reftype=hd res=204.UCMenuMakeTemplate:elink.
  110. .dm off
  111. .dm UCMenuLoadBitmap on
  112. :link reftype=hd res=203.UCMenuLoadBitmap:elink.
  113. .dm off
  114. .dm UCMenuCreateFromTemplate on
  115. :link reftype=hd res=202.UCMenuCreateFromTemplate:elink.
  116. .dm off
  117. .dm UCMenuCreateFromHMenu on
  118. :link reftype=hd res=201.UCMenuCreateFromHMenu:elink.
  119. .dm off
  120. .dm UCMenuCreateFromResource on
  121. :link reftype=hd res=200.UCMenuCreateFromResource:elink.
  122. .dm off
  123.  
  124.  
  125. .dm UCMENU_INSERTACTION on
  126. :link reftype=hd res=664.UCMENU_INSERTACTION:elink.
  127. .dm off
  128. .dm UCMENU_ACTIONSINSERTED on
  129. :link reftype=hd res=663.UCMENU_ACTIONSINSERTED:elink.
  130. .dm off
  131. .dm UCMENU_SETFONT on
  132. :link reftype=hd res=662.UCMENU_SETFONT:elink.
  133. .dm off
  134. .dm UCMENU_SETBGCOLOR on
  135. :link reftype=hd res=661.UCMENU_SETBGCOLOR:elink.
  136. .dm off
  137. .dm UCMENU_UPDATE on
  138. :link reftype=hd res=660.UCMENU_UPDATE:elink.
  139. .dm off
  140. .dm UCMENU_QUERYUCMINFO on
  141. :link reftype=hd res=659.UCMENU_QUERYUCMINFO:elink.
  142. .dm off
  143. .dm UCMENU_SETSTYLE on
  144. :link reftype=hd res=658.UCMENU_SETSTYLE:elink.
  145. .dm off
  146. .dm UCMENU_QUERYVERSION on
  147. :link reftype=hd res=657.UCMENU_QUERYVERSION:elink.
  148. .dm off
  149. .dm UCMENU_DELETECMITEM on
  150. :link reftype=hd res=656.UCMENU_DELETECMITEM:elink.
  151. .dm off
  152. .dm UCMENU_ADDITEMSTOCM on
  153. :link reftype=hd res=655.UCMENU_ADDITEMSTOCM:elink.
  154. .dm off
  155. .dm UCMENU_QUERYFORCEDSIZE on
  156. :link reftype=hd res=654.UCMENU_QUERYFORCEDSIZE:elink.
  157. .dm off
  158. .dm UCMENU_QUERYSTYLE on
  159. :link reftype=hd res=653.UCMENU_QUERYSTYLE:elink.
  160. .dm off
  161. .dm UCMENU_QUERYFONT on
  162. :link reftype=hd res=652.UCMENU_QUERYFONT:elink.
  163. .dm off
  164. .dm UCMENU_QUERYCOLOR on
  165. :link reftype=hd res=651.UCMENU_QUERYCOLOR:elink.
  166. .dm off
  167. .dm UCMENU_QUERYSIZE on
  168. :link reftype=hd res=650.UCMENU_QUERYSIZE:elink.
  169. .dm off
  170. .dm UCMENU_SETBUBBLETIMERS on
  171. :link reftype=hd res=665.UCMENU_SETBUBBLETIMERS:elink.
  172. .dm off
  173. .dm UCMENU_ACTIVECHG on
  174. :link reftype=hd res=666.UCMENU_ACTIVECHG:elink.
  175. .dm off
  176. .dm UCMENU_DISABLEUPDATE on
  177. :link reftype=hd res=667.UCMENU_DISABLEUPDATE:elink.
  178. .dm off
  179.  
  180.  
  181.  
  182. .dm UCN_HLP_BUFFET on
  183. :link reftype=hd res=622.UCN_HLP_BUFFET:elink.
  184. .dm off
  185. .dm UCN_HLP_DM on
  186. :link reftype=hd res=621.UCN_HLP_DM:elink.
  187. .dm off
  188. .dm UCN_HLP_STYLE on
  189. :link reftype=hd res=620.UCN_HLP_STYLE:elink.
  190. .dm off
  191. .dm UCN_HLP_NB_ACTION on
  192. :link reftype=hd res=619.UCN_HLP_NB_ACTION:elink.
  193. .dm off
  194. .dm UCN_HLP_NB_CREATE on
  195. :link reftype=hd res=618.UCN_HLP_NB_CREATE:elink.
  196. .dm off
  197. .dm UCN_HLP_NB_BMP on
  198. :link reftype=hd res=617.UCN_HLP_NB_BMP:elink.
  199. .dm off
  200. .dm UCN_MOUSEMOVE on
  201. :link reftype=hd res=616.UCN_MOUSEMOVE:elink.
  202. .dm off
  203. .dm UCN_CMITEM on
  204. :link reftype=hd res=615.UCN_CMITEM:elink.
  205. .dm off
  206. .dm UCN_ACTION on
  207. :link reftype=hd res=614.UCN_ACTION:elink.
  208. .dm off
  209. .dm UCN_QRYRESBMP on
  210. :link reftype=hd res=613.UCN_QRYRESBMP:elink.
  211. .dm off
  212. .dm UCN_TEXT on
  213. :link reftype=hd res=612.UCN_TEXT:elink.
  214. .dm off
  215. .dm UCN_BITMAP on
  216. :link reftype=hd res=611.UCN_BITMAP:elink.
  217. .dm off
  218. .dm UCN_DELETEDITEM on
  219. :link reftype=hd res=610.UCN_DELETEDITEM:elink.
  220. .dm off
  221. .dm UCN_ADDEDITEM on
  222. :link reftype=hd res=609.UCN_ADDEDITEM:elink.
  223. .dm off
  224. .dm UCN_COLOR on
  225. :link reftype=hd res=608.UCN_COLOR:elink.
  226. .dm off
  227. .dm UCN_FONT on
  228. :link reftype=hd res=607.UCN_FONT:elink.
  229. .dm off
  230. .dm UCN_STYLE on
  231. :link reftype=hd res=606.UCN_STYLE:elink.
  232. .dm off
  233. .dm UCN_SIZE on
  234. :link reftype=hd res=605.UCN_SIZE:elink.
  235. .dm off
  236. .dm UCN_QRYACTIONLIST on
  237. :link reftype=hd res=604.UCN_QRYACTIONLIST:elink.
  238. .dm off
  239. .dm UCN_QRYDEFTEMPLATE on
  240. :link reftype=hd res=603.UCN_QRYDEFTEMPLATE:elink.
  241. .dm off
  242. .dm UCN_QRYDEFTEMPLATEID on
  243. :link reftype=hd res=602.UCN_QRYDEFTEMPLATEID:elink.
  244. .dm off
  245. .dm UCN_QRYTEMPLATEMODULE on
  246. :link reftype=hd res=601.UCN_QRYTEMPLATEMODULE:elink.
  247. .dm off
  248. .dm UCN_ITEMSELECTED on
  249. :link reftype=hd res=600.UCN_ITEMSELECTED:elink.
  250. .dm off
  251. .dm UCN_CHANGEDITEM on
  252. :link reftype=hd res=625.UCN_CHANGEDITEM:elink.
  253. .dm off
  254. .dm UCN_QRYBUBBLEHELP on
  255. :link reftype=hd res=623.UCN_QRYBUBBLEHELP:elink.
  256. .dm off
  257. .dm UCN_QRYCONTEXTHWND on
  258. :link reftype=hd res=624.UCN_QRYCONTEXTHWND:elink.
  259. .dm off
  260. .***************************************
  261. :title.User Customizable Menus
  262. .***************************************
  263. .imd ucmlocal.h
  264. :h1. Introduction
  265. This document is the programmer's reference for the User Customizable Menu
  266. (UCMenu) PM control.  For more information on programming with this
  267. control, see :hp1.OS/2 Developer Magazine:ehp1., Jan/Feb 1995, page 50.
  268. :artwork align=center name='ALLUCM.BMP'.
  269. :p.
  270. :hp7.Acknowledgments:ehp7.
  271. .br
  272. This control was originally conceived at the IBM Yorktown Research
  273. laboratory by Gennaro Cuomo and Juerg VonKaenel for use in EPM (the
  274. OS/2 enhanced system editor) with
  275. subsequent development
  276. contributions from Guillaume Le Stum, John Ponzo, Alan Warren and Alex
  277. Bertrand.  Mark McMillan of IBM Research Triangle Park developed the
  278. sample code, frame control utility functions, and initiated
  279. improvements in the architecture.
  280. :p.
  281. :hp7.Description:ehp7.
  282. .br
  283. The :hp3.User Customizable Menu:ehp3. is a very powerful, new user interface
  284. component, designed to overcome the problems with current menu and toolbar
  285. designs.
  286. It allows the user to define the ordering of menu items and
  287. visual representation (artwork and text) of menu items. New items, like
  288. "macro assignments" can be added dynamically. A user customizable menu can
  289. be saved in its present state for later use.
  290. The UCMenu changes itself into a
  291. "scrolling" mode when the number of selectable items exceeds the
  292. allotted window size.
  293. :p.
  294. Aside from the good graphical presentation, the most significant
  295. features of this control are the easy :hp1.user customization:ehp1. methods it
  296. provides (thus its name, UCMenus).  Customizing a UCMenu is made easy
  297. for the user by extensive use of direct manipulation techniques.  For
  298. example, to delete an item from the toolbar the user can drag the item
  299. to the system shredder.  Reordering the items is as easy as dragging
  300. the item to a new position and dropping it.  Many direct manipulation
  301. functions are provided by the control.
  302. :p.
  303. There are two basic customization methods for which UCMenus
  304. provides direct support:
  305. :ol.
  306. :li.:hp1.Free Form Customization&colon.:ehp1.  Using this method,
  307. the user can alter any aspect of any menu item, including the
  308. bitmap (graphical presentation), the application function
  309. associated with the item, etc.  An OS/2 notebook control provides
  310. easy customization of all aspects of the menu items.  This is
  311. the default method if not overridden by the application.
  312. :li.:hp1.Buffet Style Customization&colon.:ehp1.  Using this
  313. method, the application provides a fixed set ("buffet") of
  314. supported menu items.  The user can only select from the
  315. buffet and cannot modify the application functions associated
  316. with the menu items.  They cannot specify alternate or
  317. custom bitmaps for the graphical presentation.  This is the
  318. easiest form of customization method for novice users or for
  319. applications with a fixed set of toolbar items.
  320. :eol.
  321. :p.
  322. All customization is encapsulated in the UCMenu control itself.  The
  323. control and the application cooperate via messages to provide
  324. application specific information during customization.  Using the
  325. built-in customization methods the user can:
  326. :ul.
  327. :li.Modify styles related to visual effects.
  328. :li.Add and delete items and submenu items.
  329. :li.Replace bitmaps with .BMP files or application supplied bitmaps.
  330. :li.Edit the text under the bitmap.
  331. :li.Associate application functions with menu items (the
  332. application supplying the list of valid functions).
  333. :li.Move/copy menu items within a menu or between menus.
  334. :li.Restore the entire menu to an application-defined default state.
  335. :eul.
  336. The application can restrict what customization functions are allowed
  337. through the use of style flags.
  338. :h1.Programming Concepts
  339. :p.
  340. There are several key concepts which need to be understood to make
  341. effective use of UCMenu controls in an application program.  As its
  342. name implies, the basic paradigm of a UCMenu control is that of a
  343. normal PM text menu; the control contains selectable items, submenus,
  344. separators, item attributes, etc.  (The current implementation is
  345. limited to a single level of submenus.)  The
  346. developers view of this control is also similar to that of a PM menu
  347. control.  This similarity is by design and allows anyone familiar with
  348. PM menus to grasp the terminology, concepts, and messages involved
  349. with UCMenu controls.  It is important to recognize that there are
  350. some key differences, many of which we will cover in this article.
  351. :p.
  352. The UCMenu control uses many of the same menu-related messages and
  353. data structures as its PM menu counterpart.
  354. For example, a MM_QUERYITEM message can
  355. be sent to the UCMenu window to obtain a MENUITEM structure which
  356. describes a particular item in the menu.  The application will
  357. receive all the standard PM menu notification messages except
  358. WM_DRAWITEM and WM_MEASUREITEM which are used internally by the
  359. UCMenu, and WM_COMMAND which is replaced with a :WM_CONTROL. message.
  360. :p.
  361. Because of its added visual and interactive complexity, the standard
  362. PM menu structures and messages are not sufficient to implement a
  363. customizable graphical menu bar.  Thus, UCMenus add another layer of
  364. messages and data structures on top of the PM menu architecture.  It
  365. is important to understand the new concepts that UCMenus brings to
  366. the existing menu architecture and how the PM menu architecture has
  367. been extended to accommodate them.  The following sections
  368. describe some of these extensions.
  369. .*******************************************************************************
  370. :h2.UCMenu Action Strings
  371. One of the most important new concepts that UCMenus brings to a menu is
  372. that of :hp1.actions:ehp1..  An :hp1.action:ehp1. is a textual description of the
  373. function assigned to a particular menu item.  It is an arbitrary string
  374. defined by the application and seen by the user when customizing a
  375. UCMenu.
  376. For example, a text editor might define action strings like:
  377. :xmp.
  378.   "Copy to Clipboard"
  379.   "Paste from Clipboard"
  380.   "Left Justify"
  381.   "Select Fonts"
  382.   ...etc...
  383. :exmp.
  384. When a user creates a new UCMenu item or modifies an existing item,
  385. they will select from a list of actions supplied by the application.
  386. :p.
  387. For a UCMenu control, the menu item IDs are arbitrary and can change during
  388. execution of the program.  An application cannot know ahead of time
  389. what the item IDs are going to be for any particular menu item.
  390. When a user adds a new menu item
  391. to an existing UCMenu toolbar the UCMenu control supplies all the
  392. user interface necessary for the user to choose a bitmap, text, and an
  393. application-specific action for the new item.  When the new item is
  394. added to the menu, the UCMenu control will choose an arbitrary item ID
  395. which is unique throughout the menu and all submenus.  Likewise, items
  396. can be moved and copied between UCMenu toolbars.  The resulting (new)
  397. menu items are assigned arbitrary IDs that do not conflict with any
  398. existing items.
  399. :p.
  400. Therefore, an application cannot depend on using
  401. item IDs to determine what function was selected on a UCMenu toobar.
  402. Instead, the application must use the :hp1.action string:ehp1. associated with the menu
  403. item to determine what function has been selected.  A UCMenu control
  404. will send a :WM_CONTROL. message with a notification code of
  405. :UCN_ITEMSELECTED. when an item is selected.  The application will not
  406. receive a WM_COMMAND message from a UCMenu control.
  407. :p.
  408. The application must associate the action string of the selected menu
  409. item with an application function.  The toolkit sample program
  410. (SAMP1.C) uses a table which maps action strings to fixed ID values.
  411. The action of the selected item is looked up in the table and then a
  412. simple switch can be used to select the correct application function.
  413. The ID values chosen for the table purposefully match the fixed
  414. item IDs used in the applications standard PM menu bar (the application
  415. has both UCMenu toolbars and a standard PM menu bar).  Thus, the same
  416. switch can be used to process WM_COMMAND messages from the PM menu and
  417. :WM_CONTROL. messages from the UCMenus.  This reduces code size and keeps
  418. application specific function from being duplicated.
  419. .******************************************************************************
  420. :h2.Data Structures
  421. :p.
  422. There are two primary data structures related to UCMenu controls.
  423. Associated with each UCMenu window is a set of data which describes
  424. various aspects of the overall toolbar appearance and behavior.  This
  425. includes information such as style flags, menu colors and text font.
  426. This is the :UCMINFO. structure.
  427. It is filled in by
  428. the application and used during creation of a UCMenu control.
  429. :p.
  430. Associated with each item of the menu are two linked data structures.
  431. The first is the
  432. standard PM MENUITEM structure.  That structure contains an 'item
  433. handle' which is generally reserved for application use.  A UCMenu
  434. uses the item handle to point to a :UCMITEM. structure which provides
  435. UCMenu specific item information.  In effect, the MENUITEM structure
  436. is extended for UCMenu specific data. It should be noted that
  437. any of the string pointers in the :UCMITEM. structure can be null.
  438. :p.
  439. These data structures are used extensively in the processing of
  440. messages to and from the UCMenu control.
  441. :p.
  442. .************************************************************************
  443. :h2.Checkable Menu Items
  444. The fact that a UCMenu can be extensively customized by the user has
  445. some important implications for applications with 'checkable' style
  446. menu items.  Like a PM menu, any item in a UCMenu can be checked
  447. simply by setting the MIA_CHECKED attribute for that item.  A menu
  448. item should be checkable if the action associated with it represents
  449. the toggling of some application state. A checked menu item is
  450. indicated in a UCMenu by drawing a thick border around it.
  451. :p.
  452. When a UCMenu item is created by the user the MIA_CHECKED attribute is
  453. not set.  Thus, if the action selected by the user for the new item is
  454. a toggle function, the application should update the current state of
  455. the item with the current state of the application.
  456. :p.
  457. Likewise, when a menu item is modified and assigned a new action, the
  458. current attributes are not changed.  If the new action is a toggle
  459. function, the item attribute must be updated to reflect the current
  460. application state.  If the action is not a toggle function, the
  461. MIA_CHECKED attribute should be cleared since the previous action may
  462. have been checked.
  463. :p.
  464. The UCMenu control will send a :WM_CONTROL. message with a notification
  465. code of :UCN_ADDEDITEM. or :UCN_ACTION. when a new item is added or an
  466. action is changed.  When these messages are received, the application
  467. must examine the new action and set or clear the MIA_CHECKED
  468. attribute.
  469. :p.
  470. When the application is notified of a selection on a checkable UCMenu
  471. item, the application must toggle the check state.  In a standard PM
  472. menu it is sufficient to toggle the state of just the menu item
  473. selected.  Since a UCMenu may have the same (toggle) action on
  474. different items in the same menu, the check state of :hp1.all:ehp1. items with
  475. the toggle action must be updated.
  476. This function has been
  477. incorporated into the UCMenu API set with the function
  478. :UCMenuSetActionAttr..  This API will set the attributes of all
  479. items in the UCMenu with the specified action string.  If the
  480. application has multiple UCMenu toolbars, all must be updated since the
  481. action may exist in any of them.
  482. :p.
  483. :h2.Customization Messages
  484. Easy customization of the toolbar is one of the most useful and
  485. powerful features of this control.  It gives the user complete
  486. flexibility to add and delete menu items, rearrange the order, create
  487. submenus, and move and copy items between toolbars.  Encapsulation of
  488. these functions into the UCMenu control means that there is very little
  489. application code required to support customization.
  490. :p.
  491. Although most of the customization function is encapsulated in the
  492. control itself, there are several messages to which the application
  493. must respond for customization to work properly.  The UCMenu control
  494. will send :WM_CONTROL. messages to its owner when it needs certain types
  495. of information.  Depending on what type of customization the
  496. application allows (free-form or 'buffet' style), some of
  497. these message may not be generated.
  498. The :WM_CONTROL. notification codes for customization are as follows:
  499. :ul.
  500. :li.:UCN_QRYDEFTEMPLATEID.&colon.  This is sent when the user selects the :hp1.Load
  501. default:ehp1. context menu item to restore the entire UCMenu to its
  502. default configuration.  The application responds by supplying the
  503. resource ID of the menu template to be loaded.
  504. :li.
  505. :UCN_QRYTEMPLATEMODULE.&colon.  This is also sent when the :hp1.Load default:ehp1.
  506. context menu item is selected.  The application must supply the
  507. handle of the module in which the :UCN_QRYDEFTEMPLATEID. resource is to be
  508. found.
  509. :li.
  510. :UCN_QRYRESBMP.&colon.  This message is sent when the user wants to display a
  511. list of application-supplied bitmaps from which to choose.  The
  512. application must allocate and construct an array of bitmap resource
  513. IDs.
  514. This message is generated by the free-form customization method.
  515. :li.
  516. :UCN_QRYACTIONLIST.&colon.  This message is sent when the user has requested
  517. a list of actions from which to choose.  The application responds by
  518. sending a series of :UCMENU_INSERTACTION. messages, each with a pointer
  519. to an action string and descriptive help text.  After the last action
  520. has been inserted, the application must send :UCMENU_ACTIONSINSERTED.
  521. to indicate the list is complete.
  522. This message is generated by the free-form customization method.
  523. :li.
  524. UCN_HLP_*&colon. This is a set of messages sent when the UCS_CUSTOMHLP
  525. menu style is used and the user requests help on a customization
  526. dialog.  By default the UCMenu control will supply the needed help
  527. text.
  528. :eul.
  529. The handling of all these messages is demonstrated in the SAMP3.C
  530. sample program in the toolkit.
  531. .**********************************************************************************
  532. :h2.Control of Customization
  533. The highly flexible customization built-in to the UCMenu control may
  534. not be desirable for all applications or situations.  For example, the
  535. ability to move items from one menu to another within an application
  536. may not make semantic sense.  An application with multiple windows
  537. performing different functions may not want to allow the user to drag
  538. items from the toolbar in one window to the toolbar in another.  The
  539. result might be 'actions' which make no sense in the context of the
  540. window.  The application may also want to provide its own
  541. customization methods to replace or supplement those of UCMenus.
  542. :p.
  543. By default, all the direct manipulations and all
  544. the context menu options are allowed.  No buffet dialog
  545. is displayed unless explicitly called using the UCMenuXXXXBuffetDlg() APIs.
  546. Various
  547. style flags (UCS_*) can be used by the application to control which
  548. direct manipulation and context menu functions are supported for that
  549. instance of the menu.  At the extreme, the application can set a style
  550. of UCS_STATIC to prevent any customization at all.  This style will
  551. disable all direct manipulation functions and the context menu.  Other
  552. style flags allow selective disabling of specific customization
  553. functions, such as disabling drag/drop between menus (but allowing it
  554. within a menu), disabling drops to the system shredder, removing the
  555. 'Edit item...'  context menu option, etc.
  556. :p.
  557. An application can also supply its own customization functions via the
  558. UCMenu context menu.  By sending the control a :UCMENU_ADDITEMSTOCM.
  559. message the application can add its own options to the context menu.
  560. The UCMenu control will send a :WM_CONTROL. message with a
  561. notify code of :UCN_CMITEM. when such an option is selected.  A sample
  562. of adding an application customization function to the context menu is
  563. shown in the SAMP3.C toolkit sample.
  564. .******************************************************************************
  565. :h1.Version Notice
  566. .br
  567. This document describes Version 2.11 of the UCMenus control.  Version 2.11 is
  568. :hp1.not:ehp1. binary-compatible with applications written for Version 1
  569. or Version 2.0.  This version is :hp1.source:ehp1. compatible with Version 2.0.
  570. :hp1.The size of some data structures were changed in this version so applications
  571. must be recompiled.:ehp1.
  572. :p.
  573. Version 2.11 contains the following major changes from Version 2.1:
  574. :ul.
  575. :li.Two new styles, CMS_MATRIX_VERT and CMS_MATRIX_HORZ allow matrix
  576. style menus be scrollable in the vertical or horizontal direction.  SAMP1 of
  577. the toolkit uses this style for the tool palette menu.
  578. :li.The frame is now activated when a button is pressed on a UCMenu
  579. control.  This prevents UCMenu context menus from appearing in
  580. a non-active frame.
  581. :li.Fixed memory leaks.
  582. :li.Improved scrolling such that UCMenus does not always return to a
  583. scroll position of zero when items are inserted, deleted, or modified.
  584. :eul.
  585. :p.
  586. Version 2.1 contains the following major changes from Version 2.0:
  587. :ul.
  588. :li.Improved :UCN_MOUSEMOVE. message generation.
  589. :li.Added support for bubble-help (cartoon-like bubble with extended description text).
  590. :li.Added following APIs:
  591. :ul compact.
  592. :li.:UCMenuStrdup.
  593. :li.:UCMenuItemDup.
  594. :li.:UCMenuItemFree.
  595. :eul.
  596. :li.Added support for application-supplied context menu.
  597. :li.Added compile-time UCMUI define statement.  Removing this statement
  598. produces a UCMenus control with no user-interface (customization) code.
  599. :li.Submenus are now dismissed when the application window becomes inactive (application
  600. must send new :UCMENU_ACTIVECHG. messages).
  601. :li.Changed item sizing algorithms such that item text is never truncated even for
  602. UCS_FORCESIZE style menus.  Item width is always set to larger of the bitmap width and
  603. the text width.
  604. :li.Added :UCMENU_DISABLEUPDATE. message to improve performance during large number
  605. of item insert/delete/modify.
  606. :li.The :hp1.pszDefaultBitmap:ehp1. field of the UCMINFO structure can now be a resource
  607. ID (in string form) or a filename.
  608. :li.Changed UCMENUS.RCH to UCMLOCAL.H since some build systems require header to have .H extension.
  609. :li.Fixed bug that caused application to hang if application had its own drag/drop functions
  610. in addition to the toolbar.
  611. :li.Improved handing of bitmap background colors:
  612. :ul compact.
  613. :li.New style UCS_CHNGBMPBG_AUTO will use the lower leftmost pixel of the bitmap to determine the
  614. background color (the :hp1.BmpBg:ehp1. field of UCMINFO is ignored).  This allows different
  615. bitmaps of the toolbar to have different transparent colors.
  616. :li.Improved algorithms to not assume 256-color bitmaps (less memory, faster execution).
  617. :li.Improved algorithms such that background colors are mapped only when the bitmap
  618. is first loaded (instead of every time the toolbar is painted).
  619. :li.All bitmaps are reloaded (and color mapped) when the background color is changed.
  620. This prevents valid colors in the bitmap from getting set to the background when
  621. several color changes are made in sequence.
  622. :li.Removed lCurBmpBgColor from UCMITEM structure since it is no longer needed.
  623. :eul.
  624. :li.Fixed stray-pixel problems when a partially-obscured button is pressed.
  625. :li.Many minor bug fixes and code changes to improve performance (in particular, store
  626. often-used window handles in UCMDATA to avoid lots of WinQueryWindow() calls).
  627. :eul.
  628. .*----------------------------------------------------------------------------
  629. :h1.Limitations and Known Problems
  630. :ul.
  631. :li.A bug in OS/2 Warp 3.0 can cause random bitmap corruption to occure during drag/drop
  632. operations.  Usually seen as the toolbar changing size unexpectedly and one or
  633. more toolbar bitmaps being corrupted.  Bug was reported to OS/2 development
  634. as APAR PJ17913.  This APAR is reported to be fixed in Warp fixpack #7.  This problem
  635. does not occure in OS/2 Version 2.X.
  636. :li.A bug in PM prevents support of MIS_BREAK on submenus (MM_QUERYITEMRECT
  637. can return wrong coordinates when an owner-draw submenu has MIS_BREAK style
  638. items).  Any MIS_BREAK style flags are removed when the UCMenu is created.
  639. :li.Bubble help is not implemented for submenus.
  640. :eul.
  641. .*----------------------------------------------------------------------------
  642. :h1.Direct Manipulations
  643. UCMenus support the following direct manipulation functions:
  644. :ul.
  645. :li.
  646. Move menu items: drag and drop menu items from one position to another.
  647. New position will be insertion point nearest the mouse cursor when
  648. the item is dropped.  MIS_SPACER items can also be moved.  Items
  649. may be moved from one toobar to another.
  650. :li.
  651. Copy menu items: drag and drop menu items with the CTRL key
  652. pressed.   Items may be copied from one toolbar to another.
  653. :li.
  654. Copy to submenu: drag menu item with ALT key pressed and drop on
  655. another menu item.  If the target
  656. item is not a submenu it will be changed to be one.  The dropped item
  657. is inserted after the last item already in the submenu.
  658. Submenu items can be copied from one toolbar to another.
  659. :li.
  660. Delete menu items: drag menu item to system shredder.
  661. :li.
  662. Create new items: drag .BMP file type from desktop or drives folder
  663. onto a toolbar.  A new item with the supplied bitmap will be
  664. created.  The item will not have any text or action associated with it
  665. until provided with the context menu 'Edit item' option.
  666. :li.
  667. Render bitmap to file: a menu item which has file-supplied bitmap (the
  668. bitmap specification is a file name, not an application resource) can
  669. be dragged to the OS/2 desktop or a folder to create a .BMP file.
  670. The bitmap can also be dropped on the OS/2 Icon Editor desktop object
  671. to open and edit the source bitmap file.
  672. :li.
  673. Change colors: a color can be dragged from the system color palette
  674. onto the toolbar background or the item background.  All items will
  675. have the same background color.
  676. :li.
  677. Change font: a font can be dragged from the system font palette onto the
  678. toolbar.  The dropped font will be used for the text under the
  679. bitmaps.
  680. :eul.
  681. Items can also be created, deleted and edited with the context menu
  682. which may be displayed by positioning the cursor on a menu item and
  683. pressing the right mouse button (if the 'Edit' context menu
  684. item is enabled by the application).
  685. .*-------------------------------------------------------------------------
  686. :h1.Submenus
  687. UCMenus supports graphical submenus in a similar fashion to normal PM
  688. submenus.  Visually, a submenu is a vertical UCMenu which is invoked
  689. by selecting from a primary UCMenu item (the submenu 'placeholder'):
  690. :artwork align=center name='SUCM.BMP'.
  691. :p.
  692. Only one level of submenu is supported.  A submenu cannot contain
  693. multiple columns (e.g. the MIS_BREAK style flag is ignored).  A
  694. submenu can be customized like the main menu by drag/drop reordering
  695. of items, adding items by dropping from other menu or submenus,
  696. using the context menu to insert, delete, or modify items, etc.
  697. :p.
  698. Submenus inheret style settings from the parent (main) menu,
  699. including background colors, fonts for text, etc.
  700. :p.
  701. :hp1.Limitations&colon.:ehp1.
  702. :ul.
  703. :li.A submenu cannot use the MIS_BREAK style to have multiple columns
  704. of selectable items.
  705. :li.An attribute of MIA_NODISMISS on a submenu placeholder is ignored.  To
  706. prevent a submenu from being dismissed when an item is selected, the
  707. item itself must have the MIA_NODISMISS attribute.  Submenu items without
  708. this attribute will cause the submenu to be dismissed when the item
  709. is selected.
  710. :eul.
  711. .*-------------------------------------------------------------------------
  712. :h1.Styles
  713. The visual appearance of a UCMenu can be
  714. modified through the use of 'style' flags.
  715. UCMenu toolbars can have a vertical, horizontal, or matrix layout:
  716. :ul compact.
  717. :li.
  718. :hp1.CMS_HORZ:ehp1.  The traditional horizontal menu bar style. If the
  719. number of items do not fit, scrolling indicators are shown. This is contrary
  720. to the style of menu bars which would wrap.
  721. :fig.
  722. :artwork name='HUCM.BMP'.
  723. :figcap.Horizontal arrangement
  724. :efig.
  725. :p.
  726. :li.
  727. :hp1.CMS_VERT:ehp1.  Display as a vertical column.  This is a very useful
  728. arrangement to display a small set of tools to the left or right of a
  729. window.
  730. :fig.
  731. :artwork name='VUCM.BMP'.
  732. :figcap.Vertical arrangement
  733. :efig.
  734. :p.
  735. :li.
  736. :hp1.CMS_MATRIX:ehp1.  A matrix arrangement, as it is typically used for tool palettes.  The
  737. matrix may free-form (application defines height and width), or it may have an
  738. orientation in which case it becomes scrollable in that direction (CMS_MATRIX_HORZ, or
  739. CMS_MATRIX_VERT).
  740. :fig.
  741. :artwork name='MUCM.BMP'.
  742. :figcap.Matrix arrangement.
  743. :efig.
  744. :eul.
  745. The
  746. bitmap items can be drawn with or without 3D frames, text underneath,
  747. and with a fixed or automatic sizing.  Individual items can be
  748. highlighted with a 'checkmark' attribute and are drawn with thick dark
  749. borders.  Background colors of the menu items and empty toolbar spaces
  750. can also be controlled.  When required by window size, scrollbar
  751. controls will automatically appear at each end of the toolbar.
  752. :p.
  753. A UCMenu can have a number of different styles that can be set on creation in
  754. the :UCMINFO. structure and changed dynamically through the context menu&colon.
  755. :parml compact break=all.
  756. :pt.:hp2.UCS_NOTEXT:ehp2.
  757. :pd.The text associated with the item is not displayed on the screen.
  758. :pt.:hp2.UCS_FRAMED:ehp2.
  759. :pd.When this is set, a frame is drawn around each item so that it looks like a 3-D
  760. button.
  761. :pt.:hp2.UCS_FORCESIZE:ehp2.
  762. :pd.The size of all items can be forced to a certain rectangle. If this is set, the size
  763. has to be specified in the :UCMINFO. structure (UCMInfo.cx and UCMInfo.cx)
  764. :pt.:hp2.UCS_SHRINK_BLEND:ehp2.
  765. :pd.When set, either BBO_OR or BBO_AND is used to shrink the bitmaps, else BBO_IGNORE is used
  766. :pt.:hp2.UCS_SHRINK_OR:ehp2.
  767. :pd.Used when BBO_IGNORE not selected. If set BBO_OR is used, else BBO_AND
  768. :pt.:hp2.UCS_NO_DM_ALT:ehp2.
  769. :pd.No drag and drop copy to a submenu when doing an Alt-drop over the UCMenu
  770. :pt.:hp2.UCS_NO_DM_M_TO_OTHER:ehp2.
  771. :pd.No drag and drop move to another UCMenu
  772. :pt.:hp2.UCS_NO_DM_M_FROM_OTHER:ehp2.
  773. :pd.No drag and drop move from another UCMenu
  774. :pt.:hp2.UCS_NO_DM_M_INSIDE:ehp2.
  775. :pd.No drag and drop move inside this UCMenu
  776. :pt.:hp2.UCS_NO_DM_C_TO_OTHER:ehp2.
  777. :pd.No drag and drop copy to another UCMenu
  778. :pt.:hp2.UCS_NO_DM_C_FROM_OTHER:ehp2.
  779. :pd.No drag and drop copy from another UCMenu
  780. :pt.:hp2.UCS_NO_DM_C_INSIDE:ehp2.
  781. :pd.No drag and drop copy inside this UCMenu
  782. :pt.:hp2.UCS_NO_DM_DISCARD:ehp2.
  783. :pd.No drag and drop to the shredder
  784. :pt.:hp2.UCS_NO_DM_RENDER_TO_BMP:ehp2.
  785. :pd.No drag and drop rendering as a BMP file
  786. :pt.:hp2.UCS_NO_DM_RENDER_FROM_BMP:ehp2.
  787. :pd.No drag and drop from a BMP file
  788. :pt.:hp2.UCS_NO_DM:ehp2.
  789. :pd.No direct manipulation at all
  790. :pt.:hp2.UCS_NO_CM_MENU_STYLE:ehp2.
  791. :pd.No "change style" in the context menu
  792. :pt.:hp2.UCS_NO_CM_MENU_IMPORT:ehp2.
  793. :pd.No "import" in the context menu
  794. :pt.:hp2.UCS_NO_CM_MENU_EXPORT:ehp2.
  795. :pd.No "export" in the context menu
  796. :pt.:hp2.UCS_NO_CM_MENU_DEFAULT:ehp2.
  797. :pd.No "load default" in the context menu
  798. :pt.:hp2.UCS_NO_CM_ITEM_EDIT:ehp2.
  799. :pd.No "edit item" in the context menu
  800. :pt.:hp2.UCS_NO_CM_ITEM_CREATE:ehp2.
  801. :pd.No "create item" in the context menu
  802. :pt.:hp2.UCS_NO_CM_ITEM_DELETE:ehp2.
  803. :pd.No "delete item" in the context menu
  804. :pt.:hp2.UCS_NO_CM_SEPARATOR:ehp2.
  805. :pd.No "delete item" in the context menu
  806. :pt.:hp2.UCS_NO_CM:ehp2.
  807. :pd.No context menu
  808. :pt.:hp2.UCS_CHNGBMPBG:ehp2.
  809. :pd.When this style is used the background color of the bitmaps is
  810. mapped to the background color of the toolbar.  The background color
  811. of the bitmaps is defined as
  812. the :hp1.BgBmp:ehp1. color in the :UCMINFO. structure.  All pixels
  813. in all bitmaps which match that color will be changed to the toolbar
  814. background color.  This style should not be used with UCS_CHNGBMPBG_AUTO.
  815. :pt.:hp2.UCS_CHNGBMPBG_AUTO:ehp2.
  816. :pd.When this style is used the background color of the bitmaps is
  817. mapped to the background color of the toolbar.  The background color of
  818. the bitmaps is defined as the color of the pixel in the lower leftmost corner
  819. of the bitmap.  All pixels of that same color in the bitmap are changed
  820. to the toolbar background color.  The :hp1.BgBmp:ehp1. field of the :UCMINFO. structure
  821. is ignored.  This style should not be used with UCS_CHNGBMPBG. 
  822. :pt.:hp2.UCS_CUSTOMHLP:ehp2.
  823. :pd.The help is provided by the user.
  824. :pt.:hp2.UCS_PROMPTING:ehp2.
  825. :pd.:UCN_MOUSEMOVE. notifications are sent to the owner.
  826. :pt.:hp2.UCS_NODEFAULTACTION:ehp2.
  827. :pd.The list of actions does not include executeprogram by default.
  828. :pt.:hp2.UCS_BUBBLEHELP:ehp2.
  829. :pd.Enables the display of cartoon-style bubble help.  When the pointer
  830. hovers on a single menu item for a defined period of time (:hp1.BubbleDelay:ehp1. in
  831. :UCMINFO.) the toolbar will query the application for the help text to
  832. be displayed in the bubble window (:UCN_QRYBUBBLEHELP.).  If the application
  833. supplies help text, it will be displayed in a cartoon-like window near the
  834. menu item.  The bubble window is removed when the pointer leaves the
  835. toolbar, or when the :hp1.BubbleRead:ehp1. time period expires, whichever
  836. occures first.  The application :hp2.must:ehp2. send :UCMENU_ACTIVECHG. messages
  837. for the bubble window to work properly.
  838. :eparml.
  839. :p.The UCM text font and background color can be set on creation, through the :UCMINFO.
  840. structure. The default font is Helv 8. Note that the color corresponds to the RGB index
  841. and can look different on different types of displays and adapters. You should use the index returned by
  842. WinQuerySysColor().
  843. :xmp.
  844.  
  845. #define UCM_DEFAULTCOLOR     0x00C9C9C9L   // -- light grey on 8514
  846. #define UCM_DEFAULTFONT      "8.Helv"
  847.  
  848. :exmp.
  849. .*-------------------------------------------------------------------------
  850. :h1.Creating a UCMenu Control
  851. Conceptually, creating a UCMenu control is the same as creating a PM
  852. menu control.  The menu structure and items are defined in textual
  853. form in a resource file (.RC) using MENU, MENUITEM, and SUBMENU
  854. statements.  The resource file is compiled with the resource compiler
  855. into binary resource format and appended to the application executable
  856. (or a DLL).  The application calls an API to read the binary resource
  857. and create the visual PM windows and underlaying data structures.
  858. Finally, the window is placed and sized on a parent window.
  859. .*-------------
  860. :h2.Resource Files
  861. The textual resource file (.RC) specifies the complete structure of
  862. the menu and the contents of the menu items.  However, the MENUITEM
  863. resource statement does not have the syntactic flexibility to allow
  864. complete specification of all the data associated with a UCMenu item.
  865. Therefore, the text field of the MENUITEM statement is interpreted to
  866. contain four extra fields of information not found on standard PM menu
  867. items:  the bitmap specification, action string, parameter string, and
  868. a data string.  Each of these fields is separated by a single
  869. character defined as the first character of the string.  A typical
  870. resource file for a UCMenu might be:
  871. :xmp.
  872. BITMAP 6  "new.bmp"
  873. BITMAP 1  "open.bmp"
  874. BITMAP 2  "save.bmp"
  875. BITMAP 62 "styles.bmp"
  876. BITMAP 63 "bold.bmp"
  877. BITMAP 64 "italic.bmp"
  878. BITMAP 8  "help.bmp"
  879.  
  880. /* Text strings are interpreted as:                           */
  881. /*                                                            */
  882. /* "<c>Text<c>BitmapID<c>ActionStr<c>ParamStr<c>DataStr"      */
  883. /*                                                            */
  884. /*   where <c> is any character that does not appear in       */
  885. /*   the strings.                                             */
  886. /*                                                            */
  887. /* Item style MIS_SPACER produces a gap in the menu bar.      */
  888.  
  889. MENU ID_COMMANDBAR LOADONCALL MOVEABLE DISCARDABLE
  890. BEGIN
  891.   MENUITEM "/New/6/New",              1,  MIS_TEXT
  892.   MENUITEM "/Open/1/Open File",       2,  MIS_TEXT
  893.   MENUITEM "/Save/2/Save File",       3,  MIS_TEXT
  894.   MENUITEM "",                        4,  MIS_SPACER
  895.   SUBMENU  "/Styles/62/Styles Submenu",     5, MIS_TEXT
  896.   BEGIN
  897.     /* Use a different delim here so we can use "/" in the strings */
  898.     MENUITEM "!Bold!63!Bold/Style",         6, MIS_TEXT │ MIS_CHECKABLE
  899.     MENUITEM "!Italic!64!Italic/Style",     7, MIS_TEXT │ MIS_CHECKABLE
  900.   END
  901.   MENUITEM "",                        8,  MIS_SPACER
  902.   MENUITEM "/Help/8/Show Help",       9,  MIS_TEXT
  903. END
  904. :exmp.
  905. The format for the text field is the following&colon.
  906. "&lbrk.#Text&rbrk.#BitmapID&lbrk.#Action&rbrk.&lbrk.#Parameters&rbrk.&lbrk.#Data&rbrk.".
  907. The first character of the string (here #) is used as a delimiter and can be any
  908. character that does not appear in the string itself.
  909. :parml compact break=all.
  910. :pt.:hp2.Text:ehp2.
  911. :pd.The text displayed in or under the bitmap
  912. :pt.:hp2.BitmapID:ehp2.
  913. :pd.Bitmap identifier or file name
  914. :pt.:hp2.Action:ehp2.
  915. :pd.Information about the action associated with the item , for example the name of a macro.
  916. :pt.:hp2.Parameters:ehp2.
  917. :pd.Parameters associated to the action.
  918. :pt.:hp2.Data:ehp2.
  919. :pd.Some text associated with the item , for example the parameters of a macro.
  920. :eparml.
  921. Some notes on UCMenu resource files:
  922. :ul.
  923. :li.
  924. The menu item IDs specified in the resource file are arbitrary.
  925. Sequential numbering is used to help keep menu items unique but is
  926. not necessary.
  927. :li.
  928. A new menu item style MIS_SPACER is defined for UCMenus.  It produces
  929. a blank space in the menu to separate menu items into groups.
  930. :li.
  931. The 'Data' field is not seen by the user and is for application use.
  932. Note that new items created by customization will have no 'data'
  933. value.
  934. :li.
  935. The bitmap items have to be declared with the MIS_TEXT style even
  936. though they will (from a PM viewpoint) be OWNERDRAW items.
  937. :li.
  938. The MIS_BREAK style is not effective for the first level UCMenu items, but it
  939. works for the submenu items.
  940. :li.
  941. Only one level of submenus is supported.
  942. :eul.
  943. .*-------------------
  944. :h2.Completing the UCMINFO Structure
  945. To complete the process of creating a UCMenu, the application must
  946. construct a :UCMINFO. data structure and fill in all the
  947. relevant fields.  The RGB values of the structure are used for color
  948. mapping the bitmap background pixels.  UCMenus supplies a means for
  949. bitmap background pixels to be automatically mapped to the current
  950. UCMenu background color.  The BgBmp value of :UCMINFO. tells UCMenus what
  951. background color was used in the design of the bitmaps.  That color
  952. will be replaced with the ItemBgColor before the bitmaps are displayed
  953. wherever that color appears in the bitmap.  The ItemBgColor should be
  954. set to the SYSCLR_MENU color returned by WinQuerySysColor().  A
  955. different color may be specified in the BgColor field.  This will be
  956. the color used wherever there are no items on the toolbar.
  957. :p.
  958. Once the :UCMINFO. structure is filled in, the function
  959. :UCMenuCreateFromTemplate. or :UCMenuCreateFromResource. is called.
  960. The template version is used if the application has manually loaded a
  961. previously saved UCMenu template.  The resource version will create a
  962. UCMenu from a menu template in the applications resources.
  963. The creation functions return two window handles.  The function result is
  964. the window handle of interest for the application, the other may be
  965. ignored.
  966. :p.
  967. :h2.Placement and Sizing of a UCMenu
  968. Toolbars are generally placed along one edge of the application window
  969. frame.  Toolbars may be attached to the top, bottom, left or right edge
  970. of the window.  The toolkit sample SAMP1.C shows toolbars on all four edges of the frame.
  971. :p.
  972. It is possible to simply place and size the toolbar into the client
  973. window of a standard PM window.  However, this simple approach
  974. introduces a lot of complexity when the application must properly scale
  975. and paint the client window.  If the frame window is a dialog, proper
  976. size and placement is even more complex since the application does not
  977. paint, and there is no separate client window.
  978. :p.
  979. The proper solution to toolbar placement is to make the toolbar a
  980. frame control.
  981. Making a window into a frame control requires a thorough knowledge of
  982. how PM frame windows and message protocols work.  Adding a frame
  983. control to a dialog window is even more complex since it may require
  984. the movement of all the dialog controls.  All the function necessary to
  985. make UCMenu windows into frame controls is supplied in a set of utility
  986. routines in the toolkit.  These routines are not a formal part of the
  987. UCMenu control, but allow an application to easily place UCMenu
  988. controls along any edge of a frame or dialog window.  By using these
  989. utilities an application can be completely removed from any sizing or
  990. positioning considerations for the toolbars.
  991. :p.
  992. The frame control utilities consist of two functions, one to add a
  993. UCMenu to a frame or dialog window, the other to remove it.
  994. The utilities support up to four toolbars per
  995. frame or dialog window (one each at the top, bottom, left, and right
  996. edges).  By calling the add/remove frame control utilities, a toolbar
  997. can be toggled on and off.
  998. :p.
  999. The UCMUtils() functions encapsulate all the complexity of frame
  1000. control management freeing the application from that task.  With just
  1001. a simple function call, the toolbar can be positioned in the frame and
  1002. will maintain its proper position as the frame is sized and moved.
  1003. Source code for the utilities is provided in the toolkit.
  1004. .***************************************************************************
  1005. :h1.A Dynamic Status Bar
  1006. A dynamic status bar can be implemented by the application to
  1007. automatically show a description of each menu item as the mouse pointer
  1008. is moved on the toolbar.  To help the application implement this
  1009. feature, a UCMenu with the UCS_PROMPTING style will send :WM_CONTROL.
  1010. messages with a notify code of :UCN_MOUSEMOVE. when the pointer moves on
  1011. the menu bar.  The message supplies the menu item ID of the item under
  1012. the mouse pointer.  Using this item ID, the application can obtain
  1013. the item data structures and determine the action string associated
  1014. with that item.  The action string string may be displayed directly, or
  1015. it may be used to lookup a more complete description for display to the
  1016. user.  The SAMP3.C sample program uses the lookup method to display a
  1017. longer description of the menu items action.
  1018. .***************************************************************************
  1019. :h1.Saving/Restoring UCMenus
  1020. The UCMenus API provides several function to aid the application in
  1021. saving and restoring the customized state of UCMenu toolbars.  The
  1022. function :UCMenuMakeTemplate. will create a binary in-storage
  1023. representation of the complete UCMenu item structure.  The binary
  1024. image will include all text, bitmaps, action strings, and arrangements
  1025. of menu items.  The corresponding APIs, :UCMenuCreateFromTemplate.
  1026. and :UCMenuNew., create and replace UCMenu controls from an in-storage
  1027. binary template.  It should be noted that these binary templates
  1028. are in a special format used by UCMenus.  UCMenu templates are not
  1029. usable as standard PM menu templates.
  1030. :p.
  1031. The SAMP3.C toolkit sample
  1032. shows the processing of WM_SAVEAPPLICATION.
  1033. The UCMenu style,
  1034. colors, and font, as well as the binary templates, are stored in the
  1035. application .INI file.  During initialization, the styles, colors,
  1036. font and templates are read from the .INI file and are used to recreate
  1037. the customized toolbars.
  1038. .*********************************************************************************************
  1039. :h1.Data Structures Reference
  1040. This section contains a list of all the structures used by a UCMenus application.
  1041. .*-------------------------------------------------------------------------
  1042. :h2 res=102.UCMITEM (UCMenu Item Structure)
  1043. This structure is used to store data related to a UCMenus menu item, such
  1044. as its bitmap handle, identifier, text and an action strings.  For each menu
  1045. item, this structure is accessed from the :hp1.hItem:ehp1. component of the
  1046. standard PM :hp1.MENUITEM:ehp1. structure (which can be obtained with
  1047. the MM_QUERYITEM message).
  1048. :p.
  1049. :xmp.
  1050. typedef struct {
  1051.    LONG    hBmp;            // Bitmap handle
  1052.    PSZ     pszBmp;          // Bitmap Identifier or file name
  1053.    PSZ     pszText;         // Bitmap Text
  1054.    PSZ     pszAction;       // Action : for instance the name of a macro
  1055.    PSZ     pszParameters;   // Parameters for the action
  1056.    PSZ     pszData;         // Data associated to the item, not visible for the user
  1057.    USHORT  usId;            // Id of the item
  1058.    LONG    lCurBmpBgRGB;    // Current background color set for the bmp (if any)
  1059.    ULONG   ulFlags;
  1060. } UCMITEM, *PUCMITEM;
  1061.  
  1062. #define ITEM(a,b) ((PUCMITEM)((a)->hItem))->b
  1063. :exmp.
  1064. ulFlags can include &colon.
  1065. :dl compact.
  1066. :dt.:hp2.UCMI_BMPFROMFILE:ehp2.
  1067. :dd.Set if the bitmap comes from a file, not set if it comes from the resources.
  1068. :edl.
  1069. .*----------------------------------------------------------------------------
  1070. :h2 res=103.CMITEMS (Context Menu items)
  1071. This structure is used to add items to the UCMenu's context menu.
  1072. It contains the identifier and text of the item.
  1073. :p.
  1074. :xmp.
  1075. typedef struct {
  1076.    ULONG ID;
  1077.    PSZ   pszItemText;
  1078. } CMITEMS,  *PCMITEMS;
  1079. :exmp.
  1080. .*----------------------------------------------------------------------------
  1081. :h2 res=101.UCMINFO (UCMenu Initialization Structure)
  1082. This structure is used to create a UCMenu. It must be passed to
  1083. the UCMCreateXXXX() APIs when creating a UCMenu.
  1084. :p.If a matrix UCMenu is created with a null width, NbOfCols must contain the
  1085. number of menu items per line. If it's created with a null height, NbOfRows
  1086. must contain the number of items per column.
  1087. :xmp.
  1088. typedef struct {
  1089.    ULONG  cb;                   // size of this structure
  1090.    HMODULE hModule;             // Module where the bitmaps are
  1091.    USHORT  NbOfCols;            // Number of Columns (used for a matrix UCM)
  1092.    USHORT  NbOfRows;            // Number of Rows    (used for a matrix UCM)
  1093.    PSZ     pszBitmapSearchPath; // Path(s) to search for bitmap files.
  1094.                                 // Environment variables separated by spaces.
  1095.    PSZ     pszDefaultBitmap;    // Bitmap to use if bitmap specified for
  1096.                                 //  a menu item can't be resolved or loaded.
  1097.    ULONG   Style;               // Style of item (combination of UCS_ flags )
  1098.    ULONG   cx;                  // Size to give to all the items if UCS_FORCESIZE
  1099.    ULONG   cy;                  //
  1100.    LONG    BgBmp;               // RGB value of the color of the bmp which has to be replaced with ItemBgColor
  1101.    LONG    BgColor;             // RGB color of the UCMenu background
  1102.    LONG    ItemBgColor;         // RGB color of the UCMenu items background
  1103.    PSZ     pszFontNameSize;     // String describing the font of the UCMenu (such as used
  1104. } UCMINFO, *PUCMINFO;           //  in WinSetPresParam), if NULL, UCM_DEFAULTFONT is used
  1105. :exmp.
  1106. .*----------------------------------------------------------------------------
  1107. :h2 res=104.QBUBBLEDATA (Query Bubble Data)
  1108. This structure is passed to the application by the
  1109. :UCN_QRYBUBBLEHELP. message.
  1110. :p.
  1111. :xmp.
  1112.    typedef struct { 
  1113.       MENUITEM     *MenuItem   ;  // Item information supplied by UCMenus
  1114.       char         *BubbleText ;  // Bubble text supplied by application (freed by UCMenus)
  1115.    } QBUBBLEDATA, *PQBUBBLEDATA;
  1116. :exmp.
  1117. .*---------------------------------------------------------------------------
  1118. .* IPFCPREP macros used for message reference entries
  1119. .*---------------------------------------------------------------------------
  1120. .dm message on.
  1121. :h2 res=&res..&name.
  1122. .**** to build links: .dm &name. on :link reftype=hd res=&res..&name.:elink.
  1123. .dm off
  1124. .*----------------
  1125. .dm params on
  1126. :parml.
  1127. .dm off
  1128. .*----------------
  1129. .dm param1 on
  1130. :pt.:hp6.Param1:ehp6.
  1131. .br
  1132. :parml.
  1133. .dm off
  1134. .*----------------
  1135. .dm param2 on
  1136. :eparml.
  1137. :pt.:hp6.Param2:ehp6.
  1138. .br
  1139. :parml.
  1140. .dm off
  1141. .*----------------
  1142. .dm item on
  1143. :pt.:hp2.&name.:ehp2. :hp1.(&type.):ehp1.
  1144. :pd.
  1145. .dm off
  1146. .*----------------
  1147. .dm returns on
  1148. :eparml.
  1149. :pt.:hp6.Returns:ehp6.&rbl.
  1150. .br
  1151. :parml.
  1152. .dm off
  1153. .*----------------
  1154. .dm eparams on
  1155. :eparml.
  1156. :eparml.
  1157. .dm off
  1158. .*----------------
  1159. .dm sample on
  1160. :p.
  1161. :h3.:hp5.Example:ehp5.
  1162. .br
  1163. :xmp.
  1164. :font facename='System Monospaced' size=12x10.
  1165. .dm off
  1166. .*----------------
  1167. .dm esample on
  1168. :font facename=default size=0x0.
  1169. :exmp.
  1170. .dm off
  1171. .*----------------
  1172. .dm remarks on
  1173. :p.
  1174. :h3.:hp5.Remarks:ehp5.
  1175. .br
  1176. .dm off
  1177. .*----------------
  1178. .dm related on
  1179. :p.
  1180. :h3.:hp5.Related:ehp5.
  1181. .br
  1182. .dm off
  1183. .*----------------
  1184. .dm defproc on
  1185. :p.
  1186. :h3.:hp5.Default Processing:ehp5.
  1187. .br
  1188. .dm off
  1189. .*----------------
  1190. .dm emessage on
  1191. .dm off
  1192. .*----------------
  1193. .*-----------------------------------------------------------------------------------------------
  1194. :h1 res=500 toc=12.WM_CONTROL Message Reference
  1195. .*-----------------------------------------------------------------------------------------------
  1196. This section describes all the WM_CONTROL messages generated by a UCMenu control and
  1197. sent to the control owner.
  1198. .*-----------------------------------------------------------------------------------------------
  1199. :message res=600 name='UCN_ITEMSELECTED' .
  1200. This WM_CONTROL notification is sent by the UCMenu to its owner when
  1201. a UCMenu menu item is selected by the user.
  1202. :params.
  1203. :param1.
  1204. :item name='UCMenuID' type='USHORT'.
  1205. ID of the UCMenu
  1206. :item name='NotifCode' type='USHORT'.
  1207. UCN_ITEMSELECTED
  1208. :param2.
  1209. :item name='pUCMitem' type='UCMITEM *'.
  1210. Pointer to the UCMenu item structure for the selected item.
  1211. :returns.
  1212. Nothing
  1213. :eparams.
  1214. :remarks.
  1215. :defproc.
  1216. :related.
  1217. :emessage.
  1218. .*-----------------------------------------------------------------------------------------------
  1219. :message res=601 name='UCN_QRYTEMPLATEMODULE' .
  1220. This WM_CONTROL notification is sent by the UCMenu to its owner when the default template is loaded
  1221. ("Load default option" in the popup context menu). The owner has to return the module
  1222. handle where we can look for the default template.
  1223. :params.
  1224. :param1.
  1225. :item name='UCMenuID' type='USHORT'.
  1226. ID of the UCMenu
  1227. :item name='NotifCode' type='USHORT'.
  1228. UCN_QRYTEMPLATEMODULE
  1229. :param2.
  1230. :item name='pHModule' type='HMODULE *'.
  1231. Pointer to the module to be filled by the owner.
  1232. :returns.
  1233. :item name='Processed' type='BOOL'.
  1234. TRUE if processed, FALSE else.
  1235. :eparams.
  1236. :remarks.
  1237. :defproc.
  1238. :related.
  1239. :UCN_QRYDEFTEMPLATEID.
  1240. :emessage.
  1241. .*---------------------------------------------------------------------------
  1242. :message res=602 name='UCN_QRYDEFTEMPLATEID' .
  1243. This WM_CONTROL notification is sent by the UCMenu to its owner when the default template is loaded
  1244. ("Load default option" in the popup context menu). The owner has to return the ID
  1245. of the menu in the resource.
  1246. :params.
  1247. :param1.
  1248. :item name='UCMenuID' type='USHORT'.
  1249. ID of the UCMenu
  1250. :item name='NotifCode' type='USHORT'.
  1251. UCN_QRYDEFTEMPLATEID
  1252. :param2.
  1253. :item name='pID' type='PUSHORT'.
  1254. Pointer to the ID to be filled by the owner.
  1255. :returns.
  1256. :item name='Processed' type='BOOL'.
  1257. TRUE if processed, FALSE else.
  1258. :eparams.
  1259. :remarks.
  1260. :defproc.
  1261. :related.
  1262. :UCN_QRYTEMPLATEMODULE.
  1263. :emessage.
  1264. .*---------------------------------------------------------------------------
  1265. :message res=603 name='UCN_QRYDEFTEMPLATE' .
  1266. This WM_CONTROL notification is sent by the UCMenu to its owner when the default template has to be loaded
  1267. ("Load default option" in the popup context menu). The owner has to return a pointer to the
  1268. template of the default toolbar, allocated with UCMenuAlloc.
  1269. :params.
  1270. :param1.
  1271. :item name='UCMenuID' type='USHORT'.
  1272. ID of the UCMenu
  1273. :item name='NotifCode' type='USHORT'.
  1274. UCN_QRYDEFTEMPLATE
  1275. :param2.
  1276. :item name='ppTemplate' type='PVOID*'.
  1277. Pointer to the pointer to the template.
  1278. :returns.
  1279. :item name='Processed' type='BOOL'.
  1280. TRUE if processed, FALSE else.
  1281. :eparams.
  1282. :remarks.
  1283. If processed, the template has to be allocated with UCMenuAlloc().
  1284. The UCMenus will free it with UCMenuFree().
  1285. :defproc.
  1286. :related.
  1287. :emessage.
  1288. .*---------------------------------------------------------------------------
  1289. :message res=604 name='UCN_QRYACTIONLIST' .
  1290. This WM_CONTROL notification is sentthe UCMenu to its owner when the settings dialog for the
  1291. action is popped up so that he can fill in the list of actions.
  1292. The owner has to send :UCMENU_INSERTACTION. messages and to post back a :UCMENU_ACTIONSINSERTED.
  1293. when it is done.
  1294. :params.
  1295. :param1.
  1296. :item name='UCMenuID' type='USHORT'.
  1297. ID of the UCMenu
  1298. :item name='NotifCode' type='USHORT'.
  1299. UCN_QRYACTIONSLIST
  1300. :param2.
  1301. :item name='hwndUCMenu' type='HWND'.
  1302. Handle of the UCMenu.
  1303. :returns.
  1304. nothing
  1305. :eparams.
  1306. :remarks.
  1307. :defproc.
  1308. :related.
  1309. :UCMENU_INSERTACTION.
  1310. :emessage.
  1311. .*---------------------------------------------------------------------------
  1312. :message res=605 name='UCN_SIZE' .
  1313. This WM_CONTROL notification is sent by the UCMenu to its owner when
  1314. its size has changed.
  1315. :params.
  1316. :param1.
  1317. :item name='UCMenuID' type='USHORT'.
  1318. ID of the UCMenu
  1319. :item name='NotifCode' type='USHORT'.
  1320. UCN_SIZE
  1321. :param2.
  1322. :item name='param2' type='ULONG'.
  1323. reserved
  1324. :returns.
  1325. Nothing
  1326. :eparams.
  1327. :remarks.
  1328. After receiving this message, further information can be obtained by using the UCMENU_QUERY* messages.
  1329. :defproc.
  1330. :related.
  1331. :emessage.
  1332. .*---------------------------------------------------------------------------
  1333. :message res=606 name='UCN_STYLE' .
  1334. This WM_CONTROL notification is sent by the UCMenu to its owner when
  1335. its style has changed.
  1336. :params.
  1337. :param1.
  1338. :item name='UCMenuID' type='USHORT'.
  1339. ID of the UCMenu
  1340. :item name='NotifCode' type='USHORT'.
  1341. UCN_STYLE
  1342. :param2.
  1343. :item name='param2' type='ULONG'.
  1344. reserved
  1345. :returns.
  1346. Nothing
  1347. :eparams.
  1348. :remarks.
  1349. After receiving this message, further information can be obtained by using the UCMENU_QUERY* messages.
  1350. :defproc.
  1351. :related.
  1352. :emessage.
  1353. .*---------------------------------------------------------------------------
  1354. :message res=607 name='UCN_FONT' .
  1355. This WM_CONTROL notification is sent by the UCMenu to its owner when
  1356. its font has changed (eg when a font has been dropped from the palette over the UCMenu ).
  1357. :params.
  1358. :param1.
  1359. :item name='UCMenuID' type='USHORT'.
  1360. ID of the UCMenu
  1361. :item name='NotifCode' type='USHORT'.
  1362. UCN_FONT
  1363. :param2.
  1364. :item name='param2' type='ULONG'.
  1365. reserved
  1366. :returns.
  1367. Nothing
  1368. :eparams.
  1369. :remarks.
  1370. After receiving this message, further information can be obtained by using the UCMENU_QUERY* messages.
  1371. :defproc.
  1372. :related.
  1373. :emessage.
  1374. .*---------------------------------------------------------------------------
  1375. :message res=608 name='UCN_COLOR' .
  1376. This WM_CONTROL notification is sent by the UCMenu to its owner when
  1377. its color has changed (eg when a color has been dropped from the palette over the UCMenu ).
  1378. :params.
  1379. :param1.
  1380. :item name='UCMenuID' type='USHORT'.
  1381. ID of the UCMenu
  1382. :item name='NotifCode' type='USHORT'.
  1383. UCN_COLOR
  1384. :param2.
  1385. :item name='param2' type='ULONG'.
  1386. reserved
  1387. :returns.
  1388. Nothing
  1389. :eparams.
  1390. :remarks.
  1391. After receiving this message, further information can be obtained by using the UCMENU_QUERY* messages.
  1392. :defproc.
  1393. :related.
  1394. :emessage.
  1395. .*---------------------------------------------------------------------------
  1396. :message res=609 name='UCN_ADDEDITEM' .
  1397. This WM_CONTROL notification is sent by the UCMenu to its owner when
  1398. an item has been added.
  1399. :params.
  1400. :param1.
  1401. :item name='UCMenuID' type='USHORT'.
  1402. ID of the UCMenu
  1403. :item name='NotifCode' type='USHORT'.
  1404. UCN_ADDEDITEM
  1405. :param2.
  1406. :item name='ItemID' type='USHORT'.
  1407. ID of the added item.
  1408. :returns.
  1409. Nothing
  1410. :eparams.
  1411. :remarks.
  1412. After receiving this message, further information can be obtained by using the UCMENU_QUERY* messages.
  1413. :defproc.
  1414. :related.
  1415. :emessage.
  1416. .*---------------------------------------------------------------------------
  1417. :message res=610 name='UCN_DELETEDITEM' .
  1418. This WM_CONTROL notification is sent by the UCMenu to its owner when
  1419. an item has been deleted.
  1420. :params.
  1421. :param1.
  1422. :item name='UCMenuID' type='USHORT'.
  1423. ID of the UCMenu
  1424. :item name='NotifCode' type='USHORT'.
  1425. UCN_DELETEDITEM
  1426. :param2.
  1427. :item name='ItemID' type='USHORT'.
  1428. ID of the added item.
  1429. :returns.
  1430. Nothing
  1431. :eparams.
  1432. :remarks.
  1433. After receiving this message, further information can be obtained by using the UCMENU_QUERY* messages.
  1434. :defproc.
  1435. :related.
  1436. :emessage.
  1437. .*---------------------------------------------------------------------------
  1438. :message res=611 name='UCN_BITMAP' .
  1439. This WM_CONTROL notification is sent by the UCMenu to its owner when
  1440. the bitmap of an item has been changed.
  1441. :params.
  1442. :param1.
  1443. :item name='UCMenuID' type='USHORT'.
  1444. ID of the UCMenu
  1445. :item name='NotifCode' type='USHORT'.
  1446. UCN_BITMAP
  1447. :param2.
  1448. :item name='ItemID' type='USHORT'.
  1449. ID of the changed item.
  1450. :returns.
  1451. Nothing
  1452. :eparams.
  1453. :remarks.
  1454. :defproc.
  1455. :related.
  1456. :emessage.
  1457. .*---------------------------------------------------------------------------
  1458. :message res=612 name='UCN_TEXT' .
  1459. This WM_CONTROL notification is sent by the UCMenu to its owner when
  1460. the text of an item has been changed.
  1461. :params.
  1462. :param1.
  1463. :item name='UCMenuID' type='USHORT'.
  1464. ID of the UCMenu
  1465. :item name='NotifCode' type='USHORT'.
  1466. UCN_TEXT
  1467. :param2.
  1468. :item name='ItemID' type='USHORT'.
  1469. ID of the changed item.
  1470. :returns.
  1471. Nothing
  1472. :eparams.
  1473. :remarks.
  1474. :defproc.
  1475. :related.
  1476. :emessage.
  1477. .*---------------------------------------------------------------------------
  1478. :message res=613 name='UCN_QRYRESBMP' .
  1479. This WM_CONTROL notification message is sent by the UCMenu to its owner when the list of bmp id is needed.
  1480. ("Predefined..." on the "general" notebook page )
  1481. :params.
  1482. :param1.
  1483. :item name='UCMenuID' type='USHORT'.
  1484. ID of the UCMenu
  1485. :item name='NotifCode' type='USHORT'.
  1486. UCN_QRYRESBMP
  1487. :param2.
  1488. :item name='pArrayId' type='PULONG *'.
  1489. The owner has to return in this pointer an array of the bitmap IDs, allocated with UCMenuAlloc.
  1490. :returns.
  1491. :item name='nbItems' type='ULONG'.
  1492. The number of elements in the returned array or zero.
  1493. :eparams.
  1494. :remarks.
  1495. The array will be freed by the UCMenu.
  1496. :defproc.
  1497. :related.
  1498. :emessage.
  1499. .*---------------------------------------------------------------------------
  1500. :message res=614 name='UCN_ACTION' .
  1501. This WM_CONTROL notification is sent by the UCMenu to its owner when
  1502. the action of an item has been changed.
  1503. :params.
  1504. :param1.
  1505. :item name='UCMenuID' type='USHORT'.
  1506. ID of the UCMenu
  1507. :item name='NotifCode' type='USHORT'.
  1508. UCN_ACTION
  1509. :param2.
  1510. :item name='ItemID' type='USHORT'.
  1511. ID of the changed item.
  1512. :returns.
  1513. Nothing
  1514. :eparams.
  1515. :remarks.
  1516. :defproc.
  1517. :related.
  1518. :emessage.
  1519. .*---------------------------------------------------------------------------
  1520. :message res=615 name='UCN_CMITEM' .
  1521. This WM_CONTROL notification is sent to the owner of the UCMenu when the context menu receives
  1522. a WM_COMMAND message for one of the items added with :UCMENU_ADDITEMSTOCM..
  1523. :params.
  1524. :param1.
  1525. :item name='UCMenuID' type='USHORT'.
  1526. ID of the UCMenu
  1527. :item name='NotifCode' type='USHORT'.
  1528. UCN_CMITEM
  1529. :param2.
  1530. :item name='CMItemID' type='USHORT'.
  1531. ID of the context menu item selected.
  1532. :item name='ItemID' type='USHORT'.
  1533. ID of item over which the context menu was popped up.
  1534. :eparams.
  1535. :remarks.
  1536. The owner should process this message by executing the function associated
  1537. to the item he added.
  1538. :defproc.
  1539. No default processing
  1540. :related.
  1541. See :CMITEMS. type.
  1542. See :UCMENU_ADDITEMSTOCM.
  1543. See :UCMENU_DELETECMITEM.
  1544. :emessage.
  1545. .*---------------------------------------------------------------------------
  1546. :message res=616 name='UCN_MOUSEMOVE' .
  1547. This WM_CONTROL notification code is sent by the UCMenu to its owner when the mouse is moved over
  1548. its menu or submenu.
  1549. :params.
  1550. :param1.
  1551. :item name='UCMenuID' type='USHORT'.
  1552. ID of the UCMenu
  1553. :item name='NotifCode' type='USHORT'.
  1554. UCN_MOUSEMOVE
  1555. :param2.
  1556. :item name='ItemID' type='USHORT'.
  1557. ID of the item over which the pointer is
  1558. :returns.
  1559. Nothing.
  1560. :eparams.
  1561. :remarks.
  1562. :defproc.
  1563. No default processing
  1564. :related.
  1565. :emessage.
  1566. .*----------------------------------------------------------------------------
  1567. :message res=617 name='UCN_HLP_NB_BMP' .
  1568. This WM_CONTROL notification is sent by the UCMenu to its owner when custom help is required
  1569. for the general page of the notebook.
  1570. :params.
  1571. :param1.
  1572. :item name='UCMenuID' type='USHORT'.
  1573. ID of the UCMenu
  1574. :item name='NotifCode' type='USHORT'.
  1575. UCN_HLP_NB_BMP
  1576. :param2.
  1577. :item name='param2' type='ULONG'.
  1578. Reserved
  1579. :returns.
  1580. Nothing.
  1581. :eparams.
  1582. :remarks.
  1583. :defproc.
  1584. No default processing
  1585. :related.
  1586. UCS_CUSTOMHLP
  1587. :emessage.
  1588. .*----------------------------------------------------------------------------
  1589. :message res=618 name='UCN_HLP_NB_CREATE' .
  1590. This WM_CONTROL notification is sent by the UCMenu to its owner when custom help is required
  1591. for the create page of the notebook.
  1592. :params.
  1593. :param1.
  1594. :item name='UCMenuID' type='USHORT'.
  1595. ID of the UCMenu
  1596. :item name='NotifCode' type='USHORT'.
  1597. UCN_HLP_NB_CREATE
  1598. :param2.
  1599. :item name='param2' type='ULONG'.
  1600. Reserved
  1601. :returns.
  1602. Nothing.
  1603. :eparams.
  1604. :remarks.
  1605. :defproc.
  1606. No default processing
  1607. :related.
  1608. UCS_CUSTOMHLP
  1609. :emessage.
  1610. .*----------------------------------------------------------------------------
  1611. :message res=619 name='UCN_HLP_NB_ACTION' .
  1612. This WM_CONTROL notification is sent by the UCMenu to its owner when custom help is required
  1613. for the action page of the notebook.
  1614. :params.
  1615. :param1.
  1616. :item name='UCMenuID' type='USHORT'.
  1617. ID of the UCMenu
  1618. :item name='NotifCode' type='USHORT'.
  1619. UCN_HLP_NB_ACTION
  1620. :param2.
  1621. :item name='param2' type='ULONG'.
  1622. Reserved
  1623. :returns.
  1624. Nothing.
  1625. :eparams.
  1626. :remarks.
  1627. :defproc.
  1628. No default processing
  1629. :related.
  1630. UCS_CUSTOMHLP
  1631. :emessage.
  1632. .*----------------------------------------------------------------------------
  1633. :message res=620 name='UCN_HLP_STYLE' .
  1634. This WM_CONTROL notification is sent by the UCMenu to its owner when custom help is required
  1635. for the style dialog.
  1636. :params.
  1637. :param1.
  1638. :item name='UCMenuID' type='USHORT'.
  1639. ID of the UCMenu
  1640. :item name='NotifCode' type='USHORT'.
  1641. UCN_HLP_NB_STYLE
  1642. :param2.
  1643. :item name='param2' type='ULONG'.
  1644. Reserved
  1645. :returns.
  1646. Nothing.
  1647. :eparams.
  1648. :remarks.
  1649. :defproc.
  1650. No default processing
  1651. :related.
  1652. UCS_CUSTOMHLP
  1653. :emessage.
  1654. .*----------------------------------------------------------------------------
  1655. :message res=621 name='UCN_HLP_DM' .
  1656. This WM_CONTROL notification is sent by the UCMenu to its owner when custom help is required
  1657. for the drag and drop.
  1658. :params.
  1659. :param1.
  1660. :item name='UCMenuID' type='USHORT'.
  1661. ID of the UCMenu
  1662. :item name='NotifCode' type='USHORT'.
  1663. UCN_HLP_NB_DM
  1664. :param2.
  1665. :item name='param2' type='ULONG'.
  1666. Reserved
  1667. :returns.
  1668. Nothing.
  1669. :eparams.
  1670. :remarks.
  1671. :defproc.
  1672. No default processing
  1673. :related.
  1674. UCS_CUSTOMHLP
  1675. :emessage.
  1676. .*----------------------------------------------------------------------------
  1677. :message res=622 name='UCN_HLP_BUFFET' .
  1678. This WM_CONTROL notification is sent by the UCMenu to its owner when custom help is required
  1679. for the buffet toolbar dialog.
  1680. :params.
  1681. :param1.
  1682. :item name='UCMenuID' type='USHORT'.
  1683. ID of the UCMenu
  1684. :item name='NotifCode' type='USHORT'.
  1685. UCN_HLP_NB_BUFFET
  1686. :param2.
  1687. :item name='param2' type='ULONG'.
  1688. Reserved
  1689. :returns.
  1690. Nothing.
  1691. :eparams.
  1692. :remarks.
  1693. :defproc.
  1694. No default processing
  1695. :related.
  1696. UCS_CUSTOMHLP
  1697. :emessage.
  1698. .*----------------------------------------------------------------------------
  1699. :message res=623 name='UCN_QRYBUBBLEHELP'.
  1700. This WM_CONTROL notification is sent by the UCMenu to its owner to obtain
  1701. the bubble-help text associated with a particular menu item.
  1702. :params.
  1703. :param1.
  1704. :item name='UCMenuID' type='USHORT'.
  1705. ID of the UCMenu
  1706. :item name='NotifCode' type='USHORT'.
  1707. UCN_QRYBUBBLEHELP
  1708. :param2.
  1709. :item name='QueryData' type='QBUBBLEDATA *'.
  1710. Pointer to :QBUBBLEDATA. structure.  The :hp1.MenuItem:ehp1. field will contain
  1711. a pointer to the MENUITEM structure.  
  1712. :returns.
  1713. Nothing.
  1714. :eparams.
  1715. :remarks.
  1716. The application should fill in the :hp1.BubbleText:ehp1. pointer of the
  1717. :QBUBBLEDATA. structure.  :hp2.Note: This text string will be freed by
  1718. UCMenus so it must be a dynamically allocated string.:ehp2.
  1719. :p.
  1720. If the :hp1.BubbleText:ehp1. field is NULL then no bubble help window will be displayed.
  1721. :defproc.
  1722. No default processing
  1723. :related.
  1724. :emessage.
  1725. .*----------------------------------------------------------------------------
  1726. :message res=624 name='UCN_QRYCONTEXTHWND'.
  1727. This WM_CONTROL notification is sent by the UCMenu to its owner to obtain
  1728. the handle of an application-supplied context menu.
  1729. :params.
  1730. :param1.
  1731. :item name='UCMenuID' type='USHORT'.
  1732. ID of the UCMenu
  1733. :item name='NotifCode' type='USHORT'.
  1734. UCN_QRYCONTEXTHWND
  1735. :param2.
  1736. :item name='MenuItem' type='MENUITEM *'.
  1737. Pointer to MENUITEM structure describing the item on which the context menu
  1738. was requested.  This structure will contain all binary zero values if
  1739. the pointer was not over a menu item when the context menu was requested.
  1740. :returns.
  1741. Nothing.
  1742. :eparams.
  1743. :remarks.
  1744. The application can ignore this message if the UCMenus built-in context menu is to
  1745. be used.  Otherwise it should supply the handle of a context menu to be
  1746. displayed.  Selections on the context menu will generate :UCN_CMITEM. messages.
  1747. :defproc.
  1748. No default processing
  1749. :related.
  1750. :emessage.
  1751. .*----------------------------------------------------------------------------
  1752. :message res=625 name='UCN_CHANGEDITEM'.
  1753. This WM_CONTROL notification is sent by the UCMenu to its owner
  1754. when a menu item has been changed and it is not possible to determine
  1755. which parts of the item were modified.
  1756. :params.
  1757. :param1.
  1758. :item name='UCMenuID' type='USHORT'.
  1759. ID of the UCMenu
  1760. :item name='NotifCode' type='USHORT'.
  1761. UCN_CHANGEDITEM
  1762. :param2.
  1763. :item name='ItemID' type='USHORT'.
  1764. ID of the menu item that changed.
  1765. :returns.
  1766. Nothing.
  1767. :eparams.
  1768. :remarks.
  1769. In general the application will get notification messages for specific changes
  1770. to menu items such as :UCN_ACTION..  However, when the MM_SETITEM message is used
  1771. to update a menu item it is not possible to determine exactly what components of
  1772. the item were changed and this message is generated.
  1773. Idefproc.
  1774. No default processing
  1775. :related.
  1776. :emessage.
  1777. .*-----------------------------------------------------------------------------------------------
  1778. :h1 toc=12.UCMenu Message Reference
  1779. .*-----------------------------------------------------------------------------------------------
  1780. This section describes all the messages an application can send to a UCMenu control
  1781. to set and query various options.
  1782. .*---------------------------------------------------------------------------
  1783. :message res=650 name='UCMENU_QUERYSIZE' .
  1784. This message is sent to the UCMenu to query the size it needs to be be fully displayed.
  1785. :params.
  1786. :param1.
  1787. :item name='pCx' type='PULONG'.
  1788. Pointer to a ULONG in which the width will be put.
  1789. :param2.
  1790. :item name='pCy' type='PULONG'.
  1791. Pointer to a ULONG in which the height will be put.
  1792. :returns.
  1793. :item name='Success' type='BOOL'.
  1794. :dl compact.
  1795. :dt.:hp2.TRUE:ehp2.
  1796. :dd.Query successful
  1797. :dt.:hp2.FALSE:ehp2.
  1798. :dd.Query Unsuccessful
  1799. :edl.
  1800. :eparams.
  1801. :remarks.
  1802. :defproc.
  1803. :related.
  1804. :emessage.
  1805. .*---------------------------------------------------------------------------
  1806. :message res=651 name='UCMENU_QUERYCOLOR' .
  1807. This message is sent to the UCMenu to query its color.
  1808. :params.
  1809. :param1.
  1810. :item name='pRGBColor' type='LONG *'.
  1811. Pointer to a LONG in which the RGB value of the UCMenu background color will be put.
  1812. :param2.
  1813. :item name='pItemRGBColor' type='LONG *'.
  1814. Pointer to a LONG in which the RGB value of the UCMenu items background color will be put.
  1815. :returns.
  1816. :item name='Success' type='BOOL'.
  1817. :dl compact.
  1818. :dt.:hp2.TRUE:ehp2.
  1819. :dd.Query successful
  1820. :dt.:hp2.FALSE:ehp2.
  1821. :dd.Query Unsuccessful
  1822. :edl.
  1823. :eparams.
  1824. :remarks.
  1825. :defproc.
  1826. :related.
  1827. :emessage.
  1828. .*---------------------------------------------------------------------------
  1829. :message res=652 name='UCMENU_QUERYFONT' .
  1830. This message is sent to the UCMenu to query its font.
  1831. :params.
  1832. :param1.
  1833. :item name='pszFontNameSize' type='PSZ'.
  1834. String in which the font  name and size will be put, allocated by the sender.
  1835. :p.The string returned has the format used in WinSetPresParam.
  1836. :param2.
  1837. :item name='Size' type='ULONG'.
  1838. Size of the string allocated by the sender
  1839. :returns.
  1840. :item name='Success' type='BOOL'.
  1841. :dl compact.
  1842. :dt.:hp2.TRUE:ehp2.
  1843. :dd.Query successful
  1844. :dt.:hp2.FALSE:ehp2.
  1845. :dd.Query Unsuccessful
  1846. :edl.
  1847. :eparams.
  1848. :remarks.
  1849. :defproc.
  1850. :related.
  1851. WinSetPresParam, WinQueryPresParam.
  1852. :emessage.
  1853. .*---------------------------------------------------------------------------
  1854. :message res=653 name='UCMENU_QUERYSTYLE' .
  1855. This message is sent to the UCMenu to query its style.
  1856. :params.
  1857. :param1.
  1858. :item name='pStyle' type='PULONG'.
  1859. Pointer to a ULONG in which the style will be put.
  1860. :p.The style is a combination of the UCS_* values.
  1861. :returns.
  1862. :item name='Success' type='BOOL'.
  1863. :dl compact.
  1864. :dt.:hp2.TRUE:ehp2.
  1865. :dd.Query successful
  1866. :dt.:hp2.FALSE:ehp2.
  1867. :dd.Query Unsuccessful
  1868. :edl.
  1869. :param2.
  1870. :item name='param2' type='ULONG'.
  1871. reserved
  1872. :eparams.
  1873. :remarks.
  1874. :defproc.
  1875. :related.
  1876. :emessage.
  1877. .*---------------------------------------------------------------------------
  1878. :message res=654 name='UCMENU_QUERYFORCEDSIZE' .
  1879. This message is sent to the UCMenu to query the value of its forced size
  1880. :params.
  1881. :param1.
  1882. :item name='pCx' type='PULONG'.
  1883. Pointer to a ULONG in which the width will be put.
  1884. :param2.
  1885. :item name='pCy' type='PULONG'.
  1886. Pointer to a ULONG in which the height will be put.
  1887. :returns.
  1888. :item name='Success' type='BOOL'.
  1889. :dl compact.
  1890. :dt.:hp2.TRUE:ehp2.
  1891. :dd.Query successful
  1892. :dt.:hp2.FALSE:ehp2.
  1893. :dd.Query Unsuccessful
  1894. :edl.
  1895. :eparams.
  1896. :remarks.
  1897. :defproc.
  1898. :related.
  1899. :emessage.
  1900. .*---------------------------------------------------------------------------
  1901. :message res=655 name='UCMENU_ADDITEMSTOCM' .
  1902. This user message can be sent to the UCMenu to add items to its context menu
  1903. :params.
  1904. :param1.
  1905. :item name='NbOfItems' type='ULONG'.
  1906. Number of items to add
  1907. :param2.
  1908. :item name='pCMItems' type='PCMITEMS'.
  1909. Pointer to a :CMITEMS. structure. It contains an ID and pszText for each item
  1910. added
  1911. :returns.
  1912. nothing
  1913. :item name='' type=''.
  1914. :eparams.
  1915. :remarks.
  1916. This message should be sent, since the caller has to free pszItemText in
  1917. the :CMITEMS. structure.
  1918. :defproc.
  1919. No default processing
  1920. :related.
  1921. See :CMITEMS. type.
  1922. See :UCMENU_DELETECMITEM.
  1923. :emessage.
  1924. .*---------------------------------------------------------------------------
  1925. :message res=656 name='UCMENU_DELETECMITEM' .
  1926. This user message can be sent to the UCMenu to delete items from its context menu
  1927. :params.
  1928. :param1.
  1929. :item name='NbOfItems' type='ULONG'.
  1930. Number of items to delete.
  1931. :param2.
  1932. :item name='pItemId' type='PULONG'.
  1933. Array of items ids.
  1934. :returns.
  1935. nothing
  1936. :eparams.
  1937. :remarks.
  1938. By default, the context menu has the following items &colon.
  1939. :dl compact.
  1940. :dt.:hp2.Edit&period.&period.&period.:ehp2.
  1941. :dd.IDM_UCM_EDIT
  1942. :dt.:hp2.Create&period.&period.&period.:ehp2.
  1943. :dd.IDM_UCM_CREATE
  1944. :dt.:hp2.Delete:ehp2.
  1945. :dd.IDM_UCM_DELETE
  1946. :dt.:hp2.Separator line:ehp2.
  1947. :dd.IDM_UCM_SEPARATOR
  1948. :dt.:hp2.Style&period.&period.&period.:ehp2.
  1949. :dd.IDM_UCM_STYLE
  1950. :dt.:hp2.Load Default:ehp2.
  1951. :dd.IDM_UCM_DEFAULT
  1952. :dt.:hp2.Import&period.&period.&period.:ehp2.
  1953. :dd.IDM_UCM_LOAD
  1954. :dt.:hp2.Export&period.&period.&period.:ehp2.
  1955. :dd.IDM_UCM_SAVEAS
  1956. :edl.
  1957. :defproc.
  1958. No default processing
  1959. :related.
  1960. See :CMITEMS. type
  1961. See :UCMENU_ADDITEMSTOCM.
  1962. See :UCN_CMITEM.
  1963. :emessage.
  1964. .*---------------------------------------------------------------------------
  1965. :message res=657 name='UCMENU_QUERYVERSION' .
  1966. This user message is sent to the UCMenu to query the version of the UCMenus dll
  1967. :params.
  1968. :param1.
  1969. :item name='param1' type='ULONG'.
  1970. Reserved
  1971. :param2.
  1972. :item name='param2' type='ULONG'.
  1973. Reserved
  1974. :returns.
  1975. :item name='version' type='ULONG'.
  1976. Version number of the dll, eg 2 for 0.02 and 100 for 1.00.
  1977. :eparams.
  1978. :remarks.
  1979. :defproc.
  1980. No default processing
  1981. :related.
  1982. :emessage.
  1983. .*---------------------------------------------------------------------------
  1984. :message res=658 name='UCMENU_SETSTYLE' .
  1985. This message is sent to the UCMenu to set the style flags and the associated width
  1986. and height values.
  1987. :params.
  1988. :param1.
  1989. :item name='StyleFlags' type='ULONG'.
  1990. Combination of UCS_* flags.
  1991. :param2.
  1992. :item name='cx' type='USHORT'.
  1993. The width of the items if UCS_FORCESIZE is set.
  1994. :item name='cy' type='USHORT'.
  1995. The height of the items if UCS_FORCESIZE is set.
  1996. :returns.
  1997. :item name='Success' type='BOOL'.
  1998. TRUE if successful, FALSE else.
  1999. :eparams.
  2000. :remarks.
  2001. A :UCMENU_UPDATE. message must be issued in order to reflect the changes.
  2002. :defproc.
  2003. :related.
  2004. :UCMENU_UPDATE.
  2005. :emessage.
  2006. .*---------------------------------------------------------------------------
  2007. :message res=659 name='UCMENU_QUERYUCMINFO' .
  2008. This message is sent to the UCMenu to retrieve the :UCMINFO. structure
  2009. :params.
  2010. :param1.
  2011. :item name='pUCMInfo' type='PUCMINFO'.
  2012. Pointer to the :UCMINFO. structure to fill.
  2013. :param2.
  2014. :item name='param2' type='ULONG'.
  2015. reserved.
  2016. :returns.
  2017. :item name='Success' type='BOOL'.
  2018. TRUE if successful, FALSE else.
  2019. :eparams.
  2020. :remarks.
  2021. If the PSZ fields are not null, they have been allocated by
  2022. the UCMenu and have to be freed with UCMenuFree by the sender.
  2023. :defproc.
  2024. No default processing
  2025. :related.
  2026. :emessage.
  2027. .*---------------------------------------------------------------------------
  2028. :message res=660 name='UCMENU_UPDATE' .
  2029. This message is sent to the UCMenu to display the changes made.
  2030. :params.
  2031. :param1.
  2032. :item name='param1' type='ULONG'.
  2033. reserved.
  2034. :param2.
  2035. :item name='param2' type='ULONG'.
  2036. reserved.
  2037. :returns.
  2038. :item name='Success' type='BOOL'.
  2039. TRUE if successful, FALSE else.
  2040. :eparams.
  2041. :remarks.
  2042. :defproc.
  2043. No default processing
  2044. :related.
  2045. :UCMENU_SETSTYLE.
  2046. :UCMENU_SETBGCOLOR.
  2047. :emessage.
  2048. .*---------------------------------------------------------------------------
  2049. :message res=661 name='UCMENU_SETBGCOLOR' .
  2050. This message is sent to the UCMenu to set the UCMenu background color
  2051. :params.
  2052. :param1.
  2053. :item name='BgColor' type='ULONG'.
  2054. The RGB color which will be used for the UCMenu background.
  2055. :param2.
  2056. :item name='ItemBgColor' type='ULONG'.
  2057. The RGB color which will be used for the items background.
  2058. :returns.
  2059. :item name='Success' type='BOOL'.
  2060. TRUE if successful, FALSE else.
  2061. :eparams.
  2062. :remarks.
  2063. :defproc.
  2064. No default processing
  2065. :related.
  2066. :emessage.
  2067. .*---------------------------------------------------------------------------
  2068. :message res=662 name='UCMENU_SETFONT' .
  2069. This message is sent to the UCMenu to set the UCMenu font.
  2070. :params.
  2071. :param1.
  2072. :item name='FontNameSize' type='PSZ'.
  2073. Font name, such as used in WinSetPresParam.
  2074. :param2.
  2075. :item name='-' type='ULONG'.
  2076. Reserved.
  2077. :returns.
  2078. :item name='Success' type='BOOL'.
  2079. TRUE if successful, FALSE else.
  2080. :eparams.
  2081. :remarks.
  2082. :defproc.
  2083. No default processing
  2084. :related.
  2085. :emessage.
  2086. .*---------------------------------------------------------------------------
  2087. :message res=663 name='UCMENU_ACTIONSINSERTED' .
  2088. This message is posted to the UCMenu by its owner when it has filled
  2089. the list of actions
  2090. :params.
  2091. :param1.
  2092. :item name='param1' type='ULONG'.
  2093. Reserved.
  2094. :param2.
  2095. :item name='param2' type='ULONG'.
  2096. Reserved
  2097. :returns.
  2098. nothing
  2099. :eparams.
  2100. :remarks.
  2101. :defproc.
  2102. :related.
  2103. :UCMENU_INSERTACTION.
  2104. :emessage.
  2105. .*---------------------------------------------------------------------------
  2106. :message res=664 name='UCMENU_INSERTACTION' .
  2107. This message is sent to the UCMenu by its owner after it received :UCN_QRYACTIONLIST..
  2108. :params.
  2109. :param1.
  2110. :item name='Action' type='PSZ'.
  2111. String including the name of the action eventually followed by parameters.
  2112. :param2.
  2113. :item name='Description' type='PSZ'.
  2114. A description of the action.
  2115. :returns.
  2116. nothing
  2117. :eparams.
  2118. :remarks.
  2119. This message has to be sent, not posted to the UCMenus control.
  2120. :defproc.
  2121. :related.
  2122. :UCN_QRYACTIONLIST.
  2123. :emessage.
  2124. .*---------------------------------------------------------------------------
  2125. :message res=665 name='UCMENU_SETBUBBLETIMERS'.
  2126. This message is sent to the UCMenu by its owner to set the time delays
  2127. associated with the bubble-help feature (UCS_BUBBLEHELP style).
  2128. :params.
  2129. :param1.
  2130. :item name='HoverDelay' type='ULONG'.
  2131. Number of msec pointer must hover over the same menu item before
  2132. the bubble help is displayed.  Maximum of 65000 msec (65 seconds).
  2133. :param2.
  2134. :item name='ReadTime' type='ULONG'.
  2135. Number of msec bubble help will be visible while pointer remains
  2136. over the same menu item.  Bubble help is removed when the
  2137. pointer leaves the UCMenu toolbar if this time has not
  2138. expired yet.  Maximum of 65000 msec (65 seconds).
  2139. :returns.
  2140. nothing
  2141. :eparams.
  2142. :remarks.
  2143. :defproc.
  2144. :related.
  2145. :emessage.
  2146. .*---------------------------------------------------------------------------
  2147. :message res=666 name='UCMENU_ACTIVECHG'.
  2148. This message is sent to the UCMenu by its owner
  2149. whenever the frame window in which the menu exists becomes active
  2150. or inactive.
  2151. :params.
  2152. :param1.
  2153. :item name='Activated' type='BOOL'.
  2154. TRUE if the window is being activated, FALSE if being deactivated.
  2155. :param2.
  2156. Reserved.
  2157. :returns.
  2158. Nothing
  2159. :eparams.
  2160. :remarks.
  2161. The owner must send this message whenever the window frame in which the
  2162. toolbar exists becomes active or inactive.
  2163. :sample.
  2164.   // Owner must notify toolbar on active status changes:
  2165.  
  2166.   case WM_ACTIVATE:
  2167.     /* Tell toolbar we are becoming active or inactive */
  2168.     WinSendMsg(ToolHwnd, UCMENU_ACTIVECHG, mp1, MPVOID);
  2169.     break;
  2170. :esample.
  2171. :related.
  2172. :emessage.
  2173. .*---------------------------------------------------------------------------
  2174. :message res=667 name='UCMENU_DISABLEUPDATE'.
  2175. This message is sent to the UCMenu by its owner
  2176. to disable updates to the toolbar window while items are inserted,
  2177. deleted, or modified.
  2178. :params.
  2179. :param1.
  2180. :item name='Disable' type='BOOL'.
  2181. TRUE if updates are to be disabled, FALSE if they are to be shown.
  2182. :param2.
  2183. Reserved.
  2184. :returns.
  2185. Nothing
  2186. :eparams.
  2187. :remarks.
  2188. This message can be used to improve performance when more than one
  2189. menu item will be inserted, deleted, or modified.  The menu will
  2190. not be visually updated when :hp1.Disable:ehp1. is TRUE.  Updates
  2191. will be shown when :hp1.Disable:ehp1. is FALSE.
  2192. :p.
  2193. Note that a :UCMENU_UPDATE. message :hp2.must:ehp2. be sent after
  2194. the menu is disabled and then enabled to insure proper update
  2195. if the window.
  2196. :related.
  2197. :emessage.
  2198. .*---------------------------------------------------------------------------
  2199. .* API Reference
  2200. .*---------------------------------------------------------------------------
  2201. :h1.Programming Interfaces (API)
  2202. This section describes each of the callable UCMenu programming interfaces.
  2203. .*---------------------------------------------------------------------------
  2204. .* IPFCPREP macros used for message reference entries
  2205. .*---------------------------------------------------------------------------
  2206. .dm function on
  2207. :h2 res=&res..&name.
  2208. .**** to produce link tags: .dm &name. on :link reftype=hd res=&res..&name.:elink.
  2209. .dm off
  2210. .*----------------
  2211. .dm syntax on
  2212. :p.
  2213. :hp7.Syntax&colon.:ehp7.
  2214. .br
  2215. :lines.
  2216. :font facename='System Monospaced' size=12x10.
  2217. :hp4.&return. &name.(¶ms.):ehp4.
  2218. :font facename=default size=0x0.
  2219. :elines.
  2220. .dm off
  2221. .*----------------
  2222. .dm fparams on
  2223. :font facename='System Monospaced' size=12x10.
  2224. :table cols='15 10 10 50' rules=both frame=box.
  2225. :row.
  2226. :c.:hp1.Name:ehp1.
  2227. :c.:hp1.Type:ehp1.
  2228. :c.:hp1.In/Out:ehp1.
  2229. :c.:hp1.Description:ehp1.
  2230. .dm off
  2231. .*----------------
  2232. .dm fparam on
  2233. :row.
  2234. :c.&name.
  2235. :c.&type.
  2236. :c.&io.
  2237. :c.
  2238. .dm off
  2239. .*----------------
  2240. .dm freturns on
  2241. :etable.
  2242. :font facename=default size=0x0.
  2243. :hp1.Returns:ehp1.
  2244. :font facename='System Monospaced' size=12x10.
  2245. :table cols='15 10 10 50' rules=both frame=box.
  2246. .dm off
  2247. .*----------------
  2248. .dm efparams on
  2249. :etable.
  2250. :font facename=default size=0x0.
  2251. .dm off
  2252. .*----------------
  2253. .dm efunction on
  2254. .dm off
  2255. .*----------------
  2256. .*--------------------------------------------------------------------------
  2257. .*-------------------------------------------------------------------------
  2258. :function res=200 name='UCMenuCreateFromResource' text='Create a UCMenu from a resource menu'.
  2259. This function creates a UCMenu using a menu template stored in the resources.
  2260. :syntax name='UCMenuCreateFromResource' params='hab hParent hOwner ulStyle x y cx cy hInsertBehind ulID hmodResource usMenuID pUCMInfo phTextMenu' return='hUCMenu' .
  2261. :fparams.
  2262. :fparam name='hab' type='HAB' io='input' .
  2263. Handle of the anchor-block.
  2264. :fparam name='hParent' type='HWND' io='input' .
  2265. Handle of the parent window
  2266. :fparam name='hOwner' type='HWND' io='input' .
  2267. Handle of the owner window
  2268. :fparam name='flStyle' type='ULONG' io='input' .
  2269. Style flags of the UCMenu window, combination of WS_ flags and CMS_VERT, CMS_HORZ, CMS_MATRIX, CMS_MATRIX_VERT, CMS_MATRIX_HORZ
  2270. :fparam name='x' type='ULONG' io='input'.
  2271. x coordinate of UCMenu window position
  2272. :fparam name='y' type='ULONG' io='input'.
  2273. y coordinate of UCMenu window position
  2274. :fparam name='cx' type='ULONG' io='input'.
  2275. width of the UCMenu window, ignored if vertical or matrix UCMenu
  2276. :fparam name='cy' type='ULONG' io='input'.
  2277. height of the UCMenu window, ignored if horizontal or matrix UCMenu
  2278. :fparam name='hInsertBehind' type='ULONG' io='input'.
  2279. Sibling window behind which the UCMenu is placed, can also be HWND_TOP or HWND_BOTTOM.
  2280. :fparam name='ulID' type='ULONG' io='input'.
  2281. ID given to the UCMenu.
  2282. :fparam name='hmodResource' type='HMODULE' io='input'.
  2283. Handle of the module where the menu resource is to be found.
  2284. :fparam name='usMenuID' type='USHORT' io='input'.
  2285. ID of the resource menu used as a template to create the UCMenu.
  2286. :fparam name='pUCMInfo' type='PUCMINFO' io='input'.
  2287. Pointer to the :UCMINFO. UCMenu creation structure
  2288. :fparam name='phTextMenu' type='PHWND' io='output'.
  2289. Handle of the menu loaded from the resource.
  2290. It should normally not be used.
  2291. :freturns.
  2292. :fparam name='hUCMenu' type='PSZ' io='return'.
  2293. Handle of the UCMenu or NULLHANDLE if the creation failed.
  2294. :efparams.
  2295. :remarks.
  2296. :related.
  2297. :UCMINFO. data structure
  2298. .*-------------------------------------------------------------------------
  2299. :function res=201 name='UCMenuCreateFromHMenu' text='Create a UCMenu from a menu handle'.
  2300. This function creates a UCMenu using an already loaded or created PM text menu.
  2301. :syntax name='UCMenuCreateFromHMenu' params='hab hParent hOwner ulStyle x y cx cy hInsertBehind ulID  hMenu pUCMInfo' return='hUCMenu'.
  2302. :fparams.
  2303. :fparam name='hab' type='HAB' io='input' .
  2304. Handle of the anchor-block.
  2305. :fparam name='hParent' type='HWND' io='input' .
  2306. Handle of the parent window
  2307. :fparam name='hOwner' type='HWND' io='input' .
  2308. Handle of the owner window
  2309. :fparam name='flStyle' type='ULONG' io='input' .
  2310. Style flags of the UCMenu window, combination of WS_ flags and CMS_VERT, CMS_HORZ, CMS_MATRIX, CMS_MATRIX_VERT, CMS_MATRIX_HORZ
  2311. :fparam name='x' type='ULONG' io='input'.
  2312. x coordinate of UCMenu window position
  2313. :fparam name='y' type='ULONG' io='input'.
  2314. y coordinate of UCMenu window position
  2315. :fparam name='cx' type='ULONG' io='input'.
  2316. width of the UCMenu window, ignored if vertical or matrix UCMenu
  2317. :fparam name='cy' type='ULONG' io='input'.
  2318. height of the UCMenu window, ignored if horizontal or matrix UCMenu
  2319. :fparam name='hInsertBehind' type='ULONG' io='input'.
  2320. Sibling window behind which the UCMenu is placed, can also be HWND_TOP or HWND_BOTTOM.
  2321. :fparam name='ulID' type='ULONG' io='input'.
  2322. ID given to the UCMenu.
  2323. :fparam name='hMenu' type='HWND' io='input'.
  2324. Handle of the PM menu used as a template to create the UCMenu
  2325. :fparam name='pUCMInfo' type='PUCMINFO' io='input'.
  2326. Pointer to the :UCMINFO. UCMenu creation structure
  2327. :freturns.
  2328. :fparam name='hUCMenu' type='PSZ' io='return'.
  2329. Handle of the UCMenu or zero if the creation failed.
  2330. :efparams.
  2331. :remarks.
  2332. Note that the passed menu handle is the handle of a standard PM
  2333. menu, not a UCMenu.  This function can be used to create an empty UCMenu
  2334. by first creating an empty PM menu as shown in the example below.
  2335. :sample.
  2336.  // Create empty UCMenu from an empty PM menu
  2337.  
  2338.  PMMenu = WinCreateWindow(hwnd,   // parent
  2339.                WC_MENU,           // PM menu class
  2340.                 "",               // no window text
  2341.                 MS_ACTIONBAR,     // window style
  2342.                 0,0,0,0,          // UCMenu will set size
  2343.                 hwnd,             // owner
  2344.                 HWND_TOP,         // top of siblings
  2345.                 0,                // ID of the control
  2346.                 NULL,             // No ctl data -> empty menu
  2347.                 NULL);            // No pres parms
  2348.  UCMenu = UCMenuCreateFromHMenu(hab,
  2349.                 hwnd,             // parent
  2350.                 hwnd,             // owner to get msgs
  2351.                 CMS_HORZ,         // Orientation (CMS_* flags)
  2352.                 0,0,0,0,          // Sizing will be done by UCMenu
  2353.                 HWND_TOP,         // Put on top of siblings
  2354.                 ID_COPYMENU,      // ID new menu will have
  2355.                 PMMenu,           // Handle of menu to use for template
  2356.                 &.UCMInfo);        // Initialization data structure
  2357. :esample.
  2358. :related.
  2359. :UCMINFO. data structure
  2360. .*-------------------------------------------------------------------------
  2361. :function res=202 name='UCMenuCreateFromTemplate' text='Create a UCMenu from a menu template'.
  2362. This function creates a UCMenu using an already loaded UCMenu template
  2363. previously created by the :UCMenuMakeTemplate. function.
  2364. :syntax name='UCMenuCreateFromTemplate' params='hab hParent hOwner ulStyle x y cx cy hInsertBehind ulID pMenuTemplate pUCMInfo phTextMenu' return='hUCMenu' .
  2365. :fparams.
  2366. :fparam name='hab' type='HAB' io='input' .
  2367. Handle of the anchor-block.
  2368. :fparam name='hParent' type='HWND' io='input' .
  2369. Handle of the parent window
  2370. :fparam name='hOwner' type='HWND' io='input' .
  2371. Handle of the owner window
  2372. :fparam name='flStyle' type='ULONG' io='input' .
  2373. Style flags of the UCMenu window, combination of WS_ flags and CMS_VERT, CMS_HORZ, CMS_MATRIX, CMS_MATRIX_VERT, CMS_MATRIX_HORZ
  2374. :fparam name='x' type='ULONG' io='input'.
  2375. x coordinate of UCMenu window position
  2376. :fparam name='y' type='ULONG' io='input'.
  2377. y coordinate of UCMenu window position
  2378. :fparam name='cx' type='ULONG' io='input'.
  2379. width of the UCMenu window, ignored if vertical or matrix UCMenu
  2380. :fparam name='cy' type='ULONG' io='input'.
  2381. height of the UCMenu window, ignored if horizontal or matrix UCMenu
  2382. :fparam name='hInsertBehind' type='ULONG' io='input'.
  2383. Sibling window behind which the UCMenu is placed, can also be HWND_TOP or HWND_BOTTOM.
  2384. :fparam name='ulID' type='ULONG' io='input'.
  2385. ID given to the UCMenu.
  2386. :fparam name='pmtMenuTemplate' type='PVOID' io='input'.
  2387. Pointer to the menu template in binary format
  2388. :fparam name='pUCMInfo' type='PUCMINFO' io='input'.
  2389. Pointer to the :UCMINFO. UCMenu creation structure
  2390. :fparam name='phTextMenu' type='PHWND' io='output'.
  2391. Handle of the menu loaded from the resource.
  2392. It should normally not be used.
  2393. :freturns.
  2394. :fparam name='hUCMenu' type='PSZ' io='return'.
  2395. Handle of the UCMenu or NULLHANDLE if the creation failed.
  2396. :efparams.
  2397. :remarks.
  2398. Note that the template is a :hp1.UCMenu:ehp1. template which is not
  2399. the same as a PM menu template.  The templated passed in much have
  2400. been created by a UCMenu template-creation function such as :UCMenuMakeTemplate..
  2401. :related.
  2402. :UCMINFO. data structure
  2403. :UCMenuMakeTemplate.
  2404. :UCMenuSaveTemplate.
  2405. :UCMenuLoadTemplate.
  2406. :UCMenuSaveTemplateIni.
  2407. :UCMenuLoadTemplateIni.
  2408. .*-------------------------------------------------------------------------
  2409. :function res=203 name='UCMenuLoadBitmap' text='Loads a bitmap'.
  2410. This function loads a bitmap from a file and returns its handle.
  2411. :syntax name='UCMenuLoadBitmap' params='pszFileName' return='hBitmap' .
  2412. :fparams.
  2413. :fparam name='pszFileName' type='PSZ' io='input' .
  2414. Name of the file to load.
  2415. :freturns.
  2416. :fparam name='hBitmap' type='LONG' io='return'.
  2417. Bit-map handle (0 if error)
  2418. :efparams.
  2419. :remarks.
  2420. If the bitmap file contains multiple resolutions, the bitmap the most appropriate to the
  2421. current display will be chosen.
  2422. :related.
  2423. .*-------------------------------------------------------------------------
  2424. :function res=204 name='UCMenuMakeTemplate' text='Builds a menu template'.
  2425. This function builds the UCMenu menu template associated with a specified UCMenu.
  2426. Note that a UCMenu menu template
  2427. is a binary data structure whose internal format is known and
  2428. understood only by UCMenus.  UCMenus templates should not be used to create
  2429. standard PM menus, and PM menu templates cannot be used to create a UCMenu.
  2430. :syntax name='UCMenuMakeTemplate' params='hwndUCMenu, pBufLen' return='pBuffer' .
  2431. :fparams.
  2432. :fparam name='hwndUCMenu' type='HWND' io='input' .
  2433. UCMenu window handle.
  2434. :fparam name='pBufLen' type='PULONG' io='output' .
  2435. Pointer to the UCMenu template buffer length.
  2436. :freturns.
  2437. :fparam name='pBuffer' type='PVOID' io='return'.
  2438. Pointer to the template (NULL if error), has to be freed by the caller with UCMenuFree.
  2439. :efparams.
  2440. :remarks.
  2441. :related.
  2442. :UCMenuCreateFromTemplate.
  2443. :UCMenuSaveTemplate.
  2444. :UCMenuLoadTemplate.
  2445. :UCMenuSaveTemplateIni.
  2446. :UCMenuLoadTemplateIni.
  2447. .*-------------------------------------------------------------------------
  2448. :function res=205 name='UCMenuSaveTemplate' text='Saves a menu template'.
  2449. This function builds and saves a UCMenu menu template.
  2450. Note that a UCMenu menu template
  2451. is a binary data structure whose internal format is known and
  2452. understood only by UCMenus.  UCMenus templates should not be used to create
  2453. standard PM menus, and PM menu templates cannot be used to create a UCMenu.
  2454. :syntax name='UCMenuSaveTemplate' params='hwndUCMenu, pszFileName' return='bRc' .
  2455. :fparams.
  2456. :fparam name='hwndUCMenu' type='HWND' io='input' .
  2457. UCMenu window handle.
  2458. :fparam name='pszFileName' type='PSZ' io='input' .
  2459. File name (NULL-terminated string)
  2460. :freturns.
  2461. :fparam name='bRc' type='BOOL' io='return'.
  2462. FALSE if an error occurred.
  2463. :efparams.
  2464. :remarks.
  2465. :related.
  2466. :UCMenuCreateFromTemplate.
  2467. :UCMenuMakeTemplate.
  2468. :UCMenuLoadTemplate.
  2469. :UCMenuSaveTemplateIni.
  2470. :UCMenuLoadTemplateIni.
  2471. .*-------------------------------------------------------------------------
  2472. :function res=206 name='UCMenuLoadTemplate' text='Loads a menu template'.
  2473. This function loads a UCMenu menu template from a file.
  2474. Note that a UCMenu menu template
  2475. is a binary data structure whose internal format is known and
  2476. understood only by UCMenus.  UCMenus templates should not be used to create
  2477. standard PM menus, and PM menu templates cannot be used to create a UCMenu.
  2478. :syntax name='UCMenuLoadTemplate' params='pszFileName, pBufLen' return='pBuffer' .
  2479. :fparams.
  2480. :fparam name='pszFileName' type='PSZ' io='input' .
  2481. File name (NULL-terminated string)
  2482. :fparam name='pBufLen' type='PULONG' io='output' .
  2483. Pointer to the length of the allocated buffer.
  2484. :freturns.
  2485. :fparam name='pBuffer' type='PVOID' io='input' .
  2486. Pointer to a buffer (NULL if error).
  2487. :hp2.Note&colon.:ehp2. The buffer must be freed by the caller using the UCMenuFree() function.
  2488. :efparams.
  2489. :remarks.
  2490. :related.
  2491. :UCMenuCreateFromTemplate.
  2492. :UCMenuMakeTemplate.
  2493. :UCMenuSaveTemplate.
  2494. :UCMenuSaveTemplateIni.
  2495. :UCMenuLoadTemplateIni.
  2496. .*-------------------------------------------------------------------------
  2497. :function res=207 name='UCMenuSaveTemplateIni' text='Saves a menu template'.
  2498. This function builds and saves a UCMenu menu template in an ini file.
  2499. Note that a UCMenu menu template
  2500. is a binary data structure whose internal format is known and
  2501. understood only by UCMenus.  UCMenus templates should not be used to create
  2502. standard PM menus, and PM menu templates cannot be used to create a UCMenu.
  2503. :syntax name='UCMenuSaveTemplateIni' params='hwndUCMenu, pszFileName, pszKeyName' return='bRc' .
  2504. :fparams.
  2505. :fparam name='hwndUCMenu' type='HWND' io='input' .
  2506. UCMenu window handle.
  2507. :fparam name='pszFileName' type='PSZ' io='input' .
  2508. File name (NULL-terminated string)
  2509. :fparam name='pszKeyName' type='PSZ' io='input' .
  2510. Template name (NULL-terminated string)
  2511. :freturns.
  2512. :fparam name='bRc' type='BOOL' io='return'.
  2513. FALSE if an error occurred.
  2514. :efparams.
  2515. :remarks.
  2516. :related.
  2517. :UCMenuCreateFromTemplate.
  2518. :UCMenuMakeTemplate.
  2519. :UCMenuSaveTemplate.
  2520. :UCMenuLoadTemplate.
  2521. :UCMenuLoadTemplateIni.
  2522. .*-------------------------------------------------------------------------
  2523. :function res=208 name='UCMenuLoadTemplateIni' text='Loads a menu template'.
  2524. This function loads a UCMenu menu template from an ini file.
  2525. Note that a UCMenu menu template
  2526. is a binary data structure whose internal format is known and
  2527. understood only by UCMenus.  UCMenus templates should not be used to create
  2528. standard PM menus, and PM menu templates cannot be used to create a UCMenu.
  2529. :syntax name='UCMenuLoadTemplateIni' params='pszFileName, pszKeyName, pBufLen' return='pBuffer' .
  2530. :fparams.
  2531. :fparam name='pszFileName' type='PSZ' io='input' .
  2532. Ini File name (NULL-terminated string)
  2533. :fparam name='pszKeyName' type='PSZ' io='input' .
  2534. Template name (NULL-terminated string)
  2535. :fparam name='pBufLen' type='PULONG' io='output' .
  2536. Pointer to the length of the allocated buffer.
  2537. :freturns.
  2538. :fparam name='pBuffer' type='PVOID' io='input' .
  2539. Pointer to a buffer (NULL if error).
  2540. :hp2.Note&colon.:ehp2. The buffer must be freed by the caller using the UCMenuFree() function.
  2541. :efparams.
  2542. :remarks.
  2543. :related.
  2544. :UCMenuCreateFromTemplate.
  2545. :UCMenuMakeTemplate.
  2546. :UCMenuSaveTemplate.
  2547. :UCMenuLoadTemplate.
  2548. :UCMenuSaveTemplateIni.
  2549. .*-------------------------------------------------------------------------
  2550. :function res=209 name='UCMenuSaveStyle' text='Saves a menu style'.
  2551. This function saves various UCMenu style-related information to a file.
  2552. :syntax name='UCMenuSaveStyle' params='hwndMenu, pszFileName' return='bRC' .
  2553. :fparams.
  2554. :fparam name='hwndUCMenu' type='HWND' io='input' .
  2555. UCMenu window handle.
  2556. :fparam name='pszFileName' type='PSZ' io='input' .
  2557. File name (NULL-terminated string)
  2558. :freturns.
  2559. :fparam name='bRC' type='BOOL' io='return'.
  2560. FALSE if an error occurred.
  2561. :efparams.
  2562. :remarks.
  2563. The following items are saved in the file:
  2564. :ul compact.
  2565. :li.Style flags
  2566. :li.Current size (cx, cy)
  2567. :li.Background color
  2568. :li.Button face background color
  2569. :li.Font name and size
  2570. :eul.
  2571. :related.
  2572. :UCMenuLoadStyle.
  2573. :UCMenuLoadStyleIni.
  2574. :UCMenuSaveStyleIni.
  2575. .*-------------------------------------------------------------------------
  2576. :function res=210 name='UCMenuLoadStyle' text='Loads a menu style'.
  2577. This function loads a menu style from a file into a :UCMINFO. UCMenu
  2578. creation structure.
  2579. :syntax name='UCMenuLoadStyle' params='pszFileName, pUCMInfo' return='bSuccess'.
  2580. :fparams.
  2581. :fparam name='pszFileName' type='PSZ' io='input' .
  2582. File name (NULL-terminated string)
  2583. :fparam name='pUCMInfo' type='UCMINFO *' io='output' .
  2584. Pointer to the :UCMINFO. structure in which to load the style
  2585. :freturns.
  2586. :fparam name='bSuccess' type='BOOL' io='return' .
  2587. FALSE if an error occurred.
  2588. :efparams.
  2589. :remarks.
  2590. :related.
  2591. :UCMenuSaveStyle.
  2592. :UCMenuLoadStyleIni.
  2593. :UCMenuSaveStyleIni.
  2594. .*-------------------------------------------------------------------------
  2595. :function res=211 name='UCMenuSaveStyleIni' text='Saves a menu style'.
  2596. This function saves the information relative to the style of a UCMenu in an ini file.
  2597. :syntax name='UCMenuSaveStyleIni' params='hwndMenu, pszFileName, pszKeyName' return='bRC' .
  2598. :fparams.
  2599. :fparam name='hwndUCMenu' type='HWND' io='input' .
  2600. UCMenu window handle.
  2601. :fparam name='pszFileName' type='PSZ' io='input' .
  2602. File name (NULL-terminated string)
  2603. :fparam name='pszKeyName' type='PSZ' io='input' .
  2604. Style name (NULL-terminated string)
  2605. :freturns.
  2606. :fparam name='bRC' type='BOOL' io='return'.
  2607. FALSE if an error occurred.
  2608. :efparams.
  2609. :remarks.
  2610. The following items are saved:
  2611. :ul compact.
  2612. :li.Style flags
  2613. :li.Current size (cx, cy)
  2614. :li.Background color
  2615. :li.Button face background color
  2616. :li.Font name and size
  2617. :eul.
  2618. :related.
  2619. :UCMenuLoadStyle.
  2620. :UCMenuSaveStyle.
  2621. :UCMenuLoadStyleIni.
  2622. .*-------------------------------------------------------------------------
  2623. :function res=212 name='UCMenuLoadStyleIni' text='Loads a menu style'.
  2624. This function loads a menu style from an ini file into a UCMInfo UCMenu
  2625. creation structure.
  2626. :syntax name='UCMenuLoadStyleIni' params='pszFileName, pszKeyName, pUCMInfo' return='bSuccess'.
  2627. :fparams.
  2628. :fparam name='pszFileName' type='PSZ' io='input' .
  2629. File name (NULL-terminated string)
  2630. :fparam name='pszKeyName' type='PSZ' io='input' .
  2631. Style name (NULL-terminated string)
  2632. :fparam name='pUCMInfo' type='UCMINFO *' io='output' .
  2633. Pointer to the UCMInfo structure in which to load the style
  2634. :freturns.
  2635. :fparam name='bSuccess' type='BOOL' io='return' .
  2636. FALSE if an error occurred.
  2637. :efparams.
  2638. :remarks.
  2639. :related.
  2640. :UCMenuLoadStyle.
  2641. :UCMenuSaveStyle.
  2642. :UCMenuSaveStyleIni.
  2643. .*-------------------------------------------------------------------------
  2644. :function res=213 name='UCMenuFreeMenuData' text='Frees the menu data'.
  2645. This function frees the data associated with the OWNERDRAW items of a menu.
  2646. :syntax name='UCMenuFreeMenuData' params='hwndMenu' return='-' .
  2647. :fparams.
  2648. :fparam name='hwndMenu' type='HWND' io='input' .
  2649. Menu window handle.
  2650. :freturns.
  2651. :fparam name='-' type='VOID' io='-'.
  2652. Nothing.
  2653. :efparams.
  2654. :remarks.
  2655. This function parses the whole menu (including submenus). It frees the
  2656. data structure associated with every OWNERDRAW item.
  2657. :p.This function requires the owner of the menu to be the UCMenu.
  2658. :hp2.Note&colon.:ehp2. This function is automatically executed when a UCMenu receives a WM_DESTROY message.
  2659. :related.
  2660. .*-------------------------------------------------------------------------
  2661. :function res=214 name='UCMenuIdFromCoord' text='Get the ID of a specified menu item' .
  2662. This function returns the id of the menu item that is at a specified position.
  2663. :syntax name='UCMenuIdFromCoord' params='hwndMenu, pptrPos' return='ItemID' .
  2664. :fparams.
  2665. :fparam name='hwndMenu' type='HWND' io='input' .
  2666. Menu window handle.
  2667. :fparam name='pptrPos' type='PPOINTL' io='input' .
  2668. Position
  2669. :freturns.
  2670. :fparam name='ItemID' type='USHORT' io='return'.
  2671. The item Identifier. 0 if not found.
  2672. :efparams.
  2673. :remarks.
  2674. This function doesn't check the submenus. However, you can identify an item in a submenu
  2675. if you pass the hwnd of the submenu.
  2676. :related.
  2677. .*-------------------------------------------------------------------------
  2678. :function res=215 name='UCMenuGetActionID' text='Get the IDs corresponding to an action' .
  2679. This function returns the ID of the item with a pszAction action, starting at the item sStart.
  2680. :syntax name='UCMenuGetActionID' params='hwndUCM, pszAction, , bSubmenus, sStart ' return='FoundID' .
  2681. :fparams.
  2682. :fparam name='hwndUCM' type='HWND' io='input' .
  2683. UCMenu window handle.
  2684. :fparam name='pszAction' type='PSZ' io='input' .
  2685. Action string to look for
  2686. :fparam name='bSubmenus' type='BOOL' io='input' .
  2687. Look in submenus or not.
  2688. :fparam name='Start' type='SHORT' io='input' .
  2689. Item ID to start with, MIT_FIRST for the beginning.
  2690. :freturns.
  2691. :fparam name='FoundID' type='SHORT' io='return'.
  2692. Item ID found, or MIT_NONE
  2693. :efparams.
  2694. :remarks.
  2695. Note that more than one item in the menu may have the same action string.  This function
  2696. can be used to enumerate all the items in the menu with a particular action string.
  2697. :related.
  2698. .*-------------------------------------------------------------------------
  2699. :function res=216 name='UCMenuSetActionAttr' text='Get the IDs corresponding to an action' .
  2700. This function sets the attributes of the items with the given action string.
  2701. :syntax name='UCMenuSetActionAttr' params='hwndUCM, pszAction, usAttrMask, usAttrValue' return='void' .
  2702. :fparams.
  2703. :fparam name='hwndUCM' type='HWND' io='input' .
  2704. UCMenu window handle.
  2705. :fparam name='pszAction' type='PSZ' io='input' .
  2706. Action string to look for
  2707. :fparam name='usAttrMask' type='USHORT' io='input' .
  2708. Attribute mask to use
  2709. :fparam name='usAttrValue' type='USHORT' io='input' .
  2710. Attribute value to set
  2711. :freturns.
  2712. :fparam name='-' type='VOID' io='return'.
  2713. Nothing
  2714. :efparams.
  2715. :remarks.
  2716. A UCMenu may have more than one item with the same action string.  This function
  2717. will set the given attribte on all items in the menu with the given action string.
  2718. :related.
  2719. .*-------------------------------------------------------------------------
  2720. :function res=217 name='UCMenuLoadDefault' text='Loads the default new UCMenu'.
  2721. This function updates the UCMenu with the default template.
  2722. :syntax name='UCMenuLoadDefault' params='hwndUCMenu' return='bSuccess' .
  2723. :fparams.
  2724. :fparam name='hwndUCMenu' type='HWND' io='input' .
  2725. Handle of the UCMenu
  2726. :freturns.
  2727. :fparam name='bSuccess' type='BOOL' io='return'.
  2728. True if successful, FALSE else
  2729. :efparams.
  2730. :remarks.
  2731. This call will cause the UCMenu to send a :UCN_QRYDEFTEMPLATE. or :UCN_QRYDEFTEMPLATEID.
  2732. message to the owner to get the default template to be loaded.
  2733. :related.
  2734. .*-------------------------------------------------------------------------
  2735. :function res=218 name='UCMenuNew' text='Loads a new menu in the UCMenu'.
  2736. This function updates the UCMenu with a new template.  Note that the template
  2737. is a UCMenus template created with one of the UCMenu template functions (such
  2738. as :UCMenuMakeTemplate.).  A PM menu template may not be used.
  2739. :syntax name='UCMenuNew' params='hwndUCMenu, pTemplate' return='bSuccess' .
  2740. :fparams.
  2741. :fparam name='hwndUCMenu' type='HWND' io='input' .
  2742. Handle of the UCMenu
  2743. :fparam name='pTemplate' type='PVOID' io='input' .
  2744. Template of the new menu.
  2745. :freturns.
  2746. :fparam name='bSuccess' type='BOOL' io='return'.
  2747. True if successful, FALSE else
  2748. :efparams.
  2749. :remarks.
  2750. :related.
  2751. .*-------------------------------------------------------------------------
  2752. :function res=219 name='UCMenuResourceBuffetDlg' text='Toolbar customization dialog'.
  2753. This dialog let the user pick items from a buffet toolbar coming from a resource.
  2754. :syntax name='UCMenuResourceBuffetDlg' params='hParent, hUCMenu, ulBuffetID, hmodBuffet' return='-' .
  2755. :fparams.
  2756. :fparam name='hParent' type='HWND' io='input' .
  2757. Parent of the dialog.
  2758. :fparam name='hUCMenu' type='HWND' io='input' .
  2759. Handle of the UCMenu to modify.
  2760. :fparam name='ulBuffetID' type='ULONG' io='input' .
  2761. ID of the buffet menu.
  2762. :fparam name='hmodBuffet' type='HMODULE' io='input' .
  2763. Module where the buffet menu is.
  2764. :freturns.
  2765. :fparam name='ulResult' type='ULONG' io='return'.
  2766. result of WinDglBox
  2767. :efparams.
  2768. :remarks.
  2769. :p.
  2770. The purpose of this call is to allow easy drag-and-drop customization of a
  2771. UCMenu.  A dialog will be displayed which contains two UCMenus (the buffet menu
  2772. and the menu to be customized).  The user can drag items from the buffet and
  2773. add them to the menu, and they can drag items from the menu to a shredder icon
  2774. to delete them.
  2775. :p.
  2776. The application supplies (via the :hp1.ulBuffetID:ehp1. menu) the list of
  2777. menu items the user can choose from.  The user cannot change the bitmaps or
  2778. action strings of the menu items, nor can they add new items not supplied by
  2779. the application.
  2780. :p.
  2781. When the user selects the :hp1.OK:ehp1. button on the buffet dialog, the UCMenu
  2782. represented by :hp1.hUCMenu:ehp1. is updated.  If the user cancels, the menu
  2783. is not affected.  When a menu is updated via the buffet dialog, all the current
  2784. items of the menu will be deleted, followed by insertion of the new items.
  2785. Applications which monitor the insert and delete of menu items should be
  2786. prepared to handle this mass-delete and mass-insert which occurs when the menu is
  2787. updated via the buffet dialog.
  2788. :related.
  2789. .*-------------------------------------------------------------------------
  2790. :function res=230 name='UCMenuTemplateBuffetDlg' text='Toolbar customization dialog'.
  2791. This dialog let the user pick items from a buffet toolbar coming from a template.  Note
  2792. that this template is a UCMenus template created by one of the UCMenu template
  2793. functions.  It is not a PM menu template.
  2794. :syntax name='UCMenuTemplateBuffetDlg' params='hParent, hUCMenu, pTemplate' return='-' .
  2795. :fparams.
  2796. :fparam name='hParent' type='HWND' io='input' .
  2797. Parent of the dialog.
  2798. :fparam name='hUCMenu' type='HWND' io='input' .
  2799. Handle of the UCMenu to modify.
  2800. :fparam name='pTemplate' type='PVOID' io='input' .
  2801. Template of the buffet menu
  2802. :freturns.
  2803. :fparam name='ulResult' type='ULONG' io='return'.
  2804. result of WinDglBox
  2805. :efparams.
  2806. :remarks.
  2807. :related.
  2808. .*-------------------------------------------------------------------------
  2809. :function res=231 name='UCMenuGetVersion' text='Get the version of the toolbar'.
  2810. This function returns the version of the UCMenus code.
  2811. :syntax name='UCMenuGetVersion' params='-' return='ulVersion' .
  2812. :fparams.
  2813. :freturns.
  2814. :fparam name='ulVersion' type='ULONG' io='return'.
  2815. version of the UCMenus.
  2816. :efparams.
  2817. :remarks.
  2818. :related.
  2819. .*-------------------------------------------------------------------------
  2820. :function res=232 name='UCMenuAlloc' text='Malloc used by UCMenus'.
  2821. External entry point to the allocation routine used by the UCMenus.
  2822. :syntax name='UCMenuAlloc' params='size' return='PVOID' .
  2823. :fparams.
  2824. :fparam name='size' type='size_t' io='input' .
  2825. Size to allocate.
  2826. :freturns.
  2827. :fparam name='pMem' type='PVOID' io='return'.
  2828. Pointer to the allocated memory or 0 if failure.
  2829. :efparams.
  2830. :remarks.
  2831. Strings and structures which may passed to UCMenus should use the
  2832. UCMenu memory allocation functions.
  2833. :related.
  2834. :UCMenuFree.
  2835. :UCMenuStrdup.
  2836. .*-------------------------------------------------------------------------
  2837. :function res=233 name='UCMenuStrdup' text='Duplication string used by UCMenus'.
  2838. Allocates and copies string using UCMenu memory allocation.
  2839. :syntax name='UCMenuStrdup' params='string' return='PSZ'.
  2840. :fparams.
  2841. :fparam name='string' type='PSZ' io='input' .
  2842. String to be copied.
  2843. :freturns.
  2844. :fparam name='copy' type='PSZ' io='return'.
  2845. Pointer to the copied string or 0 if failure.
  2846. :efparams.
  2847. :remarks.
  2848. Strings and structures which may passed to UCMenus should use the
  2849. UCMenu memory allocation functions.
  2850. :related.
  2851. :UCMenuFree.
  2852. :UCMenuAlloc.
  2853. .*-------------------------------------------------------------------------
  2854. :function res=234 name='UCMenuFree' text='Free used by the UCMenus'.
  2855. External entry point to the freeing routine used by the UCMenus.
  2856. :syntax name='UCMenuFree' params='pMem' return='-' .
  2857. :fparams.
  2858. :fparam name='pMem' type='PVOID' io='input' .
  2859. Pointer to free.
  2860. :freturns.
  2861. :fparam name='-' type='VOID' io='-'.
  2862. Nothing.
  2863. :efparams.
  2864. :remarks.
  2865. :related.
  2866. :UCMenuAlloc.
  2867. :UCMenuStrdup.
  2868. .*-------------------------------------------------------------------------
  2869. :function res=235 name='UCMenuItemDup' text='Duplicate UCMITEM structure and strings'.
  2870. Allocate storage for, and copy a :UCMITEM. structure including the strings it contains.
  2871. Any of the string pointers may be NULL.
  2872. :syntax name='UCMenuItemDup' params='UCMItem' return='UCMITEM *'.
  2873. :fparams.
  2874. :fparam name='UCMItem' type='UCMITEM *' io='input' .
  2875. Pointer to :UCMITEM. structure which is to be duplicated.
  2876. :freturns.
  2877. :fparam name='NewItem' type='UCMITEM *' io='returns'.
  2878. Returns a pointer to the new :UCMITEM. structure.  The structure will be filled with
  2879. strings duplicated from the original :UCMITEM. structure.
  2880. :efparams.
  2881. :remarks.
  2882. Note that the structure as well as the string pointes are duplicated by this function.
  2883. :related.
  2884. :UCMenuAlloc.
  2885. :UCMenuStrdup.
  2886. .*-------------------------------------------------------------------------
  2887. :function res=236 name='UCMenuItemFree' text='Free UCMITEM strings and storage'.
  2888. Free all strings in a :UCMITEM. structure and then free the storage for the structure itself.
  2889. Any of the string pointers may be NULL.
  2890. :syntax name='UCMenuItemFree' params='UCMItem' return='void'.
  2891. :fparams.
  2892. :fparam name='UCMItem' type='UCMITEM *' io='input' .
  2893. Pointer to :UCMITEM. structure which contains pointers to strings to be freed.
  2894. :freturns.
  2895. :fparam name='-' type='VOID' io='-'.
  2896. Nothing.
  2897. :efparams.
  2898. :remarks.
  2899. Note that the structure as well as the string pointes are freed by this function.
  2900. :related.
  2901. :UCMenuAlloc.
  2902. :UCMenuStrdup.
  2903. :euserdoc.
  2904.