Contiki 2.6

CTK device driver functions

The CTK device driver functions are divided into two modules, the ctk-draw module and the ctk-arch module. More...

Data Structures

struct  ctk_widget
 The generic CTK widget structure that contains all other widget structures. More...
struct  ctk_window
 Representation of a CTK window. More...
struct  ctk_menuitem
 Representation of an individual menu item. More...
struct  ctk_menu
 Representation of an individual menu. More...
struct  ctk_menus
 Representation of the menu bar. More...

Defines

#define CTK_WIDGET_SEPARATOR   1
 Widget number: The CTK separator widget.
#define CTK_WIDGET_LABEL   2
 Widget number: The CTK label widget.
#define CTK_WIDGET_BUTTON   3
 Widget number: The CTK button widget.
#define CTK_WIDGET_HYPERLINK   4
 Widget number: The CTK hyperlink widget.
#define CTK_WIDGET_TEXTENTRY   5
 Widget number: The CTK textentry widget.
#define CTK_WIDGET_BITMAP   6
 Widget number: The CTK bitmap widget.
#define CTK_WIDGET_ICON   7
 Widget number: The CTK icon widget.
#define CTK_FOCUS_NONE   0
 Widget focus flag: no focus.
#define CTK_FOCUS_WIDGET   1
 Widget focus flag: widget has focus.
#define CTK_FOCUS_WINDOW   2
 Widget focus flag: widget's window is the foremost one.
#define CTK_FOCUS_DIALOG   4
 Widget focus flag: widget is in a dialog.
#define ctk_arch_getkey()   getkey_arch()
 Get a keypress from the keyboard input queue.
#define ctk_arch_keyavail()   keyavail_arch()
 Check if there is a keypress in the keyboard input queue.

Typedefs

typedef char ctk_arch_key_t
 The keyboard character type of the system.

Functions

void ctk_draw_init (void)
 The initialization function.
void ctk_draw_clear (unsigned char clipy1, unsigned char clipy2)
 Clear the screen between the clip bounds.
void ctk_draw_clear_window (struct ctk_window *window, unsigned char focus, unsigned char clipy1, unsigned char clipy2)
 Draw the window background.
void ctk_draw_window (struct ctk_window *window, unsigned char focus, unsigned char clipy1, unsigned char clipy2, unsigned char draw_borders)
 Draw a window onto the screen.
void ctk_draw_dialog (struct ctk_window *dialog)
 Draw a dialog onto the screen.
void ctk_draw_widget (struct ctk_widget *w, unsigned char focus, unsigned char clipy1, unsigned char clipy2)
 Draw a widget on a window.
void ctk_draw_menus (struct ctk_menus *menus)
 Draw the menus on the virtual VNC desktop.
CCIF unsigned char ctk_draw_width (void)
 Obtain the height of the VNC desktop.
CCIF unsigned char ctk_draw_height (void)
 Obtain the height of the VNC desktop.

Detailed Description

The CTK device driver functions are divided into two modules, the ctk-draw module and the ctk-arch module.

The purpose of the ctk-arch and the ctk-draw modules is to act as an interface between the CTK and the actual hardware of the system on which Contiki is run. The ctk-arch takes care of the keyboard input from the user, and the ctk-draw is responsible for drawing the CTK desktop, windows and user interface widgets onto the actual screen.

More information about the ctk-draw and the ctk-arch modules can be found in the sections The ctk-draw module and The ctk-arch module.

The ctk-draw module

In order to work efficiently even on limited systems, CTK uses a simple coordinate system, where the screen is addressed using character coordinates instead of pixel coordinates.

This makes it trivial to implement the coordinate system on a text-based screen, and significantly reduces complexity for pixel based screen systems.

The top left of the screen is (0,0) with x and y coordinates growing downwards and to the right.

It is the responsibility of the ctk-draw module to keep track of the screen size and must implement the two functions ctk_draw_width() and ctk_draw_height(), which are used by the CTK for querying the screen size. The functions must return the width and the height of the ctk-draw screen in character coordinates.

The ctk-draw module is responsible for drawing CTK windows onto the screen through the function ctk_draw_window().. A pseudo-code implementation of this function might look like this:

   ctk_draw_window(window, focus, clipy1, clipy2, draw_borders) {
      if(draw_borders) {
         draw_window_borders(window, focus, clipy1, clipy2);
      }
      foreach(widget, window->inactive) {
         ctk_draw_widget(widget, focus, clipy1, clipy2);
      }
      foreach(widget, window->active) {
         if(widget == window->focused) {
            ctk_draw_widget(widget, focus | CTK_FOCUS_WIDGET,
                            clipy1, clipy2);
         } else {
            ctk_draw_widget(widget, focus, clipy1, clipy2);
         }
      }
   }

Where draw_window_borders() draws the window borders (also between clipy1 and clipy2). The ctk_draw_widget() function is explained below. Notice how the clipy1 and clipy2 parameters are passed to all other functions; every function needs to know the boundaries within which they are allowed to draw.

In order to aid in implementing a ctk-draw module, a text-based ctk-draw called ctk-conio has already been implemented. It conforms to the Borland conio C library, and a skeleton implementation of said library exists in lib/libconio.c. If a more machine specific ctk-draw module is to be implemented, the instructions in this file should be followed.

The ctk-arch module

The character used for the Return/Enter key.

#define CH_ENTER '
'

The ctk-arch module deals with keyboard input from the underlying target system on which Contiki is running. The ctk-arch manages a keyboard input queue that is queried using the two functions ctk_arch_keyavail() and ctk_arch_getkey().


Define Documentation

ctk_arch_key_t ctk_arch_getkey (   void)    getkey_arch()

Get a keypress from the keyboard input queue.

This function will remove the first keypress in the keyboard input queue and return it. If the keyboard queue is empty, the return value is undefined. This function is intended to be used only after the ctk_arch_keyavail() function has returned non-zero.

Returns:
The first keypress from the keyboard input queue.

Definition at line 49 of file getkey.h.

unsigned char ctk_arch_keyavail (   void)    keyavail_arch()

Check if there is a keypress in the keyboard input queue.

Returns:
Zero if the keyboard input queue is empty, non-zero otherwise.

Definition at line 50 of file getkey.h.

#define CTK_FOCUS_DIALOG   4

Widget focus flag: widget is in a dialog.

Definition at line 985 of file ctk.h.

Referenced by ctk_draw_dialog().

#define CTK_FOCUS_NONE   0

Widget focus flag: no focus.

Definition at line 979 of file ctk.h.

#define CTK_FOCUS_WIDGET   1

Widget focus flag: widget has focus.

Definition at line 981 of file ctk.h.

Referenced by ctk_draw_widget().

#define CTK_FOCUS_WINDOW   2

Widget focus flag: widget's window is the foremost one.

Definition at line 983 of file ctk.h.

Referenced by ctk_draw_window(), and ctk_window_redraw().

#define CTK_WIDGET_BITMAP   6

Widget number: The CTK bitmap widget.

Definition at line 75 of file ctk.h.

#define CTK_WIDGET_BUTTON   3

Widget number: The CTK button widget.

Definition at line 69 of file ctk.h.

#define CTK_WIDGET_HYPERLINK   4

Widget number: The CTK hyperlink widget.

Definition at line 71 of file ctk.h.

#define CTK_WIDGET_ICON   7

Widget number: The CTK icon widget.

Definition at line 77 of file ctk.h.

Referenced by ctk_draw_widget().

#define CTK_WIDGET_LABEL   2

Widget number: The CTK label widget.

Definition at line 67 of file ctk.h.

Referenced by ctk_widget_add().

#define CTK_WIDGET_SEPARATOR   1

Widget number: The CTK separator widget.

Definition at line 65 of file ctk.h.

Referenced by ctk_widget_add().

#define CTK_WIDGET_TEXTENTRY   5

Widget number: The CTK textentry widget.

Definition at line 73 of file ctk.h.


Typedef Documentation

typedef char ctk_arch_key_t

The keyboard character type of the system.

The ctk_arch_key_t is usually typedef'd to the char type, but some systems (such as VNC) have a 16-bit key type.

Definition at line 41 of file ctk-conio.h.


Function Documentation

void ctk_draw_clear ( unsigned char  y1,
unsigned char  y2 
)

Clear the screen between the clip bounds.

This function should clear the screen between the y coordinates "clipy1" and "clipy2", including the line at y coordinate "clipy1", but not the line at y coordinate "clipy2".

Note:
This function may be used to draw a background image (wallpaper) on the desktop; it does not necessarily "clear" the screen.
Parameters:
clipy1The lower y coordinate of the clip region.
clipy2The upper y coordinate of the clip region.

Clear the screen between the clip bounds.

Called by the CTK module.

Parameters:
y1The lower y coordinate bound.
y2The upped y coordinate bound.

Definition at line 442 of file ctk-conio.c.

Referenced by ctk_draw_init().

void ctk_draw_clear_window ( struct ctk_window window,
unsigned char  focus,
unsigned char  clipy1,
unsigned char  clipy2 
)

Draw the window background.

This function will be called by the CTK before a window will be completely redrawn.The function is supposed to draw the window background, excluding window borders as these should be drawn by the function that actually draws the window, between "clipy1" and "clipy2".

Note:
This function does not necessarily have to clear the window - it can be used for drawing a background pattern in the window as well.
Parameters:
windowThe window for which the background should be drawn.
focusThe focus of the window, either CTK_FOCUS_NONE for a background window, or CTK_FOCUS_WINDOW for the foreground window.
clipy1The lower y coordinate of the clip region.
clipy2The upper y coordinate of the clip region.

Draw the window background.

Called by the CTK module.

Parameters:
windowThe window to be cleared.
focusThe focus of the window.
clipy1The lower y coordinate bound.
clipy2The upper y coordinate bound.

Definition at line 266 of file ctk-conio.c.

References ctk_window::h, and ctk_window::w.

Referenced by ctk_draw_dialog().

void ctk_draw_dialog ( struct ctk_window dialog)

Draw a dialog onto the screen.

In CTK, a dialog is similar to a window, with the only exception being that they are drawn in a different style. Also, since dialogs always are drawn on top of everything else, they do not need to be drawn within any special boundaries.

Note:
This function can usually be implemented so that it uses the same widget drawing code as the ctk_draw_window() function.
Parameters:
dialogThe dialog that is to be drawn.

Draw a dialog onto the screen.

Called by the CTK module.

Parameters:
dialogThe dialog to be drawn.

Definition at line 754 of file ctk-vncserver.c.

References ctk_draw_clear_window(), CTK_FOCUS_DIALOG, ctk_window::h, ctk_window::w, ctk_widget::x, and ctk_widget::y.

Referenced by ctk_window_redraw().

CCIF unsigned char ctk_draw_height ( void  )

Obtain the height of the VNC desktop.

Called by the CTK module.

Returns:
The height of the VNC desktop, in characters.

Definition at line 521 of file ctk-conio.c.

void ctk_draw_init ( void  )

The initialization function.

This function is supposed to get the screen ready for drawing, and may be called at more than one time during the operation of the system.

The initialization function.

Called by the CTK module.

Definition at line 75 of file ctk-conio.c.

References ctk_draw_clear().

void ctk_draw_menus ( struct ctk_menus menus)

Draw the menus on the virtual VNC desktop.

Called by the CTK module.

Parameters:
menusThe CTK menubar.

Definition at line 884 of file ctk-vncserver.c.

References ctk_menus::desktopmenu, ctk_menus::menus, ctk_menu::next, NULL, ctk_menus::open, and ctk_menu::title.

void ctk_draw_widget ( struct ctk_widget w,
unsigned char  focus,
unsigned char  clipy1,
unsigned char  clipy2 
)

Draw a widget on a window.

This function is used for drawing a CTK widgets onto the screem is likely to be the most complex function in the ctk-draw module. Still, it is straightforward to implement as it can be written in an incremental fashion, starting with a single widget type and adding more widget types, one at a time.

The ctk-draw module may exploit how the CTK focus constants are defined in order to use a look-up table for the colors. The CTK focus constants are defined in the file ctk/ctk.h as follows:

   #define CTK_FOCUS_NONE     0
   #define CTK_FOCUS_WIDGET   1
   #define CTK_FOCUS_WINDOW   2
   #define CTK_FOCUS_DIALOG   4

This gives the following table:

   0: CTK_FOCUS_NONE      (Background window, non-focused widget)
   1: CTK_FOCUS_WIDGET    (Background window, focused widget)
   2: CTK_FOCUS_WINDOW    (Foreground window, non-focused widget)
   3: CTK_FOCUS_WINDOW | CTK_FOCUS_WIDGET
                          (Foreground window, focused widget)
   4: CTK_FOCUS_DIALOG    (Dialog, non-focused widget)
   5: CTK_FOCUS_DIALOG | CTK_FOCUS_WIDGET
                          (Dialog, focused widget)
Parameters:
wThe widget to be drawn.
focusThe focus of the widget.
clipy1The lower y coordinate of the clip region.
clipy2The upper y coordinate of the clip region.

Draw a widget on a window.

Called by the CTK module.

Parameters:
wThe widget to be drawn.
focusThe focus of the widget.
clipy1The lower y coordinate bound.
clipy2The upper y coordinate bound.

Definition at line 240 of file ctk-conio.c.

References CTK_FOCUS_WIDGET, CTK_WIDGET_ICON, ctk_window::focused, ctk_widget::h, ctk_window::h, ctk_widget::type, ctk_widget::w, ctk_window::w, ctk_widget::window, ctk_widget::x, and ctk_widget::y.

CCIF unsigned char ctk_draw_width ( void  )

Obtain the height of the VNC desktop.

Called by the CTK module.

Returns:
The height of the VNC desktop, in characters.

Definition at line 527 of file ctk-conio.c.

void ctk_draw_window ( struct ctk_window window,
unsigned char  focus,
unsigned char  clipy1,
unsigned char  clipy2,
unsigned char  draw_borders 
)

Draw a window onto the screen.

This function is called by the CTK when a window should be drawn on the screen. The ctk-draw layer is free to choose how the window will appear on screen; with or without window borders and the style of the borders, with or without transparent window background and how the background shall look, etc.

Parameters:
windowThe window which is to be drawn.
focusSpecifies if the window should be drawn in foreground or background colors and can be either CTK_FOCUS_NONE or CTK_FOCUS_WINDOW. Windows with a focus of CTK_FOCUS_WINDOW is usually drawn in a brighter color than those with CTK_FOCUS_NONE.
clipy1Specifies the first lines on screen that actually should be drawn, in screen coordinates (line 1 is the first line below the menus).
clipy2Specifies the last + 1 line on screen that should be drawn, in screen coordinates (line 1 is the first line below the menus)

Draw a window onto the screen.

Called by the CTK module.

Parameters:
windowThe window to be drawn.
focusThe focus of the window.
clipy1The lower y coordinate bound.
clipy2The upper y coordinate bound.
draw_bordersThe flag for border drawing.

Definition at line 328 of file ctk-conio.c.

References CTK_FOCUS_WINDOW, ctk_window::h, ctk_widget::h, ctk_window::titlelen, ctk_window::w, ctk_widget::x, and ctk_widget::y.

Referenced by ctk_window_redraw().