Purpose

To produce layered windows in a card-index style (property sheet).

Syntax

winio@('%Nps[option]', sheet1, sheet2, . . . , sheetN)
winio@('%`Nps[option]', sheet1, sheet2, . . . , sheetN, sheet_n)
integer sheet1, sheet2, . . . , sheetN     (input)
integer sheet_n                         (input/output)

Modifiers

Grave accent (`) - provides for a variable (sheet_n) to set and return the current sheet number. sheet_n must be SAVEd or global (e.g. in a module or common block).

Caret (^) - the call-back function is called each time the sheet is changed and when the first sheet is initially displayed.

Tilde (~) - the list of "state controls" is replaced by a single array.

Description

N is the number of sheets. sheet1 to sheetN are variables that have been introduced when defining the various %sh (Property Sheet) sheets.

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 see_propertysheet_page@(sheet_n).

%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.

INTEGER(7) NEW_TAB@(INDEX,CAPTION)
INTEGER INDEX
CHARACTER(*) CAPTION
If INDEX=1 then the first %sh (Property Sheet) 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)).

INTEGER(7) CURRENT_TAB@()
Returns the Windows HWND of the control with the initial focus (%if (Initial Focus)) in the currently selected tab.

INTEGER(7) DELETE_TAB@
Deletes the currently selected tab and returns the Windows HWND of the deleted control with the initial focus (%if (Initial Focus)).

SUBROUTINE SET_TAB_TOOLTIP@(TIP)
CHARACTER(*) TIP
Called immediately after creating a new tab in order to change its tooltip from the default. Requires %ps[tooltips].

Notes

In some contexts sheet1 etc. must be accessible after the property sheet has been closed. In which case they could, for example, be given the SAVE attribute. Alternatively %ps can be combined with %wt which ensures that the process of closing the window is completed before returning control to the caller.
If an individual sheet is closed (e.g. by placing a button without a callback function in the sheet) then the parent window will close.

See also

%sh (Property Sheet)