Introduction to PM Programming - Nov 1995

Written by Larry Salomon Jr.

Introduction
The purpose of this column is to provide the readers out there who are not familiar with PM application development the information necessary to satisfy their curiosity, educate themselves, and give them an advantage over the documentation supplied by IBM. Of course, much of this stuff could probably be found in one of the many books out there, but the problem with books in general is that they don't answer the questions you have after you read the book the first time through.

I will gladly entertain feedback from the readers about what was "glossed over" or what was detailed well, what tangential topics need to be covered and what superfluous crap should have been removed. This feedback is essential in guaranteeing that you get what you pay for.

It should be said that you must not depend solely on this column to teach you how to develop PM applications; instead, this should be viewed as a supplement to your other information storehouses (books, the network conferences, etc.). Because this column must take a general approach, there will be some topics that you would like to see discussed that really do not belong here. Specific questions can be directed to me via email and I will do my best to answer them in a timely fashion.

Where Are We?
As I sat down to write this month's instalment, I had to look back to see where we've been. The window classes that we've covered here so far are listed below: The window classes left to be covered are listed below: As I looked, I decided that we could hit three birds with one stone if we ventured into the realm of the circular slider, slider, and scrollbar, since all three controls are very similar in function.
 * Button (WC_BUTTON)
 * Entryfield (WC_ENTRYFIELD)
 * Listbox (WC_LISTBOX)
 * Menu (WC_MENU)
 * Static (WC_STATIC)
 * Titlebar (WC_TITLEBAR)
 * Circular slider (WC_CIRCULARSLIDER)
 * Combo box (WC_COMBOBOX)
 * Container (WC_CONTAINER)
 * Frame (WC_FRAME)
 * Multi-line edit (WC_MLE)
 * Notebook (WC_NOTEBOOK)
 * Scroll bar (WC_SCROLLBAR)
 * Slider (WC_SLIDER)
 * Spin button (WC_SPINBUTTON)
 * Value set (WC_VALUESET)

Purpose
What is the purpose of each of these three controls? To sum it up in one sentence, their purpose is to allow the user to choose a single value within a range of values. Since Salomon's Law states that the complexity of a window class is exponentially proportional to the number of words in which you can state its purpose, you can imagine that we won't need to spend much time on these controls.

Breakdown
If you breakdown the capabilities of the controls, you will see that all three provide the following:
 * Set / Query the range of values
 * Set / Query the current value
 * Notify the owner when the value changes

We will look at the details specific to each control in this column starting with the scroll bar (WC_SCROLLBAR).

Scroll Bar Terminology
The parts of a scroll bar are labelled in the illustration below.

The buttons are used to change the position by one increment (see below).

The slider areas are used to change the position by one page.

The thumb is used to move the scroll bar to an absolute position.

The concept of a unit or a page of units is defined by the application. One unit may correspond to one line of text, but it may correspond to three lines of text.

Scroll Bar Styles
The scroll bar styles are listed below.
 * SBS_AUTOSIZE - The PM Guide and Reference states that this style causes the scroll bar to automatically change its size to reflect the amount of data contained in the window. I have never seen the style used before and there is no documentation on its use, so we will not discuss this further.
 * SBS_AUTOTRACK - Like SBS_AUTOSIZE there is no documentation on this style. The PM Guide and Reference states that this style causes the scroll bar to automatically scroll as more information is being displayed on the screen.
 * SBS_HORZ - This style creates a horizontal scroll bar.
 * SBS_THUMBSIZE - This style indicates that a scroll bar control data (SBCDATA) structure is being passed in as the second-to-last parameter to WinCreateWindow and that the cVisible and cTotal fields are initialized.
 * SBS_VERT - This style creates a vertical scroll bar.

Scroll Bar Notifications
The scroll bar is unlike the other PM controls in that its notifications are not communicated via the WM_CONTROL message. Instead, depending on the orientation of the scroll bar (horizontal or vertical), the owner receives a WM_HSCROLL or WM_VSCROLL message.

WM_HSCROLL / WM_VSCROLL

 * SHORT1FROMMP(mpParm1):specifies the ID of the scroll bar.
 * SHORT1FROMMP(mpParm2):specifies the position of the scroll bar. This is 0 if the keyboard is being used to move the scroll bar.
 * SHORT2FROMMP(mpParm2):notification type:
 * SB_LINELEFT - the left arrow was clicked with the mouse or the left arrow key was pressed.
 * SB_LINERIGHT - the right arrow was clicked with the mouse or the right arrow key was pressed.
 * SB_LINEUP - the up arrow was clicked with the mouse or the up arrow key was pressed.
 * SB_LINEDOWN - the down arrow was clicked with the mouse or the down arrow key was pressed.
 * SB_PAGELEFT - the slider was clicked to the left of the thumb with the mouse or the page up key was pressed.
 * SB_PAGERIGHT - the slider was clicked to the right of the thumb with the mouse or the page down key was pressed.
 * SB_PAGEUP - the slider was clicked above the thumb with the mouse or the page up key was pressed.
 * SB_PAGEDOWN - the slider was clicked below the thumb with the mouse or the page down key was pressed.
 * SB_SLIDERPOSITION - this is sent to indicate the final position of the scroll bar.
 * SB_SLIDERTRACK - if the mouse is being used to "drag" the thumb, this is sent every time the position changes.
 * SB_ENDSCROLL - this indicates the end of scrolling and is sent only if the thumb was not dragged.

Scroll Bar Messages
There are five, easy to understand messages that the scroll bar understands:
 * SBM_QUERYPOS:This message returns the current position.
 * SHORT1FROMMR(mrResult) - current position.


 * SBM_QUERYRANGE:This message returns the current scroll bar range.
 * SHORT1FROMMR(mrResult) - lower bound of the range.
 * SHORT2FROMMR(mrResult) - upper bound of the range.


 * SBM_SETPOS:This message sets the current position.
 * SHORT1FROMMP(mpParm1) - new position.
 * SHORT1FROMMR(mrResult) - success indicator (BOOL).


 * SBM_SETSCROLLBAR:This message sets the current position and the range.
 * SHORT1FROMMP(mpParm1) - new position.
 * SHORT1FROMMP(mpParm2) - new lower bound of the range.
 * SHORT2FROMMP(mpParm2) - new upper bound of the range.
 * SHORT1FROMMR(mrResult) - success indicator (BOOL).


 * SBM_SETTHUMBSIZE:This message sets the size of the thumb. It is used to indicate to the user how much of the data is viewable at a time.
 * SHORT1FROMMP(mpParm1) - visible amount of data.
 * SHORT2FROMMP(mpParm1) - total amount of data.
 * SHORT1FROMMR(mrResult) - success indicator (BOOL).

Next Month
Next month we will take a look at a small application that uses both the horizontal and vertical scroll bars to allow you to scroll through a "large" amount of data. Bring your thinking caps!