ToolBar Gadget Class
Jump to navigation
Jump to search
Toolbar Gadget Class
NAME
toolbar.gadget -- Create toolbar BOOPSI objects
SUPERCLASS
gadgetclass
REQUIRES
button.gadget, select.gadget, label.image, bevel.image, shared.image
DESCRIPTION
This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.
METHODS
OM_NEW -- creates the toolbar object, sets attributes and defaults
OM_DISPOSE -- disposes of the toolbar object
OM_REMMEMBER -- used by the class internally; consider this method private
OM_SET -- sets toolbar, member and image attributes (see the OM_SET
section below for more information)
OM_GET -- retrieves toolbar attributes
TBM_GETMEMBER -- retrieves a given member attribute (see the TBM_GETMEMBER
section below for more information)
ATTRIBUTES
GA_ID (uint16)
Unique ID number for the gadget.
Defaults to 0
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
GA_ReadOnly (BOOL)
If set to TRUE, none of the toolbar buttons will be selectable.
Defaults to FALSE
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
GA_BackFill (struct Hook *)
A backfill hook to provide a background filled with a specific colour
or pattern. Please also see notes for TOOLBAR_BackFill below.
Defaults to NULL (the default backfill hook).
Applicability is (OM_NEW, OM_SET, OM_UPDATE)
GA_TextAttr (struct TextAttr *)
Pointer to a TextAttr structure describing the font to be used for
the gadget's button text labels (if they are used).
Defaults to the system's default public screen font.
Applicability is (OM_NEW, OM_SET, OM_UPDATE)
TOOLBAR_Orientation (uint32)
The toolbar orientation: horizontal or vertical.
Defaults to TB_ORIENT_HORIZ
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
TOOLBAR_Spacing (uint32)
The spacing between the individual toolbar members, in pixels.
Defaults to 2
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
TOOLBAR_HorizPadding
TOOLBAR_VertPadding (uint32)
The horizontal/vertical distance, in pixels, between the toolbar
members and the gadget border (or outer bevel, if displayed - see
TOOLBAR_BevelStyle below).
Defaults to 0
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
TOOLBAR_InnerPadding (uint32)
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.
Defaults to 4
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
TOOLBAR_HandleOverflow (BOOL)
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.
Defaults to FALSE
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
TOOLBAR_MinVisible (uint32)
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.
Defaults to 1
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
TOOLBAR_SpacerSize (uint32)
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.
Defaults to 5
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
TOOLBAR_ButtonStyle (uint32)
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.
Defaults to TB_BUTSTYLE_CLASSIC
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
TOOLBAR_BevelStyle (uint32)
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:
BVS_NONE -- no bevel is drawn around the toolbar
BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel
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.
Defaults to BVS_NONE
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
TOOLBAR_SeparatorStyle (uint32)
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.
Defaults to TB_SEPSTYLE_NORMAL
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
TOOLBAR_SelectionStyle (uint32)
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.
This tag is ignored in the classic mode with framed buttons.
Defaults to TB_SELSTYLE_NONE
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
TOOLBAR_BackFill (struct Hook *)
A custom backfill hook to provide a background filled with a specific
colour or pattern.
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.
Defaults to NULL (the default layers backfill hook).
Applicability is (OM_NEW, OM_SET, OM_UPDATE)
TOOLBAR_Display (uint32)
Specifies what you want to display inside the toolbar button or toggle
members. The possible values are:
TB_DISPLAY_IMAGES -- display only images
TB_DISPLAY_TEXT -- display only text labels
TB_DISPLAY_BOTH -- display both images and text labels
Defaults to TB_DISPLAY_IMAGES
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
TOOLBAR_TextPlace (uint32)
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.
Defaults to and currently only supports TB_PLACETEXT_BELOW
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
TOOLBAR_LabelArray (STRPTR *)
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.
TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.
Using this tag, the limitation is that you cannot create toggle members
(only buttons, separators and spacers).
A special string, " ", will create a spacer.
A special string, "_", will create a separator.
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.
The button strings are copied to an internal buffer, so the label array
need not remain valid throughout the lifetime of the gadget.
Defaults to NULL
Applicability is (OM_NEW)
TOOLBAR_EvenSize (BOOL)
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.
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.
Defaults to FALSE
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
TOOLBAR_ImageSet (uint32)
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.
Defaults to 0
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
*** Method attributes ***
The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:
TOOLBAR_AddImageSet (uint32)
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.
This tag should be followed by a sequence of TOOLBAR_AddImage tags (see
below), each creating one image in the given set.
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.
Applicability is (OM_NEW, OM_SET)
TOOLBAR_AddImage (uint32)
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.
This tag should be followed by a sequence of TBIMAGE_ tags (see the
"Image attributes" section below), each configuring one aspect of the
image, including its optional selected variant (referred to as the
"select image").
Images are added to the default image set unless a preceding
TOOLBAR_AddImageSet specifies a different set.
Applicability is (OM_NEW, OM_SET)
TOOLBAR_AddMember (uint32)
Creates a new toolbar member. The value passed to this tag is a numeric
ID identifying the member.
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.
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().
Applicability is (OM_NEW, OM_SET)
TOOLBAR_SetMember
Use this tag in a SetAttrs() call to identify the member you want to
modify.
Applicability is (OM_SET)
TOOLBAR_SetGroup
Use this tag in a SetAttrs() call to identify the group of members you
want to modify collectively.
Applicability is (OM_SET)
*** Member attributes ***
TBMEMBER_Type (uint32)
The type of the toolbar member. The possible values are the following:
TB_MTYPE_BUTTON -- a normal toolbar button
TB_MTYPE_TOGGLE -- a toggle (on/off) button
TB_MTYPE_SPACER -- a spacer
TB_MTYPE_SEPARATOR -- a separator bar
The type is set upon member creation, and cannot be changed.
Defaults to TB_MTYPE_BUTTON
Applicability is (OM_NEW)
TBMEMBER_ImageID (uint32)
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 will always return TB_NO_ID should you inquire
about the TBMEMBER_ImageID value of such a member.
Defaults to TB_NO_ID (no image associated with this member)
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)
TBMEMBER_Text (CONST_STRPTR)
The label to associate with a button or a toggle member. This tag is not
relevant to spacers and separators; TBM_GETMEMBER will always return
NULL should you inquire about the TBMEMBER_Text value of such a member.
The text label will be used as fallback in case no image is found or
provided.
The text string can contain an underscore character (_), indicating the
keyboard shortcut for this member.
Defaults to NULL
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)
TBMEMBER_Disabled (BOOL)
The current state (disabled or not disabled) of a member. This tag is
not relevant to spacers and separators; TBM_GETMEMBER will always return
FALSE should you inquire about the TBMEMBER_Disabled value of such
a member.
Defaults to FALSE
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)
TBMEMBER_Hidden (BOOL)
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.
Defaults to FALSE
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)
TBMEMBER_Selected (BOOL)
The current selection state of a toggle member. This tag is not relevant
to normal buttons (TB_MTYPE_BUTTON), spacers and separators;
TBM_GETMEMBER will always return FALSE should you inquire about the
TBMEMBER_Selected value of such a member.
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.
Defaults to FALSE
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_NOTIFY, TBM_GETMEMBER)
TBMEMBER_Group (uint32)
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.
Defaults to TB_NO_ID (not assigned to any group)
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)
TBMEMBER_MXGroup (uint32)
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.
This tag is not relevant to normal buttons, spacers and separators;
TBM_GETMEMBER will always return TB_NO_ID should you inquire about the
TBMEMBER_MXGroup value of such a member.
Defaults to TB_NO_ID (not assigned to any MX group)
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)
TBMEMBER_HintInfo (CONST_STRPTR)
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 will always return NULL should you inquire
about the TBMEMBER_HintInfo value of such a member.
Defaults to NULL
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)
TBMEMBER_UserData (APTR)
Arbitrary user data associated with this member.
Defaults to NULL
Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)
*** Image attributes ***
TBIMAGE_Image (struct Image *)
Custom image to be used for a button or a toggle member.
Defaults to NULL
Applicability is (OM_NEW)
TBIMAGE_ImageFile (CONST_STRPTR)
The full path to the source file to create the image from. The image
will be loaded and built using the Shared Image class.
All images created this way will also be disposed of automatically.
Defaults to NULL
Applicability is (OM_NEW)
TBIMAGE_SelImage (struct Image *)
Custom image to display when the member becomes selected.
Defaults to NULL
Applicability is (OM_NEW)
TBIMAGE_SelImageFile (CONST_STRPTR)
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.
All images created this way will also be disposed of automatically.
Defaults to NULL
Applicability is (OM_NEW)
TBIMAGE_Width (uint32)
TBIMAGE_Height (uint32)
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.
Defaults to 0
Applicability is (OM_NEW)
NOTES 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 method documentation below to see how to handle such situations.
Images are configured at OM_NEW, i.e. when creating each respective image. Image attributes cannot be changed later.
BUGS
SEE ALSO
toolbar.gadget/OM_SET toolbar.gadget/OM_SET
NAME OM_SET -- set toolbar attributes
SYNOPSIS uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);
uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win,
struct Requester *req, Tag tag1, ...);
FUNCTION 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.
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.
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.
INPUTS toolbar -- the toolbar gadget object win -- the window that hosts the toolbar req -- requester pointer (use NULL) tag1 etc. -- a list of toolbar attribute tags
RESULT 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.
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).
The method returns 0 if no rethink is needed.
EXAMPLE
// To set various toolbar attributes:
if ( IIntuition->SetAttrs(toolbar,
TOOLBAR_Orientation, TB_ORIENT_VERT,
TOOLBAR_Spacing, 4,
TOOLBAR_SpacerSize, 10,
TAG_END) == TB_NEED_RETHINK )
{
IIntuition->IDoMethod(winObj, WM_RETHINK);
}
// To disable a member:
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,
TOOLBAR_SetMember, MEMBER_ID,
TBMEMBER_Disabled, TRUE,
TAG_END);
// To hide a member:
IIntuition->SetAttrs(toolbar,
TOOLBAR_SetMember, MEMBER_ID,
TBMEMBER_Hidden, TRUE,
TAG_END);
IIntuition->IDoMethod(winObj, WM_RETHINK);
// To modify several member attributes at once:
IIntuition->SetAttrs(toolbar,
TOOLBAR_SetMember, MEMBER_ID,
TBMEMBER_HintInfo, "My help string",
TBMEMBER_UserData, anything,
TAG_END);
// To disable all members assigned to a group:
IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,
TOOLBAR_SetGroup, GROUP_ID,
TBMEMBER_Disabled, TRUE,
TAG_END);
NOTES BUGS SEE ALSO
toolbar.gadget/TBM_GETMEMBER toolbar.gadget/TBM_GETMEMBER
NAME TBM_GETMEMBER -- obtain the value of a specific member attribute
SYNOPSIS uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);
uint32 result = IDoMethod(Object *toolbar, uint32 methodID,
uint32 attrID, uint32 *storage);
FUNCTION Use this method to obtain the value of a given member attribute.
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:
- 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.
- 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.)
INPUTS
For IDoMethodA():
toolbar -- the toolbar gadget object
msg -- a pointer to an initialized tbGetMember structure
For IDoMethod():
toolbar -- the toolbar gadget object
methodID -- this method's identifier, TBM_GETMEMBER
attrID -- the attribute tag identifier
storage -- a pointer to the variable for storing the attribute value
RESULT 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.
EXAMPLE
// To query about the selection state of a toggle member: uint32 storage;
IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID,
TBMEMBER_Selected, &storage);