git clone http://www.coincoin169.org/git/cct.git cct
." ." Copyright (C) 2010 Guillaume Quintin. ." This file is part of cct. ." ." This program is free software; you can redistribute it and/or modify ." it under the terms of the GNU General Public License as published by ." the Free Software Foundation; either version 2 of the License, or ." (at your option) any later version. ." ." 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, write to the Free Software Foundation, Inc., ." 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. ." .TH "cct" 3
cct - a shity library to replace ncurses
#include <cct.h>
cct is a shity library for replacing ncurses with and only with ASCII support. It has no ncurses-like windows. cct knows only about the terminal and assumes it supports a very little subset of the VT100 escape codes.
cct allocates a buffer of the size of the terminal. Every output is made to that buffer. Then cct_refresh writes the buffer content to the terminal.
<cct.h> defines the following structure:
:: struct terminal { ... int fd,w,h; short attr; char unknown; ... }; ::
The terminal structure is attached to one terminal. It contains informations about the terminal whose file descriptor is fd as well as pointers to buffers containing the content of the terminal. The number of columns is in w, the number of columns is in h. Those members shall not be modified directly. The member attr is the attributes of the characters that will be written by output functions. This member shall be modified to set attributes. See the ATTRIBUTES section below. As only ASCII is supported, as soon as you want to write non-ASCII characters to the buffers, they are automatically replaced by the unknown character. This member may be modified directly and shall contain a valid ASCII character. The other members of the terminal structure shall not be modified directly.
cct only supports (for the moment) ASCII characters. If you modify the unknown member of the terminal and put non-ASCII characters, what will be drawn on the terminal is undefined. It depends on the encoding and on the locale of your application and of the terminal. For more information on ASCII see ascii(7). For more information on the different encodings see utf8(7), charsets(7), unicode(7). For more information on locales see setlocale(3).
You can control several terminals with cct. You must initialize a terminal structure with the cct_init_term function. Then you can clear the buffer with the cct_clear function and write into the buffer using functions like cct_putc, cct_puts or cct_hline. To draw onto the terminal use cct_refresh. If you need to read input from the terminal, cct provides a set of functions to manage textboxes.
Each character have attributes. They are contained in a int. They can be OR'd to be mixed. <cct.h> defines the following for foreground and background colors: CCT_FORE_BLACK, CCT_FORE_RED, CCT_FORE_GREEN, CCT_FORE_YELLOW, CCT_FORE_BLUE, CCT_FORE_MAGENTA, CCT_FORE_CYAN, CCT_FORE_WHITE, CCT_BACK_BLACK, CCT_BACK_RED, CCT_BACK_GREEN, CCT_BACK_YELLOW, CCT_BACK_BLUE, CCT_BACK_MAGENTA, CCT_BACK_CYAN, CCT_BACK_WHITE. You can also set bold, underline and reverse video as attributes with the following: CCT_BOLD, CCT_UNDERLINE and CCT_REVERSE. When a character is said to have no attributes, it has in fact attribute 0 or CCT_NORMAL. Any output function use the attr member to set the attributes of characters. This member shall be modified directly to set attributes as no function is provided for this purpose.
cct provides textboxes so that it is easy to read input for your program. The program has total control over a textbox as this exemple shows:
:: terminal term; cct_textbox box; int c;
/ initialization of the textbox / cct_textbox_init(&box,&term,x,y,width,maxlen);
for(;;) {
/ draw the textbox / cct_textbox_draw(&box);
/ refresh the terminal / cct_refresh(&term);
/ read next input key / c = cct_get_key(cct_input(0));
/ select the action to do / switch(c) {
case 't': / the user wants auto-completion / do_auto_completion(); break;
case 'n': / the user has finished typing / return;
default: / for all other keys we let the default actions provided by cct / cct_textbox_keypress(&box,c); } } ::
A textbox is initialized with cct_textbox_init. The cct_textbox_draw function draws the content of the textbox into the buffer of the terminal structure. Thus cct_refresh needs to be called. When a key is pressed it is up to the program to decide what to do. Several functions (listed below) are provided by cct to make it easy to manipulate the textbox. As shown in the exemple above, the program is free to do anything. Suppose that the program wants to go to the end of the text when the up arrow key is pressed, the cursor of the textbox goes to the end of the text. It can simply be achieved with:
:: case CCT_KEY_UP: cct_textbox_end(&box); break; ::
The cct_textbox struct has the following members along others:
:: struct cct_textbox { ... char text; int last,sel; ... }; ::
These shall never be modified directly but they can be read from. The input text is pointed to by text. The index of the last char of the textbox is last, while sel is the index of the current selected char (where the cursor is).
The <cct.h> header defines the following functions and macros:
Initialize the terminal structure pointed by t for the terminal attached to fd. For exemple, to use the terminal attached to your program fd shall be 1. On initialization, *t is filled with informations as described above. The user can of course use these informations but shall not modified them expect for the unknown member. It must be used before any output operation. On error -1 is returned.
When you do not want to use cct for a terminal anymore, call cct_end_term. It will reset all terminal attributes and free properly the terminal structure pointed by t. On error -1 is returned.
Call this function causes cct to to get the size of the terminal represented by t and resize the buffers in the terminal structure. Typical use of this function is when the terminal has been resized, upon receival of the SIGWINCH signal. See signal(7) for more information about the SIGWINCH. On error -1 is returned.
Write the character c into the buffer of terminal t at coordinates (x,y) with attributes t->attr.
Write the string s into the buffer of terminal t. The first character will be written at coordinates (x,y). All the characters will written with attribute t->attr.
Write at most n characters of the string s into the buffer of terminal t. The first character will be written at coordinates (x,y). All the characters will written with attribute t->attr.
Draw a vertical line into the buffer of terminal t of length n beginning at (x,y). The characters used to draw the line is c with attributes t->attr.
Draw a horizontal line into the buffer of terminal t of length n beginning at (x,y). The characters used to draw the line is c with attributes t->attr.
Reserve the n cells at (x,y) of terminal t and write at most n characters of string s in those cells. If the length of s is smaller than n, then the resting cells are filled with spaces. The cct_col_left_puts function tries to left align the text within the reserved cells while the cct_col_right_puts function tries to right align the text.
Fill the entire buffer of terminal t with character c with attributes t->attr. cct_clear fills the entire buffer with spaces and no attributes.
Return a pointer to one or several characters read from fd. Several characters are in the buffer when a ECMA-48 control sequence is read. Do not free the memory because it is static inside the cct_input function. To help determine which key was pressed, use the cct_get_key function which tranforms the buffer into an int. On error NULL is returned.
WARNING: depending on the configuration of the terminal (whose file descriptor is fd) from which you read, cct_input can return invalid ASCII characters. For exemple, if you use an X terminal emulator, it may accept UTF-8 encoded unicode characters. If such a character holds on, say, 3 bytes, then three calls to cct_input are necessary to retrieve the unicode character. Each call will give a single byte with negative value. It is up to the user of cct to deal with these situations.
Return a buffer containing the human readable version of the buffer contained by c. This mainly for debugging purpose.
Returns an int corresponding to c. <cct.h> defines the following: CCT_KEY_UP, CCT_KEY_DOWN, CCT_KEY_RIGHT and CCT_KEY_LEFT. All other value of c represents a single char which can correspond to a valid ASCII character (when 0 <= c <= 127), to a valid character or to a char from a multibyte character according to the locale of the terminal and the system. If the control sequence is unknown 0 is returned. No other control sequences are currently supported by cct.
Tell cct to draw the buffer content of terminal t onto the terminal t. On error -1 is returned.
Tell cct to write the buffer content of terminal t to the file referred to by the file descriptor fd. The file descriptor fd can refer to a regular file or to another terminal. In fact, any file descriptor which can be used by write(2) is valid. On error -1 is returned.
Set attributes on for terminal t. For a list of attributes see termios(3). cct_icanon_on set the canonical mode on. cct_echo_on set the echo on. On error -1 is returned.
Set attributes off for terminal t. For a list of attributes see termios(3). cct_icanon_off set the canonical mode off. cct_echo_off set the echo off. On error -1 is returned.
Initialize the cct_textbox struct. The txt struct is initialized with coordinates (x,y), with width w and is attached to terminal t. The length of the text of txt can be limited to maxlen characters if maxlen is a poositive integer. The textbox must be contained within the terminal. On error -1 is returned.
Free the memory allocated by the textbox txt.
Move and resize txt to coordinates (x,y) and width w.
Erase the text of txt.
Move the cursor of txt to the beginning.
Move the cursor of txt to the end.
Move the cursor of txt to the next char.
Move the cursor of txt the the previous char.
Simulate the DEL key. Delete the selected char of txt.
Simulate the BACKSPACE key. Delete the preceding char of the selected char of txt.
Insert the string s in the textbox txt.
Draw the content of txt in the buffer of the terminal it is attached to.
Handle the key represented by c for txt. Usually, c is an int returned by the cct_get_key function. When the left arrow key or CTRL+B is pressed, go to the previous char. When the right arrow key or CTRL+F is pressed, go to the next char. When CTRL+D is pressed the current char is deleted. When CTRL+A is pressed, go to the beginning. When CTRL+E is pressed, go to the end. When CTRL+U is pressed, erase the text of txt. When c == 8 (BACKSPACE) or c == 127 (DEBIAN BACKSPACE), delete the previous char. If c is negative or c >= 32 (space) the corresponding char is inserted into txt. All other value of c is ignored by this function.
Written by Guillaume Quintin (coincoin169@gmail.com).
tcgetattr(3), tcsetattr(3), <termios.h>(0P), tty_ioctl(4), signal(3P), <signal.h>(0P), signal(7), utf8(7), ascii(7), ncurses(3X), charsets(7), unicode(7), setlocale(3), write(2).