Next: , Previous: GtkTable, Up: Top

102 GtkExpander

A container which can hide its child

102.1 Overview

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-tree-view>.

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.

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 an ‘expanded’ property which 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");
     g_signal_connect (expander, "notify::expanded",
                       G_CALLBACK (expander_callback), NULL);
     
     ...
     
     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 */
         }
     }

102.2 Usage

— Class: <gtk-expander>

Derives from <gtk-bin>.

This class defines the following slots:

expanded
Whether the expander has been opened to reveal the child widget
label
Text of the expander's label
use-underline
If set, an underline in the text indicates the next character should be used for the mnemonic accelerator key
use-markup
The text of the label includes XML markup. See pango_parse_markup()
spacing
Space to put between the label and the child
label-widget
A widget to display in place of the usual expander label
— Signal on <gtk-expander>: activate
— Function: gtk-expander-new (label mchars) ⇒  (ret <gtk-widget>)

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

label
the text of the label
ret
a new <gtk-expander> widget.

Since 2.4

— Function: gtk-expander-new-with-mnemonic (label mchars) ⇒  (ret <gtk-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.

label
the text of the label with an underscore in front of the mnemonic character
ret
a new <gtk-expander> widget.

Since 2.4

— Function: gtk-expander-set-expanded (self <gtk-expander>) (expanded bool)
— Method: set-expanded

Sets the state of the expander. Set to ‘#t’, if you want the child widget to be revealed, and ‘#f’ if you want the child widget to be hidden.

expander
a <gtk-expander>
expanded
whether the child widget is revealed

Since 2.4

— Function: gtk-expander-get-expanded (self <gtk-expander>) ⇒  (ret bool)
— Method: get-expanded

Queries a <gtk-expander> and returns its current state. Returns ‘#t’ if the child widget is revealed.

See gtk-expander-set-expanded.

expander
a <gtk-expander>
ret
the current state of the expander.

Since 2.4

— Function: gtk-expander-set-spacing (self <gtk-expander>) (spacing int)
— Method: set-spacing

Sets the spacing field of expander, which is the number of pixels to place between expander and the child.

expander
a <gtk-expander>
spacing
distance between the expander and child in pixels.

Since 2.4

— Function: gtk-expander-get-spacing (self <gtk-expander>) ⇒  (ret int)
— Method: get-spacing

Gets the value set by gtk-expander-set-spacing.

expander
a <gtk-expander>
ret
spacing between the expander and child.

Since 2.4

— Function: gtk-expander-set-label (self <gtk-expander>) (label mchars)
— Method: set-label

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

This will also clear any previously set labels.

expander
a <gtk-expander>
label
a string

Since 2.4

— Function: gtk-expander-get-label (self <gtk-expander>) ⇒  (ret mchars)
— Method: get-label

Fetches the text from the label of the expander, as set by gtk-expander-set-label. If the label text has not been set the return value will be ‘#f’. This will be the case if you create an empty button with gtk-button-new to use as a container.

expander
a <gtk-expander>
ret
The text of the label widget. This string is owned by the widget and must not be modified or freed.

Since 2.4

— Function: gtk-expander-set-use-underline (self <gtk-expander>) (use_underline bool)
— Method: set-use-underline

If true, an underline in the text of the expander label indicates the next character should be used for the mnemonic accelerator key.

expander
a <gtk-expander>
use-underline
‘#t’ if underlines in the text indicate mnemonics

Since 2.4

— Function: gtk-expander-get-use-underline (self <gtk-expander>) ⇒  (ret bool)
— Method: get-use-underline

Returns whether an embedded underline in the expander label indicates a mnemonic. See gtk-expander-set-use-underline.

expander
a <gtk-expander>
ret
‘#t’ if an embedded underline in the expander label indicates the mnemonic accelerator keys.

Since 2.4

— Function: gtk-expander-set-use-markup (self <gtk-expander>) (use_markup bool)
— Method: set-use-markup

Sets whether the text of the label contains markup in Pango's text markup language. See gtk-label-set-markup.

expander
a <gtk-expander>
use-markup
‘#t’ if the label's text should be parsed for markup

Since 2.4

— Function: gtk-expander-get-use-markup (self <gtk-expander>) ⇒  (ret bool)
— Method: get-use-markup

Returns whether the label's text is interpreted as marked up with the Pango text markup language. See gtk-expander-set-use-markup.

expander
a <gtk-expander>
ret
‘#t’ if the label's text will be parsed for markup

Since 2.4

— Function: gtk-expander-set-label-widget (self <gtk-expander>) (label_widget <gtk-widget>)
— Method: set-label-widget

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

expander
a <gtk-expander>
label-widget
the new label widget

Since 2.4

— Function: gtk-expander-get-label-widget (self <gtk-expander>) ⇒  (ret <gtk-widget>)
— Method: get-label-widget

Retrieves the label widget for the frame. See gtk-expander-set-label-widget.

expander
a <gtk-expander>
ret
the label widget, or ‘#f’ if there is none.

Since 2.4