diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/app/cpbkdatasaveappui.h --- a/epoc32/include/app/cpbkdatasaveappui.h Tue Nov 24 13:55:44 2009 +0000 +++ b/epoc32/include/app/cpbkdatasaveappui.h Tue Mar 16 16:12:26 2010 +0000 @@ -1,1 +1,219 @@ -cpbkdatasaveappui.h +/* +* Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* 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 +* which accompanies this distribution, and is available +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: +* Phonebook Data Save service helper. Implements "Save to phonebook" +* menu functionality for external applications. +* +*/ + + +#ifndef __CPbkDataSaveAppUi_H__ +#define __CPbkDataSaveAppUi_H__ + +// INCLUDES +#include + +// FORWARD DECLARATIONS +class CEikMenuPane; +class CPbkContactEngine; +class CPbkContactItem; +class CPbkFieldInfo; +class MPbkDataSaveCallback; +class CPbkFFSCheck; +class CPbkExtGlobals; + + +// CLASS DECLARATION + +/** + * Phonebook Data Save service helper. Implements "Save to phonebook" + * menu functionality for external applications. + * + * Note that in most cases current status pane layout is replaced with the + * Phonebook one. Restoring the original pane is left to be + * the responsibility of the client. + */ +class CPbkDataSaveAppUi : public CBase + { + public: // Interface + /** + * Creates an instance of this class. + * + * @param aEngine Phonebook engine instance. + */ + IMPORT_C static CPbkDataSaveAppUi* NewL(CPbkContactEngine& aEngine); + + /** + * Destructor. Destroys this object and cancels any open dialogs. + */ + ~CPbkDataSaveAppUi(); + + /** + * Adds Phonebook data save menu items to a menu pane. Called from + * applications DynInitMenuPaneL. This call is not mandatory: + * if the application provides its own menus it may call + * HandleCommandL directly from menu's command handler. + * + * @param aMenuPane Menu pane where to add the menu items. + * @param aCommandId Id of command which to replace with Phonebook + * data save menu items. This command id is stored + * into this object as the base id after which are + * app-specific command Ids reserved for Phonebook + * data save API usage. + * @see DynInitMenuPaneL + * @see HandleCommandL + */ + IMPORT_C void AddMenuItemsL(CEikMenuPane* aMenuPane, TInt aCommandId); + + /** + * Updates Phonebook data save menu items. Called from applications + * DynInitMenuPaneL. This call is not mandatory: if the application + * provides its own menus it may call HandleCommandL directly + * from menu's command handler. + * + * @param aResourceId Resource id of the menu pane as passed to + * MEikMenuObserver::DynInitMenuPaneL. If this + * resource id does not match with Phonebook data + * save submenu this function does nothing. + * @param aMenuPane Menu pane as passed to + * MEikMenuObserver::DynInitMenuPaneL. + * @see AddMenuItemsL + */ + IMPORT_C void DynInitMenuPaneL(TInt aResourceId, CEikMenuPane* aMenuPane); + + /** + * Handles a menu command inserted by AddMenuItemsL. + * + * @param aCommandId Command to execute. iBaseCommandId+1 is + * Create New Entry and iBaseCommandId+2 is + * Add to Existing Entry. Use directly + * EPbkCmdDataSaveCreateNew or EPbkCmdDataSaveAddToExisting + * if AddMenuItemsL is not called. + * @param aFieldTypes Field types where the user can select from. + * If there is only one field type selection + * list is not displayed. + * @param aText Text to put to the selected field. + * @param aCallback Calls back to this object if there are + * problems in adding the field. See + * MPbkDataSaveCallback class for details. + * @return ETrue if the command was executed and the data added, + * EFalse if the operation was canceled in any stage. + * @see AddMenuItemsL + * @see MPbkDataSaveCallback + * @see TPbkDataSaveCommandId in PbkDataSaveAppUi.hrh + */ + IMPORT_C TBool HandleCommandL + (TInt aCommandId, + CArrayPtr& aFieldTypes, + const TDesC& aText, + MPbkDataSaveCallback* aCallback=NULL); + + /** + * Handles a menu command inserted by AddMenuItemsL. + * + * @param aCommandId Command to execute. iBaseCommandId+1 is + * Create New Entry and iBaseCommandId+2 is + * Add to Existing Entry. Use directly + * EPbkCmdDataSaveCreateNew or EPbkCmdDataSaveAddToExisting + * if AddMenuItemsL is not called. + * @param aFieldTypes Field types where the user can select from. + * If there is only one field type selection + * list is not displayed. + * @param aDate Date to put to the selected field. + * @param aCallback Calls back to this object if there are + * problems in adding the field. See + * MPbkDataSaveCallback class for details. + * @return ETrue if the command was executed and the data added, + * EFalse if the operation was canceled in any stage. + * @see AddMenuItemsL + * @see MPbkDataSaveCallback + * @see TPbkDataSaveCommandId in PbkDataSaveAppUi.hrh + */ + IMPORT_C TBool HandleCommandL + (TInt aCommandId, + CArrayPtr& aFieldTypes, + const TTime& aDate, + MPbkDataSaveCallback* aCallback=NULL); + + /** + * Hides the "Exit" command from contact editor's options menu. + * Call this function after creating this object. + */ + IMPORT_C void HideEditorExitCommand(); + + private: // Implementation + class MFieldData; + class CTextFieldData; + class CDateFieldData; + class CCommandBase; + class CCreateNewCommand; + class CAddToExistingCommand; + CPbkDataSaveAppUi(CPbkContactEngine& aEngine); + void ConstructL(); + TBool DoHandleCommandL + (TInt aCommandId, + CArrayPtr& aFieldTypes, + MFieldData& aFieldData, + MPbkDataSaveCallback* aCallback); + + private: // Data + /// Ref: Phonebook engine instance + CPbkContactEngine* iEngine; + /// Own: FFS space checker + CPbkFFSCheck* iFFSCheck; + /// Own: base command id + TInt iBaseCommandId; + /// Own: the currently executing command + CCommandBase* iExecutingCommand; + /// Own: flags + TUint iFlags; + /// Own: handle to UI extension factory + CPbkExtGlobals* iExtGlobals; + }; + + +/** + * Callback interface for CPbkDataSaveAppUi::HandleCommandL. + */ +class MPbkDataSaveCallback + { + public: // Interface + /** + * Called by CPbkDataSaveAppUi::HandleCommandL if there is no field + * available where to save the data and no new field could be added. + * Default implementation does nothing. + * + * @param aContact Contact where the field cannot be added. + */ + IMPORT_C virtual void PbkDataSaveNoFieldL(CPbkContactItem& aContact); + + /** + * Called from CPbkDataSaveAppUi::HandleCommandL if the aText is too + * long to fit into field. + * Default implementation clips aText from the end. If an empty + * string is returned the field addition is canceled. + * + * @param aText The original text. + * @param aFieldInfo The type of field where the text should be + * inserted. + * @return A substring of aText so that the substring's length is + * <=aFieldInfo.MaxLength(). + */ + IMPORT_C virtual TPtrC PbkDataSaveClipTextL + (const TDesC& aText, CPbkFieldInfo& aFieldInfo); + }; + +#endif // __CPbkDataSaveAppUi_H__ + +// End of File