| blob | 54f511266c574779a2302c42a8c5db891281f15f |
1 xdock API (version 0.2.0)\r
2 =========================\r
3 \r
4 This document describes the API used to develop **xdock** clients. \r
5 \r
6 Important:\r
7 \r
8 * the dock is 64x64 pixels, so all position parameters must be between 0 and 63.\r
9 * `uchar` means `unsigned char`.\r
10 \r
11 --------------------------------------------------------------\r
12 \r
13 Table of contents\r
14 -----------------\r
15 \r
16 * Table of Contents:\r
17 {:toc}\r
18 \r
19 --------------------------------------------------------------\r
20 \r
21 Connection functions\r
22 --------------------\r
23 \r
24 These functions deal with the connection with the xdock server.\r
25 \r
26 ### `int xd_connect()`\r
27 \r
28 > _Description_: connects to the server in localhost and creates a blank square. It must be called before any other **xdock** function is called.\r
29 \r
30 > _Returns_: -1 if connection was sucessful, 0 is not.\r
31 \r
32 ### `void xd_disconnect()`\r
33 \r
34 > _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.\r
35 \r
36 ### `void xd_flush()`\r
37 \r
38 > _Description_: all changes to the dock are made to memory only. Use this function to update all operations to the screen.\r
39 \r
40 --------------------------------------------------------------\r
41 \r
42 Versions\r
43 --------\r
44 \r
45 ### `const char* xd_version()`\r
46 \r
47 > _Description_: returns the xdock version.\r
48 \r
49 --------------------------------------------------------------\r
50 \r
51 Basic drawing functions\r
52 -----------------------\r
53 \r
54 These functions perform basic drawing.\r
55 \r
56 ### `void xd_draw_point(uchar color, uchar x, uchar y)`\r
57 \r
58 > _Description_: draw a point (one pixel).\r
59 \r
60 > _Parameters_:\r
61 > * `color` - color of the point\r
62 > * `x`, `y` - the position of the point\r
63 \r
64 ### `xd_draw_line(uchar color, uchar x1, uchar y1, uchar x2, uchar y2)`\r
65 \r
66 > _Description_: draw a line\r
67 \r
68 > _Parameters_:\r
69 > * `color` - color of the line\r
70 > * `x1`, `y1` - position of the beginning of the line\r
71 > * `x2`, `y2` - position of the end of the line\r
72 \r
73 ### `xd_draw_rectangle(uchar color, uchar x1, uchar y1, uchar x2, uchar y2)`\r
74 \r
75 > _Description_: draw a rectangle\r
76 \r
77 > _Parameters_:\r
78 > * `color` - color of the rectangle lines\r
79 > * `x1`, `y1` - position of the top/left of the rectangle\r
80 > * `x2`, `y2` - position of the bottom/right of the rectangle\r
81 \r
82 ### `xd_draw_box(uchar fgcolor, uchar bgcolor, uchar x1, uchar y1, uchar x2, uchar y2)`\r
83 \r
84 > _Description_: draw a filled rectangle\r
85 \r
86 > _Parameters_:\r
87 > * `bgcolor` - color of the rectangle lines\r
88 > * `fgcolor` - color of the rectangle background\r
89 > * `x1`, `y1` - position of the top/left of the rectangle\r
90 > * `x2`, `y2` - position of the bottom/right of the rectangle\r
91 \r
92 --------------------------------------------------------------\r
93 \r
94 Themed commands\r
95 ---------------\r
96 \r
97 These function perform drawing based on a theme. Currently, only the LED theme is available.\r
98 \r
99 ### `void xd_led_draw_panel(uchar x1, uchar y1, uchar x2, uchar y2)`\r
100 \r
101 > _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`.\r
102 \r
103 > _Parameters_:\r
104 > * `x1`, `y1` - position of the top/left of the panel\r
105 > * `x2`, `y2` - position of the bottom/right of the panel\r
106 \r
107 --------------------------------------------------------------\r
108 \r
109 Advanced operations\r
110 -------------------\r
111 \r
112 These functions are more advanced drawing operations.\r
113 \r
114 ### `void xd_move_box(uchar x1, uchar y1, uchar x2, uchar y2, uchar direction, uchar step, uchar bg_color)`\r
115 \r
116 > _Description_: move the contents inside the square (defined by x1, y1, x2, y2) a few pixels to a given direction.\r
117 \r
118 > _Parameters_:\r
119 > * `x1`, `y1` - position of the top/left of the box\r
120 > * `x2`, `y2` - position of the bottom/right of the box\r
121 > * `direction` - direction where the contents of the box will move to. Possible options are: `XD_UP`, `XD_DOWN`, `XD_LEFT` and `XD_RIGHT`.\r
122 > * `step`: number of pixels the contents of the box will move.\r
123 > * `bg_color`: the color that will be left where there were pixels, before moving.\r
124 \r
125 ### `void xd_write(uchar font, uchar x, uchar y, const char* text)`\r
126 \r
127 > _Description_: write text on the box.\r
128 \r
129 > _Parameters_:\r
130 > * `font` - the font to be used. Currently, the only option is `XD_FONT_LED_1`.\r
131 > * `x`, `y` - position of the top/left of the text\r
132 > * `text` - text to be written. Must be `null` terminated.\r
133 \r
134 ### `void xd_send_xpm(uchar n, char** xpm)`\r
135 \r
136 > _Description_: send a XPM image to the server. A XPM image can be created with [GIMP](http://www.gimp.org/) and linked into the executable. The colors of the image need not to be defined with `xd_set_color`.\r
137 \r
138 > _Parameters:_\r
139 > * `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.\r
140 > * `xpm` - the XPM structure.\r
141 \r
142 ### `void xd_draw_image(uchar n, uchar x, uchar y)`\r
143 \r
144 > _Description_: draw a XPM image defined with `xd_send_xpm`.\r
145 \r
146 > _Parameters_:\r
147 > * `n` - the number of the image, defined when the image was sent to the server.\r
148 > * `x`, `y` - position of the top/left of the image.\r
149 \r
150 ### `void xd_set_color(uchar color, uchar r, uchar g, uchar b)`\r
151 \r
152 > _Description_: define a new color.\r
153 \r
154 > _Parameters:_\r
155 > * `color` - the number of the color. It must be between 128 and 255. Colors below 128 are reserved.\r
156 > * `r`, `g` and `b`: amount of red, green and blue, respectively. Between 0 and 255.\r
157 \r
158 --------------------------------------------------------------\r
159 \r
160 Events\r
161 ------\r
162 \r
163 ### `void xd_grab_events(uchar event_mask, uchar x1, uchar y1, uchar x2, uchar y2)`\r
164 \r
165 > _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.\r
166 > 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.\r
167 \r
168 > _Parameters:_\r
169 > * `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.\r
170 > * `x1`, `y2`, `x2` and `y2` - the confined area where the events will be caught. Any mousepresses ouside this area will drag the dock.\r
171 \r
172 ### `xd_next_event(xd_event_t* event)`\r
173 \r
174 > _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`.\r
175 \r
176 > _Parameters:_\r
177 > * `event` - a event structure that will return the event. The structure of this parameter is defined below. \r
178 > * Don't pass NULL on this parameter.\r
179 \r
180 typedef struct\r
181 {\r
182 unsigned char type; // Type of event: MOUSE_DOWN, MOUSE_UP or MOUSE_PRESS\r
183 unsigned char x;\r
184 unsigned char y;\r
185 unsigned char button; // Mouse button pressed: 1 (left), 2 (middle) or 3(right)\r
186 } xd_event_t;\r
187 \r
188 --------------------------------------------------------------\r
189 \r
190 Standard color list\r
191 -------------------\r
192 \r
193 The following colors are available standard from **xdock**. You can create your own colors with `xd_set_color`.\r
194 \r
195 <table border="1">\r
196 <tr><th>Name</th><th> </th><th>R</th><th>G</th><th>B</th></tr>\r
197 \r
198 <tr><td>XD_BLACK</td><td bgcolor="#000000"></td><td>00</td><td>00</td><td>00</td></tr>\r
199 <tr><td>XD_GRAY_10</td><td bgcolor="#191919"></td><td>19</td><td>19</td><td>19</td></tr>\r
200 <tr><td>XD_GRAY_20</td><td bgcolor="#333333"></td><td>33</td><td>33</td><td>33</td></tr>\r
201 <tr><td>XD_GRAY_30</td><td bgcolor="#4C4C4C"></td><td>4C</td><td>4C</td><td>4C</td></tr>\r
202 <tr><td>XD_GRAY_40</td><td bgcolor="#656565"></td><td>65</td><td>65</td><td>65</td></tr>\r
203 <tr><td>XD_GRAY_50</td><td bgcolor="#7F7F7F"></td><td>7F</td><td>7F</td><td>7F</td></tr>\r
204 <tr><td>XD_GRAY_60</td><td bgcolor="#989898"></td><td>98</td><td>98</td><td>98</td></tr>\r
205 <tr><td>XD_GRAY_70</td><td bgcolor="#B1B1B1"></td><td>B1</td><td>B1</td><td>B1</td></tr>\r
206 <tr><td>XD_GRAY_80</td><td bgcolor="#CACACA"></td><td>CA</td><td>CA</td><td>CA</td></tr>\r
207 <tr><td>XD_GRAY_90</td><td bgcolor="#E3E3E3"></td><td>E3</td><td>E3</td><td>E3</td></tr>\r
208 <tr><td>XD_WHITE</td><td bgcolor="#FFFFFF"></td><td>FF</td><td>FF</td><td>FF</td></tr>\r
209 \r
210 <tr><td>XD_LED_BG</td><td bgcolor="#1B1B1B"></td> <td>1B</td><td>1B</td><td>1B</td></tr>\r
211 <tr><td>XD_LED_UNLIT_1</td><td bgcolor="#004840"></td><td>00</td><td>48</td><td>40</td></tr>\r
212 <tr><td>XD_LED_UNLIT_2</td><td bgcolor="#007C70"></td><td>00</td><td>7C</td><td>70</td></tr>\r
213 <tr><td>XD_LED_LIT_1</td><td bgcolor="#188880"></td> <td>18</td><td>88</td><td>80</td></tr>\r
214 <tr><td>XD_LED_LIT_2</td><td bgcolor="#20B0A8"></td> <td>20</td><td>B0</td><td>A8</td></tr>\r
215 <tr><td>XD_LED_GLOW</td><td bgcolor="#00E800"></td> <td>00</td><td>E8</td><td>00</td></tr>\r
216 \r
217 </table>\r