## Convenience Functions

Convenience Functions — Special purpose widgets and utilities

## Synopsis

    #include <libxfce4panel/libxfce4panel.h>

    GtkWidget *         xfce_panel_create_button            (void);
    GtkWidget *         xfce_panel_create_toggle_button     (void);
    const gchar *       xfce_panel_get_channel_name         (void);
    GdkPixbuf *         xfce_panel_pixbuf_from_source       (const gchar *source,
                                                             GtkIconTheme *icon_theme,
                                                             gint size);
    GdkPixbuf *         xfce_panel_pixbuf_from_source_at_size
                                                            (const gchar *source,
                                                             GtkIconTheme *icon_theme,
                                                             gint dest_width,
                                                             gint dest_height);
    #define             xfce_allow_panel_customization
    #define             xfce_create_panel_button
    #define             xfce_create_panel_toggle_button

## Description

This section describes a number of functions that were created to help developers of Xfce Panel plugins.

## Details

### xfce_panel_create_button ()

    GtkWidget *         xfce_panel_create_button            (void);

Create regular GtkButton with a few properties set to be useful in the Xfce panel: Flat (`GTK_RELIEF_NONE`), no focus on click and minimal padding.

Returns : | newly created GtkButton.

### xfce_panel_create_toggle_button ()

    GtkWidget *         xfce_panel_create_toggle_button     (void);

Create regular GtkToggleButton with a few properties set to be useful in Xfce panel: Flat (`GTK_RELIEF_NONE`), no focus on click and minimal padding.

Returns : | newly created GtkToggleButton.

### xfce_panel_get_channel_name ()

    const gchar *       xfce_panel_get_channel_name         (void);

Function for the name of the Xfconf channel used by the panel. By default this returns "xfce4-panel", but you can override this value with the environment variable XFCE_PANEL_CHANNEL_NAME.

Returns : | name of the Xfconf channel See also: XFCE_PANEL_CHANNEL_NAME, xfce_panel_plugin_xfconf_channel_new and xfce_panel_plugin_get_property_base

Since 4.8

### xfce_panel_pixbuf_from_source ()

    GdkPixbuf *         xfce_panel_pixbuf_from_source       (const gchar *source,
                                                             GtkIconTheme *icon_theme,
                                                             gint size);

See xfce_panel_pixbuf_from_source_at_size

`source` : | string that contains the location of an icon
`icon_theme` : | icon theme or `NULL` to use the default icon theme
`size` : | size the icon that should be loaded
Returns : | a GdkPixbuf or `NULL` if nothing was found. The value should be released with g_object_unref when no longer used. See also: XfcePanelImage

Since 4.8

### xfce_panel_pixbuf_from_source_at_size ()

    GdkPixbuf *         xfce_panel_pixbuf_from_source_at_size
                                                            (const gchar *source,
                                                             GtkIconTheme *icon_theme,
                                                             gint dest_width,
                                                             gint dest_height);

Try to load a pixbuf from a source string. The source could be an abolute path, an icon name or a filename that points to a file in the pixmaps directory.

This function is particularly usefull for loading names from the Icon key of desktop files.

The pixbuf is never bigger than `dest_width` and `dest_height`. If it is when loaded from the disk, the pixbuf is scaled preserving the aspect ratio.

`source` : | string that contains the location of an icon
`icon_theme` : | icon theme or `NULL` to use the default icon theme
`dest_width` : | the maximum returned width of the GdkPixbuf
`dest_height` : | the maximum returned height of the GdkPixbuf
Returns : | a GdkPixbuf or `NULL` if nothing was found. The value should be released with g_object_unref when no longer used. See also: XfcePanelImage

Since 4.10

### xfce_allow_panel_customization

    #define xfce_allow_panel_customization  (FALSE)

### Warning

`xfce_allow_panel_customization` has been deprecated since version 4.8 and should not be used in newly-written code. Look at `xfce_panel_plugin_get_locked()`.

Always returns `FALSE`. Plugins can be locked on a plugin basis level in the future, so this function is useless.

### xfce_create_panel_button

    #define xfce_create_panel_button xfce_panel_create_button

### Warning

`xfce_create_panel_button` has been deprecated since version 4.8 and should not be used in newly-written code. Use `xfce_panel_create_button()` instead.

See `xfce_panel_create_button()` for more information.

### xfce_create_panel_toggle_button

    #define xfce_create_panel_toggle_button xfce_panel_create_toggle_button

### Warning

`xfce_create_panel_toggle_button` has been deprecated since version 4.8 and should not be used in newly-written code. Use `xfce_panel_create_toggle_button()` instead.

See `xfce_panel_create_toggle_button()` for more information.