<-- Back to AG_Intro.3

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 contents and attributes of existing log entries can be updated dynamically.

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 inserted 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 characters.

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 selected lines, joined by newlines of the given variety. Similarly, AG_ConsoleExportBuffer() joins all lines in the buffer with the specified 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

HISTORY

The AG_Console widget first appeared in Agar 1.3. Support for multi-line entries appeared in Agar 1.6. File monitoring features and the AG_ConsoleExportBuffer() call also appeared in Agar 1.6. AG_ConsoleSetPadding() was replaced by the "padding" style attribute.