kdeui Library API Documentation
Overview Class Hierarchy Classes Classes (annotated) Members Namespaces Source Files

KToolBar Class Reference

Floatable toolbar with auto resize. More...

#include <ktoolbar.h>

Inheritance diagram for KToolBar:

Inheritance graph
[legend]
Collaboration diagram for KToolBar:

Collaboration graph
[legend]
List of all members.

Public Types

enum  IconText { IconOnly = 0, IconTextRight, TextOnly, IconTextBottom }
enum  BarStatus { Toggle, Show, Hide }
enum  BarPosition {
  Unmanaged, Floating, Top, Bottom,
  Right, Left, Flat
}

Public Slots

virtual void setIconText (const QString &txt)

Signals

void clicked (int id)
void doubleClicked (int id)
void pressed (int)
void released (int)
void toggled (int)
void highlighted (int id, bool isHighlighted)
void highlighted (int id)
void moved (BarPosition)
void modechange ()
void toolbarDestroyed ()

Public Member Functions

 KToolBar (QWidget *parent, const char *name=0, bool honorStyle=false, bool readConfig=true)
 KToolBar (QMainWindow *parentWindow, QMainWindow::ToolBarDock dock, bool newLine=false, const char *name=0, bool honorStyle=false, bool readConfig=true)
 KToolBar (QMainWindow *parentWindow, QWidget *dock, bool newLine=false, const char *name=0, bool honorStyle=false, bool readConfig=true)
virtual ~KToolBar ()
int insertButton (const QString &icon, int id, bool enabled=true, const QString &text=QString::null, int index=-1, KInstance *_instance=KGlobal::instance())
int insertButton (const QString &icon, int id, const char *signal, const QObject *receiver, const char *slot, bool enabled=true, const QString &text=QString::null, int index=-1, KInstance *_instance=KGlobal::instance())
int insertButton (const QPixmap &pixmap, int id, bool enabled=true, const QString &text=QString::null, int index=-1)
int insertButton (const QPixmap &pixmap, int id, const char *signal, const QObject *receiver, const char *slot, bool enabled=true, const QString &text=QString::null, int index=-1)
int insertButton (const QString &icon, int id, QPopupMenu *popup, bool enabled, const QString &_text, int index=-1)
int insertButton (const QPixmap &pixmap, int id, QPopupMenu *popup, bool enabled, const QString &_text, int index=-1)
int insertLined (const QString &text, int id, const char *signal, const QObject *receiver, const char *slot, bool enabled=true, const QString &toolTipText=QString::null, int size=70, int index=-1)
int insertCombo (const QStringList &list, int id, bool writable, const char *signal, const QObject *receiver, const char *slot, bool enabled=true, const QString &tooltiptext=QString::null, int size=70, int index=-1, QComboBox::Policy policy=QComboBox::AtBottom)
int insertCombo (const QString &text, int id, bool writable, const char *signal, QObject *receiver, const char *slot, bool enabled=true, const QString &tooltiptext=QString::null, int size=70, int index=-1, QComboBox::Policy policy=QComboBox::AtBottom)
int insertSeparator (int index=-1, int id=-1)
int insertLineSeparator (int index=-1, int id=-1)
int insertWidget (int id, int width, QWidget *_widget, int index=-1)
int insertAnimatedWidget (int id, QObject *receiver, const char *slot, const QString &icons, int index=-1)
KAnimWidget * animatedWidget (int id)
void addConnection (int id, const char *signal, const QObject *receiver, const char *slot)
void setItemEnabled (int id, bool enabled)
void setButtonIcon (int id, const QString &_icon)
void setButtonPixmap (int id, const QPixmap &_pixmap)
void setButtonIconSet (int id, const QIconSet &iconset)
void setDelayedPopup (int id, QPopupMenu *_popup, bool toggle=false)
void setAutoRepeat (int id, bool flag=true)
void setToggle (int id, bool flag=true)
void toggleButton (int id)
void setButton (int id, bool flag)
bool isButtonOn (int id) const
void setLinedText (int id, const QString &text)
QString getLinedText (int id) const
void insertComboItem (int id, const QString &text, int index)
void insertComboList (int id, const QStringList &list, int index)
void removeComboItem (int id, int index)
void setCurrentComboItem (int id, int index)
void changeComboItem (int id, const QString &text, int index=-1)
void clearCombo (int id)
QString getComboItem (int id, int index=-1) const
KComboBox * getCombo (int id)
KLineEdit * getLined (int id)
KToolBarButton * getButton (int id)
void alignItemRight (int id, bool right=true)
QWidget * getWidget (int id)
void setItemAutoSized (int id, bool yes=true)
void clear ()
void removeItem (int id)
void removeItemDelayed (int id)
void hideItem (int id)
void showItem (int id)
int itemIndex (int id)
int idAt (int index)
void setFullSize (bool flag=true)
bool fullSize () const
void enableMoving (bool flag=true) KDE_DEPRECATED
void setBarPos (BarPosition bpos)
BarPosition barPos () const
bool enable (BarStatus stat) KDE_DEPRECATED
void setMaxHeight (int h) KDE_DEPRECATED
int maxHeight () KDE_DEPRECATED
void setMaxWidth (int dw) KDE_DEPRECATED
int maxWidth () KDE_DEPRECATED
void setTitle (const QString &_title)
void enableFloating (bool flag) KDE_DEPRECATED
void setIconText (IconText it)
void setIconText (IconText it, bool update)
IconText iconText () const
void setIconSize (int size)
void setIconSize (int size, bool update)
int iconSize () const
void setEnableContextMenu (bool enable=true)
bool contextMenuEnabled () const
void setItemNoStyle (int id, bool no_style=true)
void setFlat (bool flag)
int count () const
void saveState ()
void saveSettings (KConfig *config, const QString &configGroup)
void applySettings (KConfig *config, const QString &configGroup)
void setXMLGUIClient (KXMLGUIClient *client)
void setText (const QString &txt)
QString text () const
void setStretchableWidget (QWidget *w)
QSizePolicy sizePolicy () const
bool highlight () const
QSize sizeHint () const
QSize minimumSizeHint () const
QSize minimumSize () const
void hide ()
void show ()
void updateRects (bool=false)
void loadState (const QDomElement &e)
void saveState (QDomElement &e)
void positionYourself (bool force=false)

Static Public Member Functions

bool highlightSetting ()
bool transparentSetting ()
IconText iconTextSetting ()

Protected Member Functions

void mousePressEvent (QMouseEvent *)
void childEvent (QChildEvent *e)
void showEvent (QShowEvent *e)
void resizeEvent (QResizeEvent *e)
bool event (QEvent *e)
void applyAppearanceSettings (KConfig *config, const QString &_configGroup, bool forceGlobal=false)
QString settingsGroup () const
virtual void virtual_hook (int id, void *data)

Detailed Description

Floatable toolbar with auto resize.

A KDE-style toolbar.

KToolBar can be dragged around in and between different docks.

A KToolBar can contain all sorts of widgets.

KToolBar can be used as a standalone widget, but KMainWindow provides easy factories and management of one or more toolbars. Once you have a KToolBar object, you can insert items into it with the insert... methods, or remove them with the removeItem() method. This can be done at any time; the toolbar will be automatically updated. There are also many methods to set per-child properties like alignment and toggle behavior.

KToolBar uses a global config group to load toolbar settings on construction. It will reread this config group on a KApplication::appearanceChanged() signal.

Version:
Id
ktoolbar.h,v 1.176 2003/11/05 11:43:22 tokoe Exp
Author:
Reginald Stadlbauer <reggie@kde.org>, Stephan Kulow <coolo@kde.org>, Sven Radej <radej@kde.org>.

Definition at line 103 of file ktoolbar.h.

Member Enumeration Documentation

enum KToolBar::BarStatus
 

The state of the status bar.

Deprecated:

Definition at line 119 of file ktoolbar.h.

enum KToolBar::BarPosition
 

Possible bar positions.

Definition at line 123 of file ktoolbar.h.

Referenced by barPos().

Constructor & Destructor Documentation

KToolBar::KToolBar (  QWidget *  parent,
const char *  name = 0,
bool  honorStyle = false,
bool  readConfig = true
) 
 

Normal constructor.

This constructor is used by the XML-GUI. If you use it, you need to call QMainWindow::addToolBar to specify the position of the toolbar. So it's simpler to use the other constructor.

The toolbar will read in various global config settings for things like icon size and text position, etc. However, some of the settings will be honored only if honorStyle is set to true. All other toolbars will be IconOnly and use Medium icons.

Parameters:
parent The standard toolbar parent (usually a KMainWindow)
name The standard internal name
honorStyle If true, then global settings for IconSize and IconText will be honored
readConfig whether to apply the configuration (global and application-specific)

Definition at line 201 of file ktoolbar.cpp.

KToolBar::KToolBar (  QMainWindow *  parentWindow,
QMainWindow::ToolBarDock  dock,
bool  newLine = false,
const char *  name = 0,
bool  honorStyle = false,
bool  readConfig = true
) 
 

Constructor for non-XML-GUI applications.

The toolbar will read in various global config settings for things like icon size and text position, etc. However, some of the settings will be honored only if honorStyle is set to true. All other toolbars will be IconOnly and use Medium icons.

Parameters:
parentWindow The window that should be the parent of this toolbar
dock The position of the toolbar. Usually QMainWindow::Top.
newLine If true, start a new line in the dock for this toolbar.
name The standard internal name
honorStyle If true, then global settings for IconSize and IconText will be honored
readConfig whether to apply the configuration (global and application-specific)

Definition at line 210 of file ktoolbar.cpp.

KToolBar::KToolBar (  QMainWindow *  parentWindow,
QWidget *  dock,
bool  newLine = false,
const char *  name = 0,
bool  honorStyle = false,
bool  readConfig = true
) 
 

Constructor for non-XML-GUI applications.

The toolbar will read in various global config settings for things like icon size and text position, etc. However, some of the settings will be honored only if honorStyle is set to true. All other toolbars will be IconOnly and use Medium icons.

Parameters:
parentWindow The window that should be the parent of this toolbar
dock Another widget than the mainwindow to dock toolbar to.
newLine If true, start a new line in the dock for this toolbar.
name The standard internal name
honorStyle If true, then global settings for IconSize and IconText will be honored
readConfig whether to apply the configuration (global and application-specific)

Definition at line 218 of file ktoolbar.cpp.

KToolBar::~KToolBar (   )  [virtual]
 

Destructor.

Definition at line 226 of file ktoolbar.cpp.

References toolbarDestroyed().

Member Function Documentation

int KToolBar::insertButton (  const QString &  icon,
int  id,
bool  enabled = true,
const QString &  text = QString::null,
int  index = -1,
KInstance *  _instance = KGlobal::instance()
) 
 

Insert a button (a KToolBarButton) with a pixmap.

The pixmap is loaded by the button itself based on the global icon settings.

You should connect to one or more signals in KToolBar: clicked() , pressed() , released() , or highlighted() and if the button is a toggle button ( setToggle() ) toggled() . Those signals have id of a button that caused the signal. If you want to bind a popup to button, see setButton().

Parameters:
icon The name of the icon to use as the active pixmap
id The id of this button
enabled Enable or disable the button at startup
text The tooltip or toolbar text (depending on state)
index The position of the button. (-1 = at end).
Returns:
The item index.

Definition at line 267 of file ktoolbar.cpp.

Referenced by KPasteTextAction::plug(), KToolBarPopupAction::plug(), KActionMenu::plug(), KRecentFilesAction::plug(), and KAction::plug().

int KToolBar::insertButton (  const QString &  icon,
int  id,
const char *  signal,
const QObject *  receiver,
const char *  slot,
bool  enabled = true,
const QString &  text = QString::null,
int  index = -1,
KInstance *  _instance = KGlobal::instance()
) 
 

This is the same as above, but with specified signals and slots to which this button will be connected.

You can add more signals with addConnection().

Parameters:
icon The name of the icon to use as the active pixmap
id The id of this button
signal The signal to connect to
receiver The slot's parent
slot The slot to receive the signal specified in that argument.
enabled Enable or disable the button at startup
text The tooltip or toolbar text (depending on state)
index The position of the button. (-1 = at end).
Returns:
The item index.

Definition at line 279 of file ktoolbar.cpp.

int KToolBar::insertButton (  const QPixmap &  pixmap,
int  id,
bool  enabled = true,
const QString &  text = QString::null,
int  index = -1
) 
 

Inserts a button (a KToolBarButton) with the specified pixmap.

This pixmap will be used as the "active" one and the disabled and default ones will be autogenerated.

It is recommended that you use the insertButton function that allows you to specify the icon name rather then the pixmap itself. Specifying the icon name is much more flexible.

You should connect to one or more signals in KToolBar: clicked() , pressed() , released() , or highlighted() and if the button is a toggle button ( setToggle() ) toggled() . Those signals have id of a button that caused the signal. If you want to bind a popup to button, see setButton().

Parameters:
pixmap The active pixmap
id The id of this button
enabled Enable or disable the button at startup
text The tooltip or toolbar text (depending on state)
index The position of the button. (-1 = at end).
Returns:
The item index.

Definition at line 292 of file ktoolbar.cpp.

int KToolBar::insertButton (  const QPixmap &  pixmap,
int  id,
const char *  signal,
const QObject *  receiver,
const char *  slot,
bool  enabled = true,
const QString &  text = QString::null,
int  index = -1
) 
 

This is the same as above, but with specified signals and slots to which this button will be connected.

You can add more signals with addConnection().

Parameters:
pixmap The name of the icon to use as the active pixmap
id The id of this button
signal The signal to connect to
receiver The slot's parent
slot The slot to receive the signal specified in that argument.
enabled Enable or disable the button at startup
text The tooltip or toolbar text (depending on state)
index The position of the button. (-1 = at end).
Returns:
The item index.

Definition at line 303 of file ktoolbar.cpp.

int KToolBar::insertButton (  const QString &  icon,
int  id,
QPopupMenu *  popup,
bool  enabled,
const QString &  _text,
int  index = -1
) 
 

Inserts a button with popupmenu.

Button will have small triangle. You have to connect to popup's signals. The signals KButton::pressed(), KButton::released(), KButton::clicked() or KButton::doubleClicked() are not emmited by this button (see setDelayedPopup() for that). You can add custom popups which inherit QPopupMenu to get popups with tables, drawings etc. Just don't fiddle with events there.

Definition at line 317 of file ktoolbar.cpp.

References KToolBarButton::setPopup().

int KToolBar::insertButton (  const QPixmap &  pixmap,
int  id,
QPopupMenu *  popup,
bool  enabled,
const QString &  _text,
int  index = -1
) 
 

Inserts a button with popupmenu.

Button will have small triangle. You have to connect to popup's signals. The signals KButton::pressed(), KButton::released(), KButton::clicked() or KButton::doubleClicked() are not emmited by this button (see setDelayedPopup() for that). You can add custom popups which inherit QPopupMenu to get popups with tables, drawings etc. Just don't fiddle with events there.

Definition at line 329 of file ktoolbar.cpp.

References KToolBarButton::setPopup().

int KToolBar::insertLined (  const QString &  text,
int  id,
const char *  signal,
const QObject *  receiver,
const char *  slot,
bool  enabled = true,
const QString &  toolTipText = QString::null,
int  size = 70,
int  index = -1
) 
 

Inserts a KLineEdit.

You have to specify signals and slots to which KLineEdit will be connected. KLineEdit has all slots QLineEdit has, plus signals KLineEdit::completion and KLineEdit::textRotation KLineEdit can be set to autoresize itself to full free width in toolbar, that is to last right aligned item. For that, toolbar must be set to full width (which it is by default).

See also:
setFullWidth()

setItemAutoSized()

KLineEdit

Returns:
Item index.

Definition at line 341 of file ktoolbar.cpp.

References QToolTip::add(), QString::isEmpty(), and KLineEdit::setText().

int KToolBar::insertCombo (  const QStringList &  list,
int  id,
bool  writable,
const char *  signal,
const QObject *  receiver,
const char *  slot,
bool  enabled = true,
const QString &  tooltiptext = QString::null,
int  size = 70,
int  index = -1,
QComboBox::Policy  policy = QComboBox::AtBottom
) 
 

Inserts a KComboBox with list.

Can be writable, but cannot contain pixmaps. By default inserting policy is AtBottom, i.e. typed items are placed at the bottom of the list. Can be autosized. If the size argument is specified as -1, the width of the combobox is automatically computed.

See also:
setFullWidth()

setItemAutoSized()

KComboBox

Returns:
Item index.

Definition at line 360 of file ktoolbar.cpp.

References QToolTip::add(), QComboBox::insertStringList(), QString::isEmpty(), QString::isNull(), and QComboBox::setInsertionPolicy().

Referenced by KSelectAction::plug().

int KToolBar::insertCombo (  const QString &  text,
int  id,
bool  writable,
const char *  signal,
QObject *  receiver,
const char *  slot,
bool  enabled = true,
const QString &  tooltiptext = QString::null,
int  size = 70,
int  index = -1,
QComboBox::Policy  policy = QComboBox::AtBottom
) 
 

Insert a KComboBox with text.

The rest is the same as above.

See also:
setItemAutoSized()

KComboBox

Returns:
Item index.

Definition at line 386 of file ktoolbar.cpp.

References QToolTip::add(), QComboBox::insertItem(), QString::isEmpty(), QString::isNull(), and QComboBox::setInsertionPolicy().

int KToolBar::insertSeparator (  int  index = -1,
int  id = -1
) 
 

Inserts a separator into the toolbar with the given id.

Returns:
the separator's index

Definition at line 408 of file ktoolbar.cpp.

int KToolBar::insertLineSeparator (  int  index = -1,
int  id = -1
) 
 

Inserts a line separator into the toolbar with the given id.

Returns:
the separator's index

Definition at line 415 of file ktoolbar.cpp.

int KToolBar::insertWidget (  int  id,
int  width,
QWidget *  _widget,
int  index = -1
) 
 

Inserts a user-defined widget.

The widget must have this toolbar as its parent.

Widget must have a QWidget for base class. Widget can be autosized to full width. If you forget about it, you can get a pointer to this widget with getWidget().

See also:
setItemAutoSized()
Returns:
Item index.

Definition at line 423 of file ktoolbar.cpp.

Referenced by KWidgetAction::plug().

int KToolBar::insertAnimatedWidget (  int  id,
QObject *  receiver,
const char *  slot,
const QString &  icons,
int  index = -1
) 
 

Inserts an animated widget.

A KAnimWidget will be created internally using the icon name you provide. This will emit a signal (clicked()) whenever the animation widget is clicked.

See also:
animatedWidget()
Parameters:
id The id for this toolbar item
receiver The parent of your slot
slot The slot to receive the clicked() signal
icons The name of the animation icon group to use
index The item index
Returns:
The item index

Definition at line 430 of file ktoolbar.cpp.

References clicked().

KAnimWidget * KToolBar::animatedWidget (  int  id  ) 
 

This will return a pointer to the animated widget with the given id, if it exists.

See also:
insertAnimatedWidget
Parameters:
id The id for the widget you want to get a pointer to
Returns:
A pointer to the current animated widget or 0L

Definition at line 442 of file ktoolbar.cpp.

References QMap::end(), and QMap::find().

void KToolBar::addConnection (  int  id,
const char *  signal,
const QObject *  receiver,
const char *  slot
) 
 

Adds connections to items.

It is important that you know the id of particular item. Nothing happens if you forget id.

Definition at line 470 of file ktoolbar.cpp.

References QMap::end(), and QMap::find().

void KToolBar::setItemEnabled (  int  id,
bool  enabled
) 
 

Enables/disables item.

Definition at line 480 of file ktoolbar.cpp.

References QMap::end(), and QMap::find().

void KToolBar::setButtonIcon (  int  id,
const QString &  _icon
) 
 

Sets the icon for a button.

Can be used while button is visible.

Definition at line 501 of file ktoolbar.cpp.

References QMap::end(), QMap::find(), and KToolBarButton::setIcon().

void KToolBar::setButtonPixmap (  int  id,
const QPixmap &  _pixmap
) 
 

Sets button pixmap.

Can be used while button is visible.

Definition at line 490 of file ktoolbar.cpp.

References QMap::end(), QMap::find(), and KToolBarButton::setPixmap().

void KToolBar::setButtonIconSet (  int  id,
const QIconSet &  iconset
) 
 

Sets a button icon from a QIconSet.

Can be used while button is visible.

Definition at line 511 of file ktoolbar.cpp.

References QMap::end(), QMap::find(), and KToolBarButton::setIconSet().

void KToolBar::setDelayedPopup (  int  id,
QPopupMenu *  _popup,
bool  toggle = false
) 
 

Sets a delayed popup for a button.

Delayed popup is what you see in Netscape Navigator's Previous and Next buttons: If you click them you go back or forth. If you press them long enough, you get a history-menu. This is exactly what we do here.

You will insert a normal button with connection (or use signals from toolbar): 

 bar->insertButton(icon, id, SIGNAL(clicked ()), this,
                   SLOT (slotClick()), true, "click or wait for popup");
And then add a delayed popup: 
 bar->setDelayedPopup (id, historyPopup);

Don't add delayed popups to buttons which have normal popups.

You may add popups which are derived from QPopupMenu. You may add popups that are already in the menu bar or are submenus of other popups.

Definition at line 522 of file ktoolbar.cpp.

References QMap::end(), QMap::find(), and KToolBarButton::setDelayedPopup().

Referenced by KPasteTextAction::plug(), KToolBarPopupAction::plug(), KActionMenu::plug(), and KRecentFilesAction::plug().

void KToolBar::setAutoRepeat (  int  id,
bool  flag = true
) 
 

Turns a button into an autorepeat button.

Toggle buttons, buttons with menus, or buttons with delayed menus cannot be made into autorepeat buttons. Moreover, you can and will receive only the signal clicked(), but not pressed() or released(). When the user presses this button, you will receive the signal clicked(), and if the button is still pressed after some time, you will receive more clicked() signals separated by regular intervals. Since this uses QButton::setAutoRepeat() , I can't quantify 'some'.

Definition at line 533 of file ktoolbar.cpp.

References QMap::end(), and QMap::find().

void KToolBar::setToggle (  int  id,
bool  flag = true
) 
 

Turns button into a toggle button if flag is true.

Definition at line 544 of file ktoolbar.cpp.

References QMap::end(), QMap::find(), and KToolBarButton::setToggle().

Referenced by KToggleAction::plug().

void KToolBar::toggleButton (  int  id  ) 
 

Toggles a togglebutton.

If the button is a toggle button (see setToggle()) the button state will be toggled. This will also cause the toolbar to emit the signal KButton::toggled() with parameter id. You must connect to this signal, or use addConnection() to connect directly to the button signal KButton::toggled().

Definition at line 555 of file ktoolbar.cpp.

References QMap::end(), QMap::find(), and KToolBarButton::toggle().

void KToolBar::setButton (  int  id,
bool  flag
) 
 

Sets a toggle button state.

If the button is a toggle button (see setToggle()) this will set its state flag. This will also emit the signal KButton::toggled().

See also:
setToggle()

Definition at line 566 of file ktoolbar.cpp.

References QMap::end(), QMap::find(), and KToolBarButton::on().

Referenced by KToggleAction::plug().

bool KToolBar::isButtonOn (  int  id  )  const
 

Returns true if button is on and is a toggle button.

Returns:
true if button is on and is a toggle button
See also:
setToggle()

Definition at line 577 of file ktoolbar.cpp.

References QMap::end(), and QMap::find().

void KToolBar::setLinedText (  int  id,
const QString &  text
) 
 

Sets the text of a line editor.

Cursor is set at end of text.

Definition at line 587 of file ktoolbar.cpp.

References QMap::end(), QMap::find(), and QLineEdit::setText().

QString KToolBar::getLinedText (  int  id  )  const
 

Returns the line editor text.

Returns:
the line editor text.

Definition at line 598 of file ktoolbar.cpp.

References QMap::end(), QMap::find(), and QLineEdit::text().

void KToolBar::insertComboItem (  int  id,
const QString &  text,
int  index
) 
 

Inserts text in combobox id at position index.

Definition at line 608 of file ktoolbar.cpp.

References QMap::end(), QMap::find(), and QComboBox::insertItem().

void KToolBar::insertComboList (  int  id,
const QStringList &  list,
int  index
) 
 

Inserts list in combobox id at position index.

Definition at line 618 of file ktoolbar.cpp.

References QMap::end(), QMap::find(), and QComboBox::insertStringList().

void KToolBar::removeComboItem (  int  id,
int  index
) 
 

Removes item index from combobox id.

Definition at line 629 of file ktoolbar.cpp.

References QMap::end(), QMap::find(), and QComboBox::removeItem().