Gtk Extensions: Libxfce4ui Reference Manual

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

## Stability Level

Stable, unless otherwise indicated

## Functions

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_widget_reparent ()
gboolean | xfce_gtk_menu_popup_until_mapped ()

## Includes

    #include <libxfce4ui/libxfce4ui.h>

## Description

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

## Functions

### 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_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_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