gnu/lib/libdialog/dialog.3

   1 .\"
   2 .\" Copyright (c) 1995, Jordan Hubbard
   3 .\"
   4 .\" All rights reserved.
   5 .\"
   6 .\" This manual page may be used, modified, copied, distributed, and
   7 .\" sold, in both source and binary form provided that the above
   8 .\" copyright and these terms are retained, verbatim, as the first
   9 .\" lines of this file.  Under no circumstances is the author
  10 .\" responsible for the proper functioning of the software described herein
  11 .\" nor does the author assume any responsibility for damages incurred with
  12 .\" its use.
  13 .\"
  14 .\" $FreeBSD$
  15 .\"
  16 .Dd January 1, 2000
  17 .Dt DIALOG 3
  18 .Os
  19 .Sh NAME
  20 .Nm draw_shadow ,
  21 .Nm draw_box ,
  22 .Nm line_edit ,
  23 .Nm strheight ,
  24 .Nm strwidth ,
  25 .Nm dialog_create_rc ,
  26 .Nm dialog_yesno ,
  27 .Nm dialog_noyes ,
  28 .Nm dialog_prgbox ,
  29 .Nm dialog_msgbox ,
  30 .Nm dialog_textbox ,
  31 .Nm dialog_menu ,
  32 .Nm dialog_checklist ,
  33 .Nm dialog_radiolist ,
  34 .Nm dialog_inputbox ,
  35 .Nm dialog_clear_norefresh ,
  36 .Nm dialog_clear ,
  37 .Nm dialog_update ,
  38 .Nm dialog_fselect ,
  39 .Nm dialog_notify ,
  40 .Nm dialog_mesgbox ,
  41 .Nm dialog_gauge ,
  42 .Nm init_dialog ,
  43 .Nm end_dialog ,
  44 .Nm use_helpfile ,
  45 .Nm use_helpline ,
  46 .Nm get_helpline ,
  47 .Nm restore_helpline ,
  48 .Nm dialog_ftree ,
  49 .Nm dialog_tree
  50 .Nd provide a simple ncurses-based GUI interface
  51 .Sh SYNOPSIS
  52 .In dialog.h
  53 .Ft "void"
  54 .Fn draw_shadow "WINDOW *win" "int y" "int x" "int height" "int width"
  55 .Ft "void"
  56 .Fn draw_box "WINDOW *win" "int y" "int x" "int height" "int width" "chtype box" "chtype border"
  57 .Ft "int"
  58 .Fo line_edit
  59 .Fa "WINDOW *dialog"
  60 .Fa "int box_y"
  61 .Fa "int box_x"
  62 .Fa "int flen"
  63 .Fa "int box_width"
  64 .Fa "chtype attr"
  65 .Fa "int first"
  66 .Fa "unsigned char *result"
  67 .Fa "int attr_mask"
  68 .Fc
  69 .Ft "int"
  70 .Fn strheight "const char *p"
  71 .Ft "int"
  72 .Fn strwidth "const char *p"
  73 .Ft "void"
  74 .Fn dialog_create_rc "unsigned char *filename"
  75 .Ft "int"
  76 .Fn dialog_yesno "unsigned char *title" "unsigned char *prompt" "int height" "int width"
  77 .Ft "int"
  78 .Fn dialog_noyes "unsigned char *title" "unsigned char *prompt" "int height" "int width"
  79 .Ft "int"
  80 .Fn dialog_prgbox "unsigned char *title" "const unsigned char *line" "int height" "int width" "int pause" "int use_shell"
  81 .Ft "int"
  82 .Fn dialog_textbox "unsigned char *title" "unsigned char *file" "int height" "int width"
  83 .Ft "int"
  84 .Fo dialog_menu
  85 .Fa "unsigned char *title"
  86 .Fa "unsigned char *prompt"
  87 .Fa "int height"
  88 .Fa "int width"
  89 .Fa "int menu_height"
  90 .Fa "int cnt"
  91 .Fa "void *it"
  92 .Fa "unsigned char *result"
  93 .Fa "int *ch"
  94 .Fa "int *sc"
  95 .Fc
  96 .Ft "int"
  97 .Fn dialog_checklist "unsigned char *title" "unsigned char *prompt" "int height" "int width" "int list_height" "int cnt" "void *it" "unsigned char *result"
  98 .Ft "int"
  99 .Fn dialog_radiolist "unsigned char *title" "unsigned char *prompt" "int height" "int width" "int list_height" "int cnt" "void *it" "unsigned char *result"
 100 .Ft "int"
 101 .Fn dialog_inputbox "unsigned char *title" "unsigned char *prompt" "int height" "int width" "unsigned char *result"
 102 .Ft "char *"
 103 .Fn dialog_fselect "char *dir" "char *fmask"
 104 .Ft "int"
 105 .Fn dialog_dselect "char *dir" "char *fmask"
 106 .Ft "void"
 107 .Fn dialog_notify "char *msg"
 108 .Ft "int"
 109 .Fn dialog_mesgbox "unsigned char *title" "unsigned char *prompt" "int height" "int width"
 110 .Ft "void"
 111 .Fn dialog_gauge "char *title" "char *prompt" "int y" "int x" "int height" "int width" "int perc"
 112 .Ft "void"
 113 .Fn use_helpfile "char *hfile"
 114 .Ft "void"
 115 .Fn use_helpline "char *hline"
 116 .Ft "char *"
 117 .Fn get_helpline "void"
 118 .Ft "void"
 119 .Fn dialog_clear_norefresh "void"
 120 .Ft "void"
 121 .Fn dialog_clear "void"
 122 .Ft "void"
 123 .Fn dialog_update "void"
 124 .Ft "void"
 125 .Fn init_dialog "void"
 126 .Ft "void"
 127 .Fn end_dialog "void"
 128 .Ft "int"
 129 .Fn dialog_ftree "unsigned char *filename" "unsigned char FS" "unsigned char *title" "unsigned char *prompt" "int height" "int width" "int menu_height" "unsigned char **result"
 130 .Ft "int"
 131 .Fo dialog_tree
 132 .Fa "unsigned char **names"
 133 .Fa "int size"
 134 .Fa "unsigned char FS"
 135 .Fa "unsigned char *title"
 136 .Fa "unsigned char *prompt"
 137 .Fa "int height"
 138 .Fa "int width"
 139 .Fa "int menu_height"
 140 .Fa "unsigned char **result"
 141 .Fc
 142 .Sh DESCRIPTION
 143 The dialog library attempts to provide a fairly simplistic set of
 144 fixed-presentation menus, input boxes, gauges, file requestors and
 145 other general purpose GUI (a bit of a stretch, since it uses
 146 ncurses) objects.  Since the library also had its roots in a
 147 shell-script writer's utility (see the
 148 .Xr dialog 1
 149 command), the
 150 early API was somewhat primitively based on strings being passed in or
 151 out and parsed.  This API was later extended to take either the
 152 original arguments or arrays of
 153 .Va dialogMenuItem
 154 structures,
 155 giving the user much more control over the internal behavior of each
 156 control.  The
 157 .Va dialogMenuItem
 158 structure internals are public:
 159 .Bd -literal -offset indent
 160 typedef struct _dmenu_item {
 161    char *prompt;
 162    char *title;
 163    int (*checked)(struct _dmenu_item *self);
 164    int (*fire)(struct _dmenu_item *self);
 165    int (*selected)(struct _dmenu_item *self, int is_selected);
 166    void *data;
 167    char lbra, mark, rbra;
 168    long aux;
 169 } dialogMenuItem;
 170 .Ed
 171 .Pp
 172 The
 173 .Dv prompt
 174 and
 175 .Dv title
 176 strings are pretty much self-explanatory,
 177 and the
 178 .Va checked
 179 and
 180 .Va fire
 181 function pointers provide optional
 182 display and action hooks (the
 183 .Dv data
 184 variable being available for
 185 the convenience of those hooks) when more tightly coupled feedback between
 186 a menu object and user code is required.  The
 187 .Va selected
 188 hook also
 189 allows you to verify whether or not a given item is selected (the cursor is
 190 over it) for implementing pretty much any possible context-sensitive
 191 behavior. A number of clever tricks for simulating various kinds of item
 192 types can also be done by adjusting the values of
 193 .Va lbra
 194 (default: '['),
 195 .Va mark
 196 (default: '*' for radio menus, 'X' for check menus)
 197 and
 198 .Va rbra
 199 (default: ']') and declaring a reasonable
 200 .Va checked
 201 hook,
 202 which should return TRUE for the
 203 .Dq marked
 204 state and FALSE for
 205 .Dq unmarked .
 206 The
 207 .Va aux
 208 field is not used internally, and is available for miscellaneous usage.
 209 If an item has a
 210 .Va fire
 211 hook associated with it, it will also be called
 212 whenever the item is "toggled" in some way and should return one of the
 213 following codes:
 214 .Bd -literal -offset 4n
 215 #define DITEM_SUCCESS           0    /* Successful completion */
 216 #define DITEM_FAILURE           1    /* Failed to "fire" */
 217 .Ed
 218 .Pp
 219 The following flags are in the upper 16 bits of return status:
 220 .Bd -literal -offset 4n
 221 #define DITEM_LEAVE_MENU        (1 << 16)
 222 #define DITEM_REDRAW            (1 << 17)
 223 #define DITEM_RECREATE          (1 << 18)
 224 #define DITEM_RESTORE           (1 << 19)
 225 #define DITEM_CONTINUE          (1 << 20)
 226 .Ed
 227 .Pp
 228 Two special globals also exist for putting a dialog at any arbitrary
 229 X,Y location (the early designers rather short-sightedly made no provisions
 230 for this).  If set to zero, the default centering behavior will be in
 231 effect.
 232 .Pp
 233 Below is a short description of the various functions:
 234 .Pp
 235 .Fn draw_shadow
 236 draws a shadow in curses window
 237 .Va win
 238 using the dimensions of
 239 .Va x , y , width
 240 and
 241 .Va height .
 242 .Pp
 243 .Fn draw_box
 244 draws a bordered box using the dimensions of
 245 .Va x , y , width
 246 and
 247 .Va height .
 248 The attributes from
 249 .Va box
 250 and
 251 .Va border
 252 are used, if specified, while painting the box and border regions of the
 253 object.
 254 .Pp
 255 .Fn line_edit
 256 invoke a simple line editor with an edit box of dimensions
 257 .Va box_x , box_y
 258 and
 259 .Va box_width .
 260 The field length is constrained by
 261 .Va flen ,
 262 starting at the
 263 .Va first
 264 character specified and
 265 optionally displayed with character attributes
 266 .Va attr .
 267 The string being edited is stored in
 268 .Va result .
 269 Returns 0 on success, 1 on Cancel, and -1 on failure or ESC.
 270 .Pp
 271 .Fn strheight
 272 returns the height of string in
 273 .Va p ,
 274 counting newlines.
 275 .Pp
 276 .Fn strwidth
 277 returns the width of string in
 278 .Va p ,
 279 counting newlines.
 280 .Pp
 281 .Fn dialog_create_rc
 282 dump dialog library settings into
 283 .Pa filename
 284 for later retrieval as defaults.  Returns 0 on success, -1 on failure.
 285 .Pp
 286 .Fn dialog_yesno
 287 display a text box using
 288 .Va title
 289 and
 290 .Va prompt
 291 strings of dimensions
 292 .Va height
 293 and
 294 .Va width .
 295 Also paint a pair of
 296 .Em Yes
 297 and
 298 .Em \&No
 299 buttons at the bottom.
 300 The default selection is
 301 .Em Yes .
 302 If the
 303 .Em Yes
 304 button is chosen, return FALSE.  If
 305 .Em \&No ,
 306 return TRUE.
 307 .Pp
 308 .Fn dialog_noyes
 309 is the same as
 310 .Fn dialog_yesno ,
 311 except the default selection is
 312 .Em \&No .
 313 .Pp
 314 .Fn dialog_prgbox
 315 display a text box of dimensions
 316 .Va height
 317 and
 318 .Va width
 319 containing the output of command
 320 .Va line .
 321 If
 322 .Va use_shell
 323 is TRUE,
 324 .Va line
 325 is passed as an argument to
 326 .Xr sh 1 ,
 327 otherwise it is simply passed to
 328 .Xr exec 3 .
 329 If
 330 .Va pause
 331 is TRUE, a final confirmation requestor will be put up when execution
 332 terminates.  Returns 0 on success, -1 on failure.
 333 .Pp
 334 .Fn dialog_textbox
 335 display a text box containing the contents of
 336 .Va file
 337 with dimensions of
 338 .Va height
 339 and
 340 .Va width .
 341 .Pp
 342 .Fn dialog_menu
 343 display a menu of dimensions
 344 .Va height
 345 and
 346 .Va width
 347 with an optional internal menu height of
 348 .Va menu_height .
 349 The
 350 .Va cnt
 351 and
 352 .Va it
 353 arguments are of particular importance since they,
 354 together, determine which of the 2 available APIs to use.  To use the
 355 older and traditional interface,
 356 .Va cnt
 357 should be a positive
 358 integer representing the number of string pointer pairs to find in
 359 .Va it
 360 (which should be of type
 361 .Ft char "**" ) ,
 362 the strings are
 363 expected to be in prompt and title order for each item and the
 364 .Va result
 365 parameter is expected to point to an array where the
 366 prompt string of the item selected will be copied.  To use the newer
 367 interface,
 368 .Va cnt
 369 should be a
 370 .Va negative
 371 integer representing the number of
 372 .Va dialogMenuItem
 373 structures pointed to by
 374 .Va it
 375 (which should be of type
 376 .Vt dialogMenuItem "*" ) ,
 377 one structure per item.  In the new interface, the
 378 .Va result
 379 variable is used as a simple boolean (not a pointer) and should be NULL if
 380 .Va it
 381 only points to menu items and the default OK and Cancel buttons are desired.  If
 382 .Va result
 383 is non-NULL, then
 384 .Va it
 385 is actually expected to point 2 locations
 386 .Va past
 387 the start of the menu item list.
 388 .Va it
 389 is then expected to
 390 point to an item representing the Cancel button, from which the
 391 .Va prompt
 392 and
 393 .Va fire
 394 actions are used to override the default behavior, and
 395 .Va it
 396 to the same for the OK button.
 397 .Pp
 398 Using either API behavior, the
 399 .Va ch
 400 and
 401 .Va sc
 402 values may be passed in to preserve current
 403 item selection and scroll position values across calls.
 404 .Pp
 405 .Fn dialog_checklist
 406 display a menu of dimensions
 407 .Va height
 408 and
 409 .Va width
 410 with an
 411 optional internal menu height of
 412 .Va list_height .
 413 The
 414 .Va cnt
 415 and
 416 .Va it
 417 arguments are of particular importance since they,
 418 together, determine which of the 2 available APIs to use.  To use the
 419 older and traditional interface,
 420 .Va cnt
 421 should be a positive
 422 integer representing the number of string pointer tuples to find in
 423 .Va it
 424 (which should be of type
 425 .Ft "char **" ) ,
 426 the strings are
 427 expected to be in prompt, title and state ("on" or "off") order for
 428 each item and the
 429 .Va result
 430 parameter is expected to point to an
 431 array where the prompt string of the item(s) selected will be
 432 copied.  To use the newer interface,
 433 .Va cnt
 434 should be a
 435 .Em negative
 436 integer representing the number of
 437 .Ft dialogMenuItem
 438 structures pointed to by
 439 .Va it
 440 (which should be of type
 441 .Ft "dialogMenuItem *" ) ,
 442 one structure per item. In the new interface,
 443 the
 444 .Va result
 445 variable is used as a simple boolean (not a pointer)
 446 and should be NULL if
 447 .Va it
 448 only points to menu items and the default OK and Cancel
 449 buttons are desired.  If
 450 .Va result
 451 is non-NULL, then
 452 .Va it
 453 is actually expected to
 454 point 2 locations
 455 .Va past
 456 the start of the menu item list.
 457 .Va it
 458 is then expected to point to an item representing the Cancel
 459 button, from which the
 460 .Va prompt
 461 and
 462 .Va fire
 463 actions are used to override the default behavior, and
 464 .Va it
 465 to the same for the OK button.
 466 .Pp
 467 In the standard API model, the menu supports the selection of multiple items,
 468 each of which is marked with an `X' character to denote selection.  When
 469 the OK button is selected, the prompt values for all items selected are
 470 concatenated into the
 471 .Va result
 472 string.
 473 .Pp
 474 In the new API model, it is not actually necessary to preserve
 475 "checklist" semantics at all since practically everything about how
 476 each item is displayed or marked as "selected" is fully configurable.
 477 You could have a single checklist menu that actually contained a group
 478 of items with "radio" behavior, "checklist" behavior and standard menu
 479 item behavior.  The only reason to call
 480 .Fn dialog_checklist
 481 over
 482 .Fn dialog_radiolist
 483 in the new API model is to inherit the base
 484 behavior, you're no longer constrained by it.
 485 .Pp
 486 Returns 0 on success, 1 on Cancel, and -1 on failure or ESC.
 487 .Pp
 488 .Fn dialog_radiolist
 489 display a menu of dimensions
 490 .Va height
 491 and
 492 .Va width
 493 with an
 494 optional internal menu height of
 495 .Va list_height .
 496 The
 497 .Va cnt
 498 and
 499 .Va it
 500 arguments are of particular importance since they,
 501 together, determine which of the 2 available APIs to use.  To use the
 502 older and traditional interface,
 503 .Va cnt
 504 should be a positive
 505 integer representing the number of string pointer tuples to find in
 506 .Va it
 507 (which should be of type
 508 .Ft "char **" ) ,
 509 the strings are
 510 expected to be in prompt, title and state ("on" or "off") order for
 511 each item and the
 512 .Va result
 513 parameter is expected to point to an
 514 array where the prompt string of the item(s) selected will be
 515 copied.  To use the newer interface,
 516 .Va cnt
 517 should be a
 518 .Dv negative
 519 integer representing the number of
 520 .Ft dialogMenuItem
 521 structures pointed to by
 522 .Va it
 523 (which should be of type
 524 .Ft "dialogMenuItem *" ,
 525 one structure per item. In the new interface,
 526 the
 527 .Va result
 528 variable is used as a simple boolean (not a pointer)
 529 and should be NULL if
 530 .Va it
 531 only points to menu items and the default OK and Cancel
 532 buttons are desired.  If
 533 .Va result
 534 is non-NULL, then
 535 .Va it
 536 is actually expected to point 2 locations
 537 .Va past
 538 the start of the menu item list.
 539 .Va it
 540 is then expected to point to an item representing the Cancel
 541 button, from which the
 542 .Va prompt
 543 and
 544 .Va fire
 545 actions are used to override the default behavior, and
 546 .Va it
 547 does the same for the traditional OK button.
 548 .Pp
 549 In the standard API model, the menu supports the selection of only one
 550 of multiple items, the currently active item marked with an `*'
 551 character to denote selection.  When the OK button is selected, the
 552 prompt value for this item is copied into the
 553 .Va result
 554 string.
 555 .Pp
 556 In the new API model, it is not actually necessary to preserve
 557 "radio button" semantics at all since practically everything about how
 558 each item is displayed or marked as "selected" is fully configurable.
 559 You could have a single radio menu that actually contained a group
 560 of items with "checklist" behavior, "radio" behavior and standard menu
 561 item behavior.  The only reason to call
 562 .Fn dialog_radiolist
 563 over
 564 .Fn dialog_checklistlist
 565 in the new API model is to inherit the base
 566 behavior.
 567 .Pp
 568 Returns 0 on success, 1 on Cancel and -1 on failure or ESC.
 569 .Pp
 570 .Fn dialog_inputbox
 571 displays a single-line text input field in a box displaying
 572 .Va title
 573 and
 574 .Va prompt
 575 of dimensions
 576 .Va height
 577 and
 578 .Va width .
 579 The field entered is stored in
 580 .Va result .
 581 .Pp
 582 Returns 0 on success, -1 on failure or ESC.
 583 .Pp
 584 .Fn dialog_fselect
 585 brings up a file selector dialog starting at
 586 .Va dir
 587 and showing only those file names
 588 matching
 589 .Va fmask .
 590 .Pp
 591 Returns filename selected or NULL.
 592 .Pp
 593 .Fn dialog_dselect
 594 brings up a directory selector dialog starting at
 595 .Va dir
 596 and showing only those directory names
 597 matching
 598 .Va fmask .
 599 .Pp
 600 Returns directory name selected or NULL.
 601 .Pp
 602 .Fn dialog_notify
 603 brings up a generic "hey, you!" notifier dialog containing
 604 .Va msg .
 605 .Pp
 606 .Fn dialog_mesgbox
 607 like a notifier dialog, but with more control over
 608 .Va title ,
 609 .Va prompt ,
 610 .Va width
 611 and
 612 .Va height .
 613 This object will also wait for user confirmation, unlike
 614 .Fn dialog_notify .
 615 .Pp
 616 Returns 0 on success, -1 on failure.
 617 .Pp
 618 .Fn dialog_gauge
 619 displays a horizontal bar-graph style gauge.  A value of
 620 .Em 100
 621 for
 622 .Em perc
 623 constitutes a full gauge, a value of
 624 .Em 0
 625 an empty one.
 626 .Pp
 627 .Fn use_helpfile
 628 for any menu supporting context sensitive help, invoke the text box
 629 object on this file whenever the
 630 .Em F1
 631 key is pressed.
 632 .Pp
 633 .Fn use_helpline
 634 displays this line of helpful text below any menu being displayed.
 635 .Pp
 636 .Fn get_helpline
 637 get the current value of the helpful text line.
 638 .Pp
 639 .Fn dialog_clear_norefresh
 640 clear the screen back to the dialog background color, but don't refresh the
 641 contents just yet.
 642 .Pp
 643 .Fn dialog_clear
 644 clear the screen back to the dialog background color immediately.
 645 .Pp
 646 .Fn dialog_update
 647 do any pending screen refreshes now.
 648 .Pp
 649 .Fn init_dialog
 650 initialize the dialog library (call this routine before any other dialog
 651 API calls).
 652 .Pp
 653 .Fn end_dialog
 654 shut down the dialog library (call this if you need to get back to sanity).
 655 .Pp
 656 .Fn dialog_ftree
 657 shows a tree described by the data from the file
 658 .Pa filename .
 659 The data in the file should look like
 660 .Xr find 1
 661 output.
 662 For the
 663 .Xr find 1
 664 output, the field separator
 665 .Va FS
 666 will be
 667 .Dq \&/ .
 668 If
 669 .Va height
 670 and
 671 .Va width
 672 are positive numbers, they set the absolute
 673 size of the whole
 674 .Fn dialog_ftree
 675 box. If
 676 .Va height
 677 and
 678 .Va width
 679 are negative numbers, the size of the
 680 .Fn dialog_ftree
 681 box will be calculated automatically.
 682 .Va menu_height
 683 sets the height of the tree subwindow inside the
 684 .Fn dialog_ftree
 685 box and must be set.
 686 .Va title
 687 is shown centered on the upper border of the
 688 .Fn dialog_ftree
 689 box.
 690 .Va prompt
 691 is shown inside the
 692 .Fn dialog_ftree
 693 box above the tree subwindow and can contain
 694 .Ql \e\&n
 695 to split lines.  One can navigate in
 696 the tree by pressing UP/DOWN or
 697 .Sm off
 698 .So \&+ Sc \&/ So \&- Sc ,
 699 .Sm on
 700 PG_UP/PG_DOWN or
 701 .Sm off
 702 .So b Sc \&/SPACE
 703 .Sm on
 704 and
 705 HOME/END or
 706 .Sm off
 707 .So g Sc \&/ So G Sc .
 708 .Sm on
 709 A leaf of the
 710 tree is selected by pressing TAB or LEFT/RIGHT the OK
 711 button and pressing ENTER. filename may contain data like
 712 .Xr find 1
 713 output, as well as like the output of
 714 .Xr find 1
 715 with
 716 .Fl d
 717 option. Some of the transient paths to the leaves of the tree may
 718 be absent. Such data is corrected when fed from filename.
 719 .Pp
 720 The function returns 0 and a pointer to the selected leaf (to the path to
 721 the leaf from the root of the tree) into result, if the OK button was
 722 selected. The memory allocated for the building of the tree is freed on
 723 exiting
 724 .Fn dialog_ftree .
 725 The memory for the result line should be freed
 726 later manually, if necessary. If the Cancel button was selected, the
 727 function returns 1. In case of exiting
 728 .Fn dialog_ftree
 729 on ESC, the function returns -1.
 730 .Pp
 731 .Fn dialog_tree
 732 function returns the same results as
 733 .Fn dialog_ftree .
 734 If 0 is returned, result will contain a pointer from the array
 735 .Va names .
 736 .\" \fBdialog_tree\fR displays the tree very much like \fBdialog_ftree\fR does,
 737 .\" with some exceptions. The source data for the building of the tree is an
 738 .\" array \fBnames\fR of paths to the leaves (should be similar to \fBfind(1)\fR
 739 .\" output) of the size \fBsize\fR. However, there is no correction of data like
 740 .\" in \fBdialog_ftree\fR. Thus, to display a correct tree, the array must
 741 .\" already contain correct data. Besides, in each session every unique use of
 742 .\" \fBdialog_tree\fR is kept in memory, and later, when calling
 743 .\" \fBdialog_tree\fR with the same \fBnames\fR, \fBsize\fR, \fBFS\fR,
 744 .\" \fBheight\fR, \fBwidth\fR and \fBmenu_height\fR the position of the cursor
 745 .\" in the tree subwindow is restored.
 746 .Sh SEE ALSO
 747 .Xr dialog 1 ,
 748 .Xr ncurses 3
 749 .Sh AUTHORS
 750 The primary author would appear to be
 751 .An Savio Lam Aq lam836@cs.cuhk.hk
 752 with contributions over the years by
 753 .An Stuart Herbert Aq S.Herbert@sheffield.ac.uk ,
 754 .An Marc van Kempen Aq wmbfmk@urc.tue.nl ,
 755 .An Andrey Chernov Aq ache@FreeBSD.org ,
 756 .An Jordan Hubbard Aq jkh@FreeBSD.org
 757 and
 758 .An Anatoly A. Orehovsky Aq tolik@mpeks.tomsk.su .
 759 .Sh HISTORY
 760 These functions appeared in
 761 .Fx 2.0
 762 as the
 763 .Xr dialog 1
 764 command and were soon split into a separate library
 765 and command by
 766 .An Andrey Chernov .
 767 .An Marc van Kempen implemented most of the
 768 extra controls and objects,
 769 .An Jordan Hubbard
 770 added the dialogMenuItem renovations and this man page and
 771 .An Anatoly A. Orehovsky
 772 implemented
 773 .Fn dialog_ftree
 774 and
 775 .Fn dialog_tree .
 776 .Sh BUGS
 777 Sure!