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