path: root/upstream/fedora-rawhide/man5/icewm-winoptions.5

.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "ICEWM-WINOPTIONS 5"
.TH ICEWM-WINOPTIONS 5 2024-05-20 "icewm\ 3.5.0" "Standards, Environments and Macros"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SS NAME
.IX Subsection "NAME"
.Vb 1
\& icewm\-winoptions \- IceWM window options configuration file
.Ve
.SS SYNOPSIS
.IX Subsection "SYNOPSIS"
.Vb 5
\& $ICEWM_PRIVCFG/winoptions
\& $XDG_CONFIG_HOME/icewm/winoptions
\& $HOME/.icewm/winoptions
\& /etc/icewm/winoptions
\& /usr/share/icewm/winoptions
.Ve
.SS DESCRIPTION
.IX Subsection "DESCRIPTION"
The IceWM \fIwinoptions\fR file contains settings to control
\&\fIapplication specific\fR window appearance and behavior.
For instance, they control the window border, placement and size,
the window layer, its workspace, its visibility on the task bar
and its focus behavior.
.PP
The winoptions are established when \fBicewm\fR\|(1) starts.  However,
they can be overridden later using \fBicesh\fR\|(1) or \fBicewmhint\fR\|(1).
The command \f(CW\*(C`icesh winoptions\*(C'\fR instructs icewm to reload the
\&\fIwinoptions\fR file, while \fIicewmhint\fR tunes a specific application
instance when it starts.
.SS FORMAT
.IX Subsection "FORMAT"
Each line in the file must be in one of the following formats:
.RS 4
.IP "\fINAME\fR\fB.\fR\fICLASS\fR\fB.\fR\fIOPTION\fR\fB:\fR \fIVALUE\fR" 4
.IX Item "NAME.CLASS.OPTION: VALUE"
.PD 0
.IP "\fICLASS\fR\fB.\fR\fIROLE\fR\fB.\fR\fIOPTION\fR\fB:\fR \fIVALUE\fR" 4
.IX Item "CLASS.ROLE.OPTION: VALUE"
.IP "\fINAME\fR\fB.\fR\fIROLE\fR\fB.\fR\fIOPTION\fR\fB:\fR \fIVALUE\fR" 4
.IX Item "NAME.ROLE.OPTION: VALUE"
.IP "\fICLASS\fR\fB.\fR\fIOPTION\fR\fB:\fR \fIVALUE\fR" 4
.IX Item "CLASS.OPTION: VALUE"
.IP "\fINAME\fR\fB.\fR\fIOPTION\fR\fB:\fR \fIVALUE\fR" 4
.IX Item "NAME.OPTION: VALUE"
.IP "\fIROLE\fR\fB.\fR\fIOPTION\fR\fB:\fR \fIVALUE\fR" 4
.IX Item "ROLE.OPTION: VALUE"
.IP "\fB.\fR\fIOPTION\fR\fB:\fR \fIVALUE\fR" 4
.IX Item ".OPTION: VALUE"
.RE
.RS 4
.RE
.PD
.PP
Here \fINAME\fR and \fICLASS\fR are from the \fBWM_CLASS\fR property of the
window. This can be found in the output of \f(CW\*(C`icesh \-a getClass\*(C'\fR.
.PP
While \fIROLE\fR refers to the \fBWM_WINDOW_ROLE\fR property of the window,
which is the application instance specific name. Only a minority of
windows have it. See the output of \f(CW\*(C`icesh \-a list prop WM_WINDOW_ROLE\*(C'\fR.
.PP
In rare cases, a name, class or role may contain a period. If it does,
the period should be escaped by a single backslash.
.PP
Lastly, the \fIOPTION: VALUE\fR pair refer to the options and values
described below. A line with just a dot, followed by an option/value
pair, applies to all windows.
.SS OPTIONS
.IX Subsection "OPTIONS"
There are four categories: \fIgeneral\fR, \fIfunction\fR, \fIdecor\fR and
\&\fIfeature\fR.
.SS "GENERAL OPTIONS"
.IX Subsection "GENERAL OPTIONS"
These control general characteristics of windows:
.IP "\fBicon\fR: \fINAME\fR (default: none)" 4
.IX Item "icon: NAME (default: none)"
Specifies the icon name for the window.  \fINAME\fR is the icon name, like
\&\fIutilities-terminal\fR. It can also be a file, like \fIxterm.png\fR, a full
path, or a prefix of a path without sizes or suffix.
.IP "\fBworkspace\fR: \fIWORKSPACE\fR (default: current)" 4
.IX Item "workspace: WORKSPACE (default: current)"
Specifies the default workspace for the window.  \fIWORKSPACE\fR is the
workspace number counting from zero (0).
.IP "\fBlayer\fR: {\fILAYER\fR|\fINUMBER\fR} (default: Normal)" 4
.IX Item "layer: {LAYER|NUMBER} (default: Normal)"
Specifies the default layer for the window.  Layer can be one of the
following names or a number from zero to fifteen:
.Sp
.Vb 9
\&  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\*(Aqs.
\&  Fullscreen (14)  When fullscreen and focused.
\&  AboveAll   (15)  Always above anything.
.Ve
.IP "\fBgeometry\fR \fIgeometry\fR (default: WM_SIZE_HINTS property)" 4
.IX Item "geometry geometry (default: WM_SIZE_HINTS property)"
The default geometry for the window.  This geometry should be specified
in a format that can be parsed by \fBXParseGeometry\fR\|(3):
.Sp
.Vb 1
\& [=][<width>{xX}<height>][{+\-}<xoffset>{+\-}<yoffset>]
.Ve
.Sp
The default geometry is taken from the WM_SIZE_HINTS property of the
window or else from the initial window geometry. This option overrides
the default.
.IP "\fBtray\fR: {\fBIgnore\fR|\fBMinimized\fR|\fBExclusive\fR|\fINUMBER\fR} (default: 0)" 4
.IX Item "tray: {Ignore|Minimized|Exclusive|NUMBER} (default: 0)"
The default tray option for the window.  This affects both the tray and
the task pane.  Tray can be one of the following three strings or a number
from zero (0) to two (2):
.Sp
.Vb 3
\&  Ignore     (0)  No icon is added to the tray.
\&  Minimized  (1)  Add to tray, no task when minimized.
\&  Exclusive  (2)  Add to tray, no task button.
.Ve
.IP "\fBorder\fR: \fINUMBER\fR (default: 0)" 4
.IX Item "order: NUMBER (default: 0)"
The sorting order for task buttons, tray icons, quick switch and window
list. The default value is zero. Increasing positive values go right,
while decreasing negative values go left.
.IP "\fBopacity\fR: \fINUMBER\fR (default: 0)" 4
.IX Item "opacity: NUMBER (default: 0)"
Set the _NET_WM_WINDOW_OPACITY property if \fINUMBER\fR is a value between
1 and 100. \fINUMBER\fR is interpreted as percentage of maximum opaqueness.
.IP "\fBkeyboard\fR: \fIlayout\fR (default: none)" 4
.IX Item "keyboard: layout (default: none)"
Specifies the keyboard layout to use for this window. 
The \fIlayout\fR is the name of a keyboard layout.
It can be a space-separated list of arguments to the
\&\fBsetxkbmap\fR program. Please note that \fBsetxkbmap\fR
must be installed for this to work. Also define
a default keyboard layout in \fIpreferences\fR.
.IP "\fBframe\fR: \fIlabel\fR (default: none)" 4
.IX Item "frame: label (default: none)"
All windows with the same frame label become tabs in a single frame.
.SS "FUNCTION OPTIONS"
.IX Subsection "FUNCTION OPTIONS"
Function options enable/disable (1/0) the ability to take an action on
the window.  The normal default for all options is enabled (1) unless
overridden by the application:
.PP
.Vb 7
\&  fClose:    {0|1}  can be closed.        (default: 1)
\&  fHide:     {0|1}  can be hidden.        (default: 1)
\&  fMaximize: {0|1}  can be maximized.     (default: 1)
\&  fMinimize: {0|1}  can be minimized.     (default: 1)
\&  fMove:     {0|1}  can be moved.         (default: 1)
\&  fResize:   {0|1}  can be resized.       (default: 1)
\&  fRollup:   {0|1}  can be shaded.        (default: 1)
.Ve
.SS "DECOR OPTIONS"
.IX Subsection "DECOR OPTIONS"
Decor options enable/disable (1/0) decorations on the window.  The
normal default for all options is enabled (1) unless overridden by the
application or the theme:
.PP
.Vb 10
\&  dBorder:   {0|1}  has border.           (default: 1)
\&  dClose:    {0|1}  has close button.     (default: 1)
\&  dDepth:    {0|1}  has depth button.     (default: 1)
\&  dHide:     {0|1}  has hide button.      (default: 1)
\&  dMaximize: {0|1}  has maximize button.  (default: 1)
\&  dMinimize: {0|1}  has minimize button.  (default: 1)
\&  dResize:   {0|1}  has resize grips.     (default: 1)
\&  dRollup:   {0|1}  has shade button.     (default: 1)
\&  dSysMenu:  {0|1}  has window menu.      (default: 1)
\&  dTitleBar: {0|1}  has title bar.        (default: 1)
.Ve
.SS "FEATURE OPTIONS"
.IX Subsection "FEATURE OPTIONS"
Feature options enable/disable (1/0) additional features of the window.
The normal default for all options is disabled (0) unless overridden by
the application:
.PP
.Vb 10
\&  allWorkspaces:            {1|0}  on all workspaces.
\&  appTakesFocus:            {1|0}  let application take focus.
\&  doNotCover:               {1|0}  limits workspace if sticky.
\&  doNotFocus:               {1|0}  do not focus.
\&  doNotManage:              {1|0}  do not manage.
\&  forcedClose:              {1|0}  no close confirmation dialog.
\&  fullKeys:                 {1|0}  don\*(Aqt install icewm key bindings.
\&  ignoreNoFocusHint:        {1|0}  focus even when no\-input is set.
\&  ignorePagerPreview:       {1|0}  do not show in pager preview.
\&  ignorePositionHint:       {1|0}  always let icewm place the window.
\&  ignoreQuickSwitch:        {1|0}  not on quick switch.
\&  ignoreTaskBar:            {1|0}  not on task bar.
\&  ignoreUrgentHint:         {1|0}  ignore urgent hints.
\&  ignoreWinList:            {1|0}  not on window list.
\&  ignoreActivationMessages: {1|0}  only user can focus window.
\&  ignoreOverrideRedirect:   {1|0}  ignore the override redirect flag.
\&  noFocusOnAppRaise:        {1|0}  no automatic focus on raise.
\&  noFocusOnMap:             {1|0}  do not focus when mapped.
\&  noIgnoreTaskBar:          {1|0}  always show on task bar.
\&  startClose:               {1|0}  close the window immediately.
\&  startFullscreen:          {1|0}  start full screen.
\&  startMaximized:           {1|0}  start maximized.
\&  startMaximizedHorz:       {1|0}  start maximized horizontal.
\&  startMaximizedVert:       {1|0}  start maximized vertical.
\&  startMinimized:           {1|0}  start minimized.
.Ve
.SS EXAMPLES
.IX Subsection "EXAMPLES"
This example uses the WM_WINDOW_ROLE property value \f(CW\*(C`pop\-up\*(C'\fR to deny
input focus to \fIChrome\fR pop-ups and asks to close them immediately.
.PP
.Vb 9
\&  google\-chrome.pop\-up.doNotFocus: 1
\&  google\-chrome.pop\-up.forcedClose: 1
\&  google\-chrome.pop\-up.ignorePagerPreview: 1
\&  google\-chrome.pop\-up.ignoreUrgentHint: 1
\&  google\-chrome.pop\-up.layer: Below
\&  google\-chrome.pop\-up.noFocusOnAppRaise: 1
\&  google\-chrome.pop\-up.noFocusOnMap: 1
\&  google\-chrome.pop\-up.startClose: 1
\&  google\-chrome.pop\-up.startMinimized: 1
.Ve
.PP
IceWM places dockapps in a container automatically, but for those
that fail to comply with the protocol it can also be emulated.
An emulated dockapp should appear on all workspaces, have
no decorations, and always be visible in a fixed location.
.PP
.Vb 8
\&  wmtime.wmtime.allWorkspaces: 1
\&  wmtime.wmtime.ignoreTaskBar: 1
\&  wmtime.wmtime.ignoreQuickSwitch: 1
\&  wmtime.wmtime.ignoreWinList: 1
\&  wmtime.wmtime.layer: Below
\&  wmtime.wmtime.dTitleBar: 0
\&  wmtime.wmtime.dBorder: 1
\&  wmtime.wmtime.geometry: 64x64\-74\-100
.Ve
.PP
Following shows how a shaped output-only application is shown
without titlebar and minimal functionality.
.PP
.Vb 11
\&  xeyes.tray: Exclusive
\&  xeyes.ignoreWinList: 0
\&  xeyes.ignoreTaskBar: 1
\&  xeyes.allWorkspaces: 1
\&  xeyes.dTitleBar: 0
\&  xeyes.dBorder: 0
\&  xeyes.dSysMenu: 0
\&  xeyes.dResize: 0
\&  xeyes.dClose: 0
\&  xeyes.dMinimize: 0
\&  xeyes.dMaximize: 0
.Ve
.SS FILES
.IX Subsection "FILES"
Locations for the \fIwinoptions\fR file are as follows:
.PP
.Vb 5
\& $ICEWM_PRIVCFG/winoptions
\& $XDG_CONFIG_HOME/icewm/winoptions
\& $HOME/.icewm/winoptions
\& /etc/icewm/winoptions
\& /usr/share/icewm/winoptions
.Ve
.PP
The locations are searched in the order listed; the first file found is
read and the remainder ignored.
.SS "SEE ALSO"
.IX Subsection "SEE ALSO"
\&\fBicewm\fR\|(1),
\&\fBicesh\fR\|(1),
\&\fBicewmhint\fR\|(1),
\&\fBsetxkbmap\fR\|(1),
\&\fBXParseGeometry\fR\|(3).
.SS AUTHOR
.IX Subsection "AUTHOR"
Brian Bidulock <mailto:bidulock@openss7.org>.
.SS LICENSE
.IX Subsection "LICENSE"
\&\fBIceWM\fR is licensed under the GNU Library General Public License.
See the \fICOPYING\fR file in the distribution.