TQTabBar Class Reference

The TQTabBar class provides a tab bar, e.g. for use in tabbed dialogs. More...

#include <tqtabbar.h>

Inherits TQWidget.

List of all member functions.

Public Members

TQTabBar ( TQWidget * parent = 0, const char * name = 0 )
~TQTabBar ()
enum Shape { RoundedAbove, RoundedBelow, TriangularAbove, TriangularBelow }
Shape shape () const
virtual void setShape ( Shape )
virtual int addTab ( TQTab * newTab )
virtual int insertTab ( TQTab * newTab, int index = -1 )
virtual void removeTab ( TQTab * t )
virtual void setTabEnabled ( int id, bool enabled )
bool isTabEnabled ( int id ) const
int currentTab () const
int keyboardFocusTab () const
TQTab * tab ( int id ) const
TQTab * tabAt ( int index ) const
int indexOf ( int id ) const
int count () const
virtual void layoutTabs ()
virtual TQTab * selectTab ( const TQPoint & p ) const
void removeToolTip ( int index )
void setToolTip ( int index, const TQString & tip )
TQString toolTip ( int index ) const

Public Slots

virtual void setCurrentTab ( int )
virtual void setCurrentTab ( TQTab * tab )

Signals

void selected ( int id )
void layoutChanged ()

Properties

int count - the number of tabs in the tab bar (read only)
int currentTab - the id of the tab bar's visible tab
int keyboardFocusTab - the id of the tab that has the keyboard focus (read only)
Shape shape - the shape of the tabs in the tab bar

Protected Members

virtual void paint ( TQPainter * p, TQTab * t, bool selected ) const
virtual void paintLabel ( TQPainter * p, const TQRect & br, TQTab * t, bool has_focus ) const
virtual void paintEvent ( TQPaintEvent * e )
TQPtrList<TQTab> * tabList ()

Detailed Description

The TQTabBar class provides a tab bar, e.g. for use in tabbed dialogs.

TQTabBar 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. TQt also provides a ready-made TQTabWidget and a TQTabDialog.

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 TQTabBar'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.

TQTabBar creates automatic accelerator keys in the manner of TQButton; 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.

Member Type Documentation

TQTabBar::Shape

This enum type lists the built-in shapes supported by TQTabBar:

TQTabBar::RoundedAbove - the normal rounded look above the pages
TQTabBar::RoundedBelow - the normal rounded look below the pages
TQTabBar::TriangularAbove - triangular tabs above the pages (very unusual; included for completeness)
TQTabBar::TriangularBelow - triangular tabs similar to those used in the Excel spreadsheet, for example

Member Function Documentation

TQTabBar::TQTabBar ( TQWidget * parent = 0, const char * name = 0 )

Constructs a new, empty tab bar; the parent and name arguments are passed on to the TQWidget constructor.

TQTabBar::~TQTabBar ()

Destroys the tab control, freeing memory used.

int TQTabBar::addTab ( TQTab * 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.

int TQTabBar::count () const

Returns the number of tabs in the tab bar. See the "count" property for details.

int TQTabBar::currentTab () const

Returns the id of the tab bar's visible tab. See the "currentTab" property for details.

int TQTabBar::indexOf ( int id ) const

Returns the position index of the tab with id id or -1 if no tab has this id.

int TQTabBar::insertTab ( TQTab * 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.

bool TQTabBar::isTabEnabled ( int id ) const

Returns TRUE if the tab with id id exists and is enabled; otherwise returns FALSE.

int TQTabBar::keyboardFocusTab () const

Returns the id of the tab that has the keyboard focus. See the "keyboardFocusTab" property for details.

void TQTabBar::layoutChanged () `[signal]`

TQTabBar emits the signal whenever the layout of the tab bar has been recalculated, for example when the contents of a tab change.

void TQTabBar::layoutTabs () `[virtual]`

Lays out all existing tabs according to their label and their iconset.

void TQTabBar::paint ( TQPainter * p, TQTab * 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 TQTabBar. If you decide to reimplement it, you may also need to reimplement sizeHint().

void TQTabBar::paintEvent ( TQPaintEvent * 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.

void TQTabBar::paintLabel ( TQPainter * p, const TQRect & br, TQTab * 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 TQTabBar::removeTab ( TQTab * t ) `[virtual]`

Removes tab t from the tab control, and deletes the tab.

void TQTabBar::removeToolTip ( int index )

Removes the tool tip for the tab at index position index.

TQTab * TQTabBar::selectTab ( const TQPoint & 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 TQTabBar::selected ( int id ) `[signal]`

TQTabBar 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 TQTabBar::setCurrentTab ( int ) `[virtual slot]`

Sets the id of the tab bar's visible tab. See the "currentTab" property for details.

void TQTabBar::setCurrentTab ( TQTab * 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.

void TQTabBar::setShape ( Shape ) `[virtual]`

Sets the shape of the tabs in the tab bar. See the "shape" property for details.

void TQTabBar::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.

void TQTabBar::setToolTip ( int index, const TQString & tip )

Sets the tool tip for the tab at index position index to tip.

Shape TQTabBar::shape () const

Returns the shape of the tabs in the tab bar. See the "shape" property for details.

TQTab * TQTabBar::tab ( int id ) const

Returns the tab with id id or 0 if there is no such tab.

TQTab * TQTabBar::tabAt ( int index ) const

Returns the tab at position index.

TQPtrList<TQTab> * TQTabBar::tabList () `[protected]`

The list of TQTab objects in the tab bar.

This list is unlikely to be in the order that the TQTab 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
    }

TQString TQTabBar::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().

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.

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().

Shape shape

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.