### Using Custom Modules with require()

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/README.md

Load and use functions from external Lua modules. This example shows how to require a 'util' module from a 'helpers' directory and call its setup function.

```lua
-- In devilspie2.lua:
scripts_window_open = {
    "firefox.lua",
    "terminal.lua"
}

-- In firefox.lua:
local util = require("helpers/util")
util.setup_firefox()
```

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

### Conditional Window Rule Example

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/README.md

Apply rules to windows based on their properties, such as their name. This example maximizes a window named 'Firefox' and assigns it to workspace 2.

```lua
if get_window_name() == "Firefox" then
    maximise()
    set_window_workspace(2)
end
```

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

### Get and Print Window Name

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/types.md

Fetches the window's title or name. Prints the name if it's not empty, otherwise indicates that the window has no name.

```lua
local name = get_window_name()
if string.len(name) > 0 then
    debug_print("Title: " .. name)
else
    debug_print("Window has no name")
end
```

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

### Get or Set Window Position and Size

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Retrieves the current X, Y, width, and height of the window or sets a new geometry. Omit parameters to get the current geometry.

```lua
function xywh() -> (x: number, y: number, width: number, height: number)
```

```lua
function xywh(x: number, y: number, w: number, h: number) -> void
```

```lua
-- Get geometry
local x, y, w, h = xywh()

-- Set geometry
xywh(100, 100, 800, 600)
```

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

### Set Window Type Example

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/types.md

Demonstrates setting a window's type using either the short constant or the full EWMH string form. Use when you need to categorize or control specific window behaviors.

```lua
set_window_type("WINDOW_TYPE_UTILITY")
set_window_type("_NET_WM_WINDOW_TYPE_UTILITY")
```

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

### Get and Set Window Type

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/types.md

Shows how to retrieve the current window type and conditionally apply actions, such as centering dialog windows. Also demonstrates setting a window to a toolbar type.

```lua
local wtype = get_window_type()
if wtype == "WINDOW_TYPE_DIALOG" then
    center()
end

-- Set window as toolbar
set_window_type("_NET_WM_WINDOW_TYPE_TOOLBAR")
```

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

### Check for Nil Property or Monitor

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/types.md

This example demonstrates how to handle cases where a window property might not exist or a monitor index is out of range, both of which return `nil`. It checks the return value and prints appropriate messages.

```lua
local prop = get_window_property("_NET_WM_NAME")
if prop ~= nil then
    debug_print("Property: " .. prop)
end

local x, y, w, h = get_monitor_geometry(99)
if x == nil then
    debug_print("Monitor doesn't exist")
end
```

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

### Example Devilspie2 Configuration File

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/configuration.md

A sample `devilspie2.lua` configuration file demonstrating how to define scripts for various window events like open, focus, and close. This file is typically located in the Devilspie2 configuration directory.

```lua
-- Define which scripts run on which events
scripts_window_open = {
    "firefox.lua",
    "emacs.lua",
    "terminal.lua"
}

scripts_window_focus = "on_focus.lua"

scripts_window_close = "on_close.lua"

-- Remaining scripts run only on open events
-- (firefox.lua, emacs.lua, terminal.lua listed above)
```

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

### Adjust Window Position

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/types.md

This example demonstrates how to retrieve the current window's position and dimensions, then adjust its position by adding an offset. It's useful for relative window placement.

```lua
local x, y, w, h = xywh()
set_window_position(x + 50, y + 50)
```

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

### Implement Millisecond Sleep

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/types.md

This example shows how to pause script execution for a specified duration in milliseconds. It demonstrates a 100ms sleep and the maximum allowed 1000ms (1 second) sleep.

```lua
-- Wait 100ms
millisleep(100)

-- Maximum wait (1 second)
millisleep(1000)
```

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

### Get Window Name

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Retrieves the title or name of the current window. Returns an empty string if no window is set.

```lua
function get_window_name() -> string
```

```lua
local name = get_window_name()
if name == "Terminal" then
    set_window_position(100, 100)
end
```

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

### Get Window Class

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Retrieves the general window class identifier. This provides a broad classification of the window.

```lua
function get_window_class() -> string
-- Example:
local wclass = get_window_class()
```

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

### Handling Window Manager Incompatibilities

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/errors.md

Some window managers may not support all EWMH operations, leading to silent failures. This example demonstrates attempting an operation and checking the result, or printing a message if an operation fails.

```lua
-- Try operation, but don't assume success
set_window_above()  -- May not work on all WMs

-- Check results if possible:
if not get_window_is_maximized() then
    maximize()
    if not get_window_is_maximized() then
        debug_print("Window manager doesn't support maximize")
    end
end
```

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

### Lua: Handle At Least Four Parameters Expected Error

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/errors.md

Demonstrates functions that require a minimum of four parameters. Shows an example with insufficient parameters and the correct usage.

```lua
set_window_strut(10, 20)  -- Not enough, error!
-- Correct:
set_window_strut(10, 20, 30, 40)  -- All four required
```

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

### get_window_strut()

Source: https://github.com/dsalt/devilspie2/blob/master/README.md

Gets the reserved area at the borders of the desktop for docking areas. Returns a table of 12 integers or nil. Available from version 0.45.

```APIDOC
## get_window_strut()

### Description
Get the reserved area at the borders of the desktop for a docking area such as a taskbar or a panel.

Returns a table (12 integers as for `_NET_WM_WINDOW_STRUT_PARTIAL`) or `nil`. If `_NET_WM_WINDOW_STRUT` was read then defaults are used as for [`set_window_strut()`](#user-content-set-window-strut).

### Method
N/A (Scripting function)

### Endpoint
N/A

### Parameters
None

### Request Example
```lua
local strut_info = devilspie.get_window_strut()
if strut_info then
  print("Strut info:", strut_info)
end
```

### Response
* **(table | nil)** - A table containing 12 integers representing the strut values, or nil if not set.
```

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

### Get and Print Window Property

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/types.md

Fetches a window property by name and prints its type and value. Handles string and number types, returning nil if the property does not exist.

```lua
local prop = get_window_property("_NET_WM_NAME")
if prop then
    debug_print("Property type: " .. type(prop))
    if type(prop) == "string" then
        debug_print("Value: " .. prop)
    elseif type(prop) == "number" then
        debug_print("Value: " .. tostring(prop))
    end
end
```

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

### Get and Print Strut Values

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/types.md

Retrieves the screen area reserved for docking windows (strut) and prints the top and bottom reserved dimensions.

```lua
local strut = get_window_strut()
if strut then
    debug_print("Top strut: " .. strut[3])  -- Top reserved area
    debug_print("Bottom strut: " .. strut[4])  -- Bottom reserved area
end
```

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

### Lua: Handle N to M Parameters Expected Error

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/errors.md

Illustrates functions requiring a parameter count within a specific range. Shows an example with too few parameters and the correct usage.

```lua
set_window_strut(10)  -- At least 4 required, got 1, error!
-- Correct:
set_window_strut(0, 0, 30, 0)  -- Panel 30px from top
```

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

### Lua: Handle Four Parameters Expected Error

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/errors.md

Illustrates functions requiring exactly four parameters, such as setting window geometry. Shows an example with missing parameters and the correct usage.

```lua
set_window_geometry(100, 200, 800)  -- Missing height, error!
-- Correct:
set_window_geometry(100, 200, 800, 600)
```

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

### Get Workspaces by Name and ID

Source: https://github.com/dsalt/devilspie2/blob/master/README.md

Returns two tables listing currently known workspaces, one by name and one by ID. Available from version 0.46.

```lua
local by_name, by_id = get_workspaces()
by_name = {
  ["First space"] = 1,
  ["Second"] = 2,
  ["Third and final"] = 3
}
by_id = {
  "First space", "Second", "Third and final"
}
by_name["First space"] == 1
by_id[3] == "Third and final"
```

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

### Lua: Handle One Parameter Expected Error

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/errors.md

Illustrates functions requiring exactly one parameter. Shows examples of missing or too many parameters, and the correct usage.

```lua
set_window_opacity()  -- Missing parameter, error!
set_window_opacity(0.8, 0.9)  -- Too many parameters, error!
-- Correct:
set_window_opacity(0.8)
```

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

### Get Application Name

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Retrieves the application name associated with the current window. Useful for applying rules based on the application.

```lua
function get_application_name() -> string
```

```lua
if get_application_name() == "Firefox" then
    maximise()
end
```

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

### Get Screen Geometry

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Returns the total width and height of the screen. This function takes no parameters. Available from version 0.29.

```lua
local screen_w, screen_h = get_screen_geometry()
```

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

### Lua: Handle Three Parameters Expected Error

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/errors.md

Demonstrates functions expecting three parameters, including the optional monitor index introduced in version 0.46. Shows an example with insufficient parameters.

```lua
set_window_position(100, 200)  -- Missing monitor index
-- Correct (from 0.46):
set_window_position(100, 200, 1)  -- With optional monitor parameter
```

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

### Get Window Role

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Retrieves the WM_WINDOW_ROLE hint for the window. This can be used to differentiate windows that might otherwise appear similar.

```lua
function get_window_role() -> string
-- Example:
local role = get_window_role()
```

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

### xywh([int x, int y, int w, int h])

Source: https://github.com/dsalt/devilspie2/blob/master/README.md

Sets or gets the position and size of a window. With parameters, it sets x, y, width, and height. Without parameters, it returns the current position and size.

```APIDOC
## xywh([int x, int y, int w, int h])

### Description
With parameters, set the position and size of a window. When no parameters are passed, returns the position and size of a window.

### Method
N/A (Scripting function)

### Endpoint
N/A

### Parameters
* **x** (int) - Optional. The new x-coordinate for the window.
* **y** (int) - Optional. The new y-coordinate for the window.
* **w** (int) - Optional. The new width for the window.
* **h** (int) - Optional. The new height for the window.

### Request Example (Set Position and Size)
```lua
devilspie.xywh(50, 50, 800, 600)
```

### Request Example (Get Position and Size)
```lua
local geometry = devilspie.xywh()
print("Window geometry:", geometry.x, geometry.y, geometry.w, geometry.h)
```

### Response (Get Position and Size)
* **(table)** - A table containing the window's x, y, width (w), and height (h).
```

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

### Lua: Handle Two Parameters Expected Error

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/errors.md

Shows functions that require exactly two parameters. Examples include missing a parameter or providing too many, with the correct syntax provided.

```lua
set_window_position(100)  -- Missing Y coordinate, error!
set_window_position(100, 200, 300)  -- Too many, error!
-- Correct:
set_window_position(100, 200)
```

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

### Registering C Functions with Aliases in Lua

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/internal-architecture.md

This example demonstrates how to register a C function `c_my_function` in Lua and also create an alias for it named `my_function_alias` using `lua_register`.

```c
lua_register(lua, "my_function_alias", c_my_function);
```

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

### Get and Set Window Position

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/types.md

Retrieves the current X and Y coordinates of a window and demonstrates how to move the window by adding offsets to its current position. Use for relative window positioning.

```lua
local x, y = xy()
xy(x + 100, y + 100)  -- Move window 100px right and down
```

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

### Handling No Current Window Error

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/errors.md

When getter functions are called without a current window, they return default values. Setter functions do nothing. This example shows how to handle this by checking for a window name.

```lua
-- When called outside event handler:
debug_print(get_window_name())  -- Prints empty string

-- In event handler:
-- get_window_name() returns actual window name
```

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

### Get Debug FIFO Path

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/configuration.md

Prints the filename of the debug FIFO pipe and exits. This is useful for obtaining the FIFO path without starting the daemon.

```bash
devilspie2 --print-fifo
```

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

### Get Reserved Screen Area with get_window_strut

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Retrieves the currently reserved screen area (strut) for a window. Returns a table of 12 integers representing the strut values or nil if no strut is set.

```lua
function get_window_strut() -> table|nil
```

```lua
local strut = get_window_strut()
if strut then
    debug_print("Left: " .. strut[1] .. ", Top: " .. strut[3])
end
```

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

### Safely Get Window Property

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/errors.md

Retrieves a window property, returning nil if the property does not exist. This is the safe way to access properties, as older versions might have returned an empty string.

```lua
local prop = get_window_property("_NET_WM_NAME")
if prop ~= nil then
    debug_print("Property value: " .. prop)
else
    debug_print("Property doesn't exist")
end
```

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

### Monitor Live Daemon Debug FIFO

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/configuration.md

Connect to a running Devilspie2 daemon's debug FIFO to view live output. Start the daemon with --debug-fifo and then use 'cat' to read from its FIFO.

```bash
devilspie2 --debug-fifo &
# In another terminal:
cat "$(devilspie2 -P)"
```

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

### Get or Set Window Position

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Retrieves the current X and Y coordinates of the window or sets a new position. Omit parameters to get the current position.

```lua
function xy() -> (x: number, y: number)
```

```lua
function xy(x: number, y: number) -> void
```

```lua
-- Get position
local x, y = xy()

-- Set position
xy(100, 200)
```

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

### Error Handling for Window Geometry

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/README.md

Safely retrieve and manipulate window geometry, checking for valid coordinates before applying changes. This example adds 100 pixels to the x-coordinate if successful, otherwise prints an error.

```lua
local x, y = xy()
if x and y then
    xy(x + 100, y)
else
    debug_print("Could not get position")
end
```

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

### Handling Operation Failure in Devilspie2

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/errors.md

Demonstrates a scenario where a window operation might fail, for example, if the window is closed between calls. Consider using error trapping mechanisms for robustness.

```lua
local x, y, w, h = get_window_geometry()
-- Between here and there, the window closes...
set_window_position(x + 100, y + 100)  -- May fail if window is gone
```

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

### Initialize New Translation File

Source: https://github.com/dsalt/devilspie2/blob/master/README.translators.md

Creates a new .po file for a specific locale based on the template.

```sh
msginit -i devilspie2.pot -l LOCALE
```

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

### Get X11 Window Property

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Retrieves the value of a specified X11 window property. Handles string, number, or nil return types. Returns nil for non-existent properties from version 0.45.

```lua
function get_window_property(property: string) -> value (string|number|nil)
-- Example:
local prop = get_window_property("_NET_WM_NAME")
if prop then
    debug_print("Property: " .. prop)
end
```

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

### Get Process Owner

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Retrieves the username of the owner of the process associated with the current window.

```lua
function get_process_owner() -> string
```

```lua
if get_process_owner() == "root" then
    debug_print("Root-owned window detected")
end
```

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

### Get Monitor Geometry

Source: https://github.com/dsalt/devilspie2/blob/master/README.md

Returns the x, y, width, and height for a given monitor index, or the window's monitor if no index is provided. Returns nothing if the index is out of range. Available from version 0.44.

```lua
get_monitor_geometry([int index])
```

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

### Get Window Geometry Information

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/types.md

Retrieves various geometry details for a window, including its absolute position with decorations, client area dimensions without decorations, and monitor bounding box. Useful for precise window placement and sizing.

```lua
local x, y, width, height = get_window_geometry()
local client_x, client_y, client_w, client_h = get_window_client_geometry()
local mon_x, mon_y, mon_w, mon_h = get_monitor_geometry()
```

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

### Initialize and Run GLib Main Loop

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/internal-architecture.md

Initializes and runs the GLib main loop, which is responsible for processing events such as window events, file monitor changes, and signal handlers.

```c
GMainLoop *loop = NULL;

int main(int argc, char *argv[]) {
    // ... initialization ...
    
    loop = g_main_loop_new(NULL, TRUE);
    g_main_loop_run(loop);
    
    return EXIT_SUCCESS;
}
```

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

### No Script Files Found Error Message

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/configuration.md

Displays the error message shown when Devilspie2 starts but cannot find any Lua script files in the configured script folder. This indicates that no scripts are available to execute.

```text
No script files found in the script folder - exiting.
```

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

### Show Help Information

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/configuration.md

Displays help information about Devilspie2 command-line options and then exits.

```bash
devilspie2 --help
```

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

### Get Window Geometry

Source: https://github.com/dsalt/devilspie2/blob/master/README.md

Retrieves the window's position and dimensions. Useful for positioning or resizing windows.

```lua
x, y, width, height = get_window_geometry();
print("X: "..x..", Y: "..y..", width: "..width..", height: "..height);
```

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

### Interact with Named Workspaces

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/types.md

Demonstrates checking the current workspace by name and printing a message if it matches 'Web'. Also shows how to move a window to a workspace identified by its string name.

```lua
local idx, name = get_window_workspace()
if name == "Web" then
    debug_print("In Web workspace")
end
```

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

### Adjust for Decoration

Source: https://github.com/dsalt/devilspie2/blob/master/README.md

Enables or disables adjustment for window decorations when moving or resizing. Should be used at the start of a script.

```lua
set_adjust_for_decoration(true)
```

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

### Load Configuration File

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/internal-architecture.md

Loads the main configuration file, initializes a temporary Lua state, executes devilspie2.lua, and extracts configuration variables.

```c
int load_config(gchar *filename)
```

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

### Get Total Workspace Count

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Returns the total number of available workspaces. This function is available from version 0.27.

```lua
local count = get_workspace_count()
if count > 1 then
    set_window_workspace(2)
end
```

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

### Get Window XID

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Retrieves the unique 32-bit X11 window ID (XID). This is a low-level identifier for the window.

```lua
function get_window_xid() -> number
-- Example:
local xid = get_window_xid()
debug_print("Window XID: " .. xid)
```

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

### Get Process Name

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Retrieves the name of the process that owns the current window. Note: Not compatible with busybox `ps`.

```lua
function get_process_name() -> string
```

```lua
local proc = get_process_name()
if proc == "bash" then
    -- apply rules to bash shells
end
```

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

### Get Current Window Workspace

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Retrieves the index and name of the workspace the current window is on. This function is available from version 0.46.

```lua
local idx, name = get_window_workspace()
debug_print("Window is on workspace " .. idx .. ": " .. name)
```

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

### focus()

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Focuses and activates the current window. This function takes no parameters and returns void.

```APIDOC
## focus()

### Description
Focuses/activates the current window.

### Method
N/A (Lua function)

### Parameters
Takes no parameters.

### Return Type
void (no return value)

### Example
```lua
focus()
```
```

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

### pin_window()

Source: https://github.com/dsalt/devilspie2/blob/master/README.md

Requests the window manager to place the window on all workspaces.

```APIDOC
## pin_window()

### Description
Ask the window manager to put the window on all workspaces.

### Method
N/A (Scripting function)

### Endpoint
N/A (Scripting function)
```

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

### Test Scripts with Emulation

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/configuration.md

Use emulation mode with the --emulate flag to test your scripts without affecting actual windows. Combine with --debug for detailed output.

```bash
devilspie2 --emulate --debug
```

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

### Get Active Workspace Information

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Returns the index and name of the currently active workspace. The index is 1-based. This function is available from version 0.46.

```lua
local idx, name = get_active_workspace()
debug_print("Active workspace: " .. idx .. " (" .. name .. ")")
```

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

### Set Window Size

Source: https://github.com/dsalt/devilspie2/blob/master/README.md

Sets the width and height of a window.

```lua
set_window_size(800, 600)
```

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

### Pin Window to All Workspaces

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Use this function to make a window visible on all workspaces. It takes no parameters and returns no value.

```lua
pin_window()
```

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

### Safely Get Window Geometry

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/errors.md

Checks if window geometry could be retrieved before accessing it. Returns nil if no window is set or if the window was closed.

```lua
local x, y, w, h = get_window_geometry()
if x and y then
    debug_print("Position: " .. x .. ", " .. y)
else
    debug_print("Could not get window geometry")
end
```

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

### Compare Application and Process Names

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/types.md

Retrieves both the application name (e.g., 'Firefox') and the process name (e.g., 'firefox-bin') and performs a conditional action based on the application name.

```lua
local app = get_application_name()
local proc = get_process_name()

if app == "Firefox" then
    debug_print("Running as: " .. proc)
end
```

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

### Get Window Property and UTF8 Status

Source: https://github.com/dsalt/devilspie2/blob/master/README.md

Retrieves a window property and its UTF8 status. Returns nil if the property does not exist. Available from version 0.45.

```lua
get_window_property(property), window_property_is_utf8(property)
```

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

### Safely Get Monitor Geometry

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/errors.md

Retrieves the geometry of a specific monitor by its index. Returns nil values if the monitor index is out of range or if the window is not on any monitor.

```lua
local x, y, w, h = get_monitor_geometry(5)
if x then
    debug_print("Monitor geometry: " .. x .. ", " .. y .. ", " .. w .. ", " .. h)
else
    debug_print("Monitor 5 does not exist")
end
```

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

### Global Configuration Variables

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/internal-architecture.md

Defines essential global variables for application configuration, including the configuration filename, a file monitor for the script directory, the libwnck screen handle, and the GLib main loop.

```c
gchar *config_filename = NULL;
GFileMonitor *mon = NULL;
WnckHandle *my_wnck_handle = NULL;
GMainLoop *loop = NULL;
```

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

### Implement Simple Getter Function in C for Lua

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/internal-architecture.md

Demonstrates a common pattern for implementing simple getter functions in C that can be called from Lua. It includes parameter validation, retrieving data, and pushing the result onto the Lua stack.

```c
int c_get_window_name(lua_State *lua)
{
    if (!check_param_count(lua, "get_window_name", 0)) {
        return 0;
    }

    WnckWindow *window = get_current_window();
    const char *test = window ? wnck_window_get_name(window) : "";
    
    lua_pushstring(lua, test);
    return 1;  // Return 1 value
}
```

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

### Get WM_CLASS Instance Name

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Retrieves the instance name from the WM_CLASS property. Requires libwnck 3+. Useful for targeting specific applications by their instance name.

```lua
function get_class_instance_name() -> string
-- Example:
local instance = get_class_instance_name()
if instance == "emacs" then
    maximise()
end
```

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

### Get Window Type

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Retrieves the EWMH window type. Use this to conditionally apply rules based on the window's type, like dialogs or toolbars.

```lua
function get_window_type() -> string
-- Example:
local wtype = get_window_type()
if wtype == "WINDOW_TYPE_DIALOG" then
    center()
end
```

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

### decorate_window

Source: https://github.com/dsalt/devilspie2/blob/master/README.md

Enables window decorations.

```APIDOC
## decorate_window()

### Description
Enable window decorations.
```

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

### xy([x, y])

Source: https://github.com/dsalt/devilspie2/blob/master/README.md

Sets or gets the position of a window. If parameters are provided, it sets the window's x and y coordinates. Without parameters, it returns the current position.

```APIDOC
## xy([x, y])

### Description
With parameters, set the position of a window. Without, returns the position of a window.

### Method
N/A (Scripting function)

### Endpoint
N/A

### Parameters
* **x** (int) - Optional. The new x-coordinate for the window.
* **y** (int) - Optional. The new y-coordinate for the window.

### Request Example (Set Position)
```lua
devilspie.xy(100, 200)
```

### Request Example (Get Position)
```lua
local pos = devilspie.xy()
print("Window position:", pos.x, pos.y)
```

### Response (Get Position)
* **(table)** - A table containing the window's x and y coordinates.
```

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

### Set Window Geometry (Alternative)

Source: https://github.com/dsalt/devilspie2/blob/master/README.md

Sets window geometry using XMoveResizeWindow, potentially yielding different coordinates than the default method.

```lua
set_window_geometry2(0, 0, 800, 600)
```

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

### Create devilspie2.pot

Source: https://github.com/dsalt/devilspie2/blob/master/README.translators.md

Generates the template file for translations if it does not exist.

```sh
cd po
make update-pot
```

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

### Get WM_CLASS Group Name

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Retrieves the group name from the WM_CLASS property. Requires libwnck 3+. Useful for targeting applications that share a common group name.

```lua
function get_class_group_name() -> string
-- Example:
local group = get_class_group_name()
debug_print("Class group: " .. group)
```

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

### Get Window Client Geometry

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Retrieves the position (x, y) and dimensions (width, height) of the window's content area, excluding decorations. Available from version 0.16.

```lua
function get_window_client_geometry() -> (x: number, y: number, width: number, height: number)
```

```lua
local x, y, w, h = get_window_client_geometry()
```

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

### Get Monitor Geometry by Index

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/types.md

Retrieves the geometry of a specific monitor using its 0-based index. Handles cases for the current monitor, all monitors as one, and individual monitors.

```lua
local current_monitor = get_monitor_index()
local next_monitor = current_monitor + 1

local x, y, w, h = get_monitor_geometry(next_monitor)
if x and y then  -- Monitor exists
    center(next_monitor)
end
```

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

### Monitor Directory Changes

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/internal-architecture.md

Sets up a file monitor to detect changes within a directory. Connects a callback function to the 'changed' signal for handling modifications.

```c
GFileMonitor *mon = g_file_monitor_directory(directory_file, G_FILE_MONITOR_NONE, NULL, NULL);
g_signal_connect(mon, "changed", G_CALLBACK(folder_changed_callback), ...);
```

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

### Decorate Window

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Shows all window decorations, including the title bar and borders. This function takes no parameters.

```lua
function decorate_window() -> void
```

```lua
decorate_window()
```

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

### decorate_window()

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Shows all window decoration (title bar and borders). This function takes no parameters and returns no value.

```APIDOC
## decorate_window()

### Description
Shows all window decoration (title bar and borders).

### Method
Lua function call

### Parameters
This function takes no parameters.

### Return Type
void (no return value)

### Example
```lua
decorate_window()
```
```

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

### Get Window Property and UTF-8 Status

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Retrieves a window property's value and indicates if it's UTF-8 encoded. Use when you need to know both the content and encoding of a property.

```lua
function get_window_property_full(property: string) -> (value, is_utf8: boolean)|nil

local value, is_utf8 = get_window_property_full("_NET_WM_NAME")
if value and is_utf8 then
    debug_print("UTF-8 name: " .. value)
end
```

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

### Manage Current Window Handle

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/internal-architecture.md

Global variables and functions to manage the currently active WnckWindow. Assumes the window remains valid during event processing.

```c
WnckWindow *current_window = NULL;

void set_current_window(WnckWindow *window) {
    current_window = window;
}

WnckWindow *get_current_window() {
    return current_window;
}
```

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

### Set Window Opacity

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/types.md

Use this snippet to control the transparency of a window. It shows how to set opacity to 80% (0.8) and 50% (0.5).

```lua
-- 80% opacity
set_window_opacity(0.8)

-- Semi-transparent
set_window_opacity(0.5)
```

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

### Project Structure Overview

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/internal-architecture.md

Provides a high-level view of the devilspie2 project directory structure, highlighting key source files and their purposes.

```text
devilspie2/
├── src/
│   ├── devilspie2.c           # Main entry point, event loop
│   ├── script.c               # Lua state initialization, function registration
│   ├── script.h
│   ├── script_functions.c     # Lua function implementations
│   ├── script_functions.h
│   ├── config.c               # Script loading and configuration
│   ├── config.h
│   ├── logger.c               # Debug logging and FIFO output
│   ├── logger.h
│   ├── xutils.c               # X11 utilities
│   ├── xutils.h
│   ├── error_strings.c        # Error message initialization
│   ├── error_strings.h
│   ├── compat.h               # Compatibility macros
│   └── intl.h                 # Internationalization
└── ...
```

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

### Set Window Geometry (Alternative)

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Sets window geometry using XMoveResizeWindow, an alternative to the default set_window_geometry. Available from version 0.21.

```lua
function set_window_geometry2(x: number, y: number, width: number, height: number, [index: number]) -> void
```

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

### Get Workspace Lists by Name and ID

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Retrieves two tables: one mapping workspace names to IDs and another mapping IDs to names. This function is available from version 0.46.

```lua
local by_name, by_id = get_workspaces()
local id = by_name["Workspace 1"]
if id then
    set_window_workspace(id)
end
```

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

### Debug Window Info and Resize/Maximize

Source: https://github.com/dsalt/devilspie2/blob/master/README.md

Prints window and application names for debugging. Resizes and repositions specific windows based on their initial title. Maximizes Firefox windows.

```lua
-- the debug_print command only prints to stdout
-- if devilspie2 is run using the '--debug' option
debug_print("Window name: " .. get_window_name());
debug_print("Application name: " .. get_application_name())

-- I want my Xfce4 terminal to the right on the second screen (1080p) of my
-- two-monitor setup.
-- Note that this rule will only work with the window's initial title.
if (get_window_name() == "Terminal") then
   set_window_position(1300, 200, 2)
   set_window_size(600, 800)
end

-- Make Firefox always start maximised.
if (get_application_name() == "Firefox") then
   maximise() -- maximize() for compatibility with <0.45
end
```

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

### Get and Use Workspace Tables

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/types.md

Retrieves tables mapping workspace names to indices and vice versa. This is useful for programmatically finding a workspace's ID or name to move or switch to it.

```lua
local by_name, by_id = get_workspaces()

-- by_name["First space"] == 1
-- by_id[1] == "First space"

local workspace_id = by_name["Web"]
if workspace_id then
    set_window_workspace(workspace_id)
end
```

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

### Show Devilspie2 Version

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/configuration.md

Prints the current Devilspie2 version number and exits.

```bash
devilspie2 --version
```

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

### set_adjust_for_decoration

Source: https://github.com/dsalt/devilspie2/blob/master/README.md

Allows for adjustments when window decorations are taken into account during positioning or resizing operations. This setting is off by default and sticky. It should be used at the start of a script and affects geometry, position, and size functions.

```APIDOC
## set_adjust_for_decoration([bool])

### Description
Allows for situations where moving or resizing the window is done incorrectly, i.e. `set_window_position(0,0)` results in the window decoration being taken into account twice. This is currently off by default and is sticky. If used, it should be used at the start of the script.

This affects the following functions:
* `set_window_geometry`
* `set_window_position`
* `set_window_size`
* `xy`
* `xywh`

*(Available from version 0.45)*
```

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

### set_window_geometry2(x, y, width, height, [index])

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Sets the window geometry using XMoveResizeWindow, offering an alternative to set_window_geometry. It takes position and size parameters, with an optional monitor index.

```APIDOC
## set_window_geometry2(x, y, width, height, [index])

### Description
Sets window geometry using `XMoveResizeWindow` instead of `wnck_window_set_geometry`. It accepts position, size, and an optional monitor index.

### Parameters
#### Path Parameters
- **x** (number) - Required - X coordinate of the window.
- **y** (number) - Required - Y coordinate of the window.
- **width** (number) - Required - Width of the window in pixels.
- **height** (number) - Required - Height of the window in pixels.
- **index** (number) - Optional - Monitor index. Available from 0.46.

### Return type
void (no return value)

### Notes
Available from version 0.21. `index` parameter from 0.46.
```

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

### set_window_size

Source: https://github.com/dsalt/devilspie2/blob/master/README.md

Sets the width and height of a window.

```APIDOC
## set_window_size(int width, int height)

### Description
Set the size of a window.
```

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

### Decorate Window

Source: https://github.com/dsalt/devilspie2/blob/master/README.md

Enables window decorations. This function is a placeholder and its exact behavior might depend on the window manager.

```lua
decorate_window()
```

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

### Configure scripts_window_open Variable

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/configuration.md

Defines which Lua scripts to run when a window opens. Can be a single script, a list of scripts, or an empty value to enable `require()` without running default open scripts.

```lua
scripts_window_open = "file1.lua"
-- or
scripts_window_open = {
    "file1.lua",
    "file2.lua"
}
-- or (to enable require() but disable default open events)
scripts_window_open = {}
scripts_window_open = ""
```

```lua
-- Only run specific scripts on window open
scripts_window_open = {
    "firefox.lua",
    "terminal.lua"
}

-- Load modules with require() without running open scripts
scripts_window_open = {}
```

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

### Event Lists and Types

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/internal-architecture.md

Initializes arrays to store lists of scripts for different window event types and defines an enum for these event types. Each `GSList` holds filenames of Lua scripts to be executed.

```c
GSList *event_lists[W_NUM_EVENTS] = { NULL, NULL, NULL, NULL, NULL };
const char *const event_names[W_NUM_EVENTS] = {
    "window_open",
    "window_close",
    "window_focus",
    "window_blur",
    "window_name_change",
};

typedef enum {
    W_OPEN = 0,
    W_CLOSE = 1,
    W_FOCUS = 2,
    W_BLUR = 3,
    W_NAME_CHANGED = 4,
    W_NUM_EVENTS = 5
} win_event_type;
```

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

### centre([int index = -1,] [string direction = nil])

Source: https://github.com/dsalt/devilspie2/blob/master/README.md

Centers the window on a monitor or across all monitors with options for horizontal/vertical centering. Available from version 0.40 (with parameters) and 0.26 (without parameters, as `center`).

```APIDOC
## centre([int index = -1,] [string direction = nil])

### Description
Centre the window on one monitor or across all monitors, according to the
following rules:

* If `index` = `-1`, all monitors are treated as one large virtual monitor.
* If `index` = `0`, the ‘current’ monitor (with the window's centre point)
  is used (falling back on then the first monitor showing part of the
  window then the first monitor);
* If `index` is out of range then the first monitor is used.
* Otherwise, the window is centred on the specified monitor.

* If `direction` begins with `H` or `h`, the window is horizontally
  centred only.
* If `direction` begins with `V` or `v`, the window is vertically
  centred only.
* Otherwise it is centred along both axes.

If centring only along one axis, the window may be moved along the other
axis to ensure that it is on the specified monitor.

*(Available from version 0.40; as `center` and without parameters from 0.26)*

### Method
N/A (Scripting function)

### Endpoint
N/A (Scripting function)
```

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

### Lua: Handle No Parameters Expected Error

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/errors.md

Demonstrates calling a function with no parameters when it expects none. Incorrect usage results in an error.

```lua
get_window_name("unexpected_parameter")  -- Error!
-- Should be:
get_window_name()
```

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

### set_window_opacity(float value)

Source: https://github.com/dsalt/devilspie2/blob/master/README.md

Sets the window opacity to a fractional value between 0.0 (transparent) and 1.0 (opaque). Available from version 0.29 (as `set_window_opacity`) and 0.28 (as `set_opacity`).

```APIDOC
## set_window_opacity(float value)

### Description
Set the window opacity to the given fractional value.
`1.0` is completely opaque, `0.0` is completely transparent.

*(Available from version 0.29; as `set_opacity` from 0.28)*

### Method
N/A (Scripting function)

### Endpoint
N/A (Scripting function)
```

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

### Get Monitor Index of Window

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Returns the 0-based index of the monitor that contains the window. It prioritizes the monitor at the window's center, falling back to the first monitor with any overlap. Available from version 0.44.

```lua
local idx = get_monitor_index()
debug_print("Window is on monitor: " .. (idx + 1))
```

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

### Set Window Position (Direct XMoveWindow)

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Sets the window position directly using the X11 `XMoveWindow` function. This may yield different results compared to `set_window_position()`. The `index` parameter is available from version 0.46.

```lua
set_window_position2(100, 200, 1)
```

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

### Show Lua Version

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/configuration.md

Prints the version of the Lua interpreter used by Devilspie2 and exits.

```bash
devilspie2 --lua-version
```

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

### set_window_fullscreen(bool fullscreen)

Source: https://github.com/dsalt/devilspie2/blob/master/README.md

Sets or clears the fullscreen state of the window. Available from version 0.24.

```APIDOC
## set_window_fullscreen(bool fullscreen)

### Description
Ask the window manager to set or clear the fullscreen state of the
window according to `fullscreen`.

*(Available from version 0.24)*

### Method
N/A (Scripting function)

### Endpoint
N/A (Scripting function)
```

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

### stick_window()

Source: https://github.com/dsalt/devilspie2/blob/master/README.md

Requests the window manager to fix the window's position on the screen, even when the workspace or viewport scrolls.

```APIDOC
## stick_window()

### Description
Ask the window manager to keep the window's position fixed on the screen,
even when the workspace or viewport scrolls.

### Method
N/A (Scripting function)

### Endpoint
N/A (Scripting function)
```

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

### minimize()

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Minimizes the window (iconifies it). This function takes no parameters and returns no value.

```APIDOC
## minimize()

### Description
Minimizes the window (iconifies it).

### Method
Lua function call

### Parameters
This function takes no parameters.

### Return Type
void (no return value)

### Example
```lua
minimize()
```
```

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

### Maximize Window Based on Class Instance

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/types.md

Retrieves the window's class instance name and maximizes the window if it matches 'emacs'.

```lua
local class = get_window_class()
local instance = get_class_instance_name()
local group = get_class_group_name()

if instance == "emacs" then
    maximize()
end
```

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

### C Function to Get Window Geometry

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/internal-architecture.md

The `c_get_window_geometry` function retrieves the position (x, y) and dimensions (width, height) of the current window. It pushes these four values onto the Lua stack and returns the count of values returned.

```c
int c_get_window_geometry(lua_State *lua)
{
    // ... validation ...
    
    WnckWindow *window = get_current_window();
    int x, y, width, height;
    
    if (window) {
        wnck_window_get_geometry(window, &x, &y, &width, &height);
    } else {
        x = y = width = height = 0;
    }
    
    lua_pushnumber(lua, x);
    lua_pushnumber(lua, y);
    lua_pushnumber(lua, width);
    lua_pushnumber(lua, height);
    
    return 4;  // Return 4 values
}
```

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

### C Function to Set Window Position with Validation

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/internal-architecture.md

This C function, `c_set_window_position`, is used to set a window's position. It performs validation, checks for emulation modes, adjusts for window decorations if necessary, and then calls the libwnck function to change the window's geometry. It returns a boolean indicating success.

```c
int c_set_window_position(lua_State *lua)
{
    int x, y;
    int ret = do_set_window_position_internal(lua, "set_window_position", &x, &y, FALSE);
    
    if (ret < 0)
        return 0;  // Error already reported
    else if (ret > 0) {
        WnckWindow *window = get_current_window();
        if (window) {
            if (adjusting_for_decoration)
                adjust_for_decoration(window, &x, &y, NULL, NULL);
            wnck_window_set_geometry(window, WNCK_WINDOW_GRAVITY_CURRENT,
                                     WNCK_WINDOW_CHANGE_X + WNCK_WINDOW_CHANGE_Y,
                                     x, y, -1, -1);
        }
    }
    
    lua_pushboolean(lua, ret);
    return 1;
}
```

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

### Get Window Frame Extents

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/types.md

Obtains the pixel widths of a window's frame decorations (left, right, top, bottom). This information is crucial for calculating the actual content area of a window relative to its absolute geometry.

```lua
local left, right, top, bottom = get_window_frame_extents()
local window_x, window_y, window_w, window_h = get_window_geometry()
-- Content starts at:
local content_x = window_x + left
local content_y = window_y + top
```

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

### set_window_geometry(x, y, width, height, [index])

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Sets both the position (x, y) and size (width, height) of a window in a single call. An optional monitor index can be provided to specify which monitor the window should be placed on.

```APIDOC
## set_window_geometry(x, y, width, height, [index])

### Description
Sets both position and size of the window in one call. An optional monitor index can be specified.

### Parameters
#### Path Parameters
- **x** (number) - Required - X coordinate of the window.
- **y** (number) - Required - Y coordinate of the window.
- **width** (number) - Required - Width of the window in pixels.
- **height** (number) - Required - Height of the window in pixels.
- **index** (number) - Optional - Monitor index. Available from 0.46.

### Return type
void (no return value)

### Example
```lua
set_window_geometry(100, 100, 800, 600)
```
```

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

### Lua: Handle N or M Parameters Expected Error

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/errors.md

Shows functions that accept either N or M parameters. Demonstrates an error case with an incorrect number of arguments and the correct ways to call the function.

```lua
use_utf8(true, false)  -- Expected 0 or 1, got 2, error!
-- Correct:
use_utf8()  -- 0 parameters
use_utf8(true)  -- 1 parameter
```

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

### Get Monitor Geometry

Source: https://github.com/dsalt/devilspie2/blob/master/_autodocs/lua-api-reference.md

Retrieves the position (x, y) and dimensions (width, height) of a specific monitor. If no index is provided, it returns the geometry of the monitor containing the window. Returns nil if the monitor index is out of range. Available from version 0.44 without parameters.

```lua
-- Get geometry of monitor containing window
local x, y, w, h = get_monitor_geometry()

-- Get geometry of second monitor
local x, y, w, h = get_monitor_geometry(1)
```

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

### Set Window Position (Alternative)

Source: https://github.com/dsalt/devilspie2/blob/master/README.md

Sets the position of a window using XMoveWindow, which may yield slightly different results than the default method.

```lua
set_window_position2(0,0)
```