This document describes the API used to develop xdock clients.
Important:
These functions deal with the connection with the xdock server.
XD_Connection* xd_connect(int argc, char** argv, char id[25])Description: connects to the server in localhost and creates a blank square. It must be called before any other xdock function is called.
Parameters: * argc and argv - the same argc and argv from the main procedure of the application. The library will check from the parameters -s and -p (or --server and --port) to know where to connect to. These parameters are NOT removed from the list. * id: the ID of the client application (currently used only in debug reports).
Returns: the connection structure in case of success, else NULL;
xd_disconnect(XD_Connection *c)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.
xd_update(XD_Connection* c)Description: all changes to the dock are made to memory only. Use this function to update all operations to the screen.
These functions perform basic drawing.
xd_pixel(XD_Connection* c, char color[25], int x, int y)Description: draw a single pixel.
Parameters: *
color- color of the point *x,y- the position of the point
xd_line(XD_Connection* c, char color[25], int x1, int y1, int x2, int 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_rectangle(XD_Connection* c, char color[25], int x, int y, int w, int h)Description: draw a rectangle.
Parameters: *
color- color of the rectangle lines *x,y- position of the top/left of the rectangle *w,h- height and width of the rectangle
xd_box(XD_Connection* c, char color[25], int x, int y, int w, int h)Description: draw a filled rectangle.
Parameters: *
color- color of the rectangle *x,y- position of the top/left of the rectangle *w,h- height and width of the rectangle
xd_panel(XD_Connection* c, int x, int y, int w, int h)Description: draw a filled 3D rectangle that serves as a panel. The border 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
panel_bg.Parameters: *
x1,y1- position of the top/left of the panel *x2,y2- position of the bottom/right of the panel
These functions are more advanced drawing operations.
xd_move_box(XD_Connection* c, int x, int y, int w, int h, int move_x, int move_y, char bg_color[25]);Description: move the contents inside the square (defined by x, y, w, h) a few pixels to a given direction.
Parameters: *
x,y- position of the top/left of the box *w,h- width/height of the box *move_x,move_y- how many pixels to move to each direction. It can be negative, positive or zero. *bg_color: the color that will be left where there were pixels, before moving.
xd_write(XD_Connection* c, char font[25], int x, int y, char* fmt, ...)Description: write text on the box.
Parameters: *
font- the font to be used. A few options areled5,led5_l,led7,led9andled20. *x,y- position of the top/left of the text *fmt- text to be written. Must benullterminated.
xd_send_xpm(XD_Connection* c, char name[25], char** xpm)Description: send a XPM image to the server. A XPM image can be created with GIMP and linked into the executable. Remeber to use images of the type s to use themed colors.
Parameters: *
name- a string that'll identify the image. *xpm- the XPM structure.
xd_draw_image(XD_Connection* c, char image[25], int x, int y)Description: draw a XPM image defined with
xd_send_xpm.Parameters: *
name- the name of the image, defined when the image was sent to the server. *x,y- position of the top/left of the image.
int xd_event(XD_Connection* c, XD_Event* e)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 event is returned in the parameter
e, that has this structure:
typedef struct
{
enum { MOUSE_UP, MOUSE_DOWN } type; // event type
int x, y; // pointer position
} xd_event_t;
Parameters: *
e- a event structure that will return the event. The structure of this parameter is defined above. Don't pass NULL on this parameter.
The following colors are themed colors. They can change according to the theme the user chose. It always recommended to use themed colors.
panel_bg, panel_lt, panel_sw: used for drawing the panel. The color panel_bg is the background color of the dock.unlit, halflit, lit: this are the regular colors, that is used for drawing pixels in the panel. The pixel led can be lit, unlit or halflit.glow: a very strong colorwarning_unlit, halfwarning, warning: the same as unlit, halflit and lit, but indicates a warning (it is usually red).