docs/doxygen/overviews/scrolling.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        scrolling
   3 // Purpose:     topic overview
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /*!
  10
  11  @page scrolling_overview Scrolling overview
  12
  13  Classes: #wxWindow, #wxScrolledWindow, #wxIcon, #wxScrollBar.
  14  Scrollbars come in various guises in wxWidgets. All windows have the potential
  15  to show a vertical scrollbar and/or a horizontal scrollbar: it is a basic capability of a window.
  16  However, in practice, not all windows do make use of scrollbars, such as a single-line wxTextCtrl.
  17  Because any class derived from  #wxWindow may have scrollbars,
  18  there are functions to manipulate the scrollbars and event handlers to intercept
  19  scroll events. But just because a window generates a scroll event, doesn't mean
  20  that the window necessarily handles it and physically scrolls the window. The base class
  21  wxWindow in fact doesn't have any default functionality to handle scroll events.
  22  If you created a wxWindow object with scrollbars, and then clicked on the scrollbars, nothing
  23  at all would happen. This is deliberate, because the @e interpretation of scroll
  24  events varies from one window class to another.
  25  #wxScrolledWindow (formerly wxCanvas) is an example of a window that
  26  adds functionality to make scrolling really work. It assumes that scrolling happens in
  27  consistent units, not different-sized jumps, and that page size is represented
  28  by the visible portion of the window. It is suited to drawing applications, but perhaps
  29  not so suitable for a sophisticated editor in which the amount scrolled may vary according
  30  to the size of text on a given line. For this, you would derive from wxWindow and
  31  implement scrolling yourself. #wxGrid is an example of a class
  32  that implements its own scrolling, largely because columns and rows can vary in size.
  33  @b The scrollbar model
  34  The function wxWindow::SetScrollbar gives a clue about
  35  the way a scrollbar is modeled. This function takes the following arguments:
  36
  37
  38
  39
  40
  41
  42  orientation
  43
  44
  45
  46
  47  Which scrollbar: wxVERTICAL or wxHORIZONTAL.
  48
  49
  50
  51
  52
  53  position
  54
  55
  56
  57
  58  The position of the scrollbar in scroll units.
  59
  60
  61
  62
  63
  64  visible
  65
  66
  67
  68
  69  The size of the visible portion of the scrollbar, in scroll units.
  70
  71
  72
  73
  74
  75  range
  76
  77
  78
  79
  80  The maximum position of the scrollbar.
  81
  82
  83
  84
  85
  86  refresh
  87
  88
  89
  90
  91  Whether the scrollbar should be repainted.
  92
  93
  94
  95
  96  @e orientation determines whether we're talking about
  97  the built-in horizontal or vertical scrollbar.
  98  @e position is simply the position of the 'thumb' (the bit you drag to scroll around).
  99  It is given in scroll units, and so is relative to the total range of the scrollbar.
 100  @e visible gives the number of scroll units that represents the portion of the
 101  window currently visible. Normally, a scrollbar is capable of indicating this visually
 102  by showing a different length of thumb.
 103  @e range is the maximum value of the scrollbar, where zero is the start
 104  position. You choose the units that suit you,
 105  so if you wanted to display text that has 100 lines, you would set this to 100.
 106  Note that this doesn't have to correspond to the number of pixels scrolled - it is
 107  up to you how you actually show the contents of the window.
 108  @e refresh just indicates whether the scrollbar should be repainted immediately or not.
 109  @b An example
 110  Let's say you wish to display 50 lines of text, using the same font.
 111  The window is sized so that you can only see 16 lines at a time.
 112  You would use:
 113
 114  @code
 115  SetScrollbar(wxVERTICAL, 0, 16, 50);
 116  @endcode
 117
 118
 119  Note that with the window at this size, the thumb position can never go
 120  above 50 minus 16, or 34.
 121  You can determine how many lines are currently visible by dividing the current view
 122  size by the character height in pixels.
 123  When defining your own scrollbar behaviour, you will always need to recalculate
 124  the scrollbar settings when the window size changes. You could therefore put your
 125  scrollbar calculations and SetScrollbar
 126  call into a function named AdjustScrollbars, which can be called initially and also
 127  from your #wxSizeEvent handler function.
 128
 129  */
 130
 131