CHAPTER 22

SCROLLBARS AND SCROLLING.

OVERVIEW OF SCROLLBARS:

Perhaps the first thing to understand about scrollbars and scrolling is that these require two separate and essentially independent code segments. The first will be used for scrolling the contents of the screen, and the other, separate code segment will set the scrollbar so that its appearance will represent the current scrolled position of the screen contents.

As far as the scrollbar itself is concerned, the operating system draws the scrollbar and displays it on the screen, and also updates, or redraws it, as required.

If the user operates on the scrollbar with the mouse cursor, in order to move the scroll box, the system sends one of several alternative messages to the program code. It does not, however, automatically do anything to relate the size and position of the scroll box to the contents of the screen, and does not know anything about the contents of the screen. The system therefore does not automatically update the appearance of the scrollbar in response to user actions with the mouse cursor, because it is not able to reconcile the scrollbar position with those of the screen contents.

The reconciliation of the position of the screen contents with that of the scrollbar scroll box has to be carried out by the program code, with information then being passed to the system so that the system can update the appearance of the scrollbar.

The program code must scroll the actual screen contents, as the operating system code operates only on the scrollbar itself. The program code must then calculate the corresponding position of the scrollbox, and pass this information to the system, which then automatically redraws the scrollbar. The operating system thus does only a small part of the work of operating a scrollbar.

It is not as difficult as one might initially suspect to

set up the necessary information, provided one is clear about the operating system nomenclature with respect to the elements of the scrollbar.

This is, in fact, another of those situations in which the attempt to interpret the API documentation can lead to considerable confusion for anyone as yet unfamiliar with it. I was not clear about it myself, and had to use a trial and error method, including the use of debug information, in order to gain an understanding of what the documentation nomenclature actually meant.

In an effort to help the reader to avoid, or at least minimise, such difficulties, I provide an illustration below, which shows the relationship between the contents of the screen, and the elements of the scrollbar. The screen is shown on the left, with the scrollbar, independently, to its right.

The shaded area represents the actual total extent of the text, which is larger than can be displayed on the screen, which is shown at the top, with a portion of the text showing through it. If the screen were to be scrolled down the text, the shaded portion below the screen would be moved so as to appear within the screen area, and the top portion of the shaded area would appear above the top of the screen in the illustration

Following the illustration I give a reasonably detailed account of how the labelled dimensions of the total text size, and the portion appearing on the screen, are related to the dimensions of the scrollbar and its scrollbox.

The scrollbox size, of course, will be related to the total size of the text that can be scrolled. You will no doubt be familiar with the fact that, if you paste a large body of text into a text file, the scrollbox in the vertical scrollbar will become much smaller.

It doesn't matter, in the above illustration, what the actual sizes of the scrollbar, screen contents, and screen are. It is the relative, or proportional sizes, of the different parts, to one another, within the screen environment, or within the scrollbar, that are important.

The scrollbar is thus represented as if it had an overall size equal to the total contents to be scrolled, because SCROLLBAR.MaxPos, which is the relevant scrollbar parameter, will represent this.

The scroll box size, relative to the size of the scrollbar, similarly represents the size of the visible contents on the screen, relative to the total text height, indicated by the total height of the shaded area.

Here, the total contents to be scrolled are less than two screen sizes, which means that the scroll box size is more than half the length of the scrollbar. If the scrolled contents were many times the height of the

screen, the scroll box height, representing the height of the screen, would be only a small percentage of the total height of the scroll bar.

The 'scrollbar range' is the range through which the scrollbar can be moved, and the SCROLLBAR.Pos, or scrollbar position parameter, which refers to the current position of the scroll box, is measured as a distance the bottom edge of the scrollbox has moved into the scrollbar range. The dotted lines represent a possible position of the scroll box.

What is easily a source of confusion with these parameters is that the parameter, SCROLLBAR.MaxPos, does not represent the maximum distance the scroll box can be moved into its range but represents, instead, the maximum position of the scroll box, measured from the top of the scrollbar. Why the parameters were named in this potentially confusing way I have no idea, but the above description appears to be the one that works in practice.

SCROLLBAR OPERATION:

When the user operates the scrollbar, it sends a WM_VSCROLL message to the program message queue, for a vertical scrollbar (or a WM_HSCROLL message for a horizontal scrollbar. Here I deal only with a vertical scrollbar, since precisely the same considerations apply to a horizontal scrollbar). The program code activates its scrolling code in response to this message. As far as the scrollbar itself is concerned, the program must fill out a

SCROLLINFO data structure, which will contain the parameters necessary for the operating system to calculate the size and position of the scrollbar scroll box. SCROLLBAR.MaxPos, SCROLLBAR.PageSize, and SCROLLBAR.Pos are these parameters as shown in the illustration. This information is fed to the scrollbar via the SetScrollInfo API function, as in the following code:

eq [SCROLLINFO.StrctSize], '=', 1ch
eq [SCROLLINFO.FlagMask], '=', SIF_ALL
eq [SCROLLINFO.MinScrollPos], '=', 0
eq [SCROLLINFO.MaxScrollPos], '=', [SCROLLBAR.MaxPos]
eq [SCROLLINFO.PageSize], '=', [SCROLLBAR.Page]
eq [SCROLLINFO.ScrollPos], '=', [SCROLLBAR.ScrollPos]
eq [SCROLLINFO.ScrollTrackPos], '=', 0
api SetScrollInfo,[WINDOW.Handle],SB_VERT,SCROLLINFO,1

The SetScrollInfo function requires the window handle, the SB_VERT flag, to direct it to operate on the vertical scrollbar, the address of the SCROLLINFO data structure, and a parameter that specified whether or not the scrollbar is to be immediately redrawn, i.e., 1 for yes, and 0 for no.

If the screen contents are less than the size of the screen, the 3 scrollbar parameters can be set to zero, in which case the scrollbar is not displayed, or is removed if it has already been displayed. If you want the scrollbar to be displayed as disabled, rather than removed, the SIF_DISABLENOSCROLL flag can be added to the SIF_ALL flag indicated above. If the contents require a scrollbar it will be displayed with the scroll box positioned in accordance with the three parameters provided. You can relate the values of these three parameters to the values of the text or other contents to be scrolled, as follows:

The screen height will be determined by whatever height dimension you have specified to display the program content in your program window. The SCROLLBAR.Pos parameter will have to be calculated each time a scrolling event occurs.

As mentioned above, a scrolling event created by the user sends a message to the program message loop. This is a WM_VSCROLL message, in the case of a vertical scrollbar. The WPARAM_LOWORD parameter associated with this message indicates the kind of scrollbar operation chosen by the user. There are basically five possible alternatives:

The user can click in the up or down arrow boxes at the top or bottom of the scrollbar, which will provide SB_LINEUP or SB_LINEDOWN parameters respectively, indicating that the screen text is to be scrolled up or down by only one line of text. If the screen content is not text (e.g. an image), your program will have to define what the minimum

scrolling distance is to be. This will then be regarded as 'one line'.

If the user clicks in the scrollbar itself, above or below the scroll box, the parameter will be SB_PAGEUP or SP_PAGEDOWN respectively, indicating that the screen content is to be scrolled by an amount equal to the visible height on the screen, in the up or down direction respectively.

Finally, if the user clicks within the scroll box, and drags it in the up or down direction, the parameter will be simply SB_THUMBTRACK in either case. In the latter case WPARAM_HIWORD will contain the position of the scroll box, which is the SCROLLBAR.Pos value, and the program code will have to calculate whether the scroll box is being dragged in the up or down direction by comparing the current position with the previous position of the scroll box.

Note that, in the case of text, all movements of the screen contents are created in terms of lines of text, one line, up or down, being the minimum scrolling value. Scrolling one page means scrolling to the first line of the next or previous page, and dragging the scrollbar means dragging the text up or down on a line by line basis. In this case, no scrolling is implemented until the box has been dragged at least a distance of the scroll bar equivalent of one text line.

Once information has been received from the scrollbar, the program code itself must update the screen accordingly. The system scrollbar code only operates the scrollbar itself. When your code has updated the screen, it must calculate the new position of the scrollbar, and update the scrollbar, enter it in the [SCROLLBAR.ScrollPos] parameter and call the SetScrollInfo API function as shown in the code segment above.

                  Part I: Part I Introduction
                  Chapter 1: Binary numbers, code, and procedures
                  Chapter 3: Assembly Language
                  Chapter 4: Assembly Language Code example
                  Chapter 5: Macros and HLA
                  Chapter 6: HLA code example
                  Chapter 7: The Windows operating system
                  Chapter 8: Data Structures
                  Chapter 9: How to Create a Windows Program
                  Chapter 10: How to Create an Exe File
                  Chapter 11: Structured Programming and OOP
                  Part II: Part II Introduction
                  Chapter 12: Debugging a Windows Program Code
                  Chapter 13: Painting the Window Client Area
                  Chapter 14: Creating Window Menus
                  Chapter 15: How to Create Toolbars
                  Chapter 16: How to Create Popup Menus
                  Chapter 17: About the Windows Clipboard
                  Chapter 18: How to Create Bitmaps
                  Chapter 19: Icons and the Ico Format
                  Chapter 20: Common Dialog Boxes
                  Chapter 21: Working with Files
                  Chapter 22: Scrollbars and Scrolling
                  Chapter 23: How to Send Data to the Printer
                  Chapter 24: Miscellaneous Topics

© Alen, June 2014
alen@alenspage.net

Material on this page may be reproduced
for personal use only.