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