|
Purpose |
To insert a image button or image bar. |
|
Syntax |
winio@('%n.mib[options]',bitmap_name,stat_ctrl,cb_func,...) |
|
Modifiers |
Question mark (?) - A help string for each button is placed in order (in square brackets) after the options (use empty brackets for the options list if it is blank). |
|
Description |
This format has been superseded by %mb (Multi-button Toolbar). For new code consider using %mb instead. %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: i=winio@('%ib','my_button/Press me',ctrl,cb) The button text can include newline characters: 'my_button/Press'//CHAR(10)//'me' 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 to another. 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: SUBROUTINE ADJUST_IB_SIZES@(XW,YW,OPT) 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. Using %bx (Grey Bar) 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 i=winio@('%`pm&',"[]",cb) 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]. |
|
See also |
%bt (Button), %tt (Textual Toolbar), %bx (Grey Bar), %mb (Multi-button Toolbar), Image button and image bar. |