QTabDialog(3qt)QTabDialog(3qt)NAMEQTabDialog - Stack of tabbed widgets
#include <qtabdialog.h>
Inherits QDialog.
Public Members
QTabDialog ( QWidget * parent=0, const char * name=0, bool
modal=FALSE, WFlags f=0 )
~QTabDialog ()
virtual void setFont ( const QFont & font )
void addTab ( QWidget *, const QString & )
void addTab ( QWidget * child, const QIconSet & iconset,
const QString & label )
void addTab ( QWidget *, QTab * )
void insertTab ( QWidget *, const QString &, int index =
-1 )
void insertTab ( QWidget * child, const QIconSet &
iconset, const QString & label, int index = -1 )
void insertTab ( QWidget *, QTab *, int index = -1 )
void changeTab ( QWidget *, const QString & )
void changeTab ( QWidget * child, const QIconSet &
iconset, const QString & label )
bool isTabEnabled ( QWidget * ) const
void setTabEnabled ( QWidget *, bool )
bool isTabEnabled ( const char * ) const (obsolete)
void setTabEnabled ( const char *, bool ) (obsolete)
void showPage ( QWidget * )
void removePage ( QWidget * )
QString tabLabel ( QWidget * )
QWidget* currentPage () const
void setDefaultButton ( const QString & text )
void setDefaultButton ()
bool hasDefaultButton () const
void setHelpButton ( const QString & text )
void setHelpButton ()
bool hasHelpButton () const
void setCancelButton ( const QString & text )
void setCancelButton ()
bool hasCancelButton () const
void setApplyButton ( const QString & text )
void setApplyButton ()
bool hasApplyButton () const
void setOkButton ( const QString & text )
void setOkButton ()
bool hasOkButton () const
Signals
void aboutToShow ()
void applyButtonPressed ()
void cancelButtonPressed ()
void defaultButtonPressed ()
Trolltech AS 13 June 2001 1
QTabDialog(3qt)QTabDialog(3qt)
void helpButtonPressed ()
void currentChanged ( QWidget * )
void selected ( const QString & ) (obsolete)
Protected Members
void setTabBar ( QTabBar * )
QTabBar* tabBar () const
DESCRIPTION
The QTabDialog class provides a stack of tabbed widgets.
A tabbed dialog is one in which several "pages" are
available, and the user selects which page to see and use
by clicking on its tab, or by pressing the indicated
Alt-(letter) key combination.
QTabDialog does not provide more than one row of tabs, and
does not provide tabs along the sides or bottom of the
pages. It also does not offer any way to find out which
page is currently visible or to set the visible page.
QTabDialog provides an OK button and optionally Apply,
Cancel, Defaults, and Help buttons.
The normal way to use QTabDialog is to do the following in
the constructor:
1 Create a QTabDialog.
2 Create a QWidget for each of the pages in the tab
dialog, insert children into it, set up geometry
management for it, and use addTab() to set up a tab
and keyboard accelerator for it.
3 Set up the buttons for the tab dialog (Apply,
Cancel and so on).
4 Connect to the signals and slots.
If you don't call addTab(), the page you have created will
not be visible. Please don't confuse the object name you
supply to the QWidget constructor and the tab label you
supply to addTab(): addTab() takes a name which indicates
an accelerator and is meaningful and descriptive to the
user, while the widget name is used primarily for
debugging.
Almost all applications have to connect the
applyButtonPressed() signal to something.
applyButtonPressed() is emitted when either OK or Apply is
clicked, and your slot must copy the dialog's state into
the application.
There are also several other signals which may be useful.
Trolltech AS 13 June 2001 2
QTabDialog(3qt)QTabDialog(3qt)cancelButtonPressed() is emitted when the user clicks
Cancel.
defaultButtonPressed() is emitted when the user clicks
Defaults;
helpButtonPressed() is emitted when the user clicks Help;
the slot it is connected to should reset the state of the
dialog to the application defaults.
aboutToShow() is emitted at the start of show(); if there
is any chance that the state of the application may change
between the creation of the tab dialog and the time it
show() is called, you must connect this signal to a slot
which resets the state of the dialog.
currentChanged() is emitted when the user selects some
page.
Each tab is either enabled or disabled at any given time.
If a tab is enabled, the tab text is drawn in black and
the user can select that tab. If it is disabled, the tab
is drawn in a different way and the user can not select
that tab. Note that even though a tab is disabled, the
page can still be visible, for example if all of the tabs
happen to be disabled.
While tab dialogs can be a very good way to split up a
complex dialog, it's also very easy to make a royal mess
out of a tab dialog. Here is some advice. For more, see
e.g. the UIE web page on tab dialogs.
1 Make sure that each page forms a logical whole
which is adequately described by the label on the
tab.
If two related functions are on different pages,
users will often not find one of the functions, or
will spend far too long searching for it.
2 Do not join several independent dialogs into one
tab dialog. Several aspects of one complex dialog
is acceptable (such as the various aspects of
"preferences") but a tab dialog is no substitute
for a pop-up menu leading to several smaller
dialogs.
The OK button (and the other buttons) apply to the
entire dialog. If the tab dialog is really several
independent smaller dialogs, users often press
Cancel to cancel just the changes he/she has made
on the current page: Many users will treat that
page as independent of the other pages.
Trolltech AS 13 June 2001 3
QTabDialog(3qt)QTabDialog(3qt)
3 Do not use tab dialogs for frequent operations. The
tab dialog is probably the most complex widget in
common use at the moment, and subjecting the user
to this complexity during his/her normal use of
your application is most often a bad idea.
The tab dialog is good for complex operations which
have to be performed seldom, like Preferences
dialogs. Not for common operations, like setting
left/right alignment in a word processor. (Often,
these common operations are actually independent
dialogs and should be treated as such.)
The tab dialog is not a navigational aid, it is an
organizational aid. It is a good way to organize
aspects of a complex operation (such as setting up
caching and proxies in a web browser), but a bad
way to navigate towards a simple operation (such as
emptying the cache in a web browser - emptying the
cache is not part of setting up the cache, it is a
separate and independent operation).
4 The changes should take effect when the user
presses Apply or OK. Not before.
Providing Apply, Cancel or OK buttons on the
individual pages is likely to weaken the users'
mental model of how tab dialogs work. If you think
a page needs its own buttons, consider making it a
separate dialog.
5 There should be no implicit ordering of the pages.
If there is, it is probably better to use a wizard
dialog.
If some of the pages seem to be ordered and others
not, perhaps they ought not to be joined in a tab
dialog.
Most of the functionality in QTabDialog is provided by a
QTabWidget.
[Image Omitted]
[Image Omitted]
See also QDialog.
MEMBER FUNCTION DOCUMENTATIONQTabDialog::QTabDialog ( QWidget * parent=0, const char * name=0,
bool modal=FALSE, WFlags f=0 )
Constructs a QTabDialog with only an Ok button.
Trolltech AS 13 June 2001 4
QTabDialog(3qt)QTabDialog(3qt)QTabDialog::~QTabDialog ()
Destructs the tab dialog.
void QTabDialog::aboutToShow () [signal]
This signal is emitted by show() when it's time to set the
state of the dialog's contents. The dialog should reflect
the current state of the application when if appears; if
there is any chance that the state of the application can
change between the time you call QTabDialog::QTabDialog()
and QTabDialog::show(), you should set the dialog's state
in a slot and connect this signal to it.
This applies mainly to QTabDialog objects that are kept
around hidden rather than being created, show()n and
deleted afterwards.
See also applyButtonPressed(), show() and
cancelButtonPressed().
void QTabDialog::addTab ( QWidget * child, QTab * tab )
This is a lower-level method for adding tabs, similar to
the other addTab() method. It is useful if you are using
setTabBar() to set a QTabBar subclass with an overridden
QTabBar::paint() routine for a subclass of QTab.
void QTabDialog::addTab ( QWidget * child, const QIconSet &
iconset, const QString & label )
Adds another tab and page to the tab view.
This function is the same as addTab() but with an
additional iconset.
void QTabDialog::addTab ( QWidget * child, const QString & label
)
Adds another tab and page to the tab view.
The tab will be labelled label and child constitutes the
new page. Note the difference between the widget name
(which you supply to widget constructors and to e.g.
setTabEnabled()) and the tab label: The name is internal
to the program and invariant, while the label is shown on
screen and may vary according to e.g. language.
label is written in the QButton style, where &P makes Qt
create an accelerator key on Alt-P for this page. For
example:
td->addTab( graphicsPane, "&Graphics" );
td->addTab( soundPane, "&Sound" );
If the user presses Alt-S the sound page of the tab dialog
is shown, if the user presses Alt-P the graphics page is
shown.
Trolltech AS 13 June 2001 5
QTabDialog(3qt)QTabDialog(3qt)
If you call addTab() after show(), the screen will flicker
and the user will be confused.
void QTabDialog::applyButtonPressed () [signal]
This signal is emitted when the Apply or OK buttons are
clicked.
It should be connected to a slot (or several slots) which
change the application's state according to the state of
the dialog.
See also cancelButtonPressed(), defaultButtonPressed() and
setApplyButton().
void QTabDialog::cancelButtonPressed () [signal]
This signal is emitted when the Cancel button is clicked.
It is automatically connected to QDialog::reject(), which
will hide the dialog.
The Cancel button should not change the application's
state in any way, so generally you should not need to
connect it to any slot.
See also applyButtonPressed(), defaultButtonPressed() and
setCancelButton().
void QTabDialog::changeTab ( QWidget * w, const QIconSet &
iconset, const QString & label )
Defines a new iconset and a new label for the tab of page
w
void QTabDialog::changeTab ( QWidget * w, const QString & label )
Defines a new label for the tab of page w
void QTabDialog::currentChanged ( QWidget * ) [signal]
This signal is emitted whenever the current page changes.
See also currentPage(), showPage() and tabLabel().
QWidget * QTabDialog::currentPage () const
Returns a pointer to the page currently being displayed by
the tab dialog. The tab dialog does its best to make sure
that this value is never 0, but if you try hard enough it
can be.
void QTabDialog::defaultButtonPressed () [signal]
This signal is emitted when the Defaults button is
pressed. It should reset the dialog (but not the
application) to the "factory defaults."
The application's state should not be changed until the
user clicks Apply or OK.
See also applyButtonPressed(), cancelButtonPressed() and
Trolltech AS 13 June 2001 6
QTabDialog(3qt)QTabDialog(3qt)setDefaultButton().
bool QTabDialog::hasApplyButton () const
Returns TRUE if the tab dialog has an Apply button, FALSE
if not.
See also setApplyButton(), applyButtonPressed(),
hasCancelButton() and hasDefaultButton().
bool QTabDialog::hasCancelButton () const
Returns TRUE if the tab dialog has a Cancel button, FALSE
if not.
See also setCancelButton(), cancelButtonPressed(),
hasApplyButton() and hasDefaultButton().
bool QTabDialog::hasDefaultButton () const
Returns TRUE if the tab dialog has a Defaults button,
FALSE if not.
See also setDefaultButton(), defaultButtonPressed(),
hasApplyButton() and hasCancelButton().
bool QTabDialog::hasHelpButton () const
Returns TRUE if the tab dialog has a Help button, FALSE if
not.
See also setHelpButton(), helpButtonPressed(),
hasApplyButton() and hasCancelButton().
bool QTabDialog::hasOkButton () const
Returns TRUE if the tab dialog has an OK button, FALSE if
not.
See also setOkButton(), hasApplyButton(),
hasCancelButton() and hasDefaultButton().
void QTabDialog::helpButtonPressed () [signal]
This signal is emitted when the Help button is pressed. It
should give instructions about how to use the dialog.
See also applyButtonPressed(), cancelButtonPressed() and
setHelpButton().
void QTabDialog::insertTab ( QWidget * child, QTab * tab, int
index = -1 )
This is a lower-level method for inserting tabs, similar
to the other insertTab() method. It is useful if you are
using setTabBar() to set a QTabBar subclass with an
overridden QTabBar::paint() routine for a subclass of
QTab.
void QTabDialog::insertTab ( QWidget * child, const QIconSet &
iconset, const QString & label, int index = -1 )
Trolltech AS 13 June 2001 7
QTabDialog(3qt)QTabDialog(3qt)
Inserts another tab and page to the tab view.
This function is the same as insertTab() but with an
additional iconset.
void QTabDialog::insertTab ( QWidget * child, const QString &
label, int index = -1 )
Inserts another tab and page to the tab view.
The tab will be labelled label and child constitutes the
new page. Note the difference between the widget name
(which you supply to widget constructors and to e.g.
setTabEnabled()) and the tab label: The name is internal
to the program and invariant, while the label is shown on
screen and may vary according to e.g. language.
label is written in the QButton style, where &P makes Qt
create an accelerator key on Alt-P for this page. For
example:
td->insertTab( graphicsPane, "&Graphics" );
td->insertTab( soundPane, "&Sound" );
If index is not specified, the tab is simply added.
Otherwise it's inserted at the specified position.
If the user presses Alt-S the sound page of the tab dialog
is shown, if the user presses Alt-P the graphics page is
shown.
If you call insertTab() after show(), the screen will
flicker and the user will be confused.
bool QTabDialog::isTabEnabled ( QWidget * w ) const
Returns TRUE if the page w is enabled, and false if it is
disabled.
See also setTabEnabled() and QWidget::isEnabled().
bool QTabDialog::isTabEnabled ( const char * name ) const
This function is obsolete. It is provided to keep old
source working, and will probably be removed in a future
version of Qt. We strongly advise against using it in new
code.
Returns TRUE if the page with object name name is enabled,
and false if it is disabled.
If name is 0 or not the name of any of the pages,
isTabEnabled() returns FALSE.
See also setTabEnabled() and QWidget::isEnabled().
Trolltech AS 13 June 2001 8
QTabDialog(3qt)QTabDialog(3qt)void QTabDialog::paintEvent ( QPaintEvent * ) [virtual protected]
Reimplemented for internal reasons; the API is not
affected.
Reimplemented from QWidget.
void QTabDialog::removePage ( QWidget * w )
Removes page w from this stack of widgets. Does not delete
w.
See also showPage(), QTabWidget::removePage() and
QWidgetStack::removeWidget().
void QTabDialog::resizeEvent ( QResizeEvent * e ) [virtual
protected]
Reimplemented for internal reasons; the API is not
affected.
Reimplemented from QWidget.
void QTabDialog::selected ( const QString & tabLabel ) [signal]
This function is obsolete. It is provided to keep old
source working, and will probably be removed in a future
version of Qt. We strongly advise against using it in new
code.
This signal is emitted whenever a tab is selected
(raised), including during the first show().
See also raise().
void QTabDialog::setApplyButton ()
Adds an Apply button to the dialog. The button's text is
set to a localizable "Apply".
void QTabDialog::setApplyButton ( const QString & text )
Add an Apply button to the dialog. The button's text is
set to text.
The Apply button should apply the current settings in the
dialog box to the application, while keeping the dialog
visible.
When Apply is clicked, the applyButtonPressed() signal is
emitted.
See also setCancelButton(), setDefaultButton() and
applyButtonPressed().
void QTabDialog::setCancelButton ()
Adds a Cancel button to the dialog. The button's text is
set to a localizable "Cancel".
Trolltech AS 13 June 2001 9
QTabDialog(3qt)QTabDialog(3qt)void QTabDialog::setCancelButton ( const QString & text )
Adds a Cancel button to the dialog. The button's text is
set to text.
The cancel button should always return the application to
the state it was in before the tab view popped up, or if
the user has clicked Apply, back the the state immediately
after the last Apply.
When Cancel is clicked, the cancelButtonPressed() signal
is emitted. The dialog is closed at the same time.
If text is a null string, no button is shown.
See also setApplyButton(), setDefaultButton() and
cancelButtonPressed().
void QTabDialog::setDefaultButton ()
Adds a Defaults button to the dialog. The button's text is
set to a localizable "Defaults".
void QTabDialog::setDefaultButton ( const QString & text )
Adds a Defaults button to the dialog. The button's text is
set to text.
The Defaults button should set the dialog (but not the
application) back to the application defaults.
When Defaults is clicked, the defaultButtonPressed()
signal is emitted.
If text is a null string, no button is shown.
See also setApplyButton(), setCancelButton() and
defaultButtonPressed().
void QTabDialog::setFont ( const QFont & font ) [virtual]
Sets the font for the tabs to font.
If the widget is visible, the display is updated with the
new font immediately. There may be some geometry changes,
depending on the size of the old and new fonts.
Reimplemented from QWidget.
void QTabDialog::setHelpButton ()
Adds a Help button to the dialog. The button's text is set
to a localizable "Help".
void QTabDialog::setHelpButton ( const QString & text )
Adds a Help button to the dialog. The button's text is set
to text.
When Help is clicked, the helpButtonPressed() signal is
Trolltech AS 13 June 2001 10
QTabDialog(3qt)QTabDialog(3qt)
emitted.
If text is a null string, no button is shown.
See also setApplyButton(), setCancelButton() and
helpButtonPressed().
void QTabDialog::setOkButton ()
Adds an OK to the dialog. The button's text is set to a
localizable "OK".
void QTabDialog::setOkButton ( const QString & text )
Set the OK button's text to text.
When the OK button is clicked, the applyButtonPressed()
signal is emitted, and the current settings in the dialog
box should be applied to the application. Then the dialog
closes.
If text is a null string, no button is shown.
See also setCancelButton(), setDefaultButton() and
applyButtonPressed().
void QTabDialog::setTabBar ( QTabBar * tb ) [protected]
Replaces the QTabBar heading the dialog by the given tab
bar. Note that this must be called before any tabs have
been added, or the behavior is undefined.
See also tabBar().
void QTabDialog::setTabEnabled ( QWidget * w, bool enable )
Enables/disables page w according to the value of enable,
and redraws the page's tab appropriately.
QTabWidget uses QWidget::setEnabled() internally, rather
than keep a separate flag.
Note that even a disabled tab/page may be visible. If the
page is visible already, QTabWidget will not hide it, and
if all the pages are disabled, QTabWidget will show one of
them.
See also isTabEnabled() and QWidget::setEnabled().
void QTabDialog::setTabEnabled ( const char * name, bool enable )
This function is obsolete. It is provided to keep old
source working, and will probably be removed in a future
version of Qt. We strongly advise against using it in new
code.
Finds the page with object name name, enables/disables it
according to the value of enable, and redraws the page's
tab appropriately.
Trolltech AS 13 June 2001 11
QTabDialog(3qt)QTabDialog(3qt)QTabDialog uses QWidget::setEnabled() internally, rather
than keep a separate flag.
Note that even a disabled tab/page may be visible. If the
page is visible already, QTabDialog will not hide it, and
if all the pages are disabled, QTabDialog will show one of
them.
The object name is used (rather than the tab label)
because the tab text may not be invariant in multi-
language applications.
See also isTabEnabled() and QWidget::setEnabled().
void QTabDialog::show () [virtual]
Reimplemented for internal reasons; the API is not
affected.
Examples: tabdialog/main.cpp
Reimplemented from QWidget.
void QTabDialog::showPage ( QWidget * w )
Ensures that w is shown. This is useful mainly for
accelerators.
Warning: Used carelessly, this function can easily
surprise or confuse the user.
See also QTabBar::setCurrentTab().
void QTabDialog::styleChange ( QStyle & s ) [virtual protected]
Reimplemented for internal reasons; the API is not
affected.
Reimplemented from QWidget.
QTabBar* QTabDialog::tabBar () const [protected]
Returns the currently set QTabBar.
See also setTabBar().
QString QTabDialog::tabLabel ( QWidget * w )
Returns the text in the tab for page w.
SEE ALSO
http://doc.trolltech.com/qtabdialog.html
http://www.trolltech.com/faq/tech.html
COPYRIGHT
Copyright 1992-2001 Trolltech AS,
http://www.trolltech.com. See the license file included
in the distribution for a complete license statement.
Trolltech AS 13 June 2001 12
QTabDialog(3qt)QTabDialog(3qt)AUTHOR
Generated automatically from the source code.
BUGS
If you find a bug in Qt, please report it as described in
http://doc.trolltech.com/bughowto.html. Good bug reports
make our job much simpler. Thank you.
In case of content or formattting problems with this
manual page, please report them to qt-bugs@trolltech.com.
Please include the name of the manual page
(qtabdialog.3qt) and the Qt version (2.3.1).
Trolltech AS 13 June 2001 13
