---

Form.h

Go to the documentation of this file.

/** $Revision: 1.14 $
    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__
#define __FORM__
#include <PalmOS.h>
#include "MiscFunc.h"

/** Generic form
    All you need to do is derive a class from this one and override the main handle event methods
    There are several ways in which forms can be used. If the same form is used in several other forms (with no changes) then it 
    may be best to implement that form as a singleton and use the reference from other forms.
    If the form (say A) is used only once in another form (say B), that an A object can be created inside B. Note that if you use
    forms with popup() the A has to be alive for roughly the same amount of time as B.

    However, if you use a dialog form (i.e. form closes and returns as soon as a button is pressed) you can define the form object
    local to the section it is needed in.

    When defining a new form you need to make sure that the Form constructor is called with your form's resource id as a parameter. 
    This registers the form with the FormManager. If you overload the destructor, you need to call FormManager::instance()->deregisterForm(form_id);
    
    \todo some of the handle functions will need parameters, they will appear as they will get used
*/
class Form
{   
public:
    /**  definition for table selection event. This definition is copied from  Core/UI/Event.h */
    typedef struct tblSelect {
        UInt16            tableID;
        struct TableType       *pTable;
        Int16             row;
        Int16             column;
    };
    /**  definition for popup item selection event. This definition is copied from  Core/UI/Event.h */
    typedef struct popSelect {
        UInt16            controlID;
        struct ControlType *controlP;
        UInt16            listID;
        struct ListType        *listP;
        Int16             selection;
        Int16             priorSelection;
    };

    /** The form constructor
        \todo remove the default =0 as soon as all the form classes have been ported
        @param id the identifier of the form resource this form is to serve. make sure you set this */
    Form(UInt16 id) FORM_SECTION2;
        
    /** destructor- unregisters the form */
    virtual ~Form() FORM_SECTION2;
 
    ///returns the saved attribute
    Boolean getSaved() { return saved; }
                        
    /** sets the saved attribute
        @param b the saved state */
    void setSaved(Boolean b) { saved = b; }

    /** sets the caller id attribute        
        @param t the id of the caller */
    void setCallerFormId(UInt16 t) { caller_form_id = t; }

    /** use this to obtail the form pointer (to the actual form, not to the object
        @return pointer to form managed by class */
    virtual FormPtr getFormPointer() { return frm; }

    /** executes popup for the current form */
    virtual void popup() FORM_SECTION2;

    /**  executes popup for another form, setting the caller_form_id for the popedup form to the
         id of the current form
         @param form pointer to the form to execute popup for */
    virtual void popup (Form* form) FORM_SECTION2;

     /**    executes the form as a dialog
        @param parent_form if set it will set the active form to the given form pointer */
    UInt16 doDialog(FormPtr parent_form=NULL) FORM_SECTION2;        

    /** event handler for the form; this function calls automatically the other handle* functions
        @param EventPtr pointer to the incoming event
        @return true if event was handled, false othewise */
    virtual Boolean handleEvent(EventPtr) FORM_SECTION2;
    
    /** wrapper for FrmGetObjectIndex
        @param object_id id of the object (in the current form) to obtain the index for
        @return index of the given object */
    UInt16 getObjectIndex (UInt16 object_id) FORM_SECTION2;

    ///this function is called when the form is loaded
    virtual Boolean handleLoadEvent() FORM_SECTION2;
    ///this function is called when the form is closed
    virtual Boolean handleCloseEvent() FORM_SECTION2;

protected:
    ///pointer to the form
    FormPtr frm;
    ///true if the form was saved, false otherwise
    Boolean saved;
    ///the id of the caller form; can be used to enable returning to the correct caller after finishing 
    UInt16    caller_form_id;  
    ///the id of the form resource
    UInt16    form_id;

    ///called when key down event occurs
    virtual Boolean handleKeyDownEvent(WChar key_id, UInt16 modifiers) FORM_SECTION2;
    ///called when form open event occurs
    virtual Boolean handleOpenEvent() FORM_SECTION2;
    /** called when ctl select event occurs
            @param control_id id of the control for which the event was generated */
    virtual Boolean handleCtlSelectEvent(UInt16 control_id) FORM_SECTION2;
    /**  called when a table select event occurs 
         @param tbl_select forwarded tblSelect event data   */
    virtual Boolean handleTblSelectEvent(tblSelect& tbl_select) FORM_SECTION2;
    /**  called when a list select event occurs 
         @param item item in the list that has been selected (0 based)   */
    virtual Boolean handleLstSelectEvent(UInt16 item) FORM_SECTION2;    
    /** called when a menu event occurs */
    virtual Boolean handleMenuEvent(UInt16 menu_item_id) FORM_SECTION2;
    /** called when a form update event occurs 
        @param update_code the update code signalled */
    virtual Boolean handleUpdateEvent(UInt16 update_code) FORM_SECTION2;
    ///handles events generated by the pen up
    virtual Boolean handlePenDownEvent (Int16 x_coord, Int16 y_coord) FORM_SECTION2; 
    /**  handles events generated by item selection in popup
         @param pop_select forwarded popSelect event data */
    virtual Boolean handlePopSelect (popSelect& pop_select) FORM_SECTION2;
    /** handles events generated when field are changed */
    virtual Boolean handleFldChangedEvent() FORM_SECTION2;
    /** handles events generated by the scrollbar */
    virtual Boolean handleSclRepeatEvent(UInt16 new_value, UInt16 value) FORM_SECTION2;
};


#endif

---