mirror of
https://github.com/dankamongmen/notcurses
synced 2025-03-09 17:19:03 -04:00
initial API + documentation for ncprogbar #1202
This commit is contained in:
nick black
Nick Black
parent
be3bd474f6
commit
6bff720122
61
USAGE.md
61
USAGE.md
@ -9,7 +9,7 @@ and the project is committed to backwards compatibility.
|
||||
* [Planes](#planes) ([Plane Channels API](#plane-channels-api))
|
||||
* [Cells](#cells) ([Cell Channels API](#cell-channels-api))
|
||||
* [Reels](#reels) ([ncreel Examples](#ncreel-examples))
|
||||
* [Widgets](#widgets) ([Plots](#plots)) ([Readers](#readers))
|
||||
* [Widgets](#widgets) ([Plots](#plots)) ([Readers](#readers)) ([Progbars](#progbars))
|
||||
* [Channels](#channels)
|
||||
* [Visuals](#visuals) ([QR codes](#qrcodes)) ([Multimedia](#multimedia)) ([Pixels](#pixels))
|
||||
* [Stats](#stats)
|
||||
@ -2337,6 +2337,9 @@ xxxxxxxxxxxxxxxx╰─────────────╯xxxxxxxxxxxxxxxxxxx
|
||||
|
||||
### Readers
|
||||
|
||||
ncreaders provide freeform input in a (possibly multiline) region, supporting
|
||||
optional readline keybindings.
|
||||
|
||||
```c
|
||||
typedef struct ncreader_options {
|
||||
uint64_t tchannels; // channels used for input
|
||||
@ -2344,9 +2347,8 @@ typedef struct ncreader_options {
|
||||
bool scroll; // allow more than the physical area's worth of input
|
||||
} ncreader_options;
|
||||
|
||||
// ncreaders provide freeform input in a (possibly multiline) region, supporting
|
||||
// optional readline keybindings. takes ownership of 'n', destroying it on any
|
||||
// error (ncreader_destroy() otherwise destroys the ncplane).
|
||||
// takes ownership of 'n', destroying it on any error (ncreader_destroy()
|
||||
// otherwise destroys the ncplane).
|
||||
struct ncreader* ncreader_create(struct ncplane* n, const ncreader_options* opts);
|
||||
|
||||
// empty the ncreader of any user input, and home the cursor.
|
||||
@ -2367,6 +2369,57 @@ char* ncreader_contents(const struct ncreader* n);
|
||||
void ncreader_destroy(struct ncreader* n, char** contents);
|
||||
```
|
||||
|
||||
### Progbars
|
||||
|
||||
Progress bars proceed linearly in any of four directions. The entirety of the
|
||||
provided plane will be used -- any border should be provided by the caller on
|
||||
another plane. The plane will not be erased; text preloaded into the plane
|
||||
will be consumed by the progress indicator. The bar is redrawn for each
|
||||
provided progress report (a double between 0 and 1), and can regress with
|
||||
lower values. The procession will take place along the longer dimension (at
|
||||
the time of each redraw), with the horizontal length scaled by 2 for
|
||||
purposes of comparison. I.e. for a plane of 20 rows and 50 columns, the
|
||||
progress will be to the right (50 > 40) or left with `OPTION_RETROGRADE`.
|
||||
If `NCPROGBAR_OPTION_LOCK_ORIENTATION` is provided, the initial orientation
|
||||
is locked in, despite any resizes. It locks horizontal progression by
|
||||
default; `NCPROGBAR_OPTION_FORCE_VERTICAL` locks vertical progression. These
|
||||
are recommended if you provide custom EGCs.
|
||||
|
||||
```
|
||||
// Takes ownership of the ncplane 'n', which will be destroyed by
|
||||
// ncprogbar_destroy(). The progress bar is initially at 0%.
|
||||
struct ncuplot* ncprogbar_create(struct ncplane* n, const ncprogbar_options* opts);
|
||||
|
||||
// Return a reference to the ncprogbar's underlying ncplane.
|
||||
#define NCPROGBAR_OPTION_RETROGRADE 0x0001u // proceed left/down
|
||||
#define NCPROGBAR_OPTION_LOCK_ORIENTATION 0x0002u // lock in orientation
|
||||
#define NCPROGBAR_OPTION_FORCE_VERTICAL 0x0003u // lock in vert
|
||||
|
||||
typedef struct ncprogbar_options {
|
||||
// channels for the maximum and minimum points. linear interpolation will be
|
||||
// applied across the domain between these two.
|
||||
uint64_t maxchannels;
|
||||
uint64_t minchannels;
|
||||
// provide NULL for default (geometric) glyphs. otherwise, provide one or
|
||||
// more EGCs to be used for the progress bar. the last EGC provided will be
|
||||
// at the head of the progress. the first will be used for the entirety of
|
||||
// the tail. i.e. "▃▅🭂🭍" might yield "▃▃▃▃▅🭂🭍". note that such a set of EGCs
|
||||
// would not work well for a vertical progress bar.
|
||||
const char egcs;
|
||||
uint64_t flags;
|
||||
} ncprogbar_options;
|
||||
struct ncplane* ncprogbar_plane(struct ncprogbar* n);
|
||||
|
||||
// Set the progress bar's completion, a double 0 <= 'p' <= 1.
|
||||
int ncprogbar_set_progress(struct ncprogbar* n, double p);
|
||||
|
||||
// Get the progress bar's completion, a double on [0, 1].
|
||||
double ncprogbar_progress(const struct ncprogbar* n);
|
||||
|
||||
// Destroy the progress bar and its underlying ncplane.
|
||||
void ncprogbar_destroy(struct ncprogbar* n);
|
||||
```
|
||||
|
||||
## Channels
|
||||
|
||||
A channel encodes 24 bits of RGB color, using 8 bits for each component. It
|
||||
|
||||
@ -57,6 +57,7 @@
|
||||
<a href="notcurses_palette.3.html">notcurses_palette</a>—operations on notcurses palettes<br/>
|
||||
<a href="notcurses_plane.3.html">notcurses_plane</a>—operations on <tt>ncplane</tt> objects<br/>
|
||||
<a href="notcurses_plot.3.html">notcurses_plot</a>—drawing histograms and lineplots<br/>
|
||||
<a href="notcurses_progbar.3.html">notcurses_plot</a>—drawing progress bars<br/>
|
||||
<a href="notcurses_reader.3.html">notcurses_reader</a>—high-level widget for collecting input<br/>
|
||||
<a href="notcurses_refresh.3.html">notcurses_refresh</a>—refresh an externally-damaged display<br/>
|
||||
<a href="notcurses_render.3.html">notcurses_render</a>—sync the physical display<br/>
|
||||
|
||||
@ -100,6 +100,7 @@ A few high-level widgets are included, all built atop ncplanes:
|
||||
* **notcurses_menu(3)** for menu bars at the top or bottom of the screen
|
||||
* **notcurses_multiselector(3)** for selecting one or more items from a set
|
||||
* **notcurses_plot(3)** for drawing histograms and lineplots
|
||||
* **notcurses_progbar(3)** for drawing progress bars
|
||||
* **notcurses_reader(3)** for free-form input data
|
||||
* **notcurses_reel(3)** for hierarchal display of data
|
||||
* **notcurses_selector(3)** for selecting one item from a set
|
||||
@ -156,6 +157,7 @@ order to turn most error returns into exceptions.
|
||||
**notcurses_palette(3)**,
|
||||
**notcurses_plane(3)**,
|
||||
**notcurses_plot(3)**,
|
||||
**notcurses_progbar(3)**,
|
||||
**notcurses_reader(3)**,
|
||||
**notcurses_reel(3)**,
|
||||
**notcurses_refresh(3)**,
|
||||
|
||||
72
doc/man/man3/notcurses_progbar.3.md
Normal file
72
doc/man/man3/notcurses_progbar.3.md
Normal file
@ -0,0 +1,72 @@
|
||||
% notcurses_progbar(3)
|
||||
% nick black <nickblack@linux.com>
|
||||
% v2.0.11
|
||||
|
||||
# NAME
|
||||
|
||||
notcurses_progbar - high level widget for progress bars
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
**#include <notcurses/notcurses.h>**
|
||||
|
||||
```c
|
||||
#define NCPROGBAR_OPTION_RETROGRADE 0x0001u // proceed left/down
|
||||
#define NCPROGBAR_OPTION_LOCK_ORIENTATION 0x0002u // lock in orientation
|
||||
#define NCPROGBAR_OPTION_FORCE_VERTICAL 0x0003u // lock in vert
|
||||
|
||||
typedef struct ncprogbar_options {
|
||||
uint64_t maxchannels;
|
||||
uint64_t minchannels;
|
||||
const char egcs;
|
||||
uint64_t flags;
|
||||
} ncprogbar_options;
|
||||
```
|
||||
|
||||
**struct ncuplot* ncprogbar_create(struct ncplane* ***n***, const ncprogbar_options* ***opts***)**
|
||||
|
||||
**struct ncplane* ncprogbar_plane(struct ncprogbar* ***n***)**
|
||||
|
||||
**int ncprogbar_set_progress(struct ncprogbar* ***n***, double ***p***)**
|
||||
|
||||
**double ncprogbar_progress(const struct ncprogbar* ***n***)**
|
||||
|
||||
**void ncprogbar_destroy(struct ncprogbar* ***n***)**
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
These functions draw progress bars in any of four directions. The progress
|
||||
measure is a **double** between zero and one, inclusive, provided to
|
||||
**ncprogbar_set_progress**. This will be scaled to the size of the provided
|
||||
ncplane ***n***. By default, the axis of progression is the longer element
|
||||
of the plane's geometry, but it can be explicitly chosen with
|
||||
**NCPROGBAR_OPTION_LOCK_ORIENTATION** and **NCPROGBAR_OPTION_FORCE_VERTICAL**.
|
||||
Horizontal bars proceed to the right by default, and vertical bars proceed up.
|
||||
This can be changed with **NCPROGBAR_OPTION_RETROGRADE**.
|
||||
|
||||
# NOTES
|
||||
|
||||
**ncprogbar_create** takes ownership of ***n*** in all cases. On failure,
|
||||
***n*** will be destroyed immediately. It is otherwise destroyed by
|
||||
**ncprogbar_destroy**.
|
||||
|
||||
# RETURN VALUES
|
||||
|
||||
**ncprogbar_plane** returns the **ncplane** on which the progress bar is drawn.
|
||||
**ncprogbar_progress** returns the current progress, a value between zero and
|
||||
one, inclusive. They cannot fail.
|
||||
|
||||
**ncprogbar_set_progress** returns -1 if ***p*** is less than zero or greater
|
||||
than one, or if there is an internal error redrawing the progress bar. It
|
||||
returns 0 otherwise.
|
||||
|
||||
# BUGS
|
||||
|
||||
Whether progression is to the left or right by default probably ought be an
|
||||
aspect of the current locale.
|
||||
|
||||
# SEE ALSO
|
||||
|
||||
**notcurses(3)**,
|
||||
**notcurses_plane(3)**,
|
||||
**notcurses_visual(3)**
|
||||
@ -43,8 +43,9 @@ API void notcurses_version_components(int* major, int* minor, int* patch, int* t
|
||||
struct notcurses; // Notcurses state for a given terminal, composed of ncplanes
|
||||
struct ncplane; // a drawable Notcurses surface, composed of cells
|
||||
struct ncvisual; // a visual bit of multimedia opened with LibAV|OIIO
|
||||
struct ncuplot; // a histogram, bound to a plane (uint64_ts)
|
||||
struct ncdplot; // a histogram, bound to a plane (non-negative doubles)
|
||||
struct ncuplot; // uint64_t histogram
|
||||
struct ncdplot; // double histogram
|
||||
struct ncprogbar; // progress bar
|
||||
struct ncfdplane; // i/o wrapper to dump file descriptor to plane
|
||||
struct ncsubproc; // ncfdplane wrapper with subprocess management
|
||||
struct ncselector;// widget supporting selecting 1 from a list of options
|
||||
@ -3018,6 +3019,59 @@ API bool ncmenu_offer_input(struct ncmenu* n, const struct ncinput* nc);
|
||||
// Destroy a menu created with ncmenu_create().
|
||||
API int ncmenu_destroy(struct ncmenu* n);
|
||||
|
||||
// Progress bars. They proceed linearly in any of four directions. The entirety
|
||||
// of the plane will be used -- any border should be provided by the caller on
|
||||
// another plane. The plane will not be erased; text preloaded into the plane
|
||||
// will be consumed by the progress indicator. The bar is redrawn for each
|
||||
// provided progress report (a double between 0 and 1), and can regress with
|
||||
// lower values. The procession will take place along the longer dimension (at
|
||||
// the time of each redraw), with the horizontal length scaled by 2 for
|
||||
// purposes of comparison. I.e. for a plane of 20 rows and 50 columns, the
|
||||
// progress will be to the right (50 > 40) or left with OPTION_RETROGRADE.
|
||||
// If NCPROGBAR_OPTION_LOCK_ORIENTATION is provided, the initial orientation
|
||||
// is locked in, despite any resizes. It locks horizontal progression by
|
||||
// default; NCPROGBAR_OPTION_FORCE_VERTICAL locks vertical progression. These
|
||||
// are recommended if you provide custom EGCs.
|
||||
|
||||
#define NCPROGBAR_OPTION_RETROGRADE 0x0001u // proceed left/down
|
||||
#define NCPROGBAR_OPTION_LOCK_ORIENTATION 0x0002u // lock in orientation
|
||||
#define NCPROGBAR_OPTION_FORCE_VERTICAL 0x0003u // lock in vert
|
||||
|
||||
typedef struct ncprogbar_options {
|
||||
// channels for the maximum and minimum points. linear interpolation will be
|
||||
// applied across the domain between these two.
|
||||
uint64_t maxchannels;
|
||||
uint64_t minchannels;
|
||||
// provide NULL for default (geometric) glyphs. otherwise, provide one or
|
||||
// more EGCs to be used for the progress bar. the last EGC provided will be
|
||||
// at the head of the progress. the first will be used for the entirety of
|
||||
// the tail. i.e. "▃▅🭂🭍" might yield "▃▃▃▃▅🭂🭍". note that such a set of EGCs
|
||||
// would not work well for a vertical progress bar.
|
||||
const char egcs;
|
||||
uint64_t flags;
|
||||
} ncprogbar_options;
|
||||
|
||||
// Takes ownership of the ncplane 'n', which will be destroyed by
|
||||
// ncprogbar_destroy(). The progress bar is initially at 0%.
|
||||
API struct ncuplot* ncprogbar_create(struct ncplane* n, const ncprogbar_options* opts)
|
||||
__attribute__ ((nonnull (1)));
|
||||
|
||||
// Return a reference to the ncprogbar's underlying ncplane.
|
||||
API struct ncplane* ncprogbar_plane(struct ncprogbar* n)
|
||||
__attribute__ ((nonnull (1)));
|
||||
|
||||
// Set the progress bar's completion, a double 0 <= 'p' <= 1.
|
||||
API int ncprogbar_set_progress(struct ncprogbar* n, double p)
|
||||
__attribute__ ((nonnull (1)));
|
||||
|
||||
// Get the progress bar's completion, a double on [0, 1].
|
||||
API double ncprogbar_progress(const struct ncprogbar* n)
|
||||
__attribute__ ((nonnull (1)));
|
||||
|
||||
// Destroy the progress bar and its underlying ncplane.
|
||||
API void ncprogbar_destroy(struct ncprogbar* n)
|
||||
__attribute__ ((nonnull (1)));
|
||||
|
||||
// Plots. Given a rectilinear area, an ncplot can graph samples along some axis.
|
||||
// There is some underlying independent variable--this could be e.g. measurement
|
||||
// sequence number, or measurement time. Samples are tagged with this variable, which
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user