Ubuntu Manpage: icesh - control window properties and the IceWM window manager

NAME

        icesh - control window properties and the IceWM window manager

SYNOPSIS

       icesh OPTIONS|ACTIONS+

DESCRIPTION

       icesh  provides 88 commands to change or query a window's state, and to interact with the icewm(1) window
       manager. Command arguments are called actions. Window actions operate on a selection of  windows.   icesh
       has  several  options  to  select  and filter windows.  Options and actions can be interspersed. They are
       processed and evaluated one after another from left to right. Therefore, an  option  can  only  affect  a
       subsequent  action,  but  not  a  previous  one.  Because  of  this, an action can operate on a different
       selection of windows than a previous action, if it is preceded by a new  select  option.  In  combination
       with  filter  options,  this gives icesh its expressive power. Use it in icewm-keys(5) to define your own
       window management hotkeys.

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 clients of the window manager.

-s, -shown
Selects all currently visible clients of the window manager.

-t, -top
Selects all toplevel windows from the display unconditionally.

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 (see below) or a layer
number. If LAYER starts with an exclamation mark then the filtering is inverted.

-P, -Property PROP
Filters clients by property. Clients which have a property PROP are selected. 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 and is explained 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. 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
Close the window.

kill
Terminate 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.

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. PROPERTY can be a string, a window, or a list
of one or more atoms or cardinals.

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.

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.

colormaps
Monitor which colormap is installed.

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)

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

ENVIRONMENT

       The following environment variables are examined by icesh:

       DISPLAY
           The display to use if the -display option is unspecified.

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.

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.

icewm 1.6.4                                        2020-02-16                                           ICESH(1)