N is the number of sheets. sheet1 to sheetN are handles for
the various sheets returned by %sh - Property Sheet.
Each sheet is set up using a complete winio@ format and %sh - Property Sheet.
clearwin_info@('SHEET_NO') can be used to return the current visible sheet
number which is initially set to one. Alternatively, a grave accent modifier
can be supplied in order to set the initial sheet (at a value other than one)
and to change the sheet number under program (rather than user) control. The
program can change the sheet number by changing sheet_n and calling
%ca - Caption can be used with %sh to provide a caption. The caption can include an
accelerator key indicator '&' which operates in the same way as in a menu
or on a button to select the sheet.
If a call is made to the Windows API function EnableWindow to disable one
sheet, then that sheet will no longer be selectable unless/until the window is
re-enabled. If the sheet that is currently visible is disabled, another sheet
will not automatically be selected. However, when another sheet is selected, a
disabled sheet will not be re-selectable.
option can be set to the keyword ms_style in order to use a Microsoft tab
control instead of the internal ClearWin+ control (the appearance of the
Microsoft tab control is changed by using the XP manifest). option can also
be set to the keywords bottom and hot_track both of which imply ms_style. [bottom] places
the tabs at the bottom of the control whilst [hot_track] changes the appearance of the
tab when the mouse hovers over it.
A new option [frame] has been added at version 8.40. This provides a blank tabbed control to which tabs
can be added at runtime and thus provides an alternative to the %fr - MDI Frame multi-document format. %sh - Property Sheet sheets are required when
defining %ps but these only provide templates for subsequent calls to a function NEW_TAB@(INDEX, CAPTION) where INDEX is the
index of the sheet (in the order they are defined in the program) and CAPTION is the caption to use for the tab.
Both %ps and its %sh sheets can take a pivot to allow for resizing. Initial tests have focused on sheets that contain
a single %re - Multiline Edit Box, %eb - Edit Box or %gr - Graphics Region control. For %re and %eb, the function EditFileClosePrompt@ can be called
with the first argument set to -1 (i.e. -1_7). This provides a prompt for all associated tabs that are open.
In this context, %sh sheets can include a main menu (%mn - Menu). When a tab is selected, this menu becomes the main menu for the
application. The main window and the sheets can also include %mb - Multi-button Toolbar toolbars that work in the same way - adjusting to the
currently active tab.
A new option [tooltips] can be used with [frame]. This activates tooltips for the tab captions. ClearWin+ will then
provide default tooltips which can be over-ridden by calling SET_TAB_TOOLTIP@ immediately after creating a tab.
When defining a %sh sheet, the %if - Initial Focus format code should be used to indicate the control with the initial focus. The Windows
handle (HWND) of this control is used in the following associated functions.
If INDEX=1 then the first %sh sheet defined in the program is used by the call and so on. CAPTION is the caption for the tab.
Returns the Windows HWND of the control with the initial focus (%if - Initial Focus).
Returns the Windows HWND of the control with the initial focus (%if - Initial Focus) in the currently selected tab.
Deletes the currently selected tab and returns the Windows HWND of the deleted control with the initial focus (%if - Initial Focus).
Called immediately after creating a new tab in order to change its tooltip from the default. Requires %ps[tooltips].