XAppIconChooserDialog: XApp Reference Manual

## XAppIconChooserDialog XAppIconChooserDialog — A dialog for selecting an icon |

## Functions

XAppIconChooserDialog * | xapp_icon_chooser_dialog_new ()
gint | xapp_icon_chooser_dialog_run ()
gint | xapp_icon_chooser_dialog_run_with_icon ()
gint | xapp_icon_chooser_dialog_run_with_category ()
gchar * | xapp_icon_chooser_dialog_get_icon_string ()
void | xapp_icon_chooser_dialog_add_button ()
gchar * | xapp_icon_chooser_dialog_get_default_icon ()
void | xapp_icon_chooser_dialog_set_default_icon ()
void | xapp_icon_chooser_dialog_add_custom_category ()

## Properties

gboolean | allow-paths | Read / Write
char * | default-icon | Read / Write
XAppIconSize | icon-size | Read / Write

## Signals

void | close | Action
void | select | Action

## Types and Values

#define | XAPP_TYPE_ICON_CHOOSER_DIALOG
enum | XAppIconSize
| XAppIconChooserDialog

## Object Hierarchy

        GEnum
        ╰── XAppIconSize
        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkBin
                        ╰── GtkWindow
                            ╰── XAppGtkWindow
                                ╰── XAppIconChooserDialog

## Implemented Interfaces

XAppIconChooserDialog implements AtkImplementorIface and GtkBuildable.

## Description

The XAppIconChooserDialog creates a dialog so that the user can select an icon. It provides the ability to browse by category, search by icon name, or select from a specific file.

## Functions

### xapp_icon_chooser_dialog_new ()

    XAppIconChooserDialog *
    xapp_icon_chooser_dialog_new (void);

Creates a new XAppIconChooserDialog.

#### Returns

a newly created XAppIconChooserDialog

### xapp_icon_chooser_dialog_run ()

    gint
    xapp_icon_chooser_dialog_run (XAppIconChooserDialog *dialog);

Shows the dialog and enters a separate main loop until an icon is chosen or the action is canceled.

xapp_icon_chooser_dialog_run (), `xapp_icon_chooser_dialog_run_with_icon()`, and `xapp_icon_chooser_dialog_run_with_category()` may all be called multiple times. This is useful for applications which use this dialog multiple times, as it may improve performance for subsequent calls.

#### Parameters

dialog | a XAppIconChooserDialog |

#### Returns

GTK_RESPONSE_OK if the user selected an icon, or GTK_RESPONSE_CANCEL otherwise

### xapp_icon_chooser_dialog_run_with_icon ()

    gint
    xapp_icon_chooser_dialog_run_with_icon
                                   (XAppIconChooserDialog *dialog,
                                    gchar *icon);

Like xapp_icon_chooser_dialog_run but selects the icon specified by `icon` . This can be either an icon name or a path. Passing an icon string or path that doesn't exist is accepted, but it may show multiple results, or none at all. This behavior is useful if, for example, you wish to have the user select an image file from a particular directory.

If the property allow_paths is FALSE, setting a path will yield no results when the dialog is opened.

xapp_icon_chooser_dialog_run (), `xapp_icon_chooser_dialog_run_with_icon()`, and `xapp_icon_chooser_dialog_run_with_category()` may all be called multiple times. This is useful for applications which use this dialog multiple times, as it may improve performance for subsequent calls.

#### Parameters

dialog | a XAppIconChooserDialog |
icon | a string representing the icon that should be selected |

#### Returns

GTK_RESPONSE_OK if the user selected an icon, or GTK_RESPONSE_CANCEL otherwise

### xapp_icon_chooser_dialog_run_with_category ()

    gint
    xapp_icon_chooser_dialog_run_with_category
                                   (XAppIconChooserDialog *dialog,
                                    gchar *category);

Like xapp_icon_chooser_dialog_run but selects a particular category specified by `category` . This is used when there is a particular category of icon that is more appropriate than the others. If the category does not exist, the first category in the list will be selected. To get a list of possible categories, use `gtk_icon_theme_list_contexts()`.

xapp_icon_chooser_dialog_run (), `xapp_icon_chooser_dialog_run_with_icon()`, and `xapp_icon_chooser_dialog_run_with_category()` may all be called multiple times. This is useful for applications which use this dialog multiple times, as it may improve performance for subsequent calls.

#### Parameters

dialog | a XAppIconChooserDialog |

#### Returns

GTK_RESPONSE_OK if the user selected an icon, or GTK_RESPONSE_CANCEL otherwise

### xapp_icon_chooser_dialog_get_icon_string ()

    gchar *
    xapp_icon_chooser_dialog_get_icon_string
                                   (XAppIconChooserDialog *dialog);

Gets the currently selected icon from the dialog. If allow-paths is TRUE, this function may return either an icon name or a path depending on what the user selects. Otherwise it will only return an icon name.

#### Parameters

dialog | a XAppIconChooserDialog |

#### Returns

the string representation of the currently selected icon or NULL if no icon is selected.

[transfer full]

### xapp_icon_chooser_dialog_add_button ()

    void
    xapp_icon_chooser_dialog_add_button (XAppIconChooserDialog *dialog,
                                         GtkWidget *button,
                                         GtkPackType packing,
                                         GtkResponseType response_id);

Allows a button to be added to the GtkActionBar of the dialog with a custom response id.

#### Parameters

dialog | an XAppIconChooserDialog |
button | a GtkButton to add |
packing | the GtkPackType to specify start or end packing to the action bar |
response_id | the dialog response id to return when this button is clicked. |

### xapp_icon_chooser_dialog_get_default_icon ()

    gchar *
    xapp_icon_chooser_dialog_get_default_icon
                                   (XAppIconChooserDialog *dialog);

Returns the default icon (if set).

#### Returns

the default icon, or NULL if none is set.

[transfer full]

### xapp_icon_chooser_dialog_set_default_icon ()

    void
    xapp_icon_chooser_dialog_set_default_icon
                                   (XAppIconChooserDialog *dialog,
                                    const gchar *icon);

Sets the default icon. If `icon` is not NULL, a button will be shown that will reset the dialog to it's default value.

#### Parameters

icon | the default icon, or NULL to unset |

### xapp_icon_chooser_dialog_add_custom_category ()

    void
    xapp_icon_chooser_dialog_add_custom_category
                                   (XAppIconChooserDialog *dialog,
                                    const gchar *name,
                                    GList *icons);

Adds a custom category to the dialog.

#### Parameters

dialog | a XAppIconChooserDialog |
name | the name of the category as it will be displayed in the category list |
icons | a list of icon names to add to the new category. | [transfer full][element-type utf8]

## Types and Values

### XAPP_TYPE_ICON_CHOOSER_DIALOG

    #define XAPP_TYPE_ICON_CHOOSER_DIALOG   (xapp_icon_chooser_dialog_get_type ())

### enum XAppIconSize

#### Members

XAPP_ICON_SIZE_16 |  |
XAPP_ICON_SIZE_22 |  |
XAPP_ICON_SIZE_24 |  |
XAPP_ICON_SIZE_32 |  |
XAPP_ICON_SIZE_48 |  |
XAPP_ICON_SIZE_96 |  |

### XAppIconChooserDialog

    typedef struct _XAppIconChooserDialog XAppIconChooserDialog;

## Property Details

### The `“allow-paths”` property

      “allow-paths”              gboolean

Whether to allow paths to be searched and selected or only icon names.

Owner: XAppIconChooserDialog

Flags: Read / Write

Default value: TRUE

### The `“default-icon”` property

      “default-icon”             char *

The icon to use by default.

Owner: XAppIconChooserDialog

Flags: Read / Write

Default value: NULL

### The `“icon-size”` property

      “icon-size”                XAppIconSize

The preferred size to use when looking up icons. This only works with icon names. Additionally, there is no guarantee that a selected icon name will exist in a particular size.

Owner: XAppIconChooserDialog

Flags: Read / Write

Default value: XAPP_ICON_SIZE_32

## Signal Details

### The `“close”` signal

    void
    user_function (XAppIconChooserDialog *xappiconchooserdialog,
                   gpointer               user_data)

Flags: Action

### The `“select”` signal

    void
    user_function (XAppIconChooserDialog *xappiconchooserdialog,
                   gpointer               user_data)

Flags: Action