Scrolling


Scroll Bars

Scrolling is a difficult problem. WinX deals with the low level details of managing scrollbars, but the code that actually handles scrolling is the responsibilty of the application programmer.

WinX only supports scrollbars which are attached to a window. You cannot create scrollbar controls. In most instances you can replace these with trackers anyway. If you do need scrollbars inside the client area of a window, you will be able to do so in later versions of WinX via child windows.

Every window can potentially have up to two scrollbars. One for scrolling vertically and one for scrolling horizontally. The vertical scrollbar is displayed to the right of the window and the horizontal scrollbar is displayed at the bottom of the window. To enable scrolling, you must first display the appropriate scrollbars. Use the WinXScroll_Show function to acheive this.

Scrolling Concepts

Scrolling can be a difficult concept to visualise. You need a clear mental picture to understand basic scrolling concepts. Think of a large page underneath a small picture frame. The frame represents your window. When you scroll, you are moving the page around underneath the frame. The scrolling position is the position, in scrolling units, of the frame relative to the upper left hand corner of the page. If the frame is in the upper left hand corner, the scrolling position is (0,0).

The scrolling unit is the unit in which the page is measured. This can be whatever makes sense for the application. For example, a painting program would use pixels. A word processor might use points. It must be possible to map the scrolling units to pixels with a linear (mathematical) function. If you'll remember from school, a linear function is one that can be written in the form y(x) = mx + c where m and c are constants.

The scrolling range is the size of the page in scrolling units. The scrolling position will never be < 0 because that would mean the frame has moved off the page. Equally, the scrolling position can never exceed the maximum value of the scrolling range minus the the size of the frame. If it did, the frame would again move off the page.

Configuring Scrollbars

Once the appropriate scrollbars are displayed, the next step is to set the scrolling range and page mapping function. This is a little complicated. The page mapping function is a linear function (I'm talking about functions in the mathematical sense here) which maps the size of the window in pixels (width or height depending on the scrollbar) to a number of scrolling units. For example, if you created a word processor you might want to deal with scrolling in terms of points. Your page mapping function would convert the size of the window in pixels into a number of points.

Use the WinXScroll_SetPage function to set this information. Once you have set the page mapping function, WinX will automatically adjust the scrollbars when the window is resized. Use the WinXScroll_SetRange to set the scrolling range.

If the size of the page being scrolled changes, you may need to call the WinXScroll_SetRange function again. If the user is able to zoom in or out, you'll need the WinXScroll_SetPage function to adjust the size of the units relative to pixels.

Scrolling events

When the user moves a scrollbar with the mouse, the onScroll callback will be invoked (provided you have remembered to register it). This gives you an opertunity to redraw the window.

If you want the user to be able to scroll by means other than clicking and dragging with the mouse, you'll need to process other callbacks as well. To use the mouse wheel for scrolling, use the onMouseWheel callback. To allow the keyboard to be used for scolling use the onKeyDown callback. Keep in mind that if the dialog interface is enabled, the arrow keys will not work.

Redrawing the Window

If you are using auto draw, it is very important that when you finish drawing you call WinXScroll_Update instead of WinXUpdate. This avoids nasty flickering and tearing effects. You can use WinXScroll_Update even if you are drawing the window manually, in fact, this is a good idea as it avoids any flickering or tearing.

Related Links

WinXScroll_Show
WinXScroll_SetRange
WinXScroll_SetPage
WinXScroll_Update
WinXScroll_Scroll