ToolBar Gadget Class - Revision history

Trixie: Toolbar attributes: updated TOOLBAR_TextPlace.

2021-02-14T14:37:59Z

Toolbar attributes: updated TOOLBAR_TextPlace.

Trixie: /* Notes */

2021-02-05T20:01:34Z

Notes

Trixie: /* Image attributes */

2021-02-05T20:00:30Z

Image attributes

Trixie: More updates.

2021-01-09T20:45:33Z

More updates.

Trixie: Added TBMEMBER_TextStyle. Updated TBMEMBER_Text.

2021-01-08T21:08:21Z

Added TBMEMBER_TextStyle. Updated TBMEMBER_Text.

Trixie: Added TOOLBAR_TextStyle. TBMEMBER_DomainString.

2021-01-08T20:03:11Z

Added TOOLBAR_TextStyle. TBMEMBER_DomainString.

Trixie: /* Method attributes */

2021-01-08T13:15:14Z

Method attributes

Trixie: /* Member attributes */

2021-01-05T22:19:34Z

Member attributes

Trixie: Updated GA_TextAttr, TOOLBAR_TextPen and TBMEMBER_TextAttr. Added TBMEMBER_TextPen.

2021-01-05T22:18:00Z

Updated GA_TextAttr, TOOLBAR_TextPen and TBMEMBER_TextAttr. Added TBMEMBER_TextPen.

Trixie: Updated GA_TextAttr. Added TOOLBAR_TextPen.

2021-01-05T14:33:24Z

Updated GA_TextAttr. Added TOOLBAR_TextPen.

@@ Line 160: / Line 160: @@
 ; 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. Plus, it only affects button and toggle members.
-: Defaults to and currently only supports TB_PLACETEXT_BELOW
+: The possible values are:
 : Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)

← Older revision		Revision as of 20:01, 5 February 2021
Line 363:		Line 363:

	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.		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.
−
−	~~Images are configured at OM_NEW, i.e. when creating each respective image. [[#Image attributes\|Image attributes]] cannot be changed later.~~

	== Bugs ==		== Bugs ==

← Older revision		Revision as of 20:00, 5 February 2021
Line 329:		Line 329:

	=== Image attributes ===		=== Image attributes ===
		+
		+	Note: Images are configured at OM_NEW, i.e. when creating each respective image. Image attributes cannot be changed later.

	; TBIMAGE_Image (struct Image *)		; TBIMAGE_Image (struct Image *)

@@ Line 166: / Line 166: @@
 : 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).
+: Using this tag, the limitation is that you cannot create toggle or textbox members (only buttons, separators and spacers).
 : A special string, " ", will create a spacer.
 : A special string, "_", will create a separator.
@@ Line 233: / Line 233: @@
 ; 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|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_ImageID value of such a member.
+: 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.
 : 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:
 :* by setting this attribute via RefreshSetGadgetAttrs(), or
@@ Line 244: / Line 244: @@
 : 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.
 : The text will be used as fallback in case no image is found or provided for a button or a toggle member.
 : 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.)
 : 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:
@@ Line 301: / Line 302: @@
 ; 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|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Selected value of such a member.
+: 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.
 : 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
@@ Line 313: / Line 314: @@
 ; 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|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_MXGroup value of such a member.
+: 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.
 : Defaults to TB_NO_ID (not assigned to any MX group)
 : Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])

@@ Line 245: / Line 245: @@
 : The text will be used as fallback in case no image is found or provided for a button or a toggle member.
 : 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.)
-: If your toolbar has a textbox member the contents of which is going to change dynamically, updating TBMEMBER_Text should be done like this:
+: 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:
-        IIntuition->SetAttrs(toolbar,
+      (1)   IIntuition->SetGadgetAttrs(toolbar, window, NULL,
-                    TOOLBAR_SetMember, memberID,
+                        TOOLBAR_SetMember, textboxID,
-                       TBMEMBER_Text, "New text",
+                           TBMEMBER_Text, "New text",
-                    TAG_END);
+                        TAG_END);
-        IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);
+              IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, textboxID, window);
-: 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.
+: 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.
 : Defaults to NULL
 : Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])
@@ Line 268: / Line 273: @@
 : Pointer to a TextAttr structure describing the font to be used for the member text. This tag overrides GA_TextAttr (see above).
 : 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.
-: Defaults to NULL.
+: Defaults to the GA_TextAttr value
 : Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)
@@ Line 275: / Line 280: @@
 : 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.
 : Prefer to use pens from the dri_Pens[] array in your screen's DrawInfo structure; see the <intuition/screens.h> system include file.
-: Defaults to dri_Pens[TEXTPEN]
+: Defaults to the TOOLBAR_TextPen value
 : Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)

@@ Line 57: / Line 57: @@
 ; 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).
+: Defaults to NULL (the default backfill hook)
 : Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)
@@ Line 63: / Line 63: @@
 : Pointer to a TextAttr structure describing the font to be used for the toolbar members' text.
 : 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.
-: Defaults to NULL (will use the system's default public screen font).
+: Defaults to NULL (will use the system's default public screen font)
 : Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)
@@ Line 131: / Line 131: @@
 : 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).
+: Defaults to NULL (the default backfill hook)
 : Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)
@@ Line 149: / Line 149: @@
 : Prefer to use pens from the dri_Pens[] array in your screen's DrawInfo structure; see the <intuition/screens.h> system include file.
 : Defaults to dri_Pens[TEXTPEN]
 : Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)
@@ Line 254: / Line 261: @@
 : 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.
 : The domain string is never rendered in the gadget.
-: 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.
+: This tag is not relevant to spacers and separators.
 : Defaults to NULL
-: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)
 ; TBMEMBER_TextAttr (struct TextAttr *) (V53.4)

@@ Line 184: / Line 184: @@
 ; 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.
@@ Line 190: / Line 191: @@
 ; 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|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.

@@ Line 61: / Line 61: @@
 ; GA_TextAttr (struct TextAttr *)
-: Pointer to a TextAttr structure describing the font to be used for the gadget members' text.
+: Pointer to a TextAttr structure describing the font to be used for the toolbar members' text.
-: Defaults to the system's default public screen font.
+: 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.
 : Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)
@@ Line 142: / Line 143: @@
 : Defaults to TB_DISPLAY_IMAGES
 : Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)
 ; TOOLBAR_TextPlace (uint32)