VkTabPanel(3x)VkTabPanel(3x)NAMEVkTabPanel - 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);
Page 1
VkTabPanel(3x)VkTabPanel(3x)
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);
Page 2
VkTabPanel(3x)VkTabPanel(3x)
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
Page 3
VkTabPanel(3x)VkTabPanel(3x)
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 DESCRIPTIONVkTabPanel 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 DESCRIPTIONSVkTabPanel()
VkTabPanel(char* name, Widget parent,
Boolean horizOrientation = True,
int tabHeight = 0);
virtual void ~VkTabPanel(void);
Page 4
VkTabPanel(3x)VkTabPanel(3x)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-
Page 5
VkTabPanel(3x)VkTabPanel(3x)
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);
Page 6
VkTabPanel(3x)VkTabPanel(3x)
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);
Page 7
VkTabPanel(3x)VkTabPanel(3x)
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.
Page 8
VkTabPanel(3x)VkTabPanel(3x)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.
Page 9
VkTabPanel(3x)VkTabPanel(3x)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.
Page 10
VkTabPanel(3x)VkTabPanel(3x)
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()
Page 11
VkTabPanel(3x)VkTabPanel(3x)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
Page 12
