http://wiki.amiga.org/api.php?action=feedcontributions&feedformat=atom&user=Trixiewiki.amiga.org - User contributions [en-gb]2026-04-18T07:22:23ZUser contributionsMediaWiki 1.35.9http://wiki.amiga.org/index.php?title=InfoWindow_Class&diff=1120InfoWindow Class2021-05-08T19:17:28Z<p>Trixie: /* Autodoc */</p>
<hr />
<div>== Introduction ==<br />
<br />
This guide describes the ReAction-compatible '''information window class''' for users and developers.<br />
<br />
The '''InfoWindow Class''' (installed as ''infowindow.class'' in the SYS:Classes/ directory) is a BOOPSI-compliant class that is used to display information windows such as About-windows commonly found in many applications.<br />
<br />
From developers' perspective, it provides an easy and adaptable way of creating and presenting information windows within their application. The class is highly configurable to suit many different needs and scenarios.<br />
<br />
== Version ==<br />
<br />
The latest version is 53.8 available in the [[Enhancer Software]] for both AmigaOS3 and AmigaOS4.<br />
<br />
== Features ==<br />
<br />
The features include:<br />
<br />
* Formatted text<br />
<br />
* Aligned images<br />
<br />
* Configurable panel featuring tabs, a configurable text field or a custom BOOPSI gadget<br />
<br />
* Configurable button row supporting any number of buttons, and a timeout feature.<br />
<br />
<br />
== Screenshots ==<br />
<br />
<center><br />
{|<br />
|- style="vertical-align:bottom;text-align:center;"<br />
|[[File:infowindow_class_os3_example1.png|center|250px]]<br />
''OS3 version''<br />
|[[File:infowindow_class_os3_example2.png|center|250px]]<br />
''OS3 version''<br />
|[[File:infowindow_class_os3_example3.png|center|250px]]<br />
''OS3 version''<br />
|}<br />
</center><br />
<br />
<center><br />
{|<br />
|- style="vertical-align:bottom;text-align:center;"<br />
|[[File:infowindow_class_os4_example1.png|center|250px]]<br />
''OS4 version''<br />
|[[File:infowindow_class_os4_example2.png|center|250px]]<br />
''OS4 version''<br />
|[[File:infowindow_class_os4_example3.png|center|250px]]<br />
''OS4 version''<br />
|}<br />
</center><br />
<br />
<br />
== For Developers ==<br />
<br />
=== Autodoc ===<br />
<pre><br />
infowindow.class/--datasheet-- infowindow.class/--datasheet--<br />
<br />
NAME<br />
infowindow.class -- Create an information window<br />
<br />
SUPERCLASS<br />
window.class<br />
<br />
REQUIRES<br />
bitmap.image, button.gadget, clicktab.gadget, label.image, layout.gadget,<br />
scroller.gadget, texteditor.gadget, tickbox.gadget, window.class<br />
<br />
DESCRIPTION<br />
This is a BOOPSI class to create information windows, such as those that<br />
applications display when you select the "About" menu command.<br />
<br />
Supported features:<br />
<br />
- formatted text<br />
- image with configurable placement and backfill<br />
- configurable panel to display tabs, a scrollable text field, or a custom<br />
BOOPSI gadget (e.g. a listbrowser)<br />
- configurable button row supporting any number of buttons<br />
- optional checkbox gadget for confirming information<br />
- keyboard control<br />
- timeout (with an optional counter)<br />
<br />
The class does not replace the Requester Class but it can be seen as<br />
a more sophisticated version of the REQTYPE_INFO requester type.<br />
<br />
METHODS<br />
OM_NEW -- creates the infowindow object, sets attributes and defaults<br />
<br />
OM_SET -- sets object attributes (passed to the superclass first)<br />
<br />
OM_GET -- retrieves object attributes (passed to the superclass first)<br />
<br />
OM_DISPOSE -- disposes of the infowindow object<br />
<br />
IWM_OPEN -- opens the infowindow<br />
<br />
KEYBOARD CONTROL<br />
Escape<br />
Cancels the infowindow (IWM_OPEN returns IWMRES_CANCEL).<br />
<br />
Return / Enter<br />
Selects the default choice and closes the infowindow (IWM_OPEN returns<br />
the number of the button).<br />
<br />
Cursor Left / Right<br />
Switches between tabs (if the tab panel is displayed).<br />
<br />
ATTRIBUTES<br />
The infowindow is designed as a modal (i.e. blocking) requester, so all of<br />
its attributes can only be set or retrieved when the window is NOT open.<br />
<br />
Use SetAttrs() freely in between individual IWM_OPEN calls to re-configure<br />
the infowindow: no need to dispose of and rebuild the object if you want<br />
to change the look, contents or behaviour of the window.<br />
<br />
SetAttrs() will return the number of attributes set.<br />
<br />
The InfoWindow Class is based on the Window Class, so many attributes<br />
supported by the superclass are applicable. Use them wisely: make sure<br />
you don't turn the infowindow into something it's not supposed to be.<br />
<br />
The following superclass attributes are explicitly IGNORED because their<br />
(mis)use could compromise the look or functioning of the infowindow:<br />
<br />
WA_Backdrop<br />
WA_BackFill<br />
WA_Borderless<br />
WA_Hidden<br />
WINDOW_AppPort<br />
WINDOW_AppWindow<br />
WINDOW_Iconifiable<br />
WINDOW_IconifyGadget<br />
WINDOW_IDCMPHook<br />
WINDOW_InputEvent<br />
WINDOW_MenuStrip<br />
WINDOW_NewMenu<br />
WINDOW_PopupGadget<br />
<br />
Further notes on the use of superclass attributes:<br />
<br />
WA_Width and WA_Height are treated as WA_InnerWidth and WA_InnerHeight,<br />
respectively. This behaviour is inherited from the Window Class.<br />
<br />
If WA_CloseGadget is provided and set to TRUE, the IWM_OPEN method will<br />
return the value of IWMRES_CANCEL if the window was closed (= cancelled)<br />
via the close gadget. The Escape key shortcut has an identical function<br />
(and result value) but it is available at all times, regardless of the<br />
WA_CloseGadget setting.<br />
<br />
The class needs to be able to resolve the screen on which the infowindow<br />
will open. The following policy is applied here:<br />
- If INFOWINDOW_Parent is set, the class will attempt to obtain the screen<br />
pointer from the parent window object (the window needs to be open for<br />
this to work);<br />
- the WA_CustomScreen, WA_PubScreen and WA_PubScreenName tags are next in<br />
preference, respectively;<br />
- if there is no tag setting allowing to resolve the screen, it is assumed<br />
that opening on the default public screen is requested.<br />
<br />
You might prefer setting INFOWINDOW_Parent over the Intuition screen tags.<br />
This way the infowindow will always stay with your program window, which<br />
is especially useful if your application supports jumping between screens.<br />
Otherwise you'd have to update the infowindow with a new screen pointer<br />
whenever the application changes screen.<br />
<br />
The InfoWindow Class' own attributes are described below:<br />
<br />
INFOWINDOW_Parent (Object *)<br />
A pointer to a window object that will be the "parent" of the<br />
information window. Often the parent is the application's main window.<br />
The class will automatically set the busy pointer for the parent,<br />
blocking its input while the infowindow is open.<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
INFOWINDOW_BodyText (CONST_STRPTR)<br />
Text for the body of the information window.<br />
<br />
The following codes can be used within the provided string to change<br />
the soft style of the text:<br />
<br />
ESC u -- underline<br />
ESC b -- bold<br />
ESC i -- italic<br />
ESC n -- normal<br />
<br />
Example string: "The following words \33bare in bold\33n."<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_GET)<br />
<br />
INFOWINDOW_GadgetText (CONST_STRPTR)<br />
Text for the information window's button(s), delimited by the vertical<br />
bar character (|) if you want more than one button (e.g. "Yes|No").<br />
<br />
Defaults to "_OK"<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_GET)<br />
<br />
INFOWINDOW_CheckBoxText (CONST_STRPTR)<br />
If you provide this text string, the class will display a checkbox<br />
gadget at the bottom of the information window. The string will become<br />
the gadget's label.<br />
<br />
One obvious purpose of the checkbox is to allow the user to confirm the<br />
information displayed in the window before closing it and proceeding.<br />
The state of the gadget upon closing the infowindow can be retrieved<br />
via the INFOWINDOW_Checked tag; see below.<br />
<br />
Defaults to NULL (no checkbox will be displayed)<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_GET)<br />
<br />
INFOWINDOW_CheckBoxPlace (uint32)<br />
The placement of the optional checkbox gadget within the infowindow.<br />
Possible values are PLACECHECK_LEFT, PLACECHECK_RIGHT and<br />
PLACECHECK_CENTER. The checkbox text label will be displayed to the<br />
right of the gadget unless PLACECHECK_RIGHT is set (in which case the<br />
text will show on the left).<br />
<br />
Defaults to PLACECHECK_LEFT<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
INFOWINDOW_Checked (BOOL)<br />
Setting this attribute will make the checkbox selected or unselected<br />
when the infowindow next opens. GetAttrs() can be used to retrieve the<br />
state of the gadget upon closing the window.<br />
<br />
Please note that the class stores the checkbox state regardless of<br />
whether the infowindow was OK'ed, cancelled, or timed out. You'll want<br />
to also check the IWM_OPEN method return value to distinguish between<br />
these situations.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_GET)<br />
<br />
INFOWINDOW_Justification (uint16)<br />
Body text justification. Applicable values are LJ_LEFT, LJ_CENTER<br />
or LJ_RIGHT.<br />
<br />
Defaults to LJ_LEFT (left-justified)<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
INFOWINDOW_WrapBorder (uint16)<br />
If the body text does not contain any linefeeds (\n) it will be<br />
word-wrapped automatically after the number of characters specified<br />
in this tag.<br />
<br />
Defaults to 0 (no word-wrap)<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
INFOWINDOW_DefButton (uint32)<br />
Specifies the default, highlighted button. If the Return or Enter key is<br />
pressed, the infowindow will close as if this button has been selected.<br />
A value of 0 means there is no default button, and the Return/Enter<br />
keyboard shortcut will not be available.<br />
<br />
Defaults to 1 (the first button from the left)<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
INFOWINDOW_Image (Object *)<br />
A custom BOOPSI image object to display in the information window. Note<br />
that the image will not be disposed of by the class, you need to take<br />
care of this yourself (the logic here is: "you create the image, you<br />
dispose of it").<br />
<br />
This tag takes precedence over INFOWINDOW_ImageFile (see below).<br />
<br />
If your application supports jumping between different screens, it might<br />
be necessary to rebuild your custom image object for the particular new<br />
host screen, to ensure the image is rendered with proper colours. This<br />
will be the case when jumping between an 8-bit screen and a 16/32-bit<br />
screen, or vice versa.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_GET)<br />
<br />
INFOWINDOW_ImageFile (CONST_STRPTR)<br />
A name of a source file from which the class will create a BOOPSI image<br />
to display in the information window. The file can be in any picture<br />
format supported by DataTypes. The image object created this way is<br />
stored internally and the class will dispose of it automatically.<br />
<br />
This tag will be ignored if INFOWINDOW_Image is provided (see above).<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
INFOWINDOW_ImagePlace (uint32)<br />
Flags to determine the placement of the image with regard to the body<br />
text. The image can be placed on the left (default), on the right,<br />
above or below the text. When PLACEIMAGE_ABOVE or PLACEIMAGE_BELOW is<br />
set, the image will be center-aligned horizontally unless you also set<br />
PLACEIMAGE_LEFT or PLACEIMAGE_RIGHT (for example, setting this tag to<br />
the combination of PLACEIMAGE_ABOVE|PLACEIMAGE_LEFT will display the<br />
image in the top-left corner above the body text).<br />
<br />
This tag will be ignored if there is no body text.<br />
<br />
Defaults to PLACEIMAGE_LEFT<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
INFOWINDOW_ImageBackFill (struct Hook *)<br />
Sometimes it may be desirable to place the image on a filled background.<br />
This tag allows providing a backfill hook for this purpose.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
INFOWINDOW_TabPanel (struct InfoWindowTab *)<br />
Use this tag to configure a special panel for displaying additional<br />
information in the window. This will normally be a tabbed panel with<br />
scrollable text fields but other configurations are also possible.<br />
<br />
The tabbed panel is created by passing an array of struct InfoWindowTab<br />
(see <classes/infowindow.h> for definition). The Label member of each<br />
structure in the array must contain the tab label string. The actual<br />
contents of the Data member may vary depending on the Type member value:<br />
<br />
TABDATA_STRING -- Data contains a text string<br />
TABDATA_FILE -- Data contains a name of a text file<br />
TABDATA_LOCK -- Data contains a DOS lock on a text file<br />
TABDATA_GADGET -- Data points to a custom BOOPSI gadget object<br />
<br />
This means that information to be displayed in the panel can be placed<br />
externally. For example, you can have a dedicated tab for displaying<br />
the program licence, the text of which is in a file on disk (only plain<br />
text files are supported at the moment):<br />
<br />
struct InfoWindowTab tabs[] =<br />
{<br />
{ "Credits", (APTR) "This program was made by me!", TABDATA_STRING },<br />
{ "Licence", (APTR) "PROGDIR:Docs/Licence.txt", TABDATA_FILE },<br />
{ NULL, NULL, TABDATA_END }<br />
};<br />
<br />
Note that the array must be properly terminated as shown.<br />
<br />
If instead of an array you pass a single struct InfoWindowTab with<br />
a NULL Label member, a scrollable text field will be created in the<br />
place of the tabbed panel:<br />
<br />
struct InfoWindowTab textField =<br />
{<br />
NULL,<br />
(APTR) "PROGDIR:Docs/Licence.txt",<br />
TABDATA_FILE<br />
};<br />
<br />
The configuration can be further customized by using the TABDATA_GADGET<br />
value for Type. In such a case the Data member shall point to a BOOPSI<br />
gadget (for example, a listbrowser):<br />
<br />
struct InfoWindowTab customPanel =<br />
{<br />
NULL,<br />
(APTR) myListBrowser,<br />
TABDATA_GADGET<br />
};<br />
<br />
The configuration above will display your own listbrowser gadget<br />
instead of the panel, and this<br />
<br />
struct InfoWindowTab tabs[] =<br />
{<br />
{ "Credits", (APTR) myListBrowser, TABDATA_GADGET },<br />
{ "Licence", (APTR) "PROGDIR:Docs/Licence.txt", TABDATA_FILE },<br />
{ NULL, NULL, TABDATA_END }<br />
};<br />
<br />
will show your listbrowser under the "Credits" tab instead of the<br />
standard text field.<br />
<br />
The tab panel's text fields are currently rendered using a read-only<br />
TextEditor Gadget. This may change in the future so don't assume<br />
anything about the formatting of the text.<br />
<br />
Defaults to NULL (no panel)<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
INFOWINDOW_TimeOut (uint32)<br />
The displayed information window will time out and close after the<br />
number of seconds specified via this tag. The IWM_OPEN method will<br />
return with a result of IWMRES_TIMEOUT.<br />
<br />
To visually indicate how much time is left before the window closes<br />
you can set up a counter to display in the window title bar or in<br />
a button. The respective string must include a special placeholder,<br />
%t, within its text. For example, to display a counter in the window<br />
title you would set WA_Title to something like 'Closes in %t seconds'.<br />
Similarly, the label '%t seconds left' passed in INFOWINDOW_GadgetText<br />
will display the counter in the button at the bottom of the infowindow.<br />
The number of counters is not limited and they can be freely combined,<br />
displayed in both the window title and in any (or all) of the buttons.<br />
Use with moderation, though.<br />
<br />
Defaults to 0 (no timeout)<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
INFOWINDOW_AllowSignals (BOOL)<br />
A program may want to run the infowindow on a separate process in order<br />
to make it a non-modal (non-blocking) requester. In such a case it would<br />
be desirable that the program can exercise some basic control over the <br />
independently running infowindow. If set to TRUE, this tag will allow<br />
sending a break signal to the infowindow process. The following signals<br />
are supported:<br />
<br />
SIGBREAKF_CTRL_C -- cancel the information window<br />
SIGBREAKF_CTRL_F -- bring the infowindow to front and activate it<br />
<br />
The function needed to send the signal is IExec->Signal().<br />
<br />
The IWM_OPEN method will return with a result of IWMRES_BREAK if the<br />
infowindow is cancelled via SIGBREAKF_CTRL_C.<br />
<br />
Defaults to FALSE (no signals allowed)<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
NOTES<br />
<br />
<br />
BUGS<br />
<br />
<br />
SEE ALSO<br />
<br />
<br />
infowindow.class/IWM_OPEN infowindow.class/IWM_OPEN<br />
<br />
NAME<br />
IWM_OPEN -- Open the information window<br />
<br />
SYNOPSIS<br />
int32 result = IDoMethodA(APTR obj, Msg msg);<br />
int32 result = IDoMethod(APTR obj, IWM_OPEN, NULL);<br />
<br />
FUNCTION<br />
Opens the information window.<br />
<br />
INPUTS<br />
obj - an infowindow object pointer<br />
msg - a Msg with MethodID = IWM_OPEN (see <intuition/classusr.h>)<br />
<br />
RESULT<br />
The number of the button (1, 2, 3...) the user has selected, or<br />
IWMRES_ERROR if the information window failed to open for some reason,<br />
IWMRES_CANCEL if the window was closed via the close gadget or Esc key,<br />
IWMRES_TIMEOUT if the window has timed out,<br />
IWMRES_BREAK if the window was closed via the SIGBREAKF_CTRL_C signal.<br />
<br />
EXAMPLE<br />
<br />
NOTES<br />
<br />
BUGS<br />
<br />
SEE ALSO<br />
<br />
</pre></div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1033ToolBar Gadget Class2021-02-14T14:37:59Z<p>Trixie: Toolbar attributes: updated TOOLBAR_TextPlace.</p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Supported methods ==<br />
<br />
{| class="wikitable"<br />
!Method ID<br />
!Description<br />
|-<br />
|OM_NEW<br />
|creates the toolbar object, sets attributes and defaults<br />
|-<br />
|OM_DISPOSE<br />
|disposes of the toolbar object<br />
|-<br />
|OM_REMMEMBER<br />
|used by the class internally; consider this method private<br />
|-<br />
|OM_SET<br />
|sets toolbar, member and image attributes (see the [[#OM_SET|OM_SET]] section below for more information)<br />
|-<br />
|OM_GET<br />
|retrieves toolbar attributes<br />
|-<br />
|TBM_GETMEMBER<br />
|retrieves a given member attribute (see the [[#TBM_GETMEMBER|TBM_GETMEMBER]] section below for more information)<br />
|-<br />
|TBM_REFRESHMEMBER<br />
|refreshes the imagery of a given member (see the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] section below for more information)<br />
|}<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
; GA_ID (uint16)<br />
: Unique ID number for the gadget.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_ReadOnly (BOOL)<br />
: If set to TRUE, none of the toolbar buttons will be selectable.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_BackFill (struct Hook *)<br />
: A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
: Defaults to NULL (the default backfill hook)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; GA_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the toolbar members' text.<br />
: Generally, you should use one font for the toolbar, set through this tag. However, you can override the global font and set a different one for individual members if needed; see TBMEMBER_TextAttr below.<br />
: Defaults to NULL (will use the system's default public screen font)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Orientation (uint32)<br />
: The toolbar orientation: horizontal or vertical.<br />
: Defaults to TB_ORIENT_HORIZ<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_Spacing (uint32)<br />
: The spacing between the individual toolbar members, in pixels.<br />
: Defaults to 2<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HorizPadding<br />
; TOOLBAR_VertPadding (uint32)<br />
: The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_InnerPadding (uint32)<br />
: The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.<br />
: Defaults to 4<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HandleOverflow (BOOL)<br />
: Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_MinVisible (uint32)<br />
: If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
: Defaults to 1<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SpacerSize (uint32)<br />
: The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.<br />
: Defaults to 5<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ButtonStyle (uint32)<br />
: The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
: Defaults to TB_BUTSTYLE_CLASSIC<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BevelStyle (uint32)<br />
: The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:<br />
<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
: When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.<br />
: Defaults to BVS_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SeparatorStyle (uint32)<br />
: Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.<br />
: Defaults to TB_SEPSTYLE_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SelectionStyle (uint32)<br />
: Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.<br />
: This tag is ignored in the classic mode with framed buttons.<br />
: Defaults to TB_SELSTYLE_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BackFill (struct Hook *)<br />
: A custom backfill hook to provide a background filled with a specific colour or pattern.<br />
: This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.<br />
: Defaults to NULL (the default backfill hook)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Display (uint32)<br />
: Specifies what you want to display inside the toolbar button or toggle members. The possible values are:<br />
<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
: Defaults to TB_DISPLAY_IMAGES<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_TextPen (uint16) (V53.4)<br />
: A pen to be used for the toolbar members' text.<br />
: Generally, you should use one text pen for the toolbar, set through this tag. However, you can override the global pen and set a different one for individual members if needed; see TBMEMBER_TextPen below.<br />
: Prefer to use pens from the dri_Pens[] array in your screen's DrawInfo structure; see the <intuition/screens.h> system include file.<br />
: Defaults to dri_Pens[TEXTPEN]<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_TextStyle (uint8) (V53.4)<br />
: A font style to be used for the toolbar members' text.<br />
: Generally, you should use one text style for the toolbar, set through this tag. However, you can override the global style and set a different one for individual members if needed; see TBMEMBER_TextStyle below.<br />
: The styles are defined in the <graphics/text.h> system include file.<br />
: Defaults to FS_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_TextPlace (uint32)<br />
: Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH. Plus, it only affects button and toggle members.<br />
: The possible values are:<br />
<br />
TB_PLACETEXT_BELOW<br />
TB_PLACETEXT_ABOVE (V53.6)<br />
TB_PLACETEXT_LEFT (V53.6)<br />
TB_PLACETEXT_RIGHT (V53.6)<br />
<br />
: Defaults to TB_PLACETEXT_BELOW<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_LabelArray (STRPTR *)<br />
: Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.<br />
: TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
: Using this tag, the limitation is that you cannot create toggle or textbox members (only buttons, separators and spacers).<br />
: A special string, " ", will create a spacer.<br />
: A special string, "_", will create a separator.<br />
: Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.<br />
: The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TOOLBAR_EvenSize (BOOL)<br />
: If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.<br />
: If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ImageSet (uint32)<br />
: If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in the toolbar. The value passed to this tag is the image set ID.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:<br />
<br />
; TOOLBAR_AddImageSet (uint32)<br />
: Creates a new image set. The value passed to this tag is a numeric ID identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to display the particular image set in the toolbar.<br />
: An image set must have a valid ID. The value of TB_NO_ID (~0UL) is not applicable here.<br />
: This tag should be followed by a sequence of TOOLBAR_AddImage tags (see below), each creating one image in the given set.<br />
: If the gadget only uses one set of images, passing TOOLBAR_AddImageSet is not necessary. Each TOOLBAR_AddImage will add the respective image to the default image set identified by an ID of 0.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddImage (uint32)<br />
: Creates a new image in a given image set. The value passed to this tag is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID (see below) to associate the image with a particular toolbar member.<br />
: An image must have a valid ID. The value of TB_NO_ID (~0UL) is not applicable here.<br />
: This tag should be followed by a sequence of TBIMAGE_ tags (see the [[#Image attributes|Image attributes]] section below), each configuring one aspect of the image, including its optional selected variant (referred to as the "select image").<br />
: Images are added to the default image set unless a preceding TOOLBAR_AddImageSet specifies a different set.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddMember (uint32)<br />
: Creates a new toolbar member. The value passed to this tag is a numeric ID identifying the member.<br />
: Spacers and separators normally don't need an ID, so you can use TB_NO_ID as a value for TOOLBAR_AddMember when creating these members. However, if you want to manipulate spacers/separators in your GUI, an ID will be necessary so that you can pass it to TOOLBAR_SetMember to identify the respective spacer or separator member.<br />
: You can add members when the toolbar object is being created, i.e. as part of the NewObject() call, or at any time later via SetAttrs().<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetMember<br />
: Use this tag in a SetAttrs() call to identify the member you want to modify.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetGroup<br />
: Use this tag in a SetAttrs() call to identify the group of members you want to modify collectively.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
=== Member attributes ===<br />
<br />
; TBMEMBER_Type (uint32)<br />
: The type of the toolbar member. The possible values are the following:<br />
<br />
TB_MTYPE_BUTTON -- a normal toolbar button<br />
TB_MTYPE_TOGGLE -- a toggle (on/off) button<br />
TB_MTYPE_SPACER -- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
TB_MTYPE_TEXTBOX -- a read-only box to display text (V53.4)<br />
<br />
: The type is set upon member creation, and cannot be changed.<br />
: Defaults to TB_MTYPE_BUTTON<br />
: Applicability is (OM_NEW)<br />
<br />
; TBMEMBER_ImageID (uint32)<br />
: The identifier of the image to be used for the button or toggle member (see TOOLBAR_AddImage above). This tag is not relevant to textboxes, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_ImageID value of such a member.<br />
: When [[#OM_SET|OM_SET]]-ing this attribute, the method will always return TB_NEED_RETHINK, to be on the safe side. However, invoking WM_RETHINK is really only needed if the size of the new image is different from the original image. If the size is the same, a simple gadget refresh will suffice. You can trigger the refresh:<br />
:* by setting this attribute via RefreshSetGadgetAttrs(), or<br />
:* by setting this attribute via SetAttrs() and then invoking the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method on the respective button/toggle member.<br />
: (The difference is that RefreshSetGadgetAttrs() will refresh the entire toolbar, while TBM_REFRESHMEMBER will only refresh the given member.)<br />
: Defaults to TB_NO_ID (no image associated with this member)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Text (CONST_STRPTR)<br />
: The text to associate with a button, toggle or textbox member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
: The text will be used as fallback in case no image is found or provided for a button or a toggle member.<br />
: Multi-line text is supported: use "\n" as line separator in the text string.<br />
: The text string can contain an underscore character (_), indicating the keyboard shortcut for the member. (This doesn't apply to textbox members, as they are read-only and don't respond to the keyboard.)<br />
: If your toolbar features a textbox member the contents of which is going to change dynamically, it is highly recommended that you also set TBMEMBER_DomainString (see below) at member creation time. This will guarantee a size to accommodate any text, so you won't have to perform WM_RETHINK to recalculate the textbox size each time TBMEMBER_Text changes. Updating the text can be done in one of the following ways:<br />
<br />
(1) IIntuition->SetGadgetAttrs(toolbar, window, NULL,<br />
TOOLBAR_SetMember, textboxID,<br />
TBMEMBER_Text, "New text",<br />
TAG_END);<br />
<br />
(2) IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, textboxID,<br />
TBMEMBER_Text, "New text",<br />
TAG_END);<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, textboxID, window);<br />
<br />
: The difference is that (1) performs the textbox update immediately, whereas with (2) you can set the value "quietly" and only display it when you're ready, by calling the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_DomainString (CONST_STRPTR) (V53.4)<br />
: A text string based on which the minimum size of the member will be calculated. This is useful especially with TB_MTYPE_TEXTBOX members when you want to enforce a minimum size required to fit text of variable length. The domain string ought to be at least as long as the longest text to appear in the textbox.<br />
: The domain string is never rendered in the gadget.<br />
: This tag is not relevant to spacers and separators.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_TextAttr (struct TextAttr *) (V53.4)<br />
: Pointer to a TextAttr structure describing the font to be used for the member text. This tag overrides GA_TextAttr (see above).<br />
: Generally, you should use one "global" font for the toolbar, configured via GA_TextAttr. But there are situations where it makes sense to set a particular font at the member level, for example when using textbox members.<br />
: Defaults to the GA_TextAttr value<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_TextPen (uint16) (V53.4)<br />
: A pen to be used for the member text. Overrides TOOLBAR_TextPen (see above).<br />
: Generally, you should use one "global" pen for the toolbar, configured via TOOLBAR_TextPen. But there are situations where it makes sense to set a particular pen at the member level, for example when using textbox members.<br />
: Prefer to use pens from the dri_Pens[] array in your screen's DrawInfo structure; see the <intuition/screens.h> system include file.<br />
: Defaults to the TOOLBAR_TextPen value<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_TextStyle (uint8) (V53.4)<br />
: A font style to be used for the member text. Overrides TOOLBAR_TextStyle (see above).<br />
: Generally, you should use one "global" style for the toolbar, configured via TOOLBAR_TextStyle. But there are situations where it makes sense to set a particular style at the member level, for example when using textbox members.<br />
: The styles are defined in the <graphics/text.h> system include file.<br />
: Defaults to the TOOLBAR_TextStyle value<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_Disabled (BOOL)<br />
: The current state (disabled or not disabled) of a member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Disabled value of such a member.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Hidden (BOOL)<br />
: Specifies whether the particular member is displayed in the toolbar or hidden. You can use this tag to create "dynamic" toolbar layouts that adapt the actual member set to various application settings.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Selected (BOOL)<br />
: The current selection state of a toggle member. This tag is not relevant to normal buttons (TB_MTYPE_BUTTON), textboxes, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Selected value of such a member.<br />
: You can set a target BOOPSI object for any toggle member, using the standard icclass ICA_TARGET tag. The target will receive an automatic notification of the toggle selection. This way toolbar toggles can easily communicate with other boolean gadgets such as checkboxes.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_NOTIFY, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Group (uint32)<br />
: Member group ID. Several members can be manipulated at once if they are assigned to the same group. Use TOOLBAR_SetGroup with the respective group ID to identify the group to be manipulated.<br />
: Defaults to TB_NO_ID (not assigned to any group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_MXGroup (uint32)<br />
: MX group ID. Toggle members can be put in groups of mutually-exclusive buttons. When such a toggle is selected, all other toggles in the same MX group will become deselected.<br />
: This tag is not relevant to normal buttons, textboxes, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_MXGroup value of such a member.<br />
: Defaults to TB_NO_ID (not assigned to any MX group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_HintInfo (CONST_STRPTR)<br />
: The help text to be displayed when the user hovers the mouse pointer over the respective member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_HintInfo value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_UserData (APTR)<br />
: Arbitrary user data associated with this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
=== Image attributes ===<br />
<br />
Note: Images are configured at OM_NEW, i.e. when creating each respective image. Image attributes cannot be changed later.<br />
<br />
; TBIMAGE_Image (struct Image *)<br />
: Custom image to be used for a button or a toggle member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_ImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImage (struct Image *)<br />
: Custom image to display when the member becomes selected.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the select image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
;TBIMAGE_Width (uint32)<br />
;TBIMAGE_Height (uint32)<br />
: Image dimensions, in pixels. These tags can only be used in connection with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the respective source file will be scaled to the specified width and height. Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot be resized using these tags.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW)<br />
<br />
== Notes ==<br />
<br />
Some of the attributes described above change the sizing requirements of the gadget. If set on the fly (i.e. when the toolbar is already displayed in the window), the gadget domain will need recalculating and a re-layout must take place. Refer to the [[#OM_SET|OM_SET]] method documentation below to see how to handle such situations.<br />
<br />
== Bugs ==<br />
<br />
== See also ==<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
; NAME<br />
: OM_SET -- set toolbar attributes<br />
<br />
; SYNOPSIS<br />
: uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
: uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win, struct Requester *req, Tag tag1, ...);<br />
<br />
; FUNCTION<br />
: This method sets the attributes of the toolbar and/or of its members. SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions to invoke this method.<br />
: To change a member attribute you first need to pass TOOLBAR_SetMember to identify the respective member, and then the member attribute tag(s). See the EXAMPLE section below.<br />
: To change an attribute collectively for a group of members you first need to pass TOOLBAR_SetGroup to identify the respective group, and then the member attribute tag(s). See the EXAMPLE section below.<br />
<br />
; INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
; RESULT<br />
: This method will return TB_NEED_RETHINK if the gadget ''believes'' that one or more of the attributes will change the sizing requirements of the toolbar. Typically, invoking the WM_RETHINK method on the gadget's window object is needed, in order to recalculate the domain and re-layout the contents.<br />
: If you know you will be changing an attribute that requires a WM_RETHINK, prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
: The method returns 0L if no rethink is needed.<br />
<br />
; EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, groupID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
; NAME<br />
: TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, uint32 attrID, uint32 *storage);<br />
<br />
; FUNCTION<br />
: Use this method to obtain the value of a given member attribute.<br />
: Because of the way OM_GET is implemented in Intuition, getting member attributes is done differently compared to setting them. The difference boils down to the following:<br />
:* We cannot use a convenience function such as GetAttr() or GetAttrs(), so a dedicated method is provided. Refer to the EXAMPLE section below to see how to invoke the method.<br />
:* Only one attribute can be queried at a time. (As multiple attributes will rarely be requested in real use, this limitation should not pose a significant problem.)<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
attrID -- the attribute tag identifier<br />
storage -- a pointer to the variable for storing the attribute value<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the requested attribute value has been obtained successfully. The attribute value itself is returned in the provided storage variable.<br />
<br />
; EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID, TBMEMBER_Selected, &storage);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_REFRESHMEMBER ===<br />
<br />
; NAME<br />
: TBM_REFRESHMEMBER -- refresh the imagery of a given member (V53.3)<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbRefreshMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, struct Window *window);<br />
<br />
; FUNCTION<br />
: Use this method to refresh the imagery of a given button or toggle member.<br />
: The method has no effect on spacers and separators.<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbRefreshMember structure<br />
<br />
For IDoMethod():<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_REFRESHMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
window -- a pointer to the window the toolbar resides in<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the refresh has taken place.<br />
<br />
; EXAMPLE<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1032ToolBar Gadget Class2021-02-05T20:01:34Z<p>Trixie: /* Notes */</p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Supported methods ==<br />
<br />
{| class="wikitable"<br />
!Method ID<br />
!Description<br />
|-<br />
|OM_NEW<br />
|creates the toolbar object, sets attributes and defaults<br />
|-<br />
|OM_DISPOSE<br />
|disposes of the toolbar object<br />
|-<br />
|OM_REMMEMBER<br />
|used by the class internally; consider this method private<br />
|-<br />
|OM_SET<br />
|sets toolbar, member and image attributes (see the [[#OM_SET|OM_SET]] section below for more information)<br />
|-<br />
|OM_GET<br />
|retrieves toolbar attributes<br />
|-<br />
|TBM_GETMEMBER<br />
|retrieves a given member attribute (see the [[#TBM_GETMEMBER|TBM_GETMEMBER]] section below for more information)<br />
|-<br />
|TBM_REFRESHMEMBER<br />
|refreshes the imagery of a given member (see the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] section below for more information)<br />
|}<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
; GA_ID (uint16)<br />
: Unique ID number for the gadget.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_ReadOnly (BOOL)<br />
: If set to TRUE, none of the toolbar buttons will be selectable.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_BackFill (struct Hook *)<br />
: A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
: Defaults to NULL (the default backfill hook)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; GA_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the toolbar members' text.<br />
: Generally, you should use one font for the toolbar, set through this tag. However, you can override the global font and set a different one for individual members if needed; see TBMEMBER_TextAttr below.<br />
: Defaults to NULL (will use the system's default public screen font)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Orientation (uint32)<br />
: The toolbar orientation: horizontal or vertical.<br />
: Defaults to TB_ORIENT_HORIZ<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_Spacing (uint32)<br />
: The spacing between the individual toolbar members, in pixels.<br />
: Defaults to 2<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HorizPadding<br />
; TOOLBAR_VertPadding (uint32)<br />
: The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_InnerPadding (uint32)<br />
: The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.<br />
: Defaults to 4<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HandleOverflow (BOOL)<br />
: Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_MinVisible (uint32)<br />
: If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
: Defaults to 1<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SpacerSize (uint32)<br />
: The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.<br />
: Defaults to 5<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ButtonStyle (uint32)<br />
: The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
: Defaults to TB_BUTSTYLE_CLASSIC<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BevelStyle (uint32)<br />
: The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:<br />
<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
: When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.<br />
: Defaults to BVS_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SeparatorStyle (uint32)<br />
: Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.<br />
: Defaults to TB_SEPSTYLE_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SelectionStyle (uint32)<br />
: Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.<br />
: This tag is ignored in the classic mode with framed buttons.<br />
: Defaults to TB_SELSTYLE_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BackFill (struct Hook *)<br />
: A custom backfill hook to provide a background filled with a specific colour or pattern.<br />
: This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.<br />
: Defaults to NULL (the default backfill hook)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Display (uint32)<br />
: Specifies what you want to display inside the toolbar button or toggle members. The possible values are:<br />
<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
: Defaults to TB_DISPLAY_IMAGES<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_TextPen (uint16) (V53.4)<br />
: A pen to be used for the toolbar members' text.<br />
: Generally, you should use one text pen for the toolbar, set through this tag. However, you can override the global pen and set a different one for individual members if needed; see TBMEMBER_TextPen below.<br />
: Prefer to use pens from the dri_Pens[] array in your screen's DrawInfo structure; see the <intuition/screens.h> system include file.<br />
: Defaults to dri_Pens[TEXTPEN]<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_TextStyle (uint8) (V53.4)<br />
: A font style to be used for the toolbar members' text.<br />
: Generally, you should use one text style for the toolbar, set through this tag. However, you can override the global style and set a different one for individual members if needed; see TBMEMBER_TextStyle below.<br />
: The styles are defined in the <graphics/text.h> system include file.<br />
: Defaults to FS_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_TextPlace (uint32)<br />
: Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH. Plus, it only affects button and toggle members.<br />
: Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_LabelArray (STRPTR *)<br />
: Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.<br />
: TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
: Using this tag, the limitation is that you cannot create toggle or textbox members (only buttons, separators and spacers).<br />
: A special string, " ", will create a spacer.<br />
: A special string, "_", will create a separator.<br />
: Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.<br />
: The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TOOLBAR_EvenSize (BOOL)<br />
: If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.<br />
: If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ImageSet (uint32)<br />
: If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in the toolbar. The value passed to this tag is the image set ID.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:<br />
<br />
; TOOLBAR_AddImageSet (uint32)<br />
: Creates a new image set. The value passed to this tag is a numeric ID identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to display the particular image set in the toolbar.<br />
: An image set must have a valid ID. The value of TB_NO_ID (~0UL) is not applicable here.<br />
: This tag should be followed by a sequence of TOOLBAR_AddImage tags (see below), each creating one image in the given set.<br />
: If the gadget only uses one set of images, passing TOOLBAR_AddImageSet is not necessary. Each TOOLBAR_AddImage will add the respective image to the default image set identified by an ID of 0.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddImage (uint32)<br />
: Creates a new image in a given image set. The value passed to this tag is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID (see below) to associate the image with a particular toolbar member.<br />
: An image must have a valid ID. The value of TB_NO_ID (~0UL) is not applicable here.<br />
: This tag should be followed by a sequence of TBIMAGE_ tags (see the [[#Image attributes|Image attributes]] section below), each configuring one aspect of the image, including its optional selected variant (referred to as the "select image").<br />
: Images are added to the default image set unless a preceding TOOLBAR_AddImageSet specifies a different set.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddMember (uint32)<br />
: Creates a new toolbar member. The value passed to this tag is a numeric ID identifying the member.<br />
: Spacers and separators normally don't need an ID, so you can use TB_NO_ID as a value for TOOLBAR_AddMember when creating these members. However, if you want to manipulate spacers/separators in your GUI, an ID will be necessary so that you can pass it to TOOLBAR_SetMember to identify the respective spacer or separator member.<br />
: You can add members when the toolbar object is being created, i.e. as part of the NewObject() call, or at any time later via SetAttrs().<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetMember<br />
: Use this tag in a SetAttrs() call to identify the member you want to modify.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetGroup<br />
: Use this tag in a SetAttrs() call to identify the group of members you want to modify collectively.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
=== Member attributes ===<br />
<br />
; TBMEMBER_Type (uint32)<br />
: The type of the toolbar member. The possible values are the following:<br />
<br />
TB_MTYPE_BUTTON -- a normal toolbar button<br />
TB_MTYPE_TOGGLE -- a toggle (on/off) button<br />
TB_MTYPE_SPACER -- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
TB_MTYPE_TEXTBOX -- a read-only box to display text (V53.4)<br />
<br />
: The type is set upon member creation, and cannot be changed.<br />
: Defaults to TB_MTYPE_BUTTON<br />
: Applicability is (OM_NEW)<br />
<br />
; TBMEMBER_ImageID (uint32)<br />
: The identifier of the image to be used for the button or toggle member (see TOOLBAR_AddImage above). This tag is not relevant to textboxes, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_ImageID value of such a member.<br />
: When [[#OM_SET|OM_SET]]-ing this attribute, the method will always return TB_NEED_RETHINK, to be on the safe side. However, invoking WM_RETHINK is really only needed if the size of the new image is different from the original image. If the size is the same, a simple gadget refresh will suffice. You can trigger the refresh:<br />
:* by setting this attribute via RefreshSetGadgetAttrs(), or<br />
:* by setting this attribute via SetAttrs() and then invoking the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method on the respective button/toggle member.<br />
: (The difference is that RefreshSetGadgetAttrs() will refresh the entire toolbar, while TBM_REFRESHMEMBER will only refresh the given member.)<br />
: Defaults to TB_NO_ID (no image associated with this member)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Text (CONST_STRPTR)<br />
: The text to associate with a button, toggle or textbox member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
: The text will be used as fallback in case no image is found or provided for a button or a toggle member.<br />
: Multi-line text is supported: use "\n" as line separator in the text string.<br />
: The text string can contain an underscore character (_), indicating the keyboard shortcut for the member. (This doesn't apply to textbox members, as they are read-only and don't respond to the keyboard.)<br />
: If your toolbar features a textbox member the contents of which is going to change dynamically, it is highly recommended that you also set TBMEMBER_DomainString (see below) at member creation time. This will guarantee a size to accommodate any text, so you won't have to perform WM_RETHINK to recalculate the textbox size each time TBMEMBER_Text changes. Updating the text can be done in one of the following ways:<br />
<br />
(1) IIntuition->SetGadgetAttrs(toolbar, window, NULL,<br />
TOOLBAR_SetMember, textboxID,<br />
TBMEMBER_Text, "New text",<br />
TAG_END);<br />
<br />
(2) IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, textboxID,<br />
TBMEMBER_Text, "New text",<br />
TAG_END);<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, textboxID, window);<br />
<br />
: The difference is that (1) performs the textbox update immediately, whereas with (2) you can set the value "quietly" and only display it when you're ready, by calling the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_DomainString (CONST_STRPTR) (V53.4)<br />
: A text string based on which the minimum size of the member will be calculated. This is useful especially with TB_MTYPE_TEXTBOX members when you want to enforce a minimum size required to fit text of variable length. The domain string ought to be at least as long as the longest text to appear in the textbox.<br />
: The domain string is never rendered in the gadget.<br />
: This tag is not relevant to spacers and separators.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_TextAttr (struct TextAttr *) (V53.4)<br />
: Pointer to a TextAttr structure describing the font to be used for the member text. This tag overrides GA_TextAttr (see above).<br />
: Generally, you should use one "global" font for the toolbar, configured via GA_TextAttr. But there are situations where it makes sense to set a particular font at the member level, for example when using textbox members.<br />
: Defaults to the GA_TextAttr value<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_TextPen (uint16) (V53.4)<br />
: A pen to be used for the member text. Overrides TOOLBAR_TextPen (see above).<br />
: Generally, you should use one "global" pen for the toolbar, configured via TOOLBAR_TextPen. But there are situations where it makes sense to set a particular pen at the member level, for example when using textbox members.<br />
: Prefer to use pens from the dri_Pens[] array in your screen's DrawInfo structure; see the <intuition/screens.h> system include file.<br />
: Defaults to the TOOLBAR_TextPen value<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_TextStyle (uint8) (V53.4)<br />
: A font style to be used for the member text. Overrides TOOLBAR_TextStyle (see above).<br />
: Generally, you should use one "global" style for the toolbar, configured via TOOLBAR_TextStyle. But there are situations where it makes sense to set a particular style at the member level, for example when using textbox members.<br />
: The styles are defined in the <graphics/text.h> system include file.<br />
: Defaults to the TOOLBAR_TextStyle value<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_Disabled (BOOL)<br />
: The current state (disabled or not disabled) of a member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Disabled value of such a member.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Hidden (BOOL)<br />
: Specifies whether the particular member is displayed in the toolbar or hidden. You can use this tag to create "dynamic" toolbar layouts that adapt the actual member set to various application settings.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Selected (BOOL)<br />
: The current selection state of a toggle member. This tag is not relevant to normal buttons (TB_MTYPE_BUTTON), textboxes, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Selected value of such a member.<br />
: You can set a target BOOPSI object for any toggle member, using the standard icclass ICA_TARGET tag. The target will receive an automatic notification of the toggle selection. This way toolbar toggles can easily communicate with other boolean gadgets such as checkboxes.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_NOTIFY, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Group (uint32)<br />
: Member group ID. Several members can be manipulated at once if they are assigned to the same group. Use TOOLBAR_SetGroup with the respective group ID to identify the group to be manipulated.<br />
: Defaults to TB_NO_ID (not assigned to any group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_MXGroup (uint32)<br />
: MX group ID. Toggle members can be put in groups of mutually-exclusive buttons. When such a toggle is selected, all other toggles in the same MX group will become deselected.<br />
: This tag is not relevant to normal buttons, textboxes, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_MXGroup value of such a member.<br />
: Defaults to TB_NO_ID (not assigned to any MX group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_HintInfo (CONST_STRPTR)<br />
: The help text to be displayed when the user hovers the mouse pointer over the respective member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_HintInfo value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_UserData (APTR)<br />
: Arbitrary user data associated with this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
=== Image attributes ===<br />
<br />
Note: Images are configured at OM_NEW, i.e. when creating each respective image. Image attributes cannot be changed later.<br />
<br />
; TBIMAGE_Image (struct Image *)<br />
: Custom image to be used for a button or a toggle member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_ImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImage (struct Image *)<br />
: Custom image to display when the member becomes selected.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the select image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
;TBIMAGE_Width (uint32)<br />
;TBIMAGE_Height (uint32)<br />
: Image dimensions, in pixels. These tags can only be used in connection with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the respective source file will be scaled to the specified width and height. Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot be resized using these tags.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW)<br />
<br />
== Notes ==<br />
<br />
Some of the attributes described above change the sizing requirements of the gadget. If set on the fly (i.e. when the toolbar is already displayed in the window), the gadget domain will need recalculating and a re-layout must take place. Refer to the [[#OM_SET|OM_SET]] method documentation below to see how to handle such situations.<br />
<br />
== Bugs ==<br />
<br />
== See also ==<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
; NAME<br />
: OM_SET -- set toolbar attributes<br />
<br />
; SYNOPSIS<br />
: uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
: uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win, struct Requester *req, Tag tag1, ...);<br />
<br />
; FUNCTION<br />
: This method sets the attributes of the toolbar and/or of its members. SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions to invoke this method.<br />
: To change a member attribute you first need to pass TOOLBAR_SetMember to identify the respective member, and then the member attribute tag(s). See the EXAMPLE section below.<br />
: To change an attribute collectively for a group of members you first need to pass TOOLBAR_SetGroup to identify the respective group, and then the member attribute tag(s). See the EXAMPLE section below.<br />
<br />
; INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
; RESULT<br />
: This method will return TB_NEED_RETHINK if the gadget ''believes'' that one or more of the attributes will change the sizing requirements of the toolbar. Typically, invoking the WM_RETHINK method on the gadget's window object is needed, in order to recalculate the domain and re-layout the contents.<br />
: If you know you will be changing an attribute that requires a WM_RETHINK, prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
: The method returns 0L if no rethink is needed.<br />
<br />
; EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, groupID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
; NAME<br />
: TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, uint32 attrID, uint32 *storage);<br />
<br />
; FUNCTION<br />
: Use this method to obtain the value of a given member attribute.<br />
: Because of the way OM_GET is implemented in Intuition, getting member attributes is done differently compared to setting them. The difference boils down to the following:<br />
:* We cannot use a convenience function such as GetAttr() or GetAttrs(), so a dedicated method is provided. Refer to the EXAMPLE section below to see how to invoke the method.<br />
:* Only one attribute can be queried at a time. (As multiple attributes will rarely be requested in real use, this limitation should not pose a significant problem.)<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
attrID -- the attribute tag identifier<br />
storage -- a pointer to the variable for storing the attribute value<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the requested attribute value has been obtained successfully. The attribute value itself is returned in the provided storage variable.<br />
<br />
; EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID, TBMEMBER_Selected, &storage);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_REFRESHMEMBER ===<br />
<br />
; NAME<br />
: TBM_REFRESHMEMBER -- refresh the imagery of a given member (V53.3)<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbRefreshMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, struct Window *window);<br />
<br />
; FUNCTION<br />
: Use this method to refresh the imagery of a given button or toggle member.<br />
: The method has no effect on spacers and separators.<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbRefreshMember structure<br />
<br />
For IDoMethod():<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_REFRESHMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
window -- a pointer to the window the toolbar resides in<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the refresh has taken place.<br />
<br />
; EXAMPLE<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1031ToolBar Gadget Class2021-02-05T20:00:30Z<p>Trixie: /* Image attributes */</p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Supported methods ==<br />
<br />
{| class="wikitable"<br />
!Method ID<br />
!Description<br />
|-<br />
|OM_NEW<br />
|creates the toolbar object, sets attributes and defaults<br />
|-<br />
|OM_DISPOSE<br />
|disposes of the toolbar object<br />
|-<br />
|OM_REMMEMBER<br />
|used by the class internally; consider this method private<br />
|-<br />
|OM_SET<br />
|sets toolbar, member and image attributes (see the [[#OM_SET|OM_SET]] section below for more information)<br />
|-<br />
|OM_GET<br />
|retrieves toolbar attributes<br />
|-<br />
|TBM_GETMEMBER<br />
|retrieves a given member attribute (see the [[#TBM_GETMEMBER|TBM_GETMEMBER]] section below for more information)<br />
|-<br />
|TBM_REFRESHMEMBER<br />
|refreshes the imagery of a given member (see the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] section below for more information)<br />
|}<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
; GA_ID (uint16)<br />
: Unique ID number for the gadget.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_ReadOnly (BOOL)<br />
: If set to TRUE, none of the toolbar buttons will be selectable.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_BackFill (struct Hook *)<br />
: A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
: Defaults to NULL (the default backfill hook)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; GA_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the toolbar members' text.<br />
: Generally, you should use one font for the toolbar, set through this tag. However, you can override the global font and set a different one for individual members if needed; see TBMEMBER_TextAttr below.<br />
: Defaults to NULL (will use the system's default public screen font)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Orientation (uint32)<br />
: The toolbar orientation: horizontal or vertical.<br />
: Defaults to TB_ORIENT_HORIZ<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_Spacing (uint32)<br />
: The spacing between the individual toolbar members, in pixels.<br />
: Defaults to 2<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HorizPadding<br />
; TOOLBAR_VertPadding (uint32)<br />
: The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_InnerPadding (uint32)<br />
: The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.<br />
: Defaults to 4<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HandleOverflow (BOOL)<br />
: Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_MinVisible (uint32)<br />
: If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
: Defaults to 1<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SpacerSize (uint32)<br />
: The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.<br />
: Defaults to 5<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ButtonStyle (uint32)<br />
: The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
: Defaults to TB_BUTSTYLE_CLASSIC<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BevelStyle (uint32)<br />
: The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:<br />
<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
: When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.<br />
: Defaults to BVS_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SeparatorStyle (uint32)<br />
: Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.<br />
: Defaults to TB_SEPSTYLE_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SelectionStyle (uint32)<br />
: Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.<br />
: This tag is ignored in the classic mode with framed buttons.<br />
: Defaults to TB_SELSTYLE_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BackFill (struct Hook *)<br />
: A custom backfill hook to provide a background filled with a specific colour or pattern.<br />
: This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.<br />
: Defaults to NULL (the default backfill hook)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Display (uint32)<br />
: Specifies what you want to display inside the toolbar button or toggle members. The possible values are:<br />
<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
: Defaults to TB_DISPLAY_IMAGES<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_TextPen (uint16) (V53.4)<br />
: A pen to be used for the toolbar members' text.<br />
: Generally, you should use one text pen for the toolbar, set through this tag. However, you can override the global pen and set a different one for individual members if needed; see TBMEMBER_TextPen below.<br />
: Prefer to use pens from the dri_Pens[] array in your screen's DrawInfo structure; see the <intuition/screens.h> system include file.<br />
: Defaults to dri_Pens[TEXTPEN]<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_TextStyle (uint8) (V53.4)<br />
: A font style to be used for the toolbar members' text.<br />
: Generally, you should use one text style for the toolbar, set through this tag. However, you can override the global style and set a different one for individual members if needed; see TBMEMBER_TextStyle below.<br />
: The styles are defined in the <graphics/text.h> system include file.<br />
: Defaults to FS_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_TextPlace (uint32)<br />
: Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH. Plus, it only affects button and toggle members.<br />
: Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_LabelArray (STRPTR *)<br />
: Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.<br />
: TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
: Using this tag, the limitation is that you cannot create toggle or textbox members (only buttons, separators and spacers).<br />
: A special string, " ", will create a spacer.<br />
: A special string, "_", will create a separator.<br />
: Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.<br />
: The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TOOLBAR_EvenSize (BOOL)<br />
: If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.<br />
: If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ImageSet (uint32)<br />
: If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in the toolbar. The value passed to this tag is the image set ID.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:<br />
<br />
; TOOLBAR_AddImageSet (uint32)<br />
: Creates a new image set. The value passed to this tag is a numeric ID identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to display the particular image set in the toolbar.<br />
: An image set must have a valid ID. The value of TB_NO_ID (~0UL) is not applicable here.<br />
: This tag should be followed by a sequence of TOOLBAR_AddImage tags (see below), each creating one image in the given set.<br />
: If the gadget only uses one set of images, passing TOOLBAR_AddImageSet is not necessary. Each TOOLBAR_AddImage will add the respective image to the default image set identified by an ID of 0.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddImage (uint32)<br />
: Creates a new image in a given image set. The value passed to this tag is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID (see below) to associate the image with a particular toolbar member.<br />
: An image must have a valid ID. The value of TB_NO_ID (~0UL) is not applicable here.<br />
: This tag should be followed by a sequence of TBIMAGE_ tags (see the [[#Image attributes|Image attributes]] section below), each configuring one aspect of the image, including its optional selected variant (referred to as the "select image").<br />
: Images are added to the default image set unless a preceding TOOLBAR_AddImageSet specifies a different set.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddMember (uint32)<br />
: Creates a new toolbar member. The value passed to this tag is a numeric ID identifying the member.<br />
: Spacers and separators normally don't need an ID, so you can use TB_NO_ID as a value for TOOLBAR_AddMember when creating these members. However, if you want to manipulate spacers/separators in your GUI, an ID will be necessary so that you can pass it to TOOLBAR_SetMember to identify the respective spacer or separator member.<br />
: You can add members when the toolbar object is being created, i.e. as part of the NewObject() call, or at any time later via SetAttrs().<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetMember<br />
: Use this tag in a SetAttrs() call to identify the member you want to modify.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetGroup<br />
: Use this tag in a SetAttrs() call to identify the group of members you want to modify collectively.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
=== Member attributes ===<br />
<br />
; TBMEMBER_Type (uint32)<br />
: The type of the toolbar member. The possible values are the following:<br />
<br />
TB_MTYPE_BUTTON -- a normal toolbar button<br />
TB_MTYPE_TOGGLE -- a toggle (on/off) button<br />
TB_MTYPE_SPACER -- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
TB_MTYPE_TEXTBOX -- a read-only box to display text (V53.4)<br />
<br />
: The type is set upon member creation, and cannot be changed.<br />
: Defaults to TB_MTYPE_BUTTON<br />
: Applicability is (OM_NEW)<br />
<br />
; TBMEMBER_ImageID (uint32)<br />
: The identifier of the image to be used for the button or toggle member (see TOOLBAR_AddImage above). This tag is not relevant to textboxes, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_ImageID value of such a member.<br />
: When [[#OM_SET|OM_SET]]-ing this attribute, the method will always return TB_NEED_RETHINK, to be on the safe side. However, invoking WM_RETHINK is really only needed if the size of the new image is different from the original image. If the size is the same, a simple gadget refresh will suffice. You can trigger the refresh:<br />
:* by setting this attribute via RefreshSetGadgetAttrs(), or<br />
:* by setting this attribute via SetAttrs() and then invoking the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method on the respective button/toggle member.<br />
: (The difference is that RefreshSetGadgetAttrs() will refresh the entire toolbar, while TBM_REFRESHMEMBER will only refresh the given member.)<br />
: Defaults to TB_NO_ID (no image associated with this member)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Text (CONST_STRPTR)<br />
: The text to associate with a button, toggle or textbox member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
: The text will be used as fallback in case no image is found or provided for a button or a toggle member.<br />
: Multi-line text is supported: use "\n" as line separator in the text string.<br />
: The text string can contain an underscore character (_), indicating the keyboard shortcut for the member. (This doesn't apply to textbox members, as they are read-only and don't respond to the keyboard.)<br />
: If your toolbar features a textbox member the contents of which is going to change dynamically, it is highly recommended that you also set TBMEMBER_DomainString (see below) at member creation time. This will guarantee a size to accommodate any text, so you won't have to perform WM_RETHINK to recalculate the textbox size each time TBMEMBER_Text changes. Updating the text can be done in one of the following ways:<br />
<br />
(1) IIntuition->SetGadgetAttrs(toolbar, window, NULL,<br />
TOOLBAR_SetMember, textboxID,<br />
TBMEMBER_Text, "New text",<br />
TAG_END);<br />
<br />
(2) IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, textboxID,<br />
TBMEMBER_Text, "New text",<br />
TAG_END);<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, textboxID, window);<br />
<br />
: The difference is that (1) performs the textbox update immediately, whereas with (2) you can set the value "quietly" and only display it when you're ready, by calling the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_DomainString (CONST_STRPTR) (V53.4)<br />
: A text string based on which the minimum size of the member will be calculated. This is useful especially with TB_MTYPE_TEXTBOX members when you want to enforce a minimum size required to fit text of variable length. The domain string ought to be at least as long as the longest text to appear in the textbox.<br />
: The domain string is never rendered in the gadget.<br />
: This tag is not relevant to spacers and separators.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_TextAttr (struct TextAttr *) (V53.4)<br />
: Pointer to a TextAttr structure describing the font to be used for the member text. This tag overrides GA_TextAttr (see above).<br />
: Generally, you should use one "global" font for the toolbar, configured via GA_TextAttr. But there are situations where it makes sense to set a particular font at the member level, for example when using textbox members.<br />
: Defaults to the GA_TextAttr value<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_TextPen (uint16) (V53.4)<br />
: A pen to be used for the member text. Overrides TOOLBAR_TextPen (see above).<br />
: Generally, you should use one "global" pen for the toolbar, configured via TOOLBAR_TextPen. But there are situations where it makes sense to set a particular pen at the member level, for example when using textbox members.<br />
: Prefer to use pens from the dri_Pens[] array in your screen's DrawInfo structure; see the <intuition/screens.h> system include file.<br />
: Defaults to the TOOLBAR_TextPen value<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_TextStyle (uint8) (V53.4)<br />
: A font style to be used for the member text. Overrides TOOLBAR_TextStyle (see above).<br />
: Generally, you should use one "global" style for the toolbar, configured via TOOLBAR_TextStyle. But there are situations where it makes sense to set a particular style at the member level, for example when using textbox members.<br />
: The styles are defined in the <graphics/text.h> system include file.<br />
: Defaults to the TOOLBAR_TextStyle value<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_Disabled (BOOL)<br />
: The current state (disabled or not disabled) of a member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Disabled value of such a member.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Hidden (BOOL)<br />
: Specifies whether the particular member is displayed in the toolbar or hidden. You can use this tag to create "dynamic" toolbar layouts that adapt the actual member set to various application settings.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Selected (BOOL)<br />
: The current selection state of a toggle member. This tag is not relevant to normal buttons (TB_MTYPE_BUTTON), textboxes, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Selected value of such a member.<br />
: You can set a target BOOPSI object for any toggle member, using the standard icclass ICA_TARGET tag. The target will receive an automatic notification of the toggle selection. This way toolbar toggles can easily communicate with other boolean gadgets such as checkboxes.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_NOTIFY, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Group (uint32)<br />
: Member group ID. Several members can be manipulated at once if they are assigned to the same group. Use TOOLBAR_SetGroup with the respective group ID to identify the group to be manipulated.<br />
: Defaults to TB_NO_ID (not assigned to any group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_MXGroup (uint32)<br />
: MX group ID. Toggle members can be put in groups of mutually-exclusive buttons. When such a toggle is selected, all other toggles in the same MX group will become deselected.<br />
: This tag is not relevant to normal buttons, textboxes, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_MXGroup value of such a member.<br />
: Defaults to TB_NO_ID (not assigned to any MX group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_HintInfo (CONST_STRPTR)<br />
: The help text to be displayed when the user hovers the mouse pointer over the respective member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_HintInfo value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_UserData (APTR)<br />
: Arbitrary user data associated with this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
=== Image attributes ===<br />
<br />
Note: Images are configured at OM_NEW, i.e. when creating each respective image. Image attributes cannot be changed later.<br />
<br />
; TBIMAGE_Image (struct Image *)<br />
: Custom image to be used for a button or a toggle member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_ImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImage (struct Image *)<br />
: Custom image to display when the member becomes selected.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the select image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
;TBIMAGE_Width (uint32)<br />
;TBIMAGE_Height (uint32)<br />
: Image dimensions, in pixels. These tags can only be used in connection with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the respective source file will be scaled to the specified width and height. Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot be resized using these tags.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW)<br />
<br />
== Notes ==<br />
<br />
Some of the attributes described above change the sizing requirements of the gadget. If set on the fly (i.e. when the toolbar is already displayed in the window), the gadget domain will need recalculating and a re-layout must take place. Refer to the [[#OM_SET|OM_SET]] method documentation below to see how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image. [[#Image attributes|Image attributes]] cannot be changed later.<br />
<br />
== Bugs ==<br />
<br />
== See also ==<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
; NAME<br />
: OM_SET -- set toolbar attributes<br />
<br />
; SYNOPSIS<br />
: uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
: uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win, struct Requester *req, Tag tag1, ...);<br />
<br />
; FUNCTION<br />
: This method sets the attributes of the toolbar and/or of its members. SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions to invoke this method.<br />
: To change a member attribute you first need to pass TOOLBAR_SetMember to identify the respective member, and then the member attribute tag(s). See the EXAMPLE section below.<br />
: To change an attribute collectively for a group of members you first need to pass TOOLBAR_SetGroup to identify the respective group, and then the member attribute tag(s). See the EXAMPLE section below.<br />
<br />
; INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
; RESULT<br />
: This method will return TB_NEED_RETHINK if the gadget ''believes'' that one or more of the attributes will change the sizing requirements of the toolbar. Typically, invoking the WM_RETHINK method on the gadget's window object is needed, in order to recalculate the domain and re-layout the contents.<br />
: If you know you will be changing an attribute that requires a WM_RETHINK, prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
: The method returns 0L if no rethink is needed.<br />
<br />
; EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, groupID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
; NAME<br />
: TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, uint32 attrID, uint32 *storage);<br />
<br />
; FUNCTION<br />
: Use this method to obtain the value of a given member attribute.<br />
: Because of the way OM_GET is implemented in Intuition, getting member attributes is done differently compared to setting them. The difference boils down to the following:<br />
:* We cannot use a convenience function such as GetAttr() or GetAttrs(), so a dedicated method is provided. Refer to the EXAMPLE section below to see how to invoke the method.<br />
:* Only one attribute can be queried at a time. (As multiple attributes will rarely be requested in real use, this limitation should not pose a significant problem.)<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
attrID -- the attribute tag identifier<br />
storage -- a pointer to the variable for storing the attribute value<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the requested attribute value has been obtained successfully. The attribute value itself is returned in the provided storage variable.<br />
<br />
; EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID, TBMEMBER_Selected, &storage);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_REFRESHMEMBER ===<br />
<br />
; NAME<br />
: TBM_REFRESHMEMBER -- refresh the imagery of a given member (V53.3)<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbRefreshMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, struct Window *window);<br />
<br />
; FUNCTION<br />
: Use this method to refresh the imagery of a given button or toggle member.<br />
: The method has no effect on spacers and separators.<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbRefreshMember structure<br />
<br />
For IDoMethod():<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_REFRESHMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
window -- a pointer to the window the toolbar resides in<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the refresh has taken place.<br />
<br />
; EXAMPLE<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1030ToolBar Gadget Class2021-01-09T20:45:33Z<p>Trixie: More updates.</p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Supported methods ==<br />
<br />
{| class="wikitable"<br />
!Method ID<br />
!Description<br />
|-<br />
|OM_NEW<br />
|creates the toolbar object, sets attributes and defaults<br />
|-<br />
|OM_DISPOSE<br />
|disposes of the toolbar object<br />
|-<br />
|OM_REMMEMBER<br />
|used by the class internally; consider this method private<br />
|-<br />
|OM_SET<br />
|sets toolbar, member and image attributes (see the [[#OM_SET|OM_SET]] section below for more information)<br />
|-<br />
|OM_GET<br />
|retrieves toolbar attributes<br />
|-<br />
|TBM_GETMEMBER<br />
|retrieves a given member attribute (see the [[#TBM_GETMEMBER|TBM_GETMEMBER]] section below for more information)<br />
|-<br />
|TBM_REFRESHMEMBER<br />
|refreshes the imagery of a given member (see the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] section below for more information)<br />
|}<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
; GA_ID (uint16)<br />
: Unique ID number for the gadget.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_ReadOnly (BOOL)<br />
: If set to TRUE, none of the toolbar buttons will be selectable.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_BackFill (struct Hook *)<br />
: A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
: Defaults to NULL (the default backfill hook)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; GA_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the toolbar members' text.<br />
: Generally, you should use one font for the toolbar, set through this tag. However, you can override the global font and set a different one for individual members if needed; see TBMEMBER_TextAttr below.<br />
: Defaults to NULL (will use the system's default public screen font)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Orientation (uint32)<br />
: The toolbar orientation: horizontal or vertical.<br />
: Defaults to TB_ORIENT_HORIZ<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_Spacing (uint32)<br />
: The spacing between the individual toolbar members, in pixels.<br />
: Defaults to 2<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HorizPadding<br />
; TOOLBAR_VertPadding (uint32)<br />
: The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_InnerPadding (uint32)<br />
: The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.<br />
: Defaults to 4<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HandleOverflow (BOOL)<br />
: Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_MinVisible (uint32)<br />
: If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
: Defaults to 1<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SpacerSize (uint32)<br />
: The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.<br />
: Defaults to 5<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ButtonStyle (uint32)<br />
: The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
: Defaults to TB_BUTSTYLE_CLASSIC<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BevelStyle (uint32)<br />
: The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:<br />
<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
: When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.<br />
: Defaults to BVS_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SeparatorStyle (uint32)<br />
: Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.<br />
: Defaults to TB_SEPSTYLE_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SelectionStyle (uint32)<br />
: Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.<br />
: This tag is ignored in the classic mode with framed buttons.<br />
: Defaults to TB_SELSTYLE_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BackFill (struct Hook *)<br />
: A custom backfill hook to provide a background filled with a specific colour or pattern.<br />
: This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.<br />
: Defaults to NULL (the default backfill hook)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Display (uint32)<br />
: Specifies what you want to display inside the toolbar button or toggle members. The possible values are:<br />
<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
: Defaults to TB_DISPLAY_IMAGES<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_TextPen (uint16) (V53.4)<br />
: A pen to be used for the toolbar members' text.<br />
: Generally, you should use one text pen for the toolbar, set through this tag. However, you can override the global pen and set a different one for individual members if needed; see TBMEMBER_TextPen below.<br />
: Prefer to use pens from the dri_Pens[] array in your screen's DrawInfo structure; see the <intuition/screens.h> system include file.<br />
: Defaults to dri_Pens[TEXTPEN]<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_TextStyle (uint8) (V53.4)<br />
: A font style to be used for the toolbar members' text.<br />
: Generally, you should use one text style for the toolbar, set through this tag. However, you can override the global style and set a different one for individual members if needed; see TBMEMBER_TextStyle below.<br />
: The styles are defined in the <graphics/text.h> system include file.<br />
: Defaults to FS_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_TextPlace (uint32)<br />
: Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH. Plus, it only affects button and toggle members.<br />
: Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_LabelArray (STRPTR *)<br />
: Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.<br />
: TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
: Using this tag, the limitation is that you cannot create toggle or textbox members (only buttons, separators and spacers).<br />
: A special string, " ", will create a spacer.<br />
: A special string, "_", will create a separator.<br />
: Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.<br />
: The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TOOLBAR_EvenSize (BOOL)<br />
: If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.<br />
: If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ImageSet (uint32)<br />
: If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in the toolbar. The value passed to this tag is the image set ID.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:<br />
<br />
; TOOLBAR_AddImageSet (uint32)<br />
: Creates a new image set. The value passed to this tag is a numeric ID identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to display the particular image set in the toolbar.<br />
: An image set must have a valid ID. The value of TB_NO_ID (~0UL) is not applicable here.<br />
: This tag should be followed by a sequence of TOOLBAR_AddImage tags (see below), each creating one image in the given set.<br />
: If the gadget only uses one set of images, passing TOOLBAR_AddImageSet is not necessary. Each TOOLBAR_AddImage will add the respective image to the default image set identified by an ID of 0.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddImage (uint32)<br />
: Creates a new image in a given image set. The value passed to this tag is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID (see below) to associate the image with a particular toolbar member.<br />
: An image must have a valid ID. The value of TB_NO_ID (~0UL) is not applicable here.<br />
: This tag should be followed by a sequence of TBIMAGE_ tags (see the [[#Image attributes|Image attributes]] section below), each configuring one aspect of the image, including its optional selected variant (referred to as the "select image").<br />
: Images are added to the default image set unless a preceding TOOLBAR_AddImageSet specifies a different set.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddMember (uint32)<br />
: Creates a new toolbar member. The value passed to this tag is a numeric ID identifying the member.<br />
: Spacers and separators normally don't need an ID, so you can use TB_NO_ID as a value for TOOLBAR_AddMember when creating these members. However, if you want to manipulate spacers/separators in your GUI, an ID will be necessary so that you can pass it to TOOLBAR_SetMember to identify the respective spacer or separator member.<br />
: You can add members when the toolbar object is being created, i.e. as part of the NewObject() call, or at any time later via SetAttrs().<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetMember<br />
: Use this tag in a SetAttrs() call to identify the member you want to modify.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetGroup<br />
: Use this tag in a SetAttrs() call to identify the group of members you want to modify collectively.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
=== Member attributes ===<br />
<br />
; TBMEMBER_Type (uint32)<br />
: The type of the toolbar member. The possible values are the following:<br />
<br />
TB_MTYPE_BUTTON -- a normal toolbar button<br />
TB_MTYPE_TOGGLE -- a toggle (on/off) button<br />
TB_MTYPE_SPACER -- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
TB_MTYPE_TEXTBOX -- a read-only box to display text (V53.4)<br />
<br />
: The type is set upon member creation, and cannot be changed.<br />
: Defaults to TB_MTYPE_BUTTON<br />
: Applicability is (OM_NEW)<br />
<br />
; TBMEMBER_ImageID (uint32)<br />
: The identifier of the image to be used for the button or toggle member (see TOOLBAR_AddImage above). This tag is not relevant to textboxes, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_ImageID value of such a member.<br />
: When [[#OM_SET|OM_SET]]-ing this attribute, the method will always return TB_NEED_RETHINK, to be on the safe side. However, invoking WM_RETHINK is really only needed if the size of the new image is different from the original image. If the size is the same, a simple gadget refresh will suffice. You can trigger the refresh:<br />
:* by setting this attribute via RefreshSetGadgetAttrs(), or<br />
:* by setting this attribute via SetAttrs() and then invoking the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method on the respective button/toggle member.<br />
: (The difference is that RefreshSetGadgetAttrs() will refresh the entire toolbar, while TBM_REFRESHMEMBER will only refresh the given member.)<br />
: Defaults to TB_NO_ID (no image associated with this member)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Text (CONST_STRPTR)<br />
: The text to associate with a button, toggle or textbox member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
: The text will be used as fallback in case no image is found or provided for a button or a toggle member.<br />
: Multi-line text is supported: use "\n" as line separator in the text string.<br />
: The text string can contain an underscore character (_), indicating the keyboard shortcut for the member. (This doesn't apply to textbox members, as they are read-only and don't respond to the keyboard.)<br />
: If your toolbar features a textbox member the contents of which is going to change dynamically, it is highly recommended that you also set TBMEMBER_DomainString (see below) at member creation time. This will guarantee a size to accommodate any text, so you won't have to perform WM_RETHINK to recalculate the textbox size each time TBMEMBER_Text changes. Updating the text can be done in one of the following ways:<br />
<br />
(1) IIntuition->SetGadgetAttrs(toolbar, window, NULL,<br />
TOOLBAR_SetMember, textboxID,<br />
TBMEMBER_Text, "New text",<br />
TAG_END);<br />
<br />
(2) IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, textboxID,<br />
TBMEMBER_Text, "New text",<br />
TAG_END);<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, textboxID, window);<br />
<br />
: The difference is that (1) performs the textbox update immediately, whereas with (2) you can set the value "quietly" and only display it when you're ready, by calling the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_DomainString (CONST_STRPTR) (V53.4)<br />
: A text string based on which the minimum size of the member will be calculated. This is useful especially with TB_MTYPE_TEXTBOX members when you want to enforce a minimum size required to fit text of variable length. The domain string ought to be at least as long as the longest text to appear in the textbox.<br />
: The domain string is never rendered in the gadget.<br />
: This tag is not relevant to spacers and separators.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_TextAttr (struct TextAttr *) (V53.4)<br />
: Pointer to a TextAttr structure describing the font to be used for the member text. This tag overrides GA_TextAttr (see above).<br />
: Generally, you should use one "global" font for the toolbar, configured via GA_TextAttr. But there are situations where it makes sense to set a particular font at the member level, for example when using textbox members.<br />
: Defaults to the GA_TextAttr value<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_TextPen (uint16) (V53.4)<br />
: A pen to be used for the member text. Overrides TOOLBAR_TextPen (see above).<br />
: Generally, you should use one "global" pen for the toolbar, configured via TOOLBAR_TextPen. But there are situations where it makes sense to set a particular pen at the member level, for example when using textbox members.<br />
: Prefer to use pens from the dri_Pens[] array in your screen's DrawInfo structure; see the <intuition/screens.h> system include file.<br />
: Defaults to the TOOLBAR_TextPen value<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_TextStyle (uint8) (V53.4)<br />
: A font style to be used for the member text. Overrides TOOLBAR_TextStyle (see above).<br />
: Generally, you should use one "global" style for the toolbar, configured via TOOLBAR_TextStyle. But there are situations where it makes sense to set a particular style at the member level, for example when using textbox members.<br />
: The styles are defined in the <graphics/text.h> system include file.<br />
: Defaults to the TOOLBAR_TextStyle value<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_Disabled (BOOL)<br />
: The current state (disabled or not disabled) of a member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Disabled value of such a member.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Hidden (BOOL)<br />
: Specifies whether the particular member is displayed in the toolbar or hidden. You can use this tag to create "dynamic" toolbar layouts that adapt the actual member set to various application settings.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Selected (BOOL)<br />
: The current selection state of a toggle member. This tag is not relevant to normal buttons (TB_MTYPE_BUTTON), textboxes, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Selected value of such a member.<br />
: You can set a target BOOPSI object for any toggle member, using the standard icclass ICA_TARGET tag. The target will receive an automatic notification of the toggle selection. This way toolbar toggles can easily communicate with other boolean gadgets such as checkboxes.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_NOTIFY, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Group (uint32)<br />
: Member group ID. Several members can be manipulated at once if they are assigned to the same group. Use TOOLBAR_SetGroup with the respective group ID to identify the group to be manipulated.<br />
: Defaults to TB_NO_ID (not assigned to any group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_MXGroup (uint32)<br />
: MX group ID. Toggle members can be put in groups of mutually-exclusive buttons. When such a toggle is selected, all other toggles in the same MX group will become deselected.<br />
: This tag is not relevant to normal buttons, textboxes, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_MXGroup value of such a member.<br />
: Defaults to TB_NO_ID (not assigned to any MX group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_HintInfo (CONST_STRPTR)<br />
: The help text to be displayed when the user hovers the mouse pointer over the respective member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_HintInfo value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_UserData (APTR)<br />
: Arbitrary user data associated with this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
=== Image attributes ===<br />
<br />
; TBIMAGE_Image (struct Image *)<br />
: Custom image to be used for a button or a toggle member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_ImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImage (struct Image *)<br />
: Custom image to display when the member becomes selected.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the select image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
;TBIMAGE_Width (uint32)<br />
;TBIMAGE_Height (uint32)<br />
: Image dimensions, in pixels. These tags can only be used in connection with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the respective source file will be scaled to the specified width and height. Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot be resized using these tags.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW)<br />
<br />
== Notes ==<br />
<br />
Some of the attributes described above change the sizing requirements of the gadget. If set on the fly (i.e. when the toolbar is already displayed in the window), the gadget domain will need recalculating and a re-layout must take place. Refer to the [[#OM_SET|OM_SET]] method documentation below to see how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image. [[#Image attributes|Image attributes]] cannot be changed later.<br />
<br />
== Bugs ==<br />
<br />
== See also ==<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
; NAME<br />
: OM_SET -- set toolbar attributes<br />
<br />
; SYNOPSIS<br />
: uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
: uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win, struct Requester *req, Tag tag1, ...);<br />
<br />
; FUNCTION<br />
: This method sets the attributes of the toolbar and/or of its members. SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions to invoke this method.<br />
: To change a member attribute you first need to pass TOOLBAR_SetMember to identify the respective member, and then the member attribute tag(s). See the EXAMPLE section below.<br />
: To change an attribute collectively for a group of members you first need to pass TOOLBAR_SetGroup to identify the respective group, and then the member attribute tag(s). See the EXAMPLE section below.<br />
<br />
; INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
; RESULT<br />
: This method will return TB_NEED_RETHINK if the gadget ''believes'' that one or more of the attributes will change the sizing requirements of the toolbar. Typically, invoking the WM_RETHINK method on the gadget's window object is needed, in order to recalculate the domain and re-layout the contents.<br />
: If you know you will be changing an attribute that requires a WM_RETHINK, prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
: The method returns 0L if no rethink is needed.<br />
<br />
; EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, groupID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
; NAME<br />
: TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, uint32 attrID, uint32 *storage);<br />
<br />
; FUNCTION<br />
: Use this method to obtain the value of a given member attribute.<br />
: Because of the way OM_GET is implemented in Intuition, getting member attributes is done differently compared to setting them. The difference boils down to the following:<br />
:* We cannot use a convenience function such as GetAttr() or GetAttrs(), so a dedicated method is provided. Refer to the EXAMPLE section below to see how to invoke the method.<br />
:* Only one attribute can be queried at a time. (As multiple attributes will rarely be requested in real use, this limitation should not pose a significant problem.)<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
attrID -- the attribute tag identifier<br />
storage -- a pointer to the variable for storing the attribute value<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the requested attribute value has been obtained successfully. The attribute value itself is returned in the provided storage variable.<br />
<br />
; EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID, TBMEMBER_Selected, &storage);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_REFRESHMEMBER ===<br />
<br />
; NAME<br />
: TBM_REFRESHMEMBER -- refresh the imagery of a given member (V53.3)<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbRefreshMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, struct Window *window);<br />
<br />
; FUNCTION<br />
: Use this method to refresh the imagery of a given button or toggle member.<br />
: The method has no effect on spacers and separators.<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbRefreshMember structure<br />
<br />
For IDoMethod():<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_REFRESHMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
window -- a pointer to the window the toolbar resides in<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the refresh has taken place.<br />
<br />
; EXAMPLE<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1029ToolBar Gadget Class2021-01-08T21:08:21Z<p>Trixie: Added TBMEMBER_TextStyle. Updated TBMEMBER_Text.</p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Supported methods ==<br />
<br />
{| class="wikitable"<br />
!Method ID<br />
!Description<br />
|-<br />
|OM_NEW<br />
|creates the toolbar object, sets attributes and defaults<br />
|-<br />
|OM_DISPOSE<br />
|disposes of the toolbar object<br />
|-<br />
|OM_REMMEMBER<br />
|used by the class internally; consider this method private<br />
|-<br />
|OM_SET<br />
|sets toolbar, member and image attributes (see the [[#OM_SET|OM_SET]] section below for more information)<br />
|-<br />
|OM_GET<br />
|retrieves toolbar attributes<br />
|-<br />
|TBM_GETMEMBER<br />
|retrieves a given member attribute (see the [[#TBM_GETMEMBER|TBM_GETMEMBER]] section below for more information)<br />
|-<br />
|TBM_REFRESHMEMBER<br />
|refreshes the imagery of a given member (see the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] section below for more information)<br />
|}<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
; GA_ID (uint16)<br />
: Unique ID number for the gadget.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_ReadOnly (BOOL)<br />
: If set to TRUE, none of the toolbar buttons will be selectable.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_BackFill (struct Hook *)<br />
: A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
: Defaults to NULL (the default backfill hook)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; GA_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the toolbar members' text.<br />
: Generally, you should use one font for the toolbar, set through this tag. However, you can override the global font and set a different one for individual members if needed; see TBMEMBER_TextAttr below.<br />
: Defaults to NULL (will use the system's default public screen font)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Orientation (uint32)<br />
: The toolbar orientation: horizontal or vertical.<br />
: Defaults to TB_ORIENT_HORIZ<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_Spacing (uint32)<br />
: The spacing between the individual toolbar members, in pixels.<br />
: Defaults to 2<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HorizPadding<br />
; TOOLBAR_VertPadding (uint32)<br />
: The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_InnerPadding (uint32)<br />
: The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.<br />
: Defaults to 4<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HandleOverflow (BOOL)<br />
: Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_MinVisible (uint32)<br />
: If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
: Defaults to 1<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SpacerSize (uint32)<br />
: The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.<br />
: Defaults to 5<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ButtonStyle (uint32)<br />
: The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
: Defaults to TB_BUTSTYLE_CLASSIC<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BevelStyle (uint32)<br />
: The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:<br />
<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
: When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.<br />
: Defaults to BVS_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SeparatorStyle (uint32)<br />
: Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.<br />
: Defaults to TB_SEPSTYLE_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SelectionStyle (uint32)<br />
: Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.<br />
: This tag is ignored in the classic mode with framed buttons.<br />
: Defaults to TB_SELSTYLE_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BackFill (struct Hook *)<br />
: A custom backfill hook to provide a background filled with a specific colour or pattern.<br />
: This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.<br />
: Defaults to NULL (the default backfill hook)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Display (uint32)<br />
: Specifies what you want to display inside the toolbar button or toggle members. The possible values are:<br />
<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
: Defaults to TB_DISPLAY_IMAGES<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_TextPen (uint16) (V53.4)<br />
: A pen to be used for the toolbar members' text.<br />
: Generally, you should use one text pen for the toolbar, set through this tag. However, you can override the global pen and set a different one for individual members if needed; see TBMEMBER_TextPen below.<br />
: Prefer to use pens from the dri_Pens[] array in your screen's DrawInfo structure; see the <intuition/screens.h> system include file.<br />
: Defaults to dri_Pens[TEXTPEN]<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_TextStyle (uint8) (V53.4)<br />
: A font style to be used for the toolbar members' text.<br />
: Generally, you should use one text style for the toolbar, set through this tag. However, you can override the global style and set a different one for individual members if needed; see TBMEMBER_TextStyle below.<br />
: The styles are defined in the <graphics/text.h> system include file.<br />
: Defaults to FS_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_TextPlace (uint32)<br />
: Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH. Plus, it only affects button and toggle members.<br />
: Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_LabelArray (STRPTR *)<br />
: Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.<br />
: TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
: Using this tag, the limitation is that you cannot create toggle members (only buttons, separators and spacers).<br />
: A special string, " ", will create a spacer.<br />
: A special string, "_", will create a separator.<br />
: Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.<br />
: The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TOOLBAR_EvenSize (BOOL)<br />
: If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.<br />
: If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ImageSet (uint32)<br />
: If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in the toolbar. The value passed to this tag is the image set ID.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:<br />
<br />
; TOOLBAR_AddImageSet (uint32)<br />
: Creates a new image set. The value passed to this tag is a numeric ID identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to display the particular image set in the toolbar.<br />
: An image set must have a valid ID. The value of TB_NO_ID (~0UL) is not applicable here.<br />
: This tag should be followed by a sequence of TOOLBAR_AddImage tags (see below), each creating one image in the given set.<br />
: If the gadget only uses one set of images, passing TOOLBAR_AddImageSet is not necessary. Each TOOLBAR_AddImage will add the respective image to the default image set identified by an ID of 0.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddImage (uint32)<br />
: Creates a new image in a given image set. The value passed to this tag is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID (see below) to associate the image with a particular toolbar member.<br />
: An image must have a valid ID. The value of TB_NO_ID (~0UL) is not applicable here.<br />
: This tag should be followed by a sequence of TBIMAGE_ tags (see the [[#Image attributes|Image attributes]] section below), each configuring one aspect of the image, including its optional selected variant (referred to as the "select image").<br />
: Images are added to the default image set unless a preceding TOOLBAR_AddImageSet specifies a different set.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddMember (uint32)<br />
: Creates a new toolbar member. The value passed to this tag is a numeric ID identifying the member.<br />
: Spacers and separators normally don't need an ID, so you can use TB_NO_ID as a value for TOOLBAR_AddMember when creating these members. However, if you want to manipulate spacers/separators in your GUI, an ID will be necessary so that you can pass it to TOOLBAR_SetMember to identify the respective spacer or separator member.<br />
: You can add members when the toolbar object is being created, i.e. as part of the NewObject() call, or at any time later via SetAttrs().<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetMember<br />
: Use this tag in a SetAttrs() call to identify the member you want to modify.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetGroup<br />
: Use this tag in a SetAttrs() call to identify the group of members you want to modify collectively.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
=== Member attributes ===<br />
<br />
; TBMEMBER_Type (uint32)<br />
: The type of the toolbar member. The possible values are the following:<br />
<br />
TB_MTYPE_BUTTON -- a normal toolbar button<br />
TB_MTYPE_TOGGLE -- a toggle (on/off) button<br />
TB_MTYPE_SPACER -- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
TB_MTYPE_TEXTBOX -- a read-only box to display text (V53.4)<br />
<br />
: The type is set upon member creation, and cannot be changed.<br />
: Defaults to TB_MTYPE_BUTTON<br />
: Applicability is (OM_NEW)<br />
<br />
; TBMEMBER_ImageID (uint32)<br />
: The identifier of the image to be used for the button or toggle member (see TOOLBAR_AddImage above). This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_ImageID value of such a member.<br />
: When [[#OM_SET|OM_SET]]-ing this attribute, the method will always return TB_NEED_RETHINK, to be on the safe side. However, invoking WM_RETHINK is really only needed if the size of the new image is different from the original image. If the size is the same, a simple gadget refresh will suffice. You can trigger the refresh:<br />
:* by setting this attribute via RefreshSetGadgetAttrs(), or<br />
:* by setting this attribute via SetAttrs() and then invoking the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method on the respective button/toggle member.<br />
: (The difference is that RefreshSetGadgetAttrs() will refresh the entire toolbar, while TBM_REFRESHMEMBER will only refresh the given member.)<br />
: Defaults to TB_NO_ID (no image associated with this member)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Text (CONST_STRPTR)<br />
: The text to associate with a button, toggle or textbox member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
: The text will be used as fallback in case no image is found or provided for a button or a toggle member.<br />
: The text string can contain an underscore character (_), indicating the keyboard shortcut for the member. (This doesn't apply to textbox members, as they are read-only and don't respond to the keyboard.)<br />
: If your toolbar features a textbox member the contents of which is going to change dynamically, it is highly recommended that you also set TBMEMBER_DomainString (see below) at member creation time. This will guarantee a size to accommodate any text, so you won't have to perform WM_RETHINK to recalculate the textbox size each time TBMEMBER_Text changes. Updating the text can be done in one of the following ways:<br />
<br />
(1) IIntuition->SetGadgetAttrs(toolbar, window, NULL,<br />
TOOLBAR_SetMember, textboxID,<br />
TBMEMBER_Text, "New text",<br />
TAG_END);<br />
<br />
(2) IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, textboxID,<br />
TBMEMBER_Text, "New text",<br />
TAG_END);<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, textboxID, window);<br />
<br />
: The difference is that (1) performs the textbox update immediately, whereas with (2) you can set the value "quietly" and only display it when you're ready, by calling the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_DomainString (CONST_STRPTR) (V53.4)<br />
: A text string based on which the minimum size of the member will be calculated. This is useful especially with TB_MTYPE_TEXTBOX members when you want to enforce a minimum size required to fit text of variable length. The domain string ought to be at least as long as the longest text to appear in the textbox.<br />
: The domain string is never rendered in the gadget.<br />
: This tag is not relevant to spacers and separators.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_TextAttr (struct TextAttr *) (V53.4)<br />
: Pointer to a TextAttr structure describing the font to be used for the member text. This tag overrides GA_TextAttr (see above).<br />
: Generally, you should use one "global" font for the toolbar, configured via GA_TextAttr. But there are situations where it makes sense to set a particular font at the member level, for example when using textbox members.<br />
: Defaults to the GA_TextAttr value<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_TextPen (uint16) (V53.4)<br />
: A pen to be used for the member text. Overrides TOOLBAR_TextPen (see above).<br />
: Generally, you should use one "global" pen for the toolbar, configured via TOOLBAR_TextPen. But there are situations where it makes sense to set a particular pen at the member level, for example when using textbox members.<br />
: Prefer to use pens from the dri_Pens[] array in your screen's DrawInfo structure; see the <intuition/screens.h> system include file.<br />
: Defaults to the TOOLBAR_TextPen value<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_TextStyle (uint8) (V53.4)<br />
: A font style to be used for the member text. Overrides TOOLBAR_TextStyle (see above).<br />
: Generally, you should use one "global" style for the toolbar, configured via TOOLBAR_TextStyle. But there are situations where it makes sense to set a particular style at the member level, for example when using textbox members.<br />
: The styles are defined in the <graphics/text.h> system include file.<br />
: Defaults to the TOOLBAR_TextStyle value<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_Disabled (BOOL)<br />
: The current state (disabled or not disabled) of a member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Disabled value of such a member.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Hidden (BOOL)<br />
: Specifies whether the particular member is displayed in the toolbar or hidden. You can use this tag to create "dynamic" toolbar layouts that adapt the actual member set to various application settings.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Selected (BOOL)<br />
: The current selection state of a toggle member. This tag is not relevant to normal buttons (TB_MTYPE_BUTTON), spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Selected value of such a member.<br />
: You can set a target BOOPSI object for any toggle member, using the standard icclass ICA_TARGET tag. The target will receive an automatic notification of the toggle selection. This way toolbar toggles can easily communicate with other boolean gadgets such as checkboxes.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_NOTIFY, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Group (uint32)<br />
: Member group ID. Several members can be manipulated at once if they are assigned to the same group. Use TOOLBAR_SetGroup with the respective group ID to identify the group to be manipulated.<br />
: Defaults to TB_NO_ID (not assigned to any group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_MXGroup (uint32)<br />
: MX group ID. Toggle members can be put in groups of mutually-exclusive buttons. When such a toggle is selected, all other toggles in the same MX group will become deselected.<br />
: This tag is not relevant to normal buttons, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_MXGroup value of such a member.<br />
: Defaults to TB_NO_ID (not assigned to any MX group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_HintInfo (CONST_STRPTR)<br />
: The help text to be displayed when the user hovers the mouse pointer over the respective member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_HintInfo value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_UserData (APTR)<br />
: Arbitrary user data associated with this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
=== Image attributes ===<br />
<br />
; TBIMAGE_Image (struct Image *)<br />
: Custom image to be used for a button or a toggle member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_ImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImage (struct Image *)<br />
: Custom image to display when the member becomes selected.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the select image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
;TBIMAGE_Width (uint32)<br />
;TBIMAGE_Height (uint32)<br />
: Image dimensions, in pixels. These tags can only be used in connection with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the respective source file will be scaled to the specified width and height. Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot be resized using these tags.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW)<br />
<br />
== Notes ==<br />
<br />
Some of the attributes described above change the sizing requirements of the gadget. If set on the fly (i.e. when the toolbar is already displayed in the window), the gadget domain will need recalculating and a re-layout must take place. Refer to the [[#OM_SET|OM_SET]] method documentation below to see how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image. [[#Image attributes|Image attributes]] cannot be changed later.<br />
<br />
== Bugs ==<br />
<br />
== See also ==<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
; NAME<br />
: OM_SET -- set toolbar attributes<br />
<br />
; SYNOPSIS<br />
: uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
: uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win, struct Requester *req, Tag tag1, ...);<br />
<br />
; FUNCTION<br />
: This method sets the attributes of the toolbar and/or of its members. SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions to invoke this method.<br />
: To change a member attribute you first need to pass TOOLBAR_SetMember to identify the respective member, and then the member attribute tag(s). See the EXAMPLE section below.<br />
: To change an attribute collectively for a group of members you first need to pass TOOLBAR_SetGroup to identify the respective group, and then the member attribute tag(s). See the EXAMPLE section below.<br />
<br />
; INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
; RESULT<br />
: This method will return TB_NEED_RETHINK if the gadget ''believes'' that one or more of the attributes will change the sizing requirements of the toolbar. Typically, invoking the WM_RETHINK method on the gadget's window object is needed, in order to recalculate the domain and re-layout the contents.<br />
: If you know you will be changing an attribute that requires a WM_RETHINK, prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
: The method returns 0L if no rethink is needed.<br />
<br />
; EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, groupID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
; NAME<br />
: TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, uint32 attrID, uint32 *storage);<br />
<br />
; FUNCTION<br />
: Use this method to obtain the value of a given member attribute.<br />
: Because of the way OM_GET is implemented in Intuition, getting member attributes is done differently compared to setting them. The difference boils down to the following:<br />
:* We cannot use a convenience function such as GetAttr() or GetAttrs(), so a dedicated method is provided. Refer to the EXAMPLE section below to see how to invoke the method.<br />
:* Only one attribute can be queried at a time. (As multiple attributes will rarely be requested in real use, this limitation should not pose a significant problem.)<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
attrID -- the attribute tag identifier<br />
storage -- a pointer to the variable for storing the attribute value<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the requested attribute value has been obtained successfully. The attribute value itself is returned in the provided storage variable.<br />
<br />
; EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID, TBMEMBER_Selected, &storage);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_REFRESHMEMBER ===<br />
<br />
; NAME<br />
: TBM_REFRESHMEMBER -- refresh the imagery of a given member (V53.3)<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbRefreshMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, struct Window *window);<br />
<br />
; FUNCTION<br />
: Use this method to refresh the imagery of a given button or toggle member.<br />
: The method has no effect on spacers and separators.<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbRefreshMember structure<br />
<br />
For IDoMethod():<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_REFRESHMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
window -- a pointer to the window the toolbar resides in<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the refresh has taken place.<br />
<br />
; EXAMPLE<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1028ToolBar Gadget Class2021-01-08T20:03:11Z<p>Trixie: Added TOOLBAR_TextStyle. TBMEMBER_DomainString.</p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Supported methods ==<br />
<br />
{| class="wikitable"<br />
!Method ID<br />
!Description<br />
|-<br />
|OM_NEW<br />
|creates the toolbar object, sets attributes and defaults<br />
|-<br />
|OM_DISPOSE<br />
|disposes of the toolbar object<br />
|-<br />
|OM_REMMEMBER<br />
|used by the class internally; consider this method private<br />
|-<br />
|OM_SET<br />
|sets toolbar, member and image attributes (see the [[#OM_SET|OM_SET]] section below for more information)<br />
|-<br />
|OM_GET<br />
|retrieves toolbar attributes<br />
|-<br />
|TBM_GETMEMBER<br />
|retrieves a given member attribute (see the [[#TBM_GETMEMBER|TBM_GETMEMBER]] section below for more information)<br />
|-<br />
|TBM_REFRESHMEMBER<br />
|refreshes the imagery of a given member (see the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] section below for more information)<br />
|}<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
; GA_ID (uint16)<br />
: Unique ID number for the gadget.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_ReadOnly (BOOL)<br />
: If set to TRUE, none of the toolbar buttons will be selectable.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_BackFill (struct Hook *)<br />
: A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
: Defaults to NULL (the default backfill hook)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; GA_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the toolbar members' text.<br />
: Generally, you should use one font for the toolbar, set through this tag. However, you can override the global font and set a different one for individual members if needed; see TBMEMBER_TextAttr below.<br />
: Defaults to NULL (will use the system's default public screen font)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Orientation (uint32)<br />
: The toolbar orientation: horizontal or vertical.<br />
: Defaults to TB_ORIENT_HORIZ<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_Spacing (uint32)<br />
: The spacing between the individual toolbar members, in pixels.<br />
: Defaults to 2<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HorizPadding<br />
; TOOLBAR_VertPadding (uint32)<br />
: The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_InnerPadding (uint32)<br />
: The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.<br />
: Defaults to 4<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HandleOverflow (BOOL)<br />
: Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_MinVisible (uint32)<br />
: If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
: Defaults to 1<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SpacerSize (uint32)<br />
: The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.<br />
: Defaults to 5<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ButtonStyle (uint32)<br />
: The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
: Defaults to TB_BUTSTYLE_CLASSIC<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BevelStyle (uint32)<br />
: The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:<br />
<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
: When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.<br />
: Defaults to BVS_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SeparatorStyle (uint32)<br />
: Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.<br />
: Defaults to TB_SEPSTYLE_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SelectionStyle (uint32)<br />
: Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.<br />
: This tag is ignored in the classic mode with framed buttons.<br />
: Defaults to TB_SELSTYLE_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BackFill (struct Hook *)<br />
: A custom backfill hook to provide a background filled with a specific colour or pattern.<br />
: This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.<br />
: Defaults to NULL (the default backfill hook)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Display (uint32)<br />
: Specifies what you want to display inside the toolbar button or toggle members. The possible values are:<br />
<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
: Defaults to TB_DISPLAY_IMAGES<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_TextPen (uint16) (V53.4)<br />
: A pen to be used for the toolbar members' text.<br />
: Generally, you should use one text pen for the toolbar, set through this tag. However, you can override the global pen and set a different one for individual members if needed; see TBMEMBER_TextPen below.<br />
: Prefer to use pens from the dri_Pens[] array in your screen's DrawInfo structure; see the <intuition/screens.h> system include file.<br />
: Defaults to dri_Pens[TEXTPEN]<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_TextStyle (uint8) (V53.4)<br />
: A font style to be used for the toolbar members' text.<br />
: Generally, you should use one text style for the toolbar, set through this tag. However, you can override the global style and set a different one for individual members if needed; see TBMEMBER_TextStyle below.<br />
: The styles are defined in the <graphics/text.h> system include file.<br />
: Defaults to FS_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_TextPlace (uint32)<br />
: Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH. Plus, it only affects button and toggle members.<br />
: Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_LabelArray (STRPTR *)<br />
: Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.<br />
: TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
: Using this tag, the limitation is that you cannot create toggle members (only buttons, separators and spacers).<br />
: A special string, " ", will create a spacer.<br />
: A special string, "_", will create a separator.<br />
: Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.<br />
: The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TOOLBAR_EvenSize (BOOL)<br />
: If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.<br />
: If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ImageSet (uint32)<br />
: If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in the toolbar. The value passed to this tag is the image set ID.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:<br />
<br />
; TOOLBAR_AddImageSet (uint32)<br />
: Creates a new image set. The value passed to this tag is a numeric ID identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to display the particular image set in the toolbar.<br />
: An image set must have a valid ID. The value of TB_NO_ID (~0UL) is not applicable here.<br />
: This tag should be followed by a sequence of TOOLBAR_AddImage tags (see below), each creating one image in the given set.<br />
: If the gadget only uses one set of images, passing TOOLBAR_AddImageSet is not necessary. Each TOOLBAR_AddImage will add the respective image to the default image set identified by an ID of 0.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddImage (uint32)<br />
: Creates a new image in a given image set. The value passed to this tag is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID (see below) to associate the image with a particular toolbar member.<br />
: An image must have a valid ID. The value of TB_NO_ID (~0UL) is not applicable here.<br />
: This tag should be followed by a sequence of TBIMAGE_ tags (see the [[#Image attributes|Image attributes]] section below), each configuring one aspect of the image, including its optional selected variant (referred to as the "select image").<br />
: Images are added to the default image set unless a preceding TOOLBAR_AddImageSet specifies a different set.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddMember (uint32)<br />
: Creates a new toolbar member. The value passed to this tag is a numeric ID identifying the member.<br />
: Spacers and separators normally don't need an ID, so you can use TB_NO_ID as a value for TOOLBAR_AddMember when creating these members. However, if you want to manipulate spacers/separators in your GUI, an ID will be necessary so that you can pass it to TOOLBAR_SetMember to identify the respective spacer or separator member.<br />
: You can add members when the toolbar object is being created, i.e. as part of the NewObject() call, or at any time later via SetAttrs().<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetMember<br />
: Use this tag in a SetAttrs() call to identify the member you want to modify.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetGroup<br />
: Use this tag in a SetAttrs() call to identify the group of members you want to modify collectively.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
=== Member attributes ===<br />
<br />
; TBMEMBER_Type (uint32)<br />
: The type of the toolbar member. The possible values are the following:<br />
<br />
TB_MTYPE_BUTTON -- a normal toolbar button<br />
TB_MTYPE_TOGGLE -- a toggle (on/off) button<br />
TB_MTYPE_SPACER -- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
TB_MTYPE_TEXTBOX -- a read-only box to display text (V53.4)<br />
<br />
: The type is set upon member creation, and cannot be changed.<br />
: Defaults to TB_MTYPE_BUTTON<br />
: Applicability is (OM_NEW)<br />
<br />
; TBMEMBER_ImageID (uint32)<br />
: The identifier of the image to be used for the button or toggle member (see TOOLBAR_AddImage above). This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_ImageID value of such a member.<br />
: When [[#OM_SET|OM_SET]]-ing this attribute, the method will always return TB_NEED_RETHINK, to be on the safe side. However, invoking WM_RETHINK is really only needed if the size of the new image is different from the original image. If the size is the same, a simple gadget refresh will suffice. You can trigger the refresh:<br />
:* by setting this attribute via RefreshSetGadgetAttrs(), or<br />
:* by setting this attribute via SetAttrs() and then invoking the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method on the respective button/toggle member.<br />
: (The difference is that RefreshSetGadgetAttrs() will refresh the entire toolbar, while TBM_REFRESHMEMBER will only refresh the given member.)<br />
: Defaults to TB_NO_ID (no image associated with this member)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Text (CONST_STRPTR)<br />
: The text to associate with a button, toggle or textbox member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
: The text will be used as fallback in case no image is found or provided for a button or a toggle member.<br />
: The text string can contain an underscore character (_), indicating the keyboard shortcut for the member. (This doesn't apply to textbox members, as they are read-only and don't respond to the keyboard.)<br />
: If your toolbar has a textbox member the contents of which is going to change dynamically, updating TBMEMBER_Text should be done like this:<br />
<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Text, "New text",<br />
TAG_END);<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
: Also, you should set TBMEMBER_DomainString for the textbox (see below). This will guarantee a required minimum size to fit any text, so you won't have to perform WM_RETHINK to recalculate the member size each time TBMEMBER_Text changes.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_DomainString (CONST_STRPTR) (V53.4)<br />
: A text string based on which the minimum size of the member will be calculated. This is useful especially with TB_MTYPE_TEXTBOX members when you want to enforce a minimum size required to fit text of variable length. The domain string ought to be at least as long as the longest text to appear in the textbox.<br />
: The domain string is never rendered in the gadget.<br />
: This tag is not relevant to spacers and separators.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_TextAttr (struct TextAttr *) (V53.4)<br />
: Pointer to a TextAttr structure describing the font to be used for the member text. This tag overrides GA_TextAttr (see above).<br />
: Generally, you should use one "global" font for the toolbar, configured via GA_TextAttr. But there are situations where it makes sense to set a particular font at the member level, for example when using textbox members.<br />
: Defaults to NULL.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_TextPen (uint16) (V53.4)<br />
: A pen to be used for the member text. Overrides TOOLBAR_TextPen (see above).<br />
: Generally, you should use one "global" pen for the toolbar, configured via TOOLBAR_TextPen. But there are situations where it makes sense to set a particular pen at the member level, for example when using textbox members.<br />
: Prefer to use pens from the dri_Pens[] array in your screen's DrawInfo structure; see the <intuition/screens.h> system include file.<br />
: Defaults to dri_Pens[TEXTPEN]<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_Disabled (BOOL)<br />
: The current state (disabled or not disabled) of a member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Disabled value of such a member.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Hidden (BOOL)<br />
: Specifies whether the particular member is displayed in the toolbar or hidden. You can use this tag to create "dynamic" toolbar layouts that adapt the actual member set to various application settings.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Selected (BOOL)<br />
: The current selection state of a toggle member. This tag is not relevant to normal buttons (TB_MTYPE_BUTTON), spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Selected value of such a member.<br />
: You can set a target BOOPSI object for any toggle member, using the standard icclass ICA_TARGET tag. The target will receive an automatic notification of the toggle selection. This way toolbar toggles can easily communicate with other boolean gadgets such as checkboxes.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_NOTIFY, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Group (uint32)<br />
: Member group ID. Several members can be manipulated at once if they are assigned to the same group. Use TOOLBAR_SetGroup with the respective group ID to identify the group to be manipulated.<br />
: Defaults to TB_NO_ID (not assigned to any group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_MXGroup (uint32)<br />
: MX group ID. Toggle members can be put in groups of mutually-exclusive buttons. When such a toggle is selected, all other toggles in the same MX group will become deselected.<br />
: This tag is not relevant to normal buttons, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_MXGroup value of such a member.<br />
: Defaults to TB_NO_ID (not assigned to any MX group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_HintInfo (CONST_STRPTR)<br />
: The help text to be displayed when the user hovers the mouse pointer over the respective member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_HintInfo value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_UserData (APTR)<br />
: Arbitrary user data associated with this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
=== Image attributes ===<br />
<br />
; TBIMAGE_Image (struct Image *)<br />
: Custom image to be used for a button or a toggle member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_ImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImage (struct Image *)<br />
: Custom image to display when the member becomes selected.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the select image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
;TBIMAGE_Width (uint32)<br />
;TBIMAGE_Height (uint32)<br />
: Image dimensions, in pixels. These tags can only be used in connection with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the respective source file will be scaled to the specified width and height. Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot be resized using these tags.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW)<br />
<br />
== Notes ==<br />
<br />
Some of the attributes described above change the sizing requirements of the gadget. If set on the fly (i.e. when the toolbar is already displayed in the window), the gadget domain will need recalculating and a re-layout must take place. Refer to the [[#OM_SET|OM_SET]] method documentation below to see how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image. [[#Image attributes|Image attributes]] cannot be changed later.<br />
<br />
== Bugs ==<br />
<br />
== See also ==<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
; NAME<br />
: OM_SET -- set toolbar attributes<br />
<br />
; SYNOPSIS<br />
: uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
: uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win, struct Requester *req, Tag tag1, ...);<br />
<br />
; FUNCTION<br />
: This method sets the attributes of the toolbar and/or of its members. SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions to invoke this method.<br />
: To change a member attribute you first need to pass TOOLBAR_SetMember to identify the respective member, and then the member attribute tag(s). See the EXAMPLE section below.<br />
: To change an attribute collectively for a group of members you first need to pass TOOLBAR_SetGroup to identify the respective group, and then the member attribute tag(s). See the EXAMPLE section below.<br />
<br />
; INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
; RESULT<br />
: This method will return TB_NEED_RETHINK if the gadget ''believes'' that one or more of the attributes will change the sizing requirements of the toolbar. Typically, invoking the WM_RETHINK method on the gadget's window object is needed, in order to recalculate the domain and re-layout the contents.<br />
: If you know you will be changing an attribute that requires a WM_RETHINK, prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
: The method returns 0L if no rethink is needed.<br />
<br />
; EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, groupID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
; NAME<br />
: TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, uint32 attrID, uint32 *storage);<br />
<br />
; FUNCTION<br />
: Use this method to obtain the value of a given member attribute.<br />
: Because of the way OM_GET is implemented in Intuition, getting member attributes is done differently compared to setting them. The difference boils down to the following:<br />
:* We cannot use a convenience function such as GetAttr() or GetAttrs(), so a dedicated method is provided. Refer to the EXAMPLE section below to see how to invoke the method.<br />
:* Only one attribute can be queried at a time. (As multiple attributes will rarely be requested in real use, this limitation should not pose a significant problem.)<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
attrID -- the attribute tag identifier<br />
storage -- a pointer to the variable for storing the attribute value<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the requested attribute value has been obtained successfully. The attribute value itself is returned in the provided storage variable.<br />
<br />
; EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID, TBMEMBER_Selected, &storage);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_REFRESHMEMBER ===<br />
<br />
; NAME<br />
: TBM_REFRESHMEMBER -- refresh the imagery of a given member (V53.3)<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbRefreshMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, struct Window *window);<br />
<br />
; FUNCTION<br />
: Use this method to refresh the imagery of a given button or toggle member.<br />
: The method has no effect on spacers and separators.<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbRefreshMember structure<br />
<br />
For IDoMethod():<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_REFRESHMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
window -- a pointer to the window the toolbar resides in<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the refresh has taken place.<br />
<br />
; EXAMPLE<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1027ToolBar Gadget Class2021-01-08T13:15:14Z<p>Trixie: /* Method attributes */</p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Supported methods ==<br />
<br />
{| class="wikitable"<br />
!Method ID<br />
!Description<br />
|-<br />
|OM_NEW<br />
|creates the toolbar object, sets attributes and defaults<br />
|-<br />
|OM_DISPOSE<br />
|disposes of the toolbar object<br />
|-<br />
|OM_REMMEMBER<br />
|used by the class internally; consider this method private<br />
|-<br />
|OM_SET<br />
|sets toolbar, member and image attributes (see the [[#OM_SET|OM_SET]] section below for more information)<br />
|-<br />
|OM_GET<br />
|retrieves toolbar attributes<br />
|-<br />
|TBM_GETMEMBER<br />
|retrieves a given member attribute (see the [[#TBM_GETMEMBER|TBM_GETMEMBER]] section below for more information)<br />
|-<br />
|TBM_REFRESHMEMBER<br />
|refreshes the imagery of a given member (see the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] section below for more information)<br />
|}<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
; GA_ID (uint16)<br />
: Unique ID number for the gadget.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_ReadOnly (BOOL)<br />
: If set to TRUE, none of the toolbar buttons will be selectable.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_BackFill (struct Hook *)<br />
: A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
: Defaults to NULL (the default backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; GA_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the toolbar members' text.<br />
: Generally, you should use one font for the toolbar, set through this tag. However, you can override the global font and set a different one for individual members if needed; see TBMEMBER_TextAttr below.<br />
: Defaults to NULL (will use the system's default public screen font).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Orientation (uint32)<br />
: The toolbar orientation: horizontal or vertical.<br />
: Defaults to TB_ORIENT_HORIZ<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_Spacing (uint32)<br />
: The spacing between the individual toolbar members, in pixels.<br />
: Defaults to 2<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HorizPadding<br />
; TOOLBAR_VertPadding (uint32)<br />
: The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_InnerPadding (uint32)<br />
: The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.<br />
: Defaults to 4<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HandleOverflow (BOOL)<br />
: Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_MinVisible (uint32)<br />
: If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
: Defaults to 1<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SpacerSize (uint32)<br />
: The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.<br />
: Defaults to 5<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ButtonStyle (uint32)<br />
: The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
: Defaults to TB_BUTSTYLE_CLASSIC<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BevelStyle (uint32)<br />
: The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:<br />
<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
: When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.<br />
: Defaults to BVS_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SeparatorStyle (uint32)<br />
: Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.<br />
: Defaults to TB_SEPSTYLE_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SelectionStyle (uint32)<br />
: Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.<br />
: This tag is ignored in the classic mode with framed buttons.<br />
: Defaults to TB_SELSTYLE_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BackFill (struct Hook *)<br />
: A custom backfill hook to provide a background filled with a specific colour or pattern.<br />
: This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.<br />
: Defaults to NULL (the default layers backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Display (uint32)<br />
: Specifies what you want to display inside the toolbar button or toggle members. The possible values are:<br />
<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
: Defaults to TB_DISPLAY_IMAGES<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_TextPen (uint16) (V53.4)<br />
: A pen to be used for the toolbar members' text.<br />
: Generally, you should use one text pen for the toolbar, set through this tag. However, you can override the global pen and set a different one for individual members if needed; see TBMEMBER_TextPen below.<br />
: Prefer to use pens from the dri_Pens[] array in your screen's DrawInfo structure; see the <intuition/screens.h> system include file.<br />
: Defaults to dri_Pens[TEXTPEN]<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_TextPlace (uint32)<br />
: Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH. Plus, it only affects button and toggle members.<br />
: Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_LabelArray (STRPTR *)<br />
: Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.<br />
: TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
: Using this tag, the limitation is that you cannot create toggle members (only buttons, separators and spacers).<br />
: A special string, " ", will create a spacer.<br />
: A special string, "_", will create a separator.<br />
: Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.<br />
: The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TOOLBAR_EvenSize (BOOL)<br />
: If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.<br />
: If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ImageSet (uint32)<br />
: If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in the toolbar. The value passed to this tag is the image set ID.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:<br />
<br />
; TOOLBAR_AddImageSet (uint32)<br />
: Creates a new image set. The value passed to this tag is a numeric ID identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to display the particular image set in the toolbar.<br />
: An image set must have a valid ID. The value of TB_NO_ID (~0UL) is not applicable here.<br />
: This tag should be followed by a sequence of TOOLBAR_AddImage tags (see below), each creating one image in the given set.<br />
: If the gadget only uses one set of images, passing TOOLBAR_AddImageSet is not necessary. Each TOOLBAR_AddImage will add the respective image to the default image set identified by an ID of 0.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddImage (uint32)<br />
: Creates a new image in a given image set. The value passed to this tag is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID (see below) to associate the image with a particular toolbar member.<br />
: An image must have a valid ID. The value of TB_NO_ID (~0UL) is not applicable here.<br />
: This tag should be followed by a sequence of TBIMAGE_ tags (see the [[#Image attributes|Image attributes]] section below), each configuring one aspect of the image, including its optional selected variant (referred to as the "select image").<br />
: Images are added to the default image set unless a preceding TOOLBAR_AddImageSet specifies a different set.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddMember (uint32)<br />
: Creates a new toolbar member. The value passed to this tag is a numeric ID identifying the member.<br />
: Spacers and separators normally don't need an ID, so you can use TB_NO_ID as a value for TOOLBAR_AddMember when creating these members. However, if you want to manipulate spacers/separators in your GUI, an ID will be necessary so that you can pass it to TOOLBAR_SetMember to identify the respective spacer or separator member.<br />
: You can add members when the toolbar object is being created, i.e. as part of the NewObject() call, or at any time later via SetAttrs().<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetMember<br />
: Use this tag in a SetAttrs() call to identify the member you want to modify.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetGroup<br />
: Use this tag in a SetAttrs() call to identify the group of members you want to modify collectively.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
=== Member attributes ===<br />
<br />
; TBMEMBER_Type (uint32)<br />
: The type of the toolbar member. The possible values are the following:<br />
<br />
TB_MTYPE_BUTTON -- a normal toolbar button<br />
TB_MTYPE_TOGGLE -- a toggle (on/off) button<br />
TB_MTYPE_SPACER -- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
TB_MTYPE_TEXTBOX -- a read-only box to display text (V53.4)<br />
<br />
: The type is set upon member creation, and cannot be changed.<br />
: Defaults to TB_MTYPE_BUTTON<br />
: Applicability is (OM_NEW)<br />
<br />
; TBMEMBER_ImageID (uint32)<br />
: The identifier of the image to be used for the button or toggle member (see TOOLBAR_AddImage above). This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_ImageID value of such a member.<br />
: When [[#OM_SET|OM_SET]]-ing this attribute, the method will always return TB_NEED_RETHINK, to be on the safe side. However, invoking WM_RETHINK is really only needed if the size of the new image is different from the original image. If the size is the same, a simple gadget refresh will suffice. You can trigger the refresh:<br />
:* by setting this attribute via RefreshSetGadgetAttrs(), or<br />
:* by setting this attribute via SetAttrs() and then invoking the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method on the respective button/toggle member.<br />
: (The difference is that RefreshSetGadgetAttrs() will refresh the entire toolbar, while TBM_REFRESHMEMBER will only refresh the given member.)<br />
: Defaults to TB_NO_ID (no image associated with this member)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Text (CONST_STRPTR)<br />
: The text to associate with a button, toggle or textbox member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
: The text will be used as fallback in case no image is found or provided for a button or a toggle member.<br />
: The text string can contain an underscore character (_), indicating the keyboard shortcut for the member. (This doesn't apply to textbox members, as they are read-only and don't respond to the keyboard.)<br />
: If your toolbar has a textbox member the contents of which is going to change dynamically, updating TBMEMBER_Text should be done like this:<br />
<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Text, "New text",<br />
TAG_END);<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
: Also, you should set TBMEMBER_DomainString for the textbox (see below). This will guarantee a required minimum size to fit any text, so you won't have to perform WM_RETHINK to recalculate the member size each time TBMEMBER_Text changes.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_DomainString (CONST_STRPTR) (V53.4)<br />
: A text string based on which the minimum size of the member will be calculated. This is useful especially with TB_MTYPE_TEXTBOX members when you want to enforce a minimum size required to fit text of variable length. The domain string ought to be at least as long as the longest text to appear in the textbox.<br />
: The domain string is never rendered in the gadget.<br />
: This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_DomainString value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_TextAttr (struct TextAttr *) (V53.4)<br />
: Pointer to a TextAttr structure describing the font to be used for the member text. This tag overrides GA_TextAttr (see above).<br />
: Generally, you should use one "global" font for the toolbar, configured via GA_TextAttr. But there are situations where it makes sense to set a particular font at the member level, for example when using textbox members.<br />
: Defaults to NULL.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_TextPen (uint16) (V53.4)<br />
: A pen to be used for the member text. Overrides TOOLBAR_TextPen (see above).<br />
: Generally, you should use one "global" pen for the toolbar, configured via TOOLBAR_TextPen. But there are situations where it makes sense to set a particular pen at the member level, for example when using textbox members.<br />
: Prefer to use pens from the dri_Pens[] array in your screen's DrawInfo structure; see the <intuition/screens.h> system include file.<br />
: Defaults to dri_Pens[TEXTPEN]<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_Disabled (BOOL)<br />
: The current state (disabled or not disabled) of a member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Disabled value of such a member.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Hidden (BOOL)<br />
: Specifies whether the particular member is displayed in the toolbar or hidden. You can use this tag to create "dynamic" toolbar layouts that adapt the actual member set to various application settings.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Selected (BOOL)<br />
: The current selection state of a toggle member. This tag is not relevant to normal buttons (TB_MTYPE_BUTTON), spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Selected value of such a member.<br />
: You can set a target BOOPSI object for any toggle member, using the standard icclass ICA_TARGET tag. The target will receive an automatic notification of the toggle selection. This way toolbar toggles can easily communicate with other boolean gadgets such as checkboxes.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_NOTIFY, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Group (uint32)<br />
: Member group ID. Several members can be manipulated at once if they are assigned to the same group. Use TOOLBAR_SetGroup with the respective group ID to identify the group to be manipulated.<br />
: Defaults to TB_NO_ID (not assigned to any group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_MXGroup (uint32)<br />
: MX group ID. Toggle members can be put in groups of mutually-exclusive buttons. When such a toggle is selected, all other toggles in the same MX group will become deselected.<br />
: This tag is not relevant to normal buttons, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_MXGroup value of such a member.<br />
: Defaults to TB_NO_ID (not assigned to any MX group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_HintInfo (CONST_STRPTR)<br />
: The help text to be displayed when the user hovers the mouse pointer over the respective member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_HintInfo value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_UserData (APTR)<br />
: Arbitrary user data associated with this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
=== Image attributes ===<br />
<br />
; TBIMAGE_Image (struct Image *)<br />
: Custom image to be used for a button or a toggle member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_ImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImage (struct Image *)<br />
: Custom image to display when the member becomes selected.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the select image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
;TBIMAGE_Width (uint32)<br />
;TBIMAGE_Height (uint32)<br />
: Image dimensions, in pixels. These tags can only be used in connection with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the respective source file will be scaled to the specified width and height. Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot be resized using these tags.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW)<br />
<br />
== Notes ==<br />
<br />
Some of the attributes described above change the sizing requirements of the gadget. If set on the fly (i.e. when the toolbar is already displayed in the window), the gadget domain will need recalculating and a re-layout must take place. Refer to the [[#OM_SET|OM_SET]] method documentation below to see how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image. [[#Image attributes|Image attributes]] cannot be changed later.<br />
<br />
== Bugs ==<br />
<br />
== See also ==<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
; NAME<br />
: OM_SET -- set toolbar attributes<br />
<br />
; SYNOPSIS<br />
: uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
: uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win, struct Requester *req, Tag tag1, ...);<br />
<br />
; FUNCTION<br />
: This method sets the attributes of the toolbar and/or of its members. SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions to invoke this method.<br />
: To change a member attribute you first need to pass TOOLBAR_SetMember to identify the respective member, and then the member attribute tag(s). See the EXAMPLE section below.<br />
: To change an attribute collectively for a group of members you first need to pass TOOLBAR_SetGroup to identify the respective group, and then the member attribute tag(s). See the EXAMPLE section below.<br />
<br />
; INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
; RESULT<br />
: This method will return TB_NEED_RETHINK if the gadget ''believes'' that one or more of the attributes will change the sizing requirements of the toolbar. Typically, invoking the WM_RETHINK method on the gadget's window object is needed, in order to recalculate the domain and re-layout the contents.<br />
: If you know you will be changing an attribute that requires a WM_RETHINK, prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
: The method returns 0L if no rethink is needed.<br />
<br />
; EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, groupID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
; NAME<br />
: TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, uint32 attrID, uint32 *storage);<br />
<br />
; FUNCTION<br />
: Use this method to obtain the value of a given member attribute.<br />
: Because of the way OM_GET is implemented in Intuition, getting member attributes is done differently compared to setting them. The difference boils down to the following:<br />
:* We cannot use a convenience function such as GetAttr() or GetAttrs(), so a dedicated method is provided. Refer to the EXAMPLE section below to see how to invoke the method.<br />
:* Only one attribute can be queried at a time. (As multiple attributes will rarely be requested in real use, this limitation should not pose a significant problem.)<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
attrID -- the attribute tag identifier<br />
storage -- a pointer to the variable for storing the attribute value<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the requested attribute value has been obtained successfully. The attribute value itself is returned in the provided storage variable.<br />
<br />
; EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID, TBMEMBER_Selected, &storage);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_REFRESHMEMBER ===<br />
<br />
; NAME<br />
: TBM_REFRESHMEMBER -- refresh the imagery of a given member (V53.3)<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbRefreshMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, struct Window *window);<br />
<br />
; FUNCTION<br />
: Use this method to refresh the imagery of a given button or toggle member.<br />
: The method has no effect on spacers and separators.<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbRefreshMember structure<br />
<br />
For IDoMethod():<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_REFRESHMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
window -- a pointer to the window the toolbar resides in<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the refresh has taken place.<br />
<br />
; EXAMPLE<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1026ToolBar Gadget Class2021-01-05T22:19:34Z<p>Trixie: /* Member attributes */</p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Supported methods ==<br />
<br />
{| class="wikitable"<br />
!Method ID<br />
!Description<br />
|-<br />
|OM_NEW<br />
|creates the toolbar object, sets attributes and defaults<br />
|-<br />
|OM_DISPOSE<br />
|disposes of the toolbar object<br />
|-<br />
|OM_REMMEMBER<br />
|used by the class internally; consider this method private<br />
|-<br />
|OM_SET<br />
|sets toolbar, member and image attributes (see the [[#OM_SET|OM_SET]] section below for more information)<br />
|-<br />
|OM_GET<br />
|retrieves toolbar attributes<br />
|-<br />
|TBM_GETMEMBER<br />
|retrieves a given member attribute (see the [[#TBM_GETMEMBER|TBM_GETMEMBER]] section below for more information)<br />
|-<br />
|TBM_REFRESHMEMBER<br />
|refreshes the imagery of a given member (see the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] section below for more information)<br />
|}<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
; GA_ID (uint16)<br />
: Unique ID number for the gadget.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_ReadOnly (BOOL)<br />
: If set to TRUE, none of the toolbar buttons will be selectable.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_BackFill (struct Hook *)<br />
: A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
: Defaults to NULL (the default backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; GA_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the toolbar members' text.<br />
: Generally, you should use one font for the toolbar, set through this tag. However, you can override the global font and set a different one for individual members if needed; see TBMEMBER_TextAttr below.<br />
: Defaults to NULL (will use the system's default public screen font).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Orientation (uint32)<br />
: The toolbar orientation: horizontal or vertical.<br />
: Defaults to TB_ORIENT_HORIZ<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_Spacing (uint32)<br />
: The spacing between the individual toolbar members, in pixels.<br />
: Defaults to 2<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HorizPadding<br />
; TOOLBAR_VertPadding (uint32)<br />
: The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_InnerPadding (uint32)<br />
: The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.<br />
: Defaults to 4<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HandleOverflow (BOOL)<br />
: Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_MinVisible (uint32)<br />
: If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
: Defaults to 1<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SpacerSize (uint32)<br />
: The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.<br />
: Defaults to 5<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ButtonStyle (uint32)<br />
: The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
: Defaults to TB_BUTSTYLE_CLASSIC<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BevelStyle (uint32)<br />
: The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:<br />
<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
: When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.<br />
: Defaults to BVS_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SeparatorStyle (uint32)<br />
: Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.<br />
: Defaults to TB_SEPSTYLE_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SelectionStyle (uint32)<br />
: Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.<br />
: This tag is ignored in the classic mode with framed buttons.<br />
: Defaults to TB_SELSTYLE_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BackFill (struct Hook *)<br />
: A custom backfill hook to provide a background filled with a specific colour or pattern.<br />
: This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.<br />
: Defaults to NULL (the default layers backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Display (uint32)<br />
: Specifies what you want to display inside the toolbar button or toggle members. The possible values are:<br />
<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
: Defaults to TB_DISPLAY_IMAGES<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_TextPen (uint16) (V53.4)<br />
: A pen to be used for the toolbar members' text.<br />
: Generally, you should use one text pen for the toolbar, set through this tag. However, you can override the global pen and set a different one for individual members if needed; see TBMEMBER_TextPen below.<br />
: Prefer to use pens from the dri_Pens[] array in your screen's DrawInfo structure; see the <intuition/screens.h> system include file.<br />
: Defaults to dri_Pens[TEXTPEN]<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_TextPlace (uint32)<br />
: Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH. Plus, it only affects button and toggle members.<br />
: Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_LabelArray (STRPTR *)<br />
: Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.<br />
: TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
: Using this tag, the limitation is that you cannot create toggle members (only buttons, separators and spacers).<br />
: A special string, " ", will create a spacer.<br />
: A special string, "_", will create a separator.<br />
: Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.<br />
: The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TOOLBAR_EvenSize (BOOL)<br />
: If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.<br />
: If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ImageSet (uint32)<br />
: If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in the toolbar. The value passed to this tag is the image set ID.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:<br />
<br />
; TOOLBAR_AddImageSet (uint32)<br />
: Creates a new image set. The value passed to this tag is a numeric ID identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to display the particular image set in the toolbar.<br />
: This tag should be followed by a sequence of TOOLBAR_AddImage tags (see below), each creating one image in the given set.<br />
: If the gadget only uses one set of images, passing TOOLBAR_AddImageSet is not necessary. Each TOOLBAR_AddImage will add the respective image to the default image set identified by an ID of 0.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddImage (uint32)<br />
: Creates a new image in a given image set. The value passed to this tag is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID (see below) to associate the image with a particular toolbar member.<br />
: This tag should be followed by a sequence of TBIMAGE_ tags (see the [[#Image attributes|Image attributes]] section below), each configuring one aspect of the image, including its optional selected variant (referred to as the "select image").<br />
: Images are added to the default image set unless a preceding TOOLBAR_AddImageSet specifies a different set.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddMember (uint32)<br />
: Creates a new toolbar member. The value passed to this tag is a numeric ID identifying the member.<br />
: Spacers and separators normally don't need an ID, so you can use TB_NO_ID as a value for TOOLBAR_AddMember when creating these members. However, if you want to manipulate spacers/separators in your GUI, an ID will be necessary so that you can pass it to TOOLBAR_SetMember to identify the respective spacer or separator member.<br />
: You can add members when the toolbar object is being created, i.e. as part of the NewObject() call, or at any time later via SetAttrs().<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetMember<br />
: Use this tag in a SetAttrs() call to identify the member you want to modify.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetGroup<br />
: Use this tag in a SetAttrs() call to identify the group of members you want to modify collectively.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
=== Member attributes ===<br />
<br />
; TBMEMBER_Type (uint32)<br />
: The type of the toolbar member. The possible values are the following:<br />
<br />
TB_MTYPE_BUTTON -- a normal toolbar button<br />
TB_MTYPE_TOGGLE -- a toggle (on/off) button<br />
TB_MTYPE_SPACER -- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
TB_MTYPE_TEXTBOX -- a read-only box to display text (V53.4)<br />
<br />
: The type is set upon member creation, and cannot be changed.<br />
: Defaults to TB_MTYPE_BUTTON<br />
: Applicability is (OM_NEW)<br />
<br />
; TBMEMBER_ImageID (uint32)<br />
: The identifier of the image to be used for the button or toggle member (see TOOLBAR_AddImage above). This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_ImageID value of such a member.<br />
: When [[#OM_SET|OM_SET]]-ing this attribute, the method will always return TB_NEED_RETHINK, to be on the safe side. However, invoking WM_RETHINK is really only needed if the size of the new image is different from the original image. If the size is the same, a simple gadget refresh will suffice. You can trigger the refresh:<br />
:* by setting this attribute via RefreshSetGadgetAttrs(), or<br />
:* by setting this attribute via SetAttrs() and then invoking the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method on the respective button/toggle member.<br />
: (The difference is that RefreshSetGadgetAttrs() will refresh the entire toolbar, while TBM_REFRESHMEMBER will only refresh the given member.)<br />
: Defaults to TB_NO_ID (no image associated with this member)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Text (CONST_STRPTR)<br />
: The text to associate with a button, toggle or textbox member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
: The text will be used as fallback in case no image is found or provided for a button or a toggle member.<br />
: The text string can contain an underscore character (_), indicating the keyboard shortcut for the member. (This doesn't apply to textbox members, as they are read-only and don't respond to the keyboard.)<br />
: If your toolbar has a textbox member the contents of which is going to change dynamically, updating TBMEMBER_Text should be done like this:<br />
<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Text, "New text",<br />
TAG_END);<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
: Also, you should set TBMEMBER_DomainString for the textbox (see below). This will guarantee a required minimum size to fit any text, so you won't have to perform WM_RETHINK to recalculate the member size each time TBMEMBER_Text changes.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_DomainString (CONST_STRPTR) (V53.4)<br />
: A text string based on which the minimum size of the member will be calculated. This is useful especially with TB_MTYPE_TEXTBOX members when you want to enforce a minimum size required to fit text of variable length. The domain string ought to be at least as long as the longest text to appear in the textbox.<br />
: The domain string is never rendered in the gadget.<br />
: This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_DomainString value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_TextAttr (struct TextAttr *) (V53.4)<br />
: Pointer to a TextAttr structure describing the font to be used for the member text. This tag overrides GA_TextAttr (see above).<br />
: Generally, you should use one "global" font for the toolbar, configured via GA_TextAttr. But there are situations where it makes sense to set a particular font at the member level, for example when using textbox members.<br />
: Defaults to NULL.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_TextPen (uint16) (V53.4)<br />
: A pen to be used for the member text. Overrides TOOLBAR_TextPen (see above).<br />
: Generally, you should use one "global" pen for the toolbar, configured via TOOLBAR_TextPen. But there are situations where it makes sense to set a particular pen at the member level, for example when using textbox members.<br />
: Prefer to use pens from the dri_Pens[] array in your screen's DrawInfo structure; see the <intuition/screens.h> system include file.<br />
: Defaults to dri_Pens[TEXTPEN]<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_Disabled (BOOL)<br />
: The current state (disabled or not disabled) of a member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Disabled value of such a member.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Hidden (BOOL)<br />
: Specifies whether the particular member is displayed in the toolbar or hidden. You can use this tag to create "dynamic" toolbar layouts that adapt the actual member set to various application settings.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Selected (BOOL)<br />
: The current selection state of a toggle member. This tag is not relevant to normal buttons (TB_MTYPE_BUTTON), spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Selected value of such a member.<br />
: You can set a target BOOPSI object for any toggle member, using the standard icclass ICA_TARGET tag. The target will receive an automatic notification of the toggle selection. This way toolbar toggles can easily communicate with other boolean gadgets such as checkboxes.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_NOTIFY, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Group (uint32)<br />
: Member group ID. Several members can be manipulated at once if they are assigned to the same group. Use TOOLBAR_SetGroup with the respective group ID to identify the group to be manipulated.<br />
: Defaults to TB_NO_ID (not assigned to any group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_MXGroup (uint32)<br />
: MX group ID. Toggle members can be put in groups of mutually-exclusive buttons. When such a toggle is selected, all other toggles in the same MX group will become deselected.<br />
: This tag is not relevant to normal buttons, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_MXGroup value of such a member.<br />
: Defaults to TB_NO_ID (not assigned to any MX group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_HintInfo (CONST_STRPTR)<br />
: The help text to be displayed when the user hovers the mouse pointer over the respective member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_HintInfo value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_UserData (APTR)<br />
: Arbitrary user data associated with this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
=== Image attributes ===<br />
<br />
; TBIMAGE_Image (struct Image *)<br />
: Custom image to be used for a button or a toggle member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_ImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImage (struct Image *)<br />
: Custom image to display when the member becomes selected.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the select image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
;TBIMAGE_Width (uint32)<br />
;TBIMAGE_Height (uint32)<br />
: Image dimensions, in pixels. These tags can only be used in connection with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the respective source file will be scaled to the specified width and height. Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot be resized using these tags.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW)<br />
<br />
== Notes ==<br />
<br />
Some of the attributes described above change the sizing requirements of the gadget. If set on the fly (i.e. when the toolbar is already displayed in the window), the gadget domain will need recalculating and a re-layout must take place. Refer to the [[#OM_SET|OM_SET]] method documentation below to see how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image. [[#Image attributes|Image attributes]] cannot be changed later.<br />
<br />
== Bugs ==<br />
<br />
== See also ==<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
; NAME<br />
: OM_SET -- set toolbar attributes<br />
<br />
; SYNOPSIS<br />
: uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
: uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win, struct Requester *req, Tag tag1, ...);<br />
<br />
; FUNCTION<br />
: This method sets the attributes of the toolbar and/or of its members. SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions to invoke this method.<br />
: To change a member attribute you first need to pass TOOLBAR_SetMember to identify the respective member, and then the member attribute tag(s). See the EXAMPLE section below.<br />
: To change an attribute collectively for a group of members you first need to pass TOOLBAR_SetGroup to identify the respective group, and then the member attribute tag(s). See the EXAMPLE section below.<br />
<br />
; INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
; RESULT<br />
: This method will return TB_NEED_RETHINK if the gadget ''believes'' that one or more of the attributes will change the sizing requirements of the toolbar. Typically, invoking the WM_RETHINK method on the gadget's window object is needed, in order to recalculate the domain and re-layout the contents.<br />
: If you know you will be changing an attribute that requires a WM_RETHINK, prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
: The method returns 0L if no rethink is needed.<br />
<br />
; EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, groupID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
; NAME<br />
: TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, uint32 attrID, uint32 *storage);<br />
<br />
; FUNCTION<br />
: Use this method to obtain the value of a given member attribute.<br />
: Because of the way OM_GET is implemented in Intuition, getting member attributes is done differently compared to setting them. The difference boils down to the following:<br />
:* We cannot use a convenience function such as GetAttr() or GetAttrs(), so a dedicated method is provided. Refer to the EXAMPLE section below to see how to invoke the method.<br />
:* Only one attribute can be queried at a time. (As multiple attributes will rarely be requested in real use, this limitation should not pose a significant problem.)<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
attrID -- the attribute tag identifier<br />
storage -- a pointer to the variable for storing the attribute value<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the requested attribute value has been obtained successfully. The attribute value itself is returned in the provided storage variable.<br />
<br />
; EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID, TBMEMBER_Selected, &storage);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_REFRESHMEMBER ===<br />
<br />
; NAME<br />
: TBM_REFRESHMEMBER -- refresh the imagery of a given member (V53.3)<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbRefreshMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, struct Window *window);<br />
<br />
; FUNCTION<br />
: Use this method to refresh the imagery of a given button or toggle member.<br />
: The method has no effect on spacers and separators.<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbRefreshMember structure<br />
<br />
For IDoMethod():<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_REFRESHMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
window -- a pointer to the window the toolbar resides in<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the refresh has taken place.<br />
<br />
; EXAMPLE<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1025ToolBar Gadget Class2021-01-05T22:18:00Z<p>Trixie: Updated GA_TextAttr, TOOLBAR_TextPen and TBMEMBER_TextAttr. Added TBMEMBER_TextPen.</p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Supported methods ==<br />
<br />
{| class="wikitable"<br />
!Method ID<br />
!Description<br />
|-<br />
|OM_NEW<br />
|creates the toolbar object, sets attributes and defaults<br />
|-<br />
|OM_DISPOSE<br />
|disposes of the toolbar object<br />
|-<br />
|OM_REMMEMBER<br />
|used by the class internally; consider this method private<br />
|-<br />
|OM_SET<br />
|sets toolbar, member and image attributes (see the [[#OM_SET|OM_SET]] section below for more information)<br />
|-<br />
|OM_GET<br />
|retrieves toolbar attributes<br />
|-<br />
|TBM_GETMEMBER<br />
|retrieves a given member attribute (see the [[#TBM_GETMEMBER|TBM_GETMEMBER]] section below for more information)<br />
|-<br />
|TBM_REFRESHMEMBER<br />
|refreshes the imagery of a given member (see the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] section below for more information)<br />
|}<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
; GA_ID (uint16)<br />
: Unique ID number for the gadget.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_ReadOnly (BOOL)<br />
: If set to TRUE, none of the toolbar buttons will be selectable.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_BackFill (struct Hook *)<br />
: A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
: Defaults to NULL (the default backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; GA_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the toolbar members' text.<br />
: Generally, you should use one font for the toolbar, set through this tag. However, you can override the global font and set a different one for individual members if needed; see TBMEMBER_TextAttr below.<br />
: Defaults to NULL (will use the system's default public screen font).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Orientation (uint32)<br />
: The toolbar orientation: horizontal or vertical.<br />
: Defaults to TB_ORIENT_HORIZ<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_Spacing (uint32)<br />
: The spacing between the individual toolbar members, in pixels.<br />
: Defaults to 2<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HorizPadding<br />
; TOOLBAR_VertPadding (uint32)<br />
: The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_InnerPadding (uint32)<br />
: The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.<br />
: Defaults to 4<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HandleOverflow (BOOL)<br />
: Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_MinVisible (uint32)<br />
: If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
: Defaults to 1<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SpacerSize (uint32)<br />
: The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.<br />
: Defaults to 5<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ButtonStyle (uint32)<br />
: The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
: Defaults to TB_BUTSTYLE_CLASSIC<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BevelStyle (uint32)<br />
: The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:<br />
<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
: When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.<br />
: Defaults to BVS_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SeparatorStyle (uint32)<br />
: Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.<br />
: Defaults to TB_SEPSTYLE_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SelectionStyle (uint32)<br />
: Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.<br />
: This tag is ignored in the classic mode with framed buttons.<br />
: Defaults to TB_SELSTYLE_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BackFill (struct Hook *)<br />
: A custom backfill hook to provide a background filled with a specific colour or pattern.<br />
: This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.<br />
: Defaults to NULL (the default layers backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Display (uint32)<br />
: Specifies what you want to display inside the toolbar button or toggle members. The possible values are:<br />
<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
: Defaults to TB_DISPLAY_IMAGES<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_TextPen (uint16) (V53.4)<br />
: A pen to be used for the toolbar members' text.<br />
: Generally, you should use one text pen for the toolbar, set through this tag. However, you can override the global pen and set a different one for individual members if needed; see TBMEMBER_TextPen below.<br />
: Prefer to use pens from the dri_Pens[] array in your screen's DrawInfo structure; see the <intuition/screens.h> system include file.<br />
: Defaults to dri_Pens[TEXTPEN]<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_TextPlace (uint32)<br />
: Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH. Plus, it only affects button and toggle members.<br />
: Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_LabelArray (STRPTR *)<br />
: Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.<br />
: TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
: Using this tag, the limitation is that you cannot create toggle members (only buttons, separators and spacers).<br />
: A special string, " ", will create a spacer.<br />
: A special string, "_", will create a separator.<br />
: Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.<br />
: The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TOOLBAR_EvenSize (BOOL)<br />
: If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.<br />
: If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ImageSet (uint32)<br />
: If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in the toolbar. The value passed to this tag is the image set ID.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:<br />
<br />
; TOOLBAR_AddImageSet (uint32)<br />
: Creates a new image set. The value passed to this tag is a numeric ID identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to display the particular image set in the toolbar.<br />
: This tag should be followed by a sequence of TOOLBAR_AddImage tags (see below), each creating one image in the given set.<br />
: If the gadget only uses one set of images, passing TOOLBAR_AddImageSet is not necessary. Each TOOLBAR_AddImage will add the respective image to the default image set identified by an ID of 0.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddImage (uint32)<br />
: Creates a new image in a given image set. The value passed to this tag is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID (see below) to associate the image with a particular toolbar member.<br />
: This tag should be followed by a sequence of TBIMAGE_ tags (see the [[#Image attributes|Image attributes]] section below), each configuring one aspect of the image, including its optional selected variant (referred to as the "select image").<br />
: Images are added to the default image set unless a preceding TOOLBAR_AddImageSet specifies a different set.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddMember (uint32)<br />
: Creates a new toolbar member. The value passed to this tag is a numeric ID identifying the member.<br />
: Spacers and separators normally don't need an ID, so you can use TB_NO_ID as a value for TOOLBAR_AddMember when creating these members. However, if you want to manipulate spacers/separators in your GUI, an ID will be necessary so that you can pass it to TOOLBAR_SetMember to identify the respective spacer or separator member.<br />
: You can add members when the toolbar object is being created, i.e. as part of the NewObject() call, or at any time later via SetAttrs().<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetMember<br />
: Use this tag in a SetAttrs() call to identify the member you want to modify.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetGroup<br />
: Use this tag in a SetAttrs() call to identify the group of members you want to modify collectively.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
=== Member attributes ===<br />
<br />
; TBMEMBER_Type (uint32)<br />
: The type of the toolbar member. The possible values are the following:<br />
<br />
TB_MTYPE_BUTTON -- a normal toolbar button<br />
TB_MTYPE_TOGGLE -- a toggle (on/off) button<br />
TB_MTYPE_SPACER -- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
TB_MTYPE_TEXTBOX -- a read-only box to display text (V53.4)<br />
<br />
: The type is set upon member creation, and cannot be changed.<br />
: Defaults to TB_MTYPE_BUTTON<br />
: Applicability is (OM_NEW)<br />
<br />
; TBMEMBER_ImageID (uint32)<br />
: The identifier of the image to be used for the button or toggle member (see TOOLBAR_AddImage above). This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_ImageID value of such a member.<br />
: When [[#OM_SET|OM_SET]]-ing this attribute, the method will always return TB_NEED_RETHINK, to be on the safe side. However, invoking WM_RETHINK is really only needed if the size of the new image is different from the original image. If the size is the same, a simple gadget refresh will suffice. You can trigger the refresh:<br />
:* by setting this attribute via RefreshSetGadgetAttrs(), or<br />
:* by setting this attribute via SetAttrs() and then invoking the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method on the respective button/toggle member.<br />
: (The difference is that RefreshSetGadgetAttrs() will refresh the entire toolbar, while TBM_REFRESHMEMBER will only refresh the given member.)<br />
: Defaults to TB_NO_ID (no image associated with this member)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Text (CONST_STRPTR)<br />
: The text to associate with a button, toggle or textbox member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
: The text will be used as fallback in case no image is found or provided for a button or a toggle member.<br />
: The text string can contain an underscore character (_), indicating the keyboard shortcut for the member. (This doesn't apply to textbox members, as they are read-only and don't respond to the keyboard.)<br />
: If your toolbar has a textbox member the contents of which is going to change dynamically, updating TBMEMBER_Text should be done like this:<br />
<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Text, "New text",<br />
TAG_END);<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
: Also, you should set TBMEMBER_DomainString for the textbox (see below). This will guarantee a required minimum size to fit any text, so you won't have to perform WM_RETHINK to recalculate the member size each time TBMEMBER_Text changes.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_DomainString (CONST_STRPTR)<br />
: A text string based on which the minimum size of the member will be calculated. This is useful especially with TB_MTYPE_TEXTBOX members when you want to enforce a minimum size required to fit text of variable length. The domain string ought to be at least as long as the longest text to appear in the textbox.<br />
: The domain string is never rendered in the gadget.<br />
: This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_DomainString value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_TextAttr (struct TextAttr *) (V53.4)<br />
: Pointer to a TextAttr structure describing the font to be used for the member text. This tag overrides GA_TextAttr (see above).<br />
: Generally, you should use one "global" font for the toolbar, configured via GA_TextAttr. But there are situations where it makes sense to set a particular font at the member level, for example when using textbox members.<br />
: Defaults to NULL.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_TextPen (uint16) (V53.4)<br />
: A pen to be used for the member text. Overrides TOOLBAR_TextPen (see above).<br />
: Generally, you should use one "global" pen for the toolbar, configured via TOOLBAR_TextPen. But there are situations where it makes sense to set a particular pen at the member level, for example when using textbox members.<br />
: Prefer to use pens from the dri_Pens[] array in your screen's DrawInfo structure; see the <intuition/screens.h> system include file.<br />
: Defaults to dri_Pens[TEXTPEN]<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_Disabled (BOOL)<br />
: The current state (disabled or not disabled) of a member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Disabled value of such a member.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Hidden (BOOL)<br />
: Specifies whether the particular member is displayed in the toolbar or hidden. You can use this tag to create "dynamic" toolbar layouts that adapt the actual member set to various application settings.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Selected (BOOL)<br />
: The current selection state of a toggle member. This tag is not relevant to normal buttons (TB_MTYPE_BUTTON), spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Selected value of such a member.<br />
: You can set a target BOOPSI object for any toggle member, using the standard icclass ICA_TARGET tag. The target will receive an automatic notification of the toggle selection. This way toolbar toggles can easily communicate with other boolean gadgets such as checkboxes.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_NOTIFY, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Group (uint32)<br />
: Member group ID. Several members can be manipulated at once if they are assigned to the same group. Use TOOLBAR_SetGroup with the respective group ID to identify the group to be manipulated.<br />
: Defaults to TB_NO_ID (not assigned to any group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_MXGroup (uint32)<br />
: MX group ID. Toggle members can be put in groups of mutually-exclusive buttons. When such a toggle is selected, all other toggles in the same MX group will become deselected.<br />
: This tag is not relevant to normal buttons, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_MXGroup value of such a member.<br />
: Defaults to TB_NO_ID (not assigned to any MX group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_HintInfo (CONST_STRPTR)<br />
: The help text to be displayed when the user hovers the mouse pointer over the respective member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_HintInfo value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_UserData (APTR)<br />
: Arbitrary user data associated with this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
=== Image attributes ===<br />
<br />
; TBIMAGE_Image (struct Image *)<br />
: Custom image to be used for a button or a toggle member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_ImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImage (struct Image *)<br />
: Custom image to display when the member becomes selected.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the select image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
;TBIMAGE_Width (uint32)<br />
;TBIMAGE_Height (uint32)<br />
: Image dimensions, in pixels. These tags can only be used in connection with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the respective source file will be scaled to the specified width and height. Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot be resized using these tags.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW)<br />
<br />
== Notes ==<br />
<br />
Some of the attributes described above change the sizing requirements of the gadget. If set on the fly (i.e. when the toolbar is already displayed in the window), the gadget domain will need recalculating and a re-layout must take place. Refer to the [[#OM_SET|OM_SET]] method documentation below to see how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image. [[#Image attributes|Image attributes]] cannot be changed later.<br />
<br />
== Bugs ==<br />
<br />
== See also ==<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
; NAME<br />
: OM_SET -- set toolbar attributes<br />
<br />
; SYNOPSIS<br />
: uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
: uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win, struct Requester *req, Tag tag1, ...);<br />
<br />
; FUNCTION<br />
: This method sets the attributes of the toolbar and/or of its members. SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions to invoke this method.<br />
: To change a member attribute you first need to pass TOOLBAR_SetMember to identify the respective member, and then the member attribute tag(s). See the EXAMPLE section below.<br />
: To change an attribute collectively for a group of members you first need to pass TOOLBAR_SetGroup to identify the respective group, and then the member attribute tag(s). See the EXAMPLE section below.<br />
<br />
; INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
; RESULT<br />
: This method will return TB_NEED_RETHINK if the gadget ''believes'' that one or more of the attributes will change the sizing requirements of the toolbar. Typically, invoking the WM_RETHINK method on the gadget's window object is needed, in order to recalculate the domain and re-layout the contents.<br />
: If you know you will be changing an attribute that requires a WM_RETHINK, prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
: The method returns 0L if no rethink is needed.<br />
<br />
; EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, groupID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
; NAME<br />
: TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, uint32 attrID, uint32 *storage);<br />
<br />
; FUNCTION<br />
: Use this method to obtain the value of a given member attribute.<br />
: Because of the way OM_GET is implemented in Intuition, getting member attributes is done differently compared to setting them. The difference boils down to the following:<br />
:* We cannot use a convenience function such as GetAttr() or GetAttrs(), so a dedicated method is provided. Refer to the EXAMPLE section below to see how to invoke the method.<br />
:* Only one attribute can be queried at a time. (As multiple attributes will rarely be requested in real use, this limitation should not pose a significant problem.)<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
attrID -- the attribute tag identifier<br />
storage -- a pointer to the variable for storing the attribute value<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the requested attribute value has been obtained successfully. The attribute value itself is returned in the provided storage variable.<br />
<br />
; EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID, TBMEMBER_Selected, &storage);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_REFRESHMEMBER ===<br />
<br />
; NAME<br />
: TBM_REFRESHMEMBER -- refresh the imagery of a given member (V53.3)<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbRefreshMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, struct Window *window);<br />
<br />
; FUNCTION<br />
: Use this method to refresh the imagery of a given button or toggle member.<br />
: The method has no effect on spacers and separators.<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbRefreshMember structure<br />
<br />
For IDoMethod():<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_REFRESHMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
window -- a pointer to the window the toolbar resides in<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the refresh has taken place.<br />
<br />
; EXAMPLE<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1024ToolBar Gadget Class2021-01-05T14:33:24Z<p>Trixie: Updated GA_TextAttr. Added TOOLBAR_TextPen.</p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Supported methods ==<br />
<br />
{| class="wikitable"<br />
!Method ID<br />
!Description<br />
|-<br />
|OM_NEW<br />
|creates the toolbar object, sets attributes and defaults<br />
|-<br />
|OM_DISPOSE<br />
|disposes of the toolbar object<br />
|-<br />
|OM_REMMEMBER<br />
|used by the class internally; consider this method private<br />
|-<br />
|OM_SET<br />
|sets toolbar, member and image attributes (see the [[#OM_SET|OM_SET]] section below for more information)<br />
|-<br />
|OM_GET<br />
|retrieves toolbar attributes<br />
|-<br />
|TBM_GETMEMBER<br />
|retrieves a given member attribute (see the [[#TBM_GETMEMBER|TBM_GETMEMBER]] section below for more information)<br />
|-<br />
|TBM_REFRESHMEMBER<br />
|refreshes the imagery of a given member (see the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] section below for more information)<br />
|}<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
; GA_ID (uint16)<br />
: Unique ID number for the gadget.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_ReadOnly (BOOL)<br />
: If set to TRUE, none of the toolbar buttons will be selectable.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_BackFill (struct Hook *)<br />
: A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
: Defaults to NULL (the default backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; GA_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the toolbar members' text.<br />
: Generally, you should use one font for the toolbar. However, you can override the global font and set a different one for individual members if needed; see TBMEMBER_TextAttr below.<br />
: Defaults to NULL (will use the system's default public screen font).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Orientation (uint32)<br />
: The toolbar orientation: horizontal or vertical.<br />
: Defaults to TB_ORIENT_HORIZ<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_Spacing (uint32)<br />
: The spacing between the individual toolbar members, in pixels.<br />
: Defaults to 2<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HorizPadding<br />
; TOOLBAR_VertPadding (uint32)<br />
: The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_InnerPadding (uint32)<br />
: The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.<br />
: Defaults to 4<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HandleOverflow (BOOL)<br />
: Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_MinVisible (uint32)<br />
: If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
: Defaults to 1<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SpacerSize (uint32)<br />
: The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.<br />
: Defaults to 5<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ButtonStyle (uint32)<br />
: The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
: Defaults to TB_BUTSTYLE_CLASSIC<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BevelStyle (uint32)<br />
: The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:<br />
<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
: When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.<br />
: Defaults to BVS_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SeparatorStyle (uint32)<br />
: Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.<br />
: Defaults to TB_SEPSTYLE_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SelectionStyle (uint32)<br />
: Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.<br />
: This tag is ignored in the classic mode with framed buttons.<br />
: Defaults to TB_SELSTYLE_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BackFill (struct Hook *)<br />
: A custom backfill hook to provide a background filled with a specific colour or pattern.<br />
: This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.<br />
: Defaults to NULL (the default layers backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Display (uint32)<br />
: Specifies what you want to display inside the toolbar button or toggle members. The possible values are:<br />
<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
: Defaults to TB_DISPLAY_IMAGES<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_TextPen (uint16) (V53.4)<br />
: A pen to be used for the toolbar members' text.<br />
: Generally, you should use one text pen for the toolbar. However, you can override the global pen and set a different one for individual members if needed; see TBMEMBER_TextPen below.<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
; TOOLBAR_TextPlace (uint32)<br />
: Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH. Plus, it only affects button and toggle members.<br />
: Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_LabelArray (STRPTR *)<br />
: Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.<br />
: TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
: Using this tag, the limitation is that you cannot create toggle members (only buttons, separators and spacers).<br />
: A special string, " ", will create a spacer.<br />
: A special string, "_", will create a separator.<br />
: Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.<br />
: The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TOOLBAR_EvenSize (BOOL)<br />
: If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.<br />
: If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ImageSet (uint32)<br />
: If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in the toolbar. The value passed to this tag is the image set ID.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:<br />
<br />
; TOOLBAR_AddImageSet (uint32)<br />
: Creates a new image set. The value passed to this tag is a numeric ID identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to display the particular image set in the toolbar.<br />
: This tag should be followed by a sequence of TOOLBAR_AddImage tags (see below), each creating one image in the given set.<br />
: If the gadget only uses one set of images, passing TOOLBAR_AddImageSet is not necessary. Each TOOLBAR_AddImage will add the respective image to the default image set identified by an ID of 0.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddImage (uint32)<br />
: Creates a new image in a given image set. The value passed to this tag is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID (see below) to associate the image with a particular toolbar member.<br />
: This tag should be followed by a sequence of TBIMAGE_ tags (see the [[#Image attributes|Image attributes]] section below), each configuring one aspect of the image, including its optional selected variant (referred to as the "select image").<br />
: Images are added to the default image set unless a preceding TOOLBAR_AddImageSet specifies a different set.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddMember (uint32)<br />
: Creates a new toolbar member. The value passed to this tag is a numeric ID identifying the member.<br />
: Spacers and separators normally don't need an ID, so you can use TB_NO_ID as a value for TOOLBAR_AddMember when creating these members. However, if you want to manipulate spacers/separators in your GUI, an ID will be necessary so that you can pass it to TOOLBAR_SetMember to identify the respective spacer or separator member.<br />
: You can add members when the toolbar object is being created, i.e. as part of the NewObject() call, or at any time later via SetAttrs().<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetMember<br />
: Use this tag in a SetAttrs() call to identify the member you want to modify.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetGroup<br />
: Use this tag in a SetAttrs() call to identify the group of members you want to modify collectively.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
=== Member attributes ===<br />
<br />
; TBMEMBER_Type (uint32)<br />
: The type of the toolbar member. The possible values are the following:<br />
<br />
TB_MTYPE_BUTTON -- a normal toolbar button<br />
TB_MTYPE_TOGGLE -- a toggle (on/off) button<br />
TB_MTYPE_SPACER -- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
TB_MTYPE_TEXTBOX -- a read-only box to display text (V53.4)<br />
<br />
: The type is set upon member creation, and cannot be changed.<br />
: Defaults to TB_MTYPE_BUTTON<br />
: Applicability is (OM_NEW)<br />
<br />
; TBMEMBER_ImageID (uint32)<br />
: The identifier of the image to be used for the button or toggle member (see TOOLBAR_AddImage above). This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_ImageID value of such a member.<br />
: When [[#OM_SET|OM_SET]]-ing this attribute, the method will always return TB_NEED_RETHINK, to be on the safe side. However, invoking WM_RETHINK is really only needed if the size of the new image is different from the original image. If the size is the same, a simple gadget refresh will suffice. You can trigger the refresh:<br />
:* by setting this attribute via RefreshSetGadgetAttrs(), or<br />
:* by setting this attribute via SetAttrs() and then invoking the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method on the respective button/toggle member.<br />
: (The difference is that RefreshSetGadgetAttrs() will refresh the entire toolbar, while TBM_REFRESHMEMBER will only refresh the given member.)<br />
: Defaults to TB_NO_ID (no image associated with this member)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Text (CONST_STRPTR)<br />
: The text to associate with a button, toggle or textbox member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
: The text will be used as fallback in case no image is found or provided for a button or a toggle member.<br />
: The text string can contain an underscore character (_), indicating the keyboard shortcut for the member. (This doesn't apply to textbox members, as they are read-only and don't respond to the keyboard.)<br />
: If your toolbar has a textbox member the contents of which is going to change dynamically, updating TBMEMBER_Text should be done like this:<br />
<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Text, "New text",<br />
TAG_END);<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
: Also, you should set TBMEMBER_DomainString for the textbox (see below). This will guarantee a required minimum size to fit any text, so you won't have to perform WM_RETHINK to recalculate the member size each time TBMEMBER_Text changes.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_DomainString (CONST_STRPTR)<br />
: A text string based on which the minimum size of the member will be calculated. This is useful especially with TB_MTYPE_TEXTBOX members when you want to enforce a minimum size required to fit text of variable length. The domain string ought to be at least as long as the longest text to appear in the textbox.<br />
: The domain string is never rendered in the gadget.<br />
: This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_DomainString value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the member text. This tag overrides GA_TextAttr (see above).<br />
: You should generally use one "global" font for the toolbar, configured via GA_TextAttr. But there are situations where it makes sense to set a particular font at the member level, for example when using textbox members.<br />
: Defaults to NULL.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_Disabled (BOOL)<br />
: The current state (disabled or not disabled) of a member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Disabled value of such a member.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Hidden (BOOL)<br />
: Specifies whether the particular member is displayed in the toolbar or hidden. You can use this tag to create "dynamic" toolbar layouts that adapt the actual member set to various application settings.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Selected (BOOL)<br />
: The current selection state of a toggle member. This tag is not relevant to normal buttons (TB_MTYPE_BUTTON), spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Selected value of such a member.<br />
: You can set a target BOOPSI object for any toggle member, using the standard icclass ICA_TARGET tag. The target will receive an automatic notification of the toggle selection. This way toolbar toggles can easily communicate with other boolean gadgets such as checkboxes.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_NOTIFY, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Group (uint32)<br />
: Member group ID. Several members can be manipulated at once if they are assigned to the same group. Use TOOLBAR_SetGroup with the respective group ID to identify the group to be manipulated.<br />
: Defaults to TB_NO_ID (not assigned to any group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_MXGroup (uint32)<br />
: MX group ID. Toggle members can be put in groups of mutually-exclusive buttons. When such a toggle is selected, all other toggles in the same MX group will become deselected.<br />
: This tag is not relevant to normal buttons, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_MXGroup value of such a member.<br />
: Defaults to TB_NO_ID (not assigned to any MX group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_HintInfo (CONST_STRPTR)<br />
: The help text to be displayed when the user hovers the mouse pointer over the respective member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_HintInfo value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_UserData (APTR)<br />
: Arbitrary user data associated with this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
=== Image attributes ===<br />
<br />
; TBIMAGE_Image (struct Image *)<br />
: Custom image to be used for a button or a toggle member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_ImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImage (struct Image *)<br />
: Custom image to display when the member becomes selected.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the select image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
;TBIMAGE_Width (uint32)<br />
;TBIMAGE_Height (uint32)<br />
: Image dimensions, in pixels. These tags can only be used in connection with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the respective source file will be scaled to the specified width and height. Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot be resized using these tags.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW)<br />
<br />
== Notes ==<br />
<br />
Some of the attributes described above change the sizing requirements of the gadget. If set on the fly (i.e. when the toolbar is already displayed in the window), the gadget domain will need recalculating and a re-layout must take place. Refer to the [[#OM_SET|OM_SET]] method documentation below to see how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image. [[#Image attributes|Image attributes]] cannot be changed later.<br />
<br />
== Bugs ==<br />
<br />
== See also ==<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
; NAME<br />
: OM_SET -- set toolbar attributes<br />
<br />
; SYNOPSIS<br />
: uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
: uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win, struct Requester *req, Tag tag1, ...);<br />
<br />
; FUNCTION<br />
: This method sets the attributes of the toolbar and/or of its members. SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions to invoke this method.<br />
: To change a member attribute you first need to pass TOOLBAR_SetMember to identify the respective member, and then the member attribute tag(s). See the EXAMPLE section below.<br />
: To change an attribute collectively for a group of members you first need to pass TOOLBAR_SetGroup to identify the respective group, and then the member attribute tag(s). See the EXAMPLE section below.<br />
<br />
; INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
; RESULT<br />
: This method will return TB_NEED_RETHINK if the gadget ''believes'' that one or more of the attributes will change the sizing requirements of the toolbar. Typically, invoking the WM_RETHINK method on the gadget's window object is needed, in order to recalculate the domain and re-layout the contents.<br />
: If you know you will be changing an attribute that requires a WM_RETHINK, prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
: The method returns 0L if no rethink is needed.<br />
<br />
; EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, groupID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
; NAME<br />
: TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, uint32 attrID, uint32 *storage);<br />
<br />
; FUNCTION<br />
: Use this method to obtain the value of a given member attribute.<br />
: Because of the way OM_GET is implemented in Intuition, getting member attributes is done differently compared to setting them. The difference boils down to the following:<br />
:* We cannot use a convenience function such as GetAttr() or GetAttrs(), so a dedicated method is provided. Refer to the EXAMPLE section below to see how to invoke the method.<br />
:* Only one attribute can be queried at a time. (As multiple attributes will rarely be requested in real use, this limitation should not pose a significant problem.)<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
attrID -- the attribute tag identifier<br />
storage -- a pointer to the variable for storing the attribute value<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the requested attribute value has been obtained successfully. The attribute value itself is returned in the provided storage variable.<br />
<br />
; EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID, TBMEMBER_Selected, &storage);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_REFRESHMEMBER ===<br />
<br />
; NAME<br />
: TBM_REFRESHMEMBER -- refresh the imagery of a given member (V53.3)<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbRefreshMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, struct Window *window);<br />
<br />
; FUNCTION<br />
: Use this method to refresh the imagery of a given button or toggle member.<br />
: The method has no effect on spacers and separators.<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbRefreshMember structure<br />
<br />
For IDoMethod():<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_REFRESHMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
window -- a pointer to the window the toolbar resides in<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the refresh has taken place.<br />
<br />
; EXAMPLE<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1023ToolBar Gadget Class2021-01-04T21:26:51Z<p>Trixie: /* TBM_GETMEMBER */</p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Supported methods ==<br />
<br />
{| class="wikitable"<br />
!Method ID<br />
!Description<br />
|-<br />
|OM_NEW<br />
|creates the toolbar object, sets attributes and defaults<br />
|-<br />
|OM_DISPOSE<br />
|disposes of the toolbar object<br />
|-<br />
|OM_REMMEMBER<br />
|used by the class internally; consider this method private<br />
|-<br />
|OM_SET<br />
|sets toolbar, member and image attributes (see the [[#OM_SET|OM_SET]] section below for more information)<br />
|-<br />
|OM_GET<br />
|retrieves toolbar attributes<br />
|-<br />
|TBM_GETMEMBER<br />
|retrieves a given member attribute (see the [[#TBM_GETMEMBER|TBM_GETMEMBER]] section below for more information)<br />
|-<br />
|TBM_REFRESHMEMBER<br />
|refreshes the imagery of a given member (see the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] section below for more information)<br />
|}<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
; GA_ID (uint16)<br />
: Unique ID number for the gadget.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_ReadOnly (BOOL)<br />
: If set to TRUE, none of the toolbar buttons will be selectable.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_BackFill (struct Hook *)<br />
: A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
: Defaults to NULL (the default backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; GA_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the gadget members' text.<br />
: Defaults to the system's default public screen font.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Orientation (uint32)<br />
: The toolbar orientation: horizontal or vertical.<br />
: Defaults to TB_ORIENT_HORIZ<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_Spacing (uint32)<br />
: The spacing between the individual toolbar members, in pixels.<br />
: Defaults to 2<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HorizPadding<br />
; TOOLBAR_VertPadding (uint32)<br />
: The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_InnerPadding (uint32)<br />
: The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.<br />
: Defaults to 4<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HandleOverflow (BOOL)<br />
: Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_MinVisible (uint32)<br />
: If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
: Defaults to 1<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SpacerSize (uint32)<br />
: The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.<br />
: Defaults to 5<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ButtonStyle (uint32)<br />
: The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
: Defaults to TB_BUTSTYLE_CLASSIC<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BevelStyle (uint32)<br />
: The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:<br />
<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
: When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.<br />
: Defaults to BVS_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SeparatorStyle (uint32)<br />
: Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.<br />
: Defaults to TB_SEPSTYLE_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SelectionStyle (uint32)<br />
: Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.<br />
: This tag is ignored in the classic mode with framed buttons.<br />
: Defaults to TB_SELSTYLE_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BackFill (struct Hook *)<br />
: A custom backfill hook to provide a background filled with a specific colour or pattern.<br />
: This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.<br />
: Defaults to NULL (the default layers backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Display (uint32)<br />
: Specifies what you want to display inside the toolbar button or toggle members. The possible values are:<br />
<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
: Defaults to TB_DISPLAY_IMAGES<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_TextPlace (uint32)<br />
: Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH. Plus, it only affects button and toggle members.<br />
: Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_LabelArray (STRPTR *)<br />
: Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.<br />
: TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
: Using this tag, the limitation is that you cannot create toggle members (only buttons, separators and spacers).<br />
: A special string, " ", will create a spacer.<br />
: A special string, "_", will create a separator.<br />
: Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.<br />
: The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TOOLBAR_EvenSize (BOOL)<br />
: If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.<br />
: If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ImageSet (uint32)<br />
: If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in the toolbar. The value passed to this tag is the image set ID.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:<br />
<br />
; TOOLBAR_AddImageSet (uint32)<br />
: Creates a new image set. The value passed to this tag is a numeric ID identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to display the particular image set in the toolbar.<br />
: This tag should be followed by a sequence of TOOLBAR_AddImage tags (see below), each creating one image in the given set.<br />
: If the gadget only uses one set of images, passing TOOLBAR_AddImageSet is not necessary. Each TOOLBAR_AddImage will add the respective image to the default image set identified by an ID of 0.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddImage (uint32)<br />
: Creates a new image in a given image set. The value passed to this tag is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID (see below) to associate the image with a particular toolbar member.<br />
: This tag should be followed by a sequence of TBIMAGE_ tags (see the [[#Image attributes|Image attributes]] section below), each configuring one aspect of the image, including its optional selected variant (referred to as the "select image").<br />
: Images are added to the default image set unless a preceding TOOLBAR_AddImageSet specifies a different set.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddMember (uint32)<br />
: Creates a new toolbar member. The value passed to this tag is a numeric ID identifying the member.<br />
: Spacers and separators normally don't need an ID, so you can use TB_NO_ID as a value for TOOLBAR_AddMember when creating these members. However, if you want to manipulate spacers/separators in your GUI, an ID will be necessary so that you can pass it to TOOLBAR_SetMember to identify the respective spacer or separator member.<br />
: You can add members when the toolbar object is being created, i.e. as part of the NewObject() call, or at any time later via SetAttrs().<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetMember<br />
: Use this tag in a SetAttrs() call to identify the member you want to modify.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetGroup<br />
: Use this tag in a SetAttrs() call to identify the group of members you want to modify collectively.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
=== Member attributes ===<br />
<br />
; TBMEMBER_Type (uint32)<br />
: The type of the toolbar member. The possible values are the following:<br />
<br />
TB_MTYPE_BUTTON -- a normal toolbar button<br />
TB_MTYPE_TOGGLE -- a toggle (on/off) button<br />
TB_MTYPE_SPACER -- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
TB_MTYPE_TEXTBOX -- a read-only box to display text (V53.4)<br />
<br />
: The type is set upon member creation, and cannot be changed.<br />
: Defaults to TB_MTYPE_BUTTON<br />
: Applicability is (OM_NEW)<br />
<br />
; TBMEMBER_ImageID (uint32)<br />
: The identifier of the image to be used for the button or toggle member (see TOOLBAR_AddImage above). This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_ImageID value of such a member.<br />
: When [[#OM_SET|OM_SET]]-ing this attribute, the method will always return TB_NEED_RETHINK, to be on the safe side. However, invoking WM_RETHINK is really only needed if the size of the new image is different from the original image. If the size is the same, a simple gadget refresh will suffice. You can trigger the refresh:<br />
:* by setting this attribute via RefreshSetGadgetAttrs(), or<br />
:* by setting this attribute via SetAttrs() and then invoking the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method on the respective button/toggle member.<br />
: (The difference is that RefreshSetGadgetAttrs() will refresh the entire toolbar, while TBM_REFRESHMEMBER will only refresh the given member.)<br />
: Defaults to TB_NO_ID (no image associated with this member)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Text (CONST_STRPTR)<br />
: The text to associate with a button, toggle or textbox member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
: The text will be used as fallback in case no image is found or provided for a button or a toggle member.<br />
: The text string can contain an underscore character (_), indicating the keyboard shortcut for the member. (This doesn't apply to textbox members, as they are read-only and don't respond to the keyboard.)<br />
: If your toolbar has a textbox member the contents of which is going to change dynamically, updating TBMEMBER_Text should be done like this:<br />
<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Text, "New text",<br />
TAG_END);<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
: Also, you should set TBMEMBER_DomainString for the textbox (see below). This will guarantee a required minimum size to fit any text, so you won't have to perform WM_RETHINK to recalculate the member size each time TBMEMBER_Text changes.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_DomainString (CONST_STRPTR)<br />
: A text string based on which the minimum size of the member will be calculated. This is useful especially with TB_MTYPE_TEXTBOX members when you want to enforce a minimum size required to fit text of variable length. The domain string ought to be at least as long as the longest text to appear in the textbox.<br />
: The domain string is never rendered in the gadget.<br />
: This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_DomainString value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the member text. This tag overrides GA_TextAttr (see above).<br />
: You should generally use one "global" font for the toolbar, configured via GA_TextAttr. But there are situations where it makes sense to set a particular font at the member level, for example when using textbox members.<br />
: Defaults to NULL.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_Disabled (BOOL)<br />
: The current state (disabled or not disabled) of a member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Disabled value of such a member.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Hidden (BOOL)<br />
: Specifies whether the particular member is displayed in the toolbar or hidden. You can use this tag to create "dynamic" toolbar layouts that adapt the actual member set to various application settings.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Selected (BOOL)<br />
: The current selection state of a toggle member. This tag is not relevant to normal buttons (TB_MTYPE_BUTTON), spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Selected value of such a member.<br />
: You can set a target BOOPSI object for any toggle member, using the standard icclass ICA_TARGET tag. The target will receive an automatic notification of the toggle selection. This way toolbar toggles can easily communicate with other boolean gadgets such as checkboxes.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_NOTIFY, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Group (uint32)<br />
: Member group ID. Several members can be manipulated at once if they are assigned to the same group. Use TOOLBAR_SetGroup with the respective group ID to identify the group to be manipulated.<br />
: Defaults to TB_NO_ID (not assigned to any group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_MXGroup (uint32)<br />
: MX group ID. Toggle members can be put in groups of mutually-exclusive buttons. When such a toggle is selected, all other toggles in the same MX group will become deselected.<br />
: This tag is not relevant to normal buttons, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_MXGroup value of such a member.<br />
: Defaults to TB_NO_ID (not assigned to any MX group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_HintInfo (CONST_STRPTR)<br />
: The help text to be displayed when the user hovers the mouse pointer over the respective member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_HintInfo value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_UserData (APTR)<br />
: Arbitrary user data associated with this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
=== Image attributes ===<br />
<br />
; TBIMAGE_Image (struct Image *)<br />
: Custom image to be used for a button or a toggle member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_ImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImage (struct Image *)<br />
: Custom image to display when the member becomes selected.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the select image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
;TBIMAGE_Width (uint32)<br />
;TBIMAGE_Height (uint32)<br />
: Image dimensions, in pixels. These tags can only be used in connection with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the respective source file will be scaled to the specified width and height. Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot be resized using these tags.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW)<br />
<br />
== Notes ==<br />
<br />
Some of the attributes described above change the sizing requirements of the gadget. If set on the fly (i.e. when the toolbar is already displayed in the window), the gadget domain will need recalculating and a re-layout must take place. Refer to the [[#OM_SET|OM_SET]] method documentation below to see how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image. [[#Image attributes|Image attributes]] cannot be changed later.<br />
<br />
== Bugs ==<br />
<br />
== See also ==<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
; NAME<br />
: OM_SET -- set toolbar attributes<br />
<br />
; SYNOPSIS<br />
: uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
: uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win, struct Requester *req, Tag tag1, ...);<br />
<br />
; FUNCTION<br />
: This method sets the attributes of the toolbar and/or of its members. SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions to invoke this method.<br />
: To change a member attribute you first need to pass TOOLBAR_SetMember to identify the respective member, and then the member attribute tag(s). See the EXAMPLE section below.<br />
: To change an attribute collectively for a group of members you first need to pass TOOLBAR_SetGroup to identify the respective group, and then the member attribute tag(s). See the EXAMPLE section below.<br />
<br />
; INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
; RESULT<br />
: This method will return TB_NEED_RETHINK if the gadget ''believes'' that one or more of the attributes will change the sizing requirements of the toolbar. Typically, invoking the WM_RETHINK method on the gadget's window object is needed, in order to recalculate the domain and re-layout the contents.<br />
: If you know you will be changing an attribute that requires a WM_RETHINK, prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
: The method returns 0L if no rethink is needed.<br />
<br />
; EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, groupID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
; NAME<br />
: TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, uint32 attrID, uint32 *storage);<br />
<br />
; FUNCTION<br />
: Use this method to obtain the value of a given member attribute.<br />
: Because of the way OM_GET is implemented in Intuition, getting member attributes is done differently compared to setting them. The difference boils down to the following:<br />
:* We cannot use a convenience function such as GetAttr() or GetAttrs(), so a dedicated method is provided. Refer to the EXAMPLE section below to see how to invoke the method.<br />
:* Only one attribute can be queried at a time. (As multiple attributes will rarely be requested in real use, this limitation should not pose a significant problem.)<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
attrID -- the attribute tag identifier<br />
storage -- a pointer to the variable for storing the attribute value<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the requested attribute value has been obtained successfully. The attribute value itself is returned in the provided storage variable.<br />
<br />
; EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID, TBMEMBER_Selected, &storage);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_REFRESHMEMBER ===<br />
<br />
; NAME<br />
: TBM_REFRESHMEMBER -- refresh the imagery of a given member (V53.3)<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbRefreshMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, struct Window *window);<br />
<br />
; FUNCTION<br />
: Use this method to refresh the imagery of a given button or toggle member.<br />
: The method has no effect on spacers and separators.<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbRefreshMember structure<br />
<br />
For IDoMethod():<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_REFRESHMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
window -- a pointer to the window the toolbar resides in<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the refresh has taken place.<br />
<br />
; EXAMPLE<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1022ToolBar Gadget Class2021-01-04T21:24:57Z<p>Trixie: /* OM_SET */</p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Supported methods ==<br />
<br />
{| class="wikitable"<br />
!Method ID<br />
!Description<br />
|-<br />
|OM_NEW<br />
|creates the toolbar object, sets attributes and defaults<br />
|-<br />
|OM_DISPOSE<br />
|disposes of the toolbar object<br />
|-<br />
|OM_REMMEMBER<br />
|used by the class internally; consider this method private<br />
|-<br />
|OM_SET<br />
|sets toolbar, member and image attributes (see the [[#OM_SET|OM_SET]] section below for more information)<br />
|-<br />
|OM_GET<br />
|retrieves toolbar attributes<br />
|-<br />
|TBM_GETMEMBER<br />
|retrieves a given member attribute (see the [[#TBM_GETMEMBER|TBM_GETMEMBER]] section below for more information)<br />
|-<br />
|TBM_REFRESHMEMBER<br />
|refreshes the imagery of a given member (see the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] section below for more information)<br />
|}<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
; GA_ID (uint16)<br />
: Unique ID number for the gadget.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_ReadOnly (BOOL)<br />
: If set to TRUE, none of the toolbar buttons will be selectable.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_BackFill (struct Hook *)<br />
: A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
: Defaults to NULL (the default backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; GA_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the gadget members' text.<br />
: Defaults to the system's default public screen font.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Orientation (uint32)<br />
: The toolbar orientation: horizontal or vertical.<br />
: Defaults to TB_ORIENT_HORIZ<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_Spacing (uint32)<br />
: The spacing between the individual toolbar members, in pixels.<br />
: Defaults to 2<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HorizPadding<br />
; TOOLBAR_VertPadding (uint32)<br />
: The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_InnerPadding (uint32)<br />
: The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.<br />
: Defaults to 4<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HandleOverflow (BOOL)<br />
: Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_MinVisible (uint32)<br />
: If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
: Defaults to 1<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SpacerSize (uint32)<br />
: The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.<br />
: Defaults to 5<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ButtonStyle (uint32)<br />
: The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
: Defaults to TB_BUTSTYLE_CLASSIC<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BevelStyle (uint32)<br />
: The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:<br />
<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
: When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.<br />
: Defaults to BVS_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SeparatorStyle (uint32)<br />
: Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.<br />
: Defaults to TB_SEPSTYLE_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SelectionStyle (uint32)<br />
: Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.<br />
: This tag is ignored in the classic mode with framed buttons.<br />
: Defaults to TB_SELSTYLE_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BackFill (struct Hook *)<br />
: A custom backfill hook to provide a background filled with a specific colour or pattern.<br />
: This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.<br />
: Defaults to NULL (the default layers backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Display (uint32)<br />
: Specifies what you want to display inside the toolbar button or toggle members. The possible values are:<br />
<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
: Defaults to TB_DISPLAY_IMAGES<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_TextPlace (uint32)<br />
: Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH. Plus, it only affects button and toggle members.<br />
: Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_LabelArray (STRPTR *)<br />
: Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.<br />
: TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
: Using this tag, the limitation is that you cannot create toggle members (only buttons, separators and spacers).<br />
: A special string, " ", will create a spacer.<br />
: A special string, "_", will create a separator.<br />
: Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.<br />
: The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TOOLBAR_EvenSize (BOOL)<br />
: If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.<br />
: If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ImageSet (uint32)<br />
: If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in the toolbar. The value passed to this tag is the image set ID.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:<br />
<br />
; TOOLBAR_AddImageSet (uint32)<br />
: Creates a new image set. The value passed to this tag is a numeric ID identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to display the particular image set in the toolbar.<br />
: This tag should be followed by a sequence of TOOLBAR_AddImage tags (see below), each creating one image in the given set.<br />
: If the gadget only uses one set of images, passing TOOLBAR_AddImageSet is not necessary. Each TOOLBAR_AddImage will add the respective image to the default image set identified by an ID of 0.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddImage (uint32)<br />
: Creates a new image in a given image set. The value passed to this tag is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID (see below) to associate the image with a particular toolbar member.<br />
: This tag should be followed by a sequence of TBIMAGE_ tags (see the [[#Image attributes|Image attributes]] section below), each configuring one aspect of the image, including its optional selected variant (referred to as the "select image").<br />
: Images are added to the default image set unless a preceding TOOLBAR_AddImageSet specifies a different set.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddMember (uint32)<br />
: Creates a new toolbar member. The value passed to this tag is a numeric ID identifying the member.<br />
: Spacers and separators normally don't need an ID, so you can use TB_NO_ID as a value for TOOLBAR_AddMember when creating these members. However, if you want to manipulate spacers/separators in your GUI, an ID will be necessary so that you can pass it to TOOLBAR_SetMember to identify the respective spacer or separator member.<br />
: You can add members when the toolbar object is being created, i.e. as part of the NewObject() call, or at any time later via SetAttrs().<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetMember<br />
: Use this tag in a SetAttrs() call to identify the member you want to modify.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetGroup<br />
: Use this tag in a SetAttrs() call to identify the group of members you want to modify collectively.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
=== Member attributes ===<br />
<br />
; TBMEMBER_Type (uint32)<br />
: The type of the toolbar member. The possible values are the following:<br />
<br />
TB_MTYPE_BUTTON -- a normal toolbar button<br />
TB_MTYPE_TOGGLE -- a toggle (on/off) button<br />
TB_MTYPE_SPACER -- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
TB_MTYPE_TEXTBOX -- a read-only box to display text (V53.4)<br />
<br />
: The type is set upon member creation, and cannot be changed.<br />
: Defaults to TB_MTYPE_BUTTON<br />
: Applicability is (OM_NEW)<br />
<br />
; TBMEMBER_ImageID (uint32)<br />
: The identifier of the image to be used for the button or toggle member (see TOOLBAR_AddImage above). This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_ImageID value of such a member.<br />
: When [[#OM_SET|OM_SET]]-ing this attribute, the method will always return TB_NEED_RETHINK, to be on the safe side. However, invoking WM_RETHINK is really only needed if the size of the new image is different from the original image. If the size is the same, a simple gadget refresh will suffice. You can trigger the refresh:<br />
:* by setting this attribute via RefreshSetGadgetAttrs(), or<br />
:* by setting this attribute via SetAttrs() and then invoking the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method on the respective button/toggle member.<br />
: (The difference is that RefreshSetGadgetAttrs() will refresh the entire toolbar, while TBM_REFRESHMEMBER will only refresh the given member.)<br />
: Defaults to TB_NO_ID (no image associated with this member)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Text (CONST_STRPTR)<br />
: The text to associate with a button, toggle or textbox member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
: The text will be used as fallback in case no image is found or provided for a button or a toggle member.<br />
: The text string can contain an underscore character (_), indicating the keyboard shortcut for the member. (This doesn't apply to textbox members, as they are read-only and don't respond to the keyboard.)<br />
: If your toolbar has a textbox member the contents of which is going to change dynamically, updating TBMEMBER_Text should be done like this:<br />
<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Text, "New text",<br />
TAG_END);<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
: Also, you should set TBMEMBER_DomainString for the textbox (see below). This will guarantee a required minimum size to fit any text, so you won't have to perform WM_RETHINK to recalculate the member size each time TBMEMBER_Text changes.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_DomainString (CONST_STRPTR)<br />
: A text string based on which the minimum size of the member will be calculated. This is useful especially with TB_MTYPE_TEXTBOX members when you want to enforce a minimum size required to fit text of variable length. The domain string ought to be at least as long as the longest text to appear in the textbox.<br />
: The domain string is never rendered in the gadget.<br />
: This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_DomainString value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the member text. This tag overrides GA_TextAttr (see above).<br />
: You should generally use one "global" font for the toolbar, configured via GA_TextAttr. But there are situations where it makes sense to set a particular font at the member level, for example when using textbox members.<br />
: Defaults to NULL.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_Disabled (BOOL)<br />
: The current state (disabled or not disabled) of a member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Disabled value of such a member.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Hidden (BOOL)<br />
: Specifies whether the particular member is displayed in the toolbar or hidden. You can use this tag to create "dynamic" toolbar layouts that adapt the actual member set to various application settings.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Selected (BOOL)<br />
: The current selection state of a toggle member. This tag is not relevant to normal buttons (TB_MTYPE_BUTTON), spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Selected value of such a member.<br />
: You can set a target BOOPSI object for any toggle member, using the standard icclass ICA_TARGET tag. The target will receive an automatic notification of the toggle selection. This way toolbar toggles can easily communicate with other boolean gadgets such as checkboxes.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_NOTIFY, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Group (uint32)<br />
: Member group ID. Several members can be manipulated at once if they are assigned to the same group. Use TOOLBAR_SetGroup with the respective group ID to identify the group to be manipulated.<br />
: Defaults to TB_NO_ID (not assigned to any group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_MXGroup (uint32)<br />
: MX group ID. Toggle members can be put in groups of mutually-exclusive buttons. When such a toggle is selected, all other toggles in the same MX group will become deselected.<br />
: This tag is not relevant to normal buttons, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_MXGroup value of such a member.<br />
: Defaults to TB_NO_ID (not assigned to any MX group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_HintInfo (CONST_STRPTR)<br />
: The help text to be displayed when the user hovers the mouse pointer over the respective member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_HintInfo value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_UserData (APTR)<br />
: Arbitrary user data associated with this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
=== Image attributes ===<br />
<br />
; TBIMAGE_Image (struct Image *)<br />
: Custom image to be used for a button or a toggle member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_ImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImage (struct Image *)<br />
: Custom image to display when the member becomes selected.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the select image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
;TBIMAGE_Width (uint32)<br />
;TBIMAGE_Height (uint32)<br />
: Image dimensions, in pixels. These tags can only be used in connection with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the respective source file will be scaled to the specified width and height. Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot be resized using these tags.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW)<br />
<br />
== Notes ==<br />
<br />
Some of the attributes described above change the sizing requirements of the gadget. If set on the fly (i.e. when the toolbar is already displayed in the window), the gadget domain will need recalculating and a re-layout must take place. Refer to the [[#OM_SET|OM_SET]] method documentation below to see how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image. [[#Image attributes|Image attributes]] cannot be changed later.<br />
<br />
== Bugs ==<br />
<br />
== See also ==<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
; NAME<br />
: OM_SET -- set toolbar attributes<br />
<br />
; SYNOPSIS<br />
: uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
: uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win, struct Requester *req, Tag tag1, ...);<br />
<br />
; FUNCTION<br />
: This method sets the attributes of the toolbar and/or of its members. SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions to invoke this method.<br />
: To change a member attribute you first need to pass TOOLBAR_SetMember to identify the respective member, and then the member attribute tag(s). See the EXAMPLE section below.<br />
: To change an attribute collectively for a group of members you first need to pass TOOLBAR_SetGroup to identify the respective group, and then the member attribute tag(s). See the EXAMPLE section below.<br />
<br />
; INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
; RESULT<br />
: This method will return TB_NEED_RETHINK if the gadget ''believes'' that one or more of the attributes will change the sizing requirements of the toolbar. Typically, invoking the WM_RETHINK method on the gadget's window object is needed, in order to recalculate the domain and re-layout the contents.<br />
: If you know you will be changing an attribute that requires a WM_RETHINK, prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
: The method returns 0L if no rethink is needed.<br />
<br />
; EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, groupID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
; NAME<br />
: TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, uint32 attrID, uint32 *storage);<br />
<br />
; FUNCTION<br />
: Use this method to obtain the value of a given member attribute.<br />
: Because of the way OM_GET is implemented in Intuition, getting member attributes is done differently compared to setting them. The difference boils down to the following:<br />
:* We cannot use a convenience function such as GetAttr() or GetAttrs(), so a dedicated method is provided. Refer to the EXAMPLE section below to see how to invoke the method.<br />
:* Only one attribute can be queried at a time. (As multiple attributes will rarely be requested in real use, this limitation should not pose a significant problem.)<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
attrID -- the attribute tag identifier<br />
storage -- a pointer to the variable for storing the attribute value<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the requested attribute value has been obtained successfully. The attribute value itself is returned in the provided storage variable.<br />
<br />
; EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID, TBMEMBER_Selected, &storage);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_REFRESHMEMBER ===<br />
<br />
; NAME<br />
: TBM_REFRESHMEMBER -- refresh the imagery of a given member (V53.3)<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbRefreshMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, struct Window *window);<br />
<br />
; FUNCTION<br />
: Use this method to refresh the imagery of a given button or toggle member.<br />
: The method has no effect on spacers and separators.<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbRefreshMember structure<br />
<br />
For IDoMethod():<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_REFRESHMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
window -- a pointer to the window the toolbar resides in<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the refresh has taken place.<br />
<br />
; EXAMPLE<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1021ToolBar Gadget Class2021-01-04T21:19:28Z<p>Trixie: Updated TBMEMBER_DomainString and TBMEMBER_Text.</p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Supported methods ==<br />
<br />
{| class="wikitable"<br />
!Method ID<br />
!Description<br />
|-<br />
|OM_NEW<br />
|creates the toolbar object, sets attributes and defaults<br />
|-<br />
|OM_DISPOSE<br />
|disposes of the toolbar object<br />
|-<br />
|OM_REMMEMBER<br />
|used by the class internally; consider this method private<br />
|-<br />
|OM_SET<br />
|sets toolbar, member and image attributes (see the [[#OM_SET|OM_SET]] section below for more information)<br />
|-<br />
|OM_GET<br />
|retrieves toolbar attributes<br />
|-<br />
|TBM_GETMEMBER<br />
|retrieves a given member attribute (see the [[#TBM_GETMEMBER|TBM_GETMEMBER]] section below for more information)<br />
|-<br />
|TBM_REFRESHMEMBER<br />
|refreshes the imagery of a given member (see the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] section below for more information)<br />
|}<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
; GA_ID (uint16)<br />
: Unique ID number for the gadget.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_ReadOnly (BOOL)<br />
: If set to TRUE, none of the toolbar buttons will be selectable.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_BackFill (struct Hook *)<br />
: A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
: Defaults to NULL (the default backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; GA_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the gadget members' text.<br />
: Defaults to the system's default public screen font.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Orientation (uint32)<br />
: The toolbar orientation: horizontal or vertical.<br />
: Defaults to TB_ORIENT_HORIZ<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_Spacing (uint32)<br />
: The spacing between the individual toolbar members, in pixels.<br />
: Defaults to 2<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HorizPadding<br />
; TOOLBAR_VertPadding (uint32)<br />
: The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_InnerPadding (uint32)<br />
: The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.<br />
: Defaults to 4<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HandleOverflow (BOOL)<br />
: Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_MinVisible (uint32)<br />
: If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
: Defaults to 1<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SpacerSize (uint32)<br />
: The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.<br />
: Defaults to 5<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ButtonStyle (uint32)<br />
: The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
: Defaults to TB_BUTSTYLE_CLASSIC<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BevelStyle (uint32)<br />
: The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:<br />
<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
: When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.<br />
: Defaults to BVS_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SeparatorStyle (uint32)<br />
: Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.<br />
: Defaults to TB_SEPSTYLE_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SelectionStyle (uint32)<br />
: Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.<br />
: This tag is ignored in the classic mode with framed buttons.<br />
: Defaults to TB_SELSTYLE_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BackFill (struct Hook *)<br />
: A custom backfill hook to provide a background filled with a specific colour or pattern.<br />
: This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.<br />
: Defaults to NULL (the default layers backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Display (uint32)<br />
: Specifies what you want to display inside the toolbar button or toggle members. The possible values are:<br />
<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
: Defaults to TB_DISPLAY_IMAGES<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_TextPlace (uint32)<br />
: Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH. Plus, it only affects button and toggle members.<br />
: Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_LabelArray (STRPTR *)<br />
: Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.<br />
: TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
: Using this tag, the limitation is that you cannot create toggle members (only buttons, separators and spacers).<br />
: A special string, " ", will create a spacer.<br />
: A special string, "_", will create a separator.<br />
: Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.<br />
: The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TOOLBAR_EvenSize (BOOL)<br />
: If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.<br />
: If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ImageSet (uint32)<br />
: If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in the toolbar. The value passed to this tag is the image set ID.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:<br />
<br />
; TOOLBAR_AddImageSet (uint32)<br />
: Creates a new image set. The value passed to this tag is a numeric ID identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to display the particular image set in the toolbar.<br />
: This tag should be followed by a sequence of TOOLBAR_AddImage tags (see below), each creating one image in the given set.<br />
: If the gadget only uses one set of images, passing TOOLBAR_AddImageSet is not necessary. Each TOOLBAR_AddImage will add the respective image to the default image set identified by an ID of 0.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddImage (uint32)<br />
: Creates a new image in a given image set. The value passed to this tag is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID (see below) to associate the image with a particular toolbar member.<br />
: This tag should be followed by a sequence of TBIMAGE_ tags (see the [[#Image attributes|Image attributes]] section below), each configuring one aspect of the image, including its optional selected variant (referred to as the "select image").<br />
: Images are added to the default image set unless a preceding TOOLBAR_AddImageSet specifies a different set.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddMember (uint32)<br />
: Creates a new toolbar member. The value passed to this tag is a numeric ID identifying the member.<br />
: Spacers and separators normally don't need an ID, so you can use TB_NO_ID as a value for TOOLBAR_AddMember when creating these members. However, if you want to manipulate spacers/separators in your GUI, an ID will be necessary so that you can pass it to TOOLBAR_SetMember to identify the respective spacer or separator member.<br />
: You can add members when the toolbar object is being created, i.e. as part of the NewObject() call, or at any time later via SetAttrs().<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetMember<br />
: Use this tag in a SetAttrs() call to identify the member you want to modify.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetGroup<br />
: Use this tag in a SetAttrs() call to identify the group of members you want to modify collectively.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
=== Member attributes ===<br />
<br />
; TBMEMBER_Type (uint32)<br />
: The type of the toolbar member. The possible values are the following:<br />
<br />
TB_MTYPE_BUTTON -- a normal toolbar button<br />
TB_MTYPE_TOGGLE -- a toggle (on/off) button<br />
TB_MTYPE_SPACER -- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
TB_MTYPE_TEXTBOX -- a read-only box to display text (V53.4)<br />
<br />
: The type is set upon member creation, and cannot be changed.<br />
: Defaults to TB_MTYPE_BUTTON<br />
: Applicability is (OM_NEW)<br />
<br />
; TBMEMBER_ImageID (uint32)<br />
: The identifier of the image to be used for the button or toggle member (see TOOLBAR_AddImage above). This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_ImageID value of such a member.<br />
: When [[#OM_SET|OM_SET]]-ing this attribute, the method will always return TB_NEED_RETHINK, to be on the safe side. However, invoking WM_RETHINK is really only needed if the size of the new image is different from the original image. If the size is the same, a simple gadget refresh will suffice. You can trigger the refresh:<br />
:* by setting this attribute via RefreshSetGadgetAttrs(), or<br />
:* by setting this attribute via SetAttrs() and then invoking the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method on the respective button/toggle member.<br />
: (The difference is that RefreshSetGadgetAttrs() will refresh the entire toolbar, while TBM_REFRESHMEMBER will only refresh the given member.)<br />
: Defaults to TB_NO_ID (no image associated with this member)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Text (CONST_STRPTR)<br />
: The text to associate with a button, toggle or textbox member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
: The text will be used as fallback in case no image is found or provided for a button or a toggle member.<br />
: The text string can contain an underscore character (_), indicating the keyboard shortcut for the member. (This doesn't apply to textbox members, as they are read-only and don't respond to the keyboard.)<br />
: If your toolbar has a textbox member the contents of which is going to change dynamically, updating TBMEMBER_Text should be done like this:<br />
<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, memberID,<br />
TBMEMBER_Text, "New text",<br />
TAG_END);<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
: Also, you should set TBMEMBER_DomainString for the textbox (see below). This will guarantee a required minimum size to fit any text, so you won't have to perform WM_RETHINK to recalculate the member size each time TBMEMBER_Text changes.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_DomainString (CONST_STRPTR)<br />
: A text string based on which the minimum size of the member will be calculated. This is useful especially with TB_MTYPE_TEXTBOX members when you want to enforce a minimum size required to fit text of variable length. The domain string ought to be at least as long as the longest text to appear in the textbox.<br />
: The domain string is never rendered in the gadget.<br />
: This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_DomainString value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the member text. This tag overrides GA_TextAttr (see above).<br />
: You should generally use one "global" font for the toolbar, configured via GA_TextAttr. But there are situations where it makes sense to set a particular font at the member level, for example when using textbox members.<br />
: Defaults to NULL.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_Disabled (BOOL)<br />
: The current state (disabled or not disabled) of a member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Disabled value of such a member.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Hidden (BOOL)<br />
: Specifies whether the particular member is displayed in the toolbar or hidden. You can use this tag to create "dynamic" toolbar layouts that adapt the actual member set to various application settings.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Selected (BOOL)<br />
: The current selection state of a toggle member. This tag is not relevant to normal buttons (TB_MTYPE_BUTTON), spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Selected value of such a member.<br />
: You can set a target BOOPSI object for any toggle member, using the standard icclass ICA_TARGET tag. The target will receive an automatic notification of the toggle selection. This way toolbar toggles can easily communicate with other boolean gadgets such as checkboxes.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_NOTIFY, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Group (uint32)<br />
: Member group ID. Several members can be manipulated at once if they are assigned to the same group. Use TOOLBAR_SetGroup with the respective group ID to identify the group to be manipulated.<br />
: Defaults to TB_NO_ID (not assigned to any group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_MXGroup (uint32)<br />
: MX group ID. Toggle members can be put in groups of mutually-exclusive buttons. When such a toggle is selected, all other toggles in the same MX group will become deselected.<br />
: This tag is not relevant to normal buttons, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_MXGroup value of such a member.<br />
: Defaults to TB_NO_ID (not assigned to any MX group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_HintInfo (CONST_STRPTR)<br />
: The help text to be displayed when the user hovers the mouse pointer over the respective member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_HintInfo value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_UserData (APTR)<br />
: Arbitrary user data associated with this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
=== Image attributes ===<br />
<br />
; TBIMAGE_Image (struct Image *)<br />
: Custom image to be used for a button or a toggle member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_ImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImage (struct Image *)<br />
: Custom image to display when the member becomes selected.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the select image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
;TBIMAGE_Width (uint32)<br />
;TBIMAGE_Height (uint32)<br />
: Image dimensions, in pixels. These tags can only be used in connection with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the respective source file will be scaled to the specified width and height. Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot be resized using these tags.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW)<br />
<br />
== Notes ==<br />
<br />
Some of the attributes described above change the sizing requirements of the gadget. If set on the fly (i.e. when the toolbar is already displayed in the window), the gadget domain will need recalculating and a re-layout must take place. Refer to the [[#OM_SET|OM_SET]] method documentation below to see how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image. [[#Image attributes|Image attributes]] cannot be changed later.<br />
<br />
== Bugs ==<br />
<br />
== See also ==<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
; NAME<br />
: OM_SET -- set toolbar attributes<br />
<br />
; SYNOPSIS<br />
: uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
: uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win, struct Requester *req, Tag tag1, ...);<br />
<br />
; FUNCTION<br />
: This method sets the attributes of the toolbar and/or of its members. SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions to invoke this method.<br />
: To change a member attribute you first need to pass TOOLBAR_SetMember to identify the respective member, and then the member attribute tag(s). See the EXAMPLE section below.<br />
: To change an attribute collectively for a group of members you first need to pass TOOLBAR_SetGroup to identify the respective group, and then the member attribute tag(s). See the EXAMPLE section below.<br />
<br />
; INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
; RESULT<br />
: This method will return TB_NEED_RETHINK if the gadget ''believes'' that one or more of the attributes will change the sizing requirements of the toolbar. Typically, invoking the WM_RETHINK method on the gadget's window object is needed, in order to recalculate the domain and re-layout the contents.<br />
: If you know you will be changing an attribute that requires a WM_RETHINK, prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
: The method returns 0L if no rethink is needed.<br />
<br />
; EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, GROUP_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
; NAME<br />
: TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, uint32 attrID, uint32 *storage);<br />
<br />
; FUNCTION<br />
: Use this method to obtain the value of a given member attribute.<br />
: Because of the way OM_GET is implemented in Intuition, getting member attributes is done differently compared to setting them. The difference boils down to the following:<br />
:* We cannot use a convenience function such as GetAttr() or GetAttrs(), so a dedicated method is provided. Refer to the EXAMPLE section below to see how to invoke the method.<br />
:* Only one attribute can be queried at a time. (As multiple attributes will rarely be requested in real use, this limitation should not pose a significant problem.)<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
attrID -- the attribute tag identifier<br />
storage -- a pointer to the variable for storing the attribute value<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the requested attribute value has been obtained successfully. The attribute value itself is returned in the provided storage variable.<br />
<br />
; EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID, TBMEMBER_Selected, &storage);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_REFRESHMEMBER ===<br />
<br />
; NAME<br />
: TBM_REFRESHMEMBER -- refresh the imagery of a given member (V53.3)<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbRefreshMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, struct Window *window);<br />
<br />
; FUNCTION<br />
: Use this method to refresh the imagery of a given button or toggle member.<br />
: The method has no effect on spacers and separators.<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbRefreshMember structure<br />
<br />
For IDoMethod():<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_REFRESHMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
window -- a pointer to the window the toolbar resides in<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the refresh has taken place.<br />
<br />
; EXAMPLE<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1020ToolBar Gadget Class2021-01-04T20:57:22Z<p>Trixie: Updated TOOLBAR_TextPlace</p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Supported methods ==<br />
<br />
{| class="wikitable"<br />
!Method ID<br />
!Description<br />
|-<br />
|OM_NEW<br />
|creates the toolbar object, sets attributes and defaults<br />
|-<br />
|OM_DISPOSE<br />
|disposes of the toolbar object<br />
|-<br />
|OM_REMMEMBER<br />
|used by the class internally; consider this method private<br />
|-<br />
|OM_SET<br />
|sets toolbar, member and image attributes (see the [[#OM_SET|OM_SET]] section below for more information)<br />
|-<br />
|OM_GET<br />
|retrieves toolbar attributes<br />
|-<br />
|TBM_GETMEMBER<br />
|retrieves a given member attribute (see the [[#TBM_GETMEMBER|TBM_GETMEMBER]] section below for more information)<br />
|-<br />
|TBM_REFRESHMEMBER<br />
|refreshes the imagery of a given member (see the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] section below for more information)<br />
|}<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
; GA_ID (uint16)<br />
: Unique ID number for the gadget.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_ReadOnly (BOOL)<br />
: If set to TRUE, none of the toolbar buttons will be selectable.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_BackFill (struct Hook *)<br />
: A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
: Defaults to NULL (the default backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; GA_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the gadget members' text.<br />
: Defaults to the system's default public screen font.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Orientation (uint32)<br />
: The toolbar orientation: horizontal or vertical.<br />
: Defaults to TB_ORIENT_HORIZ<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_Spacing (uint32)<br />
: The spacing between the individual toolbar members, in pixels.<br />
: Defaults to 2<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HorizPadding<br />
; TOOLBAR_VertPadding (uint32)<br />
: The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_InnerPadding (uint32)<br />
: The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.<br />
: Defaults to 4<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HandleOverflow (BOOL)<br />
: Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_MinVisible (uint32)<br />
: If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
: Defaults to 1<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SpacerSize (uint32)<br />
: The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.<br />
: Defaults to 5<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ButtonStyle (uint32)<br />
: The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
: Defaults to TB_BUTSTYLE_CLASSIC<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BevelStyle (uint32)<br />
: The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:<br />
<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
: When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.<br />
: Defaults to BVS_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SeparatorStyle (uint32)<br />
: Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.<br />
: Defaults to TB_SEPSTYLE_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SelectionStyle (uint32)<br />
: Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.<br />
: This tag is ignored in the classic mode with framed buttons.<br />
: Defaults to TB_SELSTYLE_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BackFill (struct Hook *)<br />
: A custom backfill hook to provide a background filled with a specific colour or pattern.<br />
: This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.<br />
: Defaults to NULL (the default layers backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Display (uint32)<br />
: Specifies what you want to display inside the toolbar button or toggle members. The possible values are:<br />
<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
: Defaults to TB_DISPLAY_IMAGES<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_TextPlace (uint32)<br />
: Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH. Plus, it only affects button and toggle members.<br />
: Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_LabelArray (STRPTR *)<br />
: Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.<br />
: TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
: Using this tag, the limitation is that you cannot create toggle members (only buttons, separators and spacers).<br />
: A special string, " ", will create a spacer.<br />
: A special string, "_", will create a separator.<br />
: Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.<br />
: The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TOOLBAR_EvenSize (BOOL)<br />
: If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.<br />
: If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ImageSet (uint32)<br />
: If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in the toolbar. The value passed to this tag is the image set ID.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:<br />
<br />
; TOOLBAR_AddImageSet (uint32)<br />
: Creates a new image set. The value passed to this tag is a numeric ID identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to display the particular image set in the toolbar.<br />
: This tag should be followed by a sequence of TOOLBAR_AddImage tags (see below), each creating one image in the given set.<br />
: If the gadget only uses one set of images, passing TOOLBAR_AddImageSet is not necessary. Each TOOLBAR_AddImage will add the respective image to the default image set identified by an ID of 0.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddImage (uint32)<br />
: Creates a new image in a given image set. The value passed to this tag is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID (see below) to associate the image with a particular toolbar member.<br />
: This tag should be followed by a sequence of TBIMAGE_ tags (see the [[#Image attributes|Image attributes]] section below), each configuring one aspect of the image, including its optional selected variant (referred to as the "select image").<br />
: Images are added to the default image set unless a preceding TOOLBAR_AddImageSet specifies a different set.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddMember (uint32)<br />
: Creates a new toolbar member. The value passed to this tag is a numeric ID identifying the member.<br />
: Spacers and separators normally don't need an ID, so you can use TB_NO_ID as a value for TOOLBAR_AddMember when creating these members. However, if you want to manipulate spacers/separators in your GUI, an ID will be necessary so that you can pass it to TOOLBAR_SetMember to identify the respective spacer or separator member.<br />
: You can add members when the toolbar object is being created, i.e. as part of the NewObject() call, or at any time later via SetAttrs().<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetMember<br />
: Use this tag in a SetAttrs() call to identify the member you want to modify.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetGroup<br />
: Use this tag in a SetAttrs() call to identify the group of members you want to modify collectively.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
=== Member attributes ===<br />
<br />
; TBMEMBER_Type (uint32)<br />
: The type of the toolbar member. The possible values are the following:<br />
<br />
TB_MTYPE_BUTTON -- a normal toolbar button<br />
TB_MTYPE_TOGGLE -- a toggle (on/off) button<br />
TB_MTYPE_SPACER -- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
TB_MTYPE_TEXTBOX -- a read-only box to display text (V53.4)<br />
<br />
: The type is set upon member creation, and cannot be changed.<br />
: Defaults to TB_MTYPE_BUTTON<br />
: Applicability is (OM_NEW)<br />
<br />
; TBMEMBER_ImageID (uint32)<br />
: The identifier of the image to be used for the button or toggle member (see TOOLBAR_AddImage above). This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_ImageID value of such a member.<br />
: When [[#OM_SET|OM_SET]]-ing this attribute, the method will always return TB_NEED_RETHINK, to be on the safe side. However, invoking WM_RETHINK is really only needed if the size of the new image is different from the original image. If the size is the same, a simple gadget refresh will suffice. You can trigger the refresh:<br />
:* by setting this attribute via RefreshSetGadgetAttrs(), or<br />
:* by setting this attribute via SetAttrs() and then invoking the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method on the respective button/toggle member.<br />
: (The difference is that RefreshSetGadgetAttrs() will refresh the entire toolbar, while TBM_REFRESHMEMBER will only refresh the given member.)<br />
: Defaults to TB_NO_ID (no image associated with this member)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Text (CONST_STRPTR)<br />
: The text to associate with a button, toggle or textbox member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
: The text will be used as fallback in case no image is found or provided for a button or a toggle member.<br />
: The text string can contain an underscore character (_), indicating the keyboard shortcut for this member. (This doesn't apply to textbox members, as they are read-only and don't respond to the keyboard.)<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_DomainString (CONST_STRPTR)<br />
: A text string based on which the minimum size of the member will be calculated. This is useful especially with TB_MTYPE_TEXTBOX members when you want to enforce a minimum size required to fit text of variable length.<br />
: The domain string is never rendered in the gadget.<br />
: This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_DomainString value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the member text. This tag overrides GA_TextAttr (see above).<br />
: You should generally use one "global" font for the toolbar, configured via GA_TextAttr. But there are situations where it makes sense to set a particular font at the member level, for example when using textbox members.<br />
: Defaults to NULL.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_Disabled (BOOL)<br />
: The current state (disabled or not disabled) of a member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Disabled value of such a member.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Hidden (BOOL)<br />
: Specifies whether the particular member is displayed in the toolbar or hidden. You can use this tag to create "dynamic" toolbar layouts that adapt the actual member set to various application settings.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Selected (BOOL)<br />
: The current selection state of a toggle member. This tag is not relevant to normal buttons (TB_MTYPE_BUTTON), spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Selected value of such a member.<br />
: You can set a target BOOPSI object for any toggle member, using the standard icclass ICA_TARGET tag. The target will receive an automatic notification of the toggle selection. This way toolbar toggles can easily communicate with other boolean gadgets such as checkboxes.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_NOTIFY, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Group (uint32)<br />
: Member group ID. Several members can be manipulated at once if they are assigned to the same group. Use TOOLBAR_SetGroup with the respective group ID to identify the group to be manipulated.<br />
: Defaults to TB_NO_ID (not assigned to any group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_MXGroup (uint32)<br />
: MX group ID. Toggle members can be put in groups of mutually-exclusive buttons. When such a toggle is selected, all other toggles in the same MX group will become deselected.<br />
: This tag is not relevant to normal buttons, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_MXGroup value of such a member.<br />
: Defaults to TB_NO_ID (not assigned to any MX group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_HintInfo (CONST_STRPTR)<br />
: The help text to be displayed when the user hovers the mouse pointer over the respective member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_HintInfo value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_UserData (APTR)<br />
: Arbitrary user data associated with this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
=== Image attributes ===<br />
<br />
; TBIMAGE_Image (struct Image *)<br />
: Custom image to be used for a button or a toggle member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_ImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImage (struct Image *)<br />
: Custom image to display when the member becomes selected.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the select image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
;TBIMAGE_Width (uint32)<br />
;TBIMAGE_Height (uint32)<br />
: Image dimensions, in pixels. These tags can only be used in connection with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the respective source file will be scaled to the specified width and height. Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot be resized using these tags.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW)<br />
<br />
== Notes ==<br />
<br />
Some of the attributes described above change the sizing requirements of the gadget. If set on the fly (i.e. when the toolbar is already displayed in the window), the gadget domain will need recalculating and a re-layout must take place. Refer to the [[#OM_SET|OM_SET]] method documentation below to see how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image. [[#Image attributes|Image attributes]] cannot be changed later.<br />
<br />
== Bugs ==<br />
<br />
== See also ==<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
; NAME<br />
: OM_SET -- set toolbar attributes<br />
<br />
; SYNOPSIS<br />
: uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
: uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win, struct Requester *req, Tag tag1, ...);<br />
<br />
; FUNCTION<br />
: This method sets the attributes of the toolbar and/or of its members. SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions to invoke this method.<br />
: To change a member attribute you first need to pass TOOLBAR_SetMember to identify the respective member, and then the member attribute tag(s). See the EXAMPLE section below.<br />
: To change an attribute collectively for a group of members you first need to pass TOOLBAR_SetGroup to identify the respective group, and then the member attribute tag(s). See the EXAMPLE section below.<br />
<br />
; INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
; RESULT<br />
: This method will return TB_NEED_RETHINK if the gadget ''believes'' that one or more of the attributes will change the sizing requirements of the toolbar. Typically, invoking the WM_RETHINK method on the gadget's window object is needed, in order to recalculate the domain and re-layout the contents.<br />
: If you know you will be changing an attribute that requires a WM_RETHINK, prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
: The method returns 0L if no rethink is needed.<br />
<br />
; EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, GROUP_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
; NAME<br />
: TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, uint32 attrID, uint32 *storage);<br />
<br />
; FUNCTION<br />
: Use this method to obtain the value of a given member attribute.<br />
: Because of the way OM_GET is implemented in Intuition, getting member attributes is done differently compared to setting them. The difference boils down to the following:<br />
:* We cannot use a convenience function such as GetAttr() or GetAttrs(), so a dedicated method is provided. Refer to the EXAMPLE section below to see how to invoke the method.<br />
:* Only one attribute can be queried at a time. (As multiple attributes will rarely be requested in real use, this limitation should not pose a significant problem.)<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
attrID -- the attribute tag identifier<br />
storage -- a pointer to the variable for storing the attribute value<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the requested attribute value has been obtained successfully. The attribute value itself is returned in the provided storage variable.<br />
<br />
; EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID, TBMEMBER_Selected, &storage);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_REFRESHMEMBER ===<br />
<br />
; NAME<br />
: TBM_REFRESHMEMBER -- refresh the imagery of a given member (V53.3)<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbRefreshMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, struct Window *window);<br />
<br />
; FUNCTION<br />
: Use this method to refresh the imagery of a given button or toggle member.<br />
: The method has no effect on spacers and separators.<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbRefreshMember structure<br />
<br />
For IDoMethod():<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_REFRESHMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
window -- a pointer to the window the toolbar resides in<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the refresh has taken place.<br />
<br />
; EXAMPLE<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1019ToolBar Gadget Class2021-01-02T21:19:16Z<p>Trixie: Updated TBMEMBER_Text.</p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Supported methods ==<br />
<br />
{| class="wikitable"<br />
!Method ID<br />
!Description<br />
|-<br />
|OM_NEW<br />
|creates the toolbar object, sets attributes and defaults<br />
|-<br />
|OM_DISPOSE<br />
|disposes of the toolbar object<br />
|-<br />
|OM_REMMEMBER<br />
|used by the class internally; consider this method private<br />
|-<br />
|OM_SET<br />
|sets toolbar, member and image attributes (see the [[#OM_SET|OM_SET]] section below for more information)<br />
|-<br />
|OM_GET<br />
|retrieves toolbar attributes<br />
|-<br />
|TBM_GETMEMBER<br />
|retrieves a given member attribute (see the [[#TBM_GETMEMBER|TBM_GETMEMBER]] section below for more information)<br />
|-<br />
|TBM_REFRESHMEMBER<br />
|refreshes the imagery of a given member (see the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] section below for more information)<br />
|}<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
; GA_ID (uint16)<br />
: Unique ID number for the gadget.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_ReadOnly (BOOL)<br />
: If set to TRUE, none of the toolbar buttons will be selectable.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_BackFill (struct Hook *)<br />
: A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
: Defaults to NULL (the default backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; GA_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the gadget members' text.<br />
: Defaults to the system's default public screen font.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Orientation (uint32)<br />
: The toolbar orientation: horizontal or vertical.<br />
: Defaults to TB_ORIENT_HORIZ<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_Spacing (uint32)<br />
: The spacing between the individual toolbar members, in pixels.<br />
: Defaults to 2<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HorizPadding<br />
; TOOLBAR_VertPadding (uint32)<br />
: The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_InnerPadding (uint32)<br />
: The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.<br />
: Defaults to 4<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HandleOverflow (BOOL)<br />
: Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_MinVisible (uint32)<br />
: If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
: Defaults to 1<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SpacerSize (uint32)<br />
: The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.<br />
: Defaults to 5<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ButtonStyle (uint32)<br />
: The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
: Defaults to TB_BUTSTYLE_CLASSIC<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BevelStyle (uint32)<br />
: The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:<br />
<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
: When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.<br />
: Defaults to BVS_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SeparatorStyle (uint32)<br />
: Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.<br />
: Defaults to TB_SEPSTYLE_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SelectionStyle (uint32)<br />
: Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.<br />
: This tag is ignored in the classic mode with framed buttons.<br />
: Defaults to TB_SELSTYLE_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BackFill (struct Hook *)<br />
: A custom backfill hook to provide a background filled with a specific colour or pattern.<br />
: This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.<br />
: Defaults to NULL (the default layers backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Display (uint32)<br />
: Specifies what you want to display inside the toolbar button or toggle members. The possible values are:<br />
<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
: Defaults to TB_DISPLAY_IMAGES<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_TextPlace (uint32)<br />
: Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_LabelArray (STRPTR *)<br />
: Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.<br />
: TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
: Using this tag, the limitation is that you cannot create toggle members (only buttons, separators and spacers).<br />
: A special string, " ", will create a spacer.<br />
: A special string, "_", will create a separator.<br />
: Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.<br />
: The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TOOLBAR_EvenSize (BOOL)<br />
: If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.<br />
: If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ImageSet (uint32)<br />
: If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in the toolbar. The value passed to this tag is the image set ID.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:<br />
<br />
; TOOLBAR_AddImageSet (uint32)<br />
: Creates a new image set. The value passed to this tag is a numeric ID identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to display the particular image set in the toolbar.<br />
: This tag should be followed by a sequence of TOOLBAR_AddImage tags (see below), each creating one image in the given set.<br />
: If the gadget only uses one set of images, passing TOOLBAR_AddImageSet is not necessary. Each TOOLBAR_AddImage will add the respective image to the default image set identified by an ID of 0.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddImage (uint32)<br />
: Creates a new image in a given image set. The value passed to this tag is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID (see below) to associate the image with a particular toolbar member.<br />
: This tag should be followed by a sequence of TBIMAGE_ tags (see the [[#Image attributes|Image attributes]] section below), each configuring one aspect of the image, including its optional selected variant (referred to as the "select image").<br />
: Images are added to the default image set unless a preceding TOOLBAR_AddImageSet specifies a different set.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddMember (uint32)<br />
: Creates a new toolbar member. The value passed to this tag is a numeric ID identifying the member.<br />
: Spacers and separators normally don't need an ID, so you can use TB_NO_ID as a value for TOOLBAR_AddMember when creating these members. However, if you want to manipulate spacers/separators in your GUI, an ID will be necessary so that you can pass it to TOOLBAR_SetMember to identify the respective spacer or separator member.<br />
: You can add members when the toolbar object is being created, i.e. as part of the NewObject() call, or at any time later via SetAttrs().<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetMember<br />
: Use this tag in a SetAttrs() call to identify the member you want to modify.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetGroup<br />
: Use this tag in a SetAttrs() call to identify the group of members you want to modify collectively.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
=== Member attributes ===<br />
<br />
; TBMEMBER_Type (uint32)<br />
: The type of the toolbar member. The possible values are the following:<br />
<br />
TB_MTYPE_BUTTON -- a normal toolbar button<br />
TB_MTYPE_TOGGLE -- a toggle (on/off) button<br />
TB_MTYPE_SPACER -- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
TB_MTYPE_TEXTBOX -- a read-only box to display text (V53.4)<br />
<br />
: The type is set upon member creation, and cannot be changed.<br />
: Defaults to TB_MTYPE_BUTTON<br />
: Applicability is (OM_NEW)<br />
<br />
; TBMEMBER_ImageID (uint32)<br />
: The identifier of the image to be used for the button or toggle member (see TOOLBAR_AddImage above). This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_ImageID value of such a member.<br />
: When [[#OM_SET|OM_SET]]-ing this attribute, the method will always return TB_NEED_RETHINK, to be on the safe side. However, invoking WM_RETHINK is really only needed if the size of the new image is different from the original image. If the size is the same, a simple gadget refresh will suffice. You can trigger the refresh:<br />
:* by setting this attribute via RefreshSetGadgetAttrs(), or<br />
:* by setting this attribute via SetAttrs() and then invoking the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method on the respective button/toggle member.<br />
: (The difference is that RefreshSetGadgetAttrs() will refresh the entire toolbar, while TBM_REFRESHMEMBER will only refresh the given member.)<br />
: Defaults to TB_NO_ID (no image associated with this member)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Text (CONST_STRPTR)<br />
: The text to associate with a button, toggle or textbox member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
: The text will be used as fallback in case no image is found or provided for a button or a toggle member.<br />
: The text string can contain an underscore character (_), indicating the keyboard shortcut for this member. (This doesn't apply to textbox members, as they are read-only and don't respond to the keyboard.)<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_DomainString (CONST_STRPTR)<br />
: A text string based on which the minimum size of the member will be calculated. This is useful especially with TB_MTYPE_TEXTBOX members when you want to enforce a minimum size required to fit text of variable length.<br />
: The domain string is never rendered in the gadget.<br />
: This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_DomainString value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the member text. This tag overrides GA_TextAttr (see above).<br />
: You should generally use one "global" font for the toolbar, configured via GA_TextAttr. But there are situations where it makes sense to set a particular font at the member level, for example when using textbox members.<br />
: Defaults to NULL.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_Disabled (BOOL)<br />
: The current state (disabled or not disabled) of a member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Disabled value of such a member.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Hidden (BOOL)<br />
: Specifies whether the particular member is displayed in the toolbar or hidden. You can use this tag to create "dynamic" toolbar layouts that adapt the actual member set to various application settings.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Selected (BOOL)<br />
: The current selection state of a toggle member. This tag is not relevant to normal buttons (TB_MTYPE_BUTTON), spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Selected value of such a member.<br />
: You can set a target BOOPSI object for any toggle member, using the standard icclass ICA_TARGET tag. The target will receive an automatic notification of the toggle selection. This way toolbar toggles can easily communicate with other boolean gadgets such as checkboxes.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_NOTIFY, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Group (uint32)<br />
: Member group ID. Several members can be manipulated at once if they are assigned to the same group. Use TOOLBAR_SetGroup with the respective group ID to identify the group to be manipulated.<br />
: Defaults to TB_NO_ID (not assigned to any group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_MXGroup (uint32)<br />
: MX group ID. Toggle members can be put in groups of mutually-exclusive buttons. When such a toggle is selected, all other toggles in the same MX group will become deselected.<br />
: This tag is not relevant to normal buttons, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_MXGroup value of such a member.<br />
: Defaults to TB_NO_ID (not assigned to any MX group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_HintInfo (CONST_STRPTR)<br />
: The help text to be displayed when the user hovers the mouse pointer over the respective member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_HintInfo value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_UserData (APTR)<br />
: Arbitrary user data associated with this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
=== Image attributes ===<br />
<br />
; TBIMAGE_Image (struct Image *)<br />
: Custom image to be used for a button or a toggle member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_ImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImage (struct Image *)<br />
: Custom image to display when the member becomes selected.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the select image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
;TBIMAGE_Width (uint32)<br />
;TBIMAGE_Height (uint32)<br />
: Image dimensions, in pixels. These tags can only be used in connection with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the respective source file will be scaled to the specified width and height. Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot be resized using these tags.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW)<br />
<br />
== Notes ==<br />
<br />
Some of the attributes described above change the sizing requirements of the gadget. If set on the fly (i.e. when the toolbar is already displayed in the window), the gadget domain will need recalculating and a re-layout must take place. Refer to the [[#OM_SET|OM_SET]] method documentation below to see how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image. [[#Image attributes|Image attributes]] cannot be changed later.<br />
<br />
== Bugs ==<br />
<br />
== See also ==<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
; NAME<br />
: OM_SET -- set toolbar attributes<br />
<br />
; SYNOPSIS<br />
: uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
: uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win, struct Requester *req, Tag tag1, ...);<br />
<br />
; FUNCTION<br />
: This method sets the attributes of the toolbar and/or of its members. SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions to invoke this method.<br />
: To change a member attribute you first need to pass TOOLBAR_SetMember to identify the respective member, and then the member attribute tag(s). See the EXAMPLE section below.<br />
: To change an attribute collectively for a group of members you first need to pass TOOLBAR_SetGroup to identify the respective group, and then the member attribute tag(s). See the EXAMPLE section below.<br />
<br />
; INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
; RESULT<br />
: This method will return TB_NEED_RETHINK if the gadget ''believes'' that one or more of the attributes will change the sizing requirements of the toolbar. Typically, invoking the WM_RETHINK method on the gadget's window object is needed, in order to recalculate the domain and re-layout the contents.<br />
: If you know you will be changing an attribute that requires a WM_RETHINK, prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
: The method returns 0L if no rethink is needed.<br />
<br />
; EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, GROUP_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
; NAME<br />
: TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, uint32 attrID, uint32 *storage);<br />
<br />
; FUNCTION<br />
: Use this method to obtain the value of a given member attribute.<br />
: Because of the way OM_GET is implemented in Intuition, getting member attributes is done differently compared to setting them. The difference boils down to the following:<br />
:* We cannot use a convenience function such as GetAttr() or GetAttrs(), so a dedicated method is provided. Refer to the EXAMPLE section below to see how to invoke the method.<br />
:* Only one attribute can be queried at a time. (As multiple attributes will rarely be requested in real use, this limitation should not pose a significant problem.)<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
attrID -- the attribute tag identifier<br />
storage -- a pointer to the variable for storing the attribute value<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the requested attribute value has been obtained successfully. The attribute value itself is returned in the provided storage variable.<br />
<br />
; EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID, TBMEMBER_Selected, &storage);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_REFRESHMEMBER ===<br />
<br />
; NAME<br />
: TBM_REFRESHMEMBER -- refresh the imagery of a given member (V53.3)<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbRefreshMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, struct Window *window);<br />
<br />
; FUNCTION<br />
: Use this method to refresh the imagery of a given button or toggle member.<br />
: The method has no effect on spacers and separators.<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbRefreshMember structure<br />
<br />
For IDoMethod():<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_REFRESHMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
window -- a pointer to the window the toolbar resides in<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the refresh has taken place.<br />
<br />
; EXAMPLE<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1018ToolBar Gadget Class2021-01-02T20:59:11Z<p>Trixie: Added documentation for TBMEMBER_TextAttr.</p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Supported methods ==<br />
<br />
{| class="wikitable"<br />
!Method ID<br />
!Description<br />
|-<br />
|OM_NEW<br />
|creates the toolbar object, sets attributes and defaults<br />
|-<br />
|OM_DISPOSE<br />
|disposes of the toolbar object<br />
|-<br />
|OM_REMMEMBER<br />
|used by the class internally; consider this method private<br />
|-<br />
|OM_SET<br />
|sets toolbar, member and image attributes (see the [[#OM_SET|OM_SET]] section below for more information)<br />
|-<br />
|OM_GET<br />
|retrieves toolbar attributes<br />
|-<br />
|TBM_GETMEMBER<br />
|retrieves a given member attribute (see the [[#TBM_GETMEMBER|TBM_GETMEMBER]] section below for more information)<br />
|-<br />
|TBM_REFRESHMEMBER<br />
|refreshes the imagery of a given member (see the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] section below for more information)<br />
|}<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
; GA_ID (uint16)<br />
: Unique ID number for the gadget.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_ReadOnly (BOOL)<br />
: If set to TRUE, none of the toolbar buttons will be selectable.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_BackFill (struct Hook *)<br />
: A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
: Defaults to NULL (the default backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; GA_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the gadget members' text.<br />
: Defaults to the system's default public screen font.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Orientation (uint32)<br />
: The toolbar orientation: horizontal or vertical.<br />
: Defaults to TB_ORIENT_HORIZ<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_Spacing (uint32)<br />
: The spacing between the individual toolbar members, in pixels.<br />
: Defaults to 2<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HorizPadding<br />
; TOOLBAR_VertPadding (uint32)<br />
: The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_InnerPadding (uint32)<br />
: The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.<br />
: Defaults to 4<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HandleOverflow (BOOL)<br />
: Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_MinVisible (uint32)<br />
: If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
: Defaults to 1<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SpacerSize (uint32)<br />
: The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.<br />
: Defaults to 5<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ButtonStyle (uint32)<br />
: The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
: Defaults to TB_BUTSTYLE_CLASSIC<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BevelStyle (uint32)<br />
: The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:<br />
<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
: When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.<br />
: Defaults to BVS_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SeparatorStyle (uint32)<br />
: Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.<br />
: Defaults to TB_SEPSTYLE_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SelectionStyle (uint32)<br />
: Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.<br />
: This tag is ignored in the classic mode with framed buttons.<br />
: Defaults to TB_SELSTYLE_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BackFill (struct Hook *)<br />
: A custom backfill hook to provide a background filled with a specific colour or pattern.<br />
: This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.<br />
: Defaults to NULL (the default layers backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Display (uint32)<br />
: Specifies what you want to display inside the toolbar button or toggle members. The possible values are:<br />
<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
: Defaults to TB_DISPLAY_IMAGES<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_TextPlace (uint32)<br />
: Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_LabelArray (STRPTR *)<br />
: Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.<br />
: TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
: Using this tag, the limitation is that you cannot create toggle members (only buttons, separators and spacers).<br />
: A special string, " ", will create a spacer.<br />
: A special string, "_", will create a separator.<br />
: Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.<br />
: The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TOOLBAR_EvenSize (BOOL)<br />
: If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.<br />
: If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ImageSet (uint32)<br />
: If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in the toolbar. The value passed to this tag is the image set ID.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:<br />
<br />
; TOOLBAR_AddImageSet (uint32)<br />
: Creates a new image set. The value passed to this tag is a numeric ID identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to display the particular image set in the toolbar.<br />
: This tag should be followed by a sequence of TOOLBAR_AddImage tags (see below), each creating one image in the given set.<br />
: If the gadget only uses one set of images, passing TOOLBAR_AddImageSet is not necessary. Each TOOLBAR_AddImage will add the respective image to the default image set identified by an ID of 0.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddImage (uint32)<br />
: Creates a new image in a given image set. The value passed to this tag is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID (see below) to associate the image with a particular toolbar member.<br />
: This tag should be followed by a sequence of TBIMAGE_ tags (see the [[#Image attributes|Image attributes]] section below), each configuring one aspect of the image, including its optional selected variant (referred to as the "select image").<br />
: Images are added to the default image set unless a preceding TOOLBAR_AddImageSet specifies a different set.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddMember (uint32)<br />
: Creates a new toolbar member. The value passed to this tag is a numeric ID identifying the member.<br />
: Spacers and separators normally don't need an ID, so you can use TB_NO_ID as a value for TOOLBAR_AddMember when creating these members. However, if you want to manipulate spacers/separators in your GUI, an ID will be necessary so that you can pass it to TOOLBAR_SetMember to identify the respective spacer or separator member.<br />
: You can add members when the toolbar object is being created, i.e. as part of the NewObject() call, or at any time later via SetAttrs().<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetMember<br />
: Use this tag in a SetAttrs() call to identify the member you want to modify.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetGroup<br />
: Use this tag in a SetAttrs() call to identify the group of members you want to modify collectively.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
=== Member attributes ===<br />
<br />
; TBMEMBER_Type (uint32)<br />
: The type of the toolbar member. The possible values are the following:<br />
<br />
TB_MTYPE_BUTTON -- a normal toolbar button<br />
TB_MTYPE_TOGGLE -- a toggle (on/off) button<br />
TB_MTYPE_SPACER -- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
TB_MTYPE_TEXTBOX -- a read-only box to display text (V53.4)<br />
<br />
: The type is set upon member creation, and cannot be changed.<br />
: Defaults to TB_MTYPE_BUTTON<br />
: Applicability is (OM_NEW)<br />
<br />
; TBMEMBER_ImageID (uint32)<br />
: The identifier of the image to be used for the button or toggle member (see TOOLBAR_AddImage above). This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_ImageID value of such a member.<br />
: When [[#OM_SET|OM_SET]]-ing this attribute, the method will always return TB_NEED_RETHINK, to be on the safe side. However, invoking WM_RETHINK is really only needed if the size of the new image is different from the original image. If the size is the same, a simple gadget refresh will suffice. You can trigger the refresh:<br />
:* by setting this attribute via RefreshSetGadgetAttrs(), or<br />
:* by setting this attribute via SetAttrs() and then invoking the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method on the respective button/toggle member.<br />
: (The difference is that RefreshSetGadgetAttrs() will refresh the entire toolbar, while TBM_REFRESHMEMBER will only refresh the given member.)<br />
: Defaults to TB_NO_ID (no image associated with this member)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Text (CONST_STRPTR)<br />
: The label to associate with a button or a toggle member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
: The text label will be used as fallback in case no image is found or provided.<br />
: The text string can contain an underscore character (_), indicating the keyboard shortcut for this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_DomainString (CONST_STRPTR)<br />
: A text string based on which the minimum size of the member will be calculated. This is useful especially with TB_MTYPE_TEXTBOX members when you want to enforce a minimum size required to fit text of variable length.<br />
: The domain string is never rendered in the gadget.<br />
: This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_DomainString value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the member text. This tag overrides GA_TextAttr (see above).<br />
: You should generally use one "global" font for the toolbar, configured via GA_TextAttr. But there are situations where it makes sense to set a particular font at the member level, for example when using textbox members.<br />
: Defaults to NULL.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TBMEMBER_Disabled (BOOL)<br />
: The current state (disabled or not disabled) of a member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Disabled value of such a member.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Hidden (BOOL)<br />
: Specifies whether the particular member is displayed in the toolbar or hidden. You can use this tag to create "dynamic" toolbar layouts that adapt the actual member set to various application settings.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Selected (BOOL)<br />
: The current selection state of a toggle member. This tag is not relevant to normal buttons (TB_MTYPE_BUTTON), spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Selected value of such a member.<br />
: You can set a target BOOPSI object for any toggle member, using the standard icclass ICA_TARGET tag. The target will receive an automatic notification of the toggle selection. This way toolbar toggles can easily communicate with other boolean gadgets such as checkboxes.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_NOTIFY, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Group (uint32)<br />
: Member group ID. Several members can be manipulated at once if they are assigned to the same group. Use TOOLBAR_SetGroup with the respective group ID to identify the group to be manipulated.<br />
: Defaults to TB_NO_ID (not assigned to any group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_MXGroup (uint32)<br />
: MX group ID. Toggle members can be put in groups of mutually-exclusive buttons. When such a toggle is selected, all other toggles in the same MX group will become deselected.<br />
: This tag is not relevant to normal buttons, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_MXGroup value of such a member.<br />
: Defaults to TB_NO_ID (not assigned to any MX group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_HintInfo (CONST_STRPTR)<br />
: The help text to be displayed when the user hovers the mouse pointer over the respective member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_HintInfo value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_UserData (APTR)<br />
: Arbitrary user data associated with this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
=== Image attributes ===<br />
<br />
; TBIMAGE_Image (struct Image *)<br />
: Custom image to be used for a button or a toggle member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_ImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImage (struct Image *)<br />
: Custom image to display when the member becomes selected.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the select image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
;TBIMAGE_Width (uint32)<br />
;TBIMAGE_Height (uint32)<br />
: Image dimensions, in pixels. These tags can only be used in connection with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the respective source file will be scaled to the specified width and height. Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot be resized using these tags.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW)<br />
<br />
== Notes ==<br />
<br />
Some of the attributes described above change the sizing requirements of the gadget. If set on the fly (i.e. when the toolbar is already displayed in the window), the gadget domain will need recalculating and a re-layout must take place. Refer to the [[#OM_SET|OM_SET]] method documentation below to see how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image. [[#Image attributes|Image attributes]] cannot be changed later.<br />
<br />
== Bugs ==<br />
<br />
== See also ==<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
; NAME<br />
: OM_SET -- set toolbar attributes<br />
<br />
; SYNOPSIS<br />
: uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
: uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win, struct Requester *req, Tag tag1, ...);<br />
<br />
; FUNCTION<br />
: This method sets the attributes of the toolbar and/or of its members. SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions to invoke this method.<br />
: To change a member attribute you first need to pass TOOLBAR_SetMember to identify the respective member, and then the member attribute tag(s). See the EXAMPLE section below.<br />
: To change an attribute collectively for a group of members you first need to pass TOOLBAR_SetGroup to identify the respective group, and then the member attribute tag(s). See the EXAMPLE section below.<br />
<br />
; INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
; RESULT<br />
: This method will return TB_NEED_RETHINK if the gadget ''believes'' that one or more of the attributes will change the sizing requirements of the toolbar. Typically, invoking the WM_RETHINK method on the gadget's window object is needed, in order to recalculate the domain and re-layout the contents.<br />
: If you know you will be changing an attribute that requires a WM_RETHINK, prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
: The method returns 0L if no rethink is needed.<br />
<br />
; EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, GROUP_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
; NAME<br />
: TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, uint32 attrID, uint32 *storage);<br />
<br />
; FUNCTION<br />
: Use this method to obtain the value of a given member attribute.<br />
: Because of the way OM_GET is implemented in Intuition, getting member attributes is done differently compared to setting them. The difference boils down to the following:<br />
:* We cannot use a convenience function such as GetAttr() or GetAttrs(), so a dedicated method is provided. Refer to the EXAMPLE section below to see how to invoke the method.<br />
:* Only one attribute can be queried at a time. (As multiple attributes will rarely be requested in real use, this limitation should not pose a significant problem.)<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
attrID -- the attribute tag identifier<br />
storage -- a pointer to the variable for storing the attribute value<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the requested attribute value has been obtained successfully. The attribute value itself is returned in the provided storage variable.<br />
<br />
; EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID, TBMEMBER_Selected, &storage);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_REFRESHMEMBER ===<br />
<br />
; NAME<br />
: TBM_REFRESHMEMBER -- refresh the imagery of a given member (V53.3)<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbRefreshMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, struct Window *window);<br />
<br />
; FUNCTION<br />
: Use this method to refresh the imagery of a given button or toggle member.<br />
: The method has no effect on spacers and separators.<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbRefreshMember structure<br />
<br />
For IDoMethod():<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_REFRESHMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
window -- a pointer to the window the toolbar resides in<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the refresh has taken place.<br />
<br />
; EXAMPLE<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1017ToolBar Gadget Class2021-01-02T14:02:46Z<p>Trixie: Added TBMEMBER_DomainString documentation. Updated GA_TextAttr and TBMEMBER_Type.</p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Supported methods ==<br />
<br />
{| class="wikitable"<br />
!Method ID<br />
!Description<br />
|-<br />
|OM_NEW<br />
|creates the toolbar object, sets attributes and defaults<br />
|-<br />
|OM_DISPOSE<br />
|disposes of the toolbar object<br />
|-<br />
|OM_REMMEMBER<br />
|used by the class internally; consider this method private<br />
|-<br />
|OM_SET<br />
|sets toolbar, member and image attributes (see the [[#OM_SET|OM_SET]] section below for more information)<br />
|-<br />
|OM_GET<br />
|retrieves toolbar attributes<br />
|-<br />
|TBM_GETMEMBER<br />
|retrieves a given member attribute (see the [[#TBM_GETMEMBER|TBM_GETMEMBER]] section below for more information)<br />
|-<br />
|TBM_REFRESHMEMBER<br />
|refreshes the imagery of a given member (see the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] section below for more information)<br />
|}<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
; GA_ID (uint16)<br />
: Unique ID number for the gadget.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_ReadOnly (BOOL)<br />
: If set to TRUE, none of the toolbar buttons will be selectable.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_BackFill (struct Hook *)<br />
: A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
: Defaults to NULL (the default backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; GA_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the gadget members' text.<br />
: Defaults to the system's default public screen font.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Orientation (uint32)<br />
: The toolbar orientation: horizontal or vertical.<br />
: Defaults to TB_ORIENT_HORIZ<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_Spacing (uint32)<br />
: The spacing between the individual toolbar members, in pixels.<br />
: Defaults to 2<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HorizPadding<br />
; TOOLBAR_VertPadding (uint32)<br />
: The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_InnerPadding (uint32)<br />
: The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.<br />
: Defaults to 4<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HandleOverflow (BOOL)<br />
: Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_MinVisible (uint32)<br />
: If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
: Defaults to 1<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SpacerSize (uint32)<br />
: The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.<br />
: Defaults to 5<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ButtonStyle (uint32)<br />
: The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
: Defaults to TB_BUTSTYLE_CLASSIC<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BevelStyle (uint32)<br />
: The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:<br />
<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
: When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.<br />
: Defaults to BVS_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SeparatorStyle (uint32)<br />
: Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.<br />
: Defaults to TB_SEPSTYLE_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SelectionStyle (uint32)<br />
: Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.<br />
: This tag is ignored in the classic mode with framed buttons.<br />
: Defaults to TB_SELSTYLE_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BackFill (struct Hook *)<br />
: A custom backfill hook to provide a background filled with a specific colour or pattern.<br />
: This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.<br />
: Defaults to NULL (the default layers backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Display (uint32)<br />
: Specifies what you want to display inside the toolbar button or toggle members. The possible values are:<br />
<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
: Defaults to TB_DISPLAY_IMAGES<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_TextPlace (uint32)<br />
: Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_LabelArray (STRPTR *)<br />
: Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.<br />
: TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
: Using this tag, the limitation is that you cannot create toggle members (only buttons, separators and spacers).<br />
: A special string, " ", will create a spacer.<br />
: A special string, "_", will create a separator.<br />
: Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.<br />
: The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TOOLBAR_EvenSize (BOOL)<br />
: If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.<br />
: If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ImageSet (uint32)<br />
: If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in the toolbar. The value passed to this tag is the image set ID.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:<br />
<br />
; TOOLBAR_AddImageSet (uint32)<br />
: Creates a new image set. The value passed to this tag is a numeric ID identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to display the particular image set in the toolbar.<br />
: This tag should be followed by a sequence of TOOLBAR_AddImage tags (see below), each creating one image in the given set.<br />
: If the gadget only uses one set of images, passing TOOLBAR_AddImageSet is not necessary. Each TOOLBAR_AddImage will add the respective image to the default image set identified by an ID of 0.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddImage (uint32)<br />
: Creates a new image in a given image set. The value passed to this tag is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID (see below) to associate the image with a particular toolbar member.<br />
: This tag should be followed by a sequence of TBIMAGE_ tags (see the [[#Image attributes|Image attributes]] section below), each configuring one aspect of the image, including its optional selected variant (referred to as the "select image").<br />
: Images are added to the default image set unless a preceding TOOLBAR_AddImageSet specifies a different set.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddMember (uint32)<br />
: Creates a new toolbar member. The value passed to this tag is a numeric ID identifying the member.<br />
: Spacers and separators normally don't need an ID, so you can use TB_NO_ID as a value for TOOLBAR_AddMember when creating these members. However, if you want to manipulate spacers/separators in your GUI, an ID will be necessary so that you can pass it to TOOLBAR_SetMember to identify the respective spacer or separator member.<br />
: You can add members when the toolbar object is being created, i.e. as part of the NewObject() call, or at any time later via SetAttrs().<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetMember<br />
: Use this tag in a SetAttrs() call to identify the member you want to modify.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetGroup<br />
: Use this tag in a SetAttrs() call to identify the group of members you want to modify collectively.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
=== Member attributes ===<br />
<br />
; TBMEMBER_Type (uint32)<br />
: The type of the toolbar member. The possible values are the following:<br />
<br />
TB_MTYPE_BUTTON -- a normal toolbar button<br />
TB_MTYPE_TOGGLE -- a toggle (on/off) button<br />
TB_MTYPE_SPACER -- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
TB_MTYPE_TEXTBOX -- a read-only box to display text (V53.4)<br />
<br />
: The type is set upon member creation, and cannot be changed.<br />
: Defaults to TB_MTYPE_BUTTON<br />
: Applicability is (OM_NEW)<br />
<br />
; TBMEMBER_ImageID (uint32)<br />
: The identifier of the image to be used for the button or toggle member (see TOOLBAR_AddImage above). This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_ImageID value of such a member.<br />
: When [[#OM_SET|OM_SET]]-ing this attribute, the method will always return TB_NEED_RETHINK, to be on the safe side. However, invoking WM_RETHINK is really only needed if the size of the new image is different from the original image. If the size is the same, a simple gadget refresh will suffice. You can trigger the refresh:<br />
:* by setting this attribute via RefreshSetGadgetAttrs(), or<br />
:* by setting this attribute via SetAttrs() and then invoking the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method on the respective button/toggle member.<br />
: (The difference is that RefreshSetGadgetAttrs() will refresh the entire toolbar, while TBM_REFRESHMEMBER will only refresh the given member.)<br />
: Defaults to TB_NO_ID (no image associated with this member)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Text (CONST_STRPTR)<br />
: The label to associate with a button or a toggle member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
: The text label will be used as fallback in case no image is found or provided.<br />
: The text string can contain an underscore character (_), indicating the keyboard shortcut for this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_DomainString (CONST_STRPTR)<br />
: A text string based on which the minimum size of the member will be calculated. This is useful especially with TB_MTYPE_TEXTBOX members when you want to enforce a minimum size required to fit text of variable length.<br />
: The domain string is never rendered in the gadget.<br />
: This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_DomainString value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Disabled (BOOL)<br />
: The current state (disabled or not disabled) of a member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Disabled value of such a member.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Hidden (BOOL)<br />
: Specifies whether the particular member is displayed in the toolbar or hidden. You can use this tag to create "dynamic" toolbar layouts that adapt the actual member set to various application settings.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Selected (BOOL)<br />
: The current selection state of a toggle member. This tag is not relevant to normal buttons (TB_MTYPE_BUTTON), spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Selected value of such a member.<br />
: You can set a target BOOPSI object for any toggle member, using the standard icclass ICA_TARGET tag. The target will receive an automatic notification of the toggle selection. This way toolbar toggles can easily communicate with other boolean gadgets such as checkboxes.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_NOTIFY, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Group (uint32)<br />
: Member group ID. Several members can be manipulated at once if they are assigned to the same group. Use TOOLBAR_SetGroup with the respective group ID to identify the group to be manipulated.<br />
: Defaults to TB_NO_ID (not assigned to any group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_MXGroup (uint32)<br />
: MX group ID. Toggle members can be put in groups of mutually-exclusive buttons. When such a toggle is selected, all other toggles in the same MX group will become deselected.<br />
: This tag is not relevant to normal buttons, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_MXGroup value of such a member.<br />
: Defaults to TB_NO_ID (not assigned to any MX group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_HintInfo (CONST_STRPTR)<br />
: The help text to be displayed when the user hovers the mouse pointer over the respective member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_HintInfo value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_UserData (APTR)<br />
: Arbitrary user data associated with this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
=== Image attributes ===<br />
<br />
; TBIMAGE_Image (struct Image *)<br />
: Custom image to be used for a button or a toggle member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_ImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImage (struct Image *)<br />
: Custom image to display when the member becomes selected.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the select image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
;TBIMAGE_Width (uint32)<br />
;TBIMAGE_Height (uint32)<br />
: Image dimensions, in pixels. These tags can only be used in connection with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the respective source file will be scaled to the specified width and height. Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot be resized using these tags.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW)<br />
<br />
== Notes ==<br />
<br />
Some of the attributes described above change the sizing requirements of the gadget. If set on the fly (i.e. when the toolbar is already displayed in the window), the gadget domain will need recalculating and a re-layout must take place. Refer to the [[#OM_SET|OM_SET]] method documentation below to see how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image. [[#Image attributes|Image attributes]] cannot be changed later.<br />
<br />
== Bugs ==<br />
<br />
== See also ==<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
; NAME<br />
: OM_SET -- set toolbar attributes<br />
<br />
; SYNOPSIS<br />
: uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
: uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win, struct Requester *req, Tag tag1, ...);<br />
<br />
; FUNCTION<br />
: This method sets the attributes of the toolbar and/or of its members. SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions to invoke this method.<br />
: To change a member attribute you first need to pass TOOLBAR_SetMember to identify the respective member, and then the member attribute tag(s). See the EXAMPLE section below.<br />
: To change an attribute collectively for a group of members you first need to pass TOOLBAR_SetGroup to identify the respective group, and then the member attribute tag(s). See the EXAMPLE section below.<br />
<br />
; INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
; RESULT<br />
: This method will return TB_NEED_RETHINK if the gadget ''believes'' that one or more of the attributes will change the sizing requirements of the toolbar. Typically, invoking the WM_RETHINK method on the gadget's window object is needed, in order to recalculate the domain and re-layout the contents.<br />
: If you know you will be changing an attribute that requires a WM_RETHINK, prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
: The method returns 0L if no rethink is needed.<br />
<br />
; EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, GROUP_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
; NAME<br />
: TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, uint32 attrID, uint32 *storage);<br />
<br />
; FUNCTION<br />
: Use this method to obtain the value of a given member attribute.<br />
: Because of the way OM_GET is implemented in Intuition, getting member attributes is done differently compared to setting them. The difference boils down to the following:<br />
:* We cannot use a convenience function such as GetAttr() or GetAttrs(), so a dedicated method is provided. Refer to the EXAMPLE section below to see how to invoke the method.<br />
:* Only one attribute can be queried at a time. (As multiple attributes will rarely be requested in real use, this limitation should not pose a significant problem.)<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
attrID -- the attribute tag identifier<br />
storage -- a pointer to the variable for storing the attribute value<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the requested attribute value has been obtained successfully. The attribute value itself is returned in the provided storage variable.<br />
<br />
; EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID, TBMEMBER_Selected, &storage);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_REFRESHMEMBER ===<br />
<br />
; NAME<br />
: TBM_REFRESHMEMBER -- refresh the imagery of a given member (V53.3)<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbRefreshMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, struct Window *window);<br />
<br />
; FUNCTION<br />
: Use this method to refresh the imagery of a given button or toggle member.<br />
: The method has no effect on spacers and separators.<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbRefreshMember structure<br />
<br />
For IDoMethod():<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_REFRESHMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
window -- a pointer to the window the toolbar resides in<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the refresh has taken place.<br />
<br />
; EXAMPLE<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=Enhancer_Software&diff=1016Enhancer Software2021-01-02T13:22:24Z<p>Trixie: Added the ToolBar Gadget page link to the Contents section.</p>
<hr />
<div><br />
<br />
== Introduction ==<br />
<br />
{|<br />
|-<br />
|[[File:Enhancer_Software_Icon.png]]<br />
|The Enhancer Software is a collection of utilities, commodities, classes, datatypes and libraries with the aim of enhancing the AmigaOS experience. <br />
<br />
It is distibuted both as a digital download from AMIStore App Store and [[Updater]] tool. It is also available as a [[Enhancer Software Box|boxed CD]].<br />
|}<br />
<br />
<center><br />
{|<br />
|-<br />
|[[File:EnhancerSoftwareV1.3.jpg|center|250px]]<br />
|[[File:enhancer_software_box.png|center|250px]]<br />
|}<br />
</center><br />
<br />
== Releases ==<br />
<br />
The following releases of the Enhancer Software have been made:<br />
<br />
=== Current ===<br />
<br />
Version 1.5 released on 30th June 2019 for OS4 platform.<br />
<br />
=== Historical ===<br />
<br />
[[Enhancer Software 1.4|Version 1.4]] released on 9th September 2018 for OS4 platform.<br />
<br />
[[Enhancer Software 1.3|Version 1.3]] released on 19th July 2017 for OS4 platform.<br />
<br />
[[Enhancer Software 1.2|Version 1.2]] released on 27th December 2016 for OS4 platform.<br />
<br />
[[Enhancer Software 1.1|Version 1.1]] released on 31st August 2016 for OS4 platform.<br />
<br />
[[Enhancer Software 1.0|Version 1.0]] released on 1st May 2016 for OS4 platform.<br />
<br />
== Editions ==<br />
<br />
There are three editions of the Enhancer Software:<br />
<br />
* '''Special Edition''': this edition contains all files except the [[RadeonHD]] graphics driver, [[Warp3D Nova]] and [[CANDI]]. <br />
<br />
* '''Standard Edition''': this edition features all files including the version 1 series [[RadeonHD]] driver. <br />
<br />
* '''Plus Edition''': this edition features all files including the version 2 series [[RadeonHD]] driver.<br />
<br />
== Contents ==<br />
<br />
These components which are installed across the system as follows:<br />
<br />
{| style="width: 100%"<br />
|- style="width: 50%; vertical-align: top"<br />
| <br />
'''C'''<br />
<br />
* [[RequestChooser]]<br />
* [[SystemReboot]]<br />
<br />
<br />
<br />
'''Commodities:'''<br />
<br />
* [[ClipViewer]]<br />
<br />
* [[Exchanger]]<br />
<br />
* [[TimeGuard]]<br />
<br />
<br />
<br />
'''Classes:'''<br />
<br />
* [[Anim Gadget Class]]<br />
<br />
* [[Clock Gadget Class]]<br />
<br />
* DateSheet Gadget Class<br />
<br />
* InfoData Gadget Class<br />
<br />
* [[InfoWindow Class]]<br />
<br />
* ListViewer Gadget Class<br />
<br />
* MediaDeck Gadget Class<br />
<br />
* OptionButton Gadget Class<br />
<br />
* PieChart Gadget Class<br />
<br />
* [[ProgressBar Gadget Class]]<br />
<br />
* Shared Image Class<br />
<br />
* Select Gadget Class<br />
<br />
* Sliderbar Gadget Class<br />
<br />
* [[TickBox Gadget Class]]<br />
<br />
* Time Gadget Class<br />
<br />
* [[ToolBar Gadget Class]]<br />
<br />
<br />
'''Datatypes:'''<br />
<br />
* Info Datatype<br />
<br />
* MPEGA Datatype<br />
<br />
* MOD Datatype<br />
<br />
* SimpleHTML Datatype<br />
<br />
* [[Sound Datatype]]<br />
<br />
* WAV Datatype<br />
<br />
<br />
<br />
'''Devs:'''<br />
<br />
* A1222eth.device<br />
<br />
* HDAudio.audio<br />
<br />
* p50x0_eth.device<br />
<br />
* usbadm8511.device<br />
<br />
<br />
<br />
'''Kickstart:'''<br />
<br />
* Diskcache Library<br />
<br />
* [[RadeonHD]]<br />
<br />
* [[SmartFileSystem]]<br />
<br />
<br />
<br />
'''L:'''<br />
<br />
* [[SSH2-Handler]]<br />
<br />
<br />
<br />
|<br />
<br />
'''Libraries:'''<br />
<br />
* Codesets Library<br />
<br />
* EXIF Library<br />
<br />
* Expat Library<br />
<br />
* FileSysBox Library<br />
<br />
* Geocode Library<br />
<br />
* [[OpenGL ES 2.0|OGLES2 Library]] <br />
<br />
* [[Warp3D Nova|Warp3DN Library]]<br />
<br />
* [[Warp3D Nova|Warp3DN_SI Library]]<br />
<br />
* Zip Library<br />
<br />
* Z Library<br />
<br />
<br />
<br />
'''Prefs:'''<br />
<br />
* AmiSpherePrefs<br />
<br />
* [[CANDI|CANDIPrefs]] <br />
<br />
* [[Ringhio_Notifications|Notifications Prefs]]<br />
<br />
* [[Sound_Preferences|Sound Prefs]]<br />
<br />
* [[Time_Preferences|Time Prefs]]<br />
<br />
<br />
'''SDK:'''<br />
<br />
* [[ClipViewer]]<br />
<br />
* [[Clock Gadget Class]]<br />
<br />
* DateSheetGadget<br />
<br />
* DockLib<br />
<br />
* EXIF<br />
<br />
* Expat<br />
<br />
* FileSysBox<br />
<br />
* Geocode<br />
<br />
* [[InfoWindow Class]]<br />
<br />
* [[OpenGL ES 2.0]] <br />
<br />
* OptionButton Gadget Class<br />
<br />
* PieChart Gadget Class<br />
<br />
* Progressbar Gadget Class<br />
<br />
* Shared Image Class<br />
<br />
* [[Sound Datatype]]<br />
<br />
* [[TickBox Gadget Class]]<br />
<br />
* Translations<br />
<br />
* [[Warp3D Nova]]<br />
<br />
<br />
'''System:'''<br />
<br />
* AmiSphereServer<br />
<br />
* [[Format]]<br />
<br />
* [[Ringhio_Notifications|NotificationServer]]<br />
<br />
* [[Updater]]<br />
<br />
<br />
'''Utilities:'''<br />
<br />
* AmiDVD<br />
<br />
* AmiPDF<br />
<br />
* [[CANDI]]<br />
<br />
* [[Calendar]] <br />
<br />
* [[Clock]]<br />
<br />
* [[InfoWindow]] <br />
<br />
* [[MultiEdit]]<br />
<br />
* [[Multiviewer]]<br />
<br />
* PartitionWizard<br />
<br />
* [[TuneNet]]<br />
<br />
* [[X-Dock]]<br />
|}<br />
<br />
<br />
[[File:Enhancer_Software_Installation_Files.png|center]]<br />
<br />
== Installation ==<br />
<br />
<br />
<br />
Please read these important notes before installing the Enhancer Software on your hard disk drive.<br />
<br />
<br />
To install the Enhancer Software to your system, please double click the ''Install_Enhancer_Software'' icon as shown below:<br />
<br />
<br />
[[File:Enhancer_Software_Installation.png|center]]<br />
<br />
<br />
The End-User Licence Agreement will be displayed which needs to be reviewed. If you agree to the terms, then click the '''Agree''' button to continue to the main Installation of the software.<br />
<br />
<br />
[[File:Enhancer_Software_EULA_Window.png|center|250px]]<br />
<br />
<br />
The Installation will then ask you if you wish to backup any files that could be overwritten by the Enhancer Software Installation process. It is recommended that you select '''Yes'''. If you do this, once you press '''Proceed''' button, you will then be asked the location to store on your hard disk where the files will be backed up to.<br />
<br />
<br />
There are two icon drawer sets available to install for selected Utilities and Commodities. The standard blue icon set mimics the default look of OS4.1 drawers. Alternatively the black icon set introduces the new icon style that the Enhancer Software uses. The installation process will prompt you to choose the icon set you want to use.<br />
<br />
<br />
The components of the Enhancer Software sections are installed in this order:<br />
<br />
1. Datatypes:<br />
Info Datatype<br />
LogFile Datatype<br />
MPEGA Datatype <br />
MOD Datatype<br />
SimpleHTML Datatype<br />
Sound Datatype<br />
WAV Datatype<br />
<br />
2. Gadgets and Classes:<br />
Anim Gadget Class<br />
Clock Gadget Class<br />
DateSheet Gadget Class <br />
InfoData Gadget Class <br />
InfoWindow Class<br />
ListViewer Gadget Class <br />
MediaDeck Gadget Class <br />
OptionButton Gadget Class<br />
PieChart Gadget Class <br />
ProgressBar Gadget Class<br />
Select Gadget Class <br />
SliderBar Gadget Class<br />
Shared Image Class<br />
Thumblist Gadget Class <br />
TickBox Gadget Class<br />
Time Gadget<br />
<br />
3. System:<br />
AmiSphereServer<br />
Format <br />
NotificationServer<br />
Updater<br />
<br />
4. Utilities:<br />
AmiDVD<br />
AmiPDF<br />
Calendar<br />
CANDI and CANDI Preferences ¹ <br />
Clock <br />
InfoWindow <br />
MultiEdit ¹<br />
MultiViewer ¹<br />
PartitionWizard<br />
TuneNet<br />
X-Dock<br />
<br />
5. Commodities:<br />
ClipViewer ¹<br />
Exchanger ¹ <br />
<br />
6. Libraries<br />
Codesets<br />
Expat<br />
EXIF <br />
Filesysbox<br />
Geocode <br />
OpenGL ES 2.0<br />
Warp3D Nova<br />
Zip<br />
Z<br />
<br />
7. Kickstart:<br />
Diskcache Library<br />
RadeonHD v2<br />
SmartFileSystem 2 <br />
<br />
8. CLI Commands and Tools:<br />
RequestChooser<br />
SystemReboot <br />
<br />
9. Preferences<br />
Notifications Preferences<br />
Sound Preferences<br />
Time Preferences<br />
<br />
10.Devices<br />
A1222 Ethernet Driver<br />
PTP USB Driver <br />
SSH2-Handler<br />
USBADM8511 Ethernet Driver<br />
X5000 Ethernet Driver<br />
<br />
<br />
¹ Some components from the Enhancer Software will install the image data they require for their User Interface in the Prefs/Presets drawer of your system partition. it is recommended not to change this, however, some more experienced users may want to install this data in an alternative location on their hard disks. If this is the case, you can change the default location from Presets to another bespoke location on your hard disk drive.<br />
<br />
<br />
{|<br />
|-<br />
|[[File:Gadgets_Icon.png|center]]<br />
|<u>Gadgets and Classes</u><br />
<br />
The majority of content in the Enhancer Software requires the gadgets and classes that are supplied and will not operate correctly without these being installed.<br />
<br />
|-<br />
|[[File:Documentation_Icon.png|center]]<br />
|<u>Documentation</u><br />
<br />
By default, all documentation for the components of the Enhancer Software are stored in the Documentation drawer of your system partition. There are options to install the documentation to an alternative location of your choice.<br />
<br />
|-<br />
|[[File:SDK_Icon.png|center]]<br />
|<u>Software Development Kit (SDK)</u><br />
<br />
If you are a developer and have the SDK installed on your system, then any components with SDK files available can be optionally installed. <br />
<br />
|-<br />
|[[File:Catalogs_Icon.png|center]]<br />
|<u>Catalog Language Files</u><br />
<br />
A lot of the Enhancer Software components have support for various languages. These Catalog files can be optionally installed wherever available. <br />
|}<br />
<br />
<br />
For both the SDK and Catalog language files, there is an option to skip the prompt and let the installer automatically remember your choices. The first time the SDK or Catalog Language files prompt appears, a requester window will ask if you wish to apply the installation choice to every supported component in the Enhancer Software. Click the ''Apply To All'' button to do this. Alternatively if you wish to continue to receive prompts, then click the ''Always Prompt'' button.<br />
<br />
<br />
{| style="width: 100%"<br />
|-<br />
|[[File:installchoicerequester.png|center|250px]]<br />
|[[File:installcatalogsrequester.png|center|250px]]<br />
|}<br />
<br />
<br />
<br />
At the end of the installation, a message will report how many installed components need a "soft" or "hard" reboot of your system. The installed components that require a "soft" reboot either start from the WBStartUp or require an assign in your system's s/user-startup file. The components that require a "hard" reboot may need adding to the system's '''Kickstart/Kicklayout''' file and are activated during the initialisation of the Kickstart.<br />
<br />
=Register and download updates=<br />
<br />
In between Enhancer Software releases, individual updated files are available to download through the [[Updater]] tool. In order to access these files, users will need to open an AmiSphere account and register the Enhancer Software product key code against this AmiSphere account.<br />
<br />
[https://www.amisphere.com/register_user.php AmiSphere account registration]<br />
<br />
[https://www.amisphere.com/register_product.php Enhancer Software product registration]<br />
<br />
<br />
=Forums=<br />
<br />
An official discussion and support forum is available for end users. Please refer to the following link:<br />
<br />
[https://forum.amiga.org/enhancersoftware https://forum.amiga.org/enhancersoftware]</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1008ToolBar Gadget Class2020-11-28T22:04:56Z<p>Trixie: </p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Supported methods ==<br />
<br />
{| class="wikitable"<br />
!Method ID<br />
!Description<br />
|-<br />
|OM_NEW<br />
|creates the toolbar object, sets attributes and defaults<br />
|-<br />
|OM_DISPOSE<br />
|disposes of the toolbar object<br />
|-<br />
|OM_REMMEMBER<br />
|used by the class internally; consider this method private<br />
|-<br />
|OM_SET<br />
|sets toolbar, member and image attributes (see the [[#OM_SET|OM_SET]] section below for more information)<br />
|-<br />
|OM_GET<br />
|retrieves toolbar attributes<br />
|-<br />
|TBM_GETMEMBER<br />
|retrieves a given member attribute (see the [[#TBM_GETMEMBER|TBM_GETMEMBER]] section below for more information)<br />
|-<br />
|TBM_REFRESHMEMBER<br />
|refreshes the imagery of a given member (see the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] section below for more information)<br />
|}<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
; GA_ID (uint16)<br />
: Unique ID number for the gadget.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_ReadOnly (BOOL)<br />
: If set to TRUE, none of the toolbar buttons will be selectable.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_BackFill (struct Hook *)<br />
: A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
: Defaults to NULL (the default backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; GA_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the gadget's button text labels (if they are used).<br />
: Defaults to the system's default public screen font.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Orientation (uint32)<br />
: The toolbar orientation: horizontal or vertical.<br />
: Defaults to TB_ORIENT_HORIZ<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_Spacing (uint32)<br />
: The spacing between the individual toolbar members, in pixels.<br />
: Defaults to 2<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HorizPadding<br />
; TOOLBAR_VertPadding (uint32)<br />
: The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_InnerPadding (uint32)<br />
: The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.<br />
: Defaults to 4<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HandleOverflow (BOOL)<br />
: Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_MinVisible (uint32)<br />
: If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
: Defaults to 1<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SpacerSize (uint32)<br />
: The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.<br />
: Defaults to 5<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ButtonStyle (uint32)<br />
: The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
: Defaults to TB_BUTSTYLE_CLASSIC<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BevelStyle (uint32)<br />
: The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:<br />
<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
: When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.<br />
: Defaults to BVS_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SeparatorStyle (uint32)<br />
: Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.<br />
: Defaults to TB_SEPSTYLE_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SelectionStyle (uint32)<br />
: Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.<br />
: This tag is ignored in the classic mode with framed buttons.<br />
: Defaults to TB_SELSTYLE_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BackFill (struct Hook *)<br />
: A custom backfill hook to provide a background filled with a specific colour or pattern.<br />
: This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.<br />
: Defaults to NULL (the default layers backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Display (uint32)<br />
: Specifies what you want to display inside the toolbar button or toggle members. The possible values are:<br />
<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
: Defaults to TB_DISPLAY_IMAGES<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_TextPlace (uint32)<br />
: Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_LabelArray (STRPTR *)<br />
: Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.<br />
: TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
: Using this tag, the limitation is that you cannot create toggle members (only buttons, separators and spacers).<br />
: A special string, " ", will create a spacer.<br />
: A special string, "_", will create a separator.<br />
: Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.<br />
: The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TOOLBAR_EvenSize (BOOL)<br />
: If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.<br />
: If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ImageSet (uint32)<br />
: If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in the toolbar. The value passed to this tag is the image set ID.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:<br />
<br />
; TOOLBAR_AddImageSet (uint32)<br />
: Creates a new image set. The value passed to this tag is a numeric ID identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to display the particular image set in the toolbar.<br />
: This tag should be followed by a sequence of TOOLBAR_AddImage tags (see below), each creating one image in the given set.<br />
: If the gadget only uses one set of images, passing TOOLBAR_AddImageSet is not necessary. Each TOOLBAR_AddImage will add the respective image to the default image set identified by an ID of 0.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddImage (uint32)<br />
: Creates a new image in a given image set. The value passed to this tag is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID (see below) to associate the image with a particular toolbar member.<br />
: This tag should be followed by a sequence of TBIMAGE_ tags (see the [[#Image attributes|Image attributes]] section below), each configuring one aspect of the image, including its optional selected variant (referred to as the "select image").<br />
: Images are added to the default image set unless a preceding TOOLBAR_AddImageSet specifies a different set.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddMember (uint32)<br />
: Creates a new toolbar member. The value passed to this tag is a numeric ID identifying the member.<br />
: Spacers and separators normally don't need an ID, so you can use TB_NO_ID as a value for TOOLBAR_AddMember when creating these members. However, if you want to manipulate spacers/separators in your GUI, an ID will be necessary so that you can pass it to TOOLBAR_SetMember to identify the respective spacer or separator member.<br />
: You can add members when the toolbar object is being created, i.e. as part of the NewObject() call, or at any time later via SetAttrs().<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetMember<br />
: Use this tag in a SetAttrs() call to identify the member you want to modify.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetGroup<br />
: Use this tag in a SetAttrs() call to identify the group of members you want to modify collectively.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
=== Member attributes ===<br />
<br />
; TBMEMBER_Type (uint32)<br />
: The type of the toolbar member. The possible values are the following:<br />
<br />
TB_MTYPE_BUTTON-- a normal toolbar button<br />
TB_MTYPE_TOGGLE-- a toggle (on/off) button<br />
TB_MTYPE_SPACER-- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
<br />
: The type is set upon member creation, and cannot be changed.<br />
: Defaults to TB_MTYPE_BUTTON<br />
: Applicability is (OM_NEW)<br />
<br />
; TBMEMBER_ImageID (uint32)<br />
: The identifier of the image to be used for the button or toggle member (see TOOLBAR_AddImage above). This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_ImageID value of such a member.<br />
: When [[#OM_SET|OM_SET]]-ing this attribute, the method will always return TB_NEED_RETHINK, to be on the safe side. However, invoking WM_RETHINK is really only needed if the size of the new image is different from the original image. If the size is the same, a simple gadget refresh will suffice. You can trigger the refresh:<br />
:* by setting this attribute via RefreshSetGadgetAttrs(), or<br />
:* by setting this attribute via SetAttrs() and then invoking the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method on the respective button/toggle member.<br />
: (The difference is that RefreshSetGadgetAttrs() will refresh the entire toolbar, while TBM_REFRESHMEMBER will only refresh the given member.)<br />
: Defaults to TB_NO_ID (no image associated with this member)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Text (CONST_STRPTR)<br />
: The label to associate with a button or a toggle member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
: The text label will be used as fallback in case no image is found or provided.<br />
: The text string can contain an underscore character (_), indicating the keyboard shortcut for this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Disabled (BOOL)<br />
: The current state (disabled or not disabled) of a member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Disabled value of such a member.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Hidden (BOOL)<br />
: Specifies whether the particular member is displayed in the toolbar or hidden. You can use this tag to create "dynamic" toolbar layouts that adapt the actual member set to various application settings.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Selected (BOOL)<br />
: The current selection state of a toggle member. This tag is not relevant to normal buttons (TB_MTYPE_BUTTON), spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Selected value of such a member.<br />
: You can set a target BOOPSI object for any toggle member, using the standard icclass ICA_TARGET tag. The target will receive an automatic notification of the toggle selection. This way toolbar toggles can easily communicate with other boolean gadgets such as checkboxes.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_NOTIFY, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Group (uint32)<br />
: Member group ID. Several members can be manipulated at once if they are assigned to the same group. Use TOOLBAR_SetGroup with the respective group ID to identify the group to be manipulated.<br />
: Defaults to TB_NO_ID (not assigned to any group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_MXGroup (uint32)<br />
: MX group ID. Toggle members can be put in groups of mutually-exclusive buttons. When such a toggle is selected, all other toggles in the same MX group will become deselected.<br />
: This tag is not relevant to normal buttons, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_MXGroup value of such a member.<br />
: Defaults to TB_NO_ID (not assigned to any MX group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_HintInfo (CONST_STRPTR)<br />
: The help text to be displayed when the user hovers the mouse pointer over the respective member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_HintInfo value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_UserData (APTR)<br />
: Arbitrary user data associated with this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
=== Image attributes ===<br />
<br />
; TBIMAGE_Image (struct Image *)<br />
: Custom image to be used for a button or a toggle member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_ImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImage (struct Image *)<br />
: Custom image to display when the member becomes selected.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the select image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
;TBIMAGE_Width (uint32)<br />
;TBIMAGE_Height (uint32)<br />
: Image dimensions, in pixels. These tags can only be used in connection with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the respective source file will be scaled to the specified width and height. Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot be resized using these tags.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW)<br />
<br />
== Notes ==<br />
<br />
Some of the attributes described above change the sizing requirements of the gadget. If set on the fly (i.e. when the toolbar is already displayed in the window), the gadget domain will need recalculating and a re-layout must take place. Refer to the [[#OM_SET|OM_SET]] method documentation below to see how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image. [[#Image attributes|Image attributes]] cannot be changed later.<br />
<br />
== Bugs ==<br />
<br />
== See also ==<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
; NAME<br />
: OM_SET -- set toolbar attributes<br />
<br />
; SYNOPSIS<br />
: uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
: uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win, struct Requester *req, Tag tag1, ...);<br />
<br />
; FUNCTION<br />
: This method sets the attributes of the toolbar and/or of its members. SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions to invoke this method.<br />
: To change a member attribute you first need to pass TOOLBAR_SetMember to identify the respective member, and then the member attribute tag(s). See the EXAMPLE section below.<br />
: To change an attribute collectively for a group of members you first need to pass TOOLBAR_SetGroup to identify the respective group, and then the member attribute tag(s). See the EXAMPLE section below.<br />
<br />
; INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
; RESULT<br />
: This method will return TB_NEED_RETHINK if the gadget ''believes'' that one or more of the attributes will change the sizing requirements of the toolbar. Typically, invoking the WM_RETHINK method on the gadget's window object is needed, in order to recalculate the domain and re-layout the contents.<br />
: If you know you will be changing an attribute that requires a WM_RETHINK, prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
: The method returns 0L if no rethink is needed.<br />
<br />
; EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, GROUP_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
; NAME<br />
: TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, uint32 attrID, uint32 *storage);<br />
<br />
; FUNCTION<br />
: Use this method to obtain the value of a given member attribute.<br />
: Because of the way OM_GET is implemented in Intuition, getting member attributes is done differently compared to setting them. The difference boils down to the following:<br />
:* We cannot use a convenience function such as GetAttr() or GetAttrs(), so a dedicated method is provided. Refer to the EXAMPLE section below to see how to invoke the method.<br />
:* Only one attribute can be queried at a time. (As multiple attributes will rarely be requested in real use, this limitation should not pose a significant problem.)<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
attrID -- the attribute tag identifier<br />
storage -- a pointer to the variable for storing the attribute value<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the requested attribute value has been obtained successfully. The attribute value itself is returned in the provided storage variable.<br />
<br />
; EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID, TBMEMBER_Selected, &storage);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_REFRESHMEMBER ===<br />
<br />
; NAME<br />
: TBM_REFRESHMEMBER -- refresh the imagery of a given member (V53.3)<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbRefreshMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, struct Window *window);<br />
<br />
; FUNCTION<br />
: Use this method to refresh the imagery of a given button or toggle member.<br />
: The method has no effect on spacers and separators.<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbRefreshMember structure<br />
<br />
For IDoMethod():<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_REFRESHMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
window -- a pointer to the window the toolbar resides in<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the refresh has taken place.<br />
<br />
; EXAMPLE<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1007ToolBar Gadget Class2020-11-28T21:59:48Z<p>Trixie: Updated to include the changes for V53.3.</p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Supported methods ==<br />
<br />
{| class="wikitable"<br />
!Method ID<br />
!Description<br />
|-<br />
|OM_NEW<br />
|creates the toolbar object, sets attributes and defaults<br />
|-<br />
|OM_DISPOSE<br />
|disposes of the toolbar object<br />
|-<br />
|OM_REMMEMBER<br />
|used by the class internally; consider this method private<br />
|-<br />
|OM_SET<br />
|sets toolbar, member and image attributes (see the [[#OM_SET|OM_SET]] section below for more information)<br />
|-<br />
|OM_GET<br />
|retrieves toolbar attributes<br />
|-<br />
|TBM_GETMEMBER<br />
|retrieves a given member attribute (see the [[#TBM_GETMEMBER|TBM_GETMEMBER]] section below for more information)<br />
|-<br />
|TBM_REFRESHMEMBER<br />
|refreshes the imagery of a given member (see the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] section below for more information)<br />
|}<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
; GA_ID (uint16)<br />
: Unique ID number for the gadget.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_ReadOnly (BOOL)<br />
: If set to TRUE, none of the toolbar buttons will be selectable.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_BackFill (struct Hook *)<br />
: A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
: Defaults to NULL (the default backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; GA_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the gadget's button text labels (if they are used).<br />
: Defaults to the system's default public screen font.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Orientation (uint32)<br />
: The toolbar orientation: horizontal or vertical.<br />
: Defaults to TB_ORIENT_HORIZ<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_Spacing (uint32)<br />
: The spacing between the individual toolbar members, in pixels.<br />
: Defaults to 2<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HorizPadding<br />
; TOOLBAR_VertPadding (uint32)<br />
: The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_InnerPadding (uint32)<br />
: The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.<br />
: Defaults to 4<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HandleOverflow (BOOL)<br />
: Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_MinVisible (uint32)<br />
: If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
: Defaults to 1<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SpacerSize (uint32)<br />
: The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.<br />
: Defaults to 5<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ButtonStyle (uint32)<br />
: The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
: Defaults to TB_BUTSTYLE_CLASSIC<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BevelStyle (uint32)<br />
: The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:<br />
<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
: When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.<br />
: Defaults to BVS_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SeparatorStyle (uint32)<br />
: Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.<br />
: Defaults to TB_SEPSTYLE_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SelectionStyle (uint32)<br />
: Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.<br />
: This tag is ignored in the classic mode with framed buttons.<br />
: Defaults to TB_SELSTYLE_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BackFill (struct Hook *)<br />
: A custom backfill hook to provide a background filled with a specific colour or pattern.<br />
: This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.<br />
: Defaults to NULL (the default layers backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Display (uint32)<br />
: Specifies what you want to display inside the toolbar button or toggle members. The possible values are:<br />
<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
: Defaults to TB_DISPLAY_IMAGES<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_TextPlace (uint32)<br />
: Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_LabelArray (STRPTR *)<br />
: Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.<br />
: TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
: Using this tag, the limitation is that you cannot create toggle members (only buttons, separators and spacers).<br />
: A special string, " ", will create a spacer.<br />
: A special string, "_", will create a separator.<br />
: Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.<br />
: The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TOOLBAR_EvenSize (BOOL)<br />
: If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.<br />
: If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ImageSet (uint32)<br />
: If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in the toolbar. The value passed to this tag is the image set ID.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:<br />
<br />
; TOOLBAR_AddImageSet (uint32)<br />
: Creates a new image set. The value passed to this tag is a numeric ID identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to display the particular image set in the toolbar.<br />
: This tag should be followed by a sequence of TOOLBAR_AddImage tags (see below), each creating one image in the given set.<br />
: If the gadget only uses one set of images, passing TOOLBAR_AddImageSet is not necessary. Each TOOLBAR_AddImage will add the respective image to the default image set identified by an ID of 0.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddImage (uint32)<br />
: Creates a new image in a given image set. The value passed to this tag is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID (see below) to associate the image with a particular toolbar member.<br />
: This tag should be followed by a sequence of TBIMAGE_ tags (see the [[#Image attributes|Image attributes]] section below), each configuring one aspect of the image, including its optional selected variant (referred to as the "select image").<br />
: Images are added to the default image set unless a preceding TOOLBAR_AddImageSet specifies a different set.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddMember (uint32)<br />
: Creates a new toolbar member. The value passed to this tag is a numeric ID identifying the member.<br />
: Spacers and separators normally don't need an ID, so you can use TB_NO_ID as a value for TOOLBAR_AddMember when creating these members. However, if you want to manipulate spacers/separators in your GUI, an ID will be necessary so that you can pass it to TOOLBAR_SetMember to identify the respective spacer or separator member.<br />
: You can add members when the toolbar object is being created, i.e. as part of the NewObject() call, or at any time later via SetAttrs().<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetMember<br />
: Use this tag in a SetAttrs() call to identify the member you want to modify.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetGroup<br />
: Use this tag in a SetAttrs() call to identify the group of members you want to modify collectively.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
=== Member attributes ===<br />
<br />
; TBMEMBER_Type (uint32)<br />
: The type of the toolbar member. The possible values are the following:<br />
<br />
TB_MTYPE_BUTTON-- a normal toolbar button<br />
TB_MTYPE_TOGGLE-- a toggle (on/off) button<br />
TB_MTYPE_SPACER-- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
<br />
: The type is set upon member creation, and cannot be changed.<br />
: Defaults to TB_MTYPE_BUTTON<br />
: Applicability is (OM_NEW)<br />
<br />
; TBMEMBER_ImageID (uint32)<br />
: The identifier of the image to be used for the button or toggle member (see TOOLBAR_AddImage above). This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_ImageID value of such a member.<br />
: When [[#OM_SET|OM_SET]]-ing this attribute, the method will always return TB_NEED_RETHINK, to be on the safe side. However, invoking WM_RETHINK is really only needed if the size of the new image is different from the original image. If the size is the same, a simple gadget refresh will suffice. You can trigger the refresh:<br />
:* by setting this attribute via RefreshSetGadgetAttrs(), or<br />
:* by setting this attribute via SetAttrs() and then invoking the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method on the respective button/toggle member.<br />
: (The difference is that RefreshSetGadgetAttrs() will refresh the entire toolbar, while TBM_REFRESHMEMBER will only refresh the given member.)<br />
: Defaults to TB_NO_ID (no image associated with this member)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Text (CONST_STRPTR)<br />
: The label to associate with a button or a toggle member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
: The text label will be used as fallback in case no image is found or provided.<br />
: The text string can contain an underscore character (_), indicating the keyboard shortcut for this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Disabled (BOOL)<br />
: The current state (disabled or not disabled) of a member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Disabled value of such a member.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Hidden (BOOL)<br />
: Specifies whether the particular member is displayed in the toolbar or hidden. You can use this tag to create "dynamic" toolbar layouts that adapt the actual member set to various application settings.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Selected (BOOL)<br />
: The current selection state of a toggle member. This tag is not relevant to normal buttons (TB_MTYPE_BUTTON), spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Selected value of such a member.<br />
: You can set a target BOOPSI object for any toggle member, using the standard icclass ICA_TARGET tag. The target will receive an automatic notification of the toggle selection. This way toolbar toggles can easily communicate with other boolean gadgets such as checkboxes.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_NOTIFY, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Group (uint32)<br />
: Member group ID. Several members can be manipulated at once if they are assigned to the same group. Use TOOLBAR_SetGroup with the respective group ID to identify the group to be manipulated.<br />
: Defaults to TB_NO_ID (not assigned to any group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_MXGroup (uint32)<br />
: MX group ID. Toggle members can be put in groups of mutually-exclusive buttons. When such a toggle is selected, all other toggles in the same MX group will become deselected.<br />
: This tag is not relevant to normal buttons, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_MXGroup value of such a member.<br />
: Defaults to TB_NO_ID (not assigned to any MX group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_HintInfo (CONST_STRPTR)<br />
: The help text to be displayed when the user hovers the mouse pointer over the respective member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_HintInfo value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_UserData (APTR)<br />
: Arbitrary user data associated with this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
=== Image attributes ===<br />
<br />
; TBIMAGE_Image (struct Image *)<br />
: Custom image to be used for a button or a toggle member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_ImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImage (struct Image *)<br />
: Custom image to display when the member becomes selected.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the select image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
;TBIMAGE_Width (uint32)<br />
;TBIMAGE_Height (uint32)<br />
: Image dimensions, in pixels. These tags can only be used in connection with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the respective source file will be scaled to the specified width and height. Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot be resized using these tags.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW)<br />
<br />
== Notes ==<br />
<br />
Some of the attributes described above change the sizing requirements of the gadget. If set on the fly (i.e. when the toolbar is already displayed in the window), the gadget domain will need recalculating and a re-layout must take place. Refer to the [[#OM_SET|OM_SET]] method documentation below to see how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image. Image attributes cannot be changed later.<br />
<br />
== Bugs ==<br />
<br />
== See also ==<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
; NAME<br />
: OM_SET -- set toolbar attributes<br />
<br />
; SYNOPSIS<br />
: uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
: uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win, struct Requester *req, Tag tag1, ...);<br />
<br />
; FUNCTION<br />
: This method sets the attributes of the toolbar and/or of its members. SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions to invoke this method.<br />
: To change a member attribute you first need to pass TOOLBAR_SetMember to identify the respective member, and then the member attribute tag(s). See the EXAMPLE section below.<br />
: To change an attribute collectively for a group of members you first need to pass TOOLBAR_SetGroup to identify the respective group, and then the member attribute tag(s). See the EXAMPLE section below.<br />
<br />
; INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
; RESULT<br />
: This method will return TB_NEED_RETHINK if the gadget ''believes'' that one or more of the attributes will change the sizing requirements of the toolbar. Typically, invoking the WM_RETHINK method on the gadget's window object is needed, in order to recalculate the domain and re-layout the contents.<br />
: If you know you will be changing an attribute that requires a WM_RETHINK, prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
: The method returns 0L if no rethink is needed.<br />
<br />
; EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, GROUP_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
; NAME<br />
: TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, uint32 attrID, uint32 *storage);<br />
<br />
; FUNCTION<br />
: Use this method to obtain the value of a given member attribute.<br />
: Because of the way OM_GET is implemented in Intuition, getting member attributes is done differently compared to setting them. The difference boils down to the following:<br />
:* We cannot use a convenience function such as GetAttr() or GetAttrs(), so a dedicated method is provided. Refer to the EXAMPLE section below to see how to invoke the method.<br />
:* Only one attribute can be queried at a time. (As multiple attributes will rarely be requested in real use, this limitation should not pose a significant problem.)<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
attrID -- the attribute tag identifier<br />
storage -- a pointer to the variable for storing the attribute value<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the requested attribute value has been obtained successfully. The attribute value itself is returned in the provided storage variable.<br />
<br />
; EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID, TBMEMBER_Selected, &storage);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_REFRESHMEMBER ===<br />
<br />
; NAME<br />
: TBM_REFRESHMEMBER -- refresh the imagery of a given member (V53.3)<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbRefreshMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, struct Window *window);<br />
<br />
; FUNCTION<br />
: Use this method to refresh the imagery of a given button or toggle member.<br />
: The method has no effect on spacers and separators.<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbRefreshMember structure<br />
<br />
For IDoMethod():<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_REFRESHMEMBER<br />
memberID -- the member identifier (as set in TOOLBAR_AddMember)<br />
window -- a pointer to the window the toolbar resides in<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the refresh has taken place.<br />
<br />
; EXAMPLE<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1006ToolBar Gadget Class2020-10-31T13:31:59Z<p>Trixie: </p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Supported methods ==<br />
<br />
{| class="wikitable"<br />
!Method ID<br />
!Description<br />
|-<br />
|OM_NEW<br />
|creates the toolbar object, sets attributes and defaults<br />
|-<br />
|OM_DISPOSE<br />
|disposes of the toolbar object<br />
|-<br />
|OM_REMMEMBER<br />
|used by the class internally; consider this method private<br />
|-<br />
|OM_SET<br />
|sets toolbar, member and image attributes (see the [[#OM_SET|OM_SET]] section below for more information)<br />
|-<br />
|OM_GET<br />
|retrieves toolbar attributes<br />
|-<br />
|TBM_GETMEMBER<br />
|retrieves a given member attribute (see the [[#TBM_GETMEMBER|TBM_GETMEMBER]] section below for more information)<br />
|}<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
; GA_ID (uint16)<br />
: Unique ID number for the gadget.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_ReadOnly (BOOL)<br />
: If set to TRUE, none of the toolbar buttons will be selectable.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; GA_BackFill (struct Hook *)<br />
: A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
: Defaults to NULL (the default backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; GA_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the gadget's button text labels (if they are used).<br />
: Defaults to the system's default public screen font.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Orientation (uint32)<br />
: The toolbar orientation: horizontal or vertical.<br />
: Defaults to TB_ORIENT_HORIZ<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_Spacing (uint32)<br />
: The spacing between the individual toolbar members, in pixels.<br />
: Defaults to 2<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HorizPadding<br />
; TOOLBAR_VertPadding (uint32)<br />
: The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_InnerPadding (uint32)<br />
: The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.<br />
: Defaults to 4<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HandleOverflow (BOOL)<br />
: Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_MinVisible (uint32)<br />
: If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
: Defaults to 1<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SpacerSize (uint32)<br />
: The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.<br />
: Defaults to 5<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ButtonStyle (uint32)<br />
: The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
: Defaults to TB_BUTSTYLE_CLASSIC<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BevelStyle (uint32)<br />
: The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:<br />
<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
: When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.<br />
: Defaults to BVS_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SeparatorStyle (uint32)<br />
: Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.<br />
: Defaults to TB_SEPSTYLE_NORMAL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SelectionStyle (uint32)<br />
: Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.<br />
: This tag is ignored in the classic mode with framed buttons.<br />
: Defaults to TB_SELSTYLE_NONE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BackFill (struct Hook *)<br />
: A custom backfill hook to provide a background filled with a specific colour or pattern.<br />
: This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.<br />
: Defaults to NULL (the default layers backfill hook).<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)<br />
<br />
; TOOLBAR_Display (uint32)<br />
: Specifies what you want to display inside the toolbar button or toggle members. The possible values are:<br />
<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
: Defaults to TB_DISPLAY_IMAGES<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_TextPlace (uint32)<br />
: Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_LabelArray (STRPTR *)<br />
: Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.<br />
: TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
: Using this tag, the limitation is that you cannot create toggle members (only buttons, separators and spacers).<br />
: A special string, " ", will create a spacer.<br />
: A special string, "_", will create a separator.<br />
: Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.<br />
: The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TOOLBAR_EvenSize (BOOL)<br />
: If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.<br />
: If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ImageSet (uint32)<br />
: If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in the toolbar. The value passed to this tag is the image set ID.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:<br />
<br />
; TOOLBAR_AddImageSet (uint32)<br />
: Creates a new image set. The value passed to this tag is a numeric ID identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to display the particular image set in the toolbar.<br />
: This tag should be followed by a sequence of TOOLBAR_AddImage tags (see below), each creating one image in the given set.<br />
: If the gadget only uses one set of images, passing TOOLBAR_AddImageSet is not necessary. Each TOOLBAR_AddImage will add the respective image to the default image set identified by an ID of 0.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddImage (uint32)<br />
: Creates a new image in a given image set. The value passed to this tag is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID (see below) to associate the image with a particular toolbar member.<br />
: This tag should be followed by a sequence of TBIMAGE_ tags (see the [[#Image attributes|Image attributes]] section below), each configuring one aspect of the image, including its optional selected variant (referred to as the "select image").<br />
: Images are added to the default image set unless a preceding TOOLBAR_AddImageSet specifies a different set.<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_AddMember (uint32)<br />
: Creates a new toolbar member. The value passed to this tag is a numeric ID identifying the member.<br />
: Spacers and separators normally don't need an ID, so you can use TB_NO_ID as a value for TOOLBAR_AddMember when creating these members. However, if you want to manipulate spacers/separators in your GUI, an ID will be necessary so that you can pass it to TOOLBAR_SetMember to identify the respective spacer or separator member.<br />
: You can add members when the toolbar object is being created, i.e. as part of the NewObject() call, or at any time later via SetAttrs().<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetMember<br />
: Use this tag in a SetAttrs() call to identify the member you want to modify.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
; TOOLBAR_SetGroup<br />
: Use this tag in a SetAttrs() call to identify the group of members you want to modify collectively.<br />
: Applicability is ([[#OM_SET|OM_SET]])<br />
<br />
=== Member attributes ===<br />
<br />
; TBMEMBER_Type (uint32)<br />
: The type of the toolbar member. The possible values are the following:<br />
<br />
TB_MTYPE_BUTTON-- a normal toolbar button<br />
TB_MTYPE_TOGGLE-- a toggle (on/off) button<br />
TB_MTYPE_SPACER-- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
<br />
: The type is set upon member creation, and cannot be changed.<br />
: Defaults to TB_MTYPE_BUTTON<br />
: Applicability is (OM_NEW)<br />
<br />
; TBMEMBER_ImageID (uint32)<br />
: The identifier of the image to be used for the button or toggle member (see TOOLBAR_AddImage above). This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_ImageID value of such a member.<br />
: Defaults to TB_NO_ID (no image associated with this member)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Text (CONST_STRPTR)<br />
: The label to associate with a button or a toggle member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
: The text label will be used as fallback in case no image is found or provided.<br />
: The text string can contain an underscore character (_), indicating the keyboard shortcut for this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Disabled (BOOL)<br />
: The current state (disabled or not disabled) of a member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Disabled value of such a member.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Hidden (BOOL)<br />
: Specifies whether the particular member is displayed in the toolbar or hidden. You can use this tag to create "dynamic" toolbar layouts that adapt the actual member set to various application settings.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Selected (BOOL)<br />
: The current selection state of a toggle member. This tag is not relevant to normal buttons (TB_MTYPE_BUTTON), spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Selected value of such a member.<br />
: You can set a target BOOPSI object for any toggle member, using the standard icclass ICA_TARGET tag. The target will receive an automatic notification of the toggle selection. This way toolbar toggles can easily communicate with other boolean gadgets such as checkboxes.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_NOTIFY, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Group (uint32)<br />
: Member group ID. Several members can be manipulated at once if they are assigned to the same group. Use TOOLBAR_SetGroup with the respective group ID to identify the group to be manipulated.<br />
: Defaults to TB_NO_ID (not assigned to any group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_MXGroup (uint32)<br />
: MX group ID. Toggle members can be put in groups of mutually-exclusive buttons. When such a toggle is selected, all other toggles in the same MX group will become deselected.<br />
: This tag is not relevant to normal buttons, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_MXGroup value of such a member.<br />
: Defaults to TB_NO_ID (not assigned to any MX group)<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_HintInfo (CONST_STRPTR)<br />
: The help text to be displayed when the user hovers the mouse pointer over the respective member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_HintInfo value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_UserData (APTR)<br />
: Arbitrary user data associated with this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
=== Image attributes ===<br />
<br />
; TBIMAGE_Image (struct Image *)<br />
: Custom image to be used for a button or a toggle member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_ImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImage (struct Image *)<br />
: Custom image to display when the member becomes selected.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the select image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
;TBIMAGE_Width (uint32)<br />
;TBIMAGE_Height (uint32)<br />
: Image dimensions, in pixels. These tags can only be used in connection with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the respective source file will be scaled to the specified width and height. Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot be resized using these tags.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW)<br />
<br />
== Notes ==<br />
<br />
Some of the attributes described above change the sizing requirements of the gadget. If set on the fly (i.e. when the toolbar is already displayed in the window), the gadget domain will need recalculating and a re-layout must take place. Refer to the [[#OM_SET|OM_SET]] method documentation below to see how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image. Image attributes cannot be changed later.<br />
<br />
== Bugs ==<br />
<br />
== See also ==<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
; NAME<br />
: OM_SET -- set toolbar attributes<br />
<br />
; SYNOPSIS<br />
: uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
: uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win, struct Requester *req, Tag tag1, ...);<br />
<br />
; FUNCTION<br />
: This method sets the attributes of the toolbar and/or of its members. SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions to invoke this method.<br />
: To change a member attribute you first need to pass TOOLBAR_SetMember to identify the respective member, and then the member attribute tag(s). See the EXAMPLE section below.<br />
: To change an attribute collectively for a group of members you first need to pass TOOLBAR_SetGroup to identify the respective group, and then the member attribute tag(s). See the EXAMPLE section below.<br />
<br />
; INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
; RESULT<br />
: This method will return TB_NEED_RETHINK if one or more of the attributes change the sizing requirements of the gadget. In such a case, the appropriate reaction is to call WM_RETHINK on the gadget's window object to recalculate the domain and re-layout the contents.<br />
: If you know you will be changing an attribute that requires a WM_RETHINK, prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
: The method returns 0 if no rethink is needed.<br />
<br />
; EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, GROUP_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
; NAME<br />
: TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 attrID, uint32 *storage);<br />
<br />
; FUNCTION<br />
: Use this method to obtain the value of a given member attribute.<br />
: Because of the way OM_GET is implemented in Intuition, getting member attributes is done differently compared to setting them. The difference boils down to the following:<br />
:* We cannot use a convenience function such as GetAttr() or GetAttrs(), so a dedicated method is provided. Refer to the EXAMPLE section below to see how to invoke the method.<br />
:* Only one attribute can be queried at a time. (As multiple attributes will rarely be requested in real use, this limitation should not pose a significant problem.)<br />
<br />
; INPUTS<br />
For IDoMethodA():<br />
<br />
toolbar -- the toolbar gadget object<br />
msg -- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
<br />
toolbar -- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
attrID -- the attribute tag identifier<br />
storage -- a pointer to the variable for storing the attribute value<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the requested attribute value has been obtained successfully. The attribute value itself is returned in the provided storage variable.<br />
<br />
; EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID, TBMEMBER_Selected, &storage);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1005ToolBar Gadget Class2020-10-31T09:07:46Z<p>Trixie: </p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Methods ==<br />
<br />
OM_NEW -- creates the toolbar object, sets attributes and defaults<br />
<br />
OM_DISPOSE -- disposes of the toolbar object<br />
<br />
OM_REMMEMBER -- used by the class internally; consider this method private<br />
<br />
OM_SET -- sets toolbar, member and image attributes (see the OM_SET section below for more information)<br />
<br />
OM_GET -- retrieves toolbar attributes<br />
<br />
TBM_GETMEMBER -- retrieves a given member attribute (see the [[#TBM_GETMEMBER|TBM_GETMEMBER]] section below for more information)<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
; GA_ID (uint16)<br />
: Unique ID number for the gadget.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; GA_ReadOnly (BOOL)<br />
: If set to TRUE, none of the toolbar buttons will be selectable.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; GA_BackFill (struct Hook *)<br />
: A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
: Defaults to NULL (the default backfill hook).<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
; GA_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the gadget's button text labels (if they are used).<br />
: Defaults to the system's default public screen font.<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
; TOOLBAR_Orientation (uint32)<br />
: The toolbar orientation: horizontal or vertical.<br />
: Defaults to TB_ORIENT_HORIZ<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_Spacing (uint32)<br />
: The spacing between the individual toolbar members, in pixels.<br />
: Defaults to 2<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HorizPadding<br />
; TOOLBAR_VertPadding (uint32)<br />
: The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_InnerPadding (uint32)<br />
: The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.<br />
: Defaults to 4<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HandleOverflow (BOOL)<br />
: Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_MinVisible (uint32)<br />
: If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
: Defaults to 1<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SpacerSize (uint32)<br />
: The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.<br />
: Defaults to 5<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ButtonStyle (uint32)<br />
: The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
: Defaults to TB_BUTSTYLE_CLASSIC<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BevelStyle (uint32)<br />
: The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:<br />
<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
: When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.<br />
: Defaults to BVS_NONE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SeparatorStyle (uint32)<br />
: Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.<br />
: Defaults to TB_SEPSTYLE_NORMAL<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SelectionStyle (uint32)<br />
: Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.<br />
: This tag is ignored in the classic mode with framed buttons.<br />
: Defaults to TB_SELSTYLE_NONE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BackFill (struct Hook *)<br />
: A custom backfill hook to provide a background filled with a specific colour or pattern.<br />
: This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.<br />
: Defaults to NULL (the default layers backfill hook).<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
; TOOLBAR_Display (uint32)<br />
: Specifies what you want to display inside the toolbar button or toggle members. The possible values are:<br />
<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
: Defaults to TB_DISPLAY_IMAGES<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_TextPlace (uint32)<br />
: Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_LabelArray (STRPTR *)<br />
: Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.<br />
: TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
: Using this tag, the limitation is that you cannot create toggle members (only buttons, separators and spacers).<br />
: A special string, " ", will create a spacer.<br />
: A special string, "_", will create a separator.<br />
: Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.<br />
: The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TOOLBAR_EvenSize (BOOL)<br />
: If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.<br />
: If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ImageSet (uint32)<br />
: If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in the toolbar. The value passed to this tag is the image set ID.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:<br />
<br />
; TOOLBAR_AddImageSet (uint32)<br />
: Creates a new image set. The value passed to this tag is a numeric ID identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to display the particular image set in the toolbar.<br />
: This tag should be followed by a sequence of TOOLBAR_AddImage tags (see below), each creating one image in the given set.<br />
: If the gadget only uses one set of images, passing TOOLBAR_AddImageSet is not necessary. Each TOOLBAR_AddImage will add the respective image to the default image set identified by an ID of 0.<br />
: Applicability is (OM_NEW, OM_SET)<br />
<br />
; TOOLBAR_AddImage (uint32)<br />
: Creates a new image in a given image set. The value passed to this tag is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID (see below) to associate the image with a particular toolbar member.<br />
: This tag should be followed by a sequence of TBIMAGE_ tags (see the [[#Image attributes|Image attributes]] section below), each configuring one aspect of the image, including its optional selected variant (referred to as the "select image").<br />
: Images are added to the default image set unless a preceding TOOLBAR_AddImageSet specifies a different set.<br />
: Applicability is (OM_NEW, OM_SET)<br />
<br />
; TOOLBAR_AddMember (uint32)<br />
: Creates a new toolbar member. The value passed to this tag is a numeric ID identifying the member.<br />
: Spacers and separators normally don't need an ID, so you can use TB_NO_ID as a value for TOOLBAR_AddMember when creating these members. However, if you want to manipulate spacers/separators in your GUI, an ID will be necessary so that you can pass it to TOOLBAR_SetMember to identify the respective spacer or separator member.<br />
: You can add members when the toolbar object is being created, i.e. as part of the NewObject() call, or at any time later via SetAttrs().<br />
: Applicability is (OM_NEW, OM_SET)<br />
<br />
; TOOLBAR_SetMember<br />
: Use this tag in a SetAttrs() call to identify the member you want to modify.<br />
: Applicability is (OM_SET)<br />
<br />
; TOOLBAR_SetGroup<br />
: Use this tag in a SetAttrs() call to identify the group of members you want to modify collectively.<br />
: Applicability is (OM_SET)<br />
<br />
=== Member attributes ===<br />
<br />
; TBMEMBER_Type (uint32)<br />
: The type of the toolbar member. The possible values are the following:<br />
<br />
TB_MTYPE_BUTTON-- a normal toolbar button<br />
TB_MTYPE_TOGGLE-- a toggle (on/off) button<br />
TB_MTYPE_SPACER-- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
<br />
: The type is set upon member creation, and cannot be changed.<br />
: Defaults to TB_MTYPE_BUTTON<br />
: Applicability is (OM_NEW)<br />
<br />
; TBMEMBER_ImageID (uint32)<br />
: The identifier of the image to be used for the button or toggle member (see TOOLBAR_AddImage above). This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_ImageID value of such a member.<br />
: Defaults to TB_NO_ID (no image associated with this member)<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Text (CONST_STRPTR)<br />
: The label to associate with a button or a toggle member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
: The text label will be used as fallback in case no image is found or provided.<br />
: The text string can contain an underscore character (_), indicating the keyboard shortcut for this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Disabled (BOOL)<br />
: The current state (disabled or not disabled) of a member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Disabled value of such a member.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Hidden (BOOL)<br />
: Specifies whether the particular member is displayed in the toolbar or hidden. You can use this tag to create "dynamic" toolbar layouts that adapt the actual member set to various application settings.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Selected (BOOL)<br />
: The current selection state of a toggle member. This tag is not relevant to normal buttons (TB_MTYPE_BUTTON), spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Selected value of such a member.<br />
: You can set a target BOOPSI object for any toggle member, using the standard icclass ICA_TARGET tag. The target will receive an automatic notification of the toggle selection. This way toolbar toggles can easily communicate with other boolean gadgets such as checkboxes.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_NOTIFY, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Group (uint32)<br />
: Member group ID. Several members can be manipulated at once if they are assigned to the same group. Use TOOLBAR_SetGroup with the respective group ID to identify the group to be manipulated.<br />
: Defaults to TB_NO_ID (not assigned to any group)<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_MXGroup (uint32)<br />
: MX group ID. Toggle members can be put in groups of mutually-exclusive buttons. When such a toggle is selected, all other toggles in the same MX group will become deselected.<br />
: This tag is not relevant to normal buttons, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_MXGroup value of such a member.<br />
: Defaults to TB_NO_ID (not assigned to any MX group)<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_HintInfo (CONST_STRPTR)<br />
: The help text to be displayed when the user hovers the mouse pointer over the respective member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_HintInfo value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_UserData (APTR)<br />
: Arbitrary user data associated with this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
=== Image attributes ===<br />
<br />
; TBIMAGE_Image (struct Image *)<br />
: Custom image to be used for a button or a toggle member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_ImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImage (struct Image *)<br />
: Custom image to display when the member becomes selected.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TBIMAGE_SelImageFile (CONST_STRPTR)<br />
: The full path to the source file to create the select image from. The image will be loaded and built using the Shared Image class.<br />
: All images created this way will also be disposed of automatically.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
;TBIMAGE_Width (uint32)<br />
;TBIMAGE_Height (uint32)<br />
: Image dimensions, in pixels. These tags can only be used in connection with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the respective source file will be scaled to the specified width and height. Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot be resized using these tags.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW)<br />
<br />
== Notes ==<br />
<br />
Some of the attributes described above change the sizing requirements of the gadget. If set on the fly (i.e. when the toolbar is already displayed in the window), the gadget domain will need recalculating and a re-layout must take place. Refer to the [[#OM_SET|OM_SET]] method documentation below to see how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image. Image attributes cannot be changed later.<br />
<br />
== Bugs ==<br />
<br />
== See also ==<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
; NAME<br />
: OM_SET -- set toolbar attributes<br />
<br />
; SYNOPSIS<br />
: uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
: uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win, struct Requester *req, Tag tag1, ...);<br />
<br />
; FUNCTION<br />
: This method sets the attributes of the toolbar and/or of its members. SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions to invoke this method.<br />
: To change a member attribute you first need to pass TOOLBAR_SetMember to identify the respective member, and then the member attribute tag(s). See the EXAMPLE section below.<br />
: To change an attribute collectively for a group of members you first need to pass TOOLBAR_SetGroup to identify the respective group, and then the member attribute tag(s). See the EXAMPLE section below.<br />
<br />
; INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
; RESULT<br />
: This method will return TB_NEED_RETHINK if one or more of the attributes change the sizing requirements of the gadget. In such a case, the appropriate reaction is to call WM_RETHINK on the gadget's window object to recalculate the domain and re-layout the contents.<br />
: If you know you will be changing an attribute that requires a WM_RETHINK, prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
: The method returns 0 if no rethink is needed.<br />
<br />
; EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, GROUP_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
; NAME<br />
: TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
; SYNOPSIS<br />
: uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 attrID, uint32 *storage);<br />
<br />
; FUNCTION<br />
: Use this method to obtain the value of a given member attribute.<br />
: Because of the way OM_GET is implemented in Intuition, getting member attributes is done differently compared to setting them. The difference boils down to the following:<br />
<br />
* We cannot use a convenience function such as GetAttr() or GetAttrs(), so a dedicated method is provided. Refer to the EXAMPLE section below to see how to invoke the method.<br />
<br />
* Only one attribute can be queried at a time. (As multiple attributes will rarely be requested in real use, this limitation should not pose a significant problem.)<br />
<br />
; INPUTS<br />
* For IDoMethodA():<br />
<br />
toolbar-- the toolbar gadget object<br />
msg-- a pointer to an initialized tbGetMember structure<br />
<br />
* For IDoMethod():<br />
<br />
toolbar-- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
attrID -- the attribute tag identifier<br />
storage-- a pointer to the variable for storing the attribute value<br />
<br />
; RESULT<br />
: The "result" value will be 1L if the requested attribute value has been obtained successfully. The attribute value itself is returned in the provided storage variable.<br />
<br />
; EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID,<br />
TBMEMBER_Selected, &storage);<br />
<br />
; NOTES<br />
<br />
; BUGS<br />
<br />
; SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1004ToolBar Gadget Class2020-10-31T07:47:39Z<p>Trixie: </p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Methods ==<br />
<br />
OM_NEW -- creates the toolbar object, sets attributes and defaults<br />
<br />
OM_DISPOSE -- disposes of the toolbar object<br />
<br />
OM_REMMEMBER -- used by the class internally; consider this method private<br />
<br />
OM_SET -- sets toolbar, member and image attributes (see the OM_SET section below for more information)<br />
<br />
OM_GET -- retrieves toolbar attributes<br />
<br />
TBM_GETMEMBER -- retrieves a given member attribute (see the [[#TBM_GETMEMBER|TBM_GETMEMBER]] section below for more information)<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
; GA_ID (uint16)<br />
: Unique ID number for the gadget.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; GA_ReadOnly (BOOL)<br />
: If set to TRUE, none of the toolbar buttons will be selectable.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; GA_BackFill (struct Hook *)<br />
: A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
: Defaults to NULL (the default backfill hook).<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
; GA_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the gadget's button text labels (if they are used).<br />
: Defaults to the system's default public screen font.<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
; TOOLBAR_Orientation (uint32)<br />
: The toolbar orientation: horizontal or vertical.<br />
: Defaults to TB_ORIENT_HORIZ<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_Spacing (uint32)<br />
: The spacing between the individual toolbar members, in pixels.<br />
: Defaults to 2<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HorizPadding<br />
; TOOLBAR_VertPadding (uint32)<br />
: The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_InnerPadding (uint32)<br />
: The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.<br />
: Defaults to 4<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HandleOverflow (BOOL)<br />
: Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_MinVisible (uint32)<br />
: If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
: Defaults to 1<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SpacerSize (uint32)<br />
: The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.<br />
: Defaults to 5<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ButtonStyle (uint32)<br />
: The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
: Defaults to TB_BUTSTYLE_CLASSIC<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BevelStyle (uint32)<br />
: The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:<br />
<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
: When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.<br />
: Defaults to BVS_NONE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SeparatorStyle (uint32)<br />
: Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.<br />
: Defaults to TB_SEPSTYLE_NORMAL<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SelectionStyle (uint32)<br />
: Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.<br />
: This tag is ignored in the classic mode with framed buttons.<br />
: Defaults to TB_SELSTYLE_NONE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BackFill (struct Hook *)<br />
: A custom backfill hook to provide a background filled with a specific colour or pattern.<br />
: This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.<br />
: Defaults to NULL (the default layers backfill hook).<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
; TOOLBAR_Display (uint32)<br />
: Specifies what you want to display inside the toolbar button or toggle members. The possible values are:<br />
<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
: Defaults to TB_DISPLAY_IMAGES<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_TextPlace (uint32)<br />
: Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_LabelArray (STRPTR *)<br />
: Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.<br />
: TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
: Using this tag, the limitation is that you cannot create toggle members (only buttons, separators and spacers).<br />
: A special string, " ", will create a spacer.<br />
: A special string, "_", will create a separator.<br />
: Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.<br />
: The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TOOLBAR_EvenSize (BOOL)<br />
: If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.<br />
: If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ImageSet (uint32)<br />
: If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in the toolbar. The value passed to this tag is the image set ID.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:<br />
<br />
; TOOLBAR_AddImageSet (uint32)<br />
: Creates a new image set. The value passed to this tag is a numeric ID identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to display the particular image set in the toolbar.<br />
: This tag should be followed by a sequence of TOOLBAR_AddImage tags (see below), each creating one image in the given set.<br />
: If the gadget only uses one set of images, passing TOOLBAR_AddImageSet is not necessary. Each TOOLBAR_AddImage will add the respective image to the default image set identified by an ID of 0.<br />
: Applicability is (OM_NEW, OM_SET)<br />
<br />
; TOOLBAR_AddImage (uint32)<br />
: Creates a new image in a given image set. The value passed to this tag is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID (see below) to associate the image with a particular toolbar member.<br />
: This tag should be followed by a sequence of TBIMAGE_ tags (see the [[#Image attributes|Image attributes]] section below), each configuring one aspect of the image, including its optional selected variant (referred to as the "select image").<br />
: Images are added to the default image set unless a preceding TOOLBAR_AddImageSet specifies a different set.<br />
: Applicability is (OM_NEW, OM_SET)<br />
<br />
; TOOLBAR_AddMember (uint32)<br />
: Creates a new toolbar member. The value passed to this tag is a numeric ID identifying the member.<br />
: Spacers and separators normally don't need an ID, so you can use TB_NO_ID as a value for TOOLBAR_AddMember when creating these members. However, if you want to manipulate spacers/separators in your GUI, an ID will be necessary so that you can pass it to TOOLBAR_SetMember to identify the respective spacer or separator member.<br />
: You can add members when the toolbar object is being created, i.e. as part of the NewObject() call, or at any time later via SetAttrs().<br />
: Applicability is (OM_NEW, OM_SET)<br />
<br />
; TOOLBAR_SetMember<br />
: Use this tag in a SetAttrs() call to identify the member you want to modify.<br />
: Applicability is (OM_SET)<br />
<br />
; TOOLBAR_SetGroup<br />
: Use this tag in a SetAttrs() call to identify the group of members you want to modify collectively.<br />
: Applicability is (OM_SET)<br />
<br />
=== Member attributes ===<br />
<br />
; TBMEMBER_Type (uint32)<br />
: The type of the toolbar member. The possible values are the following:<br />
<br />
TB_MTYPE_BUTTON-- a normal toolbar button<br />
TB_MTYPE_TOGGLE-- a toggle (on/off) button<br />
TB_MTYPE_SPACER-- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
<br />
: The type is set upon member creation, and cannot be changed.<br />
: Defaults to TB_MTYPE_BUTTON<br />
: Applicability is (OM_NEW)<br />
<br />
; TBMEMBER_ImageID (uint32)<br />
: The identifier of the image to be used for the button or toggle member (see TOOLBAR_AddImage above). This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_ImageID value of such a member.<br />
: Defaults to TB_NO_ID (no image associated with this member)<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Text (CONST_STRPTR)<br />
: The label to associate with a button or a toggle member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
: The text label will be used as fallback in case no image is found or provided.<br />
: The text string can contain an underscore character (_), indicating the keyboard shortcut for this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Disabled (BOOL)<br />
: The current state (disabled or not disabled) of a member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Disabled value of such a member.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Hidden (BOOL)<br />
: Specifies whether the particular member is displayed in the toolbar or hidden. You can use this tag to create "dynamic" toolbar layouts that adapt the actual member set to various application settings.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Selected (BOOL)<br />
: The current selection state of a toggle member. This tag is not relevant to normal buttons (TB_MTYPE_BUTTON), spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Selected value of such a member.<br />
: You can set a target BOOPSI object for any toggle member, using the standard icclass ICA_TARGET tag. The target will receive an automatic notification of the toggle selection. This way toolbar toggles can easily communicate with other boolean gadgets such as checkboxes.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_NOTIFY, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_Group (uint32)<br />
: Member group ID. Several members can be manipulated at once if they are assigned to the same group. Use TOOLBAR_SetGroup with the respective group ID to identify the group to be manipulated.<br />
: Defaults to TB_NO_ID (not assigned to any group)<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_MXGroup (uint32)<br />
: MX group ID. Toggle members can be put in groups of mutually-exclusive buttons. When such a toggle is selected, all other toggles in the same MX group will become deselected.<br />
: This tag is not relevant to normal buttons, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_MXGroup value of such a member.<br />
: Defaults to TB_NO_ID (not assigned to any MX group)<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_HintInfo (CONST_STRPTR)<br />
: The help text to be displayed when the user hovers the mouse pointer over the respective member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_HintInfo value of such a member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
; TBMEMBER_UserData (APTR)<br />
: Arbitrary user data associated with this member.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])<br />
<br />
=== Image attributes ===<br />
<br />
TBIMAGE_Image (struct Image *)<br />
Custom image to be used for a button or a toggle member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_ImageFile (CONST_STRPTR)<br />
The full path to the source file to create the image from. The image<br />
will be loaded and built using the Shared Image class.<br />
<br />
All images created this way will also be disposed of automatically.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_SelImage (struct Image *)<br />
Custom image to display when the member becomes selected.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_SelImageFile (CONST_STRPTR)<br />
The full path to the source file to create the select image from.<br />
The image will be loaded and built using the Shared Image class.<br />
<br />
All images created this way will also be disposed of automatically.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_Width (uint32)<br />
TBIMAGE_Height (uint32)<br />
Image dimensions, in pixels. These tags can only be used in connection<br />
with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the<br />
respective source file will be scaled to the specified width and height.<br />
Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot<br />
be resized using these tags.<br />
<br />
Defaults to 0<br />
<br />
Applicability is (OM_NEW)<br />
<br />
NOTES<br />
Some of the attributes described above change the sizing requirements of<br />
the gadget. If set on the fly (i.e. when the toolbar is already displayed<br />
in the window), the gadget domain will need recalculating and a re-layout<br />
must take place. Refer to the OM_SET method documentation below to see<br />
how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image.<br />
Image attributes cannot be changed later.<br />
<br />
BUGS<br />
<br />
<br />
SEE ALSO<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
NAME<br />
OM_SET -- set toolbar attributes<br />
<br />
SYNOPSIS<br />
uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
<br />
uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win,<br />
struct Requester *req, Tag tag1, ...);<br />
<br />
FUNCTION<br />
This method sets the attributes of the toolbar and/or of its members.<br />
SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions<br />
to invoke this method.<br />
<br />
To change a member attribute you first need to pass TOOLBAR_SetMember<br />
to identify the respective member, and then the member attribute tag(s).<br />
See the EXAMPLE section below.<br />
<br />
To change an attribute collectively for a group of members you first need<br />
to pass TOOLBAR_SetGroup to identify the respective group, and then the<br />
member attribute tag(s). See the EXAMPLE section below.<br />
<br />
INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
RESULT<br />
This method will return TB_NEED_RETHINK if one or more of the attributes<br />
change the sizing requirements of the gadget. In such a case, the<br />
appropriate reaction is to call WM_RETHINK on the gadget's window object<br />
to recalculate the domain and re-layout the contents.<br />
<br />
If you know you will be changing an attribute that requires a WM_RETHINK,<br />
prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an<br />
unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
<br />
The method returns 0 if no rethink is needed.<br />
<br />
EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, GROUP_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
NOTES<br />
<br />
BUGS<br />
<br />
SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
NAME<br />
TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
SYNOPSIS<br />
uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
<br />
uint32 result = IDoMethod(Object *toolbar, uint32 methodID,<br />
uint32 attrID, uint32 *storage);<br />
<br />
FUNCTION<br />
Use this method to obtain the value of a given member attribute.<br />
<br />
Because of the way OM_GET is implemented in Intuition, getting member<br />
attributes is done differently compared to setting them. The difference<br />
boils down to the following:<br />
<br />
- We cannot use a convenience function such as GetAttr() or GetAttrs(),<br />
so a dedicated method is provided. Refer to the EXAMPLE section below<br />
to see how to invoke the method.<br />
<br />
- Only one attribute can be queried at a time. (As multiple attributes<br />
will rarely be requested in real use, this limitation should not pose<br />
a significant problem.)<br />
<br />
INPUTS<br />
For IDoMethodA():<br />
toolbar-- the toolbar gadget object<br />
msg-- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
toolbar-- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
attrID -- the attribute tag identifier<br />
storage-- a pointer to the variable for storing the attribute value<br />
<br />
RESULT<br />
The "result" value will be 1L if the requested attribute value has been<br />
obtained successfully. The attribute value itself is returned in the<br />
provided storage variable.<br />
<br />
EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID,<br />
TBMEMBER_Selected, &storage);<br />
<br />
NOTES<br />
<br />
BUGS<br />
<br />
SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1003ToolBar Gadget Class2020-10-31T06:39:15Z<p>Trixie: </p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Methods ==<br />
<br />
OM_NEW -- creates the toolbar object, sets attributes and defaults<br />
<br />
OM_DISPOSE -- disposes of the toolbar object<br />
<br />
OM_REMMEMBER -- used by the class internally; consider this method private<br />
<br />
OM_SET -- sets toolbar, member and image attributes (see the OM_SET section below for more information)<br />
<br />
OM_GET -- retrieves toolbar attributes<br />
<br />
TBM_GETMEMBER -- retrieves a given member attribute (see the TBM_GETMEMBER section below for more information)<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
; GA_ID (uint16)<br />
: Unique ID number for the gadget.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; GA_ReadOnly (BOOL)<br />
: If set to TRUE, none of the toolbar buttons will be selectable.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; GA_BackFill (struct Hook *)<br />
: A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
: Defaults to NULL (the default backfill hook).<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
; GA_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the gadget's button text labels (if they are used).<br />
: Defaults to the system's default public screen font.<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
; TOOLBAR_Orientation (uint32)<br />
: The toolbar orientation: horizontal or vertical.<br />
: Defaults to TB_ORIENT_HORIZ<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_Spacing (uint32)<br />
: The spacing between the individual toolbar members, in pixels.<br />
: Defaults to 2<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HorizPadding<br />
; TOOLBAR_VertPadding (uint32)<br />
: The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_InnerPadding (uint32)<br />
: The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.<br />
: Defaults to 4<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HandleOverflow (BOOL)<br />
: Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_MinVisible (uint32)<br />
: If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
: Defaults to 1<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SpacerSize (uint32)<br />
: The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.<br />
: Defaults to 5<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ButtonStyle (uint32)<br />
: The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
: Defaults to TB_BUTSTYLE_CLASSIC<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BevelStyle (uint32)<br />
: The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:<br />
<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
: When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.<br />
: Defaults to BVS_NONE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SeparatorStyle (uint32)<br />
: Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.<br />
: Defaults to TB_SEPSTYLE_NORMAL<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SelectionStyle (uint32)<br />
: Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.<br />
: This tag is ignored in the classic mode with framed buttons.<br />
: Defaults to TB_SELSTYLE_NONE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BackFill (struct Hook *)<br />
: A custom backfill hook to provide a background filled with a specific colour or pattern.<br />
: This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.<br />
: Defaults to NULL (the default layers backfill hook).<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
; TOOLBAR_Display (uint32)<br />
: Specifies what you want to display inside the toolbar button or toggle members. The possible values are:<br />
<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
: Defaults to TB_DISPLAY_IMAGES<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_TextPlace (uint32)<br />
: Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_LabelArray (STRPTR *)<br />
: Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.<br />
: TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
: Using this tag, the limitation is that you cannot create toggle members (only buttons, separators and spacers).<br />
: A special string, " ", will create a spacer.<br />
: A special string, "_", will create a separator.<br />
: Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.<br />
: The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TOOLBAR_EvenSize (BOOL)<br />
: If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.<br />
: If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ImageSet (uint32)<br />
: If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in the toolbar. The value passed to this tag is the image set ID.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:<br />
<br />
TOOLBAR_AddImageSet (uint32)<br />
Creates a new image set. The value passed to this tag is a numeric ID<br />
identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to<br />
display the particular image set in the toolbar.<br />
<br />
This tag should be followed by a sequence of TOOLBAR_AddImage tags (see<br />
below), each creating one image in the given set.<br />
<br />
If the gadget only uses one set of images, passing TOOLBAR_AddImageSet<br />
is not necessary. Each TOOLBAR_AddImage will add the respective image<br />
to the default image set identified by an ID of 0.<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
TOOLBAR_AddImage (uint32)<br />
Creates a new image in a given image set. The value passed to this tag<br />
is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID<br />
(see below) to associate the image with a particular toolbar member.<br />
<br />
This tag should be followed by a sequence of TBIMAGE_ tags (see the<br />
"Image attributes" section below), each configuring one aspect of the<br />
image, including its optional selected variant (referred to as the<br />
"select image").<br />
<br />
Images are added to the default image set unless a preceding<br />
TOOLBAR_AddImageSet specifies a different set.<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
TOOLBAR_AddMember (uint32)<br />
Creates a new toolbar member. The value passed to this tag is a numeric<br />
ID identifying the member.<br />
<br />
Spacers and separators normally don't need an ID, so you can use<br />
TB_NO_ID as a value for TOOLBAR_AddMember when creating these members.<br />
However, if you want to manipulate spacers/separators in your GUI,<br />
an ID will be necessary so that you can pass it to TOOLBAR_SetMember<br />
to identify the respective spacer or separator member.<br />
<br />
You can add members when the toolbar object is being created, i.e.<br />
as part of the NewObject() call, or at any time later via SetAttrs().<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
TOOLBAR_SetMember<br />
Use this tag in a SetAttrs() call to identify the member you want to<br />
modify.<br />
<br />
Applicability is (OM_SET)<br />
<br />
TOOLBAR_SetGroup<br />
Use this tag in a SetAttrs() call to identify the group of members you<br />
want to modify collectively.<br />
<br />
Applicability is (OM_SET)<br />
<br />
=== Member attributes ===<br />
<br />
TBMEMBER_Type (uint32)<br />
The type of the toolbar member. The possible values are the following:<br />
TB_MTYPE_BUTTON-- a normal toolbar button<br />
TB_MTYPE_TOGGLE-- a toggle (on/off) button<br />
TB_MTYPE_SPACER-- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
<br />
The type is set upon member creation, and cannot be changed.<br />
<br />
Defaults to TB_MTYPE_BUTTON<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBMEMBER_ImageID (uint32)<br />
The identifier of the image to be used for the button or toggle member<br />
(see TOOLBAR_AddImage above). This tag is not relevant to spacers and<br />
separators; TBM_GETMEMBER will always return TB_NO_ID should you inquire<br />
about the TBMEMBER_ImageID value of such a member.<br />
<br />
Defaults to TB_NO_ID (no image associated with this member)<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Text (CONST_STRPTR)<br />
The label to associate with a button or a toggle member. This tag is not<br />
relevant to spacers and separators; TBM_GETMEMBER will always return<br />
NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
<br />
The text label will be used as fallback in case no image is found or<br />
provided.<br />
<br />
The text string can contain an underscore character (_), indicating the<br />
keyboard shortcut for this member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Disabled (BOOL)<br />
The current state (disabled or not disabled) of a member. This tag is<br />
not relevant to spacers and separators; TBM_GETMEMBER will always return<br />
FALSE should you inquire about the TBMEMBER_Disabled value of such<br />
a member.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Hidden (BOOL)<br />
Specifies whether the particular member is displayed in the toolbar or<br />
hidden. You can use this tag to create "dynamic" toolbar layouts that<br />
adapt the actual member set to various application settings.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Selected (BOOL)<br />
The current selection state of a toggle member. This tag is not relevant<br />
to normal buttons (TB_MTYPE_BUTTON), spacers and separators;<br />
TBM_GETMEMBER will always return FALSE should you inquire about the<br />
TBMEMBER_Selected value of such a member.<br />
<br />
You can set a target BOOPSI object for any toggle member, using the<br />
standard icclass ICA_TARGET tag. The target will receive an automatic<br />
notification of the toggle selection. This way toolbar toggles can<br />
easily communicate with other boolean gadgets such as checkboxes.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_NOTIFY, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Group (uint32)<br />
Member group ID. Several members can be manipulated at once if they are<br />
assigned to the same group. Use TOOLBAR_SetGroup with the respective<br />
group ID to identify the group to be manipulated.<br />
<br />
Defaults to TB_NO_ID (not assigned to any group)<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_MXGroup (uint32)<br />
MX group ID. Toggle members can be put in groups of mutually-exclusive<br />
buttons. When such a toggle is selected, all other toggles in the same<br />
MX group will become deselected.<br />
<br />
This tag is not relevant to normal buttons, spacers and separators;<br />
TBM_GETMEMBER will always return TB_NO_ID should you inquire about the<br />
TBMEMBER_MXGroup value of such a member.<br />
<br />
Defaults to TB_NO_ID (not assigned to any MX group)<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_HintInfo (CONST_STRPTR)<br />
The help text to be displayed when the user hovers the mouse pointer<br />
over the respective member. This tag is not relevant to spacers and<br />
separators; TBM_GETMEMBER will always return NULL should you inquire<br />
about the TBMEMBER_HintInfo value of such a member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_UserData (APTR)<br />
Arbitrary user data associated with this member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
=== Image attributes ===<br />
<br />
TBIMAGE_Image (struct Image *)<br />
Custom image to be used for a button or a toggle member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_ImageFile (CONST_STRPTR)<br />
The full path to the source file to create the image from. The image<br />
will be loaded and built using the Shared Image class.<br />
<br />
All images created this way will also be disposed of automatically.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_SelImage (struct Image *)<br />
Custom image to display when the member becomes selected.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_SelImageFile (CONST_STRPTR)<br />
The full path to the source file to create the select image from.<br />
The image will be loaded and built using the Shared Image class.<br />
<br />
All images created this way will also be disposed of automatically.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_Width (uint32)<br />
TBIMAGE_Height (uint32)<br />
Image dimensions, in pixels. These tags can only be used in connection<br />
with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the<br />
respective source file will be scaled to the specified width and height.<br />
Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot<br />
be resized using these tags.<br />
<br />
Defaults to 0<br />
<br />
Applicability is (OM_NEW)<br />
<br />
NOTES<br />
Some of the attributes described above change the sizing requirements of<br />
the gadget. If set on the fly (i.e. when the toolbar is already displayed<br />
in the window), the gadget domain will need recalculating and a re-layout<br />
must take place. Refer to the OM_SET method documentation below to see<br />
how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image.<br />
Image attributes cannot be changed later.<br />
<br />
BUGS<br />
<br />
<br />
SEE ALSO<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
NAME<br />
OM_SET -- set toolbar attributes<br />
<br />
SYNOPSIS<br />
uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
<br />
uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win,<br />
struct Requester *req, Tag tag1, ...);<br />
<br />
FUNCTION<br />
This method sets the attributes of the toolbar and/or of its members.<br />
SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions<br />
to invoke this method.<br />
<br />
To change a member attribute you first need to pass TOOLBAR_SetMember<br />
to identify the respective member, and then the member attribute tag(s).<br />
See the EXAMPLE section below.<br />
<br />
To change an attribute collectively for a group of members you first need<br />
to pass TOOLBAR_SetGroup to identify the respective group, and then the<br />
member attribute tag(s). See the EXAMPLE section below.<br />
<br />
INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
RESULT<br />
This method will return TB_NEED_RETHINK if one or more of the attributes<br />
change the sizing requirements of the gadget. In such a case, the<br />
appropriate reaction is to call WM_RETHINK on the gadget's window object<br />
to recalculate the domain and re-layout the contents.<br />
<br />
If you know you will be changing an attribute that requires a WM_RETHINK,<br />
prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an<br />
unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
<br />
The method returns 0 if no rethink is needed.<br />
<br />
EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, GROUP_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
NOTES<br />
<br />
BUGS<br />
<br />
SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
NAME<br />
TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
SYNOPSIS<br />
uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
<br />
uint32 result = IDoMethod(Object *toolbar, uint32 methodID,<br />
uint32 attrID, uint32 *storage);<br />
<br />
FUNCTION<br />
Use this method to obtain the value of a given member attribute.<br />
<br />
Because of the way OM_GET is implemented in Intuition, getting member<br />
attributes is done differently compared to setting them. The difference<br />
boils down to the following:<br />
<br />
- We cannot use a convenience function such as GetAttr() or GetAttrs(),<br />
so a dedicated method is provided. Refer to the EXAMPLE section below<br />
to see how to invoke the method.<br />
<br />
- Only one attribute can be queried at a time. (As multiple attributes<br />
will rarely be requested in real use, this limitation should not pose<br />
a significant problem.)<br />
<br />
INPUTS<br />
For IDoMethodA():<br />
toolbar-- the toolbar gadget object<br />
msg-- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
toolbar-- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
attrID -- the attribute tag identifier<br />
storage-- a pointer to the variable for storing the attribute value<br />
<br />
RESULT<br />
The "result" value will be 1L if the requested attribute value has been<br />
obtained successfully. The attribute value itself is returned in the<br />
provided storage variable.<br />
<br />
EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID,<br />
TBMEMBER_Selected, &storage);<br />
<br />
NOTES<br />
<br />
BUGS<br />
<br />
SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1002ToolBar Gadget Class2020-10-31T06:34:07Z<p>Trixie: </p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Methods ==<br />
<br />
OM_NEW -- creates the toolbar object, sets attributes and defaults<br />
<br />
OM_DISPOSE -- disposes of the toolbar object<br />
<br />
OM_REMMEMBER -- used by the class internally; consider this method private<br />
<br />
OM_SET -- sets toolbar, member and image attributes (see the OM_SET section below for more information)<br />
<br />
OM_GET -- retrieves toolbar attributes<br />
<br />
TBM_GETMEMBER -- retrieves a given member attribute (see the TBM_GETMEMBER section below for more information)<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
; GA_ID (uint16)<br />
: Unique ID number for the gadget.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; GA_ReadOnly (BOOL)<br />
: If set to TRUE, none of the toolbar buttons will be selectable.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; GA_BackFill (struct Hook *)<br />
: A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
: Defaults to NULL (the default backfill hook).<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
; GA_TextAttr (struct TextAttr *)<br />
: Pointer to a TextAttr structure describing the font to be used for the gadget's button text labels (if they are used).<br />
: Defaults to the system's default public screen font.<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
; TOOLBAR_Orientation (uint32)<br />
: The toolbar orientation: horizontal or vertical.<br />
: Defaults to TB_ORIENT_HORIZ<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_Spacing (uint32)<br />
: The spacing between the individual toolbar members, in pixels.<br />
: Defaults to 2<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HorizPadding / TOOLBAR_VertPadding (uint32)<br />
: The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_InnerPadding (uint32)<br />
: The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.<br />
: Defaults to 4<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_HandleOverflow (BOOL)<br />
: Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_MinVisible (uint32)<br />
: If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
: Defaults to 1<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SpacerSize (uint32)<br />
: The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.<br />
: Defaults to 5<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ButtonStyle (uint32)<br />
: The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
: Defaults to TB_BUTSTYLE_CLASSIC<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BevelStyle (uint32)<br />
: The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:<br />
<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
: When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.<br />
: Defaults to BVS_NONE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SeparatorStyle (uint32)<br />
: Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.<br />
: Defaults to TB_SEPSTYLE_NORMAL<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_SelectionStyle (uint32)<br />
: Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.<br />
: This tag is ignored in the classic mode with framed buttons.<br />
: Defaults to TB_SELSTYLE_NONE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_BackFill (struct Hook *)<br />
: A custom backfill hook to provide a background filled with a specific colour or pattern.<br />
: This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.<br />
: Defaults to NULL (the default layers backfill hook).<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
; TOOLBAR_Display (uint32)<br />
: Specifies what you want to display inside the toolbar button or toggle members. The possible values are:<br />
<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
: Defaults to TB_DISPLAY_IMAGES<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_TextPlace (uint32)<br />
: Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are<br />
provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_LabelArray (STRPTR *)<br />
: Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing<br />
the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.<br />
: TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
: Using this tag, the limitation is that you cannot create toggle members (only buttons, separators and spacers).<br />
: A special string, " ", will create a spacer.<br />
: A special string, "_", will create a separator.<br />
: Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or<br />
a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.<br />
: The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.<br />
: Defaults to NULL<br />
: Applicability is (OM_NEW)<br />
<br />
; TOOLBAR_EvenSize (BOOL)<br />
: If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.<br />
: If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute<br />
at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other <br />
hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
: Defaults to FALSE<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
; TOOLBAR_ImageSet (uint32)<br />
: If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in<br />
the toolbar. The value passed to this tag is the image set ID.<br />
: Defaults to 0<br />
: Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:<br />
<br />
TOOLBAR_AddImageSet (uint32)<br />
Creates a new image set. The value passed to this tag is a numeric ID<br />
identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to<br />
display the particular image set in the toolbar.<br />
<br />
This tag should be followed by a sequence of TOOLBAR_AddImage tags (see<br />
below), each creating one image in the given set.<br />
<br />
If the gadget only uses one set of images, passing TOOLBAR_AddImageSet<br />
is not necessary. Each TOOLBAR_AddImage will add the respective image<br />
to the default image set identified by an ID of 0.<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
TOOLBAR_AddImage (uint32)<br />
Creates a new image in a given image set. The value passed to this tag<br />
is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID<br />
(see below) to associate the image with a particular toolbar member.<br />
<br />
This tag should be followed by a sequence of TBIMAGE_ tags (see the<br />
"Image attributes" section below), each configuring one aspect of the<br />
image, including its optional selected variant (referred to as the<br />
"select image").<br />
<br />
Images are added to the default image set unless a preceding<br />
TOOLBAR_AddImageSet specifies a different set.<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
TOOLBAR_AddMember (uint32)<br />
Creates a new toolbar member. The value passed to this tag is a numeric<br />
ID identifying the member.<br />
<br />
Spacers and separators normally don't need an ID, so you can use<br />
TB_NO_ID as a value for TOOLBAR_AddMember when creating these members.<br />
However, if you want to manipulate spacers/separators in your GUI,<br />
an ID will be necessary so that you can pass it to TOOLBAR_SetMember<br />
to identify the respective spacer or separator member.<br />
<br />
You can add members when the toolbar object is being created, i.e.<br />
as part of the NewObject() call, or at any time later via SetAttrs().<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
TOOLBAR_SetMember<br />
Use this tag in a SetAttrs() call to identify the member you want to<br />
modify.<br />
<br />
Applicability is (OM_SET)<br />
<br />
TOOLBAR_SetGroup<br />
Use this tag in a SetAttrs() call to identify the group of members you<br />
want to modify collectively.<br />
<br />
Applicability is (OM_SET)<br />
<br />
=== Member attributes ===<br />
<br />
TBMEMBER_Type (uint32)<br />
The type of the toolbar member. The possible values are the following:<br />
TB_MTYPE_BUTTON-- a normal toolbar button<br />
TB_MTYPE_TOGGLE-- a toggle (on/off) button<br />
TB_MTYPE_SPACER-- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
<br />
The type is set upon member creation, and cannot be changed.<br />
<br />
Defaults to TB_MTYPE_BUTTON<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBMEMBER_ImageID (uint32)<br />
The identifier of the image to be used for the button or toggle member<br />
(see TOOLBAR_AddImage above). This tag is not relevant to spacers and<br />
separators; TBM_GETMEMBER will always return TB_NO_ID should you inquire<br />
about the TBMEMBER_ImageID value of such a member.<br />
<br />
Defaults to TB_NO_ID (no image associated with this member)<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Text (CONST_STRPTR)<br />
The label to associate with a button or a toggle member. This tag is not<br />
relevant to spacers and separators; TBM_GETMEMBER will always return<br />
NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
<br />
The text label will be used as fallback in case no image is found or<br />
provided.<br />
<br />
The text string can contain an underscore character (_), indicating the<br />
keyboard shortcut for this member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Disabled (BOOL)<br />
The current state (disabled or not disabled) of a member. This tag is<br />
not relevant to spacers and separators; TBM_GETMEMBER will always return<br />
FALSE should you inquire about the TBMEMBER_Disabled value of such<br />
a member.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Hidden (BOOL)<br />
Specifies whether the particular member is displayed in the toolbar or<br />
hidden. You can use this tag to create "dynamic" toolbar layouts that<br />
adapt the actual member set to various application settings.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Selected (BOOL)<br />
The current selection state of a toggle member. This tag is not relevant<br />
to normal buttons (TB_MTYPE_BUTTON), spacers and separators;<br />
TBM_GETMEMBER will always return FALSE should you inquire about the<br />
TBMEMBER_Selected value of such a member.<br />
<br />
You can set a target BOOPSI object for any toggle member, using the<br />
standard icclass ICA_TARGET tag. The target will receive an automatic<br />
notification of the toggle selection. This way toolbar toggles can<br />
easily communicate with other boolean gadgets such as checkboxes.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_NOTIFY, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Group (uint32)<br />
Member group ID. Several members can be manipulated at once if they are<br />
assigned to the same group. Use TOOLBAR_SetGroup with the respective<br />
group ID to identify the group to be manipulated.<br />
<br />
Defaults to TB_NO_ID (not assigned to any group)<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_MXGroup (uint32)<br />
MX group ID. Toggle members can be put in groups of mutually-exclusive<br />
buttons. When such a toggle is selected, all other toggles in the same<br />
MX group will become deselected.<br />
<br />
This tag is not relevant to normal buttons, spacers and separators;<br />
TBM_GETMEMBER will always return TB_NO_ID should you inquire about the<br />
TBMEMBER_MXGroup value of such a member.<br />
<br />
Defaults to TB_NO_ID (not assigned to any MX group)<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_HintInfo (CONST_STRPTR)<br />
The help text to be displayed when the user hovers the mouse pointer<br />
over the respective member. This tag is not relevant to spacers and<br />
separators; TBM_GETMEMBER will always return NULL should you inquire<br />
about the TBMEMBER_HintInfo value of such a member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_UserData (APTR)<br />
Arbitrary user data associated with this member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
=== Image attributes ===<br />
<br />
TBIMAGE_Image (struct Image *)<br />
Custom image to be used for a button or a toggle member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_ImageFile (CONST_STRPTR)<br />
The full path to the source file to create the image from. The image<br />
will be loaded and built using the Shared Image class.<br />
<br />
All images created this way will also be disposed of automatically.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_SelImage (struct Image *)<br />
Custom image to display when the member becomes selected.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_SelImageFile (CONST_STRPTR)<br />
The full path to the source file to create the select image from.<br />
The image will be loaded and built using the Shared Image class.<br />
<br />
All images created this way will also be disposed of automatically.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_Width (uint32)<br />
TBIMAGE_Height (uint32)<br />
Image dimensions, in pixels. These tags can only be used in connection<br />
with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the<br />
respective source file will be scaled to the specified width and height.<br />
Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot<br />
be resized using these tags.<br />
<br />
Defaults to 0<br />
<br />
Applicability is (OM_NEW)<br />
<br />
NOTES<br />
Some of the attributes described above change the sizing requirements of<br />
the gadget. If set on the fly (i.e. when the toolbar is already displayed<br />
in the window), the gadget domain will need recalculating and a re-layout<br />
must take place. Refer to the OM_SET method documentation below to see<br />
how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image.<br />
Image attributes cannot be changed later.<br />
<br />
BUGS<br />
<br />
<br />
SEE ALSO<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
NAME<br />
OM_SET -- set toolbar attributes<br />
<br />
SYNOPSIS<br />
uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
<br />
uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win,<br />
struct Requester *req, Tag tag1, ...);<br />
<br />
FUNCTION<br />
This method sets the attributes of the toolbar and/or of its members.<br />
SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions<br />
to invoke this method.<br />
<br />
To change a member attribute you first need to pass TOOLBAR_SetMember<br />
to identify the respective member, and then the member attribute tag(s).<br />
See the EXAMPLE section below.<br />
<br />
To change an attribute collectively for a group of members you first need<br />
to pass TOOLBAR_SetGroup to identify the respective group, and then the<br />
member attribute tag(s). See the EXAMPLE section below.<br />
<br />
INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
RESULT<br />
This method will return TB_NEED_RETHINK if one or more of the attributes<br />
change the sizing requirements of the gadget. In such a case, the<br />
appropriate reaction is to call WM_RETHINK on the gadget's window object<br />
to recalculate the domain and re-layout the contents.<br />
<br />
If you know you will be changing an attribute that requires a WM_RETHINK,<br />
prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an<br />
unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
<br />
The method returns 0 if no rethink is needed.<br />
<br />
EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, GROUP_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
NOTES<br />
<br />
BUGS<br />
<br />
SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
NAME<br />
TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
SYNOPSIS<br />
uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
<br />
uint32 result = IDoMethod(Object *toolbar, uint32 methodID,<br />
uint32 attrID, uint32 *storage);<br />
<br />
FUNCTION<br />
Use this method to obtain the value of a given member attribute.<br />
<br />
Because of the way OM_GET is implemented in Intuition, getting member<br />
attributes is done differently compared to setting them. The difference<br />
boils down to the following:<br />
<br />
- We cannot use a convenience function such as GetAttr() or GetAttrs(),<br />
so a dedicated method is provided. Refer to the EXAMPLE section below<br />
to see how to invoke the method.<br />
<br />
- Only one attribute can be queried at a time. (As multiple attributes<br />
will rarely be requested in real use, this limitation should not pose<br />
a significant problem.)<br />
<br />
INPUTS<br />
For IDoMethodA():<br />
toolbar-- the toolbar gadget object<br />
msg-- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
toolbar-- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
attrID -- the attribute tag identifier<br />
storage-- a pointer to the variable for storing the attribute value<br />
<br />
RESULT<br />
The "result" value will be 1L if the requested attribute value has been<br />
obtained successfully. The attribute value itself is returned in the<br />
provided storage variable.<br />
<br />
EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID,<br />
TBMEMBER_Selected, &storage);<br />
<br />
NOTES<br />
<br />
BUGS<br />
<br />
SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1001ToolBar Gadget Class2020-10-30T22:54:54Z<p>Trixie: </p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Methods ==<br />
<br />
OM_NEW -- creates the toolbar object, sets attributes and defaults<br />
<br />
OM_DISPOSE -- disposes of the toolbar object<br />
<br />
OM_REMMEMBER -- used by the class internally; consider this method private<br />
<br />
OM_SET -- sets toolbar, member and image attributes (see the OM_SET section below for more information)<br />
<br />
OM_GET -- retrieves toolbar attributes<br />
<br />
TBM_GETMEMBER -- retrieves a given member attribute (see the TBM_GETMEMBER section below for more information)<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
GA_ID (uint16)<br />
<br />
Unique ID number for the gadget.<br />
<br />
Defaults to 0<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
GA_ReadOnly (BOOL)<br />
<br />
If set to TRUE, none of the toolbar buttons will be selectable.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
GA_BackFill (struct Hook *)<br />
<br />
A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
<br />
Defaults to NULL (the default backfill hook).<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
GA_TextAttr (struct TextAttr *)<br />
<br />
Pointer to a TextAttr structure describing the font to be used for the gadget's button text labels (if they are used).<br />
<br />
Defaults to the system's default public screen font.<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
TOOLBAR_Orientation (uint32)<br />
<br />
The toolbar orientation: horizontal or vertical.<br />
<br />
Defaults to TB_ORIENT_HORIZ<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_Spacing (uint32)<br />
<br />
The spacing between the individual toolbar members, in pixels.<br />
<br />
Defaults to 2<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_HorizPadding / TOOLBAR_VertPadding (uint32)<br />
<br />
The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).<br />
<br />
Defaults to 0<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_InnerPadding (uint32)<br />
<br />
The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.<br />
<br />
Defaults to 4<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_HandleOverflow (BOOL)<br />
<br />
Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_MinVisible (uint32)<br />
<br />
If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
<br />
Defaults to 1<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_SpacerSize (uint32)<br />
<br />
The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.<br />
<br />
Defaults to 5<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_ButtonStyle (uint32)<br />
<br />
The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
<br />
Defaults to TB_BUTSTYLE_CLASSIC<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_BevelStyle (uint32)<br />
<br />
The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:<br />
<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.<br />
<br />
Defaults to BVS_NONE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_SeparatorStyle (uint32)<br />
<br />
Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.<br />
<br />
Defaults to TB_SEPSTYLE_NORMAL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_SelectionStyle (uint32)<br />
<br />
Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.<br />
<br />
This tag is ignored in the classic mode with framed buttons.<br />
<br />
Defaults to TB_SELSTYLE_NONE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_BackFill (struct Hook *)<br />
<br />
A custom backfill hook to provide a background filled with a specific colour or pattern.<br />
<br />
This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.<br />
<br />
Defaults to NULL (the default layers backfill hook).<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
TOOLBAR_Display (uint32)<br />
<br />
Specifies what you want to display inside the toolbar button or toggle members. The possible values are:<br />
<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
Defaults to TB_DISPLAY_IMAGES<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_TextPlace (uint32)<br />
<br />
Specifies the placement of the text labels with regard to the toolbar<br />
images. This tag is only meaningful when actual text labels are<br />
provided via TBMEMBER_Text, and TOOLBAR_Display is set to<br />
TB_DISPLAY_BOTH.<br />
<br />
Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_LabelArray (STRPTR *)<br />
<br />
Use this tag to create a minimum-configuration, text-only toolbar.<br />
You simply pass a NULL-terminated array of strings representing<br />
the toolbar button labels. Each label can contain an underscore<br />
character to indicate the keyboard shortcut for the respective button.<br />
<br />
TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
<br />
Using this tag, the limitation is that you cannot create toggle members<br />
(only buttons, separators and spacers).<br />
<br />
A special string, " ", will create a spacer.<br />
A special string, "_", will create a separator.<br />
<br />
Spacers and separators cannot appear as the very first member in the<br />
toolbar. Therefore, the label array may not begin with a spacer or<br />
a separator string. Also, the array must contain at least one valid<br />
string to create a button, otherwise the toolbar creation will fail.<br />
<br />
The button strings are copied to an internal buffer, so the label array<br />
need not remain valid throughout the lifetime of the gadget.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TOOLBAR_EvenSize (BOOL)<br />
<br />
If set to TRUE, this attribute will size all button and toggle members<br />
evenly according to the largest member. The attribute has no effect<br />
on spacers and separators.<br />
<br />
If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above)<br />
and your toolbar images are all of the same size, keep this attribute<br />
at its default FALSE value: the button dimensions will be equal anyway,<br />
and you'll spare the gadget some unnecessary calculations. On the other <br />
hand, setting this tag to TRUE may produce a visually more plausible<br />
result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_ImageSet (uint32)<br />
<br />
If more than one image set have been configured via TOOLBAR_AddImageSet<br />
(see below), use this tag to determine which set is to be displayed in<br />
the toolbar. The value passed to this tag is the image set ID.<br />
<br />
Defaults to 0<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform<br />
various functions associated with toolbar configuration:<br />
<br />
TOOLBAR_AddImageSet (uint32)<br />
Creates a new image set. The value passed to this tag is a numeric ID<br />
identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to<br />
display the particular image set in the toolbar.<br />
<br />
This tag should be followed by a sequence of TOOLBAR_AddImage tags (see<br />
below), each creating one image in the given set.<br />
<br />
If the gadget only uses one set of images, passing TOOLBAR_AddImageSet<br />
is not necessary. Each TOOLBAR_AddImage will add the respective image<br />
to the default image set identified by an ID of 0.<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
TOOLBAR_AddImage (uint32)<br />
Creates a new image in a given image set. The value passed to this tag<br />
is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID<br />
(see below) to associate the image with a particular toolbar member.<br />
<br />
This tag should be followed by a sequence of TBIMAGE_ tags (see the<br />
"Image attributes" section below), each configuring one aspect of the<br />
image, including its optional selected variant (referred to as the<br />
"select image").<br />
<br />
Images are added to the default image set unless a preceding<br />
TOOLBAR_AddImageSet specifies a different set.<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
TOOLBAR_AddMember (uint32)<br />
Creates a new toolbar member. The value passed to this tag is a numeric<br />
ID identifying the member.<br />
<br />
Spacers and separators normally don't need an ID, so you can use<br />
TB_NO_ID as a value for TOOLBAR_AddMember when creating these members.<br />
However, if you want to manipulate spacers/separators in your GUI,<br />
an ID will be necessary so that you can pass it to TOOLBAR_SetMember<br />
to identify the respective spacer or separator member.<br />
<br />
You can add members when the toolbar object is being created, i.e.<br />
as part of the NewObject() call, or at any time later via SetAttrs().<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
TOOLBAR_SetMember<br />
Use this tag in a SetAttrs() call to identify the member you want to<br />
modify.<br />
<br />
Applicability is (OM_SET)<br />
<br />
TOOLBAR_SetGroup<br />
Use this tag in a SetAttrs() call to identify the group of members you<br />
want to modify collectively.<br />
<br />
Applicability is (OM_SET)<br />
<br />
=== Member attributes ===<br />
<br />
TBMEMBER_Type (uint32)<br />
The type of the toolbar member. The possible values are the following:<br />
TB_MTYPE_BUTTON-- a normal toolbar button<br />
TB_MTYPE_TOGGLE-- a toggle (on/off) button<br />
TB_MTYPE_SPACER-- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
<br />
The type is set upon member creation, and cannot be changed.<br />
<br />
Defaults to TB_MTYPE_BUTTON<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBMEMBER_ImageID (uint32)<br />
The identifier of the image to be used for the button or toggle member<br />
(see TOOLBAR_AddImage above). This tag is not relevant to spacers and<br />
separators; TBM_GETMEMBER will always return TB_NO_ID should you inquire<br />
about the TBMEMBER_ImageID value of such a member.<br />
<br />
Defaults to TB_NO_ID (no image associated with this member)<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Text (CONST_STRPTR)<br />
The label to associate with a button or a toggle member. This tag is not<br />
relevant to spacers and separators; TBM_GETMEMBER will always return<br />
NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
<br />
The text label will be used as fallback in case no image is found or<br />
provided.<br />
<br />
The text string can contain an underscore character (_), indicating the<br />
keyboard shortcut for this member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Disabled (BOOL)<br />
The current state (disabled or not disabled) of a member. This tag is<br />
not relevant to spacers and separators; TBM_GETMEMBER will always return<br />
FALSE should you inquire about the TBMEMBER_Disabled value of such<br />
a member.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Hidden (BOOL)<br />
Specifies whether the particular member is displayed in the toolbar or<br />
hidden. You can use this tag to create "dynamic" toolbar layouts that<br />
adapt the actual member set to various application settings.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Selected (BOOL)<br />
The current selection state of a toggle member. This tag is not relevant<br />
to normal buttons (TB_MTYPE_BUTTON), spacers and separators;<br />
TBM_GETMEMBER will always return FALSE should you inquire about the<br />
TBMEMBER_Selected value of such a member.<br />
<br />
You can set a target BOOPSI object for any toggle member, using the<br />
standard icclass ICA_TARGET tag. The target will receive an automatic<br />
notification of the toggle selection. This way toolbar toggles can<br />
easily communicate with other boolean gadgets such as checkboxes.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_NOTIFY, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Group (uint32)<br />
Member group ID. Several members can be manipulated at once if they are<br />
assigned to the same group. Use TOOLBAR_SetGroup with the respective<br />
group ID to identify the group to be manipulated.<br />
<br />
Defaults to TB_NO_ID (not assigned to any group)<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_MXGroup (uint32)<br />
MX group ID. Toggle members can be put in groups of mutually-exclusive<br />
buttons. When such a toggle is selected, all other toggles in the same<br />
MX group will become deselected.<br />
<br />
This tag is not relevant to normal buttons, spacers and separators;<br />
TBM_GETMEMBER will always return TB_NO_ID should you inquire about the<br />
TBMEMBER_MXGroup value of such a member.<br />
<br />
Defaults to TB_NO_ID (not assigned to any MX group)<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_HintInfo (CONST_STRPTR)<br />
The help text to be displayed when the user hovers the mouse pointer<br />
over the respective member. This tag is not relevant to spacers and<br />
separators; TBM_GETMEMBER will always return NULL should you inquire<br />
about the TBMEMBER_HintInfo value of such a member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_UserData (APTR)<br />
Arbitrary user data associated with this member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
=== Image attributes ===<br />
<br />
TBIMAGE_Image (struct Image *)<br />
Custom image to be used for a button or a toggle member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_ImageFile (CONST_STRPTR)<br />
The full path to the source file to create the image from. The image<br />
will be loaded and built using the Shared Image class.<br />
<br />
All images created this way will also be disposed of automatically.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_SelImage (struct Image *)<br />
Custom image to display when the member becomes selected.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_SelImageFile (CONST_STRPTR)<br />
The full path to the source file to create the select image from.<br />
The image will be loaded and built using the Shared Image class.<br />
<br />
All images created this way will also be disposed of automatically.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_Width (uint32)<br />
TBIMAGE_Height (uint32)<br />
Image dimensions, in pixels. These tags can only be used in connection<br />
with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the<br />
respective source file will be scaled to the specified width and height.<br />
Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot<br />
be resized using these tags.<br />
<br />
Defaults to 0<br />
<br />
Applicability is (OM_NEW)<br />
<br />
NOTES<br />
Some of the attributes described above change the sizing requirements of<br />
the gadget. If set on the fly (i.e. when the toolbar is already displayed<br />
in the window), the gadget domain will need recalculating and a re-layout<br />
must take place. Refer to the OM_SET method documentation below to see<br />
how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image.<br />
Image attributes cannot be changed later.<br />
<br />
BUGS<br />
<br />
<br />
SEE ALSO<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
NAME<br />
OM_SET -- set toolbar attributes<br />
<br />
SYNOPSIS<br />
uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
<br />
uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win,<br />
struct Requester *req, Tag tag1, ...);<br />
<br />
FUNCTION<br />
This method sets the attributes of the toolbar and/or of its members.<br />
SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions<br />
to invoke this method.<br />
<br />
To change a member attribute you first need to pass TOOLBAR_SetMember<br />
to identify the respective member, and then the member attribute tag(s).<br />
See the EXAMPLE section below.<br />
<br />
To change an attribute collectively for a group of members you first need<br />
to pass TOOLBAR_SetGroup to identify the respective group, and then the<br />
member attribute tag(s). See the EXAMPLE section below.<br />
<br />
INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
RESULT<br />
This method will return TB_NEED_RETHINK if one or more of the attributes<br />
change the sizing requirements of the gadget. In such a case, the<br />
appropriate reaction is to call WM_RETHINK on the gadget's window object<br />
to recalculate the domain and re-layout the contents.<br />
<br />
If you know you will be changing an attribute that requires a WM_RETHINK,<br />
prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an<br />
unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
<br />
The method returns 0 if no rethink is needed.<br />
<br />
EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, GROUP_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
NOTES<br />
<br />
BUGS<br />
<br />
SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
NAME<br />
TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
SYNOPSIS<br />
uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
<br />
uint32 result = IDoMethod(Object *toolbar, uint32 methodID,<br />
uint32 attrID, uint32 *storage);<br />
<br />
FUNCTION<br />
Use this method to obtain the value of a given member attribute.<br />
<br />
Because of the way OM_GET is implemented in Intuition, getting member<br />
attributes is done differently compared to setting them. The difference<br />
boils down to the following:<br />
<br />
- We cannot use a convenience function such as GetAttr() or GetAttrs(),<br />
so a dedicated method is provided. Refer to the EXAMPLE section below<br />
to see how to invoke the method.<br />
<br />
- Only one attribute can be queried at a time. (As multiple attributes<br />
will rarely be requested in real use, this limitation should not pose<br />
a significant problem.)<br />
<br />
INPUTS<br />
For IDoMethodA():<br />
toolbar-- the toolbar gadget object<br />
msg-- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
toolbar-- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
attrID -- the attribute tag identifier<br />
storage-- a pointer to the variable for storing the attribute value<br />
<br />
RESULT<br />
The "result" value will be 1L if the requested attribute value has been<br />
obtained successfully. The attribute value itself is returned in the<br />
provided storage variable.<br />
<br />
EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID,<br />
TBMEMBER_Selected, &storage);<br />
<br />
NOTES<br />
<br />
BUGS<br />
<br />
SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=1000ToolBar Gadget Class2020-10-30T22:49:51Z<p>Trixie: </p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Methods ==<br />
<br />
OM_NEW -- creates the toolbar object, sets attributes and defaults<br />
<br />
OM_DISPOSE -- disposes of the toolbar object<br />
<br />
OM_REMMEMBER -- used by the class internally; consider this method private<br />
<br />
OM_SET -- sets toolbar, member and image attributes (see the OM_SET section below for more information)<br />
<br />
OM_GET -- retrieves toolbar attributes<br />
<br />
TBM_GETMEMBER -- retrieves a given member attribute (see the TBM_GETMEMBER section below for more information)<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
GA_ID (uint16)<br />
Unique ID number for the gadget.<br />
<br />
Defaults to 0<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
GA_ReadOnly (BOOL)<br />
If set to TRUE, none of the toolbar buttons will be selectable.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
GA_BackFill (struct Hook *)<br />
A backfill hook to provide a background filled with a specific colour<br />
or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
<br />
Defaults to NULL (the default backfill hook).<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
GA_TextAttr (struct TextAttr *)<br />
Pointer to a TextAttr structure describing the font to be used for<br />
the gadget's button text labels (if they are used).<br />
<br />
Defaults to the system's default public screen font.<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
TOOLBAR_Orientation (uint32)<br />
The toolbar orientation: horizontal or vertical.<br />
<br />
Defaults to TB_ORIENT_HORIZ<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_Spacing (uint32)<br />
The spacing between the individual toolbar members, in pixels.<br />
<br />
Defaults to 2<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_HorizPadding<br />
TOOLBAR_VertPadding (uint32)<br />
The horizontal/vertical distance, in pixels, between the toolbar<br />
members and the gadget border (or outer bevel, if displayed - see<br />
TOOLBAR_BevelStyle below).<br />
<br />
Defaults to 0<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_InnerPadding (uint32)<br />
The distance, in pixels, between the member contents (image and/or text)<br />
and the button frame. Changing this setting will affect the size of the<br />
toolbar members.<br />
<br />
Defaults to 4<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_HandleOverflow (BOOL)<br />
Overflow is a situation when there is not enough space to fit all<br />
toolbar members within the current window. If this tag is set to TRUE,<br />
all members that don't fit will be moved into a pop-up menu whenever<br />
overflow takes place. A selector to invoke the menu will be displayed<br />
on the right.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_MinVisible (uint32)<br />
If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the<br />
specified number of members (including spacers and separators) will<br />
always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
<br />
Defaults to 1<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_SpacerSize (uint32)<br />
The size of the spacer member, in pixels. This value will affect the<br />
width (in a horizontal toolbar) or the height (in a vertical toolbar)<br />
of the spacer.<br />
<br />
Defaults to 5<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_ButtonStyle (uint32)<br />
The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce<br />
a traditional-looking toolbar with framed buttons, whereas<br />
TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
<br />
Defaults to TB_BUTSTYLE_CLASSIC<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_BevelStyle (uint32)<br />
The style of the gadget's outer bevel (frame). The Bevel Image class<br />
is used, so the style values from <images/bevel.h> are applicable to<br />
this tag (although not all of them make good sense to use with the<br />
toolbar). The recommended values are:<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar<br />
buttons), make sure that you also adjust TOOLBAR_HorizPadding and<br />
TOOLBAR_VertPadding, otherwise the outer bevel will interfere with<br />
the button frames.<br />
<br />
Defaults to BVS_NONE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_SeparatorStyle (uint32)<br />
Determines the look of the separator member. If you want to change it<br />
on the fly while the window is open, call SetGadgetAttrs() rather than<br />
SetAttrs() to trigger an immediate redraw.<br />
<br />
Defaults to TB_SEPSTYLE_NORMAL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_SelectionStyle (uint32)<br />
Determines how member selection is indicated in the borderless mode.<br />
If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the<br />
selection: the programmer must provide a select image for each button<br />
or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below),<br />
otherwise there will be no visual response. If the tag is set to<br />
TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around<br />
the member to indicate the selection.<br />
<br />
This tag is ignored in the classic mode with framed buttons.<br />
<br />
Defaults to TB_SELSTYLE_NONE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_BackFill (struct Hook *)<br />
A custom backfill hook to provide a background filled with a specific<br />
colour or pattern.<br />
<br />
This tag is meant to replace GA_BackFill because if the toolbar gadget<br />
is placed in a layout, the value of GA_BackFill can only be set after<br />
the window opens (this is because the Layout Gadget propagates its own<br />
backfill to all of its children). TOOLBAR_BackFill is provided as<br />
a convenience tag that overrides GA_BackFill, and allows setting your<br />
backfill hook even before the window opens.<br />
<br />
Defaults to NULL (the default layers backfill hook).<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
TOOLBAR_Display (uint32)<br />
Specifies what you want to display inside the toolbar button or toggle<br />
members. The possible values are:<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
Defaults to TB_DISPLAY_IMAGES<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_TextPlace (uint32)<br />
Specifies the placement of the text labels with regard to the toolbar<br />
images. This tag is only meaningful when actual text labels are<br />
provided via TBMEMBER_Text, and TOOLBAR_Display is set to<br />
TB_DISPLAY_BOTH.<br />
<br />
Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_LabelArray (STRPTR *)<br />
Use this tag to create a minimum-configuration, text-only toolbar.<br />
You simply pass a NULL-terminated array of strings representing<br />
the toolbar button labels. Each label can contain an underscore<br />
character to indicate the keyboard shortcut for the respective button.<br />
<br />
TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
<br />
Using this tag, the limitation is that you cannot create toggle members<br />
(only buttons, separators and spacers).<br />
<br />
A special string, " ", will create a spacer.<br />
A special string, "_", will create a separator.<br />
<br />
Spacers and separators cannot appear as the very first member in the<br />
toolbar. Therefore, the label array may not begin with a spacer or<br />
a separator string. Also, the array must contain at least one valid<br />
string to create a button, otherwise the toolbar creation will fail.<br />
<br />
The button strings are copied to an internal buffer, so the label array<br />
need not remain valid throughout the lifetime of the gadget.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TOOLBAR_EvenSize (BOOL)<br />
If set to TRUE, this attribute will size all button and toggle members<br />
evenly according to the largest member. The attribute has no effect<br />
on spacers and separators.<br />
<br />
If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above)<br />
and your toolbar images are all of the same size, keep this attribute<br />
at its default FALSE value: the button dimensions will be equal anyway,<br />
and you'll spare the gadget some unnecessary calculations. On the other <br />
hand, setting this tag to TRUE may produce a visually more plausible<br />
result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_ImageSet (uint32)<br />
If more than one image set have been configured via TOOLBAR_AddImageSet<br />
(see below), use this tag to determine which set is to be displayed in<br />
the toolbar. The value passed to this tag is the image set ID.<br />
<br />
Defaults to 0<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform<br />
various functions associated with toolbar configuration:<br />
<br />
TOOLBAR_AddImageSet (uint32)<br />
Creates a new image set. The value passed to this tag is a numeric ID<br />
identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to<br />
display the particular image set in the toolbar.<br />
<br />
This tag should be followed by a sequence of TOOLBAR_AddImage tags (see<br />
below), each creating one image in the given set.<br />
<br />
If the gadget only uses one set of images, passing TOOLBAR_AddImageSet<br />
is not necessary. Each TOOLBAR_AddImage will add the respective image<br />
to the default image set identified by an ID of 0.<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
TOOLBAR_AddImage (uint32)<br />
Creates a new image in a given image set. The value passed to this tag<br />
is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID<br />
(see below) to associate the image with a particular toolbar member.<br />
<br />
This tag should be followed by a sequence of TBIMAGE_ tags (see the<br />
"Image attributes" section below), each configuring one aspect of the<br />
image, including its optional selected variant (referred to as the<br />
"select image").<br />
<br />
Images are added to the default image set unless a preceding<br />
TOOLBAR_AddImageSet specifies a different set.<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
TOOLBAR_AddMember (uint32)<br />
Creates a new toolbar member. The value passed to this tag is a numeric<br />
ID identifying the member.<br />
<br />
Spacers and separators normally don't need an ID, so you can use<br />
TB_NO_ID as a value for TOOLBAR_AddMember when creating these members.<br />
However, if you want to manipulate spacers/separators in your GUI,<br />
an ID will be necessary so that you can pass it to TOOLBAR_SetMember<br />
to identify the respective spacer or separator member.<br />
<br />
You can add members when the toolbar object is being created, i.e.<br />
as part of the NewObject() call, or at any time later via SetAttrs().<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
TOOLBAR_SetMember<br />
Use this tag in a SetAttrs() call to identify the member you want to<br />
modify.<br />
<br />
Applicability is (OM_SET)<br />
<br />
TOOLBAR_SetGroup<br />
Use this tag in a SetAttrs() call to identify the group of members you<br />
want to modify collectively.<br />
<br />
Applicability is (OM_SET)<br />
<br />
=== Member attributes ===<br />
<br />
TBMEMBER_Type (uint32)<br />
The type of the toolbar member. The possible values are the following:<br />
TB_MTYPE_BUTTON-- a normal toolbar button<br />
TB_MTYPE_TOGGLE-- a toggle (on/off) button<br />
TB_MTYPE_SPACER-- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
<br />
The type is set upon member creation, and cannot be changed.<br />
<br />
Defaults to TB_MTYPE_BUTTON<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBMEMBER_ImageID (uint32)<br />
The identifier of the image to be used for the button or toggle member<br />
(see TOOLBAR_AddImage above). This tag is not relevant to spacers and<br />
separators; TBM_GETMEMBER will always return TB_NO_ID should you inquire<br />
about the TBMEMBER_ImageID value of such a member.<br />
<br />
Defaults to TB_NO_ID (no image associated with this member)<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Text (CONST_STRPTR)<br />
The label to associate with a button or a toggle member. This tag is not<br />
relevant to spacers and separators; TBM_GETMEMBER will always return<br />
NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
<br />
The text label will be used as fallback in case no image is found or<br />
provided.<br />
<br />
The text string can contain an underscore character (_), indicating the<br />
keyboard shortcut for this member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Disabled (BOOL)<br />
The current state (disabled or not disabled) of a member. This tag is<br />
not relevant to spacers and separators; TBM_GETMEMBER will always return<br />
FALSE should you inquire about the TBMEMBER_Disabled value of such<br />
a member.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Hidden (BOOL)<br />
Specifies whether the particular member is displayed in the toolbar or<br />
hidden. You can use this tag to create "dynamic" toolbar layouts that<br />
adapt the actual member set to various application settings.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Selected (BOOL)<br />
The current selection state of a toggle member. This tag is not relevant<br />
to normal buttons (TB_MTYPE_BUTTON), spacers and separators;<br />
TBM_GETMEMBER will always return FALSE should you inquire about the<br />
TBMEMBER_Selected value of such a member.<br />
<br />
You can set a target BOOPSI object for any toggle member, using the<br />
standard icclass ICA_TARGET tag. The target will receive an automatic<br />
notification of the toggle selection. This way toolbar toggles can<br />
easily communicate with other boolean gadgets such as checkboxes.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_NOTIFY, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Group (uint32)<br />
Member group ID. Several members can be manipulated at once if they are<br />
assigned to the same group. Use TOOLBAR_SetGroup with the respective<br />
group ID to identify the group to be manipulated.<br />
<br />
Defaults to TB_NO_ID (not assigned to any group)<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_MXGroup (uint32)<br />
MX group ID. Toggle members can be put in groups of mutually-exclusive<br />
buttons. When such a toggle is selected, all other toggles in the same<br />
MX group will become deselected.<br />
<br />
This tag is not relevant to normal buttons, spacers and separators;<br />
TBM_GETMEMBER will always return TB_NO_ID should you inquire about the<br />
TBMEMBER_MXGroup value of such a member.<br />
<br />
Defaults to TB_NO_ID (not assigned to any MX group)<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_HintInfo (CONST_STRPTR)<br />
The help text to be displayed when the user hovers the mouse pointer<br />
over the respective member. This tag is not relevant to spacers and<br />
separators; TBM_GETMEMBER will always return NULL should you inquire<br />
about the TBMEMBER_HintInfo value of such a member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_UserData (APTR)<br />
Arbitrary user data associated with this member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
=== Image attributes ===<br />
<br />
TBIMAGE_Image (struct Image *)<br />
Custom image to be used for a button or a toggle member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_ImageFile (CONST_STRPTR)<br />
The full path to the source file to create the image from. The image<br />
will be loaded and built using the Shared Image class.<br />
<br />
All images created this way will also be disposed of automatically.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_SelImage (struct Image *)<br />
Custom image to display when the member becomes selected.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_SelImageFile (CONST_STRPTR)<br />
The full path to the source file to create the select image from.<br />
The image will be loaded and built using the Shared Image class.<br />
<br />
All images created this way will also be disposed of automatically.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_Width (uint32)<br />
TBIMAGE_Height (uint32)<br />
Image dimensions, in pixels. These tags can only be used in connection<br />
with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the<br />
respective source file will be scaled to the specified width and height.<br />
Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot<br />
be resized using these tags.<br />
<br />
Defaults to 0<br />
<br />
Applicability is (OM_NEW)<br />
<br />
NOTES<br />
Some of the attributes described above change the sizing requirements of<br />
the gadget. If set on the fly (i.e. when the toolbar is already displayed<br />
in the window), the gadget domain will need recalculating and a re-layout<br />
must take place. Refer to the OM_SET method documentation below to see<br />
how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image.<br />
Image attributes cannot be changed later.<br />
<br />
BUGS<br />
<br />
<br />
SEE ALSO<br />
<br />
== Methods ==<br />
<br />
=== OM_SET ===<br />
<br />
NAME<br />
OM_SET -- set toolbar attributes<br />
<br />
SYNOPSIS<br />
uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
<br />
uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win,<br />
struct Requester *req, Tag tag1, ...);<br />
<br />
FUNCTION<br />
This method sets the attributes of the toolbar and/or of its members.<br />
SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions<br />
to invoke this method.<br />
<br />
To change a member attribute you first need to pass TOOLBAR_SetMember<br />
to identify the respective member, and then the member attribute tag(s).<br />
See the EXAMPLE section below.<br />
<br />
To change an attribute collectively for a group of members you first need<br />
to pass TOOLBAR_SetGroup to identify the respective group, and then the<br />
member attribute tag(s). See the EXAMPLE section below.<br />
<br />
INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
RESULT<br />
This method will return TB_NEED_RETHINK if one or more of the attributes<br />
change the sizing requirements of the gadget. In such a case, the<br />
appropriate reaction is to call WM_RETHINK on the gadget's window object<br />
to recalculate the domain and re-layout the contents.<br />
<br />
If you know you will be changing an attribute that requires a WM_RETHINK,<br />
prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an<br />
unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
<br />
The method returns 0 if no rethink is needed.<br />
<br />
EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, GROUP_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
NOTES<br />
<br />
BUGS<br />
<br />
SEE ALSO<br />
<br />
=== TBM_GETMEMBER ===<br />
<br />
NAME<br />
TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
SYNOPSIS<br />
uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
<br />
uint32 result = IDoMethod(Object *toolbar, uint32 methodID,<br />
uint32 attrID, uint32 *storage);<br />
<br />
FUNCTION<br />
Use this method to obtain the value of a given member attribute.<br />
<br />
Because of the way OM_GET is implemented in Intuition, getting member<br />
attributes is done differently compared to setting them. The difference<br />
boils down to the following:<br />
<br />
- We cannot use a convenience function such as GetAttr() or GetAttrs(),<br />
so a dedicated method is provided. Refer to the EXAMPLE section below<br />
to see how to invoke the method.<br />
<br />
- Only one attribute can be queried at a time. (As multiple attributes<br />
will rarely be requested in real use, this limitation should not pose<br />
a significant problem.)<br />
<br />
INPUTS<br />
For IDoMethodA():<br />
toolbar-- the toolbar gadget object<br />
msg-- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
toolbar-- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
attrID -- the attribute tag identifier<br />
storage-- a pointer to the variable for storing the attribute value<br />
<br />
RESULT<br />
The "result" value will be 1L if the requested attribute value has been<br />
obtained successfully. The attribute value itself is returned in the<br />
provided storage variable.<br />
<br />
EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID,<br />
TBMEMBER_Selected, &storage);<br />
<br />
NOTES<br />
<br />
BUGS<br />
<br />
SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=999ToolBar Gadget Class2020-10-30T22:46:26Z<p>Trixie: </p>
<hr />
<div>== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
== Methods ==<br />
<br />
OM_NEW -- creates the toolbar object, sets attributes and defaults<br />
<br />
OM_DISPOSE -- disposes of the toolbar object<br />
<br />
OM_REMMEMBER -- used by the class internally; consider this method private<br />
<br />
OM_SET -- sets toolbar, member and image attributes (see the OM_SET section below for more information)<br />
<br />
OM_GET -- retrieves toolbar attributes<br />
<br />
TBM_GETMEMBER -- retrieves a given member attribute (see the TBM_GETMEMBER section below for more information)<br />
<br />
== Attributes ==<br />
<br />
=== Toolbar attributes ===<br />
<br />
GA_ID (uint16)<br />
Unique ID number for the gadget.<br />
<br />
Defaults to 0<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
GA_ReadOnly (BOOL)<br />
If set to TRUE, none of the toolbar buttons will be selectable.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
GA_BackFill (struct Hook *)<br />
A backfill hook to provide a background filled with a specific colour<br />
or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
<br />
Defaults to NULL (the default backfill hook).<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
GA_TextAttr (struct TextAttr *)<br />
Pointer to a TextAttr structure describing the font to be used for<br />
the gadget's button text labels (if they are used).<br />
<br />
Defaults to the system's default public screen font.<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
TOOLBAR_Orientation (uint32)<br />
The toolbar orientation: horizontal or vertical.<br />
<br />
Defaults to TB_ORIENT_HORIZ<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_Spacing (uint32)<br />
The spacing between the individual toolbar members, in pixels.<br />
<br />
Defaults to 2<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_HorizPadding<br />
TOOLBAR_VertPadding (uint32)<br />
The horizontal/vertical distance, in pixels, between the toolbar<br />
members and the gadget border (or outer bevel, if displayed - see<br />
TOOLBAR_BevelStyle below).<br />
<br />
Defaults to 0<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_InnerPadding (uint32)<br />
The distance, in pixels, between the member contents (image and/or text)<br />
and the button frame. Changing this setting will affect the size of the<br />
toolbar members.<br />
<br />
Defaults to 4<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_HandleOverflow (BOOL)<br />
Overflow is a situation when there is not enough space to fit all<br />
toolbar members within the current window. If this tag is set to TRUE,<br />
all members that don't fit will be moved into a pop-up menu whenever<br />
overflow takes place. A selector to invoke the menu will be displayed<br />
on the right.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_MinVisible (uint32)<br />
If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the<br />
specified number of members (including spacers and separators) will<br />
always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
<br />
Defaults to 1<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_SpacerSize (uint32)<br />
The size of the spacer member, in pixels. This value will affect the<br />
width (in a horizontal toolbar) or the height (in a vertical toolbar)<br />
of the spacer.<br />
<br />
Defaults to 5<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_ButtonStyle (uint32)<br />
The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce<br />
a traditional-looking toolbar with framed buttons, whereas<br />
TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
<br />
Defaults to TB_BUTSTYLE_CLASSIC<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_BevelStyle (uint32)<br />
The style of the gadget's outer bevel (frame). The Bevel Image class<br />
is used, so the style values from <images/bevel.h> are applicable to<br />
this tag (although not all of them make good sense to use with the<br />
toolbar). The recommended values are:<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar<br />
buttons), make sure that you also adjust TOOLBAR_HorizPadding and<br />
TOOLBAR_VertPadding, otherwise the outer bevel will interfere with<br />
the button frames.<br />
<br />
Defaults to BVS_NONE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_SeparatorStyle (uint32)<br />
Determines the look of the separator member. If you want to change it<br />
on the fly while the window is open, call SetGadgetAttrs() rather than<br />
SetAttrs() to trigger an immediate redraw.<br />
<br />
Defaults to TB_SEPSTYLE_NORMAL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_SelectionStyle (uint32)<br />
Determines how member selection is indicated in the borderless mode.<br />
If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the<br />
selection: the programmer must provide a select image for each button<br />
or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below),<br />
otherwise there will be no visual response. If the tag is set to<br />
TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around<br />
the member to indicate the selection.<br />
<br />
This tag is ignored in the classic mode with framed buttons.<br />
<br />
Defaults to TB_SELSTYLE_NONE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_BackFill (struct Hook *)<br />
A custom backfill hook to provide a background filled with a specific<br />
colour or pattern.<br />
<br />
This tag is meant to replace GA_BackFill because if the toolbar gadget<br />
is placed in a layout, the value of GA_BackFill can only be set after<br />
the window opens (this is because the Layout Gadget propagates its own<br />
backfill to all of its children). TOOLBAR_BackFill is provided as<br />
a convenience tag that overrides GA_BackFill, and allows setting your<br />
backfill hook even before the window opens.<br />
<br />
Defaults to NULL (the default layers backfill hook).<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
TOOLBAR_Display (uint32)<br />
Specifies what you want to display inside the toolbar button or toggle<br />
members. The possible values are:<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
Defaults to TB_DISPLAY_IMAGES<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_TextPlace (uint32)<br />
Specifies the placement of the text labels with regard to the toolbar<br />
images. This tag is only meaningful when actual text labels are<br />
provided via TBMEMBER_Text, and TOOLBAR_Display is set to<br />
TB_DISPLAY_BOTH.<br />
<br />
Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_LabelArray (STRPTR *)<br />
Use this tag to create a minimum-configuration, text-only toolbar.<br />
You simply pass a NULL-terminated array of strings representing<br />
the toolbar button labels. Each label can contain an underscore<br />
character to indicate the keyboard shortcut for the respective button.<br />
<br />
TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
<br />
Using this tag, the limitation is that you cannot create toggle members<br />
(only buttons, separators and spacers).<br />
<br />
A special string, " ", will create a spacer.<br />
A special string, "_", will create a separator.<br />
<br />
Spacers and separators cannot appear as the very first member in the<br />
toolbar. Therefore, the label array may not begin with a spacer or<br />
a separator string. Also, the array must contain at least one valid<br />
string to create a button, otherwise the toolbar creation will fail.<br />
<br />
The button strings are copied to an internal buffer, so the label array<br />
need not remain valid throughout the lifetime of the gadget.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TOOLBAR_EvenSize (BOOL)<br />
If set to TRUE, this attribute will size all button and toggle members<br />
evenly according to the largest member. The attribute has no effect<br />
on spacers and separators.<br />
<br />
If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above)<br />
and your toolbar images are all of the same size, keep this attribute<br />
at its default FALSE value: the button dimensions will be equal anyway,<br />
and you'll spare the gadget some unnecessary calculations. On the other <br />
hand, setting this tag to TRUE may produce a visually more plausible<br />
result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_ImageSet (uint32)<br />
If more than one image set have been configured via TOOLBAR_AddImageSet<br />
(see below), use this tag to determine which set is to be displayed in<br />
the toolbar. The value passed to this tag is the image set ID.<br />
<br />
Defaults to 0<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
=== Method attributes ===<br />
<br />
The following tags are not attributes but, rather, methods that perform<br />
various functions associated with toolbar configuration:<br />
<br />
TOOLBAR_AddImageSet (uint32)<br />
Creates a new image set. The value passed to this tag is a numeric ID<br />
identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to<br />
display the particular image set in the toolbar.<br />
<br />
This tag should be followed by a sequence of TOOLBAR_AddImage tags (see<br />
below), each creating one image in the given set.<br />
<br />
If the gadget only uses one set of images, passing TOOLBAR_AddImageSet<br />
is not necessary. Each TOOLBAR_AddImage will add the respective image<br />
to the default image set identified by an ID of 0.<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
TOOLBAR_AddImage (uint32)<br />
Creates a new image in a given image set. The value passed to this tag<br />
is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID<br />
(see below) to associate the image with a particular toolbar member.<br />
<br />
This tag should be followed by a sequence of TBIMAGE_ tags (see the<br />
"Image attributes" section below), each configuring one aspect of the<br />
image, including its optional selected variant (referred to as the<br />
"select image").<br />
<br />
Images are added to the default image set unless a preceding<br />
TOOLBAR_AddImageSet specifies a different set.<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
TOOLBAR_AddMember (uint32)<br />
Creates a new toolbar member. The value passed to this tag is a numeric<br />
ID identifying the member.<br />
<br />
Spacers and separators normally don't need an ID, so you can use<br />
TB_NO_ID as a value for TOOLBAR_AddMember when creating these members.<br />
However, if you want to manipulate spacers/separators in your GUI,<br />
an ID will be necessary so that you can pass it to TOOLBAR_SetMember<br />
to identify the respective spacer or separator member.<br />
<br />
You can add members when the toolbar object is being created, i.e.<br />
as part of the NewObject() call, or at any time later via SetAttrs().<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
TOOLBAR_SetMember<br />
Use this tag in a SetAttrs() call to identify the member you want to<br />
modify.<br />
<br />
Applicability is (OM_SET)<br />
<br />
TOOLBAR_SetGroup<br />
Use this tag in a SetAttrs() call to identify the group of members you<br />
want to modify collectively.<br />
<br />
Applicability is (OM_SET)<br />
<br />
=== Member attributes ===<br />
<br />
TBMEMBER_Type (uint32)<br />
The type of the toolbar member. The possible values are the following:<br />
TB_MTYPE_BUTTON-- a normal toolbar button<br />
TB_MTYPE_TOGGLE-- a toggle (on/off) button<br />
TB_MTYPE_SPACER-- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
<br />
The type is set upon member creation, and cannot be changed.<br />
<br />
Defaults to TB_MTYPE_BUTTON<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBMEMBER_ImageID (uint32)<br />
The identifier of the image to be used for the button or toggle member<br />
(see TOOLBAR_AddImage above). This tag is not relevant to spacers and<br />
separators; TBM_GETMEMBER will always return TB_NO_ID should you inquire<br />
about the TBMEMBER_ImageID value of such a member.<br />
<br />
Defaults to TB_NO_ID (no image associated with this member)<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Text (CONST_STRPTR)<br />
The label to associate with a button or a toggle member. This tag is not<br />
relevant to spacers and separators; TBM_GETMEMBER will always return<br />
NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
<br />
The text label will be used as fallback in case no image is found or<br />
provided.<br />
<br />
The text string can contain an underscore character (_), indicating the<br />
keyboard shortcut for this member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Disabled (BOOL)<br />
The current state (disabled or not disabled) of a member. This tag is<br />
not relevant to spacers and separators; TBM_GETMEMBER will always return<br />
FALSE should you inquire about the TBMEMBER_Disabled value of such<br />
a member.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Hidden (BOOL)<br />
Specifies whether the particular member is displayed in the toolbar or<br />
hidden. You can use this tag to create "dynamic" toolbar layouts that<br />
adapt the actual member set to various application settings.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Selected (BOOL)<br />
The current selection state of a toggle member. This tag is not relevant<br />
to normal buttons (TB_MTYPE_BUTTON), spacers and separators;<br />
TBM_GETMEMBER will always return FALSE should you inquire about the<br />
TBMEMBER_Selected value of such a member.<br />
<br />
You can set a target BOOPSI object for any toggle member, using the<br />
standard icclass ICA_TARGET tag. The target will receive an automatic<br />
notification of the toggle selection. This way toolbar toggles can<br />
easily communicate with other boolean gadgets such as checkboxes.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_NOTIFY, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Group (uint32)<br />
Member group ID. Several members can be manipulated at once if they are<br />
assigned to the same group. Use TOOLBAR_SetGroup with the respective<br />
group ID to identify the group to be manipulated.<br />
<br />
Defaults to TB_NO_ID (not assigned to any group)<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_MXGroup (uint32)<br />
MX group ID. Toggle members can be put in groups of mutually-exclusive<br />
buttons. When such a toggle is selected, all other toggles in the same<br />
MX group will become deselected.<br />
<br />
This tag is not relevant to normal buttons, spacers and separators;<br />
TBM_GETMEMBER will always return TB_NO_ID should you inquire about the<br />
TBMEMBER_MXGroup value of such a member.<br />
<br />
Defaults to TB_NO_ID (not assigned to any MX group)<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_HintInfo (CONST_STRPTR)<br />
The help text to be displayed when the user hovers the mouse pointer<br />
over the respective member. This tag is not relevant to spacers and<br />
separators; TBM_GETMEMBER will always return NULL should you inquire<br />
about the TBMEMBER_HintInfo value of such a member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_UserData (APTR)<br />
Arbitrary user data associated with this member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
=== Image attributes ===<br />
<br />
TBIMAGE_Image (struct Image *)<br />
Custom image to be used for a button or a toggle member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_ImageFile (CONST_STRPTR)<br />
The full path to the source file to create the image from. The image<br />
will be loaded and built using the Shared Image class.<br />
<br />
All images created this way will also be disposed of automatically.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_SelImage (struct Image *)<br />
Custom image to display when the member becomes selected.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_SelImageFile (CONST_STRPTR)<br />
The full path to the source file to create the select image from.<br />
The image will be loaded and built using the Shared Image class.<br />
<br />
All images created this way will also be disposed of automatically.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_Width (uint32)<br />
TBIMAGE_Height (uint32)<br />
Image dimensions, in pixels. These tags can only be used in connection<br />
with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the<br />
respective source file will be scaled to the specified width and height.<br />
Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot<br />
be resized using these tags.<br />
<br />
Defaults to 0<br />
<br />
Applicability is (OM_NEW)<br />
<br />
NOTES<br />
Some of the attributes described above change the sizing requirements of<br />
the gadget. If set on the fly (i.e. when the toolbar is already displayed<br />
in the window), the gadget domain will need recalculating and a re-layout<br />
must take place. Refer to the OM_SET method documentation below to see<br />
how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image.<br />
Image attributes cannot be changed later.<br />
<br />
BUGS<br />
<br />
<br />
SEE ALSO<br />
<br />
toolbar.gadget/OM_SET toolbar.gadget/OM_SET<br />
<br />
NAME<br />
OM_SET -- set toolbar attributes<br />
<br />
SYNOPSIS<br />
uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
<br />
uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win,<br />
struct Requester *req, Tag tag1, ...);<br />
<br />
FUNCTION<br />
This method sets the attributes of the toolbar and/or of its members.<br />
SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions<br />
to invoke this method.<br />
<br />
To change a member attribute you first need to pass TOOLBAR_SetMember<br />
to identify the respective member, and then the member attribute tag(s).<br />
See the EXAMPLE section below.<br />
<br />
To change an attribute collectively for a group of members you first need<br />
to pass TOOLBAR_SetGroup to identify the respective group, and then the<br />
member attribute tag(s). See the EXAMPLE section below.<br />
<br />
INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
RESULT<br />
This method will return TB_NEED_RETHINK if one or more of the attributes<br />
change the sizing requirements of the gadget. In such a case, the<br />
appropriate reaction is to call WM_RETHINK on the gadget's window object<br />
to recalculate the domain and re-layout the contents.<br />
<br />
If you know you will be changing an attribute that requires a WM_RETHINK,<br />
prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an<br />
unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
<br />
The method returns 0 if no rethink is needed.<br />
<br />
EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, GROUP_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
NOTES<br />
<br />
BUGS<br />
<br />
SEE ALSO<br />
<br />
toolbar.gadget/TBM_GETMEMBER toolbar.gadget/TBM_GETMEMBER<br />
<br />
NAME<br />
TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
SYNOPSIS<br />
uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
<br />
uint32 result = IDoMethod(Object *toolbar, uint32 methodID,<br />
uint32 attrID, uint32 *storage);<br />
<br />
FUNCTION<br />
Use this method to obtain the value of a given member attribute.<br />
<br />
Because of the way OM_GET is implemented in Intuition, getting member<br />
attributes is done differently compared to setting them. The difference<br />
boils down to the following:<br />
<br />
- We cannot use a convenience function such as GetAttr() or GetAttrs(),<br />
so a dedicated method is provided. Refer to the EXAMPLE section below<br />
to see how to invoke the method.<br />
<br />
- Only one attribute can be queried at a time. (As multiple attributes<br />
will rarely be requested in real use, this limitation should not pose<br />
a significant problem.)<br />
<br />
INPUTS<br />
For IDoMethodA():<br />
toolbar-- the toolbar gadget object<br />
msg-- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
toolbar-- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
attrID -- the attribute tag identifier<br />
storage-- a pointer to the variable for storing the attribute value<br />
<br />
RESULT<br />
The "result" value will be 1L if the requested attribute value has been<br />
obtained successfully. The attribute value itself is returned in the<br />
provided storage variable.<br />
<br />
EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID,<br />
TBMEMBER_Selected, &storage);<br />
<br />
NOTES<br />
<br />
BUGS<br />
<br />
SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=998ToolBar Gadget Class2020-10-30T22:43:08Z<p>Trixie: </p>
<hr />
<div>TABLE OF CONTENTS<br />
<br />
toolbar.gadget/--datasheet--<br />
toolbar.gadget/OM_SET<br />
toolbar.gadget/TBM_GETMEMBER<br />
<br />
<br />
== Datasheet ==<br />
<br />
; NAME<br />
: toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
;SUPERCLASS<br />
: gadgetclass<br />
<br />
; REQUIRES<br />
: button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
; DESCRIPTION<br />
: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.<br />
<br />
=== Methods ===<br />
<br />
OM_NEW -- creates the toolbar object, sets attributes and defaults<br />
<br />
OM_DISPOSE -- disposes of the toolbar object<br />
<br />
OM_REMMEMBER -- used by the class internally; consider this method private<br />
<br />
OM_SET -- sets toolbar, member and image attributes (see the OM_SET section below for more information)<br />
<br />
OM_GET -- retrieves toolbar attributes<br />
<br />
TBM_GETMEMBER -- retrieves a given member attribute (see the TBM_GETMEMBER section below for more information)<br />
<br />
=== ATTRIBUTES ===<br />
<br />
GA_ID (uint16)<br />
Unique ID number for the gadget.<br />
<br />
Defaults to 0<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
GA_ReadOnly (BOOL)<br />
If set to TRUE, none of the toolbar buttons will be selectable.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
GA_BackFill (struct Hook *)<br />
A backfill hook to provide a background filled with a specific colour<br />
or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
<br />
Defaults to NULL (the default backfill hook).<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
GA_TextAttr (struct TextAttr *)<br />
Pointer to a TextAttr structure describing the font to be used for<br />
the gadget's button text labels (if they are used).<br />
<br />
Defaults to the system's default public screen font.<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
TOOLBAR_Orientation (uint32)<br />
The toolbar orientation: horizontal or vertical.<br />
<br />
Defaults to TB_ORIENT_HORIZ<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_Spacing (uint32)<br />
The spacing between the individual toolbar members, in pixels.<br />
<br />
Defaults to 2<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_HorizPadding<br />
TOOLBAR_VertPadding (uint32)<br />
The horizontal/vertical distance, in pixels, between the toolbar<br />
members and the gadget border (or outer bevel, if displayed - see<br />
TOOLBAR_BevelStyle below).<br />
<br />
Defaults to 0<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_InnerPadding (uint32)<br />
The distance, in pixels, between the member contents (image and/or text)<br />
and the button frame. Changing this setting will affect the size of the<br />
toolbar members.<br />
<br />
Defaults to 4<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_HandleOverflow (BOOL)<br />
Overflow is a situation when there is not enough space to fit all<br />
toolbar members within the current window. If this tag is set to TRUE,<br />
all members that don't fit will be moved into a pop-up menu whenever<br />
overflow takes place. A selector to invoke the menu will be displayed<br />
on the right.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_MinVisible (uint32)<br />
If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the<br />
specified number of members (including spacers and separators) will<br />
always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
<br />
Defaults to 1<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_SpacerSize (uint32)<br />
The size of the spacer member, in pixels. This value will affect the<br />
width (in a horizontal toolbar) or the height (in a vertical toolbar)<br />
of the spacer.<br />
<br />
Defaults to 5<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_ButtonStyle (uint32)<br />
The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce<br />
a traditional-looking toolbar with framed buttons, whereas<br />
TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
<br />
Defaults to TB_BUTSTYLE_CLASSIC<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_BevelStyle (uint32)<br />
The style of the gadget's outer bevel (frame). The Bevel Image class<br />
is used, so the style values from <images/bevel.h> are applicable to<br />
this tag (although not all of them make good sense to use with the<br />
toolbar). The recommended values are:<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar<br />
buttons), make sure that you also adjust TOOLBAR_HorizPadding and<br />
TOOLBAR_VertPadding, otherwise the outer bevel will interfere with<br />
the button frames.<br />
<br />
Defaults to BVS_NONE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_SeparatorStyle (uint32)<br />
Determines the look of the separator member. If you want to change it<br />
on the fly while the window is open, call SetGadgetAttrs() rather than<br />
SetAttrs() to trigger an immediate redraw.<br />
<br />
Defaults to TB_SEPSTYLE_NORMAL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_SelectionStyle (uint32)<br />
Determines how member selection is indicated in the borderless mode.<br />
If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the<br />
selection: the programmer must provide a select image for each button<br />
or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below),<br />
otherwise there will be no visual response. If the tag is set to<br />
TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around<br />
the member to indicate the selection.<br />
<br />
This tag is ignored in the classic mode with framed buttons.<br />
<br />
Defaults to TB_SELSTYLE_NONE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_BackFill (struct Hook *)<br />
A custom backfill hook to provide a background filled with a specific<br />
colour or pattern.<br />
<br />
This tag is meant to replace GA_BackFill because if the toolbar gadget<br />
is placed in a layout, the value of GA_BackFill can only be set after<br />
the window opens (this is because the Layout Gadget propagates its own<br />
backfill to all of its children). TOOLBAR_BackFill is provided as<br />
a convenience tag that overrides GA_BackFill, and allows setting your<br />
backfill hook even before the window opens.<br />
<br />
Defaults to NULL (the default layers backfill hook).<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
TOOLBAR_Display (uint32)<br />
Specifies what you want to display inside the toolbar button or toggle<br />
members. The possible values are:<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
Defaults to TB_DISPLAY_IMAGES<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_TextPlace (uint32)<br />
Specifies the placement of the text labels with regard to the toolbar<br />
images. This tag is only meaningful when actual text labels are<br />
provided via TBMEMBER_Text, and TOOLBAR_Display is set to<br />
TB_DISPLAY_BOTH.<br />
<br />
Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_LabelArray (STRPTR *)<br />
Use this tag to create a minimum-configuration, text-only toolbar.<br />
You simply pass a NULL-terminated array of strings representing<br />
the toolbar button labels. Each label can contain an underscore<br />
character to indicate the keyboard shortcut for the respective button.<br />
<br />
TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
<br />
Using this tag, the limitation is that you cannot create toggle members<br />
(only buttons, separators and spacers).<br />
<br />
A special string, " ", will create a spacer.<br />
A special string, "_", will create a separator.<br />
<br />
Spacers and separators cannot appear as the very first member in the<br />
toolbar. Therefore, the label array may not begin with a spacer or<br />
a separator string. Also, the array must contain at least one valid<br />
string to create a button, otherwise the toolbar creation will fail.<br />
<br />
The button strings are copied to an internal buffer, so the label array<br />
need not remain valid throughout the lifetime of the gadget.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TOOLBAR_EvenSize (BOOL)<br />
If set to TRUE, this attribute will size all button and toggle members<br />
evenly according to the largest member. The attribute has no effect<br />
on spacers and separators.<br />
<br />
If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above)<br />
and your toolbar images are all of the same size, keep this attribute<br />
at its default FALSE value: the button dimensions will be equal anyway,<br />
and you'll spare the gadget some unnecessary calculations. On the other <br />
hand, setting this tag to TRUE may produce a visually more plausible<br />
result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_ImageSet (uint32)<br />
If more than one image set have been configured via TOOLBAR_AddImageSet<br />
(see below), use this tag to determine which set is to be displayed in<br />
the toolbar. The value passed to this tag is the image set ID.<br />
<br />
Defaults to 0<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
*** Method attributes ***<br />
<br />
The following tags are not attributes but, rather, methods that perform<br />
various functions associated with toolbar configuration:<br />
<br />
TOOLBAR_AddImageSet (uint32)<br />
Creates a new image set. The value passed to this tag is a numeric ID<br />
identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to<br />
display the particular image set in the toolbar.<br />
<br />
This tag should be followed by a sequence of TOOLBAR_AddImage tags (see<br />
below), each creating one image in the given set.<br />
<br />
If the gadget only uses one set of images, passing TOOLBAR_AddImageSet<br />
is not necessary. Each TOOLBAR_AddImage will add the respective image<br />
to the default image set identified by an ID of 0.<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
TOOLBAR_AddImage (uint32)<br />
Creates a new image in a given image set. The value passed to this tag<br />
is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID<br />
(see below) to associate the image with a particular toolbar member.<br />
<br />
This tag should be followed by a sequence of TBIMAGE_ tags (see the<br />
"Image attributes" section below), each configuring one aspect of the<br />
image, including its optional selected variant (referred to as the<br />
"select image").<br />
<br />
Images are added to the default image set unless a preceding<br />
TOOLBAR_AddImageSet specifies a different set.<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
TOOLBAR_AddMember (uint32)<br />
Creates a new toolbar member. The value passed to this tag is a numeric<br />
ID identifying the member.<br />
<br />
Spacers and separators normally don't need an ID, so you can use<br />
TB_NO_ID as a value for TOOLBAR_AddMember when creating these members.<br />
However, if you want to manipulate spacers/separators in your GUI,<br />
an ID will be necessary so that you can pass it to TOOLBAR_SetMember<br />
to identify the respective spacer or separator member.<br />
<br />
You can add members when the toolbar object is being created, i.e.<br />
as part of the NewObject() call, or at any time later via SetAttrs().<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
TOOLBAR_SetMember<br />
Use this tag in a SetAttrs() call to identify the member you want to<br />
modify.<br />
<br />
Applicability is (OM_SET)<br />
<br />
TOOLBAR_SetGroup<br />
Use this tag in a SetAttrs() call to identify the group of members you<br />
want to modify collectively.<br />
<br />
Applicability is (OM_SET)<br />
<br />
*** Member attributes ***<br />
<br />
TBMEMBER_Type (uint32)<br />
The type of the toolbar member. The possible values are the following:<br />
TB_MTYPE_BUTTON-- a normal toolbar button<br />
TB_MTYPE_TOGGLE-- a toggle (on/off) button<br />
TB_MTYPE_SPACER-- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
<br />
The type is set upon member creation, and cannot be changed.<br />
<br />
Defaults to TB_MTYPE_BUTTON<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBMEMBER_ImageID (uint32)<br />
The identifier of the image to be used for the button or toggle member<br />
(see TOOLBAR_AddImage above). This tag is not relevant to spacers and<br />
separators; TBM_GETMEMBER will always return TB_NO_ID should you inquire<br />
about the TBMEMBER_ImageID value of such a member.<br />
<br />
Defaults to TB_NO_ID (no image associated with this member)<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Text (CONST_STRPTR)<br />
The label to associate with a button or a toggle member. This tag is not<br />
relevant to spacers and separators; TBM_GETMEMBER will always return<br />
NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
<br />
The text label will be used as fallback in case no image is found or<br />
provided.<br />
<br />
The text string can contain an underscore character (_), indicating the<br />
keyboard shortcut for this member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Disabled (BOOL)<br />
The current state (disabled or not disabled) of a member. This tag is<br />
not relevant to spacers and separators; TBM_GETMEMBER will always return<br />
FALSE should you inquire about the TBMEMBER_Disabled value of such<br />
a member.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Hidden (BOOL)<br />
Specifies whether the particular member is displayed in the toolbar or<br />
hidden. You can use this tag to create "dynamic" toolbar layouts that<br />
adapt the actual member set to various application settings.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Selected (BOOL)<br />
The current selection state of a toggle member. This tag is not relevant<br />
to normal buttons (TB_MTYPE_BUTTON), spacers and separators;<br />
TBM_GETMEMBER will always return FALSE should you inquire about the<br />
TBMEMBER_Selected value of such a member.<br />
<br />
You can set a target BOOPSI object for any toggle member, using the<br />
standard icclass ICA_TARGET tag. The target will receive an automatic<br />
notification of the toggle selection. This way toolbar toggles can<br />
easily communicate with other boolean gadgets such as checkboxes.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_NOTIFY, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Group (uint32)<br />
Member group ID. Several members can be manipulated at once if they are<br />
assigned to the same group. Use TOOLBAR_SetGroup with the respective<br />
group ID to identify the group to be manipulated.<br />
<br />
Defaults to TB_NO_ID (not assigned to any group)<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_MXGroup (uint32)<br />
MX group ID. Toggle members can be put in groups of mutually-exclusive<br />
buttons. When such a toggle is selected, all other toggles in the same<br />
MX group will become deselected.<br />
<br />
This tag is not relevant to normal buttons, spacers and separators;<br />
TBM_GETMEMBER will always return TB_NO_ID should you inquire about the<br />
TBMEMBER_MXGroup value of such a member.<br />
<br />
Defaults to TB_NO_ID (not assigned to any MX group)<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_HintInfo (CONST_STRPTR)<br />
The help text to be displayed when the user hovers the mouse pointer<br />
over the respective member. This tag is not relevant to spacers and<br />
separators; TBM_GETMEMBER will always return NULL should you inquire<br />
about the TBMEMBER_HintInfo value of such a member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_UserData (APTR)<br />
Arbitrary user data associated with this member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
*** Image attributes ***<br />
<br />
TBIMAGE_Image (struct Image *)<br />
Custom image to be used for a button or a toggle member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_ImageFile (CONST_STRPTR)<br />
The full path to the source file to create the image from. The image<br />
will be loaded and built using the Shared Image class.<br />
<br />
All images created this way will also be disposed of automatically.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_SelImage (struct Image *)<br />
Custom image to display when the member becomes selected.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_SelImageFile (CONST_STRPTR)<br />
The full path to the source file to create the select image from.<br />
The image will be loaded and built using the Shared Image class.<br />
<br />
All images created this way will also be disposed of automatically.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_Width (uint32)<br />
TBIMAGE_Height (uint32)<br />
Image dimensions, in pixels. These tags can only be used in connection<br />
with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the<br />
respective source file will be scaled to the specified width and height.<br />
Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot<br />
be resized using these tags.<br />
<br />
Defaults to 0<br />
<br />
Applicability is (OM_NEW)<br />
<br />
NOTES<br />
Some of the attributes described above change the sizing requirements of<br />
the gadget. If set on the fly (i.e. when the toolbar is already displayed<br />
in the window), the gadget domain will need recalculating and a re-layout<br />
must take place. Refer to the OM_SET method documentation below to see<br />
how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image.<br />
Image attributes cannot be changed later.<br />
<br />
BUGS<br />
<br />
<br />
SEE ALSO<br />
<br />
toolbar.gadget/OM_SET toolbar.gadget/OM_SET<br />
<br />
NAME<br />
OM_SET -- set toolbar attributes<br />
<br />
SYNOPSIS<br />
uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
<br />
uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win,<br />
struct Requester *req, Tag tag1, ...);<br />
<br />
FUNCTION<br />
This method sets the attributes of the toolbar and/or of its members.<br />
SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions<br />
to invoke this method.<br />
<br />
To change a member attribute you first need to pass TOOLBAR_SetMember<br />
to identify the respective member, and then the member attribute tag(s).<br />
See the EXAMPLE section below.<br />
<br />
To change an attribute collectively for a group of members you first need<br />
to pass TOOLBAR_SetGroup to identify the respective group, and then the<br />
member attribute tag(s). See the EXAMPLE section below.<br />
<br />
INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
RESULT<br />
This method will return TB_NEED_RETHINK if one or more of the attributes<br />
change the sizing requirements of the gadget. In such a case, the<br />
appropriate reaction is to call WM_RETHINK on the gadget's window object<br />
to recalculate the domain and re-layout the contents.<br />
<br />
If you know you will be changing an attribute that requires a WM_RETHINK,<br />
prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an<br />
unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
<br />
The method returns 0 if no rethink is needed.<br />
<br />
EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, GROUP_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
NOTES<br />
<br />
BUGS<br />
<br />
SEE ALSO<br />
<br />
toolbar.gadget/TBM_GETMEMBER toolbar.gadget/TBM_GETMEMBER<br />
<br />
NAME<br />
TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
SYNOPSIS<br />
uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
<br />
uint32 result = IDoMethod(Object *toolbar, uint32 methodID,<br />
uint32 attrID, uint32 *storage);<br />
<br />
FUNCTION<br />
Use this method to obtain the value of a given member attribute.<br />
<br />
Because of the way OM_GET is implemented in Intuition, getting member<br />
attributes is done differently compared to setting them. The difference<br />
boils down to the following:<br />
<br />
- We cannot use a convenience function such as GetAttr() or GetAttrs(),<br />
so a dedicated method is provided. Refer to the EXAMPLE section below<br />
to see how to invoke the method.<br />
<br />
- Only one attribute can be queried at a time. (As multiple attributes<br />
will rarely be requested in real use, this limitation should not pose<br />
a significant problem.)<br />
<br />
INPUTS<br />
For IDoMethodA():<br />
toolbar-- the toolbar gadget object<br />
msg-- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
toolbar-- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
attrID -- the attribute tag identifier<br />
storage-- a pointer to the variable for storing the attribute value<br />
<br />
RESULT<br />
The "result" value will be 1L if the requested attribute value has been<br />
obtained successfully. The attribute value itself is returned in the<br />
provided storage variable.<br />
<br />
EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID,<br />
TBMEMBER_Selected, &storage);<br />
<br />
NOTES<br />
<br />
BUGS<br />
<br />
SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=ToolBar_Gadget_Class&diff=997ToolBar Gadget Class2020-10-30T22:32:21Z<p>Trixie: </p>
<hr />
<div>TABLE OF CONTENTS<br />
<br />
toolbar.gadget/--datasheet--<br />
toolbar.gadget/OM_SET<br />
toolbar.gadget/TBM_GETMEMBER<br />
<br />
<br />
toolbar.gadget/--datasheet-- toolbar.gadget/--datasheet--<br />
<br />
NAME<br />
toolbar.gadget -- Create toolbar BOOPSI objects<br />
<br />
SUPERCLASS<br />
gadgetclass<br />
<br />
REQUIRES<br />
button.gadget, select.gadget, label.image, bevel.image, shared.image<br />
<br />
DESCRIPTION<br />
This class is an easy-to-setup, highly configurable alternative to the<br />
standard speedbar.gadget provided by the operating system.<br />
<br />
METHODS<br />
OM_NEW -- creates the toolbar object, sets attributes and defaults<br />
<br />
OM_DISPOSE -- disposes of the toolbar object<br />
<br />
OM_REMMEMBER -- used by the class internally; consider this method private<br />
<br />
OM_SET -- sets toolbar, member and image attributes (see the OM_SET<br />
section below for more information)<br />
<br />
OM_GET -- retrieves toolbar attributes<br />
<br />
TBM_GETMEMBER -- retrieves a given member attribute (see the TBM_GETMEMBER<br />
section below for more information)<br />
<br />
ATTRIBUTES<br />
GA_ID (uint16)<br />
Unique ID number for the gadget.<br />
<br />
Defaults to 0<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
GA_ReadOnly (BOOL)<br />
If set to TRUE, none of the toolbar buttons will be selectable.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
GA_BackFill (struct Hook *)<br />
A backfill hook to provide a background filled with a specific colour<br />
or pattern. Please also see notes for TOOLBAR_BackFill below.<br />
<br />
Defaults to NULL (the default backfill hook).<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
GA_TextAttr (struct TextAttr *)<br />
Pointer to a TextAttr structure describing the font to be used for<br />
the gadget's button text labels (if they are used).<br />
<br />
Defaults to the system's default public screen font.<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
TOOLBAR_Orientation (uint32)<br />
The toolbar orientation: horizontal or vertical.<br />
<br />
Defaults to TB_ORIENT_HORIZ<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_Spacing (uint32)<br />
The spacing between the individual toolbar members, in pixels.<br />
<br />
Defaults to 2<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_HorizPadding<br />
TOOLBAR_VertPadding (uint32)<br />
The horizontal/vertical distance, in pixels, between the toolbar<br />
members and the gadget border (or outer bevel, if displayed - see<br />
TOOLBAR_BevelStyle below).<br />
<br />
Defaults to 0<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_InnerPadding (uint32)<br />
The distance, in pixels, between the member contents (image and/or text)<br />
and the button frame. Changing this setting will affect the size of the<br />
toolbar members.<br />
<br />
Defaults to 4<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_HandleOverflow (BOOL)<br />
Overflow is a situation when there is not enough space to fit all<br />
toolbar members within the current window. If this tag is set to TRUE,<br />
all members that don't fit will be moved into a pop-up menu whenever<br />
overflow takes place. A selector to invoke the menu will be displayed<br />
on the right.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_MinVisible (uint32)<br />
If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the<br />
specified number of members (including spacers and separators) will<br />
always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.<br />
<br />
Defaults to 1<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_SpacerSize (uint32)<br />
The size of the spacer member, in pixels. This value will affect the<br />
width (in a horizontal toolbar) or the height (in a vertical toolbar)<br />
of the spacer.<br />
<br />
Defaults to 5<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_ButtonStyle (uint32)<br />
The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce<br />
a traditional-looking toolbar with framed buttons, whereas<br />
TB_BUTSTYLE_BORDERLESS will configure a borderless look.<br />
<br />
Defaults to TB_BUTSTYLE_CLASSIC<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_BevelStyle (uint32)<br />
The style of the gadget's outer bevel (frame). The Bevel Image class<br />
is used, so the style values from <images/bevel.h> are applicable to<br />
this tag (although not all of them make good sense to use with the<br />
toolbar). The recommended values are:<br />
BVS_NONE -- no bevel is drawn around the toolbar<br />
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel<br />
<br />
When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar<br />
buttons), make sure that you also adjust TOOLBAR_HorizPadding and<br />
TOOLBAR_VertPadding, otherwise the outer bevel will interfere with<br />
the button frames.<br />
<br />
Defaults to BVS_NONE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_SeparatorStyle (uint32)<br />
Determines the look of the separator member. If you want to change it<br />
on the fly while the window is open, call SetGadgetAttrs() rather than<br />
SetAttrs() to trigger an immediate redraw.<br />
<br />
Defaults to TB_SEPSTYLE_NORMAL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_SelectionStyle (uint32)<br />
Determines how member selection is indicated in the borderless mode.<br />
If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the<br />
selection: the programmer must provide a select image for each button<br />
or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below),<br />
otherwise there will be no visual response. If the tag is set to<br />
TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around<br />
the member to indicate the selection.<br />
<br />
This tag is ignored in the classic mode with framed buttons.<br />
<br />
Defaults to TB_SELSTYLE_NONE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_BackFill (struct Hook *)<br />
A custom backfill hook to provide a background filled with a specific<br />
colour or pattern.<br />
<br />
This tag is meant to replace GA_BackFill because if the toolbar gadget<br />
is placed in a layout, the value of GA_BackFill can only be set after<br />
the window opens (this is because the Layout Gadget propagates its own<br />
backfill to all of its children). TOOLBAR_BackFill is provided as<br />
a convenience tag that overrides GA_BackFill, and allows setting your<br />
backfill hook even before the window opens.<br />
<br />
Defaults to NULL (the default layers backfill hook).<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE)<br />
<br />
TOOLBAR_Display (uint32)<br />
Specifies what you want to display inside the toolbar button or toggle<br />
members. The possible values are:<br />
TB_DISPLAY_IMAGES -- display only images<br />
TB_DISPLAY_TEXT -- display only text labels<br />
TB_DISPLAY_BOTH -- display both images and text labels<br />
<br />
Defaults to TB_DISPLAY_IMAGES<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_TextPlace (uint32)<br />
Specifies the placement of the text labels with regard to the toolbar<br />
images. This tag is only meaningful when actual text labels are<br />
provided via TBMEMBER_Text, and TOOLBAR_Display is set to<br />
TB_DISPLAY_BOTH.<br />
<br />
Defaults to and currently only supports TB_PLACETEXT_BELOW<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_LabelArray (STRPTR *)<br />
Use this tag to create a minimum-configuration, text-only toolbar.<br />
You simply pass a NULL-terminated array of strings representing<br />
the toolbar button labels. Each label can contain an underscore<br />
character to indicate the keyboard shortcut for the respective button.<br />
<br />
TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.<br />
<br />
Using this tag, the limitation is that you cannot create toggle members<br />
(only buttons, separators and spacers).<br />
<br />
A special string, " ", will create a spacer.<br />
A special string, "_", will create a separator.<br />
<br />
Spacers and separators cannot appear as the very first member in the<br />
toolbar. Therefore, the label array may not begin with a spacer or<br />
a separator string. Also, the array must contain at least one valid<br />
string to create a button, otherwise the toolbar creation will fail.<br />
<br />
The button strings are copied to an internal buffer, so the label array<br />
need not remain valid throughout the lifetime of the gadget.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TOOLBAR_EvenSize (BOOL)<br />
If set to TRUE, this attribute will size all button and toggle members<br />
evenly according to the largest member. The attribute has no effect<br />
on spacers and separators.<br />
<br />
If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above)<br />
and your toolbar images are all of the same size, keep this attribute<br />
at its default FALSE value: the button dimensions will be equal anyway,<br />
and you'll spare the gadget some unnecessary calculations. On the other <br />
hand, setting this tag to TRUE may produce a visually more plausible<br />
result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
TOOLBAR_ImageSet (uint32)<br />
If more than one image set have been configured via TOOLBAR_AddImageSet<br />
(see below), use this tag to determine which set is to be displayed in<br />
the toolbar. The value passed to this tag is the image set ID.<br />
<br />
Defaults to 0<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)<br />
<br />
*** Method attributes ***<br />
<br />
The following tags are not attributes but, rather, methods that perform<br />
various functions associated with toolbar configuration:<br />
<br />
TOOLBAR_AddImageSet (uint32)<br />
Creates a new image set. The value passed to this tag is a numeric ID<br />
identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to<br />
display the particular image set in the toolbar.<br />
<br />
This tag should be followed by a sequence of TOOLBAR_AddImage tags (see<br />
below), each creating one image in the given set.<br />
<br />
If the gadget only uses one set of images, passing TOOLBAR_AddImageSet<br />
is not necessary. Each TOOLBAR_AddImage will add the respective image<br />
to the default image set identified by an ID of 0.<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
TOOLBAR_AddImage (uint32)<br />
Creates a new image in a given image set. The value passed to this tag<br />
is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID<br />
(see below) to associate the image with a particular toolbar member.<br />
<br />
This tag should be followed by a sequence of TBIMAGE_ tags (see the<br />
"Image attributes" section below), each configuring one aspect of the<br />
image, including its optional selected variant (referred to as the<br />
"select image").<br />
<br />
Images are added to the default image set unless a preceding<br />
TOOLBAR_AddImageSet specifies a different set.<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
TOOLBAR_AddMember (uint32)<br />
Creates a new toolbar member. The value passed to this tag is a numeric<br />
ID identifying the member.<br />
<br />
Spacers and separators normally don't need an ID, so you can use<br />
TB_NO_ID as a value for TOOLBAR_AddMember when creating these members.<br />
However, if you want to manipulate spacers/separators in your GUI,<br />
an ID will be necessary so that you can pass it to TOOLBAR_SetMember<br />
to identify the respective spacer or separator member.<br />
<br />
You can add members when the toolbar object is being created, i.e.<br />
as part of the NewObject() call, or at any time later via SetAttrs().<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
TOOLBAR_SetMember<br />
Use this tag in a SetAttrs() call to identify the member you want to<br />
modify.<br />
<br />
Applicability is (OM_SET)<br />
<br />
TOOLBAR_SetGroup<br />
Use this tag in a SetAttrs() call to identify the group of members you<br />
want to modify collectively.<br />
<br />
Applicability is (OM_SET)<br />
<br />
*** Member attributes ***<br />
<br />
TBMEMBER_Type (uint32)<br />
The type of the toolbar member. The possible values are the following:<br />
TB_MTYPE_BUTTON-- a normal toolbar button<br />
TB_MTYPE_TOGGLE-- a toggle (on/off) button<br />
TB_MTYPE_SPACER-- a spacer<br />
TB_MTYPE_SEPARATOR -- a separator bar<br />
<br />
The type is set upon member creation, and cannot be changed.<br />
<br />
Defaults to TB_MTYPE_BUTTON<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBMEMBER_ImageID (uint32)<br />
The identifier of the image to be used for the button or toggle member<br />
(see TOOLBAR_AddImage above). This tag is not relevant to spacers and<br />
separators; TBM_GETMEMBER will always return TB_NO_ID should you inquire<br />
about the TBMEMBER_ImageID value of such a member.<br />
<br />
Defaults to TB_NO_ID (no image associated with this member)<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Text (CONST_STRPTR)<br />
The label to associate with a button or a toggle member. This tag is not<br />
relevant to spacers and separators; TBM_GETMEMBER will always return<br />
NULL should you inquire about the TBMEMBER_Text value of such a member.<br />
<br />
The text label will be used as fallback in case no image is found or<br />
provided.<br />
<br />
The text string can contain an underscore character (_), indicating the<br />
keyboard shortcut for this member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Disabled (BOOL)<br />
The current state (disabled or not disabled) of a member. This tag is<br />
not relevant to spacers and separators; TBM_GETMEMBER will always return<br />
FALSE should you inquire about the TBMEMBER_Disabled value of such<br />
a member.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Hidden (BOOL)<br />
Specifies whether the particular member is displayed in the toolbar or<br />
hidden. You can use this tag to create "dynamic" toolbar layouts that<br />
adapt the actual member set to various application settings.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Selected (BOOL)<br />
The current selection state of a toggle member. This tag is not relevant<br />
to normal buttons (TB_MTYPE_BUTTON), spacers and separators;<br />
TBM_GETMEMBER will always return FALSE should you inquire about the<br />
TBMEMBER_Selected value of such a member.<br />
<br />
You can set a target BOOPSI object for any toggle member, using the<br />
standard icclass ICA_TARGET tag. The target will receive an automatic<br />
notification of the toggle selection. This way toolbar toggles can<br />
easily communicate with other boolean gadgets such as checkboxes.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_NOTIFY, TBM_GETMEMBER)<br />
<br />
TBMEMBER_Group (uint32)<br />
Member group ID. Several members can be manipulated at once if they are<br />
assigned to the same group. Use TOOLBAR_SetGroup with the respective<br />
group ID to identify the group to be manipulated.<br />
<br />
Defaults to TB_NO_ID (not assigned to any group)<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_MXGroup (uint32)<br />
MX group ID. Toggle members can be put in groups of mutually-exclusive<br />
buttons. When such a toggle is selected, all other toggles in the same<br />
MX group will become deselected.<br />
<br />
This tag is not relevant to normal buttons, spacers and separators;<br />
TBM_GETMEMBER will always return TB_NO_ID should you inquire about the<br />
TBMEMBER_MXGroup value of such a member.<br />
<br />
Defaults to TB_NO_ID (not assigned to any MX group)<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_HintInfo (CONST_STRPTR)<br />
The help text to be displayed when the user hovers the mouse pointer<br />
over the respective member. This tag is not relevant to spacers and<br />
separators; TBM_GETMEMBER will always return NULL should you inquire<br />
about the TBMEMBER_HintInfo value of such a member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
TBMEMBER_UserData (APTR)<br />
Arbitrary user data associated with this member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)<br />
<br />
*** Image attributes ***<br />
<br />
TBIMAGE_Image (struct Image *)<br />
Custom image to be used for a button or a toggle member.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_ImageFile (CONST_STRPTR)<br />
The full path to the source file to create the image from. The image<br />
will be loaded and built using the Shared Image class.<br />
<br />
All images created this way will also be disposed of automatically.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_SelImage (struct Image *)<br />
Custom image to display when the member becomes selected.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_SelImageFile (CONST_STRPTR)<br />
The full path to the source file to create the select image from.<br />
The image will be loaded and built using the Shared Image class.<br />
<br />
All images created this way will also be disposed of automatically.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW)<br />
<br />
TBIMAGE_Width (uint32)<br />
TBIMAGE_Height (uint32)<br />
Image dimensions, in pixels. These tags can only be used in connection<br />
with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the<br />
respective source file will be scaled to the specified width and height.<br />
Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot<br />
be resized using these tags.<br />
<br />
Defaults to 0<br />
<br />
Applicability is (OM_NEW)<br />
<br />
NOTES<br />
Some of the attributes described above change the sizing requirements of<br />
the gadget. If set on the fly (i.e. when the toolbar is already displayed<br />
in the window), the gadget domain will need recalculating and a re-layout<br />
must take place. Refer to the OM_SET method documentation below to see<br />
how to handle such situations.<br />
<br />
Images are configured at OM_NEW, i.e. when creating each respective image.<br />
Image attributes cannot be changed later.<br />
<br />
BUGS<br />
<br />
<br />
SEE ALSO<br />
<br />
toolbar.gadget/OM_SET toolbar.gadget/OM_SET<br />
<br />
NAME<br />
OM_SET -- set toolbar attributes<br />
<br />
SYNOPSIS<br />
uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);<br />
<br />
uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win,<br />
struct Requester *req, Tag tag1, ...);<br />
<br />
FUNCTION<br />
This method sets the attributes of the toolbar and/or of its members.<br />
SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions<br />
to invoke this method.<br />
<br />
To change a member attribute you first need to pass TOOLBAR_SetMember<br />
to identify the respective member, and then the member attribute tag(s).<br />
See the EXAMPLE section below.<br />
<br />
To change an attribute collectively for a group of members you first need<br />
to pass TOOLBAR_SetGroup to identify the respective group, and then the<br />
member attribute tag(s). See the EXAMPLE section below.<br />
<br />
INPUTS<br />
toolbar -- the toolbar gadget object<br />
win -- the window that hosts the toolbar<br />
req -- requester pointer (use NULL)<br />
tag1 etc. -- a list of toolbar attribute tags<br />
<br />
RESULT<br />
This method will return TB_NEED_RETHINK if one or more of the attributes<br />
change the sizing requirements of the gadget. In such a case, the<br />
appropriate reaction is to call WM_RETHINK on the gadget's window object<br />
to recalculate the domain and re-layout the contents.<br />
<br />
If you know you will be changing an attribute that requires a WM_RETHINK,<br />
prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an<br />
unnecessary redraw (WM_RETHINK will perform the redraw for you).<br />
<br />
The method returns 0 if no rethink is needed.<br />
<br />
EXAMPLE<br />
<br />
// To set various toolbar attributes:<br />
if ( IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_Orientation, TB_ORIENT_VERT,<br />
TOOLBAR_Spacing, 4,<br />
TOOLBAR_SpacerSize, 10,<br />
TAG_END) == TB_NEED_RETHINK )<br />
{<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
}<br />
<br />
// To disable a member:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
// To hide a member:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_Hidden, TRUE,<br />
TAG_END);<br />
IIntuition->IDoMethod(winObj, WM_RETHINK);<br />
<br />
// To modify several member attributes at once:<br />
IIntuition->SetAttrs(toolbar,<br />
TOOLBAR_SetMember, MEMBER_ID,<br />
TBMEMBER_HintInfo, "My help string",<br />
TBMEMBER_UserData, anything,<br />
TAG_END);<br />
<br />
// To disable all members assigned to a group:<br />
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,<br />
TOOLBAR_SetGroup, GROUP_ID,<br />
TBMEMBER_Disabled, TRUE,<br />
TAG_END);<br />
<br />
NOTES<br />
<br />
BUGS<br />
<br />
SEE ALSO<br />
<br />
toolbar.gadget/TBM_GETMEMBER toolbar.gadget/TBM_GETMEMBER<br />
<br />
NAME<br />
TBM_GETMEMBER -- obtain the value of a specific member attribute<br />
<br />
SYNOPSIS<br />
uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);<br />
<br />
uint32 result = IDoMethod(Object *toolbar, uint32 methodID,<br />
uint32 attrID, uint32 *storage);<br />
<br />
FUNCTION<br />
Use this method to obtain the value of a given member attribute.<br />
<br />
Because of the way OM_GET is implemented in Intuition, getting member<br />
attributes is done differently compared to setting them. The difference<br />
boils down to the following:<br />
<br />
- We cannot use a convenience function such as GetAttr() or GetAttrs(),<br />
so a dedicated method is provided. Refer to the EXAMPLE section below<br />
to see how to invoke the method.<br />
<br />
- Only one attribute can be queried at a time. (As multiple attributes<br />
will rarely be requested in real use, this limitation should not pose<br />
a significant problem.)<br />
<br />
INPUTS<br />
For IDoMethodA():<br />
toolbar-- the toolbar gadget object<br />
msg-- a pointer to an initialized tbGetMember structure<br />
<br />
For IDoMethod():<br />
toolbar-- the toolbar gadget object<br />
methodID -- this method's identifier, TBM_GETMEMBER<br />
attrID -- the attribute tag identifier<br />
storage-- a pointer to the variable for storing the attribute value<br />
<br />
RESULT<br />
The "result" value will be 1L if the requested attribute value has been<br />
obtained successfully. The attribute value itself is returned in the<br />
provided storage variable.<br />
<br />
EXAMPLE<br />
<br />
// To query about the selection state of a toggle member:<br />
uint32 storage;<br />
<br />
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID,<br />
TBMEMBER_Selected, &storage);<br />
<br />
NOTES<br />
<br />
BUGS<br />
<br />
SEE ALSO</div>Trixiehttp://wiki.amiga.org/index.php?title=InfoWindow_Class&diff=821InfoWindow Class2017-12-06T11:32:29Z<p>Trixie: </p>
<hr />
<div>== Introduction ==<br />
<br />
This guide describes the ReAction-compatible '''information window class''' for users and developers.<br />
<br />
The '''InfoWindow Class''' (installed as ''infowindow.class'' in the SYS:Classes/ directory) is a BOOPSI-compliant class that is used to display information windows such as About-windows commonly found in many applications.<br />
<br />
From developers' perspective, it provides an easy and adaptable way of creating and presenting information windows within their application. The class is highly configurable to suit many different needs and scenarios.<br />
<br />
== Version ==<br />
<br />
The latest version is 53.8 available in the [[Enhancer Software]] for both AmigaOS3 and AmigaOS4.<br />
<br />
== Features ==<br />
<br />
The features include:<br />
<br />
* Formatted text<br />
<br />
* Aligned images<br />
<br />
* Configurable panel featuring tabs, a configurable text field or a custom BOOPSI gadget<br />
<br />
* Configurable button row supporting any number of buttons, and a timeout feature.<br />
<br />
<br />
== Screenshots ==<br />
<br />
<center><br />
{|<br />
|- style="vertical-align:bottom;text-align:center;"<br />
|[[File:infowindow_class_os3_example1.png|center|250px]]<br />
''OS3 version''<br />
|[[File:infowindow_class_os3_example2.png|center|250px]]<br />
''OS3 version''<br />
|[[File:infowindow_class_os3_example3.png|center|250px]]<br />
''OS3 version''<br />
|}<br />
</center><br />
<br />
<center><br />
{|<br />
|- style="vertical-align:bottom;text-align:center;"<br />
|[[File:infowindow_class_os4_example1.png|center|250px]]<br />
''OS4 version''<br />
|[[File:infowindow_class_os4_example2.png|center|250px]]<br />
''OS4 version''<br />
|[[File:infowindow_class_os4_example3.png|center|250px]]<br />
''OS4 version''<br />
|}<br />
</center><br />
<br />
<br />
== For Developers ==<br />
<br />
=== Autodoc ===<br />
<pre><br />
TABLE OF CONTENTS<br />
<br />
infowindow.class/--datasheet--<br />
infowindow.class/IWM_OPEN<br />
<br />
<br />
<br />
infowindow.class/--datasheet-- infowindow.class/--datasheet--<br />
<br />
NAME<br />
infowindow.class -- Create an information window<br />
<br />
SUPERCLASS<br />
window.class<br />
<br />
REQUIRES<br />
bitmap.image, button.gadget, checkbox.gadget, clicktab.gadget,<br />
label.image, layout.gadget, scroller.gadget, texteditor.gadget,<br />
window.class<br />
<br />
DESCRIPTION<br />
This is a BOOPSI class to create information windows, such as those that<br />
applications display when you select the "About" menu command.<br />
<br />
Supported features:<br />
<br />
- formatted text<br />
- image with configurable placement and backfill<br />
- configurable panel to display tabs, a scrollable text field, or a custom<br />
BOOPSI gadget (e.g. a listbrowser)<br />
- configurable button row supporting any number of buttons<br />
- optional checkbox gadget for confirming information<br />
- keyboard control<br />
- timeout<br />
<br />
The class does not replace the Requester Class but it can be seen as<br />
a more sophisticated version of the REQTYPE_INFO requester type.<br />
<br />
METHODS<br />
OM_NEW -- creates the infowindow object, sets attributes and defaults<br />
<br />
OM_SET -- sets object attributes (passed to the superclass first)<br />
<br />
OM_GET -- retrieves object attributes (passed to the superclass first)<br />
<br />
OM_DISPOSE -- disposes of the infowindow object<br />
<br />
IWM_OPEN -- opens the infowindow<br />
<br />
KEYBOARD CONTROL<br />
Escape<br />
Cancels the infowindow (IWM_OPEN returns IWMRES_CANCEL).<br />
<br />
Return / Enter<br />
Selects the default choice and closes the infowindow (IWM_OPEN returns<br />
the number of the button).<br />
<br />
Cursor Left / Right<br />
Switches between tabs (if the tab panel is displayed).<br />
<br />
ATTRIBUTES<br />
The infowindow is in fact a modal (i.e. blocking) requester, so all of its<br />
attributes can only be set or retrieved when the window is NOT open.<br />
<br />
Use SetAttrs() freely in between individual IWM_OPEN calls to re-configure<br />
the infowindow: no need to dispose of and rebuild the object if you want<br />
to change the look, contents or behaviour of the window.<br />
<br />
SetAttrs() will return the number of attributes set.<br />
<br />
The InfoWindow Class is based on the Window Class, so many attributes<br />
supported by the superclass are applicable. Use them wisely: make sure<br />
you don't turn the infowindow into something it's not supposed to be.<br />
<br />
The following superclass attributes are explicitly IGNORED because their<br />
(mis)use could compromise the look or functioning of the infowindow:<br />
<br />
WA_Backdrop<br />
WA_BackFill<br />
WA_Borderless<br />
WA_Hidden<br />
WINDOW_AppPort<br />
WINDOW_AppWindow<br />
WINDOW_Iconifiable<br />
WINDOW_IconifyGadget<br />
WINDOW_IDCMPHook<br />
WINDOW_InputEvent<br />
WINDOW_MenuStrip<br />
WINDOW_NewMenu<br />
WINDOW_PopupGadget<br />
<br />
Further notes on the use of superclass attributes:<br />
<br />
WA_Width and WA_Height are treated as WA_InnerWidth and WA_InnerHeight,<br />
respectively. This behaviour is inherited from the Window Class.<br />
<br />
If WA_CloseGadget is provided and set to TRUE, the IWM_OPEN method will<br />
return the value of IWMRES_CANCEL if the window was closed (= cancelled)<br />
via the close gadget. The Escape key shortcut has an identical function<br />
(and result value) but it is available at all times, regardless of the<br />
WA_CloseGadget setting.<br />
<br />
The class needs to be able to resolve the screen on which the infowindow<br />
will open. The following policy is applied here:<br />
- If INFOWINDOW_Parent is set, the class will attempt to obtain the screen<br />
pointer from the parent window object (the window needs to be open for<br />
this to work);<br />
- the WA_CustomScreen, WA_PubScreen and WA_PubScreenName tags are next in<br />
preference, respectively;<br />
- if there is no tag setting allowing to resolve the screen, it is assumed<br />
that opening on the default public screen is requested.<br />
<br />
You might prefer setting INFOWINDOW_Parent over the Intuition screen tags.<br />
This way the infowindow will always stay with your program window, which<br />
is especially useful if your application supports jumping between screens.<br />
Otherwise you'd have to update the infowindow with a new screen pointer<br />
whenever the application changes screen.<br />
<br />
The InfoWindow Class' own attributes are described below:<br />
<br />
INFOWINDOW_Parent (Object *)<br />
A pointer to a window object that will be the "parent" of the<br />
information window. Often the parent is the application's main window.<br />
The class will automatically set the busy pointer for the parent,<br />
blocking its input while the infowindow is open.<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
INFOWINDOW_BodyText (CONST_STRPTR)<br />
Text for the body of the information window.<br />
<br />
The following codes can be used within the provided string to change<br />
the soft style of the text:<br />
<br />
ESC u -- underline<br />
ESC b -- bold<br />
ESC i -- italic<br />
ESC n -- normal<br />
<br />
Example string: "The following words \33bare in bold\33n."<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_GET)<br />
<br />
INFOWINDOW_GadgetText (CONST_STRPTR)<br />
Text for the information window's button(s), delimited by the vertical<br />
bar character (|) if you want more than one button (e.g. "Yes|No").<br />
<br />
Defaults to "_OK"<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_GET)<br />
<br />
INFOWINDOW_CheckBoxText (CONST_STRPTR)<br />
If you provide this text string, the class will display a checkbox<br />
gadget at the bottom of the information window. The string will become<br />
the gadget's label.<br />
<br />
One obvious purpose of the checkbox is to allow the user to confirm the<br />
information displayed in the window before closing it and proceeding.<br />
The state of the gadget upon closing the infowindow can be retrieved<br />
via the INFOWINDOW_Checked tag; see below.<br />
<br />
Defaults to NULL (no checkbox will be displayed)<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_GET)<br />
<br />
INFOWINDOW_Checked (BOOL)<br />
Setting this attribute will make the checkbox selected or unselected<br />
when the infowindow next opens. GetAttrs() can be used to retrieve the<br />
state of the gadget upon closing the window.<br />
<br />
Please note that the class stores the checkbox state regardless of<br />
whether the infowindow was OK'ed, cancelled, or timed out. You'll want<br />
to also check the IWM_OPEN method return value to distinguish between<br />
these situations.<br />
<br />
Defaults to FALSE<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_GET)<br />
<br />
INFOWINDOW_Justification (uint16)<br />
Body text justification. Applicable values are LJ_LEFT, LJ_CENTER<br />
or LJ_RIGHT.<br />
<br />
Defaults to LJ_LEFT (left-justified)<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
INFOWINDOW_WrapBorder (uint16)<br />
If the body text does not contain any linefeeds (\n) it will be<br />
word-wrapped automatically after the number of characters specified<br />
in this tag.<br />
<br />
Defaults to 0 (no word-wrap)<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
INFOWINDOW_DefButton (uint32)<br />
Specifies the default, highlighted button. If the Return or Enter key is<br />
pressed, the infowindow will close as if this button has been selected.<br />
A value of 0 means there is no default button, and the Return/Enter<br />
keyboard shortcut will not be available.<br />
<br />
Defaults to 1 (the first button from the left)<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
INFOWINDOW_Image (Object *)<br />
A custom BOOPSI image object to display in the information window. Note<br />
that the image will not be disposed of by the class, you need to take<br />
care of this yourself (the logic here is: "you create the image, you<br />
dispose of it").<br />
<br />
This tag takes precedence over INFOWINDOW_ImageFile (see below).<br />
<br />
If your application supports jumping between different screens, it might<br />
be necessary to rebuild your custom image object for the particular new<br />
host screen, to ensure the image is rendered with proper colours. This<br />
will be the case when jumping between an 8-bit screen and a 16/32-bit<br />
screen, or vice versa.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET, OM_GET)<br />
<br />
INFOWINDOW_ImageFile (CONST_STRPTR)<br />
A name of a source file from which the class will create a BOOPSI image<br />
to display in the information window. The file can be in any picture<br />
format supported by DataTypes. The image object created this way is<br />
stored internally and the class will dispose of it automatically.<br />
<br />
This tag will be ignored if INFOWINDOW_Image is provided (see above).<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
INFOWINDOW_ImagePlace (uint32)<br />
Flags to determine the placement of the image with regard to the body<br />
text. The image can be placed on the left (default), on the right,<br />
above or below the text. When PLACEIMAGE_ABOVE or PLACEIMAGE_BELOW is<br />
set, the image will be center-aligned horizontally unless you also set<br />
PLACEIMAGE_LEFT or PLACEIMAGE_RIGHT (for example, setting this tag to<br />
the combination of PLACEIMAGE_ABOVE|PLACEIMAGE_LEFT will display the<br />
image in the top-left corner above the body text).<br />
<br />
This tag will be ignored if there is no body text.<br />
<br />
Defaults to PLACEIMAGE_LEFT<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
INFOWINDOW_ImageBackFill (struct Hook *)<br />
Sometimes it may be desirable to place the image on a filled background.<br />
This tag allows providing a backfill hook for this purpose.<br />
<br />
Defaults to NULL<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
INFOWINDOW_TabPanel (struct InfoWindowTab *)<br />
Use this tag to configure a special panel for displaying additional<br />
information in the window. This will normally be a tabbed panel with<br />
scrollable text fields but other configurations are also possible.<br />
<br />
The tabbed panel is created by passing an array of struct InfoWindowTab<br />
(see <classes/infowindow.h> for definition). The Label member of each<br />
structure in the array must contain the tab label string. The actual<br />
contents of the Data member may vary depending on the Type member value:<br />
<br />
TABDATA_STRING -- Data contains a text string<br />
TABDATA_FILE -- Data contains a name of a text file<br />
TABDATA_LOCK -- Data contains a DOS lock on a text file<br />
<br />
This means that information to be displayed in the panel can be placed<br />
externally. For example, you can have a dedicated tab for displaying<br />
the program licence, the text of which is in a file on disk (only plain<br />
text files are supported at the moment):<br />
<br />
struct InfoWindowTab tabs[] =<br />
{<br />
{ "Credits", (APTR) "This program was made by me!", TABDATA_STRING },<br />
{ "Licence", (APTR) "PROGDIR:Docs/Licence.txt", TABDATA_FILE },<br />
{ NULL, NULL, TABDATA_END }<br />
};<br />
<br />
Note that the array must be properly terminated as shown.<br />
<br />
If instead of an array you pass a single struct InfoWindowTab with<br />
a NULL Label member, a scrollable text field will be created in the<br />
place of the tabbed panel:<br />
<br />
struct InfoWindowTab textField =<br />
{<br />
NULL,<br />
(APTR) "PROGDIR:Docs/Licence.txt",<br />
TABDATA_FILE<br />
};<br />
<br />
The configuration can be further customized by using the TABDATA_GADGET<br />
value for Type. In such a case the Data member shall point to a BOOPSI<br />
gadget (for example, a listbrowser):<br />
<br />
struct InfoWindowTab customPanel =<br />
{<br />
NULL,<br />
(APTR) myListBrowser,<br />
TABDATA_GADGET<br />
};<br />
<br />
The configuration above will display your own listbrowser gadget<br />
instead of the panel, and this<br />
<br />
struct InfoWindowTab tabs[] =<br />
{<br />
{ "Credits", (APTR) myListBrowser, TABDATA_GADGET },<br />
{ "Licence", (APTR) "PROGDIR:Docs/Licence.txt", TABDATA_FILE },<br />
{ NULL, NULL, TABDATA_END }<br />
};<br />
<br />
will show your listbrowser under the "Credits" tab instead of the<br />
standard text field.<br />
<br />
The tab panel's text fields are currently rendered using the Texteditor<br />
Gadget. This may change in the future.<br />
<br />
Defaults to NULL (no panel)<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
INFOWINDOW_TimeOut (uint32)<br />
The displayed information window will time out and close after the<br />
number of seconds specified via this tag. The IWM_OPEN method will<br />
return with a result of IWMRES_TIMEOUT.<br />
<br />
Defaults to 0 (no timeout)<br />
<br />
Applicability is (OM_NEW, OM_SET)<br />
<br />
NOTES<br />
The timeout feature is currently implemented with IntuiTicks, so the<br />
internal countdown will stop when the infowindow becomes inactive.<br />
This needs to be reimplemented using timer.device.<br />
<br />
BUGS<br />
<br />
<br />
SEE ALSO<br />
<br />
<br />
infowindow.class/IWM_OPEN infowindow.class/IWM_OPEN<br />
<br />
NAME<br />
IWM_OPEN -- Open the information window<br />
<br />
SYNOPSIS<br />
int32 result = IDoMethodA(APTR obj, Msg msg);<br />
int32 result = IDoMethod(APTR obj, IWM_OPEN, NULL);<br />
<br />
FUNCTION<br />
Opens the information window.<br />
<br />
INPUTS<br />
obj - an infowindow object pointer<br />
msg - a Msg with MethodID = IWM_OPEN (see <intuition/classusr.h>)<br />
<br />
RESULT<br />
The number of the button (1, 2, 3...) the user has selected.<br />
IWMRES_ERROR if the information window failed to open for some reason.<br />
IWMRES_CANCEL if the window was closed via the close gadget or Esc key.<br />
IWMRES_TIMEOUT if the window has timed out.<br />
<br />
EXAMPLE<br />
<br />
NOTES<br />
<br />
BUGS<br />
<br />
SEE ALSO<br />
</pre></div>Trixiehttp://wiki.amiga.org/index.php?title=Exchanger&diff=246Exchanger2016-03-13T10:07:46Z<p>Trixie: </p>
<hr />
<div>== Introduction ==<br />
<br />
Exchanger is a program manager for AmigaOS 4. It allows basic external control of running applications and commodities, including:<br />
<br />
* showing or hiding the program GUI;<br />
* shutting the program down;<br />
* displaying the Workbench information requester for the particular program;<br />
* enabling and disabling commodities.<br />
<br />
The name may suggest that Exchanger is a replacement for Commodore's original Exchange tool distributed as part of the Amiga operating system. This is partly true; however, the scope of usability is wider. In addition, Exchanger supports modern AmigaOS features such as jumping between screens, object-oriented menus with images, or program window snapshotting.<br />
<br />
=== Minimum requirements ===<br />
<br />
* AmigaOS 4.1 Update 6 or newer<br />
* Commodities Library version 53.6 or newer<br />
<br />
Exchanger cannot possibly run on earlier systems because of certain Commodities Library features that were not implemented before version 53.6. Program window snapshotting and menu images will only be available when running Exchanger under AmigaOS 4.1 Final Edition or newer.<br />
<br />
The program will use the InfoWindow Class for its About window if the class is installed in the system.<br />
<br />
== Program control in AmigaOS 4.x ==<br />
<br />
As of AmigaOS release 4, there are two types of program that register with the operating system:<br />
<br />
* ''commodities'' (managed via the Commodities Library);<br />
* ''registered applications'' (managed via the Application Library).<br />
<br />
Both types supply the OS with some information about themselves, and provide a certain level of external control. For example, both commodities and registered applications can hide or show their user interface (GUI) in response to a command sent via the respective library. Similarly, a commodity or an application can shut itself down when a corresponding command is received.<br />
<br />
Exchanger aims at becoming a common control point for both program types.<br />
<br />
== User interface ==<br />
<br />
Exchanger features a simple and easy-to-use graphic user interface (GUI) contained within a single program window. The GUI consists of four main parts:<br />
<br />
* the ''program list'', located on the left-hand side of the program window; it lists all programs currently registered in the OS;<br />
* the ''info display'' on the right, which shows information about the program;<br />
* the graphic ''toolbar'', located below the info display;<br />
* the ''menu''.<br />
<br />
Closing the program window via the close gadget will NOT quit Exchanger. Rather, the program will be put to hidden state and run in the background, from which it can be recalled using the CX_POPKEY keyboard shortcut (see below in Configuration).<br />
<br />
=== Program list ===<br />
<br />
The program list displays all applications and commodities currently registered in the system, in alphabetical order. By default Exchanger will not show itself in the list; this can be overridden by settings (see below in Configuration).<br />
<br />
Two or more running instances of the same registered application will show up as separate entries in the program list. The individual instances will be distinguished by their application ID in the info display.<br />
<br />
Programs that are neither commodities, nor they register with the Application Library will not appear in Exchanger's program list. If you think that a particular program would benefit from being controlled by Exchanger, please contact the author of the software in question.<br />
<br />
=== Info display ===<br />
<br />
As commodities and applications register with slightly different information about themselves, the info display is tabbed in order to cater for both program types. The first tab is for applications, the other for commodities. Should a program register as a commodity and, at the same time, as an application (the OS technically allows this, although such implementation is rarely useful), the program name will only be shown once in the program list, and the user can switch between the tabs in the info display to see the respective information.<br />
<br />
=== Toolbar ===<br />
<br />
The toolbar consists of five graphic buttons, from left to right:<br />
<br />
;Show interface<br />
: If the program allows external control of its GUI, this button will send a command telling the respective program to bring up its GUI.<br />
<br />
;Hide interface<br />
: If the program allows external control of its GUI, this button will send a command telling the respective program to hide (commodities) or iconify (applications) its GUI.<br />
<br />
;Enable/Disable<br />
: If the program is a commodity, this button will toggle its activation state. A disabled (inactive) commodity cannot receive input events from the Commodities Network. This button will be unavailable (ghosted) if the program is an application.<br />
<br />
;WB Info<br />
: If Exchanger is able to locate the selected program's icon, this button will display the Workbench information requester for the given program.<br />
<br />
;Shutdown<br />
: Tells the selected program to quit.<br />
<br />
If a button is not available, it usually means that the particular function is not supported by the selected program. For example, commodities that have no GUI will have the Show/Hide interface buttons ghosted.<br />
<br />
If Exchanger cannot find its images at startup, it will use text-only buttons in the toolbar.<br />
<br />
=== Menu ===<br />
<br />
Exchanger features a standard Amiga menu strip, with the following commands:<br />
<br />
==== Project ====<br />
<br />
;About<br />
: Displays the program information window.<br />
<br />
;Hide<br />
: Hides the program GUI completely.<br />
<br />
;Iconify<br />
: Iconifies the program on the Workbench screen.<br />
<br />
;Quit<br />
: Quits Exchanger.<br />
<br />
==== Settings ====<br />
<br />
;Show self in program list?<br />
: Toggles the display of Exchanger in the program list.<br />
<br />
;Show hints?<br />
: Toggles the display of help hints for the toolbar buttons.<br />
<br />
;Save<br />
: Stores current settings as tooltypes in the program icon.<br />
<br />
== Configuration ==<br />
<br />
Exchanger is configured via icon tooltypes or command line parameters, depending on whether the program is started from Workbench or Shell. Some of its features can also be configured during runtime from the Settings menu.<br />
<br />
{| class="wikitable"<br />
!Tooltype<br />
!CLI parameter<br />
!Description<br />
|-<br />
|DONOTWAIT<br />
|N/A<br />
|If you run Exchanger from WBStartup, make sure this tooltype is in place.<br />
|-<br />
|CX_PRIORITY<br />
|CX_PRIORITY<br />
|The priority of Exchanger's commodity broker (default: 0). No need to change this.<br />
|-<br />
|CX_POPUP<br />
|CX_POPUP<br />
|Determines whether Exchanger should display its GUI on program startup (default: YES). If you run Exchanger from WBStartup, you'll probably want to change this to NO (the program will run hidden) and bring up the Exchanger window via the CX_POPKEY shortcut when needed.<br />
|-<br />
|CX_POPKEY<br />
|CX_POPKEY<br />
|The keyboard shortcut to bring Exchanger back from hidden or iconified state (default: ctrl-alt-x).<br />
|-<br />
|SHOWSELF<br />
|SHOWSELF<br />
|Determines whether Exchanger should display itself in the program list (default: NO).<br />
|-<br />
|SHOWHINTS<br />
|SHOWHINTS<br />
|Determines whether Exchanger should display help hints for the toolbar buttons (default: YES).<br />
|-<br />
|GUIIMAGES<br />
|GUIIMAGES<br />
|Specifies the DOS path to the images used by the program (default: PROGDIR:Images).<br />
|}<br />
<br />
== Notes on use ==<br />
<br />
Multiple instances of Exchanger are not allowed. An attempt to start a second instance will bring up the currently running one.<br />
<br />
The way the selected program reacts to the control commands sent by Exchanger absolutely depends on how the respective program is implemented. If a program allows external control (which should normally be the case with both commodities and registered applications), it is the responsibility of the programmer to implement it in a sensible, logical and safe way.<br />
<br />
* If a program does not provide the information it should (for example, no description for it is shown in Exchanger's info display),<br />
* if a program does not react to the interface control buttons (Show/Hide),<br />
* if a commodity cannot be enabled or disabled,<br />
* if a program does not quit (or worse, crashes) upon pressing the Shutdown button,<br />
<br />
please contact the author of the respective program. Exchanger is really just a control board which - on user request - tells other programs what to do.<br />
<br />
== Developers ==<br />
<br />
If you would like to implement or improve external control in your software so that it works better with program managers like Exchanger, please contact A-EON. You will be given all support.</div>Trixiehttp://wiki.amiga.org/index.php?title=Exchanger&diff=245Exchanger2016-03-13T10:05:04Z<p>Trixie: /* Notes on use */</p>
<hr />
<div>== Introduction ==<br />
<br />
Exchanger is a program manager for AmigaOS 4. It allows basic external control of running applications and commodities, including:<br />
<br />
* showing or hiding the program GUI;<br />
* shutting the program down;<br />
* displaying the Workbench information requester for the particular program;<br />
* enabling and disabling commodities.<br />
<br />
The name may suggest that Exchanger is a replacement for Commodore's original Exchange tool distributed as part of the Amiga operating system. This is partly true; however, the scope of usability is wider. In addition, Exchanger supports modern AmigaOS features such as jumping between screens, object-oriented menus with images, or program window snapshotting.<br />
<br />
=== Minimum requirements ===<br />
<br />
* AmigaOS 4.1 Update 6 or newer<br />
* Commodities Library version 53.6 or newer<br />
<br />
Exchanger cannot possibly run on earlier systems because of certain Commodities Library features that were not implemented before version 53.6. Program window snapshotting and menu images will only be available when running Exchanger under AmigaOS 4.1 Final Edition or newer.<br />
<br />
The program will use the InfoWindow Class for its About window if the class is installed in the system.<br />
<br />
== Program control in AmigaOS 4.x ==<br />
<br />
As of AmigaOS release 4, there are two types of program that register with the operating system:<br />
<br />
* ''commodities'' (managed via the Commodities Library);<br />
* ''registered applications'' (managed via the Application Library).<br />
<br />
Both types supply the OS with some information about themselves, and provide a certain level of external control. For example, both commodities and registered applications can hide or show their user interface (GUI) in response to a command sent via the respective library. Similarly, a commodity or an application can shut itself down when a corresponding command is received.<br />
<br />
Exchanger aims at becoming a common control point for both program types.<br />
<br />
== User interface ==<br />
<br />
Exchanger features a simple and easy-to-use graphic user interface (GUI) contained within a single program window. The GUI consists of four main parts:<br />
<br />
* the ''program list'', located on the left-hand side of the program window; it lists all programs currently registered in the OS;<br />
* the ''info display'' on the right, which shows information about the program;<br />
* the graphic ''toolbar'', located below the info display;<br />
* the ''menu''.<br />
<br />
Closing the program window via the close gadget will NOT quit Exchanger. Rather, the program will be put to hidden state and run in the background, from which it can be recalled using the CX_POPKEY keyboard shortcut (see below).<br />
<br />
=== Program list ===<br />
<br />
The program list displays all applications and commodities currently registered in the system, in alphabetical order. By default Exchanger will not show itself in the list; this can be overridden by settings (see below).<br />
<br />
Two or more running instances of the same registered application will show up as separate entries in the program list. The individual instances will be distinguished by their application ID in the info display.<br />
<br />
Programs that are neither commodities, nor they register with the Application Library will not appear in Exchanger's program list. If you think that a particular program would benefit from being controlled by Exchanger, please contact the author of the software in question.<br />
<br />
=== Info display ===<br />
<br />
As commodities and applications register with slightly different information about themselves, the info display is tabbed in order to cater for both program types. The first tab is for applications, the other for commodities. Should a program register as a commodity and, at the same time, as an application (the OS technically allows this, although such implementation is rarely useful), the program name will only be shown once in the program list, and the user can switch between the tabs in the info display to see the respective information.<br />
<br />
=== Toolbar ===<br />
<br />
The toolbar consists of five graphic buttons, from left to right:<br />
<br />
;Show interface<br />
: If the program allows external control of its GUI, this button will send a command telling the respective program to bring up its GUI.<br />
<br />
;Hide interface<br />
: If the program allows external control of its GUI, this button will send a command telling the respective program to hide (commodities) or iconify (applications) its GUI.<br />
<br />
;Enable/Disable<br />
: If the program is a commodity, this button will toggle its activation state. A disabled (inactive) commodity cannot receive input events from the Commodities Network. This button will be unavailable (ghosted) if the program is an application.<br />
<br />
;WB Info<br />
: If Exchanger is able to locate the selected program's icon, this button will display the Workbench information requester for the given program.<br />
<br />
;Shutdown<br />
: Tells the selected program to quit.<br />
<br />
If a button is not available, it usually means that the particular function is not supported by the selected program. For example, commodities that have no GUI will have the Show/Hide interface buttons ghosted.<br />
<br />
If Exchanger cannot find its images at startup, it will use text-only buttons in the toolbar.<br />
<br />
=== Menu ===<br />
<br />
Exchanger features a standard Amiga menu strip, with the following commands:<br />
<br />
==== Project ====<br />
<br />
;About<br />
: Displays the program information window.<br />
<br />
;Hide<br />
: Hides the program GUI completely.<br />
<br />
;Iconify<br />
: Iconifies the program on the Workbench screen.<br />
<br />
;Quit<br />
: Quits Exchanger.<br />
<br />
==== Settings ====<br />
<br />
;Show self in program list?<br />
: Toggles the display of Exchanger in the program list.<br />
<br />
;Show hints?<br />
: Toggles the display of help hints for the toolbar buttons.<br />
<br />
;Save<br />
: Stores current settings as tooltypes in the program icon.<br />
<br />
== Configuration ==<br />
<br />
Exchanger is configured via icon tooltypes or command line parameters, depending on whether the program is started from Workbench or Shell. Some of its features can also be configured during runtime from the Settings menu.<br />
<br />
{| class="wikitable"<br />
!Tooltype<br />
!CLI parameter<br />
!Description<br />
|-<br />
|DONOTWAIT<br />
|N/A<br />
|If you run Exchanger from WBStartup, make sure this tooltype is in place.<br />
|-<br />
|CX_PRIORITY<br />
|CX_PRIORITY<br />
|The priority of Exchanger's commodity broker (default: 0). No need to change this.<br />
|-<br />
|CX_POPUP<br />
|CX_POPUP<br />
|Determines whether Exchanger should display its GUI on program startup (default: YES). If you run Exchanger from WBStartup, you'll probably want to change this to NO (the program will run hidden) and bring up the Exchanger window via the CX_POPKEY shortcut when needed.<br />
|-<br />
|CX_POPKEY<br />
|CX_POPKEY<br />
|The keyboard shortcut to bring Exchanger back from hidden or iconified state (default: ctrl-alt-x).<br />
|-<br />
|SHOWSELF<br />
|SHOWSELF<br />
|Determines whether Exchanger should display itself in the program list (default: NO).<br />
|-<br />
|SHOWHINTS<br />
|SHOWHINTS<br />
|Determines whether Exchanger should display help hints for the toolbar buttons (default: YES).<br />
|-<br />
|GUIIMAGES<br />
|GUIIMAGES<br />
|Specifies the DOS path to the images used by the program (default: PROGDIR:Images).<br />
|}<br />
<br />
== Notes on use ==<br />
<br />
Multiple instances of Exchanger are not allowed. An attempt to start a second instance will bring up the currently running one.<br />
<br />
The way the selected program reacts to the control commands sent by Exchanger absolutely depends on how the respective program is implemented. If a program allows external control (which should normally be the case with both commodities and registered applications), it is the responsibility of the programmer to implement it in a sensible, logical and safe way.<br />
<br />
* If a program does not provide the information it should (for example, no description for it is shown in Exchanger's info display),<br />
* if a program does not react to the interface control buttons (Show/Hide),<br />
* if a commodity cannot be enabled or disabled,<br />
* if a program does not quit (or worse, crashes) upon pressing the Shutdown button,<br />
<br />
please contact the author of the respective program. Exchanger is really just a control board which - on user request - tells other programs what to do.<br />
<br />
== Developers ==<br />
<br />
If you would like to implement or improve external control in your software so that it works better with program managers like Exchanger, please contact A-EON. You will be given all support.</div>Trixiehttp://wiki.amiga.org/index.php?title=Exchanger&diff=244Exchanger2016-03-13T10:02:20Z<p>Trixie: /* User interface */</p>
<hr />
<div>== Introduction ==<br />
<br />
Exchanger is a program manager for AmigaOS 4. It allows basic external control of running applications and commodities, including:<br />
<br />
* showing or hiding the program GUI;<br />
* shutting the program down;<br />
* displaying the Workbench information requester for the particular program;<br />
* enabling and disabling commodities.<br />
<br />
The name may suggest that Exchanger is a replacement for Commodore's original Exchange tool distributed as part of the Amiga operating system. This is partly true; however, the scope of usability is wider. In addition, Exchanger supports modern AmigaOS features such as jumping between screens, object-oriented menus with images, or program window snapshotting.<br />
<br />
=== Minimum requirements ===<br />
<br />
* AmigaOS 4.1 Update 6 or newer<br />
* Commodities Library version 53.6 or newer<br />
<br />
Exchanger cannot possibly run on earlier systems because of certain Commodities Library features that were not implemented before version 53.6. Program window snapshotting and menu images will only be available when running Exchanger under AmigaOS 4.1 Final Edition or newer.<br />
<br />
The program will use the InfoWindow Class for its About window if the class is installed in the system.<br />
<br />
== Program control in AmigaOS 4.x ==<br />
<br />
As of AmigaOS release 4, there are two types of program that register with the operating system:<br />
<br />
* ''commodities'' (managed via the Commodities Library);<br />
* ''registered applications'' (managed via the Application Library).<br />
<br />
Both types supply the OS with some information about themselves, and provide a certain level of external control. For example, both commodities and registered applications can hide or show their user interface (GUI) in response to a command sent via the respective library. Similarly, a commodity or an application can shut itself down when a corresponding command is received.<br />
<br />
Exchanger aims at becoming a common control point for both program types.<br />
<br />
== User interface ==<br />
<br />
Exchanger features a simple and easy-to-use graphic user interface (GUI) contained within a single program window. The GUI consists of four main parts:<br />
<br />
* the ''program list'', located on the left-hand side of the program window; it lists all programs currently registered in the OS;<br />
* the ''info display'' on the right, which shows information about the program;<br />
* the graphic ''toolbar'', located below the info display;<br />
* the ''menu''.<br />
<br />
Closing the program window via the close gadget will NOT quit Exchanger. Rather, the program will be put to hidden state and run in the background, from which it can be recalled using the CX_POPKEY keyboard shortcut (see below).<br />
<br />
=== Program list ===<br />
<br />
The program list displays all applications and commodities currently registered in the system, in alphabetical order. By default Exchanger will not show itself in the list; this can be overridden by settings (see below).<br />
<br />
Two or more running instances of the same registered application will show up as separate entries in the program list. The individual instances will be distinguished by their application ID in the info display.<br />
<br />
Programs that are neither commodities, nor they register with the Application Library will not appear in Exchanger's program list. If you think that a particular program would benefit from being controlled by Exchanger, please contact the author of the software in question.<br />
<br />
=== Info display ===<br />
<br />
As commodities and applications register with slightly different information about themselves, the info display is tabbed in order to cater for both program types. The first tab is for applications, the other for commodities. Should a program register as a commodity and, at the same time, as an application (the OS technically allows this, although such implementation is rarely useful), the program name will only be shown once in the program list, and the user can switch between the tabs in the info display to see the respective information.<br />
<br />
=== Toolbar ===<br />
<br />
The toolbar consists of five graphic buttons, from left to right:<br />
<br />
;Show interface<br />
: If the program allows external control of its GUI, this button will send a command telling the respective program to bring up its GUI.<br />
<br />
;Hide interface<br />
: If the program allows external control of its GUI, this button will send a command telling the respective program to hide (commodities) or iconify (applications) its GUI.<br />
<br />
;Enable/Disable<br />
: If the program is a commodity, this button will toggle its activation state. A disabled (inactive) commodity cannot receive input events from the Commodities Network. This button will be unavailable (ghosted) if the program is an application.<br />
<br />
;WB Info<br />
: If Exchanger is able to locate the selected program's icon, this button will display the Workbench information requester for the given program.<br />
<br />
;Shutdown<br />
: Tells the selected program to quit.<br />
<br />
If a button is not available, it usually means that the particular function is not supported by the selected program. For example, commodities that have no GUI will have the Show/Hide interface buttons ghosted.<br />
<br />
If Exchanger cannot find its images at startup, it will use text-only buttons in the toolbar.<br />
<br />
=== Menu ===<br />
<br />
Exchanger features a standard Amiga menu strip, with the following commands:<br />
<br />
==== Project ====<br />
<br />
;About<br />
: Displays the program information window.<br />
<br />
;Hide<br />
: Hides the program GUI completely.<br />
<br />
;Iconify<br />
: Iconifies the program on the Workbench screen.<br />
<br />
;Quit<br />
: Quits Exchanger.<br />
<br />
==== Settings ====<br />
<br />
;Show self in program list?<br />
: Toggles the display of Exchanger in the program list.<br />
<br />
;Show hints?<br />
: Toggles the display of help hints for the toolbar buttons.<br />
<br />
;Save<br />
: Stores current settings as tooltypes in the program icon.<br />
<br />
== Configuration ==<br />
<br />
Exchanger is configured via icon tooltypes or command line parameters, depending on whether the program is started from Workbench or Shell. Some of its features can also be configured during runtime from the Settings menu.<br />
<br />
{| class="wikitable"<br />
!Tooltype<br />
!CLI parameter<br />
!Description<br />
|-<br />
|DONOTWAIT<br />
|N/A<br />
|If you run Exchanger from WBStartup, make sure this tooltype is in place.<br />
|-<br />
|CX_PRIORITY<br />
|CX_PRIORITY<br />
|The priority of Exchanger's commodity broker (default: 0). No need to change this.<br />
|-<br />
|CX_POPUP<br />
|CX_POPUP<br />
|Determines whether Exchanger should display its GUI on program startup (default: YES). If you run Exchanger from WBStartup, you'll probably want to change this to NO (the program will run hidden) and bring up the Exchanger window via the CX_POPKEY shortcut when needed.<br />
|-<br />
|CX_POPKEY<br />
|CX_POPKEY<br />
|The keyboard shortcut to bring Exchanger back from hidden or iconified state (default: ctrl-alt-x).<br />
|-<br />
|SHOWSELF<br />
|SHOWSELF<br />
|Determines whether Exchanger should display itself in the program list (default: NO).<br />
|-<br />
|SHOWHINTS<br />
|SHOWHINTS<br />
|Determines whether Exchanger should display help hints for the toolbar buttons (default: YES).<br />
|-<br />
|GUIIMAGES<br />
|GUIIMAGES<br />
|Specifies the DOS path to the images used by the program (default: PROGDIR:Images).<br />
|}<br />
<br />
== Notes on use ==<br />
<br />
The way the selected program reacts to the control commands sent by Exchanger absolutely depends on how the respective program is implemented. If a program allows external control (which should normally be the case with both commodities and registered applications), it is the responsibility of the programmer to implement it in a sensible, logical and safe way.<br />
<br />
* If a program does not provide the information it should (for example, no description for it is shown in Exchanger's info display),<br />
* if a program does not react to the interface control buttons (Show/Hide),<br />
* if a commodity cannot be enabled or disabled,<br />
* if a program does not quit (or worse, crashes) upon pressing the Shutdown button,<br />
<br />
please contact the author of the respective program. Exchanger is really just a control board which - on user request - tells other programs what to do.<br />
<br />
== Developers ==<br />
<br />
If you would like to implement or improve external control in your software so that it works better with program managers like Exchanger, please contact A-EON. You will be given all support.</div>Trixiehttp://wiki.amiga.org/index.php?title=Exchanger&diff=243Exchanger2016-03-13T09:39:05Z<p>Trixie: /* Program control in AmigaOS 4.x */</p>
<hr />
<div>== Introduction ==<br />
<br />
Exchanger is a program manager for AmigaOS 4. It allows basic external control of running applications and commodities, including:<br />
<br />
* showing or hiding the program GUI;<br />
* shutting the program down;<br />
* displaying the Workbench information requester for the particular program;<br />
* enabling and disabling commodities.<br />
<br />
The name may suggest that Exchanger is a replacement for Commodore's original Exchange tool distributed as part of the Amiga operating system. This is partly true; however, the scope of usability is wider. In addition, Exchanger supports modern AmigaOS features such as jumping between screens, object-oriented menus with images, or program window snapshotting.<br />
<br />
=== Minimum requirements ===<br />
<br />
* AmigaOS 4.1 Update 6 or newer<br />
* Commodities Library version 53.6 or newer<br />
<br />
Exchanger cannot possibly run on earlier systems because of certain Commodities Library features that were not implemented before version 53.6. Program window snapshotting and menu images will only be available when running Exchanger under AmigaOS 4.1 Final Edition or newer.<br />
<br />
The program will use the InfoWindow Class for its About window if the class is installed in the system.<br />
<br />
== Program control in AmigaOS 4.x ==<br />
<br />
As of AmigaOS release 4, there are two types of program that register with the operating system:<br />
<br />
* ''commodities'' (managed via the Commodities Library);<br />
* ''registered applications'' (managed via the Application Library).<br />
<br />
Both types supply the OS with some information about themselves, and provide a certain level of external control. For example, both commodities and registered applications can hide or show their user interface (GUI) in response to a command sent via the respective library. Similarly, a commodity or an application can shut itself down when a corresponding command is received.<br />
<br />
Exchanger aims at becoming a common control point for both program types.<br />
<br />
== User interface ==<br />
<br />
Exchanger features a simple and easy-to-use graphic user interface (GUI) contained within a single program window. The GUI consists of four main parts:<br />
<br />
* the ''program list'', located on the left-hand side of the program window; it lists all programs currently registered in the OS;<br />
* the ''info display'' on the right, which shows information about the program;<br />
* the graphic ''toolbar'', located below the info display;<br />
* the ''menu''.<br />
<br />
=== Program list ===<br />
<br />
The program list displays all applications and commodities currently registered in the system, in alphabetical order. By default Exchanger will not show itself in the list; this can be overridden by settings (see below).<br />
<br />
Two or more running instances of the same registered application will show up as separate entries in the program list. The individual instances will be distinguished by their application ID in the info display.<br />
<br />
Programs that are neither commodities, nor they register with the Application Library will not appear in Exchanger's program list. If you think that a particular program would benefit from being controlled by Exchanger, please contact the author of the software in question.<br />
<br />
=== Info display ===<br />
<br />
As commodities and applications register with slightly different information about themselves, the info display is tabbed in order to cater for both program types. The first tab is for applications, the other for commodities. Should a program register as a commodity and, at the same time, as an application (the OS technically allows this, although such implementation is rarely useful), the program name will only be shown once in the program list, and the user can switch between the tabs in the info display to see the respective information.<br />
<br />
=== Toolbar ===<br />
<br />
The toolbar consists of five graphic buttons, from left to right:<br />
<br />
;"Show interface"<br />
: If the program allows external control of its GUI, this button will send a command telling the respective program to bring up its GUI.<br />
<br />
;"Hide interface"<br />
: If the program allows external control of its GUI, this button will send a command telling the respective program to hide (commodities) or iconify (applications) its GUI.<br />
<br />
;"Enable/Disable"<br />
: If the program is a commodity, this button will toggle its activation state. A disabled (inactive) commodity cannot receive input events from the Commodities Network. This button will be unavailable (ghosted) if the program is an application.<br />
<br />
;"WB Info"<br />
: If Exchanger is able to locate the selected program's icon, this button will display the Workbench information requester for the given program.<br />
<br />
;"Shutdown"<br />
: Tells the selected program to quit.<br />
<br />
If a button is not available, it usually means that the particular function is not supported by the selected program. For example, commodities that have no GUI will have the Show/Hide interface buttons ghosted.<br />
<br />
== Configuration ==<br />
<br />
Exchanger is configured via icon tooltypes or command line parameters, depending on whether the program is started from Workbench or Shell. Some of its features can also be configured during runtime from the Settings menu.<br />
<br />
{| class="wikitable"<br />
!Tooltype<br />
!CLI parameter<br />
!Description<br />
|-<br />
|DONOTWAIT<br />
|N/A<br />
|If you run Exchanger from WBStartup, make sure this tooltype is in place.<br />
|-<br />
|CX_PRIORITY<br />
|CX_PRIORITY<br />
|The priority of Exchanger's commodity broker (default: 0). No need to change this.<br />
|-<br />
|CX_POPUP<br />
|CX_POPUP<br />
|Determines whether Exchanger should display its GUI on program startup (default: YES). If you run Exchanger from WBStartup, you'll probably want to change this to NO (the program will run hidden) and bring up the Exchanger window via the CX_POPKEY shortcut when needed.<br />
|-<br />
|CX_POPKEY<br />
|CX_POPKEY<br />
|The keyboard shortcut to bring Exchanger back from hidden or iconified state (default: ctrl-alt-x).<br />
|-<br />
|SHOWSELF<br />
|SHOWSELF<br />
|Determines whether Exchanger should display itself in the program list (default: NO).<br />
|-<br />
|SHOWHINTS<br />
|SHOWHINTS<br />
|Determines whether Exchanger should display help hints for the toolbar buttons (default: YES).<br />
|-<br />
|GUIIMAGES<br />
|GUIIMAGES<br />
|Specifies the DOS path to the images used by the program (default: PROGDIR:Images).<br />
|}<br />
<br />
== Notes on use ==<br />
<br />
The way the selected program reacts to the control commands sent by Exchanger absolutely depends on how the respective program is implemented. If a program allows external control (which should normally be the case with both commodities and registered applications), it is the responsibility of the programmer to implement it in a sensible, logical and safe way.<br />
<br />
* If a program does not provide the information it should (for example, no description for it is shown in Exchanger's info display),<br />
* if a program does not react to the interface control buttons (Show/Hide),<br />
* if a commodity cannot be enabled or disabled,<br />
* if a program does not quit (or worse, crashes) upon pressing the Shutdown button,<br />
<br />
please contact the author of the respective program. Exchanger is really just a control board which - on user request - tells other programs what to do.<br />
<br />
== Developers ==<br />
<br />
If you would like to implement or improve external control in your software so that it works better with program managers like Exchanger, please contact A-EON. You will be given all support.</div>Trixiehttp://wiki.amiga.org/index.php?title=Exchanger&diff=242Exchanger2016-03-13T09:35:39Z<p>Trixie: /* User interface */</p>
<hr />
<div>== Introduction ==<br />
<br />
Exchanger is a program manager for AmigaOS 4. It allows basic external control of running applications and commodities, including:<br />
<br />
* showing or hiding the program GUI;<br />
* shutting the program down;<br />
* displaying the Workbench information requester for the particular program;<br />
* enabling and disabling commodities.<br />
<br />
The name may suggest that Exchanger is a replacement for Commodore's original Exchange tool distributed as part of the Amiga operating system. This is partly true; however, the scope of usability is wider. In addition, Exchanger supports modern AmigaOS features such as jumping between screens, object-oriented menus with images, or program window snapshotting.<br />
<br />
=== Minimum requirements ===<br />
<br />
* AmigaOS 4.1 Update 6 or newer<br />
* Commodities Library version 53.6 or newer<br />
<br />
Exchanger cannot possibly run on earlier systems because of certain Commodities Library features that were not implemented before version 53.6. Program window snapshotting and menu images will only be available when running Exchanger under AmigaOS 4.1 Final Edition or newer.<br />
<br />
The program will use the InfoWindow Class for its About window if the class is installed in the system.<br />
<br />
== Program control in AmigaOS 4.x ==<br />
<br />
As of AmigaOS release 4, there are two types of program that register with the operating system:<br />
<br />
* ''commodities'' (auxiliary programs and services, managed via the Commodities Library);<br />
* ''registered applications'' (full-fledged programs, managed via the Application Library).<br />
<br />
Both types supply the OS with some information about themselves, and provide a certain level of external control. For example, both commodities and registered applications can hide or show their user interface (GUI) in response to a command sent via the respective library. Similarly, a commodity or an application can shut itself down when a corresponding command is received.<br />
<br />
Exchanger aims at becoming a common control point for both program types.<br />
<br />
== User interface ==<br />
<br />
Exchanger features a simple and easy-to-use graphic user interface (GUI) contained within a single program window. The GUI consists of four main parts:<br />
<br />
* the ''program list'', located on the left-hand side of the program window; it lists all programs currently registered in the OS;<br />
* the ''info display'' on the right, which shows information about the program;<br />
* the graphic ''toolbar'', located below the info display;<br />
* the ''menu''.<br />
<br />
=== Program list ===<br />
<br />
The program list displays all applications and commodities currently registered in the system, in alphabetical order. By default Exchanger will not show itself in the list; this can be overridden by settings (see below).<br />
<br />
Two or more running instances of the same registered application will show up as separate entries in the program list. The individual instances will be distinguished by their application ID in the info display.<br />
<br />
Programs that are neither commodities, nor they register with the Application Library will not appear in Exchanger's program list. If you think that a particular program would benefit from being controlled by Exchanger, please contact the author of the software in question.<br />
<br />
=== Info display ===<br />
<br />
As commodities and applications register with slightly different information about themselves, the info display is tabbed in order to cater for both program types. The first tab is for applications, the other for commodities. Should a program register as a commodity and, at the same time, as an application (the OS technically allows this, although such implementation is rarely useful), the program name will only be shown once in the program list, and the user can switch between the tabs in the info display to see the respective information.<br />
<br />
=== Toolbar ===<br />
<br />
The toolbar consists of five graphic buttons, from left to right:<br />
<br />
;"Show interface"<br />
: If the program allows external control of its GUI, this button will send a command telling the respective program to bring up its GUI.<br />
<br />
;"Hide interface"<br />
: If the program allows external control of its GUI, this button will send a command telling the respective program to hide (commodities) or iconify (applications) its GUI.<br />
<br />
;"Enable/Disable"<br />
: If the program is a commodity, this button will toggle its activation state. A disabled (inactive) commodity cannot receive input events from the Commodities Network. This button will be unavailable (ghosted) if the program is an application.<br />
<br />
;"WB Info"<br />
: If Exchanger is able to locate the selected program's icon, this button will display the Workbench information requester for the given program.<br />
<br />
;"Shutdown"<br />
: Tells the selected program to quit.<br />
<br />
If a button is not available, it usually means that the particular function is not supported by the selected program. For example, commodities that have no GUI will have the Show/Hide interface buttons ghosted.<br />
<br />
== Configuration ==<br />
<br />
Exchanger is configured via icon tooltypes or command line parameters, depending on whether the program is started from Workbench or Shell. Some of its features can also be configured during runtime from the Settings menu.<br />
<br />
{| class="wikitable"<br />
!Tooltype<br />
!CLI parameter<br />
!Description<br />
|-<br />
|DONOTWAIT<br />
|N/A<br />
|If you run Exchanger from WBStartup, make sure this tooltype is in place.<br />
|-<br />
|CX_PRIORITY<br />
|CX_PRIORITY<br />
|The priority of Exchanger's commodity broker (default: 0). No need to change this.<br />
|-<br />
|CX_POPUP<br />
|CX_POPUP<br />
|Determines whether Exchanger should display its GUI on program startup (default: YES). If you run Exchanger from WBStartup, you'll probably want to change this to NO (the program will run hidden) and bring up the Exchanger window via the CX_POPKEY shortcut when needed.<br />
|-<br />
|CX_POPKEY<br />
|CX_POPKEY<br />
|The keyboard shortcut to bring Exchanger back from hidden or iconified state (default: ctrl-alt-x).<br />
|-<br />
|SHOWSELF<br />
|SHOWSELF<br />
|Determines whether Exchanger should display itself in the program list (default: NO).<br />
|-<br />
|SHOWHINTS<br />
|SHOWHINTS<br />
|Determines whether Exchanger should display help hints for the toolbar buttons (default: YES).<br />
|-<br />
|GUIIMAGES<br />
|GUIIMAGES<br />
|Specifies the DOS path to the images used by the program (default: PROGDIR:Images).<br />
|}<br />
<br />
== Notes on use ==<br />
<br />
The way the selected program reacts to the control commands sent by Exchanger absolutely depends on how the respective program is implemented. If a program allows external control (which should normally be the case with both commodities and registered applications), it is the responsibility of the programmer to implement it in a sensible, logical and safe way.<br />
<br />
* If a program does not provide the information it should (for example, no description for it is shown in Exchanger's info display),<br />
* if a program does not react to the interface control buttons (Show/Hide),<br />
* if a commodity cannot be enabled or disabled,<br />
* if a program does not quit (or worse, crashes) upon pressing the Shutdown button,<br />
<br />
please contact the author of the respective program. Exchanger is really just a control board which - on user request - tells other programs what to do.<br />
<br />
== Developers ==<br />
<br />
If you would like to implement or improve external control in your software so that it works better with program managers like Exchanger, please contact A-EON. You will be given all support.</div>Trixiehttp://wiki.amiga.org/index.php?title=Exchanger&diff=241Exchanger2016-03-13T09:29:16Z<p>Trixie: /* Usability note */</p>
<hr />
<div>== Introduction ==<br />
<br />
Exchanger is a program manager for AmigaOS 4. It allows basic external control of running applications and commodities, including:<br />
<br />
* showing or hiding the program GUI;<br />
* shutting the program down;<br />
* displaying the Workbench information requester for the particular program;<br />
* enabling and disabling commodities.<br />
<br />
The name may suggest that Exchanger is a replacement for Commodore's original Exchange tool distributed as part of the Amiga operating system. This is partly true; however, the scope of usability is wider. In addition, Exchanger supports modern AmigaOS features such as jumping between screens, object-oriented menus with images, or program window snapshotting.<br />
<br />
=== Minimum requirements ===<br />
<br />
* AmigaOS 4.1 Update 6 or newer<br />
* Commodities Library version 53.6 or newer<br />
<br />
Exchanger cannot possibly run on earlier systems because of certain Commodities Library features that were not implemented before version 53.6. Program window snapshotting and menu images will only be available when running Exchanger under AmigaOS 4.1 Final Edition or newer.<br />
<br />
The program will use the InfoWindow Class for its About window if the class is installed in the system.<br />
<br />
== Program control in AmigaOS 4.x ==<br />
<br />
As of AmigaOS release 4, there are two types of program that register with the operating system:<br />
<br />
* ''commodities'' (auxiliary programs and services, managed via the Commodities Library);<br />
* ''registered applications'' (full-fledged programs, managed via the Application Library).<br />
<br />
Both types supply the OS with some information about themselves, and provide a certain level of external control. For example, both commodities and registered applications can hide or show their user interface (GUI) in response to a command sent via the respective library. Similarly, a commodity or an application can shut itself down when a corresponding command is received.<br />
<br />
Exchanger aims at becoming a common control point for both program types.<br />
<br />
== User interface ==<br />
<br />
Exchanger features a simple and easy-to-use graphic user interface (GUI) contained within a single program window. The GUI consists of four main parts:<br />
<br />
* the ''program list'', located on the left-hand side of the program window; it lists all programs currently registered in the OS;<br />
* the ''info display'' on the right, which shows information about the program;<br />
* the graphic ''toolbar'', located below the info display;<br />
* the ''menu''.<br />
<br />
=== Info display ===<br />
<br />
As commodities and applications register with slightly different information about themselves, the info display is tabbed in order to cater for both program types. The first tab is for applications, the other for commodities. Should a program register as a commodity and, at the same time, as an application (the OS technically allows this, although such implementation is rarely useful), the program name will only be shown once in the program list, and the user can switch between the tabs in the info display to see the respective information.<br />
<br />
=== Toolbar ===<br />
<br />
The toolbar consists of five graphic buttons, from left to right:<br />
<br />
;"Show interface"<br />
: If the program allows external control of its GUI, this button will send a command telling the respective program to bring up its GUI.<br />
<br />
;"Hide interface"<br />
: If the program allows external control of its GUI, this button will send a command telling the respective program to hide (commodities) or iconify (applications) its GUI.<br />
<br />
;"Enable/Disable"<br />
: If the program is a commodity, this button will toggle its activation state. A disabled (inactive) commodity cannot receive input events from the Commodities Network. This button will be unavailable (ghosted) if the program is an application.<br />
<br />
;"WB Info"<br />
: If Exchanger is able to locate the selected program's icon, this button will display the Workbench information requester for the given program.<br />
<br />
;"Shutdown"<br />
: Tells the selected program to quit.<br />
<br />
If a button is not available, it usually means that the particular function is not supported by the selected program. For example, commodities that have no GUI will have the Show/Hide interface buttons ghosted.<br />
<br />
== Configuration ==<br />
<br />
Exchanger is configured via icon tooltypes or command line parameters, depending on whether the program is started from Workbench or Shell. Some of its features can also be configured during runtime from the Settings menu.<br />
<br />
{| class="wikitable"<br />
!Tooltype<br />
!CLI parameter<br />
!Description<br />
|-<br />
|DONOTWAIT<br />
|N/A<br />
|If you run Exchanger from WBStartup, make sure this tooltype is in place.<br />
|-<br />
|CX_PRIORITY<br />
|CX_PRIORITY<br />
|The priority of Exchanger's commodity broker (default: 0). No need to change this.<br />
|-<br />
|CX_POPUP<br />
|CX_POPUP<br />
|Determines whether Exchanger should display its GUI on program startup (default: YES). If you run Exchanger from WBStartup, you'll probably want to change this to NO (the program will run hidden) and bring up the Exchanger window via the CX_POPKEY shortcut when needed.<br />
|-<br />
|CX_POPKEY<br />
|CX_POPKEY<br />
|The keyboard shortcut to bring Exchanger back from hidden or iconified state (default: ctrl-alt-x).<br />
|-<br />
|SHOWSELF<br />
|SHOWSELF<br />
|Determines whether Exchanger should display itself in the program list (default: NO).<br />
|-<br />
|SHOWHINTS<br />
|SHOWHINTS<br />
|Determines whether Exchanger should display help hints for the toolbar buttons (default: YES).<br />
|-<br />
|GUIIMAGES<br />
|GUIIMAGES<br />
|Specifies the DOS path to the images used by the program (default: PROGDIR:Images).<br />
|}<br />
<br />
== Notes on use ==<br />
<br />
The way the selected program reacts to the control commands sent by Exchanger absolutely depends on how the respective program is implemented. If a program allows external control (which should normally be the case with both commodities and registered applications), it is the responsibility of the programmer to implement it in a sensible, logical and safe way.<br />
<br />
* If a program does not provide the information it should (for example, no description for it is shown in Exchanger's info display),<br />
* if a program does not react to the interface control buttons (Show/Hide),<br />
* if a commodity cannot be enabled or disabled,<br />
* if a program does not quit (or worse, crashes) upon pressing the Shutdown button,<br />
<br />
please contact the author of the respective program. Exchanger is really just a control board which - on user request - tells other programs what to do.<br />
<br />
== Developers ==<br />
<br />
If you would like to implement or improve external control in your software so that it works better with program managers like Exchanger, please contact A-EON. You will be given all support.</div>Trixiehttp://wiki.amiga.org/index.php?title=Exchanger&diff=240Exchanger2016-03-13T09:09:22Z<p>Trixie: /* Configuration */</p>
<hr />
<div>== Introduction ==<br />
<br />
Exchanger is a program manager for AmigaOS 4. It allows basic external control of running applications and commodities, including:<br />
<br />
* showing or hiding the program GUI;<br />
* shutting the program down;<br />
* displaying the Workbench information requester for the particular program;<br />
* enabling and disabling commodities.<br />
<br />
The name may suggest that Exchanger is a replacement for Commodore's original Exchange tool distributed as part of the Amiga operating system. This is partly true; however, the scope of usability is wider. In addition, Exchanger supports modern AmigaOS features such as jumping between screens, object-oriented menus with images, or program window snapshotting.<br />
<br />
=== Minimum requirements ===<br />
<br />
* AmigaOS 4.1 Update 6 or newer<br />
* Commodities Library version 53.6 or newer<br />
<br />
Exchanger cannot possibly run on earlier systems because of certain Commodities Library features that were not implemented before version 53.6. Program window snapshotting and menu images will only be available when running Exchanger under AmigaOS 4.1 Final Edition or newer.<br />
<br />
The program will use the InfoWindow Class for its About window if the class is installed in the system.<br />
<br />
== Program control in AmigaOS 4.x ==<br />
<br />
As of AmigaOS release 4, there are two types of program that register with the operating system:<br />
<br />
* ''commodities'' (auxiliary programs and services, managed via the Commodities Library);<br />
* ''registered applications'' (full-fledged programs, managed via the Application Library).<br />
<br />
Both types supply the OS with some information about themselves, and provide a certain level of external control. For example, both commodities and registered applications can hide or show their user interface (GUI) in response to a command sent via the respective library. Similarly, a commodity or an application can shut itself down when a corresponding command is received.<br />
<br />
Exchanger aims at becoming a common control point for both program types.<br />
<br />
== User interface ==<br />
<br />
Exchanger features a simple and easy-to-use graphic user interface (GUI) contained within a single program window. The GUI consists of four main parts:<br />
<br />
* the ''program list'', located on the left-hand side of the program window; it lists all programs currently registered in the OS;<br />
* the ''info display'' on the right, which shows information about the program;<br />
* the graphic ''toolbar'', located below the info display;<br />
* the ''menu''.<br />
<br />
=== Info display ===<br />
<br />
As commodities and applications register with slightly different information about themselves, the info display is tabbed in order to cater for both program types. The first tab is for applications, the other for commodities. Should a program register as a commodity and, at the same time, as an application (the OS technically allows this, although such implementation is rarely useful), the program name will only be shown once in the program list, and the user can switch between the tabs in the info display to see the respective information.<br />
<br />
=== Toolbar ===<br />
<br />
The toolbar consists of five graphic buttons, from left to right:<br />
<br />
;"Show interface"<br />
: If the program allows external control of its GUI, this button will send a command telling the respective program to bring up its GUI.<br />
<br />
;"Hide interface"<br />
: If the program allows external control of its GUI, this button will send a command telling the respective program to hide (commodities) or iconify (applications) its GUI.<br />
<br />
;"Enable/Disable"<br />
: If the program is a commodity, this button will toggle its activation state. A disabled (inactive) commodity cannot receive input events from the Commodities Network. This button will be unavailable (ghosted) if the program is an application.<br />
<br />
;"WB Info"<br />
: If Exchanger is able to locate the selected program's icon, this button will display the Workbench information requester for the given program.<br />
<br />
;"Shutdown"<br />
: Tells the selected program to quit.<br />
<br />
If a button is not available, it usually means that the particular function is not supported by the selected program. For example, commodities that have no GUI will have the Show/Hide interface buttons ghosted.<br />
<br />
== Configuration ==<br />
<br />
Exchanger is configured via icon tooltypes or command line parameters, depending on whether the program is started from Workbench or Shell. Some of its features can also be configured during runtime from the Settings menu.<br />
<br />
{| class="wikitable"<br />
!Tooltype<br />
!CLI parameter<br />
!Description<br />
|-<br />
|DONOTWAIT<br />
|N/A<br />
|If you run Exchanger from WBStartup, make sure this tooltype is in place.<br />
|-<br />
|CX_PRIORITY<br />
|CX_PRIORITY<br />
|The priority of Exchanger's commodity broker (default: 0). No need to change this.<br />
|-<br />
|CX_POPUP<br />
|CX_POPUP<br />
|Determines whether Exchanger should display its GUI on program startup (default: YES). If you run Exchanger from WBStartup, you'll probably want to change this to NO (the program will run hidden) and bring up the Exchanger window via the CX_POPKEY shortcut when needed.<br />
|-<br />
|CX_POPKEY<br />
|CX_POPKEY<br />
|The keyboard shortcut to bring Exchanger back from hidden or iconified state (default: ctrl-alt-x).<br />
|-<br />
|SHOWSELF<br />
|SHOWSELF<br />
|Determines whether Exchanger should display itself in the program list (default: NO).<br />
|-<br />
|SHOWHINTS<br />
|SHOWHINTS<br />
|Determines whether Exchanger should display help hints for the toolbar buttons (default: YES).<br />
|-<br />
|GUIIMAGES<br />
|GUIIMAGES<br />
|Specifies the DOS path to the images used by the program (default: PROGDIR:Images).<br />
|}<br />
<br />
== Usability note ==<br />
<br />
The way the program reacts to the control commands sent by Exchanger absolutely depends on how the respective program is implemented. If a program allows external control (which should normally be the case with both commodities and registered applications), it is the responsibility of the programmer to implement it in a sensible, logical and safe way.<br />
<br />
* If a program does not provide the information it should (for example, no description for it is shown in Exchanger's info display),<br />
* if a program does not react to the interface control buttons (Show/Hide),<br />
* if a commodity cannot be enabled or disabled,<br />
* if a program does not quit (or worse, crashes) upon pressing the Shutdown button,<br />
<br />
please contact the author of the respective program. Exchanger is really just a control board that - on user request - tells other programs what to do.</div>Trixiehttp://wiki.amiga.org/index.php?title=Exchanger&diff=239Exchanger2016-03-12T22:47:50Z<p>Trixie: Created page with "== Introduction == Exchanger is a program manager for AmigaOS 4. It allows basic external control of running applications and commodities, including: * showing or hiding the..."</p>
<hr />
<div>== Introduction ==<br />
<br />
Exchanger is a program manager for AmigaOS 4. It allows basic external control of running applications and commodities, including:<br />
<br />
* showing or hiding the program GUI;<br />
* shutting the program down;<br />
* displaying the Workbench information requester for the particular program;<br />
* enabling and disabling commodities.<br />
<br />
The name may suggest that Exchanger is a replacement for Commodore's original Exchange tool distributed as part of the Amiga operating system. This is partly true; however, the scope of usability is wider. In addition, Exchanger supports modern AmigaOS features such as jumping between screens, object-oriented menus with images, or program window snapshotting.<br />
<br />
=== Minimum requirements ===<br />
<br />
* AmigaOS 4.1 Update 6 or newer<br />
* Commodities Library version 53.6 or newer<br />
<br />
Exchanger cannot possibly run on earlier systems because of certain Commodities Library features that were not implemented before version 53.6. Program window snapshotting and menu images will only be available when running Exchanger under AmigaOS 4.1 Final Edition or newer.<br />
<br />
The program will use the InfoWindow Class for its About window if the class is installed in the system.<br />
<br />
== Program control in AmigaOS 4.x ==<br />
<br />
As of AmigaOS release 4, there are two types of program that register with the operating system:<br />
<br />
* ''commodities'' (auxiliary programs and services, managed via the Commodities Library);<br />
* ''registered applications'' (full-fledged programs, managed via the Application Library).<br />
<br />
Both types supply the OS with some information about themselves, and provide a certain level of external control. For example, both commodities and registered applications can hide or show their user interface (GUI) in response to a command sent via the respective library. Similarly, a commodity or an application can shut itself down when a corresponding command is received.<br />
<br />
Exchanger aims at becoming a common control point for both program types.<br />
<br />
== User interface ==<br />
<br />
Exchanger features a simple and easy-to-use graphic user interface (GUI) contained within a single program window. The GUI consists of four main parts:<br />
<br />
* the ''program list'', located on the left-hand side of the program window; it lists all programs currently registered in the OS;<br />
* the ''info display'' on the right, which shows information about the program;<br />
* the graphic ''toolbar'', located below the info display;<br />
* the ''menu''.<br />
<br />
=== Info display ===<br />
<br />
As commodities and applications register with slightly different information about themselves, the info display is tabbed in order to cater for both program types. The first tab is for applications, the other for commodities. Should a program register as a commodity and, at the same time, as an application (the OS technically allows this, although such implementation is rarely useful), the program name will only be shown once in the program list, and the user can switch between the tabs in the info display to see the respective information.<br />
<br />
=== Toolbar ===<br />
<br />
The toolbar consists of five graphic buttons, from left to right:<br />
<br />
;"Show interface"<br />
: If the program allows external control of its GUI, this button will send a command telling the respective program to bring up its GUI.<br />
<br />
;"Hide interface"<br />
: If the program allows external control of its GUI, this button will send a command telling the respective program to hide (commodities) or iconify (applications) its GUI.<br />
<br />
;"Enable/Disable"<br />
: If the program is a commodity, this button will toggle its activation state. A disabled (inactive) commodity cannot receive input events from the Commodities Network. This button will be unavailable (ghosted) if the program is an application.<br />
<br />
;"WB Info"<br />
: If Exchanger is able to locate the selected program's icon, this button will display the Workbench information requester for the given program.<br />
<br />
;"Shutdown"<br />
: Tells the selected program to quit.<br />
<br />
If a button is not available, it usually means that the particular function is not supported by the selected program. For example, commodities that have no GUI will have the Show/Hide interface buttons ghosted.<br />
<br />
== Configuration ==<br />
<br />
Exchanger is configured via icon tooltypes or command line (CLI) parameters. Some of its features can also be configured from the Settings menu.<br />
<br />
=== Tooltypes ===<br />
<br />
;DONOTWAIT<br />
: If you run Exchanger from WBStartup, make sure this tooltype is in place.<br />
<br />
;CX_PRIORITY<br />
: The priority of Exchanger's commodity broker (default: 0). No need to change this.<br />
<br />
;CX_POPUP<br />
: Determines whether Exchanger should display its GUI on program startup (default: YES). If you run Exchanger from WBStartup, you'll probably want to change this to NO (the program will run hidden) and bring up the Exchanger window via the CX_POPKEY shortcut when needed.<br />
<br />
;CX_POPKEY<br />
: The keyboard shortcut to bring Exchanger back from hidden or iconified state (default: ctrl-alt-x).<br />
<br />
;SHOWSELF<br />
: Determines whether Exchanger should display itself in the program list (default: NO).<br />
<br />
;SHOWHINTS<br />
: Determines whether Exchanger should display help hints for the toolbar buttons (default: YES).<br />
<br />
;GUIIMAGES<br />
: Specifies the DOS path to the images used by the program (default: PROGDIR:Images).<br />
<br />
=== CLI parameters ===<br />
<br />
CX_PRIORITY<br />
<br />
CX_POPUP<br />
<br />
CX_POPKEY<br />
<br />
SHOWSELF<br />
<br />
SHOWHINTS<br />
<br />
See above in Tooltypes.<br />
<br />
== Usability note ==<br />
<br />
The way the program reacts to the control commands sent by Exchanger absolutely depends on how the respective program is implemented. If a program allows external control (which should normally be the case with both commodities and registered applications), it is the responsibility of the programmer to implement it in a sensible, logical and safe way.<br />
<br />
* If a program does not provide the information it should (for example, no description for it is shown in Exchanger's info display),<br />
* if a program does not react to the interface control buttons (Show/Hide),<br />
* if a commodity cannot be enabled or disabled,<br />
* if a program does not quit (or worse, crashes) upon pressing the Shutdown button,<br />
<br />
please contact the author of the respective program. Exchanger is really just a control board that - on user request - tells other programs what to do.</div>Trixiehttp://wiki.amiga.org/index.php?title=Main_Page&diff=238Main Page2016-03-12T21:35:02Z<p>Trixie: /* Software */</p>
<hr />
<div>== Welcome ==<br />
<br />
Welcome to wiki.amiga.org<br />
<br />
This is a documentation and information repository for all A-EON Technology and selected partner projects relating to the original Amiga and AmigaONE computer systems.<br />
<br />
<br />
== Hardware ==<br />
<br />
Next Generation Hardware:<br />
<br />
* [[AmigaONE 500]]<br />
* AmigaONE X1000<br />
* [[AmigaONE X5000]]<br />
<br />
Classic Hardware:<br />
<br />
* Amiga 500<br />
* Amiga 500+<br />
* Amiga 600<br />
* Amiga 1000<br />
* Amiga 1200<br />
* Amiga 1500<br />
* Amiga 2000<br />
* Amiga 2500<br />
* Amiga 3000<br />
* Amiga 3000UX<br />
* Amiga 3500<br />
* Amiga 4000<br />
* Amiga 4000T<br />
* Amiga CDTV<br />
* Amiga CD32<br />
<br />
== Software ==<br />
<br />
* [[AMIStore]]<br />
* [[CANDI]]<br />
* [[Exchanger]]<br />
* [[InfoWindow Class]]<br />
* [[MultiEdit]]<br />
* [[Multiviewer]]<br />
* [[RadeonHD Driver]]<br />
* [[Ringhio Notifications]]<br />
* [[SmartFileSystem]]<br />
* [[TuneNet]]<br />
* [[Warp3D]]<br />
* [[X-Dock]]<br />
<br />
== Copyright Notice ==<br />
All content submitted to and contained on this website, unless explicitly stated is Copyright &copy; 2015-2016 A-EON Technology Ltd. All rights reserved. You shall not copy, reproduce, distribute, transmit, broadcast, display, sell, license, or otherwise exploit any content for any other purposes without the prior written consent of A-EON Technology Ltd or the respective licensors of the content.</div>Trixiehttp://wiki.amiga.org/index.php?title=InformationWindow_Class&diff=237InformationWindow Class2016-03-12T21:34:32Z<p>Trixie: Trixie moved page InformationWindow Class to InfoWindow Class</p>
<hr />
<div>#REDIRECT [[InfoWindow Class]]</div>Trixiehttp://wiki.amiga.org/index.php?title=InfoWindow_Class&diff=236InfoWindow Class2016-03-12T21:34:32Z<p>Trixie: Trixie moved page InformationWindow Class to InfoWindow Class</p>
<hr />
<div>==Introduction==<br />
<br />
This guide describes the ReAction compatible '''InformationWindow.class''' for users and developers.<br />
<br />
==Overview==<br />
<br />
==Features==<br />
<br />
<br />
<br />
==For Users==<br />
<br />
<br />
<br />
==For Developers==</div>Trixiehttp://wiki.amiga.org/index.php?title=Main_Page&diff=235Main Page2016-03-12T21:32:16Z<p>Trixie: /* Software */</p>
<hr />
<div>== Welcome ==<br />
<br />
Welcome to wiki.amiga.org<br />
<br />
This is a documentation and information repository for all A-EON Technology and selected partner projects relating to the original Amiga and AmigaONE computer systems.<br />
<br />
<br />
== Hardware ==<br />
<br />
Next Generation Hardware:<br />
<br />
* [[AmigaONE 500]]<br />
* AmigaONE X1000<br />
* [[AmigaONE X5000]]<br />
<br />
Classic Hardware:<br />
<br />
* Amiga 500<br />
* Amiga 500+<br />
* Amiga 600<br />
* Amiga 1000<br />
* Amiga 1200<br />
* Amiga 1500<br />
* Amiga 2000<br />
* Amiga 2500<br />
* Amiga 3000<br />
* Amiga 3000UX<br />
* Amiga 3500<br />
* Amiga 4000<br />
* Amiga 4000T<br />
* Amiga CDTV<br />
* Amiga CD32<br />
<br />
== Software ==<br />
<br />
* [[AMIStore]]<br />
* [[CANDI]]<br />
* [[Exchanger]]<br />
* [[InformationWindow Class]]<br />
* [[MultiEdit]]<br />
* [[Multiviewer]]<br />
* [[RadeonHD Driver]]<br />
* [[Ringhio Notifications]]<br />
* [[SmartFileSystem]]<br />
* [[TuneNet]]<br />
* [[Warp3D]]<br />
* [[X-Dock]]<br />
<br />
== Copyright Notice ==<br />
All content submitted to and contained on this website, unless explicitly stated is Copyright &copy; 2015-2016 A-EON Technology Ltd. All rights reserved. You shall not copy, reproduce, distribute, transmit, broadcast, display, sell, license, or otherwise exploit any content for any other purposes without the prior written consent of A-EON Technology Ltd or the respective licensors of the content.</div>Trixie