(0.4.0)

Declarations for ColrC cursor controls. More...

#include "colr.h"

This graph shows which files directly or indirectly include 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
ColorResult *	Colr_cursor_hide (void)
	Returns an allocated ColorResult that hides the cursor when printed. More...

ColorResult *	Colr_cursor_show (void)
	Returns an allocated ColorResult that shows the cursor when printed. More...

ColorResult *	Colr_erase_display (EraseMethod method)
	Returns an allocated ColorResult that will erase the display or part of the display when printed. More...

ColorResult *	Colr_erase_line (EraseMethod method)
	Returns an allocated ColorResult that will erase line or part of a line when printed. More...

ColorResult *	Colr_move_back (unsigned int columns)
	Returns an allocated ColorResult that will move the cursor back a number of columns when printed. More...

ColorResult *	Colr_move_column (unsigned int column)
	Returns an allocated ColorResult that will move the cursor to a specific column when printed. More...

ColorResult *	Colr_move_down (unsigned int lines)
	Returns an allocated ColorResult that will move the cursor down a number of lines when printed. More...

ColorResult *	Colr_move_forward (unsigned int columns)
	Returns an allocated ColorResult that will move the cursor forward a number of columns when printed. More...

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. More...

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. More...

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. More...

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. More...

ColorResult *	Colr_move_up (unsigned int lines)
	Returns an allocated ColorResult that will move the cursor up a number of lines when printed. More...

ColorResult *	Colr_pos_restore (void)
	Returns an allocated ColorResult that restores a previously saved cursor position when printed. More...

ColorResult *	Colr_pos_save (void)
	Returns an allocated ColorResult that saves the cursor position when printed. More...

ColorResult *	Colr_scroll_down (unsigned int lines)
	Returns an allocated ColorResult that will scroll the cursor down a number of lines when printed. More...

ColorResult *	Colr_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)

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)

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 \
    )

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] method The 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

enum 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(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, 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. ");
    colr_control(Colr_cursor_hide());
    puts("About to show the cursor.");
    colr_control(Colr_cursor_show());
}

◆ 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(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, 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] method The 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(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, 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_control(Colr_erase_display(ALL_MOVE));
    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] method The 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(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, 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.
    colr_control(
        "This is a line.",
        Colr_erase_line(ALL),
        Colr_move_return(),
        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] columns The 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(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, 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] column The 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(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, 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] lines The 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(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, 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] columns The 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(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, 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] lines The 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(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, 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]	line	The line to move to. Using `0` is the same as using `1`.
[in]	column	The 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(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, 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] lines The 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(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, 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(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, 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] lines The 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(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, 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(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, 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.");
    colr_control(Colr_pos_save());
    printf("About to restore the cursor.");
    colr_control(Colr_pos_restore());
    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(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, 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] lines The 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(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, 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] lines The 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(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().

(0.4.0)

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ colr_control

◆ colr_print_inplace

◆ colr_print_overwrite

◆ EraseMethod_to_str

Enumeration Type Documentation

◆ EraseMethod

Function Documentation

◆ Colr_cursor_hide()

◆ Colr_cursor_show()

◆ Colr_erase_display()

◆ Colr_erase_line()

◆ Colr_move_back()

◆ Colr_move_column()

◆ Colr_move_down()

◆ Colr_move_forward()

◆ Colr_move_next()

◆ Colr_move_pos()

◆ Colr_move_prev()

◆ Colr_move_return()

◆ Colr_move_up()

◆ Colr_pos_restore()

◆ Colr_pos_save()

◆ Colr_scroll_down()

◆ Colr_scroll_up()