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