docs/latex/wx/varscrollhelperbase.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        varscrollhelperbase.tex
   3 %% Purpose:     wxVarScrollHelperBase Documentation
   4 %% Author:      Bryan Petty
   5 %% Modified by:
   6 %% Created:     2007-04-04
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) 2007 wxWidgets Team
   9 %% License:     wxWindows Licence
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxVarScrollHelperBase}}\label{wxvarscrollhelperbase}
  13
  14 This class provides all common base functionality for scroll calculations
  15 shared among all variable scrolled window implementations as well as
  16 automatic scrollbar functionality, saved scroll positions, controlling
  17 target windows to be scrolled, as well as defining all required virtual
  18 functions that need to be implemented for any orientation specific work.
  19
  20 Documentation of this class is provided specifically for referencing use
  21 of the functions provided by this class for use with the variable scrolled
  22 windows that derive from here. You will likely want to derive your window
  23 from one of the already implemented variable scrolled windows rather than
  24 from wxVarScrollHelperBase directly.
  25
  26 \wxheading{Include files}
  27
  28 <wx/vscroll.h>
  29
  30 \wxheading{See also}
  31
  32 \helpref{wxHScrolledWindow}{wxhscrolledwindow},
  33 \rtfsp\helpref{wxHVScrolledWindow}{wxhvscrolledwindow},
  34 \rtfsp\helpref{wxVScrolledWindow}{wxvscrolledwindow}
  35
  36 \latexignore{\rtfignore{\wxheading{Members}}}
  37
  38
  39 \membersection{wxVarScrollHelperBase::wxVarScrollHelperBase}\label{wxvarscrollhelperbasewxvarscrollhelperbase}
  40
  41 \func{}{wxVarScrollHelperBase}{\param{wxWindow* }{winToScroll}}
  42
  43 Constructor taking the target window to be scrolled by this helper class.
  44 This will attach scroll event handlers to the target window to catch and
  45 handle scroll events appropriately.
  46
  47
  48 \membersection{wxVarScrollHelperBase::\destruct{wxVarScrollHelperBase}}\label{wxvarscrollhelperbasedtor}
  49
  50 \func{virtual }{\destruct{wxVarScrollHelperBase}}{\void}
  51
  52 Virtual destructor for detaching scroll event handlers attached with this
  53 helper class.
  54
  55
  56 \membersection{wxVarScrollHelperBase::CalcScrolledPosition}\label{wxvarscrollhelperbasecalcscrolledposition}
  57
  58 \constfunc{int}{CalcScrolledPosition}{\param{int }{coord}}
  59
  60 Translates the logical coordinate given to the current device coordinate.
  61 For example, if the window is scrolled 10 units and each scroll unit
  62 represents 10 device units (which may not be the case since this class allows
  63 for variable scroll unit sizes), a call to this function with a coordinate of
  64 15 will return -85.
  65
  66 \wxheading{See also}
  67
  68 \helpref{CalcUnscrolledPosition()}{wxvarscrollhelperbasecalcunscrolledposition}
  69
  70
  71 \membersection{wxVarScrollHelperBase::CalcUnscrolledPosition}\label{wxvarscrollhelperbasecalcunscrolledposition}
  72
  73 \constfunc{int}{CalcUnscrolledPosition}{\param{int }{coord}}
  74
  75 Translates the device coordinate given to the corresponding logical
  76 coordinate. For example, if the window is scrolled 10 units and each scroll
  77 unit represents 10 device units (which may not be the case since this class
  78 allows for variable scroll unit sizes), a call to this function with a
  79 coordinate of 15 will return 115.
  80
  81 \wxheading{See also}
  82
  83 \helpref{CalcScrolledPosition()}{wxvarscrollhelperbasecalcscrolledposition}
  84
  85
  86 \membersection{wxVarScrollHelperBase::EnablePhysicalScrolling}\label{wxvarscrollhelperbaseenablephysicalscrolling}
  87
  88 \func{void}{EnablePhysicalScrolling}{\param{bool }{scrolling = true}}
  89
  90 With physical scrolling on (when this is {\tt true}), the device origin is
  91 changed properly when a \rtfsp\helpref{wxPaintDC}{wxpaintdc} is prepared,
  92 children are actually moved and laid out properly, and the contents of the
  93 window (pixels) are actually moved. When this is {\tt false}, you are
  94 responsible for repainting any invalidated areas of the window yourself to
  95 account for the new scroll position.
  96
  97
  98 \membersection{wxVarScrollHelperBase::EstimateTotalSize}\label{wxvarscrollhelperbaseestimatetotalsize}
  99
 100 \constfunc{virtual wxCoord}{EstimateTotalSize}{\void}
 101
 102 When the number of scroll units change, we try to estimate the total size of
 103 all units when the full window size is needed (i.e. to calculate the scrollbar
 104 thumb size). This is a rather expensive operation in terms of unit access, so
 105 if the user code may estimate the average size better or faster than we do, it
 106 should override this function to implement its own logic. This function should
 107 return the best guess for the total virtual window size.
 108
 109 Note that although returning a totally wrong value would still work, it risks
 110 resulting in very strange scrollbar behaviour so this function should really
 111 try to make the best guess possible.
 112
 113
 114 \membersection{wxVarScrollHelperBase::GetNonOrientationTargetSize}\label{wxvarscrollhelperbasegetnonorientationtargetsize}
 115
 116 \constfunc{virtual int}{GetNonOrientationTargetSize}{\void}
 117
 118 This function needs to be overridden in the in the derived class to return the
 119 window size with respect to the opposing orientation. If this is a vertical
 120 scrolled window, it should return the height.
 121
 122 \wxheading{See also}
 123
 124 \helpref{GetOrientationTargetSize()}{wxvarscrollhelperbasegetorientationtargetsize}
 125
 126
 127 \membersection{wxVarScrollHelperBase::GetOrientation}\label{wxvarscrollhelperbasegetorientation}
 128
 129 \constfunc{virtual wxOrientation}{GetOrientation}{\void}
 130
 131 This function need to be overridden to return the orientation that this helper
 132 is working with, either {\tt wxHORIZONTAL} or {\tt wxVERTICAL}.
 133
 134
 135 \membersection{wxVarScrollHelperBase::GetOrientationTargetSize}\label{wxvarscrollhelperbasegetorientationtargetsize}
 136
 137 \constfunc{virtual int}{GetOrientationTargetSize}{\void}
 138
 139 This function needs to be overridden in the in the derived class to return the
 140 window size with respect to the orientation this helper is working with. If
 141 this is a vertical scrolled window, it should return the width.
 142
 143 \wxheading{See also}
 144
 145 \helpref{GetNonOrientationTargetSize()}{wxvarscrollhelperbasegetnonorientationtargetsize}
 146
 147
 148 \membersection{wxVarScrollHelperBase::GetTargetWindow}\label{wxvarscrollhelperbasegettargetwindow}
 149
 150 \constfunc{wxWindow*}{GetTargetWindow}{\void}
 151
 152 This function will return the target window this helper class is currently
 153 scrolling.
 154
 155 \wxheading{See also}
 156
 157 \helpref{SetTargetWindow()}{wxvarscrollhelperbasesettargetwindow}
 158
 159
 160 \membersection{wxVarScrollHelperBase::GetVisibleBegin}\label{wxvarscrollhelperbasegetvisiblebegin}
 161
 162 \constfunc{size\_t}{GetVisibleBegin}{\void}
 163
 164 Returns the index of the first visible unit based on the scroll position.
 165
 166
 167 \membersection{wxVarScrollHelperBase::GetVisibleEnd}\label{wxvarscrollhelperbasegetvisibleend}
 168
 169 \constfunc{size\_t}{GetVisibleEnd}{\void}
 170
 171 Returns the index of the last visible unit based on the scroll position. This
 172 includes the last unit even if it is only partially visible.
 173
 174
 175 \membersection{wxVarScrollHelperBase::HitTest}\label{wxvarscrollhelperbasehittest}
 176
 177 \constfunc{virtual int}{HitTest}{\param{wxCoord }{coord}}
 178
 179 Returns the scroll unit under the device unit given accounting for scroll
 180 position or {\tt wxNOT\_FOUND} if none (i.e. if it is below the last item).
 181
 182
 183 \membersection{wxVarScrollHelperBase::IsVisible}\label{wxvarscrollhelperbaseisvisible}
 184
 185 \constfunc{bool}{IsVisible}{\param{size\_t }{unit}}
 186
 187 Returns {\tt true} if the given scroll unit is currently visible (even if only
 188 partially visible) or {\tt false} otherwise.
 189
 190
 191 \membersection{wxVarScrollHelperBase::OnGetUnitSize}\label{wxvarscrollhelperbaseongetunitsize}
 192
 193 \constfunc{virtual wxCoord}{OnGetUnitSize}{\param{size\_t }{unit}}
 194
 195 This function must be overridden in the derived class, and should return the
 196 size of the given unit in pixels.
 197
 198
 199 \membersection{wxVarScrollHelperBase::OnGetUnitsSizeHint}\label{wxvarscrollhelperbaseongetunitssizehint}
 200
 201 \constfunc{virtual void}{OnGetUnitsSizeHint}{\param{size\_t }{unitMin}, \param{size\_t }{unitMax}}
 202
 203 This function doesn't have to be overridden but it may be useful to do so if
 204 calculating the units' sizes is a relatively expensive operation as it gives
 205 your code a chance to calculate several of them at once and cache the result
 206 if necessary.
 207
 208 {\tt OnGetUnitsSizeHint()} is normally called just before
 209 \helpref{OnGetUnitSize()}{wxvarscrollhelperbaseongetunitsize} but you
 210 shouldn't rely on the latter being called for all units in the interval
 211 specified here. It is also possible that OnGetUnitSize() will be called for
 212 units outside of this interval, so this is really just a hint, not a promise.
 213
 214 Finally, note that unitMin is inclusive, while unitMax is exclusive.
 215
 216
 217 \membersection{wxVarScrollHelperBase::RefreshAll}\label{wxvarscrollhelperbaserefreshall}
 218
 219 \func{virtual void}{RefreshAll}{\void}
 220
 221 Recalculate all parameters and repaint all units.
 222
 223
 224 \membersection{wxVarScrollHelperBase::SetTargetWindow}\label{wxvarscrollhelperbasesettargetwindow}
 225
 226 \func{void}{SetTargetWindow}{\param{wxWindow* }{target}}
 227
 228 Normally the window will scroll itself, but in some rare occasions you might
 229 want it to scroll (part of) another window (e.g. a child of it in order to
 230 scroll only a portion the area between the scrollbars like a spreadsheet where
 231 only the cell area will move).
 232
 233 \wxheading{See also}
 234
 235 \helpref{GetTargetWindow()}{wxvarscrollhelperbasegettargetwindow}
 236
 237
 238 \membersection{wxVarScrollHelperBase::UpdateScrollbar}\label{wxvarscrollhelperbaseupdatescrollbar}
 239
 240 \func{virtual void}{UpdateScrollbar}{\void}
 241
 242 Update the thumb size shown by the scrollbar.
 243