### uwsm .desktop File Example

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

Example of a .desktop file to launch uwsm from a display manager. This entry specifies the name, comment, and the command to execute uwsm start, referencing a compositor's desktop file.

```ini
[Desktop Entry]
Name=My compositor (with UWSM)
Comment=My cool compositor, UWSM session

# a reference to another entry (preferred since some DMs may fail on quoted arguments)
Exec=uwsm start -- my-compositor.desktop

# or a full command line with metadata and executable
#Exec=uwsm start -N "My compositor" -D mycompositor:mylib -C "My cool compositor" -- mywm

# invalidates entry if uwsm is missing
TryExec=uwsm

DesktopNames=mycompositor;mylib
Type=Application
```

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

### Example: Wait for Compositor Start

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/session-management.md

Demonstrates waiting for a Wayland compositor service to become active using `wait_for_unit`. Includes D-Bus interaction setup.

```python
from uwsm.dbus import DbusInteractions
from uwsm.main import wait_for_unit

bus = DbusInteractions('session')
if wait_for_unit('wayland-wm@sway.service', bus, timeout=15):
    print("Compositor started")
else:
    print("Timeout waiting for compositor")
```

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

### Python Examples for Launching Applications

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/application-launching.md

Provides Python code examples for using the `app` function to launch applications. Shows how to start applications in the default graphical slice and how to launch a command in a terminal within a specific slice.

```python
from uwsm.main import app

# Launch Firefox in default graphical app slice
app(['firefox', '--new-instance'])
```

```python
# Launch terminal with command
app(['bash', '-i'], terminal=True, slice_name='session-graphical')
```

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

### Full uwsm start command with options

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

This snippet shows the extended syntax for 'uwsm start', including options for setting desktop names, compositor name, description, hardcode mode, and session management.

```bash
uwsm start \
		[-[a|e]D DesktopName1[:DesktopName2:...]] \
		[-N Name] \
		[-C "Compositor description"] \
		[-F] \
		[-g|-G seconds] \
		[-o] \
		[-U run|home] \
		[-t] \
		[-n] \
		-- ${compositor} [with "any complex" --arguments]
```

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

### Example UWSM Environment File Content

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/configuration.md

Shows example content for general and desktop-specific UWSM environment files, demonstrating how to export environment variables.

```bash
# ~/.config/uwsm/env
export PATH="${HOME}/.local/bin:${PATH}"
export QT_QPA_PLATFORM_PLUGIN_PATH=/usr/lib/qt6/plugins

# ~/.config/uwsm/env-sway
export CLUTTER_BACKEND=wayland
export GDK_BACKEND=wayland

```

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

### Command-Line Usage Examples for uwsm app

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/application-launching.md

Demonstrates various ways to use the `uwsm app` command-line tool to launch applications. Includes examples for default launch, background slices, service units, desktop entries, and custom properties.

```bash
# Launch executable in default slice (app-graphical)
uwsm app -- firefox
```

```bash
# Launch in background slice
uwsm app -s b -- firefox
```

```bash
# Launch as service (backgrounded) in session slice
uwsm app -s s -t service -- myservice
```

```bash
# Launch desktop entry
uwsm app -- firefox.desktop
```

```bash
# Launch desktop entry with action
uwsm app -- featherpad.desktop:standalone-window
```

```bash
# Launch in terminal
uwsm app -T -- myapp
```

```bash
# Launch with custom properties
uwsm app -- --Unit-Property=X-Custom=value myapp
```

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

### Basic uwsm start command

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

The fundamental syntax for starting a compositor with uwsm. Always use '--' to separate uwsm arguments from compositor arguments.

```bash
uwsm start [options] -- ${compositor} [arguments]
```

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

### Start compositor with default selection

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/configuration.md

Starts the default compositor. This is the simplest way to launch a Wayland session.

```bash
uwsm start default
```

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

### Start compositor and generate units in home directory

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/configuration.md

Starts the sway compositor and configures uwsm to generate its unit files in the user's home directory using the -U home option.

```bash
uwsm start -U home -- sway
```

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

### Start compositor with custom arguments

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/configuration.md

Starts a specific compositor (sway) and passes additional arguments to it. Use '--' to separate uwsm arguments from compositor arguments.

```bash
uwsm start -- sway --config ~/.config/sway/custom.config
```

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

### Start Wayland WM Service

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

Starts the main compositor service using systemctl. This command runs the compositor disconnected from a login session.

```bash
systemctl --user start wayland-wm@${compositor}.service
```

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

### Start compositor with custom metadata

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/configuration.md

Starts a compositor (mutter) while setting custom XDG_CURRENT_DESKTOP names and a friendly name. The -D option specifies desktop entry metadata, and -N sets the friendly name.

```bash
uwsm start -D gnome:wayland -N "GNOME Wayland" -- mutter
```

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

### Build and Install Python Project

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

Builds and installs the Python project directly using Meson. Enables optional tools like uuctl, fumon, ttyautolock, and uwsm-app.

```bash
meson setup --prefix=/usr/local -Duuctl=enabled -Dfumon=enabled -Duwsm-app=enabled -Dttyautolock=enabled build
meson install -C build
```

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

### Preview generated units without starting

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/configuration.md

Performs a dry run of the 'start' command for the sway compositor. The -n option prevents uwsm from writing or starting anything, allowing you to preview the generated units.

```bash
uwsm start -n -- sway
```

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

### Systemd Unit Configuration Example

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

These are example file paths for systemd unit drop-ins used to configure arbitrary compositor command lines or other data. They allow for customization of environment and service behavior.

```systemd
wayland-wm-env@${compositor}.service.d/50_custom.conf
wayland-wm@${compositor}.service.d/50_custom.conf
```

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

### Example UWSM Environment Configuration Structure

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/configuration.md

Illustrates the directory structure for UWSM environment configuration files, including general and desktop-specific files.

```tree
~/.config/uwsm/
├── env                          # General session vars
├── env.d/
│   ├── 10-paths.sh
│   └── 20-locale.sh
├── env-sway                     # Sway-specific
├── env-sway.d/
│   └── 10-sway-settings.sh
└── default-id                   # Default compositor

```

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

### Build and Install Deb Package

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

Installs a deb package for UWsm. This involves setting up build dependencies and then building and installing the package.

```bash
IFS='()' read -r _ current_version _ < debian/changelog
sudo apt install devscripts
mk-build-deps
sudo apt install --mark-auto ./uwsm-build-deps_${current_version}_all.deb
dpkg-buildpackage -b -tc --no-sign
sudo apt install ../uwsm_${current_version}_all.deb
```

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

### Start UWsm with Custom Compositor

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

Populates systemd/user/ configuration with units for a specified compositor. Use -o to only populate and do nothing else. Destination rung can be $XDG_RUNTIME_DIR or $XDG_CONFIG_HOME.

```bash
uwsm start -o ${compositor}
```

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

### Start User Systemd Service

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

Manually start a user-level systemd service for an application.

```bash
systemctl --user start not-a-service.service
```

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

### Finalize Session Environment Setup

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/session-management.md

Signals compositor readiness and finalizes environment setup by exporting Wayland and display variables, applying additional variables, and notifying systemd. Use this when the compositor finishes its startup.

```python
def finalize(additional_vars: list = None) -> None
```

```bash
# In compositor autostart
exec exec uwsm finalize SWAYSOCK I3SOCK XCURSOR_SIZE
```

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

### Install UWsm on Arch Linux

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

Installs UWsm using the pacman package manager on Arch Linux.

```bash
pacman -S uwsm
```

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

### Integrate UWSM with Shell Profile

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/README.md

Execute this script in your shell profile to check if UWSM can start and then select the default compositor before starting the session.

```bash
if uwsm check may-start && uwsm select;
then
    exec uwsm start default
fi
```

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

### check_path Example

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/main-classes.md

Demonstrates how to use the check_path method to validate a file path. This checks for existence and necessary permissions.

```python
arg = MainArg("/usr/bin/sway")
arg.check_path()  # Validates existence and permissions
```

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

### Configure UWSM Environment and Run

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/README.md

Set environment variables and create configuration files to customize UWSM behavior. This includes defining unit run directories and finalizing variable names. Finally, start the UWSM service with the desired compositor.

```bash
# Set environment variables
export UWSM_UNIT_RUNG=home          # Store units in ~/.config
export UWSM_FINALIZE_VARNAMES="SWAYSOCK I3SOCK"
export DEBUG=1                       # Enable debug output

# Create environment config
mkdir -p ~/.config/uwsm/env.d
cat > ~/.config/uwsm/env-sway << 'EOF'
export GDK_BACKEND=wayland
export QT_QPA_PLATFORM=wayland
export CLUTTER_BACKEND=wayland
EOF

# Run UWSM
uwsm start -- sway
```

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

### Launch application with specific desktop entry

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/configuration.md

Launches Firefox, specifically requesting a new window. This example demonstrates targeting a specific desktop entry and action.

```bash
uwsm app -- firefox.desktop:new-window
```

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

### Start UWsm with Arguments

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

Appends any remainder arguments to the compositor argument list. Use -- to disambiguate between compositor arguments and other arguments.

```bash
uwsm start -o -- ${compositor} with "any complex" --arguments
```

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

### Start Wayland Session on Login

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

This script starts a Wayland session automatically on tty1 if the system is in graphical.target and the user is in an interactive login shell. It includes checks to prevent startup loops and ensures the compositor is started gracefully, holding the session open until the compositor exits.

```bash
MY_COMPOSITOR=sway
if [ "${0}" != "${0#-}" ] &&
   ! systemctl --user is-active -q wayland-wm@*.service &&
   [ "$XDG_VTNR" = "1" ] &&
   {
       # wait while graphical.target is in startup queue
       while case "$(systemctl list-jobs --plain --no-legend --full graphical.target)" in
       *start*) true ;; *) false ;; esac; do
         sleep 1
       done
       systemctl is-active -q graphical.target
   }
then
    # generate units
    uwsm start -o ${MY_COMPOSITOR}

    # save login environment
    mkdir -p "$XDG_RUNTIME_DIR/uwsm"
    env -0 > "$XDG_RUNTIME_DIR/uwsm/env_login"

    # bind wayland session to login shell PID $$ and start compositor
    echo Starting ${MY_COMPOSITOR} compositor
    systemctl --user start wayland-session-bindpid@$$.service

    # do not die right away on signals, stop gracefully
    trap "trap '' TERM HUP INT; systemctl --user stop --wait wayland-wm@${MY_COMPOSITOR}.service; wait \$SCPID; exit" TERM HUP INT
    {
    	trap '' TERM HUP INT
    	exec systemctl --user start --wait wayland-wm@${MY_COMPOSITOR}.service
    } &
    SCPID=$!
    # hold session open
    wait $SCPID
fi
```

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

### Prepare Environment with UWsm

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

Launches uwsm aux prepare-env to prepare the environment when wayland-wm-env@.service starts. It sources shell profiles and UWsm-specific environment files.

```bash
uwsm aux prepare-env ${compositor}
```

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

### Finalize compositor startup with exported variables

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/configuration.md

Finalizes the compositor startup process and exports necessary Wayland variables. This example shows how to export SWAYSOCK, I3SOCK, and other variables as defined in the sway config.

```bash
exec exec uwsm finalize SWAYSOCK I3SOCK XCURSOR_SIZE XCURSOR_THEME
```

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

### Launch uwsm on Login via Shell Profile

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

Integrate uwsm into your shell profile to launch automatically after login. This snippet checks if uwsm can start and then selects and starts the default compositor, replacing the login shell.

```shell
if uwsm check may-start && uwsm select;
then
	exec uwsm start default
fi
```

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

### check_may_start()

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/session-management.md

Perform checks to determine if a graphical session can start. It verifies various system and user states before allowing a session to begin.

```APIDOC
## check_may_start()

### Description
Perform checks to determine if a graphical session can start.

### Returns
`int` - Exit code (0 if all checks pass, non-zero otherwise)

### Checks Performed:
- User's D-Bus is available
- Parent process is a login shell (name starts with '-')
- TTY1 is in foreground
- Login session's TTY matches
- Login session is local
- System's graphical.target is active or activating
- User's graphical-session.target and related units are inactive

### Example:
```python
# Run from shell profile
if uwsm check may-start && uwsm select; then
    exec uwsm start default
fi
```
```

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

### finalize(additional_vars: list = None)

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/session-management.md

Signal compositor readiness and finalize environment setup by exporting necessary variables and signaling systemd.

```APIDOC
## finalize(additional_vars: list = None)

### Description
Signal compositor readiness and finalize environment setup.

### Parameters:
#### Path Parameters
- **additional_vars** (`list | None`) - Optional - Additional variable names to export

### Returns
`None`

### Behavior:
- Exports WAYLAND_DISPLAY and DISPLAY to systemd and D-Bus
- Exports additional variables from UWSM_FINALIZE_VARNAMES
- Exports variables specified as arguments
- Signals unit readiness to systemd (Type=notify)
- Adds exported vars to cleanup list

### Usage:
Called by compositor at end of startup, or specified in UWSM_FINALIZE_VARNAMES.

### Example:
```bash
# In compositor autostart
exec exec uwsm finalize SWAYSOCK I3SOCK XCURSOR_SIZE
```
```

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

### Example Default Compositor ID

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/configuration.md

Specifies the default compositor to be used by UWSM, stored in a single-line text file.

```text
sway

```

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

### CompGlobals Usage Example

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/main-classes.md

Instantiate CompGlobals to access compositor-related global variables and print information such as the compositor ID, command line, and desktop names.

```python
from uwsm.main import CompGlobals

# Access compositor information
comp = CompGlobals()
print(f"Compositor ID: {comp.id}")
print(f"Command: {' '.join(comp.cmdline)}")
print(f"Desktop names: {':'.join(comp.desktop_names)}")
```

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

### check_exec Example

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/main-classes.md

Demonstrates how to use the check_exec method to validate an executable argument. This will raise an error if the executable is not found in the system's PATH.

```python
arg = MainArg("sway")
arg.check_exec()  # Raises if sway not found
```

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

### Example Wayland Session Desktop Entry

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/configuration.md

A standard .desktop file format for defining a Wayland session, including Name, Comment, Exec, and Type.

```ini
[Desktop Entry]
Name=Sway
Comment=Sway Wayland Compositor

Exec=uwsm start -- sway
TryExec=sway

Type=Application
DesktopNames=sway

```

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

### MainArg Usage Example

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/main-classes.md

Illustrates the usage of the MainArg class for parsing executables, desktop entries with actions, and file paths, including validation checks.

```python
from uwsm.main import MainArg

# Parse executable
arg1 = MainArg("sway")
assert arg1.executable == "sway"
arg1.check_exec()

# Parse desktop entry with action
arg2 = MainArg("my-compositor.desktop:standalone")
assert arg2.entry_id == "my-compositor.desktop"
assert arg2.entry_action == "standalone"

# Parse path
arg3 = MainArg("/usr/bin/sway")
arg3.check_path()
assert arg3.path == "/usr/bin/sway"
```

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

### Custom Compositor Plugin Actions

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

Example of a shell plugin defining custom actions for a compositor named 'my_cool_wm'. It shows how to set environment variables before loading the environment and how to override standard functions to include custom configuration loading.

```bash
#!/bin/false

# function to make arbitrary actions before loading environment
quirks__my_cool_wm() {
  # here additional vars can be set or unset
  export I_WANT_THIS_IN_SESSION=yes
  unset I_DO_NOT_WANT_THAT
  # or prepare a config for compositor
  # or set a var to modify what sourcing uwsm/env, uwsm/env-${__WM_ID__}
  # in the next stage will do
  ...
  # add a var to be exported by uwsm finalize:
  UWSM_FINALIZE_VARNAMES="${UWSM_FINALIZE_VARNAMES}${UWSM_FINALIZE_VARNAMES:+ }ANOTHER_VAR1 ANOTHER_VAR2"
  # add a var to wait and depend on before graphical session:
  UWSM_WAIT_VARNAMES="${UWSM_WAIT_VARNAMES}${UWSM_WAIT_VARNAMES:+ }ANOTHER_VAR1 ANOTHER_VAR2"
}

in_each_config_dir_reversed__my_cool_wm() {
  # custom mechanism for loading of env files (or a stub)
  # replaces standard function, but we want it also
  # so call it explicitly
  in_each_config_dir_reversed "$1"
  # and additionally source our file
  source_file "${1}/${__WM_ID__}/env"
}
```

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

### Finalize UWSM in Compositor Config

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/README.md

Use this command within your compositor's configuration file to signal readiness after UWSM has finalized its setup.

```bash
exec exec uwsm finalize SWAYSOCK I3SOCK XCURSOR_SIZE
```

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

### Check if Session Can Start

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/session-management.md

Performs checks to determine if a graphical session can be initiated. Returns an exit code indicating success (0) or failure (non-zero).

```python
def check_may_start() -> int
```

```shell
# Run from shell profile
if uwsm check may-start && uwsm select; then
    exec uwsm start default
fi
```

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

### Connect to D-Bus and Get Systemd Environment

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/START_HERE.md

Establishes a connection to the D-Bus session bus and retrieves systemd environment variables. Useful for accessing session-specific configurations.

```python
from uwsm.dbus import DbusInteractions

bus = DbusInteractions('session')
env = bus.get_systemd_vars()
print(f"WAYLAND_DISPLAY = {env.get('WAYLAND_DISPLAY')}")
```

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

### Launch Application with uwsm-app Client

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/application-launching.md

Use the `uwsm-app` client for faster application launches compared to `uwsm app`. This is the recommended way to invoke applications through the daemon.

```bash
# Use uwsm-app client (faster than uwsm app)
uwsm-app firefox.desktop
uwsm-app -- "$(fuzzel --launch-prefix='uwsm-app -- ')"
```

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

### Launch Applications with uwsm.main.app

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/START_HERE.md

Demonstrates launching applications in different contexts: graphical sessions, background services, and terminals. Allows specifying slice names and application unit types.

```python
from uwsm.main import app

# In app-graphical slice
app(['firefox', '--private-window'])

# In background slice as a service
app(['my-daemon'], slice_name='b', app_unit_type='service')

# In terminal
app(['bash'], terminal=True, slice_name='s')
```

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

### Session Management Functions

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/INDEX.md

Functions for managing user sessions, including starting, finalizing, and cleaning up environments.

```APIDOC
## Session Management

### `check_may_start()`

#### Description
Checks if a new session may be started.

#### Parameters
None

#### Returns
- int: An integer indicating the status.

### `prepare_env()`

#### Description
Prepares the environment for a new session.

#### Parameters
None

#### Returns
- None

### `finalize(additional_vars)`

#### Description
Finalizes the current session, optionally with additional variables.

#### Parameters
- **additional_vars** (list or None): A list of additional variables to set during finalization.

#### Returns
- None

### `cleanup_env()`

#### Description
Cleans up the environment after a session.

#### Parameters
None

#### Returns
- None

### `filter_varnames(data)`

#### Description
Filters environment variable names from a dictionary.

#### Parameters
- **data** (dict): A dictionary containing environment variables.

#### Returns
- set: A set of filtered environment variable names.

### `append_to_cleanup_file(varnames, skip_always_cleanup, create)`

#### Description
Appends variable names to a cleanup file.

#### Parameters
- **varnames** (set): A set of variable names to append.
- **skip_always_cleanup** (bool): Whether to skip always cleanup.
- **create** (bool): Whether to create the file if it does not exist.

#### Returns
- None

### `wait_for_unit(unit, bus, timeout, states, quiet)`

#### Description
Waits for a systemd unit to reach a specific state.

#### Parameters
- **unit** (str): The name of the systemd unit.
- **bus** (DbusInteractions): D-Bus interaction object.
- **timeout** (int): The timeout in seconds.
- **states** (list): A list of target states.
- **quiet** (bool): Whether to suppress output.

#### Returns
- bool: True if the unit reached the target state within the timeout, False otherwise.

### `waitenv(varnames, timeout, step, end_buffer)`

#### Description
Waits for specified environment variables to be set.

#### Parameters
- **varnames** (list): A list of environment variable names to wait for.
- **timeout** (float): The timeout in seconds.
- **step** (float): The polling interval in seconds.
- **end_buffer** (float): A buffer time in seconds before ending the wait.

#### Returns
- bool: True if all variables are set within the timeout, False otherwise.

### `get_active_wm_unit(active, activating, bus_session)`

#### Description
Gets the systemd unit for the active window manager.

#### Parameters
- **active** (bool): Whether to check for an active WM.
- **activating** (bool): Whether to check for an activating WM.
- **bus_session** (DbusInteractions): D-Bus interaction object for the session.

#### Returns
- str: The name of the active window manager unit.

### `is_active(check_wm_id, verbose, verbose_active, bus_session)`

#### Description
Checks if a window manager is active.

#### Parameters
- **check_wm_id** (str): The window manager ID to check.
- **verbose** (bool): Whether to enable verbose output.
- **verbose_active** (bool): Whether to enable verbose output for active state.
- **bus_session** (DbusInteractions): D-Bus interaction object for the session.

#### Returns
- bool: True if the window manager is active, False otherwise.

### `stop_wm()`

#### Description
Stops the window manager.

#### Parameters
None

#### Returns
- None

### `extract_wm_id(unit_id)`

#### Description
Extracts the window manager ID from a unit ID.

#### Parameters
- **unit_id** (str): The systemd unit ID.

#### Returns
- str: The extracted window manager ID.

### `get_fg_vt()`

#### Description
Gets the virtual terminal (VT) of the foreground process.

#### Parameters
None

#### Returns
- int: The foreground VT number.

### `get_session_by_vt(vtnr, bus_system)`

#### Description
Gets the session associated with a virtual terminal.

#### Parameters
- **vtnr** (int): The virtual terminal number.
- **bus_system** (DbusInteractions): D-Bus interaction object for the system.

#### Returns
- str: The session name associated with the VT.
```

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

### Initialize and Interact with Core UWSM Classes

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/README.md

Import and use core classes like CompGlobals, Varnames, and MainArg to parse arguments and interact with D-Bus services. Ensure the executable is validated before proceeding.

```python
# Import core classes
from uwsm.main import CompGlobals, Varnames, MainArg
from uwsm.dbus import DbusInteractions
from uwsm.misc import Styles, print_ok, print_error

# Parse command-line argument
arg = MainArg("sway")  # or "my-app.desktop" or "/path/to/executable"
arg.check_exec()       # Validate executable exists

# Access D-Bus services
bus = DbusInteractions('session')
props = bus.get_systemd_properties(['Environment'])
bus.notify(summary="Session Ready", body="Wayland started")

# Get compositor info
comp = CompGlobals()
print_ok(f"Compositor: {comp.name} ({comp.id})")
```

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

### Launch application as a service in session slice

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/configuration.md

Launches an important application as a 'service' unit within the 'session-graphical' slice. Use -s s for the session slice and -t service for the unit type.

```bash
uwsm app -s s -t service -- important-app
```

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

### prepare_env()

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/session-management.md

Prepare the environment for a graphical session by loading saved configurations, sourcing shell profiles, and applying custom environment settings.

```APIDOC
## prepare_env()

### Description
Prepare environment for graphical session.

### Returns
`None`

### Behavior:
1. Loads saved environment from `uwsm start` if available
2. Otherwise sources POSIX shell profile (/etc/profile, ~/.profile)
3. Sources common uwsm/env files
4. Sources desktop-specific uwsm/env-${desktop} files
5. Applies plugin hooks for custom environment
6. Exports environment variables to systemd and D-Bus

### Environment File Locations:
- `${XDG_CONFIG_HOME}/uwsm/env`
- `${XDG_CONFIG_HOME}/uwsm/env.d/*`
- `${XDG_CONFIG_HOME}/uwsm/env-${desktop}`
- `${XDG_CONFIG_HOME}/uwsm/env-${desktop}.d/*`

### Session-Specific Variables:
Variables like XDG_SEAT, XDG_SESSION_ID, XDG_VTNR are set automatically and not exported to activation environments.
```

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

### Session Management Functions

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/INDEX.md

Functions for managing user sessions, including checking if a session can start, preparing the environment, and finalizing a session.

```APIDOC
## Session Management Functions

### check_may_start()

#### Description
Checks if a session may be started.

### prepare_env()

#### Description
Prepares the environment for a new session.

### finalize()

#### Description
Finalizes the current session.
```

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

### Launch Applications via Tofi with UWMS

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

This command uses Tofi to select an application and then launches it via `uwsm app --`.

```bash
uwsm app -- $(tofi-drun)
```

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

### Get Foreground Virtual Terminal Number

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/session-management.md

Retrieves the number of the foreground virtual terminal (VT). Returns 0 if the VT is not available.

```python
def get_fg_vt() -> int:
    pass
```

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

### API Reference - Application Launching

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/README.md

Core functions for launching applications, including a main launcher with slice and unit-type control, fast background daemon launching, and utilities for generating application commands and finding desktop entries.

```APIDOC
## Application Launching Functions

### Description
Provides functionalities for launching applications, managing their execution contexts, and discovering relevant desktop entries.

### Functions
- `app(entry_data, unit_type, slice)`: The main function to launch an application with control over systemd slice and unit type.
- `app_daemon(entry_data, unit_type, slice)`: Launches an application as a background daemon.
- `gen_entry_args(entry_data)`: Generates the command-line arguments for an application based on its desktop entry.
- `find_terminal_entry(entry_data)`: Finds a suitable desktop entry for launching within a terminal.
- `find_entries(search_paths)`: Searches for desktop entries in specified paths.
- `get_default_comp_entry()`: Retrieves the default compositor desktop entry.
- `save_default_comp_entry(entry_data)`: Saves the default compositor desktop entry.
- `select_comp_entry(entries)`: Allows interactive selection of a compositor entry.
```

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

### Launch Any Application with UWMS

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

Use this command to launch any application through UWMS. It supports executable names, desktop entry paths, or specific actions, along with any arguments.

```bash
uwsm app -- {executable|entry.desktop[:action]} [args ...]
```

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

### app_daemon()

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/application-launching.md

Provides a fast application daemon for handling repeated application launches, reducing startup overhead by parsing desktop entries once and managing the environment.

```APIDOC
## app_daemon()

### Description
Fast application daemon for handling repeated app launches. Reduces startup overhead of repeated `uwsm app` invocations by providing a background daemon that parses desktop entries once, handles environment management, generates launch commands, and avoids Python interpreter startup cost. The daemon listens on a socket for client requests and responds with generated commands. It is started on-demand by the first `uwsm-app` client and stays running throughout the session.

### Method
N/A (Background Service)

### Endpoint
N/A (Socket Communication)

### Usage
```bash
# Use uwsm-app client (faster than uwsm app)
uwsm-app firefox.desktop
uwsm-app -- "$(fuzzel --launch-prefix='uwsm-app -- ')"
```
```

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

### Launch Applications via Wofi with Desktop Entry ID

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

This command uses Wofi to select a desktop entry and then pipes it to `uwsm app --`, ensuring the correct format for UWMS.

```bash
uwsm app -- "$(wofi --show drun --define=drun-print_desktop_file=true | sed -E 's/(\.desktop) /\1:/')"
```

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

### Retrieve Systemd Unit Property

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/dbus-interactions.md

Get a specific property from a systemd unit. Optionally skip generic interfaces by setting skip_generic to True.

```Python
state = bus_session.get_unit_property('wayland-wm@sway.service', 'ActiveState')
```

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

### Generate Tweak Drop-ins for XDG Autostart

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/unit-management.md

Generates tweak drop-ins for XDG autostart and other services. Use 'run' or 'home' as the destination.

```python
def generate_tweaks(rung: str = "run") -> None:
    pass
```

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

### Varnames Usage Example

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/main-classes.md

Utilize the Varnames class to check environment variable classifications, such as determining if a variable is slated for cleanup or retrieving all session-specific variables.

```python
from uwsm.main import Varnames

# Check if a variable should be cleaned up
if "MYVAR" in Varnames.always_cleanup:
    print("Will be cleaned up")

# Get all session-specific variables
session_vars = Varnames.session_specific
```

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

### Launch Applications via Wofi with Desktop Entry ID (Advanced Case)

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

This command handles Wofi output, specifically extracting and formatting desktop entry information for `uwsm app --`.

```bash
uwsm app -- "$(D=$(wofi --show drun --define=drun-print_desktop_file=true); case "$D" in *'.desktop '*) echo "${D%.desktop *}.desktop:${D#*.desktop }";; *) echo "$D";; esac)"
```

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

### Get Currently Active Compositor Unit

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/unit-management.md

Retrieves the name of the currently running or activating compositor unit. It searches for units matching the 'wayland-wm@*.service' pattern.

```python
from uwsm.main import get_active_wm_unit

unit = get_active_wm_unit()
if unit:
    print(f"Running: {unit}")
```

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

### Get Active Window Manager Unit

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/session-management.md

Retrieves the name of the currently active window manager unit. Use this when you need to identify the running Wayland compositor.

```python
from uwsm.main import get_active_wm_unit

unit = get_active_wm_unit()
if unit:
    print(f"Active compositor: {unit}")
```

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

### Configure UWSM for Display Manager

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/README.md

Add this entry to your display manager's `.desktop` file to launch UWSM as a compositor.

```ini
[Desktop Entry]
Name=My Compositor (UWSM)
Exec=uwsm start -- my-compositor
TryExec=uwsm
Type=Application
```

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

### Configure Hyprlauncher for UWMS App Launching

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

Set `desktop_launch_prefix` in Hyprlauncher's configuration to `uwsm app --` to integrate with UWMS application launching.

```ini
desktop_launch_prefix = uwsm app --
```

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

### Systemd Unit Name Escaping with simple_systemd_escape

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/utility-functions.md

Escapes a string for use in systemd unit names or contexts. The 'start' parameter controls escaping direction. Import from uwsm.main.

```python
from uwsm.main import simple_systemd_escape

escaped = simple_systemd_escape("my-compositor:instance")
# Result: escaped string safe for unit names
```

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

### generate_tweaks()

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/unit-management.md

Generates tweak drop-ins for XDG autostart and other services. This includes slice assignment for autostart apps and ordering constraints for KDE desktop portal.

```APIDOC
## generate_tweaks()

### Description
Generate tweak drop-ins for XDG autostart and other services.

### Method
```python
def generate_tweaks(rung: str = "run") -> None
```

### Parameters
#### Path Parameters
- **rung** (str) - Optional - Destination: 'run' or 'home'. Default: "run"

### Generated Tweaks
1. **XDG Autostart Slice Assignment**
   - File: `app-@autostart.service.d/slice-tweak.conf`
   - Effect: Assigns autostart apps to app-graphical.slice

2. **KDE Desktop Portal Ordering**
   - File: `plasma-xdg-desktop-portal-kde.service.d/order-tweak.conf`
   - Effect: Adds ordering constraint after graphical-session.target
```

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

### Add Dependency to Graphical Session Target

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

If an application's service unit does not already specify `WantedBy=graphical-session.target`, manually add it as a dependency to ensure it starts within the graphical session.

```bash
systemctl --user add-wants graphical-session.target that-app.service
```

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

### Get Session ID by Virtual Terminal Number

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/session-management.md

Retrieves the login session ID associated with a given virtual terminal number. An optional system bus connection can be provided.

```python
def get_session_by_vt(vtnr: int, bus_system=None) -> str:
    pass
```

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

### Prepare Environment for Graphical Session

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/session-management.md

Prepares the environment for a graphical session by loading saved settings, sourcing profile and uwsm environment files, applying plugin hooks, and exporting variables.

```python
def prepare_env() -> None
```

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

### Bind PID and Wait for Session End

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

Starts the wayland-session-bindpid@.service to track the PID of the login shell and stop the graphical session when it exits. Use --wait to hold the terminal until the session ends.

```bash
systemctl --user start wayland-session-bindpid@$$.service
```

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

### Escape String for Systemd Unit Names

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/unit-management.md

Escapes special characters in a string to make it safe for use in systemd unit names and specifiers. The `start` parameter controls whether escaping applies from the beginning or end of the string.

```python
from uwsm.main import simple_systemd_escape

escaped = simple_systemd_escape("my-compositor:instance")
# Result: safe for use in unit names
```

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

### Configure Rofi for UWMS App Launching

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

Use Rofi's `-run-command` option to specify `uwsm app -- {cmd}` for launching applications through UWMS.

```bash
rofi -show drun -run-command "uwsm app -- {cmd}"
```

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

### Configure Fuzzel via Config File for UWMS

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

Set the `launch-prefix` in Fuzzel's configuration to `uwsm app --` to integrate with UWMS application launching.

```ini
launch-prefix=uwsm app --
```

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

### Configure Fuzzel for UWMS App Launching

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

This shows how to configure Fuzzel to use `uwsm app --` as its launch prefix, enabling it to launch applications via UWMS.

```bash
fuzzel "--launch-prefix=uwsm app --"
```

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

### Get Systemd Unit File Path

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/unit-management.md

Use `get_unit_path` to determine the filesystem path for a systemd unit file. Specify the unit name, and optionally the `rung` ('run' or 'home') and `level` ('user' or 'system') to resolve the correct path based on systemd conventions.

```python
from uwsm.main import get_unit_path

path = get_unit_path('wayland-wm@sway.service', rung='run')
# Result: /run/user/1000/systemd/user/wayland-wm@sway.service
```

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

### Launch application in default slice and type

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/configuration.md

Launches the Firefox application. By default, it targets the 'app-graphical' slice and creates a 'scope' unit type.

```bash
uwsm app -- firefox
```

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

### Launch Featherpad with Specific Action via uwsm

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

Configures a keybinding to launch Featherpad with the 'standalone-window' action using its desktop entry via uwsm. This demonstrates launching applications with specific actions.

```shell
bindsym --to-code $mod+n exec exec uwsm app featherpad.desktop:standalone-window
```

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

### API Reference - Utility Functions

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/README.md

A collection of general utility functions for environment file I/O, systemd variable management, string manipulation, and output formatting.

```APIDOC
## Utility Functions

### Description
Provides various helper functions for common tasks such as file I/O, string manipulation, and output formatting.

### Functions
- `save_env(filepath, env_vars)`: Saves environment variables to a file.
- `load_env(filepath)`: Loads environment variables from a file.
- `set_systemd_vars(unit_name, env_vars)`: Sets environment variables for a systemd unit.
- `unset_systemd_vars(unit_name, var_names)`: Unsets environment variables for a systemd unit.
- `char2cesc(char)`: Converts a character to its escape sequence.
- `simple_systemd_escape(s)`: Performs a simple escape for systemd values.
- `path2url(path)`: Converts a file path to a URL.
- `print_ok(message)`: Prints an success message.
- `print_warning(message)`: Prints a warning message.
- `print_error(message)`: Prints an error message.
- `print_debug(message)`: Prints a debug message.
- `str2bool_plus(value)`: Converts a string to a boolean with extended support.
- `sane_split(s, sep)`: Splits a string by a separator, handling quotes.
- `random_hex(length)`: Generates a random hexadecimal string.
- `dedent(text)`: Removes common leading whitespace from a multi-line string.
```

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

### Launch Default Terminal with uwsm

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

Configures a keybinding to launch the default terminal using uwsm. Assumes uwsm is configured to use scopes by default.

```shell
bindsym --to-code $mod+t exec exec uwsm app -T
```

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

### Wait for Environment Variables with uwsm

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

Configure `UWSM_WAIT_VARNAMES` to delay graphical session startup until specified variables appear in the systemd activation environment. This can be combined with `uwsm finalize` for more control. Explicit assignment can serve as a marker for unset variables.

```bash
# in env file:
export UWSM_WAIT_VARNAMES="${UWSM_WAIT_VARNAMES} FINALIZED"

# in compositor's autostart:
 uwsm finalize FINALIZED="I'm here" SWAYSOCK I3SOCK XCURSOR_SIZE XCURSOR_THEME
```

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

### Select Compositor Entry Interactively

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/application-launching.md

Displays an interactive menu using 'whiptail' to allow the user to select a compositor entry. It can highlight a default entry and optionally just confirm the default without showing the menu.

```bash
# Interactive selection
uwsm select
```

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

### Configure UWSM Finalization and Readiness Variables

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/configuration.md

Customize the finalization process by specifying additional variables to export and variables to wait for before considering the graphical session active. Adjust the settlement time after all required variables are found.

```bash
# In ~/.config/uwsm/env or sway config
export UWSM_FINALIZE_VARNAMES="SWAYSOCK I3SOCK XCURSOR_SIZE XCURSOR_THEME"
export UWSM_WAIT_VARNAMES="WAYLAND_DISPLAY SWAYSOCK"
export UWSM_WAIT_VARNAMES_SETTLETIME=0.1
```

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

### Filesystem Path to URL Conversion with path2url

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/utility-functions.md

Converts a given filesystem path into a file:// URL. Import the function from uwsm.main.

```python
from uwsm.main import path2url

url = path2url("/home/user/.config/sway/config")
# Result: "file:///home/user/.config/sway/config"
```

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

### waitenv()

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/session-management.md

Waits for a list of environment variables to appear in the systemd activation environment within a specified timeout.

```APIDOC
## waitenv()

### Description
Wait for environment variables to appear in systemd activation environment.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **varnames** (list) - Required - Variable names to wait for
- **timeout** (float) - Required - Maximum wait time in seconds
- **step** (float) - Optional - Check interval in seconds (Default: 0.1)
- **end_buffer** (float) - Optional - Additional wait after all vars found (Default: 0)

### Response
#### Success Response (200)
- Returns True if all variables found, False on timeout.

### Usage
Called by session startup to wait for compositor to set WAYLAND_DISPLAY and other important variables.
```

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

### Configure UWsm on NixOS

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

Enables UWsm on NixOS using configuration options. Allows configuration of available compositors.

```nix
programs.uwsm.enable = true;
programs.uwsm.waylandCompositors = [ ... ];
```

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

### Initialize DbusInteractions

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/dbus-interactions.md

Connect to either the session or system D-Bus. Ensure the correct dbus_level ('session' or 'system') is provided.

```Python
from uwsm.dbus import DbusInteractions

# Connect to session bus
bus_session = DbusInteractions('session')

# Connect to system bus
bus_system = DbusInteractions('system')
```

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

### Wait for Environment Variables

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/session-management.md

Waits for a list of environment variables to appear in the systemd activation environment. Includes configurable step intervals and an end buffer.

```python
def waitenv(varnames: list, timeout: float, step: float = 0.1, end_buffer: float = 0) -> bool
```

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

### notify(summary, body, app_name, replaces_id, app_icon, actions, hints, expire_timeout, urgency)

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/INDEX.md

Sends a desktop notification.

```APIDOC
## notify DbusInteractions

### Description
Sends a desktop notification to the user.

### Parameters
* **summary** (str) - The summary text for the notification.
* **body** (str) - The main body text of the notification.
* **app_name** (str) - The name of the application sending the notification.
* **replaces_id** (int) - The ID of a notification to replace.
* **app_icon** (str) - The icon for the notification.
* **actions** (list) - A list of actions that can be taken on the notification.
* **hints** (dict) - A dictionary of hints for the notification server.
* **expire_timeout** (int) - The timeout in milliseconds before the notification expires.
* **urgency** (int) - The urgency level of the notification.
```

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

### check_entry_showin()

Source: https://github.com/vladimir-csp/uwsm/blob/master/_autodocs/api-reference/entry-parsing.md

Checks if a desktop entry should be displayed based on OnlyShowIn and NotShowIn restrictions, considering the current desktop environment.

```APIDOC
## check_entry_showin()

### Description
Checks if entry should be shown based on OnlyShowIn and NotShowIn restrictions.

### Method
Python Function

### Parameters
#### Path Parameters
- **entry** (DesktopEntry) - Required - Desktop entry to check

### Returns
- **bool** - True if entry should be shown

### Raises
- **RuntimeError** - If entry should not be shown based on XDG_CURRENT_DESKTOP

### Logic:
- If OnlyShowIn is set, entry is shown only if it contains a value from XDG_CURRENT_DESKTOP
- If NotShowIn is set, entry is hidden if it contains a value from XDG_CURRENT_DESKTOP
- If neither is set, entry is shown

### Request Example:
```python
from xdg.DesktopEntry import DesktopEntry
from uwsm.main import check_entry_showin
import os

os.environ['XDG_CURRENT_DESKTOP'] = 'sway:GNOME'

entry = DesktopEntry('/usr/share/applications/some-app.desktop')
try:
    check_entry_showin(entry)
    print("Entry matches current desktop")
except RuntimeError as e:
    print(f"Entry not for current desktop: {e}")
```
```

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

### Basic Systemd Unit Files for Wayland Session Management

Source: https://github.com/vladimir-csp/uwsm/blob/master/README.md

This list includes fundamental systemd unit files provided by uwsm for managing Wayland sessions. These units handle slices, targets, services, and dependencies for a clean session lifecycle.

```systemd
background-graphical.slice
app-graphical.slice
session-graphical.slice
wayland-session-envelope@.target
wayland-session-pre@.target
wayland-session-shutdown.target
wayland-session-xdg-autostart@.target
wayland-session@.target
wayland-wm-app-daemon.service
wayland-wm-env@.service
wayland-wm@.service
wayland-session-bindpid@.service
wayland-session-waitenv.service
```