core/docs/theme_format

   1 1. Theme metadata
   2 -----------------
   3
   4 It is advised that all fbsplash themes be shipped with a metadata.xml
   5 file providing additional information about the author, license and origin
   6 of the theme.  The XML schema for this file is available in
   7 thememeta.xsd.  A sample metadata file is provided in metadata_sample.xml.
   8 The metadata.xml file should be located in the main directory of the
   9 fbsplash theme (e.g. /etc/splash/<themename>/metadata.xml).
  10
  11
  12
  13 2. Config file directives
  14 -------------------------
  15
  16 NOTE: Unless otherwise stated, all coordinates are specified in the screen
  17 coordinate system (i.e. the top left pixel is at (0,0)).
  18
  19 There are two types of directives that can be used in fbsplash config
  20 files: object/setting and grouping directives.  The first kind is used
  21 to specify that an object is to be displayed on the screen or that
  22 a setting should take a specific value.  The grouping directives on the
  23 other hand are used add a context to the set of object/setting directives
  24 that they enclose.
  25
  26
  27 2.1 Grouping directives
  28 ------------------------
  29
  30 * <type type-spec [type-spec]>..</type>
  31   type-spec can be any of the following: 'bootup', 'reboot', 'shutdown',
  32   'suspend', 'resume' and 'other'.
  33
  34   All directives enclosed in a <type> section will be effective only if
  35   one of the processes specified in 'type-spec' is taking place.  If a
  36   directive is not contained in a <type> section, it is effective regardless
  37   of which process is taking place.
  38
  39   Example:
  40
  41   # Progress bar for boot-up.
  42   <type bootup>
  43      box silent inter 0    262  0    337  #22222c #191920 #383849 #2e2e3d
  44          box silent       0    262  799  337  #22222c #191920 #383849 #2e2e3d
  45   </type>
  46
  47   # Progress bar for reboot/shutdown.
  48   <type reboot shutdown>
  49      box silent inter 0    262  799  337  #22222c #191920 #383849 #2e2e3d
  50      box silent       0    262  0    337  #22222c #191920 #383849 #2e2e3d
  51   </type>
  52
  53 * <textbox>..</textbox>
  54
  55   Directives enclosed in this section will be assumed to form an integral
  56   part of a textbox that is only to be displayed on an explicit request
  57   by the user (by a config file setting or by pressing F3 when fbsplash is
  58   active).
  59
  60   The textbox usually contains the fbsplash message log.
  61
  62   Example:
  63   <textbox>
  64      text silent dejavu.ttf 12 100 100 #ffffff "System messages:"
  65          text silent courier.ttf 10 100 120 #eeeeee msglog
  66   </textbox>
  67
  68
  69 2.2 Silent mode directives
  70 --------------------------
  71
  72 * silentpic=<path>
  73   Relative path to the JPG/PNG background image for silent mode.
  74
  75 * silentpic256=<path>
  76   Relative path to the PNG background image for silent splash mode and 8 bpp
  77   video modes.
  78
  79   NOTES:
  80   - The image can have a maximum of 256 colors.
  81
  82 * log_lines=<n>
  83   Number of lines to display from the fbsplash message log.
  84
  85 * log_cols=<n>
  86   Number of columns to display from the fbsplash message log.
  87
  88 * text_x=<n>
  89   The x coordinate of the main system message.
  90
  91 * text_y=<n>
  92   The y coordinate of the main system message.
  93
  94 * text_size=<n>
  95   The size of the font used to render the main system message.
  96
  97 * text_color=<color>
  98   The color of the main system message either in [0x|#]rrggbb or in
  99   [0x|#]rrggbbaa format.
 100
 101 * text_font=<file>
 102   A path to the TTF font with which the main system message will be rendered.
 103   The path can be either:
 104    - an absolute path, starting with '/',
 105    - a path relative to THEME_DIR (eg. /etc/splash),
 106    - a path relative to THEME_DIR/<theme_name> (eg. /etc/splash/default),
 107
 108 * text [flags] <font> [style] <size> <x> [left|middle|right]
 109   <y> [top|middle|bottom] <color> ([exec] [eval] "text" | msglog)
 110
 111   Draws an UTF8-encoded text string somewhere on the screen.
 112
 113   Flags:
 114   silent  - The text is rendered only in silent mode.
 115   verbose - The text is rendered only in verbose mode.
 116
 117   If no flags are specified, the text is rendered in both modes.
 118
 119   'font' is the name of the file with a TTF font. The path is interpreted in
 120   the same way as in the case of the 'text_font' configuration directive.
 121
 122   'style' can be used to select a bold/italic/underlined form. The style
 123   selector is formed with the following characters:
 124
 125    'b' - bold
 126    'i' - italic
 127    'u' - underlined
 128
 129   Example:
 130    A style selector for a bold italic font: bi
 131
 132   The color can be specified either as #rrggbb or as #rrggbbaa.
 133
 134   The x and y coordinates specify the position of the hot spot of the text
 135   string. The position of the hot spot within the bounding rectangle of the
 136   text string can be chosen with the 'left', 'middle' and 'right', 'top'
 137   and 'bottom' flags.
 138
 139   The different positions of the hot spot are shown below:
 140
 141  (lt)-------------------------(mt)----------------------------(rt)
 142   | TTTTTT EEEEE  SSSS TTTTTT      TTTTTT EEEEE XX  XX TTTTTT   |
 143   |   TT   EE    SS      TT          TT   EE     XXXX    TT     |
 144  (lm) TT   EEEE   SSS    TT   (mm)   TT   EEEE    XX     TT   (rm)
 145   |   TT   EE       SS   TT          TT   EE     XXXX    TT     |
 146   |   TT   EEEEE SSSS    TT          TT   EEEEE XX  XX   TT     |
 147  (lb)-------------------------(mb)----------------------------(rb)
 148
 149   lt = left/top
 150   mt = middle/top
 151   rt = right/top
 152   lm = left/middle
 153   ...
 154
 155   The default position of the hot spot is (lt) (left - top).
 156
 157   Before the text is rendered/evaluated, all expressions of the form:
 158   '\x', where 'x' is any character, are replaced by 'x'.
 159
 160   If the 'exec' flag is set, sh -c 'text' is executed, and the value
 161   read from stdout is rendered on the screen.
 162
 163   If the 'eval' flag is set, evaluation is performed on the 'text'
 164   argument. Variables of the form $variablename are replaced by their
 165   values. Recognized variables:
 166    - $progress - progress indicator (in percents)
 167
 168   If the 'msglog' flag is set, the text object will display the
 169   contents of the fbsplash message log.
 170
 171   The 'text' argument has to be enclosed in double quotes.
 172
 173 * box [flags] <x0> <y0> <x1> <y1> <color1> [color2 color3 color4]
 174   Draws a box on the screen.
 175
 176   Flags:
 177   silent - The box is drawn only in silent mode. If a box doesn't have
 178            this flag set, it's drawn only in verbose mode.
 179   noover - This stands for no-overpaint. Boxes with this flag set are
 180            painted only when progress == 0 or the repaint command is used.
 181   inter  - The box will be interpolated with the following one, based
 182            on the value of the progress variable.
 183
 184   x0, y0 - coordinates of the upper left corner of the box
 185   x1, y1 - coordinates of the lower right corner of the box
 186
 187   Colors are specified in one of the following formats:
 188   - #rrggbb
 189   - #rrggbbaa
 190   aa = alpha, 00 - translucent, ff - solid
 191
 192   If only color1 is specified, the box is filled with the color.
 193   If all four colors are specified, then:
 194
 195   color1   is the color of the   upper left    corner of the box,
 196   color2   is the color of the   upper right   corner of the box,
 197   color3   is the color of the   lower left    corner of the box,
 198   color4   is the color of the   lower right   corner of the box,
 199
 200   and the box is filled with a gradient formed by these colors.
 201
 202 * icon <path> <x> <y> [crop from to] [state service]
 203   Draws an icon (a PNG image) at coordinates x, y, based on
 204   the current state of a service.
 205
 206   If the 'crop' keyword is used, the icon will be cropped by a
 207   rectangle interpolated between 'from' and 'to', based on the
 208   value of the progress variable. 'from' and 'to' are both
 209   rectangles described in the icon coordinate system using the
 210   following format:
 211
 212     <x0, y0, x1, y1>
 213
 214   In the icon coordinate system, the icon's top left corner
 215   is at (0,0).
 216
 217   'state' can be one of the following:
 218   svc_inactive_start,   svc_inactive_stop,
 219   svc_started,          svc_stopped,
 220   svc_start_failed,     svc_stop_failed,
 221   svc_start,            svc_stop,
 222
 223   'service' is the name of the system service.
 224
 225   An icon will be rendered on the screen only if its state has
 226   been set through an appropriate splash daemon command.
 227
 228   Examples:
 229
 230    1) icon img/logo.png 100 100 crop <0,0,49,0> <0,0,49,199>
 231       The image from img/logo.png will be painted at (100,100)
 232       (ie. at the 101-th pixel from the left and from the top).
 233
 234       The image will be cropped. When progress == 0, no part of
 235       it will be displayed on the screen (height of the first
 236       rectangle is equal to 0). As the progress increases, the
 237       image will be extended downward, until it reaches the
 238       full size of 50 x 200 pixels.
 239
 240 * anim <once|loop|proportional> <path> <x> <y> [state service]
 241
 242   Displays a MNG animation on the silent splash screen at (x,y).
 243
 244   'once' -- the animation is displayed only once. After it reaches its
 245             last frame, it is displayed just like an icon.
 246
 247   'loop' -- the animation is displayed in an infinite loop.
 248
 249   'proportional' -- the animation progress is coupled with the progress
 250                     variable. Note that in this case, the animation
 251                     isn't smooth and only single frames are displayed.
 252
 253   Depending on how the mng file is constructed 'once' and 'proportional'
 254   might not work as aspected. When the file is internally looped, the
 255   animation will always be displayed in an infinite loop (even when
 256   the 'once' flag is used). When the file doesn't contain a frame
 257   counter, 'proportional' will not work and only the first frame will
 258   be displayed.
 259
 260   The animations are displayed only when the screen is painted by the
 261   splash daemon, they won't work with the kernel helper (i.e. the animations
 262   won't work from an initrd).
 263
 264
 265 2.3 Special effects modifiers
 266 -----------------------------
 267
 268 Each of the following object directives: box, text, icon, anim can be
 269 directly followed by a whitespace-separated set of special effect
 270 modifiers:
 271
 272 * blendin(time)
 273   When the object becomes visible, its alpha is smoothly changed from
 274   0% (transparent) to 100% (full opacity).  Time is specified in
 275   miliseconds.
 276
 277 * blendout(time)
 278   When the object becomes invisible, its alpha is smoothly changed from
 279   100% (full opacity) to 0% (invisible).  Time is specified in
 280   miliseconds.
 281
 282 The notion of changing the visibility of an object refers to one of the
 283 following:
 284 - the first time the object is displayed,
 285 - a change of the status of a service causing the object to be shown/hidden.
 286
 287
 288 2.4 Verbose mode settings (for fbcondecor)
 289 ------------------------------------------
 290
 291 * pic=<path>
 292   Relative path to the JPG/PNG background image for verbose mode.
 293
 294 * pic256=<path>
 295   Relative path to the PNG background image for verbose splash mode and 8 bpp
 296   video modes.
 297
 298   NOTES:
 299   - The image can have a maximum of 240 colors. 16 colors are taken by fbcon
 300     and cannot be used in the picture.
 301
 302 * bgcolor=<n>
 303   Background color which is to be treated as transparent by fbcon. Usually 0.
 304
 305 * tx=<n>
 306   The x coordinate of the upper left corner of the text window.
 307
 308 * ty=<n>
 309   The y coordinate of the upper left corner of the text window.
 310
 311 * tw=<n>
 312   The width of the text window. n cannot be greater than horizontal resolution.
 313
 314 * th=<n>
 315   The height of the text window. n cannot be greater than vertical resolution.
 316
 317
 318 2.5 Deprecated settings
 319 ------------------------
 320 * jpeg=<path>
 321   Relative path to the JPG background image for verbose mode.
 322   (Use pic=<path> instead.)
 323
 324 * silentjpeg=<path>
 325   Relative path to the JPG background image for silent mode.
 326   (Use silentpic=<path> instead.)
 327
 328