VkTabPanel(3x)
VkTabPanel - A component for displaying a tabular control panel
As shipped in IRIX 6.5.19. Unchanged since IRIX 6.5.
NAME VkTabPanel - A component for displaying a tabular control panel INHERITS FROM VkComponent : VkCallbackObject HEADER FILE #include <Vk/VkTabPanel.h> PUBLIC PROTOCOL SUMMARY Constructor/Destructor VkTabPanel(char* name, Widget parent, Boolean horizOrientation = True, int tabHeight = 0); virtual void ~VkTabPanel(void); Configuration Pixel getSelectedTabBg(void); Pixel getUnselectedTabBg(void); Boolean horiz(void); Boolean uniformTabs(void); int size(void); Pixel tabBg(void); Pixel selectedTabBg(void); Pixel labelFg(void); Pixel labelBg(void); GC gc(void); int lineThickness(void); int tabHeight(void); Setup Functions int addTab(char* label, void* clientData, Boolean sorted = False); void addTabs(char** labels, void** clientData, int numLabels, Boolean sorted = False); Boolean removeTab(int index); Boolean removeTab(char* label); Boolean tabPixmap(int index, Pixmap* pixmap_return); Boolean tabPixmap(char* label, Pixmap* pixmap_return); Boolean setTabPixmap(int index, Pixmap pixmap); Boolean setTabPixmap(char* label, Pixmap pixmap); Boolean setTabLabel(int index, char* label); Boolean setTabClientData(int index, void* clientData); Tab Width Functions int getTabWidth (int index=0); int getMaxTabWidth (); void matchTabWidth (VkTabPanel* panel=NULL, enum VK_TAB_MATCH_WIDTH =VK_DEFAULT); void setTabWidth (int width=0); void setTabWidth (char*); Access Functions int selectedTab(void); Boolean getTab(int index, char** label_return, void** clientData_return); Widget area1(void); Widget area2(void); X RESOURCES ASSOCIATED WITH THIS CLASS additionalMarginHeight Added to tab label margin additionalMarginWidth Added to tab label margin background Background component color, around tabs darkPercent Set the unselected tabs' background to a color that is this percentage of the way between the selected tab's background color and the selected tab's BottomShadow color. endMultiplier End-indicator duplication (3) endSpacing End-indicator internal spacing (9) lineThickness Thickness of tab edges (1) margin Margin between tab edges and the component edge (5) margin1 Margin between workarea1 and the tabs (5) margin2 Margin between workarea2 and the tabs (5) pixmapSpacing Spacing between tab label and pixmap (3) selectedTabBackground Different background used for the selected tab (none) sideOffset Tab edge curvature (17) tabHeight Tab height (0, use label height) tabLabel.background Background used for tabs, bitmaps tabLabel.fontList Font used for tab labels tabLabel.foreground Foreground used for tab labels, bitmaps tabLabel.height Tab height default if tabHeight is 0 tabLabel.marginHeight Tab label margin tabLabel.marginWidth Tab label margin uniformTabs Whether tabs should be all the same width (False) use3DTabs Draw the tabs with a shaded, 3-D, appearance CLASS DESCRIPTION VkTabPanel presents a row or column of overlayed tabs. One tab is always selected, and appears on top of all the others. The user can left-click on a tab to select it. If the orientation is horizontal, work areas are provided to the left and right of the tab display for application use. If the orientation is vertical, work areas are provided above and below the tab display. When the tabs do not fit within the provided space, end-indicators appear as necessary to represent a set of collapsed tabs. When the user left-clicks or right-clicks in an end-indicator, a popup menu appears listing all the tabs. The user may choose an item to select the corresponding tab. DERIVING SUBCLASSES A private class, VkTabArea, does virtually all of the work. VkTabPanel creates a VkTabArea amongst the work areas and other Motif widgets. VkTabArea's public interface is the same as VkTabPanel's interface. Many of the VkTabPanel methods simply call the corresponding VkTabArea methods. FUNCTION DESCRIPTIONS VkTabPanel() VkTabPanel(char* name, Widget parent, Boolean horizOrientation = True, int tabHeight = 0); virtual void ~VkTabPanel(void); VkTabPanel creates a component using the name and parent parameters. The optional horizOrientation argument can be used to create a vertically-oriented VkTabPanel instead of the default horizontal orientation. The tabHeight argument defaults to 0, indicating that the default label height should determine the height of the tabs. Applications which display pixmaps in the tabs may want to specify a height for the tabs. getSelectedTabBg() Pixel getSelectedTabBg(void); Returns the color used for the selected tab background. This color is set by the "selectedTabBackground" resource. If no resource value is specified, the normal tab background color is used. getUnselectedTabBg() Pixel getUnselectedTabBg(void); Returns the color used for the unselected tab background. This color is a calculated value. horiz() Boolean horiz(void); This function returns TRUE if the tab component is horizontally- oriented, FALSE otherwise. uniformTabs() Boolean uniformTabs(void); This function returns TRUE if the tabs have a uniform width (or height, if the tab component is vertically-oriented). By default, tabs take on the necessary width to display their label and pixmap. If the "uniformTabs" resource is set to "true", all tabs take on the width of the largest tab in the group. The total width of a tab is the sum of its label width and if it has a non-NULL pixmap, the pixmap spacing plus the pixmap size. The pixmap spacing is set by the "pixmapSpacing" resource of the VkTabPanel baseWidget, which defaults to 3. Also included is the tab margin width, which is set by the "marginWidth" resource of the "tabLabel" widget created by VkTabPanel plus the "additionalMarginWidth" resource of the VkTabPanel baseWidget, which defaults to 4. When the tabs are displayed, the amount of overlap is set by the "sideOffset" resource of the VkTabPanel baseWidget, which defaults to 17. When the tabs do not fit within the provided space, end- indicators are displayed. Their appearances are set by the "endSpacing" and "endMultiplier" resources which affect the line spacing and number of lines drawn. They default to 9 and 3, respectively. size() int size(void); Returns the number of tabs in the group. tabBg() Pixel tabBg(void); Returns the color used for the background area underneath the tabs. This color is set by the "background" resource of the VkTabPanel baseWidget. selectedTabBg() Pixel selectedTabBg(void); Returns the color used for the selected tab background. This color is set by the "selectedTabBackground" resource. If no resource value is specified, the normal tab background color is used. labelFg() Pixel labelFg(void); Returns the color used for tab foregrounds (e.g. the tab lettering). This color is set by the "foreground" resource for the "tabLabel" widget created by VkTabPanel. When a bitmap is supplied as the pixmap, this color is used for the 1 bits. labelBg() Pixel labelBg(void); Returns the color used for tab backgrounds. This color is set by the "background" resource for the "tabLabel" widget created by VkTabPanel. When a bitmap is supplied as the pixmap, this color is used for the 0 bits unless the tab is selected and a selectedTabBackground color resource exists. gc() GC gc(void); Returns the X graphics context used for drawing the tabs. This may be useful to an application when it creates pixmaps and wants to use the same foreground and background colors as the tabs. This function is now deprecated, in favor of getSelectedTabBg() and getUnselectedTabBg(). gc() is meaningful only with use3DTabs = FALSE. Applications that construct pixmaps for tab labels should set use3DTabs = TRUE and use the new functions to get their backgrounds. lineThickness() int lineThickness(void); Returns the line thickness used when drawing the tab edges. The line thickness defaults to 1, but can be set by the "lineThickness" resource of the VkTabPanel baseWidget. However, line thickness other than 1 may not render properly. tabHeight() int tabHeight(void); Returns the height of the tab display area. This is the maximum display height for pixmaps. Pixmaps which are greater than this size will be truncated, and pixmaps which are smaller will be centered. This height can be specified in the constructor, or by the "tabHeight" resource of the VkTabPanel baseWidget, or by the font height of the "tabLabel" widget created by VkTabPanel. The total tab height is the tab display area height, plus the tab margin height, which is set by the "marginHeight" resource of the "tabLabel" widget created by VkTabPanel plus the "additionalMarginHeight" resource of the VkTabPanel baseWidget, which defaults to 2. The difference between the VkTabPanel component's height (or width, if vertically-oriented) and the true height of its tabs, is set by the "margin" resource of the VkTabPanel baseWidget, which defaults to 5. selectedTab() int selectedTab(void); Returns the index of the currently-selected tab. Tab indices start with zero. The maximum tab index, then, is size()-1. area1() Widget area1(void); Returns the first work area. This is a Motif XmForm widget placed to the left of the tabs in a horizontal tab group, and above the tabs in a vertical group. The work area is separated from the tabs by the number of pixels specified by the "margin1" resource of the VkTabPanel baseWidget, which defaults to 5. area2() Widget area2(void); Returns the second work area. This is a Motif XmForm widget placed to the right of the tabs in a horizontal tab group, and below the tabs in a vertical group. The work area is separated from the tabs by the number of pixels specified by the "margin2" resource of the VkTabPanel baseWidget, which defaults to 5. addTab int addTab(char* label, void* clientData, Boolean sorted = False); void addTabs(char** labels, void** clientData, int numLabels, Boolean sorted = False); Adds a new tab to the group. The label is used as a resource lookup for the actual label string and if no resource match is found, used verbatim as the string. The clientData argument is for the application's convenience, and is returned in the VkTabCallbackStruct when that tab is selected. New tabs initially have a NULL pixmap. If the new tab is the first tab in the group, it is automatically selected. The index of the newly-added tab is returned. The addTabs form simply takes a list of new tabs to be added. The new tab is added to the end of the group unless the optional sorted argument is set to TRUE, in which case the tab is inserted before the first tab whose label alphabetically succeeds the new tab's label. If the tab added is the first tab in the panel, this tab will get selected and the tabSelectCallback will be invoked. selectTab() Boolean selectTab(int index, XEvent* event = NULL); Boolean selectTab(char* label, XEvent* event = NULL); Selects a tab. The tab's index or label can be used for selection. If the operation succeeds, TRUE is returned. If the tab couldn't be found or if the index is out of range, FALSE is returned. The optional event parameter is passed in the VkTabCallbackStruct for possible application use. If more than one tab match the label, the first one is selected. removeTab() Boolean removeTab(int index); Boolean removeTab(char* label); Removes a tab from the list. The tab's index or label can be used for selection. If the operation succeeds, TRUE is returned. If the tab couldn't be found or if the index is out of range, FALSE is returned. If more than one tab match the label, the first one is selected. tabPixmap() Boolean tabPixmap(int index, Pixmap* pixmap_return); Boolean tabPixmap(char* label, Pixmap* pixmap_return); Returns the pixmap associated with a tab. The tab's index or label can be used for selection. If the operation succeeds, TRUE is returned and the pixmap is returned through the pixmap_return argument. If the tab couldn't be found or if the index is out of range, FALSE is returned. If more than one tab match the label, the first one is selected. setTabPixmap() Boolean setTabPixmap(int index, Pixmap pixmap); Boolean setTabPixmap(char* label, Pixmap pixmap); Changes the pixmap associated with a tab. Use a NULL pixmap to eliminate the pixmap display. The tab's index or label can be used for selection. If the operation succeeds, TRUE is returned and the tabs are redrawn. If the tab couldn't be found or if the index is out of range, FALSE is returned. If more than one tab match the label, the first one is selected. setTabLabel() Boolean setTabLabel(int index, char* label); Changes the label associated with a tab. The label is used as a resource lookup for the actual label string and if no resource match is found, used verbatim as the string. If the operation succeeds, TRUE is returned and the tabs are redrawn. If the index is out of range, FALSE is returned. setTabClientData() Boolean setTabClientData(int index, void* clientData); Changes the clientData associated with a tab. If the operation succeeds, TRUE is returned and the tabs are redrawn. If the index is out of range, FALSE is returned. getTabWidth() int getTabWidth (int index=0); Returns the width of the tab whose index is passed. (Tabs are indexed from 0 to n-1.) getMaxTabWidth() int getMaxTabWidth (); Gets the width that will be used to display the widest tab. This may not be wide enough to accommodate all labels if setTabWidth() has been used. matchTabWidth() void matchTabWidth (VkTabPanel *tp=NULL, enum VK_TAB_MATCH_WIDTH = VK_DEFAULT); This introduces the concept of a tab panel match set. When a VkTabPanel's matchTabWidth() member is called, that VkTabPanel is assumed to be the set leader. It does not matter which tab panel you pick to be the set leader. All it does is some record-keeping. But you do need to be consistent about it. (The concept of a set leader is regarded as an unfortunate implementation limitation that we shall remove later if there is enough demand to do so.) If the getMaxTabWidth() for tp is larger than that of the existing set, then the existing set's VkTabPanel's are each set to the new width. Otherwise tp is set to the width of the existing set. In either case, tp is added to the match set. matchTabWidth() sets widths using setTabWidth(). /fBVK_DEFAULT is the only current setting for the enum. It is provided so we have an easy extension mechanism if we later need to use a different definition of matching. setTabWidth() void setTabWidth (int width=0); void setTabWidth (char *longestString); Normally, each tab is the right size to hold its label. That means that each tab in a single VkTabPanel is sized independently. setTabWidth sets the width of each tab for a single VkTabPanel to a single value. width sets the width to that number of pixels. longestString sets the width to be enough to hold the specified string. The string does not need to be an actual tab label, although generally it will be. If the labels will be translated, be careful. The longest string in one language may not be the longest one in all languages. In most cases it will be easier to synchronize tab widths with matchTabWidth. setTabWidth is provided for those cases where an application needs more control than matchTabWidth gives. If setTabWidth(0), then tab width reverts to being calculated according to the length of the label. DATA MEMBER DESCRIPTIONS tabSelectCallback static const const char* tabSelectCallback; A callback function for detecting changes in the selected tab. The callData argument to the callback should be cast to a (VkTabCallbackStruct *). This structure returns the tab's label and clientData as passed to addTab, the current tab index, and the event which triggered the selection. The event may be NULL, if the user used the popup menu or the selection was programmatic. tabPopupCallback static const const char* tabPopupCallback; A callback function for detecting when the user right-buttons in a tab. The callData argument to the callback should be cast to a (VkTabCallbackStruct *). This structure returns the tab's label and clientData as passed to addTab, the current tab index, and the event which triggered the selection. Inherited from VkComponent installDestroyHandler(), removeDestroyHandler(), widgetDestroyed(), setDefaultResources(), getResources(), manage(), unmanage(), baseWidget(), okToQuit(), _name, _baseWidget, _w, deleteCallback Inherited from VkCallbackObject callCallbacks(), addCallback(), removeCallback(), removeAllCallbacks() SEE ALSO VkComponent ViewKit Programmer's Guide The X Window System, DEC Press, Bob Sheifler and Jim Gettys The X Window System Toolkit, DEC Press, Paul Asente and Ralph Swick The OSF/Motif Programmers Reference, Prentice Hall, OSF