AG_SOCKET(3)

NAME
AG_Socket - agar socket widget

SYNOPSIS

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

DESCRIPTION
The AG_Socket widget is a place holder for one or more drag-and-droppable AG_Icon(3) widgets (or subclasses of it). AG_Socket also provides a boolean ‘state’ binding and a numerical ‘count’ binding.

INHERITANCE HIERARCHY
AG_Object(3) -> AG_Widget(3) -> AG_Socket.

INITIALIZATION
AG_Socket * AG_SocketNew(AG_Widget *parent, Uint flags)

AG_Socket * AG_SocketFromSurface(AG_Widget *parent, Uint flags, AG_Surface *s)

AG_Socket * AG_SocketFromBMP(AG_Widget *parent, Uint flags, const char *file)

void AG_SocketInsertFn(AG_Socket *socket, int (*fn)(AG_Socket *, AG_Icon *))

void AG_SocketRemoveFn(AG_Socket *socket, void (*fn)(AG_Socket *, AG_Icon *))

void AG_SocketOverlayFn(AG_Socket *socket, AG_EventFn fn, const char *fmt, ...)

void AG_SocketSetPadding(AG_Socket *socket, int left, int right, int top, int bottom)

void AG_SocketBgRect(AG_Socket *socket, Uint width, Uint height)

void AG_SocketBgCircle(AG_Socket *socket, Uint radius)

void AG_SocketBgPixmap(AG_Socket *socket, const AG_Surface *s)

void AG_SocketBgPixmapNODUP(AG_Socket *socket, AG_Surface *s)

The AG_SocketNew() function allocates, initializes, and attaches a new AG_Socket widget. The AG_SocketFromSurface() and AG_SocketFromBMP() variants also set a background image for the socket, typically used to show the type of icons that can be drag-and-dropped onto the socket. Acceptable flags include:

AG_SOCKET_STICKY_STATE
    Mouse click should toggle the boolean state.

AG_SOCKET_HFILL
    Expand horizontally in parent container.

AG_SOCKET_VFILL
    Expand vertically in parent container.

AG_SOCKET_EXPAND
    Shorthand for AG_SOCKET_HFILL | AG_SOCKET_VFILL.

The AG_SocketInsertFn() function configures a callback routine fn() that will be invoked whenever the user tries to drop an icon onto the socket. A pointer to the socket and the icon being dropped will be passed to that function. Typically, this routine will use AG_SocketInsertIcon() to assign the icon to the socket. If fn() returns 1, the drag-and-drop item will be destroyed.

The AG_SocketRemoveFn() function registers a callback routine that will be invoked before an icon is removed from a socket.

The AG_SocketOverlayFn() registers a routine that will be invoked in rendering context to draw items on top of the socket (and any contained icons).

The AG_SocketSetPadding() function sets the padding around the socket's icon area in pixels.

AG_SocketBgRect() configures the socket to use a rectangular shape of the given dimensions in pixels.

AG_SocketBgCircle() arranges for the socket to use a circular shape of the given radius in pixels.

AG_SocketBgPixmap() uses (a duplicate of) the given surface as background image. The AG_SocketBgPixmapNODUP() variant uses the surface without copy (potentially unsafe).

EVENTS
The AG_Socket widget generates the following events:

socket-mouseoverlap(int state)
    Cursor has moved inside or outside socket area.
socket-click(int state)
    User has clicked on the socket area.

BINDINGS
The AG_Socket widget provides the following bindings.

BOOL *state
    A generic boolean state associated with the socket.
INT *count
    A generic "count" associated with the socket. Typically used when the socket contains a stack of items.

EXAMPLES
See tests/sockets.c in the Agar source distribution.

STRUCTURE DATA
For the AG_Socket object:

AG_Icon *icon
    Icon in socket or NULL (read-only).

SEE ALSO
AG_Button(3), AG_Intro(3), AG_Pixmap(3), AG_Surface(3), AG_Widget(3), AG_Window(3)

HISTORY
The AG_Socket widget first appeared in Agar 1.0.