docs/latex/wx/vscrolledwindow.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        vscrolledwindow.tex (moved from vscroll.tex)
   3 %% Purpose:     wxVScrolledWindow Documentation
   4 %% Author:      Vadim Zeitlin, Bryan Petty
   5 %% Modified by:
   6 %% Created:     2003-05-30, modified 2007-04-04
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) 2003, 2007 wxWidgets Team
   9 %% License:     wxWindows Licence
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxVScrolledWindow}}\label{wxvscrolledwindow}
  13
  14 In the name of this class, "V" may stand for "variable" because it can be
  15 used for scrolling rows of variable heights; "virtual", because it is not
  16 necessary to know the heights of all rows in advance -- only those which
  17 are shown on the screen need to be measured; or even "vertical", because
  18 this class only supports scrolling vertically.
  19
  20 In any case, this is a generalization of the
  21 \helpref{wxScrolledWindow}{wxscrolledwindow} class which can be only used when
  22 all rows have the same heights. It lacks some other wxScrolledWindow features
  23 however, notably it can't scroll only a rectangle of the window and not its
  24 entire client area.
  25
  26 To use this class, you need to derive from it and implement the
  27 \helpref{OnGetRowHeight()}{wxvarvscrollhelperongetrowheight} pure virtual
  28 method. You also must call \helpref{SetRowCount}{wxvarvscrollhelpersetrowcount}
  29 to let the base class know how many rows it should display, but from that
  30 moment on the scrolling is handled entirely by wxVScrolledWindow. You only
  31 need to draw the visible part of contents in your {\tt OnPaint()} method as
  32 usual. You should use \helpref{GetVisibleRowsBegin()}{wxvarvscrollhelpergetvisiblerowsbegin}
  33 and \helpref{GetVisibleRowsEnd()}{wxvarvscrollhelpergetvisiblerowsend} to
  34 select the lines to display. Note that the device context origin is not shifted
  35 so the first visible row always appears at the point $(0, 0)$ in physical as
  36 well as logical coordinates.
  37
  38 \wxheading{Derived from}
  39
  40 \helpref{wxPanel}{wxpanel}\\
  41 \helpref{wxWindow}{wxwindow}\\
  42 \helpref{wxEvtHandler}{wxevthandler}\\
  43 \helpref{wxObject}{wxobject}
  44
  45 \helpref{wxVarVScrollHelper}{wxvarvscrollhelper}\\
  46 \helpref{wxVarScrollHelperBase}{wxvarscrollhelperbase}
  47
  48 \wxheading{Include files}
  49
  50 <wx/vscroll.h>
  51
  52 \wxheading{Library}
  53
  54 \helpref{wxCore}{librarieslist}
  55
  56 \wxheading{See also}
  57
  58 \helpref{wxHScrolledWindow}{wxhscrolledwindow},
  59 \rtfsp\helpref{wxHVScrolledWindow}{wxhvscrolledwindow}
  60
  61 \latexignore{\rtfignore{\wxheading{Members}}}
  62
  63
  64 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  65 %% wxVarVScrollLegacyAdapter Compatibility Functions
  66 %% This section will need to be removed when 2.8 compatibility is removed.
  67 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  68
  69 \membersection{wxWidgets 2.6 and 2.8 Compatibility Functions}\label{wxvscrolledwindowbackwardcompatibility}
  70
  71 The following functions provide backwards compatibility for applications
  72 originally built using wxVScrolledWindow in 2.6 or 2.8. Originally,
  73 wxVScrolledWindow referred to scrolling "lines". We now use "units" in
  74 wxVarScrollHelperBase to avoid implying any orientation (since the functions
  75 are used for both horizontal and vertical scrolling in derived classes). And
  76 in the new wxVScrolledWindow and wxHScrolledWindow classes, we refer to them
  77 as "rows" and "columns", respectively. This is to help clear some confusion
  78 in not only those classes, but also in wxHVScrolledWindow where functions
  79 are inherited from both.
  80
  81 You are encouraged to update any existing code using these function to use
  82 the new replacements mentioned below, and avoid using these functions for
  83 any new code as they are deprecated.
  84
  85 \constfunc{size\_t}{GetFirstVisibleLine}{\void}
  86
  87 Deprecated for \helpref{GetVisibleRowsBegin()}{wxvarvscrollhelpergetvisiblerowsbegin}.
  88
  89 \constfunc{size\_t}{GetLastVisibleLine}{\void}
  90
  91 Deprecated for \helpref{GetVisibleRowsEnd()}{wxvarvscrollhelpergetvisiblerowsend}.
  92
  93 This function originally had a slight design flaw in that it was possible to
  94 return \texttt{(size\_t)-1} (ie: a large positive number) if the scroll
  95 position was 0 and the first line wasn't completely visible.
  96
  97 \constfunc{size\_t}{GetLineCount}{\void}
  98
  99 Deprecated for \helpref{GetRowCount()}{wxvarvscrollhelpergetrowcount}.
 100
 101 \constfunc{int}{HitTest}{\param{wxCoord }{x}, \param{wxCoord }{y}}
 102 \constfunc{int}{HitTest}{\param{const wxPoint\& }{pt}}
 103
 104 Deprecated for \helpref{VirtualHitTest()}{wxvarscrollhelperbasevirtualhittest}.
 105
 106 \constfunc{virtual wxCoord}{OnGetLineHeight}{\param{size\_t }{line}}
 107
 108 Deprecated for \helpref{OnGetRowHeight()}{wxvarvscrollhelperongetrowheight}.
 109
 110 \constfunc{virtual void}{OnGetLinesHint}{\param{size\_t }{lineMin}, \param{size\_t }{lineMax}}
 111
 112 Deprecated for \helpref{OnGetRowsHeightHint()}{wxvarvscrollhelperongetrowsheighthint}.
 113
 114 \func{virtual void}{RefreshLine}{\param{size\_t }{line}}
 115
 116 Deprecated for \helpref{RefreshRow()}{wxvarvscrollhelperrefreshrow}.
 117
 118 \func{virtual void}{RefreshLines}{\param{size\_t }{from}, \param{size\_t }{to}}
 119
 120 Deprecated for \helpref{RefreshRows()}{wxvarvscrollhelperrefreshrows}.
 121
 122 \func{virtual bool}{ScrollLines}{\param{int }{lines}}
 123
 124 Deprecated for \helpref{ScrollRows()}{wxvarvscrollhelperscrollrows}.
 125
 126 \func{virtual bool}{ScrollPages}{\param{int }{pages}}
 127
 128 Deprecated for \helpref{ScrollRowPages()}{wxvarvscrollhelperscrollrowpages}.
 129
 130 \func{bool}{ScrollToLine}{\param{size\_t }{line}}
 131
 132 Deprecated for \helpref{ScrollToRow()}{wxvarvscrollhelperscrolltorow}.
 133
 134 \func{void}{SetLineCount}{\param{size\_t }{count}}
 135
 136 Deprecated for \helpref{SetRowCount()}{wxvarvscrollhelpersetrowcount}.
 137
 138 %%%%%%%%%%%%%%%%%%%%%%% END COMPATIBILITY FUNCTIONS %%%%%%%%%%%%%%%%%%%%%%%%%%
 139 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 140
 141
 142 \membersection{wxVScrolledWindow::wxVScrolledWindow}\label{wxvscrolledwindowwxvscrolledwindow}
 143
 144 \func{}{wxVScrolledWindow}{\void}
 145
 146 Default constructor, you must call \helpref{Create()}{wxvscrolledwindowcreate}
 147 later.
 148
 149 \func{}{wxVScrolledWindow}{\param{wxWindow* }{parent}, \param{wxWindowID }{id = wxID\_ANY}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = 0}, \param{const wxString\& }{name = wxPanelNameStr}}
 150
 151 This is the normal constructor, no need to call {\tt Create()} after using this one.
 152
 153 Note that {\tt wxVSCROLL} is always automatically added to our style, there is
 154 no need to specify it explicitly.
 155
 156 \wxheading{Parameters}
 157
 158 \docparam{parent}{The parent window, must not be {\tt NULL}}
 159
 160 \docparam{id}{The identifier of this window, {\tt wxID\_ANY} by default}
 161
 162 \docparam{pos}{The initial window position}
 163
 164 \docparam{size}{The initial window size}
 165
 166 \docparam{style}{The window style. There are no special style bits defined for
 167 this class.}
 168
 169 \docparam{name}{The name for this window; usually not used}
 170
 171
 172 \membersection{wxVScrolledWindow::Create}\label{wxvscrolledwindowcreate}
 173
 174 \func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID }{id = wxID\_ANY}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = 0}, \param{const wxString\& }{name = wxPanelNameStr}}
 175
 176 Same as the \helpref{non-default constuctor}{wxvscrolledwindowwxvscrolledwindow}
 177 but returns status code: {\tt true} if ok, {\tt false} if the window couldn't
 178 be created.
 179
 180 Just as with the constructor above, the {\tt wxVSCROLL} style is always used,
 181 there is no need to specify it explicitly.
 182