gtk-0.12.0: Binding to the Gtk+ graphical user interface library.

Portability | portable (depends on GHC)
Stability | provisional
Maintainer | gtk2hs-users@lists.sourceforge.net

Graphics.UI.Gtk.MenuComboToolbar.Toolbar

Contents

- Detail
- Class Hierarchy
- Types
- Constructors
- Methods
- Attributes
- Child Attributes
- Signals

Description

Create bars of buttons and other widgets

Synopsis

- data Toolbar
- class ContainerClass o => ToolbarClass o
- castToToolbar :: GObjectClass obj => obj -> Toolbar
- gTypeToolbar :: GType
- toToolbar :: ToolbarClass o => o -> Toolbar
- data Orientation
  - = OrientationHorizontal
  - | OrientationVertical
- data ToolbarStyle
  - = ToolbarIcons
  - | ToolbarText
  - | ToolbarBoth
  - | ToolbarBothHoriz
- toolbarNew :: IO Toolbar
- toolbarInsertNewButton :: ToolbarClass self => self -> Int -> StockId -> Maybe (String, String) -> IO Button
- toolbarAppendNewButton :: ToolbarClass self => self -> String -> Maybe (String, String) -> IO Button
- toolbarPrependNewButton :: ToolbarClass self => self -> String -> Maybe (String, String) -> IO Button
- toolbarInsertNewToggleButton :: ToolbarClass self => self -> Int -> StockId -> Maybe (String, String) -> IO ToggleButton
- toolbarAppendNewToggleButton :: ToolbarClass self => self -> String -> Maybe (String, String) -> IO ToggleButton
- toolbarPrependNewToggleButton :: ToolbarClass self => self -> String -> Maybe (String, String) -> IO ToggleButton
- toolbarInsertNewRadioButton :: (ToolbarClass self, RadioButtonClass rb) => self -> Int -> StockId -> Maybe (String, String) -> Maybe rb -> IO RadioButton
- toolbarAppendNewRadioButton :: (ToolbarClass self, RadioButtonClass rb) => self -> String -> Maybe (String, String) -> Maybe rb -> IO RadioButton
- toolbarPrependNewRadioButton :: (ToolbarClass self, RadioButtonClass rb) => self -> String -> Maybe (String, String) -> Maybe rb -> IO RadioButton
- toolbarInsertNewWidget :: (ToolbarClass self, WidgetClass w) => self -> Int -> w -> Maybe (String, String) -> IO ()
- toolbarAppendNewWidget :: (ToolbarClass self, WidgetClass w) => self -> w -> Maybe (String, String) -> IO ()
- toolbarPrependNewWidget :: (ToolbarClass self, WidgetClass w) => self -> w -> Maybe (String, String) -> IO ()
- toolbarSetOrientation :: ToolbarClass self => self -> Orientation -> IO ()
- toolbarGetOrientation :: ToolbarClass self => self -> IO Orientation
- toolbarSetStyle :: ToolbarClass self => self -> ToolbarStyle -> IO ()
- toolbarGetStyle :: ToolbarClass self => self -> IO ToolbarStyle
- toolbarUnsetStyle :: ToolbarClass self => self -> IO ()
- toolbarSetTooltips :: ToolbarClass self => self -> Bool -> IO ()
- toolbarGetTooltips :: ToolbarClass self => self -> IO Bool
- data IconSize
  - = IconSizeInvalid
  - | IconSizeMenu
  - | IconSizeSmallToolbar
  - | IconSizeLargeToolbar
  - | IconSizeButton
  - | IconSizeDnd
  - | IconSizeDialog
  - | IconSizeUser Int
- toolbarSetIconSize :: ToolbarClass self => self -> IconSize -> IO ()
- toolbarGetIconSize :: ToolbarClass self => self -> IO IconSize
- toolbarInsert :: (ToolbarClass self, ToolItemClass item) => self -> item -> Int -> IO ()
- toolbarGetItemIndex :: (ToolbarClass self, ToolItemClass item) => self -> item -> IO Int
- toolbarGetNItems :: ToolbarClass self => self -> IO Int
- toolbarGetNthItem :: ToolbarClass self => self -> Int -> IO (Maybe ToolItem)
- toolbarGetDropIndex :: ToolbarClass self => self -> (Int, Int) -> IO Int
- toolbarSetDropHighlightItem :: (ToolbarClass self, ToolItemClass toolItem) => self -> Maybe toolItem -> Int -> IO ()
- toolbarSetShowArrow :: ToolbarClass self => self -> Bool -> IO ()
- toolbarGetShowArrow :: ToolbarClass self => self -> IO Bool
- data ReliefStyle
  - = ReliefNormal
  - | ReliefHalf
  - | ReliefNone
- toolbarGetReliefStyle :: ToolbarClass self => self -> IO ReliefStyle
- toolbarOrientation :: ToolbarClass self => Attr self Orientation
- toolbarShowArrow :: ToolbarClass self => Attr self Bool
- toolbarTooltips :: ToolbarClass self => Attr self Bool
- toolbarStyle :: ToolbarClass self => Attr self ToolbarStyle
- toolbarChildExpand :: (ToolbarClass self, WidgetClass child) => child -> Attr self Bool
- toolbarChildHomogeneous :: (ToolbarClass self, WidgetClass child) => child -> Attr self Bool
- onOrientationChanged :: ToolbarClass self => self -> (Orientation -> IO ()) -> IO (ConnectId self)
- afterOrientationChanged :: ToolbarClass self => self -> (Orientation -> IO ()) -> IO (ConnectId self)
- onStyleChanged :: ToolbarClass self => self -> (ToolbarStyle -> IO ()) -> IO (ConnectId self)
- afterStyleChanged :: ToolbarClass self => self -> (ToolbarStyle -> IO ()) -> IO (ConnectId self)
- onPopupContextMenu :: ToolbarClass self => self -> (Int -> Int -> Int -> IO Bool) -> IO (ConnectId self)
- afterPopupContextMenu :: ToolbarClass self => self -> (Int -> Int -> Int -> IO Bool) -> IO (ConnectId self)

# Detail

This widget underwent a signficant overhaul in gtk 2.4 and the recommended api changed substantially. The old interface is still supported but it is not recommended.

- The following information applies to the new interface only.

A toolbar is created with a call to `toolbarNew`.

A toolbar can contain instances of a subclass of `ToolItem`. To add a `ToolItem` to the a toolbar, use `toolbarInsert`. To remove an item from the toolbar use `containerRemove`. To add a button to the toolbar, add an instance of `ToolButton`.

Toolbar items can be visually grouped by adding instances of `SeparatorToolItem` to the toolbar. If a `SeparatorToolItem` has the "expand" property set to `True` and the "draw" property set to `False` the effect is to force all following items to the end of the toolbar.

Creating a context menu for the toolbar can be done using `onPopupContextMenu`.

- The following information applies to the old interface only.

`Button`s, `RadioButton`s and `ToggleButton`s can be added by refering to stock images. Their size can be changed by calling `toolbarSetIconSize`. In contrast, normal widget cannot be added. Due to the bad interface of Toolbar mnemonics of `RadioButton`s and `ToggleButton`s are not honored.

All the append, insert and prepend functions use an internal function to do the actual work. In fact the interface is pretty skrewed up: To insert icons by using stock items is definitely the best practice as all other images cannot react to `toolbarSetIconSize` and other theming actions. On the other hand `toolbarInsertStock` always generates simple `Button`s but is the only function that is able to insert `Mnemonic`s on the label. Our solution is to use `StockItem`s to specify all `Images` of the `Buttons`. If the user inserts `RadioButton`s or `ToggleButton`s, the stock image lookup is done manually. A mnemonic in the labels is sadly not honored this way.

# Class Hierarchy

     | GObject
     | +----Object
     | +----Widget
     | +----Container
     | +----Toolbar

# Types

data Toolbar

Instances

Eq Toolbar |
Ord Toolbar |
GObjectClass Toolbar |
ToolbarClass Toolbar |
ContainerClass Toolbar |
WidgetClass Toolbar |
ObjectClass Toolbar |

class ContainerClass o => ToolbarClass o

Instances

ToolbarClass Toolbar |

castToToolbar :: GObjectClass obj => obj -> Toolbar

gTypeToolbar :: GType

toToolbar :: ToolbarClass o => o -> Toolbar

data Orientation

Orientation is good

Constructors

OrientationHorizontal |
OrientationVertical |

Instances

Enum Orientation |
Eq Orientation |
Show Orientation |

data ToolbarStyle

Where to place the toolbar?

Constructors

ToolbarIcons |
ToolbarText |
ToolbarBoth |
ToolbarBothHoriz |

Instances

Enum ToolbarStyle |
Eq ToolbarStyle |
Show ToolbarStyle |

# Constructors

toolbarNew :: IO Toolbar

Creates a new toolbar.

# Methods

toolbarInsertNewButton :: ToolbarClass self => self -> Int -> StockId -> Maybe (String, String) -> IO Button

Insert a new `Button` into the `Toolbar`.

The new `Button` is created at position `pos`, counting from 0.

The icon and label for the button is referenced by `stockId` which must be a valid entry in the `Toolbar`s Style or the default `IconFactory`.

If you whish to have `Tooltips` added to this button you can specify `Just (tipText, tipPrivate)` , otherwise specify `Nothing`.

The newly created `Button` is returned. Use this button to add an action function with `"connectToClicked"`.

- Warning: this function is deprecated and should not be used in newly-written code.

toolbarAppendNewButton :: ToolbarClass self => self -> String -> Maybe (String, String) -> IO Button

Append a new `Button` to the `Toolbar`.

See `toolbarInsertNewButton` for details.

- Warning: this function is deprecated and should not be used in newly-written code.

toolbarPrependNewButton :: ToolbarClass self => self -> String -> Maybe (String, String) -> IO Button

Prepend a new `Button` to the `Toolbar`.

See `toolbarInsertNewButton` for details.

- Warning: this function is deprecated and should not be used in newly-written code.

toolbarInsertNewToggleButton :: ToolbarClass self => self -> Int -> StockId -> Maybe (String, String) -> IO ToggleButton

Insert a new `ToggleButton` into the `Toolbar`.

See `toolbarInsertNewButton` for details.

- Warning: this function is deprecated and should not be used in newly-written code.

toolbarAppendNewToggleButton :: ToolbarClass self => self -> String -> Maybe (String, String) -> IO ToggleButton

Append a new `ToggleButton` to the `Toolbar`.

See `toolbarInsertNewButton` for details.

- Warning: this function is deprecated and should not be used in newly-written code.

toolbarPrependNewToggleButton :: ToolbarClass self => self -> String -> Maybe (String, String) -> IO ToggleButton

Prepend a new `ToggleButton` to the `Toolbar`.

See `toolbarInsertNewButton` for details.

- Warning: this function is deprecated and should not be used in newly-written code.

toolbarInsertNewRadioButton :: (ToolbarClass self, RadioButtonClass rb) => self -> Int -> StockId -> Maybe (String, String) -> Maybe rb -> IO RadioButton

Insert a new `RadioButton` into the `Toolbar`.

See `toolbarInsertNewButton` for details.

- Warning: this function is deprecated and should not be used in newly-written code.

The `parent` argument must be set to another `RadioButton` in the group. If `Nothing` is given, a new group is generated (which is the desired behavious for the first button of a group).

- Warning: this function is deprecated and should not be used in newly-written code.

toolbarAppendNewRadioButton :: (ToolbarClass self, RadioButtonClass rb) => self -> String -> Maybe (String, String) -> Maybe rb -> IO RadioButton

Append a new `RadioButton` to the `Toolbar`.

See `toolbarInsertNewButton` for details.

- Warning: this function is deprecated and should not be used in newly-written code.

toolbarPrependNewRadioButton :: (ToolbarClass self, RadioButtonClass rb) => self -> String -> Maybe (String, String) -> Maybe rb -> IO RadioButton

Prepend a new `RadioButton` to the `Toolbar`.

See `toolbarInsertNewButton` for details.

- Warning: this function is deprecated and should not be used in newly-written code.

toolbarInsertNewWidget :: (ToolbarClass self, WidgetClass w) => self -> Int -> w -> Maybe (String, String) -> IO ()

Insert an arbitrary widget to the `Toolbar`.

The `Widget` should not be a button. Adding `Button`s with the `toolbarInsertButton`,... functions with stock objects is much better as it takes care of theme handling.

- Warning: this function is deprecated and should not be used in newly-written code.

toolbarAppendNewWidget :: (ToolbarClass self, WidgetClass w) => self -> w -> Maybe (String, String) -> IO ()

Append a new `Widget` to the `Toolbar`.

See `toolbarInsertNewButton` for details.

- Warning: this function is deprecated and should not be used in newly-written code.

toolbarPrependNewWidget :: (ToolbarClass self, WidgetClass w) => self -> w -> Maybe (String, String) -> IO ()

Prepend a new `Widget` to the `Toolbar`.

See `toolbarInsertNewButton` for details.

- Warning: this function is deprecated and should not be used in newly-written code.

toolbarSetOrientation :: ToolbarClass self => self -> Orientation -> IO ()

Sets whether a toolbar should appear horizontally or vertically.

toolbarGetOrientation :: ToolbarClass self => self -> IO Orientation

Retrieves the current orientation of the toolbar. See `toolbarSetOrientation`.

toolbarSetStyle :: ToolbarClass self => self -> ToolbarStyle -> IO ()

Alters the view of the toolbar to display either icons only, text only, or both.

toolbarGetStyle :: ToolbarClass self => self -> IO ToolbarStyle

Retrieves whether the toolbar has text, icons, or both. See `toolbarSetStyle`.

toolbarUnsetStyle :: ToolbarClass self => self -> IO ()

Unsets a toolbar style set with `toolbarSetStyle`, so that user preferences will be used to determine the toolbar style.

toolbarSetTooltips

Arguments

:: ToolbarClass self |
=> self |
-> Bool | `enable` - set to `False` to disable the tooltips, or `True` to enable them.
-> IO () |

Sets if the tooltips of a toolbar should be active or not.

toolbarGetTooltips :: ToolbarClass self => self -> IO Bool

Retrieves whether tooltips are enabled. See `toolbarSetTooltips`.

data IconSize

The size of an icon in pixels.

- This enumeration contains one case that is not exported and which is used when new sizes are registered using `Graphics.UI.Gtk.General.IconFactory.iconSizeRegister`.
- Applying `show` to this type will reveal the name of the size that is registered with Gtk+.

Constructors

IconSizeInvalid | Don't scale but use any of the available sizes.
IconSizeMenu | Icon size to use in next to menu items in drop-down menus.
IconSizeSmallToolbar | Icon size for small toolbars.
IconSizeLargeToolbar | Icon size for larger toolbars.
IconSizeButton | Icon size for icons in buttons, next to the label.
IconSizeDnd | Icon size for icons in drag-and-drop.
IconSizeDialog | Icon size for icons next to dialog text.
IconSizeUser Int |

Instances

Enum IconSize |
Eq IconSize |
Show IconSize |

toolbarSetIconSize :: ToolbarClass self => self -> IconSize -> IO ()

This function sets the size of stock icons in the toolbar. You can call it both before you add the icons and after they've been added. The size you set will override user preferences for the default icon size.

It might be sensible to restrict oneself to `IconSizeSmallToolbar` and `IconSizeLargeToolbar`.

- Warning: this function is deprecated and should not be used in newly-written code.

toolbarGetIconSize :: ToolbarClass self => self -> IO IconSize

Retrieves the icon size for the toolbar. See `toolbarSetIconSize`.

toolbarInsert

Arguments

:: (ToolbarClass self, ToolItemClass item) |
=> self |
-> item | `item` - a `ToolItem`
-> Int | `pos` - the position of the new item
-> IO () |

Insert a `ToolItem` into the toolbar at position `pos`. If `pos` is 0 the item is prepended to the start of the toolbar. If `pos` is negative, the item is appended to the end of the toolbar.

- Available since Gtk version 2.4

toolbarGetItemIndex

Arguments

:: (ToolbarClass self, ToolItemClass item) |
=> self |
-> item | `item` - a `ToolItem` that is a child of `toolbar`
-> IO Int | returns the position of item on the toolbar.

Returns the position of `item` on the toolbar, starting from 0. It is an error if `item` is not a child of the toolbar.

- Available since Gtk version 2.4

toolbarGetNItems :: ToolbarClass self => self -> IO Int

Returns the number of items on the toolbar.

- Available since Gtk version 2.4

toolbarGetNthItem

Arguments

:: ToolbarClass self |
=> self |
-> Int | `n` - A position on the toolbar
-> IO (Maybe ToolItem) | returns The `n`'th `ToolItem` on the toolbar, or `Nothing` if there isn't an `n`'th item.

Returns the `n`'th item on toolbar, or `Nothing` if the toolbar does not contain an `n`'th item.

- Available since Gtk+ version 2.4

toolbarGetDropIndex

Arguments

:: ToolbarClass self |
=> self |
-> (Int, Int) | `(x, y)` - coordinate of a point on the toolbar. Note that `(x, y)` are in toolbar coordinates, not window coordinates.
-> IO Int | returns The position corresponding to the point `(x, y)` on the toolbar.

Returns the position corresponding to the indicated point on toolbar. This is useful when dragging items to the toolbar: this function returns the position a new item should be inserted.

- Available since Gtk version 2.4

toolbarSetDropHighlightItem

Arguments

:: (ToolbarClass self, ToolItemClass toolItem) |
=> self |
-> Maybe toolItem | `toolItem` - a `ToolItem`, or `Nothing` to turn of highlighting
-> Int | `index` - a position on the toolbar
-> IO () |

Highlights the toolbar to give an idea of what it would look like if `item` was added to toolbar at the position indicated by `index`. If `item` is `Nothing`, highlighting is turned off (and the index is ignored).

The `toolItem` passed to this function must not be part of any widget hierarchy. When an item is set as a drop highlight item it can not added to any widget hierarchy or used as highlight item for another toolbar.

- Available since Gtk version 2.4

toolbarSetShowArrow :: ToolbarClass self => self -> Bool -> IO ()

Sets whether to show an overflow menu when the toolbar doesn't have room for all items on it. If `True`, items that there are not room are available through an overflow menu.

- Available since Gtk version 2.4

toolbarGetShowArrow :: ToolbarClass self => self -> IO Bool

Returns whether the toolbar has an overflow menu. See `toolbarSetShowArrow`.

- Available since Gtk+ version 2.4

data ReliefStyle

I don't have a clue.

Constructors

ReliefNormal |
ReliefHalf |
ReliefNone |

Instances

Enum ReliefStyle |
Eq ReliefStyle |
Show ReliefStyle |

toolbarGetReliefStyle :: ToolbarClass self => self -> IO ReliefStyle

Returns the relief style of buttons on the toolbar. See `buttonSetRelief`.

- Available since Gtk+ version 2.4

# Attributes

toolbarOrientation :: ToolbarClass self => Attr self Orientation

The orientation of the toolbar.

Default value: `OrientationHorizontal`

toolbarShowArrow :: ToolbarClass self => Attr self Bool

If an arrow should be shown if the toolbar doesn't fit.

Default value: `True`

toolbarTooltips :: ToolbarClass self => Attr self Bool

If the tooltips of the toolbar should be active or not.

Default value: `True`

toolbarStyle :: ToolbarClass self => Attr self ToolbarStyle

How to draw the toolbar.

Default value: `ToolbarIcons`

# Child Attributes

toolbarChildExpand :: (ToolbarClass self, WidgetClass child) => child -> Attr self Bool

Whether the item should receive extra space when the toolbar grows.

Default value: `True`

toolbarChildHomogeneous :: (ToolbarClass self, WidgetClass child) => child -> Attr self Bool

Whether the item should be the same size as other homogeneous items.

Default value: `True`

# Signals

onOrientationChanged :: ToolbarClass self => self -> (Orientation -> IO ()) -> IO (ConnectId self)

afterOrientationChanged :: ToolbarClass self => self -> (Orientation -> IO ()) -> IO (ConnectId self)

Emitted when the orientation of the toolbar changes.

onStyleChanged :: ToolbarClass self => self -> (ToolbarStyle -> IO ()) -> IO (ConnectId self)

afterStyleChanged :: ToolbarClass self => self -> (ToolbarStyle -> IO ()) -> IO (ConnectId self)

Emitted when the style of the toolbar changes.

onPopupContextMenu

Arguments

:: ToolbarClass self |
=> self |
-> (Int -> Int -> Int -> IO Bool) | `(x y button -> ...)` - The handler should return True if the signal was handled, False if not.
-> IO (ConnectId self) |

afterPopupContextMenu

Arguments

:: ToolbarClass self |
=> self |
-> (Int -> Int -> Int -> IO Bool) | `(x y button -> ...)` - The handler should return True if the signal was handled, False if not.
-> IO (ConnectId self) |

Emitted when the user right-clicks the toolbar or uses the keybinding to display a popup menu.

Application developers should handle this signal if they want to display a context menu on the toolbar. The context-menu should appear at the coordinates given by `x` and `y`. The mouse button number is given by the `button` parameter. If the menu was popped up using the keybaord, `button` is -1.