Gtk Extensions: libxfce4ui Reference Manual

## Gtk Extensions Gtk Extensions — various extensions to Gtk+ |

## Stability Level

Stable, unless otherwise indicated

## Functions

GtkWidget * | xfce_gtk_menu_item_new ()
GtkWidget * | xfce_gtk_image_menu_item_new ()
GtkWidget * | xfce_gtk_image_menu_item_new_from_icon_name ()
GtkWidget * | xfce_gtk_check_menu_item_new ()
GtkWidget * | xfce_gtk_radio_menu_item_new ()
GtkWidget * | xfce_gtk_menu_item_new_from_action_entry ()
GtkWidget * | xfce_gtk_toggle_menu_item_new_from_action_entry ()
GtkWidget * | xfce_gtk_tool_button_new_from_action_entry ()
GtkWidget * | xfce_gtk_toggle_tool_button_new_from_action_entry ()
void | xfce_gtk_accel_map_add_entries ()
void | xfce_gtk_accel_group_connect_action_entries ()
void | xfce_gtk_accel_group_disconnect_action_entries ()
const XfceGtkActionEntry * | xfce_gtk_get_action_entry_by_id ()
void | xfce_gtk_translate_action_entries ()
gboolean | xfce_gtk_handle_tab_accels ()
gboolean | xfce_gtk_execute_tab_accel ()
void | xfce_gtk_menu_append_separator ()
GtkWidget * | xfce_gtk_button_new_mixed ()
GtkWidget * | xfce_gtk_frame_box_new ()
GtkWidget * | xfce_gtk_frame_box_new_with_content ()
void | xfce_gtk_window_center_on_active_screen ()
gboolean | xfce_gtk_menu_popup_until_mapped ()
gboolean | xfce_widget_reparent ()
gchar * | xfce_icon_name_from_desktop_id ()
GIcon * | xfce_gicon_from_name ()
void | xfce_gtk_menu_item_set_accel_label ()
gboolean | xfce_has_gtk_frame_extents ()
void | xfce_gtk_label_set_a11y_relation ()

## Types and Values

enum | XfceGtkMenuItem
| XfceGtkActionEntry

## Includes

    #include <libxfce4ui/libxfce4ui.h>

## Description

Common used functions for GtkWidget's that are not provided by the Gtk+ library

## Functions

### xfce_gtk_menu_item_new ()

    GtkWidget *
    xfce_gtk_menu_item_new (const gchar *label_text,
                            const gchar *tooltip_text,
                            const gchar *accel_path,
                            GCallback callback,
                            GObject *callback_param,
                            GtkMenuShell *menu_to_append_item);

Convenience method to create a GtkMenuItem and preconfigure it with the passed parameters.

#### Parameters

label_text | Label to use for the GtkMenuItem |
tooltip_text | Tooltip to add on the passed item, or NULL. | [nullable]
accel_path | Unique path, used to identify the accelerator, or NULL. | [nullable]
callback | GCallback which will be triggered on activation, or NULL. | [scope notified][nullable]
callback_param | optional callback parameter, or NULL. | [nullable]
menu_to_append_item | GtkMenuShell on which the item should be appended, or NULL. | [nullable]

#### Returns

A new GtkMenuItem.

[transfer floating]

Since: 4.16

### xfce_gtk_image_menu_item_new ()

    GtkWidget *
    xfce_gtk_image_menu_item_new (const gchar *label_text,
                                  const gchar *tooltip_text,
                                  const gchar *accel_path,
                                  GCallback callback,
                                  GObject *callback_param,
                                  GtkWidget *image,
                                  GtkMenuShell *menu_to_append_item);

Convenience method to create a deprecated GtkImageMenuItem and preconfigure it with the passed parameters. In order to prevent G_GNUC_BEGIN_IGNORE_DEPRECATIONS in all xfce projects, this method can be used

#### Parameters

label_text | Label to use for the GtkImageMenuItem |
tooltip_text | Tooltip to add on the passed item, or NULL. | [nullable]
accel_path | Unique path, used to identify the accelerator, or NULL. | [nullable]
callback | GCallback which will be triggered on activation, or NULL. | [scope notified][nullable]
callback_param | optional callback parameter, or NULL. | [nullable]
image | a widget to set as the image for the menu item, or NULL. | [nullable]
menu_to_append_item | GtkMenuShell on which the item should be appended, or NULL. | [nullable]

#### Returns

A new GtkImageMenuItem.

[transfer floating]

Since: 4.16

### xfce_gtk_image_menu_item_new_from_icon_name ()

    GtkWidget *
    xfce_gtk_image_menu_item_new_from_icon_name
                                   (const gchar *label_text,
                                    const gchar *tooltip_text,
                                    const gchar *accel_path,
                                    GCallback callback,
                                    GObject *callback_param,
                                    const gchar *icon_name,
                                    GtkMenuShell *menu_to_append_item);

Convenience method to create a GtkImageMenuItem and preconfigure it with the passed parameters.

#### Parameters

label_text | Label to use for the GtkImageMenuItem |
tooltip_text | Tooltip to add on the passed item, or NULL. | [nullable]
accel_path | Unique path, used to identify the accelerator, or NULL. | [nullable]
callback | GCallback which will be triggered on activation, or NULL. | [scope notified][nullable]
callback_param | optional callback parameter, or NULL. | [nullable]
icon_name | name of the icon to use for the GtkImageMenuItem, or NULL. | [nullable]
menu_to_append_item | GtkMenuShell on which the item should be appended, or NULL. | [nullable]

#### Returns

A new GtkImageMenuItem.

[transfer floating]

Since: 4.16

### xfce_gtk_check_menu_item_new ()

    GtkWidget *
    xfce_gtk_check_menu_item_new (const gchar *label_text,
                                  const gchar *tooltip_text,
                                  const gchar *accel_path,
                                  GCallback callback,
                                  GObject *callback_param,
                                  gboolean active,
                                  GtkMenuShell *menu_to_append_item);

Convenience method to create a GtkCheckMenuItem and preconfigure it with the passed parameters.

#### Parameters

label_text | Label to use for the GtkCheckMenuItem |
tooltip_text | Tooltip to add on the passed item, or NULL. | [nullable]
accel_path | Unique path, used to identify the accelerator, or NULL. | [nullable]
callback | GCallback which will be triggered on activation, or NULL. | [scope notified][nullable]
callback_param | optional callback parameter, or NULL. | [nullable]
active | boolean value indicating whether the check box is active. |
menu_to_append_item | GtkMenuShell on which the item should be appended, or NULL. | [nullable]

#### Returns

A new GtkCheckMenuItem.

[transfer floating]

Since: 4.16

### xfce_gtk_radio_menu_item_new ()

    GtkWidget *
    xfce_gtk_radio_menu_item_new (const gchar *label_text,
                                  const gchar *tooltip_text,
                                  const gchar *accel_path,
                                  GCallback callback,
                                  GObject *callback_param,
                                  gboolean active,
                                  GtkMenuShell *menu_to_append_item);

Convenience method to create a GtkCheckMenuItem and preconfigure it with the passed parameters. In order to simplify usage, a GtkCheckMenuItem is created and drawn as radio-item

#### Parameters

label_text | Label to use for the GtkCheckMenuItem |
tooltip_text | Tooltip to add on the passed item, or NULL. | [nullable]
accel_path | Unique path, used to identify the accelerator, or NULL. | [nullable]
callback | GCallback which will be triggered on activation, or NULL. | [scope notified][nullable]
callback_param | optional callback parameter, or NULL. | [nullable]
active | boolean value indicating whether the check box is active. |
menu_to_append_item | GtkMenuShell on which the item should be appended, or NULL. | [nullable]

#### Returns

A new GtkCheckMenuItem.

[transfer floating]

Since: 4.16

### xfce_gtk_menu_item_new_from_action_entry ()

    GtkWidget *
    xfce_gtk_menu_item_new_from_action_entry
                                   (const XfceGtkActionEntry *action_entry,
                                    GObject *callback_param,
                                    GtkMenuShell *menu_to_append_item);

Method to create a menu item from the passed action entry

#### Parameters

action_entry | Label to use for the GtkCheckMenuItem |
callback_param | optional callback parameter, or NULL. | [nullable]
menu_to_append_item | GtkMenuShell on which the item should be appended, or NULL. | [nullable]

#### Returns

A new GtkMenuItem or NULL.

[transfer floating][nullable]

Since: 4.16

### xfce_gtk_toggle_menu_item_new_from_action_entry ()

    GtkWidget *
    xfce_gtk_toggle_menu_item_new_from_action_entry
                                   (const XfceGtkActionEntry *action_entry,
                                    GObject *callback_param,
                                    gboolean active,
                                    GtkMenuShell *menu_to_append_item);

Method to create a toggle menu item from the passed action entry

#### Parameters

action_entry | Label to use for the GtkCheckMenuItem |
callback_param | optional callback parameter, or NULL. | [nullable]
active | boolean value indicating whether the check box is active. |
menu_to_append_item | GtkMenuShell on which the item should be appended, or NULL. | [nullable]

#### Returns

A new GtkMenuItem or NULL.

[transfer floating][nullable]

Since: 4.16

### xfce_gtk_tool_button_new_from_action_entry ()

    GtkWidget *
    xfce_gtk_tool_button_new_from_action_entry
                                   (const XfceGtkActionEntry *action_entry,
                                    GObject *callback_param,
                                    GtkToolbar *toolbar_to_append_item);

Method to create a toolbar button from the passed action entry.

#### Parameters

action_entry | Label to use for the GtkToolButton |
callback_param | optional callback parameter, or `NULL`. | [nullable]
toolbar_to_append_item | GtkToolbar on which the item should be appended |

#### Returns

A new GtkToolButton.

[transfer floating]

Since: 4.16

### xfce_gtk_toggle_tool_button_new_from_action_entry ()

    GtkWidget *
    xfce_gtk_toggle_tool_button_new_from_action_entry
                                   (const XfceGtkActionEntry *action_entry,
                                    GObject *callback_param,
                                    gboolean active,
                                    GtkToolbar *toolbar_to_append_item);

Method to create a toolbar toggle-button from the passed action entry.

#### Parameters

action_entry | Label to use for the GtkToggleToolButton |
callback_param | optional callback parameter, or `NULL`. | [nullable]
active | boolean value indicating whether the toggle is initially active. |
toolbar_to_append_item | GtkToolbar on which the item should be appended |

#### Returns

A new GtkToggleToolButton.

[transfer floating]

Since: 4.17.6

### xfce_gtk_accel_map_add_entries ()

    void
    xfce_gtk_accel_map_add_entries (const XfceGtkActionEntry *action_entries,
                                    guint n_action_entries);

Adds the default key of each ActionEntry to the accel_map, if no key was defined for the related accel_path so far.

#### Parameters

action_entries | array of action_entries to be added |
n_action_entries | size of the action_entries array |

Since: 4.16

### xfce_gtk_accel_group_connect_action_entries ()

    void
    xfce_gtk_accel_group_connect_action_entries
                                   (GtkAccelGroup *accel_group,
                                    const XfceGtkActionEntry *action_entries,
                                    guint n_action_entries,
                                    gpointer callback_data);

This method will connect each accel_path from the XfceGtkActionEntry in action_entries to its related callback. If the accelerator is pressed, the related callback will be called.

#### Parameters

accel_group | the GtkAccelGroup to connect to |
action_entries | array of action_entries to be added |
n_action_entries | size of the action_entries array |
callback_data | data which should be passed to the callback of each XfceGtkActionEntry |

Since: 4.16

### xfce_gtk_accel_group_disconnect_action_entries ()

    void
    xfce_gtk_accel_group_disconnect_action_entries
                                   (GtkAccelGroup *accel_group,
                                    const XfceGtkActionEntry *action_entries,
                                    guint n_action_entries);

This method will disconnect each accel_path from the XfceGtkActionEntry in action_entries.

#### Parameters

accel_group | the GtkAccelGroup to connect to |
action_entries | array of action_entries to be added |
n_action_entries | size of the action_entries array |

Since: 4.16

### xfce_gtk_get_action_entry_by_id ()

    const XfceGtkActionEntry *
    xfce_gtk_get_action_entry_by_id (const XfceGtkActionEntry *action_entries,
                                     guint n_action_entries,
                                     guint id);

Convenience method to find a specific action_entry from an array of action_entries

#### Parameters

action_entries | array of action_entries to be searched |
n_action_entries | size of the action_entries array |
id | id of the action entry (usually enum values are used) |

#### Returns

The matching XfceGtkActionEntry or NULL if not found.

[transfer none][nullable]

Since: 4.16

### xfce_gtk_translate_action_entries ()

    void
    xfce_gtk_translate_action_entries (XfceGtkActionEntry *action_entries,
                                       guint n_action_entries);

Convenience method to translate the label text and tooltip text of an array of action_entries

#### Parameters

action_entries | array of action_entries to be translated |
n_action_entries | size of the action_entries array |

Since: 4.16

### xfce_gtk_handle_tab_accels ()

    gboolean
    xfce_gtk_handle_tab_accels (GdkEventKey *key_event,
                                GtkAccelGroup *accel_group,
                                gpointer data,
                                XfceGtkActionEntry *entries,
                                size_t entry_count);

The Tab key is used to navigate the interface by GTK+ so we need to handle shortcuts with the Tab accelerator manually. Tab sometimes becomes ISO_Left_Tab (e.g. in Ctrl+Shift+Tab) so check both here.

#### Parameters

key_event | the GdkEventKey that might trigger a shortcut |
accel_group | the GtkAccelGroup that will be get queried |
data | a pointer of data that will be passed to the callback if a tab-shortcut is found |
entries | a XfceGtkActionEntry[] |
entry_count | the number of entries in `entries` |

#### Returns

a boolean that is GDK_EVENT_STOP (TRUE) if the event was handled, otherwise it is GDK_EVENT_PROPAGATE (FALSE)

### xfce_gtk_execute_tab_accel ()

    gboolean
    xfce_gtk_execute_tab_accel (const gchar *accel_path,
                                gpointer data,
                                XfceGtkActionEntry *entries,
                                size_t entry_count);

Activates the callback function of the XfceGtkActionEntry that corresponds to `accel_path` . If no such action exists in `entries` , then nothing happens.

#### Parameters

accel_path | the accelerator path of the action that we want to activate |
data | a pointer of data that will be passed to the callback if a tab-shortcut is found |
entries | a XfceGtkActionEntry[] |
entry_count | the number of entries in `entries` |

#### Returns

a boolean that is TRUE if the action was found, otherwise it is FALSE

### xfce_gtk_menu_append_separator ()

    void
    xfce_gtk_menu_append_separator (GtkMenuShell *menu);

Convenience method do add separators, used to prevent code duplication

#### Parameters

menu | GtkMenuShell on which the separator should be appended |

Since: 4.16

### xfce_gtk_button_new_mixed ()

    GtkWidget *
    xfce_gtk_button_new_mixed (const gchar *stock_id,
                               const gchar *label);

Creates a new GtkButton containing a mnemonic label and a stock icon. The `stock_id` could be something like GTK_STOCK_OK or GTK_STOCK_APPLY.

When the `stock_id` is `NULL` a normal mnemonic button will be created, when `label` is `NULL` a stock button will be created. This behaviour is added for `xfce_message_dialog_new()`.

#### Parameters

stock_id | the name of the stock item. | [nullable]
label | the text of the button, with an underscore in front of the mnemonic character. | [nullable]

#### Returns

the newly created GtkButton widget.

[transfer floating]

### xfce_gtk_frame_box_new ()

    GtkWidget *
    xfce_gtk_frame_box_new (const gchar *label,
                            GtkWidget **container_return);

Creates an Xfce-styled frame. The frame is a GtkFrame, without outline and an optional bolded text label. The contents of the frame are indented on the left. The return value is the GtkFrame itself. The `container_return` is a GtkAlignment widget to which children of the frame should be added.

See also: `xfce_gtk_frame_box_new_with_content()`.

#### Parameters

label | the text to use as the label of the frame. |
container_return | return location for the frame's container. | [out][nullable]

#### Returns

the newly created GtkFrame widget.

[transfer floating]

### xfce_gtk_frame_box_new_with_content ()

    GtkWidget *
    xfce_gtk_frame_box_new_with_content (const gchar *label,
                                         GtkWidget *content);

Creates a widget with `xfce_gtk_frame_box_new()` and adds the `content` GtkWidget to the frame.

#### Parameters

label | the text to use as the label of the frame. |
content | the GtkWidget to put inside the frame. |

#### Returns

the newly created GtkFrame widget.

[transfer floating]

### xfce_gtk_window_center_on_active_screen ()

    void
    xfce_gtk_window_center_on_active_screen
                                   (GtkWindow *window);

Determines the screen that contains the pointer and centers the `window` on it. If it failes to determine the current pointer position, `window` is centered on the default screen.

This function only works properly if you call it before realizing the window and you haven't set a fixed window position using `gtk_window_move()`.

See also: `xfce_gdk_screen_get_active()`.

#### Parameters

window | the GtkWindow to center. |

### xfce_gtk_menu_popup_until_mapped ()

    gboolean
    xfce_gtk_menu_popup_until_mapped (GtkMenu *menu,
                                      GtkWidget *parent_menu_shell,
                                      GtkWidget *parent_menu_item,
                                      GtkMenuPositionFunc func,
                                      gpointer data,
                                      guint button,
                                      guint32 activate_time);

Attempts to pop up a GtkMenu for a short duration. Unlike the original `gtk_menu_popup()`, this function will verify that the menu has been mapped or will keep trying for up to 250ms. It will also return a value indicating whether the menu was eventually mapped or not. Following is an excerpt from the GTK+ Documentation on GtkMenu.

Displays a menu and makes it available for selection.

Applications can use this function to display context-sensitive menus, and will typically supply `NULL` for the `parent_menu_shell` , `parent_menu_item` , `func` and `data` parameters. The default menu positioning function will position the menu at the current mouse cursor position.

The `button` parameter should be the mouse button pressed to initiate the menu popup. If the menu popup was initiated by something other than a mouse button press, such as a mouse button release or a keypress, button should be 0.

The `activate_time` parameter is used to conflict-resolve initiation of concurrent requests for mouse/keyboard grab requests. To function properly, this needs to be the timestamp of the user event (such as a mouse click or key press) that caused the initiation of the popup. Only if no such event is available, `gtk_get_current_event_time()` can be used instead.

#### Parameters

menu | a GtkMenu. |
parent_menu_shell | the menu shell containing the triggering menu item, or `NULL`. | [nullable]
parent_menu_item | the menu item whose activation triggered the popup, or `NULL`. | [nullable]
func | a user supplied function used to position the menu, or `NULL`. | [scope call][nullable]
data | user supplied data to be passed to func. | [nullable]
button | the mouse button which was pressed to initiate the event. |
activate_time | the time at which the activation event occurred. |

#### Returns

`TRUE` if the menu could be mapped, `FALSE` otherwise.

Since: 4.14

### xfce_widget_reparent ()

    gboolean
    xfce_widget_reparent (GtkWidget *widget,
                          GtkWidget *new_parent);

Moves a widget from one GtkContainer to another, handling reference count issues to avoid destroying the widget.

#### Parameters

widget | a GtkWidget. |
new_parent | a GtkContainer to move the widget into |

#### Returns

`TRUE` if the widget could be moved, `FALSE` otherwise.

Since: 4.14

### xfce_icon_name_from_desktop_id ()

    gchar *
    xfce_icon_name_from_desktop_id (const gchar *desktop_id);

#### Parameters

desktop_id | Name of the desktop file. |

#### Returns

`NULL` on error, else the string value of the "Icon" property.

Since: 4.16

### xfce_gicon_from_name ()

    GIcon *
    xfce_gicon_from_name (const gchar *name);

This function will first look for a desktop file of `name` and if successful use the value of the "Icon" property to return a GIcon. If no desktop file of `name` is found it will fallback to returning a GIcon based on g_themed_icon_new_with_default_fallbacks and gtk_icon_theme_lookup_by_gicon.

#### Parameters

name | Name of the application. |

#### Returns

a new GThemedIcon.

[transfer full]

Since: 4.16

### xfce_gtk_menu_item_set_accel_label ()

    void
    xfce_gtk_menu_item_set_accel_label (GtkMenuItem *menu_item,
                                        const gchar *accel_path);

Use the passed accel_path show the related GtkAccelLabel with the correct accelerator on the item.

#### Parameters

menu_item | GtkMenuItem on which the accel label is to set |
accel_path | Unique path, used to identify the accelerator, or NULL to show no accelerator. | [nullable]

Since: 4.16

### xfce_has_gtk_frame_extents ()

    gboolean
    xfce_has_gtk_frame_extents (GdkWindow *window,
                                GtkBorder *extents);

This function can be called to determine if a GdkWindow is using client-side decorations which is indicated by the _GTK_FRAME_EXTENTS X11 atom. It furthermore sets a pointer of type GtkBorder to the actual extents.

#### Parameters

window | A GdkWindow |
extents | A pointer to a GtkBorder to copy to. |

#### Returns

TRUE if a GdkWindow has the _GTK_FRAME_EXTENTS atom set.

Since: 4.16

### xfce_gtk_label_set_a11y_relation ()

    void
    xfce_gtk_label_set_a11y_relation (GtkLabel *label,
                                      GtkWidget *widget);

Sets the `ATK_RELATION_LABEL_FOR` relation on `label` for `widget` , which means accessiblity tools will identify `label` as descriptive item for the specified `widget` .

#### Parameters

label | a GtkLabel. |
widget | a GtkWidget. |

## Types and Values

### enum XfceGtkMenuItem

List of item types which are supported by the XfceGtkActionEntry. To be extended if required.

#### Members

XFCE_GTK_MENU_ITEM | see GtkMenuItem |
XFCE_GTK_IMAGE_MENU_ITEM | see GtkImageMenuItem |
XFCE_GTK_CHECK_MENU_ITEM | see GtkCheckMenuItem |
XFCE_GTK_RADIO_MENU_ITEM | see GtkRadioMenuItem |

### XfceGtkActionEntry

    typedef struct {
      guint id;
      const gchar *accel_path;
      const gchar *default_accelerator;

      /* menu_item data is optional, only relevant if there exists a menu_item for that accelerator */
      XfceGtkMenuItem menu_item_type;
      gchar *menu_item_label_text;
      gchar *menu_item_tooltip_text;
      const gchar *menu_item_icon_name;

      GCallback callback;
    } XfceGtkActionEntry;

Replacement for the deprecated GtkActionEntry. The idea is to provide a fixed list of XfceGtkActionEntrys:

- use `xfce_gtk_translate_action_entries()` once to translate the list

- use `xfce_gtk_accel_map_add_entries()` once to register the provided accelerators

- use `xfce_gtk_get_action_entry_by_id()` to find a single entry, e.g. by using a enumeration

- use xfce_gtk_*_new_from_action_entry() to create the specific menu- or tool-items from the entry

#### Members

guint `id`; | unique identifier for instances of this structure (you might want to use a enum) |
const gchar *`accel_path`; | the unique path, used to identify the accelerator |
const gchar *`default_accelerator`; | the default key and modifier to trigger the callback linked to the entry |
XfceGtkMenuItem `menu_item_type`; | the type of the item which should be used for creation |
gchar *`menu_item_label_text`; | text which should be shown in the menu |
gchar *`menu_item_tooltip_text`; | optional tooltip of the item |
const gchar *`menu_item_icon_name`; | optional icon name which will be used to find a image for the item |
GCallback `callback`; | the callback which will be triggered on activation. The callback has to return `TRUE` to signal that the accelerator was activated and handled |