.\" Copyright (c) 2007 Hypertriton, Inc. <http://hypertriton.com/>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd October 2, 2007
.Dt AG_CONSOLE 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.3
.Sh NAME
.Nm AG_Console
.Nd agar log console widget
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
The
.Nm
widget displays a set of messages in log format, where a number of
attributes may be associated with individual messages.
The display is automatically scrolled to display new messages.
.Sh INHERITANCE HIERARCHY
.Xr AG_Object 3 ->
.Xr AG_Widget 3 ->
.Nm .
.Sh INITIALIZATION
.nr nS 1
.Ft "AG_Console *"
.Fn AG_ConsoleNew "AG_Widget *parent" "Uint flags"
.Pp
.Ft "void"
.Fn AG_ConsoleSetPadding "AG_Console *cons" "int padding"
.Pp
.nr nS 0
The
.Fn AG_ConsoleNew
function allocates, initializes, and attaches a new
.Nm
widget.
.Pp
.Fn AG_ConsoleSetPadding
sets the padding around messages in pixels.
.Pp
There are currently no specific
.Fa flags
defined for 
.Nm .
.Sh MESSAGES
.nr nS 1
.Ft "AG_ConsoleLine *"
.Fn AG_ConsoleMsg "AG_Console *cons" "const char *fmt" "..."
.Pp
.Ft "AG_ConsoleLine *"
.Fn AG_ConsoleAppendLine "AG_Console *cons" "const char *s"
.Pp
.Ft "void"
.Fn AG_ConsoleMsgPtr "AG_ConsoleLine *line" "void *ptr"
.Pp
.Ft "void"
.Fn AG_ConsoleMsgIcon "AG_ConsoleLine *line" "int surface"
.Pp
.Ft "void"
.Fn AG_ConsoleClear "AG_Console *cons"
.Pp
.nr nS 0
The
.Fn AG_ConsoleMsg
function appends a new message to the log, using a
.Xr printf 3
style format string.
The
.Fn AG_ConsoleAppendLine
variant accepts a bare string.
.Pp
.Fn AG_ConsoleMsgPtr
associates an arbitrary user pointer with the given line entry.
.Fn AG_ConsoleMsgIcon
sets an icon to display left of the message
(see
.Xr AG_IconMgr 3 ) .
.Pp
.Fn AG_ConsoleClear
removes all entries.
.Sh EVENTS
.\" The
.\" .Nm
.\" widget neither reacts to nor generates any event.
The
.Nm
widget reacts to the following events:
.Pp
.Bl -tag -compact -width "window-mousebuttondown "
.It window-mousemotion
.It window-mousebuttonup
.It window-mousebuttondown
.It window-keyup
.It window-keydown
Scroll display.
.El
.Pp
The
.Nm
widget does not generate any event.
.Sh STRUCTURE DATA
For the
.Ft AG_Console
object:
.Pp
.Bl -tag -compact -width "AG_ConsoleLine *lines "
.It Ft AG_Mutex lock
Lock on buffer contents.
.It Ft AG_ConsoleLine *lines
Lines in buffer.
.It Ft Uint nLines
Line count.
.El
.Pp
For the
.Ft AG_ConsoleLine
structure:
.Pp
.Bl -tag -compact -width "int selected "
.It Ft char *text
Text string.
.It Ft size_t len
Length of string, not including NUL.
.It Ft int selected
Line selection flag.
.It Ft int icon
Icon surface to display.
.It Ft AG_Font *font
Text font.
.It Ft Uint32 cFg
Foreground color (in
.Va agDisplayFmt
format).
.It Ft Uint32 cBg
Background color (in
.Va agDisplayFmt
format).
.It Ft void *p
User pointer
.El
.Sh SEE ALSO
.Xr AG_Intro 3 ,
.Xr AG_Widget 3 ,
.Xr AG_Textbox 3 ,
.Xr AG_Window 3
.Sh HISTORY
The
.Nm
widget first appeared in Agar 1.3.