gtk.HandleBox
Prev | The gtk Class Reference | Next

## gtk.HandleBox

gtk.HandleBox — a widget for detachable window portions.

## Synopsis

    class gtk.HandleBox(gtk.Bin):
        gtk.HandleBox()
        def set_shadow_type(type)
        def get_shadow_type()
        def set_handle_position(position)
        def get_handle_position()
        def set_snap_edge(edge)
        def get_snap_edge()
        def get_child_detached()

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.Widget
          +-- gtk.Container
            +-- gtk.Bin
              +-- gtk.HandleBox

## Implemented Interfaces

`gtk.HandleBox` implements `gtk.Buildable`

## gtk.HandleBox Properties

gtk.Object Properties

gtk.Widget Properties

gtk.Container Properties

"child-detached" | Read | `True` if the handlebox's child is detached, `False` otherwise.
"handle-position" | Read-Write | The position of the handle relative to the child widget; one of the GTK Position Type Constants.
"shadow-type" | Read-Write | The type of shadow; one of the GTK Shadow Type Constants.
"snap-edge" | Read-Write | The side of the handlebox that's lined up with the docking point to dock the handlebox; one of the GTK Position Type Constants.
"snap-edge-set" | Read-Write | If `True`, use the value from "snap-edge"; otherwise, use a value derived from "handle-position". Available in GTK+ 2.2 and above.

## gtk.HandleBox Style Properties

gtk.Widget Style Properties

## gtk.HandleBox Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

gtk.Widget Signal Prototypes

gtk.Container Signal Prototypes

"child-attached" | `def callback(`handlebox`, `widget`, `user_param1`, `...`)`
"child-detached" | `def callback(`handlebox`, `widget`, `user_param1`, `...`)`

## Description

The `gtk.HandleBox` widget allows a portion of a window to be "torn off". It is a bin widget which displays its child and a handle that the user can drag to tear off into a separate floating window containing the child widget. A thin ghost is drawn in the original location of the handlebox. The separate window can be dragged back to its original location to be reattached. When reattaching, the ghost and float window, must be aligned along one of the edges called the snap edge that can be specified by the application, or specified automatically using a reasonable default based on the handle position. The snap edge is automatically set as `gtk.POS_TOP` if the handle position is `gtk.POS_RIGHT` or `gtk.POS_LEFT`; otherwise, the snap edge will be set as `gtk.POS_LEFT`.

To make detaching and reattaching the handlebox as minimally confusing as possible to the user, it is important to set the snap edge so that the snap edge does not move when the handlebox is detached. For example, if the handlebox is packed at the bottom of a `gtk.VBox`, then when the handlebox is detached, the bottom edge of the handlebox's allocation will remain fixed as the height of the handlebox shrinks, so the snap edge should be set to `gtk.POS_BOTTOM`.

## Constructor

        gtk.HandleBox()

Returns : | a new handlebox widget

Creates a new `gtk.HandleBox` widget.

## Methods

### gtk.HandleBox.set_shadow_type

        def set_shadow_type(type)

`type` : | the shadow type: `gtk.SHADOW_NONE`, `gtk.SHADOW_IN`, `gtk.SHADOW_OUT`, `gtk.SHADOW_ETCHED_IN`, `gtk.SHADOW_ETCHED_OUT`

The `set_shadow_type`() method sets the type of shadow to be drawn around the border of the handle box as specified by `type`. The value of `type` must be one of: `gtk.SHADOW_NONE`, `gtk.SHADOW_IN`, `gtk.SHADOW_OUT`, `gtk.SHADOW_ETCHED_IN`, `gtk.SHADOW_ETCHED_OUT`.

### gtk.HandleBox.get_shadow_type

        def get_shadow_type()

Returns : | the type of shadow currently drawn around the handle box.

The `get_shadow_type`() method gets the type of shadow drawn around the handle box. The shadow type is one of: `gtk.SHADOW_NONE`, `gtk.SHADOW_IN`, `gtk.SHADOW_OUT`, `gtk.SHADOW_ETCHED_IN`, `gtk.SHADOW_ETCHED_OUT`. See `set_shadow_type`().

### gtk.HandleBox.set_handle_position

        def set_handle_position(position)

`position` : | the side of the handlebox where the handle should be drawn.

The `set_handle_position`() method sets the side of the handlebox where the handle is drawn using the value of `position`. The value of `position` must be one of: `gtk.POS_LEFT`, `gtk.POS_RIGHT`, `gtk.POS_TOP`, `gtk.POS_BOTTOM`

### gtk.HandleBox.get_handle_position

        def get_handle_position()

Returns : | the current handle position.

The `get_handle_position`() method gets the handle position of the handle box; one of: `gtk.POS_LEFT`, `gtk.POS_RIGHT`, `gtk.POS_TOP`, `gtk.POS_BOTTOM`. See `set_handle_position`().

### gtk.HandleBox.set_snap_edge

        def set_snap_edge(edge)

`edge` : | the edge to use as the snap edge or -1 to have PyGTK automatically pick the snap edge

The `set_snap_edge`() method sets the snap edge of the handlebox to the value specified by `edge`. The value of `edge` can be one of: `gtk.POS_LEFT`, `gtk.POS_RIGHT`, `gtk.POS_TOP`, `gtk.POS_BOTTOM` or -1 to have the snap edge automatically specified.

The snap edge is the edge of the detached child that must be aligned with the corresponding edge of the "ghost" left behind when the child was detached to reattach the torn-off window. Usually, the snap edge should be chosen so that it stays in the same place on the screen when the handlebox is torn off. If the snap edge is not set, then an appropriate value will be guessed from the handle position. If the handle position is `gtk.POS_RIGHT` or `gtk.POS_LEFT`, then the snap edge will be `gtk.POS_TOP`, otherwise it will be `gtk.POS_LEFT`.

### gtk.HandleBox.get_snap_edge

        def get_snap_edge()

Returns : | the edge used for determining reattachment, or -1 if the snap edge is determined (as per default) from the handle position.

The `get_snap_edge`() method gets the edge used for determining reattachment of the handle box. The return value will be one of: `gtk.POS_LEFT`, `gtk.POS_RIGHT`, `gtk.POS_TOP`, `gtk.POS_BOTTOM` or -1 to indicate the snap edge is automatically selected. See `set_snap_edge`().

### gtk.HandleBox.get_child_detached

        def get_child_detached()

Returns : | `True` if the child is currently detached, otherwise `False`

### Note

This method is available in PyGTK 2.14 and above.

The `get_child_detached`() method gets whether the handlebox's child is currently detached.

## Signals

### The "child-attached" gtk.HandleBox Signal

        def callback(handlebox, widget, user_param1, ...)

`handlebox` : | the widget that received the signal
`widget` : | the child widget
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "child-attached" signal is emitted when the contents of the handlebox are reattached to the main window.

### The "child-detached" gtk.HandleBox Signal

        def callback(handlebox, widget, user_param1, ...)

`handlebox` : | the widget that received the signal
`widget` : | the child widget
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "child-detached" signal is emitted when the contents of the handlebox are detached from the main window.

Prev | Up | Next
gtk.GenericTreeModel | Home | gtk.HBox