1% notcurses_progbar(3)
2% nick black <nickblack@linux.com>
3% v2.0.11
4
5# NAME
6
7notcurses_progbar - high level widget for progress bars
8
9# SYNOPSIS
10
11**#include <notcurses/notcurses.h>**
12
13```c
14struct ncprogbar;
15
16#define NCPROGBAR_OPTION_RETROGRADE        0x0001u // proceed left/down
17
18typedef struct ncprogbar_options {
19  uint64_t maxchannels;
20  uint64_t minchannels;
21  uint64_t flags;
22} ncprogbar_options;
23```
24
25**struct ncprogbar* ncprogbar_create(struct ncplane* ***n***, const ncprogbar_options* ***opts***)**
26
27**struct ncplane* ncprogbar_plane(struct ncprogbar* ***n***)**
28
29**int ncprogbar_set_progress(struct ncprogbar* ***n***, double ***p***)**
30
31**double ncprogbar_progress(const struct ncprogbar* ***n***)**
32
33**void ncprogbar_destroy(struct ncprogbar* ***n***)**
34
35# DESCRIPTION
36
37These functions draw progress bars in any of four directions. The progress
38measure is a **double** between zero and one, inclusive, provided to
39**ncprogbar_set_progress**. This will be scaled to the size of the provided
40ncplane ***n***. The axis of progression is the longer element of the plane's
41geometry. Horizontal bars proceed to the right by default, and vertical bars
42proceed up. This can be changed with **NCPROGBAR_OPTION_RETROGRADE**.
43
44# NOTES
45
46**ncprogbar_create** takes ownership of ***n*** in all cases. On failure,
47***n*** will be destroyed immediately. It is otherwise destroyed by
48**ncprogbar_destroy**.
49
50# RETURN VALUES
51
52**ncprogbar_plane** returns the **ncplane** on which the progress bar is drawn.
53**ncprogbar_progress** returns the current progress, a value between zero and
54one, inclusive. They cannot fail.
55
56**ncprogbar_set_progress** returns -1 if ***p*** is less than zero or greater
57than one, or if there is an internal error redrawing the progress bar. It
58returns 0 otherwise.
59
60# BUGS
61
62Whether progression is to the left or right by default probably ought be an
63aspect of the current locale.
64
65# SEE ALSO
66
67**notcurses(3)**,
68**notcurses_plane(3)**,
69**notcurses_visual(3)**
70