stand/lua/drawer.lua.8

   1 .\"
   2 .\" SPDX-License-Identifier: BSD-2-Clause
   3 .\"
   4 .\" Copyright (c) 2018 Kyle Evans <kevans@FreeBSD.org>
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .Dd August 19, 2018
  28 .Dt DRAWER.LUA 8
  29 .Os
  30 .Sh NAME
  31 .Nm drawer.lua
  32 .Nd FreeBSD menu/screen drawer module
  33 .Sh DESCRIPTION
  34 .Nm
  35 contains functionality for drawing and manipulating the menu, logo, and brand
  36 to the screen.
  37 .Pp
  38 Before using the functionality provided by
  39 .Nm ,
  40 it must be included with a statement such as the following:
  41 .Pp
  42 .Dl local drawer = require("drawer")
  43 .Ss BRAND DEFINITIONS
  44 Brand definitions describe a
  45 .Dq brand ,
  46 traditionally drawn above the menu.
  47 The exact position may be controlled by using the
  48 .Xr loader.conf 5
  49 variables
  50 .Va loader_brand_x
  51 and
  52 .Va loader_brand_y .
  53 The following keys may be defined for a brand definition:
  54 .Bl -tag -width ".Ic Graphic" -offset indent
  55 .It Ic graphic
  56 A table of strings containing rows of text to be drawn to the screen.
  57 .El
  58 .Ss LOGO DEFINITIONS
  59 Logo definitions describe a
  60 .Dq logo ,
  61 traditionally to the right of the menu.
  62 The exact position may be controlled by using the
  63 .Xr loader.conf 5
  64 variables
  65 .Va loader_logo_x
  66 and
  67 .Va loader_logo_y .
  68 The following keys may be defined for a logo definition:
  69 .Bl -tag -width ".Ic requires_color" -offset indent
  70 .It Ic requires_color
  71 A boolean describing whether or not this logo definition requires color.
  72 If it is chosen to be drawn and it requires color on a color-disabled boot,
  73 .Nm
  74 will elect to use the default
  75 .Dq orbbw
  76 logo rather than the chosen logo.
  77 .It Ic graphic
  78 A table of strings containing rows of text to be drawn to the screen.
  79 .It Ic shift
  80 A table describing the
  81 .Va x
  82 and
  83 .Va y
  84 shift that should be applied to all elements should this logo be selected.
  85 This is typically used for shifting the menu and brand if an empty or minimal
  86 logo are selected.
  87 .El
  88 .Ss CUSTOM BRANDS AND LOGOS
  89 The brand and logo system is designed to allow brands and logos to be easily
  90 plugged in.
  91 When an unrecognized
  92 .Ev loader_brand
  93 or
  94 .Ev loader_logo
  95 are encountered,
  96 .Nm
  97 will attempt to include
  98 .Pa brand-${loader_brand}.lua
  99 or
 100 .Pa logo-${loader_logo}.lua
 101 respectively.
 102 These files are expected to call either
 103 .Fn drawer.addBrand
 104 or
 105 .Fn drawer.addLogo
 106 to add the requested branddef or logodef.
 107 .Nm
 108 will attempt to do another lookup for the requested brand or logo before falling
 109 back to one of the following:
 110 .Bl -tag -width ".Ic drawer.default_color_logodef" -offset indent
 111 .It Ic drawer.default_brand
 112 The default brand to be used if the requested brand cannot be located.
 113 .It Ic drawer.default_color_logodef
 114 The default logodef to be used if an invalid logodef is requested and
 115 .Xr loader 8
 116 has been configured to allow output of color.
 117 .It Ic drawer.default_bw_logodef
 118 The default logodef to be used if either an invalid logodef has been requested,
 119 or a logodef has been requested that requires color and
 120 .Xr loader 8
 121 has been configured to not output color.
 122 .El
 123 .Ss FRAME STYLES
 124 .Nm
 125 contains the definitions for the different frame styles that may be drawn around
 126 the menu.
 127 Frame styles define the characters drawn for horizontal lines, vertical aligns,
 128 and each of the four corner styles.
 129 The following keys may be defined for a frame style:
 130 .Bl -bullet -width ""
 131 .It
 132 horizontal
 133 .It
 134 vertical
 135 .It
 136 top_left
 137 .It
 138 bottom_left
 139 .It
 140 top_right
 141 .It
 142 bottom_right
 143 .El
 144 Frame styles are currently defined in the table
 145 .Ic drawer.frame_styles
 146 indexed by the name used for
 147 .Ev loader_menu_frame .
 148 No API currently exists for manipulating this table indirectly.
 149 .Ss Exported functions
 150 The following functions are exported from
 151 .Nm :
 152 .Bl -tag -width hook.registerType -offset indent
 153 .It Fn drawer.addBrand name def
 154 Add the brand definition described by
 155 .Fa def
 156 to the table of known brand definitions, indexed by
 157 .Fa name .
 158 .It Fn drawer.addLogo name def
 159 Add the logo definition described by
 160 .Fa def
 161 to the table of known logo definitions, indexed by
 162 .Fa name .
 163 .It Fn drawer.drawscreen menudef
 164 Draws the logo, brand, menu frame, and the current menu as described in
 165 .Fa menudef ,
 166 formatted as defined by
 167 .Xr menu.lua 8 .
 168 .El
 169 .Sh SEE ALSO
 170 .Xr menu.lua 8
 171 .Sh AUTHORS
 172 The
 173 .Nm
 174 file was originally written by
 175 .An Pedro Souza Aq Mt pedrosouza@FreeBSD.org .
 176 Later work and this manual page was done by
 177 .An Kyle Evans Aq Mt kevans@FreeBSD.org .