home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / mclb.zip / lb.pak / DMLB.INF (.txt) < prev    next >
OS/2 Help File  |  1995-07-31  |  23KB  |  416 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Introduction ΓòÉΓòÉΓòÉ
  3.  
  4. This document is the programmer's reference for the Direct Manipulation ListBox 
  5. (DMLB) control. For more information on programming with this control, see OS/2 
  6. Developer Magazine, Nov/Dec 1995. 
  7.  
  8. Acknowledgments 
  9. This control was originally conceived at IBM Yorktown Research by Alan Warren. 
  10. The control was rewritten and enhanced by Mark McMillan of IBM, Research 
  11. Triangle Park, USA. 
  12.  
  13. Description 
  14. The Direct Manipulation ListBox is a very useful enhancement for the standard 
  15. PM listbox control.  It supplies the capability to support drag/drop reordering 
  16. of items in a listbox, and drag/drop of items from one listbox to another. 
  17.  
  18.  
  19. ΓòÉΓòÉΓòÉ 2. Using the DMLB ΓòÉΓòÉΓòÉ
  20.  
  21. To add direct-manipulation capability to a standard listbox (or an MCLB), the 
  22. listbox or MCLB should be created in the usual way.  After the listbox control 
  23. is created, the DMLBInitialize function is called to establish the DMLB 
  24. subclass. 
  25.  
  26. The application must define the following resources in its .RC file: 
  27.  
  28. #include "dmlb.h"
  29. POINTER ID_DMLB_DRAGMOVE "lbdrag.ptr"
  30. POINTER ID_DMLB_DRAGCOPY "lbdragcp.ptr"
  31. POINTER ID_DMLB_DRAGNONE "nodrag.ptr"
  32. POINTER ID_DMLB_DRGNORTH "drgnorth.ptr"
  33. POINTER ID_DMLB_DRGSOUTH "drgsouth.ptr"
  34. POINTER ID_DMLB_DRGDEL   "drgdel.ptr"
  35.  
  36. If these resources reside an a DLL, the DLL module handle must be supplied on 
  37. the DMLBInitialize call. 
  38.  
  39. Once the DMLB subclass is established, the application must, at a minimum, 
  40. respond to the LN_DMLB_QRYDROP message.  It may choose to also process other 
  41. DMLB notification messages. 
  42.  
  43.  
  44. ΓòÉΓòÉΓòÉ 3. WM_CONTROL Message Reference ΓòÉΓòÉΓòÉ
  45.  
  46. This section describes all the WM_CONTROL messages generated by a DMLB 
  47. subclassed control and sent to the control owner.  Note that all of the 
  48. standard LN_* messages are generated from the listbox as usual. 
  49.  
  50.  
  51. ΓòÉΓòÉΓòÉ 3.1. LN_DMLB_CONTEXT ΓòÉΓòÉΓòÉ
  52.  
  53. This WM_CONTROL notification is sent by the DMLB to its owner when the user has 
  54. requested a context menu on the listbox. 
  55.  
  56. Param1 
  57.  
  58.    DMLBID (USHORT) 
  59.              ID of the DMLB listbox 
  60.  
  61.    NotifyCode (USHORT) 
  62.              LN_DMLB_CONTEXT 
  63.  
  64. Param2 
  65.  
  66.    Index (SHORT) 
  67.              Index of the item for which the context menu was requested.  This 
  68.              value will be LIT_NONE if the pointer was not over an item when 
  69.              the menu was requested. 
  70.  
  71. Returns
  72. Nothing 
  73.  
  74.  
  75. Remarks 
  76. The owner can respond by poping up a context menu at the current pointer 
  77. coordinates or it can ignore this message if context menus are not supported. 
  78.  
  79.  
  80. Example 
  81.  
  82. case WM_INITDLG: // or WM_CREATE
  83.   ContextHwnd = WinLoadMenu(...);
  84.   ...
  85.  
  86. case WM_CONTROL:
  87.   switch SHORT1FROMMP(mp1) {
  88.     case ID_LISTBOX:
  89.       switch (SHORT2FROMMP(mp1)) {
  90.  
  91.         case LN_DMLB_CONTEXT: {
  92.           /* The user has requested a context menu.  Short 1 of mp2 is the */
  93.           /* index of the listbox item under the pointer.                  */
  94.           POINTL Point;
  95.           SHORT  ContextIndex;
  96.  
  97.           ContextIndx = SHORT1FROMMP(mp2);
  98.  
  99.           /* Popup the context menu at the pointer position. */
  100.           WinQueryMsgPos((HAB)0, &Point);
  101.           WinPopupMenu(HWND_DESKTOP, hwnd, ContextHwnd, Point.x, Point.y,
  102.                                           0, PU_HCONSTRAIN| PU_VCONSTRAIN
  103.                       PU_MOUSEBUTTON1 | PU_MOUSEBUTTON2 | PU_MOUSEBUTTON3
  104.                                                         | PU_KEYBOARD );
  105.           return (MRESULT)TRUE;
  106.           }
  107.       }
  108.       break;
  109.   }
  110.   break; /* End of WM_CONTROL */
  111.  
  112.  
  113. ΓòÉΓòÉΓòÉ 3.2. LN_DMLB_DELETE ΓòÉΓòÉΓòÉ
  114.  
  115. This WM_CONTROL notification is sent to the owner of the source listbox when a 
  116. listbox item is about to be deleted as a result of a drag/drop operation. 
  117.  
  118. Param1 
  119.  
  120.    DMLBID (USHORT) 
  121.              ID of the DMLB listbox 
  122.  
  123.    NotifyCode (USHORT) 
  124.              LN_DMLB_DELETE 
  125.  
  126. Param2 
  127.  
  128.    Target (HWND) 
  129.              The window handle of the target listbox on which the drop has 
  130.              occured. 
  131.  
  132. Returns
  133. Nothing 
  134.  
  135.  
  136. Remarks 
  137. This message occures when a listbox item is dropped on a listbox which returned 
  138. DROPMODE_DELETE in response to a LN_DMLB_QRYDROP message.  The listbox on which 
  139. the drop occured is given in mp2. The item to be deleted is the currently 
  140. selected item of the listbox. 
  141.  
  142. Note that this message does not occure when an item is moved from one listbox 
  143. to another.  It occures only if the item is to be deleted. 
  144.  
  145. This message is sent before the item is deleted giving the owner a chance to 
  146. free any dynamic resources that may be associated with this item. 
  147.  
  148.  
  149. ΓòÉΓòÉΓòÉ 3.3. LN_DMLB_DELETE_MOVE ΓòÉΓòÉΓòÉ
  150.  
  151. This WM_CONTROL notification is sent to the owner of the source listbox when a 
  152. listbox item is about to be moved to another listbox as a result of a drag/drop 
  153. operation. 
  154.  
  155. Param1 
  156.  
  157.    DMLBID (USHORT) 
  158.              ID of the DMLB listbox 
  159.  
  160.    NotifyCode (USHORT) 
  161.              LN_DMLB_DELETE_MOVE 
  162.  
  163. Param2 
  164.  
  165.    Target (HWND) 
  166.              The window handle of the target listbox on which the drop has 
  167.              occured. 
  168.  
  169. Returns
  170. Nothing 
  171.  
  172.  
  173. Remarks 
  174. This message occures when a listbox item is dropped on a listbox which returned 
  175. DROPMODE_MOVE in response to a LN_DMLB_QRYDROP message.  The listbox on which 
  176. the drop occured is given in mp2. The item to be moved is the currently 
  177. selected item of the listbox. 
  178.  
  179. Note that this message does not occure when an item is moved within the same 
  180. listbox (see LN_DMLB_REORDERED).  It occures only if the item is moved from 
  181. this (source) listbox to another (target) listbox.  When an item is moved from 
  182. one listbox to another, the item text and handle are both copied to the target 
  183. listbox and then the item is deleted from the source listbox. 
  184.  
  185. This message is sent before the item is deleted from the source listbox. 
  186.  
  187.  
  188. ΓòÉΓòÉΓòÉ 3.4. LN_DMLB_REORDERED ΓòÉΓòÉΓòÉ
  189.  
  190. This WM_CONTROL notification is sent by the DMLB to its owner when a listbox 
  191. item is moved within the same listbox (the listbox items are reordered). 
  192.  
  193. Param1 
  194.  
  195.    DMLBID (USHORT) 
  196.              ID of the DMLB listbox 
  197.  
  198.    NotifyCode (USHORT) 
  199.              LN_DMLB_REORDERED 
  200.  
  201. Param2 
  202.  
  203.    Target (HWND) 
  204.              The window handle of listbox 
  205.  
  206. Returns
  207. Nothing 
  208.  
  209.  
  210. Remarks 
  211. This message occures when a listbox item is dragged and dropped on the same 
  212. listbox.  The moved item is the currently selected item. 
  213.  
  214. When an item is moved the item text and item handle are copied, the item is 
  215. deleted, and then the item is reinserted at a new position. 
  216.  
  217.  
  218. ΓòÉΓòÉΓòÉ 3.5. LN_DMLB_INSERT_MOVE ΓòÉΓòÉΓòÉ
  219.  
  220. This WM_CONTROL notification is sent to the owner of the target listbox when a 
  221. listbox item inserted by being moved from another listbox. 
  222.  
  223. Param1 
  224.  
  225.    DMLBID (USHORT) 
  226.              ID of the DMLB listbox 
  227.  
  228.    NotifyCode (USHORT) 
  229.              LN_DMLB_INSERT_MOVE 
  230.  
  231. Param2 
  232.  
  233.    Target (HWND) 
  234.              The window handle of the source listbox 
  235.  
  236. Returns
  237. Nothing 
  238.  
  239.  
  240. Remarks 
  241. This message occures when a listbox item is dragged from another listbox and 
  242. dropped on this listbox.  This listbox must responded with DROPMODE_MOVE to 
  243. LN_DMLB_QRYDROP to receive this message. 
  244.  
  245. This message is sent after the insert has been completed.  The inserted item is 
  246. the currently selected item.  This message occures before the item is deleted 
  247. from the source listbox. Both the item text and item handle are copied from the 
  248. source listbox. 
  249.  
  250.  
  251. ΓòÉΓòÉΓòÉ 3.6. LN_DMLB_INSERT_COPY ΓòÉΓòÉΓòÉ
  252.  
  253. This WM_CONTROL notification is sent to the owner of the target listbox when a 
  254. listbox item inserted by being copied from another listbox. 
  255.  
  256. Param1 
  257.  
  258.    DMLBID (USHORT) 
  259.              ID of the DMLB listbox 
  260.  
  261.    NotifyCode (USHORT) 
  262.              LN_DMLB_INSERT_COPY 
  263.  
  264. Param2 
  265.  
  266.    Target (HWND) 
  267.              The window handle of the source listbox 
  268.  
  269. Returns
  270. Nothing 
  271.  
  272.  
  273. Remarks 
  274. This message occures when a listbox item is dragged from another listbox and 
  275. dropped on this listbox.  This listbox must responded with DROPMODE_COPY to 
  276. LN_DMLB_QRYDROP to receive this message. 
  277.  
  278. This message is sent after the insert has been completed.  The inserted item is 
  279. the currently selected item. Both the item text and item handle are copied from 
  280. the source listbox.  The source listbox item is not deleted. 
  281.  
  282.  
  283. ΓòÉΓòÉΓòÉ 3.7. LN_DMLB_QRYDROP ΓòÉΓòÉΓòÉ
  284.  
  285. This WM_CONTROL notification is sent to the owner of the target listbox when a 
  286. listbox item is dragged over it. 
  287.  
  288. Param1 
  289.  
  290.    DMLBID (USHORT) 
  291.              ID of the DMLB listbox 
  292.  
  293.    NotifyCode (USHORT) 
  294.              LN_DMLB_QRYDROP 
  295.  
  296. Param2 
  297.  
  298.    Target (HWND) 
  299.              The window handle of the source listbox 
  300.  
  301. Returns
  302.  
  303.    DropAllowed (BOOL) 
  304.              If FALSE is returned then no drop is allowed and the pointer will 
  305.              be set to the "no drop" shape.  If TRUE is returned then a drop is 
  306.              allowed and the pointer shape is set according to the DropType 
  307.              value. 
  308.  
  309.    DropType (SHORT) 
  310.              If DropAllowed is FALSE then this value is ignored.  Otherwise 
  311.              this value indicates what action will be taken if the user 
  312.              completes the drop on this listbox.  The possible values are: 
  313.  
  314.       o DROPMODE_MOVE The item will be inserted into the current listbox and 
  315.         deleted from the source listbox.  If the source and target listboxs are 
  316.         same a LN_DMLB_REORDERED notification message will be sent.  If they 
  317.         are different listboxes, LN_DMLB_INSERT_MOVE will be sent to the target 
  318.         and LN_DMLB_DELETE_MOVE will be sent to the source. 
  319.  
  320.       o DROPMODE_MOVE The item will be inserted into the current listbox.  It 
  321.         will not be deleted from the source listbox.  If the source and target 
  322.         listboxs are same the item will be duplicated in the listbox. A 
  323.         LN_DMLB_INSERT_COPY notification message is sent to the target listbox. 
  324.         No notification is sent to the source. 
  325.  
  326.       o DROPMODE_DELETE The item will be deleted from the source listbox.  It 
  327.         will not be inserted in the target listbox.  The source listbox will 
  328.         receive a LN_DMLB_DELETE notification message. 
  329.  
  330.  
  331. Remarks 
  332. This message is sent to the target listbox while a drag is in progress over the 
  333. listbox.  The application must respond by indicating if a drop is allowed or 
  334. not, and if so, what type of drop should occure (copy, move, or delete).  The 
  335. pointer shape will be changed to reflect the result of this message and if 
  336. NoDrop is TRUE, no drop will be allowed. 
  337.  
  338. Note that this message does occure when a listbox item is dragged on its own 
  339. listbox. 
  340.  
  341.  
  342. Example 
  343.  
  344.   case WM_CONTROL:
  345.     switch SHORT1FROMMP(mp1) {
  346.       case ID_LISTBOX:
  347.         switch (SHORT2FROMMP(mp1)) {
  348.  
  349.           case LN_DMLB_QRYDROP:
  350.             // If dropping in same listbox, move the item.  If drop is
  351.             // from some other listbox, refuse it.
  352.  
  353.             if (HWNDFROMMP(mp2) == WinWindowFromID(hwnd, ID_LISTBOX))
  354.               return MRFROM2SHORT(TRUE, DROPMODE_MOVE);
  355.  
  356.             return MRFROM2SHORT(FALSE, 0);
  357.  
  358.             ...
  359.  
  360.  
  361. ΓòÉΓòÉΓòÉ 4. DMLB Resources ΓòÉΓòÉΓòÉ
  362.  
  363. The DMLB subclass requires access to several POINTER type resources to use 
  364. during drag/drop operations.  The application must have the following 
  365. statements in its resource (.RC) file: 
  366.  
  367.   #include "dmlb.h"
  368.   POINTER ID_DMLB_DRAGMOVE "lbdrag.ptr"
  369.   POINTER ID_DMLB_DRAGCOPY "lbdragcp.ptr"
  370.   POINTER ID_DMLB_DRAGNONE "nodrag.ptr"
  371.   POINTER ID_DMLB_DRGNORTH "drgnorth.ptr"
  372.   POINTER ID_DMLB_DRGSOUTH "drgsouth.ptr"
  373.   POINTER ID_DMLB_DRGDEL   "drgdel.ptr"
  374.  
  375. As supplied in the toolkit, these resources use POINTER IDs 9000 through 9005. 
  376. Application defined POINTER resources must not conflict with these ID values. 
  377.  
  378. If these resources are defined in a DLL then the DLL module handle must be 
  379. supplied on the DMLBInitialize call. 
  380.  
  381.  
  382. ΓòÉΓòÉΓòÉ 5. DMLBInitialize ΓòÉΓòÉΓòÉ
  383.  
  384. This function establishes a DMLB subclass on a standard PM listbox control. 
  385.  
  386. Syntax: 
  387.  
  388. BOOL DMLBInitialize(LBHwnd, ResHMod)
  389.  
  390. ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  391. ΓöéName           ΓöéType      ΓöéIn/Out    ΓöéDescription                                       Γöé
  392. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  393. ΓöéLBHwnd         ΓöéHWND      Γöéinput     ΓöéHandle of the listbox to be subclassed.           Γöé
  394. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  395. ΓöéResHMod        ΓöéHMODULE   Γöéinput     ΓöéHandle of the module (DLL) the DMLB Resources are Γöé
  396. Γöé               Γöé          Γöé          Γöéto be retrieved from.  This may be NULLHANDLE if  Γöé
  397. Γöé               Γöé          Γöé          Γöéthe sources are bound to the EXE.                 Γöé
  398. ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  399. Returns 
  400.  
  401. ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  402. ΓöéSucess         ΓöéBOOL      Γöéreturn    ΓöéTRUE if initialization sucessful, FALSE if it     Γöé
  403. Γöé               Γöé          Γöé          Γöéfailed.                                           Γöé
  404. ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  405.  
  406.  
  407. Remarks 
  408. This function is called to setup a DMLB subclassing of a standard PM listbox 
  409. control.  Note that the QWL_USER window words of the listbox window will be 
  410. used by the subclass for a pointer to the subclass instance data. After this 
  411. function sucessfully completes, the application may use the first PVOID of the 
  412. DMLB instance data. 
  413.  
  414. The application must have the DMLB Resources (pointers) available in a resource 
  415. DLL or bound to the executable module.  If the resources reside in a DLL the 
  416. DLL module handle must be supplied on this call.