NAME

AG_Console —

agar log console widget

SYNOPSIS

#include <agar/core.h>
#include <agar/gui.h>

DESCRIPTION

The AG_Console widget displays a scrollable list of messages in log format. Messages may be copied to the clipboard or exported to a file. After a message has been appended to the log, its text (and other attributes) can be changed. By default, the display automatically scrolls down to make new messages visible.

INHERITANCE HIERARCHY

AG_Object(3) -> AG_Widget(3) -> AG_Console.

INITIALIZATION

AG_Console *
AG_ConsoleNew(AG_Widget *parent, Uint flags);

void
AG_ConsoleSetPadding(AG_Console *cons, int padding);

void
AG_ConsoleSetFont(AG_Console *cons, AG_Font *font);

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 contextual popup menus.
AG_CONSOLE_HFILL: Expand horizontally in parent (equivalent to invoking AG_ExpandHoriz(3)).
AG_CONSOLE_VFILL: Expand vertically in parent (equivalent to invoking AG_ExpandVert(3)).
AG_CONSOLE_EXPAND: Shorthand for AG_CONSOLE_HFILL|AG_CONSOLE_VFILL.

The AG_ConsoleSetPadding() function sets the padding around messages in pixels.

AG_ConsoleSetFont() configures an alternate font for the AG_Console messages (see AG_FetchFont(3)).

MESSAGES

AG_ConsoleLine *
AG_ConsoleMsg(AG_Console *cons, const char *format, ...);

AG_ConsoleLine *
AG_ConsoleMsgS(AG_Console *cons, const char *text);

void
AG_ConsoleMsgEdit(AG_ConsoleLine *line, const char *newText);

void
AG_ConsoleMsgPtr(AG_ConsoleLine *line, void *ptr);

void
AG_ConsoleMsgIcon(AG_ConsoleLine *line, int surface);

void
AG_ConsoleMsgColor(AG_ConsoleLine *line, const AG_Color *c);

void
AG_ConsoleClear(AG_Console *cons);

char *
AG_ConsoleExportText(AG_Console *cons, int nativeNewlines);

The AG_ConsoleMsg() function appends a new message to the console log. Unless an error occurs, the function returns a AG_ConsoleLine handle. This handle remains valid until the widget is destroyed, or AG_ConsoleClear() is used.

As a special case, if a cons argument of NULL is passed to AG_ConsoleMsg() or AG_ConsoleMsgS(), the function prints the message with AG_Verbose(3) before returning NULL.

The AG_ConsoleMsgEdit() routine replaces the text of an existing message. AG_ConsoleMsgPtr() associates an arbitrary user pointer with the given message. AG_ConsoleMsgIcon() sets an icon to display next to the message (see AG_IconMgr(3)). AG_ConsoleMsgColor() an alternate, line-specific text color.

AG_ConsoleClear() clears all messages from the console.

The AG_ConsoleExportText() routine returns a C string containing the currently selected lines. The lines are joined with newlines. If nativeNewlines is non-zero, platform-specific newlines are used.

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.
size_t len: Length of string in characters.
int selected: Line selection flag.
int icon: Icon surface to display.
AG_Font *font: Alternate font (if NULL, the default font is used). Usually set with AG_ConsoleSetFont().
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.