TAB
A tab control looks like a notebook folder. It has "tabs" that the user can click upon to select. Each tab has its own label and/or an icon. The other part (blank area) of the tab is where you can add other controls whose state/contents will typically be altered whenever the user selects one of the tabs.
Uses
A Tab control is useful for letting the user switch between different "pages" or windows. For example, REXX Programmer Center uses a tab control to switch between various REXX scripts that you may have open. (But only the tabs are shown. The tab control's height is set so that there is no blank area below the tabs).
Styles
Shortcut | The Shortcut box lets you enter a keyboard shortcut that will automatically select this control whenever the user presses that shortcut. |
A TAB normally displays tabs in a notebook appearance. But if desired, you can instead specify one of the following 2 styles to change the tab appearance:
Buttons | Tabs appear as push buttons. |
Flat buttons | (FLAT) Tabs appear as flat push buttons. |
Normally, the TAB control gets the focus when the user clicks upon a tab. But if desired, you can instead specify one of the following 2 styles:
On tab click | (ONFOCUSON) The tab gets the focus when the user clicks on a tab button. Used with the button appearance styles. |
Never | (NOFOCUS) The TAB control never gets the focus when the user clicks on a tab. |
Normally, each tab is sized to exactly fit its label. But if desired, you can instead specify one of the following 2 styles:
Stretched right | (RIGHTJUSTIFY) The width of each tab is increased, if necessary, so that each row of tabs fills the entire width of the tab control. This is useful with the MULTILINE style. |
Fixed width | (FIXED) All tabs are sized the same as the tab with the largest label. |
In addition to the above, a TAB may have any, all, or none of the following styles:
Multiple Select | (MULTI) Several tabs can be selected simultaneously by holding down the CTRL key when clicking. This style is applicable only with the button appearance styles. |
Vertical tabs | (VERTICAL) The tab labels are displayed vertically. (Without this style, tabs appear horizontally). |
Bottom tabs | (BOTTOM) Tabs appear beneath the blank area. (Without this style, tabs appear at the top). If using the VERTICAL style also, then tabs appear on the right instead of the left. |
Owner drawn | (OWNER) DRAWITEM events happen for your window whenever the tabs need to be drawn, and your WM_DRAWITEM event handler must draw the tabs. A MEASUREITEM event also happens so you can specify the height of a tab. |
Tool tips | (TIPS) Creates a tooltip for the control. |
HotTrack | (TRACK) Gives the control a visible outline as the pointer passes over it. Also known as hover selection, or hot tracking. |
Icon on left | (ICONLEFT) A tab's icon is placed to the left of its label. (Without this style, the icon is placed to the right). This style is not applicable unless you use a fixed width. |
Label on left | (LABELLEFT) The label is positioned to the left instead of centered within the tab. This style is not applicable unless you use a fixed width. |
Multiple rows | (MULTILINE) By default, a tab control displays only one row of tabs. If not all tabs can be shown at once, the tab control displays some arrows so that the user can scroll additional tabs into view. You can cause a tab control to display multiple rows of tabs, if necessary, by specifying the MULTILINE style. In this way, all tabs can be displayed at once. The tabs are left-aligned within each row unless you also specify the RIGHTJUSTIFY style. In this case, the width of each tab is increased so that each row of tabs fills the entire width of the tab control. |
Scroll select | (OPPOSITE) Unneeded tabs scroll to the opposite side of the control when a tab is selected. |
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). For example, to make a group of radio buttons function properly, the first radio button should have the GROUP style, and the subsequent buttons must not. |
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 TAB can have the following extra styles:
Item Index | (INDEX) Use the numeric value associated with a tab, rather than its label, when setting and retrieving the current selection. |
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). |
Align text right | (RIGHT) Gives the control generic right-aligned properties (as opposed to the default of left-aligned properties). |
Read right-to-left | (RTLREADING) Displays the window text using right-to-left reading order properties (instead of the default of left-to-right). |
Transparent | The control is to be transparent. Any controls that are beneath this one are not obscured. |
Events
A TAB generates the following events:
Event name When it occurs SELCHANGING The user has selected a new tab, but the TAB has not yet highlighted his choice. If you handle this event, you can return a 1 to prevent his new selection. SELCHANGED A new tab has been selected. FOCUSCHANGE The focus has changed. GETOBJECT The user has dragged some item and dropped it on the TAB control. This event happens only if the DRAGOBJECT style is specified. RELEASE The TAB control is releasing mouse capture. KEYDOWN The user pressed a key while the TAB control has the input focus. CLICK The user has clicked the left mouse button within the control. DBLCLK The user has double-clicked the left mouse button within the control. RCLICK The user has clicked the right mouse button within the control.
REXX Variable
Each tab can have its own label and/or an icon. Each tab can also have a unique numeric value that you associate with it. This number can be used for any purpose. For example, you could have a window handle associated with each tab.
A TAB must have a REXX variable associated with it. Before opening the window which contains the TAB, you must set this variable's value to the label of the tab you wish selected, or if using the INDEX style, the numeric value you associated with that tab.
Dynamically add/remove a TAB
You can dynamically add a TAB to an already open window by calling GuiAddCtl. You must pass a line that describes the control. The format for this line is:
TAB X, Y, Width, Height, Styles, ExtraStyles, VariableName, Accelerator, TabX 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.
Tab is the name of a STRING resource containing the labels for the tabs. You can omit this if you instead wish to later add each tab using GuiAddCtlText().
If you initialize a TAB from some STRING resource, then before adding a TAB, you should set its associated REXX variable to either the label of the tab you wish selected, or if using the INDEX style, whatever numeric value you assigned to it. Here we create a TAB control with an REXX variable name of MyTab. The labels are gotten from the STRING resource named MyTabLabels. We select the tab with the label "Tab 1".
/* Select "Tab 1" */ MyTab = "Tab 1" /* Create the TAB control */ error = GuiAddCtl("TAB 10,10,100,80, BORDER, CLIENTEDGE|QUIET, MyTab, MyTabLabels")Note: If you wish the TAB to have no selected item, then either DROP its associated variable, or set the variable to an empty string.
You can dynamically remove a TAB by calling GuiRemoveCtl. Here we remove the above TAB:
error = GuiRemoveCtl("MyTab")
Add labels
You can dynamically add new labels by calling GuiAddCtlText. You pass the quoted name of the REXX variable associated with the TAB. You also pass the desired label to add. If desired, you can pass an additional arg which is whatever numeric value you want associated with the label. Here we add a new label of "My tab" and associate some window handle with it:
GuiAddCtlText("MyTab", "My tab", MyWindowHandle)
Remove labels
You can remove a label by calling GuiRemoveCtlText. You pass the quoted name of the REXX variable associated with the TAB. You also pass either the label you wish to delete, or if using the INDEX style, pass the numeric value you associated with it. Here we delete the label "My tab":
error = GuiRemoveCtlText("MyTab", "My Tab")To delete the currently selected label, then call GuiRemoveCtlText, and pass an empty string for the label to delete:
error = GuiRemoveCtlText("MyTab", "")To delete all labels, then call GuiRemoveCtlText, and pass only the name of the variable associated with the control:
error = GuiRemoveCtlText("MyTab")
Selecting a label
To select a label, first set the associated REXX variable to the desired label, or if using the INDEX style, set the variable to the numeric value you associated with that label. Then call GuiSetCtlValue, passing that quoted variable name. Here we select the label that is associated with the window handle we stored in the variable MyWindowHandle (assuming the INDEX style):
MyTab = MyWindowHandle GuiSetCtlValue("MyTab")To unselect all labels, DROP the variable:
DROP MyTab GuiSetCtlValue("MyTab")Alternately, you can set the variable to an empty string:
MyTab = "" GuiSetCtlValue("MyTab")
Querying the selected label
To determine which label has been selected, call GuiGetCtlValue. This will set its associated REXX variable to the control's current selection. For example, here we query the above control's selection:error = GuiGetCtlValue("MyTab") IF error == "" THEN SAY "Selected tab:" MyTabNote: If using the INDEX style, then the variable is set to the numeric value you associated with the label.
If there's no selection, then the rexx variable is DROP'ed:
error = GuiGetCtlValue("MyTab") IF error == "" THEN DO IF EXISTS("MyTab") THEN SAY "Selected tab:" MyTab ELSE SAY "No selection" END
Change a label and/or index
To change the label of the currently selected item, call GuiSendMsg to send the TAB a "SETITEM" message. Before calling GuiSendMsg, you must initialize the variable !Mask to "LABEL", and set the variable !Label to the new label. Here we change the current item's label to "My label":!Mask = "LABEL" !Label = "My Label" GuiSendMsg("MyTab", "SETITEM")To change the index of the currently selected item, you must initialize the variable !Mask to "INDEX", and set the variable !Index to the new index. Here we change the current item's label to 50:
!Mask = "INDEX" !Index = 50 GuiSendMsg("MyTab", "SETITEM")Note that you can set both the index and label simultaneously by setting !Mask to "LABEL|INDEX":
!Mask = "LABEL|INDEX" !Label = "My Label" !Index = 50 GuiSendMsg("MyTab", "SETITEM")