Sash Item

The sash item creates items whose appearance is a separator bar with a handle on it which can be used to divide a dialog box into separate horizontal panes. The user can grab the sash handle and drag the sash up and down the dialog box changing the amount of display space in each pane. The item hook function controls how far the sash can move and the resizing/redisplaying of items in each pane.

The hook function is responsible for performing the resizing of items on each side of the sash; the sash item handler does not do any item resizing itself. The item hook can, and should, perform the resizing using both a motion function hook and button up event processing logic.

Item list specification

The DialogItemRsc field extent specifies the horizontal location of the sash. The y position should be defined and the x, width and height fields are ignored and should be 0.

The type field should be Sash.

The ID determines the DItem_SashRsc instance to load.

The attributes field can be ON or OFF and optionally combined with HIDDEN. It will usually be ON.

The itemArg field is unused and should usually be set to 0.

The label field is unused for sash items and should be set to "".

The auxInfo field is unused for sash items and should be set to "".

The following is an example of a sash item list specification:

{{0, 0, 10*YC, 0}, Sash, SASHID_Example, ON, 0, "", ""}

Item resource specification

The sash item is defined in a resource file with the following structure:

typedef struct ditem_sashrsc
{
        ULong helpInfo;
        ULong helpSource;
        long itemHookId;
        long itemHookArg;
        long topBorder;                         // min dist. from top (in dcoords)
        long bottomBorder;                              // min dist. from bottom (in dcoords)
        ULong attributes;
} DItem_SashRsc;

The DItem_SashRsc structure has the following unique fields. See CommonItemResourceFields for a description of any field not in this table

Field	Description
topBorder	Specifies the minimum distance from the top of the dialog box that the sash can be moved.
bottomBorder	Specifies the minimum distance from the bottom of the dialog box that the sash can be moved.

The following is an example of a sash item resource.

DItem_SashRsc SASHID_Example=
{ 
        NOHELP, MHELP, HOOKID_Sash, NOARG, 5*YC, 5*YC, 0 
}; 

The following table lists possible values for the attributes field (described above) and the meaning of those values:

attributes Value	Meaning
SASHATTR_VERTICAL	Indicates the sash is to be vertical.
SASHATTR_ALLGRAB	The entire width of the sash is grab enabled as opposed to the grab box.
SASHATTR_WIDE	The item itself and the grab area are wider
SASHATTR_SOLIDTRACK	The motion track bar is solid instead of dotted
SASHATRR_SAVEPOSITION	The sash position is automatically saved to the preferences file.

Item hook function messages

The following messages are sent to item hook functions that are attached to sash items:

          DITEM_MESSAGE_BUTTON

When handling the DITEM_MESSAGE_BUTTON message for a BUTTONTRANS_DOWN event, the item hook function can use a motion function (the u.button.motionFunc member) to allow the application to track cursor movement while the button is down. Using a motion function would allow the MDL application to dynamically resize the panes as they are "resized" by the sash item.

Sash item functions

Function	Description
mdlDialog_sashGetInfo	retrieves detailed information about a sash item.
mdlDialog_sashGetInfoEx	retrieves detailed information about a sash item.
mdlDialog_sashIsVertical	returns a value indicating whether the sash is vertically oriented.
mdlDialog_sashSetInfo	sets detailed information about a sash item.
mdlDialog_sashSetInfoEx	sets detailed information about a sash item.