Purpose

Multi-button toolbar.

Syntax

winio@("%*mb[options], N, BITMAP_INDEX, BUTTON_STYLE, [BITMAP_NAME,] [BUTTON_STATE,] [BUTTON_ORDER])
integer,parameter::N
integer BITMAP_INDEX(N), BUTTON_STYLE(N), BUTTON_STATE(N), BUTTON_ORDER(N)
character(*) BITMAP_NAME

Modifiers

Grave accent (`) - used with the optional BITMAP_NAME argument that gives the name of a bitmap resource. The bitmap image provides a strip of images, one for each button. If the modifier is omitted then the control uses standard Microsoft image strips.

Tilde (~) - used with the optional BUTTON_STATE argument that describes the state of the each button.

Caret (^) - one callback function is provided and is used for all buttons.

Question (?) - one help string is provided. This contains "tooltip" help text for each button in turn.

Description

• N is the maximum number of items in the toolbar, including buttons, separators and hidden buttons.
• The argument called BITMAP_INDEX provides an array of zero based indexes when selecting an image from an image strip. So if BITMAP_INDEX(4)=7 then the 8th image in the strip will be used for the 4th button.
• The argument called BUTTON_STYLE provides an array of Microsoft button styles such as TBSTYLE_BUTTON (=0) and TBSTYLE_SEP (=1). TBSTYLE_BUTTON gives a simple button whilst TBSTYLE_SEP provides a separator between buttons. TBSTYLE_DROPDOWN (=8) adds drop-down functionality to a simple button.
• The argument called BITMAP_NAME requires the grave accent (`) and is used when an image strip is supplied. The name is that of a bitmap resource made up of button images. The depressed and greyed state button images are generated automatically by the control. By default these will be 16x16 images one after another in a horizontal strip. The option [bt_wd=w] provides for a button width w other than 16 whilst the option [bt_ht=h] provides for a button height other than 16. The option [ILC_bits=hex] represents parameters in the Microsoft ImageList_Create function and defaults to the hexadecimal value hex = ILC_COLOR24+ILC_MASK. The default mask colour is 0xC0C0C0 which is the same as using the option [mask=#C0C0C0]. This mask is the "transparent" bitmap background colour to use when creating the bitmap.
• If the grave accent is not used then %mb uses one of three standard Microsoft image strips. By default this corresponds to the Microsoft parameter IDB_STD_SMALL_COLOR (=0) that provides "standard" 16x16 images. The option [view] changes this to IDB_VIEW_SMALL_COLOR whilst [hist] gives IDB_HIST_SMALL_COLOR. Any one of these three can be increased in size to 24x24 bit images by adding the option [large].
• The argument called BUTTON_STATE requires the tilde modifier (~) and provides an array of Microsoft button state values such as TBSTATE_ENABLED (=4). If the modifier and argument are not provided then all buttons will be automatically enabled. The state array can be changed at runtime but the change must be followed by a CALL to window_update@(BUTTON_STATE) in order to apply the change.
• The argument called BUTTON_ORDER requires the option [adjustable] which allows the toolbar to be customised at runtime. Array elements can be initialised to -1 and will contain the user's ordering (with zero represently the first button displayed) after runtime customising. This ordering can be saved for the next time the toolbar is used.
  To change the order at runtime, hold down the shift key and drag a button to a different position in the toolbar or hide it by dragging it off the toolbar. Alternatively double click on the toolbar in order to open a "Customise" dialog.
• The argument called BUTTON_ORDER must be added when the option [adjustable] is used. If the button order is changed at runtime then the BUTTON_ORDER array receives the new order and this array can be saved for the next time the application is run. The array can be filled initially with the value -1 in order to apply the programmed ordering. If the BUTTON_STATE value of an item is initalised to TBSTATE_HIDDEN+TBSTATE_ENABLED then the item will not be displayed but will be available in the "Customise" dialog.
• By default the toolbar appears at the top of the "client" area. The option [bottom] provides the style CCS_BOTTOM whilst the option [left] provides the style CCS_LEFT. Up to three toolbars can be used at one time but they must be in different positions. When using %mb, the default %bg (Background Colour) background colour is set to "button face" colour and this cannot be changed when using [left].
• The option [border] adds the style WS_BORDER whilst other toolbar styles may be added via the option [style_bits=hex] where hex is a hexadecimal value such as [style_bits=200] (which is TBSTYLE_WRAPABLE=0x0200).
• The option [arrows] adds the extended style TBSTYLE_EX_DRAWDDARROWS that controls the appearance and behaviour of a TBSTYLE_DROPDOWN button. With this option an arrow is drawn. Clicking on the button provides a "command" whilst clicking on the arrow provides a "notification" (see below). Without this option, the arrow is not drawn and clicking on the button provides a "notification".
• The question modifier (?) requires a single help string presented in the standard way. For example, if it is presented in square brackets after the options then it might take the form [|Cut|Copy||Paste]. In this example the first pipe character (|) is used to indicate the character used to divide the string into a list. The tooltip help strings are then "Cut", "Copy" and "Paste" with a blank in the third position for a button separator.
• The option [strings] has the effect is to replace what otherwise would be tooltips by text below each button bitmap. Another option, [list] can be used with [strings] and the result is that the text appears to the right of each button bitmap rather than below it. The character string for the texts is constructed in the same way as you would construct tooltips and this string appears at the end of the list of winio@ arguments for %mb as it would do for %?mb. The combination represented by %?mb[strings] is not permitted.
• The caret modifier (^) requires a single callback function for the whole toolbar that uses the following callback "reasons". These are returned by a call to clearwin_string@("CALLBACK_REASON"):

  "MB_COMMAND"	This is the response to a TBSTYLE_BUTTON or TBSTYLE_DROPDOWN "command". CLEARWIN_INFO@("MB_BUTTON") provides the index of the button using the original order starting at button number 1 and including any separators. The callback should return the standard 0, 1 or 2 values to "close", "update" or "continue".
  "MB_DROPDOWN?"	This is the response to a TBSTYLE_DROPDOWN "notification". CLEARWIN_INFO@("MB_BUTTON") provides the index as for "MB_COMMAND". A typical response is to provide a drop-down menu as, for example, iw = winio@("%nw&",mbCtrl) iw = winio@("%pm[Item 1,Item 2, Item 3]",cb1,cb2,cb3) where mbCtrl is the INTEGER(7) value associated with %lc (Handle of Last Control) and used immediately after %mb. Typically the callback will return zero (TBDDRET_DEFAULT) to inform the control to continue with its default response.
  "MB_CUSTOMISE?"	Used with [adjustable] to notify the user has used a double click to open the "Customise" dialog. If the callback returns zero then the action is inhibited. Otherwise return 2.
  "MB_HELP"	Used with [adjustable] to notify the user has clicked on the Help button in the "Customise" dialog.
  "MB_DELETE?"	Used with [adjustable] to notify the user has started to move a button. If the callback returns zero then the action is inhibited. Otherwise return 2.
  "MB_INSERT?"	Used with [adjustable] to notify the user has finished moving a button. If the callback returns zero then the action is inhibited. Otherwise return 2.

Notes

Introduced with FTN95 8.20.

See also

%tb (Bitmap Button), %ib (Image Button)