Gtk.Expander¶

class — extends Widget, Accessible, Buildable, ConstraintTarget

Allows the user to reveal or conceal a child widget.

This is similar to the triangles used in a GtkTreeView.

Normally you use an expander as you would use a frame; you create the child widget and use Expander.set_child 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 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 GtkExpander but do not add a child to it. The expander widget has an Expander.expanded property which can be used to monitor its expansion state. You should watch this property with a signal connection as follows:

static void
expander_callback (GObject    *object,
                   GParamSpec *param_spec,
                   gpointer    user_data)
{
  GtkExpander *expander;

  expander = GTK_EXPANDER (object);

  if (gtk_expander_get_expanded (expander))
    {
      // Show or create widgets
    }
  else
    {
      // Hide or destroy widgets
    }
}

static void
create_expander (void)
{
  GtkWidget *expander = gtk_expander_new_with_mnemonic ("_More Options");
  g_signal_connect (expander, "notify::expanded",
                    G_CALLBACK (expander_callback), NULL);

  // ...
}

GtkExpander as GtkBuildable¶

An example of a UI definition fragment with GtkExpander:

<object class="GtkExpander">
  <property name="label-widget">
    <object class="GtkLabel" id="expander-label"/>
  </property>
  <property name="child">
    <object class="GtkEntry" id="expander-content"/>
  </property>
</object>

CSS nodes¶

expander-widget
╰── box
    ├── title
    │   ├── expander
    │   ╰── <label widget>
    ╰── <child>

GtkExpander has a main node expander-widget, and subnode box containing the title and child widget. The box subnode title contains node expander, i.e. the expand/collapse arrow; then the label widget if any. The arrow of an expander that is showing its child gets the :checked pseudoclass set on it.

Accessibility¶

GtkExpander uses the AccessibleRole.button role.

Constructors¶

new¶

@classmethod
def new(cls, label: str | None = ...) -> Widget

Creates a new expander using label as the text of the label.

Parameters:

label — the text of the label

new_with_mnemonic¶

@classmethod
def new_with_mnemonic(cls, label: str | None = ...) -> Widget

Creates a new 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 and that key activates the button.

Parameters:

label — the text of the label with an underscore in front of the mnemonic character

Methods¶

get_child¶

def get_child(self) -> Widget | None

Gets the child widget of expander.

get_expanded¶

def get_expanded(self) -> bool

Queries a GtkExpander and returns its current state.

Returns True if the child widget is revealed.

get_label¶

def get_label(self) -> str | None

Fetches the text from a label widget.

This is including any embedded underlines indicating mnemonics and Pango markup, as set by Expander.set_label. If the label text has not been set the return value will be None. This will be the case if you create an empty button with Button.new to use as a container.

get_label_widget¶

def get_label_widget(self) -> Widget | None

Retrieves the label widget for the frame.

get_resize_toplevel¶

def get_resize_toplevel(self) -> bool

Returns whether the expander will resize the toplevel widget containing the expander upon resizing and collapsing.

get_use_markup¶

def get_use_markup(self) -> bool

Returns whether the label’s text is interpreted as Pango markup.

get_use_underline¶

def get_use_underline(self) -> bool

Returns whether an underline in the text indicates a mnemonic.

set_child¶

def set_child(self, child: Widget | None = ...) -> None

Sets the child widget of expander.

Parameters:

child — the child widget

set_expanded¶

def set_expanded(self, expanded: bool) -> None

Sets the state of the expander.

Set to True, if you want the child widget to be revealed, and False if you want the child widget to be hidden.

Parameters:

expanded — whether the child widget is revealed

set_label¶

def set_label(self, label: str | None = ...) -> None

Sets the text of the label of the expander to label.

This will also clear any previously set labels.

Parameters:

label — a string

set_label_widget¶

def set_label_widget(self, label_widget: Widget | None = ...) -> None

Set the label widget for the expander.

This is the widget that will appear embedded alongside the expander arrow.

Parameters:

label_widget — the new label widget

set_resize_toplevel¶

def set_resize_toplevel(self, resize_toplevel: bool) -> None

Sets whether the expander will resize the toplevel widget containing the expander upon resizing and collapsing.

Parameters:

resize_toplevel — whether to resize the toplevel

set_use_markup¶

def set_use_markup(self, use_markup: bool) -> None

Sets whether the text of the label contains Pango markup.

Parameters:

use_markup — True if the label’s text should be parsed for markup

set_use_underline¶

def set_use_underline(self, use_underline: bool) -> None

If true, an underline in the text indicates a mnemonic.

Parameters:

use_underline — True if underlines in the text indicate mnemonics

Properties¶

child¶

child: Widget  # read/write

The child widget.

expanded¶

expanded: bool  # read/write

Whether the expander has been opened to reveal the child.

label¶

label: str  # read/write

The text of the expanders label.

label_widget¶

label_widget: Widget  # read/write

A widget to display instead of the usual expander label.

resize_toplevel¶

resize_toplevel: bool  # read/write

When this property is True, the expander will resize the toplevel widget containing the expander upon expanding and collapsing.

use_markup¶

use_markup: bool  # read/write

Whether the text in the label is Pango markup.

use_underline¶

use_underline: bool  # read/write

Whether an underline in the text indicates a mnemonic.

Signals¶

activate¶

def on_activate(self) -> None: ...

Activates the GtkExpander.