Skip to content

Latest commit

 

History

History
327 lines (222 loc) · 6.03 KB

README.md

File metadata and controls

327 lines (222 loc) · 6.03 KB
Raw

progress.h

Simple progress bar display for the terminal inspired by node-progress

usage

#include <progress.h>

example

#include <progress.h>

void
on_progress (progress_data_t *data);

int
main (void) {
  progress_t *progress = progress_new(100, 60);
  progress->fmt = "progress [:bar] :percent :elapsed";
   
  // listen for progress
  progress_on(progress, PROGRESS_EVENT_PROGRESS, on_progress);
  
  // tick progress
  progress_tick(progress, 10);
}

void
on_progress (progress_data_t *data) {
  progress_write(data->holder);
}

output

progress [======------------------------------------------------------] 10% 0.0s

usage

setup

Create a new progress_t * pointer with a given int total and progress bar size_t width.

int total = 100;
size_t width = 20;
progress_t *progress = progress_new

format

You can define the output to stdout by setting the char * fmt member on the progress_t * pointer. Available tokens in the format string are:

  • :bar - represents progress bar
  • :percent - represents current progress percent
  • :elapsed - represents current elapsed time in seconds as a float
progress->fmt = "  downloading :percent (:elapsed) :bar";

The characters used to draw the complete and incomplete parts of the progress bar can be set too.

progress->bar_char = ".";
progress->bg_bar_char = " ";

events

Bind function callbacks to events where an progress_event_type_t event is:

  • PROGRESS_EVENT_START - represents an event type for when progress has begun
  • PROGRESS_EVENT_PROGRESS - represents an event type for when progress has ticked
  • PROGRESS_EVENT_END - represents an event type for when progress has completed

A valid callback has the following signature which accepts a progress_data_t * pointer.

void callback (progress_data_t *data);
progress_on(progress, PROGRESS_EVENT_START, on_progress_start);
progress_on(progress, PROGRESS_EVENT_PROGRESS, on_progress);
progress_on(progress, PROGRESS_EVENT_END, on_progress_end);

ticks

To increment progress the progress_t * pointer must be passded to progress_tick. If the total has been met then any function pointer bound to PROGRESS_EVENT_END will be called in the order they were bound.

progress_tick(progress, 42);

value

to set the progress bar to specific value you can call. If the total has been met then any function pointer bound to PROGRESS_EVENT_END will be called in the order they were bound.

progress_value(progress, 20);

inspect

You can inspect your progress_t * struct with progress_inspect(progress);.

progress_inspect(progress);

output

#progress =>
    .value: 100
    .total: 100
    .listener_count: 3
    .elapsed: 2.000000
    .start: 1378344826
    .width: 60
    .started: true
    .finished: true
    .bar_char: "="
    .bg_bar_char: "-"
    .fmt: "progress [:bar] :percent :elapsed"
    .listeners[3]

api

progress_new(total, width);

progress_t *
progress_new (int total, size_t width);

Initializes a new progress_t * pointer with a total and width.

example

progress_t *progress = progress_new(100, 20);

progress_event_new(type);

progress_event_t *
progress_event_new(progress_event_type_t type);

Initializes a new progress_event_t * pointer with an event type where type is of enum progress_event_types.

example

progress_event_t * = progress_event_new(PROGRESS_EVENT_PROGRESS);

progress_event_listener_new(type, cb);

progress_event_listener_t *
progress_event_listener_new (progress_event_t *event, progress_cb_t cb);

Initializes a new progress_event_listener_t * pointer bound to an event with a given callback progress_cb_t function pointer.

example

...

progress_event_t *event = progress_event_new(PROGRESS_EVENT_PROGRESS);
progress_event_listener_t *listener = progress_event_listener_new(event, onprogress);

...

void
onprogress (progress_data_t *data) {
  printf("value -> %d\n", data->value);
  printf("ts -> %d\n", data->ts);
}

progress_event_listener_free(listener);

void
progress_event_listener_free (progress_event_listener_t *listener);

Frees a progress_event_listener_t * pointer

example

progress_event_listener_free(listener);

progress_data_new(holder, value);

Initializes a new progress_data_t * pointer

progress_data_t *
progress_data_new (progress_t *holder, int value);

example

progress_data_t * data = progress_data_new(progress, 32);

progress_on(progress, type, cb);

bool
progress_on (progress_t *progress, progress_event_type_t type, progress_cb_t cb);

Binds a progress_cb_t * pointer to a progress_event_t pointer on a progress_t pointer.

example

progress_on(progress, PROGRESS_EVENT_PROGRESS, onprogress);

progress_emit(progress, event, data);

Emits an event with data.

bool
progress_emit (progress_t *progress, progress_event_t *event, progress_data_t *data);

example

progress_event_t *event = progress_event_new(PROGRESS_EVENT_START);
progress_data_t *data = progres_data_new(46);
progress_emit(progress, event, data);

progress_tick(progress, value);

Increments progress by a given value.

bool
progress_tick (progress_t *progress, int value);

example

progress_tick(progress, 16);

progress_value(progress, value);

set progress value

bool
progress_value (progress_t *progress, int value);

example

progress_value(progress, 16);

progress_write(progress);

Draws the progress bar to stdout.

void
progress_write (progress_t *progress);

example

progress_write(progress);
// progress [======------------------------------------------------------] 10% 0.0s

progress_free(progress);

Fress a progress_t * poiinter.

void
progress_free (progress_t *progress);

example

progress_free(progress);

license

MIT