include/pwlib/listbox.h

   1 /*
   2  * listbox.h
   3  *
   4  * List Box control.
   5  *
   6  * Portable Windows Library
   7  *
   8  * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
   9  *
  10  * The contents of this file are subject to the Mozilla Public License
  11  * Version 1.0 (the "License"); you may not use this file except in
  12  * compliance with the License. You may obtain a copy of the License at
  13  * http://www.mozilla.org/MPL/
  14  *
  15  * Software distributed under the License is distributed on an "AS IS"
  16  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
  17  * the License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * The Original Code is Portable Windows Library.
  21  *
  22  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
  23  *
  24  * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
  25  * All Rights Reserved.
  26  *
  27  * Contributor(s): ______________________________________.
  28  *
  29  * $Log$
  30  * Revision 1.27  2001/05/22 12:49:33  robertj
  31  * Did some seriously wierd rewrite of platform headers to eliminate the
  32  *   stupid GNU compiler warning about braces not matching.
  33  *
  34  * Revision 1.26  1999/11/16 06:51:41  robertj
  35  * Created PCustomListBox to allow motif native code PStringListBox implementation
  36  *
  37  * Revision 1.25  1999/11/16 05:19:36  craigs
  38  * Created PCustomListBox to allow native code PStringListBox implementation
  39  *
  40  * Revision 1.24  1999/03/10 03:49:52  robertj
  41  * More documentation adjustments.
  42  *
  43  * Revision 1.23  1999/03/09 08:01:48  robertj
  44  * Changed comments for doc++ support (more to come).
  45  *
  46  * Revision 1.22  1999/02/16 08:08:45  robertj
  47  * MSVC 6.0 compatibility changes.
  48  *
  49  * Revision 1.21  1998/09/23 06:24:05  robertj
  50  * Added open source copyright license.
  51  *
  52  * Revision 1.20  1995/10/14 14:57:43  robertj
  53  * Added addition of colection as strings to box.
  54  *
  55  * Revision 1.19  1995/06/17 11:12:42  robertj
  56  * Documentation update.
  57  *
  58  * Revision 1.18  1995/03/14 12:41:40  robertj
  59  * Updated documentation to use HTML codes.
  60  *
  61  * Revision 1.17  1995/02/19  04:19:13  robertj
  62  * Added dynamically linked command processing.
  63  *
  64  * Revision 1.16  1995/01/14  06:22:48  robertj
  65  * Documentation
  66  *
  67  * Revision 1.15  1995/01/02  12:15:15  robertj
  68  * Documentation
  69  *
  70  * Revision 1.14  1994/10/30  11:46:47  robertj
  71  * Changed mechanism for doing notification callback functions.
  72  *
  73  * Revision 1.13  1994/08/23  11:32:52  robertj
  74  * Oops
  75  *
  76  * Revision 1.12  1994/08/22  00:46:48  robertj
  77  * Added pragma fro GNU C++ compiler.
  78  *
  79  * Revision 1.11  1994/06/25  11:55:15  robertj
  80  * Unix version synchronisation.
  81  *
  82  * Revision 1.10  1994/04/03  08:34:18  robertj
  83  * Added help and focus functionality.
  84  *
  85  * Revision 1.9  1994/03/07  07:38:19  robertj
  86  * Major enhancementsacross the board.
  87  *
  88  * Revision 1.8  1994/01/15  02:50:29  robertj
  89  * Moved control contructors to common and added a platform dependent Construct() function.
  90  *
  91  * Revision 1.7  1994/01/03  04:42:23  robertj
  92  * Mass changes to common container classes and interactors etc etc etc.
  93  *
  94  * Revision 1.6  1993/12/16  02:02:52  robertj
  95  * As can delete objects in listbox, objects should not be const.
  96  *
  97  * Revision 1.5  1993/12/15  21:10:10  robertj
  98  * Added optional deletion of objects in the list box.
  99  *
 100  * Revision 1.4  1993/09/27  16:35:25  robertj
 101  * Removed special constructor for dialog resource loading.
 102  *
 103  * Revision 1.3  1993/07/15  04:23:39  robertj
 104  * Added optional update screen parameter to list box modification functions.
 105  *
 106  * Revision 1.2  1993/07/14  12:49:16  robertj
 107  * Fixed RCS keywords.
 108  *
 109  */
 110
 111
 112 #define _PLISTBOX
 113
 114 #ifdef __GNUC__
 115 #pragma interface
 116 #endif
 117
 118
 119 /**A scrollable list box control for selection of a one or more of items. The
 120    application writer should not normally descend from this class directly but
 121    descend from either the PStringListBox or PCustomListBox class.
 122  */
 123 class PListBox : public PControl
 124 {
 125   PCLASSINFO(PListBox, PControl);
 126
 127   public:
 128    /**Option used when constructing a list box for whether the list box
 129        entries are sorted or unsorted.
 130      */
 131     enum StringSorting {
 132       /// Entries are added to list in any order.
 133       NotSorted,
 134       /// Entries are added to list in correct sorted position.
 135       Sorted
 136     };
 137
 138    /**Option used when constructing a list box for whether the list box
 139        may have single or multiple entries selected.
 140      */
 141     enum SelectType {
 142       /// Only zero or one entry may be selected at a time.
 143       SingleSelect,
 144       /// Any number of entries may be selected.
 145       MultiSelect
 146     };
 147
 148     /** Create a list box with the specified options. */
 149     PListBox(
 150       PInteractor * parent,     /// Interactor into which the control is placed.
 151       StringSorting sorted = Sorted,
 152      /**If set to #Sorted# then strings will be inserted in sorted
 153          order. This requires that the \Ref{PObject::Compare()} function
 154          operate correctly for objects placed into the list box.
 155        */
 156       SelectType select = SingleSelect,
 157      /**If set to #MultiSelect# then more than one item may be
 158          selected at a time. Otherwise only zero or one item may be selected.
 159        */
 160       PDIMENSION columnWidth = 0,
 161      /**If this parameter is zero then only one column with a vertical scroll
 162          bar is displayed. If non-zero, then multiple columns of this width,
 163          in font based coordinates, will be used and a horizontal scroll bar
 164          displayed.
 165        */
 166       BOOL deleteObj = TRUE
 167      /**If this parameter is TRUE then when the list box is destroyed all
 168          entries objects are deleted as well using the delete operator.
 169          Similarly if \Ref{DeleteEntry()} or \Ref{DeleteAllEntries()} is
 170          called the entry or entries are deleted, again using the delete
 171          operator).
 172        */
 173     );
 174     PListBox(
 175       PInteractor * parent,     /// Interactor into which the control is placed.
 176       const PNotifier & notify,  /// Function to call when changes state.
 177       StringSorting sorted = Sorted,
 178      /**If set to #Sorted# then strings will be inserted in sorted
 179          order. This requires that the \Ref{PObject::Compare()} function
 180          operate correctly for objects placed into the list box.
 181        */
 182       SelectType select = SingleSelect,
 183      /**If set to #MultiSelect# then more than one item may be
 184          selected at a time. Otherwise only zero or one item may be selected.
 185        */
 186       PDIMENSION columnWidth = 0,
 187      /**If this parameter is zero then only one column with a vertical scroll
 188          bar is displayed. If non-zero, then multiple columns of this width,
 189          in font based coordinates, will be used and a horizontal scroll bar
 190          displayed.
 191        */
 192       BOOL deleteObj = TRUE
 193      /**If this parameter is TRUE then when the list box is destroyed all
 194          entries objects are deleted as well using the delete operator.
 195          Similarly if \Ref{DeleteEntry()} or \Ref{DeleteAllEntries()} is
 196          called the entry or entries are deleted, again using the delete
 197          operator).
 198        */
 199     );
 200
 201     /** Create control from interactor layout with the specified control ID. */
 202     PListBox(
 203       PInteractorLayout * parent, /// Interactor into which the box is placed.
 204       PRESOURCE_ID ctlID,         /// Identifier for the control in the layout.
 205       const PNotifier & notify,   /// Function to call when changes state.
 206       PINDEX * valuePtr           /// Variable to change to the list box state.
 207     );
 208
 209     /** Destroy the list box and all its contents. */
 210     virtual ~PListBox();
 211
 212
 213   /**@name PNotifier codes */
 214    /**Notification codes passed to the PNotifier function when the specified
 215        notification events occur.
 216      */
 217     enum {
 218       /// A new entry was selected or deselected.
 219       NewSelection = NotifyChange,
 220       /// An entry was double clicked.
 221       DoubleClick
 222     };
 223
 224
 225     /**@name Overrides from class PControl */
 226    /**This function transfers the value of the control to or from the variable
 227        pointed to by the value pointer member variable.
 228      */
 229     virtual void TransferValue(
 230       int option
 231      /**Transfer value option. When this is -1 when the function transfers
 232          the value from the value pointer into the control. This is called in
 233          \Ref{PDialog::OnInit()} function. When option is zero then the
 234          function transfers the value from the control to the value pointer
 235          variable. This is called just before the callback function every time
 236          the list box value changes.
 237        */
 238     );
 239
 240
 241     /**@name New functions for class */
 242     /** Set flag to delete entry objects using delete operator. */
 243     virtual void AllowDeleteObjects(
 244       BOOL yes = TRUE   /// New flag for deleting entries in list box.
 245     );
 246
 247    /**Reset flag to delete entry objects using delete operator. This is
 248        equivalent to #AllowDeleteObjects(FALSE)#.
 249      */
 250     virtual void DisallowDeleteObjects();
 251
 252    /**Delete the entry from the list box. If the delete objects option was
 253        selected then all the objects added to the list box are deleted as well.
 254
 255        If the #update# parameter is FALSE then it is the users
 256        responsibility to redraw the list box, ie call
 257        \Ref{PInteractor::Invalidate()} or \Ref{PInteractor::Update()} some
 258        time afterward. This is typically used if a large number of entries are
 259        to be deleted to the list box in one go. The user would delete the
 260        entries and then call the \Ref{PInteractor::Invalidate()} function on
 261        the list box to force a redraw. This is much faster and tidier in
 262        appearance.
 263      */
 264     virtual void DeleteEntry(
 265       PINDEX index,       /// Index position in list box to delete entry.
 266       BOOL update = TRUE  /// Flag to indicate screen should be updated.
 267     );
 268
 269    /**Delete all of the entries in the list box. If the delete objects option
 270        was selected then all the objects added to the list box are deleted as
 271        well.
 272
 273        If the #update# parameter is FALSE then it is the users
 274        responsibility to redraw the list box, ie call
 275        \Ref{PInteractor::Invalidate()} or \Ref{PInteractor::Update()} some
 276        time afterward. This is typically used if entries are to be added to the
 277        list box immediately after deleting then. This is much faster and tidier
 278        in appearance.
 279      */
 280     virtual void DeleteAllEntries(
 281       BOOL update = TRUE  /// Flag to indicate screen should be updated.
 282     );
 283
 284    /**Get the count of the number of items in the list of entries in the
 285        list box.
 286
 287        @return
 288        number of entries.
 289      */
 290     virtual PINDEX GetCount() const;
 291
 292    /**Set the index of the list box entry that is currently visible at the
 293        top of the list. The list is scrolled accordingly.
 294
 295        If the #update# parameter is FALSE then it is the users
 296        responsibility to redraw the list box, ie call
 297        \Ref{PInteractor::Invalidate()} or \Ref{PInteractor::Update()} some
 298        time afterward.
 299      */
 300     virtual void SetTopIndex(
 301       PINDEX index,       /// Index position in list box to make the top item.
 302       BOOL update = TRUE  /// Flag to indicate screen should be updated.
 303     );
 304
 305    /**Get the index of the list box entry that is currently visible at the
 306        top of the list.
 307
 308        @return
 309        index position of the list boxes top entry.
 310      */
 311     virtual PINDEX GetTopIndex() const;
 312
 313    /**Set the new width of columns in the list box.
 314
 315        Note that the list box must have been created with a non-zero width in
 316        the first place for this to work. It only allows the width to be
 317        readjusted.
 318
 319        For the same reason the function will assert if the
 320        #newWidth# parameter is zero.
 321
 322        If the #update# parameter is FALSE then it is the users
 323        responsibility to redraw the list box, ie call
 324        \Ref{PInteractor::Invalidate()} or \Ref{PInteractor::Update()} some
 325        time afterward.
 326      */
 327     virtual void SetColumnWidth(
 328       PDIMENSION newWidth,    /// New width for the columns in the list box.
 329       BOOL update = TRUE      /// Flag to indicate screen should be updated.
 330     );
 331
 332    /**Set the current selection to the entry specified by the index.
 333
 334        If the multiple selection option is used then this will deselect all
 335        other items and only have the specified entry selected.
 336
 337        If the #index# parameter is beyond the end of the list box
 338        then all entries are deselected.
 339      */
 340     virtual void SetSelection(
 341       PINDEX index  /// Index of entry to become the single selection.
 342     );
 343
 344    /**Get the current selection index. If the list box has the multi-select
 345        option this only indicates the item that has the focus.
 346
 347        @return
 348        currently selected item or P_MAX_INDEX if nothing selected.
 349      */
 350     virtual PINDEX GetSelection() const;
 351
 352    /**Set the selection state of the list box item. If the list box is not a
 353        multi-select then deselects all others before selecting or deselecting
 354        the item specified.
 355
 356        If the #update# parameter is FALSE then it is the users
 357        responsibility to redraw the list box, ie call
 358        \Ref{PInteractor::Invalidate()} or \Ref{PInteractor::Update()} some
 359        time afterward. This is typically used if a large number of entries are
 360        to be changed in the list box in one go. The user would change the
 361        entries and then call the \Ref{PInteractor::Invalidate()} function on
 362        the list box to force a redraw. This is much faster and tidier in
 363        appearance.
 364      */
 365     virtual void Select(
 366       PINDEX index,       /// Index position in list box to select.
 367       BOOL update = TRUE, /// Flag to indicate screen should be updated.
 368       BOOL sel = TRUE     /// State in which to set the entries selection.
 369     );
 370
 371    /**Reset the selection state of the list box item. This is equivalent to
 372        #Select(index, FALSE, update)#.
 373
 374        If the list box was not multi select then all entries a deselected.
 375      */
 376     virtual void Deselect(
 377       PINDEX index,       /// Index position in list box to select.
 378       BOOL update = TRUE  /// Flag to indicate screen should be updated.
 379     );
 380
 381       /** Get the selection state of the list box item. */
 382     virtual BOOL IsSelected(
 383       PINDEX index    /// Index of entry to check for being selected.
 384     ) const;
 385
 386    /**Get the number of list box items that are selected. This would only be
 387        one or zero unless multiple selection option is used.
 388
 389        @return
 390        total items selected in list box.
 391      */
 392     virtual PINDEX GetSelCount() const;
 393
 394    /**Get the current value pointer associated with the control. The variable
 395        pointed to by this is autamatically updated with the current value of
 396        the list box.
 397
 398        @return
 399        value pointer associated with the control.
 400      */
 401     virtual PINDEX * GetValuePointer() const;
 402
 403    /**Set the current value pointer associated with the control. The variable
 404        pointed to by this is autamatically updated with the current value of
 405        the list box.
 406      */
 407     virtual void SetValuePointer(
 408       PINDEX * ptr  /// New value pointer to associate with the control.
 409     );
 410
 411   protected:
 412     // Member variables
 413     /** Flag indicating list is sorted. */
 414     BOOL sort;
 415
 416     /** Flag indicating the list may have multiple selections. */
 417     BOOL multi;
 418
 419     /** Width of multi-column list box. */
 420     PDIMENSION width;
 421
 422     /** Flag to indicate objects placed in list should be deleted when removed. */
 423     BOOL deleteObjects;
 424
 425
 426   private:
 427     // New functions for class
 428     void Construct();
 429       // Common constructor code
 430
 431
 432 // Include platform dependent part of class
 433 #include <pwlib/listbox.h>
 434 };
 435
 436
 437 // End Of File ///////////////////////////////////////////////////////////////