Functions

dialog_confirm_close_tabs (parent, num_tabs, show_confirm_box, confirm_box_checked)

dialog_show_help (parent, component, page, offset)

dialog_show_help_with_version (parent, component, page, offset, version)

gdk_device_grab (seat, window, capabilities, cursor)

gdk_screen_get_active ()

gdk_screen_get_geometry ()

gicon_from_name (name)

gtk_accel_group_connect_action_entries (accel_group, action_entries, n_action_entries, callback_data)

gtk_accel_group_disconnect_action_entries (accel_group, action_entries, n_action_entries)

gtk_accel_map_add_entries (action_entries, n_action_entries)

gtk_button_new_mixed (stock_id, label)

gtk_check_menu_item_new (label_text, tooltip_text, accel_path, callback, callback_param, active, menu_to_append_item)

gtk_execute_tab_accel (accel_path, data, entries, entry_count)

gtk_frame_box_new (label)

gtk_frame_box_new_with_content (label, content)

gtk_get_action_entry_by_id (action_entries, n_action_entries, id)

gtk_handle_tab_accels (key_event, accel_group, data, entries, entry_count)

gtk_image_menu_item_new (label_text, tooltip_text, accel_path, callback, callback_param, image, menu_to_append_item)

gtk_image_menu_item_new_from_icon_name (label_text, tooltip_text, accel_path, callback, callback_param, icon_name, menu_to_append_item)

gtk_label_set_a11y_relation (label, widget)

gtk_menu_append_separator (menu)

gtk_menu_append_seperator (menu)

gtk_menu_item_new (label_text, tooltip_text, accel_path, callback, callback_param, menu_to_append_item)

gtk_menu_item_new_from_action_entry (action_entry, callback_param, menu_to_append_item)

gtk_menu_item_set_accel_label (menu_item, accel_path)

gtk_menu_popup_until_mapped (menu, parent_menu_shell, parent_menu_item, func, data, button, activate_time)

gtk_radio_menu_item_new (label_text, tooltip_text, accel_path, callback, callback_param, active, menu_to_append_item)

gtk_toggle_menu_item_new_from_action_entry (action_entry, callback_param, active, menu_to_append_item)

gtk_toggle_tool_button_new_from_action_entry (action_entry, callback_param, active, toolbar_to_append_item)

gtk_tool_button_new_from_action_entry (action_entry, callback_param, toolbar_to_append_item)

gtk_translate_action_entries (action_entries, n_action_entries)

gtk_window_center_on_active_screen (window)

has_gtk_frame_extents (window, extents)

icon_name_from_desktop_id (desktop_id)

spawn (screen, working_directory, argv, envp, flags, startup_notify, startup_timestamp, startup_icon_name, child_process)

spawn_command_line (screen, command_line, in_terminal, startup_notify, child_process)

spawn_command_line_on_screen (screen, command_line, in_terminal, startup_notify)

spawn_on_screen (screen, working_directory, argv, envp, flags, startup_notify, startup_timestamp, startup_icon_name)

spawn_on_screen_with_child_watch (screen, working_directory, argv, envp, flags, startup_notify, startup_timestamp, startup_icon_name, child_watch_closure)

widget_reparent (widget, new_parent)

Details

Libxfce4ui.dialog_confirm_close_tabs(parent, num_tabs, show_confirm_box, confirm_box_checked)
Parameters:

  • parent (Gtk.Window or None) – transient parent of the dialog, or None.

  • num_tabs (int) – the number of open tabs for display to user

  • show_confirm_box (bool) – whether to ask the user if this confirmation shall be shown in the future

  • confirm_box_checked (bool or None) – state of confirmation checkbox

Returns:

Gtk.ResponseType.CANCEL if cancelled, Gtk.ResponseType.YES if the user wants to close the window, Gtk.ResponseType.CLOSE if the user wants to close the tab, and Gtk.ResponseType.NONE for an error.

Return type:

int

Runs a dialog to ask the user whether they want to close the whole window, close the current tab, or cancel.

If num_tabs is non-negative, the message to the user will state that there are num_tabs open tabs. If num_tabs is negative, then the message to the user will state simply that there are “multiple open tabs”.

If show_confirm_box is True a checkbox is added to the dialog to allow the user to set whether they wish to see this dialog in future. The initial state of the checkbox is determined by the value stored at confirm_box_checked and the value at confirm_box_checked after returning records the state of the checkbox. If show_confirm_box is False, confirm_box_checked is ignored and may be None.

New in version 4.16.

Libxfce4ui.dialog_show_help(parent, component, page, offset)
Parameters:

  • parent (Gtk.Window or None) – transient parent of the dialog, or None.

  • component (str or None) – name of the component opening the help page or None. If the value is None the target will be the main page of the documentation website.

  • page (str or None) – subpage of the component on the website or None.

  • offset (str or None) – anchor offset in page or None.

Asks the user to visit the online documentation. If confirmed, it will open the webbrowser and redirect the user to the correct location.

Appart from the component, page and offset the following information is also send to the server: user language and the Libxfce4util.version_string().

See also: Libxfce4ui.dialog_show_help_with_version().

New in version 4.10.

Libxfce4ui.dialog_show_help_with_version(parent, component, page, offset, version)
Parameters:

Asks the user to visit the online documentation. If confirmed, it will open the webbrowser and redirect the user to the correct location.

Apart from the component, page and offset the following information is also sent to the server: user language and the Libxfce4util.version_string() or version if set.

See also: Libxfce4ui.dialog_show_help().

New in version 4.12.

Libxfce4ui.gdk_device_grab(seat, window, capabilities, cursor)
Parameters:

  • seat (Gdk.Seat) – A Gdk.Seat.

  • window (Gdk.Window) – The Gdk.Window which will own the grab.

  • capabilities (Gdk.SeatCapabilities) – Capabilities that will be grabbed.

  • cursor (Gdk.Cursor or None) – The cursor to display while the grab is active. If this is None then the normal cursors are used for window and its descendants, and the cursor for window is used elsewhere.

Returns:

True on success, False otherwise.

Return type:

bool

Similar to Gdk.Seat.grab but tries to grab the seat five times with 100ms between each attempt.

New in version 4.18.

Libxfce4ui.gdk_screen_get_active()
Returns:

the currently active Gdk.Screen.

monitor_return:

Address to store the monitor number to or None.

Return type:

(Gdk.Screen, monitor_return: int)

Returns the currently active Gdk.Screen, that is, the screen which currently contains the pointer. If no active screen was found, the default Gdk.Screen is returned.

Libxfce4ui.gdk_screen_get_geometry()
Returns:

a newly created Gdk.Rectangle containing the width and height of the screen.

Return type:

Gdk.Rectangle

Returns the width and height of the default Gdk.Screen. This is a replacement for Gdk.Screen.width/Gdk.Screen.height.

New in version 4.14.

Libxfce4ui.gicon_from_name(name)
Parameters:

name (str) – Name of the application.

Returns:

a new Gio.ThemedIcon.

Return type:

Gio.Icon

This function will first look for a desktop file of name and if successful use the value of the “Icon” property to return a Gio.Icon. If no desktop file of name is found it will fallback to returning a Gio.Icon based on Gio.ThemedIcon.new_with_default_fallbacks and Gtk.IconTheme.lookup_by_gicon.

New in version 4.16.

Libxfce4ui.gtk_accel_group_connect_action_entries(accel_group, action_entries, n_action_entries, callback_data)
Parameters:

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

New in version 4.16.

Libxfce4ui.gtk_accel_group_disconnect_action_entries(accel_group, action_entries, n_action_entries)
Parameters:

This method will disconnect each accel_path from the Libxfce4ui.GtkActionEntry in action_entries.

New in version 4.16.

Libxfce4ui.gtk_accel_map_add_entries(action_entries, n_action_entries)
Parameters:

  • action_entries (Libxfce4ui.GtkActionEntry) – array of action_entries to be added

  • n_action_entries (int) – size of the action_entries array

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

New in version 4.16.

Libxfce4ui.gtk_button_new_mixed(stock_id, label)
Parameters:

  • stock_id (str or None) – the name of the stock item.

  • label (str or None) – the text of the button, with an underscore in front of the mnemonic character.

Returns:

the newly created Gtk.Button widget.

Return type:

Gtk.Widget

Creates a new Gtk.Button 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 None a normal mnemonic button will be created, when label is None a stock button will be created. This behaviour is added for xfce_message_dialog_new().

Libxfce4ui.gtk_check_menu_item_new(label_text, tooltip_text, accel_path, callback, callback_param, active, menu_to_append_item)
Parameters:
Returns:

A new Gtk.CheckMenuItem.

Return type:

Gtk.Widget

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

New in version 4.16.

Libxfce4ui.gtk_execute_tab_accel(accel_path, data, entries, entry_count)
Parameters:
Returns:

a boolean that is True if the action was found, otherwise it is False

Return type:

bool

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

Libxfce4ui.gtk_frame_box_new(label)
Parameters:

label (str) – the text to use as the label of the frame.

Returns:

the newly created Gtk.Frame widget.

container_return:

return location for the frame’s container.

Return type:

(Gtk.Widget, container_return: Gtk.Widget or None)

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

See also: Libxfce4ui.gtk_frame_box_new_with_content().

Libxfce4ui.gtk_frame_box_new_with_content(label, content)
Parameters:

  • label (str) – the text to use as the label of the frame.

  • content (Gtk.Widget) – the Gtk.Widget to put inside the frame.

Returns:

the newly created Gtk.Frame widget.

Return type:

Gtk.Widget

Creates a widget with Libxfce4ui.gtk_frame_box_new() and adds the content Gtk.Widget to the frame.

Libxfce4ui.gtk_get_action_entry_by_id(action_entries, n_action_entries, id)
Parameters:

  • action_entries (Libxfce4ui.GtkActionEntry) – array of action_entries to be searched

  • n_action_entries (int) – size of the action_entries array

  • id (int) – id of the action entry (usually enum values are used)

Returns:

The matching Libxfce4ui.GtkActionEntry or None if not found

Return type:

Libxfce4ui.GtkActionEntry or None

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

New in version 4.16.

Libxfce4ui.gtk_handle_tab_accels(key_event, accel_group, data, entries, entry_count)
Parameters:
Returns:

a boolean that is Gdk.EVENT_STOP (True) if the event was handled, otherwise it is Gdk.EVENT_PROPAGATE (False)

Return type:

bool

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.

Libxfce4ui.gtk_image_menu_item_new(label_text, tooltip_text, accel_path, callback, callback_param, image, menu_to_append_item)
Parameters:
Returns:

A new Gtk.ImageMenuItem.

Return type:

Gtk.Widget

Convenience method to create a deprecated Gtk.ImageMenuItem 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

New in version 4.16.

Libxfce4ui.gtk_image_menu_item_new_from_icon_name(label_text, tooltip_text, accel_path, callback, callback_param, icon_name, menu_to_append_item)
Parameters:
Returns:

A new Gtk.ImageMenuItem.

Return type:

Gtk.Widget

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

New in version 4.16.

Libxfce4ui.gtk_label_set_a11y_relation(label, widget)
Parameters:

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.

Libxfce4ui.gtk_menu_append_separator(menu)
Parameters:

menu (Gtk.MenuShell) – Gtk.MenuShell on which the separator should be appended

Convenience method do add separators, used to prevent code duplication

New in version 4.16.

Libxfce4ui.gtk_menu_append_seperator(menu)
Parameters:

menu (Gtk.MenuShell) – Gtk.MenuShell on which the separator should be appended

Convenience method do add separators, used to prevent code duplication

New in version 4.16.

Deprecated since version 4.19.1: Use Libxfce4ui.gtk_menu_append_separator() instead.

Libxfce4ui.gtk_menu_item_new(label_text, tooltip_text, accel_path, callback, callback_param, menu_to_append_item)
Parameters:
Returns:

A new Gtk.MenuItem.

Return type:

Gtk.Widget

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

New in version 4.16.

Libxfce4ui.gtk_menu_item_new_from_action_entry(action_entry, callback_param, menu_to_append_item)
Parameters:
Returns:

A new Gtk.MenuItem or None

Return type:

Gtk.Widget or None

Method to create a menu item from the passed action entry

New in version 4.16.

Libxfce4ui.gtk_menu_item_set_accel_label(menu_item, accel_path)
Parameters:

  • menu_item (Gtk.MenuItem) – Gtk.MenuItem on which the accel label is to set

  • accel_path (str or None) – Unique path, used to identify the accelerator, or None to show no accelerator

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

New in version 4.16.

Libxfce4ui.gtk_menu_popup_until_mapped(menu, parent_menu_shell, parent_menu_item, func, data, button, activate_time)
Parameters:

  • menu (Gtk.Menu) – a Gtk.Menu.

  • parent_menu_shell (Gtk.Widget or None) – the menu shell containing the triggering menu item, or None.

  • parent_menu_item (Gtk.Widget or None) – the menu item whose activation triggered the popup, or None.

  • func (Gtk.MenuPositionFunc or None) – a user supplied function used to position the menu, or None.

  • data (object or None) – user supplied data to be passed to func.

  • button (int) – the mouse button which was pressed to initiate the event.

  • activate_time (int) – the time at which the activation event occurred.

Returns:

True if the menu could be mapped, False otherwise.

Return type:

bool

Attempts to pop up a Gtk.Menu 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 Gtk.Menu.

Displays a menu and makes it available for selection.

Applications can use this function to display context-sensitive menus, and will typically supply None 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.

New in version 4.14.

Libxfce4ui.gtk_radio_menu_item_new(label_text, tooltip_text, accel_path, callback, callback_param, active, menu_to_append_item)
Parameters:
Returns:

A new Gtk.CheckMenuItem.

Return type:

Gtk.Widget

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

New in version 4.16.

Libxfce4ui.gtk_toggle_menu_item_new_from_action_entry(action_entry, callback_param, active, menu_to_append_item)
Parameters:
Returns:

A new Gtk.MenuItem or None

Return type:

Gtk.Widget or None

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

New in version 4.16.

Libxfce4ui.gtk_toggle_tool_button_new_from_action_entry(action_entry, callback_param, active, toolbar_to_append_item)
Parameters:
Returns:

A new Gtk.ToggleToolButton

Return type:

Gtk.Widget

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

New in version 4.17.6.

Libxfce4ui.gtk_tool_button_new_from_action_entry(action_entry, callback_param, toolbar_to_append_item)
Parameters:
Returns:

A new Gtk.ToolButton

Return type:

Gtk.Widget

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

New in version 4.16.

Libxfce4ui.gtk_translate_action_entries(action_entries, n_action_entries)
Parameters:

  • action_entries (Libxfce4ui.GtkActionEntry) – array of action_entries to be translated

  • n_action_entries (int) – size of the action_entries array

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

New in version 4.16.

Libxfce4ui.gtk_window_center_on_active_screen(window)
Parameters:

window (Gtk.Window) – the Gtk.Window to center.

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: Libxfce4ui.gdk_screen_get_active().

Libxfce4ui.has_gtk_frame_extents(window, extents)
Parameters:
Returns:

True if a Gdk.Window has the _GTK_FRAME_EXTENTS atom set.

Return type:

bool

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

New in version 4.16.

Libxfce4ui.icon_name_from_desktop_id(desktop_id)
Parameters:

desktop_id (str) – Name of the desktop file.

Returns:

None on error, else the string value of the “Icon” property.

Return type:

str

New in version 4.16.

Libxfce4ui.spawn(screen, working_directory, argv, envp, flags, startup_notify, startup_timestamp, startup_icon_name, child_process)
Parameters:
Raises:

GLib.Error

Returns:

True on success, False if error is set.

Return type:

bool

Like gdk_spawn_on_screen() (GDK 2), but also supports startup notification (if Libxfce4ui was built with startup notification support).

New in version 4.16.

Libxfce4ui.spawn_command_line(screen, command_line, in_terminal, startup_notify, child_process)
Parameters:
Raises:

GLib.Error

Returns:

True if the command_line was executed successfully, False if error is set.

Return type:

bool

Executes the given command_line and returns True if the command terminated successfully. Else, the error is set to the standard error output.

New in version 4.16.

Libxfce4ui.spawn_command_line_on_screen(screen, command_line, in_terminal, startup_notify)
Parameters:
Raises:

GLib.Error

Returns:

True if the command_line was executed successfully, False if error is set.

Return type:

bool

Executes the given command_line and returns True if the command terminated successfully. Else, the error is set to the standard error output.

Deprecated since version 4.16: Use Libxfce4ui.spawn_command_line instead.

Libxfce4ui.spawn_on_screen(screen, working_directory, argv, envp, flags, startup_notify, startup_timestamp, startup_icon_name)
Parameters:
Raises:

GLib.Error

Returns:

True on success, False if error is set.

Return type:

bool

Like gdk_spawn_on_screen() (GDK 2), but also supports startup notification (if Libxfce4ui was built with startup notification support).

Deprecated since version 4.16: Use Libxfce4ui.spawn instead.

Libxfce4ui.spawn_on_screen_with_child_watch(screen, working_directory, argv, envp, flags, startup_notify, startup_timestamp, startup_icon_name, child_watch_closure)
Parameters:
Raises:

GLib.Error

Returns:

True on success, False if error is set.

Return type:

bool

Like Libxfce4ui.spawn_on_screen(), but allows to attach a closure to watch the child’s exit status. This because only one GLib.child_watch_add() is allowed on Unix (per PID) and this is already internally needed for a proper startup notification implementation.

Spawning with a child watch
static void
child_watch_callback (GObject *object,
                      gint     status)
{
  g_message ("Child exit status is %d", status);
}

static void
spawn_something (void)
{
  GClosure *child_watch;

  child_watch = g_cclosure_new_swap (G_CALLBACK (child_watch_callback),
                                     object, NULL);
  xfce_spawn_on_screen_with_child_watch (...,
                                         child_watch,
                                         ...);
}
Libxfce4ui.widget_reparent(widget, new_parent)
Parameters:
Returns:

True if the widget could be moved, False otherwise.

Return type:

bool

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

New in version 4.14.