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