1 .\" Copyright (c) 2013-2016 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
32 .Nd dialog progress view library
39 .Fa "struct dpv_config *config, struct dpv_file_node *file_list"
48 library provides an interface for creating complex
50 widgets for displaying progress on various actions.
53 library can display progress with one of
58 .Pq x11/xdialog from the ports tree .
63 argument contains the following properties for configuring global display
65 .Bd -literal -offset indent
67 uint8_t keep_tite; /* Cleaner exit for scripts */
68 enum dpv_display display_type; /* Def. DPV_DISPLAY_LIBDIALOG */
69 enum dpv_output output_type; /* Default DPV_OUTPUT_NONE */
70 int debug; /* Enable debug on stderr */
71 int display_limit; /* Files/page. Default -1 */
72 int label_size; /* Label size. Default 28 */
73 int pbar_size; /* Mini-progress size */
74 int dialog_updates_per_second; /* Default 16 */
75 int status_updates_per_second; /* Default 2 */
76 uint16_t options; /* Default 0 (none) */
77 char *title; /* Widget title */
78 char *backtitle; /* Widget backtitle */
79 char *aprompt; /* Append. Default NULL */
80 char *pprompt; /* Prefix. Default NULL */
81 char *msg_done; /* Default `Done' */
82 char *msg_fail; /* Default `Fail' */
83 char *msg_pending; /* Default `Pending' */
84 char *output; /* Output format string */
85 const char *status_solo; /* dialog(3) solo-status format.
86 * Default DPV_STATUS_SOLO */
87 const char *status_many; /* dialog(3) many-status format.
88 * Default DPV_STATUS_MANY */
91 * Function pointer; action to perform data transfer
93 int (*action)(struct dpv_file_node *file, int out);
97 DPV_DISPLAY_LIBDIALOG = 0, /* Use dialog(3) (default) */
98 DPV_DISPLAY_STDOUT, /* Use stdout */
99 DPV_DISPLAY_DIALOG, /* Use spawned dialog(1) */
100 DPV_DISPLAY_XDIALOG, /* Use spawned Xdialog(1) */
104 DPV_OUTPUT_NONE = 0, /* No output (default) */
105 DPV_OUTPUT_FILE, /* Read `output' member as file path */
106 DPV_OUTPUT_SHELL, /* Read `output' member as shell cmd */
115 argument is a mask of bit fields indicating various processing options.
116 Possible flags are as follows:
117 .Bl -tag -width DPV_NO_OVERRUN
124 argument is not called but instead simulated-data is used to drive progress.
136 .Dv DPV_STATUS_DEFAULT
140 In wide mode, the length of the
147 argument will bump the width of the gauge widget.
148 Prompts wider than the maximum width will wrap
152 see BUGS section below
155 Disables the display of labels associated with each transfer
164 Force the use of color even if the
166 does not support color
169 environment variable is ignored
171 .It Dv DPV_NO_OVERRUN
172 When enabled, callbacks for the current
176 returns 100 or greater
178 alleviates the need to change the
182 but may also cause file truncation if the stream exceeds expected length
192 described as follows in
194 .Bd -literal -offset indent
195 struct dpv_file_node {
196 enum dpv_status status; /* status of read operation */
197 char *msg; /* display instead of "Done/Fail" */
198 char *name; /* name of file to read */
199 char *path; /* path to file */
200 long long length; /* expected size */
201 long long read; /* number units read (e.g., bytes) */
202 struct dpv_file_node *next;/* pointer to next (end with NULL) */
206 For each of the items in the
211 callback member of the
217 function should perform a
219 action on the file and return.
222 represents the current progress percentage
224 for the current file.
228 callback provides two variables for each call.
230 provides a reference to the current
234 provides a file descriptor where the data should go.
241 argument was set to DPV_OUTPUT_NONE
242 .Pq default ; when invoking Fn dpv ,
247 will be zero and should be ignored.
250 was set to DPV_OUTPUT_FILE,
252 will be an open file descriptor to a file.
255 was set to DPV_OUTPUT_SHELL,
257 will be an open file descriptor to a pipe for a spawned shell program.
260 is greater than zero, you should write any data you have read back to
267 callback or asynchronously from a signal handler, two globals are provided via
269 .Bd -literal -offset indent
270 extern int dpv_interrupt; /* Set to TRUE in interrupt handler */
271 extern int dpv_abort; /* Set to true in callback to abort */
274 These globals are not automatically reset and must be manually maintained.
275 Don't forget to reset these globals before subsequent invocations of
277 when making multiple calls from the same program.
284 argument can be used to control callbacks for the current file.
287 member can be set to any of the following from
289 .Bd -literal -offset indent
291 DPV_STATUS_RUNNING = 0, /* Running (default) */
292 DPV_STATUS_DONE, /* Completed */
293 DPV_STATUS_FAILED, /* Oops, something went wrong */
299 is zero, DPV_STATUS_RUNING, which keeps the callbacks coming for the current
303 to anything other than DPV_STATUS_RUNNING will cause
305 to loop to the next file, effecting the next callback, if any.
309 callback is responsible for calculating percentages and
315 can display throughput statistics.
316 Percentages are reported through the
321 Throughput statistics are calculated from the following global
325 .Bd -literal -offset indent
326 extern int dpv_overall_read;
329 This should be set to the number of bytes that have been read for all files.
330 Throughput information is displayed in the status line
331 .Pq only available when using Xr dialog 3
332 at the bottom of the screen.
333 See DPV_DISPLAY_LIBDIALOG above.
337 does not have to represent bytes.
338 For example, you can change the
340 to display something other than
345 .Pq e.g., counting lines .
349 is processing the current file, the
356 argument are used for calculating the display of mini progress bars
364 member of the current
367 .Pq indicating an unknown file length ,
369 .Xr humanize_number 3
372 member is used instead of a traditional progress bar.
373 Otherwise a progress bar is calculated as percentage read to file length.
375 callback must maintain these member values for mini-progress bars.
381 on private global variables initialized by
384 The following environment variables are referenced by
386 .Bl -tag -width ".Ev USE_COLOR"
388 Override command string used to launch
390 .Pq requires Dv DPV_DISPLAY_DIALOG
393 .Pq requires Dv DPV_DISPLAY_XDIALOG ;
396 .Pq for Dv DPV_DISPLAY_DIALOG
399 .Pq for Dv DPV_DISPLAY_XDIALOG .
401 If set and non-NULL, path to
407 is either not set or NULL, used as a prefix to
409 .Pq i.e., Ql $HOME/.dialogrc .
411 If set and NULL, disables the use of color when using
413 .Pq does not apply to Xr Xdialog 1 .
414 .It Ev msg_done Ev msg_fail Ev msg_pending
415 Internationalization strings for overriding the default English strings
421 To prevent their usage, explicitly set the
429 argument to default macros
430 .Pq DPV_DONE_DEFAULT, DPV_FAIL_DEFAULT, and DPV_PENDING_DEFAULT
434 .Bl -tag -width ".Pa $HOME/.dialogrc" -compact
435 .It Pa $HOME/.dialogrc
444 library first appeared in
447 .An Devin Teske Aq dteske@FreeBSD.org
451 .Ql Fl -title Ar title
456 .Va struct dpv_config
459 .Ql Fl -backtitle Ar backtitle
464 .Va struct dpv_config
466 displays the backtitle in place of the title and vice-versa.
469 does not wrap long prompt texts received after initial launch.
470 This is a known issue with the
474 Embed escaped newlines within prompt text(s) to force line breaks.
477 does not display the first character after a series of escaped escape-sequences
478 (e.g., ``\\\\n'' produces ``\\'' instead of ``\\n'').
479 This is a known issue with
486 If your application ignores
488 when set and NULL before calling
490 with color escape sequences anyway,
494 may not render properly.
495 Workaround is to detect when
497 is set and NULL and either not use color escape sequences at that time or use
501 forcing interpretation of color sequences.
504 which renders the color escape sequences as plain text.
507 embedded "\\Z" sequences
511 for additional information.