|
|
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 behaviour.
KToolBar uses a global config group to load toolbar settings on construction. It will reread this config group on a KApplication::appearanceChanged() signal.
| enum IconText {IconOnly = 0, IconTextRight, TextOnly, IconTextBottom} | IconText |
| enum BarStatus {Toggle, Show, Hide} | BarStatus |
The state of the status bar.
| enum BarPosition { Unmanaged, Floating, Top, Bottom, Right, Left, Flat} | BarPosition |
Possible bar positions.
| KToolBar ( QWidget *parent, const char *name = 0, bool honor_style = FALSE, bool readConfig = TRUE )
| KToolBar |
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 _honor_mode 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 |
| honor_style | If true, then global settings for IconSize and IconText will be honored |
| readConfig | whether to apply the configuration (global and application-specific) |
| KToolBar ( QMainWindow *parentWindow, QMainWindow::ToolBarDock dock , bool newLine = false,
const char *name = 0, bool honor_style = FALSE, bool readConfig = TRUE )
| KToolBar |
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 _honor_mode 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 |
| honor_style | If true, then global settings for IconSize and IconText will be honored |
| readConfig | whether to apply the configuration (global and application-specific) |
| KToolBar ( QMainWindow *parentWindow, QWidget *dock, bool newLine = false,
const char *name = 0, bool honor_style = FALSE, bool readConfig = TRUE )
| KToolBar |
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 _honor_mode 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 |
| honor_style | If true, then global settings for IconSize and IconText will be honored |
| readConfig | whether to apply the configuration (global and application-specific) |
| ~KToolBar ()
| ~KToolBar |
[virtual]
| int insertButton (const QString& icon, int id, bool enabled = true,
const QString& text = QString::null, int index=-1,
KInstance *_instance = KGlobal::instance())
| insertButton |
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.
| 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() )
| insertButton |
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 |
| 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.
| int insertButton (const QPixmap& pixmap, int id, bool enabled = true,
const QString& text = QString::null, int index=-1 )
| insertButton |
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.
| 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 )
| insertButton |
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 |
| 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.
| int insertButton (const QString& icon, int id, QPopupMenu *popup,
bool enabled, const QString&_text, int index=-1)
| insertButton |
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.
| int insertButton (const QPixmap& pixmap, int id, QPopupMenu *popup,
bool enabled, const QString&_text, int index=-1)
| insertButton |
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.
| 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)
| insertLined |
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).
Returns: Item index.
See also: KLineEdit, setItemAutoSized(), KLineEdit
| 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)
| insertCombo |
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.
Returns: Item index.
See also: KComboBox, setItemAutoSized(), KComboBox
| int insertCombo (const QString& text, int id, bool writable,
const char *signal, QObject *recevier,
const char *slot, bool enabled=true,
const QString& tooltiptext=QString::null,
int size=70, int index=-1,
QComboBox::Policy policy = QComboBox::AtBottom)
| insertCombo |
Insert a KComboBox with text.
The rest is the same as above.
Returns: Item index.
See also: KComboBox, KComboBox
| int insertSeparator ( int index = -1, int id = -1 )
| insertSeparator |
Inserts a separator into the toolbar with the given id. Returns the separator's index
| int insertLineSeparator ( int index = -1, int id = -1 )
| insertLineSeparator |
Inserts a line separator into the toolbar with the given id. Returns the separator's index
| int insertWidget (int id, int width, QWidget *_widget, int index=-1)
| insertWidget |
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().
Returns: Item index.
See also: setItemAutoSized()
| int insertAnimatedWidget (int id, QObject *receiver, const char *slot,
const QString& icons, int index = -1)
| insertAnimatedWidget |
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.
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
See also: animatedWidget()
| KAnimWidget * animatedWidget ( int id )
| animatedWidget |
This will return a pointer to the given animated widget, if it exists.
Parameters:
| id | The id for the widget you want to get a pointer to |
Returns: A pointer to the current animated widget or 0L
See also: insertAnimatedWidget
| void addConnection (int id, const char *signal,
const QObject *receiver, const char *slot)
| addConnection |
Adds connections to items.
It is important that you
know the id of particular item. Nothing happens if you forget id.
| void setItemEnabled ( int id, bool enabled )
| setItemEnabled |
Enables/disables item.
| void setButtonIcon ( int id, const QString& _icon )
| setButtonIcon |
Sets the icon for a button.
Can be used while button is visible.
| void setButtonPixmap ( int id, const QPixmap& _pixmap )
| setButtonPixmap |
Sets button pixmap.
Can be used while button is visible.
| void setButtonIconSet ( int id, const QIconSet& iconset )
| setButtonIconSet |
Sets a button icon from a QIconSet.
Can be used while button is visible.
| void setDelayedPopup (int id , QPopupMenu *_popup, bool toggle = false)
| setDelayedPopup |
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 normal a button with connection (or use signals from toolbar):
bar->insertButton(icon, id, const SIGNAL(clicked ()), this, SLOT (slotClick()), true, "click or wait for popup"); |
bar->setDelayedPopup (id, historyPopup);Don't add delayed popups to buttons which have normal popups. You may add popups which are derived from @ref QPopupMenu. You may add popups that are already in the menu bar or are submenus of other popups. |
| void setAutoRepeat (int id, bool flag=true)
| setAutoRepeat |
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'.
| void setToggle (int id, bool flag = true)
| setToggle |
Turns button into a toggle button if flag is true.
| void toggleButton (int id)
| toggleButton |
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().
| void setButton (int id, bool flag)
| setButton |
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()
| bool isButtonOn (int id)
| isButtonOn |
[const]
Returns: true if button is on, false if button is off or if the
button is not a toggle button.
See also: setToggle()
| void setLinedText (int id, const QString& text)
| setLinedText |
Sets the text of a line editor.
Cursor is set at end of text.
| QString getLinedText (int id)
| getLinedText |
[const]
Returns a line editor text.
| void insertComboItem (int id, const QString& text, int index)
| insertComboItem |
Inserts text in combobox id at position index.
| void insertComboList (int id, const QStringList &list, int index)
| insertComboList |
Inserts list in combobox id at position index.
| void removeComboItem (int id, int index)
| removeComboItem |
Removes item index from combobox id.
| void setCurrentComboItem (int id, int index)
| setCurrentComboItem |
Sets item index to be current item in combobox id.
| void changeComboItem (int id, const QString& text, int index=-1)
| changeComboItem |
Changes item index in combobox id to text.
index = -1 refers current item (one displayed in the button).
| void clearCombo (int id)
| clearCombo |
Clears the combobox id.
Does not delete it or hide it.
| QString getComboItem (int id, int index=-1)
| getComboItem |
[const]
Returns text of item index from combobox id.
index = -1 refers to current item.
| KComboBox * getCombo (int id)
| getCombo |
Returns a pointer to the combobox.
Example:
KComboBox *combo = toolbar->getCombo(combo_id); |
That way you can get access to other public methods that KComboBox provides.
| KLineEdit * getLined (int id)
| getLined |
Returns a pointer to KToolBarLined.
Example:
KLineEdit * lined = toolbar->getKTollBarLined(lined_id); |
That way you can get access to other public methods that KLineEdit provides. KLineEdit is the same thing as QLineEdit plus completion signals.
| KToolBarButton * getButton (int id)
| getButton |
Returns a pointer to KToolBarButton.
Example:
KToolBarButton * button = toolbar->getButton(button_id); |
That way you can get access to other public methods that KToolBarButton provides.
Using this method is not recommended.
| void alignItemRight (int id, bool right = true)
| alignItemRight |
Align item to the right.
This works only if toolbar is set to full width.
See also: setFullWidth()
| QWidget * getWidget (int id)
| getWidget |
Returns a pointer to an inserted widget.
Wrong ids are not tested. You can do with this whatever you want, except change its height (hardcoded). If you change its width you will probably have to call QToolBar::updateRects(true)
See also: QWidget, updateRects()
| void setItemAutoSized (int id, bool yes = true)
| setItemAutoSized |
Set item autosized.
This works only if the toolbar is set to full width.
Only one item can be autosized, and it has to be
the last left-aligned item. Items that come after this must be right
aligned. Items that can be right aligned are Lineds, Frames, Widgets and
Combos. An autosized item will resize itself whenever the toolbar geometry
changes to the last right-aligned item (or to end of toolbar if there
are no right-aligned items.)
See also: setFullWidth(), alignItemRight()
| void clear ()
| clear |
Remove all items.
The toolbar is redrawn after it.
| void removeItem (int id)
| removeItem |
Remove item id.
Item is deleted. Toolbar is redrawn after it.
| void hideItem (int id)
| hideItem |
Hide item.
| void showItem (int id)
| showItem |
Show item.
| void setFullSize (bool flag = true)
| setFullSize |
Set toolbar to full parent size (default).
In full size mode the bar extends over the parent's full width or height. If the mode is disabled the toolbar tries to take as much space as it needs without wrapping, but it does not exceed the parent box. You can force a certain width or height with setMaxWidth() or setMaxHeight().
If you want to use right-aligned items or auto-sized items you must use full size mode.
| bool fullSize ()
| fullSize |
[const]
Returns: true if the full-size mode is enabled. Otherwise
it returns @false.
| void enableMoving (bool flag = true)
| enableMoving |
Enable or disable moving of toolbar.
| void setBarPos (BarPosition bpos)
| setBarPos |
Set position of toolbar.
See also: BarPosition()
| BarPosition barPos ()
| barPos |
[const]
Returns position of toolbar.
| bool enable (BarStatus stat)
| enable |
Show, hide, or toggle toolbar.
This method is provided for compatibility only, please use show() and/or hide() instead.
See also: BarStatus
| void setMaxHeight (int h)
| setMaxHeight |
Use setMaximumHeight() instead.
| int maxHeight ()
| maxHeight |
Use maximumHeight() instead. Returns the value that was set with setMaxHeight().
| void setMaxWidth (int dw)
| setMaxWidth |
Use setMaximumWidth() instead. Set maximal width of horizontal (top or bottom) toolbar.
| int maxWidth ()
| maxWidth |
Use maximumWidth() instead. Returns the value that was set with setMaxWidth().
| void setTitle (const QString& _title)
| setTitle |
Set title for toolbar when it floats.
Titles are however not (yet) visible. You can't change toolbar's title while it's floating.
| void enableFloating (bool arrrrrrgh)
| enableFloating |
Use enableMoving() instead.
| void setIconText (IconText it)
| setIconText |
Set the kind of painting for buttons.
Choose from:
See also: IconText
| void setIconText (IconText it, bool update)
| setIconText |
Similar to setIconText(IconText it) but allows you to
disable or enable updating. If update is false, then the
buttons will not be updated. This is useful only if you know
that you will be forcing an update later.
| IconText iconText ()
| iconText |
[const]
Returns: The current text style for buttons.
| void setIconSize (int size)
| setIconSize |
Set the icon size to load. Usually you should not call this, the icon size is taken care of by KIconLoader and globally configured. By default, the toolbar will load icons of size 32 for main toolbars and 22 for other toolbars
Parameters:
| size | The size to use |
See also: KIconLoader.
| void setIconSize (int size, bool update)
| setIconSize |
Same as setIconText(int size) but allows you to disable the toolbar update.
Parameters:
| size | The size to use |
| update | If true, then the toolbar will be updated after this |
| int iconSize ()
| iconSize |
[const]
Returns: The current icon size for buttons.
| void setEnableContextMenu (bool enable = true)
| setEnableContextMenu |
This allows you to enable or disable the context menu.
Parameters:
| enable | If false, then the context menu will be disabled |
| bool contextMenuEnabled ()
| contextMenuEnabled |
[const]
Returns whether or not the context menu is disabled
Returns: The context menu state
| void setItemNoStyle (int id, bool no_style = true)
| setItemNoStyle |
This will inform a toolbar button to ignore certain style changes. Specifically, it will ignore IconText (always IconOnly) and will not allow image effects to apply.
Parameters:
| id | The button to exclude from styles |
| no_style | If true, then it is excluded (default: true). |
| void setFlat (bool flag)
| setFlat |
| int count ()
| count |
[const]
Returns: the number of items in the toolbar
| void saveState ()
| saveState |
Instruct the toolbar to save it's current state to either the app config file or to the XML-GUI resource file (whichever has precedence).
| void saveSettings (KConfig *config, const QString &configGroup)
| saveSettings |
Save the toolbar settings to group configGroup in config.
| void applySettings (KConfig *config, const QString &configGroup)
| applySettings |
Read the toolbar settings from group configGroup in config
and apply them.
| void setXMLGUIClient ( KXMLGUIClient *client )
| setXMLGUIClient |
Tell the toolbar what XML-GUI resource file it should use to save it's state. The state of the toolbar (position, size, etc) is saved in KConfig files if the application does not use XML-GUI.. but if the app does, then it's saved the XML file. This function allows this to happen.
Parameters:
| xmlfile | The XML-GUI resource file to write to |
| xml | The DOM document for the XML-GUI building |
| void setText ( const QString & txt )
| setText |
Assign a (translated) text to this toolbar. This is used for the tooltip on the handle, and when listing the toolbars.
| QString text ()
| text |
[const]
Returns: the toolbar's text.
| void setStretchableWidget ( QWidget *w )
| setStretchableWidget |
| QSizePolicy sizePolicy ()
| sizePolicy |
[const]
| bool highlight ()
| highlight |
[const]
| QSize sizeHint ()
| sizeHint |
[const]
| QSize minimumSizeHint ()
| minimumSizeHint |
[const]
| QSize minimumSize ()
| minimumSize |
[const]
| void hide ()
| hide |
| void show ()
| show |
| void updateRects ( bool = FALSE )
| updateRects |
| void loadState ( const QDomElement &e )
| loadState |
| void saveState ( QDomElement &e )
| saveState |
| void positionYourself ( bool force = false)
| positionYourself |
| void clicked (int id)
| clicked |
[signal]
Emitted when button id is clicked.
| void doubleClicked (int id)
| doubleClicked |
[signal]
Emitted when button id is double-clicked.
Note: you will always recive two clicked() , pressed() and released() signals. There is no way to avoid it - at least no easy way. If you need to resolve this all you can do is set up timers which wait for QApplication::doubleClickInterval() to expire. If in that time you don't get this signal, you may belive that button was only clicked and not double-clicked. And please note that butons with popup menus do not emit this signal, but those with delayed popup do.
| void pressed (int)
| pressed |
[signal]
Emitted when button id is pressed.
| void released (int)
| released |
[signal]
Emits when button id is released.
| void toggled (int)
| toggled |
[signal]
Emitted when a toggle button changes state.
Emitted also if you change state with setButton() or toggleButton() If you make a button normal again, with setToggle(false), this signal won't be emitted.
| void highlighted (int id, bool isHighlighted)
| highlighted |
[signal]
This signal is emitted when item id gets highlighted/unhighlighted (i.e when mouse enters/exits).
Note that this signal is emitted from
all buttons (normal, disabled and toggle) even when there is no visible
change in buttons (i.e., buttons do not raise when mouse enters).
The parameter isHighlighted is true when mouse enters and false when
mouse exits.
| void highlighted (int id )
| highlighted |
[signal]
This signal is emitted when item id gets highlighted/unhighlighted (i.e when mouse enters/exits).
Note that this signal is emitted from all buttons (normal, disabled and toggle) even when there is no visible change in buttons (i.e., buttons do not raise when mouse enters).
| void moved ( BarPosition )
| moved |
[signal]
Emitted when toolbar changes position, or when an item is removed from toolbar.
If you subclass KMainWindow and reimplement KMainWindow::resizeEvent() be sure to connect to this signal. Note: You can connect this signal to a slot that doesn't take parameter.
| void modechange ()
| modechange |
[signal]
This signal is emited when toolbar detects changing of following parameters: highlighting, button-size, button-mode. This signal is internal, aimed to buttons.
| bool highlightSetting ()
| highlightSetting |
[static signal]
Returns: global setting for "Highlight buttons under mouse"
| bool transparentSetting ()
| transparentSetting |
[static signal]
Returns: global setting for "Toolbars transparent when moving"
| IconText iconTextSetting ()
| iconTextSetting |
[static signal]
Returns: global setting for "Icon Text"
| void setIconText ( const QString &txt )
| setIconText |
[virtual slot]
| void mousePressEvent ( QMouseEvent * )
| mousePressEvent |
[protected]
| void childEvent ( QChildEvent *e )
| childEvent |
[protected]
| void showEvent ( QShowEvent *e )
| showEvent |
[protected]
| void resizeEvent ( QResizeEvent *e )
| resizeEvent |
[protected]
| bool event ( QEvent *e )
| event |
[protected]
| void applyAppearanceSettings (KConfig *config, const QString &_configGroup, bool forceGlobal = false)
| applyAppearanceSettings |
[protected]
| QString settingsGroup ()
| settingsGroup |
[protected const]
| void virtual_hook ( int id, void* data )
| virtual_hook |
[protected virtual]