--- 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 <e32base.h>
+
+// 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<CPbkFieldInfo>& 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<CPbkFieldInfo>& 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<CPbkFieldInfo>& 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