X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/15b6757b26a0277472a4f6b071b52050abd922da..1d156af3247c862e51a7c62f569a3fd302052a42:/docs/doxygen/overviews/scrolling.h diff --git a/docs/doxygen/overviews/scrolling.h b/docs/doxygen/overviews/scrolling.h index ddc732e8e3..c28cd77248 100644 --- a/docs/doxygen/overviews/scrolling.h +++ b/docs/doxygen/overviews/scrolling.h @@ -1,131 +1,101 @@ ///////////////////////////////////////////////////////////////////////////// -// Name: scrolling +// Name: scrolling.h // Purpose: topic overview // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// -/*! - - @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. - - */ - - +/** + +@page overview_scrolling Scrolled Windows + +Classes: wxWindow, wxScrolledWindow, wxScrollBar + +@li @ref overview_scrolling_model +@li @ref overview_scrolling_example + +
+ + +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. + + +@section overview_scrolling_model The Scrollbar Model + +The function wxWindow::SetScrollbar gives a clue about the way a scrollbar is +modeled. This function takes the following arguments: + +@beginTable +@row2col{ @c orientation , Which scrollbar: wxVERTICAL or wxHORIZONTAL. } +@row2col{ @c position , The position of the scrollbar in scroll units. } +@row2col{ @c visible , The size of the visible portion of the scrollbar, + in scroll units. } +@row2col{ @c range , The maximum position of the scrollbar. } +@row2col{ @c refresh , Whether the scrollbar should be repainted. } +@endTable + +@c orientation determines whether we're talking about the built-in horizontal +or vertical scrollbar. + +@c 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. + +@c 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. + +@c 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. + +@c refresh just indicates whether the scrollbar should be repainted immediately +or not. + + +@section overview_scrolling_example 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. + +*/ +