Categories: Symbian C++ | Code Examples | UI

This page was last modified 12:45, 20 June 2008.

From Forum Nokia Wiki

What is Form

Forms provide a way to allow the user to quickly and easily enter or edit many items of data in one process. Forms can have a number of fields, displayed in a similar way to a list, which the user can scroll up and down. Unlike list items, form lines are editable when they are in focus.

Forms have either a view mode and an edit mode, or just an edit mode. Use of a view mode implies that there is some existing information to display in the form, which the user can then edit. For example, in a game application a form could be used in view mode to display information about existing details for an opponent, and then in edit mode to change the details.

Creating Form from Resource

Forms are contained within a DIALOG resource, specifying the form components.

RESOURCE DIALOG r_myform_form_dialog
{
	flags = EEikDialogFlagNoDrag | 
			EEikDialogFlagFillAppClientRect |
			EEikDialogFlagWait |
			EEikDialogFlagCbaButtons;
			
	buttons = R_AVKON_SOFTKEYS_OPTIONS_BACK;
	form = r_myform_form;
	
	
}

// r_myform_form is defined as :
 
RESOURCE FORM r_myform_form
	{
	flags =  EEikFormUseDoubleSpacedFormat ;
	items =
		{
		DLG_LINE
			{
			type=EEikCtEdwin;
			prompt=NAME_TEXT;
			id=EmyformDlgCIdEdwin;
			itemflags = EEikDlgItemTakesEnterKey | EEikDlgItemOfferAllHotKeys;
			control=EDWIN 
				{
				width=50; 
				maxlength=50;
				};
			},
			DLG_LINE
			{
			type=EEikCtEdwin;
			prompt=PHONE_NO_TEXT;
			id=EmyformDlgCIdEdwin2;
			itemflags = EEikDlgItemTakesEnterKey | EEikDlgItemOfferAllHotKeys;
			control=EDWIN 
				{
				width=50; 
				maxlength=50;
				};
			},
			DLG_LINE
			{
			type=EEikCtEdwin;
			prompt=EMAIL_TEXT;
			id=EmyformDlgCIdEdwin3;
			control=EDWIN 
				{
				width=50; 
				maxlength=50;
				};
			}
		};
	}

Header File

// Derive the class from CAknForm
 
class CMyForm : public CAknForm
    {
    public:  // Constructor and destructor  
        /**
        * NewL
        * Two-phased constructor.
        */
        static CMyForm* NewL();
 
        /**
        * ~CMyForm
        * Destructor.
        */
        virtual ~CMyForm();
 
    public:
        /**
        * From CAknForm, ExecuteLD
        * @return CAknForm::ExecuteLD return value
        * @param aResourceId resource ID
        */
        TInt ExecuteLD( TInt aResourceId ); 
 
        /**
        * From CAknForm, PrepareLC
        * @param aResourceId resource ID
        */
        void PrepareLC( TInt aResourceId ); 
 
    private:  // Constructor
        /**
        * CMyForm
        * Default constructor.
        */
        CMyForm();
 
        /**
        * ConstructL
        * Second-phase constructor.
        */
        void ConstructL();
    
    private:  // Functions from base class
        /**
        * From CEikDialog, PostLayoutDynInitL 
        * Set default field value to member data.
        */
        void PreLayoutDynInitL();
 
        /**
        * From CAknForm , QuerySaveChangesL
        * Show save query. If user answers "No" to this query.
        * return field value to the value which is before editing.
        */
        TBool QuerySaveChangesL();
 
        /**
        * From CAknForm , SaveFormDataL
        * Save the contents of the form.
        */
        TBool SaveFormDataL(); 
 
        /**
        * From CAknForm, DoNotSaveFormDataL
        * Does not save the contents of the form.
        */
        void DoNotSaveFormDataL();
 
    private:
        /**
        * For holding controls value
        */
        TBuf<EAknExFormEdwinMaxLength> iDataName;
	.
	.
	.
	.
 };

Implementation File

/**
* Symbian OS 2 phase constructor.
* Constructs the CMyForm  using the NewLC method, popping
* the constructed object from the CleanupStack before returning it.
* 
* @return The newly constructed CMyForm 
*/
 
CMyForm * CMyForm ::NewL()
	{
	CMyForm * self = new (ELeave) CMyForm ();
	CleanupStack::PushL(self);
	self->ConstructL();
	CleanupStack::Pop(self);
	return self;
	}

Getting Form Control Value

/**
* Called by the framework whenver the 'Save' menu item is selected, and by the
* QuerySaveChangesL method when the user answers yes to the save query.
* Saves the data from the forms controls.
* @return TBool ETrue if the form data has been saved, EFalse otherwise.
*/
 
TBool CMyForm ::SaveFormDataL()
	{
 
	CEikEdwin* nEditor = static_cast <CEikEdwin*> (ControlOrNull(EmyformDlgCIdEdwin));
	if ( nEditor )
		{
			// Save the value of Control to class member //
		}
		
	return ETrue;
	}

Setting Form Control Value

/**
* Called when the form is  executed and when the user chooses to discard changes
* in QuerySaveChangesL (via  DoNotSaveFormDataL).
*/
 
void CMyForm ::LoadFormValuesFromDataL()
	{
	CEikEdwin* nEditor = static_cast <CEikEdwin*> (ControlOrNull(EmyformDlgCIdEdwin));
	if (nEditor)
		{
			// Example : set the Control Text //
 
			TBuf<50> myName;
			myName.Copy(_L("Vasant"));
			HBufC* name = myName.AllocLC();
			// Setting the Value //
 
			nEditor->SetTextL(name);
			CleanupStack::PopAndDestroy(name);
		
		}
	
	
	}

/**
* Called by QuerySaveChangeL when the user chooses to discard changes made to 
* the form. Loads the form values from iOpponent
*/
 
void CMyForm ::DoNotSaveFormDataL()
	{
	LoadFormValuesFromDataL();
	}
 
 
/**
* Called by the framework before the form is initialised
* Loads the form values from iOpponent ready for execution of the form
*/
 
void CMyForm ::PreLayoutDynInitL()
	{
	CAknForm::PreLayoutDynInitL();
	LoadFormValuesFromDataL();
	}
 
 
/**
* Called by the framework when a menu is displayed.
* Removes the default items from the options menu of the form for editing a
* fields label, adding a field and deleting a field
*/
 
void CMyForm ::DynInitMenuPaneL(TInt aResourceId, CEikMenuPane* aMenuPane)
	{
	CAknForm::DynInitMenuPaneL(aResourceId,aMenuPane);
	
	if (aResourceId == R_AVKON_FORM_MENUPANE)
		{
		aMenuPane->SetItemDimmed(EAknFormCmdLabel, ETrue);
		aMenuPane->SetItemDimmed(EAknFormCmdAdd, ETrue);
		aMenuPane->SetItemDimmed(EAknFormCmdDelete, ETrue);
		}
	}

Executing Form

CMyForm* form = CMyForm ::NewL();
TInt ret = form->ExecuteLD( R_MYFORM_FORM_DIALOG );

Getting Key Press Event in Form and Exiting from Form

// override OfferKeyEventL for getting key press events. //
 
TKeyResponse  CMyForm::OfferKeyEventL(const TKeyEvent& aKeyEvent,TEventCode aType)
{
		// We send EKeyEscape, for exiting from form if user press EKeyLeftArrow
 
		if ( aKeyEvent.iCode == EKeyLeftArrow  )
		{
			TKeyEvent key;
			key.iCode = EKeyEscape;
			key.iScanCode = EStdKeyEscape;
			key.iRepeats = 0;
			key.iModifiers = 0;
			return CAknForm::OfferKeyEventL(key, EEventKey);
		}
 
}

Adding Menus to Form

// Override DynInitMenuPaneL  //
 
void CMyForm::DynInitMenuPaneL(TInt aResourceId, CEikMenuPane* aMenuPane)
	{
	CAknForm::DynInitMenuPaneL(aResourceId,aMenuPane);
	
	if (aResourceId == R_AVKON_FORM_MENUPANE)
		{
			// Add the menu from the resource defined in the .rss file
			aMenuPane->AddMenuItemsL(R_MOBICRM_ASS_MENU,0,1);
 
		}
	}

Hiding the Default Menus

void CMyForm::DynInitMenuPaneL(TInt aResourceId, CEikMenuPane* aMenuPane)
	{
	CAknForm::DynInitMenuPaneL(aResourceId,aMenuPane);
	
	if (aResourceId == R_AVKON_FORM_MENUPANE)
		{
			// you can hide the default form menus //
 
			aMenuPane->SetItemDimmed(EAknFormCmdLabel,ETrue);
			aMenuPane->SetItemDimmed(EAknFormCmdAdd, ETrue);
			aMenuPane->SetItemDimmed(EAknFormCmdDelete, ETrue);
 
 
		}
	}

Processing commands

/*
* ProcessCommandL() can be overridden to handle * custom commands. Built-in form
* commands are * handled by CAknForm.
*
*/
 
void CMyForm::ProcessCommandL( TInt aCommandId )
    {
    // Form default commands.
    CAknForm::ProcessCommandL( aCommandId );
    // Custom commands.
    switch ( aCommandId )
        {
        case ECommand1:
            User::InfoPrint( _L("Pressed command1 on Form") );
            break;
        default:
            break;
        }
    }

Adding Control Dynamically

In edit mode, fields can be added or deleted dynamically using CAknForm::AddItemL()

void CMyForm::AddItemL()
    {
    _LIT( caption, "New Control" );
    TInt pageId = ActivePageId();
    TInt id = iTotalControls++; 
    TInt type = EEikCtEdwin;
    TAny* unused=0;
    CEikEdwin* edwin = (CEikEdwin*)CreateLineByTypeL
        ( caption, pageId, id, type, unused );
    edwin->ConstructL
        ( EEikEdwinNoHorizScrolling | EEikEdwinResizable, 10, 100, 1 );
    Line( id )->ActivateL();
    SetEditableL( IsEditable() ) ;
    DrawNow();
    }

Setting Focus on Desired Control on Form

// Pass the Id of the Control on which focus is to be set.
TryChangeFocusToL( EmyformDlgCIdEdwin2 );

Updating Form

//  Only has effect on forms, call this after adding or deleting lines
UpdatePageL( ETrue );

Getting Control ID in Focus

// Gets the ID of the Control having Focus //
 
TInt FocusedControlId = IdOfFocusControl();
 
if( FocusedControlId == EmyformDlgCIdEdwin)
{
   // Do Something //
}

Getting the Mode ( editable or view mode )

if( IsEditable() )
{
  // Form is in the edit mode //
}
else
{
  // Form is not in the edit mode //
}