workspace/doc/kdm/theme-ref.docbook

   1 <chapter id="kdm-themes">
   2   <title>Creating themes for the &kdm; greeter</title>
   3
   4   <para>
   5     This section describes the creation of themes for the themed
   6     greeter.  For examples including screenshots, see the installed
   7     standard themes and the themes from
   8     <ulink type="http" url="http://www.kde-look.org/index.php?xcontentmode=40">
   9     the theme website</ulink>.
  10   </para>
  11
  12   <sect1 id="theme-overview">
  13     <title>Theme Overview</title>
  14
  15     <para>
  16       &kdm; themes can be created by creating an XML file that follows the
  17       specification in
  18       <filename>$<envar>KDEDIR</envar>/share/apps/doc/kdm/greeter.dtd</filename>.
  19       Theme files are stored in the directory
  20       <filename class="directory">$<envar>KDEDIR</envar>/share/apps/kdm/themes/<replaceable>theme_name</replaceable></filename>.
  21       The theme directory should contain a file called
  22       <filename>KdmGreeterTheme.desktop</filename> which has similar format
  23       to other <filename class="extension">.desktop</filename> files and looks
  24       like:
  25
  26 <programlisting>
  27 [KdmGreeterTheme]
  28 Greeter=circles.xml
  29 Name=Circles
  30 Description=Theme with blue circles
  31 Author=Bond, James Bond
  32 Copyright=(c) 2002 Bond, James Bond
  33 Screenshot=screenshot.png
  34 </programlisting>
  35     </para>
  36
  37     <para>
  38       The <literal>Name</literal>, <literal>Description</literal>,
  39       <literal>Author</literal> and <literal>Copyright</literal> fields can
  40       be translated just like in other
  41       <filename class="extension">.desktop</filename> files. All the files
  42       that are mentioned should be in the theme directory itself.  The
  43       <literal>Screenshot</literal> field points to a file which should be a
  44       200x150 screenshot of the theme in action (it is OK not to have one,
  45       but it makes it nicer for the user).  The <literal>Greeter</literal>
  46       entry points to an XML file that contains the description of the theme.
  47     </para>
  48
  49     <!--
  50     <para>
  51       Once a theme is installed, it can be tested with the
  52       <command>gdmthemetester</command> program.  This program assumes that
  53       the X server supports a nested server command.  This command takes two
  54       arguments, first the environment that should be used.  The environment
  55       can be one of the following values: console, console-timed, flexi,
  56       remote-flexi, or xdmcp.  The &quot;console&quot; option tests the
  57       theme as it would be shown on an attached display.  The
  58       &quot;console-timed&quot; option tests the theme as it would be shown
  59       on an attached display with timed login enabled.  The &quot;flexi&quot;
  60       option tests the theme as it would be shown on an attached flexible
  61       display (such as started via Xnest).  Finally, the &quot;xdmcp&quot;
  62       option tests the theme as it would be shown for remote XDMCP
  63       displays.  The second argument is the theme name.  For example, to
  64       test how the circles theme would look in XDMP remote display mode,
  65       you would run the following command:
  66     </para>
  67
  68 <cmdsynopsis>
  69   <command>gdmthemetester</command> <arg>xdmcp</arg> <arg><replaceable>circles</replaceable></arg>
  70 </cmdsynopsis>
  71
  72     <para>
  73       When developing a theme, make sure to test all the environments, and
  74       make sure to test how the caps lock warning looks by pressing the caps
  75       lock key.  Running <command>gdmthemetester</command> is also a good way
  76       to take screenshots of &kdm; themes.  Simply take a screenshot of the
  77       theme running in the nested display window.  This can be done in GNOME
  78       by focusing the nested login window and pressing Alt-PrintScreen.
  79     </para>
  80     -->
  81
  82     <para>
  83       Once a theme has been fully tested, make a tarball that contains
  84       the directory as it would be installed to the
  85       <filename class="directory">$<envar>KDEDIR</envar>/share/apps/kdm/themes</filename>
  86       directory. This is the standard format for distributing &kdm; themes.
  87     </para>
  88   </sect1>
  89
  90   <sect1 id="theme-format">
  91     <title>Detailed Description of Theme XML format</title>
  92
  93     <sect2 id="greeter-tag">
  94       <title>Toplevel Node</title>
  95
  96       <para>
  97         &kdm; themes are XML files with the &lt;greeter&gt; tag at their root.
  98         The toplevel node is an <link linkend="item-nodes">item node</link>
  99         of type <literal>rect</literal> with an implicit
 100         <link linkend="fixed-nodes">fixed layout</link>.
 101       </para>
 102
 103       <!--
 104       <para>
 105         You may specify a Qt GUI style to
 106         be used with this theme by using the gui-style attribute in the
 107           greeter tag as in the following example.
 108  gui-style=&quot;Plastique&quot;
 109       </para>
 110       -->
 111
 112 <programlisting>
 113 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
 114 &lt;!DOCTYPE greeter SYSTEM "greeter.dtd"&gt;
 115 &lt;greeter&gt;
 116 [...]
 117 &lt;/greeter&gt;
 118 </programlisting>
 119
 120       <para>
 121         Contained within the greeter tag can be the nodes described
 122         in the next sections of this document.  Some of these nodes are
 123         containers (layout nodes, item nodes) which can contain other
 124         nodes again.
 125       </para>
 126     </sect2>
 127
 128     <sect2 id="item-nodes">
 129       <title>Item Nodes</title>
 130
 131       <para>
 132         A &kdm; theme is created by specifying a hierarchy of item and layout
 133         nodes.  Item nodes can have the following value for the
 134         <literal>type</literal> attribute:
 135       </para>
 136
 137       <variablelist>
 138
 139         <varlistentry>
 140           <term>button</term>
 141           <listitem>
 142             <para>
 143               A button field.  This field uses a Qt button.
 144             </para>
 145             <para>
 146               It is also possible to make any other item act like a button
 147               by setting its <literal>button</literal> attribute to
 148               <literal>true</literal>.  However, it is better to use
 149               Qt buttons in &kdm; themes since these are accessible to
 150               users with disabilities.
 151             </para>
 152           </listitem>
 153         </varlistentry>
 154
 155         <varlistentry>
 156           <term>entry</term>
 157           <listitem>
 158             <para>An input widget like a line edit or combo box.
 159               Note that this is merely a placeholder for Qt widgets.</para>
 160           </listitem>
 161         </varlistentry>
 162
 163         <varlistentry>
 164           <term>label</term>
 165           <listitem>
 166             <para>
 167               A text label.  Must contain either a
 168               <link linkend="text-nodes"><literal>text</literal> node</link>
 169               or a
 170               <link linkend="stock-nodes"><literal>stock</literal> node</link>
 171               to specify the text.
 172             </para>
 173           </listitem>
 174         </varlistentry>
 175
 176         <varlistentry>
 177           <term>list</term>
 178           <listitem>
 179             <para>A face browser widget.</para>
 180           </listitem>
 181         </varlistentry>
 182
 183         <varlistentry>
 184           <term>pixmap</term>
 185           <listitem>
 186             <para>A raster image in a format that Qt supports, &eg;
 187               PNG, JPEG, Tiff, etc.</para>
 188           </listitem>
 189         </varlistentry>
 190
 191         <varlistentry>
 192           <term>rect</term>
 193           <listitem>
 194             <para>A plain rectangle.</para>
 195           </listitem>
 196         </varlistentry>
 197
 198         <varlistentry>
 199           <term>svg</term>
 200           <listitem>
 201             <para>A vector image in SVG format.</para>
 202           </listitem>
 203         </varlistentry>
 204       </variablelist>
 205
 206       <para>
 207         For example:
 208 <programlisting>
 209 &lt;item type=&quot;label&quot;&gt;
 210 </programlisting>
 211
 212         An item that acts as a button:
 213 <programlisting>
 214  &lt;item type=&quot;rect&quot; id=&quot;disconnect_button&quot; button=&quot;true&quot;&gt;.
 215 </programlisting>
 216       </para>
 217
 218       <para>
 219         By default, the &kdm; login screen will disappear after authentication.
 220         This can result in flicker between the login screen and the session.
 221         The <literal>background</literal> attribute allows users to specify
 222         what elements of the theme are the background image.  When used, this
 223         will cause &kdm; to remove all non-background items from the display
 224         and render the remaining <literal>background</literal> items to the root
 225         window.  This can be used to create a smooth transition between the
 226         login screen and the session:
 227
 228 <programlisting>
 229 &lt;item type=&quot;rect&quot; background=&quot;true&quot;&gt;
 230   &lt;normal file="background.svg"/&gt;
 231   &lt;pos x=&quot;0&quot; y=&quot;0&quot; width=&quot;100%&quot; height=&quot;-75&quot;/&gt;
 232 &lt;/item&gt;
 233 </programlisting>
 234
 235         To use a different background for login transition than the one
 236         used for login, the theme should specify two item nodes (which
 237         could contain pixmaps or svg images, for example).  The item
 238         which corresponds to the greeter background should not have the
 239         <literal>background</literal> property while the item which corresponds
 240         to the transition background should have the
 241         <literal>background</literal> property.  For instance :
 242
 243 <programlisting>
 244 &lt;?xml version="1.0" encoding=&quot;UTF-8&quot;?&gt;
 245 &lt;!DOCTYPE greeter SYSTEM &quot;greeter.dtd&quot;&gt;
 246 &lt;greeter&gt;
 247   &lt;item type=&quot;rect&quot; background=&quot;true&quot;&gt;
 248     &lt;normal file="background_for_login.svg" element="background"/&gt;
 249     &lt;pos x=&quot;0&quot; y=&quot;0&quot; width=&quot;100%&quot; height=&quot;100%&quot;/&gt;
 250   &lt;/item&gt;
 251   &lt;item type=&quot;rect&quot;&gt;
 252     &lt;normal file="background_for_greeter.svg"/&gt;
 253     &lt;pos x=&quot;0&quot; y=&quot;0&quot; width=&quot;100%&quot; height=&quot;100%&quot;/&gt;
 254   &lt;/item&gt;
 255   [...]
 256 &lt;/greeter&gt;
 257 </programlisting>
 258
 259       </para>
 260
 261       <para>
 262         In multi-screen setups, themes may also specify the look of other
 263         screens than the one the greeter is on - but typically only background
 264         items will appear there. To specify which screen(s) an item should
 265         appear on, the <literal>screen</literal> attribute can be used with the
 266         value being one of <literal>greeter</literal>, <literal>other</literal>
 267         or <literal>all</literal>, meaning the screen the greeter is on, all
 268         screens the greeter is not on and all screens, resp.
 269       </para>
 270
 271       <variablelist>
 272         <para>
 273           Each item can be given a name via the <literal>id</literal>
 274           attribute. Certain ids are recognized by &kdm; to give those
 275           items a special function:
 276         </para>
 277
 278         <!--
 279         <varlistentry>
 280           <term><literal>list</literal> items</term>
 281           <listitem>
 282
 283             <para>
 284               List items by default display as lists, but the
 285               <literal>combo=&quot;true&quot;</literal> attribute can be used
 286               to specify combo box style (combo style supported since &kde; ).
 287               Some predefined lists may be included in a theme by using the
 288               following id values.  Customized lists may also be defined,
 289               which are explained below.
 290             </para>
 291
 292             <segmentedlist>
 293               <?dbhtml list-presentation="table"?>
 294               <segtitle>Id</segtitle><segtitle>Function</segtitle>
 295
 296               <seglistitem>
 297                 <seg>session</seg>
 298                 <seg>A list of available sessions, which allows the user to
 299                   pick the session to use.  Supported since &kde; .</seg>
 300               </seglistitem>
 301
 302               <seglistitem>
 303                 <seg>language</seg>
 304                 <seg>A list of available languages, which allows the user to
 305                   pick the language to use.  Supported since &kde; .</seg>
 306               </seglistitem>
 307
 308             </segmentedlist>
 309           </listitem>
 310         </varlistentry>
 311         -->
 312
 313         <varlistentry>
 314           <term><literal>button</literal> items and items with the
 315             <literal>button=&quot;true&quot;</literal> attribute.</term>
 316
 317           <listitem>
 318             <para>
 319               Buttons typically trigger certain actions.
 320               Addionally, &kdm; will hide buttons whose actions are
 321               not available for some reason.
 322             </para>
 323
 324             <segmentedlist>
 325               <?dbhtml list-presentation="table"?>
 326               <segtitle>Id</segtitle><segtitle>Action</segtitle>
 327
 328               <seglistitem>
 329                 <seg>chooser_button</seg>
 330                 <seg>Runs the XDMCP chooser.</seg>
 331               </seglistitem>
 332
 333               <!--
 334               <seglistitem>
 335                 <seg>custom_cmd_button[0-9]</seg>
 336                 <seg>Runs the <filename>n-th</filename> custom command.</seg>
 337               </seglistitem>
 338               -->
 339
 340               <seglistitem>
 341                 <seg>disconnect_button</seg>
 342                 <seg>Disconnect from remote session.</seg>
 343               </seglistitem>
 344
 345               <!--
 346               <seglistitem>
 347                 <seg>language_button</seg>
 348                 <seg>Open the language selection menu.</seg>
 349               </seglistitem>
 350               -->
 351
 352               <!--
 353               <seglistitem>
 354                 <seg>halt_button</seg>
 355                 <seg>Power off the system.</seg>
 356               </seglistitem>
 357
 358               <seglistitem>
 359                 <seg>reboot_button</seg>
 360                 <seg>Restart the system.</seg>
 361               </seglistitem>
 362
 363               <seglistitem>
 364                 <seg>suspend_button</seg>
 365                 <seg>Suspend the system.</seg>
 366               </seglistitem>
 367               -->
 368
 369               <seglistitem>
 370                 <seg>session_button</seg>
 371                 <seg>Open the session type selection menu.</seg>
 372               </seglistitem>
 373
 374               <seglistitem>
 375                 <seg>system_button</seg>
 376                 <seg>Open a catch-all menu with various options and actions,
 377                   depending on the configuration.</seg>
 378               </seglistitem>
 379             </segmentedlist>
 380           </listitem>
 381         </varlistentry>
 382
 383         <varlistentry>
 384           <term><literal>label</literal> items</term>
 385
 386           <listitem>
 387             <para>
 388               &kdm; will show/hide these labels and set their text depending
 389               on the state of the login dialog.
 390             </para>
 391
 392             <segmentedlist>
 393               <?dbhtml list-presentation="table"?>
 394               <segtitle>Id</segtitle><segtitle>Function</segtitle>
 395
 396               <!--
 397               <seglistitem>
 398                 <seg>pam-prompt</seg>
 399                 <seg>Label that displays the <acronym>PAM</acronym> prompt.
 400                   This is the prompt that <acronym>PAM</acronym>
 401                   uses to ask for username, password, etc.</seg>
 402               </seglistitem>
 403
 404               <seglistitem>
 405                 <seg>pam-message</seg>
 406                 <seg>Label that displays the <acronym>PAM</acronym> message.
 407                   These are messages that <acronym>PAM</acronym>/&kdm; gives
 408                   about state of the account, help about the prompts and other
 409                   information.</seg>
 410               </seglistitem>
 411               -->
 412
 413               <seglistitem>
 414                 <seg>pam-error</seg>
 415                 <seg>This displays the <guilabel>Login failed.</guilabel>
 416                   message.</seg>
 417               </seglistitem>
 418
 419             </segmentedlist>
 420           </listitem>
 421         </varlistentry>
 422
 423         <varlistentry>
 424           <term>Widget embedding items</term>
 425
 426           <listitem>
 427             <para>
 428               &kdm; will embed particular Qt widgets into these items.
 429             </para>
 430
 431             <segmentedlist>
 432               <?dbhtml list-presentation="table"?>
 433               <segtitle>Id</segtitle><segtitle>Function</segtitle>
 434
 435               <seglistitem>
 436                 <seg>user-entry</seg>
 437                 <seg>Entry field for username entry.</seg>
 438               </seglistitem>
 439
 440               <seglistitem>
 441                 <seg>pw-entry</seg>
 442                 <seg>Entry field for password entry.</seg>
 443               </seglistitem>
 444
 445               <seglistitem>
 446                 <seg>domain-entry</seg>
 447                 <seg>Some <quote>conversation</quote> plugins use this field
 448                   to query a domain name. If this field is present, the related
 449                   enclosing items should have
 450                   <link linkend="show-nodes">show nodes</link> with the type
 451                   <literal>plugin-domain-entry</literal>.</seg>
 452               </seglistitem>
 453
 454               <seglistitem>
 455                 <seg>talker</seg>
 456                 <seg>This item should be of type <literal>rect</literal>.
 457                   It represents the <quote>hot</quote> area of the
 458                   greeter: it contains the <literal>label</literal> and
 459                   <literal>entry</literal> items which concern the
 460                   authentication process.  If a given
 461                   <quote>conversation</quote> plugin cannot match the
 462                   existing items with its needs, it tries to embed a complex
 463                   widget with an own layout into this item, thus completely
 464                   overriding the theme's <quote>talker</quote>.
 465                   Strictily speaking, &kdm; themes do not need to provide
 466                   own <quote>talker</quote> designs at all, as all &kdm;
 467                   authentication plugins are able make use of the
 468                   <literal>talker</literal> item.
 469                 </seg>
 470               </seglistitem>
 471
 472               <seglistitem>
 473                 <seg>userlist</seg>
 474                 <seg>This item must be of type <literal>list</literal>.
 475                   If the user list feature is enabled, &kdm; will embed
 476                   the user list widget here. Otherwise, this item is
 477                   hidden.</seg>
 478               </seglistitem>
 479
 480               <seglistitem>
 481                 <seg>xconsole</seg>
 482                 <seg>This item should be of type <literal>rect</literal>.
 483                   If the built-in <command>xconsole</command> feature is
 484                   compiled in and enabled, &kdm; will embed
 485                   the console log widget here. Otherwise, this item is
 486                   hidden.</seg>
 487               </seglistitem>
 488
 489             </segmentedlist>
 490           </listitem>
 491         </varlistentry>
 492
 493         <varlistentry>
 494           <term>Other items</term>
 495
 496           <listitem>
 497             <para>
 498               &kdm; will show/hide these items depending on the configuration
 499               and the current state of the greeter.  &kdm; does not impose
 500               type requirements on them, but they usually lend themselves
 501               to a particular type.
 502             </para>
 503
 504             <segmentedlist>
 505               <?dbhtml list-presentation="table"?>
 506               <segtitle>Id</segtitle><segtitle>Shown only when ...</segtitle>
 507
 508               <seglistitem>
 509                 <seg>timed-label</seg>
 510                 <seg>... timed login is in progress.</seg>
 511               </seglistitem>
 512
 513               <seglistitem>
 514                 <seg>caps-lock-warning</seg>
 515                 <seg>... Caps Lock is active.</seg>
 516               </seglistitem>
 517
 518               <seglistitem>
 519                 <seg>xauth-warning</seg>
 520                 <seg>... the &X-Server; requires no X authorization to
 521                   connect.</seg>
 522               </seglistitem>
 523
 524               <!--
 525               <seglistitem>
 526                 <seg>pam-error-logo</seg>
 527                 <seg>... a pam-error message is being displayed.
 528                   This is useful for displaying an <guiicon>Attention</guiicon>
 529                   icon, for example.</seg>
 530               </seglistitem>
 531               -->
 532
 533               <seglistitem>
 534                 <seg>userlist-rect</seg>
 535                 <seg>... the user list is enabled.  By nesting the
 536                   <literal>userlist</literal> item into this one, it is possible
 537                   to create something like a frame around the list and have
 538                   it shown only when the user list itself if shown.</seg>
 539               </seglistitem>
 540
 541               <seglistitem>
 542                 <seg>xconsole-rect</seg>
 543                 <seg>... the built-in <command>xconsole</command> is enabled.
 544                   Analogous to <literal>userlist-rect</literal>.</seg>
 545               </seglistitem>
 546
 547             </segmentedlist>
 548           </listitem>
 549         </varlistentry>
 550
 551       </variablelist>
 552
 553     </sect2>
 554
 555     <sect2 id="layout-nodes">
 556       <title>Layout Container Nodes</title>
 557
 558       <para>
 559         Layout nodes appear inside item nodes and contain item nodes again.
 560         The type of the layout node determines the arrangement of its
 561         child nodes.  An item node can contain one layout node of each type.
 562       </para>
 563
 564       <sect3 id="box-nodes">
 565         <title>Box Nodes</title>
 566
 567         <para>
 568           Box nodes automatically arrange their children in a row.
 569           They are specified as follows:
 570 <programlisting>
 571 &lt;box orientation=&quot;<replaceable>alignment</replaceable>&quot; min-width=&quot;<replaceable>num</replaceable>&quot; min-height=&quot;<replaceable>num</replaceable>&quot;
 572     xpadding=&quot;<replaceable>num</replaceable>&quot; ypadding=&quot;<replaceable>num</replaceable>&quot; spacing=&quot;<replaceable>num</replaceable>&quot;
 573     homogeneous=&quot;<replaceable>bool</replaceable>&quot;&gt;
 574 </programlisting>
 575           Where <replaceable>num</replaceable> means number of pixels and
 576           <replaceable>bool</replaceable> means either <literal>true</literal>
 577           or <literal>false</literal>.
 578           The <replaceable>alignment</replaceable> value can be either
 579           <literal>horizontal</literal> or <literal>vertical</literal>.
 580           If you leave any attribute off, it will default to zero for numbers,
 581           <literal>false</literal> for bools and <literal>vertical</literal>
 582           for the orientation.
 583         </para>
 584
 585         <para>
 586           The spacing is the distance between neighboring child items.
 587           The padding is the box' outer margin.
 588           If the box is homogeneous, the same amount of space is allocated
 589           to each child item.
 590         </para>
 591       </sect3>
 592
 593       <sect3 id="fixed-nodes">
 594         <title>Fixed Nodes</title>
 595
 596         <para>
 597           Fixed is a container that has its children
 598           laid out at precise coordinates.  The size of this container
 599           is the smallest rectangle that contains all the children.  Fixed
 600           has no extra attributes and so you just use:
 601 <programlisting>
 602 &lt;fixed&gt;
 603 </programlisting>
 604           Then you put other items with proper position nodes inside it.
 605         </para>
 606       </sect3>
 607
 608     </sect2>
 609
 610     <sect2 id="position-nodes">
 611       <title>Position Nodes</title>
 612
 613       <para>
 614         Each item can specify its position and size via the <literal>pos</literal>
 615         node.  For example:
 616 <programlisting>
 617 &lt;pos x=&quot;0&quot; y=&quot;4&quot; width=&quot;100%&quot; height=&quot;100%&quot;/&gt;
 618 </programlisting>
 619       </para>
 620
 621       <para>
 622         If the size is not specified, it will be the item's
 623         <quote>natural</quote> size, called the size hint.
 624         Note that not all items have a useful size hint.
 625       </para>
 626
 627       <para>
 628         Both position and size can be given in percent and will be calculated
 629         relative to the size of the enclosing container in this case.
 630         For toplevel items it is the percentage of the whole screen.
 631         By appending circumflexes (<literal>^</literal>) to the size
 632         specification it is possible to modify it to be relative to the
 633         size of the enclosing item's enclosing item and so on.
 634       </para>
 635
 636       <para>
 637         If the item contains a box, <literal>width</literal> and
 638         <literal>height</literal> can be specified to be
 639         <literal>box</literal> to mean that they are supposed to be the width
 640         and height of the box, that is the items in the box plus the padding.
 641       </para>
 642
 643       <para>
 644         One of <literal>width</literal> and <literal>height</literal> can
 645         be specified to be <literal>scale</literal>
 646         to mean that it should be scaled according to the other dimension's
 647         scale relative to its size hint.  Use this to preserve the aspect
 648         ratio of scaled images automatically.
 649       </para>
 650
 651       <para>
 652         If the <literal>expand</literal> attribute is specified and
 653         <literal>true</literal>, this item will be expanded in the
 654         enclosing box as much as possible (that is it will be given
 655         more space if available).
 656       </para>
 657
 658       <para>
 659         If <literal>width</literal> or <literal>height</literal> is a
 660         plain number, a negative value represents
 661         an offset from the enclosing container's size.  Note that it is
 662         possible to specify a positive offset by writing two minus signs.
 663       </para>
 664
 665       <para>
 666         In either case it is possible to constrain the final size with the
 667         <literal>min-width</literal>, <literal>min-height</literal>,
 668         <literal>max-width</literal> and <literal>max-height</literal>
 669         attributes which can be specified in the same ways as
 670         <literal>width</literal> and <literal>height</literal>.
 671       </para>
 672
 673       <para>
 674         If <literal>x</literal> or <literal>y</literal> is a plain number,
 675         a negative value represents an offset from the right resp. bottom edge,
 676         unlike the default which is the left resp. top edge.
 677       </para>
 678
 679       <para>
 680         It is also possible to specify which point within the item the
 681         position refers to.  This is called the anchor and can be
 682         either <literal>c</literal> for center or one of
 683         <literal>n</literal>, <literal>ne</literal>, <literal>e</literal>,
 684         <literal>se</literal>, <literal>s</literal>, <literal>sw</literal>,
 685         <literal>w</literal> and <literal>nw</literal>
 686         which stand for the different edges/corners corresponding the
 687         directions on a topographical map.
 688         The default is <literal>nw</literal>, which is the upper left corner.
 689         For example:
 690 <programlisting>
 691 &lt;pos x=&quot;10%&quot; y=&quot;50%&quot; anchor=&quot;w&quot; width=&quot;80%&quot; height=&quot;95&quot;/&gt;
 692 </programlisting>
 693       </para>
 694
 695     </sect2>
 696
 697     <sect2 id="show-nodes">
 698       <title>Show Nodes</title>
 699
 700       <!-- not really implemented
 701       <para>
 702         Some items may only display in certain modes, like when doing a
 703         remote display.  Multiple values can be specified and must be
 704         separated with commas.  The following values are possible:
 705       </para>
 706
 707       <para>
 708         <filename>console</filename> - In console mode.
 709       </para>
 710       <para>
 711         <filename>console-fixed</filename> - In console non-flexi mode.
 712       </para>
 713       <para>
 714         <filename>console-flexi</filename> - In console &amp; flexi mode.
 715       </para>
 716       <para>
 717         <filename>flexi</filename> - In flexi mode.
 718       </para>
 719       <para>
 720         <filename>remote</filename> - In remote mode.
 721       </para>
 722       <para>
 723         <filename>remote-flexi</filename> - In remote &amp; flexi mode.
 724       </para>
 725
 726       <para>
 727         For example:
 728 <programlisting>
 729 &lt;show modes=&quot;flexi,remote&quot;/&gt;
 730 </programlisting>
 731       </para>
 732       -->
 733
 734       <para>
 735         You can specify the <literal>type</literal> attribute to indicate that
 736         certain items should only be displayed if the type is set.
 737         Prefixing the type with an exclamation mark (<literal>!</literal>)
 738         reverses the condition.
 739         Valid values include the following:
 740       </para>
 741         <segmentedlist>
 742           <?dbhtml list-presentation="table"?>
 743           <segtitle>Type</segtitle><segtitle>Display if ...</segtitle>
 744
 745           <seglistitem>
 746             <seg><literal>chooser</literal></seg>
 747             <seg>switching to remote login is permitted.</seg>
 748           </seglistitem>
 749
 750           <!--
 751           <seglistitem>
 752             <seg><literal>custom_cmd[0-9]</literal></seg>
 753             <seg><literal>n-th</literal> CustomCommand is specified in
 754               the &kdm; configuration.</seg>
 755           </seglistitem>
 756           -->
 757
 758           <seglistitem>
 759             <seg><literal>halt</literal> and <literal>reboot</literal></seg>
 760             <seg>system shutdown is permitted.</seg>
 761           </seglistitem>
 762
 763           <!--
 764           <seglistitem>
 765             <seg><literal>suspend</literal></seg>
 766             <seg>suspending the system is permitted.</seg>
 767           </seglistitem>
 768           -->
 769
 770           <seglistitem>
 771             <seg><literal>system</literal></seg>
 772             <seg>no condition (always set in &kdm;).</seg>
 773           </seglistitem>
 774
 775           <!--
 776           <seglistitem>
 777             <seg><literal>timed</literal></seg>
 778             <seg>a timed login is being counted down.</seg>
 779           </seglistitem>
 780           -->
 781
 782           <seglistitem>
 783             <seg><literal>plugin-</literal><replaceable>entry-name</replaceable></seg>
 784             <seg>the <quote>conversation</quote> plugin provides a
 785               corresponding input field.</seg>
 786           </seglistitem>
 787
 788         </segmentedlist>
 789
 790
 791       <para>
 792         For example:
 793 <programlisting>
 794 &lt;show type=&quot;chooser&quot;/&gt;
 795 </programlisting>
 796       </para>
 797
 798       <para>
 799         Alternatively, you can specify a <literal>min-screen-width</literal> or
 800         <literal>min-screen-height</literal> value to indicate that certain
 801         items should be displayed only if the screen resolution is the
 802         at least the specified size.
 803         For example:
 804 <programlisting>
 805 &lt;show min-screen-height=&quot;768&quot;/&gt;
 806 </programlisting>
 807       </para>
 808
 809     </sect2>
 810
 811     <sect2 id="nor-act-pre-nodes">
 812       <title>Normal/Active/Prelight Nodes</title>
 813
 814       <para>
 815         The look of most item types can be parametrized via the following
 816         tags:
 817       </para>
 818
 819       <variablelist>
 820         <varlistentry>
 821           <term><literal>normal</literal></term>
 822           <listitem>
 823             <para>Normal state.</para>
 824           </listitem>
 825         </varlistentry>
 826         <varlistentry>
 827           <term><literal>prelight</literal></term>
 828           <listitem>
 829             <para>When the mouse is hovering over the item.</para>
 830           </listitem>
 831         </varlistentry>
 832         <varlistentry>
 833           <term><literal>active</literal></term>
 834           <listitem>
 835             <para>When a mouse button is clicked on the item.</para>
 836           </listitem>
 837         </varlistentry>
 838       </variablelist>
 839
 840       <variablelist>
 841
 842         <para>
 843           The exact set of available attributes depends on the item type:
 844         </para>
 845
 846         <varlistentry>
 847           <term><literal>rect</literal></term>
 848           <listitem>
 849             <para>
 850 <programlisting>
 851 &lt;normal color=&quot;#000000&quot; alpha=&quot;0.0&quot;/&gt;
 852 </programlisting>
 853               Either of the attributes may be omitted, in which case the
 854               default is used (the example represents the defaults).
 855               <literal>alpha</literal> is a floating point number between
 856               zero (transparent) and one (opaque).
 857               <literal>color</literal> is a hashmark followed by a six-digit
 858               hex number; the format is
 859               <quote><literal>#</literal><replaceable>rrggbb</replaceable></quote>.
 860               Alternatively, <literal>color</literal> may be specified as an
 861               eight-digit hex number, in which case the first two digits are
 862               the alpha value.
 863             </para>
 864           </listitem>
 865         </varlistentry>
 866
 867         <varlistentry>
 868           <term><literal>label</literal></term>
 869           <listitem>
 870             <para>
 871 <programlisting>
 872 &lt;normal color=&quot;#ffffff&quot; alpha=&quot;1.0&quot; font=&quot;Sans 14&quot;/&gt;
 873 </programlisting>
 874               <literal>alpha</literal> and <literal>color</literal> are
 875               specified like in <quote>rect</quote> items.
 876             </para>
 877             <para>
 878               <literal>font</literal> follows the format
 879               <quote><replaceable>family-list</replaceable>&nbsp;<replaceable>style-options</replaceable>&nbsp;<replaceable>size</replaceable></quote>.
 880               Each part is optional.
 881             </para>
 882             <para>
 883               <replaceable>family-list</replaceable> is a comma-separated
 884               list of font families like <quote>helvetica</quote>,
 885               <quote>monospace</quote>, etc.
 886             </para>
 887             <para>
 888               <replaceable>style-options</replaceable> is a space-delimited
 889               list of keywords from the categories style, weight and stretch;
 890               from each category at most one.
 891               The style can be <literal>normal</literal>,
 892               <literal>italic</literal> or <literal>oblique</literal>.
 893               Weight can be <literal>ultra-light</literal>,
 894               <literal>light</literal>, <literal>medium</literal>,
 895               <literal>semi-bold</literal>, <literal>bold</literal>,
 896               <literal>ultra-bold</literal> or <literal>heavy</literal>.
 897               Allowable stretches comprise <literal>ultra-condensed</literal>,
 898               <literal>extra-condensed</literal>, <literal>condensed</literal>,
 899               <literal>semi-condensed</literal>, <literal>normal</literal>,
 900               <literal>semi-expanded</literal>, <literal>expanded</literal>,
 901               <literal>extra-expanded</literal> and <literal>ultra-expanded</literal>.
 902             </para>
 903             <para>
 904               <replaceable>size</replaceable> is either a floating point
 905               number representing the size in points (1/72 inch) or an
 906               integer followed by <literal>px</literal> representing the
 907               size in pixels.  Point sizes are preferable, as they are
 908               independent from the display resolution.
 909             </para>
 910             <para>
 911               If either attribute is left out, the values from the
 912               <link linkend="style-nodes">style node</link> are used.
 913               If this yields no window-text color specification, white
 914               is used.  The default font is the one configured in &kdmrc;.
 915             </para>
 916           </listitem>
 917         </varlistentry>
 918
 919         <varlistentry>
 920           <term><literal>pixmap</literal></term>
 921           <term><literal>svg</literal></term>
 922           <listitem>
 923             <para>
 924 <programlisting>
 925 &lt;normal file=&quot;picture.png&quot; tint=&quot;#dddddd&quot; alpha=&quot;1.0&quot;/&gt;
 926 </programlisting>
 927             </para>
 928
 929             <para>
 930               <literal>file</literal> specifies the file containing the image.
 931               Relative pathnames are relative to the theme's directory.
 932             </para>
 933
 934             <para>
 935               <literal>element</literal> specifies the element id of a SVG file.
 936               If empty, the whole SVG image will be rendered.
 937             </para>
 938
 939             <para>
 940               For <literal>pixmap</literal> nodes, &kdm; first tries to open
 941               a file that matches <replaceable>basename</replaceable><literal>-</literal><replaceable>width</replaceable><literal>x</literal><replaceable>height</replaceable><literal>.</literal><replaceable>extension</replaceable>
 942               based on the specified file name, so the best-quality image
 943               for a given resolution can be used.
 944             </para>
 945
 946             <!--
 947             <para>
 948               Note that an alternative image file can be specified using the
 949               <literal>altfile</literal><optional><replaceable>n</replaceable></optional>
 950               attribute.  &kdm; will use the last valid image filename
 951               specified.  For example:
 952 <programlisting>
 953 &lt;normal file=&quot;picture.png&quot; altfile1=&quot;distribution-blah-image.png&quot; altfile2=&quot;distribution-foo-image.png&quot;/&gt;
 954 </programlisting>
 955               If <filename>distribution-foo-image.png</filename> is a valid
 956               image filename it will be used.
 957               Otherwise distribution-blah-image.png will be used if valid.
 958               This feature is supported since &kde; .
 959             </para>
 960             -->
 961
 962             <para>
 963               <literal>tint</literal> and <literal>alpha</literal> form a
 964               color specification like in <literal>rect</literal> items.
 965               Each pixel of the image is multiplied with this color
 966               component-wise.
 967             </para>
 968           </listitem>
 969         </varlistentry>
 970
 971       </variablelist>
 972
 973     </sect2>
 974
 975     <sect2 id="style-nodes">
 976       <title>Widget Style Nodes</title>
 977
 978       <para>
 979         This tag makes it possible to change the appearance of labels and
 980         Qt widgets embedded into the theme, e.g., line edits, buttons or
 981         the user list.
 982         The style settings are inherited by child items, but can be
 983         overridden individually. The defaults are taken from &kdmrc;.
 984       </para>
 985
 986       <para>
 987         The <literal>font</literal> attribute defines the font for all widgets.
 988         For widgets with an input function it can be overridden with the
 989         <literal>edit-font</literal> attribute.
 990         Fonts are specified the same way as in
 991         <link linkend="nor-act-pre-nodes">normal/active/prelight nodes</link>.
 992       </para>
 993
 994       <para>
 995         Usually, the theming engine tries hard to remove any frames from
 996         Qt widgets, so they melt into the theme seamlessly.  In cases
 997         where this is not desired, the <literal>frame</literal> attribute can
 998         be set to <literal>true</literal>.
 999       </para>
1000
1001       <para>
1002         It is possible to specify almost the entire palette for the widgets
1003         as documented at
1004         <ulink type="http" url="http://doc.trolltech.com/4.3/qpalette.html">Trolltech's site</ulink>.
1005         Attribute names are composed from a scope, a color role and a suffix.
1006
1007         Possible scopes are - in order of increasing precedence -
1008         <literal>all-</literal> for all color groups,
1009         no scope for the active and inactive color groups and
1010         <literal>active-</literal>, <literal>inactive-</literal> and
1011         <literal>disabled-</literal> for the respective color group.
1012
1013         Supported color roles are
1014         <literal>window</literal>, <literal>window-text</literal>,
1015         <literal>base</literal>, <literal>alternate-base</literal>,
1016         <literal>text</literal>, <literal>bright-text</literal>,
1017         <literal>highlight</literal>, <literal>highlighted-text</literal>,
1018         <literal>button</literal> and <literal>button-text</literal>.
1019
1020         The suffix can be <literal>-color</literal> or
1021         <literal>-alpha</literal> with the respective meaning as in
1022         <link linkend="nor-act-pre-nodes">normal/active/prelight nodes</link>.
1023       </para>
1024
1025       <para>
1026         Example:
1027 <programlisting>
1028 &lt;style edit-font=&quot;Comic 16&quot; text-color=&quot;#dddddd&quot; frame=&quot;true&quot;/&gt;
1029 </programlisting>
1030       </para>
1031     </sect2>
1032
1033     <sect2 id="color-nodes">
1034       <title>Face Browser Color Nodes</title>
1035
1036       <para>
1037         Color nodes permit overriding the background color of the items
1038         in the face browser. <literal>labelcolor</literal> and
1039         <literal>altlabelcolor</literal> are essentially equivalent to
1040         <literal>all-base-color</literal> resp.
1041         <literal>all-alternate-base-color</literal> in
1042         <link linkend="style-nodes">style nodes</link>.
1043         If only <literal>labelcolor</literal> is specified, alternating
1044         item backgrounds are disabled.
1045       </para>
1046
1047       <para>
1048 <programlisting>
1049 &lt;color labelcolor=&quot;#80ffffff&quot; altlabelcolor=&quot;#80f0f0f0&quot;/&gt;
1050 </programlisting>
1051       </para>
1052     </sect2>
1053
1054     <sect2 id="text-nodes">
1055       <title>Text Nodes</title>
1056
1057       <para>
1058         Text tags are used by labels.  They can be used to display
1059         localized text as follows (if the <literal>xml:lang</literal>
1060         attribute is omitted, the POSIX locale is assumed):
1061 <programlisting>
1062 &lt;text xml:lang=&quot;fr&quot;&gt;Option&lt;/text&gt;
1063 </programlisting>
1064       </para>
1065
1066       <!--
1067       <para>
1068         You can include pango markup in the text nodes for labels, however
1069         you must encode it.  So for example to have the label of
1070         &quot;foo&lt;sup&gt;bar&lt;/sup&gt;&quot;, you must type:
1071 <programlisting>
1072 &lt;text&gt;&quot;foo&lt;sup&gt;bar&lt;/sup&gt;&quot;&lt;/text&gt;
1073 </programlisting>
1074       </para>
1075       -->
1076
1077       <para>
1078         Text nodes can contain the following special character sequences
1079         which will be translated as follows:
1080       </para>
1081
1082       <segmentedlist>
1083         <?dbhtml list-presentation="table"?>
1084         <segtitle>Sequence</segtitle><segtitle>Expansion</segtitle>
1085
1086         <seglistitem>
1087           <seg>%%</seg>
1088           <seg>A literal % character</seg>
1089         </seglistitem>
1090
1091         <seglistitem>
1092           <seg>%c</seg>
1093           <seg>Wall clock time and date</seg>
1094         </seglistitem>
1095
1096         <seglistitem>
1097           <seg>%d</seg>
1098           <seg>Display name (<envar>DISPLAY</envar> environment variable)</seg>
1099         </seglistitem>
1100
1101         <seglistitem>
1102           <seg>%h</seg>
1103           <seg>Hostname (<function>gethostname</function> output)</seg>
1104         </seglistitem>
1105
1106         <seglistitem>
1107           <seg>%m</seg>
1108           <seg>Machine name (<structfield>machine</structfield> part of
1109             <function>uname</function> output)</seg>
1110         </seglistitem>
1111
1112         <seglistitem>
1113           <seg>%n</seg>
1114           <seg>Node name (<structfield>nodename</structfield> part of
1115             <function>uname</function> output)</seg>
1116         </seglistitem>
1117
1118         <seglistitem>
1119           <seg>%o</seg>
1120           <seg>Domain name (<function>getdomainname</function> output)</seg>
1121         </seglistitem>
1122
1123         <seglistitem>
1124           <seg>%r</seg>
1125           <seg>Release name (<structfield>release</structfield> part of
1126             <function>uname</function> output)</seg>
1127         </seglistitem>
1128
1129         <seglistitem>
1130           <seg>%s</seg>
1131           <seg>System name (<structfield>sysname</structfield> part of
1132             <function>uname</function> output)</seg>
1133         </seglistitem>
1134
1135         <seglistitem>
1136           <seg>%t</seg>
1137           <seg>Remaining number of seconds until timed login is performed,
1138             plus the appropriate i18n plural form of <quote>second</quote></seg>
1139         </seglistitem>
1140
1141         <seglistitem>
1142           <seg>%u</seg>
1143           <seg>Username for timed login</seg>
1144         </seglistitem>
1145
1146         <!-- Need to switch to richtext painting for this purpose.
1147         <seglistitem>
1148           <seg>\n</seg>
1149           <seg>Newline</seg>
1150         </seglistitem>
1151         -->
1152
1153         <seglistitem>
1154           <seg>_</seg>
1155           <seg>Causes the following character to be an accelerator</seg>
1156         </seglistitem>
1157
1158       </segmentedlist>
1159
1160       <para>
1161         <literal>%t</literal> and <literal>%u</literal> are intended to be
1162         used only internally to display the <literal>timed-label</literal>
1163         message, which is automatically updated every second.
1164       </para>
1165     </sect2>
1166
1167     <sect2 id="stock-nodes">
1168       <title>Stock Nodes</title>
1169
1170       <para>
1171         Certain common localized labels can be specified via the stock
1172         tags.  The <literal>text</literal> tag is ignored if the
1173         <literal>stock</literal> tag is used.  You really should use the
1174         stock labels rather than just putting all the translations into
1175         the themes.  This yields faster load times and likely better
1176         translations.  The following values are valid:
1177       </para>
1178
1179       <segmentedlist>
1180         <?dbhtml list-presentation="table"?>
1181         <segtitle>Type</segtitle><segtitle>Expansion</segtitle>
1182
1183         <!--
1184         <seglistitem>
1185           <seg>ok</seg>
1186           <seg><quote>_OK</quote></seg>
1187         </seglistitem>
1188         <seglistitem>
1189           <seg>cancel</seg>
1190           <seg>_Cancel</seg>
1191         </seglistitem>
1192         <seglistitem>
1193           <seg>options</seg>
1194           <seg>_Options</seg>
1195         </seglistitem>
1196         <seglistitem>
1197           <seg>custom_cmd[0-9]</seg>
1198           <seg>Obtained from the config file.</seg>
1199         </seglistitem>
1200         -->
1201         <seglistitem>
1202           <seg>caps-lock-warning</seg>
1203           <seg><quote>Caps Lock is enabled</quote></seg>
1204         </seglistitem>
1205         <seglistitem>
1206           <seg>chooser</seg>
1207           <seg><quote>XDMCP Choose_r</quote></seg>
1208         </seglistitem>
1209         <seglistitem>
1210           <seg>quit</seg>
1211           <seg><quote>_Quit</quote></seg>
1212         </seglistitem>
1213         <seglistitem>
1214           <seg>disconnect</seg>
1215           <seg><quote>Disconn_ect</quote></seg>
1216         </seglistitem>
1217         <seglistitem>
1218           <seg>halt</seg>
1219           <seg><quote>Power o_ff</quote></seg>
1220         </seglistitem>
1221         <seglistitem>
1222           <seg>language</seg>
1223           <seg><quote>Lan_guage</quote></seg>
1224         </seglistitem>
1225         <seglistitem>
1226           <seg>login</seg>
1227           <seg><quote>_Login</quote></seg>
1228         </seglistitem>
1229         <seglistitem>
1230           <seg>session</seg>
1231           <seg><quote>Session _Type</quote></seg>
1232         </seglistitem>
1233         <seglistitem>
1234           <seg>reboot</seg>
1235           <seg><quote>Re_boot</quote></seg>
1236         </seglistitem>
1237         <!--
1238         <seglistitem>
1239           <seg>suspend</seg>
1240           <seg><quote>Sus_pend</quote></seg>
1241         </seglistitem>
1242         -->
1243         <seglistitem>
1244           <seg>system</seg>
1245           <seg><quote>_Menu</quote></seg>
1246         </seglistitem>
1247         <seglistitem>
1248           <seg>timed-label</seg>
1249           <seg><quote>User %u will login in %t</quote></seg>
1250         </seglistitem>
1251         <seglistitem>
1252           <seg>domain-label</seg>
1253           <seg><quote>_Domain:</quote></seg>
1254         </seglistitem>
1255         <seglistitem>
1256           <seg>username-label</seg>
1257           <seg><quote>_Username:</quote></seg>
1258         </seglistitem>
1259         <seglistitem>
1260           <seg>password-label</seg>
1261           <seg><quote>_Password:</quote></seg>
1262         </seglistitem>
1263         <seglistitem>
1264           <seg>welcome-label</seg>
1265           <seg><quote>Welcome to %h</quote></seg>
1266         </seglistitem>
1267
1268       </segmentedlist>
1269
1270       <para>
1271         For example:
1272 <programlisting>
1273 &lt;stock type=&quot;welcome-label&quot;/&gt;
1274 </programlisting>
1275       </para>
1276     </sect2>
1277
1278     <sect2 id="buddy-nodes">
1279       <title>Buddy Nodes</title>
1280
1281       <para>
1282         Items which do not directly cause an action can be assigned a buddy.
1283         The buddy is given input focus when the item is activated (clicked
1284         or a <literal>label</literal>'s accelerator pressed).
1285       </para>
1286
1287       <para>
1288         The buddy is referenced by id with the <literal>idref</literal>
1289         attribute.  Obviously, it must be given an id.  Example:
1290 <programlisting>
1291 &lt;item type=&quot;label&quot;&gt;
1292   &lt;stock type=&quot;username-label&quot;/&gt;
1293   &lt;buddy idref=&quot;user-entry&quot;/&gt;
1294   [...]
1295 &lt;/item&gt;
1296 [...]
1297 &lt;item type=&quot;entry&quot; id=&quot;user-entry&quot;&gt;
1298   [...]
1299 &lt;/item&gt;
1300 </programlisting>
1301       </para>
1302     </sect2>
1303
1304   </sect1>
1305
1306 </chapter>