.. include:: headings.inc


.. _scrolled windows:

=================================================
|phoenix_title|  **Scrolled Windows Overview**
=================================================


Scrollbars come in various guises in wxWidgets. All windows have the
potential to show a vertical scrollbar and/or a horizontal scrollbar:
it is a basic capability of a window. However, in practice, not all
windows do make use of scrollbars, such as a single-line
:ref:`wx.TextCtrl`.

Because any class derived from :ref:`wx.Window` may have scrollbars,
there are functions to manipulate the scrollbars and event handlers to
intercept scroll events. But just because a window generates a scroll
event, doesn't mean that the window necessarily handles it and
physically scrolls the window. The base class :ref:`wx.Window` in fact
doesn't have any default functionality to handle scroll events. If you
created a :ref:`wx.Window` object with scrollbars, and then clicked on
the scrollbars, nothing at all would happen. This is deliberate,
because the interpretation of scroll events varies from one window
class to another.

:ref:`wx.ScrolledWindow` is an example of a window that adds
functionality to make scrolling really work. It assumes that scrolling
happens in consistent units, not different-sized jumps, and that page
size is represented by the visible portion of the window.  It is
suited to drawing applications, but perhaps not so suitable for a
sophisticated editor in which the amount scrolled may vary according
to the size of text on a given line. For this, you would derive from
:ref:`wx.Window` and implement scrolling yourself.
:ref:`wx.grid.Grid` is an example of a class that implements its own
scrolling, largely because columns and rows can vary in size.


The Scrollbar Model
-------------------

The function :meth:`wx.Window.SetScrollbar` gives a clue about the way
a scrollbar is modeled. This function takes the following arguments:

=================== ===================================
`orientation`	    Which scrollbar: ``wx.VERTICAL`` or ``wx.HORIZONTAL``.
`position`	    The position of the scrollbar in scroll units.
`visible`	    The size of the visible portion of the scrollbar, in scroll units.
`range`	            The maximum position of the scrollbar.
`refresh`	    Whether the scrollbar should be repainted.
=================== ===================================

`orientation` determines whether we're talking about the built-in
horizontal or vertical scrollbar.

`position` is simply the position of the 'thumb' (the bit you drag to
scroll around). It is given in scroll units, and so is relative to the
total range of the scrollbar.

`visible` gives the number of scroll units that represents the portion
of the window currently visible. Normally, a scrollbar is capable of
indicating this visually by showing a different length of thumb.

`range` is the maximum value of the scrollbar, where zero is the start
position. You choose the units that suit you, so if you wanted to
display text that has 100 lines, you would set this to 100. Note that
this doesn't have to correspond to the number of pixels scrolled - it
is up to you how you actually show the contents of the window.

`refresh` just indicates whether the scrollbar should be repainted
immediately or not.


An Example
----------

Let's say you wish to display 50 lines of text, using the same
font. The window is sized so that you can only see 16 lines at a
time. You would use::

    SetScrollbar(wx.VERTICAL, 0, 16, 50)


.. note:: Note that with the window at this size, the thumb position
   can never go above 50 minus 16, or 34. You can determine how many
   lines are currently visible by dividing the current view size by
   the character height in pixels.

When defining your own scrollbar behaviour, you will always need to
recalculate the scrollbar settings when the window size changes. You
could therefore put your scrollbar calculations and `SetScrollbar`
call into a function named `AdjustScrollbars`, which can be called
initially and also from your :ref:`wx.SizeEvent` handler function.