1.\" $NetBSD: msgc.1,v 1.20 2003/10/15 20:02:10 wiz Exp $ 2.\" 3.\" Copyright 1997 Piermont Information Systems Inc. 4.\" All rights reserved. 5.\" 6.\" Written by Philip A. Nelson for Piermont Information Systems Inc. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. All advertising materials mentioning features or use of this software 17.\" must display the following acknowledgement: 18.\" This product includes software developed for the NetBSD Project by 19.\" Piermont Information Systems Inc. 20.\" 4. The name of Piermont Information Systems Inc. may not be used to endorse 21.\" or promote products derived from this software without specific prior 22.\" written permission. 23.\" 24.\" THIS SOFTWARE IS PROVIDED BY PIERMONT INFORMATION SYSTEMS INC. ``AS IS'' 25.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 26.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 27.\" ARE DISCLAIMED. IN NO EVENT SHALL PIERMONT INFORMATION SYSTEMS INC. BE 28.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 29.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 30.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 31.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 32.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 33.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 34.\" THE POSSIBILITY OF SUCH DAMAGE. 35.\" 36.Dd September 25, 2003 37.Os 38.Dt MSGC 1 39.Sh NAME 40.Nm msgc , 41.Nm msg_window , 42.Nm msg_string , 43.Nm msg_clear , 44.Nm msg_standout , 45.Nm msg_standend , 46.Nm msg_display , 47.Nm msg_display_add , 48.Nm msg_prompt , 49.Nm msg_prompt_add , 50.Nm msg_prompt_win , 51.Nm msg_prompt_noecho , 52.Nm msg_row , 53.Nm msg_table_add 54.Nd simple message list compiler 55.Sh SYNOPSIS 56msgc 57.Op Fl o Ar name 58.Ar file 59.Pp 60.Fd #include \b'"'msg_defs.h\b'"' 61.Ft void 62.Fn msg_window "WINDOW *window" 63.Ft const char * 64.Fn msg_string "msg msg_no" 65.Ft void 66.Fn msg_clear "void" 67.Ft void 68.Fn msg_standout "void" 69.Ft void 70.Fn msg_standend "void" 71.Ft void 72.Fn msg_display "msg msg_no" ... 73.Ft void 74.Fn msg_display_add "msg msg_no" ... 75.Ft void 76.Fn msg_prompt "msg msg_no" "const char *def" "char *val" "int max_chars" ... 77.Ft void 78.Fn msg_prompt_add "msg msg_no" "const char *def" "char *val" "int max_chars" ... 79.Ft void 80.Fn msg_prompt_win "msg msg_no" "WINDOW *win" "const char *def" "char *val" "int max_chars" ... 81.Ft void 82.Fn msg_prompt_noecho "msg msg_no" "const char *def" "char *val" "int max_chars" ... 83.Ft int 84.Fn msg_row "void" 85.Ft void 86.Fn msg_table_add "msg msg_no" ... 87.Sh DESCRIPTION 88This implements a curses based message display system. 89A source file that lists messages with associated names is given to 90.Nm 91and produces both a .c and a .h file that implement the menu system. 92The standard root name of the files is 93.Pa msg_defs . 94The 95.Fl o Ar name 96can be used to specify a different root name. 97.Sh ENVIRONMENT 98.Bl -tag -width MSGDEF 99.It Ev MSGDEF 100Can be set to point to a different set of 101definition files for 102.Nm msgc . 103The current location defaults to 104.Pa /usr/share/misc . 105.El 106.Sh FILES 107.Bl -item -width /usr/share/misc/msg_sys.def 108.It 109.Pa /usr/share/misc/msg_sys.def 110.El 111.Sh SOURCE DESCRIPTION 112The format is very simple. 113Each message is started with the word 114.Sq message 115followed by the name of the message. 116The body of the message is next and is started by a { and closed by a }. 117The braces are not part of the message. 118Everything, including newlines between the braces are part of the message. 119.Sh MESSAGE FUNCTIONS 120The defined messages are used through calls routines that manipulate 121the messages. 122You first need to set the 123.Xr curses 3 124environment up and then tell the message system which window to use 125for displaying message by calling the function 126.Fn msg_window . 127.Pp 128All variable argument lists in the functions are used as 129are arguments to 130.Xr sprintf 3 . 131The messages may have 132.Xr sprintf 3 133conversions in them and the corresponding parameters should match. 134Messages are identified by name using the notation 135.Sq MENU_name 136where 137.Dq name 138is the name in the message source file. 139(The definitions are accessed by including the generated .h file into a 140source file wanting to use the message routines.) 141.Pp 142The function 143.Fn msg_string 144just returns a pointer to the actual message string. 145The functions 146.Fn msg_clear , 147.Fn msg_standout 148and 149.Fn msg_standend 150respectively clear the message window, set standout mode and clear standout 151mode. 152.Pp 153The functions 154.Fn msg_display 155and 156.Fn msg_display_add 157cause a defined message to be displayed in the message window and does 158the requested conversions before printing. 159The difference is that 160.Fn msg_display 161clears the window before displaying the message. 162These functions fill paragraphs for readability. 163The 164.Fn msg_table_add 165function behaves like 166.Fn msg_display_add 167but does not fill text. 168.Pp 169The remaining functions deal with a prompt facility. 170A prompt message is either taken from the message directory or from a 171given string. 172The message is processed with 173.Xr sprintf 3 174and then displayed. 175If the parameter 176.Ar def 177is 178.No non- Ns Dv NULL 179and not a string of zero length, a default value is printed 180in brackets. 181The user is allowed to type in a response. 182If the user types just the newline character, the default is returned 183in the value. 184The parameter 185.Ar max_chars 186is the length of the parameter 187.Ar val , 188where the results are stored. 189The parameters 190.Ar def 191and 192.Ar val 193may point to the same character array. 194If the default is chosen, the character array is not changed. 195The functions 196.Fn msg_echo 197and 198.Fn msg_noecho 199control whether the prompt routine echo or don't echo the input that 200is typed by the user. 201.Pp 202.Fn msg_prompt_win 203uses the specified curses window instead of the default one. 204.Pp 205.Fn msg_row 206return the current row - i.e.: getcury(msg_win) + getbegy(msg_win). 207.Sh AUTHORS 208Philip A. Nelson for Piermont Information Systems Inc. 209