=pod

=head2 NAME

icewmhint - set IceWM hints by window class and instance

=head2 SYNOPSIS

B<icewmhint> I<CLASS>B<.>I<INSTANCE> I<OPTION> I<VALUE> ...

=head2 DESCRIPTION

B<icewmhint> is a utility for passing IceWM hints to L<icewm(1)>.
B<icewm> uses these hints for the first I<X11 client> which is
subsequently started. They take precedence over hints from
the L<icewm-winoptions(1)> file.

A hint is a triplet consisting of a I<class.instance>, an
I<IceWM winoption> and its value. Multiple hints can be given per
invocation of B<icewmhint>.

The hints are communicated over the C<_ICEWM_WINOPTHINT> property on
the root window.  B<icewmhint> appends hints to this property, while
B<icewm> removes the property after reading it.

=head2 OPTIONS

B<icewmhint> recognizes the following options:

=head2 COMMAND OPTIONS

Only one command option can be specified per invocation.  If no command
option is specified, argument parsing and processing is performed.

=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

=head2 GENERAL OPTIONS

=over

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

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

=back

=head2 ARGUMENTS

The following three arguments are required for each hint.

=over

=item I<CLASS>B<.>I<INSTANCE>

Specifies the ICCCM 2.0 B<WM_CLASS> property in terms of resource class
and resource name separated by a period (C<.>).  For example:
C<XTerm.xterm>. Just the resource class or resource name without a dot
is also acceptable, like C<XTerm> or C<xterm>.

=item I<OPTION>

Specifies the I<OPTION> to affect.

=item I<VALUE>

Gives the I<VALUE> for the option.

=back

Multiple hints can be given.

=head2 GENERAL OPTION ARGUMENTS

=over

=item B<icon> I<NAME>

Specifies the icon name for windows of I<CLASS>B<.>I<INSTANCE>.
I<NAME> should be the name of the icon.  L<icewm(1)> will use its
usual method to locate the icon.  The default is the name provided
by window manager hints.

=item B<workspace> I<WORKSPACE>

Specifies the workspace on which a window of I<CLASS>B<.>I<INSTANCE>
will be initially placed.  The default is the current workspace.
I<WORKSPACE> should be a workspace number counting from 0.

=item B<geometry> I<GEOMETRY>

Specifies the initial geometry for windows of the given
I<CLASS>B<.>I<INSTANCE>.  I<GEOMETRY> must be a geometry that can be
parsed by L<XParseGeometry(3)>.  The default is the geometry provided by
window manager hints.

=item B<order> I<NUMBER>

The sorting order of task buttons and tray icons. The default value is
zero. Increasing positive values go farther right, while decreasing
negative values go farther left. The order option applies to the task
pane, the tray pane and the system tray.

=item B<opacity> I<NUMBER>

Set the _NET_WM_WINDOW_OPACITY property if I<NUMBER> is a value between
1 and 100. I<NUMBER> is interpreted as percentage of maximum opaqueness.

=item B<layer> {I<LAYER>|I<NUMBER>}

This command option specifies the layer to be associated with a
I<CLASS>B<.>I<INSTANCE>.  The default is the C<Normal> layer.  I<VALUE>
is either a layer number or a symbolic layer name.  Symbolic
layer names are:

    Desktop     (0)  Desktop window.
    Below       (2)  Below the default layer.
    Normal      (4)  Default layer for windows.
    OnTop       (6)  Above the default layer.
    Dock        (8)  Docked windows at edge of screen.
    AboveDock  (10)  Windows above the dock.
    Menu       (12)  The layer for menu's.
    Fullscreen (14)  When fullscreen and focused.
    AboveAll   (15)  Always above anything.

=item B<tray> {B<Ignore>|B<Minimized>|B<Exclusive>|I<NUMBER>}

Specifies the tray handling to be applied to windows with
I<CLASS>B<.>I<INSTANCE>.  This option is specific to L<icewm(1)> and
sets the C<_ICEWM_TRAY> property associated with the window.
The default is C<Ignore>.  I<VALUE> can be an option number
or a symbolic name as follows:

    Ignore     (0)  only in task list.
    Minimized  (1)  icon in tray, task list unminimized.
    Exclusive  (2)  only in tray, not in task list.

=item B<frame> I<label> (default: none)

All windows with the same frame label become tabs in a single frame.

=back

=head2 FUNCTION OPTION ARGUMENTS

Specifies which functions are disabled or enabled (0/1) for windows with
I<CLASS>B<.>I<INSTANCE>.  All functions have a default value of enabled
(1) unless overridden by the application.  The Motif-like functions are
as follows:

    fClose     can be closed:        (default: 1).
    fHide      can be hidden:        (default: 1).
    fMaximize  can be maximized:     (default: 1).
    fMinimize  can be minimized:     (default: 1).
    fMove      can be moved:         (default: 1).
    fResize    can be resized:       (default: 1).
    fRollup    can be shaded:        (default: 1).

=head2 DECOR OPTION ARGUMENTS

Specifies which decorations are disabled or enabled (0/1) for windows
with I<CLASS>B<.>I<INSTANCE>.  All decor options have a default value
of enabled (1) unless overridden by the application. The Motif-like
decorations are as follows:

    dBorder    has border:           (default: 1).
    dClose     has close button:     (default: 1).
    dDepth     has depth button:     (default: 1).
    dHide      has hide button:      (default: 1).
    dMaximize  has maximize button:  (default: 1).
    dMinimize  has minimize button:  (default: 1).
    dResize    has resize grips:     (default: 1).
    dRollup    has shade button:     (default: 1).
    dSysMenu   has window menu:      (default: 1).
    dTitleBar  has title bar:        (default: 1).

=head2 FEATURE OPTION ARGUMENTS

Specifies which advanced features to be enabled/disabled (1/0) for
windows with I<CLASS>B<.>I<INSTANCE>.  All advanced features have a
default value of disabled (0) unless overridden by the application.  The
advanced features are as follows:

    allWorkspaces             on all workspaces.
    appTakesFocus             let application take focus.
    doNotCover                limits workspace if sticky.
    doNotFocus                do not focus.
    doNotManage               do not manage.
    forcedClose               no close dialog.
    fullKeys                  provided more keys.
    ignoreNoFocusHint         focus even no-input.
    ignorePagerPreview        do not show in pager preview.
    ignorePositionHint        place automatically.
    ignoreQuickSwitch         not on quick switch.
    ignoreTaskBar             not on task bar.
    ignoreUrgentHint          ignore urgent hints.
    ignoreWinList             not on window list.
    ignoreActivationMessages  only user can focus window.
    ignoreOverrideRedirect    ignore the override redirect flag.
    noFocusOnAppRaise         no focus on raise.
    noFocusOnMap              do not focus when mapped.
    noIgnoreTaskBar           on task bar.
    startClose                close the window immediately.
    startFullscreen           start full screen.
    startMaximized            start maximized.
    startMaximizedHorz        start maximized horizontal.
    startMaximizedVert        start maximized vertical.
    startMinimized            start minimized.

=head2 EXAMPLE

    # Here is how to preload an invisible background process of chromium
    # on the fourth workspace which is only visible on the Window List.

    icewmhint Chromium-browser startMinimized 1 \
              Chromium-browser workspace 3 \
              Chromium-browser ignorePagerPreview 1 \
              Chromium-browser ignorePositionHint 1 \
              Chromium-browser ignoreTaskBar 1 \
              Chromium-browser ignoreQuickSwitch 1 \
              Chromium-browser ignoreUrgentHint 1 \
              Chromium-browser noFocusOnAppRaise 1
    chromium

=head2 BUGS

Please report bugs at L<https://github.com/bbidulock/icewm/issues>.

=head2 AUTHOR

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

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

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