home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / mclb.zip / lb.pak / MCLB.IPF < prev    next >
Text File  |  1995-08-17  |  35KB  |  899 lines
  1. .***************************************************************************
  2. .* MCLB 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 MCLBINFO on
  27. :link reftype=hd res=101.MCLBINFO:elink.
  28. .dm off
  29. .dm WM_CONTROL on
  30. :link reftype=hd res=500.WM_CONTROL:elink.
  31. .dm off
  32. .dm WM_MEASUREITEM on
  33. :link reftype=hd res=501.WM_MEASUREITEM:elink.
  34. .dm off
  35. .dm WM_DRAWITEM on
  36. :link reftype=hd res=502.WM_DRAWITEM:elink.
  37. .dm off
  38. .dm MCLBCreateWindow on
  39. :link reftype=hd res=1000.MCLBCreateWindow:elink.
  40. .dm off
  41. .dm MCLBN_COLSIZED on
  42. :link reftype=hd res=900.MCLBN_COLSIZED:elink.
  43. .dm off
  44. .dm MCLBN_CUSTOMSIZE on
  45. :link reftype=hd res=901.MCLBN_CUSTOMSIZE:elink. 
  46. .dm off
  47. .dm MCLBN_PPCHANGED on
  48. :link reftype=hd res=902.MCLBN_PPCHANGED:elink. 
  49. .dm off
  50. .dm  MCLB_SETTITLES on
  51. :link reftype=hd res=910.MCLB_SETTITLES:elink. 
  52. .dm off
  53. .dm  MCLB_SETTITLEFONT on
  54. :link reftype=hd res=911.MCLB_SETTITLEFONT:elink. 
  55. .dm off
  56. .dm  MCLB_SETLISTFONT on
  57. :link reftype=hd res=912.MCLB_SETLISTFONT:elink. 
  58. .dm off
  59. .dm  MCLB_SETTITLECOLORS on
  60. :link reftype=hd res=913.MCLB_SETTITLECOLORS:elink. 
  61. .dm off
  62. .dm  MCLB_SETLISTCOLORS on
  63. :link reftype=hd res=914.MCLB_SETLISTCOLORS:elink. 
  64. .dm off
  65. .dm  MCLB_SETCOLSIZES on
  66. :link reftype=hd res=915.MCLB_SETCOLSIZES:elink. 
  67. .dm off
  68. .dm  MCLB_QUERYCOLSIZES on
  69. :link reftype=hd res=916.MCLB_QUERYCOLSIZES:elink. 
  70. .dm off
  71. .dm  MCLB_QUERYINFO on
  72. :link reftype=hd res=917.MCLB_QUERYINFO:elink. 
  73. .dm off
  74. .dm  MCLB_QUERYSTYLE on
  75. :link reftype=hd res=918.MCLB_QUERYSTYLE:elink. 
  76. .dm off
  77. .dm  MCLB_QUERYFULLSIZE on
  78. :link reftype=hd res=919.MCLB_QUERYFULLSIZE:elink. 
  79. .dm off
  80. .dm  MCLB_QUERYCTLCOL on
  81. :link reftype=hd res=920.MCLB_QUERYCTLCOL:elink. 
  82. .dm off
  83. .dm MCLBS_NOCOLRESIZE on
  84. :link reftype=hd res=400.MCLBS_NOCOLRESIZE:elink.
  85. .dm off
  86. .dm MCLBS_SIZEMETHOD_PROP on
  87. :link reftype=hd res=400.MCLBS_SIZEMETHOD_PROP:elink.
  88. .dm off
  89. .dm MCLBS_CUASELECT on
  90. :link reftype=hd res=400.MCLBS_CUASELECT:elink.
  91. .dm off
  92. .dm MCLBS_SIZEMETHOD_LEFT on
  93. :link reftype=hd res=400.MCLBS_SIZEMETHOD_LEFT:elink.
  94. .dm off
  95. .dm MCLBS_SIZEMETHOD_CUSTOM on
  96. :link reftype=hd res=400.MCLBS_SIZEMETHOD_CUSTOM:elink.
  97. .dm off
  98. .***************************************
  99. :title.Multi-Column ListBox (MCLB)
  100. .***************************************
  101. :h1. Introduction
  102. This document is the programmer's reference for the MultiColumn ListBox (MCLB)
  103. PM control.  For more information on programming with this
  104. control, see :hp1.OS/2 Developer Magazine:ehp1., Nov/Dec 1995.
  105. :p.
  106. :artwork align=center name='pic1.bmp'.
  107. :p.
  108. :hp7.Acknowledgments:ehp7.
  109. .br
  110. This control was originally conceived at the IBM United Kingdom Warwick
  111. Development group by Charles Cooper.  The control was rewritten
  112. and enhanced by Mark McMillan of IBM, Research Triangle Park, USA.
  113. :p.
  114. :hp7.Description:ehp7.
  115. .br
  116. The :hp3.MultiColumn ListBox:ehp3. is a very useful PM custom control
  117. designed to overcome some of the limitations of the standard
  118. PM listbox and container controls.  It is simpler and in many cases
  119. faster than a container, but provides multicolumn (tabular) support
  120. for display of column-oriented data.
  121. :p.
  122. The MCLB supports individually sizable columns, optional horizontal
  123. scroll bars at the base of each column, seperate font and color support
  124. for the titles and column data, owner-drawn lists,
  125. and a simple listbox-style programming
  126. model.
  127. :p.
  128. The MCLB can be subclassed with the DMLB (Direct Manipulation ListBox)
  129. function also supplied in this toolkit to provide drag/drop reordering
  130. capability to the MCLB.
  131. .*-------------------------------------------------------------------------
  132. :h1 res=401.Creating an MCLB
  133. To create an MCLB the application must create an :MCLBINFO. data structure
  134. and initialize it.  At a minimum, the following fields must be supplied:
  135. :ul compact.
  136. :li.Size
  137. :li.Cols
  138. :li.Titles
  139. :li.InitSizes
  140. :li.TabChar
  141. :eul.
  142. .br
  143. The application must then call :MCLBCreateWindow. to create the MCLB
  144. control.
  145. :p.
  146. As supplied in the toolkit, the
  147. MCLB does not support
  148. direct creation from a dialog template.
  149. However, it is very easy to get the same effect by defining a
  150. static rectangle (or any other control) in the dialog template to
  151. act as a placeholder.  During WM_INITDLG processing the application
  152. can create the MCLB and size/position
  153. it exactly on top of the placeholder control.
  154. See the SAMP1 sample for code that does this.
  155. .*-------------------------------------------------------------------------
  156. :h1 res=400.Styles
  157. The visual appearance of an MCLB can be
  158. modified through the use of 'style' flags which are passed
  159. to the :MCLBCreateWindow. API when the control is created.  The
  160. style flags cannot be changed after the MCLB is created.
  161. In addition
  162. to the flags described below, any standard PM WS_* window style flags
  163. can be used (e.g. WS_VISIBLE).  The standard PM listbox styles are
  164. shown here, along with the extended styles unqiue to MCLB controls:
  165. :ul.
  166. :li.
  167. :hp2.LS_MULTIPLESEL:ehp2.  Allow multiple items to be selected in the list
  168. (same as normal PM listbox control).
  169. :li.
  170. :hp2.LS_EXTENDEDSEL:ehp2.  Allows extended selection methods to be used in the list
  171. (same as normal PM listbox control).
  172. :li.
  173. :hp2.LS_HORZSCROLL:ehp2.  When this style is specified each column of the
  174. MCLB will have a horizontal scroll bar at the bottom.  Note that for LS_OWNERDRAW
  175. style, the application must properly process :WM_MEASUREITEM. messages in order
  176. for the scroll bar to work correctly.  This is true even if the application
  177. returns FALSE from :WM_DRAWITEM. and lets PM draw the text of an ownerdraw listbox.
  178. :li.
  179. :hp2.LS_OWNERDRAW:ehp2.  The listbox items are to be drawn by the application.
  180. When this style is used the application must respond to the :WM_MEASUREITEM.
  181. and :WM_DRAWITEM. messages.  This style applies to all columns of the MCLB (e.g.
  182. the application will be responsible for drawing all items in all columns).
  183. :li.
  184. :hp2.LS_NOADJUSTPOS:ehp2.  When this style is specified the control is
  185. sized exactly as specified and the last row may be partially visible.  When this
  186. style is not specified, the columns will be vertically sized such that
  187. the last row is not clipped.  The overall MCLB control size is never altered 
  188. (the size of the title area will be adjusted to prevent clipping if this
  189. style is not specified).
  190. :li.
  191. :hp2.MCLBS_CUASELECT:ehp2.  When this style is specified the
  192. LS_MULTIPLESEL and LS_EXTENDEDSEL styles will also be used.  This
  193. style causes the MCLB to deselect all items except one when the
  194. left button is pressed.  This behaviour is consistent with the
  195. container control.  Without this style, a left button press on
  196. an already selected item will have no effect.
  197. :li.
  198. :hp2.MCLBS_NOCOLRESIZE:ehp2.  When this style is specified the user is not
  199. allowed to change the relative column sizes.  The MCLB will be displayed
  200. without splitbars between the columns (just thin vertical lines will be
  201. drawn between the columns).  This style applies to all columns of the MCLB.
  202. It is not possible to have some sizable and some fixed-width columns in the
  203. same MCLB control.  The default is for the columns to be sizable and
  204. movable splitbars to be displayed between each column.
  205. :li.
  206. :hp2.MCLBS_SIZEMETHOD_PROP:ehp2.  This is the default SIZEMETHOD style if none
  207. is specified.  The SIZEMETHOD styles determine how the column sizes are adjusted
  208. if the MCLB control is resized by the application.  Note that this is not
  209. related to user-initiated column sizing, but only to what happens when the
  210. entire MCLB size is changed.
  211. :p.
  212. This method will cause each column size to be adjusted in proportion to its
  213. previous size.  For example, if a column was 20% of the width of the MCLB
  214. before resizing, it will be adjusted to be 20% of the width after resizing.
  215. Thus each column remains the same :hp2.relative:ehp2. size when the size
  216. of the control is changed.
  217. :li.
  218. :hp2.MCLBS_SIZEMETHOD_LEFT:ehp2.  With this SIZEMETHOD style, any change in the
  219. size of the MCLB control is reflected in the leftmost MCLB columns.  If the
  220. MCLB size is increased, the leftmost column will increase by the same
  221. amount.  If the size is decreased, column size reduction starts in the
  222. leftmost column and continues left-to-right reducing each column to
  223. zero width until the new overall control width is achieved.
  224. :li.
  225. :hp2.MCLBS_SIZEMETHOD_CUSTOM:ehp2.  With this SIZEMETHOD style, any change in the
  226. size of the MCLB control must be handled by the application.  When the size
  227. of the MCLB is changed the application will be sent a :WM_CONTROL. message
  228. with a notification code of :MCLBN_CUSTOMSIZE..  Message parameter 2 will be
  229. a pointer to array of n+1 LONG values where "n" is the number of columns.
  230. The [0] element will contain the new
  231. overall width (accounting for margins, dividers, etc).  The [1]-[n]
  232. elements contain the current column widths in pixels.  The application must
  233. set the new column widths in the [1]-[n] array elements.  The sum of the
  234. [1]-[n] values should equal the overall width given in element [0].
  235. :p.
  236. This style can be used to implement specific column sizing rules as may
  237. be required for particular applications.  For example, it might be used
  238. to prevent a particular column of being reduced below a certain minimum
  239. size.  There are some important notes to consider in using this style:
  240. :ol.
  241. :li.This style effects only the adjustment of column sizes that occures
  242. when the MCLB control size is changed.  It does not effect user-controlled
  243. column sizing.
  244. :li.If the sum of the [1]-[n] elements is not equal to the value of the
  245. [0] element, the last column will be used to make up the difference.
  246. :li.The application can choose to use the default sizing method by
  247. returning FALSE from the :MCLBN_CUSTOMSIZE. control message.
  248. :eol.
  249. :eul.
  250. .*********************************************************************************************
  251. :h1 res=101.MCLBINFO Data Structure
  252. The MCLBINFO structure describes the characteristics of an MCLB control.
  253. This structure is created and filled in by an application prior to
  254. calling the :MCLBCreateWindow. API.  It is also returned to the
  255. application with the current values when the application sends
  256. a :MCLB_QUERYINFO. message.
  257. :p.
  258. :xmp.
  259. typedef struct _MCLBINFO { 
  260.   ULONG  Size;                    /* Length of this structure                   */
  261.   char   *Titles;                 /* Title strings (TabChar separated)          */
  262.   char   TitleFont[MAX_FONTLEN];  /* Title font (null to inherit from owner)    */
  263.   char   ListFont[MAX_FONTLEN];   /* List  font (null to inherit from owner)    */
  264.   ULONG  TitleBColor;             /* Title background color (RGB)               */
  265.   ULONG  TitleFColor;             /* Title foreground color (RGB)               */
  266.   ULONG  ListBColor;              /* List  background color (RGB)               */
  267.   ULONG  ListFColor;              /* List  foreground color (RGB)               */
  268.   LONG   *InitSizes;              /* Ptr to array of initial sizes              */
  269.   char   _Reserved[64];           /* Reserved for future use                    */
  270.   USHORT Cols;                    /* Number of columns                          */
  271.   char   TabChar;                 /* Data column separator character            */
  272.   char   _Padd;                   /* Padd for separator character (zero)        */
  273. } MCLBINFO;
  274. :exmp.
  275. .*---------------------------------------------------------------------------
  276. .* IPFCPREP macros used for message reference entries
  277. .*---------------------------------------------------------------------------
  278. .dm message on.
  279. :h2 res=&res..&name.
  280. .dm off
  281. .*----------------
  282. .dm params on
  283. :parml.
  284. .dm off
  285. .*----------------
  286. .dm param1 on
  287. :pt.:hp6.Param1:ehp6.
  288. .br
  289. :parml.
  290. .dm off
  291. .*----------------
  292. .dm param2 on
  293. :eparml.
  294. :pt.:hp6.Param2:ehp6.
  295. .br
  296. :parml.
  297. .dm off
  298. .*----------------
  299. .dm item on
  300. :pt.:hp2.&name.:ehp2. :hp1.(&type.):ehp1.
  301. :pd.
  302. .dm off
  303. .*----------------
  304. .dm returns on
  305. :eparml.
  306. :pt.:hp6.Returns:ehp6.&rbl.
  307. .br
  308. :parml.
  309. .dm off
  310. .*----------------
  311. .dm eparams on
  312. :eparml.
  313. :eparml.
  314. .dm off
  315. .*----------------
  316. .dm remarks on
  317. :p.
  318. :h3.:hp5.Remarks:ehp5.
  319. .br
  320. .dm off
  321. .*----------------
  322. .dm related on
  323. :p.
  324. :h3.:hp5.Related:ehp5.
  325. .br
  326. .dm off
  327. .*----------------
  328. .dm defproc on
  329. :p.
  330. :h3.:hp5.Default Processing:ehp5.
  331. .br
  332. .dm off
  333. .*----------------
  334. .dm emessage on
  335. .dm off
  336. .*----------------
  337. .*-----------------------------------------------------------------------------------------------
  338. :h1 res=500 toc=12.WM_CONTROL Message Reference
  339. .*-----------------------------------------------------------------------------------------------
  340. This section describes all the WM_CONTROL messages generated by a MCLB control and
  341. sent to the control owner.  Note that most of the standard LN_* messages are
  342. the same as for standard PM listbox controls.  Only LN_* messages that  differ from
  343. the PM definitions are shown here.
  344. :p.
  345. For some WM_CONTROL messages it may be necessary for the application to know which
  346. column of the MCLB generated the message.  The application may :hp1.send:ehp1. the
  347. :MCLB_QUERYCTLCOL. message to get the number of the column which caused the current
  348. WM_CONTROL message.  Note that :MCLB_QUERYCTLCOL. must :hp1.only:ehp1. be sent during
  349. the processing of a WM_CONTROL message.
  350. .*-----------------------------------------------------------------------------------------------
  351. :message res=904 name='LN_*'.
  352. The following WM_CONTROL listbox notification messages retain their normal PM meanings.  Note
  353. that the control ID in SHORT 1 of mp1, and the window handle in mp2 are those of
  354. the MCLB control itself.
  355. :xmp.
  356.    LN_ENTER
  357.    LN_KILLFOCUS
  358.    LN_SETFOCUS
  359.    LN_SCROLL
  360.    LN_SELECT
  361. :exmp.
  362. .*-----------------------------------------------------------------------------------------------
  363. :message res=900 name='MCLBN_COLSIZED' .
  364. This WM_CONTROL notification is sent by the MCLB to its owner when
  365. the user has moved a column divider.
  366. :params.
  367. :param1.
  368. :item name='MCLBID' type='USHORT'.
  369. ID of the MCLB control
  370. :item name='NotifyCode' type='USHORT'.
  371. MCLBN_COLSIZED
  372. :param2.
  373. :item name='ColNum' type='USHORT'.
  374. Number of the column to the left of the moved divider.  Note that this
  375. column and the ColNum+1 column have both changed size.
  376. :returns.
  377. Nothing
  378. :eparams.
  379. :remarks.
  380. This message occures only when the user moves a column divider in the MCLB.
  381. It does not occure when the size of the MCLB control is changed.  The
  382. :MCLB_QUERYCOLSIZES. message can be used to find the new column sizes.
  383. :related.
  384. :MCLBS_NOCOLRESIZE. style
  385. .br
  386. :MCLB_QUERYCOLSIZES. message
  387. :emessage.
  388. .*-----------------------------------------------------------------------------------------------
  389. :message res=901 name='MCLBN_CUSTOMSIZE'.
  390. This WM_CONTROL notification is sent by the MCLB to its owner when
  391. the control window size has been changed and the control has the
  392. :MCLBS_SIZEMETHOD_CUSTOM. style.
  393. :params.
  394. :param1.
  395. :item name='MCLBID' type='USHORT'.
  396. ID of the MCLB control
  397. :item name='NotifyCode' type='USHORT'.
  398. MCLBN_CUSTOMSIZE
  399. :param2.
  400. :item name='Sizes' type='LONG *'.
  401. Pointer to array of LONG values.  The array has N+1 elements where
  402. N is the number of columns.  The [0] element contains the new
  403. width the columns must fit into.  The [1] to [N] elements contain
  404. the current column sizes in pixels.
  405. :returns.
  406. :item name='Processed' type='BOOL'.
  407. Return TRUE if the application has updated the [1] to [N] elements
  408. of the array with the new column widths.  Return FALSE for the
  409. MCLB control to proportionally resize the columns.
  410. :eparams.
  411. :remarks.
  412. This message occures only if the :MCLBS_SIZEMETHOD_CUSTOM. style is used.
  413. The application can choose to process this message and return TRUE, or
  414. return FALSE and let the MCLB control perform default proportional
  415. column sizing.
  416. :p.
  417. If the application returns TRUE, the [1] to [N] elements of the array
  418. must be updated with the new adjusted column sizes.  The sum of the
  419. [1] to [N] elements should be equal to the supplied [0] element value.
  420. E.g. the new column sizes must add up to the new width allocated for
  421. the columns.
  422. :related.
  423. :MCLBS_SIZEMETHOD_CUSTOM. style
  424. :emessage.
  425. .*-----------------------------------------------------------------------------------------------
  426. :message res=902 name='MCLBN_PPCHANGED'.
  427. This WM_CONTROL notification is sent by the MCLB to its owner when
  428. any presentation parameter is altered.
  429. :params.
  430. :param1.
  431. :item name='MCLBID' type='USHORT'.
  432. ID of the MCLB control
  433. :item name='NotifyCode' type='USHORT'.
  434. MCLBN_PPCHANGED
  435. :param2.
  436. :item name='ColNum' type='USHORT'.
  437. Number of the column that originated the presentation
  438. parameter changes or zero if the title area was changed.
  439. Note that all columns will have the same presentation parameters
  440. (e.g. all columns will use the same font and colors).
  441. :item name='PPType' type='USHORT'.
  442. Indicates the type of presentation parameter that was changed:
  443. :xmp.
  444.   MCLBPP_FONT         Font changed
  445.   MCLBPP_FORECOLOR    Foreground color changed
  446.   MCLBPP_BACKCOLOR    Background color changed
  447. :exmp.
  448. :returns.
  449. Nothing
  450. :eparams.
  451. :remarks.
  452. The :MCLB_QUERYINFO. message can be used to determine the current
  453. fonts and colors of the MCLB.
  454. :related.
  455. :MCLB_QUERYINFO.
  456. :emessage.
  457.  
  458. .*-----------------------------------------------------------------------------------------------
  459. :h1 toc=12.Owner-Draw Messages
  460. .*-----------------------------------------------------------------------------------------------
  461. This section describes messages the owner of an MCLB will receive
  462. if the LS_OWNERDRAW style is used.
  463. .*---------------------------------------------------------------------------
  464. :message res=501 name='WM_MEASUREITEM'.
  465. This message is sent to the owner of an owner-draw style MCLB to determine
  466. the size of a listbox item.  This message will occure for each item of each
  467. column of the listbox.  The measurements returned must be for just one
  468. column, not the aggregate size of all columns.
  469. :p.
  470. This standard PM message is extended for an MCLB to include the column
  471. number in SHORT 2 of mp1 (unused by PM).
  472. :params.
  473. :param1.
  474. :item name='MCLBId' type='SHORT'.
  475. ID of the MCLB control.
  476. :item name='Col' type='USHORT'.
  477. Column number of the item to be measured.
  478. :param2.
  479. :item name='ItemIndex' type='SHORT'.
  480. Index of the item to be measured.
  481. :returns.
  482. :item name='Height' type='SHORT'.
  483. Height of the item.
  484. :item name='Width' type='SHORT'.
  485. Width of the item.
  486. :eparams.
  487. :remarks.
  488. The application should be prepared to receive this message when the
  489. MCLB control is created (e.g. during :MCLBCreateWindow. processing).
  490. :p.
  491. Note that the vertical height
  492. of all items in all columns must be the same, and this value must
  493. be equal to or greater than the vertical font size for the listbox items.
  494. :p.
  495. The width must be the actual width of the item in the
  496. column.  If the column
  497. contains text the width returned should be the actual drawn
  498. text width.
  499. :related.
  500. :emessage.
  501. .*---------------------------------------------------------------------------
  502. :message res=502 name='WM_DRAWITEM'.
  503. This message is sent to the owner of an owner-draw style MCLB when any
  504. item in any column needs to be redrawn.  Note that this draw message
  505. applies to just a single item in a single column, not to an entire
  506. row.
  507. :p.
  508. This standard PM message is extended for an MCLB to include the column
  509. number in SHORT 2 of mp1 (unused by PM).
  510. :params.
  511. :param1.
  512. :item name='MCLBId' type='SHORT'.
  513. ID of the MCLB control.
  514. :item name='Col' type='USHORT'.
  515. Column number of the item to be drawn.
  516. :param2.
  517. :item name='DrawInfo' type='OWNERITEM *'.
  518. Pointer to an OWNERITEM data structure.
  519. :returns.
  520. :item name='Drawn' type='BOOL'.
  521. Return TRUE if the application has drawn the item.  Return
  522. FALSE for the listbox to draw the item text.
  523. :eparams.
  524. :remarks.
  525. :related.
  526. :emessage.
  527. .*-----------------------------------------------------------------------------------------------
  528. :h1 toc=12.MCLB Messages
  529. .*-----------------------------------------------------------------------------------------------
  530. This section describes all the messages an application can send to a MCLB control.
  531. Unless noted otherwise here, all the PM listbox LM_* messages work as documented
  532. for a listbox control.  Also unless stated otherwise, item text consists of
  533. all the column data separated with the column separator character.
  534. .*---------------------------------------------------------------------------
  535. :message res=1100 name='LM_INSERTITEM'.
  536. This standard listbox message is extended to include the column number
  537. by which the inserted item is to be sorted.  SHORT 2 of mp1 is unused
  538. by PM, but is defined for an MCLB as the column number by which sorting is
  539. to be done.  If it is zero or greater than the number of columns,
  540. LIT_ERORR will be returned.
  541. :p.
  542. It is recomended that if many items are to be inserted in the MBLB,
  543. that WinEnableWindowUpdate() be used to improve performance.  Window
  544. updating should be disabled before the first insert and enabled after
  545. the last insert.
  546. :params.
  547. :param1.
  548. :item name='InsertIndex' type='SHORT'.
  549. Position in the list at which to insert, or LIT_END, LIT_SORTASCENDING, or
  550. LIT_SORTDECENDING.
  551. :item name='SortCol' type='USHORT'.
  552. If InsertIndex is LIT_SORTASCENDING or LIT_SORTDECENDING then the
  553. specified column number is used to determine the sorting sequence.
  554. :param2.
  555. :item name='Text' type='char *'.
  556. Pointer to string to be inserted.  Column data is separated in the
  557. string by the column separator charcter defined in :MCLBINFO. when the
  558. MCLB was created.
  559. :returns.
  560. :item name='InsertedAt' type='SHORT'.
  561. Index of newly inserted item or LIT_MEMERROR, or LIT_ERROR.
  562. :eparams.
  563. :remarks.
  564. :related.
  565. :emessage.
  566. .*---------------------------------------------------------------------------
  567. :message res=1101 name='LM_INSERTMULTITEMS'.
  568. :hp1.(Note: This is a new message in OS/2 Warp.):ehp1.
  569. :p.
  570. This standard listbox message is extended to include the column number
  571. by which the inserted items are to be sorted.  The :hp2.reserved2:ehp2. field
  572. of the LBOXINFO structure is used  to define
  573. the column number by which sorting is
  574. to be done.  If it is zero or greater than the number of columns,
  575. LIT_ERORR will be returned.
  576. :p.
  577. Note that due to the implementation of the MCLB, there is little performance
  578. difference between using this message to insert items and repeated use
  579. of LM_INSERTITEM.
  580. :params.
  581. :param1.
  582. :item name='Info' type='LBOXINFO *'.
  583. Pointer to LBOXINFO structure (new in Warp 3.0 toolkit).
  584. :param2.
  585. :item name='Strings' type='char **'.
  586. Pointer to array of string pointers.  Each string represents one
  587. row of the MCLB using the column separator character to separate
  588. the data into columns.
  589. :returns.
  590. :item name='InsertedAt' type='SHORT'.
  591. Index of newly inserted item or LIT_MEMERROR, or LIT_ERROR.
  592. :eparams.
  593. :remarks.
  594. :related.
  595. :emessage.
  596. .*---------------------------------------------------------------------------
  597. :message res=1102 name='LM_SEARCHSTRING'.
  598. :hp1.This message is not fully implemented for an MCLB control.:ehp1.
  599. The search is performed only on the first column.
  600. :emessage.
  601. .*---------------------------------------------------------------------------
  602. :message res=910 name='MCLB_SETTITLES' .
  603. This message is sent to the MCLB to set the title strings (column headers).
  604. :params.
  605. :param1.
  606. :item name='Titles' type='* char'.
  607. Pointer to a character string which contains the new column titles.  The
  608. titles must be separated by the MCLB column separator character as defined
  609. in the :MCLBINFO. structure when the MCLB was created.
  610. :param2.
  611. Reserved
  612. :returns.
  613. Nothing
  614. :eparams.
  615. :remarks.
  616. :related.
  617. :emessage.
  618. .*---------------------------------------------------------------------------
  619. :message res=911 name='MCLB_SETTITLEFONT'.
  620. This message is sent to the MCLB to set the font to be used for the titles.
  621. :params.
  622. :param1.
  623. :item name='FontNameSize' type='* char'.
  624. Pointer to a character string which contains the new font to be used.
  625. The format of the string is the same as that used in the WinSetPresParam() call
  626. such as "8.Helv".  This parameter may be NULL in which case the title
  627. font is reset to the default font.
  628. :param2.
  629. Reserved
  630. :returns.
  631. Nothing
  632. :eparams.
  633. :remarks.
  634. :related.
  635. :emessage.
  636. .*---------------------------------------------------------------------------
  637. :message res=912 name='MCLB_SETLISTFONT'.
  638. This message is sent to the MCLB to set the font to be used for the list items.
  639. :params.
  640. :param1.
  641. :item name='FontNameSize' type='* char'.
  642. Pointer to a character string which contains the new font to be used.
  643. The format of the string is the same as that used in the WinSetPresParam() call
  644. such as "8.Helv".  This parameter may be NULL in which case the list
  645. font is reset to the default font.
  646. :param2.
  647. Reserved
  648. :returns.
  649. Nothing
  650. :eparams.
  651. :remarks.
  652. :related.
  653. :emessage.
  654. .*---------------------------------------------------------------------------
  655. :message res=913 name='MCLB_SETTITLECOLORS'.
  656. This message is sent to the MCLB to set the colors to be used for the titles.
  657. :params.
  658. :param1.
  659. :item name='Foreground' type='LONG'.
  660. Contains the RGB value of the foreground color.
  661. :param2.
  662. :item name='Background' type='LONG'.
  663. Contains the RGB value of the background color.
  664. :returns.
  665. Nothing
  666. :eparams.
  667. :remarks.
  668. If the foreground and background colors specified are the same,
  669. the title colors are reset to the default colors.
  670. :related.
  671. :emessage.
  672. .*---------------------------------------------------------------------------
  673. :message res=914 name='MCLB_SETLISTCOLORS'.
  674. This message is sent to the MCLB to set the colors to be used for the list items.
  675. :params.
  676. :param1.
  677. :item name='Foreground' type='LONG'.
  678. Contains the RGB value of the foreground color.
  679. :param2.
  680. :item name='Background' type='LONG'.
  681. Contains the RGB value of the background color.
  682. :returns.
  683. Nothing
  684. :eparams.
  685. :remarks.
  686. If the foreground and background colors specified are the same,
  687. the list colors are reset to the default colors.
  688. :related.
  689. :emessage.
  690. .*---------------------------------------------------------------------------
  691. :message res=915 name='MCLB_SETCOLSIZES'.
  692. This message is sent to the MCLB to set the columns to specific sizes.
  693. :params.
  694. :param1.
  695. :item name='NewSizes' type='LONG *'.
  696. Pointer to array of LONG values.  Array must contain at least
  697. N elements, where N is the number of columns in the MCLB.
  698. :param2.
  699. Reserved
  700. :returns.
  701. Nothing
  702. :eparams.
  703. :remarks.
  704. The value of the [0] to [N-1] elements of the array must add up
  705. to the current width of all the columns.  The current sum of the column
  706. widths can be deterined with the :MCLB_QUERYFULLSIZE. message.
  707. :related.
  708. :emessage.
  709. .*---------------------------------------------------------------------------
  710. :message res=916 name='MCLB_QUERYCOLSIZES'.
  711. This message is sent to the MCLB to query the current size of the columns.
  712. :params.
  713. :param1.
  714. :item name='Sizes' type='LONG *'.
  715. Pointer to array of LONG values.  Array must contain at least
  716. N elements, where N is the number of columns in the MCLB.
  717. :param2.
  718. Reserved
  719. :returns.
  720. Nothing
  721. :eparams.
  722. :remarks.
  723. The value of the [0] to [N-1] elements of the array will
  724. be set to the current column widths in pixels.
  725. :related.
  726. :emessage.
  727. .*---------------------------------------------------------------------------
  728. :message res=917 name='MCLB_QUERYINFO'.
  729. This message is sent to the MCLB to query the current MCLB configuration.
  730. :params.
  731. :param1.
  732. :item name='Info' type='* MCLBINFO'.
  733. Pointer to :MCLBINFO. structure.  Upon return the structured will
  734. be filled with the current values. 
  735. :param2.
  736. Reserved
  737. :returns.
  738. Nothing
  739. :eparams.
  740. :remarks.
  741. The value of the :hp1.InitSizes:ehp1. array will be set to the
  742. current column sizes.
  743. :p.
  744. :hp1.NOTE&colon.:ehp1. The application must free the :hp1.InitSizes:ehp1.
  745. array and the :hp1.Titles:ehp1. string.
  746. :related.
  747. :emessage.
  748. .*---------------------------------------------------------------------------
  749. :message res=918 name='MCLB_QUERYSTYLE'.
  750. This message is sent to the MCLB to query the MCLB styles flags.
  751. :params.
  752. :param1.
  753. Reserved
  754. :param2.
  755. Reserved
  756. :returns.
  757. :item name='Styles' type='ULONG'.
  758. Only the MCLB-specific style bits (MCLBS_* flags) will be returned.
  759. :eparams.
  760. :remarks.
  761. :related.
  762. :emessage.
  763. .*---------------------------------------------------------------------------
  764. :message res=919 name='MCLB_QUERYFULLSIZE'.
  765. This message is sent to the MCLB to query the sum of the column widths
  766. :params.
  767. :param1.
  768. Reserved
  769. :param2.
  770. Reserved
  771. :returns.
  772. :item name='Width' type='LONG'.
  773. The sum of the current column widths.
  774. :eparams.
  775. :remarks.
  776. Note that this value is not the same as the width of the control window.
  777. This value is the width of the control minus the width of all dividers,
  778. vertical scroll bars, borders, etc.  It is the number of pixels actually
  779. allocated for the columns of data.
  780. :related.
  781. :emessage.
  782. .*---------------------------------------------------------------------------
  783. :message res=920 name='MCLB_QUERYCTLCOL'.
  784. This message is sent to the MCLB to query column which caused the current :WM_CONTROL. message.
  785. :params.
  786. :param1.
  787. Reserved
  788. :param2.
  789. Reserved
  790. :returns.
  791. :item name='Col' type='USHORT'.
  792. The number of the column which caused the current :WM_CONTROL. message.
  793. :eparams.
  794. :remarks.
  795. This message must be :hp1.sent:ehp1. to the MCLB, not posted.  The results
  796. of this message are only defined during :WM_CONTROL. message processing.
  797. :p.
  798. It can be useful at times to know which column of an MCLB has caused a
  799. particular :WM_CONTROL. message to be sent to the owner.  The owner can
  800. discover this by sending the MCLB this message.  This message must be
  801. sent while the owner is processing the :WM_CONTROL. message of interest.
  802. :related.
  803. :emessage.
  804. .*---------------------------------------------------------------------------
  805. .* API Reference
  806. .*---------------------------------------------------------------------------
  807. :h1.Programming Interfaces (API)
  808. This section describes each of the callable MCLB programming interfaces.
  809. .*---------------------------------------------------------------------------
  810. .* IPFCPREP macros used for message reference entries
  811. .*---------------------------------------------------------------------------
  812. .dm function on
  813. :h2 res=&res..&name.
  814. .dm off
  815. .*----------------
  816. .dm syntax on
  817. :p.
  818. :hp7.Syntax&colon.:ehp7.
  819. .br
  820. :lines.
  821. :font facename='System Monospaced' size=12x10.
  822. :hp4.&return. &name.(¶ms.):ehp4.
  823. :font facename=default size=0x0.
  824. :elines.
  825. .dm off
  826. .*----------------
  827. .dm fparams on
  828. :font facename='System Monospaced' size=12x10.
  829. :table cols='15 10 10 50' rules=both frame=box.
  830. :row.
  831. :c.:hp1.Name:ehp1.
  832. :c.:hp1.Type:ehp1.
  833. :c.:hp1.In/Out:ehp1.
  834. :c.:hp1.Description:ehp1.
  835. .dm off
  836. .*----------------
  837. .dm fparam on
  838. :row.
  839. :c.&name.
  840. :c.&type.
  841. :c.&io.
  842. :c.
  843. .dm off
  844. .*----------------
  845. .dm freturns on
  846. :etable.
  847. :font facename=default size=0x0.
  848. :hp1.Returns:ehp1.
  849. :font facename='System Monospaced' size=12x10.
  850. :table cols='15 10 10 50' rules=both frame=box.
  851. .dm off
  852. .*----------------
  853. .dm efparams on
  854. :etable.
  855. :font facename=default size=0x0.
  856. .dm off
  857. .*----------------
  858. .dm efunction on
  859. .dm off
  860. .*----------------
  861. .*--------------------------------------------------------------------------
  862. .*-------------------------------------------------------------------------
  863. :function res=1000 name='MCLBCreateWindow' text='Create an MCLB Control'.
  864. This function creates an MCLB and returns its window handle.
  865. :syntax name='MCLBCreateWindow' params='Parent, Owner, Style, x, y, cx, cy, Behind, Id, MCLBInfo' return='MCLBHwnd'.
  866. :fparams.
  867. :fparam name='Parent' type='HWND' io='input'.
  868. Handle of the parent window.
  869. :fparam name='Owner' type='HWND' io='input'.
  870. Handle of the owner window.  This window will recieve :WM_CONTROL. messages
  871. from the MCLB.
  872. :fparam name='Style' type='ULONG' io='input'.
  873. Style flags.  This is a logical-OR combination of WS_* window styles,
  874. LS_* listbox styles, and :link reftype=hd res=400.MCLBS_* MCLB styles:elink..
  875. :fparam name='x' type='LONG' io='input'.
  876. X position of the window relative to the Parent window.
  877. :fparam name='y' type='LONG' io='input'.
  878. Y position of the window relative to the Parent window.
  879. :fparam name='cx' type='LONG' io='input'.
  880. Width of the window.
  881. :fparam name='cy' type='LONG' io='input'.
  882. Height of the window.
  883. :fparam name='Behind' type='HWND' io='input'.
  884. Sibling window behind which this window is to be placed.  HWND_TOP or
  885. HWND_BOTTOM can be used to place this window on top of, or behind all
  886. other sibling windows.
  887. :fparam name='Id' type='USHORT' io='input'.
  888. Id of this window.  This Id is encoded in all :WM_CONTROL. messages from this MCLB.
  889. :fparam name='Info' type='MCLBINFO *' io='input'.
  890. Pointer to completed :MCLBINFO. data structure.
  891. :freturns.
  892. :fparam name='MCLBHwnd' type='HWND' io='return'.
  893. Handle of the MCLB window, or NULLHANDLE if creation failed.
  894. :efparams.
  895. :remarks.
  896. :related.
  897. :MCLBINFO.
  898. :euserdoc.
  899.