xdock API (version 0.2.0)

This document describes the API used to develop xdock clients.

Important:

• the dock is 64x64 pixels, so all position parameters must be between 0 and 63.
• uchar means unsigned char.

Table of contents

Connection functions

These functions deal with the connection with the xdock server.

int xd_connect()

Description: connects to the server in localhost and creates a blank square. It must be called before any other xdock function is called.

Returns: -1 if connection was sucessful, 0 is not.

void xd_disconnect()

Description: closes the connection with the server. It’s not necessary to call this function at the end of the execution of the program, use it to close the connection during the execution.

void xd_flush()

Description: all changes to the dock are made to memory only. Use this function to update all operations to the screen.

Versions

const char* xd_version()

Description: returns the xdock version.

Basic drawing functions

These functions perform basic drawing.

void xd_draw_point(uchar color, uchar x, uchar y)

Description: draw a point (one pixel).

Parameters:

• color - color of the point
• x, y - the position of the point

xd_draw_line(uchar color, uchar x1, uchar y1, uchar x2, uchar y2)

Description: draw a line

Parameters:

• color - color of the line
• x1, y1 - position of the beginning of the line
• x2, y2 - position of the end of the line

xd_draw_rectangle(uchar color, uchar x1, uchar y1, uchar x2, uchar y2)

Description: draw a rectangle

Parameters:

• color - color of the rectangle lines
• x1, y1 - position of the top/left of the rectangle
• x2, y2 - position of the bottom/right of the rectangle

xd_draw_box(uchar fgcolor, uchar bgcolor, uchar x1, uchar y1, uchar x2, uchar y2)

Description: draw a filled rectangle

Parameters:

• bgcolor - color of the rectangle lines
• fgcolor - color of the rectangle background
• x1, y1 - position of the top/left of the rectangle
• x2, y2 - position of the bottom/right of the rectangle

Themed commands

These function perform drawing based on a theme. Currently, only the LED theme is available.

void xd_led_draw_panel(uchar x1, uchar y1, uchar x2, uchar y2)

Description: draw a filled rectangle that serves as a LED panel. The berder of the panel is 2 pixel wide, so remember to make move operations one pixel inside the panel. The background of the panel is the color XD_LED_BG.

Parameters:

• x1, y1 - position of the top/left of the panel
• x2, y2 - position of the bottom/right of the panel

Advanced operations

These functions are more advanced drawing operations.

void xd_move_box(uchar x1, uchar y1, uchar x2, uchar y2, uchar direction, uchar step, uchar bg_color)

Description: move the contents inside the square (defined by x1, y1, x2, y2) a few pixels to a given direction.

Parameters:

• x1, y1 - position of the top/left of the box
• x2, y2 - position of the bottom/right of the box
• direction - direction where the contents of the box will move to. Possible options are: XD_UP, XD_DOWN, XD_LEFT and XD_RIGHT.
• step: number of pixels the contents of the box will move.
• bg_color: the color that will be left where there were pixels, before moving.

void xd_write(uchar font, uchar x, uchar y, const char* text)

Description: write text on the box.

Parameters:

• font - the font to be used. Currently, the only option is XD_FONT_LED_1.
• x, y - position of the top/left of the text
• text - text to be written. Must be null terminated.

void xd_send_xpm(uchar n, char** xpm)

Description: send a XPM image to the server. A XPM image can be created with GIMP and linked into the executable. The colors of the image need not to be defined with xd_set_color.

Parameters:

• n - the number of the image. It can be any number from 0 to 255. This number will be used to refer to the image when drawing it.
• xpm - the XPM structure.

void xd_draw_image(uchar n, uchar x, uchar y)

Description: draw a XPM image defined with xd_send_xpm.

Parameters:

• n - the number of the image, defined when the image was sent to the server.
• x, y - position of the top/left of the image.

void xd_set_color(uchar color, uchar r, uchar g, uchar b)

Description: define a new color.

Parameters:

• color - the number of the color. It must be between 128 and 255. Colors below 128 are reserved.
• r, g and b: amount of red, green and blue, respectively. Between 0 and 255.

Events

void xd_grab_events(uchar event_mask, uchar x1, uchar y1, uchar x2, uchar y2)

Description: calling this function means that the server will start sending to the client all events (such as mousepresses) that occur within the area described by the parameters x1, y1, x2 and x2. Only the parameters set my the event_mask parameters will be caught. If this function is called more than once, then the last call replaces the previous one. The area outside outside the defined event area is used to drag the dock to a new position. It is recommended that is left a area of at least 4 pixels in each side.

Parameters:

• event_mask - the type of event that’ll be caught. It can be one of: MOUSE_DOWN, MOUSE_UP and MOUSE_PRESS. MOUSE_PRESS emulates a click on a button, when the mouse is pressed and released without moving.
• x1, y2, x2 and y2 - the confined area where the events will be caught. Any mousepresses ouside this area will drag the dock.

xd_next_event(xd_event_t* event)

Description: gets the next event from the server. It’s a non blocking function, and it will return 1 if a event is on the queue, and 0 if the queue is empty. The next event in queue is returned in the parameter event.

Parameters:

• event - a event structure that will return the event. The structure of this parameter is defined below.
• Don’t pass NULL on this parameter.

typedef struct
{
    unsigned char type; // Type of event: MOUSE_DOWN, MOUSE_UP or MOUSE_PRESS
    unsigned char x;
    unsigned char y;
    unsigned char button; // Mouse button pressed: 1 (left), 2 (middle) or 3(right)
} xd_event_t;

Standard color list

The following colors are available standard from xdock. You can create your own colors with xd_set_color.