home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / mclb.zip / lb.pak / DMLB.IPF < prev    next >
Text File  |  1995-07-31  |  20KB  |  556 lines
  1. .***************************************************************************
  2. .* DMLB 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 DMLBInitialize on
  27. :link reftype=hd res=400.DMLBInitialize:elink.
  28. .dm off
  29.  
  30. .dm Resources on
  31. :link reftype=hd res=700.DMLB Resources:elink.
  32. .dm off
  33.  
  34. .dm LN_DMLB_QRYDROP on
  35. :link reftype=hd res=906.LN_DMLB_QRYDROP:elink.
  36. .dm off
  37.  
  38. .dm LN_DMLB_INSERT_COPY on
  39. :link reftype=hd res=905.LN_DMLB_INSERT_COPY:elink.
  40. .dm off
  41.  
  42. .dm LN_DMLB_INSERT_MOVE on
  43. :link reftype=hd res=904.LN_DMLB_INSERT_MOVE:elink.
  44. .dm off
  45.  
  46. .dm LN_DMLB_REORDERED on
  47. :link reftype=hd res=903.LN_DMLB_REORDERED:elink.
  48. .dm off
  49.  
  50. .dm LN_DMLB_DELETE_MOVE on
  51. :link reftype=hd res=902.LN_DMLB_DELETE_MOVE:elink.
  52. .dm off
  53.  
  54. .dm LN_DMLB_DELETE on
  55. :link reftype=hd res=901.LN_DMLB_DELETE:elink.
  56. .dm off
  57.  
  58. .dm LN_DMLB_CONTEXT on
  59. :link reftype=hd res=900.LN_DMLBN_CONTEXT:elink.
  60. .dm off
  61. .***************************************
  62. :title.Direct Manipulation ListBox (DMLB)
  63. .***************************************
  64. :h1. Introduction
  65. This document is the programmer's reference for the Direct Manipulation ListBox (DMLB)
  66. control.
  67. For more information on programming with this
  68. control, see :hp1.OS/2 Developer Magazine:ehp1., Nov/Dec 1995.
  69. :p.
  70. :artwork align=center name='pic2.bmp'.
  71. :p.
  72. :hp7.Acknowledgments:ehp7.
  73. .br
  74. This control was originally conceived at IBM Yorktown Research by
  75. Alan Warren. The control was rewritten
  76. and enhanced by Mark McMillan of IBM, Research Triangle Park, USA.
  77. :p.
  78. :hp7.Description:ehp7.
  79. .br
  80. The :hp3.Direct Manipulation ListBox:ehp3. is a very useful
  81. enhancement for the standard PM listbox control.  It supplies the
  82. capability to support drag/drop reordering of items in a listbox,
  83. and drag/drop of items from one listbox to another.
  84.  
  85. .*---------------------------------------------------------------------------
  86. :h1.Using the DMLB
  87. To add direct-manipulation capability to a standard listbox (or an MCLB),
  88. the listbox or MCLB should be created in the usual way.  After the listbox
  89. control is created, the :DMLBInitialize. function is called to establish
  90. the DMLB subclass.
  91. :p.
  92. The application must define the following resources in its .RC file:
  93. :xmp.
  94. #include "dmlb.h"
  95. POINTER ID_DMLB_DRAGMOVE "lbdrag.ptr"
  96. POINTER ID_DMLB_DRAGCOPY "lbdragcp.ptr"
  97. POINTER ID_DMLB_DRAGNONE "nodrag.ptr"
  98. POINTER ID_DMLB_DRGNORTH "drgnorth.ptr"
  99. POINTER ID_DMLB_DRGSOUTH "drgsouth.ptr"
  100. POINTER ID_DMLB_DRGDEL   "drgdel.ptr"
  101. :exmp.
  102. .br
  103. If these resources reside an a DLL, the DLL module handle must be
  104. supplied on the :DMLBInitialize. call.
  105. :p.
  106. Once the DMLB subclass is established, the application must, at a
  107. minimum, respond to the :LN_DMLB_QRYDROP. message.  It may choose
  108. to also process other DMLB notification messages.
  109. .*---------------------------------------------------------------------------
  110. .* IPFCPREP macros used for message reference entries
  111. .*---------------------------------------------------------------------------
  112. .dm message on.
  113. :h2 res=&res..&name.
  114. .dm off
  115. .*----------------
  116. .dm params on
  117. :parml.
  118. .dm off
  119. .*----------------
  120. .dm param1 on
  121. :pt.:hp6.Param1:ehp6.
  122. .br
  123. :parml.
  124. .dm off
  125. .*----------------
  126. .dm param2 on
  127. :eparml.
  128. :pt.:hp6.Param2:ehp6.
  129. .br
  130. :parml.
  131. .dm off
  132. .*----------------
  133. .dm item on
  134. :pt.:hp2.&name.:ehp2. :hp1.(&type.):ehp1.
  135. :pd.
  136. .dm off
  137. .*----------------
  138. .dm returns on
  139. :eparml.
  140. :pt.:hp6.Returns:ehp6.&rbl.
  141. .br
  142. :parml.
  143. .dm off
  144. .*----------------
  145. .dm eparams on
  146. :eparml.
  147. :eparml.
  148. .dm off
  149. .*----------------
  150. .dm remarks on
  151. :p.
  152. :h3.:hp5.Remarks:ehp5.
  153. .br
  154. .dm off
  155. .*----------------
  156. .dm related on
  157. :p.
  158. :h3.:hp5.Related:ehp5.
  159. .br
  160. .dm off
  161. .*----------------
  162. .dm sample on
  163. :p.
  164. :h3.:hp5.Example:ehp5.
  165. .br
  166. :xmp.
  167. :font facename='System Monospaced' size=12x10.
  168. .dm off
  169. .*----------------
  170. .dm esample on
  171. :font facename=default size=0x0.
  172. :exmp.
  173. .dm off
  174. .*----------------
  175. .dm defproc on
  176. :p.
  177. :h3.:hp5.Default Processing:ehp5.
  178. .br
  179. .dm off
  180. .*----------------
  181. .dm emessage on
  182. .dm off
  183. .*----------------
  184. .*-----------------------------------------------------------------------------------------------
  185. :h1 res=500 toc=12.WM_CONTROL Message Reference
  186. .*-----------------------------------------------------------------------------------------------
  187. This section describes all the WM_CONTROL messages generated by a DMLB subclassed control and
  188. sent to the control owner.  Note that all of the standard LN_* messages are
  189. generated from the listbox as usual.
  190. .*-----------------------------------------------------------------------------------------------
  191. :message res=900 name='LN_DMLB_CONTEXT'.
  192. This WM_CONTROL notification is sent by the DMLB to its owner when
  193. the user has requested a context menu on the listbox.
  194. :params.
  195. :param1.
  196. :item name='DMLBID' type='USHORT'.
  197. ID of the DMLB listbox
  198. :item name='NotifyCode' type='USHORT'.
  199. LN_DMLB_CONTEXT
  200. :param2.
  201. :item name='Index' type='SHORT'.
  202. Index of the item for which the context menu was requested.  This value
  203. will be LIT_NONE if the pointer was not over an item when the menu
  204. was requested.
  205. :returns.
  206. Nothing
  207. :eparams.
  208. :remarks.
  209. The owner can respond by poping up a context menu at the current pointer
  210. coordinates or it can ignore this message if context menus are not
  211. supported.
  212. :sample.
  213. case WM_INITDLG: // or WM_CREATE
  214.   ContextHwnd = WinLoadMenu(...);
  215.   ...
  216.  
  217. case WM_CONTROL:                                          
  218.   switch SHORT1FROMMP(mp1) {                              
  219.     case ID_LISTBOX:
  220.       switch (SHORT2FROMMP(mp1)) {
  221.  
  222.         case LN_DMLB_CONTEXT: {
  223.           /* The user has requested a context menu.  Short 1 of mp2 is the */
  224.           /* index of the listbox item under the pointer.                  */
  225.           POINTL Point;
  226.           SHORT  ContextIndex;
  227.  
  228.           ContextIndx = SHORT1FROMMP(mp2);
  229.  
  230.           /* Popup the context menu at the pointer position. */
  231.           WinQueryMsgPos((HAB)0, &.Point);
  232.           WinPopupMenu(HWND_DESKTOP, hwnd, ContextHwnd, Point.x, Point.y,
  233.                                           0, PU_HCONSTRAIN| PU_VCONSTRAIN
  234.                       PU_MOUSEBUTTON1 | PU_MOUSEBUTTON2 | PU_MOUSEBUTTON3
  235.                                                         | PU_KEYBOARD );
  236.           return (MRESULT)TRUE;
  237.           }
  238.       }                           
  239.       break;                      
  240.   }                               
  241.   break; /* End of WM_CONTROL */          
  242. :esample.
  243. :emessage.
  244. .*-----------------------------------------------------------------------------------------------
  245. :message res=901 name='LN_DMLB_DELETE'.
  246. This WM_CONTROL notification is sent to the owner of the :hp2.source:ehp2. listbox when
  247. a listbox item is about to be deleted as a result of a drag/drop operation.
  248. :params.
  249. :param1.
  250. :item name='DMLBID' type='USHORT'.
  251. ID of the DMLB listbox
  252. :item name='NotifyCode' type='USHORT'.
  253. LN_DMLB_DELETE
  254. :param2.
  255. :item name='Target' type='HWND'.
  256. The window handle of the target listbox on which the drop
  257. has occured.
  258. :returns.
  259. Nothing
  260. :eparams.
  261. :remarks.
  262. This message occures when a listbox item is dropped on a listbox
  263. which returned DROPMODE_DELETE in response to a :LN_DMLB_QRYDROP.
  264. message.  The listbox on which the drop occured is given in mp2.
  265. The item to be deleted is the currently selected item of the
  266. listbox.
  267. :p.
  268. Note that this message does :hp2.not:ehp2. occure when an item
  269. is :hp1.moved:ehp1. from one listbox to another.  It occures
  270. only if the item is to be deleted.
  271. :p.
  272. This message is sent :hp2.before:ehp2. the item is deleted giving
  273. the owner a chance to free any dynamic resources that may be
  274. associated with this item.
  275. :emessage.
  276. .*-----------------------------------------------------------------------------------------------
  277. :message res=902 name='LN_DMLB_DELETE_MOVE'.
  278. This WM_CONTROL notification is sent to the owner of the :hp2.source:ehp2. listbox when
  279. a listbox item is about to be moved to another listbox as a result of a drag/drop operation.
  280. :params.
  281. :param1.
  282. :item name='DMLBID' type='USHORT'.
  283. ID of the DMLB listbox
  284. :item name='NotifyCode' type='USHORT'.
  285. LN_DMLB_DELETE_MOVE
  286. :param2.
  287. :item name='Target' type='HWND'.
  288. The window handle of the target listbox on which the drop
  289. has occured.
  290. :returns.
  291. Nothing
  292. :eparams.
  293. :remarks.
  294. This message occures when a listbox item is dropped on a listbox
  295. which returned DROPMODE_MOVE in response to a :LN_DMLB_QRYDROP.
  296. message.  The listbox on which the drop occured is given in mp2.
  297. The item to be moved is the currently selected item of the
  298. listbox.
  299. :p.
  300. Note that this message does :hp2.not:ehp2. occure when an item
  301. is :hp1.moved:ehp1. within the same listbox (see :LN_DMLB_REORDERED.).  It occures
  302. only if the item is moved from this (source) listbox to another
  303. (target) listbox.  When an item is moved from one listbox to
  304. another, the item text and handle are both copied to the target
  305. listbox and then the item is deleted from the source listbox.
  306. :p.
  307. This message is sent :hp2.before:ehp2. the item is deleted from the
  308. source listbox.
  309. :emessage.
  310. .*-----------------------------------------------------------------------------------------------
  311. :message res=903 name='LN_DMLB_REORDERED'.
  312. This WM_CONTROL notification is sent by the DMLB to its owner when
  313. a listbox item is moved within the same listbox (the listbox items are reordered).
  314. :params.
  315. :param1.
  316. :item name='DMLBID' type='USHORT'.
  317. ID of the DMLB listbox
  318. :item name='NotifyCode' type='USHORT'.
  319. LN_DMLB_REORDERED
  320. :param2.
  321. :item name='Target' type='HWND'.
  322. The window handle of listbox
  323. :returns.
  324. Nothing
  325. :eparams.
  326. :remarks.
  327. This message occures when a listbox item is dragged and dropped
  328. on the same listbox.  The moved item is the currently
  329. selected item.
  330. :p.
  331. When an item is moved the item text and item handle are copied, the
  332. item is deleted, and then the item is reinserted at a new position.
  333. :emessage.
  334. .*-----------------------------------------------------------------------------------------------
  335. :message res=904 name='LN_DMLB_INSERT_MOVE'.
  336. This WM_CONTROL notification is sent to the owner of the :hp2.target:ehp2. listbox when
  337. a listbox item inserted by being moved from another listbox.
  338. :params.
  339. :param1.
  340. :item name='DMLBID' type='USHORT'.
  341. ID of the DMLB listbox
  342. :item name='NotifyCode' type='USHORT'.
  343. LN_DMLB_INSERT_MOVE
  344. :param2.
  345. :item name='Target' type='HWND'.
  346. The window handle of the source listbox
  347. :returns.
  348. Nothing
  349. :eparams.
  350. :remarks.
  351. This message occures when a listbox item is dragged from another
  352. listbox and dropped on this listbox.  This listbox must
  353. responded with DROPMODE_MOVE to :LN_DMLB_QRYDROP. to receive
  354. this message.
  355. :p.
  356. This message is sent after the insert has been completed.  The
  357. inserted item is the currently selected item.  This message
  358. occures before the item is deleted from the source listbox.
  359. Both the item text and item handle are copied from the source
  360. listbox.
  361. :emessage.
  362. .*-----------------------------------------------------------------------------------------------
  363. :message res=905 name='LN_DMLB_INSERT_COPY'.
  364. This WM_CONTROL notification is sent to the owner of the :hp2.target:ehp2. listbox
  365. when a listbox item inserted by being copied from another listbox.
  366. :params.
  367. :param1.
  368. :item name='DMLBID' type='USHORT'.
  369. ID of the DMLB listbox
  370. :item name='NotifyCode' type='USHORT'.
  371. LN_DMLB_INSERT_COPY
  372. :param2.
  373. :item name='Target' type='HWND'.
  374. The window handle of the source listbox
  375. :returns.
  376. Nothing
  377. :eparams.
  378. :remarks.
  379. This message occures when a listbox item is dragged from another
  380. listbox and dropped on this listbox.  This listbox must
  381. responded with DROPMODE_COPY to :LN_DMLB_QRYDROP. to receive
  382. this message.
  383. :p.
  384. This message is sent after the insert has been completed.  The
  385. inserted item is the currently selected item.  
  386. Both the item text and item handle are copied from the source
  387. listbox.  The source listbox item is not deleted.
  388. :emessage.
  389. .*-----------------------------------------------------------------------------------------------
  390. :message res=906 name='LN_DMLB_QRYDROP'.
  391. This WM_CONTROL notification is sent to the owner of the :hp2.target:ehp2. listbox
  392. when a listbox item is dragged over it.
  393. :params.
  394. :param1.
  395. :item name='DMLBID' type='USHORT'.
  396. ID of the DMLB listbox
  397. :item name='NotifyCode' type='USHORT'.
  398. LN_DMLB_QRYDROP
  399. :param2.
  400. :item name='Target' type='HWND'.
  401. The window handle of the source listbox
  402. :returns.
  403. :item name='DropAllowed' type='BOOL'.
  404. If FALSE is returned then no drop is allowed and the pointer will
  405. be set to the "no drop" shape.  If TRUE is returned then a drop
  406. is allowed and the pointer shape is set according to the
  407. :hp1.DropType:ehp1. value.
  408. :item name='DropType' type='SHORT'.
  409. If :hp1.DropAllowed:ehp1. is FALSE then this value is ignored.  Otherwise
  410. this value indicates what action will be taken if the user completes
  411. the drop on this listbox.  The possible values are:
  412. :ul.
  413. :li.:hp2.DROPMODE_MOVE:ehp2. The item will be inserted into the current
  414. listbox and deleted from the source listbox.  If the source and target
  415. listboxs are same a :LN_DMLB_REORDERED. notification message will be sent.  If
  416. they are different listboxes, :LN_DMLB_INSERT_MOVE. will be sent to the
  417. target and :LN_DMLB_DELETE_MOVE. will be sent to the source.
  418. :li.:hp2.DROPMODE_MOVE:ehp2. The item will be inserted into the current
  419. listbox.  It will not be deleted from the source listbox.  If the source and target
  420. listboxs are same the item will be duplicated in the listbox. A
  421. :LN_DMLB_INSERT_COPY. notification message is sent to the target listbox.
  422. No notification is sent to the source.
  423. :li.:hp2.DROPMODE_DELETE:ehp2. The item will be deleted from the source
  424. listbox.  It will not be inserted in the target listbox.  The source
  425. listbox will receive a :LN_DMLB_DELETE. notification message.
  426. :eul.
  427. :eparams.
  428. :remarks.
  429. This message is sent to the target listbox while a drag is in progress
  430. over the listbox.  The application must respond by indicating if
  431. a drop is allowed or not, and if so, what type of drop should occure
  432. (copy, move, or delete).  The pointer shape will be changed to reflect
  433. the result of this message and if :hp1.NoDrop:ehp1. is TRUE, no
  434. drop will be allowed.
  435. :p.
  436. Note that this message does occure when a listbox item is dragged
  437. on its own listbox.
  438. :sample.
  439.   case WM_CONTROL:                                          
  440.     switch SHORT1FROMMP(mp1) {                              
  441.       case ID_LISTBOX:
  442.         switch (SHORT2FROMMP(mp1)) {
  443.  
  444.           case LN_DMLB_QRYDROP:
  445.             // If dropping in same listbox, move the item.  If drop is
  446.             // from some other listbox, refuse it.
  447.  
  448.             if (HWNDFROMMP(mp2) == WinWindowFromID(hwnd, ID_LISTBOX))
  449.               return MRFROM2SHORT(TRUE, DROPMODE_MOVE);
  450.  
  451.             return MRFROM2SHORT(FALSE, 0);
  452.  
  453.             ...
  454. :esample.
  455. :emessage.
  456. .*---------------------------------------------------------------------------
  457. :h1 res=700.DMLB Resources
  458. .*---------------------------------------------------------------------------
  459. The DMLB subclass requires access to several POINTER type resources
  460. to use during drag/drop operations.  The application must have the
  461. following statements in its resource (.RC) file:
  462. :xmp.
  463.   #include "dmlb.h"
  464.   POINTER ID_DMLB_DRAGMOVE "lbdrag.ptr"
  465.   POINTER ID_DMLB_DRAGCOPY "lbdragcp.ptr"
  466.   POINTER ID_DMLB_DRAGNONE "nodrag.ptr"
  467.   POINTER ID_DMLB_DRGNORTH "drgnorth.ptr"
  468.   POINTER ID_DMLB_DRGSOUTH "drgsouth.ptr"
  469.   POINTER ID_DMLB_DRGDEL   "drgdel.ptr"
  470. :exmp.
  471. .br
  472. As supplied in the toolkit, these resources use POINTER IDs 9000 through 9005.
  473. Application defined POINTER resources must not conflict with these ID values.
  474. :p.
  475. If these resources are defined in a DLL then the DLL module handle must be
  476. supplied on the :DMLBInitialize. call.
  477. .*---------------------------------------------------------------------------
  478. .* IPFCPREP macros used for API reference entries
  479. .*---------------------------------------------------------------------------
  480. .dm function on
  481. :h1 res=&res..&name.
  482. .dm off
  483. .*----------------
  484. .dm syntax on
  485. :p.
  486. :hp7.Syntax&colon.:ehp7.
  487. .br
  488. :lines.
  489. :font facename='System Monospaced' size=12x10.
  490. :hp4.&return. &name.(¶ms.):ehp4.
  491. :font facename=default size=0x0.
  492. :elines.
  493. .dm off
  494. .*----------------
  495. .dm fparams on
  496. :font facename='System Monospaced' size=12x10.
  497. :table cols='15 10 10 50' rules=both frame=box.
  498. :row.
  499. :c.:hp1.Name:ehp1.
  500. :c.:hp1.Type:ehp1.
  501. :c.:hp1.In/Out:ehp1.
  502. :c.:hp1.Description:ehp1.
  503. .dm off
  504. .*----------------
  505. .dm fparam on
  506. :row.
  507. :c.&name.
  508. :c.&type.
  509. :c.&io.
  510. :c.
  511. .dm off
  512. .*----------------
  513. .dm freturns on
  514. :etable.
  515. :font facename=default size=0x0.
  516. :hp1.Returns:ehp1.
  517. :font facename='System Monospaced' size=12x10.
  518. :table cols='15 10 10 50' rules=both frame=box.
  519. .dm off
  520. .*----------------
  521. .dm efparams on
  522. :etable.
  523. :font facename=default size=0x0.
  524. .dm off
  525. .*----------------
  526. .dm efunction on
  527. .dm off
  528. .*----------------
  529. .*--------------------------------------------------------------------------
  530. :function res=400 name='DMLBInitialize' text='Establish and initialize DMLB subclass'.
  531. This function establishes a DMLB subclass on a standard PM listbox control.
  532. :syntax name='DMLBInitialize' params='LBHwnd, ResHMod' return='BOOL'.
  533. :fparams.
  534. :fparam name='LBHwnd' type='HWND' io='input'.
  535. Handle of the listbox to be subclassed.
  536. :fparam name='ResHMod' type='HMODULE' io='input'.
  537. Handle of the module (DLL) the :Resources. are to be
  538. retrieved from.  This may be NULLHANDLE if the sources are bound
  539. to the EXE.
  540. :freturns.
  541. :fparam name='Sucess' type='BOOL' io='return'.
  542. TRUE if initialization sucessful, FALSE if it failed.
  543. :efparams.
  544. :remarks.
  545. This function is called to setup a DMLB subclassing of a standard PM listbox
  546. control.  Note that the QWL_USER window words of the listbox window will be
  547. used by the subclass for a pointer to the subclass instance data.
  548. After this function sucessfully completes, the
  549. application may use the first PVOID of the DMLB instance data.
  550. :p.
  551. The application must have the :Resources. (pointers) available
  552. in a resource DLL or bound to the executable module.  If the resources
  553. reside in a DLL the DLL module handle must be supplied on this call.
  554. :efunction.
  555. :euserdoc.
  556.