=pod

=head1 NAME

 icesh - control properties of windows

=head1 SYNOPSIS

=over

=item B<icesh> [I<OPTIONS>] I<ACTIONS>

=back

=head1 DESCRIPTION

B<icesh> provides commands for use by shell scripts that affect a
window's state, similar to L<wmctrl(1)> or L<xdotool(1)>, except
mostly limited to GNOME WinWM/WMH properties
and B<icewm(1)> specific commands.

=head1 OPTIONS

B<icesh> recognizes the following options:

=head2 COMMAND OPTIONS

A command option specifies the window or windows to which subsequent
arguments apply. If no command option is given, but an argument
does require a window then a selection crossbar is invoked to select
the desired window interactively. Some arguments do not require this.

=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<-c>, B<-class> I<WM_CLASS>

Specifies the window manager class, I<WM_CLASS>, for which the action
applies.  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<-r>, B<-root>

Is equivalent to B<-window> B<root>.

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

Is equivalent to B<-window> B<focus>.

=back

=head2 GENERAL OPTIONS

=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 ARGUMENTS

B<icesh> accepts the following arguments:

=over

=item B<ACTIONS> ::= I<ACTION> [I<ACTION>]*

Actions can be one of:

=over

=item B<setIconTitle> I<TITLE>

Set the icon title for the specified window to I<TITLE>.

=item B<getIconTitle>

Prints the icon title for the specified window.

=item B<setWindowTitle> I<TITLE>

Set the window title for the specified window to I<TITLE>

=item B<getWindowTitle>

Prints the window title for the specified window.

=item B<setGeometry> I<GEOMETRY>

Set the window geometry for the specified window to I<GEOMETRY>.

=item B<getGeometry>

Prints the window geometry for the specified window.

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

Set the GNOME window state for the specified window to I<STATE>.  Only
the bits selected by I<MASK> are affected.  I<STATE> and I<MASK> are
expressions of the domain GNOME window state.  See L</GNOME window
state>, below, for I<STATE> and I<MASK> symbols.

=item B<toggleState> I<STATE>

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

=item B<getState>

Prints the GNOME window state for the specified window.

=item B<setHints> I<HINTS>

Set the GNOME window hints for the specified window to I<HINTS>.  See
L</GNOME window hints>, below, for I<HINTS> symbols.

=item B<getHints>

Prints the GNOME window hints for the specified window.

=item B<setLayer> I<LAYER>

Moves the specified window to another GNOME window layer.  See
L</GNOME window layer>, below, for I<LAYER> symbols.

=item B<getLayer>

Prints the GNOME window layer for the specified window.

=item B<setWorkspace> I<WORKSPACE>

Moves 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.

=item B<getWorkspace>

Prints the workspace for the specified window.

=item B<listWorkspaces>

Lists the names of all workspaces.

=item B<setTrayOption> I<TRAYOPTION>

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

=item B<getTrayOption>

Prints the IceWM tray option for the specified window.

=back

The following actions do not require a window or class command option:

=over

=item B<check>

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

=item B<clients>

Lists all managed client windows, their titles and geometries.

=item B<shown>

Lists all managed client windows for the current desktop,
their titles and geometries.

=item B<windows>

Lists all toplevel windows, their titles and geometries.

=item B<logout>

Ask IceWM to execute the C<LogoutCommand>.

=item B<reboot>

Ask IceWM to execute the C<RebootCommand>.

=item B<shutdown>

Ask IceWM to execute the C<ShutdownCommand>.

=item B<cancel>

Ask IceWM to cancel the logout/reboot/shutdown.

=item B<about>

Ask IceWM to show the about window.

=item B<windowlist>

Ask IceWM to show the window list window.

=item B<restart>

Ask IceWM to restart.

=item B<suspend>

Ask IceWM to 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

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

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

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)
    All                 (1023)

These symbols are used with the I<MASK> and I<STATE> arguments to the
C<setState> and C<toggleState> actions.

=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

=back

=head1 USAGE

The purpose of B<icesh> is to provide commands that can be used from a
shell script (see L<sh(1)>) to affect the state, geometry and hints
associated with a window, or to list and parse information about
existing windows.

It should be noted that B<icesh> works on any window manager that is
compliant with the GNOME WinWM/WMH specification.  Some commands, like
C<setTrayOption> and the actions, however, are IceWM specific.

=head1 EXAMPLES

The following command lists all workspace names:

    icesh listWorkspaces

Example output:

    workspace #0: `main'
    workspace #1: `web'
    workspace #2: `doc'
    workspace #3: `dev'
    workspace #4: `scr'
    workspace #5: `gfx'
    workspace #6: `misc'
    workspace #7: `'

=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 does not support NetWM/EWMH.

=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 HISTORY

B<icesh> is historical and deprecated.  The command only supports
the GNOME WinWM/WMH specification and IceWM specific commands.  Unlike
L<wmctrl(1)> and L<xdotool(1)>, support for NetWM/EWMH was never included.
For most of the supported commands, L<wmctrl(1)> and L<xdotool(1)>
are quite capable of performing the necessary functions and more.

=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:
