lib/libmenu/menus.3

   1 .\"     $NetBSD: menus.3,v 1.14 2002/10/01 19:27:00 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1999
   4 .\"     Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au
   5 .\"
   6 .\" This code is donated to The NetBSD Foundation by the author.
   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 the Author may not be used to endorse or promote
  17 .\"    products derived from this software without specific prior written
  18 .\"    permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
  21 .\" 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 THE AUTHOR BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .Dd September 10, 1999
  33 .Dt MENUS 3
  34 .Os
  35 .Sh NAME
  36 .Nm menus
  37 .Nd menu library
  38 .Sh LIBRARY
  39 .Lb libmenu
  40 .Sh SYNOPSIS
  41 .In menu.h
  42 .Sh DESCRIPTION
  43 The
  44 .Nm
  45 library provides a terminal independent menu system using the
  46 .Xr curses 3
  47 library.
  48 Before using the
  49 .Nm
  50 functions the terminal must be set up by
  51 .Xr curses 3
  52 using the
  53 .Fn initscr
  54 function or similar.
  55 Programs using
  56 .Nm
  57 functions must be linked with the
  58 .Xr curses 3
  59 library.
  60 .Pp
  61 The
  62 .Nm
  63 library provides facilities for defining menu items, placing a menu on the
  64 terminal screen, assign pre- and post-change operations and setting the
  65 attributes of both the menu and its items.
  66 .Ss Defining default attributes for menus and items
  67 The
  68 .Nm
  69 library allows any settable attribute or option of both the menu and item
  70 objects to be defined such that any new menu or item automatically inherits
  71 the value as default.
  72 Setting the default value will not affect any item or
  73 menu that has already been created but will be applied to subsequent objects.
  74 To set the default attribute or option the set routine is passed a NULL
  75 pointer in the item or menu parameter when calling the set routine.
  76 The current default value can be retrieved by calling the get routine with a
  77 NULL pointer for the item or menu parameter.
  78 .Pp
  79 .Bl -tag -width item_description -compact
  80 .It function name
  81 manual page name
  82 .It current_item
  83 .Xr menu_item_current 3
  84 .It free_item
  85 .Xr menu_item_new 3
  86 .It free_menu
  87 .Xr menu_new 3
  88 .It item_count
  89 .Xr menu_items 3
  90 .It item_description
  91 .Xr menu_item_name 3
  92 .It item_index
  93 .Xr menu_item_current 3
  94 .It item_init
  95 .Xr menu_hook 3
  96 .It item_name
  97 .Xr menu_item_name 3
  98 .It item_opts
  99 .Xr menu_item_opts 3
 100 .It item_opts_off
 101 .Xr menu_item_opts 3
 102 .It item_opts_on
 103 .Xr menu_item_opts 3
 104 .It item_selected
 105 .Xr menu_item_value 3
 106 .It item_term
 107 .Xr menu_hook 3
 108 .It item_userptr
 109 .Xr menu_item_userptr 3
 110 .It item_value
 111 .Xr menu_item_value 3
 112 .It item_visible
 113 .Xr menu_item_visible 3
 114 .It menu_back
 115 .Xr menu_attributes 3
 116 .It menu_driver
 117 .Xr menu_driver 3
 118 .It menu_fore
 119 .Xr menu_attributes 3
 120 .It menu_format
 121 .Xr menu_format 3
 122 .It menu_grey
 123 .Xr menu_attributes 3
 124 .It menu_init
 125 .Xr menu_hook 3
 126 .It menu_items
 127 .Xr menu_items 3
 128 .It menu_mark
 129 .Xr menu_mark 3
 130 .It menu_opts
 131 .Xr menu_opts 3
 132 .It menu_opts_off
 133 .Xr menu_opts 3
 134 .It menu_opts_on
 135 .Xr menu_opts 3
 136 .It menu_pad
 137 .Xr menu_attributes 3
 138 .It menu_pattern
 139 .Xr menu_pattern 3
 140 .It menu_sub
 141 .Xr menu_win 3
 142 .It menu_term
 143 .Xr menu_hook 3
 144 .It menu_unmark
 145 .Xr menu_mark 3
 146 .It menu_userptr
 147 .Xr menu_userptr 3
 148 .It men_win
 149 .Xr menu_win 3
 150 .It new_item
 151 .Xr menu_item_new 3
 152 .It new_menu
 153 .Xr menu_new 3
 154 .It pos_menu_cursor
 155 .Xr menu_cursor 3
 156 .It post_menu
 157 .Xr menu_post 3
 158 .It scale_menu
 159 .Xr menu_win 3
 160 .It set_current_item
 161 .Xr menu_item_current 3
 162 .It set_item_init
 163 .Xr menu_hook 3
 164 .It set_item_opts
 165 .Xr menu_item_opts 3
 166 .It set_item_term
 167 .Xr menu_hook 3
 168 .It set_item_userptr
 169 .Xr menu_item_userptr 3
 170 .It set_item_value
 171 .Xr menu_item_value 3
 172 .It set_menu_back
 173 .Xr menu_attributes 3
 174 .It set_menu_fore
 175 .Xr menu_attributes 3
 176 .It set_menu_format
 177 .Xr menu_format 3
 178 .It set_menu_grey
 179 .Xr menu_attributes 3
 180 .It set_menu_init
 181 .Xr menu_hook 3
 182 .It set_menu_items
 183 .Xr menu_items 3
 184 .It set_menu_mark
 185 .Xr menu_mark 3
 186 .It set_menu_opts
 187 .Xr menu_opts 3
 188 .It set_menu_pad
 189 .Xr menu_attributes 3
 190 .It set_menu_pattern
 191 .Xr menu_pattern 3
 192 .It set_menu_sub
 193 .Xr menu_win 3
 194 .It set_menu_term
 195 .Xr menu_hook 3
 196 .It set_menu_unmark
 197 .Xr menu_mark 3
 198 .It set_menu_userptr
 199 .Xr menu_userptr 3
 200 .It set_menu_win
 201 .Xr menu_win 3
 202 .It set_top_row
 203 .Xr menu_item_current 3
 204 .It top_row
 205 .Xr menu_item_current 3
 206 .It unpost_menu
 207 .Xr menu_post 3
 208 .El
 209 .Sh RETURN VALUES
 210 Any function returning a string pointer will return NULL if an error
 211 occurs.
 212 Functions returning an integer will return one of the following:
 213 .Pp
 214 .Bl -tag -width E_UNKNOWN_COMMAND -compact
 215 .It Er E_OK
 216 The function was successful.
 217 .It Er E_SYSTEM_ERROR
 218 There was a system error during the call.
 219 .It Er E_BAD_ARGUMENT
 220 One or more of the arguments passed to the function was incorrect.
 221 .It Er E_POSTED
 222 The menu is already posted.
 223 .It Er E_CONNECTED
 224 An item was already connected to a menu.
 225 .It Er E_BAD_STATE
 226 The function was called from within an initialization or termination
 227 routine.
 228 .It Er E_NO_ROOM
 229 The menu does not fit within the subwindow.
 230 .It Er E_NOT_POSTED
 231 The menu is not posted.
 232 .It Er E_UNKNOWN_COMMAND
 233 The menu driver does not recognize the request passed to it.
 234 .It Er E_NO_MATCH
 235 The character search failed to find a match.
 236 .It Er E_NOT_SELECTABLE
 237 The item could not be selected.
 238 .It Er E_NOT_CONNECTED
 239 The item is not connected to a menu.
 240 .It Er E_REQUEST_DENIED
 241 The menu driver could not process the request.
 242 .El
 243 .Sh SEE ALSO
 244 .Xr curses 3 ,
 245 .Xr menu_attributes 3 ,
 246 .Xr menu_cursor 3 ,
 247 .Xr menu_driver 3 ,
 248 .Xr menu_format 3 ,
 249 .Xr menu_hook 3 ,
 250 .Xr menu_item_current 3 ,
 251 .Xr menu_item_name 3 ,
 252 .Xr menu_item_new 3 ,
 253 .Xr menu_item_opts 3 ,
 254 .Xr menu_item_userptr 3 ,
 255 .Xr menu_item_value 3 ,
 256 .Xr menu_item_visible 3 ,
 257 .Xr menu_items 3 ,
 258 .Xr menu_mark 3 ,
 259 .Xr menu_new 3 ,
 260 .Xr menu_opts 3 ,
 261 .Xr menu_pattern 3 ,
 262 .Xr menu_post 3 ,
 263 .Xr menu_userptr 3 ,
 264 .Xr menu_win 3
 265 .Sh NOTES
 266 This implementation of the menus library does depart in behaviour
 267 subtly from the original AT \*[Am] T implementation.
 268 Some of the more notable departures are:
 269 .Pp
 270 .Bl -tag -width "item marking" -compact
 271 .It unmark
 272 The original implementation did not have a marker for an unmarked field
 273 the mark was only displayed next to a field when it had been marked using
 274 the REQ_TOGGLE_ITEM.
 275 In this implementation a separate marker can be used
 276 to indicate an unmarked item.
 277 This can be set using set_menu_unmark function.
 278 There is no requirement for the mark and unmark strings to be the same
 279 length.
 280 Room will be left for the longest of the two.
 281 The unmark string
 282 is optional, if it is not set then menus defaults to the old behaviour.
 283 .It item marking
 284 In the original implementation the current item was considered selected
 285 and hence had the mark string displayed next to it.
 286 This implementation does not do this because the Author considers the
 287 effect too confusing.
 288 Especially in the case of a multiple selection menu because there was no
 289 way to tell if the current item is selected or not without shifting off
 290 of it.
 291 Since the current item is displayed using the foreground attribute it was
 292 deemed unnecessary to also display the mark string against the current item.
 293 .El
 294 .Pp
 295 The option O_RADIO and the function
 296 .Fn item_selected
 297 are
 298 .Nx
 299 extensions and must not be used in portable code.