PMGuide - Slider Controls

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

Presentation Manager Programming Guide and Reference

How to Use this Book Device Functions Direct Manipulation Functions Dynamic Data Formatting Functions Hooks and Procedures Profile Functions Spooler Functions Window Functions Message Processing Data Types Errors Atom Tables Button Controls Clipboards Combination Box Container Controls Control Windows Cursors Dialog Windows Direct Manipulation Drawing in Windows Dynamic Data Exchange Entry-Field Controls File Dialog Controls Font Dialog Controls Frame Windows Hooks Initialization Files Keyboard Accelerators List-Box Controls Menus Messages and Message Queues Multiple-Line Entry Field Controls Mouse and Keyboard Input Mouse Pointers and Icons Notebook Controls Painting and Drawing Presentation Parameters Resource Files Scroll-Bar Controls Slider Controls Spin Button Controls Static Controls Title-Bar Controls Value Set Controls Windows Window Classes Window Procedures Window Timers Appendices Notices Glossary

A slider control is a visual component that displays a range of values and allows a user to set, display, or modify a value by moving a slider arm. There are two types of sliders:

• The linear slider is represented as a shaft along which the slider arm can be moved by the user to set a value.
• The circular slider is represented as a dial with the slider arm shown as the radius of the dial.

This chapter explains how to use each of these slider controls in PM applications.

About Slider Controls

This section covers linear and circular slider controls. Linear sliders are used to set values that have familiar increments. Circular sliders, although different in appearance from linear sliders, provide much the same function. Both types of sliders can be used in a window to create a user interface.

Linear Sliders

Typically, linear sliders are used to easily set values that have familiar increments, such as feet, inches, degrees, and decibels. They also can be used for other purposes when immediate feedback is required, such as blending colors or showing a task's percentage of completion. For example, an application might let a user mix and match color shades by moving a slider arm, or a read-only slider could show how much of a task is complete by filling in the slider shaft as the task progresses. These are just a few examples of the ways in which sliders can be used.

The slider arm shows the value currently set by its position on the slider shaft. The user selects slider values by changing the location of the slider arm.

A tick mark indicates an incremental value in a slider scale. A detent, which is similar to a tick mark, also represents a value on the scale. However, a detent can be placed anywhere along the slider scale, rather than only in specific increments, and can be selected.

The appearance of a slider and the user interaction with a slider are similar to that of a scroll bar. However, these two controls are not interchangeable because each has a unique purpose. A scroll bar scrolls information into view that is outside a window's work area, while the slider is used to set, display, or modify that information, whether it is in or out of the work area.

Although linear sliders usually use values that have familiar increments, text also can be used. However, if the text is too long it can overlap the text displayed on the next tick mark or detent. Also, if the text on the far edge markers is too long, some of the text will not be displayed on screen. To prevent this use one of the following:

• Smaller font
• Shorter text values
• Static controls

The slider can be customized to meet varying application requirements, while providing a user interface component that can be used easily to develop products that conform to the Systems Application Architecture (SAA) Common User Access (CUA) user interface guidelines. The application can specify different scales, sizes, and orientations for its sliders, but the underlying function of the control remains the same. For a complete description of CUA sliders, refer to the SAA CUA Guide to User Interface Design and the SAA CUA Advanced Interface Design Reference.

Linear Slider Styles

Slider control styles are set when a slider window is created. The following table describes linear slider control styles. If no styles are specified, defaults are used as indicated in the table.

Style Name	Description
LS_BOTTOM	Positions the slider at the bottom of the slider window. Valid only for horizontal sliders.
LS_BUTTONSBOTTOM	Specifies that the optional slider buttons are to be used and places them at the bottom of the slider shaft. The buttons move the slider arm by one position, up or down, in the direction selected. Valid only for vertical sliders.
LS_BUTTONSLEFT	Specifies that the optional slider buttons are to be used and places them to the left of the slider shaft. The buttons move the slider arm by one position, left or right, in the direction selected. Valid only for horizontal sliders.
LS_BUTTONSRIGHT	Specifies that the optional slider buttons are to be used and places them to the right of the slider shaft. The buttons move the slider arm by one position, left or right, in the direction selected. Valid only for horizontal sliders.
LS_BUTTONSTOP	Specifies that the optional slider buttons are to be used and places them at the top of the slider shaft. The buttons move the slider arm by one position, up or down, in the direction selected. Valid only for vertical sliders.
LS_CENTER	Centers the slider within the slider window. This is the default position of the slider.
LS_HOMEBOTTOM	Specifies the slider arm's home position. The bottom of the slider is used as the base value for incrementing. Valid only for vertical sliders.
LS_HOMELEFT	Specifies the slider arm's home position. The left edge is used as the base value for incrementing. This is the default for horizontal sliders and is valid only for horizontal sliders.
LS_HOMERIGHT	Specifies the slider arm's home position. The right edge is used as the base value for incrementing. Valid only for horizontal sliders.
LS_HOMETOP	Specifies the slider arm's home position. The top of the slider is used as the base value for incrementing. Valid only for vertical sliders.
LS_HORIZONTAL	Positions the slider horizontally. The slider arm can move left and right on the slider shaft. A scale can be placed on top of the slider shaft, below the slider shaft, or in both places. This is the default orientation of the slider.
LS_LEFT	Positions the slider at the left edge of the slider window. Valid only for vertical sliders.
LS_OWNERDRAW	Notifies the application whenever the slider shaft, the ribbon strip, the slider arm, and the slider background are to be drawn.
LS_PRIMARYSCALE1	Determines the location of the scale on the slider shaft by using increment and spacing specified for scale 1 as the incremental value for positioning the slider arm. Scale 1 is displayed above the slider shaft of a horizontal slider and to the right of the slider shaft of a vertical slider. This is the default for a slider.
LS_PRIMARYSCALE2	Determines the location of the scale on the slider shaft by using increment and spacing specified for scale 2 as the incremental value for positioning the slider arm. Scale 2 is displayed below the slider shaft of a horizontal slider and to the left of the slider shaft of a vertical slider.
LS_READONLY	Creates a read-only slider, which presents information to the user but allows no interaction with the user.
LS_RIBBONSTRIP	Fills, as the slider arm moves, the slider shaft between the home position and the slider arm with a color value different from slider shaft color, similar to mercury in a thermometer.
LS_RIGHT	Positions the slider at the right edge of the slider window. Valid only for vertical sliders.
LS_SNAPTOINCREMENT	Causes the slider arm, when positioned between two values, to be positioned to the nearest value and redrawn at that position.
LS_TOP	Positions the slider at the top of the slider window. Valid only for horizontal sliders.
LS_VERTICAL	Positions the slider vertically. The slider arm can move up and down the slider shaft. A scale can be placed on the left side of the slider shaft, on the right side of the slider shaft, or in both places.

More on Linear Slider Styles

This section summarizes information in the table and provides additional information on some of the styles.

Slider Orientation

The slider's orientation is determined by specifying SLS_HORIZONTAL or SLS_VERTICAL. The default orientation is horizontal, with the slider arm moving left and right on the shaft.

Slider Positioning

The slider's positioning within the slider window is determined by specifying SLS_CENTER, SLS_BOTTOM, SLS_TOP, SLS_LEFT, or SLS_RIGHT. The default positioning is centered in the slider window.

Slider Scale Location

The location of the scale on the slider shaft is determined by specifying SLS_PRIMARYSCALE1 or SLS_PRIMARYSCALE2. The default is to use the increment and spacing specified for scale 1 as the incremental value for positioning the slider arm. Scale 1 is displayed above the slider shaft of a horizontal slider and to the right of the slider shaft of a vertical slider.

Slider Arm Home Position

The slider arm's home position is determined by specifying SLS_HOMELEFT, SLS_HOMERIGHT, SLS_HOMEBOTTOM, or SLS_HOMETOP. The default is SLS_HOMELEFT for horizontal sliders and SLS_HOMEBOTTOM for vertical sliders.

Slider Buttons Location

The location of the slider buttons, if used, is determined by specifying SLS_BUTTONSLEFT, SLS_BUTTONSRIGHT, SLS_BUTTONSBOTTOM, or SLS_BUTTONSTOP. If you do not specify one of these styles, or if conflicting styles are specified, slider buttons are not included in the slider control.

Other Styles

If SLS_SNAPTOINCREMENT is specified and the slider arm is moved to a position between two values on the slider scale, it is positioned on the nearest value and redrawn at that position. If this style is not specified, the slider arm remains at the position to which it is moved.

SLS_READONLY creates a read-only slider. This means the user cannot interact with the slider. It is simply used to present a quantity to the user, such as the percentage of completion of an ongoing task. Visual differences for a read-only slider include a narrow slider arm, no slider buttons, and no detents.

The SLS_RIBBONSTRIP style allows movement of the slider arm to cause the slider shaft between home position and the slider arm to be filled with a color value that is different from the slider shaft color, similar to mercury in a thermometer.

If SLS_OWNERDRAW is specified, the application is notified whenever the slider shaft, the ribbon strip, the slider arm, and the slider background are to be drawn.

Circular Sliders

The circular slider, although different in appearance from the linear slider, provides much the same function. The circular slider control provides an analog user interface and emulates the controls of stereo and video equipment. Because the circular slider takes up less space on the screen, it may be more practical to use in cases where you might want to have several controls in the same window. You may want to use both types of sliders in a window to create a user interface that makes good use of available space and provides a familiar appearance to the user.

The slider arm shows the value currently set by its position on the slider dial. The slider arm can also be represented as a small circular thumb on the dial rather than a line. The user selects slider values by changing the location of the slider arm on the dial. Outside the perimeter of the dial is a circular scale with tick marks representing incremental values the slider arm can point to. Its values can be tracked by pointing to any area on the dial and pressing the select button while moving the mouse on the desktop.

The circular slider can have a set of buttons, one to the left and the other to the right of the scroll range, similar to the buttons found on the linear slider, that can be used to modify the value shown on the slider.

The minus sign on the left button and plus sign on the right button can be replaced with other symbols. For example, you might want to use a left arrow and a right arrow instead of the minus and plus signs.

Another option of the circular slider is to have a window, in the center of the dial, that displays the value of the dial in scrollable numeric text.

The appearance and functionality of the circular slider are controlled by the circular slider control styles specified. These style bits are summarized in the section that follows.

Circular Slider Styles

Circular slider control style bits control the appearance and behavior of the slider. The following table describes circular slider control styles:

Style Name	Description
SS_360	Extends the scroll range of the dial to 360 degrees. When this style is set, CSS_NONUMBER and CSS_NOBUTTON styles automatically are set.
SS_CIRCULARVALUE	Draws a circular thumb, rather than a line, for the value indicator.
SS_MIDPOINT	Enlarges the mid-point and end-point tick marks.
SS_NOBUTTON	Prevents the display of the + and - value buttons.
SS_NONUMBER	Prevents the display of a scrollable numeric value on the dial indicating the dial's value.
SS_NOTEXT	Prevents the display of a window title beneath the dial.
SS_POINTSELECT	Enables tracking of the dial's value with the mouse.
SS_PROPORTIONALTICKS	Enables the length of the tick marks to be calculated as a percentage of the dial's radius.

More on Circular Slider Styles

This section provides information on some of the styles.

Circular Slider Buttons

The circular slider has a set of buttons, one to the left and the other to the right of the scroll range. These buttons are similar to the buttons found on the linear slider. When selected, they modify the value of the circular slider in opposing ways. If you decide you do not want to display these buttons as part of your circular slider, specify the style CSS_NOBUTTON.

The bit maps that show a minus sign (-) on the left button and a plus sign (+) on the right button can be replaced. For example, you might want to use a left arrow (←) and a right arrow (→). To set the bit map data for the replacement bit maps, the owner window must send the CSM_SETBITMAPDATA control message. The optimal size for the button bit maps is 10x10 pels.

Window Title

Centered beneath the dial of the circular slider is a rectangular text field that contains the title of the window. To prevent the display of this feature, specify CSS_NOTEXT.

Dial Value Window

Another option of the circular slider is a window, in the center of the dial, that displays the value of the dial in scrollable numeric text. To prevent the display of this window, specify CSS_NONUMBER.

360-Degree Scale

You can choose a scale of 360 degrees for your slider with CSS_360. Setting this style causes theoksia

the CSS_NOBUTTON and CSS_NONUMBER styles to be set automatically. The CSS_NONUMBER style prevents the value indicator from corrupting the dial value. A 360-degree circular slider is displayed without the bit maps for the plus and minus buttons.

Tracking Modes for Direct Manipulation

There are two tracking modes used for direct manipulation of the circular slider: scrolling the dial and point selection.

The default tracking behavior is scrolling, where the dial position of the slider is changed gradually. For example, by holding down the select mouse button while the pointer is positioned on the indicator line of the dial, you can move the mouse and cause the dial to rotate. This gradual changing of the dial value might be desirable for a volume control.

If the CSS_POINTSELECT style is specified for the circular slider, the position of the dial is changed immediately to a point on the scale that has been selected by the mouse. Point selection allows value changes to occur immediately.

Sizing Tick Marks

When a low-resolution display is being used, or in situations where the circular slider must be made very small, the length of the tick marks can be sized proportionately to allow effective sizing of the circular slider. Specifying the CSS_PROPORTIONALTICKS style causes the length of the tick marks to be calculated as a percentage of the dial's radius. This style does not adversely affect the size of the push buttons and bit-map graphics an application might provide.

Using Slider Controls

This section explains how to use sliders in your PM applications. It covers:

• Creating a linear slider
• Retrieving data for selected slider values
• Creating a circular slider

Code samples are provided.

Creating a Linear Slider

Before the slider is created, a temporary SLDCDATA data structure is allocated, and variables are specified for the slider control window handle and slider style. The SLDCDATA data structure is allocated so that the scale increments and spacing of the slider can be specified.

The slider style variable enables the application to specify style bits, SLS_* values, that are used to customize the slider.

You create a slider by using the WC_SLIDER window class name in the ClassName parameter of WinCreateWindow call. The handle of the slider control window is returned in the slider window variable.

After the slider is created, but before it is made visible, the application can set other slider control characteristics, such as:

• Size and placement of tick marks
• Text above one or more tick marks
• One or more detents
• Initial slider arm position

The settings in the preceding list are just a few that an application can specify. Slider control messages are used to specify these settings.

The sample code in the following figure shows an example of how a linear slider is created. The main components of the slider are labeled.

SLDCDATA sldcData;                  /* SLDCDATA data structure        */
CHAR     szTickText[5];             /* Text strings variable          */
USHORT   idx;                       /* Counter for setting text       */
                                    /* strings                        */
HWND     hwndSlider;                /* Slider window handle           */
ULONG    ulSliderStyle;             /* Slider styles                  */

/**********************************************************************/
/* Initialize the parameters in the data structure.                   */
/**********************************************************************/
sldcData.cbSize = sizeof(SLDCDATA); /* Size of SLDCDATA structure     */
sldcData.usScale1Increments = 6;    /* Number of increments           */
sldcData.usScale1Spacing = 0;       /* Use 0 to have slider calculate */
                                    /* spacing                        */

/**********************************************************************/
/* Set the SLS_* style flags to the default values, plus slider       */
/* buttons right.                                                     */
/**********************************************************************/
ulSliderStyle = SLS_HORIZONTAL    | /* Slider is horizontal           */
                SLS_CENTER        | /* Slider shaft centered in       */
                                    /* slider window                  */
                SLS_HOMELEFT      | /* Home position is left edge of  */
                                    /* slider                         */
                SLS_PRIMARYSCALE1 | /* Scale is displayed above       */
                                    /* slider shaft                   */
                SLS_BUTTONSRIGHT;   /* Slider buttons at right end of */
                                    /* slider                         */

/**********************************************************************/
/* Create the slider control window.                                  */
/* The handle of the window is returned in hwndSlider.                */
/**********************************************************************/
hwndSlider = WinCreateWindow(
               hwndClient,          /* Parent window handle           */
               WC_SLIDER,           /* Slider window class name       */
               (PSZ)NULL,           /* No window text                 */
               ulSliderStyle,       /* Slider styles variable         */
               (SHORT)10,           /* X coordinate                   */
               (SHORT)10,           /* Y coordinate                   */
               (SHORT)150,          /* Window width                   */
               (SHORT)80,           /* Window height                  */
               hwndClient,          /* Owner window handle            */
               HWND_TOP,            /* Sibling window handle          */
               ID_SLIDER,           /* Slider control window ID       */
               &sldcData,           /* Control data structure         */
               (PVOID)NULL);        /* No presentation parameters     */

/**********************************************************************/
/* Set tick marks at several places on the slider shaft using the     */
/* primary scale.                                                     */
/**********************************************************************/
WinSendMsg(hwndSlider,              /* Slider window handle           */
           SLM_SETTICKSIZE,         /* Message for setting tick mark  */
                                    /* size.                          */
           MPFROM2SHORT(
             SMA_SETALLTICKS,       /* Attribute for setting all tick */
                                    /* marks to the same size         */
             6),                    /* Draw tick marks 6 pixels long  */
           NULL);                   /* Reserved value                 */

/**********************************************************************/
/* Set text above the tick marks.                                     */
/**********************************************************************/
for (idx = 0; idx <= 5; idx++)      /* Count from 0 to 5              */
{
  itoa(10*idx, szTickText, 10);     /* Set text at increments of 10   */

  WinSendMsg(hwndSlider,            /* Slider window handle           */
           SLM_SETSCALETEXT,        /* Message for setting text on a  */
                                    /* slider scale                   */
           MPFROMSHORT(idx),        /* Text string counter            */
           MPFROMP(szTickText));    /* Text to put on slider scale    */
}

/**********************************************************************/
/* Set detents between two of the tick marks on the slider shaft.     */
/**********************************************************************/
WinSendMsg(hwndSlider,              /* Slider window handle           */
           SLM_ADDDETENT,           /* Message for adding detents to  */
                                    /* a slider scale                 */
           MPFROMSHORT(5),          /* Put a detent 5 pixels from home*/
           NULL);                   /* Reserved value                 */

WinSendMsg(hwndSlider,              /* Slider window handle           */
           SLM_ADDDETENT,           /* Message for adding detents to  */
                                    /* slider scale                   */
           MPFROMSHORT(25),         /* Put a detent 25 pixels from    */
                                    /* home                           */
           NULL);                   /* Reserved value                 */

/**********************************************************************/
/* Set the slider arm position to the 1st increment on the scale.     */
/**********************************************************************/
WinSendMsg(hwndSlider,              /* Slider window handle           */
           SLM_SETSLIDERINFO,       /* Message for setting slider     */
                                    /* attributes                     */
           MPFROM2SHORT(
             SMA_SLIDERARMPOSITION, /* Modify slider arm position     */
             SMA_INCREMENTVALUE),   /* Use an increment value         */
           MPFROMSHORT(1));         /* Value to use is 1st            */
                                    /* increment                      */

/**********************************************************************/
/* Since all items have been set, make the control visible.           */
/**********************************************************************/
WinShowWindow(hwndSlider,           /* Slider window handle           */
              TRUE);                /* Make the window visible        */

Retrieving Data for Selected Slider Values

To retrieve data represented by a slider value, specify a variable for the current position of the slider arm. Then, use the SLM_QUERYSLIDERINFO message to retrieve information about the current slider arm position in increment coordinates. The code fragment in the following figure shows how to retrieve data for a selected slider value:

ULONG  ulValue;                     /* Variable in which to store     */
                                    /* current slider arm position    */

/**********************************************************************/
/* Get the information about the current slider arm position in       */
/* incremental coordinates.                                           */
/**********************************************************************/
ulValue = (ULONG)WinSendMsg(
  hwndSlider,                       /* Slider window handle           */
  SLM_QUERYSLIDERINFO,              /* Message for querying slider    */
                                    /* attributes                     */
  MPFROM2SHORT(
    SMA_SLIDERARMPOSITION,          /* Get increment at which slider  */
    SMA_INCREMENTVALUE),            /* arm is located                 */
  NULL);                            /* Reserved value                 */

Creating a Circular Slider

The circular slider PM window class WC_CIRCULARSLIDER is similar to the window class of a linear slider or a scroll bar. This window class must be registered with WinRegisterCircularSlider before you can create a circular slider. A circular slider can be created by a CONTROL statement in a dialog resource, as shown in the following figure:

CONTROL "~Balance",
        ID_BALANCECS,
        10, 50, 60, 60,
        WC_CIRCULARSLIDER,
        WS_TABSTOP |
        WS_VISIBLE |
        CSS_POINTSELECT

A circular slider also can be created by specifying the WC_CIRCULARSLIDER window class name as a parameter of the WinCreateWindow call, as shown in the following sample code:

hwndCS = WinCreateWindow (hwndClient,           /* Parent handle  */
                          WC_CIRCULARSLIDER,    /* Class name     */
                          "~Balance",           /* Window text    */
                          WS_VISIBLE |
                          WS_TABSTOP |
                          CSS_POINTSELECT,
                          0,0,0,0,              /* Coordinates    */
                          hwndClient,           /* Owner handle   */
                          HWND_TOP,             /* Z-order        */
                          ID_BALANCECS,         /* Window ID      */
                          NULL,                 /* Control data   */
                          NULL);                /* Presparam      */

Circular Slider Sample

The following is a complete coding example for adding a circular slider, and includes the following files:

• CIRCLE.C
• CIRCLE.RC
• CIRCLE.H

================
CIRCLE.C
================
#define  INCL_WIN

#include <os2.h>
#include "circle.h"

/* Procedure Prototype */
MRESULT EXPENTRY MyWindowProc(HWND hwnd,ULONG msg,MPARAM mp1,MPARAM mp2);
MRESULT EXPENTRY MainProc(HWND hwnd,ULONG msg,MPARAM mp1,MPARAM mp2);

/* Global Variables */
HAB     hab;
HMQ     hmq;
QMSG    qmsg;
HWND    hwndFrame;
ULONG   flCreate;
HWND    hwndClient;

INT main(VOID)
{
  /* Convert system pointer into hourglass pointer */
  WinSetPointer(HWND_DESKTOP,
    WinQuerySysPointer(HWND_DESKTOP,SPTR_WAIT,FALSE));

  hab = WinInitialize(0);
  hmq = WinCreateMsgQueue(hab,0);

  WinRegisterClass(hab,"Client",MainProc,CS_SIZEREDRAW,0);

  flCreate = FCF_SYSMENU       |
             FCF_SIZEBORDER    |
             FCF_TITLEBAR      |
             FCF_MENU          |
             FCF_MINMAX        |
             FCF_SHELLPOSITION |
             FCF_TASKLIST;

  hwndFrame = WinCreateStdWindow(HWND_DESKTOP,
                                 WS_VISIBLE,
                                 &flCreate,
                                 "Client",
                                 "My Dial",
                                 0L, 0,
                                 MAIN_FRAME,
                                 &hwndClient);

  /* Convert system pointer into arrow pointer */
  WinSetPointer(HWND_DESKTOP,
    WinQuerySysPointer(HWND_DESKTOP,SPTR_ARROW,FALSE));

  while (WinGetMsg(hab,&qmsg,0,0,0))WinDispatchMsg(hab,&qmsg);

  WinDestroyWindow(hwndFrame);
  WinDestroyMsgQueue(hmq);
  WinTerminate(hab);

  /* Beep when done */
  DosBeep(750,500);
  return(0);
}

MRESULT EXPENTRY MainProc(HWND hwnd,ULONG msg,MPARAM mp1,MPARAM mp2)
{
    HPS     hps;
    static  HWND hwndCirc;
    SWP     swp;
    switch(msg)

    {
        case WM_CLOSE:
            WinPostMsg(hwnd,WM_QUIT,0L,0L);
            return ((MRESULT)NULL);

        case WM_COMMAND:
            /* Exit option was selected in the menu bar */
            switch(SHORT1FROMMP(mp1))
            {
                case IDM_FILEEXIT:
                    WinPostMsg(hwnd,WM_QUIT,0L,0L);
                    return ((MRESULT)NULL);
            }
            return ((MRESULT)NULL);

        case WM_CONTROL:
            /* Process circular slider notification messages */
            if (SHORT1FROMMP(mp1) == ID_DIAL)
            {
              switch (SHORT2FROMMP(mp1))
              {
               /* Notification codes can be specified here */
              }
            }
            /* Default processing for other control window ids */
            return (WinDefWindowProc(hwnd,msg,mp1,mp2));

        case WM_CREATE:
            /* Create circular slider control */
            hwndCirc = WinCreateWindow(hwnd,
                        WC_CIRCULARSLIDER,
                        "My Dial Window",
                        WS_VISIBLE,
                        0, 0, 0, 0,          /* Position & size      */
                        hwnd,                /* Client window        */
                        HWND_TOP,
                        ID_DIAL,
                        NULL,NULL);

            /* Specify range of values for circular slider */
            WinSendMsg (hwndCirc,
                        CSM_SETRANGE,
                        MPFROMLONG(0L),
                        MPFROMLONG(100L));

            /* Specify scroll & tick mark increments */
            WinSendMsg (hwndCirc,
                        CSM_SETINCREMENT,
                        MPFROMLONG(10L),
                        MPFROMLONG(2L));

            /* Set initial value */
            WinSendMsg (hwndCirc,
                        CSM_SETVALUE,
                        MPFROMLONG(80L),
                        NULL);

            return (MRESULT)FALSE;

        case WM_SIZE:
            /* The frame window has changed in size */
            /* Recalculate size of circular slider  */
            WinQueryWindowPos(hwnd,&swp);
            WinSetWindowPos(hwndCirc,
                            HWND_TOP,
                            0, 0,
                            swp.cx,
                            swp.cy,
                            SWP_MOVE |
                            SWP_SIZE);
            return (MRESULT)NULL;

        case WM_PAINT:
            hps = WinBeginPaint(hwnd,0,NULL);
            WinEndPaint(hps);
            return (MRESULT)NULL;

        default:
            return (WinDefWindowProc(hwnd,msg,mp1,mp2));
    }
}

================
CIRCLE.RC
================
#include <os2.h>
#include "circle.h"

ACCELTABLE MAIN_FRAME
{
        VK_F3, IDM_FILEEXIT, VIRTUALKEY
}

MENU    MAIN_FRAME
{
    SUBMENU         "~File",            IDM_FILEMENU
    {
        MENUITEM    "E~xit\tF3",        IDM_FILEEXIT
    }
}

================
CIRCLE.H
================
#define MAIN_FRAME    255
#define IDM_FILEMENU  256
#define IDM_FILEEXIT  257
#define ID_DIAL       258

Graphical User Interface Support for Slider Controls

This section describes the support the slider control provides for graphical user interfaces (GUIs). Except where noted, this support conforms to the guidelines in the SAA CUA Advanced Interface Design Reference.

Since slider values all are mutually exclusive, only one of them can be selected at a time. Therefore, the only type of selection supported by the slider control is single selection.

Note: If more than one slider window is open, selecting values in one slider window has no effect on the values selected in any other slider window. For linear sliders, a black square is drawn in the center of the slider arm to show which slider control window has the focus.

An initial value is selected when the slider control is first displayed. If the application does not provide the initial selection for a linear slider (using the SLM_SETSLIDERINFO message) to position the slider arm, the value at the home position is selected automatically. The home position is the end of the slider that contains the lowest value on the scale.

Slider Navigation Techniques

The slider control supports the use of pointing devices and the keyboard for selecting values.

Pointing Device Support

A user can select slider values with a pointing device. The CUA guidelines define mouse button 1 (the select button) as the button for selecting values, and button 2 (the drag button) for dragging the slider arm to a value. These definitions also apply to the same buttons on any other pointing device, such as a joystick.

The select button and drag button can be used in conjunction with the following slider components to select slider values:

• Slider arm

Moving the pointer over the slider arm, then pressing and holding the select or drag buttons while moving the pointer, causes the slider arm to move in the direction the pointer is moving. When the button is released, the value closest to the slider arm position becomes the selected value.

• Slider shaft

Clicking the select button when the pointer is over the slider shaft causes the slider arm to move one increment in the direction of the pointer. For linear sliders, increments are determined by the initial values passed for the primary scale specified (SLS_PRIMARYSCALE1 or SLS_PRIMARYSCALE2) when the slider is created.

Clicking the drag button when the pointer is over the slider shaft causes the slider arm to move to the pointer's location.

• Slider buttons

Clicking the select button when the pointer is over a slider button causes the slider arm to move one increment in the direction the arrow on the slider button is pointing.

Slider buttons are optional. If used, two slider buttons are available to the user. The arrows on top of the slider buttons point to opposite ends of the slider. Both slider buttons are positioned at the same end of the slider.

For linear sliders, slider buttons are enabled by specifying the appropriate SLS_* value when the slider control window is created. For horizontal sliders, you can specify either SLS_BUTTONSLEFT or SLS_BUTTONSRIGHT. For vertical sliders, you can specify either SLS_BUTTONSBOTTOM or SLS_BUTTONSTOP. The default is no slider buttons. If more than one of these style bits is specified, no slider buttons are enabled.

• Detents

A detent is similar to a tick mark on a linear slider scale because it represents a value on the scale. However, unlike a tick mark, a detent can be placed anywhere along the slider scale instead of in specific increments.

A detent can be selected by moving the pointer over it and pressing the select button on the pointing device. When this happens, the slider arm moves to the position on the slider shaft indicated by the detent.

Keyboard Support

A user can select a value by using the navigation keys to move the slider arm to the value or by typing a value in an entry field, if one is provided by the application. The following list describes these methods of selecting slider values:

• Values can be selected using the Up, Down, Left, and Right Arrow keys to move the slider arm one increment at a time. The Up and Down Arrow keys are enabled for vertical sliders, and the Right and Left Arrow keys are enabled for horizontal sliders. If no tick mark exists on the scale in the requested direction, the slider arm does not move.

• If an Arrow key is pressed in conjunction with the Shift key, the slider arm moves to the next detent instead of the next tick mark. If no detent exists on the scale in the requested direction, the slider arm does not move.

• The Home and End keys can be used to select the lowest and highest values, respectively, in the))^

scale. If the application provides an optional entry field for the slider control, it must be implemented as follows:

- The user must be allowed to type a value into the entry field. - If the typed value is within the range of the slider scale, the slider arm moves to that value as soon as the value is typed. - No other action, such as pressing the Enter key, is required.