1 .\" Copyright (c) 2013-2018 Devin Teske
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
30 .Nd dialog progress view library
37 .Fa "struct dpv_config *config"
38 .Fa "struct dpv_file_node *file_list"
47 library provides an interface for creating complex
49 widgets for displaying progress on various actions.
52 library can display progress with one of
56 .Xr Xdialog 1 Pq Pa ports/x11/xdialog .
61 argument properties for configuring global display features:
62 .Bd -literal -offset indent
64 uint8_t keep_tite; /* Cleaner exit for scripts */
65 enum dpv_display display_type; /* Def. DPV_DISPLAY_LIBDIALOG */
66 enum dpv_output output_type; /* Default DPV_OUTPUT_NONE */
67 int debug; /* Enable debug on stderr */
68 int display_limit; /* Files/page. Default -1 */
69 int label_size; /* Label size. Default 28 */
70 int pbar_size; /* Mini-progress size */
71 int dialog_updates_per_second; /* Default 16 */
72 int status_updates_per_second; /* Default 2 */
73 uint16_t options; /* Default 0 (none) */
74 char *title; /* Widget title */
75 char *backtitle; /* Widget backtitle */
76 char *aprompt; /* Append. Default NULL */
77 char *pprompt; /* Prefix. Default NULL */
78 char *msg_done; /* Default `Done' */
79 char *msg_fail; /* Default `Fail' */
80 char *msg_pending; /* Default `Pending' */
81 char *output; /* Output format string */
82 const char *status_solo; /* dialog(3) solo-status format.
83 * Default DPV_STATUS_SOLO */
84 const char *status_many; /* dialog(3) many-status format.
85 * Default DPV_STATUS_MANY */
88 * Function pointer; action to perform data transfer
90 int (*action)(struct dpv_file_node *file, int out);
94 DPV_DISPLAY_LIBDIALOG = 0, /* Use dialog(3) (default) */
95 DPV_DISPLAY_STDOUT, /* Use stdout */
96 DPV_DISPLAY_DIALOG, /* Use spawned dialog(1) */
97 DPV_DISPLAY_XDIALOG, /* Use spawned Xdialog(1) */
101 DPV_OUTPUT_NONE = 0, /* No output (default) */
102 DPV_OUTPUT_FILE, /* Read `output' member as file path */
103 DPV_OUTPUT_SHELL, /* Read `output' member as shell cmd */
112 argument is a mask of bit fields indicating various processing options.
114 .Bl -tag -width DPV_NO_OVERRUN
122 argument is not called but instead simulated-data is used to drive progress.
136 .Dv DPV_STATUS_DEFAULT
148 argument will bump the width of the gauge widget.
149 Prompts wider than the maximum width will wrap
152 .Xr Xdialog 1 Pq Pa ports/x11/xdialog ;
153 see BUGS section below
156 Disables the display of labels associated with each transfer
165 Force the use of color even if the
167 does not support color
170 environment variable is ignored
172 .It Dv DPV_NO_OVERRUN
174 callbacks for the current
178 returns 100 or greater
180 alleviates the need to change the
184 but may also cause file truncation if the stream exceeds expected length
196 .Bd -literal -offset indent
197 struct dpv_file_node {
198 enum dpv_status status; /* status of read operation */
199 char *msg; /* display instead of "Done/Fail" */
200 char *name; /* name of file to read */
201 char *path; /* path to file */
202 long long length; /* expected size */
203 long long read; /* number units read (e.g., bytes) */
204 struct dpv_file_node *next;/* pointer to next (end with NULL) */
208 For each of the items in the
214 callback member of the
222 action on the file and return.
225 represents the current progress percentage
227 for the current file.
231 callback provides two variables for each call.
233 provides a reference to the current
237 provides a file descriptor where the data goes.
244 argument was set to DPV_OUTPUT_NONE
245 .Pq default ; when invoking Fn dpv ,
250 will be zero and can be ignored.
253 was set to DPV_OUTPUT_FILE,
255 will be an open file descriptor to a file.
258 was set to DPV_OUTPUT_SHELL,
260 will be an open file descriptor to a pipe for a spawned shell program.
263 is greater than zero,
264 write data that has been read back to
271 callback or asynchronously from a signal handler,
272 two globals are provided via
274 .Bd -literal -offset indent
275 extern int dpv_interrupt; /* Set to TRUE in interrupt handler */
276 extern int dpv_abort; /* Set to true in callback to abort */
279 These globals are not automatically reset and must be manually maintained.
280 Do not forget to reset these globals before subsequent invocations of
282 when making multiple calls from the same program.
290 argument can be used to control callbacks for the current file.
293 member can be set to any of the below from
295 .Bd -literal -offset indent
297 DPV_STATUS_RUNNING = 0, /* Running (default) */
298 DPV_STATUS_DONE, /* Completed */
299 DPV_STATUS_FAILED, /* Oops, something went wrong */
307 which keeps the callbacks coming for the current
311 to anything other than DPV_STATUS_RUNNING will cause
313 to loop to the next file,
314 effecting the next callback,
319 callback is responsible for calculating percentages and
325 can display throughput statistics.
326 Percentages are reported through the
331 Throughput statistics are calculated from the below global
335 .Bd -literal -offset indent
336 extern int dpv_overall_read;
339 Set this to the number of bytes that have been read for all files.
340 Throughput information is displayed in the status line
341 .Pq only available when using Xr dialog 3
342 at the bottom of the screen.
343 See DPV_DISPLAY_LIBDIALOG above.
347 does not have to represent bytes.
351 can be changed to display something other than
356 .Pq for example, counting lines .
360 is processing the current file,
368 argument are used for calculating the display of mini progress bars
377 member of the current
380 .Pq indicating an unknown file length ,
382 .Xr humanize_number 3
385 member is used instead of a traditional progress bar.
386 Otherwise a progress bar is calculated as percentage read to file length.
388 callback must maintain these member values for mini-progress bars.
394 on private global variables initialized by
397 The below environment variables are referenced by
399 .Bl -tag -width ".Ev USE_COLOR"
401 Override command string used to launch
403 .Pq requires Dv DPV_DISPLAY_DIALOG
405 .Xr Xdialog 1 Pq Pa ports/x11/xdialog
406 .Pq requires Dv DPV_DISPLAY_XDIALOG ;
409 .Pq for Dv DPV_DISPLAY_DIALOG
412 .Pq for Dv DPV_DISPLAY_XDIALOG .
421 is either not set or NULL,
424 .Pq that is, Ql $HOME/.dialogrc .
427 disables the use of color when using
430 .Xr Xdialog 1 Pq Pa ports/x11/xdialog .
431 .It Ev msg_done Ev msg_fail Ev msg_pending
432 Internationalization strings for overriding the default English strings
438 To prevent their usage,
447 argument to default macros
448 .Pq DPV_DONE_DEFAULT, DPV_FAIL_DEFAULT, and DPV_PENDING_DEFAULT
452 .Bl -tag -width ".Pa $HOME/.dialogrc" -compact
453 .It Pa $HOME/.dialogrc
457 .Xr Xdialog 1 Pq Pa ports/x11/xdialog ,
462 library first appeared in
465 .An Devin Teske Aq dteske@FreeBSD.org
467 .Xr Xdialog 1 Pq Pa ports/x11/xdialog ,
469 .Ql Fl -title Ar title
474 .Va struct dpv_config
477 .Ql Fl -backtitle Ar backtitle
482 .Va struct dpv_config
484 displays the backtitle in place of the title and vice-versa.
486 .Xr Xdialog 1 Pq Pa ports/x11/xdialog
487 does not wrap long prompt texts received after initial launch.
488 This is a known issue with the
491 .Xr Xdialog 1 Pq Pa ports/x11/xdialog .
492 Embed escaped newlines within prompt text to force line breaks.
495 does not display the first character after a series of escaped escape-sequences
496 (for example, ``\\\\n'' produces ``\\'' instead of ``\\n'').
497 This is a known issue with
502 .Xr Xdialog 1 Pq Pa ports/x11/xdialog .
504 If an application ignores
506 when set and NULL before calling
508 with color escape sequences anyway,
512 may not render properly.
513 Workaround is to detect when
515 is set and NULL and either not use color escape sequences at that time or use
519 forcing interpretation of color sequences.
521 .Xr Xdialog 1 Pq Pa ports/x11/xdialog ,
522 which renders the color escape sequences as plain text.
525 embedded "\\Z" sequences
529 for additional information.