Xfdesktop

https://github.com/xfce-mirror/xfdesktop
Admin
Xfdesktop is a desktop manager for the Xfce Desktop Environment that handles background images, root...
Tokens:19,326
Snippets:135
Trust Score:8
Update:5 months ago
Show doc for...
Tokens:
Raw
### Build and Install Xfdesktop with All Features

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Clone the repository, set up the build with all optional features enabled using Meson, compile, and install the package. This is the recommended approach for a full-featured installation.

```sh
git clone https://gitlab.xfce.org/xfce/xfdesktop.git
cd xfdesktop
meson setup build \
  -Ddesktop-menu=enabled \
  -Ddesktop-icons=true \
  -Dfile-icons=file \
  -Dthunarx=enabled \
  -Dnotifications=enabled \
  -Dx11=enabled \
  -Dwayland=enabled \
  -Dvideo-backdrop=true \
  -Dfile-manager-fallback=Thunar \
  -Ddefault-backdrop-filename=backgrounds/xfce/xfce-x.svg
meson compile -C build
meson install -C build
```

--------------------------------

### Build xfdesktop from Source

Source: https://github.com/xfce-mirror/xfdesktop/blob/master/README.md

Instructions for building and installing xfdesktop from its source code using Meson.

```bash
% cd xfdesktop
% meson setup build
% meson compile -C build
% meson install -C build
```

--------------------------------

### Build xfdesktop from Release Tarball

Source: https://github.com/xfce-mirror/xfdesktop/blob/master/README.md

Instructions for building and installing xfdesktop from a release tarball using Meson.

```bash
tar xf xfdesktop-<version>.tar.xz
cd xfdesktop-<version>
meson setup build
meson compile -C build
meson install -C build
```

--------------------------------

### Start Xfdesktop Daemon

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Launch the Xfdesktop daemon. This command should typically be run once per session by the session manager.

```sh
xfdesktop
```

--------------------------------

### Build Xfdesktop with Minimal Features

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Configure the build with specific features disabled, such as Wayland, file icons, and video backdrops, using Meson options. This is useful for creating a lightweight installation.

```sh
meson setup build-minimal \
  -Dwayland=disabled \
  -Dfile-icons=false \
  -Dvideo-backdrop=false
meson compile -C build-minimal
```

--------------------------------

### Show Xfdesktop Version

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Display the version of the Xfdesktop application and exit. This is a standard command for checking the installed version.

```sh
xfdesktop --version
```

--------------------------------

### Enable Backdrop Cycling

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Activate the feature to automatically change the wallpaper at a set interval. This example enables cycling every 10 minutes in random order.

```sh
xfconf-query -c xfce4-desktop \
  -p /backdrop/screen0/monitoreDP-1/workspace0/backdrop-cycle-enable -s true
xfconf-query -c xfce4-desktop \
  -p /backdrop/screen0/monitoreDP-1/workspace0/backdrop-cycle-period \
  -s 2  # 0=Seconds, 1=Minutes, 2=Hours, 3=Startup, 4=Hourly, 5=Daily, 6=Chronological
xfconf-query -c xfce4-desktop \
  -p /backdrop/screen0/monitoreDP-1/workspace0/backdrop-cycle-timer \
  -s 10
xfconf-query -c xfce4-desktop \
  -p /backdrop/screen0/monitoreDP-1/workspace0/backdrop-cycle-random-order \
  -s true
```

--------------------------------

### XfdesktopIconPositionConfigs

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Manages the persistent storage of icon positions in a YAML file, supporting multi-monitor setups with per-monitor display name and icon identifier.

```APIDOC
## `XfdesktopIconPositionConfigs` — Persistent Icon Position Storage

Icon positions are stored in a YAML file and keyed by per-monitor display name and icon identifier. The configuration supports multi-monitor setups with per-level (primary/secondary/other) monitor assignment.

```c
#include "xfdesktop-icon-position-configs.h"

/* Position file lives at ~/.config/xfce4/desktop/icons.yaml */
GFile *pos_file = g_file_new_build_filename(
    g_get_user_config_dir(), "xfce4", "desktop", "icons.yaml", NULL);

XfdesktopIconPositionConfigs *configs =
    xfdesktop_icon_position_configs_new(pos_file);

GError *error = NULL;
if (!xfdesktop_icon_position_configs_load(configs, &error)) {
    g_warning("Failed to load icon positions: %s", error->message);
    g_clear_error(&error);
}

/* Look up the saved position for an icon by its identifier string */
XfwMonitor *found_monitor = NULL;
gint row = -1, col = -1;
if (xfdesktop_icon_position_configs_lookup(configs, "file:///home/user/Desktop/notes.txt",
                                           &found_monitor, &row, &col)) {
    g_print("Icon at row=%d col=%d on monitor %s\n",
            row, col, xfw_monitor_get_connector(found_monitor));
}

/* Register a monitor with a priority level and get/create its config */
GList *candidates = NULL;
XfdesktopIconPositionConfig *config =
    xfdesktop_icon_position_configs_add_monitor(
        configs, primary_monitor, XFDESKTOP_ICON_POSITION_LEVEL_PRIMARY, &candidates);
g_list_free(candidates);

/* Save an icon's new position after drag-and-drop */
xfdesktop_icon_position_configs_set_icon_position(
    configs, config,
    "file:///home/user/Desktop/notes.txt",
    2, 5,                              /* row, col */
    (guint64)g_get_real_time());       /* last_seen_timestamp */

/* Persist to disk */
if (!xfdesktop_icon_position_configs_save(configs, &error)) {
    g_warning("Failed to save icon positions: %s", error->message);
    g_clear_error(&error);
}

xfdesktop_icon_position_configs_free(configs);
g_object_unref(pos_file);
```
```

--------------------------------

### Pop up Applications Menu

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Display the right-click applications menu at the current mouse cursor position. This provides quick access to installed applications.

```sh
xfdesktop --menu            # or: xfdesktop -M
```

--------------------------------

### Disable Window Manager Check

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Start the Xfdesktop daemon without waiting for a window manager to be available. This can be useful in specific startup scenarios.

```sh
xfdesktop --disable-wm-check
```

--------------------------------

### C Function Declaration and Structure Example

Source: https://github.com/xfce-mirror/xfdesktop/blob/master/HACKING.md

Illustrates the preferred C coding style for function declarations, including return type, function name, parameters on separate lines, and brace placement. Also shows variable declarations at the top of the function and conditional logic.

```c
static void
example_foo_function(FooObject *cheese,
                     gboolean bar,
                     gint baz)
{
    gint i, j;
    BarObject *monkey = BAR_OBJECT(monkey);
    const gchar *happy_string;
    
    if (bar || baz == 0)
        do_something();
    else {
        really_long_function_call(cheese,
                                  "I like to eat cheese all the time",
                                  baz,
                                  monkey);
        do_something_else();
    }
    
    /* ... */
}
```

--------------------------------

### XfdesktopApplication Main Entry Point

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

The main function for the Xfdesktop application, initializing GTK, obtaining the singleton application instance, and handling application startup and IPC.

```c
#include "xfdesktop-application.h"

int main(int argc, char **argv) {
    XfdesktopApplication *app;
    int ret;

    gtk_init(&argc, &argv);

    /* Get or create the singleton application instance */
    app = xfdesktop_application_get();

    /* On X11, register the session-management option group */
    if (xfw_windowing_get() == XFW_WINDOWING_X11) {
        g_application_add_option_group(G_APPLICATION(app),
                                       xfce_sm_client_get_option_group(argc, argv));
    }

    /* Running the app will handle IPC if another instance is already running */
    ret = g_application_run(G_APPLICATION(app), argc, argv);
    g_object_unref(app);
    return ret;
}
```

--------------------------------

### Get Current Monitor Index

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Determines the index of the monitor currently under the mouse pointer. Requires an active GdkDisplay.

```c
/* Get the index of the monitor under the pointer */
gint current_mon = xfdesktop_get_current_monitor_num(display);
```

--------------------------------

### Load, Lookup, and Save Icon Positions with XfdesktopIconPositionConfigs

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Demonstrates loading icon positions from a YAML file, looking up specific icon positions, adding monitor configurations, setting icon positions, and saving changes. Ensure the configuration file path is correctly set.

```c
#include "xfdesktop-icon-position-configs.h"

/* Position file lives at ~/.config/xfce4/desktop/icons.yaml */
GFile *pos_file = g_file_new_build_filename(
    g_get_user_config_dir(), "xfce4", "desktop", "icons.yaml", NULL);

XfdesktopIconPositionConfigs *configs = 
    xfdesktop_icon_position_configs_new(pos_file);

GError *error = NULL;
if (!xfdesktop_icon_position_configs_load(configs, &error)) {
    g_warning("Failed to load icon positions: %s", error->message);
    g_clear_error(&error);
}

/* Look up the saved position for an icon by its identifier string */
XfwMonitor *found_monitor = NULL;
gint row = -1, col = -1;
if (xfdesktop_icon_position_configs_lookup(configs, "file:///home/user/Desktop/notes.txt",
                                           &found_monitor, &row, &col)) {
    g_print("Icon at row=%d col=%d on monitor %s\n",
            row, col, xfw_monitor_get_connector(found_monitor));
}

/* Register a monitor with a priority level and get/create its config */
GList *candidates = NULL;
XfdesktopIconPositionConfig *config = 
    xfdesktop_icon_position_configs_add_monitor(
        configs, primary_monitor, XFDESKTOP_ICON_POSITION_LEVEL_PRIMARY, &candidates);
g_list_free(candidates);

/* Save an icon's new position after drag-and-drop */
xfdesktop_icon_position_configs_set_icon_position(
    configs, config,
    "file:///home/user/Desktop/notes.txt",
    2, 5,                              /* row, col */
    (guint64)g_get_real_time());       /* last_seen_timestamp */

/* Persist to disk */
if (!xfdesktop_icon_position_configs_save(configs, &error)) {
    g_warning("Failed to save icon positions: %s", error->message);
    g_clear_error(&error);
}

xfdesktop_icon_position_configs_free(configs);
g_object_unref(pos_file);

```

--------------------------------

### XfceDesktop Initialization and Management

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Code for creating and managing an XfceDesktop window, which represents a single desktop surface. Includes backdrop and icon management, and monitor handling.

```c
#include "xfce-desktop.h"
#include "xfdesktop-backdrop-manager.h"

/* Create a desktop window for a specific monitor */
GdkScreen *screen = gdk_screen_get_default();
XfwScreen *xfw_screen = xfw_screen_get_default();
XfwMonitor *monitor = /* obtain from libxfce4windowing */;
XfconfChannel *channel = xfconf_channel_get("xfce4-desktop");
XfdesktopBackdropManager *manager =
    xfdesktop_backdrop_manager_new(xfw_screen, channel);

GtkWidget *desktop = xfce_desktop_new(screen, monitor, channel,
                                      "/backdrop/screen0/monitoreDP-1",
                                      manager);

/* Activate (show backdrop + icons) */
xfce_desktop_set_is_active(XFCE_DESKTOP(desktop), TRUE);

/* Force a refresh of backdrop and icons */
xfce_desktop_refresh(XFCE_DESKTOP(desktop));

/* Manually cycle to the next backdrop image */
xfce_desktop_cycle_backdrop(XFCE_DESKTOP(desktop));

/* Auto-arrange icons into the grid */
xfce_desktop_arrange_icons(XFCE_DESKTOP(desktop));

/* Query which monitor this desktop covers */
XfwMonitor *mon = xfce_desktop_get_monitor(XFCE_DESKTOP(desktop));

/* Handle monitor hotplug: swap desktop to a new XfwMonitor */
xfce_desktop_monitor_changed(XFCE_DESKTOP(desktop), new_monitor);
```

--------------------------------

### Get Monitor Index

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Obtains the numerical index of a GdkMonitor. This requires a default display and a specific monitor object.

```c
/* Get the monitor index for a GdkMonitor */
GdkDisplay *display = gdk_display_get_default();
GdkMonitor *monitor = gdk_display_get_monitor(display, 0);
gint mon_num = xfdesktop_get_monitor_num(display, monitor);
```

--------------------------------

### Configure Xfdesktop Icon Activation and Thumbnails

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Set whether to use single-click activation for icons and whether to display thumbnails for files. Also configure the visibility of hidden files.

```bash
xfconf-query -c xfce4-desktop -p /desktop-icons/single-click -s false
xfconf-query -c xfce4-desktop -p /desktop-icons/show-thumbnails -s true
xfconf-query -c xfce4-desktop -p /desktop-icons/show-hidden-files -s false
```

--------------------------------

### Initialize and Manage Keyboard Shortcuts in C

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Initializes shortcut storage, retrieves desktop and icon view actions, and saves user-modified shortcuts. Ensure to call shutdown at exit.

```c
#include "xfdesktop-keyboard-shortcuts.h"

/* Initialize shortcut storage (call once at startup) */
xfdesktop_keyboard_shortcuts_init();

/* Retrieve the desktop-level actions (reload, menu, window list, next bg) */
gsize n_desktop_actions;
XfceGtkActionEntry *desktop_actions =
    xfdesktop_get_desktop_actions(NULL, &n_desktop_actions);
/* Register with an XfceGtkActionManager or GtkAccelGroup */
xfce_gtk_accel_group_connect_action_entries(accel_group,
    desktop_actions, n_desktop_actions, G_OBJECT(desktop));
g_free(desktop_actions);

#ifdef ENABLE_DESKTOP_ICONS
/* Icon view navigation actions (activate, select-all, arrange, etc.) */
gsize n_icon_actions;
XfceGtkActionEntry *icon_actions =
    xfdesktop_get_icon_view_actions(NULL, &n_icon_actions);
g_free(icon_actions);

#ifdef ENABLE_FILE_ICONS
/* File manager actions (cut, copy, paste, rename, delete, properties, ...) */
gsize n_file_actions;
XfceGtkActionEntry *file_actions =
    xfdesktop_get_file_icon_manager_actions(NULL, &n_file_actions);
g_free(file_actions);
#endif
#endif

/* Persist any user-modified shortcuts to disk */
xfdesktop_keyboard_shortcuts_save();

/* Clean up at shutdown */
xfdesktop_keyboard_shortcuts_shutdown();

```

--------------------------------

### Configure Xfdesktop Wallpaper Settings

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Use these commands to set a single wallpaper across all workspaces or to configure workspace-specific wallpapers.

```bash
xfconf-query -c xfce4-desktop -p /backdrop/single-workspace-mode -s true
xfconf-query -c xfce4-desktop -p /backdrop/single-workspace-number -s 0
```

--------------------------------

### Get Human-Readable Monitor Name

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Retrieves a human-readable name for a monitor based on a GTK widget context. Ensure the monitor name is freed after use.

```c
#include "xfdesktop-common.h"

/* Get a human-readable monitor name from a widget context */
gchar *mon_name =
    xfdesktop_get_monitor_name_from_gtk_widget(GTK_WIDGET(desktop), 0);
g_print("Monitor name: %s\n", mon_name);
g_free(mon_name);
```

--------------------------------

### Manage Backdrop Images and Videos with XfdesktopBackdropMedia

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Use XfdesktopBackdropMedia to display images or videos as desktop backgrounds. For images, provide a cairo_surface_t. For videos, provide a URI and ensure GStreamer is available. Video playback requires explicit materialization and dematerialization.

```c
#include "xfdesktop-backdrop-media.h"

/* --- Image backdrop --- */
cairo_surface_t *surface = cairo_image_surface_create(
    CAIRO_FORMAT_ARGB32, 1920, 1080);
XfdesktopBackdropMedia *img_media =
    xfdesktop_backdrop_media_new_from_image(surface);
/* surface ownership transferred; do not destroy it manually */

g_assert(xfdesktop_backdrop_media_get_kind(img_media) ==
         XFDESKTOP_BACKDROP_MEDIA_KIND_IMAGE);

cairo_surface_t *retrieved =
    xfdesktop_backdrop_media_get_image_surface(img_media);
/* 'retrieved' is a borrowed reference */

/* Compare two media objects (e.g., to skip redundant repaints) */
gboolean same = xfdesktop_backdrop_media_equal(img_media, other_media);

g_object_unref(img_media);
```

```c
#ifdef ENABLE_VIDEO_BACKDROP
/* --- Video backdrop (requires GStreamer + gst-plugin-gtk) --- */
XfdesktopBackdropMedia *vid_media =
    xfdesktop_backdrop_media_new_from_video_uri(
        "file:///home/user/Videos/loop.mp4",
        XFCE_BACKDROP_IMAGE_ZOOMED);

gboolean gl_status = FALSE;
if (xfdesktop_backdrop_media_video_materialize(vid_media, TRUE, &gl_status)) {
    GtkWidget *video_widget =
        xfdesktop_backdrop_media_get_video_widget(vid_media);
    /* Embed video_widget into the desktop layer */

    GstElement *playbin =
        xfdesktop_backdrop_media_get_video_playbin(vid_media);
    gst_element_set_state(playbin, GST_STATE_PLAYING);
}

/* Tear down GStreamer resources without destroying the media object */
xfdesktop_backdrop_media_video_dematerialize(vid_media);
g_object_unref(vid_media);
#endif /* ENABLE_VIDEO_BACKDROP */
```

--------------------------------

### Get Workspace Number and Total

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Retrieves the current workspace number and the total number of workspaces. Requires a screen, workspace manager, and active workspace.

```c
/* Workspace number + total count lookup */
gint ws_num, ws_total;
XfwWorkspaceManager *wm = xfw_screen_get_workspace_manager(screen);
XfwWorkspace *ws = xfw_workspace_manager_get_active_workspace(wm);
xdesktop_workspace_get_number_and_total(wm, ws, &ws_num, &ws_total);
g_print("Workspace %d of %d\n", ws_num + 1, ws_total);
```

--------------------------------

### Create and Use XfdesktopBackdropManager

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Initializes the backdrop manager, requests image surfaces asynchronously, and notifies about monitor changes. Ensure to unreference objects when done.

```c
#include "xfdesktop-backdrop-manager.h"

XfwScreen *screen = xfw_screen_get_default();
XfconfChannel *channel = xfconf_channel_get("xfce4-desktop");

/* Create the manager */
XfdesktopBackdropManager *manager =
    xfdesktop_backdrop_manager_new(screen, channel);

/* Asynchronous surface request: callback receives a cairo_surface_t */
static void
on_image_surface_ready(XfdesktopBackdropMedia *bmedia,
                       GdkRectangle *surface_region,
                       GFile *image_file,
                       GError *error,
                       gpointer user_data)
{
    if (error != NULL) {
        g_warning("Backdrop error: %s", error->message);
        return;
    }
    cairo_surface_t *surface =
        xfdesktop_backdrop_media_get_image_surface(bmedia);
    /* Paint surface onto the desktop window */
}

GCancellable *cancel = g_cancellable_new();
xfdesktop_backdrop_manager_get_image_surface(manager,
                                             cancel,
                                             IMAGE_GET_CACHED,  /* or IMAGE_FORCE_RELOAD */
                                             monitor,
                                             workspace,
                                             on_image_surface_ready,
                                             NULL);

/* Check and trigger wallpaper cycling */
if (xfdesktop_backdrop_manager_can_cycle_backdrop(manager, monitor, workspace)) {
    xfdesktop_backdrop_manager_cycle_backdrop(manager, monitor, workspace);
}

/* Notify manager when monitor geometry changes */
xfdesktop_backdrop_manager_monitor_changed(manager, monitor);

g_object_unref(cancel);
g_object_unref(manager);
```

--------------------------------

### Manage Desktops and Icons with XfdesktopIconViewManager

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Illustrates using the abstract XfdesktopIconViewManager to interact with desktop environments, including querying screen information, listing managed desktops, handling desktop lifecycle events, sorting icons, and retrieving context menus. Concrete subclasses are managed internally.

```c
#include "xfdesktop-icon-view-manager.h"

/* Concrete subclasses are created internally; usage is via the base class API */
XfdesktopIconViewManager *manager = /* file or window icon manager instance */;

/* Query the associated XfwScreen */
XfwScreen *screen = 
    xfdesktop_icon_view_manager_get_screen(manager);

/* List all active XfceDesktop objects managed */
GList *desktops = 
    xfdesktop_icon_view_manager_get_desktops(manager);

/* Notify when a new desktop window is created for a new monitor */
xfdesktop_icon_view_manager_desktop_added(manager, new_xfce_desktop);

/* Remove a desktop when a monitor is disconnected */
xfdesktop_icon_view_manager_desktop_removed(manager, old_xfce_desktop);

/* Query which desktop currently has keyboard focus */
XfceDesktop *focused = 
    xfdesktop_icon_view_manager_get_focused_desktop(manager);

/* Sort icons on all desktops */
xfdesktop_icon_view_manager_sort_icons(
    manager,
    GTK_SORT_ASCENDING,
    XFDESKTOP_ICON_VIEW_MANAGER_SORT_ALL_DESKTOPS);

/* Trigger a full reload (re-read the ~/Desktop directory, etc.) */
xfdesktop_icon_view_manager_reload(manager);

/* Get the right-click context menu for a given desktop and pointer location */
GtkWidget *menu_parent = NULL;
GtkMenu *menu = 
    xfdesktop_icon_view_manager_get_context_menu(
        manager, focused, 320, 240, &menu_parent);
if (menu != NULL) {
    gtk_menu_popup_at_pointer(menu, NULL);
}

```

--------------------------------

### Configure Xfdesktop Icon Display Style

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Set the display style for desktop icons. Options include no icons, window icons, or file icons.

```bash
xfconf-query -c xfce4-desktop -p /desktop-icons/style -s 2
```

--------------------------------

### XfdesktopBackdropMedia - Image Backdrop

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Demonstrates how to create and manage an image backdrop using XfdesktopBackdropMedia.

```APIDOC
## `xfdesktop_backdrop_media_new_from_image`

### Description
Creates a new `XfdesktopBackdropMedia` object from a `cairo_surface_t`.

### Parameters
- **surface** (`cairo_surface_t*`) - The Cairo surface to use as the backdrop. Ownership is transferred to the function.

### Returns
- (`XfdesktopBackdropMedia*`) - A new backdrop media object.
```

```APIDOC
## `xfdesktop_backdrop_media_get_kind`

### Description
Gets the kind of the backdrop media.

### Parameters
- **media** (`XfdesktopBackdropMedia*`) - The backdrop media object.

### Returns
- (`XfdesktopBackdropMediaKind`) - The kind of the media (e.g., image or video).
```

```APIDOC
## `xfdesktop_backdrop_media_get_image_surface`

### Description
Retrieves the `cairo_surface_t` from an image backdrop media object.

### Parameters
- **media** (`XfdesktopBackdropMedia*`) - The image backdrop media object.

### Returns
- (`cairo_surface_t*`) - A borrowed reference to the Cairo surface. Do not free this reference.
```

```APIDOC
## `xfdesktop_backdrop_media_equal`

### Description
Compares two `XfdesktopBackdropMedia` objects for equality.

### Parameters
- **media1** (`XfdesktopBackdropMedia*`) - The first backdrop media object.
- **media2** (`XfdesktopBackdropMedia*`) - The second backdrop media object.

### Returns
- (`gboolean`) - `TRUE` if the media objects are equal, `FALSE` otherwise.
```

--------------------------------

### Create and Configure XfdesktopIconView Widget

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Instantiate XfdesktopIconView with a GtkTreeModel to display desktop icons. Configure icon size, font, text alignment, selection mode, and tooltips. Supports hit testing and finding free grid positions.

```c
#include "xfdesktop-icon-view.h"

XfconfChannel *channel = xfconf_channel_get("xfce4-desktop");
XfwScreen *screen = xfw_screen_get_default();
GtkTreeModel *model = /* XfdesktopFileIconModel or XfdesktopWindowIconModel */;

/* Construct the icon view with an existing model */
GtkWidget *icon_view =
    xfdesktop_icon_view_new_with_model(channel, screen, model);

/* Bind model columns */
xfdesktop_icon_view_set_pixbuf_column(
    XFDESKTOP_ICON_VIEW(icon_view), COL_PIXBUF);
xfdesktop_icon_view_set_text_column(XFDESKTOP_ICON_VIEW(icon_view), COL_LABEL);
xfdesktop_icon_view_set_tooltip_text_column(
    XFDESKTOP_ICON_VIEW(icon_view), COL_TOOLTIP);
xfdesktop_icon_view_set_row_column(XFDESKTOP_ICON_VIEW(icon_view), COL_ROW);
xfdesktop_icon_view_set_col_column(XFDESKTOP_ICON_VIEW(icon_view), COL_COL);

/* Appearance */
xfdesktop_icon_view_set_icon_size(XFDESKTOP_ICON_VIEW(icon_view), 48);
xfdesktop_icon_view_set_font_size(XFDESKTOP_ICON_VIEW(icon_view), 12.0);
xfdesktop_icon_view_set_use_font_size(XFDESKTOP_ICON_VIEW(icon_view), TRUE);
xfdesktop_icon_view_set_center_text(XFDESKTOP_ICON_VIEW(icon_view), TRUE);

/* Gravity: icons flow top-left by default */
xfdesktop_icon_view_set_gravity(
    XFDESKTOP_ICON_VIEW(icon_view),
    XFDESKTOP_ICON_VIEW_GRAVITY_BOTTOM | XFDESKTOP_ICON_VIEW_GRAVITY_RIGHT);

/* Behaviour */
xfdesktop_icon_view_set_single_click(XFDESKTOP_ICON_VIEW(icon_view), FALSE);
xfdesktop_icon_view_set_show_tooltips(XFDESKTOP_ICON_VIEW(icon_view), TRUE);
xfdesktop_icon_view_set_selection_mode(
    XFDESKTOP_ICON_VIEW(icon_view), GTK_SELECTION_MULTIPLE);

/* Selection queries */
GList *selected =
    xfdesktop_icon_view_get_selected_items(XFDESKTOP_ICON_VIEW(icon_view));
/* Each element is a GtkTreeIter* */
g_list_free(selected);

/* Hit testing: widget coords → tree iter */
GtkTreeIter iter;
if (xfdesktop_icon_view_widget_coords_to_item(
        XFDESKTOP_ICON_VIEW(icon_view), 320, 240, &iter)) {
    /* iter references the icon under the pointer */
}

/* Find the next free grid slot starting at (row=0, col=0) */
gint next_row, next_col;
xfdesktop_icon_view_get_next_free_grid_position(
    XFDESKTOP_ICON_VIEW(icon_view), 0, 0, &next_row, &next_col);

/* Sort icons alphabetically */
xfdesktop_icon_view_sort_icons(
    XFDESKTOP_ICON_VIEW(icon_view), GTK_SORT_ASCENDING);
```

--------------------------------

### XfdesktopBackdropMedia - Video Backdrop

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Demonstrates how to create and manage a video backdrop using XfdesktopBackdropMedia, requiring GStreamer.

```APIDOC
## `xfdesktop_backdrop_media_new_from_video_uri`

### Description
Creates a new `XfdesktopBackdropMedia` object from a video URI.

### Parameters
- **uri** (`const char*`) - The URI of the video file.
- **zoom_mode** (`XfceBackdropImageZoomed`) - The zoom mode for the video.

### Returns
- (`XfdesktopBackdropMedia*`) - A new backdrop media object.
```

```APIDOC
## `xfdesktop_backdrop_media_video_materialize`

### Description
Initializes the GStreamer pipeline for video playback.

### Parameters
- **media** (`XfdesktopBackdropMedia*`) - The video backdrop media object.
- **use_gl** (`gboolean`) - Whether to use OpenGL for rendering.
- **gl_status** (`gboolean*`) - Output parameter indicating if OpenGL was successfully used.

### Returns
- (`gboolean`) - `TRUE` if the video pipeline was successfully materialized, `FALSE` otherwise.
```

```APIDOC
## `xfdesktop_backdrop_media_get_video_widget`

### Description
Retrieves the `GtkWidget` used for displaying the video.

### Parameters
- **media** (`XfdesktopBackdropMedia*`) - The video backdrop media object.

### Returns
- (`GtkWidget*`) - The video widget.
```

```APIDOC
## `xfdesktop_backdrop_media_get_video_playbin`

### Description
Retrieves the GStreamer `GstElement` (playbin) used for video playback.

### Parameters
- **media** (`XfdesktopBackdropMedia*`) - The video backdrop media object.

### Returns
- (`GstElement*`) - The GStreamer playbin element.
```

```APIDOC
## `xfdesktop_backdrop_media_video_dematerialize`

### Description
Tears down GStreamer resources associated with the video backdrop without destroying the media object.

### Parameters
- **media** (`XfdesktopBackdropMedia*`) - The video backdrop media object.
```

--------------------------------

### XfdesktopApplication Singleton

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

The XfdesktopApplication is the main GApplication subclass that manages the Xfce desktop environment. It handles application startup, command-line arguments, and inter-process communication with other instances of the application.

```APIDOC
## XfdesktopApplication — Application Singleton

`XfdesktopApplication` is the top-level `GApplication` subclass. It owns all desktops and handles startup, command-line dispatch, and IPC with other instances.

```c
#include "xfdesktop-application.h"

int main(int argc, char **argv) {
    XfdesktopApplication *app;
    int ret;

    gtk_init(&argc, &argv);

    /* Get or create the singleton application instance */
    app = xfdesktop_application_get();

    /* On X11, register the session-management option group */
    if (xfw_windowing_get() == XFW_WINDOWING_X11) {
        g_application_add_option_group(G_APPLICATION(app),
                                       xfce_sm_client_get_option_group(argc, argv));
    }

    /* Running the app will handle IPC if another instance is already running */
    ret = g_application_run(G_APPLICATION(app), argc, argv);
    g_object_unref(app);
    return ret;
}
```
```

--------------------------------

### XfdesktopSpecialFileIcon Creation and Usage

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Details on creating and using XfdesktopSpecialFileIcon for built-in desktop icons like Home, Filesystem, and Trash.

```APIDOC
## XfdesktopSpecialFileIcon

### Description
A concrete `XfdesktopFileIcon` subclass representing the three built-in special desktop icons: Home folder, Filesystem root, and Trash.

### Methods
- `xfdesktop_special_file_icon_new(type, screen)`: Creates a new special file icon of the specified type.
- `xfdesktop_special_file_icon_file_for_type(type)`: Retrieves the `GFile` backing a special icon type.
- `xfdesktop_special_file_icon_get_icon_type(icon)`: Determines the type of a given special icon.

### Example Usage
```c
#include "xfdesktop-special-file-icon.h"

GdkScreen *screen = gdk_screen_get_default();

/* Create each special icon */
XfdesktopSpecialFileIcon *home_icon = 
    xfdesktop_special_file_icon_new(XFDESKTOP_SPECIAL_FILE_ICON_HOME, screen);
XfdesktopSpecialFileIcon *fs_icon = 
    xfdesktop_special_file_icon_new(XFDESKTOP_SPECIAL_FILE_ICON_FILESYSTEM, screen);
XfdesktopSpecialFileIcon *trash_icon = 
    xfdesktop_special_file_icon_new(XFDESKTOP_SPECIAL_FILE_ICON_TRASH, screen);

/* Query the GFile backing a special icon type */
GFile *home_file = 
    xfdesktop_special_file_icon_file_for_type(XFDESKTOP_SPECIAL_FILE_ICON_HOME);
gchar *home_path = g_file_get_path(home_file);
g_print("Home icon path: %s\n", home_path);  /* e.g. /home/user */
g_free(home_path);
g_object_unref(home_file);

/* Determine which type a given special icon is */
XfdesktopSpecialFileIconType type = 
    xfdesktop_special_file_icon_get_icon_type(trash_icon);
g_assert(type == XFDESKTOP_SPECIAL_FILE_ICON_TRASH);

g_object_unref(home_icon);
g_object_unref(fs_icon);
g_object_unref(trash_icon);
```
```

--------------------------------

### Specify X Display

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Run Xfdesktop and connect to a specific X display, identified by its display number. This is useful when managing multiple X sessions.

```sh
xfdesktop --display=:1
```

--------------------------------

### Set Wallpaper Image

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Configure the wallpaper image for a specific screen, monitor, and workspace using `xfconf-query`. Ensure the path to the image is correct.

```sh
xfconf-query -c xfce4-desktop \
  -p /backdrop/screen0/monitoreDP-1/workspace0/last-image \
  -s /usr/share/backgrounds/xfce/xfce-x.svg
```

--------------------------------

### Configure Xfdesktop Window List Menu

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Customize the window list menu, including its visibility, icon display, workspace name display, submenus, and options for adding/removing workspaces.

```bash
xfconf-query -c xfce4-desktop -p /windowlist-menu/show -s true
xfconf-query -c xfce4-desktop -p /windowlist-menu/show-icons -s true
xfconf-query -c xfce4-desktop -p /windowlist-menu/show-workspace-names -s true
xfconf-query -c xfce4-desktop -p /windowlist-menu/show-submenus -s false
xfconf-query -c xfce4-desktop -p /windowlist-menu/show-add-remove-workspaces -s true
```

--------------------------------

### Create and Manage Special Desktop Icons

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Use XfdesktopSpecialFileIcon to represent Home, Filesystem, and Trash icons. You can create these icons and query their underlying GFile or determine their type.

```c
#include "xfdesktop-special-file-icon.h"

GdkScreen *screen = gdk_screen_get_default();

/* Create each special icon */
XfdesktopSpecialFileIcon *home_icon =
    xfdesktop_special_file_icon_new(XFDESKTOP_SPECIAL_FILE_ICON_HOME, screen);
XfdesktopSpecialFileIcon *fs_icon =
    xfdesktop_special_file_icon_new(XFDESKTOP_SPECIAL_FILE_ICON_FILESYSTEM, screen);
XfdesktopSpecialFileIcon *trash_icon =
    xfdesktop_special_file_icon_new(XFDESKTOP_SPECIAL_FILE_ICON_TRASH, screen);

/* Query the GFile backing a special icon type */
GFile *home_file =
    xfdesktop_special_file_icon_file_for_type(XFDESKTOP_SPECIAL_FILE_ICON_HOME);
gchar *home_path = g_file_get_path(home_file);
g_print("Home icon path: %s\n", home_path);  /* e.g. /home/user */
g_free(home_path);
g_object_unref(home_file);

/* Determine which type a given special icon is */
XfdesktopSpecialFileIconType type =
    xfdesktop_special_file_icon_get_icon_type(trash_icon);
g_assert(type == XFDESKTOP_SPECIAL_FILE_ICON_TRASH);

g_object_unref(home_icon);
g_object_unref(fs_icon);
g_object_unref(trash_icon);
```

--------------------------------

### Enable Debug Logging

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Activate debug logging for the Xfdesktop daemon at runtime. This is helpful for diagnosing issues.

```sh
xfdesktop --enable-debug
```

--------------------------------

### XfdesktopFileIcon

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Provides access to GFileInfo, GIcon, opacity, hash/equality, and sort-key helpers for GIO-backed file icons.

```APIDOC
## `XfdesktopFileIcon` — File Icon Base Class

`XfdesktopFileIcon` is the abstract base for all GIO-backed file icons, providing access to `GFileInfo`, `GIcon`, opacity, hash/equality, and sort-key helpers used by the icon model.

```c
#include "xfdesktop-file-icon.h"

XfdesktopFileIcon *ficon = XFDESKTOP_FILE_ICON(some_regular_or_special_icon);

/* Access GIO metadata */
GFileInfo *info      = xfdesktop_file_icon_peek_file_info(ficon);
GFileInfo *fs_info   = xfdesktop_file_icon_peek_filesystem_info(ficon);
GFile     *gfile     = xfdesktop_file_icon_peek_file(ficon);

/* Update icon after an inotify/GFileMonitor event */
GFileInfo *new_info = g_file_query_info(gfile,
    "standard::*,access::*,thumbnail::*",
    G_FILE_QUERY_INFO_NONE, NULL, NULL);
xfdesktop_file_icon_update_file_info(ficon, new_info);
g_object_unref(new_info);

/* Capability checks */
gboolean can_rename = xfdesktop_file_icon_can_rename_file(ficon);
gboolean can_delete = xfdesktop_file_icon_can_delete_file(ficon);
gboolean is_hidden  = xfdesktop_file_icon_is_hidden_file(ficon);

/* Get the GIcon with emblem decorations (e.g. symbolic link arrow) */
GIcon *base_icon = xfdesktop_file_icon_get_gicon(ficon);
GIcon *emblemed  = xfdesktop_file_icon_add_emblems(ficon, base_icon);
/* emblemed is a new reference */
g_object_unref(emblemed);

/* Opacity (0.5 when file is cut to clipboard) */
gdouble opacity = xfdesktop_file_icon_get_opacity(ficon);

/* Sort key for consistent alphabetical ordering */
const gchar *sort_key = xfdesktop_file_icon_peek_sort_key(ficon);

/* Use as GHashTable key */
gpointer hash_key = xfdesktop_file_icon_get_hash_key(ficon);
xfdesktop_file_icon_free_hash_key(hash_key);

/* Force icon cache invalidation (e.g. after theme change) */
xfdesktop_file_icon_invalidate_icon(ficon);
```
```

--------------------------------

### XfdesktopIcon Operations

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Demonstrates common operations on XfdesktopIcon objects, such as setting position, retrieving properties, activation, and context menu population.

```APIDOC
## XfdesktopIcon

### Description
Abstract base class for all icon types. Tracks grid position, monitor assignment, and label/tooltip text, and dispatches activation and context-menu population.

### Methods
- `xfdesktop_icon_set_monitor(icon, xfw_monitor)`: Assigns an icon to a specific monitor.
- `xfdesktop_icon_set_position(icon, row, col)`: Sets the grid position (row and column) of the icon.
- `xfdesktop_icon_get_position(icon, &row, &col)`: Retrieves the grid position of the icon.
- `xfdesktop_icon_peek_label(icon)`: Returns the label text of the icon.
- `xfdesktop_icon_peek_tooltip(icon)`: Returns the tooltip text of the icon.
- `xfdesktop_icon_peek_identifier(icon)`: Returns the identifier of the icon.
- `xfdesktop_icon_activate(icon, parent_window)`: Activates (opens/launches) the icon.
- `xfdesktop_icon_populate_context_menu(icon, menu)`: Populates a context menu for the icon.
- `xfdesktop_icon_set_thumbnail_file(icon, thumb_file)`: Sets the thumbnail file for the icon.
- `xfdesktop_icon_delete_thumbnail(icon)`: Deletes the thumbnail for the icon.
- `xfdesktop_icon_pixbuf_changed(icon)`: Notifies the icon view that the pixbuf has changed.

### Example Usage
```c
#include "xfdesktop-icon.h"

XfdesktopIcon *icon = XFDESKTOP_ICON(some_file_icon);

/* Assign to a monitor */
xfdesktop_icon_set_monitor(icon, xfw_monitor);

/* Position in the grid */
xfdesktop_icon_set_position(icon, 2, 3);  /* row=2, col=3 */

gint16 row, col;
if (xfdesktop_icon_get_position(icon, &row, &col)) {
    g_print("Icon at row=%d col=%d\n", row, col);
}

/* Peek label and tooltip (borrowed strings, valid while icon alive) */
const gchar *label   = xfdesktop_icon_peek_label(icon);
const gchar *tooltip = xfdesktop_icon_peek_tooltip(icon);
const gchar *id      = xfdesktop_icon_peek_identifier(icon);

/* Activate (open/launch) the icon */
GtkWindow *parent_window = GTK_WINDOW(desktop_widget);
xfdesktop_icon_activate(icon, parent_window);

/* Populate a context menu for this icon */
GtkWidget *menu = gtk_menu_new();
xfdesktop_icon_populate_context_menu(icon, menu);
gtk_menu_popup_at_pointer(GTK_MENU(menu), NULL);

/* Thumbnail support */
GFile *thumb_file = g_file_new_for_path("/path/to/thumbnail.png");
xfdesktop_icon_set_thumbnail_file(icon, thumb_file);
xfdesktop_icon_delete_thumbnail(icon);
g_object_unref(thumb_file);

/* Signal: notify icon view that the pixbuf changed */
xfdesktop_icon_pixbuf_changed(icon);
```
```

--------------------------------

### Configure Xfdesktop Icon and Font Size

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Adjust the size of desktop icons and the font size used for their labels. Ensure custom font size is enabled before setting the font size.

```bash
xfconf-query -c xfce4-desktop -p /desktop-icons/icon-size -s 48
xfconf-query -c xfce4-desktop -p /desktop-icons/use-custom-font-size -s true
xfconf-query -c xfce4-desktop -p /desktop-icons/font-size -s 12.0
```

--------------------------------

### Reload Xfdesktop Settings

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Instruct the running Xfdesktop instance to reload all settings and redraw the desktop background. This is useful after making configuration changes.

```sh
xfdesktop --reload          # or: xfdesktop -R
```

--------------------------------

### XfdesktopVolumeIcon for Removable Media

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Information on creating and managing XfdesktopVolumeIcon for removable media like USB drives and optical discs.

```APIDOC
## XfdesktopVolumeIcon

### Description
A concrete `XfdesktopFileIcon` representing a removable volume (USB drive, optical disc, network share, etc.).

### Methods
- `xfdesktop_volume_icon_new_for_volume(volume, screen)`: Creates a new volume icon for a given `GVolume`.
- `xfdesktop_volume_icon_peek_volume(icon)`: Returns the underlying `GVolume` of the volume icon.
- `xfdesktop_volume_icon_mounted(icon, mount)`: Notifies the icon that the volume has been mounted.
- `xfdesktop_volume_icon_unmounted(icon)`: Notifies the icon that the volume has been unmounted.
- `xfdesktop_volume_icon_sort_key_for_volume(volume)`: Generates a sorting key for a given `GVolume`.

### Example Usage
```c
#include "xfdesktop-volume-icon.h"

/* Obtain a GVolume or GMount from GVolumeMonitor */
GVolumeMonitor *vm = g_volume_monitor_get();
GList *volumes = g_volume_monitor_get_volumes(vm);
if (volumes != NULL) {
    GVolume *volume = G_VOLUME(volumes->data);

    /* Create icon from a GVolume (not yet mounted) */
    XfdesktopVolumeIcon *icon = 
        xfdesktop_volume_icon_new_for_volume(volume, gdk_screen_get_default());

    /* Access the underlying GVolume */
    GVolume *v = xfdesktop_volume_icon_peek_volume(icon);
    gchar *name = g_volume_get_name(v);
    g_print("Volume: %s\n", name);
    g_free(name);

    /* When the volume gets mounted, update the icon */
    GMount *mount = g_volume_get_mount(v);
    if (mount != NULL) {
        xfdesktop_volume_icon_mounted(icon, mount);
        g_object_unref(mount);
    }

    /* Notify icon that volume was unmounted */
    xfdesktop_volume_icon_unmounted(icon);

    /* Sorting key helpers */
    gchar *sort_key = xfdesktop_volume_icon_sort_key_for_volume(volume);
    g_free(sort_key);

    g_object_unref(icon);
    g_list_free_full(volumes, g_object_unref);
}
g_object_unref(vm);
```
```

--------------------------------

### Auto-arrange Desktop Icons

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Organize all desktop icons into their predefined grid positions. This command helps maintain a tidy desktop.

```sh
xfdesktop --arrange         # or: xfdesktop -A
```

--------------------------------

### XfdesktopIconView - Creation and Model Binding

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Details on creating an XfdesktopIconView widget and binding it to a data model.

```APIDOC
## `xfdesktop_icon_view_new_with_model`

### Description
Constructs a new `XfdesktopIconView` widget with a specified data model.

### Parameters
- **channel** (`XfconfChannel*`) - The Xfconf channel to use.
- **screen** (`XfwScreen*`) - The screen object.
- **model** (`GtkTreeModel*`) - The `GtkTreeModel` to back the icon view.

### Returns
- (`GtkWidget*`) - A new `XfdesktopIconView` widget.
```

```APIDOC
## `xfdesktop_icon_view_set_pixbuf_column`

### Description
Sets the model column that contains the icon pixbufs.

### Parameters
- **icon_view** (`XfdesktopIconView*`) - The icon view widget.
- **column** (`gint`) - The column number in the model for pixbufs.
```

```APIDOC
## `xfdesktop_icon_view_set_text_column`

### Description
Sets the model column that contains the icon labels.

### Parameters
- **icon_view** (`XfdesktopIconView*`) - The icon view widget.
- **column** (`gint`) - The column number in the model for text labels.
```

```APIDOC
## `xfdesktop_icon_view_set_tooltip_text_column`

### Description
Sets the model column that contains the tooltip text.

### Parameters
- **icon_view** (`XfdesktopIconView*`) - The icon view widget.
- **column** (`gint`) - The column number in the model for tooltip text.
```

```APIDOC
## `xfdesktop_icon_view_set_row_column`

### Description
Sets the model column that specifies the icon's row in the grid.

### Parameters
- **icon_view** (`XfdesktopIconView*`) - The icon view widget.
- **column** (`gint`) - The column number in the model for the row.
```

```APIDOC
## `xfdesktop_icon_view_set_col_column`

### Description
Sets the model column that specifies the icon's column in the grid.

### Parameters
- **icon_view** (`XfdesktopIconView*`) - The icon view widget.
- **column** (`gint`) - The column number in the model for the column.
```

--------------------------------

### Configure Visibility of Special File Icons

Source: https://context7.com/xfce-mirror/xfdesktop/llms.txt

Control the visibility of special file icons on the desktop, such as Home, Trash, Filesystem, and Removable devices.

```bash
xfconf-query -c xfce4-desktop -p /desktop-icons/file-icons/show-home -s true
xfconf-query -c xfce4-desktop -p /desktop-icons/file-icons/show-trash -s true
xfconf-query -c xfce4-desktop -p /desktop-icons/file-icons/show-filesystem -s false
xfconf-query -c xfce4-desktop -p /desktop-icons/file-icons/show-removable -s true
```
Tokens:
Raw