GtkAppChooserButton: GTK+ 3 Reference Manual

## GtkAppChooserButton GtkAppChooserButton — A button to launch an application chooser dialog |

## Functions

GtkWidget * | gtk_app_chooser_button_new ()
void | gtk_app_chooser_button_append_custom_item ()
void | gtk_app_chooser_button_append_separator ()
void | gtk_app_chooser_button_set_active_custom_item ()
gboolean | gtk_app_chooser_button_get_show_default_item ()
void | gtk_app_chooser_button_set_show_default_item ()
gboolean | gtk_app_chooser_button_get_show_dialog_item ()
void | gtk_app_chooser_button_set_show_dialog_item ()
const gchar * | gtk_app_chooser_button_get_heading ()
void | gtk_app_chooser_button_set_heading ()

## Properties

gchar * | heading | Read / Write
gboolean | show-default-item | Read / Write / Construct
gboolean | show-dialog-item | Read / Write / Construct

## Signals

void | custom-item-activated | Has Details

## Types and Values

struct | GtkAppChooserButton
struct | GtkAppChooserButtonClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkBin
                        ╰── GtkComboBox
                            ╰── GtkAppChooserButton

## Implemented Interfaces

GtkAppChooserButton implements AtkImplementorIface, GtkBuildable, GtkCellLayout, GtkCellEditable and GtkAppChooser.

## Includes

    #include <gtk/gtk.h>

## Description

The GtkAppChooserButton is a widget that lets the user select an application. It implements the GtkAppChooser interface.

Initially, a GtkAppChooserButton selects the first application in its list, which will either be the most-recently used application or, if “show-default-item” is `TRUE`, the default application.

The list of applications shown in a GtkAppChooserButton includes the recommended applications for the given content type. When “show-default-item” is set, the default application is also included. To let the user chooser other applications, you can set the “show-dialog-item” property, which allows to open a full GtkAppChooserDialog.

It is possible to add custom items to the list, using `gtk_app_chooser_button_append_custom_item()`. These items cause the “custom-item-activated” signal to be emitted when they are selected.

To track changes in the selected application, use the “changed” signal.

## Functions

### gtk_app_chooser_button_new ()

    GtkWidget *
    gtk_app_chooser_button_new (const gchar *content_type);

Creates a new GtkAppChooserButton for applications that can handle content of the given type.

#### Parameters

content_type | the content type to show applications for |

#### Returns

a newly created GtkAppChooserButton

Since 3.0

### gtk_app_chooser_button_append_custom_item ()

    void
    gtk_app_chooser_button_append_custom_item
                                   (GtkAppChooserButton *self,
                                    const gchar *name,
                                    const gchar *label,
                                    GIcon *icon);

Appends a custom item to the list of applications that is shown in the popup; the item name must be unique per-widget. Clients can use the provided name as a detail for the “custom-item-activated” signal, to add a callback for the activation of a particular custom item in the list. See also `gtk_app_chooser_button_append_separator()`.

#### Parameters

self | a GtkAppChooserButton |
name | the name of the custom item |
label | the label for the custom item |
icon | the icon for the custom item |

Since 3.0

### gtk_app_chooser_button_append_separator ()

    void
    gtk_app_chooser_button_append_separator
                                   (GtkAppChooserButton *self);

Appends a separator to the list of applications that is shown in the popup.

#### Parameters

self | a GtkAppChooserButton |

Since 3.0

### gtk_app_chooser_button_set_active_custom_item ()

    void
    gtk_app_chooser_button_set_active_custom_item
                                   (GtkAppChooserButton *self,
                                    const gchar *name);

Selects a custom item previously added with `gtk_app_chooser_button_append_custom_item()`.

Use `gtk_app_chooser_refresh()` to bring the selection to its initial state.

#### Parameters

self | a GtkAppChooserButton |
name | the name of the custom item |

Since 3.0

### gtk_app_chooser_button_get_show_default_item ()

    gboolean
    gtk_app_chooser_button_get_show_default_item
                                   (GtkAppChooserButton *self);

Returns the current value of the “show-default-item” property.

#### Parameters

self | a GtkAppChooserButton |

#### Returns

the value of “show-default-item”

Since 3.2

### gtk_app_chooser_button_set_show_default_item ()

    void
    gtk_app_chooser_button_set_show_default_item
                                   (GtkAppChooserButton *self,
                                    gboolean setting);

Sets whether the dropdown menu of this button should show the default application for the given content type at top.

#### Parameters

self | a GtkAppChooserButton |
setting | the new value for “show-default-item” |

Since 3.2

### gtk_app_chooser_button_get_show_dialog_item ()

    gboolean
    gtk_app_chooser_button_get_show_dialog_item
                                   (GtkAppChooserButton *self);

Returns the current value of the “show-dialog-item” property.

#### Parameters

self | a GtkAppChooserButton |

#### Returns

the value of “show-dialog-item”

Since 3.0

### gtk_app_chooser_button_set_show_dialog_item ()

    void
    gtk_app_chooser_button_set_show_dialog_item
                                   (GtkAppChooserButton *self,
                                    gboolean setting);

Sets whether the dropdown menu of this button should show an entry to trigger a GtkAppChooserDialog.

#### Parameters

self | a GtkAppChooserButton |
setting | the new value for “show-dialog-item” |

Since 3.0

### gtk_app_chooser_button_get_heading ()

    const gchar *
    gtk_app_chooser_button_get_heading (GtkAppChooserButton *self);

Returns the text to display at the top of the dialog.

#### Parameters

self | a GtkAppChooserButton |

#### Returns

the text to display at the top of the dialog, or `NULL`, in which case a default text is displayed

### gtk_app_chooser_button_set_heading ()

    void
    gtk_app_chooser_button_set_heading (GtkAppChooserButton *self,
                                        const gchar *heading);

Sets the text to display at the top of the dialog. If the heading is not set, the dialog displays a default text.

#### Parameters

self | a GtkAppChooserButton |
heading | a string containing Pango markup |

## Types and Values

### struct GtkAppChooserButton

    struct GtkAppChooserButton;

### struct GtkAppChooserButtonClass

    struct GtkAppChooserButtonClass {
      GtkComboBoxClass parent_class;

      void (* custom_item_activated) (GtkAppChooserButton *self,
                                      const gchar *item_name);
    };

#### Members

GtkComboBoxClass `parent_class`; | The parent class. |
`custom_item_activated` () | Signal emitted when a custom item, previously added with `gtk_app_chooser_button_append_custom_item()`, is activated from the dropdown menu. |

## Property Details

### The `“heading”` property

      “heading”                  gchar *

The text to show at the top of the dialog that can be opened from the button. The string may contain Pango markup.

Flags: Read / Write

Default value: NULL

### The `“show-default-item”` property

      “show-default-item”        gboolean

The “show-default-item” property determines whether the dropdown menu should show the default application on top for the provided content type.

Flags: Read / Write / Construct

Default value: FALSE

Since 3.2

### The `“show-dialog-item”` property

      “show-dialog-item”         gboolean

The “show-dialog-item” property determines whether the dropdown menu should show an item that triggers a GtkAppChooserDialog when clicked.

Flags: Read / Write / Construct

Default value: FALSE

## Signal Details

### The `“custom-item-activated”` signal

    void
    user_function (GtkAppChooserButton *self,
                   gchar               *item_name,
                   gpointer             user_data)

Emitted when a custom item, previously added with `gtk_app_chooser_button_append_custom_item()`, is activated from the dropdown menu.

#### Parameters

self | the object which received the signal |
item_name | the name of the activated item |
user_data | user data set when the signal handler was connected. |

Flags: Has Details