User Commands

# NAME

     icesh - control window properties and the IceWM window manager

# SYNOPSIS

icesh OPTIONS|ACTIONS+

# DESCRIPTION

icesh provides 92 commands to interact with the icewm(1) window manager. There are two types of commands:

1. Commands to directly interact with icewm:

  These are listed in the section "MANAGER ACTIONS" below. They are easy to use, because they don't require to select one or more windows. For example, `icesh restart` will restart icewm and `icesh clients` lists the applications which are managed by icewm.

2. Commands which operate on a selection of windows:

  See the section `WINDOW ACTIONS` below. For example, `icesh close` is a request to close a window, but which window? Now icesh will turn the mouse pointer into a crosshair. Click on a window and a close request will be sent to that application.

  The power of icesh lies in its ability to programmatically select one or more windows and operate on that selection. This can be used in scripts and in icewm-keys(5) to define your own window management hotkeys. For example, to immediately close all xterm windows do `icesh -c xterm close`.

  There are about ten `SELECT OPTIONS` to select windows. They start with a minus sign '-' or with a plus sign '+'. The first starts a new selection. The second adds more windows to an existing selection.

  This selection of windows can be reduced by `FILTER OPTIONS`. These remove unwanted windows from the current selection. Multiple filter options can be given. For example, `icesh -c xterm -W this close` will close only those xterms which are shown on the current workspace. The xterms on other workspaces are filtered out by the `-W this` filter option.

  There is no limit to the number of selections, filters and actions which you can give to a single icesh command. They are processed and evaluated one by one from left to right. This makes icesh a small declarative programming language. Have a look at some examples near the end of this document.

# OPTIONS

icesh recognizes the following options:

## SELECT OPTIONS

Select options specify the window or windows to which subsequent actions apply. If none is given, but an action does require a window, then a selection crossbar is invoked to select the desired window interactively. The manager actions do not require window options.

The following five options select one or more client windows. If needed, they can be repeated for successive actions.

-w, -window, +w, +window WINDOW_ID

  Specifies the identifier of the window, WINDOW_ID, for which the action applies. Special identifiers are root for the root window and focus for the currently focused window. The option with minus sign replaces the existing selection. With a plus sign the window is added to an existing selection.

-r, -root, +r, +root

  Is equivalent to -window root and selects the root window. The option with minus sign replaces the existing selection with the root window. With a plus sign the root window is added to an existing selection.

-f, -focus, +f, +focus

  Is equivalent to -window focus and selects the focused window. The option with minus sign replaces the existing selection with the focused window. With a plus sign the focused window is added to an existing selection.

-a, -all

  Selects all client windows of the window manager.

-s, -shown

  Selects all clients which are on the current workspace.

-t, -top

  Selects all toplevel windows from the display unconditionally. This includes windows which have never been mapped and windows with the override redirect bit set to evade management.

-x, -xembed

  Selects all windows which are embedded using the XEMBED protocol.

## FILTER OPTIONS

The following options filter the currently selected set of windows. If no previous select option was given then a -all option is implicitly assumed to filter all client windows.

-c, -class WM_CLASS

  Filters the set of windows on window manager class, WM_CLASS. If WM_CLASS contains a period, only windows with exactly the same WM_CLASS property are matched. If there is no period, windows of the same class and windows of the same instance (aka. -name) are selected.

-l, -last

  Filter clients and keep only the most recent client.

-m, -machine HOST

  Filters clients by host name. Clients with a WM_CLIENT_MACHINE property equal to HOST are selected.

-n, -name NAME

  Filters clients by _NET_WM_NAME or WM_NAME. NAME matches any part of the property value. To match at the beginning use a `^` prefix. To match at the end use a `$` suffix.

-p, -pid PID

  Filters clients by process ID. Clients with a _NET_WM_PID property equal to PID are selected.

-G, -Gravity GRAVITY

  Filters clients by the window gravity field of the WM_NORMAL_HINTS property. Clients with a gravity equal to GRAVITY are selected. If GRAVITY starts with an exclamation mark then the filtering is inverted.

-L, -Layer LAYER

  Filters clients by GNOME window layer, which can either be a layer name or a layer number. See EXPRESSIONS below. If LAYER starts with an exclamation mark then the filtering is inverted.

-N, -Netstate STATE

  Filters clients by EWMH window state. Clients which have at least an EWMH window state of STATE are selected. This state refers to details like minized or maximized. See EXPRESSIONS below. If STATE starts with an exclamation mark then the filtering is inverted. A question mark `?` filters clients with any bit set in STATE.

-P, -Property PROP[=value]

  Filters clients by property. Clients which have a property PROP are selected. If the optional value is given, the match succeeds only if PROP is a string, window, cardinal, or atom, with a value equal to value. The filtering is inverted if PROP starts with an exclamation mark.

-R, -Role ROLE

  Filters clients by WM_WINDOW_ROLE. Clients which have a WM_WINDOW_ROLE property value equal to ROLE are selected. The filtering is inverted if ROLE starts with an exclamation mark.

-S, -State STATE

  Filters clients by GNOME window state. Clients which have at least a state of STATE are selected. The window state refers to details like minized or maximized. See EXPRESSIONS below. If STATE starts with an exclamation mark then the filtering is inverted. A question mark `?` filters clients with any bit set in STATE.

-W, -Workspace WORKSPACE

  Filter clients by workspace. Workspace WORKSPACE is either a workspace name, or a workspace number counting from zero, or the word `this` for the current workspace, or the word `All` for all workspaces. If WORKSPACE starts with an exclamation mark then the filtering is inverted.

-X, -Xinerama MONITOR

  Limit clients by RandR/Xinerama monitor. Only operate on clients which are displayed on MONITOR, where MONITOR can be `All` for all monitors, `this` for the monitor where the active window is displayed, or a monitor number starting from zero. See the output of `randr` or `xinerama` below.

## GENERAL OPTIONS

The following options are identical for every IceWM command.

-d, -display DISPLAY

  Specifies the X11 DISPLAY. If unspecified, defaults to $DISPLAY.

-h, --help

  Print a brief usage statement to stdout and exit.

-V, --version

  Print the program version to stdout and exit.

-C, --copying

  Print copying permissions to stdout for the program and exit.

# ACTIONS

icesh expects one or more action arguments. There are two kinds of actions: window actions and manager actions. The first operates on the selected windows. The second directly interacts with the icewm window manager.

## WINDOW ACTIONS

The following actions affect the selected window or windows.

activate

  Activate the window, aka. to focus.

close

  Send a close request to the client that created the window.

kill

  Force an immediate close down of the client that created the window.

id

  Print window identifiers for the selected windows.

pid

  Print process identifiers for the selected windows.

list

  Show window details, like geometry and names.

lower

  Lower the window.

raise

  Raise the window.

above

  Stack the window above others.

below

  Stack the window below others.

rollup

  Rollup the specified window.

fullscreen

  Set the window to fullscreen.

maximize

  Maximize the window.

horizontal

  Maximize the window only horizontally.

vertical

  Maximize the window only vertically.

minimize

  Minimize the window.

restore

  Restore the window to normal.

hide

  Make window hidden.

unhide

  Undo window hidden.

skip

  Don't show window on taskbar.

unskip

  Do show window on taskbar.

resize WIDTH HEIGHT

  Resize window to WIDTH by HEIGHT window units.

sizeto WIDTH HEIGHT

  Resize window to WIDTH by HEIGHT pixels. If WIDTH or HEIGHT ends with a percent sign `%`, then they refer to a percentage of the desktop work area. For instance, `sizeto 50% 100%` resizes to half the desktop width and whatever height is available above or below the taskbar.

sizeby WIDTH HEIGHT

  Resize window by WIDTH by HEIGHT pixels. If WIDTH or HEIGHT ends with a percent sign `%`, then they refer to a percentage of the current window size. For instance, `sizeto 50% 200` increases the width by 50% and increases the height by 200 pixels.

move X Y

  Move the selected window or windows to the screen position X Y. To specify X or Y values relative to the right side or bottom side precede the value with an extra minus sign, like in `move -+10 --20`.

moveby X Y

  Displace window by X Y pixels.

center

  Position window in the center of the desktop work area.

left

  Position window against the left side of the desktop work area.

right

  Position window against the right side of the desktop work area.

top

  Position window against the top side of the desktop work area.

bottom

  Position window against the bottom side of the desktop work area.

setIconTitle TITLE

  Set the icon title to TITLE.

getIconTitle

  Print the icon title.

setWindowTitle TITLE

  Set the window title to TITLE.

getWindowTitle

  Print the window title.

setGeometry GEOMETRY

  Set the window geometry to GEOMETRY.

getGeometry

  Print the window geometry.

netState [STATE]

  If STATE is omitted then it shows the EWMH window state. If STATE starts with a `+` then flags in STATE are appended to the existing EWMH window state. If STATE starts with a `-` then flags in STATE are removed from the existing EWMH window state. If STATE starts with a `=` then the EWMH window state is set to STATE. See EXPRESSIONS below. A list of EWMH flags can be found in the output of `icesh symbols`.

setState MASK STATE

  Set the GNOME window state to STATE. Only bits selected by MASK are affected. See below for STATE and MASK symbols.

toggleState STATE

  Toggle the GNOME window state bits specified by the STATE expression. See below for STATE symbols.

getState

  Print the GNOME window state for the specified window.

setHints HINTS

  Set the GNOME window hints to HINTS. See below for symbols.

getHints

  Print the GNOME window hints for the specified window.

setLayer LAYER

  Move the specified window to another GNOME window layer. See below for LAYER symbols.

getLayer

  Print the GNOME window layer for the specified window.

setWorkspace WORKSPACE

  Move the specified window to another workspace. Select the root window to change the current workspace. If WORKSPACE is `All` then the specified window becomes visible on all workspaces. Specify `this` for the current workspace.

getWorkspace

  Print the workspace for the specified window.

opacity [OPACITY]

  Print the window opacity if OPACITY is not given, otherwise set the window opacity to OPACITY.

setTrayOption TRAYOPTION

  Set the IceWM tray option for the specified window to TRAYOPTION. See IceWM tray options, below, for TRAYOPTION symbols.

getTrayOption

  Print the IceWM tray option for the specified window.

setNormalGravity GRAVITY

  Set the window gravity field in the WM_NORMAL_HINTS property for the specified window to GRAVITY. See below for GRAVITY symbols.

getNormalGravity

  Print the window gravity from the WM_NORMAL_HINTS property for the specified window.

setWindowGravity GRAVITY

  Set the window gravity for the specified window to GRAVITY. See below for GRAVITY symbols.

getWindowGravity

  Print the window gravity for the specified window.

setBitGravity GRAVITY

  Set the bit gravity> for the specified window to GRAVITY. See below for GRAVITY symbols.

getBitGravity

  Print the bit gravity for the specified window.

motif [funcs FUNCTIONS | decor DECORATIONS | remove]

  Query, set or modify the `_MOTIF_WM_HINTS` property for the specified window. Without arguments motif will show the current value, but only if the window has such a property. The property can be removed or reset with the remove argument. With funcs and decor individual fields of this property can be enabled or disabled. If FUNCTIONS or DECORATIONS starts with a minus or plus sign then the existing value is modified, otherwise it is set to the new value. Note that if `All` is set, then other set fields will be disabled and cleared fields will be enabled.

prop PROPERTY

  Print the value of property PROPERTY if it is present.

click window-x window-y button

  Send a button press and release event at position (window-x, window-y). A negative position is relative to the bottom right corner. The mouse pointer is warped to the position before sending the events. The button number should be between 1 and 5 inclusive.

spy

  Observe the selected windows and report any changes. This includes focus, visibility, position, size and all window properties.

## MANAGER ACTIONS

The following actions control the IceWM window manager and therefore do not require a window select or filter option:

listWorkspaces

  List the names of all workspaces.

current

  Show the number and name of the current workspace.

goto WORKSPACE

  Change the current workspace to WORKSPACE.

workspaces [COUNT]

  Print the number of workspaces if COUNT is not given, otherwise set the number of workspaces to COUNT.

setWorkspaceName INDEX NAME

  Change the name of the workspace INDEX to NAME, where INDEX is a workspace number starting from zero.

setWorkspaceNames NAME [NAME]*

  Change the workspace names to the list of NAMEs.

addWorkspace NAME

  Create a new workspace with name NAME.

desktop [SHOWING]

  If SHOWING is `1` then set `showing the desktop` mode. If SHOWING is `0` then turn off `showing the desktop`. Print the current mode if SHOWING is not given.

randr

  Summarize the RandR configuration.

xinerama

  Summarize the Xinerama configuration.

check

  Print information about the current window manager, like name, version, class, locale, command, host name and pid.

clients

  List all managed client windows, their titles and geometries.

shown

  List all mapped client windows for the current desktop, their titles and geometries.

windows

  List all toplevel windows, their titles and geometries.

systray

  List applications which are managed by the IceWM system tray.

xembed

  List application windows which are embedded using the XEMBED protocol. This is another way to discover system tray applications.

logout

  Let icewm execute the `LogoutCommand`.

reboot

  Let icewm execute the `RebootCommand`.

shutdown

  Let icewm execute the `ShutdownCommand`.

cancel

  Let icewm cancel the logout/reboot/shutdown.

about

  Let icewm show the about window.

windowlist

  Let icewm show the window list window.

restart

  Let icewm restart itself.

suspend

  Let icewm execute the `SuspendCommand`.

winoptions

  Let icewm reload the `winoptions`.

keys

  Let icewm reload the `keys` file.

guievents

  Monitor the ICEWM_GUI_EVENT property and report all changes.

delay [time]

  Stop execution for time or 0.1 seconds.

runonce program [arguments...]

  This action is meant to be used together with the -class option. Only if no window is matched by WM_CLASS then program [arguments...] is executed.

sync

  Synchronize with the IceWM window manager. That is, wait for icewm to process all previous actions.

symbols

  List all named symbols.

## EXPRESSIONS

Some of the window actions require one or two EXPRESSION arguments.

EXPRESSION ::= SYMBOL | EXPRESSION { `+` | `|` } SYMBOL

Each SYMBOL may be from one of the following applicable domains:

GNOME window state

  Named symbols of the domain GNOME window state (numeric range: 0-1023):

          AllWorkspaces          (1)
          Sticky                 (1)
          Minimized              (2)
          Maximized             (12)
          MaximizedVert          (4)
          MaximizedVertical      (4)
          MaximizedHoriz         (8)
          MaximizedHorizontal    (8)
          Hidden                (16)
          Rollup                (32)
          All                 (1023)

  These symbols are used with the MASK and STATE arguments to the `setState` and `toggleState` actions. Some additional states include: Above, Below, Urgent and Fullscreen.

GNOME window hint

  Named symbols of the domain GNOME window hint (numeric range: 0-63):

          SkipFocus              (1)
          SkipWindowMenu         (2)
          SkipTaskBar            (4)
          FocusOnClick          (16)
          DoNotCover            (32)
          All                   (63)

  These symbols are used with the HINTS argument to the `setHints` action.

GNOME window layer

  Named symbols of the domain GNOME window layer (numeric range: 0-15):

          Desktop                (0)
          Below                  (2)
          Normal                 (4)
          OnTop                  (6)
          Dock                   (8)
          AboveDock             (10)
          Menu                  (12)

  These symbols are used with the LAYER argument to the `setLayer` action.

IceWM tray option

  Named symbols of the domain IceWM tray option (numeric range: 0-2):

          Ignore                 (0)
          Minimized              (1)
          Exclusive              (2)

  These symbols are used with the TRAYOPTION argument to the `setTrayOption` action.

Gravity symbols

  Named symbols for window and bit gravity (numeric range: 0-10):

          ForgetGravity         (0)
          NorthWestGravity      (1)
          NorthGravity          (2)
          NorthEastGravity      (3)
          WestGravity           (4)
          CenterGravity         (5)
          EastGravity           (6)
          SouthWestGravity      (7)
          SouthGravity          (8)
          SouthEastGravity      (9)
          StaticGravity         (10)

Motif functions

          All                  (1)
          Resize               (2)
          Move                 (4)
          Minimize             (8)
          Maximize             (16)
          Close                (32)

Motif decorations

          All                  (1)
          Border               (2)
          Resize               (4)
          Title                (8)
          Menu                 (16)
          Minimize             (32)
          Maximize             (64)

EWMH window state symbols

  Named symbols of the domain EWMH state (numeric range: 0-8191):

          ABOVE                 (1)
          BELOW                 (2)
          DEMANDS_ATTENTION     (4)
          FOCUSED               (8)
          FULLSCREEN            (16)
          HIDDEN                (32)
          MAXIMIZED_HORZ        (64)
          MAXIMIZED_VERT        (128)
          MODAL                 (256)
          SHADED                (512)
          SKIP_PAGER            (1024)
          SKIP_TASKBAR          (2048)
          STICKY                (4096)

# EXAMPLES

List all workspace names:

        icesh listWorkspaces

Example output:

        workspace #0: `main'
        workspace #1: `web'
        workspace #2: `doc'
        workspace #3: `dev'

Close terminal work and activate terminal fun.

        icesh -c work.XTerm close -a -c fun.XTerm activate

Print opacity for all xterms.

        icesh -c XTerm opacity

Change opacity for all xterms.

        icesh -c XTerm opacity 84

Move all windows on workspace "Top" to the current workspace.

        icesh -W "Top" setWorkspace "this"

Restore all hidden clients, minimize all clients on the current workspace and activate Firefox.

        icesh -S hidden restore -a -W "this" minimize -a -c Firefox activate

Resize the focused window to occupy the right half of the desktop area.

        icesh -f sizeto 49% 100% sync top sync right sync raise activate

Toggle the frame border of the focused window.

        if icesh -f motif | grep -q 'decor:$'; then \
            icesh -f motif decor All; else icesh -f motif decor ""; fi

# ENVIRONMENT

DISPLAY

  The default display.

# COMPLIANCE

While icesh is largely compliant with the GNOME WinWM/WMH specification, it only minimally supports NetWM/EWMH. Some commands, like tray options and manager actions, are specific to IceWM.

# SEE ALSO

icewm(1), wmctrl(1), xdotool(1), xprop(1), xwininfo(1).

# BUGS

icesh had no known bugs at the time of release. Please report bugs for current versions to the source code repository at https://github.com/bbidulock/icewm/issues.

# AUTHOR

Brian Bidulock mailto:bidulock@openss7.org.

See --copying for full copyright notice and copying permissions.

# LICENSE

IceWM is licensed under the GNU Library General Public License. See the COPYING file in the distribution or use the --copying flag to display copying permissions.

User Commands