GI.Gtk.Objects.Container

A GTK user interface is constructed by nesting widgets inside widgets. Container widgets are the inner nodes in the resulting tree of widgets: they contain other widgets. So, for example, you might have a Window containing a Frame containing a Label. If you wanted an image instead of a textual label inside the frame, you might replace the Label widget with a Image widget.

There are two major kinds of container widgets in GTK. Both are subclasses of the abstract GtkContainer base class.

The first type of container widget has a single child widget and derives from Bin. These containers are decorators, which add some kind of functionality to the child. For example, a Button makes its child into a clickable button; a Frame draws a frame around its child and a Window places its child widget inside a top-level window.

The second type of container can have more than one child; its purpose is to manage layout. This means that these containers assign sizes and positions to their children. For example, a horizontal Box arranges its children in a horizontal row, and a Grid arranges the widgets it contains in a two-dimensional grid.

For implementations of Container the virtual method ContainerClass.forall() is always required, since it's used for drawing and other internal operations on the children. If the Container implementation expect to have non internal children it's needed to implement both ContainerClass.add() and ContainerClass.remove(). If the GtkContainer implementation has internal children, they should be added with widgetSetParent on init() and removed with widgetUnparent in the WidgetClass.destroy() implementation.

See more about implementing custom widgets at https://wiki.gnome.org/HowDoI/CustomWidgets

Exported types

newtype Container

Memory-managed wrapper type.

Constructors

Container (ManagedPtr Container)

Instances

Eq Container

Defined in GI.Gtk.Objects.Container

Methods

(==) :: Container -> Container -> Bool

(/=) :: Container -> Container -> Bool

IsGValue Container

Convert Container to and from GValue with toGValue and fromGValue.

Defined in GI.Gtk.Objects.Container

Methods

toGValue :: Container -> IO GValue

fromGValue :: GValue -> IO Container

GObject Container

Defined in GI.Gtk.Objects.Container

Methods

gobjectType :: IO GType

HasParentTypes Container

Defined in GI.Gtk.Objects.Container

type ParentTypes Container

Defined in GI.Gtk.Objects.Container

type ParentTypes Container = '[Widget, Object, ImplementorIface, Buildable]

class (GObject o, IsDescendantOf Container o) => IsContainer o

Type class for types which can be safely cast to Container, for instance with toContainer.

Instances

(GObject o, IsDescendantOf Container o) => IsContainer o

Defined in GI.Gtk.Objects.Container

toContainer :: (MonadIO m, IsContainer o) => o -> m Container

Cast to Container, for types for which this is known to be safe. For general casts, use castTo.

noContainer :: Maybe Container

A convenience alias for Nothing :: Maybe Container.

Methods

Overloaded methods

add

containerAdd

Arguments

:: (HasCallStack, MonadIO m, IsContainer a, IsWidget b)

=> a

container: a Container

-> b

widget: a widget to be placed inside container

-> m ()

Adds widget to container. Typically used for simple containers such as Window, Frame, or Button; for more complicated layout containers such Grid, this function will pick default packing parameters that may not be correct. So consider functions such as gridAttach as an alternative to containerAdd in those cases. A widget may be added to only one container at a time; you can’t place the same widget inside two different containers.

Note that some containers, such as ScrolledWindow or ListBox, may add intermediate children between the added widget and the container.

childType

containerChildType

Arguments

:: (HasCallStack, MonadIO m, IsContainer a)

=> a

container: a Container

-> m GType

Returns: a GType

Returns the type of the children supported by the container.

Note that this may return G_TYPE_NONE to indicate that no more children can be added, e.g. for a Paned which already has two children.

forall

containerForall

Arguments

:: (HasCallStack, MonadIO m, IsContainer a)

=> a

container: a Container

-> Callback

callback: a callback

-> m ()

Invokes callback on each direct child of container, including children that are considered “internal” (implementation details of the container). “Internal” children generally weren’t added by the user of the container, but were added by the container implementation itself.

Most applications should use containerForeach, rather than containerForall.

foreach

containerForeach

Arguments

:: (HasCallStack, MonadIO m, IsContainer a)

=> a

container: a Container

-> Callback

callback: a callback

-> m ()

Invokes callback on each non-internal child of container. See containerForall for details on what constitutes an “internal” child. For all practical purposes, this function should iterate over precisely those child widgets that were added to the container by the application with explicit add() calls.

It is permissible to remove the child from the callback handler.

Most applications should use containerForeach, rather than containerForall.

getChildren

containerGetChildren

Arguments

:: (HasCallStack, MonadIO m, IsContainer a)

=> a

container: a Container

-> m [Widget]

Returns: a newly-allocated list of the container’s non-internal children.

Returns the container’s non-internal children. See containerForall for details on what constitutes an "internal" child.

getFocusHadjustment

containerGetFocusHadjustment

Arguments

:: (HasCallStack, MonadIO m, IsContainer a)

=> a

container: a Container

-> m (Maybe Adjustment)

Returns: the horizontal focus adjustment, or Nothing if none has been set.

Retrieves the horizontal focus adjustment for the container. See gtk_container_set_focus_hadjustment ().

getFocusVadjustment

containerGetFocusVadjustment

Arguments

:: (HasCallStack, MonadIO m, IsContainer a)

=> a

container: a Container

-> m (Maybe Adjustment)

Returns: the vertical focus adjustment, or Nothing if none has been set.

Retrieves the vertical focus adjustment for the container. See containerSetFocusVadjustment.

getPathForChild

containerGetPathForChild

Arguments

:: (HasCallStack, MonadIO m, IsContainer a, IsWidget b)

=> a

container: a Container

-> b

child: a child of container

-> m WidgetPath

Returns: A newly created WidgetPath

Returns a newly created widget path representing all the widget hierarchy from the toplevel down to and including child.

remove

containerRemove

Arguments

:: (HasCallStack, MonadIO m, IsContainer a, IsWidget b)

=> a

container: a Container

-> b

widget: a current child of container

-> m ()

Removes widget from container. widget must be inside container. Note that container will own a reference to widget, and that this may be the last reference held; so removing a widget from its container can destroy that widget. If you want to use widget again, you need to add a reference to it before removing it from a container, using objectRef. If you don’t want to use widget again it’s usually more efficient to simply destroy it directly using widgetDestroy since this will remove it from the container and help break any circular reference count cycles.

setFocusHadjustment

containerSetFocusHadjustment

Arguments

:: (HasCallStack, MonadIO m, IsContainer a, IsAdjustment b)

=> a

container: a Container

-> b

adjustment: an adjustment which should be adjusted when the focus is moved among the descendents of container

-> m ()

Hooks up an adjustment to focus handling in a container, so when a child of the container is focused, the adjustment is scrolled to show that widget. This function sets the horizontal alignment. See scrolledWindowGetHadjustment for a typical way of obtaining the adjustment and containerSetFocusVadjustment for setting the vertical adjustment.

The adjustments have to be in pixel units and in the same coordinate system as the allocation for immediate children of the container.

setFocusVadjustment

containerSetFocusVadjustment

Arguments

:: (HasCallStack, MonadIO m, IsContainer a, IsAdjustment b)

=> a

container: a Container

-> b

adjustment: an adjustment which should be adjusted when the focus is moved among the descendents of container

-> m ()

Hooks up an adjustment to focus handling in a container, so when a child of the container is focused, the adjustment is scrolled to show that widget. This function sets the vertical alignment. See scrolledWindowGetVadjustment for a typical way of obtaining the adjustment and containerSetFocusHadjustment for setting the horizontal adjustment.

The adjustments have to be in pixel units and in the same coordinate system as the allocation for immediate children of the container.

Signals

add

type C_ContainerAddCallback = Ptr () -> Ptr Widget -> Ptr () -> IO ()

Type for the callback on the (unwrapped) C side.

type ContainerAddCallback = Widget -> IO ()

No description available in the introspection data.

afterContainerAdd :: (IsContainer a, MonadIO m) => a -> ContainerAddCallback -> m SignalHandlerId

Connect a signal handler for the add signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after container #add callback

genClosure_ContainerAdd :: MonadIO m => ContainerAddCallback -> m (GClosure C_ContainerAddCallback)

Wrap the callback into a GClosure.

mk_ContainerAddCallback :: C_ContainerAddCallback -> IO (FunPtr C_ContainerAddCallback)

Generate a function pointer callable from C code, from a C_ContainerAddCallback.

noContainerAddCallback :: Maybe ContainerAddCallback

A convenience synonym for Nothing :: Maybe ContainerAddCallback.

onContainerAdd :: (IsContainer a, MonadIO m) => a -> ContainerAddCallback -> m SignalHandlerId

Connect a signal handler for the add signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on container #add callback

wrap_ContainerAddCallback :: ContainerAddCallback -> C_ContainerAddCallback

Wrap a ContainerAddCallback into a C_ContainerAddCallback.

remove

type C_ContainerRemoveCallback = Ptr () -> Ptr Widget -> Ptr () -> IO ()

Type for the callback on the (unwrapped) C side.

type ContainerRemoveCallback = Widget -> IO ()

No description available in the introspection data.

afterContainerRemove :: (IsContainer a, MonadIO m) => a -> ContainerRemoveCallback -> m SignalHandlerId

Connect a signal handler for the remove signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after container #remove callback

genClosure_ContainerRemove :: MonadIO m => ContainerRemoveCallback -> m (GClosure C_ContainerRemoveCallback)

Wrap the callback into a GClosure.

mk_ContainerRemoveCallback :: C_ContainerRemoveCallback -> IO (FunPtr C_ContainerRemoveCallback)

Generate a function pointer callable from C code, from a C_ContainerRemoveCallback.

noContainerRemoveCallback :: Maybe ContainerRemoveCallback

A convenience synonym for Nothing :: Maybe ContainerRemoveCallback.

onContainerRemove :: (IsContainer a, MonadIO m) => a -> ContainerRemoveCallback -> m SignalHandlerId

Connect a signal handler for the remove signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on container #remove callback

wrap_ContainerRemoveCallback :: ContainerRemoveCallback -> C_ContainerRemoveCallback

Wrap a ContainerRemoveCallback into a C_ContainerRemoveCallback.