FreeBSD Manual Pages
AG_CONSOLE(3) Library Functions Manual AG_CONSOLE(3) NAME AG_Console -- agar log console widget SYNOPSIS #include <agar/core.h> #include <agar/gui.h> DESCRIPTION AG_Console displays a scrollable list of messages in a log format. Log entries can be copied to the clipboard or exported to a file. The con- tents and attributes of existing log entries can be updated dynami- cally. INHERITANCE HIERARCHY AG_Object(3) -> AG_Widget(3) -> AG_Console. INITIALIZATION AG_Console * AG_ConsoleNew(AG_Widget *parent, Uint flags) The AG_ConsoleNew() function allocates, initializes, and attaches a new AG_Console widget. Acceptable flags include: AG_CONSOLE_NOAUTOSCROLL Don't scroll automatically to make newly in- serted lines visible. AG_CONSOLE_NOPOPUP Disable the right-click contextual popup menu (with Copy, Select All and Export functions). AG_CONSOLE_HFILL Expand horizontally in parent container. AG_CONSOLE_VFILL Expand vertically in parent container. AG_CONSOLE_EXPAND Shorthand for AG_CONSOLE_HFILL | AG_CONSOLE_VFILL. MESSAGES AG_ConsoleLine * AG_ConsoleMsg(AG_Console *cons, const char *format, ...) AG_ConsoleLine * AG_ConsoleMsgS(AG_Console *cons, const char *s) AG_ConsoleLine * AG_ConsoleBinary(AG_Console *cons, const void *data, AG_Size data_size, const char *label, const char *format) void AG_ConsoleMsgEdit(AG_ConsoleLine *line, const char *s) void AG_ConsoleMsgCatS(AG_ConsoleLine *line, const char *s) void AG_ConsoleMsgPtr(AG_ConsoleLine *line, void *ptr) void AG_ConsoleMsgColor(AG_ConsoleLine *line, const AG_Color *c) void AG_ConsoleClear(AG_Console *cons) char * AG_ConsoleExportText(AG_Console *cons, enum ag_newline_type newline) char * AG_ConsoleExportBuffer(AG_Console *cons, enum ag_newline_type newline) The AG_ConsoleMsg() function appends a new message to the console log. Unless an error occurs, the function returns a pointer to the created AG_ConsoleLine. If the message contains newlines, create a group of lines (which will be displayed in an indented style) and return a pointer to the first line (which will be the parent of the subsequent lines). The returned AG_ConsoleLine remains valid until deleted (or AG_ConsoleClear() is used). As a special case, if a cons argument of NULL is passed to AG_ConsoleMsg() then the message is passed to AG_Verbose(3) (and the function returns NULL). AG_ConsoleBinary() displays binary data in canonical hex+ASCII format. If non-NULL, label is prepended to every line. If non-NULL, format specifies an alternate format string (such as "%02d " for decimal). The default format is "%02x ". The format string must generate 3 char- acters. AG_ConsoleMsgEdit() replaces an existing log entry's text with the given string. AG_ConsoleMsgCatS() appends the given string to an existing log entry's text. AG_ConsoleMsgPtr() sets an optional user pointer for this log entry. AG_ConsoleMsgColor() sets an alternate, line-specific color for this log entry. AG_ConsoleClear() clears all messages from the console. AG_ConsoleExportText() returns a C string containing all currently se- lected lines, joined by newlines of the given variety. Similarly, AG_ConsoleExportBuffer() joins all lines in the buffer with the speci- fied type of newline. FILE MONITORING AG_ConsoleFile * AG_ConsoleOpenFile(AG_Console *cons, const char *label, const char *file, enum ag_newline_type newline, Uint flags) AG_ConsoleFile * AG_ConsoleOpenFD(AG_Console *cons, const char *label, int fd, enum ag_newline_type newline, Uint flags) AG_ConsoleFile * AG_ConsoleOpenStream(AG_Console *cons, const char *label, FILE *f, enum ag_newline_type newline, Uint flags) void AG_ConsoleClose(AG_Console *cons, AG_ConsoleFile *cf) AG_ConsoleOpenFile() opens a file for reading, displays its contents on the console and then arranges for AG_Console to follow changes made to the file (similar to "tail -f" in Unix). Internally the function uses AG_AddEventSink(3) to set up an event sink of type AG_SINK_READ on the open file descriptor. The newline argument indicates the style of newline to use: enum ag_newline_type { AG_NEWLINE_LF, /* Unix, Amiga, BeOS, Multics, RISC OS */ AG_NEWLINE_CR_LF, /* DOS/Windows, early non-Unix */ AG_NEWLINE_CR, /* Commodore 8-bit machines (C64/128) */ }; Possible flags include: #define AG_CONSOLE_FILE_BINARY 0x01 /* Binary hex dump */ #define AG_CONSOLE_FILE_LEAVE_OPEN 0x02 /* Don't close fd on detach */ If AG_CONSOLE_FILE_BINARY is used then AG_Console produces a canonical hex+ASCII dump of the file (and any changes to it). The AG_CONSOLE_FILE_LEAVE_OPEN option causes AG_ConsoleClose() to leave the file descriptor (or FILE * handle) open. The AG_ConsoleOpenFD() variant accepts an integer file descriptor, and AG_ConsoleOpenFILE() accepts the FILE * handle of an open stream. AG_ConsoleClose() closes a file being followed. EVENTS The AG_Console widget does not generate any event. STRUCTURE DATA For the AG_Console object: int pos Current cursor position (or -1). int sel Selection (offset from cursor). AG_Mutex lock Lock on buffer contents. AG_ConsoleLine **lines Lines in buffer. Uint nLines Line count. For the AG_ConsoleLine structure: char *text Text string. AG_Size len Length of string in characters. int selected Line selection flag. int icon Icon surface to display. AG_Color cFg Foreground color. AG_Color cBg Background color. void *p User pointer SEE ALSO AG_Color(3), AG_Intro(3), AG_Text(3), AG_Textbox(3), AG_Widget(3), AG_Window(3) HISTORY The AG_Console widget first appeared in Agar 1.3.4. In Agar 1.6.0, AG_ConsoleSetPadding() was deprecated by the generic "padding" style attribute. Agar 1.6.0 added support for multi-line entries and intro- duced AG_ConsoleOpenFile(), AG_ConsoleOpenFD(), AG_ConsoleOpenStream(), AG_ConsoleClose(), AG_ConsoleMsgCatS(), AG_ConsoleBinary() and AG_ConsoleExportBuffer(). Agar 1.7 December 21, 2022 AG_CONSOLE(3)
NAME | SYNOPSIS | DESCRIPTION | INHERITANCE HIERARCHY | INITIALIZATION | MESSAGES | FILE MONITORING | EVENTS | STRUCTURE DATA | SEE ALSO | HISTORY
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=AG_Console&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>