=pod

=head1 NAME

 icesh - control properties of windows

=head1 SYNOPSIS

=over

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

=item B<icesh> {B<-h>|B<--help>}

=item B<icesh> {B<-V>|B<--version>}

=item B<icesh> {B<-C>|B<--copying>}

=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 more
limited, specifically for B<icewm(1)>, and limited to affecting GNOME
WinWM/WMH properties.

=head1 OPTIONS

B<icesh> recognizes the following options:

=head2 COMMAND OPTIONS

Command options are mutually exclusive.  Only one command option can be
specified per invocation.  If no command option is specified, action
argument parsing and processing is performed.

=over

=item B<-display> I<DISPLAY>

Specifies the X11 I<DISPLAY> to use.  When unspecified, defaults to the
$DISPLAY environment variable.

=item 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.
When no I<WINDOW_ID> or I<WM_CLASS> is specified, a selection crossbar
is invoked to select the desired window.

=item 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.
When no I<WINDOW_ID> or I<WM_CLASS> is specified, a selection crossbar
is invoked to select the desired window.

=back

=head2 GENERAL OPTIONS

=over

=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<setWindowTitle> I<TITLE>

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

=item B<setGeometry> I<GEOMETRY>

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

=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 I<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<setHints> I<HINTS>

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

=item B<setLayer> I<LAYER>

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

=item B<setWorkspace> I<WORKSPACE>

Moves the specified window to another workspace.  Select the root
window to change the current workspace.

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

=back

=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.  The C<setTrayOption>
action; however, is IceWM specific.

=head1 EXAMPLES

The following command will list all the workspaces associated with the
root window after a window (any window) is selected:

    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 set or examined by B<icesh>:

=over

=item B<DISPLAY>

When the B<-display> option is not specified, the C<DISPLAY> environment
variable is consulted to determine the display.

=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 originally (and
still) only supported the GNOME WinWM/WMH specification.  Unlike
L<wmctrl(1)> and L<xdotool(1)>, NetWM/EWMH support was never included.
Except for the C<setTrayOption> command, 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:
