Microscroll Custom Control SDK Sample
Microsoft Windows 3.1
(c)1990-1992 Microsoft Corporation, All Rights Reserved



Introduction:
-------------

The MicroScroll Custom Control is an interface extension to Microsoft
Windows.  The control is implemented in a DLL that includes interface
functions for the Windows Software Development Kit Dialog Editor.

The MicroScroll is essentially a scrollbar without a thumb or thumbtrack,
and is capable of being much smaller than a standard scrollbar.  This
means that it can be placed next to an edit control to create a spin
button, such as in Control Panel's Date/Time dialog.  It sends scroll
messages to its associate window to indicate that it was clicked.
Initially the associate window is the parent of the control.  The associate
window can do whatever it desires with the messages, which is useful in
implementing many other classes of controls.

The remaining sections in this file describe the programming interface
to the Microscroll control:

    Definitions
    Styles
    Messages and Message API Functions
    Notification Codes



Definitions:
------------

  Associate Window
    The window that receives all messages sent from a MicroScroll
    control.  This is, by default, the parent window of the control
    but may be any other window.


  Range:
    The values that define the minimum and maximum values of
    the position.  The range minimum defines the lowest value of
    the position, and the range maximum defines the highest position.

    The current position must lie between these two values, and the
    minimum is always less than or equal to the maximum. The range must
    be within the maximum limits of 0 to 32767.

  Current Position:
    A value within the range that is sent to the associate window
    with WM_VSCROLL and WM_HSCROLL message.  It can be changed with
    the MSM_SETCURPOS message or by clicking the arrows of the control.

    Clicking the left and up arrows decrements the current position,
    and clicking the right and down arrows increment the current
    position.  If the MSS_INVERTRANGE style is used, the left and
    up arrows increment the current position and the right and
    down arrows decrement the current position.

    The current position must exist in the range, and therefore must
    be a value from 0 to 32767.




Styles:
-------

  MSS_VERTICAL:
    Specifies a MicroScroll with an up arrow and a down arrow.
    This is the default style if neither MSS_VERTICAL nor
    MSS_HORIZONTAL are specified.  A MicroScroll of this style
    will send WM_VSCROLL messages to the associate window.  The
    scroll code SB_LINEUP is sent when the up arrow is pressed,
    and the scroll code SB_LINEDOWN is sent when the down arrow
    is pressed.

    This style cannot be used with MSS_HORIZONTAL.


  MSS_HORIZONTAL:
    Specifies a MicroScroll with a left arrow and a right arrow.
    A MicroScroll created with this style will send WM_HSCROLL
    messages to the associate window.  The scroll code SB_LINEUP
    is sent when the left arrow is pressed, and the scroll code
    SB_LINEDOWN is sent when the right arrow is pressed.

    This style cannot be used with MSS_VERTICAL.


  MSS_NOPEGSCROLL:
    Specifies a MicroScroll that will not send scroll messages
    if the current scroll position is at the minimum or maximum
    of the range and the user has clicked on an arrow that would
    send the position outside of the range.

    When this style is specified, scroll messages are only sent
    when the position of the MicroScroll changes in response to
    a user action.  Without this style, the MicroScroll control will
    send scroll messages repeatedly when the current position is
    pegged at either the minimum or maximum.


  MSS_TEXTHASRANGE:
    Specifies that the text given for the MicroScroll control will
    be parsed to set the initial range (minimum, maximum), and
    current position of the control.

    The text must be in the format:
        min,max,pos     Example:  1,99,50

    Where min is the initial minimum of the range, max is the
    initial maximum of the range, and pos is the initial position
    that must be with the range.  If the values are not valid for
    a MicroScroll range, that is between 0 and 32767, then the
    defaults 1, 9, and 5 are used for the minimum, maximum, and
    position respectively.


    The defaults will be used if there is any error in parsing
    this text.  Whitespace is not allowed between the values and
    commas.  If the position specified in the text is not in the
    specified range, then it is set to the midpoint of the range.
    No scrolling messages are sent to the associate window on this
    change.


  MSS_INVERTRANGE:
    Specifies that the change in the current position on clicking
    the up/left and down/right arrows is inverted.  Without this
    style, up/left decrements the current position and down/right
    increments it.  With MSS_INVERTRANGE, up/left increments the
    current position and down/right decrements it.



Messages and Message API Functions:
-----------------------------------

If the wParam or lParam message parameters are not mentioned then
they are not used.  All Message API functions take a window handle
to identify the control to be affected.



  MSM_HWNDASSOCIATESET
  HWND FAR PASCAL MSHAssociateSet(HWND hWnd, HWND hWndAssociate);

    Changes the current associate window of the control.

    Parameters:     Message   Function        Definition
                    wParam    hWndAssociate   New associate window handle.


    Return Value:   Previous associate window handle; contained in
                    low-order word if returned from SendMessage.

    Comments:       The control always sends a WM_COMMAND message with the
                    MSN_ASSOCIATELOSS to the previous associate window and
                    a MSN_ASSOCIATEGAIN to the new associate window.



  MSM_HWNDASSOCIATEGET
  HWND FAR PASCAL MSHAssociateGet(HWND hWnd);

    Returns the current associate window of the control.

    Parameters:     None

    Return Value:   Current associate window handle; contained in
                    low-order word if returned from SendMessage.



  MSM_DWRANGESET
  DWORD FAR PASCAL MSDwRangeSet(HWND hWnd, WORD iMin, WORD iMax);

    Changes the current range of the control, moving the position
    if the current position is outside of the new range.

    Parameters:     Message         Function    Definition
                    LOWORD(lParam)  iMin        New minimum of the range.
                    HIWORD(lParam)  iMax        New maximum of the range.

    Return Value:   Previous range:  minimum is in the low-order word,
                    maximum in the high-order word.

    Comments:       The control always sends a WM_COMMAND message with the
                    MSN_RANGECHANGE notification to the associate window.
                    If the current position is outside the new range, the
                    position is set to the middle of the range and the
                    control sends a scroll message with SB_THUMBTRACK.




  MSM_DWRANGEGET
  DWORD FAR PASCAL MSDwRangeGet(HWND hWnd);

    Returns the current range of the control.

    Parameters:     None

    Return Value:   Current range:  minimum is in the low-order word,
                    maximum in the high-order word.



  MSM_WCURRENTPOSSET
  WORD FAR PASCAL MSWCurrentPosSet(HWND hWnd, WORD iPos);

    Changes the current position of the control if the new position
    is within the current range.,

    Parameters:     Message     Function    Definition
                    wParam      iPos        New position.

    Return Value:   Previous position; contained in low-order word if
                    returned from SendMessage.  -1 is returned if the
                    new position is not in the current range.

    Comments:       If the new position is in the current range, the
                    control always sends a scroll message with the
                    SB_THUMTRACK code notification to the associate window.



  MSM_WCURRENTPOSGET
  WORD FAR PASCAL MSWCurrentPosGet(HWND hWnd);

    Returns the current position of the control.

    Parameters:     None

    Return Value:   Current position; contained in low-order word if
                    returned from SendMessage.



  MSM_FNOPEGSCROLLSET
  BOOL FAR PASCAL MSFNoPegScrollSet(HWND hWnd, BOOL fNoPegScroll);

    Changes the MSS_NOPEGSCROLL style bit in the control.

    Parameters:     Message   Function        Definition
                    wParam    fNoPegScroll    TRUE to set the
                                              MSS_NOPEGSCROLL style or
                                              FALSE to clear it.

    Return Value:   Previous state of the MSS_NOPEGSCROLL style bit;
                    contained in the low-order WORD if returned from
                    SendMessage.


  MSM_FNOPEGSCROLLGET
  BOOL FAR PASCAL MSFNoPegScrollGet(HWND hWnd);

    Returns the current state of the the MSS_NOPEGSCROLL style bit in
    the control.

    Parameters:     None

    Return Value:   Current state of the MSS_NOPEGSCROLL style bit;
                    contained in low-order word if returned from
                    SendMessage.



  MSM_FINVERTRANGESET
  BOOL FAR PASCAL MSFInvertRangeSet(HWND hWnd, BOOL fInvertRange);

    Changes the MSS_INVERTRANGE style bit in the control.

    Parameters:     Message     Function        Definition
                    wParam      fInvertRange    TRUE to set the
                                                MSS_INVERTRANGE style or
                                                FALSE to clear it.

    Return Value:   Previous state of the MSS_INVERTRANGE style bit;
                    contained in the low-order WORD if returned from
                    SendMessage.



  MSM_FINVERTRANGEGET
  BOOL FAR PASCAL MSFInvertRangeGet(HWND hWnd);

    Returns the current state of the the MSS_INVERTRANGE style bit in
    the control.

    Parameters:     None

    Return Value:   Current state of the MSS_INVERTRANGE style bit;
                    contained in low-order word if returned from
                    SendMessage.



  MSM_CRCOLORSET
  COLORREF FAR PASCAL MSCrColorSet(HWND hWnd, WORD iColor, COLORREF cr);

    Changes a specified color used in the control.

    Parameters:     Message     Function    Definition
                    wParam      iColor      Index of the color to change.
                    lParam      cr          New COLORREF value for the color.

                    iColor can be one of the following:
                        MSCOLOR_FACE        Face color
                        MSCOLOR_ARROW       Arrow color
                        MSCOLOR_SHADOW      Dark shadowing color
                        MSCOLOR_HIGHLIGHT   Bright highlight color
                        MSCOLOR_FRAME       Outer frame color



    Return Value:   Previous color for the given index.  0L if the color
                    index is out of range.



  MSM_CRCOLORGET
  COLORREF FAR PASCAL MSCrColorGet(HWND hWnd, WORD iColor);

    Returns a specified color used in the control.

    Parameters:     Message     Function    Definition
                    wParam      iColor      Index of the color to change.

                    iColor can be one of the following:
                        MSCOLOR_FACE        Face color
                        MSCOLOR_ARROW       Arrow color
                        MSCOLOR_SHADOW      Dark shadowing color
                        MSCOLOR_HIGHLIGHT   Bright highlight color
                        MSCOLOR_FRAME       Outer frame color



    Return Value:   Current color for the given index.  -1 if the
                    control is using a default color.  0L if the color
                    index is out of range.






Notification Codes:
-------------------

  MSN_ASSOCIATELOSS:
    Notifies the current associate window of a Microscroll that it
    is no longer the associate.

  MSN_ASSOCIATEGAIN
    Notifies a window that it is becoming the current associate window
    of a Microscroll control.

  MSN_RANGECHANGE
    Notifies the associate window that the Microscroll's range and
    position have changed.
