%ib provides an enhanced and simplified replacement for %tb - Bitmap Button. Like %tb - Bitmap Button, %ib can
be used to create toolbars or rectangular arrays of image buttons. However,
only one flat image is required for each button - all the variants are created
automatically. Also, text can be automatically added to the image.
%n.mib creates block of buttons n buttons wide and m deep.
n and m are optional and both default to 1. When n is used
.m is optional. The arguments consist of the following triplet
repeated for each button in turn: bitmap_name, stat_ctrl, cb_func.
Note that every button has a call-back function.
bitmap_name is the name of a bitmap resource. If text is to be added to
the image, the name is followed by a forward slash and then the text. For
example, here is the code for a single button with some text:
The button text can include newline characters:
The integer variable stat_ctrl encodes the state of the button with
1=up, 2=down, 3=greyed, and 4=push button. States 1 and 2 are used with a
button that toggles up and down, i.e. a button that requires two separate
clicks to return it to the up state. Each time the user presses and releases a
button that is not greyed, the call-back function is invoked with call-back
reason 'BUTTON_PRESS'. If you decide to use the same call-back function for
several buttons you can use clearwin_info@('BUTTON_NUMBER') to establish which
button was pressed (buttons are numbered along the rows starting at 1).
A call-back function (or any other code) can alter the control variable stat_ctrl
and pass it to window_update@ to change the state of a button. For example, you
could disable/enable a button. Passing any of the control variables belonging
to a given %ib toolbar will update the entire block.
%ib[flat] produces a different style of button that pops up and becomes
coloured when the mouse is moved over it. %ib[coloured] is similar but active
buttons remain coloured by default.
%ib is designed for bitmaps that have a grey background. If the image has a
one-pixel border (using just one colour) then this border colour is used
as the background colour, otherwise the background is assumed to be light grey
(192,192,192). This light grey colour is then translated into the current
system COLOR_BTNFACE colour. This can be selected by the user from the
Control Panel. The default value varies from one Windows operating system
Images are padded as required to produce a rectangular array, however for best
results you should make the images the same size. Alternatively you can
use one of the following two mechanisms to produce a rectangular array.
a) The option [const_width] causes the width of each button to be equal to the
maximum width of all the buttons whilst the option [const_height] causes
the height of each button to be equal to the maximum height of all the buttons.
[const_width] is redundant when used on a single column of buttons.
[const_height] is redundant when used on a single row of buttons.
b) By adding a ^ modifier to %ib you can specify an overall callback function
for the control in addition to the individual callback functions that
are required for each button. The overall callback is placed after the
other arguments. Currently the only call of this function is before the window
is displayed and has the callback reason 'SIZE_ADJUST'. The callback function
can call the following function to adjust the toolbar layout:
The arrays should be large enough to cover the corresponding dimension of the
%ib toolbar. If OPT is zero this routine copies the maximum width of each
column into XW and the maximum depth of each row into YW. If OPT is non-zero
this data is copied in the opposite direction. Thus the callback function
should make an opt=0 call to obtain the data, modify it (e.g. by setting each
array to its maximum value, or implementing some scheme which rounds to a small
number of sizes) and return it using opt=1. All sizes are in pixels.
Buttons can be grouped together by using a %ib for each group. These can be
separated by interposing a separator bar using %se. %se takes one double
precision argument that extends the height of the separator. This argument is
usually set to zero.& %se accepts the option [flat] and this provides a
space rather than a vertical bar.
Using %se (or alternatively %bx) causes button groups to be anchored when
sizing a window that uses a pivot (%pv - Pivot).
The option [mouse_hover] enables mouse sensitivity with the result that the
button callback function is invoked with call-back reason 'MOUSE_ENTER' when
the mouse begins to hover over the button. Also the reason 'MOUSE_LEAVE' is
provided when the mouse ceases to hover over the button. This allows you to
create fly-out toolbars and menus. For a menu, you can create a blank enhanced
popup menu in the form
Then, in your callback function for the button, you can replace and display
the enhanced popup menu with a call to the subroutine DISPLAY_IB_MENU@. This
routine takes the same arguments as REPLACE_ENHANCED_MENU@. The result is that
ClearWin+ displays a dropdown menu below the button as soon as the mouse is
moved over it. In this context, if you are also using [flat] then it should be
combined with [coloured].