home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional Developers Kit 1992 November / Disc01 / Disc01.mdf / cppbeta / ibmcli / ilistbox.hp_ / ILISTBOX.HPP
Encoding:
C/C++ Source or Header  |  1992-10-26  |  20.0 KB  |  428 lines
  1. #ifndef _ILISTBOX_
  2.   #define _ILISTBOX_
  3. /*******************************************************************************
  4. * FILE NAME: ilistbox.hpp                                                      *
  5. *                                                                              *
  6. * DESCRIPTION:                                                                 *
  7. *   Declaration of the class(es):                                              *
  8. *     Ilistbox - This class creates and manages the listbox control window.    *
  9. *                                                                              *
  10. * COPYRIGHT:                                                                   *
  11. *   Licensed Materials - Property of IBM                                       *
  12. *   (C) Copyright IBM Corporation 1992, 1993                                   *
  13. *   All Rights Reserved                                                        *
  14. *   US Government Users Restricted Rights - Use, duplication, or disclosure    *
  15. *   restricted by GSA ADP Schedule Contract with IBM Corp.                     *
  16. *                                                                              *
  17. * $Log:   R:/IBMCLASS/IBASECTL/VCS/ILISTBOX.HPV  $
  18. //
  19. //   Rev 1.4   25 Oct 1992 17:05:32   nunn
  20. //changed library name to ICLUI
  21. //
  22. //   Rev 1.3   25 Oct 1992 10:55:02   boezeman
  23. //Add documentation and converted file to skeleton.hpp format.
  24.  
  25.       Rev 1.6   15 Oct 1992 21:17:36   Ph Gregoire
  26.    Added BBXX-like nested cursors
  27.  
  28.       Rev 1.6   16 Sep 1992 21:17:36   Jeff Shusterman
  29.    Code for IBM C++ - OS2 2.0
  30.  
  31.       Rev 1.4   23 Jan 1992 20:55:52   Jeff Shusterman
  32.    Up to IBM Class V2.0 Level
  33.  
  34.       Rev 1.3   01 Nov 1991 19:02:08   Jeff Shusterman
  35.    Refined & enhanced.
  36.  
  37.       Rev 1.2   22 Apr 1991 19:02:08   David Nguyen
  38.    Refined; added methods
  39.  
  40.       Rev 1.1   28 Oct 1989 19:02:08   Larry Morley
  41.    Initial
  42. *******************************************************************************/
  43. #ifndef _ICONTROL_
  44.   #include "icontrol.hpp"
  45. #endif
  46. // Forward declarations for other classes:
  47. class IListBox;
  48. class IString;
  49. class IRectangle;
  50. class IResourceMgr;
  51. class IWindowHandle;
  52. typedef long itemInfo;
  53. static const itemInfo FIRSTITEM = -1;
  54. static const itemInfo NOITEMS   = -1;
  55.  
  56. class IListBox : public virtual IControl {
  57. /*******************************************************************************
  58. * This class creates and manages the listbox control window.                   *
  59. *                                                                              *
  60. * A ListBox operates as if it is a zero based arrays of items.  In the         *
  61. * following methods, the item index requested or returned is the zero          *
  62. * based index number of the location of the item in question.                  *
  63. * A ListBox can have one or more of the following styles:                      *
  64. * LS_HORZSCROLL   allows horizontall scroll of the ListBox.                    *
  65. * LS_MULTIPLESEL  allows more than one item to be selected. A ListBox without  *
  66. *                 this style allows only single selection.                     *
  67. * LS_OWNERDRAW    allows ListBox items to be drawn. Typically used to display  *
  68. *                 bit maps. This style is used and is required to support      *
  69. *                 multiple columns on the ListBox.                             *
  70. * LS_NOADJUSTPOS  if this style is included, the ListBox control is drawn at   *
  71. *                 the size specified. This can cause parts of an item to be    *
  72. *                 shown.                                                       *
  73. *                                                                              *
  74. * EXAMPLE:                                                                     *
  75. *  #include <ilistbox.hpp>                                                     *
  76. *  lb_test = new IListBox(ID_LISTBOX, this, IRectangle(IPoint(px, py),         *
  77. *                         ISize(sx, sy)));                                     *
  78. *  lb_test->addItemAsc("This is first item");                                  *
  79. *  SelectedItem = lb_test->selection();                                        *
  80. *  This code shows creating a ListBox, adding an item to it and returning the  *
  81. *  index of the selected item.                                                 *
  82. *******************************************************************************/
  83. typedef IControl
  84.   Inherited;
  85. public:
  86. INESTEDBITFLAGCLASSDEF2(Style, IListBox, IWindow, IControl);
  87.                                   //Style class definition
  88. static const Style
  89.   horizontalscroll,
  90.   multipleselect,
  91.   extendedselect,
  92.   ownerdraw,
  93.   noadjustposition;
  94. static const Style&
  95.   defStyle;
  96. /*------------------------ CONSTRUCTORS/DESTRUCTORS ----------------------------
  97. | There are 3 ways to construct instances of this class:                       |
  98. |   1. default                                                                 |
  99. |   2. From a Dialog Template                                                  |
  100. |   3. From a Window                                                           |
  101. ------------------------------------------------------------------------------*/
  102.   IListBox(unsigned long Id,
  103.            const IWindow* pParent,
  104.            const IWindow* pOwner,
  105.            const IRectangle& initial,
  106.            Style style = defStyle);
  107.  
  108.   IListBox(unsigned long Id,
  109.          const IWindow* pParentDialog);
  110.  
  111.   IListBox(IWindowHandle handle);
  112.  
  113. virtual
  114.   ~IListBox() {;}
  115.  
  116. /*-------------------------------- STYLES --------------------------------------
  117. | These function provide means of getting and setting the default style        |
  118. | attributes of instances of this class:                                       |
  119. |   defaultStyle    - returns the listbox default style setting                |
  120. |   setDefaultStyle - sets the listbox default style                           |
  121. ------------------------------------------------------------------------------*/
  122. static Style
  123.    defaultStyle();
  124. static void
  125.    setDefaultStyle(Style style);
  126.  
  127. /*------------------------ ADD ITEM OPERATIONS ---------------------------------
  128. | Add a line of text to the listbox.                                           |
  129. | addItem        - allows the line to be inserted anyplace in the listbox      |
  130. | addItemToFront - allows the line to be inserted to the front of the listbox  |
  131. | addItemToEnd   - allows the line to be inserted to the end of the listbox    |
  132. | addItemAsc     - allows the line to be inserted in ascending sort order      |
  133. | addItemDesc    - allows the line to be inserted in descending sort order     |
  134. ------------------------------------------------------------------------------*/
  135. long
  136.   addItem(long  lIndex, const char* pszString),
  137.   addItemToFront(const char* pszString),
  138.   addItemToEnd(const char* pszString),
  139.   addItemAsc(const char*pszString),
  140.   addItemDesc(const char* pszString);
  141.  
  142. /*------------------------ GET/CHANGE ITEM OPERATIONS --------------------------
  143. | Get or change the text of an item in the listbox.  Return the length of an   |
  144. | an item in the listbox.                                                      |
  145. | itemText       - Return the text of an item in the listbox                   |
  146. | itemTextLen    - Return the length of an item in the listbox                 |
  147. | setItemText    - Change the text of an item in the listbox.                  |
  148. ------------------------------------------------------------------------------*/
  149. IString
  150.   itemText(unsigned long lIndex) const;
  151. long
  152.   itemTextLen(unsigned long lIndex) const;
  153. void
  154.   setItemText(long lIndex, const char* pszString); /* Change an item */
  155.  
  156. /*------------------------ REMOVE ITEM OPERATIONS ------------------------------
  157. | Remove all or one item from the listbox.                                     |
  158. | removeAll      - Remove all items from the listbox.                          |
  159. | removeItem     - Remove one item from the listbox and return the count of    |
  160. |                  the number of items that remain.                            |
  161. ------------------------------------------------------------------------------*/
  162. void
  163.   removeAll();
  164. long
  165.   removeItem(long lIndex );
  166.  
  167. /*------------------------ SELECTION STATE OPERATIONS --------------------------
  168. | Set or return the selection state operations.                                |
  169. | selectItem     - Sets the selection state of an item.                        |
  170. | deselectItem   - Removes the selection state from an item.                   |
  171. | isSelected     - Returns the selection state of an item.                     |
  172. | selectAll      - Sets the selection state for all items in the listbox.      |
  173. | deselectAll    - Removes the selection state from all items in the listbox.  |
  174. | resetSelection - Sets the "current" selection to LIT_FIRST.  This can be     |
  175. |                  used for looping through the set of selected items, starting|
  176. |                  with the first selection.  A better way to loop through the |
  177. |                  selections is to use the IListBoxCursor.                    |
  178. | selection      - Returns the item number of the next selection after the     |
  179. |                  requested item number. LIT_FIRST starts the search with the |
  180. |                  first item. If the rest of the list has no selection,       |
  181. |                  LIT_NONE is returned. The result of the search is also set  |
  182. |                  as the "current" selection.                                 |
  183. | firstSelection - Reset "current" selection with their result.                |
  184. | nextSelection  - Reset "current" selection with their result.                |
  185. | prevSelection  - Use "current" selection as the starting point and also      |
  186. |                  reset "current" selection with their result.                |
  187. | lastSelection  - Use "current" selection as the starting point and also      |
  188. |                  reset "current" selection with their result.                |
  189. | selectionCount - Returns the number of selected items and does not change    |
  190. |                  "current" selection                                         |
  191. ------------------------------------------------------------------------------*/
  192. void
  193.   selectItem(long lIndex ),
  194.   deselectItem(long lIndex ),
  195.   selectAll(),
  196.   deselectAll();
  197. void
  198.   resetSelection() {lClSelection = FIRSTITEM;}   /* For looping */
  199. Boolean
  200.   isSelected(long lIndex );  /* Returns true if selected */
  201. long
  202.   selection(long lAfterItem = FIRSTITEM),
  203.   firstSelection(),
  204.   nextSelection(),
  205.   prevSelection(),
  206.   lastSelection(),
  207.   selectionCount();  /* Does not affect lClSelection */
  208.  
  209. /*------------------------ SCROLLING OPERATIONS --------------------------------
  210. | Scrolls an item to the top of the listbox or returns the item at the top of  |
  211. | the listbox.                                                                 |
  212. | setTopItem     - Scrolls the requested item to the top of the listbox.       |
  213. | topItem        - Returns the item number of the item currently at the top    |
  214. |                  of the listbox or LIT_NONE if there are no items in the     |
  215. |                  listbox.                                                    |
  216. ------------------------------------------------------------------------------*/
  217. void
  218.   setTopItem(long lIndex);
  219. long
  220.   topItem() const;
  221.  
  222. /*------------------------ HANDLE OPERATIONS -----------------------------------
  223. | Set or retrieve a handle of a listbox item.                                  |
  224. | setItemHandle  - Sets a handle of a listbox item.                            |
  225. | itemHandle     - Returns a handle of a listbox item.  An item without a      |
  226. |                  handle returns 0.                                           |
  227. ------------------------------------------------------------------------------*/
  228. void
  229.   setItemHandle(unsigned long lIndex, unsigned long ulHandle ); /*Returns OK or warning*/
  230. unsigned long
  231.   itemHandle(unsigned long lIndex ) const;
  232.  
  233. /*------------------------ QUERY OPERATIONS ------------------------------------
  234. | findString     - Return the item number of the listbox item that matches the |
  235. |                  search string. Start the search after the index.  If no     |
  236. |                  match is found the method returns LIT_NONE.                 |
  237. ------------------------------------------------------------------------------*/
  238. long    findString(const char* pszSearchString,
  239.                    Boolean caseSensitive = true, /*unsigned long ulFindOptions = LSS_CASESENSITIVE | LSS_SUBSTRING,*/
  240.                    Boolean checkSubstring = true,
  241.                    long  lIndex = FIRSTITEM) const;
  242.  
  243. /*------------------------ MISCELLANEOUS OPERATIONS ----------------------------
  244. | itemCount      - Return the count of the number of items in the listbox.     |
  245. | setItemHeight  - Set the height of a listbox item.  This does not change the |
  246. |                  font size, it changes the cell within which an item is displayed|
  247. ------------------------------------------------------------------------------*/
  248. long
  249.   itemCount() const;
  250. void
  251.   setItemHeight(long lNewHeight);
  252. //void    setForegdColor(COLOR clrForegdColor);
  253. //void    setBackgdColor(COLOR clrBackgdColor);
  254. //COLOR   color( HPS hpsItem, unsigned long ulAttrType1,
  255. //               unsigned long ulAttrType2, COLOR clrDefault );
  256. /*------------------------ STYLES ----------------------------------------------
  257. | isHorizontalscroll   - Returns true if the horizontal scroll style is set.   |
  258. | isMultipleselect     - Returns true if the mulipleselect style is set.       |
  259. | isExtendedselect     - Returns true if the extendedselect style is set.      |
  260. | isOwnerdraw          - Returns true if the ownerdraw style is set.           |
  261. | isNoadjustposition   - Returns true if the noadjustposition style is set.    |
  262. | setHorizontalscroll  - enables or disable the horizontal scroll style for    |
  263. |                        the listbox                                           |
  264. | setMultipleselect    - enables or disable the multipleselect style for       |
  265. |                        the listbox                                           |
  266. | setExtendedselect    - enables or disable the extended select style for      |
  267. |                        the listbox                                           |
  268. | setOwnerdraw         - enables or disable the ownerdraw style for            |
  269. |                        the listbox                                           |
  270. | setNoadjustposition  - enables or disable the noadjustposition style for     |
  271. |                        the listbox                                           |
  272. ------------------------------------------------------------------------------*/
  273. Boolean isHorizontalscroll(),
  274.   isMultipleselect(),
  275.   isExtendedselect(),
  276.   isOwnerdraw(),
  277.   isNoadjustposition();
  278. void
  279.   setHorizontalscroll(Boolean setTheStyle = true),
  280.   setMultipleselect(Boolean setTheStyle = true),
  281.   setExtendedselect(Boolean setTheStyle = true),
  282.   setOwnerdraw(Boolean setTheStyle = true),
  283.   setNoadjustposition(Boolean setTheStyle = true);
  284.  
  285. /*------------------------- CURSOR SUPPORT -----------------------
  286. | - Nested cursor class                                          |
  287. | - Functions to retrieve/set add/remove elements at cursor      |
  288. ----------------------------------------------------------------*/
  289. class Cursor {
  290.   enum CursorType { selectedItems, allItems };
  291.   public :
  292.   Cursor(const IListBox& rlb,
  293.          CursorType type = selectedItems);
  294.  
  295.   /*------------------------ CURSOR MOVEMENT ------------------------
  296.   | setToFirst - point to first object item of LB                   |
  297.   | setToNext  - point to next item or invalidates if none          |
  298.   | setToPrevious - point to previous item of LB or invalid if none |
  299.   | setToLast  - point to last object of LB                         |
  300.   | setToIndex - point to item with given 0-based index             |
  301.   -----------------------------------------------------------------*/
  302.   Boolean
  303.     setToFirst(),
  304.     setToNext(),
  305.     setToPrevious(),
  306.     setToLast(),
  307.     setToIndex(long lIndex);
  308.  
  309.   /*--------------- CURSOR VALIDATION / CONVERSION -----------------+
  310.   | isValid - does this cursor point to a valid item?               |
  311.   | invalidate - flag this cursor as invalid                        |
  312.   | asIndex - returns the index of the item pointed to by cursor    |
  313.   +----------------------------------------------------------------*/
  314.   Boolean
  315.     isValid() const;
  316.   void
  317.     invalidate();
  318.   long
  319.     asIndex() const;
  320.  
  321.   private :
  322.   const IListBox&
  323.     rlbCl;
  324.   long
  325.     lClCurrent;
  326.   CursorType
  327.     cursorTypeCl;
  328. };
  329. /*------------------------ CURSOR OPERATIONS ---------------------+
  330. | Operations on listbox items using cursor                        |
  331. | elementAt     - Returns the item's string at cursor             |
  332. | removeAt      - Remove item at cursor                           |
  333. | replaceAt     - Replace item's string at cursor                 |
  334. | add           - add item at cursor (push evrything after cursor)|
  335. | addAsFirst    - add item as first and set cursor to first       |
  336. | addAsLast     - add item as last and set cursor there           |
  337. | addAsNext     - add item as next and set cursor there           |
  338. +----------------------------------------------------------------*/
  339. IString
  340.   elementAt(const Cursor& cursor);
  341. void
  342.   removeAt(const Cursor& cursor),
  343.   replaceAt(const Cursor& cursor, const IString& strNew);
  344. Boolean
  345.   add(const IString& strItem, Cursor& cursor);
  346. void
  347.   addAsFirst(const IString& strItem, Cursor& cursor),
  348.   addAsLast(const IString& strItem, Cursor& cursor),
  349.   addAsNext(const IString& strItem, Cursor& cursor);
  350.  
  351. /*----------------------- ISET OPERATIONS ------------------------+
  352. | Operations on listbox with same terminology as BBXX ISet        |
  353. |   isEmpty - returns true if the LB is empty                     |
  354. |   numberOfElements - returns the count of elements in the LB    |
  355. +----------------------------------------------------------------*/
  356. Boolean
  357.   isEmpty() const;
  358. unsigned long
  359.   numberOfElements() const;
  360.  
  361. protected:
  362. /*----------------------------- LAYOUT SIZE ------------------------------------
  363. | This operation returns the minimum size for the listbox control.             |
  364. |   calcMinSize - returns the minimum size that this listbox should be.        |
  365. ------------------------------------------------------------------------------*/
  366. virtual ISize
  367.   calcMinSize() {return (ISize)(0,0);/**???????????????**/}
  368.  
  369. static  Style
  370.   classDefaultStyle;
  371.  
  372. /*???? To be implemented in IWindow ?????*/
  373. unsigned long
  374.   style() const;
  375. void
  376.   setStyle(unsigned long style);
  377.  
  378. /* "Current" Location - Used & set by next/prevSelection(); set by selection,first&last */
  379. long
  380.   lClSelection;
  381.  
  382. //     /******************************************************************************/
  383. //     /*   Protected Constructor              - used by IListBoxMultiCol            */
  384. //     /******************************************************************************/
  385. //     IListBox(Boolean protectSwitch,
  386. //              unsigned long Id,
  387. //              const IWindow* pParent,
  388. //              const IWindow* pOwner,
  389. //              const IRectangle& intial,
  390. //              Style style = defStyle);
  391.  
  392. /*------------------------------------------------------------------------------
  393. |   Protected Constructors             - used by IComboBox                     |
  394. ------------------------------------------------------------------------------*/
  395.   IListBox();
  396. };   //ILISTBOX
  397. enum CursorType{selectedItems, allItems};
  398.  
  399. class IListBoxCursor {
  400.   public :
  401.     IListBoxCursor (IListBox* plb,
  402.                     CursorType type = selectedItems);
  403.   long
  404.     current(),
  405.     first(),
  406.     last(),
  407.     next(),
  408.     prior(),
  409.     after(long lAfterItem);
  410.   void
  411.     reset();
  412.  
  413.   private :
  414.   IListBox*
  415.     plbCl;
  416.   long
  417.     lClCurrent;
  418.   CursorType
  419.     cursorTypeCl;
  420. };
  421.  
  422. //Global Style Functions
  423. INESTEDBITFLAGCLASSFUNCS(Style, IListBox);
  424.  
  425.  
  426.                                   // global style functions
  427. #endif  /* _ILISTBOX_ */
  428.