<-- Back to AG_Intro.3

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.