SPIN

A spin is an entry that deals with numeric values. It consists two arrows, oriented up and down, or left and right. The arrows will cycle the spin through its numeric range. The up/right arrow increments the value, and the down/left arrow decrements the value. The spin can also work in conjunction with an entry or text control, referred to as its "buddy window". When a spin has a buddy window, that entry or text will display the current numeric value. If the buddy window is an entry, then the user can click inside of the entry box, and type a number in just as he would manipulate an entry. His input is checked against the spin's upper and lower limit, and forced to fall within that range. When the entry is activated, he can also use the up and down arrow keys (on the keyboard) to cycle through the range.


Uses

Useful for allowing the user to specify some numeric parameter such as how many copies of a document he would like printed. Because the user can type a specific value into the entry, this offers an easy way to pick out one particular value. (ie, It's easy to make fine adjustments with a spin).


Styles

Shortcut The Shortcut box lets you enter a keyboard shortcut that will automatically select this control whenever the user presses that shortcut.

A SPIN must be created with one of the following 2 styles for its Orientation:

Horizontal Orients the arrows pointing left and right.
Vertical Orients the arrows pointing up and down.

A SPIN must also be created with one of the following 3 styles for its Alignment:

Left Places the spin arrows on the left edge of the buddy control. The buddy control is moved to the right and its width decreased to accommodate the width of the arrows.
Right Places the spin arrows on the right edge of the buddy control. The buddy control is moved to the left and its width decreased to accommodate the width of the arrows.
Unattached (DETACH) The spin arrows are not placed alongside the buddy control, and may be visually distanced from the buddy control.

In addition to the above, a SPIN may have any, all, or none of the following styles:

Auto Buddy (BUDDY) Automatically uses the previously added ENTRY or TEXT control as the buddy control. The buddy control is used to display the SPIN's current value. Do not use this style if you plan to manually set a SPIN's buddy control with GuiAddCtlText.
Update value (INT) Causes the spin control to set the text of the buddy control (using a SETTEXT message) when the numeric value changes. The text consists of the position formatted as a decimal or hexadecimal string.
No Thousands (NOTHOUSANDS) Does not insert a thousands separator between every three decimal digits.
Wrap value (WRAP) Causes the numeric value to “wrap” if it is incremented or decremented beyond the ending or beginning of the range.
Arrow keys (KEYS) Causes the control to increment and decrement the numeric value when the UP ARROW and DOWN ARROW keys are pressed.
Hot track (HOTTRACK) Gives the control a visible outline as the pointer passes over it. Also known as hover selection, or hot tracking.
No Sibling (NOSIBLING) Prevents this control from drawing into any overlapping controls.
Group Marks this control as the first of a group of controls in which the user can move from one control to the next with the arrow keys. All subsequent controls (after this first control) belong to the same group up to the next control that has its GROUP flag set. (ie, One group ends where the next begins).
Tabstop The user can move to this control using the TAB key.
Disabled Control is initially disabled. You can later enable it with a call to GuiSetCtlPlacement.
Hide Control is hidden. You can later make it visible with a call to GuiSetCtlPlacement.
Border Has a border.


Extra styles

A SPIN can have the following extra styles:

Quiet Do not report any events for this control.
Modal Frame (MODALFRAME) Has a double border.
Static Edge (STATICEDGE) Has a three-dimensional border intended to be used for windows that do not accept user input.
Client Edge (CLIENTEDGE) Has a 3D look comprised of a border with a sunken edge.
Accept files (FILES) Accepts drag-and-drop files (ie, the DROPFILES event).
Transparent The control is to be transparent. Any controls that are beneath this one are not obscured.


Events

A SPIN generates the same events as a SLIDER.


REXX Variable

A SPIN must have a REXX variable associated with it. A SPIN must also have a buddy control of the ENTRY type. This ENTRY displays the current value. You can either use the BUDDY style for the SPIN (in which case Reginald will pick a preceding ENTRY control as the buddy), or you can manually set the buddy control as described below.

If you use the BUDDY style, then before opening the window which contains the SPIN, you must set the buddy control's variable to the desired numeric value for the spin.


Dynamically add/remove a SPIN

You can dynamically add a SPIN to an already open window by calling GuiAddCtl. You must pass a line that describes the control. The format for this line is:

SPIN X, Y, Width, Height, Styles, ExtraStyles, VariableName, Accelerator, LowLimit HighLimit
X and Y is the position of the top left corner of the control, relative to the window's top left corner.

Width and Height are the size of the control, in pixels.

Styles and ExtraStyles are those listed above, with each style separated by a | character.

VariableName is the variable name to be associated with the control.

Accelerator is the keyboard shortcut that causes the control to be selected for user input.

LowLimit is the lowest numeric value that the spin can be set to. HighLimit is the highest numeric value that the spin can be set to.

For example, here we add a SPIN at an X Y position of 10, 10, with a width and height of 80 and 20, with the style INT, extra styles of CLIENTEDGE and QUIET, a REXX Variable name of MySpin, a low limit of -10 and a high limit of 20.

error = GuiAddCtl("SPIN 10,10,80,20,INT, CLIENTEDGE|QUIET,MySpin,,-10 20")
You can dynamically remove a SPIN by calling GuiRemoveCtl. Here we remove the above spin:
error = GuiRemoveCtl("MySpin")

Change a SPIN's buddy control.

You can change a SPIN's buddy control by calling GuiAddCtlText. You pass the REXX variable name of the spin, and then a second arg which is the REXX variable name (or handle) associated with the buddy control. Here we change the above spin's buddy control to the control associated with the variable MyTextControl:

error = GuiAddCtlText("MySpin", "MyTextControl")
Note: The buddy control should be a TEXT or ENTRY control type. If using a TEXT type, then make sure you have associated a REXX variable name with it.

After you set the buddy control, then the spin's current value will be displayed in that buddy control.


Change a SPIN's value

You can dynamically change a SPIN's value by calling GuiSetCtlValue. You first set the REXX variable associated with the buddy control (ie, not the SPIN's variable) to the desired value, and then call GuiSetCtlValue, passing that variable name. For example, assuming that our buddy control has an associated variable of MyEntry, here we set the above spin to the value 5:

MyEntry = 5
error = GuiSetCtlValue("MySpin")


Query a SPIN's value

You can query a SPIN's value by calling GuiGetCtlValue, and passing the name of the variable associated with the buddy control. This will set the buddy control's associated REXX variable to the spin's current value. For example, here we query the above spin:

error = GuiGetCtlValue("MySpin")
IF error == "" THEN SAY "Spin value:" MyEntry

Decimal or hexadecimal

A SPIN's value can be displayed in either decimal or hexadecimal notation. To change the notation, send a SETBASE message. For the third arg, pass a 10 for decimal or 16 for hexadecimal. Here we set hexadecimal:

error = GuiSendMsg("MySpin", "SETBASE", 16)

Change a SPIN's range

You can change a SPIN's range by sending a SETRANGE message. For the fourth arg, pass 2 numbers. The first number is the desired minumum range, and the second number is the desired maximum range. Here we set a range of 1 to 10:

error = GuiSendMsg("MySpin", "SETRANGE", , 1 10)

Note: The third arg is always omitted.