doc/fvwm/initialization.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   3   "../docbook-xml/docbookx.dtd"
   4 [
   5 ]>
   6
   7 <section id='initialization'>
   8 <title>Initialization</title>
   9
  10 <para>During initialization, fvwm searches for a configuration file
  11 which describes key and button bindings, and many other
  12 things. The format of these files is described later.  Fvwm first
  13 searches for configuration files using the command</para>
  14
  15 <programlisting>
  16 <fvwmref cmd="Read"/> <filename>config</filename>
  17 </programlisting>
  18
  19 <para>This looks for file
  20 <filename>config</filename> in <envar>$FVWM_USERDIR</envar> and <envar>$FVWM_DATADIR</envar>
  21 directories, as described in
  22 <fvwmref cmd="Read"/>.  If this fails more files are queried for backward
  23 compatibility.  Here is the complete list of all file locations
  24 queried in the default installation (only the first found file
  25 is used):</para>
  26
  27 <simplelist>
  28 <member><envar>$HOME</envar>/.fvwm/config</member>
  29 <member>/usr/local/share/fvwm/config</member>
  30 </simplelist>
  31 <para output="html"></para>
  32 <simplelist>
  33 <member><envar>$HOME</envar>/.fvwm/.fvwm2rc</member>
  34 <member><envar>$HOME</envar>/.fvwm2rc</member>
  35 <member>/usr/local/share/fvwm/.fvwm2rc</member>
  36 <member>/usr/local/share/fvwm/system.fvwm2rc</member>
  37 <member>/etc/system.fvwm2rc</member>
  38 </simplelist>
  39
  40 <para>Please note, the last 5 locations are not guaranteed to be
  41 supported in the future.</para>
  42
  43 <para>If a configuration file is not found, the left mouse button, or
  44 <keysym>Help</keysym>
  45 or
  46 <keysym>F1</keysym>
  47 keys on the root window bring up menus and forms that can create
  48 a starting configuration file.</para>
  49
  50 <para>Fvwm sets two environment variables which are inherited by its
  51 children.  These are
  52 <envar>$DISPLAY</envar>
  53 which describes the display on which fvwm is running.
  54 <envar>$DISPLAY</envar>
  55 may be
  56 <emphasis remap='I'>unix:0.0</emphasis>
  57 or
  58 <emphasis remap='I'>:0.0</emphasis>,
  59 which doesn't work too well when passed through ssh to another
  60 machine, so
  61 <envar>$HOSTDISPLAY</envar>
  62 is set to a network-ready description of the display.
  63 <envar>$HOSTDISPLAY</envar>
  64 always uses the TCP/IP transport protocol (even for a local
  65 connection) so
  66 <envar>$DISPLAY</envar>
  67 should be used for local connections, as it may use Unix-domain
  68 sockets, which are faster.</para>
  69
  70 <para>If you want to start some applications or modules with fvwm, you
  71 can simply put</para>
  72
  73 <programlisting>
  74 <fvwmref cmd="Exec"/> app
  75 </programlisting>
  76
  77 <para>or</para>
  78
  79 <programlisting>
  80 <fvwmref cmd="Module"/> FvwmXxx
  81 </programlisting>
  82
  83 <para>into your
  84 <filename>config</filename>,
  85 but it is not recommended; do this only if you know what you are
  86 doing. It is usually important to start applications or modules
  87 after the entire config is read, because it contains styles or
  88 module configurations which can affect window appearance and
  89 functionality.</para>
  90
  91 <para>The standard way to start applications or modules on fvwm's start
  92 up is to add them to an initialization function (usually
  93 <emphasis remap='B'>StartFunction</emphasis> or <emphasis remap='B'>InitFunction</emphasis>).
  94 This way they are only started after fvwm finishes to read and
  95 execute
  96 <filename>config</filename>
  97 file.</para>
  98
  99 <para>Fvwm has three special functions for initialization:
 100 <emphasis remap='B'>StartFunction</emphasis>,
 101 which is executed on startups and restarts;
 102 <emphasis remap='B'>InitFunction</emphasis> and <emphasis remap='B'>RestartFunction</emphasis>,
 103 which are executed during initialization and restarts
 104 (respectively) just after StartFunction.  These functions may be
 105 customized in a user's
 106 <filename>config</filename>
 107 file using the
 108 <fvwmref cmd="AddToFunc"/>
 109 command (described later) to start up modules, xterms, or whatever
 110 you'd like to have started by fvwm.</para>
 111
 112 <para>Fvwm has also a special exit function:
 113 <emphasis remap='B'>ExitFunction</emphasis>,
 114 executed when exiting or restarting before actually quitting.
 115 It could be used to explicitly kill modules, etc.</para>
 116
 117 <para>If fvwm is run under a session manager, functions
 118 <emphasis remap='B'>SessionInitFunction</emphasis> and <emphasis remap='B'>SessionRestartFunction</emphasis>
 119 are executed instead of InitFunction and RestartFunction.
 120 This helps to define the user's
 121 <filename>config</filename>
 122 file to be good for both running under a session manager and
 123 without it.  Generally it is a bad idea to start xterms or other
 124 applications in "Session*" functions.  Also someone can decide to
 125 start different modules while running under a session manager or
 126 not.  For the similar purposes
 127 <emphasis remap='B'>SessionExitFunction</emphasis>
 128 is used instead of ExitFunction.</para>
 129
 130 <programlisting>
 131 <fvwmref cmd="DestroyFunc"/> StartFunction
 132 <fvwmref cmd="AddToFunc"/> StartFunction
 133  + I <fvwmref cmd="Module"/> <fvwmref mod="FvwmPager"/> * *
 134  + I <fvwmref cmd="Module"/> <fvwmref mod="FvwmButtons"/>
 135
 136 <fvwmref cmd="DestroyFunc"/> InitFunction
 137 <fvwmref cmd="AddToFunc"/> InitFunction
 138  + I <fvwmref cmd="Module"/> <fvwmref mod="FvwmBanner"/>
 139  + I <fvwmref cmd="Module"/> <fvwmref mod="FvwmTaskBar"/>
 140  + I <fvwmref cmd="Exec"/> xsetroot -solid cyan
 141  + I <fvwmref cmd="Exec"/> xterm
 142  + I <fvwmref cmd="Exec"/> netscape
 143
 144 <fvwmref cmd="DestroyFunc"/> RestartFunction
 145 <fvwmref cmd="AddToFunc"/> RestartFunction
 146  + I <fvwmref cmd="Module"/> <fvwmref mod="FvwmTaskBar"/>
 147
 148 <fvwmref cmd="DestroyFunc"/> SessionInitFunction
 149 <fvwmref cmd="AddToFunc"/> SessionInitFunction
 150  + I <fvwmref cmd="Module"/> <fvwmref mod="FvwmBanner"/>
 151
 152 <fvwmref cmd="DestroyFunc"/> SessionRestartFunction
 153 <fvwmref cmd="AddToFunc"/> SessionRestartFunction
 154  + I <fvwmref cmd="Nop"/>
 155 </programlisting>
 156
 157 <para>You do not need to define all special functions if some are empty.
 158 Also note, all these special functions may be emulated now using
 159 <emphasis remap='B'>StartFunction</emphasis> and <emphasis remap='B'>ExitFunction,</emphasis>
 160 like this:</para>
 161
 162 <programlisting>
 163 <fvwmref cmd="DestroyFunc"/> StartFunction
 164 <fvwmref cmd="AddToFunc"/> StartFunction
 165 + I <fvwmref cmd="Test"/> (Init) <fvwmref cmd="Module"/> <fvwmref mod="FvwmBanner"/>
 166 + I <fvwmref cmd="Module"/> <fvwmref mod="FvwmPager"/> * *
 167 + I <fvwmref cmd="Test"/> (Restart) <fvwmref cmd="Beep"/>
 168
 169 <fvwmref cmd="DestroyFunc"/> ExitFunction
 170 <fvwmref cmd="AddToFunc"/> ExitFunction
 171 + I <fvwmref cmd="Test"/> (Quit) <fvwmref cmd="Echo"/> Bye-bye
 172 + I <fvwmref cmd="KillModule"/> MyBuggyModule
 173 + I <fvwmref cmd="Test"/> (ToRestart) <fvwmref cmd="Beep"/>
 174 </programlisting>
 175
 176 </section>