include/pwlib/editbox.h

   1 /*
   2  * editbox.h
   3  *
   4  * Single line text edit 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.24  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.23  2000/04/13 01:37:14  robertj
  35  * Added missing implementation of PEditBox::GetSelection() on Win32.
  36  * Added PEditBox::ReplaceSelection() function.
  37  *
  38  * Revision 1.22  1999/03/10 03:49:51  robertj
  39  * More documentation adjustments.
  40  *
  41  * Revision 1.21  1999/03/09 08:01:48  robertj
  42  * Changed comments for doc++ support (more to come).
  43  *
  44  * Revision 1.20  1999/02/16 08:08:45  robertj
  45  * MSVC 6.0 compatibility changes.
  46  *
  47  * Revision 1.19  1998/09/23 06:23:25  robertj
  48  * Added open source copyright license.
  49  *
  50  * Revision 1.18  1995/06/17 11:12:32  robertj
  51  * Documentation update.
  52  *
  53  * Revision 1.17  1995/06/04 08:47:27  robertj
  54  * Added missing virtual for SetText() - Unix implementation requirement.
  55  *
  56  * Revision 1.16  1995/03/14 12:41:22  robertj
  57  * Updated documentation to use HTML codes.
  58  *
  59  * Revision 1.15  1995/02/19  04:19:08  robertj
  60  * Added dynamically linked command processing.
  61  *
  62  * Revision 1.14  1995/02/05  00:46:10  robertj
  63  * Added notification of end input.
  64  *
  65  * Revision 1.13  1995/01/27  11:45:57  robertj
  66  * documentation.
  67  *
  68  * Revision 1.12  1994/12/15  12:47:13  robertj
  69  * Documentation.
  70  *
  71  * Revision 1.11  1994/10/30  11:46:36  robertj
  72  * Changed mechanism for doing notification callback functions.
  73  *
  74  * Revision 1.10  1994/08/23  11:32:52  robertj
  75  * Oops
  76  *
  77  * Revision 1.9  1994/08/22  00:46:48  robertj
  78  * Added pragma fro GNU C++ compiler.
  79  *
  80  * Revision 1.8  1994/06/25  11:55:15  robertj
  81  * Unix version synchronisation.
  82  *
  83  * Revision 1.7  1994/04/11  14:14:01  robertj
  84  * Added consts.
  85  *
  86  * Revision 1.6  1994/03/07  07:38:19  robertj
  87  * Major enhancementsacross the board.
  88  *
  89  * Revision 1.5  1994/01/03  04:42:23  robertj
  90  * Mass changes to common container classes and interactors etc etc etc.
  91  *
  92  * Revision 1.4  1993/09/27  16:35:25  robertj
  93  * Removed special constructor for dialog resource loading.
  94  *
  95  * Revision 1.3  1993/08/21  01:50:33  robertj
  96  * Made Clone() function optional, default will assert if called.
  97  *
  98  * Revision 1.2  1993/07/14  12:49:16  robertj
  99  * Fixed RCS keywords.
 100  *
 101  */
 102
 103 #define _PEDITBOX
 104
 105 #ifdef __GNUC__
 106 #pragma interface
 107 #endif
 108
 109
 110 /**This class defines a text edit box control. This control is for a single
 111    line of text. The usual capabilities for editing text are available,
 112    though the exact features are platform dependent.
 113  */
 114 class PEditBox : public PControl
 115 {
 116   PCLASSINFO(PEditBox, PControl);
 117
 118   public:
 119    /**Create a new single line edit box control.
 120      */
 121     PEditBox(
 122       PInteractor * parent  /// Interactor into which the control is placed.
 123     );
 124
 125     /** Create control from interactor layout with the specified control ID. */
 126     PEditBox(
 127       PInteractorLayout * parent, /// Interactor into which the box is placed.
 128       PRESOURCE_ID ctlID,         /// Identifier for the control in the layout.
 129       const PNotifier & notify,   /// Function to call when changes state.
 130       PString * valuePtr          /// Variable to change to the editor value.
 131     );
 132
 133     /** Destroy the edit box control. */
 134     virtual ~PEditBox();
 135
 136
 137   /**@name PNotifier codes */
 138     /** Notification codes sent to the callback function. */
 139     enum {
 140      /**Notification code for each change of the edit text box string. This
 141          would notify the user on every key entered and may be used to take
 142          action on the particular value of the control.
 143        */
 144       EditChange = NotifyChange,
 145      /**Notification code for when the user exits the edit box. This occurs
 146          when the control loses the keyboard focus and the \Ref{OnEndInput()}
 147          function has returned TRUE.
 148        */
 149       EndEdit
 150     };
 151
 152
 153   /**@name Overrides from class PInteractor */
 154    /**The system calls this whenever the system wishes to change focus to
 155        another interactor in a given \Ref{PTitledWindow} or
 156        \Ref{PInteractorLayout}.
 157
 158        This function in conjunction with the keyboard focus changing and the
 159        \Ref{PInteractor::SetFocusInteractor()} function controls the transfer
 160        of focus from one interactor in a logical group (eg dialog) to another.
 161        It is primarily used for field level validation. For example the
 162        \Ref{PIntegerEditBox} control uses this to prevent the user from
 163        exiting the control until a valid entry hash been made.
 164
 165        Note that the focus {\bf does} actually change with appropriate
 166        calls to the \Ref{PInteractor::OnGainFocus()} and
 167        \Ref{PInteractor::OnLostFocus()} functions. The focus gets set back to
 168        the original interactor when this function disallows the focus change.
 169
 170        For edit boxes this will execute the notification function before
 171        returning TRUE.
 172
 173        @return
 174        FALSE will prevent the focus change from occurring and TRUE allows the
 175        change.
 176      */
 177     virtual BOOL OnEndInput();
 178
 179
 180   /**@name Overrides from class PControl */
 181    /**This function transfers the value of the control to or from the variable
 182        pointed to by the value pointer member variable.
 183      */
 184     virtual void TransferValue(
 185       int option
 186      /**Transfer value option. When this is -1 when the function transfers
 187          the value from the value pointer into the control. This is called in
 188          \Ref{PDialog::OnInit()} function. When option is zero then the
 189          function transfers the value from the control to the value pointer
 190          variable. This is called just before the callback function every time
 191          the edit box value changes.
 192        */
 193     );
 194
 195
 196     /**@name New functions for class */
 197    /**Set the text contents of the edit box control. This will be updated on
 198        the screen immediately (within OS constraints).
 199
 200        A call to this function will cause the notification function to be
 201        called with a code of #EditChange#.
 202      */
 203     virtual void SetText(
 204       const PString & str  /// New value string for the edit text box.
 205     );
 206
 207    /**Get the current text contents of the edit box control as entered by the
 208        user, or set via the \Ref{SetText()} function.
 209
 210        @return
 211        string for the current contents of the edit box.
 212      */
 213     PString GetText() const;
 214
 215    /**Get the current value pointer associated with the control. The variable
 216        pointed to by this is autamatically updated with the current value of
 217        the edit box.
 218
 219        @return
 220        value pointer associated with the control.
 221      */
 222     PString * GetValuePointer() const;
 223
 224    /**Set the current value pointer associated with the control. The variable
 225        pointed to by this is autamatically updated with the current value of
 226        the edit box.
 227      */
 228     void SetValuePointer(
 229       PString * ptr  /// New value pointer to associate with the control.
 230     );
 231
 232
 233    /**Set the maximum amount of text that the user may enter in the combo-box
 234        edit text part. Extra characters entered when it is full are ignored.
 235      */
 236     void SetMaxText(
 237       PINDEX max  /// New maximum character entry limit.
 238     );
 239
 240    /**Get the current length of the text entered into the edit box. This is
 241        equivalent to #GetText().GetLength()#.
 242
 243        @return
 244        number of characters in edit box.
 245      */
 246     PINDEX GetLength() const;
 247
 248    /**Determine if the edit control has been modified by the user since the
 249        last call to \Ref{SetText()} or \Ref{GetText()}.
 250
 251        @return
 252        TRUE if the user has changed the text in the edit box.
 253      */
 254     BOOL IsModified() const;
 255
 256    /**Set the selected region in the text within the edit box. The selected
 257        region includes the character at the #start# position but
 258        does not include the character at the #finish# position.
 259
 260        If #start# and #finish# are equal then there is
 261        no selected region. However, the caret is placed immediately before
 262        that position, ie so that the next character entered will be at
 263        #start# offset into the resultant string.
 264
 265        If #finish# is less than #start# it is set to the
 266        same value as #start#. If either value is greater than the
 267        current length of the edit box, then they are set to the position of
 268        the end of the string.
 269      */
 270     void SetSelection(
 271       PINDEX start = 0,           /// Start index position of selected text.
 272       PINDEX finish = P_MAX_INDEX /// Finish index position of selected text.
 273     );
 274
 275    /**Get the selected region in the text in the edit box. If there is no
 276        selection active, the #start# and #finish#
 277        variables are both set to the caret position in the string.
 278
 279        @return
 280        TRUE if has selection, FALSE if there is nothing selected.
 281      */
 282     BOOL GetSelection(
 283       PINDEX * start = NULL,
 284         /// Pointer to receive starting position of selected text.
 285       PINDEX * finish = NULL
 286         /// Pointer to receive finishing position of selected text.
 287     ) const;
 288
 289     /**Replace the selection with the string.
 290        If there is no selection then the string is inserted into the edit box
 291        at the curent cursor location.
 292       */
 293     void ReplaceSelection(
 294       const PString & text,   /// Text to replace selection with
 295       BOOL canUndo = TRUE     /// Flag to indicate replacement can be undone.
 296     );
 297
 298    /**Determine if the edit control can undo the last edit operation performed
 299        by the user.
 300
 301        @return
 302        TRUE if undo will succeed.
 303      */
 304     BOOL CanUndo() const;
 305
 306     /** Undo the last edit operation performed by the user. */
 307     void Undo();
 308
 309    /**Cut the selected text to the clipboard. This copies the data and then
 310        deletes the current selection.
 311
 312        If there is no current selection then this function does nothing.
 313
 314        A call to this function will cause the notification functionto be
 315        called with a code of #EditChange#.
 316      */
 317     void Cut();
 318
 319    /**Copy the selected text to the clipboard.
 320
 321        If there is no current selection then this function does nothing.
 322      */
 323     void Copy() const;
 324
 325    /**Paste into the edit control from the clipboard into the edit box at the
 326        current caret position.
 327
 328        If the paste would add so many characters that the limit set with
 329        \Ref{SetMaxText()} would be exceeded then the paste does not take
 330        place.
 331
 332        Also, if there is no text in the clipboard then this function does
 333        nothing.
 334
 335        A call to this function will cause the notification functionto be
 336        called with a code of #EditChange#.
 337      */
 338     void Paste();
 339
 340    /**Delete the selected text. This does not copy the information to the
 341        clipboard and the selected text is lost.
 342
 343        If there is no current selection then this function does nothing.
 344
 345        A call to this function will cause the notification functionto be
 346        called with a code of #EditChange#.
 347      */
 348     void Clear();
 349
 350
 351   private:
 352     void Construct();
 353       // Common contructor code.
 354
 355
 356 // Include platform dependent part of class
 357 #include <pwlib/editbox.h>
 358 };
 359
 360
 361 // End Of File ///////////////////////////////////////////////////////////////