---

FormManager.h

Go to the documentation of this file.

/** $Revision: 1.12 $
    Last updated: $Date: 2002/09/24 19:46:42 $
    
    Copyright (C) 2001-2002 Vlad Mereuta <dizzy@users.sourceforge.net>

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */

#ifndef __FORM_MANAGER__
#define __FORM_MANAGER__

#include "FreeCoinsRsc.h"
#include "Form.h"
#include <PalmOS.h>


/** This class manages dispatching Form events, by using Form classes instead of the normal C mechanism provided by PalmOS.
    The current implementation is jusr a hack, but it seems to work rather well.

    The idea behind this is to keep a dictionary of form_id's and the associated form pointers.  This way any kind of
    events can be dispatched to the right form, provided the form registered with the manager (i.e. the manager know
    what form handles the form_id which is targeted by the incoming event.

    Please note that this class is a Singleton. Ummm sort of that is. more like a singleton hack. Point is that you are only meant
    to access it via the frm_mngr pointer, which in turn is automatically initialised at the first
    call to registerForm (so *DO NOT* calll any other method before register form)

    \todo class should be reimplemented. May be convenient to use a linked list instead of a fixed size array */

class FormManager
{
public:
    /** returns a reference to FormManager. This is the only allowed way to access this class */
    static FormManager* instance();
    /** destroys the instance (if no forms are still registred) */
    static void destroyInstance() FORM_SECTION2;
    /** instructs the FormManger to destroy its instance immidiately if possible or when all forms have been de-registred */
    void suicide() FORM_SECTION2;
    /** this function  adds the details given by the paramaters to the forms array
        @param form_id id of the form to be added
        @param form pointer to the form to be added. All events will be re-routed via this pointer */
    void registerForm(UInt16 form_id, Form* form) FORM_SECTION2;
    /** removes a form from the forms array containing registred forms */
    void deregisterForm(UInt16 form_id) FORM_SECTION2;
    /** rearanges the forms array in such a way that the given form always receives the events
        first. This is useful when a given form has more than one instance, all active at the same
        time and they are all sharing the same form_id
        @param form_id id of the form resource
        @param form pointer to form to handle events for this resource first. */
    void bringToFront (UInt16 form_id, Form* form) FORM_SECTION2;
    /** dispatches event to the right form (if registred)
        @param event event to be dispatched */
    Boolean dispatchEvent(EventPtr event) FORM_SECTION2;
    /** dispatches a load event to a given form
        @param form_id form to dispatch load event to */
    Boolean dispatchLoadEvent(UInt16 form_id) FORM_SECTION2;
    /** dispatches a close event to a given form
        @param form_id form to dispatch load event to */    
    Boolean dispatchCloseEvent(UInt16 form_id) FORM_SECTION2;

private:
    ///form information stored by the manager
    struct  form_info {
        ///id of the form
        UInt16  form_id;
        ///pointer to the form
        Form*   frm;
        ///flag signaling whether the form is active or not
        Boolean active;
    };
    
    ///maximum number of forms that can be handled (active at the same time)
    const static UInt8 max_forms=25;

    ///information on all forms
    form_info forms[max_forms];

    ///singleton reference to this class
    static FormManager* _instance;
    ///flag indicating whether the FormManager is required to kill itself. this cannot be accomplished while forms are still registred
    static Boolean _destroy_requested;
    ///number of forms currently registred with the FormManager
    static UInt8 _form_count;

    ///constructor; initialises the forms array (private to prevent accidental duplication)
    FormManager() FORM_SECTION2;
};

#endif

---