stand/lua/drawer.lua.8

   1 .\"
   2 .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
   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 .\" $FreeBSD$
  28 .\"
  29 .Dd August 19, 2018
  30 .Dt DRAWER.LUA 8
  31 .Os
  32 .Sh NAME
  33 .Nm drawer.lua
  34 .Nd FreeBSD menu/screen drawer module
  35 .Sh DESCRIPTION
  36 .Nm
  37 contains functionality for drawing and manipulating the menu, logo, and brand
  38 to the screen.
  39 .Pp
  40 Before using the functionality provided by
  41 .Nm ,
  42 it must be included with a statement such as the following:
  43 .Pp
  44 .Dl local drawer = require("drawer")
  45 .Ss BRAND DEFINITIONS
  46 Brand definitions describe a
  47 .Dq brand ,
  48 traditionally drawn above the menu.
  49 The exact position may be controlled by using the
  50 .Xr loader.conf 5
  51 variables
  52 .Va loader_brand_x
  53 and
  54 .Va loader_brand_y .
  55 The following keys may be defined for a brand definition:
  56 .Bl -tag -width ".Ic Graphic" -offset indent
  57 .It Ic graphic
  58 A table of strings containing rows of text to be drawn to the screen.
  59 .El
  60 .Ss LOGO DEFINITIONS
  61 Logo definitions describe a
  62 .Dq logo ,
  63 traditionally to the right of the menu.
  64 The exact position may be controlled by using the
  65 .Xr loader.conf 5
  66 variables
  67 .Va loader_logo_x
  68 and
  69 .Va loader_logo_y .
  70 The following keys may be defined for a logo definition:
  71 .Bl -tag -width ".Ic requires_color" -offset indent
  72 .It Ic requires_color
  73 A boolean describing whether or not this logo definition requires color.
  74 If it is chosen to be drawn and it requires color on a color-disabled boot,
  75 .Nm
  76 will elect to use the default
  77 .Dq orbbw
  78 logo rather than the chosen logo.
  79 .It Ic graphic
  80 A table of strings containing rows of text to be drawn to the screen.
  81 .It Ic shift
  82 A table describing the
  83 .Va x
  84 and
  85 .Va y
  86 shift that should be applied to all elements should this logo be selected.
  87 This is typically used for shifting the menu and brand if an empty or minimal
  88 logo are selected.
  89 .El
  90 .Ss CUSTOM BRANDS AND LOGOS
  91 The brand and logo system is designed to allow brands and logos to be easily
  92 plugged in.
  93 When an unrecognized
  94 .Ev loader_brand
  95 or
  96 .Ev loader_logo
  97 are encountered,
  98 .Nm
  99 will attempt to include
 100 .Pa brand-${loader_brand}.lua
 101 or
 102 .Pa logo-${loader_logo}.lua
 103 respectively.
 104 These files are expected to call either
 105 .Fn drawer.addBrand
 106 or
 107 .Fn drawer.addLogo
 108 to add the requested branddef or logodef.
 109 .Nm
 110 will attempt to do another lookup for the requested brand or logo before falling
 111 back to one of the following:
 112 .Bl -tag -width ".Ic drawer.default_color_logodef" -offset indent
 113 .It Ic drawer.default_brand
 114 The default brand to be used if the requested brand cannot be located.
 115 .It Ic drawer.default_color_logodef
 116 The default logodef to be used if an invalid logodef is requested and
 117 .Xr loader 8
 118 has been configured to allow output of color.
 119 .It Ic drawer.default_bw_logodef
 120 The default logodef to be used if either an invalid logodef has been requested,
 121 or a logodef has been requested that requires color and
 122 .Xr loader 8
 123 has been configured to not output color.
 124 .El
 125 .Ss FRAME STYLES
 126 .Nm
 127 contains the definitions for the different frame styles that may be drawn around
 128 the menu.
 129 Frame styles define the characters drawn for horizontal lines, vertical aligns,
 130 and each of the four corner styles.
 131 The following keys may be defined for a frame style:
 132 .Bl -bullet -width ""
 133 .It
 134 horizontal
 135 .It
 136 vertical
 137 .It
 138 top_left
 139 .It
 140 bottom_left
 141 .It
 142 top_right
 143 .It
 144 bottom_right
 145 .El
 146 Frame styles are currently defined in the table
 147 .Ic drawer.frame_styles
 148 indexed by the name used for
 149 .Ev loader_menu_frame .
 150 No API currently exists for manipulating this table indirectly.
 151 .Ss Exported functions
 152 The following functions are exported from
 153 .Nm :
 154 .Bl -tag -width hook.registerType -offset indent
 155 .It Fn drawer.addBrand name def
 156 Add the brand definition described by
 157 .Fa def
 158 to the table of known brand definitions, indexed by
 159 .Fa name .
 160 .It Fn drawer.addLogo name def
 161 Add the logo definition described by
 162 .Fa def
 163 to the table of known logo definitions, indexed by
 164 .Fa name .
 165 .It Fn drawer.drawscreen menudef
 166 Draws the logo, brand, menu frame, and the current menu as described in
 167 .Fa menudef ,
 168 formatted as defined by
 169 .Xr menu.lua 8 .
 170 .El
 171 .Sh SEE ALSO
 172 .Xr menu.lua 8
 173 .Sh AUTHORS
 174 The
 175 .Nm
 176 file was originally written by
 177 .An Pedro Souza Aq Mt pedrosouza@FreeBSD.org .
 178 Later work and this manual page was done by
 179 .An Kyle Evans Aq Mt kevans@FreeBSD.org .