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

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

Graphics.UI.Gtk.Abstract.Box

Contents

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

Description

Base class for box containers

Synopsis

- data Box
- class ContainerClass o => BoxClass o
- castToBox :: GObjectClass obj => obj -> Box
- gTypeBox :: GType
- toBox :: BoxClass o => o -> Box
- data Packing
  - = PackRepel
  - | PackGrow
  - | PackNatural
- boxPackStart :: (BoxClass self, WidgetClass child) => self -> child -> Packing -> Int -> IO ()
- boxPackEnd :: (BoxClass self, WidgetClass child) => self -> child -> Packing -> Int -> IO ()
- boxPackStartDefaults :: (BoxClass self, WidgetClass widget) => self -> widget -> IO ()
- boxPackEndDefaults :: (BoxClass self, WidgetClass widget) => self -> widget -> IO ()
- boxGetHomogeneous :: BoxClass self => self -> IO Bool
- boxSetHomogeneous :: BoxClass self => self -> Bool -> IO ()
- boxGetSpacing :: BoxClass self => self -> IO Int
- boxSetSpacing :: BoxClass self => self -> Int -> IO ()
- boxReorderChild :: (BoxClass self, WidgetClass child) => self -> child -> Int -> IO ()
- boxQueryChildPacking :: (BoxClass self, WidgetClass child) => self -> child -> IO (Packing, Int, PackType)
- boxSetChildPacking :: (BoxClass self, WidgetClass child) => self -> child -> Packing -> Int -> PackType -> IO ()
- boxSpacing :: BoxClass self => Attr self Int
- boxHomogeneous :: BoxClass self => Attr self Bool
- boxChildPacking :: (BoxClass self, WidgetClass child) => child -> Attr self Packing
- boxChildPadding :: (BoxClass self, WidgetClass child) => child -> Attr self Int
- boxChildPackType :: (BoxClass self, WidgetClass child) => child -> Attr self PackType
- boxChildPosition :: (BoxClass self, WidgetClass child) => child -> Attr self Int

# Detail

`Box` is an abstract widget which encapsulates functionality for a particular kind of container, one that organizes a variable number of widgets into a rectangular area. `Box` currently has two derived classes, `HBox` and `VBox`.

The rectangular area of a `Box` is organized into either a single row or a single column of child widgets depending upon whether the box is of type `HBox` or `VBox`, respectively. Thus, all children of a `Box` are allocated one dimension in common, which is the height of a row, or the width of a column.

`Box` uses a notion of packing. Packing refers to adding widgets with reference to a particular position in a `Container`. For a `Box`, there are two reference positions: the start and the end of the box. For a `VBox`, the start is defined as the top of the box and the end is defined as the bottom. For a `HBox` the start is defined as the left side and the end is defined as the right side.

Use repeated calls to `boxPackStart` to pack widgets into a `Box` from start to end. Use `boxPackEnd` to add widgets from end to start. You may intersperse these calls and add widgets from both ends of the same `Box`. Besides adding widgets at the start or the end of a box, you can also specify the padding around each widget (in pixels) and a `Packing` parameter that denotes how to fill up unused space. The functions `boxPackStartDefaults` or `boxPackEndDefaults` are a convenient way to pack widgets into a `Box` without specifying these extra paramters.

While the right amount of padding around each widget is a matter of appearance, the `Packing` paramter specifies the way the widgets in the container behave when the window is resized and thereby affect the usability. Hence, once you have created a window, you should resize it and see if the widgets behave as expected. The `Packing` parameter of each child widget determines how excess space is used by that particular widget. See the description of `Packing` for a detailed explanaition.

Because `Box` is a `Container`, you may also use `Graphics.UI.Gtk.Abstract.Container.containerAdd` to insert widgets into the box, and they will be packed as if with `boxPackStartDefaults`. Use `Graphics.UI.Gtk.Abstract.Container.containerRemove` to remove widgets from the `Box`.

Use `boxSetHomogeneous` to specify whether or not all children of the `Box` are forced to get the same amount of space. Note that the `Packing` options `PackNatural` and `PackRepel` coincide if space is allotted homogeneously.

Use `boxSetSpacing` to determine how much space will be minimally placed between all children in the `Box`.

Use `boxReorderChild` to move a `Box` child to a different place in the box.

Use `boxSetChildPacking` to reset the expand, fill, and padding attributes of any `Box` child. Use `boxQueryChildPacking` to query these fields.

# Class Hierarchy

     | GObject
     | +----Object
     | +----Widget
     | +----Container
     | +----Box
     | +----ButtonBox
     | +----VBox
     | +----HBox

# Types

data Box

Instances

Eq Box |
Ord Box |
GObjectClass Box |
BoxClass Box |
ContainerClass Box |
WidgetClass Box |
ObjectClass Box |

class ContainerClass o => BoxClass o

Instances

BoxClass Statusbar |
BoxClass FileChooserButton |
BoxClass Combo |
BoxClass InfoBar |
BoxClass HBox |
BoxClass FileChooserWidget |
BoxClass FontSelection |
BoxClass ColorSelection |
BoxClass RecentChooserWidget |
BoxClass VBox |
BoxClass VButtonBox |
BoxClass HButtonBox |
BoxClass ButtonBox |
BoxClass Box |

castToBox :: GObjectClass obj => obj -> Box

gTypeBox :: GType

toBox :: BoxClass o => o -> Box

data Packing

Packing parameters of a widget

- The `Packing` parameter determines how the child behaves in the horizontal or vertical way in an `Graphics.UI.Gtk.Layout.HBox` or `Graphics.UI.Gtk.Layout.VBox`, respectively. `PackNatural` means the child is as big as it reqests. It will stay at the start of the end of a `Graphics.UI.Gtk.Layout.Box` if there is more space available. All children packed with `PackRepel` will be padded on both sides with additional space. `PackGrow` will increase the size of a widget so that it covers the available space. A menu bar, for instance, should always stay at the top of a window and should only occupy as little space as possible. Hence it should be packed at the start of a `Graphics.UI.Gtk.Layout.VBox` with the packing option `PackNatural`. The working area of a window (e.g. the text area in an editor) should expand when the window is resized. Here the packing option `PackGrow` is the right choice and it is irrelevant whether the main area is inserted at the start or the end of a box. Finally `PackRepel` is most useful in a window where no widget can make use of excess space. Examples include a dialog box without list boxes or text fields.

Constructors

PackRepel |
PackGrow |
PackNatural |

Instances

Enum Packing |
Eq Packing |
Show Packing |

# Methods

boxPackStart

Arguments

:: (BoxClass self, WidgetClass child) |
=> self |
-> child | `child` - the `Widget` to be added to the box.
-> Packing |
-> Int | `padding` - extra space in pixels to put between this child and its neighbors, over and above the global amount specified by spacing `boxSetSpacing`. If `child` is a widget at one of the reference ends of `box`, then `padding` pixels are also put between `child` and the reference edge of `box`.
-> IO () |

Adds the `child` widget to the box, packed with reference to the start of the box. The `child` is packed after any other child packed with reference to the start of the box.

boxPackEnd

Arguments

:: (BoxClass self, WidgetClass child) |
=> self |
-> child | `child` - the `Widget` to be added to the box.
-> Packing |
-> Int | `padding` - extra space in pixels to put between this child and its neighbors, over and above the global amount specified by spacing `boxSetSpacing`. If `child` is a widget at one of the reference ends of `box`, then `padding` pixels are also put between `child` and the reference edge of `box`.
-> IO () |

Adds the `child` widget to the box, packed with reference to the end of the box. The `child` is packed after (away from end of) any other child packed with reference to the end of the box.

Note that for `boxPackEnd` the `PackNatural` option will move a child to the right in an `HBox` or to the bottom in an `VBox` if there is more space availble.

boxPackStartDefaults

Arguments

:: (BoxClass self, WidgetClass widget) |
=> self |
-> widget | `widget` - the `Widget` to be added to the box.
-> IO () |

Like `boxPackStart` but uses the default parameters `PackRepel` and 0 for padding.

boxPackEndDefaults

Arguments

:: (BoxClass self, WidgetClass widget) |
=> self |
-> widget | `widget` - the `Widget` to be added to the box.
-> IO () |

Like `boxPackEnd` but uses the default parameters `PackRepel` and 0 for padding.

boxGetHomogeneous

Arguments

:: BoxClass self |
=> self |
-> IO Bool | returns `True` if the box is homogeneous.

Returns whether the box is homogeneous (all children are the same size). See `boxSetHomogeneous`.

boxSetHomogeneous

Arguments

:: BoxClass self |
=> self |
-> Bool | `homogeneous` - a boolean value, `True` to create equal allotments, `False` for variable allotments.
-> IO () |

Sets the homogeneous property, controlling whether or not all children of the box are given equal space

boxGetSpacing

Arguments

:: BoxClass self |
=> self |
-> IO Int | returns spacing between children

Retrieves the standard spacing between widgets.

boxSetSpacing

Arguments

:: BoxClass self |
=> self |
-> Int | `spacing` - the number of pixels to put between children.
-> IO () |

Set the standard spacing between two children.

This space is in addition to the padding parameter that is given for each child.

boxReorderChild

Arguments

:: (BoxClass self, WidgetClass child) |
=> self |
-> child | `child` - the `Widget` to move.
-> Int | `position` - the new position for `child` in the children list starting from 0. If negative, indicates the end of the list.
-> IO () |

Moves `child` to a new `position` in the list of `box` children. The list contains both widgets packed `PackStart` as well as widgets packed `PackEnd`, in the order that these widgets were added to the box.

A widget's position in the box children list determines where the widget is packed into the box. A child widget at some position in the list will be packed just after all other widgets of the same packing type that appear earlier in the list.

boxQueryChildPacking

Arguments

:: (BoxClass self, WidgetClass child) |
=> self |
-> child | `child` - the `Widget` of the child to query.
-> IO (Packing, Int, PackType) |
    (packing, padding, packType)

Returns information about how `child` is packed into the box.

Returns information on the behaviour if free space is available (in `Packing`), the additional padding for this widget and if the widget was inserted at the start or end of the container (`PackType`).

boxSetChildPacking

Arguments

:: (BoxClass self, WidgetClass child) |
=> self |
-> child | `child` - the `Widget` of the child to set.
-> Packing |
-> Int |
    padding
-> PackType |
    packType
-> IO () |

Sets the way `child` is packed into the box.

# Attributes

boxSpacing :: BoxClass self => Attr self Int

The amount of space between children.

Allowed values: >= 0

Default value: 0

boxHomogeneous :: BoxClass self => Attr self Bool

Whether the children should all be the same size.

Default value: `False`

# Child Attributes

boxChildPacking :: (BoxClass self, WidgetClass child) => child -> Attr self Packing

The packing style of the child.

Default value: ``PackGrow``

boxChildPadding :: (BoxClass self, WidgetClass child) => child -> Attr self Int

Extra space to put between the child and its neighbors, in pixels.

Allowed values: <= `(`maxBound` :: Int)`

Default value: 0

boxChildPackType :: (BoxClass self, WidgetClass child) => child -> Attr self PackType

A `PackType` indicating whether the child is packed with reference to the start or end of the parent.

Default value: `PackStart`

boxChildPosition :: (BoxClass self, WidgetClass child) => child -> Attr self Int

The index of the child in the parent.

Allowed values: >= -1

Default value: 0