home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / cset21v1.zip / IBMCPP / IBMCLASS / ILISTBOX.HPP < prev    next >
C/C++ Source or Header  |  1993-10-22  |  26KB  |  483 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. *******************************************************************************/
  18. #ifndef _ICONTROL_
  19.   #include <icontrol.hpp>
  20. #endif
  21. // Forward declarations for other classes:
  22. class IString;
  23. class IResourceId;
  24. #ifndef _IRECT_
  25.   #include <irect.hpp>
  26. #endif
  27.  
  28. /*----------------------------------------------------------------------------*/
  29. /* Align classes on four byte boundary.                                       */
  30. /*----------------------------------------------------------------------------*/
  31. #pragma pack(4)
  32.  
  33. /*----------------------------------------------------------------------------*/
  34. /* Turn off warning for compiler generated copy/assignment                    */
  35. /*----------------------------------------------------------------------------*/
  36. #pragma info(nocpy)
  37.  
  38. class IListBox : public IControl  {
  39. typedef IControl Inherited;
  40. /*******************************************************************************
  41. * The IListBox class creates and manages the list box control window.  A list  *
  42. * box operates as if it is a 0-based array of items.  The item index           *
  43. * requested or returned is the 0-based index number of the location of the     *
  44. * item in question.                                                            *
  45. *                                                                              *
  46. * EXAMPLE:                                                                     *
  47. *  #include <ilistbox.hpp>                                                     *
  48. *  lb_test = new IListBox(ID_LISTBOX, this, this, IRectangle(x1, y1, x2, y2)); *
  49. *  lb_test->addItemAscending("This is first item");                            *
  50. *  SelectedItem = lb_test->selection();                                        *
  51. *******************************************************************************/
  52. public:
  53. /*---------------------- Style --------------------------------------------
  54.   The following functions provide a means to set and query list box styles:
  55.  
  56.     Style - Nested class that provides static members that define the set of
  57.             valid list box styles.  These styles can be used in conjunction
  58.             with the styles defined by the nested classes IWindow::Style and
  59.             IControl::Style.  For example, you could define an instance of
  60.             the IListBox::Style class and initialize it like:
  61.               IListBox::Style
  62.                 style = IListBox::horizontalScroll | IControl::tabStop;
  63.             An object of this type is provided when the list box is created.
  64.             A customizable default is used if no styles are specified.  Once
  65.             the object is constructed, IListBox, IWindow, and IControl
  66.             member functions can be used to set or query the object's style.
  67.  
  68.             The declaration of the IListBox::Style nested class is generated
  69.             by the INESTEDBITFLAGCLASSDEF2 macro.
  70.  
  71.   The valid list box styles are:
  72.     classDefaultStyle - This specifies the original default style for this
  73.                         class, which is horizontalScroll | noAdjustPosition |
  74.                         IWindow::visible.
  75.     horizontalScroll  - This style allows horizontal scrolling of the list
  76.                         box.
  77.     multipleSelect    - This style specifies that the user can select any
  78.                         number of objects at a time in the list box, or not
  79.                         select any.
  80.     extendedSelect    - This style is a type of selection optimized for the
  81.                         selection of a single object.  A user can extend
  82.                         selection to more than one object, if required.
  83.     drawItem          - This style allows list box items to be drawn.  It is
  84.                         typically used to display bit maps.
  85.     noAdjustPosition  - If this style is included, the list box control is
  86.                         drawn at the size specified. This can cause an item
  87.                         to be only partially shown.
  88.  
  89.   The following functions provide a means of getting and setting the default
  90.   style for this class:
  91.     defaultStyle    - Returns the current default style.  This is the same as
  92.                       classDefaultStyle unless setDefaultStyle has been
  93.                       called.
  94.     setDefaultStyle - Sets the default style for all subsequent list boxes.
  95. -------------------------------------------------------------------------*/
  96. INESTEDBITFLAGCLASSDEF2(Style, IListBox, IWindow, IControl);
  97.  
  98. static const Style
  99.   classDefaultStyle,
  100.   horizontalScroll,
  101.   multipleSelect,
  102.   extendedSelect,
  103.   drawItem,
  104.   noAdjustPosition;
  105.  
  106. static Style
  107.    defaultStyle();
  108. static void
  109.    setDefaultStyle(Style style);
  110.  
  111. /*------------------------ Constructors ----------------------------------------
  112. | You can construct an instance of this class in the following ways:           |
  113. |    - From a control ID, parent and owner windows, rectangle, and style.      |
  114. |      This creates the specified list box control and an object for it.       |
  115. |    - From the ID of a list box control on a dialog window.  This creates     |
  116. |      the object for the specified list box control.                          |
  117. |    - From the window handle of an existing list box control.  This creates   |
  118. |      the object for the specified list box control.                          |
  119. ------------------------------------------------------------------------------*/
  120.   IListBox(unsigned long id,
  121.            IWindow* parent,
  122.            IWindow* owner,
  123.            const IRectangle& initial= IRectangle(),
  124.            const Style& style = defaultStyle() );
  125.  
  126.   IListBox(unsigned long id,
  127.            IWindow* parent);
  128.  
  129.   IListBox(const IWindowHandle& handle);
  130.  
  131.   virtual ~IListBox();
  132.  
  133. /*------------------------ Add Item Operations ---------------------------------
  134. | Add a line of text to the list box.                                          |
  135. |   add          - Allows the line to be inserted any place in the list box.   |
  136. |   addAsFirst   - Allows the line to be inserted at the top of the list box.  |
  137. |   addAsLast    - Allows the line to be inserted to the bottom of the list    |
  138. |                  box.                                                        |
  139. |   addAscending - Allows the line to be inserted in ascending sort order.     |
  140. |   addDescending- Allows the line to be inserted in descending sort order.    |
  141. ------------------------------------------------------------------------------*/
  142. unsigned long
  143.   add(unsigned long  index, const char* text),
  144.   addAsFirst(const char* text),
  145.   addAsLast(const char* text),
  146.   addAscending(const char* text),
  147.   addDescending(const char* text),
  148.   add(unsigned long  index, const IResourceId& resid),
  149.   addAsFirst(const IResourceId& resid),
  150.   addAsLast(const IResourceId& resid),
  151.   addAscending(const IResourceId& resid),
  152.   addDescending(const IResourceId& resid);
  153.  
  154. /*------------------------ Get/Change Item Operations --------------------------
  155. | Get or change the text of an item in the list box.                           |
  156. |   itemText    - Returns the text of an item in the list box                  |
  157. |   setItemText - Changes the text of an item in the list box.                 |
  158. ------------------------------------------------------------------------------*/
  159. IString
  160.   itemText(unsigned long index) const;
  161. IListBox&
  162.   setItemText(unsigned long index, const char* string);
  163.  
  164. /*------------------------ Remove Item Operations ------------------------------
  165. | Remove all or one item from the list box.                                    |
  166. |   removeAll - Removes all items from the list box.                           |
  167. |   remove    - Removes one item from the list box and returns the count of    |
  168. |               the number of items that remain.                               |
  169. ------------------------------------------------------------------------------*/
  170. IListBox&
  171.   removeAll();
  172. long
  173.   remove(unsigned long index );
  174.  
  175. /*------------------------ Selection-state Operations --------------------------
  176. | Set or return the selection state operations.                                |
  177. |   select             - Sets the selection state of an item based on the      |
  178. |                        Boolean value that is passed in.  If true is passed   |
  179. |                        in and the list box is a single-selection list box,   |
  180. |                        the item is selected and any item that was            |
  181. |                        previously selected is deselected.  If true is        |
  182. |                        passed in and the list box is a multiple-selection    |
  183. |                        or extended-selection list box, the item is selected. |
  184. |                        In all cases, if false is passed in, the item is      |
  185. |                        deselected.                                           |
  186. |   deselect           - Removes the selection state from an item.             |
  187. |   selectAll          - Sets the selection state for all items in the list    |
  188. |                        box.                                                  |
  189. |   deselectAll        - Removes the selection state from all items in the     |
  190. |                        list box.                                             |
  191. |   isSelected         - Returns the selection state of an item.               |
  192. |   numberOfSelections - Returns 0 if no item in a single-selection list box   |
  193. |                        is selected or 1 if an item is selected.  Returns     |
  194. |                        the number of selected items in a multiple-selection  |
  195. |                        or extended-selection list box.  In all cases, the    |
  196. |                        current selection does not change.                    |
  197. |   selection          - Returns the 0-based index of the selected item in a   |
  198. |                        single-selection list box, or the 0-based index of    |
  199. |                        the first selected item in a multiple-selection or    |
  200. |                        extended-selection list box.  In all cases, if no     |
  201. |                        item is selected, -1 is returned.                     |
  202. ------------------------------------------------------------------------------*/
  203. IListBox
  204.   &select(unsigned long index, Boolean select = true ),
  205.   &deselect(unsigned long index ),
  206.   &selectAll(),
  207.   &deselectAll();
  208. Boolean
  209.   isSelected(unsigned long index );
  210. unsigned long
  211.   numberOfSelections() const;
  212. long
  213.   selection();
  214.  
  215. /*------------------------ Scrolling Operations --------------------------------
  216. | Scrolls an item to the top of the list box or returns the item at the top of |
  217. | the list box.                                                                |
  218. |   setTop - Scrolls the requested item to the top of the list box.            |
  219. |   top    - Returns the item number of the item currently at the top of the   |
  220. |            list box. If there are no items in the list box, an exception is  |
  221. |            thrown.                                                           |
  222. ------------------------------------------------------------------------------*/
  223. IListBox&
  224.   setTop(unsigned long index);
  225. unsigned long
  226.   top() const;
  227.  
  228. /*------------------------ Handle Operations -----------------------------------
  229. | Set or retrieve a handle of a list box item.                                 |
  230. |   setItemHandle - Sets a handle of a list box item.                          |
  231. |   itemHandle    - Returns a handle of a list box item.  An item without a    |
  232. |                   handle returns 0.                                          |
  233. ------------------------------------------------------------------------------*/
  234. IListBox&
  235.   setItemHandle(unsigned long index, unsigned long handle );
  236. unsigned long
  237.   itemHandle(unsigned long index ) const;
  238.  
  239. /*---------------------------- Enumerations ------------------------------------
  240. | The following enumerations are defined:                                      |
  241. |   SearchType - Used for determining the type of search to perform.  Values   |
  242. |               are:                                                           |
  243. |               prefix      - Matching occurs if the leading characters        |
  244. |                             of the item contain the specified characters.    |
  245. |               substring   - Matching occurs if the item contains a substring |
  246. |                             of the specified characters.                     |
  247. |               exactMatch  - Matching occurs if the item is an exact match for|
  248. |                             the specified characters.                        |
  249. ------------------------------------------------------------------------------*/
  250. enum SearchType {
  251.   prefix,
  252.   substring,
  253.   exactMatch
  254. };
  255.  
  256. /*------------------------ Query Operations ------------------------------------
  257. | locateText - Returns the item number of the list box item that matches the   |
  258. |              search string.  The search is started after the index.  If no   |
  259. |              match is found, it returns notFound.  If there is an error, an  |
  260. |              exception occurs.                                               |
  261. ------------------------------------------------------------------------------*/
  262. static const unsigned long notFound ;
  263. static const long first ;
  264. unsigned long
  265.   locateText(const char* searchString,
  266.              Boolean caseSensitive = true,
  267.              SearchType search = exactMatch,
  268.              long  index = first) const;
  269.  
  270. /*------------------------ Miscellaneous Operations ----------------------------
  271. | count     - Returns the count of the number of items in the list box.        |
  272. | setHeight - Sets the height of a list box item, in pixels.  This does not    |
  273. |             change the font size.  It changes the height of the cell within  |
  274. |             which an item is displayed.                                      |
  275. ------------------------------------------------------------------------------*/
  276. unsigned long
  277.   count() const;
  278. IListBox&
  279.   setHeight(long newHeight);
  280.  
  281. /*---------------------------- Enumerations ------------------------------------
  282. | The following enumerations are defined:                                      |
  283. |   ColorArea - Used to replace the color for a particular region.  Values     |
  284. |               are:                                                           |
  285. |               foreground          - Sets the color for the foreground text.  |
  286. |               disabledForeground  - Sets the foreground color for disabled   |
  287. |                                     text.                                    |
  288. |               highlightForeground - Sets the foreground color for            |
  289. |                                     highlighted text.                        |
  290. |               border              - Sets the color of the border that        |
  291. |                                     surrounds the list box.                  |
  292. ------------------------------------------------------------------------------*/
  293. enum ColorArea {
  294.   foreground,
  295.   disabledForeground,
  296.   highlightForeground,
  297.   border
  298. };
  299. /*----------------------------- Color Functions --------------------------------
  300. |   setColor   - Changes the color of the displayed text.                      |
  301. |   color      - Returns the color of the displayed text.                      |
  302. ------------------------------------------------------------------------------*/
  303.  
  304. IListBox
  305.   &setColor(ColorArea value, const IColor& color);
  306.  
  307. IColor
  308.   color(ColorArea value) const;
  309.  
  310. /*------------------------ Style Functions -------------------------------------
  311. | isHorizontalScroll      - Returns true if the horizontalScroll style is set. |
  312. | isMultipleSelect        - Returns true if the multipleSelect style is set.   |
  313. | isExtendedSelect        - Returns true if the extendedSelect style is set.   |
  314. | isDrawItem              - Returns true if the drawItem style is set.         |
  315. | isNoAdjustPosition      - Returns true if the noAdjustPosition style is set. |
  316. | enableMultipleSelect    - Enables or disables the multipleSelect style for   |
  317. |                           the list box.                                      |
  318. | disableMultipleSelect   - Disables the multipleSelect style for the list     |
  319. |                           box.                                               |
  320. | enableExtendedSelect    - Enables or disables the extendedSelect style for   |
  321. |                           the list box.                                      |
  322. | disableExtendedSelect   - Disables the extendedSelect style for the list     |
  323. |                           box.                                               |
  324. | enableDrawItem          - Enables or disables the drawItem style for the     |
  325. |                           list box.                                          |
  326. | disableDrawItem         - Disables the drawItem style for the list box.      |
  327. | enableNoAdjustPosition  - Enables or disables the noAdjustPosition style     |
  328. |                           for the list box.                                  |
  329. | disableNoAdjustPosition - Disables the noAdjustPosition style for the list   |
  330. |                           box.                                               |
  331. ------------------------------------------------------------------------------*/
  332. Boolean isHorizontalScroll(),
  333.   isMultipleSelect(),
  334.   isExtendedSelect(),
  335.   isDrawItem(),
  336.   isNoAdjustPosition();
  337. IListBox
  338.   &enableMultipleSelect(Boolean enable = true),
  339.   &disableMultipleSelect(),
  340.   &enableExtendedSelect(Boolean enable = true),
  341.   &disableExtendedSelect(),
  342.   &enableDrawItem(Boolean enable = true),
  343.   &disableDrawItem(),
  344.   &enableNoAdjustPosition(Boolean enable = true),
  345.   &disableNoAdjustPosition();
  346.  
  347. class Cursor : public IVBase {
  348. /*******************************************************************************
  349. * The IListBox::Cursor class creates and manages the cursor support of the     *
  350. * list box.                                                                    *
  351. *                                                                              *
  352. * EXAMPLE:                                                                     *
  353. *  #include <ilistbox.hpp>                                                     *
  354. *  lb_test = new IListBox(ID_LISTBOX, this, this, IRectangle(x1, y1, x2, y2)); *
  355. *  lb_test->addAscending("This is first item");                                *
  356. *  lb_cursor = new IListBox::Cursor(*lb_test);                                 *
  357. *  lb_cursor->setToFirst();                                                    *
  358. *  CurrentItem = lb_cursor->asIndex();                                         *
  359. *******************************************************************************/
  360.   public :
  361.   /*------------------------ Filters -------------------------------+
  362.   | The following functions allow you to specify how list box items |
  363.   | will be filtered:                                               |
  364.   |   Filter - Enumeration that defines which items are to be       |
  365.   |            filtered (selectedItems or allItems).                |
  366.   +----------------------------------------------------------------*/
  367.   enum Filter { selectedItems, allItems };
  368.   /*------------------------ Constructors ---------------------------
  369.   | You can create instances of this class from a list box control  |
  370.   | and a filter type.  This creates the specified list box cursor  |
  371.   | object.                                                         |
  372.   -----------------------------------------------------------------*/
  373.   Cursor(const IListBox& rlb,
  374.          Filter type = selectedItems);
  375.  
  376.   virtual ~Cursor();
  377.  
  378.   /*------------------------ Cursor Movement -----------------------+
  379.   | setToFirst    - Points to the list box item and validates the   |
  380.   |                 cursor.                                         |
  381.   | setToNext     - Points to the next item in the list box.  If no |
  382.   |                 more items exist, this will invalidate the      |
  383.   |                 cursor.                                         |
  384.   | setToPrevious - Points to the previous item in the list box.    |
  385.   |                 If no previous items exist, this will           |
  386.   |                 invalidate the cursor.                          |
  387.   | setToLast     - Points to the last list box item and validates  |
  388.   |                 the cursor.                                     |
  389.   | setToIndex    - Points to the item with the given 0-based index |
  390.   |                 and validates the cursor.                       |
  391.   +----------------------------------------------------------------*/
  392.   Boolean
  393.     setToFirst(),
  394.     setToNext(),
  395.     setToPrevious(),
  396.     setToLast(),
  397.     setToIndex(unsigned long index);
  398.  
  399.   /*--------------- Cursor Validation/Conversion -------------------+
  400.   | isValid    - Queries whether this cursor points to a valid      |
  401.   |              item.                                              |
  402.   | invalidate - Flags this cursor as invalid.                      |
  403.   | asIndex    - Returns the index of the item to which the cursor  |
  404.   |              is pointing.                                       |
  405.   +----------------------------------------------------------------*/
  406.   Boolean
  407.     isValid() const;
  408.   void
  409.     invalidate();
  410.   unsigned long
  411.     asIndex() const;
  412.  
  413.   private :
  414.   const IListBox&
  415.     rlbCl;
  416.   unsigned long
  417.     lClCurrent;
  418.   Filter
  419.     cursorTypeCl;
  420.   unsigned long
  421.     sameValidation;
  422. };
  423. /*------------------------ Cursor Operations ---------------------+
  424. | The following are operations on list box items using a cursor:  |
  425. |   elementAt   - Returns the item's string at the cursor.        |
  426. |   removeAt    - Removes the item at the cursor and places the   |
  427. |                 cursor at the next available valid item.        |
  428. |   replaceAt   - Replaces the item's string at the cursor.       |
  429. |   add         - Adds the item at the cursor by pushing          |
  430. |                 everything after the cursor.                    |
  431. |   addAsFirst  - Adds the item as the first item in the list box |
  432. |                 and sets the cursor on the added item.          |
  433. |   addAsLast   - Adds the item as the last item in the list box  |
  434. |                 and sets the cursor on the added item.          |
  435. |   addAsNext   - Adds the item as the next item in the list box  |
  436. |                 and sets the cursor on the added item.          |            |
  437. +----------------------------------------------------------------*/
  438. IString
  439.   elementAt(const Cursor& cursor) const;
  440. IListBox
  441.   &add(const char* strItem, Cursor& cursor),
  442.   &add(const IResourceId& resid  , Cursor& cursor),
  443.   &removeAt(Cursor& cursor),
  444.   &replaceAt(const char* strNew,const Cursor& cursor),
  445.   &addAsFirst(const char* strItem, Cursor& cursor),
  446.   &addAsLast(const char* strItem, Cursor& cursor),
  447.   &addAsNext(const char* strItem, Cursor& cursor),
  448.   &addAsFirst(const IResourceId& resid, Cursor& cursor),
  449.   &addAsLast( const IResourceId& resid, Cursor& cursor),
  450.   &addAsNext( const IResourceId& resid, Cursor& cursor),
  451.   &replaceAt( const IResourceId& resid, const Cursor& cursor);
  452.  
  453. /*----------------------- ISet Operations ------------------------+
  454. | The following operates on list boxes with the same terminology  |
  455. | as BBXX ISet:                                                   |
  456. |   isEmpty - Returns true if the list box is empty.              |
  457. +----------------------------------------------------------------*/
  458. Boolean
  459.   isEmpty() const;
  460.  
  461. protected:
  462.  
  463. private:
  464. static  Style
  465.   currentDefaultStyle;
  466. unsigned long
  467.   needValidation;
  468. friend class IListBox::Cursor;
  469.  
  470. };   //ILISTBOX
  471.  
  472.  
  473. //Global Style Functions
  474. INESTEDBITFLAGCLASSFUNCS(Style, IListBox);
  475.  
  476. /*----------------------------------------------------------------------------*/
  477. /* Resume compiler default packing and warning messages.                      */
  478. /*----------------------------------------------------------------------------*/
  479. #pragma pack()
  480. #pragma info(restore)
  481.  
  482. #endif  /* _ILISTBOX_ */
  483.