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

Razor.doxy.mainpage

Go to the documentation of this file.
00001 // $Id$
00002 /**
00003 @mainpage Razor! Engine Developer's Guide
00004  
00005 @section contents Contents
00006 Section @ref razor_introduction_page contains an overview over the Razor! framework's features
00007 <p>
00008 Section @ref framework_introduction_page explains the nature of a framework
00009 <p>
00010 Section @ref customizing_razor_page explains how to develop an application with Razor!
00011 */
00012 
00013 /**
00014 @page razor_introduction_page The Razor! Framework
00015 @subsection overview Introduction to the Razor! framework's features
00016 Razor! is a highly modular, easy to use, embeddable presentation engine for Palm Powered(tm) devices. 
00017 It makes it easier for developers to create multimedia software, such as animations and games.
00018 The engine is not a ready-to-use executable. Instead it comes as a bundle of C++ source files which need to
00019 be customized, compiled and linked with your own code.
00020 <p>
00021 Its main features include
00022 <ul>
00023 <li><em>Timing + Flow control</em> - Razor! ensures the correct order of all actions, and their precise timing.</li>
00024 <li><em>%Canvas management</em> - Razor! manages the drawing area (aka %Canvas). It provides double buffering with optimized copying.</li>
00025 <li><em>%Sprite engine</em> - Razor! can draw sprites (small bitmaps with transparent parts). It manages their position, shown/hidden state, etc.</li>
00026 <li><em>Sound engine</em> - Razor! can play music (faking three voices), and sound FX.</li>
00027 <li><em>Input management</em> - Razor! can poll the hard keys, and direct other events to your app.</li>
00028 </ul>
00029 Razor! is written in C++ and is delivered as a so-called <em>hybrid framework</em>.
00030 */
00031 
00032 /**
00033 @page framework_introduction_page The nature of a Framework
00034 @subsection framework Framework vs. Class Library
00035 It is important to understand the nature of a framework, especially in comparison to a class library.
00036 Frameworks operate by the &quot;Hollywood principle&quot; (don't call us, we'll call you). That means,
00037 the framework controls the entire flow of your application's execution, calling your code in a few well-defined
00038 places. When you are using a class library, it is just the other way around: You control the flow, and make
00039 calls into the library.
00040 <br>
00041 A framework is harder to design than a class library, but provided that your application fits the domain of
00042 the framework, it can save you a lot of work, and provide results of superior quality, because you are not
00043 only using proven code, but also proven patterns for application design.
00044 <br>
00045 In reality, you will rarely find a pure framework. Most frameworks are also accompanied by a class library. These
00046 are called <em>hybrid frameworks</em>.
00047 @subsection hotspots Hotspots
00048 The places in your code, which are invoked by the framework, are called <em>hotspots</em>. These are the places where
00049 you are given the chance to customize the behavior of the resulting application. The control flow between the invocations
00050 to your code is defined entirely by the framework, and cannot be modified by you.
00051 */
00052 
00053 /**
00054 @page customizing_razor_page Application development with the Razor! framework
00055 @subsection hollywood The Hollywood principle applies
00056 As has been explained in section @ref framework_introduction_page, the behavior of an application which is based on a 
00057 framework is defined by the code which you provide to the framework for invocation during program execution.
00058 This fully applies to the Razor! framework. The entire main application, including the startup code, the event loop, all the
00059 decisions about control flow, are provided by the Razor! framework. The framework will make calls into code which you will
00060 have to provide. You will have to present your code to the framework as a class which inherits from the ActionEngine
00061 class that is defined by the framework. ActionEngine defines all the hotspots that will be invoked by the framework.
00062 You are of course free to split up the functionality of your application into as many classes as you like, but you
00063 will always have to provide an ActionEngine as the main entry point into your code.
00064 @subsection steps Required steps
00065 In order to develop a new application with Razor!, you will need to
00066 <ul>
00067 <li>Make a copy of the Razor! source code, and of the project file.
00068 <li>Include your source files into the project file.
00069 <li>Create a specialization of ActionEngine (using inheritance)
00070 <li>Modifiy the file &quot;ActionEngineFactory.h&quot; in order to tell Razor! the name of your new class. 
00071 <li>Modify the file &quot;Customization.h&quot; (Make sure you are at least providing a proper Creator ID).
00072 </ul>
00073 @subsection samples Sample code
00074 Look at the class DemoActionEngine for a working example of an ActionEngine.
00075 */

Razor! Engine Developer's Guide. Copyright © by Tilo Christ. All Rights Reserved. Last updated: 17 Dec 2000