contiki/ctk/ctk-draw.h

/**
 * \file
 * CTK screen drawing module interface, ctk-draw.
 * \author Adam Dunkels <adam@dunkels.com>
 *
 * This file contains the interface for the ctk-draw module.The
 * ctk-draw module takes care of the actual screen drawing for CTK by
 * implementing a handful of functions that are called by CTK.
 *
 * The purpose of the ctk-arch and the ctk-draw 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.
 *
 * 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.
 *
 * 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:
 * \code
   ctk_draw_window(window, focus, clipy1, clipy2) {
      draw_window_borders(window, focus, clipy1, clipy2);
      foreach(widget, window->inactive) {
         draw_widget(widget, focus, clipy1, clipy2);
      }
      foreach(widget, window->active) {
         if(widget == window->focused) {
	    draw_widget(widget, focus | CTK_FOCUS_WIDGET,
	                    clipy1, clipy2);
	 } else {
	    draw_widget(widget, focus, clipy1, clipy2);
	 }
      }
   }
   
   \endcode
   
 * Where draw_window_borders() draws the window borders (also between
 * clipy1 and clipy2). The draw_widget() function used may the same
 * function as ctk_draw_widget() explained later. 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.
 */

/*
 * Copyright (c) 2002-2003, Adam Dunkels.
 * All rights reserved. 
 *
 * Redistribution and use in source and binary forms, with or without 
 * modification, are permitted provided that the following conditions 
 * are met: 
 * 1. Redistributions of source code must retain the above copyright 
 *    notice, this list of conditions and the following disclaimer. 
 * 2. Redistributions in binary form must reproduce the above
 *    copyright notice, this list of conditions and the following
 *    disclaimer in the documentation and/or other materials provided
 *    with the distribution. 
 * 3. The name of the author may not be used to endorse or promote
 *    products derived from this software without specific prior
 *    written permission.  
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
 * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.  
 *
 * This file is part of the Contiki desktop OS.
 *
 * $Id: ctk-draw.h,v 1.3 2003/09/01 22:23:26 adamdunkels Exp $
 *
 */

#ifndef __CTK_DRAW_H__
#define __CTK_DRAW_H__

#include "ctk.h"

#include "ctk-arch.h"

/**
 * 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.
 */
void ctk_draw_init(void);

/**
 * 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.
 *
 * \param clipy1 The lower y coordinate of the clip region.
 * \param clipy2 The upper y coordinate of the clip region. 
 */
void ctk_draw_clear(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.
 *
 * \param window The window for which the background should be drawn.
 *
 * \param focus The focus of the window, either CTK_FOCUS_NONE for a
 * background window, or CTK_FOCUS_WINDOW for the foreground window.
 * 
 * \param clipy1 The lower y coordinate of the clip region.
 * \param clipy2 The upper y coordinate of the clip region. 
*/
void ctk_draw_clear_window(struct ctk_window *window,
			   unsigned char focus,
			   unsigned char clipy1,
			   unsigned char clipy2);
/**
 * 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.
 *
 * \param window The window which is to be drawn.
 *
 * \param focus Specifies 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.
 *
 * \param clipy1 Specifies the first lines on screen that actually
 * should be drawn, in screen coordinates (line 1 is the first line
 * below the menus).
 *
 * \param clipy2 Specifies the last + 1 line on screen that should be
 * drawn, in screen coordinates (line 1 is the first line below the
 * menus)
 *
 */
void ctk_draw_window(struct ctk_window *window,
		     unsigned char focus,
		     unsigned char clipy1,
		     unsigned char clipy2);


/**
 * 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.
 *
 * \param dialog The dialog that is to be drawn.
 */
void ctk_draw_dialog(struct ctk_window *dialog);

/**
 * 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:
 \code
   #define CTK_FOCUS_NONE     0
   #define CTK_FOCUS_WIDGET   1
   #define CTK_FOCUS_WINDOW   2
   #define CTK_FOCUS_DIALOG   4
 \endcode

 * This gives the following table:
 \code
   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)
 \endcode 


 * \param w The widget to be drawn.
 * \param focus The focus of the widget.
 * \param clipy1 The lower y coordinate of the clip region.
 * \param clipy2 The upper y coordinate of the clip region. 
 */

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

void ctk_draw_menus(struct ctk_menus *menus);



/* Returns width and height of screen. */
unsigned char ctk_draw_width(void);
unsigned char ctk_draw_height(void);


#endif /* __CTK_DRAW_H__ */