docs/doxygen/overviews/scrolling.h

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