QToolBar Class

Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions |

# QToolBar Class Reference

The QToolBar class provides a movable panel containing widgets such as tool buttons. More...

`#include <qtoolbar.h>`

Inherits QDockWindow.

List of all member functions.

## Public Members

- QToolBar ( const QString & label, QMainWindow *, ToolBarDock = DockTop, bool newLine = FALSE, const char * name = 0 ) (obsolete)
- QToolBar ( const QString & label, QMainWindow * mainWindow, QWidget * parent, bool newLine = FALSE, const char * name = 0, WFlags f = 0 )
- QToolBar ( QMainWindow * parent = 0, const char * name = 0 )
- void addSeparator ()
- QMainWindow * mainWindow () const
- virtual void setStretchableWidget ( QWidget * w )
- virtual void setLabel ( const QString & )
- QString label () const
- virtual void clear ()

## Properties

- QString label - the label of the toolbar

## Detailed Description

The QToolBar class provides a movable panel containing widgets such as tool buttons.

A toolbar is a panel that contains a set of controls, usually represented by small icons. It's purpose is to provide quick access to frequently used commands or options. Within a QMainWindow the user can drag toolbars within and between the dock areas. Toolbars can also be dragged out of any dock area to float freely as top level windows.

QToolBar is a specialization of QDockWindow, and so provides all the functionality of a QDockWindow.

To use QToolBar you simply create a QToolBar as a child of a QMainWindow, create a number of QToolButton widgets (or other widgets) in left to right (or top to bottom) order and call addSeparator() when you want a separator. When a toolbar is floated the caption used is the label given in the constructor call. This can be changed with setLabel().

            QToolBar * fileTools = new QToolBar( this, "file operations" );
            fileTools->setLabel( "File Operations" );
            fileOpenAction->addTo( fileTools );
            fileSaveAction->addTo( fileTools );

This extract from the application/application.cpp example shows the creation of a new toolbar as a child of a QMainWindow and adding two QActions.

You may use most widgets within a toolbar, with QToolButton and QComboBox being the most common.

Note that if you create a new widget on a already visible QToolBar, this widget becomes automatically visible without explicitly calling show() on it (unlike in all other widget containers in Qt). Please call explicitly show() on all widgets you put into an already visible QToolBar anyway, as this behavior might be fixed in the future.

QToolBars, like QDockWindows, are located in QDockAreas or float as top level windows. QMainWindow provides four QDockAreas (top, left, right and bottom). When you create a new toolbar (as in the example above) as a child of a QMainWindow the toolbar will be added to the top dock area. You can move it to another dock area (or float it) by calling QMainWindow::moveDockWindow(). QDock areas lay out their windows in Lines.

If the main window is resized so that the area occupied by the toolbar is too small to show all its widgets a little arrow button (which looks like a right-pointing chevron, '»') will appear at the right or bottom of the toolbar depending on its orientation. Clicking this button pops up a menu that shows the 'overflowing' items.

Usually a toolbar will get precisely the space it needs. However, with setHorizontalStretchable(), setVerticalStretchable() or setStretchableWidget() you can tell the main window to expand the toolbar to fill all available space in the specified orientation.

The toolbar arranges its buttons either horizontally or vertically (see orientation() for details). Generally, QDockArea will set the orientation correctly for you, but you can set it yourself with setOrientation() and track any changes by connecting to the orientationChanged() signal.

You can use the clear() method to remove all items from a toolbar.

> A floating QToolbar (dock window)

See also QToolButton, QMainWindow, Parts of Isys on Visual Design, GUI Design Handbook: Tool Bar and Main Window and Related Classes.

## Member Function Documentation

### QToolBar::QToolBar ( const QString & label, QMainWindow *, ToolBarDock = DockTop, bool newLine = FALSE, const char * name = 0 )

This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.

### QToolBar::QToolBar ( const QString & label, QMainWindow * mainWindow, QWidget * parent, bool newLine = FALSE, const char * name = 0, WFlags f = 0 )

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Constructs an empty horizontal toolbar.

The toolbar is a child of parent and is managed by mainWindow. The label and newLine parameters are passed straight to QMainWindow::addDockWindow(). name is the object name and f is the widget flags.

Use this constructor if you want to create torn-off (undocked, floating) toolbars or toolbars in the status bar.

### QToolBar::QToolBar ( QMainWindow * parent = 0, const char * name = 0 )

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Constructs an empty toolbar, with parent parent and name name, in its parent's top dock area, without any label and without requiring a newline.

### void QToolBar::addSeparator ()

Adds a separator to the right/bottom of the toolbar.

Examples: fileiconview/mainwindow.cpp, helpviewer/helpwindow.cpp, qfd/fontdisplayer.cpp and scribble/scribble.cpp.

### void QToolBar::clear ()`[virtual]`

Deletes all the toolbar's child widgets.

### QString QToolBar::label () const

Returns the label of the toolbar. See the "label" property for details.

### QMainWindow * QToolBar::mainWindow () const

Returns a pointer to the QMainWindow which manages this toolbar.

### void QToolBar::setLabel ( const QString & )`[virtual]`

Sets the label of the toolbar. See the "label" property for details.

### void QToolBar::setStretchableWidget ( QWidget * w )`[virtual]`

Sets the widget w to be expanded if this toolbar is requested to stretch.

The request to stretch might occur because QMainWindow right-justifies the dock it's in, or because this toolbar's isVerticalStretchable() or isHorizontalStretchable() is set to TRUE.

If you call this function and the toolbar is not yet stretchable, setStretchable() is called.

See also QMainWindow::rightJustification, setVerticalStretchable() and setHorizontalStretchable().

Examples: fileiconview/mainwindow.cpp and helpviewer/helpwindow.cpp.

## Property Documentation

### QString label

This property holds the label of the toolbar.

If the toolbar is floated the label becomes the toolbar window's caption. There is no default label text.

Set this property's value with setLabel() and get this property's value with label().

This file is part of the Qt toolkit. Copyright © 1995-2002 Trolltech. All Rights Reserved.