XfwWindow: libxfce4windowing Reference Manual

## XfwWindow XfwWindow — A representation of a toplevel window |

## Stability Level

Unstable, unless otherwise indicated

## Functions

guint64 | xfw_window_get_id ()
const gchar * | xfw_window_get_name ()
GdkPixbuf * | xfw_window_get_icon ()
GIcon * | xfw_window_get_gicon ()
gboolean | xfw_window_icon_is_fallback ()
XfwWindowType | xfw_window_get_window_type ()
XfwWindowState | xfw_window_get_state ()
XfwWindowCapabilities | xfw_window_get_capabilities ()
GdkRectangle * | xfw_window_get_geometry ()
XfwScreen * | xfw_window_get_screen ()
XfwWorkspace * | xfw_window_get_workspace ()
GList * | xfw_window_get_monitors ()
XfwApplication * | xfw_window_get_application ()
gboolean | xfw_window_activate ()
gboolean | xfw_window_close ()
gboolean | xfw_window_start_move ()
gboolean | xfw_window_start_resize ()
gboolean | xfw_window_set_geometry ()
gboolean | xfw_window_set_button_geometry ()
gboolean | xfw_window_move_to_workspace ()
gboolean | xfw_window_set_minimized ()
gboolean | xfw_window_set_maximized ()
gboolean | xfw_window_set_fullscreen ()
gboolean | xfw_window_set_skip_pager ()
gboolean | xfw_window_set_skip_tasklist ()
gboolean | xfw_window_set_pinned ()
gboolean | xfw_window_set_shaded ()
gboolean | xfw_window_set_above ()
gboolean | xfw_window_set_below ()
gboolean | xfw_window_is_active ()
gboolean | xfw_window_is_minimized ()
gboolean | xfw_window_is_maximized ()
gboolean | xfw_window_is_fullscreen ()
gboolean | xfw_window_is_skip_pager ()
gboolean | xfw_window_is_skip_tasklist ()
gboolean | xfw_window_is_pinned ()
gboolean | xfw_window_is_shaded ()
gboolean | xfw_window_is_above ()
gboolean | xfw_window_is_below ()
gboolean | xfw_window_is_urgent ()
gboolean | xfw_window_is_on_workspace ()
gboolean | xfw_window_is_in_viewport ()

## Properties

XfwApplication * | application | Read
XfwWindowCapabilities | capabilities | Read
GIcon * | gicon | Read
guint64 | id | Read
gpointer | monitors | Read
char * | name | Read
XfwScreen * | screen | Read / Write / Construct Only
XfwWindowState | state | Read
XfwWindowType | type | Read
XfwWorkspace * | workspace | Read

## Signals

void | capabilities-changed | Run Last
void | closed | Run Last
void | geometry-changed | Run Last
void | icon-changed | Run Last
void | name-changed | Run Last
void | state-changed | Run Last
void | type-changed | Run Last
void | workspace-changed | Run Last

## Types and Values

| XfwWindow
enum | XfwWindowCapabilities
enum | XfwWindowState
enum | XfwWindowType

## Object Hierarchy

        GFlags
        ├── XfwWindowCapabilities
        ╰── XfwWindowState
        GObject
        ╰── XfwWindow

## Includes

    #include <libxfce4windowing/libxfce4windowing.h>

## Description

XfwWindow describes a toplevel window on the screen, and provides access to the window's state, type, and actions that can be performed on it.

Other metadata, like the window's title or icon, is also available.

If the window supports it, actions can be taken, like minimizing, maximizing, pinning, moving between workspaces, or closing the window.

Note that XfwWindow is actually an interface; when obtaining an instance, an instance of a windowing-environment-specific object that implements this interface will be returned.

## Functions

### xfw_window_get_id ()

    guint64
    xfw_window_get_id (XfwWindow *window);

Fetches the windowing-platform dependent window ID.

#### Parameters

window | an XfwWindow. |

#### Returns

a 64-bit unsigned integer.

### xfw_window_get_name ()

    const gchar *
    xfw_window_get_name (XfwWindow *window);

Fetches `window` 's name/title.

#### Parameters

window | an XfwWindow. |

#### Returns

a window title, or `NULL` if there is no title. The returned title should not be modified or freed.

[nullable][transfer none]

### xfw_window_get_icon ()

    GdkPixbuf *
    xfw_window_get_icon (XfwWindow *window,
                         gint size,
                         gint scale);

Fetches `window` 's icon. If `window` has no icon, a fallback icon may be returned. Whether or not the returned icon is a fallback icon can be determined using `xfw_window_icon_is_fallback()`.

#### Parameters

window | an XfwWindow. |
size | the desired icon size. |
scale | the UI scale factor. |

#### Returns

a GdkPixbuf, owned by `window` , or `NULL` if `window` has no icon and a fallback cannot be rendered.

[nullable][transfer none]

### xfw_window_get_gicon ()

    GIcon *
    xfw_window_get_gicon (XfwWindow *window);

Fetches `window` 's icon as a size-independent GIcon. If an icon cannot be found, a GIcon representing a fallback icon will be returned. Whether or not the returned icon is a fallback icon can be determined using `xfw_window_icon_is_fallback()`.

#### Parameters

window | an XfwWindow. |

#### Returns

a GIcon, owned by `window` .

[not nullable][transfer none]

Since: 4.19.1

### xfw_window_icon_is_fallback ()

    gboolean
    xfw_window_icon_is_fallback (XfwWindow *window);

Determines if `window` does not have an icon, and thus a fallback icon will be returned from `xfw_window_get_icon()` and `xfw_window_get_gicon()`.

#### Parameters

window | an XfwWindow. |

#### Returns

`TRUE` or `FALSE`, depending on if `window` 's icon uses a fallback icon or not.

Since: 4.19.1

### xfw_window_get_window_type ()

    XfwWindowType
    xfw_window_get_window_type (XfwWindow *window);

### xfw_window_get_state ()

    XfwWindowState
    xfw_window_get_state (XfwWindow *window);

Fetches `window` 's state bitfield.

#### Parameters

window | an XfwWindow. |

#### Returns

a bitfield with zero or more bits from XfwWindowState set.

### xfw_window_get_capabilities ()

    XfwWindowCapabilities
    xfw_window_get_capabilities (XfwWindow *window);

Fetches `window` 's capabilities bitfield.

#### Parameters

window | an XfwWindow. |

#### Returns

a bitfield with zero or more bits from XfwWindowCapabilities set.

### xfw_window_get_geometry ()

    GdkRectangle *
    xfw_window_get_geometry (XfwWindow *window);

Fetches `window` 's position and size.

#### Parameters

window | an XfwWindow. |

#### Returns

A GdkRectangle representing `window` 's geometry, which should not be modified or freed.

[not nullable][transfer none]

### xfw_window_get_screen ()

    XfwScreen *
    xfw_window_get_screen (XfwWindow *window);

Fetches the XfwScreen instance that owns `window` .

#### Parameters

window | an XfwWindow. |

#### Returns

A XfwScreen instance, with a reference owned by `window` .

[not nullable][transfer none]

### xfw_window_get_workspace ()

    XfwWorkspace *
    xfw_window_get_workspace (XfwWindow *window);

Fetches `window` 's workspace, if any. This may return `NULL` if `window` is not on a workspace, or is pinned to all workspaces.

#### Parameters

window | an XfwWindow. |

#### Returns

A XfwWorkspace instance, with a reference owned by `window` , or `NULL`.

[nullable][transfer none]

### xfw_window_get_monitors ()

    GList *
    xfw_window_get_monitors (XfwWindow *window);

Fetches the list of monitors `window` is displayed on, if any.

#### Parameters

window | an XfwWindow. |

#### Returns

A list of GdkMonitor instances, or `NULL`. The list and its contents are owned by `window` and should not be modified or freed.

[nullable][element-type GdkMonitor][transfer none]

### xfw_window_get_application ()

    XfwApplication *
    xfw_window_get_application (XfwWindow *window);

Fetches `window` 's application.

#### Parameters

window | an XfwWindow. |

#### Returns

An XfwApplication instance, with a reference owned by `window` .

[transfer none]

### xfw_window_activate ()

    gboolean
    xfw_window_activate (XfwWindow *window,
                         guint64 event_timestamp,
                         GError **error);

### xfw_window_close ()

    gboolean
    xfw_window_close (XfwWindow *window,
                      guint64 event_timestamp,
                      GError **error);

### xfw_window_start_move ()

    gboolean
    xfw_window_start_move (XfwWindow *window,
                           GError **error);

### xfw_window_start_resize ()

    gboolean
    xfw_window_start_resize (XfwWindow *window,
                             GError **error);

### xfw_window_set_geometry ()

    gboolean
    xfw_window_set_geometry (XfwWindow *window,
                             const GdkRectangle *rect,
                             GError **error);

### xfw_window_set_button_geometry ()

    gboolean
    xfw_window_set_button_geometry (XfwWindow *window,
                                    GdkWindow *relative_to,
                                    const GdkRectangle *rect,
                                    GError **error);

### xfw_window_move_to_workspace ()

    gboolean
    xfw_window_move_to_workspace (XfwWindow *window,
                                  XfwWorkspace *workspace,
                                  GError **error);

### xfw_window_set_minimized ()

    gboolean
    xfw_window_set_minimized (XfwWindow *window,
                              gboolean is_minimized,
                              GError **error);

### xfw_window_set_maximized ()

    gboolean
    xfw_window_set_maximized (XfwWindow *window,
                              gboolean is_maximized,
                              GError **error);

### xfw_window_set_fullscreen ()

    gboolean
    xfw_window_set_fullscreen (XfwWindow *window,
                               gboolean is_fullscreen,
                               GError **error);

### xfw_window_set_skip_pager ()

    gboolean
    xfw_window_set_skip_pager (XfwWindow *window,
                               gboolean is_skip_pager,
                               GError **error);

### xfw_window_set_skip_tasklist ()

    gboolean
    xfw_window_set_skip_tasklist (XfwWindow *window,
                                  gboolean is_skip_tasklist,
                                  GError **error);

### xfw_window_set_pinned ()

    gboolean
    xfw_window_set_pinned (XfwWindow *window,
                           gboolean is_pinned,
                           GError **error);

### xfw_window_set_shaded ()

    gboolean
    xfw_window_set_shaded (XfwWindow *window,
                           gboolean is_shaded,
                           GError **error);

### xfw_window_set_above ()

    gboolean
    xfw_window_set_above (XfwWindow *window,
                          gboolean is_above,
                          GError **error);

### xfw_window_set_below ()

    gboolean
    xfw_window_set_below (XfwWindow *window,
                          gboolean is_below,
                          GError **error);

### xfw_window_is_active ()

    gboolean
    xfw_window_is_active (XfwWindow *window);

### xfw_window_is_minimized ()

    gboolean
    xfw_window_is_minimized (XfwWindow *window);

### xfw_window_is_maximized ()

    gboolean
    xfw_window_is_maximized (XfwWindow *window);

### xfw_window_is_fullscreen ()

    gboolean
    xfw_window_is_fullscreen (XfwWindow *window);

### xfw_window_is_skip_pager ()

    gboolean
    xfw_window_is_skip_pager (XfwWindow *window);

### xfw_window_is_skip_tasklist ()

    gboolean
    xfw_window_is_skip_tasklist (XfwWindow *window);

### xfw_window_is_pinned ()

    gboolean
    xfw_window_is_pinned (XfwWindow *window);

### xfw_window_is_shaded ()

    gboolean
    xfw_window_is_shaded (XfwWindow *window);

### xfw_window_is_above ()

    gboolean
    xfw_window_is_above (XfwWindow *window);

### xfw_window_is_below ()

    gboolean
    xfw_window_is_below (XfwWindow *window);

### xfw_window_is_urgent ()

    gboolean
    xfw_window_is_urgent (XfwWindow *window);

### xfw_window_is_on_workspace ()

    gboolean
    xfw_window_is_on_workspace (XfwWindow *window,
                                XfwWorkspace *workspace);

### xfw_window_is_in_viewport ()

    gboolean
    xfw_window_is_in_viewport (XfwWindow *window,
                               XfwWorkspace *workspace);

## Types and Values

### XfwWindow

    typedef struct _XfwWindow XfwWindow;

### enum XfwWindowCapabilities

Flags bitfield that describes actions that can be taken on the window.

#### Members

XFW_WINDOW_CAPABILITIES_NONE | window has no capabilities. |
XFW_WINDOW_CAPABILITIES_CAN_MINIMIZE | window can be minimized/hidden. |
XFW_WINDOW_CAPABILITIES_CAN_UNMINIMIZE | window can be unminimized/unhidden. |
XFW_WINDOW_CAPABILITIES_CAN_MAXIMIZE | window can be maximized. |
XFW_WINDOW_CAPABILITIES_CAN_UNMAXIMIZE | window can be unmaximized/restored. |
XFW_WINDOW_CAPABILITIES_CAN_FULLSCREEN | window can be set fullscreen. |
XFW_WINDOW_CAPABILITIES_CAN_UNFULLSCREEN | window can be unset fullscreen. |
XFW_WINDOW_CAPABILITIES_CAN_SHADE | window can be shaded. |
XFW_WINDOW_CAPABILITIES_CAN_UNSHADE | window can be unshaded. |
XFW_WINDOW_CAPABILITIES_CAN_MOVE | window can be moved. |
XFW_WINDOW_CAPABILITIES_CAN_RESIZE | window can be resized. |
XFW_WINDOW_CAPABILITIES_CAN_PLACE_ABOVE | window can be placed above others. |
XFW_WINDOW_CAPABILITIES_CAN_UNPLACE_ABOVE | always above window can be returned to the normal stacking order. |
XFW_WINDOW_CAPABILITIES_CAN_PLACE_BELOW | window can be placed below others. |
XFW_WINDOW_CAPABILITIES_CAN_UNPLACE_BELOW | always below window can be returned to the normal stacking order. |
XFW_WINDOW_CAPABILITIES_CAN_CHANGE_WORKSPACE | window can be moved to a different workspace or can be pinned and unpinned. |

### enum XfwWindowState

A flags bitfield representing various states the window can hold.

#### Members

XFW_WINDOW_STATE_NONE | window has no state bits set. |
XFW_WINDOW_STATE_ACTIVE | window is active (and often has the keyboard focus). |
XFW_WINDOW_STATE_MINIMIZED | window is minimized/hidden. |
XFW_WINDOW_STATE_MAXIMIZED | window is maximized. |
XFW_WINDOW_STATE_FULLSCREEN | window is filling the entire screen. |
XFW_WINDOW_STATE_SKIP_PAGER | window should not be shown in pagers. |
XFW_WINDOW_STATE_SKIP_TASKLIST | window should not be shown in task lists. |
XFW_WINDOW_STATE_PINNED | window is shown on al workspaces. |
XFW_WINDOW_STATE_SHADED | window is hidden, except for its title bar. |
XFW_WINDOW_STATE_ABOVE | window is always shown above other windows. |
XFW_WINDOW_STATE_BELOW | window is always shown below other windows. |
XFW_WINDOW_STATE_URGENT | window is attempting to get the user's attention. |

### enum XfwWindowType

Enumeration describing the windows type or function.

#### Members

XFW_WINDOW_TYPE_NORMAL | window is a regular window. |
XFW_WINDOW_TYPE_DESKTOP | window is responsible for drawing the desktop. |
XFW_WINDOW_TYPE_DOCK | window is a dock or panel. |
XFW_WINDOW_TYPE_DIALOG | window is a temporary dialog, like an error alert. |
XFW_WINDOW_TYPE_TOOLBAR | window is a detached toolbar. |
XFW_WINDOW_TYPE_MENU | window is a popup menu. |
XFW_WINDOW_TYPE_UTILITY | window is a utility menu, like a tool picker or color palette. |
XFW_WINDOW_TYPE_SPLASHSCREEN | window is an application splash screen. |

## Property Details

### The `“application”` property

      “application”              XfwApplication *

The XfwApplication that owns this window.

Owner: XfwWindow

Flags: Read

### The `“capabilities”` property

      “capabilities”             XfwWindowCapabilities

The window's capabilities bitfield.

Owner: XfwWindow

Flags: Read

### The `“gicon”` property

      “gicon”                    GIcon *

The GIcon that represents this window.

Owner: XfwWindow

Flags: Read

### The `“id”` property

      “id”                       guint64

A windowing-platform dependent window ID.

Owner: XfwWindow

Flags: Read

Default value: 0

### The `“monitors”` property

      “monitors”                 gpointer

The list of monitors (if any) that the window is displayed on.

Owner: XfwWindow

Flags: Read

### The `“name”` property

      “name”                     char *

The window's name or title.

Owner: XfwWindow

Flags: Read

Default value: ""

### The `“screen”` property

      “screen”                   XfwScreen *

The XfwScreen instances that owns this window.

Owner: XfwWindow

Flags: Read / Write / Construct Only

### The `“state”` property

      “state”                    XfwWindowState

The window's state bitfield.

Owner: XfwWindow

Flags: Read

### The `“type”` property

      “type”                     XfwWindowType

The window's type or function.

Owner: XfwWindow

Flags: Read

Default value: XFW_WINDOW_TYPE_NORMAL

### The `“workspace”` property

      “workspace”                XfwWorkspace *

workspace.

Owner: XfwWindow

Flags: Read

## Signal Details

### The `“capabilities-changed”` signal

    void
    user_function (XfwWindow            *window,
                   XfwWindowCapabilities changed_mask,
                   XfwWindowCapabilities new_state,
                   gpointer              user_data)

Emitted when `window` 's capabilities change.

#### Parameters

window | the object which received the signal. |
changed_mask | bitfield representing which state bits have changed. |
new_state | the new state bitfield. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“closed”` signal

    void
    user_function (XfwWindow *window,
                   gpointer   user_data)

Emitted when `window` is closed.

#### Parameters

window | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“geometry-changed”` signal

    void
    user_function (XfwWindow *window,
                   gpointer   user_data)

Emitted when `window` 's position or size changes.

#### Parameters

window | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“icon-changed”` signal

    void
    user_function (XfwWindow *window,
                   gpointer   user_data)

Emitted when `window` 's icon changes.

#### Parameters

window | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“name-changed”` signal

    void
    user_function (XfwWindow *window,
                   gpointer   user_data)

Emitted when `window` 's name/title changes.

#### Parameters

window | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“state-changed”` signal

    void
    user_function (XfwWindow     *window,
                   XfwWindowState changed_mask,
                   XfwWindowState new_state,
                   gpointer       user_data)

Emitted when `window` 's state changes.

#### Parameters

window | the object which received the signal. |
changed_mask | bitfield representing which state bits have changed. |
new_state | the new state bitfield. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“type-changed”` signal

    void
    user_function (XfwWindow    *window,
                   XfwWindowType old_type,
                   gpointer      user_data)

Emitted when `window` 's type changes.

#### Parameters

window | the object which received the signal. |
old_type | the previous window type. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“workspace-changed”` signal

    void
    user_function (XfwWindow *window,
                   gpointer   user_data)

Emitted when `window` is moved to a different worksapce.

#### Parameters

window | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last