NeoMutt  2021-02-05-666-ge300cd
Teaching an old dog new tricks
DOXYGEN
lib.h File Reference

Progress bar. More...

#include <stdio.h>
+ Include dependency graph for lib.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Enumerations

enum  ProgressType { MUTT_PROGRESS_READ, MUTT_PROGRESS_WRITE, MUTT_PROGRESS_NET }
 What kind of operation is this progress tracking? More...
 

Functions

void progress_free (struct Progress **ptr)
 Free a Progress Bar. More...
 
struct Progressprogress_new (const char *msg, enum ProgressType type, size_t size)
 Create a new Progress Bar. More...
 
void progress_update (struct Progress *progress, size_t pos, int percent)
 Update the state of the progress bar. More...
 

Detailed Description

Progress bar.

Authors
  • Richard Russon
  • Pietro Cerutti

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Definition in file lib.h.

Enumeration Type Documentation

◆ ProgressType

What kind of operation is this progress tracking?

Enumerator
MUTT_PROGRESS_READ 

Progress tracks elements, according to $read_inc

MUTT_PROGRESS_WRITE 

Progress tracks elements, according to $write_inc

MUTT_PROGRESS_NET 

Progress tracks bytes, according to $net_inc

Definition at line 44 of file lib.h.

45 {
49 };
Progress tracks elements, according to $read_inc
Definition: lib.h:46
Progress tracks bytes, according to $net_inc
Definition: lib.h:48
Progress tracks elements, according to $write_inc
Definition: lib.h:47

Function Documentation

◆ progress_free()

void progress_free ( struct Progress **  ptr)

Free a Progress Bar.

Parameters
ptrProgress Bar to free

Definition at line 228 of file progress.c.

229 {
230  if (!ptr || !*ptr)
231  return;
232 
234  // struct Progress *progress = *ptr;
235 
236  FREE(ptr);
237 }
void mutt_clear_error(void)
Clear the message line (bottom line of screen)
Definition: mutt_logging.c:112
#define FREE(x)
Definition: memory.h:40
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ progress_new()

struct Progress* progress_new ( const char *  msg,
enum ProgressType  type,
size_t  size 
)

Create a new Progress Bar.

Parameters
msgMessage to display; this is copied into the Progress object
typeType, e.g. MUTT_PROGRESS_READ
sizeTotal size of expected file / traffic
Return values
ptrNew Progress Bar

Definition at line 246 of file progress.c.

247 {
248  if (OptNoCurses)
249  return NULL;
250 
251  struct Progress *progress = mutt_mem_calloc(1, sizeof(struct Progress));
252 
253  /* Initialize Progress structure */
254  progress->win = msgwin_get_window();
255  mutt_str_copy(progress->msg, msg, sizeof(progress->msg));
256  progress->size = size;
257  progress->inc = choose_increment(type);
258  progress->is_bytes = (type == MUTT_PROGRESS_NET);
259 
260  /* Generate the size string, if a total size was specified */
261  if (progress->size != 0)
262  {
263  if (progress->is_bytes)
264  {
265  mutt_str_pretty_size(progress->sizestr, sizeof(progress->sizestr),
266  progress->size);
267  }
268  else
269  {
270  snprintf(progress->sizestr, sizeof(progress->sizestr), "%zu", progress->size);
271  }
272  }
273 
274  if (progress->inc == 0)
275  {
276  /* This progress bar does not increment - write the initial message */
277  if (progress->size == 0)
278  {
279  mutt_message(progress->msg);
280  }
281  else
282  {
283  mutt_message("%s (%s)", progress->msg, progress->sizestr);
284  }
285  }
286  else
287  {
288  /* This progress bar does increment - perform the initial update */
289  progress_update(progress, 0, 0);
290  }
291  return progress;
292 }
void * mutt_mem_calloc(size_t nmemb, size_t size)
Allocate zeroed memory on the heap.
Definition: memory.c:50
size_t size
Total expected size.
Definition: progress.c:53
bool is_bytes
true if measuring bytes
Definition: progress.c:56
WHERE bool OptNoCurses
(pseudo) when sending in batch mode
Definition: options.h:47
A Progress Bar.
Definition: progress.c:47
struct MuttWindow * msgwin_get_window(void)
Get the Message Window pointer.
Definition: msgwin.c:253
static size_t choose_increment(enum ProgressType type)
Choose the right increment given a ProgressType.
Definition: progress.c:128
void mutt_str_pretty_size(char *buf, size_t buflen, size_t num)
Display an abbreviated size, like 3.4K.
Definition: muttlib.c:1679
size_t inc
Increment size.
Definition: progress.c:54
char msg[1024]
Message to display.
Definition: progress.c:50
Progress tracks bytes, according to $net_inc
Definition: lib.h:48
void progress_update(struct Progress *progress, size_t pos, int percent)
Update the state of the progress bar.
Definition: progress.c:175
size_t mutt_str_copy(char *dest, const char *src, size_t dsize)
Copy a string into a buffer (guaranteeing NUL-termination)
Definition: string.c:749
#define mutt_message(...)
Definition: logging.h:87
char sizestr[24]
String for percentage/size.
Definition: progress.c:51
struct MuttWindow * win
Window to draw on.
Definition: progress.c:49
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ progress_update()

void progress_update ( struct Progress progress,
size_t  pos,
int  percent 
)

Update the state of the progress bar.

Parameters
progressProgress bar
posPosition, or count
percentPercentage complete

If percent is -1, then the percentage will be calculated using pos and the size in progress.

If percent is positive, it is displayed as percentage, otherwise percentage is calculated from progress->size and pos if progress was initialized with positive size, otherwise no percentage is shown

Definition at line 175 of file progress.c.

176 {
177  if (!progress || OptNoCurses)
178  return;
179 
180  const uint64_t now = mutt_date_epoch_ms();
181 
182  const bool update =
183  (pos == 0) /* always show the first update */ ||
184  (pos_needs_update(progress, pos) && time_needs_update(progress, now));
185 
186  if ((progress->inc != 0) && update)
187  {
188  progress->pos = pos;
189  progress->timestamp = now;
190 
191  char posstr[128];
192  if (progress->is_bytes)
193  {
194  const size_t round_pos =
195  (progress->pos / (progress->inc << 10)) * (progress->inc << 10);
196  mutt_str_pretty_size(posstr, sizeof(posstr), round_pos);
197  }
198  else
199  {
200  snprintf(posstr, sizeof(posstr), "%zu", progress->pos);
201  }
202 
203  mutt_debug(LL_DEBUG4, "updating progress: %s\n", posstr);
204 
205  if (progress->size != 0)
206  {
207  if (percent < 0)
208  {
209  percent = 100.0 * progress->pos / progress->size;
210  }
211  message_bar(progress->win, percent, "%s %s/%s (%d%%)", progress->msg,
212  posstr, progress->sizestr, percent);
213  }
214  else
215  {
216  if (percent > 0)
217  message_bar(progress->win, percent, "%s %s (%d%%)", progress->msg, posstr, percent);
218  else
219  mutt_message("%s %s", progress->msg, posstr);
220  }
221  }
222 }
Log at debug level 4.
Definition: logging.h:43
uint64_t mutt_date_epoch_ms(void)
Return the number of milliseconds since the Unix epoch.
Definition: date.c:436
static void message_bar(struct MuttWindow *win, int percent, const char *fmt,...)
Draw a colourful progress bar.
Definition: progress.c:66
size_t size
Total expected size.
Definition: progress.c:53
bool is_bytes
true if measuring bytes
Definition: progress.c:56
static bool pos_needs_update(const struct Progress *progress, long pos)
Do we need to update, given the current pos?
Definition: progress.c:143
WHERE bool OptNoCurses
(pseudo) when sending in batch mode
Definition: options.h:47
size_t pos
Current postion.
Definition: progress.c:52
static bool time_needs_update(const struct Progress *progress, size_t now)
Do we need to update, given the current time?
Definition: progress.c:155
void mutt_str_pretty_size(char *buf, size_t buflen, size_t num)
Display an abbreviated size, like 3.4K.
Definition: muttlib.c:1679
size_t inc
Increment size.
Definition: progress.c:54
char msg[1024]
Message to display.
Definition: progress.c:50
uint64_t timestamp
Time of last update.
Definition: progress.c:55
#define mutt_debug(LEVEL,...)
Definition: logging.h:85
#define mutt_message(...)
Definition: logging.h:87
char sizestr[24]
String for percentage/size.
Definition: progress.c:51
struct MuttWindow * win
Window to draw on.
Definition: progress.c:49
+ Here is the call graph for this function:
+ Here is the caller graph for this function: