.\" Automatically generated by Pandoc 3.1.12.1
.\"
.TH "notcurses_progbar" "3" "v2.0.11" "" ""
.SH NAME
notcurses_progbar \- high level widget for progress bars
.SH SYNOPSIS
\f[B]#include <notcurses/notcurses.h>\f[R]
.IP
.EX
\f[B]struct\f[R] ncprogbar;

#define NCPROGBAR_OPTION_RETROGRADE        0x0001u \f[I]// proceed left/down\f[R]

\f[B]typedef\f[R] \f[B]struct\f[R] ncprogbar_options {
  uint32_t ulchannel; \f[I]// upper\-left channel. in the context of a progress bar,\f[R]
  uint32_t urchannel; \f[I]// \[dq]up\[dq] is the direction we are progressing towards, and\f[R]
  uint32_t blchannel; \f[I]// \[dq]bottom\[dq] is the direction of origin. for monochromatic\f[R]
  uint32_t brchannel; \f[I]// bar, all four channels ought be the same.\f[R]
  uint64_t flags;
} ncprogbar_options;
.EE
.PP
\f[B]struct ncprogbar* ncprogbar_create(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], const ncprogbar_options*
\f[R]\f[I]opts\f[R]\f[B])\f[R]
.PP
\f[B]struct ncplane* ncprogbar_plane(struct ncprogbar*
\f[R]\f[I]n\f[R]\f[B])\f[R]
.PP
\f[B]int ncprogbar_set_progress(struct ncprogbar* \f[R]\f[I]n\f[R]\f[B],
double \f[R]\f[I]p\f[R]\f[B])\f[R]
.PP
\f[B]double ncprogbar_progress(const struct ncprogbar*
\f[R]\f[I]n\f[R]\f[B])\f[R]
.PP
\f[B]void ncprogbar_destroy(struct ncprogbar*
\f[R]\f[I]n\f[R]\f[B])\f[R]
.SH DESCRIPTION
These functions draw progress bars in any of four directions.
The progress measure is a \f[B]double\f[R] between zero and one,
inclusive, provided to \f[B]ncprogbar_set_progress\f[R].
This will be scaled to the size of the provided ncplane
\f[B]\f[BI]n\f[B]\f[R].
The axis of progression is the longer element of the plane\[aq]s
geometry.
Horizontal bars proceed to the right by default, and vertical bars
proceed up.
This can be changed with \f[B]NCPROGBAR_OPTION_RETROGRADE\f[R].
.SH NOTES
\f[B]ncprogbar_create\f[R] takes ownership of \f[B]\f[BI]n\f[B]\f[R] in
all cases.
On failure, \f[B]\f[BI]n\f[B]\f[R] will be destroyed immediately.
It is otherwise destroyed by \f[B]ncprogbar_destroy\f[R].
.SH RETURN VALUES
\f[B]ncprogbar_plane\f[R] returns the \f[B]ncplane\f[R] on which the
progress bar is drawn.
\f[B]ncprogbar_progress\f[R] returns the current progress, a value
between zero and one, inclusive.
They cannot fail.
.PP
\f[B]ncprogbar_set_progress\f[R] returns \-1 if \f[B]\f[BI]p\f[B]\f[R]
is less than zero or greater than one, or if there is an internal error
redrawing the progress bar.
It returns 0 otherwise.
.SH BUGS
Whether progression is to the left or right by default probably ought be
an aspect of the current locale.
.SH SEE ALSO
\f[B]notcurses(3)\f[R], \f[B]notcurses_plane(3)\f[R],
\f[B]notcurses_visual(3)\f[R]
.SH AUTHORS
nick black \c
.MT nickblack@linux.com
.ME \c.