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