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

(0.3.7)

Implements everything in the colr.controls.h header. More...

#include "colr.controls.h"

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

Implements everything in the colr.controls.h header.

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

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().