Main Page   Class Hierarchy   Compound List   File List   Compound Members   File Members

Canvas.h

Go to the documentation of this file.
00001 /*********************************************************************************
00002  *
00003  * Razor! Engine - A modular C++ presentation engine
00004  *
00005  * $Id: Canvas.h,v 1.5 2003/05/30 12:30:21 teacy Exp $
00006  *
00007  * Copyright (c) 2000-2003 Tilo Christ. All Rights Reserved.
00008  * 
00009  * Permission is hereby granted, free of charge, to any person obtaining a 
00010  * copy of this software and associated documentation files (the  "Software"), 
00011  * to deal in the Software without restriction, including without limitation 
00012  * the rights to use, copy, modify, merge, publish, distribute, sublicense, 
00013  * and/or sell copies of the Software, and to permit persons to whom the Software 
00014  * is furnished to do so, subject to the following conditions:
00015  *
00016  * The above copyright notice and this permission notice shall be included in all 
00017  * copies or substantial portions of the Software.
00018  *
00019  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, 
00020  * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR 
00021  * PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE 
00022  * FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 
00023  * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00024  *
00025  **********************************************************************************/
00026 
00027 /*
00028  TODO: Is _drawBitmap unneccessary?
00029  TODO: Should argument order be moved to allow defaults (index, numBitmaps)?
00030  TODO: How can text with transparent background be realized?
00031  TODO: Should drawText rather work with a 0x00-terminated string?
00032  TODO: Color params can be made constant
00033  */
00034 
00035 
00036 #ifndef CANVAS_H
00037 #define CANVAS_H
00038 
00039 #include <PalmOS.h>
00040 #include "RazorSections.h"
00041 
00042 #include "gfx/Geometry.h"
00043 #include "gfx/Color.h"
00044 
00045 
00046 namespace prvrazor
00047 {
00048     class Blitter;
00049 }
00050 
00051 using namespace prvrazor;
00052 
00053 
00054 class Canvas;
00055 
00056 
00057 class BitmapArray
00058 {
00059     public:
00060     virtual ~BitmapArray() SEC_RAZOR_INIT = 0;
00061     virtual void draw(const Canvas *canvas, UInt16 index, Coord x, Coord y) const = 0;
00062 
00063     Coord width;
00064     Coord height;
00065     UInt16 numBitmaps;  
00066 
00067     protected:
00068     BitmapArray(UInt16 numBitmaps) SEC_RAZOR_INIT;
00069 };
00070 
00071 
00072 
00073 class SaveBufferArray
00074 {
00075     public:
00076     virtual ~SaveBufferArray() SEC_RAZOR_INIT = 0;
00077     virtual void save(const Canvas *canvas, UInt16 index, Coord x, Coord y) const = 0;
00078     virtual void restore(const Canvas *canvas, UInt16 index) const = 0;
00079 
00080     Int16 width;
00081     Int16 height;
00082     UInt16 numBuffers;
00083 
00084     protected:
00085     SaveBufferArray(UInt16 numBuffers, Coord width, Coord height) SEC_RAZOR_INIT;
00086 };
00087 
00088 
00089 /**
00090  * Canvas represents a drawing area.
00091  * <br>
00092  * An instance of Canvas has properties, such as width and height, 
00093  * and a few basic drawing operations.
00094  * <br>
00095  * It can save/restore parts of itself.
00096  * <br>
00097  * It may provide access to its screen memory, to enable drawing
00098  * through direct memory manipulations.
00099  */
00100 class Canvas
00101 {
00102     public:
00103 
00104     enum CoordSystem {COORDS_STANDARD = 1, COORDS_NATIVE = 2};
00105 
00106 ///@name Construction / Destruction
00107 //@{
00108     /**
00109      * Construct a new Canvas.
00110      */
00111     Canvas(Coord width, Coord height, CoordSystem coordSystem) SEC_RAZOR_INIT;
00112 
00113     /**
00114      * Destroy the Canvas.
00115      */
00116     virtual ~Canvas() SEC_RAZOR_INIT;
00117 //@}
00118 
00119 ///@name Coordinate systems
00120 //@{
00121     virtual void setCoordSystem(CoordSystem coordSystem) SEC_RAZOR_INIT;
00122 //@}
00123 
00124 ///@name Draw operations
00125 //@{
00126     const BitmapArray *prepareTransparentBitmaps(UInt16 numBitmaps, DmResID bitmapID, DmResID maskID) const SEC_RAZOR_INIT;
00127     const BitmapArray *prepareTransparentBitmap(DmResID bitmapID, DmResID maskID) const SEC_RAZOR_INIT;
00128     const BitmapArray *prepareSolidBitmaps(UInt16 numBitmaps, DmResID bitmapID) const SEC_RAZOR_INIT;
00129     const BitmapArray *prepareSolidBitmap(DmResID bitmapID) const SEC_RAZOR_INIT;
00130 
00131     /**
00132      * Draw the indexth bitmap from an array of bitmaps.
00133      * 
00134      * @param index the index into the array of bitmaps. Must be 0..elements-1
00135      * @param bitmapArray the array of bitmaps. Must have at least index+1 elements
00136      * @param x the logical x coordinate
00137      * @param y the logical y coordinate
00138      */
00139     void drawBitmap(UInt16 index, const BitmapArray *bitmapArray, Coord x, Coord y) const SEC_RAZOR;
00140 
00141     /**
00142      * Draw the first bitmap (index=0) from an array of bitmaps.
00143      * 
00144      * @param bitmapArray the array of bitmaps. Must have at least 1 element
00145      * @param x the logical x coordinate
00146      * @param y the logical y coordinate
00147      */
00148     void drawBitmap(const BitmapArray *bitmapArray, Coord x, Coord y) const SEC_RAZOR;
00149 
00150     /**
00151      * Draw a text string.
00152      * 
00153      * @param textColor the color of the text
00154      * @param bgColor the color of the background
00155      * @param font the font (TODO: Which ones are supported on all devices)
00156      * @param chars the text
00157      * @param len the length of the text (TODO: Why is this signed int?)
00158      * @param x the logical x coordinate of the topleft corner of the first character
00159      * @param y the logical y coordinate of the topleft corner of the first character
00160      */
00161     void drawText(Color textColor, Color bgColor, FontID font, const Char *chars, Int16 len, Coord x, Coord y) const SEC_RAZOR;
00162 
00163     void fillRectangle(Color color, Coord topX, Coord topY, Coord bottomX, Coord bottomY) const SEC_RAZOR;
00164 
00165     void drawPolygon(const xy *e, int edgeCount, const Color color) const SEC_RAZOR;
00166 //@}
00167 
00168 
00169 ///@name Save/Restore Area operations
00170 //@{
00171     SaveBufferArray *prepareSaveBuffers(UInt16 numBuffers, Coord width, Coord height) const SEC_RAZOR_INIT;
00172     void saveBitmap(UInt16 index, SaveBufferArray *bufferArray, Coord x, Coord y) const SEC_RAZOR;
00173     void restoreBitmap(UInt16 index, SaveBufferArray *bufferArray) const SEC_RAZOR;
00174 //@}
00175 
00176 
00177 ///@name OS interaction
00178 //@{
00179     /**
00180      * Use this Canvas as the default canvas for OS drawing operations.
00181      */
00182     virtual void setOSCanvas() const = 0;
00183 
00184     /**
00185      * Make the underlying OS use the color as foreground color. Returns a special indicator for 1bpp devices.
00186      *
00187      * @return true = color is dark, false = color is light.
00188      */
00189     virtual Boolean setForegroundColor(const Color color) const = 0;
00190     
00191     /**
00192      * Make the underlying OS use the color as background color. Returns a special indicator for 1bpp devices.
00193      *
00194      * @return true = color is dark, false = color is light.
00195      */
00196     virtual Boolean setBackgroundColor(const Color color) const = 0;
00197 //@}
00198 
00199 
00200 
00201     Coord width;
00202     Coord height;
00203     Coord rows;
00204     Coord cols;
00205 
00206     Int8 shiftFactor;
00207     CoordSystem coordSystem;
00208         
00209 
00210     /**
00211      * The handle to the Canvas' window
00212      */
00213     WinHandle drawWindow;
00214 
00215     /**
00216      * The pointer to the Canvas' bitmap
00217      */
00218     BitmapType *_drawBitmap;
00219 
00220     /**
00221      * The pointer to the Canvas' bitmap bits
00222      */
00223     void *drawBits;
00224 
00225     /**
00226      * The number of bytes in a row of the Canvas
00227      */ 
00228     UInt16 rowBytes;
00229 
00230 
00231     protected:
00232     /**
00233      * Blitter that can be used to draw to the Canvas
00234      */
00235     Blitter *blitter;
00236 
00237 
00238     private:
00239     static int calcShiftFactor(UInt16 coordSystem);
00240 };
00241 
00242 
00243 #endif

Razor! Engine Developer's Guide. Copyright © by Tilo Christ. All Rights Reserved. Last updated: 31 May 2003