path: root/doc/fluxbox-apps.5.in

'\" t
.\"     Title: fluxbox-apps
.\"    Author: Jim Ramsay <i.am@jimramsay.com>
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 28 October 2011
.\"    Manual: Fluxbox Manual
.\"    Source: fluxbox-apps.txt
.\"  Language: English
.\"
.TH "FLUXBOX\-APPS" "5" "28 October 2011" "fluxbox\-apps\&.txt" "Fluxbox Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
fluxbox-apps \- per\-window attribute configuration for fluxbox(1)
.SH "SYNOPSIS"
.sp
~/\&.fluxbox/apps
.SH "SYNTAX"
.sp
Variable parameters are shown in emphasis: \fIargument\fR
.sp
All other characters shown are required verbatim\&. Whitespace is only required to delimit words, but it is fine to add more whitespace\&.
.SH "DESCRIPTION"
.sp
It is possible to force an application to always have the same dimensions, position, and other settings when it is first launched\&. These settings are saved in the \(oqapps\(cq file\&.
.sp
Most simple settings can be saved using the \(lqRemember\&...\(rq submenu of the window menu, which can usually be opened with a right\-click on the titlebar\&. More advanced features require manually editing the \(oqapps\(cq file\&. This may include using \fBGROUP SECTIONS\fR to set up automatic window tab groups\&.
.sp
You do not need to \(lqreload\(rq fluxbox after editing the apps file, the changes should be rescanned when the next window is opened\&.
.sp
The file is made up of two main types of sections, apps and groups, detailed below\&.
.SH "APP SECTIONS"
.sp
\fB[app]\fR sections provide settings for individual application windows\&.
.PP
These sections begin with a line of the format
.RS 4

\fB[app]\fR
\fB(\fR\fIpattern\fR\fB)\fR
\fB{\fR\fIcount\fR\fB}\fR
.RE
.sp
The \fIpattern\fR can be one or more patterns which match windows\&. For more details, see \fBCLIENT PATTERNS\fR\&. If you specify more than one \fIpattern\fR, they must ALL match for the settings to be applied\&.
.sp
The \fB{\fR\fIcount\fR\fB}\fR is optional\&. If specified, then the entry will only match at most that many windows at any time\&. If omitted, the default is to apply the settings to all matching windows\&.
.sp
This opening \fB[apps]\fR line is followed by any number of settings for the application\&. See \fBSETTINGS\fR for more details\&.
.PP
Each of these sections ends with the single line
.RS 4

\fB[end]\fR
.RE
.SH "GROUP SECTIONS"
.sp
The primary purpose of \fB[group]\fR sections is to group windows together\&. All windows in a group will be tabbed together automatically\&.
.PP
These sections begin with a line of the format
.RS 4

\fB[group]\fR
\fB(\fR\fIpattern\fR\fB)\fR
.RE
.sp
Where the \fIpattern\fR item is optional\&. If specified, this pattern must match for the group to take effect\&. It is common to use non\-window\-specific patterns such as \fB(workspace)\fR here\&. See \fBCLIENT PATTERNS\fR for more details\&.
.sp
This is followed by any number of \fB[app]\fR lines\&. These have a similar format to the \fB[app]\fR section detailed above in \fBAPP SECTIONS\fR, but do not contain any settings and do not have an associated \fB[end]\fR line\&.
.PP
Like this
.RS 4

\fB[app]\fR
\fB(\fR\fIpattern\fR\fB)\fR
.RE
.sp
This section may also contain settings that are applied to every window in the group\&. See the \fBSETTINGS\fR section for details\&.
.PP
As with \fB[app]\fR sections, each of these sections ends with the single line
.RS 4

\fB[end]\fR
.RE
.SH "SETTINGS"
.sp
These settings may be stored in the \(oqapps\(cq file\&. A settings line must appear inside either an \fB[app]\fR or \fB[group]\fR section\&.
.PP
The general format is
.RS 4

\fB[\fR\fIsetting\fR\fB]\fR
\fB{\fR\fIvalue\fR\fB}\fR
.RE
.sp
All allowed values are described below, except for \fIbool\fR which can simply have the value \fByes\fR or \fBno\fR, which enables or disables the associated setting, respectively\&.
.PP
\fB[Workspace]\fR {\fInumber\fR}
.RS 4
Forces the application to open on the
\fInumber\fR
workspace specified\&. Workspaces are set by number, beginning with 0\&.
.RE
.PP
\fB[Jump]\fR {\fIbool\fR}
.RS 4
Changes the active workspace to the remembered one when the application is opened\&. This is only useful when used in conjunction with
\fI[Workspace]\fR\&. See
\fBEXAMPLES\fR\&.
.RE
.PP
\fB[Head]\fR {\fInumber\fR}
.RS 4
Forces the application to open on the
\fInumber\fR
head specified (Xinerama only)\&.
.RE
.PP
\fB[Layer]\fR {\fInumber\fR}
.RS 4
Specify the layer to open the window on (by number)\&. Each layer has a number\&. The named ones are: 2\-AboveDock, 4\-Dock, 6\-Top, 8\-Normal, 10\-Bottom, 12\-Desktop\&.
.RE
.PP
\fB[Dimensions]\fR {\fIwidth[%]\fR \fIheight[%]\fR}
.RS 4
Opens the application with the specified
\fIwidth\fR
and
\fIheight\fR, in pixels\&. If the value is given in percent, then the window size will be based on the current screen\(cqs size\&.
.RE
.PP
\fB[Position]\fR (\fIanchor\fR) {\fIX[%]\fR \fIY[%]\fR}
.RS 4
Position the application at a particular spot\&. By default the upper\-left corner is placed at screen coordinates (\fIX\fR,\fIY\fR)\&. If you specify an
\fIanchor\fR, say BottomRight, then the lower\-right corner of the window is positioned (\fIX\fR,\fIY\fR) pixels from the lower\-right corner of the screen\&. If the value is given in percent, then the coordinates will be based on the current screen\(cqs size\&.
.PP
\fIanchor\fR may be set to one of:
.RS 4

\fBTopLeft Left BottomLeft Top Center Bottom TopRight Right BottomRight\fR
.RE
.RE
.PP
\fB[Deco]\fR {\fIvalue\fR}
.RS 4
.PP
Specify the decoration state\&. There are several predefined \fIvalue\fR sets:
.RS 4
.PP
\fBNORMAL\fR
.RS 4
Standard decorations
.RE
.PP
\fBNONE\fR
.RS 4
No decorations
.RE
.PP
\fBBORDER\fR
.RS 4
Like NONE except keep the X window border
.RE
.PP
\fBTAB\fR
.RS 4
Like BORDER except keep external tabs (if enabled)
.RE
.PP
\fBTINY\fR
.RS 4
Titlebar with only an iconify button
.RE
.PP
\fBTOOL\fR
.RS 4
Titlebar only
.RE
.sp
The
\fIvalue\fR
may also be a bitmask for finer\-grained control\&. The bits are, from (1<<0) to (1<<10): Titlebar, Handle/Grips, Border, Iconify Button, Maximize Button, Close Button, Menu Button, Sticky Button, Shade Button, External Tabs, Focus Enabled\&.
.RE
.RE
.PP
\fB[Shaded]\fR {\fIbool\fR}
.RS 4
Whether the window is Shaded (rolled\-up) or not\&.
.RE
.PP
\fB[Tab]\fR {\fIbool\fR}
.RS 4
Whether the window has tabs enabled\&.
.RE
.PP
\fB[FocusNewWindow]\fR {\fIbool\fR}
.RS 4
If enabled, a new window will grab X focus as soon as it is opened\&. If disabled, a new window will not grab X focus as soon as it is opened\&.
.RE
.PP
\fB[FocusHidden]\fR {\fIbool\fR}
.RS 4
If enabled, the window will not appear in
\fINextWindow\fR/\fIPrevWindow\fR
lists\&.
.RE
.PP
\fB[IconHidden]\fR {\fIbool\fR}
.RS 4
If enabled, the window will not appear in the icon area of the toolbar\&.
.RE
.PP
\fB[Hidden]\fR {\fIbool\fR}
.RS 4
A shortcut for setting both
\fBFocusHidden\fR
and
\fBIconHidden\fR
at the same time\&.
.RE
.PP
\fB[Sticky]\fR {\fIbool\fR}
.RS 4
Specify if an application should be sticky (shown on all workspaces) or not\&.
.RE
.PP
\fB[Minimized]\fR {\fIbool\fR}
.RS 4
Application should start minimized
.RE
.PP
\fB[Maximized]\fR {\fIvalue\fR}
.RS 4
.PP
Application should start maximized\&. \fIvalue\fR may be:
.RS 4
.PP
\fByes\fR
.RS 4
Fully maximized
.RE
.PP
\fBhorz\fR
.RS 4
Horizontally maximized
.RE
.PP
\fBvert\fR
.RS 4
Vertically maximized
.RE
.PP
\fBno\fR
.RS 4
Not maximized
.RE
.RE
.RE
.PP
\fB[Fullscreen]\fR {\fIbool\fR}
.RS 4
Application should start in fullscreen mode (fully maximized without any decorations)\&.
.RE
.PP
\fB[Close]\fR {\fIbool\fR}
.RS 4
Save settings on close\&. By default, application settings are not updated when a window is closed\&.
.RE
.PP
\fB[Alpha]\fR {\fIvalue\fR [\fIvalue\fR]}
.RS 4
Set the alpha value for this window\&. If two values are given, they correspond to the focused and unfocused transparency, respectively\&. One number only will be used for both values\&.
\fIvalue\fR
is an integer between 0 and 255\&.
.RE
.SH "CLIENT PATTERNS"
.PP
A \fIpattern\fR looks like this
.RS 4

\fB(\fR[\fIpropertyname\fR[!]=]\fIregexp\fR\fB)\fR
\&...
.RE
.sp
Match definitions are enclosed in parentheses \fB(\fR\&...\fB)\fR, and if no \fIpropertyname\fR is given then \fBName\fR is assumed\&. The \fIregexp\fR can contain any regular expression, or the special value \fB[current]\fR, which matches the corresponding value of the currently focused window\&. See \fIregex(7)\fR for more information on acceptable regular expressions\&.
.sp
\fIpropertyname\fR is not case sensitive, whereas the \fIregexp\fR is\&.
.sp
If you specify multiple \fB(\fR\fB\fIpattern\fR\fR) arguments, this implies an AND condition \- All specified patterns must match\&.
.sp
You can use \fB=\fR to test for equality or \fB!=\fR to test for inequality\&.
.PP
The following values are accepted for \fIpropertyname\fR
.RS 4
.PP
\fBName\fR
.RS 4
A string, corresponding to the CLASSNAME property (The first field of WM_CLASS from the output of the
\fBxprop(1)\fR
utility)\&.
.RE
.PP
\fBClass\fR
.RS 4
A string, corresponding to the CLASSCLASS property (The second field of WM_CLASS from the output of the
\fBxprop(1)\fR
utility)\&.
.RE
.PP
\fBTitle\fR
.RS 4
A string, corresponding to the window title (WM_NAME from
\fBxprop(1)\fR)\&.
.RE
.PP
\fBRole\fR
.RS 4
A string, corresponding to the ROLE property (WM_WINDOW_ROLE from
\fBxprop(1)\fR)\&.
.RE
.PP
\fBTransient\fR
.RS 4
Either
\fByes\fR
or
\fBno\fR, depending on whether the window is transient (typically, a popup dialog) or not\&.
.RE
.PP
\fBMaximized\fR
.RS 4
Either
\fByes\fR
or
\fBno\fR, depending on whether the window is maximized or not\&.
.RE
.PP
\fBMaximizedHorizontal\fR
.RS 4
Either
\fByes\fR
or
\fBno\fR, depending on whether the window is maximized horizontally or not\&.
.RE
.PP
\fBMaximizedVertical\fR
.RS 4
Either
\fByes\fR
or
\fBno\fR, depending on whether the window is maximized vertically or not\&.
.RE
.PP
\fBMinimized\fR
.RS 4
Either
\fByes\fR
or
\fBno\fR, depending on whether the window is minimized (iconified) or not\&.
.RE
.PP
\fBFullscreen\fR
.RS 4
Either
\fByes\fR
or
\fBno\fR, depending on whether the window is fullscreen or not\&.
.RE
.PP
\fBShaded\fR
.RS 4
Either
\fByes\fR
or
\fBno\fR, depending on whether the window is shaded or not\&.
.RE
.PP
\fBStuck\fR
.RS 4
Either
\fByes\fR
or
\fBno\fR, depending on whether the window is sticky (on all workspaces) or not\&.
.RE
.PP
\fBFocusHidden\fR
.RS 4
Either
\fByes\fR
or
\fBno\fR, depending on whether the window has asked to be left off the focus list (or, the alt\-tab list), or not\&.
.RE
.PP
\fBIconHidden\fR
.RS 4
Either
\fByes\fR
or
\fBno\fR, depending on whether the window has asked to be left off the icon list (or, the taskbar), or not\&.
.RE
.PP
\fBUrgent\fR
.RS 4
Either
\fByes\fR
or
\fBno\fR, depending on whether the window has the urgent hint set\&.
.RE
.PP
\fBWorkspace\fR
.RS 4
A number corresponding to the workspace number to which the window is attached\&. The first workspace here is
\fB0\fR\&. You may also use
\fB[current]\fR
to match the currently visible workspace\&.
.RE
.PP
\fBWorkspaceName\fR
.RS 4
A string corresponding to the name of the workspace to which the window is attached\&.
.RE
.PP
\fBHead\fR
.RS 4
The number of the display head to which the window is attached\&. You may match this against the special value
\fB[mouse]\fR
which refers to the head where the mouse pointer currently resides\&.
.RE
.PP
\fBLayer\fR
.RS 4
The string name of the window\(cqs layer, which is one of
\fBAboveDock\fR,
\fBDock\fR,
\fBTop\fR,
\fBNormal\fR,
\fBBottom\fR,
\fBDesktop\fR
.RE
.PP
\fBScreen\fR
.RS 4
The number of the currently used
\fIscreen\fR\&. If the setup of the running xserver involves independent screens (\fInot Xinerama\fR), the $DISPLAY environment contains something like
\fI:0\&.1\fR
or
\fI:1\&.0\fR\&. The part after the dot (\fI\&.\fR) is the number of the screen\&.
.RE
.PP
\fB@XPROP\fR
.RS 4
A string, corresponding to any xproperty (Use either the
\fBxprop(1)\fR
utility or the
\fISetXProp\fR
command to set a xproperty to a window)
.RE
.RE
.PP
\fBMatches any windows with the CLASSNAME of "xterm"\fR. 
.sp
.if n \{\
.RS 4
.\}
.nf
(xterm)
.fi
.if n \{\
.RE
.\}
.PP
\fBMatches any windows with the same CLASSNAME as the currently focused window\fR. 
.sp
.if n \{\
.RS 4
.\}
.nf
(Name=[current])
.fi
.if n \{\
.RE
.\}
.PP
\fBMatches any windows on the same head as the mouse but on a different layer than the currently focused window\fR. 
.sp
.if n \{\
.RS 4
.\}
.nf
(Head=[mouse]) (Layer!=[current])
.fi
.if n \{\
.RE
.\}
.PP
\fBMatches any windows having a xproperty named FOO with "bar" in it\fR. 
.sp
.if n \{\
.RS 4
.\}
.nf
(@FOO=\&.*bar\&.*)
.fi
.if n \{\
.RE
.\}
.sp
.SH "FILES"
.PP
\fB~/\&.fluxbox/apps\fR
.RS 4
This is the default location for the application settings\&.
.RE
.SH "RESOURCES"
.PP
\fBsession\&.appsFile:\fR \fIlocation\fR
.RS 4
This may be set to override the location of the application settings\&.
.RE
.SH "EXAMPLES"
.sp
Here are some interesting and/or useful examples you can do with your apps file\&.
.sp
.if n \{\
.RS 4
.\}
.nf
# Put the first two windows which end with \*(Aqterm\*(Aq on workspace 1
[app] (name=\&.*[tT]erm) {2}
  [Workspace]   {1}
[end]

# Center kate with a specific size, and update these values when the window is
# closed\&.
[app] (name=kate)
  [Dimensions]  {1022 747}
  [Position]    (CENTER) {0 0}
  [Close]       {yes}
[end]

# When starting konqueror, jump to workspace 1 first and start it there\&.
[app] (name=konqueror)
  [Workspace]   {1}
  [Jump]        {yes}
[end]

# start all aterm without decorations
[app] (name=aterm)
  [Deco]        {NONE}
[end]

# a group with the gimp dock and toolbox
# appears on layer 4 (bottom)
[group]
  [app] (name=gimp) (role=gimp\-dock)
  [app] (name=gimp) (role=gimp\-toolbox)
  [Layer]       {4}
[end]
.fi
.if n \{\
.RE
.\}
.SH "AUTHORS"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Jim Ramsay <i\&.am at jimramsay com> (>fluxbox\-1\&.0\&.0)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Curt Micol <asenchi at asenchi com> (>fluxbox\-0\&.9\&.11)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Tobias Klausmann <klausman at users sourceforge net> (\(lafluxbox\-0\&.9\&.11)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Grubert <grubert at users sourceforge net> (fluxbox)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Matthew Hawkins <matt at mh dropbear id au> (blackbox)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Wilbert Berendsen <wbsoft at xs4all nl> (blackbox)
.RE
.SH "SEE ALSO"
.sp
fluxbox(1) xprop(1) regex(7)
.SH "AUTHOR"
.PP
\fBJim Ramsay\fR <\&i\&.am@jimramsay\&.com\&>
.RS 4
Author.
.RE