<?xml version="1.0" encoding="UTF-8" ?>
<!-- $Id$ -->
<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
  "../docbook-xml/docbookx.dtd"
[
<!ENTITY % myents SYSTEM "../fvwm.ent" >
%myents;
]>


<section id='TitleStyle'>
<title>TitleStyle</title>

<cmdsynopsis>
	<command>TitleStyle</command
	><arg choice='opt'
		><replaceable>justification</replaceable
	></arg
	><arg choice='opt'
		>Height <optional
			><replaceable>num</replaceable
		></optional
	></arg
	><arg choice='opt'
		>MinHeight <optional
			><replaceable>num</replaceable
		></optional
	></arg>
</cmdsynopsis>

<para>Sets attributes for the title-bar.  Justifications can be
<fvwmopt cmd="TitleStyle" opt="Centered"/>,
<fvwmopt cmd="TitleStyle" opt="RightJustified"/> or
<fvwmopt cmd="TitleStyle" opt="LeftJustified"/>.
<fvwmopt cmd="TitleStyle" opt="Height"/>
sets the title bar's height to an amount in pixels.
<fvwmopt cmd="TitleStyle" opt="MinHeight"/>
sets the minimal height in pixels of the title bar.
Defaults are
<emphasis remap='I'>Centered</emphasis>,
the window's font height and no minimal height.
To reset the font height to the
default value, omit the
<replaceable>num</replaceable>
argument after the
<emphasis remap='I'>Height</emphasis>
keyword. The
<emphasis remap='I'>MinHeight</emphasis>
height is reset by
<emphasis remap='I'>Height</emphasis>
or if given with no argument.
Example:</para>

<programlisting>
TitleStyle LeftJustified Height 24
</programlisting>


<cmdsynopsis>
	<command>TitleStyle</command
	><arg choice='opt'
		><replaceable>state</replaceable
	></arg
	><arg choice='opt'
		><replaceable>style</replaceable
	></arg
	><arg choice='opt'
		>-- <arg choice='plain' rep='repeat'
			><optional>!</optional
			><replaceable>flag</replaceable
		></arg
	></arg>
</cmdsynopsis>


<para>Sets the style for the title-bar.
See also
<fvwmref cmd="AddTitleStyle"/> and <fvwmref cmd="ButtonStyle" />
<replaceable>state</replaceable>
can be one of "<fvwmref cmd="ButtonStyle" opt="ActiveUp"/>",
"<fvwmref cmd="ButtonStyle" opt="ActiveDown"/>",
"<fvwmref cmd="ButtonStyle" opt="InactiveUp"/>",
or "<fvwmref cmd="ButtonStyle" opt="InactiveDown"/>".  Shortcuts like
"<fvwmref cmd="ButtonStyle" opt="Active"/>" and
"<fvwmref cmd="ButtonStyle" opt="Inactive"/>" are
allowed.  The states with the "Toggled" prefix are allowed too,
the title itself does not use "Toggled" states, but these states
are used for the buttons with
<fvwmref cmd="ButtonStyle"/>
<fvwmref cmd="ButtonStyle" opt="UseTitleStyle" />.
If
<replaceable>state</replaceable>
is omitted, then the
<replaceable>style</replaceable>
is added to every state.  If parentheses are placed around the
<replaceable>style</replaceable> and <replaceable>flags</replaceable>,
then multiple state definitions can be given per line.
<replaceable>style</replaceable>
can be omitted so that flags can be set while not destroying the
current style.</para>

<para>If a
'!'
is prefixed to any
<replaceable>flag</replaceable>,
its behavior is negated.  Valid flags for each state include
<fvwmref cmd="ButtonStyle" opt="Raised"/>,
<fvwmref cmd="ButtonStyle" opt="Flat"/> and 
<fvwmref cmd="ButtonStyle" opt="Sunk"/>
(these are mutually exclusive).  The default is
<fvwmref cmd="ButtonStyle" opt="Raised"/>.
See the note in
<fvwmref cmd="ButtonStyle"/>
regarding the "<fvwmref cmd="ButtonStyle" opt="ActiveDown"/>" state.  Examples:</para>

<programlisting>
TitleStyle ActiveUp HGradient 16 navy black
TitleStyle \
	ActiveDown (Solid red -- flat) \
	Inactive (TiledPixmap wood.xpm)
TitleStyle \
	ActiveUp (-- Flat) \
	ActiveDown (-- Raised) \
	InactiveUp (-- Flat) \
	InactiveDown (-- Sunk)
</programlisting>

<para>This sets the "ActiveUp" state to a horizontal gradient, the
"ActiveDown" state to solid red, and the "Inactive" states to a
tiled wood pixmap. Finally, "ActiveUp" and "InactiveUp" are set
to look flat, while "ActiveDown" set to be sunk (the
<fvwmref cmd="ButtonStyle" opt="Raised"/>
flag for the "ActiveDown" state causes it to appear sunk due to
relief inversion), and "InactiveDown" is set to look raised. An
example which sets flags for all states:</para>

<programlisting>
TitleStyle -- flat
</programlisting>

<para>For a flattened look:</para>

<programlisting>
TitleStyle -- flat
<fvwmref cmd="ButtonStyle"/> <fvwmref cmd="All"/> Active (-- flat) Inactive (-- flat)
</programlisting>


<para><emphasis remap='B'>TitleStyle</emphasis>
accepts all the
<fvwmref cmd="ButtonStyle"/>
 styles and arguments:</para>

<para><fvwmref cmd="ButtonStyle" opt="Simple"/>,
<fvwmref cmd="ButtonStyle" opt="Default"/>,
<fvwmref cmd="ButtonStyle" opt="Solid"/>,
<fvwmref cmd="ButtonStyle" opt="Colorset"/>,
<fvwmref cmd="ButtonStyle" opt="Vector"/>,
<fvwmref cmd="ButtonStyle" opt="?Gradient"/>,
<fvwmref cmd="ButtonStyle" opt="Pixmap"/>,
<fvwmref cmd="ButtonStyle" opt="AdjustedPixmap"/>,
<fvwmref cmd="ButtonStyle" opt="ShrunkPixmap"/>,
<fvwmref cmd="ButtonStyle" opt="StretchedPixmap"/>,
<fvwmref cmd="ButtonStyle" opt="TiledPixmap"/>,
<fvwmref cmd="ButtonStyle" opt="MiniIcon"/>.</para>

<para>See the
<fvwmref cmd="ButtonStyle"/>
command for a description of all these styles and their arguments.</para>

<para>In addition to these styles
<emphasis remap='B'>TitleStyle</emphasis>
accepts a powerful
<fvwmopt cmd="TitleStyle" opt="MultiPixmap"/>
option. This allows you to specify different pixmaps, colorsets or
colors for different parts of the titlebar. Some of them are tiled or
stretched to fit a particular space; others are discrete "transition"
images. The definable
<fvwmref cmd="ButtonStyle" opt="sections"/>
are:</para>

<variablelist>
	<varlistentry>
		<term><fvwmopt cmd="TitleStyle" opt="Main"/></term>
		<listitem><para>The full titlebar</para></listitem>
	</varlistentry>
	<varlistentry>
		<term><fvwmopt cmd="TitleStyle" opt="LeftMain"/></term>
		<listitem><para>Left of title text</para></listitem>
	</varlistentry>
	<varlistentry>
		<term><fvwmopt cmd="TitleStyle" opt="RightMain"/></term>
		<listitem><para>Right of title text</para></listitem>
	</varlistentry>
	<varlistentry>
		<term><fvwmopt cmd="TitleStyle" opt="UnderText"/></term>
		<listitem><para>Underneath title text</para></listitem>
	</varlistentry>
	<varlistentry>
		<term><fvwmopt cmd="TitleStyle" opt="LeftOfText"/></term>
		<listitem><para>just to the left of the title text</para></listitem>
	</varlistentry>
	<varlistentry>
		<term><fvwmopt cmd="TitleStyle" opt="RightOfText"/></term>
		<listitem><para>just to the right of the title text</para></listitem>
	</varlistentry>
	<varlistentry>
		<term><fvwmopt cmd="TitleStyle" opt="LeftEnd"/></term>
		<listitem><para>at the far left end of the titlebar
  (just after left buttons if any)</para></listitem>
	</varlistentry>
	<varlistentry>
		<term><fvwmopt cmd="TitleStyle" opt="RightEnd"/></term>
		<listitem><para>at the far right end of the titlebar
			(just before right buttons if any)</para></listitem>
	</varlistentry>
	<varlistentry>
		<term><fvwmopt cmd="TilteStyle" opt="Buttons"/></term>
		<listitem><para>under buttons in case of
		    <fvwmopt cmd="ButtonStyle" opt="UseTitleStyle"/>
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term><fvwmopt cmd="TitleStyle" opt="LeftButtons"/></term>
		<listitem><para>under left buttons in case of
		    <fvwmopt cmd="ButtonStyle" opt="UseTitleStyle"/>
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term><fvwmopt cmd="TitleStyle" opt="RightButtons"/></term>
		<listitem><para>under right buttons in case of
		    <fvwmopt cmd="ButtonStyle" opt="UseTitleStyle"/>
		</para></listitem>
	</varlistentry>
</variablelist>

<para>None of these are mandatory except for
<emphasis>Main</emphasis>
(or, if you do not define
<emphasis>Main</emphasis>
you must define both
<emphasis>LeftMain</emphasis> and <emphasis>RightMain</emphasis>).
If no
<emphasis>Buttons</emphasis>
pixmaps are defined and
<fvwmref cmd="ButtonStyle" opt="UseTitleStyle"/>
is specified for one or more buttons,
<emphasis>Main</emphasis>,
<emphasis>LeftMain</emphasis> or <emphasis>RightMain</emphasis>
are used as appropriate.</para>

<para>The syntax for this style type is:</para>

<programlisting>
MultiPixmap section style arg, ...
</programlisting>

<para>continuing for whatever you want to define. The
<replaceable>style</replaceable>
can be either
<fvwmref cmd="ButtonStyle" opt="TiledPixmap"/>, <fvwmref cmd="ButtonStyle" opt="AdjustedPixmap"/>, <fvwmref cmd="ButtonStyle" opt="Colorset"/> or <fvwmref cmd="ButtonStyle" opt="Solid"/>.
See the
<fvwmref cmd="ButtonStyle"/>
command for the description of these styles.
In the case of a transition section,
<emphasis>LeftEnd</emphasis>, <emphasis>LeftOfText</emphasis>,
<emphasis>RightOfText</emphasis> or <emphasis>RightEnd</emphasis>,
<fvwmref cmd="ButtonStyle" opt="AdjustedPixmap"/>
only resize the pixmap in the "y" direction. For the
<fvwmref cmd="ButtonStyle" opt="Colorset"/> and <fvwmref cmd="ButtonStyle" opt="Solid"/>
styles a width of the half of the title bar height is assumed
for the transition sections.</para>

<para>An example:</para>

<programlisting>
MultiPixmap Main AdjustedPixmap foo.xpm, \
            UnderText TiledPixmap bar.xpm, \
            Buttons <fvwmref cmd="ButtonStyle" opt="Colorset"/> 2
</programlisting>

<para>Note that the old syntax is still supported: if the style is omitted,
<fvwmref cmd="ButtonStyle" opt="TiledPixmap"/>
is assumed and adding "(stretched)" between the section and the
file name implies
<fvwmref cmd="ButtonStyle" opt="AdjustedPixmap"/>.</para>

</section>