|
|
A KDE-style toolbar.
KToolBar can be "floated", dragged and docked from its parent window.
A KToolBar can contain standard or toggle buttons, line edit widgets, combo boxes, frames or any developer-defined custom widget, with automatic full-width resize for each widget (except buttons). Buttons can also be connected to popup menus with a delay option.
KToolBar can be used as a standalone widget, but KTMainWindow 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.
BUGS: Sometimes flickers on auto resize, no workaround has yet been found for this.
enum IconText {IconOnly = 0, IconTextRight, TextOnly, IconTextBottom} |
Possible positions for text.
enum BarStatus {Toggle, Show, Hide} |
The state of the status bar.
enum BarPosition {Top, Left, Bottom, Right, Floating, Flat} |
Possible bar positions.
KToolBar (QWidget *parent=0L, const char *name=0L, int _item_size = -1, bool _honor_mode=false) |
Constructor.
Toolbar will read global-config file for item size highlight 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) which sets size to minimum 40 pixels. For setting IconText mode, see setIconText() . Setting size in constructor is not recommended.
~KToolBar () |
Destructor.
If toolbar is floating it will cleanup itself.
int insertButton (const QPixmap& pixmap, int id, bool enabled = true, const QString& ToolTipText = QString::null, int index=-1 ) |
Insert a pushbutton (a KButton) with a pixmap.
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:
index | The position of the button. (-1 = at end). |
Returns: Item index.
int insertButton (const QPixmap& pixmap, int ID, const char *signal, const QObject *receiver, const char *slot, bool enabled = true, const QString& tooltiptext = QString::null, int index=-1 ) |
This is the same as above, but with specified signals and slots to which this button will be connected.
Button emits signals KButton::pressed(), KButton::clicked(), and KButton::released(), and if toolbar is toggle button ( setToggle() ) toggled(). You can add more signals with addConnection().
Returns: Item index.
int insertButton (const QPixmap& pixmap, int id, QPopupMenu *popup, bool enabled, const QString&_text, int index=-1) |
Insert 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 @bf 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) |
Inserts a KLined. 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::rotation 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 (QStrList *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) |
Insert QComboBox 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.
Returns: Item index.
See also: QComboBox, setItemAutoSized(), QComboBox
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) |
Insert QComboBox 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.
Returns: Item index.
See also: QComboBox, setItemAutoSized(), QComboBox
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) |
Insert QComboBox with text.
The rest is the same as above.
Returns: Item index.
See also: QComboBox, QComboBox
int insertSeparator (int index=-1) |
Insert separator.
int insertLineSeparator (int index=-1) |
Insert line separator.
int insertFrame (int id, int width, int index =-1) |
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
int insertWidget (int id, int width, QWidget *_widget, int index=-1) |
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 a pointer to this widget with getWidget().
Returns: Item index.
void 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
.
void setItemEnabled ( int id, bool enabled ) |
Enable/disable item.
void setButtonPixmap ( int id, const QPixmap& _pixmap ) |
Set button pixmap.
Can be used while button is visible.
void setDelayedPopup (int id , QPopupMenu *_popup, bool toggle = false) |
Set 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(pixmap, id, const SIGNAL(clicked ()), this, SLOT (slotClick()), true, "click or wait for popup");
bar->setDelayedPopup (id, historyPopup); </pre> 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) |
Make a button 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) |
Make button a toggle button if flag
is true.
void toggleButton (int id) |
Toggle 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) |
See 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().
bool isButtonOn (int id) |
Returns: true
if button is on, false
if button is off or if the
button is not a toggle button.
void setLinedText (int id, const QString& text) |
Set text in line editor.
Cursor is set at end of text.
QString getLinedText (int id) |
Retreive line editor text.
If you want to store this text, you have to deep-copy it somewhere.
void insertComboItem (int id, const QString& text, int index) |
Insert text in combobox id
at position index
.
void insertComboList (int id, QStrList *list, int index) |
Insert list in combobox id
at position index
.
void insertComboList (int id, const QStringList &list, int index) |
Insert list in combobox id
at position index
.
void removeComboItem (int id, int index) |
Remove item index
from combobox id
.
void setCurrentComboItem (int id, int index) |
Set item index
to be current item in combobox id
.
void changeComboItem (int id, const QString& text, int index=-1) |
Change item index
in combobox id
to text.
index
= -1 refers current item (one displayed in the button).
void clearCombo (int id) |
Clear combobox id
.
Does not delete it or hide it.
QString getComboItem (int id, int index=-1) |
Return text of item index
from combobox id
.
index
= -1 refers to current item.
QComboBox * getCombo (int id) |
Retrieve a pointer to the combobox.
Example:
QComboBox *combo = toolbar->getCombo(combo_id);
That way you can get access to other public methods that QComboBox provides.
KLineEdit * getLined (int id) |
Retrieve 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) |
Retrieve 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) |
Align item to the right.
This works only if toolbar is set to full width.
QFrame * getFrame (int id) |
This function is @deprecated and might be removed. Use insertWidget and getWidget instead.<br> 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) |
Retrieve 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 probbably have to call toolbar->updateRects (true)
See also: QWidget, updateRects()
void setItemAutoSized (int id, bool yes = true) |
Set item autosized.
This works only if the toolbar is set to full width. @bf Only @bf 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 () |
Remove all items.
The toolbar is redrawn after it.
void removeItem (int id) |
Remove item id
.
Item is deleted. Toolbar is redrawn after it.
void hideItem (int id) |
Hide item.
void showItem (int id) |
Show item.
void setFullWidth (bool flag = true) |
Obsolete! This function has been replaced by setFullSize().
void setFullSize (bool flag = true) |
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 () |
Returns: true
if the full-size mode is enabled. Otherwise
it returns @false.
void enableMoving (bool flag = true) |
Enable or disable moving of toolbar.
void setBarPos (BarPosition bpos) |
Set position of toolbar.
BarPosition barPos () |
Retrieve position of toolbar.
bool enable (BarStatus stat) |
Show, hide, or toggle toolbar.
If toolbar floats, hiding means minimizing. Warning: kwm will not show a minimized toolbar on taskbar. Therefore hiding means hiding.
void setMaxHeight (int h) |
Set maximal height of vertical (Right or Left) toolbar.
You normally do not have to call it, since it's called from KTMainWindow::updateRects() If you reimplement KTMainWindow::resizeEvent() or KTMainWindow::updateRects(), be sure to call this function with the maximal height the toolbar can have. In 0xFE cases out of 0xFF (i.e., quite nearly always) you don't need to use this function.
int maxHeight () |
Retrieve the value that was set with setMaxHeight().
void setMaxWidth (int dw) |
Set 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.
int maxWidth () |
Retrieve the value that was set with setMaxWidth().
void setTitle (const QString& _title) |
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) |
Enable or disable 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 (IconText it) |
Set the kind of painting for buttons.
Choose from:
IconText iconText () |
Returns: The current kind of painting for buttons.
void updateRects (bool resize = false) |
Arrange the toolbar items and calculates their position and size.
Most of the work is done by layoutHorizontal() and layoutVertical() though. In some cases it may be desirable to trigger a resize operation, then set resize to true. Do not call updateRects(true) when processing a resize event as this will start an infinite recursion!
QSize sizeHint () |
Retrieve the preferred size.
This function is required for the Qt layout management to work.
QSize minimumSizeHint () |
Retrieve the minimum size.
This function is required for the Qt layout management to work.
QSize maximumSizeHint () |
Retrieve the maximum size.
This function return the maximum size the toolbar would need without wrapping. Use this function when you want to fix the toolbar to it's maximum width/height.
int widthForHeight (int height) |
Retrieve the width needed to properly display at a given height
.
This function is required for the Qt layout management to work. It return the minimum width for a given height. It makes only sense for vertical tool bars.
int heightForWidth (int width) |
Retrieve the height needed to properly display at a given width
.
This function is required for the Qt layout management to work. It return the minimum height for a given width. It makes only sense for horizontal tool bars.
QSizePolicy sizePolicy () |
This function is required for the Qt layout management to work. It returns information about the size policy.
int count () |
Returns: the number of items in the toolbar
void clicked (int id) |
Emitted when button id
is clicked.
void doubleClicked (int id) |
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) |
Emitted when button id
is pressed.
void released (int) |
Emits when button id
is released.
void toggled (int) |
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) |
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 moved ( BarPosition ) |
Emitted when toolbar changes position, or when an item is removed from toolbar.
This is normaly connected to KTMainWindow::updateRects(). If you subclass KTMainWindow and reimplement KTMainWindow::resizeEvent() or KTMainWindow::updateRects(), be sure to connect to this signal. Note: You can connect this signal to a slot that doesn't take parameter.
void modechange () |
This signal is emited when toolbar detects changing of following parameters: highlighting, button-size, button-mode. This signal is internal, aimed to buttons.