1 aknform.h

     1 /*

     2 * Copyright (c) 2002-2004 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * 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

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 * 	  Support for Form component. Also has CAknDialog which specialized 

    16 *     CEikDialog (adds menu capability) Note that most support for Avkon

    17 *     Forms is contained within CEikDialog.

    18 *

    19 *

    20 */

    21 

    22 

    23 #ifndef __AKNFORM_H__

    24 #define __AKNFORM_H__

    25 

    26 // INCLUDES

    27 #include <aknDialog.h>

    28 

    29 // CLASS DECLARATION

    30 class CEikMenuBar ;

    31 

    32 /**

    33 * Forms are special types of dialogs. The item layout and functionality can

    34 * differ between the two states. In the view state, the fields are not 

    35 * editable. It looks and acts like a listbox. The listbox focus can be moved

    36 * and items can be selected.

    37 *

    38 *  @since Series 60 0.9

    39 */

    40 class CAknForm : public CAknDialog

    41 	{

    42 public:

    43 	

    44 	/**

    45 	* Base class default constructor.

    46 	*/

    47 	IMPORT_C CAknForm();

    48 	

    49 	/**

    50     * Perform the second phase construction of a object. If a leave occurs

    51     * the framework generates a Symbian Leave code.

    52     * @param aMenuResource The menu resource to be used for the form.

    53     */

    54 	IMPORT_C void ConstructL( TInt aMenuBarId=0 );

    55 	

    56 	/**

    57 	* Destructor.

    58 	*/

    59 	IMPORT_C ~CAknForm();

    60 

    61     /**

    62     * Function from @c MEikMenuObserver. The framework 

    63     * calls this function. It removes the unused default form options. If a 

    64     * leave occurs the framework generates a Symbian Leave code. 

    65     * @param aResourceId The ID of the menu pane.

    66     * @param aMenuPane The menu pane itself.

    67     */

    68 	IMPORT_C virtual void DynInitMenuPaneL( TInt aResourceId, CEikMenuPane* aMenuPane );

    69 

    70     /**

    71     * Function from @c MEikCommandObserver. Handle user menu commands. If a

    72     * leave occurs the framework generates a Symbian Leave code.

    73     * @param aCommandId The command identifier to process.

    74     */ 

    75 	IMPORT_C virtual void ProcessCommandL( TInt aCommandId );

    76 

    77 protected:

    78 	/**

    79 	* Function from @c CEikDialog. Called by framework when the softkey is 

    80 	* pressed. Use this to pop up the options menu or close the dialog. Will

    81 	* call c@ SaveFormDataL() before closing if data has been edited. Will 

    82 	* NOT permit exit if attempt to save data fails. If a leave occurs the 

    83 	* framework generates a Symbian Leave code.

    84  	* @param aButtonId Translates the button presses into commands ID.

    85  	* @return @c ETrue if the dialog should exit, and @c EFalse if it should

    86  	* not. 

    87 	*/ 

    88 	IMPORT_C virtual TBool OkToExitL( TInt aButtonId );

    89 

    90 	/**

    91 	* Function from @c CEikDialog and thence from c@ MEikDialogPageObserver.

    92 	* This funtion should be implemented to prepare for focus transition from

    93 	* the current line. If deleting then this routine must not do anything (the

    94 	* default tries to access the control which has just been deleted). If a

    95 	* leave occurs the framework generates a Symbian Leave code.

    96 	*/

    97 	IMPORT_C virtual void PrepareForFocusTransitionL();

    98 

    99 public:

   100 

   101 	/**

   102 	* Function from @c CCoeControl handles a change to the control's resources

   103 	* of type aType which are shared across the environment, e.g. colors or 

   104 	* fonts.

   105 	* @param aType. A message UID value.

   106 	* @since Series 60 2.0

   107 	*/

   108 	IMPORT_C void HandleResourceChange(TInt aType);

   109 

   110         /**

   111          * From CCoeControl.     

   112          * Handles pointer events

   113          * @param aPointerEvent     The pointer event.

   114          */

   115     	IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

   116 

   117 protected:

   118 

   119 	/**

   120 	* This routine should be re-implemented by the client to save the contents

   121 	* of the form. The re-implementation can call this function to display the 

   122 	* 'Saved' dialog @c CAknForm::SaveFormDataL().

   123 	* @return @c ETrue if the editable state can be left. The return value should

   124 	* reflect whether or not the form is to leave the editable state. A real 

   125 	* system problem saving should generate a Symbian Leave code.

   126 	*/

   127 	IMPORT_C virtual TBool SaveFormDataL(); 

   128 	

   129 	/**

   130 	* This routine should be implemented by the client for dealing with the 

   131 	* occasion of a change from edit->view mode but the user does not wish to 

   132 	* save the changes. A typical implementation would set the controls back 

   133 	* to their old values. If a leave occurs the framework generates a 

   134 	* Symbian Leave code.

   135 	*/

   136 	IMPORT_C virtual void DoNotSaveFormDataL(); 

   137 

   138 	/**

   139 	* This routine may be overridden. Default displays 'Save Changes Dialog 

   140 	* Yes/No'. Data validation may occur here as an alternative to overriding

   141 	* @c OkToExit(). Re-implementation may put data validation here (as an 

   142 	* alternative to over-riding @c OkToExit() - which is a more complicated 

   143 	* method). Note that this routine does not perform the changes itself. If 

   144 	* the leave occurs the framework generates a Symbian Leave code.

   145 	* @return @c ETrue if changes are requested to be saved and then are 

   146 	* successfully saved. Save of data is not performed here but in 

   147 	* @c SaveFormDataL().

   148     */

   149 	IMPORT_C virtual TBool QuerySaveChangesL();

   150 	

   151 	/**

   152  	* This routine may be overridden. Default displays old label as caption and

   153  	* editor for new one. Uses customised dialog.If a leave occurs the 

   154  	* framework generates a Symbian Leave code.

   155  	*/

   156 	IMPORT_C virtual void EditCurrentLabelL();

   157 		

   158 	/**

   159  	* This routine may be overridden. Default displays "Delete item? Yes/No"

   160  	* Deletes item on return from the dialog before returning. If a leave occurs

   161  	* the framework generates a Symbian Leave code.

   162  	*/	

   163 	IMPORT_C virtual void DeleteCurrentItemL();

   164 	

   165 	/**

   166  	* This routine may be overridden. Implementation is missing in this class.

   167  	*/	

   168 	IMPORT_C virtual void AddItemL();

   169 	

   170 	/**

   171 	* Sets changes pending.

   172 	* @param aChangesPending @c ETrue if changes are pending. Else @cEFalse. 

   173 	*/	

   174 	IMPORT_C void SetChangesPending(TBool aChangesPending);

   175 	

   176 	/**

   177 	* Function from @c CEikdialog. This function is called by the EIKON 

   178 	* dialog framework just before the dialog is activated, after it has 

   179 	* called @c PreLayoutDynInitL() and the dialog has been sized. If a  

   180 	* leave occurs the framework generates a Symbian Leave code.

   181 	*/	

   182 	IMPORT_C void PostLayoutDynInitL();

   183 	

   184 	/**

   185 	* Overridden, so that the form can tell if a line's state has changed.

   186 	* This is used to decide when to save changes. If a leave occurs the

   187 	* framework generates a Symbian Leave code.

   188 	* @param aControlId. Control id. 

   189 	*/	

   190 	IMPORT_C void HandleControlStateChangeL(TInt aControlId);

   191 	

   192 	/** 

   193 	* This is added, so that anyone adding lines either in @c PreLayoutDynInit()

   194 	* or @c SetInitialCurrentLine() should have the lines in a consistent state.

   195 	*/	

   196 	IMPORT_C void SetInitialCurrentLine();

   197 

   198 	/** 

   199 	* Required by @c OkToExit().

   200 	* @return @c ETrue if unsave editing, and @c EFalse if it 

   201 	* should not.

   202 	*/

   203 	IMPORT_C TBool UnsavedEdit() const;

   204 	

   205 	/** 

   206 	* Required by @c PrepareForFocusTransitionL().

   207 	* @return @c ETrue if deleting, and @c EFalse if it 

   208 	* should not.

   209 	*/	

   210 	IMPORT_C TBool Deleting() const;

   211 

   212 enum TFlags

   213 	{

   214 	/** Flag for deleting item. */

   215 	EDeleting = 0x1, // Form flag enum

   216 	

   217 	/** Flag for unsave editing item. */

   218 	EUnsavedEdit = 0x2 // Form flag enum

   219 	};

   220 

   221 	/**

   222 	* Set the form flag indicated.

   223 	* @param aFlagPattern Pattern of bits to set or clear.

   224 	* @param aSetTheFlag If @c ETrue, sets the pattern; if @c EFalse, clear the 

   225 	* pattern.

   226 	*/

   227 	IMPORT_C void SetFormFlag( TFlags aFlagPattern, TBool aSetTheFlag );

   228 

   229 private: 

   230     /**

   231     * From CAknControl

   232     */

   233     IMPORT_C void* ExtensionInterface( TUid aInterface );

   234 

   235 private: 

   236 	IMPORT_C virtual void CEikDialog_Reserved_1();

   237 	IMPORT_C virtual void CEikDialog_Reserved_2();	

   238 private: 

   239 	IMPORT_C virtual void CAknDialog_Reserved();

   240 private:// new function  

   241 	IMPORT_C virtual void CAknForm_Reserved();

   242 private: // helpers

   243 	void DoLayout();

   244 private :

   245 	TInt iMenuBarId ;  // resource ID

   246 	TInt iFlags ;

   247 	TInt iWsBufferRequestID;

   248 	} ;

   249 

   250 #endif	// __AKNFORM_H__