home *** CD-ROM | disk | FTP | other *** search
/ Stars of Shareware: Programmierung / SOURCE.mdf / programm / msdos / pascal / rehack / text / game.txt < prev    next >
Encoding:
Text File  |  1993-06-27  |  6.3 KB  |  177 lines
  1. File:            GAME.TXT
  2. Path:            ...\REHACK\TEXT\GAME.TXT
  3. Version:        0.01
  4. Author:            Pat Reilly
  5. CIS Id:            71333,2764
  6. Created On:        6/25/93
  7. Modified On:    6/27/93
  8. Description:    Documentation on classes in GAME.HPP
  9. Tabs:            4
  10.  
  11. Typedef VisMaker
  12. ================
  13.  
  14.     This typedef just makes referring to a "function which takes a Rect
  15. argument and returns a pointer to a Visible" easier to do. For a function
  16. pointer to be a VisMaker, it has to be in the form:
  17.     Visible* foo(Rect);
  18.  
  19. Class GameInit
  20. ==============
  21.  
  22.     The sole purpose in life of GameInit is to allow classes derived from
  23. Game to initialize some of the default members when Game::Game() ctor is
  24. called. See the description for the Game class for more information.
  25.  
  26. Methods
  27. -------
  28.  
  29.     GameInit(VisMaker A, VisMaker B, VisMaker C, VisMaker D, VisMaker E)
  30.         A, B, C, D and E are all of the VisMaker typedef; that is, they are
  31.         all pointers to functions which are passed a Rect and return a
  32.         pointer to a Visible object. All GameInit() does is to store these
  33.         function pointers in closeUpMaker, autoMapMaker, buttonsMaker,
  34.         characterMaker, and messageMaker. Game::Game() will use these
  35.         to build the appropriate sub-windows of Game.
  36.  
  37. Members
  38. -------
  39.  
  40.     closeUpMaker
  41.         VisMaker which makes the close-up object.
  42.  
  43.     autoMapMaker
  44.         VisMaker which makes the automap object.
  45.  
  46.     buttonsMaker
  47.         VisMaker which makes the buttons object.
  48.  
  49.     characterMaker
  50.         VisMaker which makes the character object.
  51.  
  52.     messageMaker
  53.         VisMaker which makes the message object.
  54.  
  55.  
  56. Class Game - derived from Window and virtually from GameInit
  57. ==========
  58.  
  59.     Game encapsulates the basic framework for the REHACK game. It inherits
  60. most of the functionality from Window, and has GameInit as a virtual base
  61. class.
  62.     Virtual base classes which have non-default constructors MUST be
  63. explicitly initialized by the most-derived class. This means that if you
  64. derive a new class from Game, it's ctor initialization list must explicitly
  65. call GameInit::GameInit(...). For example:
  66.  
  67.     class MyGame : public Game
  68.     {
  69.     public:
  70.         MyGame(const Rect& aBounds) :
  71.             Game(aBounds),
  72.             GameInit(fnA, fnB, fnC, fnD, fnE)
  73.         {}
  74.     };
  75.  
  76. GameInit's purpose is to store VisMaker function pointers which can be used
  77. by Game's constructor. We cannot use virtual functions for this because
  78. when Game's constructor is called, MyGame (above) hasn't been built yet; if
  79. we called a virtual function foo, Game::foo() would get called instead of
  80. MyGame::foo().
  81.     We work around that limitation by having the GameInit virtual base class.
  82. Because GameInit is a virtual base, and it has a non-default constructor,
  83. then MyGame (as shown) HAS to initialize GameInit explicitly; also, this
  84. initialization will occur BEFORE Game::Game()'s body is executed. So the
  85. five function pointers that we pass to GameInit in MyGame::MyGame() will be
  86. stored in the inherited GameInit members BEFORE Game::Game() is executed.
  87. Now Game's ctor can call those functions to initialize the standard sub-
  88. windows of game (automap, character, etc)
  89.     Game also overrides the get(Event&) member so that (since Game has no
  90. owner) the local eventQueue is called upon to retrieve events.
  91.     Never try to just use a Game and run() it - it will enter an endless
  92. loop since the eventQueue's won't be receiving input, and the Game has no
  93. sub-windows to force it to quit (by default, all the function pointers passed
  94. to GameInit are null). Once we have some working Keyboard, Mouse, etc classes
  95. Game can be modified to instantiate them.
  96.     For a sub-object, or a derived Game::handle() to quit the game, Game's
  97. modal state has to be ended. Game::handle() handles Message events which
  98. have an id of IdQuit to end the modal state. For more on modal, see
  99. WINDOW.TXT.
  100.  
  101. Methods
  102. -------
  103.  
  104.     Game(const Rect&)            constructor
  105.         Passes the rect to the Window ctor. Next it calls getLocalBounds() to
  106.         get the bounding rectangle for the Game (topLeft at (0,0)) and
  107.         calls each function stored by the virtual base GameInit to initialize
  108.         the five static members. If the function was null, then the
  109.         associated static Visible* member is set to null.
  110.  
  111.     void get(Event& event)        virtual
  112.         Overridden from Visible::get() so that events are retrieved from the
  113.         eventQueue member. If the retrieved event is null, the virtual
  114.         member idle() is called so that required background operations can
  115.         be performed.
  116.  
  117.     void handle(Event& event)    virtual
  118.         Overridden from Window::handle(). First it checks to see if the event
  119.         is a Message/IdQuit event; if so, stopRunning is called so that the
  120.         modal state ends; also then clears the event. If the event is not
  121.         this, it is passed on to the base Window::handle(event) to handle
  122.         the event.
  123.  
  124.     void idle()                    virtual
  125.         This is called whenever get() retrieves an event from the queue and
  126.         the event is null (indicating no pending events). This function just
  127.         returns; if background operations need to be performed during idle
  128.         time, override this function.
  129.  
  130.     bool sendMessage(Visible* dest, word type, word id, void* info)    static
  131.         This member allows you to more easily send a message directly to a
  132.         Visible. It build an Event with event.type == type, event.msg.id == id,
  133.         and event.msg.pointerValue == info; then it calls dest->handle(event)
  134.         to process the event. If the event is null afterward (dest handled it)
  135.         returns true; if dest is null or the event is *not* null afterward,
  136.         returns false.
  137.  
  138. Members
  139. -------
  140.  
  141.     EventQueue eventQueue        static
  142.         This is the event queue, which hold Event class objects. See
  143.         EVENTQ.TXT for more information. Since this member is public and
  144.         static, any module can access the system queue by including GAME.HPP
  145.         and accessing it through:
  146.                 #include "WINDOW\GAME.HPP"
  147.  
  148.                 ...
  149.                 Game::eventQueue.put(event);
  150.                 ...
  151.  
  152.     Mouse mouse                    static
  153.         This is the default mouse class.
  154.  
  155.     Game* game                    static
  156.         Points to the (only) instance of game. Using this, you can call
  157.         virtual functions in a derived Game class.
  158.  
  159.     Visible* closeUp            static
  160.         Pointer to the close up window.
  161.  
  162.     Visible* autoMap            static
  163.         Pointer to the automap window.
  164.  
  165.     Visible* buttons            static
  166.         Pointer to the buttons window.
  167.  
  168.     Visible* character            static
  169.         Pointer to the character window.
  170.  
  171.     Visible* message
  172.         Pointer to the message window.
  173.  
  174.     Note: the above pointers are provided so that modules can pass events
  175.     directly to the windows if necessary.
  176.  
  177.