gtk.Expander
Prev | The gtk Class Reference | Next

## gtk.Expander

gtk.Expander — a container that can hide its child (new in PyGTK 2.4)

## Synopsis

    class gtk.Expander(gtk.Bin):
        gtk.Expander(label=None)
        def set_expanded(expanded)
        def get_expanded()
        def set_spacing(spacing)
        def get_spacing()
        def set_label(label)
        def get_label()
        def set_use_underline(use_underline)
        def get_use_underline()
        def set_use_markup(use_markup)
        def get_use_markup()
        def set_label_widget(label_widget)
        def get_label_widget()

    Functions

        def gtk.expander_new_with_mnemonic(label=None)

## Ancestry

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

## gtk.Expander Properties

gtk.Object Properties

gtk.Widget Properties

gtk.Container Properties

"expanded" | Read-Write | If `True`, the expander has been opened to reveal the child widget.
"label" | Read-Write | The text of the expander's label.
"label-widget" | Read-Write | A widget to display in place of the usual expander label.
"spacing" | Read-Write | The space to put between the label and the child.
"use-markup" | Read-Write | If `True`, the text of the label includes Pango markup. See the `pango.parse_markup`() function.
"use-underline" | Read-Write | If `True`, n underline in the text indicates the next character should be used for the mnemonic accelerator key.

## gtk.Expander Style Properties

gtk.Widget Style Properties

"expander-size" | Read | The size of the expander arrow.
"expander-spacing" | Read | The spacing around expander arrow.

## gtk.Expander Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

gtk.Widget Signal Prototypes

gtk.Container Signal Prototypes

"activate" | `def callback(`expander`, `user_param1`, `...`)`

## Description

### Note

This widget is available in PyGTK 2.4 and above.

A `gtk.Expander` allows the user to hide or show its child by clicking on an expander triangle similar to the triangles used in a `gtk.TreeView`.

Normally you use an expander as you would use any other descendant of `gtk.Bin`; you create the child widget and use `gtk.Container.add`() to add it to the expander. When the expander is toggled, it will take care of showing and hiding the child automatically.

### Special Usage

There there are situations in which you may prefer to show and hide the expanded widget yourself, such as when you want to actually create the widget at expansion time. In this case, create a `gtk.Expander` but do not add a child to it. The expander widget has the "expanded" property that can be used to monitor its expansion state. You should watch this property with a signal connection as follows:

      expander = gtk.expander_new_with_mnemonic("_More Options")
      expander.connect("notify::expanded", expander_callback)

      ...

      def expander_callback(expander, param_spec, user_data):
        if expander.get_expanded():
          # Show or create widgets
        else:
          # Hide or destroy widgets

The "activate" signal can also be used to track the expansion though it occurs before the "expanded" property is changed so the logic of the `expander_callback`() function would have to be reversed.

## Constructor

        gtk.Expander(label=None)

`label` : | the text of the label or `None`
Returns : | a new `gtk.Expander` widget.

### Note

This constructor is available in PyGTK 2.4 and above.

Creates a new expander using `label` as the text of the label. If `label` is `None` or not specified, no label will be created.

## Methods

### gtk.Expander.set_expanded

        def set_expanded(expanded)

`expanded` : | if `True`, the child widget is revealed

### Note

This method is available in PyGTK 2.4 and above.

The `set_expanded`() method sets the "expanded" property to the value of `expanded`. If `expanded` is `True`, the child widget is revealed; if `False`, the child widget is hidden.

### gtk.Expander.get_expanded

        def get_expanded()

Returns : | True if the child is revealed.

### Note

This method is available in PyGTK 2.4 and above.

The `get_expanded`() method returns the value of the "expanded" property. If "expanded" is `True` the child widget is revealed.

### gtk.Expander.set_spacing

        def set_spacing(spacing)

`spacing` : | the distance between the expander and child in pixels.

### Note

This method is available in PyGTK 2.4 and above.

The `set_spacing`() method sets the "spacing" property to the value of `spacing` that sets is the number of pixels to place between expander and the child.

### gtk.Expander.get_spacing

        def get_spacing()

Returns : | the spacing between the expander and child.

### Note

This method is available in PyGTK 2.4 and above.

The `get_spacing`() method returns the value of the "spacing" property set by the `set_spacing()` method.

### gtk.Expander.set_label

        def set_label(label)

`label` : | a string to use as the label or `None`

### Note

This method is available in PyGTK 2.4 and above.

The `set_label`() method sets the "label" property to the value of `label` and sets the text of the label of the expander. Any previously set label will be cleared. If `label` is `None` the expander will have no label.

### gtk.Expander.get_label

        def get_label()

Returns : | the text of the label widget.

### Note

This method is available in PyGTK 2.4 and above.

The `get_label`() method returns the value of the "label" property that contains the text of the expander label, as set by the `set_label()` method. If the label text has not been set the return value will be `None`.

### gtk.Expander.set_use_underline

        def set_use_underline(use_underline)

`use_underline` : | `True` if underlines in the text indicate mnemonics

### Note

This method is available in PyGTK 2.4 and above.

The `set_use_underline`() method sets the "use_underline" property to the value of `use_underline`. If `use_underline` is `True`, an underline in the text of the expander label indicates the next character should be used for the mnemonic accelerator key.

### gtk.Expander.get_use_underline

        def get_use_underline()

Returns : | `True` if an embedded underline in the expander label indicates the mnemonic accelerator keys.

### Note

This method is available in PyGTK 2.4 and above.

The `get_use_underline`() method returns the value of the "use-underline" property. If "use-underline" is `True` an embedded underline in the expander label indicates a mnemonic. See the `set_use_underline()` method.

### gtk.Expander.set_use_markup

        def set_use_markup(use_markup)

`use_markup` : | if `True`, the label's text should be parsed for markup

### Note

This method is available in PyGTK 2.4 and above.

The `set_use_markup`() method sets the "use-markup" property to the value of `use_markup`. If `use_markup` is `True` the text of the label contains markup in the Pango text markup language. See the `gtk.Label.set_markup()` method for more information.

### gtk.Expander.get_use_markup

        def get_use_markup()

Returns : | `True` if the label's text will be parsed for markup

### Note

This method is available in PyGTK 2.4 and above.

The `get_use_markup`() method returns the value of the "use-markup" property. If "use-markup" is `True`, the label's text is interpreted as marked up with the Pango text markup language. See the `set_use_markup()` method.

### gtk.Expander.set_label_widget

        def set_label_widget(label_widget)

`label_widget` : | the new label widget or `None`

### Note

This method is available in PyGTK 2.4 and above.

The `set_label_widget`() method sets the expander to use the widget specified by `label_widget` as the label instead of a `gtk.Label`. This widget appears embedded alongside the expander arrow. If `label_widget` is `None`, the expander will have no label.

### gtk.Expander.get_label_widget

        def get_label_widget()

Returns : | the label widget, or `None` if there is none.

### Note

This method is available in PyGTK 2.4 and above.

The `get_label_widget`() method retrieves the expander's label widget. See the `set_label_widget()` method.

## Functions

### gtk.expander_new_with_mnemonic

        def gtk.expander_new_with_mnemonic(label=None)

`label` : | the text of the label with an underscore in front of the mnemonic character or `None`
Returns : | a new `gtk.Expander` widget.

### Note

This function is available in PyGTK 2.4 and above.

The `gtk.expander_new_with_mnemonic`() function creates a new `gtk.Expander` using `label` as the text of the label. If characters in `label` are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use '__' (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. Pressing Alt with that key activates the button. If `label` is `None` the expander will have no label.

## Signals

### The "activate" gtk.Expander Signal

        def callback(expander, user_param1, ...)

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

### Note

This signal is available in PyGTK 2.4 and above.

The "activate" signal is emitted when the expander is activated by the user clicking on the expander toggle. Using the "notify:expanded" signal may be more appropriate in some cases as noted in the Special Usage description.

Prev | Up | Next
gtk.EventBox | Home | gtk.FileChooser