clicktab.gadget
File folder tabs gadget.FUNCTIONS
SUPERCLASS
gadgetclass
REQUIRES
Chooser.gadget.
DESCRIPTION
The tabs gadget class provides a custom control that has imagery similar in style to the tabs seen in a real world drawer full of file folders.
The action of the gadget is the same as a conventional mutual-exclusion control in that only one tab can be active at a time and a tab is selected by clicking upon it.
Tabs may also have an optional close gadget attached to them, which can be used to close the relevant item.
The tabs gadget class is best used in combination with a page.gadget so the user can select a tab and the appropriate page is displayed. The tab "bar" allows strumming across the selections. The current selection is displayed differently according to various GUI preferences.
With version 53 and V47, the clicktab.gadget has been updated to allow tabs to be added and removed dynamically. Simply detaching the label list from the gadget, adding or removing clicktab nodes, and reattaching the list is sufficient to induce this behaviour.
When using dynamic tabs it is possible too many tabs are added that can possibly fit within the drawing bounds. When this situation occurs, clicktab will hide tabs that will not fit and a chooser gadget will automatically appear to enable the user to select any hidden tabs.
Dynamic tabs also change the way GM_DOMAIN is handled. Normally, there are a fixed number of tabs and the tab labels do not change. This means the GM_DOMAIN does not change and any layout gadgets can work normally. With dynamic tabs, the GM_DOMAIN changing as tabs are added, removed and renamed. The CLICKTAB_AutoFit tag has been introduced to handle this situation and should always be set when working with dynamic tabs so that the GM_DOMAIN remains constant at a reasonable minimal size.
Do not forget to call WM_RETHINK or equivalent when not using the CLICKTAB_AutoFit tag. Otherwise the graphics may render outside of the window boundaries due to the changing GM_DOMAIN.
When using dynamic tabs with a PageGroup attached to the gadget, you must make sure to heed the following: If CLICKTAB_AutoTabNumbering is set to FALSE, the TNA_Number attribute will not be recalculated when the tab list is added back to the gadget after removing a tab. This will cause the PageGroup object to display the wrong page. This is especially important if you are removing the layout object from the PageGroup with PAGE_Remove when removing the tab, as it may cause the PageGroup to try rendering a layout which has been disposed of. If you intend to remove tabs and its associated layout object, then make sure the CLICKTAB_AutoTabNumbering is set to TRUE. If you do not remove the layouts from the PageObject, then ensure that the tabs do not get renumbered, as this will keep the two gadgets in synchronisation.
More details can be found in the SDK examples directory.
The action of the gadget is the same as a conventional mutual-exclusion control in that only one tab can be active at a time and a tab is selected by clicking upon it.
Tabs may also have an optional close gadget attached to them, which can be used to close the relevant item.
The tabs gadget class is best used in combination with a page.gadget so the user can select a tab and the appropriate page is displayed. The tab "bar" allows strumming across the selections. The current selection is displayed differently according to various GUI preferences.
With version 53 and V47, the clicktab.gadget has been updated to allow tabs to be added and removed dynamically. Simply detaching the label list from the gadget, adding or removing clicktab nodes, and reattaching the list is sufficient to induce this behaviour.
When using dynamic tabs it is possible too many tabs are added that can possibly fit within the drawing bounds. When this situation occurs, clicktab will hide tabs that will not fit and a chooser gadget will automatically appear to enable the user to select any hidden tabs.
Dynamic tabs also change the way GM_DOMAIN is handled. Normally, there are a fixed number of tabs and the tab labels do not change. This means the GM_DOMAIN does not change and any layout gadgets can work normally. With dynamic tabs, the GM_DOMAIN changing as tabs are added, removed and renamed. The CLICKTAB_AutoFit tag has been introduced to handle this situation and should always be set when working with dynamic tabs so that the GM_DOMAIN remains constant at a reasonable minimal size.
Do not forget to call WM_RETHINK or equivalent when not using the CLICKTAB_AutoFit tag. Otherwise the graphics may render outside of the window boundaries due to the changing GM_DOMAIN.
When using dynamic tabs with a PageGroup attached to the gadget, you must make sure to heed the following: If CLICKTAB_AutoTabNumbering is set to FALSE, the TNA_Number attribute will not be recalculated when the tab list is added back to the gadget after removing a tab. This will cause the PageGroup object to display the wrong page. This is especially important if you are removing the layout object from the PageGroup with PAGE_Remove when removing the tab, as it may cause the PageGroup to try rendering a layout which has been disposed of. If you intend to remove tabs and its associated layout object, then make sure the CLICKTAB_AutoTabNumbering is set to TRUE. If you do not remove the layouts from the PageObject, then ensure that the tabs do not get renumbered, as this will keep the two gadgets in synchronisation.
More details can be found in the SDK examples directory.
ATTRIBUTES
- GA_ID (WORD)
-
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_NOTIFY)
- GA_Top (LONG)
-
The top of the gadget. Typically win->BorderTop + 2 for proper placement along the inner top of a window unless used within a layout gadget group, then placement is automatic.
- GA_Left (LONG)
-
The left edge of the gadget.
- GA_Height (LONG)
-
Height of the gadget. Typically font height plus eight.
- GA_RelHeight (LONG)
-
Like all other ReAction gadgets, this attribute is supported. However, due to the nature of the classes intended visuals it is stylistically a bad thing to do.
- GA_Disabled (BOOL)
-
Determines whether the gadget is disabled or not. Changing disable state will invoke GM_RENDER. A disabled gadget's border and label are all rendered in SHADOWPEN and then dusted in a ghosting pattern that is rendered in SHADOWPEN.
This tag did nothing until V47.
Defaults to FALSE.
- GA_TextAttr (struct TextAttr *)
-
Optional text attribute for the font to use for the labels.
Defaults to NULL.
- GA_Text (STRPTR *)
-
A NULL terminated array of strings to use as labels. New for V45.1. The array can be allocated on the stack, the text, however needs to stay for the whole lifetime of the object.
Defaults to NULL.
Applicability is (OM_NEW) (V45)
- CLICKTAB_Labels (struct List *)
-
A list of clicktab node structures used to indicate the labels for each of the tabs.
Note this list of nodes is the application's responsibility and will not be automatically freed when the clicktab.gadget is deleted.
Defaults to NULL.
Applicability is (OM_NEW, OM_GET, OM_SET)
- CLICKTAB_Current (LONG)
-
Currently selected tab.
Defaults to 0.
Applicability is (OM_NEW, OM_GET, OM_SET, OM_NOTIFY)
- CLICKTAB_CurrentNode (LONG)
-
Currently selected tab node.
Defaults to NULL.
Applicability is (OM_NEW, OM_GET, OM_SET, OM_NOTIFY)
- CLICKTAB_PageGroup (LONG)
-
Embedded PageObject child pointer.
Defaults to NULL.
Applicability is (OM_NEW, OM_SET) (V41.43)
- CLICKTAB_PageGroupBorder (BOOL)
-
Specify whether to draw a border around the pages of the gadget.
Defaults to TRUE.
Applicability is (OM_NEW, OM_SET, OM_GET) (V53.7 and V47)
- CLICKTAB_PageGroupBackFill (struct Hook *)
-
Embedded PageObject + selected ClickTab backfill pointer.
Defaults to NULL.
Applicability is (OM_NEW, OM_SET) (V42)
- CLICKTAB_CloseImage (Object *)
-
Specify the image you want to use as the close gadget. Ideally this should be at least a pointer to a dual state BOOPSI image, so that it changes visibly when pressed. You may allocate this multi-state image using the bitmap.image class. Check the CloseTest example program for further information on creating the BOOPSI image. In the interests of not confusing the user, you should avoid changing images after the gadget has been created, as this image applies to all tabs. The image will not be freed when the gadget is disposed of, this is your responsibility. This does mean, however, that you may share the same image between multiple clicktab.gadget instances. NB: Only the currently active tab will display the close gadget, as closing inactive tabs is not supported.
Defaults to NULL (no gadget displayed).
Applicability is (OM_NEW, OM_SET) (V53.29 and V47)
- CLICKTAB_ClosePlacement (ULONG)
-
Specify which side of the tab to place the close gadget. Choices are PLACECLOSE_LEFT and PLACECLOSE_RIGHT.
Defaults to PLACECLOSE_LEFT.
Applicability is (OM_NEW, OM_SET) (V53.30 and V47)
- CLICKTAB_NodeClosed (struct Node *)
-
After receiving a GADGETUP event you should check this attribute to see if the user selected a tabs close gadget. See CLICKTAB_Closed for further information. You should also check the TNA_CloseGadget attribute documentation in the AllocClickTabNode function to see how to set the close gadget for each node. Like the above, this is also reset once either attribute is read.
Defaults to NULL.
Applicability is (OM_GET) and for V47: OM_NOTIFY (V53.29 and V47)
- CLICKTAB_AutoFit (BOOL)
-
Enables auto-fit mode which tries to fit as many tabs as possible within the current bounds while keeping the GM_DOMAIN constant at a reasonable size.
This is especially important when your application invokes the WM_RETHINK method when dynamically adding/removing objects in a layout for example.
Defaults to FALSE.
Applicability is (OM_NEW, OM_SET) (V53.20 and V47)
- CLICKTAB_AutoTabNumbering (BOOL)
-
Tabs are automatically numbered. When using dynamic tabs with a PageGroup attached to the gadget, you must make sure CLICKTAB_AutoTabNumbering is set to FALSE, otherwise the TNA_Number attribute will not be recalculated when the tab list is added back to the gadget after a tab is removed. This causes the PageGroup object to display the wrong page. See the DYNAMIC TABS section above for full details.
Defaults to FALSE.
Applicability is (OM_NEW, OM_SET) (V53.29 and V47)
- CLICKTAB_MinorLabelChange (BOOL)
-
If, when setting CLICKTAB_Labels, only text or tooltips are affected then also setting CLICKTAB_MinorLabelChange can help to avoid flicker because no relayout of a page widget will take place.
Defaults to FALSE.
Applicability is (OM_SET) (V47)
- CLICKTAB_TabsOffsetAsLayoutSpacing (BOOL)
-
Set this if tabs should be indented from left and right by 1 layout.gadget space. This should be set to TRUE when you use the tabs without PageBorder. At the same time the clicktab.gadget should extend from side to side of the window with no other spacing creating an unbroken illusion.
Defaults to FALSE.
Applicability is (OM_NEW, OM_GET, OM_SET) (V47)
NOTES
This class is best suited for use inside a layout.gadget and requires receiving GM_DOMAIN prior to the first GM_RENDER in order to size & position its imagery correctly.