Gtk Extensions

Gtk Extensions — various extensions to Gtk+

Stability Level

Stable, unless otherwise indicated

Functions

Types and Values

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

 

accel_path

Unique path, used to identify the accelerator, or NULL

 

callback

GCallback which will be triggered on activation, or NULL.

[scope notified]

callback_param

optional callback parameter, or NULL.

 

menu_to_append_item

GtkMenuShell on which the item should be appended, or NULL

 

Returns

A new GtkMenuItem.

[transfer full]

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

 

accel_path

Unique path, used to identify the accelerator, or NULL

 

callback

GCallback which will be triggered on activation, or NULL.

[scope notified]

callback_param

optional callback parameter, or NULL.

 

image

a widget to set as the image for the menu item, or NULL

 

menu_to_append_item

GtkMenuShell on which the item should be appended, or NULL

 

Returns

A new GtkImageMenuItem.

[transfer full]

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

 

accel_path

Unique path, used to identify the accelerator, or NULL

 

callback

GCallback which will be triggered on activation, or NULL.

[scope notified]

callback_param

optional callback parameter, or NULL.

 

icon_name

name of the icon to use for the GtkImageMenuItem, or NULL

 

menu_to_append_item

GtkMenuShell on which the item should be appended, or NULL

 

Returns

A new GtkImageMenuItem.

[transfer full]

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

 

accel_path

Unique path, used to identify the accelerator, or NULL

 

callback

GCallback which will be triggered on activation, or NULL.

[scope notified]

callback_param

optional callback parameter, or NULL.

 

active

boolean value indicating whether the check box is active.

 

menu_to_append_item

GtkMenuShell on which the item should be appended, or NULL

 

Returns

A new GtkCheckMenuItem.

[transfer full]

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

 

accel_path

Unique path, used to identify the accelerator, or NULL

 

callback

GCallback which will be triggered on activation, or NULL.

[scope notified]

callback_param

optional callback parameter, or NULL.

 

active

boolean value indicating whether the check box is active.

 

menu_to_append_item

GtkMenuShell on which the item should be appended, or NULL

 

Returns

A new GtkCheckMenuItem.

[transfer full]

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.

 

menu_to_append_item

GtkMenuShell on which the item should be appended, or NULL

 

Returns

A new GtkMenuItem or NULL.

[transfer full]

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.

 

active

boolean value indicating whether the check box is active.

 

menu_to_append_item

GtkMenuShell on which the item should be appended, or NULL

 

Returns

A new GtkMenuItem or NULL.

[transfer full]

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 GtkTolButton

 

callback_param

optional callback parameter, or NULL.

 

toolbar_to_append_item

GtkToolBar on which the item should be appended

 

Returns

A new GtkTolButton.

[transfer full]

Since: 4.16


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]

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_menu_append_seperator ()

void
xfce_gtk_menu_append_seperator (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.

 

label

the text of the button, with an underscore in front of the mnemonic character.

 

Returns

the newly created GtkButton widget.

[transfer full]


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][allow-none]

Returns

the newly created GtkFrame widget.

[transfer full]


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 full]


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.

[allow-none]

parent_menu_item

the menu item whose activation triggered the popup, or NULL.

[allow-none]

func

a user supplied function used to position the menu, or NULL.

[scope call][allow-none]

data

user supplied data to be passed to func.

[allow-none]

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

 

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

Members

XFCE_GTK_MENU_ITEM

   

XFCE_GTK_IMAGE_MENU_ITEM

   

XFCE_GTK_CHECK_MENU_ITEM

   

XFCE_GTK_RADIO_MENU_ITEM

   

XfceGtkActionEntry

typedef struct {
  /*
   * 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
  */

  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 */

  /* menu_item data is optional, only relevant if there exists a menu_item for that accelerator */
  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 */
} XfceGtkActionEntry;