williamr@2: /*
williamr@2: * Copyright (c) 2002-2004 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@2: * under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
williamr@2: * which accompanies this distribution, and is available
williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description: 
williamr@2: * 	  Support for Form component. Also has CAknDialog which specialized 
williamr@2: *     CEikDialog (adds menu capability) Note that most support for Avkon
williamr@2: *     Forms is contained within CEikDialog.
williamr@2: *
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: #ifndef __AKNFORM_H__
williamr@2: #define __AKNFORM_H__
williamr@2: 
williamr@2: // INCLUDES
williamr@2: #include <aknDialog.h>
williamr@2: 
williamr@2: // CLASS DECLARATION
williamr@2: class CEikMenuBar ;
williamr@2: 
williamr@2: /**
williamr@2: * Forms are special types of dialogs. The item layout and functionality can
williamr@2: * differ between the two states. In the view state, the fields are not 
williamr@2: * editable. It looks and acts like a listbox. The listbox focus can be moved
williamr@2: * and items can be selected.
williamr@2: *
williamr@2: *  @since Series 60 0.9
williamr@2: */
williamr@2: class CAknForm : public CAknDialog
williamr@2: 	{
williamr@2: public:
williamr@2: 	
williamr@2: 	/**
williamr@2: 	* Base class default constructor.
williamr@2: 	*/
williamr@2: 	IMPORT_C CAknForm();
williamr@2: 	
williamr@2: 	/**
williamr@2:     * Perform the second phase construction of a object. If a leave occurs
williamr@2:     * the framework generates a Symbian Leave code.
williamr@2:     * @param aMenuResource The menu resource to be used for the form.
williamr@2:     */
williamr@2: 	IMPORT_C void ConstructL( TInt aMenuBarId=0 );
williamr@2: 	
williamr@2: 	/**
williamr@2: 	* Destructor.
williamr@2: 	*/
williamr@2: 	IMPORT_C ~CAknForm();
williamr@2: 
williamr@2:     /**
williamr@2:     * Function from @c MEikMenuObserver. The framework 
williamr@2:     * calls this function. It removes the unused default form options. If a 
williamr@2:     * leave occurs the framework generates a Symbian Leave code. 
williamr@2:     * @param aResourceId The ID of the menu pane.
williamr@2:     * @param aMenuPane The menu pane itself.
williamr@2:     */
williamr@2: 	IMPORT_C virtual void DynInitMenuPaneL( TInt aResourceId, CEikMenuPane* aMenuPane );
williamr@2: 
williamr@2:     /**
williamr@2:     * Function from @c MEikCommandObserver. Handle user menu commands. If a
williamr@2:     * leave occurs the framework generates a Symbian Leave code.
williamr@2:     * @param aCommandId The command identifier to process.
williamr@2:     */ 
williamr@2: 	IMPORT_C virtual void ProcessCommandL( TInt aCommandId );
williamr@2: 
williamr@2: protected:
williamr@2: 	/**
williamr@2: 	* Function from @c CEikDialog. Called by framework when the softkey is 
williamr@2: 	* pressed. Use this to pop up the options menu or close the dialog. Will
williamr@2: 	* call c@ SaveFormDataL() before closing if data has been edited. Will 
williamr@2: 	* NOT permit exit if attempt to save data fails. If a leave occurs the 
williamr@2: 	* framework generates a Symbian Leave code.
williamr@2:  	* @param aButtonId Translates the button presses into commands ID.
williamr@2:  	* @return @c ETrue if the dialog should exit, and @c EFalse if it should
williamr@2:  	* not. 
williamr@2: 	*/ 
williamr@2: 	IMPORT_C virtual TBool OkToExitL( TInt aButtonId );
williamr@2: 
williamr@2: 	/**
williamr@2: 	* Function from @c CEikDialog and thence from c@ MEikDialogPageObserver.
williamr@2: 	* This funtion should be implemented to prepare for focus transition from
williamr@2: 	* the current line. If deleting then this routine must not do anything (the
williamr@2: 	* default tries to access the control which has just been deleted). If a
williamr@2: 	* leave occurs the framework generates a Symbian Leave code.
williamr@2: 	*/
williamr@2: 	IMPORT_C virtual void PrepareForFocusTransitionL();
williamr@2: 
williamr@2: public:
williamr@2: 
williamr@2: 	/**
williamr@2: 	* Function from @c CCoeControl handles a change to the control's resources
williamr@2: 	* of type aType which are shared across the environment, e.g. colors or 
williamr@2: 	* fonts.
williamr@2: 	* @param aType. A message UID value.
williamr@2: 	* @since Series 60 2.0
williamr@2: 	*/
williamr@2: 	IMPORT_C void HandleResourceChange(TInt aType);
williamr@2: 
williamr@2:         /**
williamr@2:          * From CCoeControl.     
williamr@2:          * Handles pointer events
williamr@2:          * @param aPointerEvent     The pointer event.
williamr@2:          */
williamr@2:     	IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);
williamr@2: 
williamr@2: protected:
williamr@2: 
williamr@2: 	/**
williamr@2: 	* This routine should be re-implemented by the client to save the contents
williamr@2: 	* of the form. The re-implementation can call this function to display the 
williamr@2: 	* 'Saved' dialog @c CAknForm::SaveFormDataL().
williamr@2: 	* @return @c ETrue if the editable state can be left. The return value should
williamr@2: 	* reflect whether or not the form is to leave the editable state. A real 
williamr@2: 	* system problem saving should generate a Symbian Leave code.
williamr@2: 	*/
williamr@2: 	IMPORT_C virtual TBool SaveFormDataL(); 
williamr@2: 	
williamr@2: 	/**
williamr@2: 	* This routine should be implemented by the client for dealing with the 
williamr@2: 	* occasion of a change from edit->view mode but the user does not wish to 
williamr@2: 	* save the changes. A typical implementation would set the controls back 
williamr@2: 	* to their old values. If a leave occurs the framework generates a 
williamr@2: 	* Symbian Leave code.
williamr@2: 	*/
williamr@2: 	IMPORT_C virtual void DoNotSaveFormDataL(); 
williamr@2: 
williamr@2: 	/**
williamr@2: 	* This routine may be overridden. Default displays 'Save Changes Dialog 
williamr@2: 	* Yes/No'. Data validation may occur here as an alternative to overriding
williamr@2: 	* @c OkToExit(). Re-implementation may put data validation here (as an 
williamr@2: 	* alternative to over-riding @c OkToExit() - which is a more complicated 
williamr@2: 	* method). Note that this routine does not perform the changes itself. If 
williamr@2: 	* the leave occurs the framework generates a Symbian Leave code.
williamr@2: 	* @return @c ETrue if changes are requested to be saved and then are 
williamr@2: 	* successfully saved. Save of data is not performed here but in 
williamr@2: 	* @c SaveFormDataL().
williamr@2:     */
williamr@2: 	IMPORT_C virtual TBool QuerySaveChangesL();
williamr@2: 	
williamr@2: 	/**
williamr@2:  	* This routine may be overridden. Default displays old label as caption and
williamr@2:  	* editor for new one. Uses customised dialog.If a leave occurs the 
williamr@2:  	* framework generates a Symbian Leave code.
williamr@2:  	*/
williamr@2: 	IMPORT_C virtual void EditCurrentLabelL();
williamr@2: 		
williamr@2: 	/**
williamr@2:  	* This routine may be overridden. Default displays "Delete item? Yes/No"
williamr@2:  	* Deletes item on return from the dialog before returning. If a leave occurs
williamr@2:  	* the framework generates a Symbian Leave code.
williamr@2:  	*/	
williamr@2: 	IMPORT_C virtual void DeleteCurrentItemL();
williamr@2: 	
williamr@2: 	/**
williamr@2:  	* This routine may be overridden. Implementation is missing in this class.
williamr@2:  	*/	
williamr@2: 	IMPORT_C virtual void AddItemL();
williamr@2: 	
williamr@2: 	/**
williamr@2: 	* Sets changes pending.
williamr@2: 	* @param aChangesPending @c ETrue if changes are pending. Else @cEFalse. 
williamr@2: 	*/	
williamr@2: 	IMPORT_C void SetChangesPending(TBool aChangesPending);
williamr@2: 	
williamr@2: 	/**
williamr@2: 	* Function from @c CEikdialog. This function is called by the EIKON 
williamr@2: 	* dialog framework just before the dialog is activated, after it has 
williamr@2: 	* called @c PreLayoutDynInitL() and the dialog has been sized. If a  
williamr@2: 	* leave occurs the framework generates a Symbian Leave code.
williamr@2: 	*/	
williamr@2: 	IMPORT_C void PostLayoutDynInitL();
williamr@2: 	
williamr@2: 	/**
williamr@2: 	* Overridden, so that the form can tell if a line's state has changed.
williamr@2: 	* This is used to decide when to save changes. If a leave occurs the
williamr@2: 	* framework generates a Symbian Leave code.
williamr@2: 	* @param aControlId. Control id. 
williamr@2: 	*/	
williamr@2: 	IMPORT_C void HandleControlStateChangeL(TInt aControlId);
williamr@2: 	
williamr@2: 	/** 
williamr@2: 	* This is added, so that anyone adding lines either in @c PreLayoutDynInit()
williamr@2: 	* or @c SetInitialCurrentLine() should have the lines in a consistent state.
williamr@2: 	*/	
williamr@2: 	IMPORT_C void SetInitialCurrentLine();
williamr@2: 
williamr@2: 	/** 
williamr@2: 	* Required by @c OkToExit().
williamr@2: 	* @return @c ETrue if unsave editing, and @c EFalse if it 
williamr@2: 	* should not.
williamr@2: 	*/
williamr@2: 	IMPORT_C TBool UnsavedEdit() const;
williamr@2: 	
williamr@2: 	/** 
williamr@2: 	* Required by @c PrepareForFocusTransitionL().
williamr@2: 	* @return @c ETrue if deleting, and @c EFalse if it 
williamr@2: 	* should not.
williamr@2: 	*/	
williamr@2: 	IMPORT_C TBool Deleting() const;
williamr@2: 
williamr@2: enum TFlags
williamr@2: 	{
williamr@2: 	/** Flag for deleting item. */
williamr@2: 	EDeleting = 0x1, // Form flag enum
williamr@2: 	
williamr@2: 	/** Flag for unsave editing item. */
williamr@2: 	EUnsavedEdit = 0x2 // Form flag enum
williamr@2: 	};
williamr@2: 
williamr@2: 	/**
williamr@2: 	* Set the form flag indicated.
williamr@2: 	* @param aFlagPattern Pattern of bits to set or clear.
williamr@2: 	* @param aSetTheFlag If @c ETrue, sets the pattern; if @c EFalse, clear the 
williamr@2: 	* pattern.
williamr@2: 	*/
williamr@2: 	IMPORT_C void SetFormFlag( TFlags aFlagPattern, TBool aSetTheFlag );
williamr@2: 
williamr@2: private: 
williamr@2:     /**
williamr@2:     * From CAknControl
williamr@2:     */
williamr@2:     IMPORT_C void* ExtensionInterface( TUid aInterface );
williamr@2: 
williamr@2: private: 
williamr@2: 	IMPORT_C virtual void CEikDialog_Reserved_1();
williamr@2: 	IMPORT_C virtual void CEikDialog_Reserved_2();	
williamr@2: private: 
williamr@2: 	IMPORT_C virtual void CAknDialog_Reserved();
williamr@2: private:// new function  
williamr@2: 	IMPORT_C virtual void CAknForm_Reserved();
williamr@2: private: // helpers
williamr@2: 	void DoLayout();
williamr@2: private :
williamr@2: 	TInt iMenuBarId ;  // resource ID
williamr@2: 	TInt iFlags ;
williamr@2: 	TInt iWsBufferRequestID;
williamr@2: 	} ;
williamr@2: 
williamr@2: #endif	// __AKNFORM_H__