KToolBar Class Reference

[kdeui Index] [kdeui Hierarchy] [Headers]


KDE Toolbar widget More...

#include <ktoolbar.h>

Inherits: QFrame (qt)

Public Members

Protected Members

Signals

Private Members

Private Slots


Detailed Description

KToolBar is a self resizing, floatable widget. It is usually managed from KTopLevelWidget, but can be used even if you don't use KTopLevelWidget. If you want to handle this without KTopLevelWidget, see updateRects .
KToolBar can contain buttons Line inputs Combo Boxes, frames, and custom widgets. Combos, Frames and Lineds, and Widgets can be autosized to full width. Any Item can be right aligned, and buttons can be toggle buttons. Item height, type of buttons (icon or icon+text), and option for highlighting is adjustable on constructor invocation by reading config file. Toolbar will reread config-file when it recieves signal Kapplication:appearanceChanged. Toolbar can float, be dragged from and docked back to parent window. It autoresizes itself. This may lead to some flickering, but there is no way to solve it (as far as I know).
You can bind popups and delayed popups to buttons.
You normaly use toolbar from subclassed KTopLevelWidget. When you create toolbar object, insert items that you want to be in it. Items can be inserted or removed ( removeItem() ) later, when toolbar is displayed. It will update itself. Then set their propperties ( alignItemRight , setItemAutoSized , setToggle ...) After that set the toolbar itself, enable ,setBarPos ...). Then simply do addToolbar (toolbar), and you're on. See how it's done in kwindowtest.


KToolBar(QWidget *parent=0L, const char *name=0L, int _item_size = -1) [public]

Constructor. Toolbar will read global-config file for item Size higlight option and button type. However, you can pass desired height. If you specify height here, config value has no effect. Exception is if you set Icontext mode to 3 (icons under text) whic sets size to minimum 40 pixels. For setting IconText mode, see setIconText . Setting size in constructor is not recomended.

~KToolBar() [public virtual]

Destructor. If toolbar is floating it will cleanup itself.

int insertButton(const QPixmap& pixmap, int ID, bool enabled = true, const char *ToolTipText = 0L, int index=-1 ) [public]

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

Parameters:
index the position of the button. (-1 = at end).
Returns:
Returns item index

int insertButton(const QPixmap& pixmap, int ID, const char *signal, const QObject *receiver, const char *slot, bool enabled = true, const char *tooltiptext = 0L, int index=-1 ) [public]

This is the same as above, but with specified signals and slots to which this button will be connected. Button emits signals pressed, clicked and released, and if toolbar is toggle button ( setToggle ) toggled . You can add more signals with addConnection .

Returns:
Returns item index

int insertButton(const QPixmap& pixmap, int id, QPopupMenu *popup, bool enabled, const char *_text, int index=-1) [public]

This inserts a button with popupmenu. Button will have small trialngle. You have to connect to popup's signals. The signals pressed, released, clikced or 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 char *text, int ID, const char *signal, const QObject *receiver, const char *slot, bool enabled = true, const char *toolTipText = 0L, int size = 70, int index =-1) [public]

Inserts a KLined. You have to specify signals and slots to which KLined will be connected. KLined has all slots QLineEdit has, plus signals KLined::completion and KLined::rotation KLined 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:
Returns item index
See Also:
setFullWidth, setItemAutoSized, KLined

int insertCombo(QStrList *list, int id, bool writable, const char *signal, QObject *recevier, const char *slot, bool enabled=true, const char *tooltiptext=0L, int size=70, int index=-1, KCombo.html">KCombo::Policy policy = KCombo.html">KCombo::AtBottom) [public]

Inserts 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 KCombo is almost the same thing as QComboBox.

Returns:
Returns item index
See Also:
setFullWidth, setItemAutoSized, KCombo

int insertCombo(const char *text, int id, bool writable, const char *signal, QObject *recevier, const char *slot, bool enabled=true, const char *tooltiptext=0L, int size=70, int index=-1, KCombo.html">KCombo::Policy policy = KCombo.html">KCombo::AtBottom) [public]

Inserts KCombo with text. The rest is the same as above.

Returns:
Returns item index
See Also:
setItemAutoSized, KCombo

int insertSeparator(int index=-1) [public]

Insert separator

int insertFrame(int id, int width, int index =-1) [public]

This function is deprecated and will be removed. Use insertWidget to insert anything. Inserts frame with specified width. You can get pointer to this frame with getFrame Frame can be autosized to full width.

Returns:
Returns item index
See Also:
setItemAutoSized

int insertWidget(int id, int width, QWidget *_widget, int index=-1) [public]

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

Returns:
Returns item index
See Also:
setItemAutoSized

void addConnection(int id, const char *signal, const QObject *receiver, const char *slot) [public]

This adds connection to items. Therefore it is important that you know id of particular item. Nothing happens if you miss id.

void setItemEnabled( int id, bool enabled ) [public]

Enables/disables item.

void setButtonPixmap( int id, const QPixmap& _pixmap ) [public]

Sets button pixmap. Can be used while button is visible.

void setDelayedPopup(int id , QPopupMenu *_popup) [public]

Sets delayed popup to a button. Delayed popup is what you see in netscape's Previous&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 button with connection (or use signals from toolbar):

bar->insertButton(pixmap, id, const 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 wich are derived from QPopupMenu. You may add popups that are already in menu bar or are submenus of other popups.

void setAutoRepeat(int id, bool flag=true) [public]

Makes a button autorepeat button. Toggle, buttons with menu or delayed menu cannot be autorepeat. More, you can and will receive only signals clicked, and not pressed or released. When user presses this buton, you will receive signal clicked, and if button is still pressed after some time, more clicks in some interval. Since this uses QButton::setAutoRepeat , I don't know how much is 'some'.

void setToggle(int id, bool flag = true) [public]

Makes button a toggle button if flag is true

void toggleButton(int id) [public]

If button is toggle (setToggle must be called first) button state will be toggled. This will also cause toolbar to emit signal toggled wit parameter id. You must connect to this signal, or use addConnection to connect directly to button-signal toggled.

void setButton(int id, bool flag) [public]

If button is toggle (setToggle must be called first) this will set him to state flag. This will also emit signal #ref toggled .

See Also:
setToggle

bool isButtonOn(int id) [public]

Returns true if button is on, false if button is off. If button is not a toggle button returns false

See Also:
setToggle

void setLinedText(int id, const char *text) [public]

Sets text in Lined. Cursor is set at end of text.

const char* getLinedText(int id) [public]

Returns Lined text. If you want to store this text, you have to deep-copy it somwhere.

void insertComboItem(int id, const char *text, int index) [public]

Inserts text in combo id with at position index.

void insertComboList(int id, QStrList *list, int index) [public]

Inserts list in combo id at position index

void removeComboItem(int id, int index) [public]

Removes item index from Combo id.

void setCurrentComboItem(int id, int index) [public]

Sets item index to be current item in Combo id.

void changeComboItem(int id, const char *text, int index=-1) [public]

Changes item index in Combo id to text. index = -1 means current item (one displayed in the button).

void clearCombo(int id) [public]

Clears combo id. Does not delete it or hide it.

const char* getComboItem(int id, int index=-1) [public]

Returns text of item index from Combo id. index = -1 means current item

KCombo * getCombo(int id) [public]

This returns pointer to Combo. Example:

KCombo *combo = toolbar->getCombo(combo_id);
That way you can get access to other public methods that KCombo provides. KCombo is KDE enhancement of QComboBox . KCombo inherits QComboBox, so you can use pointer to QComboBox too.

KLined * getLined(int id) [public]

This returns pointer to KToolBarLined. Example:

KLined * lined = toolbar->getKTollBarLined(lined_id);
That way you can get access to other public methods that KLined provides. KLined is the same thing as QLineEdit plus completion signals.

KToolBarButton * getButton(int id) [public]

This 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 of this method is not recomended.

void alignItemRight(int id, bool right = true) [public]

Alignes item right. This works only if toolbar is set to full width.

See Also:
setFullWidth

QFrame * getFrame(int id) [public]

This function is deprecated and might be removed. Use insertWidget and getWidget instead.
Returns pointer to inserted frame. Wrong ids are not tested. Example:

QFrame *frame = toolbar->getframe (frameid);
You can do with this frame whatever you want, except change its height (hardcoded). If you change its width you will probbably have to call toolbar->updateRects (true)

See Also:
QFrame, updateRects

QWidget* getWidget(int id) [public]

Returns pointer to 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 probbably have to call toolbar->updateRects (true)

See Also:
QWidget, updateRects

void setItemAutoSized(int id, bool yes = true) [public]

Sets item autosized. This works only if 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. Auto sized item will resize itself whenever toolbar geometry changes, to last right-aligned item (or till end of toolbar if there are no right aligned items

See Also:
setFullWidth, alignItemRight

void removeItem(int id) [public]

Removes item id. Item is deleted. Toolbar is redrawn after it.

void hideItem(int id) [public]

Hides item.

void showItem(int id) [public]

shows item.

void setFullWidth(bool flag = true) [public]

Sets toolbar to full parent width (or to value set by setMaxWidth). You have to call this function if you want to have right aligned items or autosized item.
The toolbar is set to full width by default.

See Also:
alignItemRight, setItemAutoSized

void enableMoving(bool flag = true) [public]

Enables or disables moving of toolbar.

void setBarPos(BarPosition bpos) [public]

Sets position of toolbar. This cannot be used to set toolbar flat. For That, use setFlat .

See Also:
BarPosition

BarPosition barPos() [public]

Returns position of toolbar

bool enable(BarStatus stat) [public]

This shows, hides, or toggles toolbar. If toolbar floats, hiding means minimizing. Warning: kwm will not show minimized toolbar on taskbar. Therefore hiding means hiding.

See Also:
BarStatus

void setMaxHeight(int h) [public]

Sets maximal height of vertical (Right or Left) toolbar. You normaly do not have to call it, since it's called from KTopLevelWidget::updateRects If you reimplement KTopLevelWidget::resizeEvent or KTopLevelWidget#updateRects, be sure to call this function with maximal height toolbar can have. In 0xFE cases out of 0xFF you don't need to use this function.

See Also:
updateRects

void setMaxWidth(int dw) [public]

Sets maximal width of horizontal (top or bottom) toolbar. This works only for horizontal toolbars (at Top or Bottom), and has no effect otherwise. Has no effect when toolbar is floating.

void setTitle(const char *_title) [public]

Sets 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) [public]

Enables or disables floating. Floating is enabled by default. This only disables menu entry Floating in popup menu, so toolbar can still be moved by setBarPos or by dragging. This function is obsolete and do not use it. If you want to make toolbar static use enableMoving

void setIconText(int it) [public]

Sets the kind of painting for buttons between : 0 (only icons), 1 (icon and text, text is left from icons), 2 (only text), and 3 (icons and text, text is under icons).

void updateRects(bool resize = false) [public]

Redraw toolbar and resize it if resize is true. You normaly don't have to call it, since it's called from KTopLevelWidget::updateRects or from resizeEvent. You can call it if you manualy change width of inserted frame, or if you wish to force toolbar to recalculate itself.
You don't want to fiddle with this. KtopLevelWidget works closely with toolbar. If you want to subclass KTopLevelWidget to change its resize policy, hear this:

resizeEvent() in KTopLevelWidget just calls updateRects, which handles children sizes. Call updateRects when you're done with your things.

If you want to handle everything yourself:

KToolBar manages itself by calling toolbar->updateRects (true). It will autosize itself, but won't move itself. You have to do the moving.
First setup & move anything that is above toolbars (menus...). Then setup statusbars and other horizontal things on bottom. Then loop through all HORIZONTAL toolbars, call their updateRects(true), _then_ take their size, an move them (note that they size themselves according to parent width()). After you have looped through HORIZONTAL toolbars, calculate the maximum height that vertical toolbars may have (this is your free area height). Then loop through vertical toolbars, setMaxHeight (calculated_max_height) on them, call their updateRects(true), and _then_ move them to their locations. In 0xFE cases out of 0xFF you don't need to use this function.

See Also:
KtopLevelWidget::updateRects

QSize sizeHint() [public]

Returns minimal width for top-level window, so that toolbar has only one row.

void setFlat(bool flag) [public]

This method switches flat/unflat mode. Carefull: might not work If toolbar is floating.

void clicked(int id) [signal]

Emits when button id is clicked.

void doubleClicked(int id) [signal]

Emits 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 waits for QApplication::doubleClickInterval to expire. if in that time you don't get this signal, you may belive that button was only clicked. And please note that butons with popup menus do not emit this signal, but those with delayed popup do.

void pressed(int) [signal]

Emits when button id is pressed.

void released(int) [signal]

Emits when button id is released.

void toggled(int) [signal]

Emits when toggle button changes state Emits also if you change state with setButton or toggleButton If you make a button normal again, with setToggle (false), this signal won't be emited.

void highlighted(int id, bool isHighlighted) [signal]

This signal is emmited when item id gets highlighted/unhighlighted (i.e when mouse enters/exits). Note that this signal is emited from all buttons (normal, disabled and toggle) even when there is no visible change in buttons (meaning, buttons do not raise when mouse enters). Parameter isHighlighted is true when mouse enters and false when mouse exits.

void moved( BarPosition ) [signal]

Emits when toolbar changes its position, or when item is removed from toolbar. This is normaly connected to KTopLevelWidget::updateRects If you subclass KTopLevelWidget and reimplement KTopLevelWidget::resizeEvent or KTopLevelWidget::updateRects be sure to connect to this signal. You can connect this signal to slot that doesn't take parameter.

See Also:
updateRects

void modechange() [signal]

Internal. This signal is emited when toolbar detects changing of following parameters: highlighting, button-size, button-mode. This signal is internal, aimed to buttons.


  • Author: Stephan Kulow <coolo@kde.org> Maintained by Sven Radej <radej@kde.org>
  • Documentation generated by root@darkstar.lst.de on Wed Sep 8 17:38:27 CEST 1999
Kdoc