gtk.Paned
Prev | The gtk Class Reference | Next

## gtk.Paned

gtk.Paned — a base class for widgets with two adjustable panes

## Synopsis

    class gtk.Paned(gtk.Container):
        def add1(child)
        def add2(child)
        def pack1(child, resize=False, shrink=True)
        def pack2(child, resize=True, shrink=True)
        def get_position()
        def set_position(position)
        def compute_position(allocation, child1_req, child2_req)
        def get_child1()
        def get_child2()

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.Widget
          +-- gtk.Container
            +-- gtk.Paned

## Implemented Interfaces

`gtk.Paned` implements `gtk.Buildable`

## gtk.Paned Properties

gtk.Object Properties

gtk.Widget Properties

gtk.Container Properties

"max-position" | Read-Write | The largest possible value for the position property. This property is derived from the size and shrinkability of the widget's children. Available in GTK+ 2.4 and above.
"min-position" | Read-Write | The smallest possible value for the position property. This property is derived from the size and shrinkability of the widget's children. Available in GTK+ 2.4 and above.
"position" | Read-Write | The position of the paned separator in pixels (0 means all the way to the left or top).
"position-set" | Read-Write | If `True`, the "position" property is valid.

## gtk.Paned Child Properties

"resize" | Read-Write | If `True`, the child expands and shrinks along with the paned widget. Available in GTK+ 2.4 and above.
"shrink" | Read-Write | If `True`, the child can be made smaller than its requisition. Available in GTK+ 2.4 and above.

## gtk.Paned Style Properties

gtk.Widget Style Properties

"handle-size" | Read | The width of the handle

## gtk.Paned Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

gtk.Widget Signal Prototypes

gtk.Container Signal Prototypes

"accept-position" | `def callback(`paned`, `user_param1`, `...`)`
"cancel-position" | `def callback(`paned`, `user_param1`, `...`)`
"cycle-child-focus" | `def callback(`paned`, `reversed`, `user_param1`, `...`)`
"cycle-handle-focus" | `def callback(`paned`, `reversed`, `user_param1`, `...`)`
"move-handle" | `def callback(`paned`, `scrolltype`, `user_param1`, `...`)`
"toggle-handle-focus" | `def callback(`paned`, `user_param1`, `...`)`

## Description

`gtk.Paned` is the base class for widgets with two panes, arranged either horizontally (`gtk.HPaned`) or vertically (`gtk.VPaned`). Child widgets are added to the panes of the widget with the `pack1`() and `pack2`() methods. The division between the two children is set by default from the size requests of the children, but it can be adjusted by the user.

A paned widget draws a separator between the two child widgets and a small handle that the user can drag to adjust the division. It does not draw any relief around the children or around the separator. (The space in which the separator located is called the gutter.) Often, it is useful to put each child inside a `gtk.Frame` with the shadow type set to `gtk.SHADOW_IN` so that the gutter appears as a ridge.

Each child has two options that can be set, resize and shrink. If resize is `True`, when the `gtk.Paned` is resized, that child will expand or shrink along with the paned widget. If shrink is `True`, the child can be made smaller than it's requisition. Setting shrink to `False` allows the application to set a minimum size. If resize is `False` for both children, the resizing behaves as if resize is `True` for both children. The application can set the position of the slider by calling the `set_position`() method.

## Methods

### gtk.Paned.add1

        def add1(child)

`child` : | the widget to add

The `add1`() method adds the widget specified by `child` to the top or left pane with the default packing parameters (resize is `False` and shrink is `True`). See the `pack1`() method.

### gtk.Paned.add2

        def add2(child)

`child` : | the widget to add

The `add2`() method adds the widget specified by `child` to the bottom or right pane with the default packing parameters (resize is `True` and shrink is `True`). See the `pack2`() method.

### gtk.Paned.pack1

        def pack1(child, resize=False, shrink=True)

`child` : | the widget to add
`resize` : | if `True` `child` should resize when the paned is resized
`shrink` : | if `True` `child` can be made smaller than its minimum size request

The `pack1`() method adds the widget specified by `child` to the top or left pane with the parameters specified by `resize` and `shrink`. If `resize` is `True` `child` should be resized when the paned widget is resized. If `shrink` is `True` `child` can be made smaller than its minimum size request.

### gtk.Paned.pack2

        def pack2(child, resize=True, shrink=True)

`child` : | the widget to add
`resize` : | if `True` `child` should resize when the paned is resized
`shrink` : | if `True` `child` can be made smaller than its minimum size request

The `pack2`() method adds the widget specified by `child` to the bottom or right pane with the parameters specified by `resize` and `shrink`. If `resize` is `True` `child` should be resized when the paned widget is resized. If `shrink` is `True` `child` can be made smaller than its minimum size request.

### gtk.Paned.get_position

        def get_position()

Returns : | the position of the divider

The `get_position`() method returns the position of the divider in pixels between the two panes.

### gtk.Paned.set_position

        def set_position(position)

`position` : | the new pixel position of divider, a negative value means that the position is unset.

The `set_position`() method sets the position of the divider between the two panes to the value specified by `position` and sets the "position-set" property to `True` if `position` is non-negative. If `position` is negative the divider position will be recalculated by the paned widget using the child widget requisitions and the "position-set" property will be set to `False`.

### gtk.Paned.compute_position

        def compute_position(allocation, child1_req, child2_req)

`allocation` : | the total space allocation in pixels for the paned widget
`child1_req` : | the minimum space in pixels required for the left or top child widget
`child2_req` : | the minimum space in pixels required for the right or bottom child widget

The `compute_position`() method computes the position of the separator according to the specification of the parameters: `allocation`, `child1_req` and `child2_req`. The calculation is affected by the packing parameters of the child widgets depending on whether they can resize and shrink. This method is used by subclasses of `gtk.Paned` and is usually not needed by applications. the `gtk.Widget.queue_resize`() method must be called after this method to have the resizing displayed.

The minimum position is 0 if child1's shrink value is `True` or the value of `child1_req`, if `False`. The maximum position is the value of `allocation` if child2's shrink value is True, or the value of (`allocation` - `child2_req`), if `False`. The final calculated position will be between the minimum and maximum positions.

### gtk.Paned.get_child1

        def get_child1()

Returns : | the first child, or`None`

### Note

This method is available in PyGTK 2.4 and above.

The `get_child1`() method returns the first child of the paned widget.

### gtk.Paned.get_child2

        def get_child2()

Returns : | the second child, or `None`

### Note

This method is available in PyGTK 2.4 and above.

The `get_child2`() method returns the second child of the paned widget.

## Signals

### The "accept-position" gtk.Paned Signal

        def callback(paned, user_param1, ...)

`paned` : | the paned that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if the signal was handled

The "accept-position" signal is emitted when `paned` has the focus and any of the Return, Enter, Space keys are pressed. This will also cause the child widget with the focus to be activated.

### The "cancel-position" gtk.Paned Signal

        def callback(paned, user_param1, ...)

`paned` : | the paned that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if the signal was handled

The "cancel-position" signal is emitted when the Esc key is pressed while `paned` has the focus.

### The "cycle-child-focus" gtk.Paned Signal

        def callback(paned, reversed, user_param1, ...)

`paned` : | the paned that received the signal
`reversed` : | if `True` the focus cycle direction should be reversed
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if the signal was handled

The "cycle-child-focus" signal is emitted when F6 or Shift+F6 is pressed while `paned` has the focus.

### The "cycle-handle-focus" gtk.Paned Signal

        def callback(paned, reversed, user_param1, ...)

`paned` : | the paned that received the signal
`reversed` : | if `True` the focus cycle direction should be reversed
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if the signal was handled

The "cycle-handle-focus" signal is emitted when `paned` has the focus and any of the Tab, Ctrl+Tab, Shift+Tab or Ctrl+Shift+Tab keys combinations are pressed. Tab and Ctrl+Tab set `reversed` to `False` while Shift+Tab and Ctrl+Shift+Tab set `reversed` to `True`.

### The "move-handle" gtk.Paned Signal

        def callback(paned, scrolltype, user_param1, ...)

`paned` : | the paned that received the signal
`scrolltype` : | the scroll type: `gtk.SCROLL_NONE`, `gtk.SCROLL_JUMP`, `gtk.SCROLL_STEP_BACKWARD`, `gtk.SCROLL_STEP_FORWARD`, `gtk.SCROLL_PAGE_BACKWARD`, `gtk.SCROLL_PAGE_FORWARD`, `gtk.SCROLL_STEP_UP`, `gtk.SCROLL_STEP_DOWN`, `gtk.SCROLL_PAGE_UP`, `gtk.SCROLL_PAGE_DOWN`, `gtk.SCROLL_STEP_LEFT`, `gtk.SCROLL_STEP_RIGHT`, `gtk.SCROLL_PAGE_LEFT`, `gtk.SCROLL_PAGE_RIGHT`, `gtk.SCROLL_START` or `gtk.SCROLL_END`
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if the signal was handled

The "move-handle" signal is emitted when `paned` has the focus and one of the following key combinations is pressed to move the separator:

- Left Arrow
- Right Arrow
- Up Arrow
- Down Arrow
- Page Up
- Page Down
- Home
- End

The value of `scrolltype` is one of: `gtk.SCROLL_NONE`, `gtk.SCROLL_JUMP`, `gtk.SCROLL_STEP_BACKWARD`, `gtk.SCROLL_STEP_FORWARD`, `gtk.SCROLL_PAGE_BACKWARD`, `gtk.SCROLL_PAGE_FORWARD`, `gtk.SCROLL_STEP_UP`, `gtk.SCROLL_STEP_DOWN`, `gtk.SCROLL_PAGE_UP`, `gtk.SCROLL_PAGE_DOWN`, `gtk.SCROLL_STEP_LEFT`, `gtk.SCROLL_STEP_RIGHT`, `gtk.SCROLL_PAGE_LEFT`, `gtk.SCROLL_PAGE_RIGHT`, `gtk.SCROLL_START` or `gtk.SCROLL_END`. The default handler for this signal moves the separator if the separator has the focus.

### The "toggle-handle-focus" gtk.Paned Signal

        def callback(paned, user_param1, ...)

`paned` : | the paned that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if the signal was handled

The "toggle-handle-focus" signal is emitted when `paned` has the focus and F8 is pressed to give the focus to or take the focus from the separator handle.

Prev | Up | Next
gtk.PageSetup | Home | gtk.PaperSize