Contiki 2.6

ctk-draw.h

Go to the documentation of this file.
00001 /**
00002  * \addtogroup ctk
00003  * @{
00004  */
00005 
00006 /**
00007  * \file
00008  * CTK screen drawing module interface, ctk-draw.
00009  * \author Adam Dunkels <adam@dunkels.com>
00010  *
00011  * This file contains the interface for the ctk-draw module.The
00012  * ctk-draw module takes care of the actual screen drawing for CTK by
00013  * implementing a handful of functions that are called by CTK.
00014  *
00015  */
00016 
00017 /*
00018  * Copyright (c) 2002-2003, Adam Dunkels.
00019  * All rights reserved. 
00020  *
00021  * Redistribution and use in source and binary forms, with or without 
00022  * modification, are permitted provided that the following conditions 
00023  * are met: 
00024  * 1. Redistributions of source code must retain the above copyright 
00025  *    notice, this list of conditions and the following disclaimer. 
00026  * 2. Redistributions in binary form must reproduce the above
00027  *    copyright notice, this list of conditions and the following
00028  *    disclaimer in the documentation and/or other materials provided
00029  *    with the distribution. 
00030  * 3. The name of the author may not be used to endorse or promote
00031  *    products derived from this software without specific prior
00032  *    written permission.  
00033  *
00034  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
00035  * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00036  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00037  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
00038  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00039  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
00040  * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00041  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
00042  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00043  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00044  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.  
00045  *
00046  * This file is part of the Contiki desktop OS.
00047  *
00048  * $Id: ctk-draw.h,v 1.2 2006/08/26 23:56:18 oliverschmidt Exp $
00049  *
00050  */
00051 
00052 #ifndef __CTK_DRAW_H__
00053 #define __CTK_DRAW_H__
00054 
00055 #include "ctk/ctk.h"
00056 #include "contiki-conf.h"
00057 
00058 /**
00059  * \defgroup ctkdraw CTK device driver functions
00060  * @{
00061  *
00062  * The CTK device driver functions are divided into two modules, the
00063  * ctk-draw module and the ctk-arch module. The purpose of the
00064  * ctk-arch and the ctk-draw modules is to act as an interface between
00065  * the CTK and the actual hardware of the system on which Contiki is
00066  * run. The ctk-arch takes care of the keyboard input from the user,
00067  * and the ctk-draw is responsible for drawing the CTK desktop,
00068  * windows and user interface widgets onto the actual screen.
00069  *
00070  * More information about the ctk-draw and the ctk-arch modules can be
00071  * found in the sections \ref ctk-draw and \ref ctk-arch.
00072  */
00073 
00074 /**
00075  * \page ctk-draw The ctk-draw module
00076  *
00077  * In order to work efficiently even on limited systems, CTK uses a
00078  * simple coordinate system, where the screen is addressed using
00079  * character coordinates instead of pixel coordinates. This makes it
00080  * trivial to implement the coordinate system on a text-based screen,
00081  * and significantly reduces complexity for pixel based screen
00082  * systems.
00083  *
00084  * The top left of the screen is (0,0) with x and y coordinates
00085  * growing downwards and to the right.
00086  *
00087  * It is the responsibility of the ctk-draw module to keep track of
00088  * the screen size and must implement the two functions
00089  * ctk_draw_width() and ctk_draw_height(), which are used by the CTK
00090  * for querying the screen size. The functions must return the width
00091  * and the height of the ctk-draw screen in character coordinates.
00092  *
00093  * The ctk-draw module is responsible for drawing CTK windows onto the
00094  * screen through the function ctk_draw_window().. A pseudo-code
00095  * implementation of this  function might look like this:
00096  * \code
00097    ctk_draw_window(window, focus, clipy1, clipy2, draw_borders) {
00098       if(draw_borders) {
00099          draw_window_borders(window, focus, clipy1, clipy2);
00100       }
00101       foreach(widget, window->inactive) {
00102          ctk_draw_widget(widget, focus, clipy1, clipy2);
00103       }
00104       foreach(widget, window->active) {
00105          if(widget == window->focused) {
00106             ctk_draw_widget(widget, focus | CTK_FOCUS_WIDGET,
00107                             clipy1, clipy2);
00108          } else {
00109             ctk_draw_widget(widget, focus, clipy1, clipy2);
00110          }
00111       }
00112    }
00113    
00114    \endcode
00115  *
00116  * Where draw_window_borders() draws the window borders (also between
00117  * clipy1 and clipy2). The ctk_draw_widget() function is explained
00118  * below. Notice how the clipy1 and clipy2 parameters are passed to
00119  * all other functions; every function needs to know the boundaries
00120  * within which they are allowed to draw.
00121  *
00122  * In order to aid in implementing a ctk-draw module, a text-based
00123  * ctk-draw called ctk-conio has already been implemented. It conforms
00124  * to the Borland conio C library, and a skeleton implementation of
00125  * said library exists in lib/libconio.c. If a more machine specific
00126  * ctk-draw module is to be implemented, the instructions in this file
00127  * should be followed.
00128  * 
00129  */
00130 
00131 /**
00132  * The initialization function.
00133  *
00134  * This function is supposed to get the screen ready for drawing, and
00135  * may be called at more than one time during the operation of the
00136  * system.
00137  */
00138 void ctk_draw_init(void);
00139 
00140 /**
00141  * Clear the screen between the clip bounds.
00142  *
00143  * This function should clear the screen between the y coordinates
00144  * "clipy1" and "clipy2", including the line at y coordinate "clipy1",
00145  * but not the line at y coordinate "clipy2".
00146  *
00147  * \note This function may be used to draw a background image
00148  * (wallpaper) on the desktop; it does not necessarily "clear" the
00149  * screen.
00150  *
00151  * \param clipy1 The lower y coordinate of the clip region.
00152  * \param clipy2 The upper y coordinate of the clip region. 
00153  */
00154 void ctk_draw_clear(unsigned char clipy1, unsigned char clipy2);
00155 
00156 /**
00157  * Draw the window background.
00158  *
00159  * This function will be called by the CTK before a window will be
00160  * completely redrawn.The function is supposed to draw the window
00161  * background, excluding window borders as these should be drawn by
00162  * the function that actually draws the window, between "clipy1" and
00163  * "clipy2".
00164  *
00165  * \note This function does not necessarily have to clear the window -
00166  * it can be used for drawing a background pattern in the window as
00167  * well.
00168  *
00169  * \param window The window for which the background should be drawn.
00170  *
00171  * \param focus The focus of the window, either CTK_FOCUS_NONE for a
00172  * background window, or CTK_FOCUS_WINDOW for the foreground window.
00173  * 
00174  * \param clipy1 The lower y coordinate of the clip region.
00175  * \param clipy2 The upper y coordinate of the clip region. 
00176 */
00177 void ctk_draw_clear_window(struct ctk_window *window,
00178                            unsigned char focus,
00179                            unsigned char clipy1,
00180                            unsigned char clipy2);
00181 /**
00182  * Draw a window onto the screen.
00183  *
00184  * This function is called by the CTK when a window should be drawn on
00185  * the screen. The ctk-draw layer is free to choose how the window
00186  * will appear on screen; with or without window borders and the style
00187  * of the borders, with or without transparent window background and
00188  * how the background shall look, etc.
00189  *
00190  * \param window The window which is to be drawn.
00191  *
00192  * \param focus Specifies if the window should be drawn in foreground
00193  * or background colors and can be either CTK_FOCUS_NONE or
00194  * CTK_FOCUS_WINDOW. Windows with a focus of CTK_FOCUS_WINDOW is
00195  * usually drawn in a brighter color than those with CTK_FOCUS_NONE.
00196  *
00197  * \param clipy1 Specifies the first lines on screen that actually
00198  * should be drawn, in screen coordinates (line 1 is the first line
00199  * below the menus).
00200  *
00201  * \param clipy2 Specifies the last + 1 line on screen that should be
00202  * drawn, in screen coordinates (line 1 is the first line below the
00203  * menus)
00204  *
00205  */
00206 void ctk_draw_window(struct ctk_window *window,
00207                      unsigned char focus,
00208                      unsigned char clipy1,
00209                      unsigned char clipy2,
00210                      unsigned char draw_borders);
00211 
00212 
00213 /**
00214  * Draw a dialog onto the screen.
00215  *
00216  * In CTK, a dialog is similar to a window, with the only exception
00217  * being that they are drawn in a different style. Also, since dialogs
00218  * always are drawn on top of everything else, they do not need to be
00219  * drawn within any special boundaries.
00220  *
00221  * \note This function can usually be implemented so that it uses the
00222  * same widget drawing code as the ctk_draw_window() function.
00223  *
00224  * \param dialog The dialog that is to be drawn.
00225  */
00226 void ctk_draw_dialog(struct ctk_window *dialog);
00227 
00228 /**
00229  * Draw a widget on a window.
00230  *
00231  * This function is used for drawing a CTK widgets onto the screem is
00232  * likely to be the most complex function in the ctk-draw
00233  * module. Still, it is straightforward to implement as it can be
00234  * written in an incremental fashion, starting with a single widget
00235  * type and adding more widget types, one at a time.
00236 
00237  * The ctk-draw module may exploit how the CTK focus constants are
00238  * defined in order to use a look-up table for the colors. The CTK
00239  * focus constants are defined in the file ctk/ctk.h as follows:
00240  \code
00241    #define CTK_FOCUS_NONE     0
00242    #define CTK_FOCUS_WIDGET   1
00243    #define CTK_FOCUS_WINDOW   2
00244    #define CTK_FOCUS_DIALOG   4
00245  \endcode
00246 
00247  * This gives the following table:
00248  \code
00249    0: CTK_FOCUS_NONE      (Background window, non-focused widget)
00250    1: CTK_FOCUS_WIDGET    (Background window, focused widget)
00251    2: CTK_FOCUS_WINDOW    (Foreground window, non-focused widget)
00252    3: CTK_FOCUS_WINDOW | CTK_FOCUS_WIDGET
00253                           (Foreground window, focused widget)
00254    4: CTK_FOCUS_DIALOG    (Dialog, non-focused widget)
00255    5: CTK_FOCUS_DIALOG | CTK_FOCUS_WIDGET
00256                           (Dialog, focused widget)
00257  \endcode 
00258 
00259 
00260  * \param w The widget to be drawn.
00261  * \param focus The focus of the widget.
00262  * \param clipy1 The lower y coordinate of the clip region.
00263  * \param clipy2 The upper y coordinate of the clip region. 
00264  */
00265 
00266 void ctk_draw_widget(struct ctk_widget *w,
00267                      unsigned char focus,
00268                      unsigned char clipy1,
00269                      unsigned char clipy2);
00270 
00271 void ctk_draw_menus(struct ctk_menus *menus);
00272 
00273 
00274 
00275 /* Returns width and height of screen. */
00276 CCIF unsigned char ctk_draw_width(void);
00277 CCIF unsigned char ctk_draw_height(void);
00278 
00279 
00280 extern unsigned char ctk_draw_windowborder_width,
00281   ctk_draw_windowborder_height,
00282   ctk_draw_windowtitle_height;
00283 
00284 
00285 #endif /* __CTK_DRAW_H__ */
00286 
00287 
00288 /**
00289  * The keyboard character type of the system
00290  *
00291  * The ctk_arch_key_t is usually typedef'd to the char type, but some
00292  * systems (such as VNC) have a 16-bit key type.
00293  *
00294  * \var typedef char ctk_arch_key_t;
00295  */
00296 
00297 /**
00298  * Get a keypress from the keyboard input queue.
00299  *
00300  * This function will remove the first keypress in the keyboard input
00301  * queue and return it. If the keyboard queue is empty, the return
00302  * value is undefined. This function is intended to be used only after
00303  * the ctk_arch_keyavail() function has returned non-zero.
00304  *
00305  * \return The first keypress from the keyboard input queue.
00306  *
00307  * \fn ctk_arch_key_t ctk_arch_getkey(void);
00308  */
00309 
00310 /**
00311  * Check if there is a keypress in the keyboard input queue.
00312  *
00313  * \return Zero if the keyboard input queue is empty, non-zero
00314  * otherwise.
00315  *
00316  * \fn unsigned char ctk_arch_keyavail(void);
00317  */
00318 
00319 /**
00320  * The character used for the Return/Enter key.
00321  *
00322  * \define #define CH_ENTER '\n'
00323  */
00324 
00325 /**
00326  * \page ctk-arch The ctk-arch module
00327  *
00328  * The ctk-arch module deals with keyboard input from the underlying
00329  * target system on which Contiki is running. The ctk-arch manages a
00330  * keyboard input queue that is queried using the two functions
00331  * ctk_arch_keyavail() and ctk_arch_getkey().
00332  */
00333 
00334 /** @} */
00335 /** @} */