Xfce Foundation Classes
 « Main Page | Index

Tool Items

Table of Contents

  1. Tool Buttons
  2. Toggle Tool Buttons
  3. Radio Tool Buttons
  4. Separator Tool Items

Tool items are widgets that can appear on a toolbar. There are three types of tool items that contain buttons: ToolButton, ToggleToolButton and RadioToolButton. A separator tool item can used to separate items in a toolbar.

To create a tool item that contains a widget other than a button use the following constructor and then call Gtk::Container::add() to add a child widget to the tool item.

ToolItem();
   
ToolItem(Gtk::Widget& widget);

The first constructor creates an empty tool item. The second constructor creates a tool item that contains the specified widget.

The homogeneous property of a tool item can be set or retrieved using the following methods respectively:

void set_homogeneous(bool homogeneous);

bool get_homogeneous() const;

If 'homogeneous' is set to true the tool item will be allocated the same size as other homogeneous items in the toolbar, which is usually the size of the largest item. The default value is false.

The expand property of a tool item can be set or retrieved using the following methods respectively:

void set_expand(bool expand);

bool get_expand() const;

If 'expand' is set to true the tool item is allocated extra space when there is more room in the toolbar than needed for the items. The default value is false.

A tooltip can be set on a tool item with this method:

void set_tooltip(Tooltips& tooltips, const String& tip_text, const String& tip_private = 0);

The 'tooltips' argument is the tooltips object to use. The 'tip_text' argument is the text to use as tooltip text for the tool item. The 'tip_private' argument is a text string that might be useful if a user gets stuck. Usually it can just be ignored.

A tool item's horizontal and vertical visibility can be set or retrieved with the following four methods respectively:
 
void set_visible_horizontal(bool visible_horizontal);

bool get_visible_horizontal() const;
  
void set_visible_vertical(bool visible_vertical);

bool get_visible_vertical() const;

If 'visible_horizontal' is true the tool item is visible when the toolbar is docked horizontally. If 'visible_vertical' is true the tool item is visible when the toolbar is docked vertically. By default, visible_horizontal and visible_vertical are both true.

A tool item's is_important property can be set or retrieved with the following methods respectively:

void set_is_important(bool is_important);

bool get_is_important() const;

A tool button uses this property to decide whether to show or hide its label when the toolbar style is Gtk::TOOLBAR_BOTH_HORIZ. The result is that only tool items with 'is_important' set to true will have labels.

Tool Buttons

A ToolButton is a tool item that contains a button. The tool button can display a custom icon widget, a custom label widget or a stock item. You can create a ToolButton with one of the following constructors:

ToolButton();

ToolButton(Widget& icon_widget);
  
ToolButton(const String& label, bool use_underline = false);
  
ToolButton(Widget& icon_widget, const String& label, bool use_underline = false);
    
ToolButton(const StockId& stock_id);

The first constructor creates an empty tool button. The second constructor creates a tool button that uses 'icon_widget' as its icon. The third constructor creates a tool button that uses 'label' as the label. The fourth constructor creates a tool button that uses 'icon_widget' as its icon and 'label' as the label. If 'use_underline' is true the label text is parsed for a underscore preceding the mnemonic character. The last constructor creates a tool button using the icon and label of the stock item specified by 'stock_id'.

The label of a ToolButton is determined by the properties 'label_widget', 'label', and 'stock_id'. If 'label_widget' is not null, then that widget is used as the label. Otherwise, if
'label' is not null, that string is used as the label. Otherwise, if 'stock_id' is not null, the label is determined by the stock item. Otherwise, the button does not have a label.

The icon of a ToolButton is determined by the properties 'icon_widget' and 'stock_id'. If 'icon_widget' is not null, then that widget is used as the icon. Otherwise, if 'stock_id' is not null, the icon is determined by the stock item. Otherwise, the button does not have an icon.

You can set or retrieve the label widget, or label, with the following four methods respectively:

void set_label_widget(Widget *label_widget);

Widget* get_label_widget() const;

void set_label(const String& label, bool use_underline = false);

String get_label() const;

You can set or retrieve the icon widget with the following methods respectively:

void set_icon_widget(Widget *icon_widget);

Widget* get_icon_widget() const;

You can set or retrieve the stock item with the following methods respectively:

void set_stock_id(const StockId& stock_id);

String get_stock_id() const;

As a convenience, the following method can be used to set the icon widget and label. This is equivalent to calling set_icon_widget() and set_label() separately.

void set_contents(Widget& icon_widget, const String& label, bool use_underline = false);

Toggle Tool Buttons

A ToggleToolButton is a tool item that contains a toggle button.  You can create a ToggleButton with the following constructors:
 
ToggleToolButton();

ToggleToolButton(const StockId& stock_id);

The first constructor creates an empty toggle tool button. The second constructor creates a toggle tool button containing the image and text of the stock item specified by 'stock_id'.

You can set or retrieve the 'active' state of a toggle tool button with the following methods respectively:

void set_active(bool is_active);

bool get_active() const;

Radio Tool Buttons

A RadioToolButton is a tool item that contains a radio button, that is, a button that is part of a group of toggle buttons where only one button can be active at a time. You can create a RadioToolButton with the following constructors:

RadioToolButton();

RadioToolButton(const RadioToolButton *group);
  
RadioToolButton(const RadioToolButton *group, const StockId& stock_id);

The first constructor creates  an empty radio tool button that is the first member in a new group. The second constructor creates and empty radio tool button that is a member of an existing group. The last constructor creates a radio tool button that is a member of an existing group and contains the icon and label of the stock item specified by 'stock_id'.

If the 'group' argument is null a new group will be created for the radio tool button. This should be the case for the first radio tool button created in a group. Then for subsequent radio tool buttons you create, pass a pointer to the previous radio tool button. This allows a chain of radio tool buttons to be established.

You can set or retrieve the group a RadioToolButton belongs to with the following methods:

void set_group(Group *group);

Group* get_group() const;

The 'group' argument in these methods is a typedef for GSList.

Separator Tool Items

A SeparatorToolItem is a tool item that separates groups of other tool items. Depending on the theme, a SeparatorToolItem will often look like a vertical line on horizontally docked toolbars. You can create a new SeparatorToolItem with the following constructor:

SeparatorToolItem();

You can set or retrieve an item's 'draw' property which determines whether the separator is drawn as a vertical line or a blank:

void set_draw(bool draw);

bool get_draw() const;

If a separator tool item's expand property is true and its draw property is false, the separator will act as a 'spring' that forces other items to the end of the toolbar.

For an example that uses tool items see the Toolbar example.

Copyright © 2004-2005 The XFC Development Team Top
 XFC 4.4