1.\" Copyright (c) 2013-2014 Devin Teske 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd Oct 24, 2014 28.Dt DPV 3 29.Os 30.Sh NAME 31.Nm dpv 32.Nd dialog progress view library 33.Sh LIBRARY 34.Lb libdpv 35.Sh SYNOPSIS 36.In dpv.h 37.Ft int 38.Fo dpv 39.Fa "struct dpv_config *config, struct dpv_file_node *file_list" 40.Fc 41.Ft void 42.Fo dpv_free 43.Fa "void" 44.Fc 45.Sh DESCRIPTION 46The 47.Nm 48library provides an interface for creating complex 49.Dq gauge 50widgets for displaying progress on various actions. 51The 52.Nm 53library can display progress with one of 54.Xr dialog 3 , 55.Xr dialog 1 , 56or 57.Xr Xdialog 1 58.Pq x11/xdialog from the ports tree . 59.Pp 60The 61.Fn dpv 62.Fa config 63argument contains the following properties for configuring global display 64features: 65.Bd -literal -offset indent 66struct dpv_config { 67 enum dpv_display display_type; /* Def. DPV_DISPLAY_LIBDIALOG */ 68 enum dpv_output output_type; /* Default DPV_OUTPUT_NONE */ 69 int debug; /* Enable debug on stderr */ 70 int display_limit; /* Files/page. Default -1 */ 71 int label_size; /* Label size. Default 28 */ 72 int pbar_size; /* Mini-progress size */ 73 int dialog_updates_per_second; /* Default 16 */ 74 int status_updates_per_second; /* Default 2 */ 75 uint16_t options; /* Default 0 (none) */ 76 char *title; /* Widget title */ 77 char *backtitle; /* Widget backtitle */ 78 char *aprompt; /* Append. Default NULL */ 79 char *pprompt; /* Prefix. Default NULL */ 80 char *msg_done; /* Default `Done' */ 81 char *msg_fail; /* Default `Fail' */ 82 char *msg_pending; /* Default `Pending' */ 83 char *output; /* Output format string */ 84 const char *status_solo; /* dialog(3) solo-status format. 85 * Default DPV_STATUS_SOLO */ 86 const char *status_many; /* dialog(3) many-status format. 87 * Default DPV_STATUS_MANY */ 88 89 /* 90 * Function pointer; action to perform data transfer 91 */ 92 int (*action)(struct dpv_file_node *file, int out); 93}; 94 95enum dpv_display { 96 DPV_DISPLAY_LIBDIALOG = 0, /* Use dialog(3) (default) */ 97 DPV_DISPLAY_STDOUT, /* Use stdout */ 98 DPV_DISPLAY_DIALOG, /* Use spawned dialog(1) */ 99 DPV_DISPLAY_XDIALOG, /* Use spawned Xdialog(1) */ 100}; 101 102enum dpv_output { 103 DPV_OUTPUT_NONE = 0, /* No output (default) */ 104 DPV_OUTPUT_FILE, /* Read `output' member as file path */ 105 DPV_OUTPUT_SHELL, /* Read `output' member as shell cmd */ 106}; 107.Ed 108.Pp 109The 110.Va options 111member of the 112.Fn dpv 113.Fa config 114argument is a mask of bit fields indicating various processing options. 115Possible flags are as follows: 116.Bl -tag -width DPV_NO_OVERRUN 117.It Dv DPV_TEST_MODE 118Enable test mode. 119In test mode, the 120.Fn action 121callback of the 122.Fa config 123argument is not called but instead simulated-data is used to drive progress. 124Appends 125.Dq [TEST MODE] 126to the status line 127.Po 128to override, set the 129.Va status_format 130member of the 131.Fn dpv 132.Fa config 133argument; 134e.g., to 135.Dv DPV_STATUS_DEFAULT 136.Pc . 137.It Dv DPV_WIDE_MODE 138Enable wide mode. 139In wide mode, the length of the 140.Va aprompt 141and 142.Va pprompt 143members of the 144.Fn dpv 145.Fa config 146argument will bump the width of the gauge widget. 147Prompts wider than the maximum width will wrap 148.Po 149unless using 150.Xr Xdialog 1 ; 151see BUGS section below 152.Pc . 153.It Dv DPV_NO_LABELS 154Disables the display of labels associated with each transfer 155.Po 156.Va label_size 157member of 158.Fn dpv 159.Fa config 160argument is ignored 161.Pc . 162.It Dv DPV_USE_COLOR 163Force the use of color even if the 164.Va display_type 165does not support color 166.Po 167.Ev USE_COLOR 168environment variable is ignored 169.Pc . 170.It Dv DPV_NO_OVERRUN 171When enabled, callbacks for the current 172.Vt dpv_file_node 173are terminated when 174.Fn action 175returns 100 or greater 176.Po 177alleviates the need to change the 178.Va status 179of the current 180.Vt dpv_file_node 181but may also cause file truncation if the stream exceeds expected length 182.Pc . 183.El 184.Pp 185The 186.Fa file_list 187argument to 188.Fn dpv 189is a pointer to a 190.Dq linked-list , 191described as follows in 192.In dpv.h : 193.Bd -literal -offset indent 194struct dpv_file_node { 195 enum dpv_status status; /* status of read operation */ 196 char *msg; /* display instead of "Done/Fail" */ 197 char *name; /* name of file to read */ 198 char *path; /* path to file */ 199 long long length; /* expected size */ 200 long long read; /* number units read (e.g., bytes) */ 201 struct dpv_file_node *next;/* pointer to next (end with NULL) */ 202}; 203.Ed 204.Pp 205For each of the items in the 206.Fa file_list 207.Dq linked-list 208argument, the 209.Fn action 210callback member of the 211.Fn dpv 212.Fa config 213argument is called. 214The 215.Fn action 216function should perform a 217.Dq nominal 218action on the file and return. 219The return value of 220.Vt int 221represents the current progress percentage 222.Pq 0-100 223for the current file. 224.Pp 225The 226.Fn action 227callback provides two variables for each call. 228.Fa file 229provides a reference to the current 230.Vt dpv_file_node 231being processed. 232.Fa out 233provides a file descriptor where the data should go. 234.Pp 235If the 236.Va output 237member of the 238.Fn dpv 239.Fa config 240argument was set to DPV_OUTPUT_NONE 241.Pq default ; when invoking Fn dpv , 242the 243.Fa out 244file descriptor of 245.Fn action 246will be zero and should be ignored. 247If 248.Fa output 249was set to DPV_OUTPUT_FILE, 250.Fa out 251will be an open file descriptor to a file. 252If 253.Fa output 254was set to DPV_OUTPUT_SHELL, 255.Fa out 256will be an open file descriptor to a pipe for a spawned shell program. 257When 258.Fa out 259is greater than zero, you should write any data you have read back to 260.Fa out . 261.Pp 262To abort 263.Fn dpv , 264either from the 265.Fn action 266callback or asynchronously from a signal handler, two globals are provided via 267.In dpv.h : 268.Bd -literal -offset indent 269extern int dpv_interrupt; /* Set to TRUE in interrupt handler */ 270extern int dpv_abort; /* Set to true in callback to abort */ 271.Ed 272.Pp 273These globals are not automatically reset and must be manually maintained. 274Don't forget to reset these globals before subsequent invocations of 275.Fn dpv 276when making multiple calls from the same program. 277.Pp 278In addition, the 279.Va status 280member of the 281.Fn action 282.Fa file 283argument can be used to control callbacks for the current file. 284The 285.Va status 286member can be set to any of the following from 287.In dpv.h : 288.Bd -literal -offset indent 289enum dpv_status { 290 DPV_STATUS_RUNNING = 0, /* Running (default) */ 291 DPV_STATUS_DONE, /* Completed */ 292 DPV_STATUS_FAILED, /* Oops, something went wrong */ 293}; 294.Ed 295.Pp 296The default 297.Fa status 298is zero, DPV_STATUS_RUNING, which keeps the callbacks coming for the current 299.Fn file . 300Setting 301.Ql file->status 302to anything other than DPV_STATUS_RUNNING will cause 303.Fn dpv 304to loop to the next file, effecting the next callback, if any. 305.Pp 306The 307.Fn action 308callback is responsible for calculating percentages and 309.Pq recommended 310maintaining a 311.Nm 312global counter so 313.Fn dpv 314can display throughput statistics. 315Percentages are reported through the 316.Vt int 317return value of the 318.Fn action 319callback. 320Throughput statistics are calculated from the following global 321.Vt int 322in 323.In dpv.h : 324.Bd -literal -offset indent 325extern int dpv_overall_read; 326.Ed 327.Pp 328This should be set to the number of bytes that have been read for all files. 329Throughput information is displayed in the status line 330.Pq only available when using Xr dialog 3 331at the bottom of the screen. 332See DPV_DISPLAY_LIBDIALOG above. 333.Pp 334Note that 335.Va dpv_overall_read 336does not have to represent bytes. 337For example, you can change the 338.Va status_format 339to display something other than 340.Dq Li bytes 341and increment 342.Va dpv_overall_read 343accordingly 344.Pq e.g., counting lines . 345.Pp 346When 347.Fn dpv 348is processing the current file, the 349.Va length 350and 351.Va read 352members of the 353.Fn action 354.Fa file 355argument are used for calculating the display of mini progress bars 356.Po 357if enabled; see 358.Va pbar_size 359above 360.Pc . 361If the 362.Va length 363member of the current 364.Fa file 365is less than zero 366.Pq indicating an unknown file length , 367a 368.Xr humanize_number 3 369version of the 370.Va read 371member is used instead of a traditional progress bar. 372Otherwise a progress bar is calculated as percentage read to file length. 373.Fn action 374callback must maintain these member values for mini-progress bars. 375.Pp 376The 377.Fn dpv_free 378function performs 379.Xr free 3 380on private global variables initialized by 381.Fn dpv . 382.Sh ENVIRONMENT 383The following environment variables are referenced by 384.Nm : 385.Bl -tag -width ".Ev USE_COLOR" 386.It Ev DIALOG 387Override command string used to launch 388.Xr dialog 1 389.Pq requires Dv DPV_DISPLAY_DIALOG 390or 391.Xr Xdialog 1 392.Pq requires Dv DPV_DISPLAY_XDIALOG ; 393default is either 394.Ql dialog 395.Pq for Dv DPV_DISPLAY_DIALOG 396or 397.Ql Xdialog 398.Pq for Dv DPV_DISPLAY_XDIALOG . 399.It Ev DIALOGRC 400If set and non-NULL, path to 401.Ql .dialogrc 402file. 403.It Ev HOME 404If 405.Ql Ev $DIALOGRC 406is either not set or NULL, used as a prefix to 407.Ql .dialogrc 408.Pq i.e., Ql $HOME/.dialogrc . 409.It Ev USE_COLOR 410If set and NULL, disables the use of color when using 411.Xr dialog 1 412.Pq does not apply to Xr Xdialog 1 . 413.It Ev msg_done Ev msg_fail Ev msg_pending 414Internationalization strings for overriding the default English strings 415.Ql Done , 416.Ql Fail , 417and 418.Ql Pending 419respectively. 420To prevent their usage, explicitly set the 421.Va msg_done , 422.Va msg_fail , 423and 424.Va msg_pending 425members of 426.Fn dpv 427.Fa config 428argument to default macros 429.Pq DPV_DONE_DEFAULT, DPV_FAIL_DEFAULT, and DPV_PENDING_DEFAULT 430or desired values. 431.El 432.Sh FILES 433.Bl -tag -width ".Pa $HOME/.dialogrc" -compact 434.It Pa $HOME/.dialogrc 435.El 436.Sh SEE ALSO 437.Xr dialog 1 , 438.Xr Xdialog 1 , 439.Xr dialog 3 440.Sh HISTORY 441The 442.Nm 443library first appeared in 444.Fx 11.0 . 445.Sh AUTHORS 446.An Devin Teske Aq dteske@FreeBSD.org 447.Sh BUGS 448.Xr Xdialog 1 , 449when given both 450.Ql Fl -title Ar title 451.Po 452see above 453.Ql Va title 454member of 455.Va struct dpv_config 456.Pc 457and 458.Ql Fl -backtitle Ar backtitle 459.Po 460see above 461.Ql Va backtitle 462member of 463.Va struct dpv_config 464.Pc , 465displays the backtitle in place of the title and vice-versa. 466.Pp 467.Xr Xdialog 1 468does not wrap long prompt texts received after initial launch. 469This is a known issue with the 470.Ql --gauge 471widget in 472.Xr Xdialog 1 . 473Embed escaped newlines within prompt text(s) to force line breaks. 474.Pp 475.Xr dialog 1 476does not display the first character after a series of escaped escape-sequences 477(e.g., ``\\\\n'' produces ``\\'' instead of ``\\n''). 478This is a known issue with 479.Xr dialog 1 480and does not affect 481.Xr dialog 3 482or 483.Xr Xdialog 1 . 484.Pp 485If your application ignores 486.Ev USE_COLOR 487when set and NULL before calling 488.Xr dpv 3 489with color escape sequences anyway, 490.Xr dialog 3 491and 492.Xr dialog 1 493may not render properly. 494Workaround is to detect when 495.Ev USE_COLOR 496is set and NULL and either not use color escape sequences at that time or use 497.Xr unsetenv 3 498to unset 499.Ev USE_COLOR , 500forcing interpretation of color sequences. 501This does not effect 502.Xr Xdialog 1 , 503which renders the color escape sequences as plain text. 504See 505.Do 506embedded "\\Z" sequences 507.Dc 508in 509.Xr dialog 1 510for additional information. 511