## GtkAppChooserButton

GtkAppChooserButton — A button to launch an application chooser dialog

## Synopsis

    #include <gtk/gtk.h>

    struct              GtkAppChooserButton;
    GtkWidget *         gtk_app_chooser_button_new          (const gchar *content_type);
    void                gtk_app_chooser_button_append_custom_item
                                                            (GtkAppChooserButton *self,
                                                             const gchar *name,
                                                             const gchar *label,
                                                             GIcon *icon);
    void                gtk_app_chooser_button_append_separator
                                                            (GtkAppChooserButton *self);
    void                gtk_app_chooser_button_set_active_custom_item
                                                            (GtkAppChooserButton *self,
                                                             const gchar *name);
    gboolean            gtk_app_chooser_button_get_show_default_item
                                                            (GtkAppChooserButton *self);
    void                gtk_app_chooser_button_set_show_default_item
                                                            (GtkAppChooserButton *self,
                                                             gboolean setting);
    gboolean            gtk_app_chooser_button_get_show_dialog_item
                                                            (GtkAppChooserButton *self);
    void                gtk_app_chooser_button_set_show_dialog_item
                                                            (GtkAppChooserButton *self,
                                                             gboolean setting);
    const gchar *       gtk_app_chooser_button_get_heading  (GtkAppChooserButton *self);
    void                gtk_app_chooser_button_set_heading  (GtkAppChooserButton *self,
                                                             const gchar *heading);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkWidget
                   +----GtkContainer
                         +----GtkBin
                               +----GtkComboBox
                                     +----GtkAppChooserButton

## Implemented Interfaces

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

## Properties

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

## Signals

      "custom-item-activated"                          : Has Details

## 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.

## Details

### struct GtkAppChooserButton

    struct GtkAppChooserButton;

### 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.

`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()`.

`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.

`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.

`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.

`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.

`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.

`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.

`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.

`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.

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

## Property Details

### The `"heading"` property

      "heading"                  gchar*                : Read / Write

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

Default value: NULL

### The `"show-default-item"` property

      "show-default-item"        gboolean              : Read / Write / Construct

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

Default value: FALSE

Since 3.2

### The `"show-dialog-item"` property

      "show-dialog-item"         gboolean              : Read / Write / Construct

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

Default value: FALSE

## Signal Details

### The `"custom-item-activated"` signal

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

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

`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.