include/pwlib/choicbox.h

   1 /*
   2  * choicbox.h
   3  *
   4  * Choice 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.23  2001/05/22 12:49:32  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.22  1999/03/10 03:49:51  robertj
  35  * More documentation adjustments.
  36  *
  37  * Revision 1.21  1999/03/09 08:01:47  robertj
  38  * Changed comments for doc++ support (more to come).
  39  *
  40  * Revision 1.20  1999/02/16 08:08:45  robertj
  41  * MSVC 6.0 compatibility changes.
  42  *
  43  * Revision 1.19  1998/09/23 06:23:03  robertj
  44  * Added open source copyright license.
  45  *
  46  * Revision 1.18  1995/10/14 14:53:55  robertj
  47  * Added addition of colection as strings to box.
  48  * Changed SetChoice to SetSelection for consistencies sake.
  49  *
  50  * Revision 1.17  1995/03/14 12:41:06  robertj
  51  * Updated documentation to use HTML codes.
  52  *
  53  * Revision 1.16  1995/02/19  04:19:05  robertj
  54  * Added dynamically linked command processing.
  55  *
  56  * Revision 1.15  1995/01/14  06:20:25  robertj
  57  * Documentation
  58  *
  59  * Revision 1.14  1994/12/05  11:14:53  robertj
  60  * Documentation.
  61  *
  62  * Revision 1.13  1994/10/30  11:46:32  robertj
  63  * Changed mechanism for doing notification callback functions.
  64  *
  65  * Revision 1.12  1994/08/23  11:32:52  robertj
  66  * Oops
  67  *
  68  * Revision 1.11  1994/08/22  00:46:48  robertj
  69  * Added pragma fro GNU C++ compiler.
  70  *
  71  * Revision 1.10  1994/06/25  11:55:15  robertj
  72  * Unix version synchronisation.
  73  *
  74  * Revision 1.9  1994/04/11  14:11:15  robertj
  75  * Added consts.
  76  *
  77  * Revision 1.8  1994/04/03  08:34:18  robertj
  78  * Added help and focus functionality.
  79  *
  80  * Revision 1.7  1994/03/07  07:38:19  robertj
  81  * Major enhancementsacross the board.
  82  *
  83  * Revision 1.6  1994/01/15  02:50:29  robertj
  84  * Moved control contructors to common and added a platform dependent Construct() function.
  85  *
  86  * Revision 1.5  1994/01/03  04:42:23  robertj
  87  * Mass changes to common container classes and interactors etc etc etc.
  88  *
  89  * Revision 1.4  1993/09/27  16:35:25  robertj
  90  * Removed special constructor for dialog resource loading.
  91  *
  92  * Revision 1.3  1993/08/21  01:50:33  robertj
  93  * Made Clone() function optional, default will assert if called.
  94  *
  95  * Revision 1.2  1993/07/14  12:49:16  robertj
  96  * Fixed RCS keywords.
  97  *
  98  */
  99
 100
 101 #define _PCHOICEBOX
 102
 103 #ifdef __GNUC__
 104 #pragma interface
 105 #endif
 106
 107
 108
 109 /**A control for selecting one of a number of choices, similar to radio
 110    buttons but typically for larger numbers of options in a smaller space.
 111
 112    The exact appearence of a choice box is platform dependent, for example,
 113    in MS-Windows this is a fixed combo-box, in Mac-OS it is a popup menu.
 114  */
 115 class PChoiceBox : public PControl
 116 {
 117   PCLASSINFO(PChoiceBox, PControl);
 118
 119   public:
 120     /** Option for the strings in the choice box. */
 121     enum StringSorting {
 122       /// Strings are in the order they are added.
 123       NotSorted,
 124       /// Strings are in alphabetic order.
 125       Sorted
 126     };
 127
 128     /** Create a choice box with optional sorting of the list elements. */
 129     PChoiceBox(
 130       PInteractor * parent,    /// Interactor into which the control is placed.
 131       StringSorting sorted = NotSorted  /// Sorting option for strings in box.
 132     );
 133     PChoiceBox(
 134       PInteractor * parent,    /// Interactor into which the control is placed.
 135       const PNotifier & notify,  /// Function to call when changes state.
 136       StringSorting sorted = NotSorted  /// Sorting option for strings in box.
 137     );
 138
 139     /** Create control from interactor layout with the specified control ID. */
 140     PChoiceBox(
 141       PInteractorLayout * parent, /// Interactor into which the box is placed.
 142       PRESOURCE_ID ctlID,         /// Identifier for the control in the layout.
 143       const PNotifier & notify,   /// Function to call when changes state.
 144       PINDEX * valuePtr           /// Variable to change to the check box state.
 145     );
 146
 147     /** Destroy the choice box and its contents. */
 148     virtual ~PChoiceBox();
 149
 150
 151    /**Codes passed to the PNotifier function when the specified notification
 152        events occur.
 153      */
 154     enum {
 155       /// A new choice was made from this list
 156       NewSelection = NotifyChange,
 157         /// The list of selections has been presented.
 158       ListDropped,
 159       /// The list of selections has been hidden.
 160       ListClosed
 161     };
 162
 163
 164   /**@name Overrides from class PControl */
 165    /**This function transfers the value of the control to or from the variable
 166        pointed to by the value pointer member variable.
 167      */
 168     virtual void TransferValue(
 169       int option
 170      /**Transfer value option. When this is -1 when the function transfers
 171          the value from the value pointer into the control. This is called in
 172          \Ref{PDialog::OnInit()} function. When option is zero then the
 173          function transfers the value from the control to the value pointer
 174          variable. This is called just before the callback function every time
 175          the choice box value changes.
 176        */
 177     );
 178
 179
 180   /**@name New functions for class */
 181    /**Set the index of the string that is currently selected and visible in
 182        the non-popped up state. The first string is index 0 etc. This will be
 183        updated on the screen immediately (within OS constraints).
 184      */
 185     void SetSelection(
 186       PINDEX newValue   /// New index of the choice box string selected,
 187     );
 188
 189    /**Get the index of the string that is currently selected.
 190
 191        @return
 192        index of choice box selection.
 193      */
 194     PINDEX GetSelection() const;
 195
 196    /**Get the current value pointer associated with the control. The variable
 197        pointed to by this is autamatically updated with the current value of
 198        the choice box.
 199
 200        @return
 201        value pointer associated with the control.
 202      */
 203     PINDEX * GetValuePointer() const;
 204
 205    /**Set the current value pointer associated with the control. The variable
 206        pointed to by this is autamatically updated with the current value of
 207        the choice box.
 208      */
 209     void SetValuePointer(
 210       PINDEX * ptr  /// New value pointer to associate with the control.
 211     );
 212
 213
 214    /**Add a new string to the list box. If the sorted option was used this
 215        will place the string in the correct position. Otherwise it adds it to
 216        the end of the list.
 217
 218        @return
 219        the index that the string was placed.
 220      */
 221     PINDEX AddString(
 222       const PString & str   /// String to add to the list of choices.
 223     );
 224
 225    /**Add a collection of new entries to the choice box. Each element of the
 226        collection is added in order using the \Ref{AddEntry()} function. Thus,
 227        for example, a sorted list string will be added in sorted order.
 228
 229        If the collection is not of string objects then they are translated into
 230        a string by the use of the \Ref{operator<<} function.
 231      */
 232     void AddStrings(
 233       const PCollection & objects /// New objects to add to list box.
 234     );
 235
 236    /**Insert a string at the specified location. This ignores the sort order
 237        and explicitly places the string at the index position.
 238      */
 239     void InsertString(
 240       const PString & str,  /// String to add to the list of choices.
 241       PINDEX index          /// Position in list to place the new string.
 242     );
 243
 244     /** Delete a string from the list of choices in the choice box. */
 245     void DeleteString(
 246       PINDEX index   /// Position in list of the string to remove.
 247     );
 248
 249     /** Delete all the strings in the list of choices in the choice box. */
 250     void DeleteAllStrings();
 251
 252    /**Find the string in the list of choices starting at the entry after the
 253        specified starting index. If the index is P_MAX_INDEX then searches the
 254        whole list. The exact flag indicates that the whole string must match
 255        otherwise a string in the list box that matches up to the length of the
 256        argument string will be found.
 257
 258        @return
 259        index position of the string that meets the matching criteria or
 260        #P_MAX_INDEX# if it was not found.
 261      */
 262     PINDEX FindString(
 263       const PString & str,  /// String to search for in the list of choices.
 264       PINDEX startIndex = P_MAX_INDEX,  /// Index into list to start search.
 265       BOOL exact = FALSE    /// Flag for whether search is exact or partial.
 266     ) const;
 267
 268    /**Set the string at the index position. If the index is beyond the end of
 269        the list then simply adds the string to the end of the list.
 270      */
 271     void SetString(
 272       const PString & str,  /// String to set in the list of choices.
 273       PINDEX index          /// Position in the list of choices to set.
 274     );
 275
 276    /**Get the string at the index. If the index is beyond the end of the list
 277        then returns the empty string.
 278
 279        @return
 280        string for the entry in the list of choices.
 281      */
 282     PString GetString(
 283       PINDEX index    /// Position in the list of choices to retrieve.
 284     ) const;
 285
 286    /**Get the count of the number of items in the list of choices in the
 287        choice box.
 288
 289        @return
 290        number of choices.
 291      */
 292     PINDEX GetCount() const;
 293
 294
 295   protected:
 296   // Member variables
 297     /** The coice box strings are sorted. */
 298     BOOL sort;
 299
 300
 301   private:
 302   // New functions for class
 303     void Construct();
 304     // Common constructor code
 305
 306
 307 // Include platform dependent part of class
 308 #include <pwlib/choicbox.h>
 309 };
 310
 311
 312 // End Of File ///////////////////////////////////////////////////////////////