AG_CONSOLE(3)

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

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.