=pod

=head1 NAME

icesh - control window properties and the IceWM window manager

=head1 SYNOPSIS

=over

=item B<icesh> I<OPTIONS|ACTIONS>+

=back

=head1 DESCRIPTION

B<icesh> provides 69 commands to change or query a window's state,
and to interact with the L<icewm(1)> window manager. Command arguments
are called actions. Window actions operate on a selection of windows.
B<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 B<icesh> its expressive power.

=head1 OPTIONS

B<icesh> recognizes the following options:

=head2 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 I<select> one or more client windows.
If needed, they can be repeated for successive actions.

=over

=item B<-w>, B<-window> I<WINDOW_ID>

Specifies the identifier of the window, I<WINDOW_ID>, for which the
action applies.  Special identifiers are B<root> for the root window
and B<focus> for the currently focused window.

=item B<-r>, B<-root>

Is equivalent to B<-window> B<root> and selects the root window.

=item B<-f>, B<-focus>

Is equivalent to B<-window> B<focus> and selects the focused window.

=item B<-a>, B<-all>

Selects all clients of the window manager.

=item B<-s>, B<-shown>

Selects all currently visible clients of the window manager.

=item B<-t>, B<-top>

Selects all toplevel windows from the display unconditionally.

=back

=head2 FILTER OPTIONS

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

=over

=item B<-c>, B<-class> I<WM_CLASS>

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

=item B<-l>, B<-last>

Filter clients and keep only the most recent client.

=item B<-p>, B<-pid> I<PID>

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

=item B<-m>, B<-machine> I<HOST>

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

=item B<-n>, B<-name> I<NAME>

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

=item B<-L>, B<-Layer> I<LAYER>

Filters clients by I<GNOME window layer>, which can either be a layer
name (see below) or a layer number.

=item B<-S>, B<-State> I<STATE>

Filters clients by I<GNOME window state>. Clients which have at least
a state of I<STATE> are selected.  The window state refers to details
like B<minized> or B<maximized> and is explained below.

=item B<-W>, B<-Workspace> I<WORKSPACE>

Filter clients by workspace. Workspace I<WORKSPACE> is either a
workspace name or a workspace number counting from zero.

=item B<-X>, B<-Xinerama> I<MONITOR>

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

=back

=head2 GENERAL OPTIONS

The following options are identical for every IceWM command.

=over

=item B<-d>, B<-display> I<DISPLAY>

Specifies the X11 DISPLAY.  If unspecified, defaults to B<$DISPLAY>.

=item B<-h>, B<--help>

Print a brief usage statement to F<stdout> and exit.

=item B<-V>, B<--version>

Print the program version to F<stdout> and exit.

=item B<-C>, B<--copying>

Print copying permissions to F<stdout> for the program and exit.

=back

=head1 ACTIONS

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

=head2 WINDOW ACTIONS

The following actions affect the selected window or windows.

=over

=item B<activate>

Activate the window, aka. I<to focus>.

=item B<close>

Close the window.

=item B<kill>

Terminate the window.

=item B<id>

Print window identifiers for the selected windows.

=item B<list>

Show window details, like geometry and names.

=item B<lower>

Lower the window.

=item B<raise>

Raise the window.

=item B<above>

Stack the window above others.

=item B<below>

Stack the window below others.

=item B<rollup>

Rollup the specified window.

=item B<fullscreen>

Set the window to fullscreen.

=item B<maximize>

Maximize the window.

=item B<horizontal>

Maximize the window only horizontally.

=item B<vertical>

Maximize the window only vertically.

=item B<minimize>

Minimize the window.

=item B<restore>

Restore the window to normal.

=item B<hide>

Make window hidden.

=item B<unhide>

Undo window hidden.

=item B<skip>

Don't show window on taskbar.

=item B<unskip>

Do show window on taskbar.

=item B<resize> I<WIDTH> I<HEIGHT>

Resize window to I<WIDTH> by I<HEIGHT> window units.

=item B<move> I<X> I<Y>

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

=item B<moveby> I<X> I<Y>

Displace window by I<X> I<Y> pixels.

=item B<center>

Position window in the center of the screen.

=item B<left>

Position window against the left side of the screen.

=item B<right>

Position window against the right side of the screen.

=item B<top>

Position window against the top side of the screen.

=item B<bottom>

Position window against the bottom side of the screen.

=item B<setIconTitle> I<TITLE>

Set the icon title to I<TITLE>.

=item B<getIconTitle>

Print the icon title.

=item B<setWindowTitle> I<TITLE>

Set the window title to I<TITLE>.

=item B<getWindowTitle>

Print the window title.

=item B<setGeometry> I<GEOMETRY>

Set the window geometry to I<GEOMETRY>.

=item B<getGeometry>

Print the window geometry.

=item B<setState> I<MASK> I<STATE>

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

=item B<toggleState> I<STATE>

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

=item B<getState>

Print the I<GNOME window state> for the specified window.

=item B<setHints> I<HINTS>

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

=item B<getHints>

Print the I<GNOME window hints> for the specified window.

=item B<setLayer> I<LAYER>

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

=item B<getLayer>

Print the I<GNOME window layer> for the specified window.

=item B<setWorkspace> I<WORKSPACE>

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

=item B<getWorkspace>

Print the workspace for the specified window.

=item B<opacity> [I<OPACITY>]

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

=item B<setTrayOption> I<TRAYOPTION>

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

=item B<getTrayOption>

Print the I<IceWM tray option> for the specified window.

=back

=head2 MANAGER ACTIONS

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

=over

=item B<listWorkspaces>

List the names of all workspaces.

=item B<goto> I<WORKSPACE>

Change the current workspace to I<WORKSPACE>.

=item B<workspaces> [I<COUNT>]

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

=item B<setWorkspaceName> I<INDEX> I<NAME>

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

=item B<setWorkspaceNames> I<NAME> [I<NAME>]*

Change the workspace names to the list of I<NAME>s.

=item B<desktop> [I<SHOWING>]

If I<SHOWING> is C<1> then set C<showing the desktop> mode.
If I<SHOWING> is C<0> then turn off C<showing the desktop>.
Print the current mode if I<SHOWING> is not given.

=item B<randr>

Summarize the I<RandR> configuration.

=item B<xinerama>

Summarize the I<Xinerama> configuration.

=item B<check>

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

=item B<clients>

List all managed client windows, their titles and geometries.

=item B<shown>

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

=item B<windows>

List all toplevel windows, their titles and geometries.

=item B<logout>

Let icewm execute the C<LogoutCommand>.

=item B<reboot>

Let icewm execute the C<RebootCommand>.

=item B<shutdown>

Let icewm execute the C<ShutdownCommand>.

=item B<cancel>

Let icewm cancel the logout/reboot/shutdown.

=item B<about>

Let icewm show the about window.

=item B<windowlist>

Let icewm show the window list window.

=item B<restart>

Let icewm restart itself.

=item B<suspend>

Let icewm execute the C<SuspendCommand>.

=item B<guievents>

Monitor the B<ICEWM_GUI_EVENT> property and report all changes.

=item B<colormaps>

Monitor which colormap is installed.

=item B<runonce> I<program> [I<arguments...>]

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

=back

=head2 EXPRESSIONS

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

=over

=item B<EXPRESSION> ::= I<SYMBOL> | I<EXPRESSION> { C<+> | C<|> }
I<SYMBOL>

=back

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

=over

=item I<GNOME window state>

Named symbols of the domain I<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 I<MASK> and I<STATE> arguments to the
C<setState> and C<toggleState> actions. Some additional states include:
Above, Below, Urgent and Fullscreen.

=item I<GNOME window hint>

Named symbols of the domain I<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 I<HINTS> argument to the C<setHints>
action.

=item I<GNOME window layer>

Named symbols of the domain I<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 I<LAYER> argument to the C<setLayer>
action.

=item I<IceWM tray option>

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

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

These symbols are used with the I<TRAYOPTION> argument to the
C<setTrayOption> action.

=back

=head1 EXAMPLES

List all workspace names:

    icesh listWorkspaces

Example output:

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

Close terminal work.

    icesh -c work.XTerm close

Activate terminal fun.

    icesh -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

=head1 ENVIRONMENT

The following environment variables are examined by B<icesh>:

=over

=item B<DISPLAY>

The display to use if the B<-display> option is unspecified.

=back

=head1 COMPLIANCE

While B<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.

=head1 SEE ALSO

L<icewm(1)>, L<wmctrl(1)>, L<xdotool(1)>, L<xprop(1)>, L<xwininfo(1)>.

=head1 BUGS

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

=head1 AUTHOR

Brian Bidulock L<mailto:bidulock@openss7.org>.

See B<--copying> for full copyright notice and copying permissions.

=head1 LICENSE

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

=cut

# vim: set sw=4 tw=72 nocin spell spelllang=en_ca:
