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