[wxWidgets.git] / docs / doxygen / overviews / scrolling.h

/////////////////////////////////////////////////////////////////////////////
// Name:        scrolling
// Purpose:     topic overview
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/*!

 @page scrolling_overview Scrolling overview

 Classes: #wxWindow, #wxScrolledWindow, #wxIcon, #wxScrollBar.
 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 wxTextCtrl.
 Because any class derived from  #wxWindow 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
 wxWindow in fact doesn't have any default functionality to handle scroll events.
 If you created a wxWindow object with scrollbars, and then clicked on the scrollbars, nothing
 at all would happen. This is deliberate, because the @e interpretation of scroll
 events varies from one window class to another.
 #wxScrolledWindow (formerly wxCanvas) 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 wxWindow and
 implement scrolling yourself. #wxGrid is an example of a class
 that implements its own scrolling, largely because columns and rows can vary in size.
 @b The scrollbar model
 The function wxWindow::SetScrollbar gives a clue about
 the way a scrollbar is modeled. This function takes the following arguments:


 orientation


 Which scrollbar: wxVERTICAL or wxHORIZONTAL.


 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.


 @e orientation determines whether we're talking about
 the built-in horizontal or vertical scrollbar.
 @e 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.
 @e 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.
 @e 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.
 @e refresh just indicates whether the scrollbar should be repainted immediately or not.
 @b 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:

 @code
 SetScrollbar(wxVERTICAL, 0, 16, 50);
 @endcode


 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 #wxSizeEvent handler function.

 */
Commit	Line	Data
15b6757b FM	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: scrolling
	3	// Purpose: topic overview
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9	/*!
36c9828f	10
15b6757b	11	@page scrolling_overview Scrolling overview
36c9828f	12
15b6757b FM	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:
36c9828f FM	36
	37
	38
	39
	40
	41
15b6757b	42	orientation
36c9828f FM	43
	44
	45
	46
15b6757b	47	Which scrollbar: wxVERTICAL or wxHORIZONTAL.
36c9828f FM	48
	49
	50
	51
	52
15b6757b	53	position
36c9828f FM	54
	55
	56
	57
15b6757b	58	The position of the scrollbar in scroll units.
36c9828f FM	59
	60
	61
	62
	63
15b6757b	64	visible
36c9828f FM	65
	66
	67
	68
15b6757b	69	The size of the visible portion of the scrollbar, in scroll units.
36c9828f FM	70
	71
	72
	73
	74
15b6757b	75	range
36c9828f FM	76
	77
	78
	79
15b6757b	80	The maximum position of the scrollbar.
36c9828f FM	81
	82
	83
	84
	85
15b6757b	86	refresh
36c9828f FM	87
	88
	89
	90
15b6757b	91	Whether the scrollbar should be repainted.
36c9828f FM	92
	93
	94
	95
15b6757b FM	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:
36c9828f	113
15b6757b FM	114	@code
	115	SetScrollbar(wxVERTICAL, 0, 16, 50);
	116	@endcode
36c9828f FM	117
36c9828f FM	118
15b6757b FM	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.
36c9828f	128
15b6757b	129	*/
36c9828f FM	130
36c9828f FM	131