ColrC  0.3.7
An easy to use C library for linux terminal colors/escape-codes.
colr.controls.h File Reference

(0.3.7)

Declarations for ColrC cursor controls. More...

#include "colr.h"
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define colr_control(...)
 Like colr_fprint(stdout, ...) except it flushes stdout after it prints. More...
 
#define COLR_ESC   "\x1b["
 Escape sequence to use when creating escape codes.
 
#define COLR_ESC_LEN   3
 Length of COLR_ESC, with NULL-terminator.
 
#define colr_print_inplace(...)
 Save the cursor position, print exactly like colr_control(), and then restore the cursor position. More...
 
#define colr_print_overwrite(...)
 Erase the current line, move to column 1 and print exactly like colr_control(). More...
 
#define EraseMethod_to_str(method)
 Returns a static string representation for an EraseMethod. More...
 

Enumerations

enum  EraseMethod {
  END,
  START,
  ALL_MOVE,
  ALL_ERASE,
  ALL_MOVE_ERASE,
  ALL
}
 Methods to erase text. More...
 

Functions

ColorResultColr_cursor_hide (void)
 Returns an allocated ColorResult that hides the cursor when printed. More...
 
ColorResultColr_cursor_show (void)
 Returns an allocated ColorResult that shows the cursor when printed. More...
 
ColorResultColr_erase_display (EraseMethod method)
 Returns an allocated ColorResult that will erase the display or part of the display when printed. More...
 
ColorResultColr_erase_line (EraseMethod method)
 Returns an allocated ColorResult that will erase line or part of a line when printed. More...
 
ColorResultColr_move_back (unsigned int columns)
 Returns an allocated ColorResult that will move the cursor back a number of columns when printed. More...
 
ColorResultColr_move_column (unsigned int column)
 Returns an allocated ColorResult that will move the cursor to a specific column when printed. More...
 
ColorResultColr_move_down (unsigned int lines)
 Returns an allocated ColorResult that will move the cursor down a number of lines when printed. More...
 
ColorResultColr_move_forward (unsigned int columns)
 Returns an allocated ColorResult that will move the cursor forward a number of columns when printed. More...
 
ColorResultColr_move_next (unsigned int lines)
 Returns an allocated ColorResult that will move the cursor down a number of lines, at the start of the line, when printed. More...
 
ColorResultColr_move_pos (unsigned int line, unsigned int column)
 Returns an allocated ColorResult that will position the cursor on the desired line and column when printed. More...
 
ColorResultColr_move_prev (unsigned int lines)
 Returns an allocated ColorResult that will move the cursor up a number of lines, at the start of the line, when printed. More...
 
ColorResultColr_move_return (void)
 Returns an allocated ColorResult that will move the cursor back to the beginning of the line with a carriage return character when printed. More...
 
ColorResultColr_move_up (unsigned int lines)
 Returns an allocated ColorResult that will move the cursor up a number of lines when printed. More...
 
ColorResultColr_pos_restore (void)
 Returns an allocated ColorResult that restores a previously saved cursor position when printed. More...
 
ColorResultColr_pos_save (void)
 Returns an allocated ColorResult that saves the cursor position when printed. More...
 
ColorResultColr_scroll_down (unsigned int lines)
 Returns an allocated ColorResult that will scroll the cursor down a number of lines when printed. More...
 
ColorResultColr_scroll_up (unsigned int lines)
 Returns an allocated ColorResult that will scroll the cursor up a number of lines when printed. More...
 

Detailed Description

Declarations for ColrC cursor controls.

To use ColrC Controls in your project, you will need to include colr.controls.h and compile both colr.c and colr.controls.c with the rest of your files.

Don't forget to compile with colr.c and -lm.

gcc -std=c11 -c your_program.c colr.c colr.controls.c -lm

Macro Definition Documentation

◆ colr_control

#define colr_control (   ...)
Value:
do { \
colr_fprint(stdout, __VA_ARGS__); \
fflush(stdout); \
} while (0)

Like colr_fprint(stdout, ...) except it flushes stdout after it prints.

You may not want to flush stdout after every call. You can use colr_print() with the exact same arguments as colr_control() for those times.

Parameters
[in]...Arguments for colr_fprintf.

◆ colr_print_inplace

#define colr_print_inplace (   ...)
Value:
do { \
colr_control(Colr_pos_save(), __VA_ARGS__, Colr_pos_restore()); \
} while (0)
ColorResult * Colr_pos_restore(void)
Returns an allocated ColorResult that restores a previously saved cursor position when printed...
Definition: colr.controls.c:343
ColorResult * Colr_pos_save(void)
Returns an allocated ColorResult that saves the cursor position when printed.
Definition: colr.controls.c:358

Save the cursor position, print exactly like colr_control(), and then restore the cursor position.

Parameters
[in]...Arguments for colr_control() to print.

◆ colr_print_overwrite

#define colr_print_overwrite (   ...)
Value:
do { \
colr_control(Colr_erase_line(ALL), Colr_move_column(1), __VA_ARGS__); \
} while (0)
ColorResult * Colr_erase_line(EraseMethod method)
Returns an allocated ColorResult that will erase line or part of a line when printed.
Definition: colr.controls.c:122
This is an alias for ALL_MOVE, when using the erase_line functions.
Definition: colr.controls.h:101
ColorResult * Colr_move_column(unsigned int column)
Returns an allocated ColorResult that will move the cursor to a specific column when printed...
Definition: colr.controls.c:182

Erase the current line, move to column 1 and print exactly like colr_control().

Parameters
[in]...Arguments for colr_control() to print.

◆ EraseMethod_to_str

#define EraseMethod_to_str (   method)
Value:
( \
method == END ? "0" : \
method == START ? "1" : \
method == ALL_MOVE ? "2" : \
method == ALL_ERASE ? "3" : \
method == ALL_MOVE_ERASE ? "4" : \
method == ALL ? "2" : \
NULL \
)
Clear cursor to the start of the line/screen (depending on erase function used).
Definition: colr.controls.h:91
Clear cursor to the end of the line/screen (depending on erase function used).
Definition: colr.controls.h:89
Clear all, and erase scrollback buffer.
Definition: colr.controls.h:95
This is an alias for ALL_MOVE, when using the erase_line functions.
Definition: colr.controls.h:101
Clear all, and move home for display, or clear entire the line when doing a line erase.
Definition: colr.controls.h:93
Clear all, move home, and erase scrollback buffer.
Definition: colr.controls.h:99

Returns a static string representation for an EraseMethod.

This will be optimized away into a static string, placed in the read-only data section (https://gcc.godbolt.org/z/c3nzTz).

Parameters
[in]methodThe EraseMethod value to get a string representation for.
Returns
A stack-allocated (read-only) string with the result, or NULL if the method was unknown.

Referenced by Colr_erase_display(), and Colr_erase_line().

Enumeration Type Documentation

◆ EraseMethod

Methods to erase text.

Enumerator
END 

Clear cursor to the end of the line/screen (depending on erase function used).

START 

Clear cursor to the start of the line/screen (depending on erase function used).

ALL_MOVE 

Clear all, and move home for display, or clear entire the line when doing a line erase.

ALL_ERASE 

Clear all, and erase scrollback buffer.

ALL_MOVE_ERASE 

Clear all, move home, and erase scrollback buffer.

This is a feature of ColrC. It is not standard.

ALL 

This is an alias for ALL_MOVE, when using the erase_line functions.

Function Documentation

◆ Colr_cursor_hide()

ColorResult* Colr_cursor_hide ( void  )

Returns an allocated ColorResult that hides the cursor when printed.

Returns

An allocated ColorResult.

If allocation fails, NULL is returned.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

◆  Colr_cursor_hide example:
#include "colr.controls.h"
int main(void) {
printf("Hiding the cursor. ");
puts("About to show the cursor.");
}

◆ Colr_cursor_show()

ColorResult* Colr_cursor_show ( void  )

Returns an allocated ColorResult that shows the cursor when printed.

Returns

An allocated ColorResult.

If allocation fails, NULL is returned.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

◆ Colr_erase_display()

ColorResult* Colr_erase_display ( EraseMethod  method)

Returns an allocated ColorResult that will erase the display or part of the display when printed.

Parameters
[in]methodThe erase method.
Returns

An allocated ColorResult, or NULL if the EraseMethod was invalid.

If allocation fails, NULL is returned.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

◆  Colr_erase_display example:
#include "colr.controls.h"
int main(void) {
// Force flush with colr_control, so we see the first line.
colr_control("This is a line.");
colr_puts(Colr("This is a blue line.", fore(BLUE)));
}

◆ Colr_erase_line()

ColorResult* Colr_erase_line ( EraseMethod  method)

Returns an allocated ColorResult that will erase line or part of a line when printed.

Parameters
[in]methodThe erase method.
Returns

An allocated ColorResult, or NULL if the EraseMethod was invalid.

If allocation fails, NULL is returned.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

◆  Colr_erase_line example:
#include "colr.controls.h"
int main(void) {
// Force flush with colr_control, so we see the first line.
"This is a line.",
Colr("This is a blue line.", fore(BLUE))
);
}

◆ Colr_move_back()

ColorResult* Colr_move_back ( unsigned int  columns)

Returns an allocated ColorResult that will move the cursor back a number of columns when printed.

Parameters
[in]columnsThe number of columns to move. Using 0 is the same as using 1.
Returns

An allocated ColorResult.

If allocation fails, NULL is returned.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

◆ Colr_move_column()

ColorResult* Colr_move_column ( unsigned int  column)

Returns an allocated ColorResult that will move the cursor to a specific column when printed.

Columns start at 1.

Parameters
[in]columnThe column to move to. Using 0 is the same as using 1.
Returns

An allocated ColorResult.

If allocation fails, NULL is returned.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

◆ Colr_move_down()

ColorResult* Colr_move_down ( unsigned int  lines)

Returns an allocated ColorResult that will move the cursor down a number of lines when printed.

Parameters
[in]linesThe number of lines to move. Using 0 is the same as using 1.
Returns

An allocated ColorResult.

If allocation fails, NULL is returned.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

◆ Colr_move_forward()

ColorResult* Colr_move_forward ( unsigned int  columns)

Returns an allocated ColorResult that will move the cursor forward a number of columns when printed.

Parameters
[in]columnsThe number of columns to move. Using 0 is the same as using 1.
Returns

An allocated ColorResult.

If allocation fails, NULL is returned.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

◆ Colr_move_next()

ColorResult* Colr_move_next ( unsigned int  lines)

Returns an allocated ColorResult that will move the cursor down a number of lines, at the start of the line, when printed.

Parameters
[in]linesThe number of lines to move. Using 0 is the same as using 1.
Returns

An allocated ColorResult.

If allocation fails, NULL is returned.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

◆ Colr_move_pos()

ColorResult* Colr_move_pos ( unsigned int  line,
unsigned int  column 
)

Returns an allocated ColorResult that will position the cursor on the desired line and column when printed.

Positions start at 1.

Parameters
[in]lineThe line to move to. Using 0 is the same as using 1.
[in]columnThe column to move to. Using 0 is the same as using 1.
Returns

An allocated ColorResult.

If allocation fails, NULL is returned.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

◆ Colr_move_prev()

ColorResult* Colr_move_prev ( unsigned int  lines)

Returns an allocated ColorResult that will move the cursor up a number of lines, at the start of the line, when printed.

Parameters
[in]linesThe number of lines to move. Using 0 is the same as using 1.
Returns

An allocated ColorResult.

If allocation fails, NULL is returned.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

◆ Colr_move_return()

ColorResult* Colr_move_return ( void  )

Returns an allocated ColorResult that will move the cursor back to the beginning of the line with a carriage return character when printed.

Returns

An allocated ColorResult.

If allocation fails, NULL is returned.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

◆ Colr_move_up()

ColorResult* Colr_move_up ( unsigned int  lines)

Returns an allocated ColorResult that will move the cursor up a number of lines when printed.

Positions start at 1.

Parameters
[in]linesThe number of lines to move. Using 0 is the same as using 1.
Returns

An allocated ColorResult.

If allocation fails, NULL is returned.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

◆ Colr_pos_restore()

ColorResult* Colr_pos_restore ( void  )

Returns an allocated ColorResult that restores a previously saved cursor position when printed.

This only restores the column position, not the line position.

Returns

An allocated ColorResult.

If allocation fails, NULL is returned.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

◆  Colr_pos_restore example:
#include "colr.controls.h"
int main(void) {
printf("Saving the cursor.");
printf("About to restore the cursor.");
puts(" <-- I'm back to where I started.");
}

◆ Colr_pos_save()

ColorResult* Colr_pos_save ( void  )

Returns an allocated ColorResult that saves the cursor position when printed.

This only saves the column position, not the line position.

Returns

An allocated ColorResult.

If allocation fails, NULL is returned.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

◆ Colr_scroll_down()

ColorResult* Colr_scroll_down ( unsigned int  lines)

Returns an allocated ColorResult that will scroll the cursor down a number of lines when printed.

New lines are added to the top.

Parameters
[in]linesThe number of lines to scroll. Using 0 is the same as using 1.
Returns

An allocated ColorResult.

If allocation fails, NULL is returned.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

◆  Colr_scroll_down example:
#include "colr.controls.h"
int main(void) {
colr_control("Start here.\n");
for (int i = 0; i < 5; i++) {
printf("Line: 1-%d\n", i);
}
colr_control(Colr_scroll_down(5), "Back again.\n");
for (int i = 0; i < 5; i++) {
printf("Line: 2-%d\n", i);
}
}

◆ Colr_scroll_up()

ColorResult* Colr_scroll_up ( unsigned int  lines)

Returns an allocated ColorResult that will scroll the cursor up a number of lines when printed.

New lines are added to the bottom.

Parameters
[in]linesThe number of lines to scroll. Using 0 is the same as using 1.
Returns

An allocated ColorResult.

If allocation fails, NULL is returned.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().