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