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{See also}
  53
  54 \helpref{wxHScrolledWindow}{wxhscrolledwindow},
  55 \rtfsp\helpref{wxHVScrolledWindow}{wxhvscrolledwindow}
  56
  57 \latexignore{\rtfignore{\wxheading{Members}}}
  58
  59
  60 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  61 %% wxVarVScrollLegacyAdapter Compatibility Functions
  62 %% This section will need to be removed when 2.8 compatibility is removed.
  63 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  64
  65 \membersection{wxWidgets 2.6 and 2.8 Compatibility Functions}\label{wxvscrolledwindowbackwardcompatibility}
  66
  67 The following functions provide backwards compatibility for applications
  68 originally built using wxVScrolledWindow in 2.6 or 2.8. Originally,
  69 wxVScrolledWindow referred to scrolling "lines". We now use "units" in
  70 wxVarScrollHelperBase to avoid implying any orientation (since the functions
  71 are used for both horizontal and vertical scrolling in derived classes). And
  72 in the new wxVScrolledWindow and wxHScrolledWindow classes, we refer to them
  73 as "rows" and "columns", respectively. This is to help clear some confusion
  74 in not only those classes, but also in wxHVScrolledWindow where functions
  75 are inherited from both.
  76
  77 You are encouraged to update any existing code using these function to use
  78 the new replacements mentioned below, and avoid using these functions for
  79 any new code as they are deprecated.
  80
  81 \constfunc{size\_t}{GetFirstVisibleLine}{\void}
  82
  83 Deprecated for \helpref{GetVisibleRowsBegin()}{wxvarvscrollhelpergetvisiblerowsbegin}.
  84
  85 \constfunc{size\_t}{GetLastVisibleLine}{\void}
  86
  87 Deprecated for \helpref{GetVisibleRowsEnd()}{wxvarvscrollhelpergetvisiblerowsend}.
  88
  89 This function originally had a slight design flaw in that it was possible to
  90 return \texttt{(size\_t)-1} (ie: a large positive number) if the scroll
  91 position was 0 and the first line wasn't completely visible.
  92
  93 \constfunc{size\_t}{GetLineCount}{\void}
  94
  95 Deprecated for \helpref{GetRowCount()}{wxvarvscrollhelpergetrowcount}.
  96
  97 \constfunc{int}{HitTest}{\param{wxCoord }{x}, \param{wxCoord }{y}}
  98 \constfunc{int}{HitTest}{\param{const wxPoint\& }{pt}}
  99
 100 Deprecated for \helpref{VirtualHitTest()}{wxvarscrollhelperbasevirtualhittest}.
 101
 102 \constfunc{virtual wxCoord}{OnGetLineHeight}{\param{size\_t }{line}}
 103
 104 Deprecated for \helpref{OnGetRowHeight()}{wxvarvscrollhelperongetrowheight}.
 105
 106 \constfunc{virtual void}{OnGetLinesHint}{\param{size\_t }{lineMin}, \param{size\_t }{lineMax}}
 107
 108 Deprecated for \helpref{OnGetRowsHeightHint()}{wxvarvscrollhelperongetrowsheighthint}.
 109
 110 \func{virtual void}{RefreshLine}{\param{size\_t }{line}}
 111
 112 Deprecated for \helpref{RefreshRow()}{wxvarvscrollhelperrefreshrow}.
 113
 114 \func{virtual void}{RefreshLines}{\param{size\_t }{from}, \param{size\_t }{to}}
 115
 116 Deprecated for \helpref{RefreshRows()}{wxvarvscrollhelperrefreshrows}.
 117
 118 \func{virtual bool}{ScrollLines}{\param{int }{lines}}
 119
 120 Deprecated for \helpref{ScrollRows()}{wxvarvscrollhelperscrollrows}.
 121
 122 \func{virtual bool}{ScrollPages}{\param{int }{pages}}
 123
 124 Deprecated for \helpref{ScrollRowPages()}{wxvarvscrollhelperscrollrowpages}.
 125
 126 \func{bool}{ScrollToLine}{\param{size\_t }{line}}
 127
 128 Deprecated for \helpref{ScrollToRow()}{wxvarvscrollhelperscrolltorow}.
 129
 130 \func{void}{SetLineCount}{\param{size\_t }{count}}
 131
 132 Deprecated for \helpref{SetRowCount()}{wxvarvscrollhelpersetrowcount}.
 133
 134 %%%%%%%%%%%%%%%%%%%%%%% END COMPATIBILITY FUNCTIONS %%%%%%%%%%%%%%%%%%%%%%%%%%
 135 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 136
 137
 138 \membersection{wxVScrolledWindow::wxVScrolledWindow}\label{wxvscrolledwindowwxvscrolledwindow}
 139
 140 \func{}{wxVScrolledWindow}{\void}
 141
 142 Default constructor, you must call \helpref{Create()}{wxvscrolledwindowcreate}
 143 later.
 144
 145 \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}}
 146
 147 This is the normal constructor, no need to call {\tt Create()} after using this one.
 148
 149 Note that {\tt wxVSCROLL} is always automatically added to our style, there is
 150 no need to specify it explicitly.
 151
 152 \wxheading{Parameters}
 153
 154 \docparam{parent}{The parent window, must not be {\tt NULL}}
 155
 156 \docparam{id}{The identifier of this window, {\tt wxID\_ANY} by default}
 157
 158 \docparam{pos}{The initial window position}
 159
 160 \docparam{size}{The initial window size}
 161
 162 \docparam{style}{The window style. There are no special style bits defined for
 163 this class.}
 164
 165 \docparam{name}{The name for this window; usually not used}
 166
 167
 168 \membersection{wxVScrolledWindow::Create}\label{wxvscrolledwindowcreate}
 169
 170 \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}}
 171
 172 Same as the \helpref{non-default constuctor}{wxvscrolledwindowwxvscrolledwindow}
 173 but returns status code: {\tt true} if ok, {\tt false} if the window couldn't
 174 be created.
 175
 176 Just as with the constructor above, the {\tt wxVSCROLL} style is always used,
 177 there is no need to specify it explicitly.
 178