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::VirtualHitTest}\label{wxvarscrollhelperbasevirtualhittest}
 176
 177 \constfunc{int}{VirtualHitTest}{\param{wxCoord }{coord}}
 178
 179 Returns the virtual scroll unit under the device unit given accounting for
 180 scroll position or {\tt wxNOT\_FOUND} if none (i.e. if it is below the last
 181 item).
 182
 183
 184 \membersection{wxVarScrollHelperBase::IsVisible}\label{wxvarscrollhelperbaseisvisible}
 185
 186 \constfunc{bool}{IsVisible}{\param{size\_t }{unit}}
 187
 188 Returns {\tt true} if the given scroll unit is currently visible (even if only
 189 partially visible) or {\tt false} otherwise.
 190
 191
 192 \membersection{wxVarScrollHelperBase::OnGetUnitSize}\label{wxvarscrollhelperbaseongetunitsize}
 193
 194 \constfunc{virtual wxCoord}{OnGetUnitSize}{\param{size\_t }{unit}}
 195
 196 This function must be overridden in the derived class, and should return the
 197 size of the given unit in pixels.
 198
 199
 200 \membersection{wxVarScrollHelperBase::OnGetUnitsSizeHint}\label{wxvarscrollhelperbaseongetunitssizehint}
 201
 202 \constfunc{virtual void}{OnGetUnitsSizeHint}{\param{size\_t }{unitMin}, \param{size\_t }{unitMax}}
 203
 204 This function doesn't have to be overridden but it may be useful to do so if
 205 calculating the units' sizes is a relatively expensive operation as it gives
 206 your code a chance to calculate several of them at once and cache the result
 207 if necessary.
 208
 209 {\tt OnGetUnitsSizeHint()} is normally called just before
 210 \helpref{OnGetUnitSize()}{wxvarscrollhelperbaseongetunitsize} but you
 211 shouldn't rely on the latter being called for all units in the interval
 212 specified here. It is also possible that OnGetUnitSize() will be called for
 213 units outside of this interval, so this is really just a hint, not a promise.
 214
 215 Finally, note that unitMin is inclusive, while unitMax is exclusive.
 216
 217
 218 \membersection{wxVarScrollHelperBase::RefreshAll}\label{wxvarscrollhelperbaserefreshall}
 219
 220 \func{virtual void}{RefreshAll}{\void}
 221
 222 Recalculate all parameters and repaint all units.
 223
 224
 225 \membersection{wxVarScrollHelperBase::SetTargetWindow}\label{wxvarscrollhelperbasesettargetwindow}
 226
 227 \func{void}{SetTargetWindow}{\param{wxWindow* }{target}}
 228
 229 Normally the window will scroll itself, but in some rare occasions you might
 230 want it to scroll (part of) another window (e.g. a child of it in order to
 231 scroll only a portion the area between the scrollbars like a spreadsheet where
 232 only the cell area will move).
 233
 234 \wxheading{See also}
 235
 236 \helpref{GetTargetWindow()}{wxvarscrollhelperbasegettargetwindow}
 237
 238
 239 \membersection{wxVarScrollHelperBase::UpdateScrollbar}\label{wxvarscrollhelperbaseupdatescrollbar}
 240
 241 \func{virtual void}{UpdateScrollbar}{\void}
 242
 243 Update the thumb size shown by the scrollbar.
 244