Detailed Description
The QTabBar class provides a tab bar, e.g. for use in tabbed dialogs.
QTabBar is straightforward to use; it draws the tabs using one of
the predefined shapes, and emits a
signal when a tab is selected. It can be subclassed to tailor the
look and feel. Qt also provides a ready-made QTabWidget and a
QTabDialog.
The choice of tab shape is a matter of taste, although tab dialogs
(for preferences and similar) invariably use RoundedAbove;
nobody uses TriangularAbove. Tab controls in windows other than
dialogs almost always use either RoundedBelow or TriangularBelow. Many spreadsheets and other tab controls in which
all the pages are essentially similar use TriangularBelow,
whereas RoundedBelow is used mostly when the pages are
different (e.g. a multi-page tool palette).
The most important part of QTabBar's API is the selected() signal.
This is emitted whenever the selected page changes (even at
startup, when the selected page changes from 'none'). There is
also a slot, setCurrentTab(), which can be used to select a page
programmatically.
QTabBar creates automatic accelerator keys in the manner of
QButton; e.g. if a tab's label is "&Graphics", Alt+G becomes an
accelerator key for switching to that tab.
The following virtual functions may need to be reimplemented:
- paint() paints a single tab. paintEvent() calls paint() for
each tab so that any overlap will look right.
- addTab() creates a new tab and adds it to the bar.
- selectTab() decides which tab, if any, the user selects with the mouse.
The index of the current tab is returned by currentTab(). The tab
with a particular index is returned by tabAt(), the tab with a
particular id is returned by tab(). The index of a tab is returned
by indexOf(). The current tab can be set by index or tab pointer
using one of the setCurrentTab() functions.
See also Advanced Widgets.
Member Type Documentation
QTabBar::Shape
This enum type lists the built-in shapes supported by QTabBar:
- QTabBar::RoundedAbove - the normal rounded look above the pages
- QTabBar::RoundedBelow - the normal rounded look below the pages
- QTabBar::TriangularAbove - triangular tabs above the pages (very
unusual; included for completeness)
- QTabBar::TriangularBelow - triangular tabs similar to those used in
the Excel spreadsheet, for example
Member Function Documentation
QTabBar::QTabBar ( QWidget * parent = 0, const char * name = 0 )
Constructs a new, empty tab bar; the parent and name
arguments are passed on to the QWidget constructor.
QTabBar::~QTabBar ()
Destroys the tab control, freeing memory used.
int QTabBar::addTab ( QTab * newTab ) [virtual]
Adds the tab, newTab, to the tab control.
Sets newTab's id to a new id and places the tab just to the
right of the existing tabs. If the tab's label contains an
ampersand, the letter following the ampersand is used as an
accelerator for the tab, e.g. if the label is "Bro&wse" then
Alt+W becomes an accelerator which will move the focus to this
tab. Returns the id.
See also insertTab().
int QTabBar::count () const
Returns the number of tabs in the tab bar.
See the "count" property for details.
int QTabBar::currentTab () const
Returns the id of the tab bar's visible tab.
See the "currentTab" property for details.
int QTabBar::indexOf ( int id ) const
Returns the position index of the tab with id id or -1 if no
tab has this id.
See also tabAt().
int QTabBar::insertTab ( QTab * newTab, int index = -1 ) [virtual]
Inserts the tab, newTab, into the tab control.
If index is not specified, the tab is simply appended.
Otherwise it's inserted at the specified position.
Sets newTab's id to a new id. If the tab's label contains an
ampersand, the letter following the ampersand is used as an
accelerator for the tab, e.g. if the label is "Bro&wse" then
Alt+W becomes an accelerator which will move the focus to this
tab. Returns the id.
See also addTab().
bool QTabBar::isTabEnabled ( int id ) const
Returns TRUE if the tab with id id exists and is enabled;
otherwise returns FALSE.
See also setTabEnabled().
int QTabBar::keyboardFocusTab () const
Returns the id of the tab that has the keyboard focus.
See the "keyboardFocusTab" property for details.
void QTabBar::layoutChanged () [signal]
QTabBar emits the signal whenever the layout of the tab bar has
been recalculated, for example when the contents of a tab change.
void QTabBar::layoutTabs () [virtual]
Lays out all existing tabs according to their label and their
iconset.
void QTabBar::paint ( QPainter * p, QTab * t, bool selected ) const [virtual protected]
Paints the tab t using painter p. If and only if selected
is TRUE, t is drawn currently selected.
This virtual function may be reimplemented to change the look of
QTabBar. If you decide to reimplement it, you may also need to
reimplement sizeHint().
void QTabBar::paintEvent ( QPaintEvent * e ) [virtual protected]
Repaints the tab row. All the painting is done by paint();
paintEvent() only decides which tabs need painting and in what
order. The event is passed in e.
See also paint().
Reimplemented from QWidget.
void QTabBar::paintLabel ( QPainter * p, const QRect & br, QTab * t, bool has_focus ) const [virtual protected]
Paints the label of tab t centered in rectangle br using
painter p. A focus indication is drawn if has_focus is TRUE.
void QTabBar::removeTab ( QTab * t ) [virtual]
Removes tab t from the tab control, and deletes the tab.
void QTabBar::removeToolTip ( int index )
Removes the tool tip for the tab at index position index.
QTab * QTabBar::selectTab ( const QPoint & p ) const [virtual]
This virtual function is called by the mouse event handlers to
determine which tab is pressed. The default implementation returns
a pointer to the tab whose bounding rectangle contains p, if
exactly one tab's bounding rectangle contains p. Otherwise it
returns 0.
See also mousePressEvent() and mouseReleaseEvent().
void QTabBar::selected ( int id ) [signal]
QTabBar emits this signal whenever any tab is selected, whether by
the program or by the user. The argument id is the id of the
tab as returned by addTab().
show() is guaranteed to emit this signal; you can display your
page in a slot connected to this signal.
void QTabBar::setCurrentTab ( int ) [virtual slot]
Sets the id of the tab bar's visible tab.
See the "currentTab" property for details.
void QTabBar::setCurrentTab ( QTab * tab ) [virtual slot]
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Raises tab and emits the selected() signal unless the tab was
already current.
See also currentTab and selected().
void QTabBar::setShape ( Shape ) [virtual]
Sets the shape of the tabs in the tab bar.
See the "shape" property for details.
void QTabBar::setTabEnabled ( int id, bool enabled ) [virtual]
Enables tab id if enabled is TRUE or disables it if enabled is FALSE. If id is currently selected,
setTabEnabled(FALSE) makes another tab selected.
setTabEnabled() updates the display if this causes a change in id's status.
See also update() and isTabEnabled().
void QTabBar::setToolTip ( int index, const QString & tip )
Sets the tool tip for the tab at index position index to tip.
Shape QTabBar::shape () const
Returns the shape of the tabs in the tab bar.
See the "shape" property for details.
QTab * QTabBar::tab ( int id ) const
Returns the tab with id id or 0 if there is no such tab.
See also count.
QTab * QTabBar::tabAt ( int index ) const
Returns the tab at position index.
See also indexOf().
QPtrList<QTab> * QTabBar::tabList () [protected]
The list of QTab objects in the tab bar.
This list is unlikely to be in the order that the QTab elements
appear visually. One way of iterating over the tabs is like this:
for ( uint i = 0; i < myTabBar->count(); ++i ) {
nextTab = myTabBar->tabAt( i );
// do something with nextTab
}
QString QTabBar::toolTip ( int index ) const
Returns the tool tip for the tab at index position index.
Property Documentation
int count
This property holds the number of tabs in the tab bar.
Get this property's value with count().
See also tab().
int currentTab
This property holds the id of the tab bar's visible tab.
If no tab page is currently visible, the property's value is -1.
Even if the property's value is not -1, you cannot assume that the
user can see the relevant page, or that the tab is enabled. When
you need to display something the value of this property
represents the best page to display.
When this property is set to id, it will raise the tab with the
id id and emit the selected() signal.
See also selected() and isTabEnabled().
Set this property's value with setCurrentTab() and get this property's value with currentTab().
int keyboardFocusTab
This property holds the id of the tab that has the keyboard focus.
This property contains the id of the tab that has the keyboard
focus or -1 if the tab bar does not have the keyboard focus.
Get this property's value with keyboardFocusTab().
This property holds the shape of the tabs in the tab bar.
The value of this property is one of the following: RoundedAbove (default), RoundedBelow, TriangularAbove or TriangularBelow.
See also Shape.
Set this property's value with setShape() and get this property's value with shape().
This file is part of the Qt toolkit.
Copyright © 1995-2003
Trolltech. All Rights Reserved.
