include/pwlib/scrollb.h

   1 /*
   2  * scrollb.h
   3  *
   4  * Scroll bar ancestor class.
   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.20  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.19  1999/03/10 03:49:53  robertj
  35  * More documentation adjustments.
  36  *
  37  * Revision 1.18  1999/03/09 08:01:50  robertj
  38  * Changed comments for doc++ support (more to come).
  39  *
  40  * Revision 1.17  1999/02/16 08:08:46  robertj
  41  * MSVC 6.0 compatibility changes.
  42  *
  43  * Revision 1.16  1998/09/23 06:28:58  robertj
  44  * Added open source copyright license.
  45  *
  46  * Revision 1.15  1995/03/14 12:42:32  robertj
  47  * Updated documentation to use HTML codes.
  48  *
  49  * Revision 1.14  1995/02/19  04:19:18  robertj
  50  * Added dynamically linked command processing.
  51  *
  52  * Revision 1.13  1995/02/05  00:50:17  robertj
  53  * Had to change variable name "small" for MSVC 2.0
  54  *
  55  * Revision 1.12  1994/12/21  11:53:28  robertj
  56  * Documentation and variable normalisation.
  57  *
  58  * Revision 1.11  1994/10/30  11:47:05  robertj
  59  * Changed mechanism for doing notification callback functions.
  60  *
  61  * Revision 1.10  1994/08/23  11:32:52  robertj
  62  * Oops
  63  *
  64  * Revision 1.9  1994/08/22  00:46:48  robertj
  65  * Added pragma fro GNU C++ compiler.
  66  *
  67  * Revision 1.8  1994/06/25  11:55:15  robertj
  68  * Unix version synchronisation.
  69  *
  70  * Revision 1.7  1994/03/07  07:38:19  robertj
  71  * Major enhancementsacross the board.
  72  *
  73  * Revision 1.6  1994/01/15  02:50:29  robertj
  74  * Moved control contructors to common and added a platform dependent Construct() function.
  75  *
  76  * Revision 1.5  1994/01/03  04:42:23  robertj
  77  * Mass changes to common container classes and interactors etc etc etc.
  78  *
  79  * Revision 1.4  1993/09/27  16:35:25  robertj
  80  * Removed special constructor for dialog resource loading.
  81  *
  82  * Revision 1.3  1993/08/20  21:26:09  robertj
  83  * Added control notification codes.
  84  *
  85  * Revision 1.2  1993/07/14  12:49:16  robertj
  86  * Fixed RCS keywords.
  87  *
  88  */
  89
  90
  91 #define _PSCROLLBAR
  92
  93 #ifdef __GNUC__
  94 #pragma interface
  95 #endif
  96
  97
  98 /**A scroll bar control for visually setting an integer value.
  99
 100    The exact appearance of a scroll bar is platform dependent. However certain
 101    functionality exists for all platforms. These are that the scroll bar allows
 102    values between a minimum and maximum to be set via small nudges (typically
 103    a up or down arrow), large nudges (typically the page up or down area to
 104    either side of the thumb) or by explicitly setting a value (typically by
 105    dragging the thumb).
 106
 107    This is an abstract class combining the common functionality of
 108    \Ref{PHorizontalScrollBar} and \Ref{PVerticalScrollBar} controls.
 109  */
 110 class PScrollBar : public PControl
 111 {
 112   PCLASSINFO(PScrollBar, PControl);
 113
 114   public:
 115    /**Create a new scroll bar control with the specified default parameters
 116        for controlling the scroll bars operation.
 117      */
 118     PScrollBar(
 119       PInteractor * parent,  /// Interactor into which the control is placed.
 120       PSCROLLBAR_VALUE max,  /// Maximum value for scroll bar.
 121       PSCROLLBAR_VALUE min,  /// Minimum value for scroll bar.
 122       PSCROLLBAR_VALUE val,  /// Initial value for scroll bar.
 123       PSCROLLBAR_VALUE sml,  /// Amount to move with the nudge button.
 124       PSCROLLBAR_VALUE lge   /// Amount to move with the paging area.
 125     );
 126     PScrollBar(
 127       PInteractor * parent,   /// Interactor into which the control is placed.
 128       const PNotifier & func, /// Function to call when changes state.
 129       PSCROLLBAR_VALUE max,   /// Maximum value for scroll bar.
 130       PSCROLLBAR_VALUE min,   /// Minimum value for scroll bar.
 131       PSCROLLBAR_VALUE val,   /// Initial value for scroll bar.
 132       PSCROLLBAR_VALUE sml,   /// Amount to move with the nudge button.
 133       PSCROLLBAR_VALUE lge    /// Amount to move with the paging area.
 134     );
 135
 136     /** Create control from interactor layout with the specified control ID. */
 137     PScrollBar(
 138       PInteractorLayout * parent, /// Interactor into which the box is placed.
 139       PRESOURCE_ID ctlID,         /// Identifier for the control in the layout.
 140       const PNotifier & notify,   /// Function to call when changes state.
 141       PSCROLLBAR_VALUE * valuePtr /// Variable to change to the scrollbar value.
 142     );
 143
 144     /** Destroy the scroll bar. */
 145     virtual ~PScrollBar();
 146
 147
 148   /**@name PNotifier codes */
 149    /**Codes passed to the notification function on changes of state.
 150
 151        A change to a scroll bar may proceed for some time, for example if the
 152        mouse button is pressed in the down arrow and held down. An auto-repeat
 153        would occur to continually change the scroll bar value until it is
 154        released.
 155      */
 156     enum {
 157         /** A scroll bar value change operation has been ended by the user. */
 158       EndTrack = NotifyChange,
 159         /** A scroll bar value change operation has been initiated by the user. */
 160       StartTrack,
 161         /** A scroll bar value change operation is in progress by the user. */
 162       Tracking
 163     };
 164
 165
 166   /**@name Overrides from class PControl */
 167    /**This function transfers the value of the control to or from the variable
 168        pointed to by the value pointer member variable.
 169      */
 170     virtual void TransferValue(
 171       int option
 172      /**Transfer value option. When this is -1 when the function transfers
 173          the value from the value pointer into the control. This is called in
 174          \Ref{PDialog::OnInit()} function. When option is zero then the
 175          function transfers the value from the control to the value pointer
 176          variable. This is called just before the callback function every time
 177          the scroll bar value changes.
 178        */
 179     );
 180
 181
 182   /**@name New functions for class */
 183    /**Set the current thumb position of the scroll bar. If the
 184        #redraw# parameter is TRUE then this will be updated on the
 185        screen immediately (within OS constraints).
 186      */
 187     void SetValue(
 188       PSCROLLBAR_VALUE val,   /// New value for scroll bar.
 189       BOOL redraw = TRUE      /// Whether to update the screen.
 190     );
 191
 192    /**Get the current thumb position of the scroll bar.
 193
 194        @return
 195        current scroll bar value.
 196      */
 197     PSCROLLBAR_VALUE GetValue() const;
 198
 199    /**Get the current value pointer associated with the control. The variable
 200        pointed to by this is autamatically updated with the current value of
 201        the scroll bar.
 202
 203        @return
 204        value pointer associated with the control.
 205      */
 206     PSCROLLBAR_VALUE * GetValuePointer() const;
 207
 208    /**Set the current value pointer associated with the control. The variable
 209        pointed to by this is autamatically updated with the current value of
 210        the scroll bar.
 211      */
 212     void SetValuePointer(
 213       PSCROLLBAR_VALUE * ptr //New value pointer to associate with the control.
 214     );
 215
 216
 217    /**Set the maximum thumb position of the scroll bar. If the
 218        #redraw# parameter is TRUE then this will be updated on the
 219        screen immediately (within OS constraints).
 220      */
 221     void SetMaximum(
 222       PSCROLLBAR_VALUE val,   /// New maximum value for the scroll bar.
 223       BOOL redraw = TRUE      /// Whether to update the screen.
 224     );
 225
 226    /**Get the maximum thumb position of the scroll bar.
 227
 228        @return
 229        current scroll bar maximum.
 230      */
 231     PSCROLLBAR_VALUE GetMaximum() const;
 232
 233    /**Set the minimum thumb position of the scroll bar. If the
 234        #redraw# parameter is TRUE then this will be updated on the
 235        screen immediately (within OS constraints).
 236      */
 237     void SetMinimum(
 238       PSCROLLBAR_VALUE val,   /// New minimum value for the scroll bar.
 239       BOOL redraw = TRUE      /// Whether to update the screen.
 240     );
 241
 242    /**Get the minimum thumb position of the scroll bar.
 243
 244        @return
 245        current scroll bar minimum.
 246      */
 247     PSCROLLBAR_VALUE GetMinimum() const;
 248
 249    /**Set the the amount by which the up and down arrows will move the thumb
 250        each time the are clicked. The up and down arrow keys do the same thing
 251        if the scroll bar has the focus.
 252      */
 253     void SetSmallNudge(
 254       PSCROLLBAR_VALUE val    /// New nudge value for small increments.
 255     );
 256
 257    /**Get the the amount by with the up and down arrows will move the thumb.
 258
 259        @return
 260        small nudge value.
 261      */
 262     PSCROLLBAR_VALUE GetSmallNudge() const;
 263
 264    /**Set the the amount by which clicking above or below the thumb will move
 265        it. The page up and page down keys do the same thing if the scroll bar
 266        has the focus.
 267      */
 268     void SetLargeNudge(
 269       PSCROLLBAR_VALUE val    /// New nudge value for large increments.
 270     );
 271
 272    /**Get the the amount by which clicking above or below the thumb will
 273        move it.
 274
 275        @return
 276        large nudge value.
 277      */
 278     PSCROLLBAR_VALUE GetLargeNudge() const;
 279
 280
 281   protected:
 282     /**@name Member variables */
 283     PSCROLLBAR_VALUE minimum;
 284     PSCROLLBAR_VALUE maximum;
 285     PSCROLLBAR_VALUE value;
 286     PSCROLLBAR_VALUE smallNudge;
 287     PSCROLLBAR_VALUE largeNudge;
 288       /* Small and large nudge amounts. */
 289
 290
 291   private:
 292     // New functions for class
 293     void Construct();
 294       // Common constructor code
 295
 296
 297 // Include platform dependent part of class
 298 #include <pwlib/scrollb.h>
 299 };
 300
 301
 302 // End Of File ///////////////////////////////////////////////////////////////