2 .\" SPDX-License-Identifier: BSD-2-Clause
4 .\" Copyright (c) 2018 Kyle Evans <kevans@FreeBSD.org>
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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
32 .Nd FreeBSD menu/screen drawer module
35 contains functionality for drawing and manipulating the menu, logo, and brand
38 Before using the functionality provided by
40 it must be included with a statement such as the following:
42 .Dl local drawer = require("drawer")
44 Brand definitions describe a
46 traditionally drawn above the menu.
47 The exact position may be controlled by using the
53 The following keys may be defined for a brand definition:
54 .Bl -tag -width ".Ic Graphic" -offset indent
56 A table of strings containing rows of text to be drawn to the screen.
59 Logo definitions describe a
61 traditionally to the right of the menu.
62 The exact position may be controlled by using the
68 The following keys may be defined for a logo definition:
69 .Bl -tag -width ".Ic requires_color" -offset indent
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,
74 will elect to use the default
76 logo rather than the chosen logo.
78 A table of strings containing rows of text to be drawn to the screen.
80 A table describing the
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
88 .Ss CUSTOM BRANDS AND LOGOS
89 The brand and logo system is designed to allow brands and logos to be easily
97 will attempt to include
98 .Pa brand-${loader_brand}.lua
100 .Pa logo-${loader_logo}.lua
102 These files are expected to call either
106 to add the requested branddef or logodef.
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
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
121 has been configured to not output color.
125 contains the definitions for the different frame styles that may be drawn around
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 ""
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
152 .Bl -tag -width hook.registerType -offset indent
153 .It Fn drawer.addBrand name def
154 Add the brand definition described by
156 to the table of known brand definitions, indexed by
158 .It Fn drawer.addLogo name def
159 Add the logo definition described by
161 to the table of known logo definitions, indexed by
163 .It Fn drawer.drawscreen menudef
164 Draws the logo, brand, menu frame, and the current menu as described in
166 formatted as defined by
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 .