adamdunkels | 14324cb | 2003-03-28 12:21:52 +0000 | [diff] [blame] | 1 | This file describes the interface between the generic part of the |
| 2 | Contiki toolkit (CTK) and the architecture specific parts of CTK (the |
| 3 | so-called ctk-draw and ctk-arch layers). |
| 4 | |
| 5 | Author: Adam Dunkels <adam@dunkels.com> |
oliverschmidt | adf27db | 2005-03-15 15:51:17 +0000 | [diff] [blame] | 6 | Version: $Id: ctk.txt,v 1.3 2005/03/15 15:53:51 oliverschmidt Exp $ |
adamdunkels | 14324cb | 2003-03-28 12:21:52 +0000 | [diff] [blame] | 7 | |
| 8 | |
| 9 | * Introduction * |
| 10 | ---------------- |
| 11 | |
| 12 | The purpose of the ctk-arch and the ctk-draw is to act as an interface |
| 13 | between the CTK and the actual hardware of the system on which Contiki |
| 14 | is run. The ctk-arch takes care of the keyboard input from the user, |
| 15 | and the ctk-draw is responsible for drawing the CTK desktop, windows |
| 16 | and user interface widgets onto the actual screen. |
| 17 | |
| 18 | In order to aid in implementing a ctk-draw module, a text-based |
| 19 | ctk-draw called ctk-conio has already been implemented. It conforms to |
| 20 | the Borland conio C library, and a skeleton implementation of said |
| 21 | library exists in lib/libconio.c. If a more machine specific ctk-draw |
| 22 | module is to be implemented, the instructions in this file should be |
| 23 | followed. |
| 24 | |
| 25 | |
| 26 | * Keyboard input * |
| 27 | ------------------ |
| 28 | |
| 29 | Keyboard input is implemented using two functions: |
| 30 | |
| 31 | unsigned char ctk_arch_keyavail(void); |
| 32 | |
| 33 | and |
| 34 | |
| 35 | ctk_arch_key_t ctk_arch_getkey(void); |
| 36 | |
| 37 | The ctk_arch_keyavail() function should return zero if there are no |
| 38 | keys in the keyboard input queue, and non-zero if there are key presses |
| 39 | waiting in the input queue. The ctk_arch_getkey() function should |
| 40 | remove the first key press on the input queue, and return it to the |
| 41 | caller. The ctk_arch_key_t type should usually be typedef'ed to be |
| 42 | "char", but some architectures use other C types for representing |
| 43 | key presses (such as the 16-bit short type). |
| 44 | |
| 45 | The usual typedef looks like the following: |
| 46 | |
| 47 | typedef char ctk_arch_key_t; |
| 48 | |
| 49 | and should be put into a file named "ctk-arch.h", together with the C |
| 50 | #defines described below. |
| 51 | |
| 52 | Apart from the C functions that handles keyboard input, CTK requires a |
| 53 | few special characters such as the cursor keys and the enter |
| 54 | key. These are #defined as C macros in the "ctk-arch.h" file. The |
| 55 | following macros must be defined: |
| 56 | |
| 57 | CH_CURS_DOWN |
| 58 | CH_CURS_LEFT |
| 59 | CH_CURS_RIGHT |
| 60 | CH_CURS_UP |
| 61 | CH_DEL |
| 62 | CH_ENTER |
| 63 | CH_ESC |
| 64 | CH_KEY |
| 65 | |
| 66 | |
| 67 | * Screen drawing * |
| 68 | ------------------ |
| 69 | |
| 70 | The ctk-draw module takes care of the actual screen drawing for CTK by |
| 71 | implementing a handful of functions that are called by CTK. The |
| 72 | functions will be described in detail below, but are listed here for |
| 73 | convenience: |
| 74 | |
| 75 | void ctk_draw_init(void); |
| 76 | unsigned char ctk_draw_width(void); |
| 77 | unsigned char ctk_draw_height(void); |
| 78 | void ctk_draw_clear(unsigned char clipy1, unsigned char clipy2); |
| 79 | void ctk_draw_menus(struct ctk_menus *menus); |
adamdunkels | 9d3a0e5 | 2003-04-02 09:53:59 +0000 | [diff] [blame] | 80 | void ctk_draw_clear_window(struct ctk_window *window, |
| 81 | unsigned char focus, |
| 82 | unsigned char clipy1, unsigned char clipy2); |
adamdunkels | 14324cb | 2003-03-28 12:21:52 +0000 | [diff] [blame] | 83 | void ctk_draw_window(struct ctk_window *window, |
| 84 | unsigned char focus, |
| 85 | unsigned char clipy1, |
oliverschmidt | adf27db | 2005-03-15 15:51:17 +0000 | [diff] [blame] | 86 | unsigned char clipy2, |
| 87 | unsigned char draw_borders); |
adamdunkels | 14324cb | 2003-03-28 12:21:52 +0000 | [diff] [blame] | 88 | void ctk_draw_dialog(struct ctk_window *dialog); |
| 89 | void ctk_draw_widget(struct ctk_widget *w, |
| 90 | unsigned char focus, |
| 91 | unsigned char clipy1, |
| 92 | unsigned char clipy2); |
| 93 | |
| 94 | |
| 95 | * Initialization * |
| 96 | ------------------ |
| 97 | |
| 98 | The ctk-draw initializes itself by the function: |
| 99 | |
| 100 | void ctk_draw_init(void); |
| 101 | |
| 102 | This function is supposed to get the screen ready for drawing, and may |
| 103 | be called at more than one time during the operation of the system. |
| 104 | |
| 105 | |
| 106 | * Screen coordinates * |
| 107 | ---------------------- |
| 108 | |
| 109 | In order to work efficiently even on limited systems, CTK uses a |
| 110 | simple coordinate system, where the screen is addressed using |
| 111 | character coordinates instead of pixel coordinates. This makes it |
| 112 | trivial to implement the coordinate system on a text-based screen, |
| 113 | and significantly reduces complexity for pixel based screen systems. |
| 114 | |
| 115 | The top left of the screen is (0,0) with x and y coordinates growing |
| 116 | downwards and to the right. |
| 117 | |
| 118 | It is the responsibility of the ctk-draw module to keep track of the |
| 119 | screen size and must implement two functions which are used by the CTK |
| 120 | for querying the screen size: |
| 121 | |
| 122 | unsigned char ctk_draw_width(void); |
| 123 | unsigned char ctk_draw_height(void); |
| 124 | |
| 125 | The functions must return the width and the height of the ctk-draw |
| 126 | screen in character coordinates. |
| 127 | |
| 128 | |
| 129 | * Clearing the screen * |
| 130 | ----------------------- |
| 131 | |
| 132 | The ctk-draw is required to implement a function for clearing parts of |
| 133 | the screen. This function is called by the CTK before an area of the |
| 134 | screen is to be redrawn. The function prototype is: |
| 135 | |
| 136 | void ctk_draw_clear(unsigned char clipy1, unsigned char clipy2); |
| 137 | |
| 138 | The function should clear the screen between the y coordinates |
| 139 | "clipy1" and "clipy2", including the line at y coordinate "clipy1", |
| 140 | but not the line at y coordinate "clipy2". |
| 141 | |
| 142 | Note that this function may be used to draw a background image |
| 143 | (wallpaper) on the desktop; it does not necessarily "clear" the |
| 144 | screen. |
| 145 | |
| 146 | |
| 147 | * Drawing menus * |
| 148 | ----------------- |
| 149 | |
| 150 | Drawing the menus is the responsibility of the ctk-draw, and is done |
| 151 | from the function: |
| 152 | |
| 153 | void ctk_draw_menus(struct ctk_menus *menus); |
| 154 | |
| 155 | The ctk_draw_menus() function takes a pointer to a struct ctk_menus as |
| 156 | its argument and draws the menus at the top of the screen. The struct |
| 157 | ctk_menus is defined in the file ctk/ctk.h as: |
| 158 | |
| 159 | struct ctk_menus { |
| 160 | struct ctk_menu *menus; |
| 161 | struct ctk_menu *open; |
| 162 | struct ctk_menu *desktopmenu; |
| 163 | }; |
| 164 | |
| 165 | The "open" item points to the currently active menu, if any. If all |
| 166 | menus are closed, the "open" item is NULL. The "desktopmenu" item |
| 167 | points to the "Desktop" menu, and can be used for drawing the desktop |
| 168 | menu in a special way (such as drawing it at the rightmost |
| 169 | position). The "menus" item points to a linked list of all menus, |
| 170 | including the open menu and the desktop menu. |
| 171 | |
| 172 | The struct ctk_menu is also defined in ctk/ctk.h: |
| 173 | |
| 174 | struct ctk_menu { |
| 175 | struct ctk_menu *next; |
| 176 | char *title; |
| 177 | unsigned char titlelen; |
| 178 | unsigned char nitems; |
| 179 | unsigned char active; |
| 180 | struct ctk_menuitem items[CTK_CONF_MAXMENUITEMS]; |
| 181 | }; |
| 182 | |
| 183 | The "next" pointer points to the next menu, or is NULL if this is the |
| 184 | last menu, and should be used for stepping through the menus when |
| 185 | drawing them on screen. The "title" is the title of the menu, and the |
| 186 | length of the title is given in the "titlelen" field. The "nitems" |
| 187 | field specifies the total number of menu items in the menu and the |
| 188 | "active" item specifies the active item in the menu. The active item |
| 189 | should be drawn differently from the other items (it usually is drawn |
| 190 | inverted). Finally, the list of menu items is present in the "items" |
| 191 | list. This list consists of struct ctk_menuitem items; the struct |
| 192 | ctk_menuitem is defined in the file ctk/ctk.h as: |
| 193 | |
| 194 | struct ctk_menuitem { |
| 195 | char *title; |
| 196 | unsigned char titlelen; |
| 197 | }; |
| 198 | |
| 199 | Where the "title" field is the title of the menu item and the |
| 200 | "titlelen" the length of the title in characters. |
| 201 | |
| 202 | |
adamdunkels | 9d3a0e5 | 2003-04-02 09:53:59 +0000 | [diff] [blame] | 203 | * Drawing window background * |
| 204 | ----------------------------- |
| 205 | |
| 206 | The ctk-draw layer must implement a function for "clearing" the |
| 207 | window, i.e., draw the window background. This function will be called |
| 208 | by the CTK before a window will be completely redrawn, and looks like: |
| 209 | |
| 210 | void ctk_draw_clear_window(struct ctk_window *window, |
| 211 | unsigned char focus, |
| 212 | unsigned char clipy1, unsigned char clipy2); |
| 213 | |
| 214 | The function is supposed to draw the window background, excluding |
| 215 | window borders as these should be drawn by the function that actually |
| 216 | draws the window, between "clipy1" and "clipy2". |
| 217 | |
| 218 | |
adamdunkels | 14324cb | 2003-03-28 12:21:52 +0000 | [diff] [blame] | 219 | * Drawing windows * |
| 220 | ------------------- |
| 221 | |
| 222 | The CTK will call upon the ctk-draw layer to actually draw windows |
| 223 | onto the screen. The ctk-draw layer is free to choose how the window |
| 224 | will appear on screen; with or without window borders and the style of |
| 225 | the borders, with or without transparent window background and how the |
| 226 | background shall look, etc. |
| 227 | |
| 228 | The function called by the CTK for drawing a window is: |
| 229 | |
| 230 | void ctk_draw_window(struct ctk_window *window, |
| 231 | unsigned char focus, |
| 232 | unsigned char clipy1, |
oliverschmidt | adf27db | 2005-03-15 15:51:17 +0000 | [diff] [blame] | 233 | unsigned char clipy2, |
| 234 | unsigned char draw_borders); |
adamdunkels | 14324cb | 2003-03-28 12:21:52 +0000 | [diff] [blame] | 235 | |
| 236 | The "clipy1" and "clipy2" parameters specify the first and last + 1 |
| 237 | lines on screen that actually should be drawn (if clipy1 = 2 and |
| 238 | clipy2 = 3, only line 2 should be drawn). The clip parameters are |
| 239 | given in screen coordinates, so line 1 is the first line below the |
| 240 | menus. |
| 241 | |
| 242 | The focus parameter specifies if the window should be drawn in |
| 243 | foreground or background colors and can be either CTK_FOCUS_NONE or |
| 244 | CTK_FOCUS_WINDOW. Windows with a focus of CTK_FOCUS_WINDOW is usually |
| 245 | drawn in a brighter color than those with CTK_FOCUS_NONE. |
| 246 | |
oliverschmidt | adf27db | 2005-03-15 15:51:17 +0000 | [diff] [blame] | 247 | The draw_borders parameter specifies if the window frame should be drawn. |
| 248 | |
adamdunkels | 14324cb | 2003-03-28 12:21:52 +0000 | [diff] [blame] | 249 | Finally, the "window" parameter gives the actual window to be |
| 250 | drawn. This is specified as a struct ctk_window, which is defined in |
| 251 | the file ctk/ctk.h as: |
| 252 | |
| 253 | struct ctk_window { |
| 254 | struct ctk_window *next, *prev; |
| 255 | ek_id_t owner; |
| 256 | char *title; |
| 257 | unsigned char titlelen; |
| 258 | struct ctk_button closebutton; |
| 259 | struct ctk_button titlebutton; |
| 260 | |
| 261 | unsigned char x, y; |
| 262 | unsigned char w, h; |
| 263 | |
| 264 | struct ctk_widget *inactive; |
| 265 | struct ctk_widget *active; |
| 266 | struct ctk_widget *focused; |
| 267 | }; |
| 268 | |
| 269 | The first "next" and "prev" fields are pointers used by the CTK for |
| 270 | keeping the windows on a doubly linked list and are not used by the |
| 271 | ctk-draw. Likewise, the "owner" field is used by the CTK to keep track |
| 272 | of the process that created the window, and is not used by |
| 273 | ctk-draw. The "title" and "titlelen" fields are used by the CTK when |
| 274 | constructing the desktop menu, and should usually not be used by the |
| 275 | ctk-draw. |
| 276 | |
| 277 | The "closebutton" and "titlebutton" fields are the CTK buttons used in |
| 278 | the title bar. These should not be used directly by the ctk-draw |
| 279 | module, as they are already present in the "active" widgets field |
| 280 | described below. They may be used as a comparison to give special |
| 281 | treatment to these two widgets however (e.g., if the close button |
| 282 | should be drawn at the upper left corner instead of the default upper |
| 283 | right corner), but may otherwise be ignored by the ctk-draw module. |
| 284 | |
| 285 | The "x" and "y" fields specify the x and y coordinates of the top left |
| 286 | corner of the window and the "w" and "h" fields give the width and |
| 287 | height of the window (excluding any window borders). |
| 288 | |
| 289 | Finally, the "inactive" and "active" widget pointers points to linked |
| 290 | lists of CTK widgets. The "focused" pointer points either to one of |
| 291 | the widgets in the "active" list, or is NULL if no widget is |
| 292 | focused. How CTK widgets are drawn is explained below. |
| 293 | |
| 294 | A pseudo-code implementation of a ctk_draw_window() function might |
| 295 | look like this: |
| 296 | |
oliverschmidt | adf27db | 2005-03-15 15:51:17 +0000 | [diff] [blame] | 297 | ctk_draw_window(window, focus, clipy1, clipy2, draw_borders) { |
| 298 | if(draw_borders) { |
| 299 | draw_window_borders(window, focus, clipy1, clipy2); |
| 300 | } |
adamdunkels | 14324cb | 2003-03-28 12:21:52 +0000 | [diff] [blame] | 301 | foreach(widget, window->inactive) { |
| 302 | draw_widget(widget, focus, clipy1, clipy2); |
| 303 | } |
| 304 | foreach(widget, window->active) { |
| 305 | if(widget == window->focused) { |
| 306 | draw_widget(widget, focus | CTK_FOCUS_WIDGET, |
| 307 | clipy1, clipy2); |
| 308 | } else { |
| 309 | draw_widget(widget, focus, clipy1, clipy2); |
| 310 | } |
| 311 | } |
| 312 | } |
| 313 | |
adamdunkels | 9d3a0e5 | 2003-04-02 09:53:59 +0000 | [diff] [blame] | 314 | Where draw_window_borders() draws the window borders (also between |
| 315 | clipy1 and clipy2). The draw_widget() function used may the same |
| 316 | function as ctk_draw_widget() explained later. Notice how the clipy1 |
| 317 | and clipy2 parameters are passed to all other functions; every |
adamdunkels | 14324cb | 2003-03-28 12:21:52 +0000 | [diff] [blame] | 318 | function needs to know the boundaries within which they are allowed to |
| 319 | draw. |
| 320 | |
| 321 | |
| 322 | * Drawing dialogs * |
| 323 | ------------------- |
| 324 | |
| 325 | In CTK, a dialog is similar to a window, with the only exception being |
| 326 | that they are drawn in a different style. Also, since dialogs always |
| 327 | are drawn on top of everything else, they do not need to be drawn |
| 328 | within any special boundaries. |
| 329 | |
| 330 | The ctk-draw function that draws a dialog on screen is as follows: |
| 331 | |
| 332 | void ctk_draw_dialog(struct ctk_window *dialog); |
| 333 | |
| 334 | It can usually be implemented together with the ctk_draw_window() |
| 335 | function, which is explained above. |
| 336 | |
| 337 | |
| 338 | * Drawing widgets * |
| 339 | ------------------- |
| 340 | |
| 341 | The function that draws the CTK widgets is likely to be the most |
| 342 | complex function in the ctk-draw module. Still, it is straightforward |
| 343 | to implement as it can be written in an incremental fashion, starting |
| 344 | with a single widget type and adding more widget types, one at a time. |
| 345 | |
| 346 | The function for drawing widgets is: |
| 347 | |
| 348 | void ctk_draw_widget(struct ctk_widget *widget, |
| 349 | unsigned char focus, |
| 350 | unsigned char clipy1, |
| 351 | unsigned char clipy2); |
| 352 | |
| 353 | The "clipy1" and "clipy2" parameters specify the upper and lower |
| 354 | bounds for the widget. The "focus" parameter specifies how the widget |
| 355 | is focused and usually is used to decide in what colors the widget is |
| 356 | to be drawn. The focus is a logical "or" combination of |
| 357 | CTK_FOCUS_WIDGET and either CTK_FOCUS_WINDOW, CTK_FOCUS_DIALOG or |
| 358 | CTK_FOCUS_NONE. A non-focused widget in a background window will have |
| 359 | focus == CTK_FOCUS_NONE, a focused widget in a foreground window will |
| 360 | have focus == CTK_FOCUS_WIDGET | CTK_FOCUS_WINDOW, and so on. |
| 361 | |
| 362 | The ctk-draw module may exploit how the CTK focus constants are |
| 363 | defined in order to use a look-up table for the colors. The CTK focus |
| 364 | constants are defined in the file ctk/ctk.h as follows: |
| 365 | |
| 366 | #define CTK_FOCUS_NONE 0 |
| 367 | #define CTK_FOCUS_WIDGET 1 |
| 368 | #define CTK_FOCUS_WINDOW 2 |
| 369 | #define CTK_FOCUS_DIALOG 4 |
| 370 | |
| 371 | This gives the following table: |
| 372 | |
| 373 | 0: CTK_FOCUS_NONE (Background window, non-focused widget) |
| 374 | 1: CTK_FOCUS_WIDGET (Background window, focused widget) |
| 375 | 2: CTK_FOCUS_WINDOW (Foreground window, non-focused widget) |
| 376 | 3: CTK_FOCUS_WINDOW | CTK_FOCUS_WIDGET |
| 377 | (Foreground window, focused widget) |
| 378 | 4: CTK_FOCUS_DIALOG (Dialog, non-focused widget) |
| 379 | 5: CTK_FOCUS_DIALOG | CTK_FOCUS_WIDGET |
| 380 | (Dialog, focused widget) |
| 381 | |
| 382 | Finally, the "widget" parameter gives the actual widget that is to be |
| 383 | drawn. The struct ctk_widget is defined in ctk/ctk.h and looks like: |
| 384 | |
| 385 | struct ctk_widget { |
| 386 | struct ctk_widget *next; |
| 387 | struct ctk_window *window; |
| 388 | unsigned char x, y; |
| 389 | unsigned char type; |
| 390 | unsigned char w; |
| 391 | union { |
| 392 | struct ctk_widget_label label; |
| 393 | struct ctk_widget_button button; |
| 394 | struct ctk_widget_hyperlink hyperlink; |
| 395 | struct ctk_widget_textentry textentry; |
| 396 | struct ctk_widget_icon icon; |
| 397 | struct ctk_widget_bitmap bitmap; |
| 398 | } widget; |
| 399 | }; |
| 400 | |
| 401 | The "next" pointer points to the next widget in the linked list of |
| 402 | widgets and should be used by the ctk_draw_window() function when |
| 403 | stepping through the widgets. It should not be used by the |
| 404 | ctk_draw_widget() function, however. The "window" pointer points to |
| 405 | the window in which the widget is contained, and should be used to |
| 406 | obtain the coordinates for the window. |
| 407 | |
| 408 | The "x" and "y" fields are the x and y coordinates of the widget, |
| 409 | relative to the x and y coordinates of the window in which the widget |
| 410 | is contained (the "window" pointer). The "type" field specifies what |
| 411 | kind of widget this is, and the "w" field has the width of the widget. |
| 412 | |
| 413 | Finally, the "widget" union holds the actual widget structure. These |
| 414 | are described below. |
| 415 | |
| 416 | |
| 417 | * The separator widget * |
| 418 | ------------------------ |
| 419 | |
| 420 | The separator widget is the simplest of all widgets, and do not need |
| 421 | any more information than what already is present in the struct |
| 422 | ctk_widget structure: it has x and y coordinates and a width. |
| 423 | |
| 424 | |
| 425 | * The label widget * |
| 426 | -------------------- |
| 427 | |
| 428 | The label widget is defined by the struct ctk_widget_label structure |
| 429 | (accessible from the struct ctk_widget *widget as |
| 430 | widget->widget.label), which is found in ctk/ctk.h: |
| 431 | |
| 432 | struct ctk_widget_label { |
| 433 | char *text; |
| 434 | unsigned char h; |
| 435 | }; |
| 436 | |
| 437 | The "text" points to an array of text, and the "h" specifies the |
| 438 | height of the label. Each line of text in the "text" array is found at |
| 439 | "w" distance from each other (the "w" is found in the struct |
| 440 | ctk_widget). |
| 441 | |
| 442 | |
| 443 | * The button widget * |
| 444 | --------------------- |
| 445 | |
| 446 | The struct ctk_widget_button looks like: |
| 447 | |
| 448 | struct ctk_widget_button { |
| 449 | char *text; |
| 450 | }; |
| 451 | |
| 452 | Where the "text" is the text that is to be displayed on the |
| 453 | button. The CTK assumes that the button widget will have one character |
| 454 | of space to the left and right of it (this is usually where the button |
| 455 | borders are drawn). |
| 456 | |
| 457 | |
| 458 | * The hyperlink widget * |
| 459 | ------------------------ |
| 460 | |
| 461 | The hyperlink widget is defined by the struct ctk_widget_hyperlink |
| 462 | structure: |
| 463 | |
| 464 | struct ctk_widget_hyperlink { |
| 465 | char *text; |
| 466 | char *url; |
| 467 | }; |
| 468 | |
| 469 | The "text" pointer points to the text of the hyperlink, and the "url" |
| 470 | is the URL to which the hyperlink points. The ctk-draw usually will |
| 471 | not need to bother with the "url" field. The hyperlink widget usually |
| 472 | is drawn in a different color than the label widget, preferably |
| 473 | underlined. |
| 474 | |
| 475 | |
| 476 | * The text entry widget * |
| 477 | ------------------------- |
| 478 | |
| 479 | The text entry widget is a little more complicated to draw than the |
| 480 | other widgets because it has a number of state variables which |
| 481 | influence the way it should be drawn. The struct ctk_widget_textentry |
| 482 | looks like this: |
| 483 | |
| 484 | struct ctk_widget_textentry { |
| 485 | char *text; |
| 486 | unsigned char h; |
| 487 | unsigned char len; |
| 488 | unsigned char xpos, ypos; |
| 489 | unsigned char state; |
| 490 | }; |
| 491 | |
| 492 | Where "text" is the text which is to be edited, "h" is the height of |
| 493 | the text edit widget, "len" is the length of the line(s) that is being |
| 494 | edited (which may be different from the width "w" of the |
| 495 | widget). "xpos" and "ypos" is the position of the cursor in the text |
| 496 | edit widget and "state" is the state in which the widget is. The state |
| 497 | can be |
| 498 | |
| 499 | CTK_TEXTENTRY_NORMAL |
| 500 | |
| 501 | or |
| 502 | |
| 503 | CTK_TEXTENTRY_EDIT |
| 504 | |
| 505 | In the CTK_TEXTENTRY_EDIT state, the text is currenly being edited, |
| 506 | while in the CTK_TEXTENTRY_NORMAL, the text is not being edited. Text |
| 507 | entry widgets where the text is being edited should be drawn |
| 508 | differently than when in the normal state. |
| 509 | |
| 510 | |
| 511 | * The bitmap widget * |
| 512 | --------------------- |
| 513 | |
| 514 | The bitmap widget is different from the other CTK widgets because it |
| 515 | is architecture dependant; there is no standard bitmap format |
| 516 | specified for Contiki, but this is up to the architecture. (This means |
| 517 | that application programs that use the bitmap widget must be able to |
| 518 | draw in the architecture specific format as well.) |
| 519 | |
| 520 | The struct ctk_widget_bitmap looks like: |
| 521 | |
| 522 | struct ctk_widget_bitmap { |
| 523 | unsigned char *bitmap; |
| 524 | unsigned char h; |
| 525 | }; |
| 526 | |
| 527 | Where "h" is the height of the bitmap widget, and "bitmap" is a |
| 528 | generic pointer that points to an architecture specific |
| 529 | repressentation of the bitmap. |
| 530 | |
| 531 | * The icon widget * |
| 532 | ------------------- |
| 533 | |
| 534 | The icon widget is similar to the bitmap widget in that it uses an |
| 535 | architecture specific bitmap format for the repressentation of the |
| 536 | graphical icon. It also includes a text version of the icon. XXX: the |
| 537 | icon widget format is likely to change in the near future! |
| 538 | |
| 539 | The struct ctk_widget_icon is defined as: |
| 540 | |
| 541 | struct ctk_widget_icon { |
| 542 | char *title; |
| 543 | ek_id_t owner; |
| 544 | unsigned char *bitmap; |
| 545 | char *textmap; |
| 546 | }; |
| 547 | |
| 548 | The "title" field is the name of the icon, and should be drawn below |
| 549 | the icon picture. The "owner" is the process that created the icon, |
| 550 | and should normally be ignored by the ctk-draw. The "bitmap" is a |
| 551 | pointer to an architecture specific repressentation of the icon; the |
| 552 | same on-screen drawing function can be used for this bitmap as for the |
| 553 | bitmap widget. Finally, the "textmap" is a text based icon. |
| 554 | |
| 555 | Currently, icons are 24x24 pixels large (the text based versions are |
| 556 | 3x3 characters). |
| 557 | |