williamr@2: // Copyright (c) 1999-2009 Nokia Corporation and/or its subsidiary(-ies). williamr@2: // All rights reserved. williamr@2: // This component and the accompanying materials are made available williamr@4: // under the terms of "Eclipse Public License v1.0" williamr@2: // which accompanies this distribution, and is available williamr@4: // at the URL "http://www.eclipse.org/legal/epl-v10.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: // williamr@2: williamr@2: #ifndef __HLPMODEL_H williamr@2: #define __HLPMODEL_H williamr@2: williamr@2: // System includes williamr@2: #include williamr@2: #include // For MDesCArray williamr@2: #include // For MRichTextStoreResolver williamr@2: #include // For MPictureFactory williamr@2: #include williamr@2: // Help model includes williamr@2: #include "hlpconstants.h" williamr@2: williamr@2: // Classes referenced williamr@2: class CRichText; williamr@2: class CHlpDatabase; williamr@2: class CHlpFileEntry; williamr@2: class CHlpSQLSearch; williamr@2: class TCoeHelpContext; williamr@2: class CParaFormatLayer; williamr@2: class CCharFormatLayer; williamr@2: class CHlpPicture; williamr@2: williamr@2: // Typedefs williamr@2: /** williamr@4: @publishedAll williamr@2: @released williamr@2: */ williamr@2: typedef CArrayPtrFlat CHlpDatabases; williamr@2: williamr@2: /** williamr@4: @publishedAll williamr@4: @released williamr@4: */ williamr@4: typedef CArrayPtrFlat CHlpFileList; williamr@4: #ifdef SYMBIAN_ENABLE_SPLIT_HEADERS williamr@4: /** Maximum Title column. williamr@4: @publishedAll williamr@4: @released williamr@4: */ williamr@4: const TInt KMaxTitleColumn = 120; williamr@4: #endif williamr@4: williamr@4: #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS williamr@4: /** williamr@2: @internalComponent williamr@2: @released williamr@2: */ williamr@4: const TInt KHlpModelDefaultNumberOfImagesForV6Point2Files = 1; williamr@4: /** williamr@4: @internalComponent williamr@4: @released williamr@4: */ williamr@4: const TInt KHlpModelMaximumNumberOfImagesForV6Point2Files = 3; williamr@4: // williamr@4: /** Default zoom factor for small zoom size. williamr@4: @internalComponent williamr@4: @released williamr@4: */ williamr@4: const TInt KHlpModelZoomFactorSmall = 750; williamr@4: /** Default zoom factor for medium zoom size. williamr@4: @internalComponent williamr@4: @released williamr@4: */ williamr@4: const TInt KHlpModelZoomFactorMedium = 1000; williamr@4: /** Default zoom factor for large zoom size. williamr@4: @internalComponent williamr@4: @released williamr@4: */ williamr@4: const TInt KHlpModelZoomFactorLarge = 1250; williamr@2: williamr@4: /** Default zoom factor for medium zoom size as real number. williamr@4: @internalComponent williamr@4: @released williamr@4: */ williamr@4: const TReal KHlpModelDefaultZoomFactorAsRealNumber = 1000.0; williamr@4: williamr@4: #endif //SYMBIAN_ENABLE_SPLIT_HEADERS williamr@2: williamr@2: class MHlpModelObserver williamr@2: /** Client callback inteface to receive events from the help model. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: { williamr@2: public: williamr@2: /** Receives a help model event. williamr@2: williamr@2: @param aEvent Help model event. Events are listed in the enums that begin williamr@2: ECategoryListAvailable, and ENoRecordsFound. */ williamr@2: virtual void HandleModelEventL(TInt aEvent) = 0; williamr@2: }; williamr@2: williamr@4: williamr@2: class MHlpDbObserver williamr@4: /** Internal API to handle events reported by the search engine williamr@4: @publishedAll williamr@2: @released williamr@2: */ williamr@2: { williamr@2: public: // TInt aEvent should be a named enum williamr@2: virtual void HandleDbEventL(TInt aEvent) = 0; williamr@2: }; williamr@2: williamr@2: // williamr@2: // Search types (these should be named, but SC cannot be broken until v7.0 williamr@2: // williamr@4: /** Defines the search types for use with CHlpModel::SearchL(). williamr@4: @publishedAll williamr@4: @released williamr@4: */ williamr@2: enum williamr@2: { williamr@2: /** Gets a list of index entries for all help files. williamr@2: williamr@2: Success is indicated by an EIndexListAvailable event; failure by EIndexListNoneFound. williamr@2: The list can be retrieved using CHlpModel::LoadListL(). */ williamr@2: EIndexList, williamr@2: /** Gets a list of categories for all help files. williamr@2: williamr@2: Success is indicated by an ECategoryListAvailable event; failure by ECategoryListNoneFound. williamr@2: The list can be retrieved using CHlpModel::CategoryListL(). */ williamr@2: ECategoryList, williamr@2: /** Gets a list of topics for a specified category. williamr@2: williamr@2: Success is indicated by an ETopicListAvailable event; failure by ETopicListNoneFound. williamr@2: The list can be retrieved using CHlpModel::LoadListL(). */ williamr@2: ETopicListForCategory, williamr@2: /** Gets a list of topics for a specified category UID. williamr@2: williamr@2: Success is indicated by an ETopicListAvailable event; failure by ETopicListNoneFound. williamr@2: The list can be retrieved using CHlpModel::LoadListL(). */ williamr@2: ETopicListForCategoryUID, williamr@2: /** Searches for a topic with the specified help context. williamr@2: williamr@2: A successful search generates an ETopicAvailable event. The topic can then be retrieved williamr@2: using CHlpModel::LoadTopicL(). An unsuccessful search generates an ETopicNotFound event. */ williamr@2: EContextSearch, williamr@2: /** Searches for index entries for the specified help item. williamr@2: williamr@2: A successful search generates an ETopicListAvailable event. The list can then be retrieved williamr@2: using CHlpModel::LoadListL(). An unsuccessful search generates an ETopicListNoneFound event. */ williamr@2: EIndexSearch, williamr@2: /** Searches the topic titles for the specified text. williamr@2: williamr@2: A successful search generates an ESearchListAvailable event. The list can then be williamr@2: retrieved using CHlpModel::LoadListL(). An unsuccessful search generates an williamr@2: ESearchListNoneFound event. */ williamr@2: EQuickSearch, williamr@2: /** Searches the full text of topics for the specified text. williamr@2: williamr@2: A successful search generates an ESearchListAvailable event. The list can then be williamr@2: retrieved using CHlpModel::LoadListL(). An unsuccessful search generates an williamr@2: ESearchListNoneFound event. */ williamr@2: EFullTextSearch, williamr@2: /** Searches for a topic with the specified ID. williamr@2: williamr@2: A successful search generates an ETopicAvailable event. The topic can then be williamr@2: retrieved using CHlpModel::LoadTopicL(). An unsuccessful search generates an williamr@2: ETopicNotFound event. */ williamr@2: ETopicIdSearch williamr@2: }; williamr@2: williamr@2: // williamr@2: // Search progress responses (this should be scoped as members of MHlpModelObserver williamr@2: // and should also be named, but SC cannot be broken until v7.0 williamr@2: // williamr@4: /** Search progress responses williamr@4: @publishedAll williamr@4: @released williamr@4: */ williamr@2: enum williamr@2: { williamr@2: ENoRecordsFound, williamr@2: ESearchInProgress, williamr@2: ESearchComplete williamr@2: }; williamr@2: williamr@2: // williamr@2: // Search progress responses (ditto for naming and scoping) williamr@2: // williamr@4: /** Help model search result events williamr@4: @publishedAll williamr@4: @released williamr@4: */ williamr@2: enum williamr@2: { williamr@2: /** The search returned a category list. williamr@2: williamr@2: The list can be retrieved using CHlpModel::CategoryListL(). */ williamr@2: ECategoryListAvailable, williamr@2: /** The search did not return a category list. */ williamr@2: ECategoryListNoneFound, williamr@2: /** The search returned a results list. williamr@2: williamr@2: The list can be retrieved using CHlpModel::LoadListL(). */ williamr@2: ESearchListAvailable, williamr@2: /** The search did not return a results list. */ williamr@2: ESearchListNoneFound, williamr@2: /** The search returned a topic list. williamr@2: williamr@2: The list can be retrieved using CHlpModel::LoadListL(). */ williamr@2: ETopicListAvailable, // Category expansion williamr@2: /** The search did not return a topic list. */ williamr@2: ETopicListNoneFound, williamr@2: /** The search returned an index item list. williamr@2: williamr@2: The list can be retrieved using CHlpModel::LoadListL(). */ williamr@2: EIndexListAvailable, williamr@2: /** The search did not return an index item list. */ williamr@2: EIndexListNoneFound, williamr@2: /** The search returned a topic list from an index phrase search. williamr@2: williamr@2: The list can be retrieved using CHlpModel::LoadListL(). */ williamr@2: EIndexSearchListAvailable, williamr@2: /** The search did not return a topic list from an index phrase search. */ williamr@2: EIndexSearchListNoneFound, williamr@2: /** The search returned a topic. williamr@2: williamr@2: The topic can be retrieved using CHlpModel::LoadTopicL(). */ williamr@2: ETopicAvailable, williamr@2: /** The search did not return a topic. */ williamr@2: ETopicNotFound, williamr@2: /** The search is in progress. */ williamr@2: EModelSearchInProgress, williamr@2: /** The search has been cancelled. */ williamr@2: EHlpSearchCancelled williamr@2: }; williamr@4: williamr@4: // Constants williamr@2: williamr@4: /** Defines help model zoom sizes. williamr@4: @publishedAll williamr@4: @released williamr@4: */ williamr@2: enum THlpZoomState williamr@2: { williamr@2: /** Small zoom. */ williamr@2: EHlpZoomStateSmall = 0, williamr@2: /** Medium zoom. */ williamr@2: EHlpZoomStateMedium = 1, williamr@2: /** Large zoom. */ williamr@2: EHlpZoomStateLarge = 2 williamr@2: }; williamr@2: williamr@2: williamr@2: class CHlpItem : public CBase williamr@2: /** Encapsulates an individual item in a help file. williamr@2: williamr@2: Note that item IDs are assigned in increasing numerical order by the help williamr@2: compiler and are not unique. Categories and help files are however specified williamr@2: by UID, and so are unique. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: { williamr@2: public: williamr@2: static CHlpItem* NewL(const TDesC& aTitle, TUint32 aId, TUid aCategoryId, TUid aHelpFileUid); williamr@2: static CHlpItem* NewLC(const TDesC& aTitle, TUint32 aId, TUid aCategoryId, TUid aHelpFileUid); williamr@2: static CHlpItem* NewLC(const TDesC& aTitle, TUint32 aId, TUid aHelpFileUid); williamr@2: IMPORT_C ~CHlpItem(); williamr@2: williamr@2: public: // Access williamr@2: inline TUid CategoryUid() const williamr@2: /** Gets the item's category ID. williamr@2: williamr@2: @return Category ID */ williamr@2: { return iCategoryUid; } williamr@2: inline TUid HelpFileUid() const williamr@2: /** Gets the item's help file UID. williamr@2: williamr@2: @return Help file UID */ williamr@2: { return iHelpFileUid; } williamr@2: inline TUint32 Id() const williamr@2: /** Gets the item's ID. williamr@2: williamr@2: @return Item's ID */ williamr@2: { return iId; } williamr@2: inline const TDesC& Title() const williamr@2: /** Gets the item's title. williamr@2: williamr@2: @return Item's title */ williamr@2: { return *iTitle; } williamr@2: williamr@2: public: // These should not be public, but I can't break SC (these were inherited from williamr@2: // the previous author. williamr@2: /** Item's title */ williamr@2: HBufC* iTitle; williamr@2: /** Item's ID */ williamr@2: TUint32 iId; williamr@2: williamr@2: private: williamr@2: friend class CHlpList; // Needed for searching williamr@2: CHlpItem(TUint32 aId); williamr@2: CHlpItem(TUint32 aId, TUid aHelpFileUid); williamr@2: CHlpItem(TUint32 aId, TUid aCategoryId, TUid aHelpFileUid); williamr@2: void ConstructL(const TDesC& aTitle); williamr@2: williamr@2: private: // Meta data required for correct restoration of topics williamr@2: TUid iCategoryUid; williamr@2: TUid iHelpFileUid; williamr@2: }; williamr@2: williamr@2: williamr@2: williamr@4: // williamr@2: // ----> MHlpTitleArray williamr@4: // williamr@2: class MHlpTitleArray : public MDesCArray williamr@2: /** Interface to get a topic ID from an array index. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: { williamr@2: public: williamr@2: /** Gets a topic ID for the specified index. williamr@2: williamr@2: @param aIndex Index of item to get williamr@2: @return Topic ID */ williamr@2: virtual TUint32 At(TInt aIndex) const = 0; williamr@2: }; williamr@2: williamr@2: williamr@2: williamr@4: // williamr@2: // ----> CHlpList williamr@4: // williamr@2: class CHlpList : public CBase, public MHlpTitleArray williamr@2: /** A list of help items (CHlpItem objects). williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: { williamr@2: public: // Static construct / destruct williamr@2: IMPORT_C static CHlpList* NewL(); williamr@2: IMPORT_C static CHlpList* NewLC(); williamr@2: IMPORT_C ~CHlpList(); williamr@2: williamr@2: public: // From MDesCArray williamr@2: IMPORT_C TInt MdcaCount() const; williamr@2: IMPORT_C TPtrC MdcaPoint(TInt aIndex) const; williamr@2: williamr@2: public: williamr@2: // 'At' returns topic Id, but this function is next to useless because you can't williamr@2: // uniquely identify a help topic by topic id alone. You need to know 3 things:- williamr@2: // a) topic id, 2) category id, 3) help file uid. This information is all williamr@2: // encapsulated in CHlpItem so help app authors should use 'Item' instead. williamr@2: IMPORT_C TUint32 At(TInt aIndex) const; williamr@2: IMPORT_C CHlpItem* Item(TInt aIndex) const; williamr@2: IMPORT_C TInt Find(TUint32 aId); williamr@2: IMPORT_C void Reset(); williamr@2: IMPORT_C void AppendL(CHlpItem* aItem); williamr@2: williamr@2: private: // 2nd phase constructor williamr@2: void ConstructL(); williamr@2: williamr@2: private: williamr@2: // This is the array of help items that were located as a result of williamr@2: // performing a search. williamr@2: CArrayPtr* iList; williamr@2: }; williamr@2: williamr@2: williamr@2: williamr@4: // williamr@2: // ----> CHlpTopic williamr@4: // williamr@2: class CHlpTopic : public CBase williamr@2: /** Encapsulates a help topic. williamr@2: williamr@2: A help topic has text, a title, a category, and paragraph and character formatting. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: { williamr@2: public: williamr@2: IMPORT_C static CHlpTopic* NewL(); williamr@2: IMPORT_C static CHlpTopic* NewLC(); williamr@2: IMPORT_C ~CHlpTopic(); williamr@2: williamr@2: public: williamr@2: // This function will not behave as expected in the case where it is used to williamr@2: // restore rich text that includes pictures. Instead, only the text and markup williamr@2: // will be restored. Help App authors should use 'CHlpModel::LoadTopic' instead. williamr@2: // I can't remove this as it would break S&BC. williamr@2: IMPORT_C void RestoreL(RDbView* aView); williamr@2: williamr@2: IMPORT_C CRichText* TopicText(); williamr@2: IMPORT_C TDesC& TopicTitle(); williamr@2: IMPORT_C TDesC& Category(); williamr@2: williamr@2: inline CParaFormatLayer* ParaFormatLayer() const williamr@2: /** Gets the topic paragraph formatting. williamr@2: williamr@2: @return Topic paragraph formatting */ williamr@2: { return iGlobalParaFormatLayer; } williamr@2: inline CCharFormatLayer* CharFormatLayer() const williamr@2: /** Gets the topic character formatting. williamr@2: williamr@2: @return Topic character formatting */ williamr@2: { return iGlobalCharFormatLayer; } williamr@2: williamr@2: private: williamr@2: void ConstructL(); williamr@2: williamr@2: private: williamr@2: friend class CHlpModel; williamr@2: williamr@2: TUint32 iTopicId; williamr@2: TBuf iTopicTitle; williamr@2: TBuf iCategory; williamr@2: williamr@2: CRichText* iTopicText; williamr@2: CParaFormatLayer* iGlobalParaFormatLayer; williamr@2: CCharFormatLayer* iGlobalCharFormatLayer; williamr@2: }; williamr@2: williamr@2: williamr@2: williamr@2: williamr@4: // williamr@2: // ----> CHlpModel williamr@4: // williamr@2: class CHlpModel : public CBase, public MHlpDbObserver, public MPictureFactory, public MRichTextStoreResolver williamr@2: /** Help model interface. williamr@2: williamr@2: It provides functions to search help files in various ways. williamr@2: williamr@2: The interface implements MHlpDbObserver for help database events, and MRichTextStoreResolver williamr@2: and MPictureFactory to obtain pictures from rich text stores. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: { williamr@2: public: // Construct / destruct williamr@2: IMPORT_C static CHlpModel* NewL(RFs& aFs, MHlpModelObserver* aObserver); williamr@2: IMPORT_C static CHlpModel* NewLC(RFs& aFs, MHlpModelObserver* aObserver); williamr@2: IMPORT_C ~CHlpModel(); williamr@2: williamr@2: public: // Opens all the help files in \System\Help williamr@2: IMPORT_C void OpenL(); williamr@2: IMPORT_C void CloseL(); williamr@2: williamr@2: public: // Opens specific help files williamr@2: IMPORT_C void OpenFileL(const TDesC& aFileName); williamr@2: IMPORT_C void CloseFileL(const TDesC& aFileName); williamr@2: williamr@2: public: // Specialized searching williamr@2: IMPORT_C void ContextSearchL(TCoeHelpContext& aContext); williamr@2: IMPORT_C void CategoryUIDSearchL(TUid aCategoryUID); williamr@2: IMPORT_C void TopicSearchL(const CHlpItem& aHelpItem); williamr@2: IMPORT_C void IndexSearchL(const CHlpItem& aHelpItem); williamr@2: williamr@2: // Generic searching williamr@2: IMPORT_C void SearchL(TInt aType, TUint32 aId); williamr@2: IMPORT_C void SearchL(TInt aType, HBufC* aCriterion=NULL); williamr@2: IMPORT_C void SearchL(TInt aType, const TDesC& aCriterion); williamr@2: williamr@2: public: // Cancel EFullTextSearch types - will return KErrArgument if not the correct type williamr@2: IMPORT_C TInt CancelSearch(); williamr@2: williamr@2: public: // Assumes that the search has already been performed and that the view is valid williamr@2: IMPORT_C void LoadTopicL(CRichText& aRichText, TDes& aTitle); williamr@2: IMPORT_C void LoadTopicL(CRichText& aRichText); williamr@2: IMPORT_C void LoadTopicL(CHlpTopic* aTopic); williamr@2: IMPORT_C void LoadListL(CHlpList* aList); williamr@2: IMPORT_C void CategoryListL(CDesCArray* aList); williamr@2: williamr@2: public: williamr@2: IMPORT_C void SetZoomSizeL(THlpZoomState aState = EHlpZoomStateMedium); williamr@2: IMPORT_C THlpZoomState ZoomSize() const; williamr@2: IMPORT_C void SetZoomFactors(THlpZoomState aZoomState, TInt aFactor); williamr@2: TInt CurrentZoomFactor() const; williamr@2: void RemoveHelpPicture(CHlpPicture* aHelpPicture); williamr@2: williamr@2: public: // FROM MPictureFactory williamr@2: void NewPictureL(TPictureHeader& aHdr, const CStreamStore& aDeferredPictureStore) const; williamr@2: williamr@2: public: // FROM MRichTextStoreResolver williamr@2: IMPORT_C const CStreamStore& StreamStoreL(TInt aPos) const; williamr@2: williamr@2: public: williamr@2: // Check to see if any of the databases have matching meta data williamr@2: IMPORT_C TInt MatchUidL(TUid aUid); williamr@2: williamr@2: // Replace the current observer with another williamr@2: IMPORT_C void SetObserver(MHlpModelObserver* aObserver); williamr@2: williamr@2: public: williamr@2: void NotifyHelpModelDestructionToPictures(); williamr@2: williamr@2: private: // Internal search API williamr@2: void DoSearchL(TInt aType, const TDesC& aCriterion); williamr@2: void DoNextSearchL(); williamr@2: void ResetReadyForSearch(); williamr@2: void ResetViews(); williamr@2: void SetCriterionL(const TDesC& aCriterion); williamr@2: williamr@2: private: // Event management williamr@2: void HandleDbEventL(TInt aEvent); williamr@2: void ReportEventToObserverL(TInt aEvent); williamr@2: williamr@2: private: // Misc internal functions williamr@2: inline CHlpDatabase* CurrentDatabase() const; williamr@2: inline TInt DatabaseCount() const; williamr@2: inline void SetSearchType(TInt aSearchType); williamr@2: inline TInt CurrentSearchType() const; williamr@2: RDbView* CurrentView() const; williamr@2: TBool DiskPresent(TInt aDrive) const; williamr@2: CHlpFileList* BuildListForDriveLC(TDriveUnit aDrive, RFs& aFsSession) const; williamr@2: static void ResetAndDestroyArrayOfCHlpFileEntry(TAny* aObject); williamr@2: williamr@2: private: williamr@2: CHlpModel(RFs& aFs, MHlpModelObserver& aObserver); williamr@2: void ConstructL(); williamr@2: williamr@2: private: // Member data williamr@2: RFs& iFsSession; williamr@2: williamr@2: // This is required in order to restore rich text pictures from the database williamr@2: CStreamStore* iCurrentRichTextStore; williamr@2: williamr@2: // Creates our SQL string based upon the search type and criteria williamr@2: CHlpSQLSearch* iSearch; williamr@2: williamr@2: // An array of all the help files currently available williamr@2: CHlpDatabases* iDatabases; williamr@2: williamr@2: // Receives help model notifications as various actions are performed williamr@2: MHlpModelObserver* iObserver; williamr@2: williamr@2: // Were any matching results found for this search williamr@2: TBool iFound; williamr@2: williamr@2: // What was being searched for williamr@2: HBufC* iCriterion; williamr@2: williamr@2: // What type of search was being performed williamr@2: TInt iSearchType; williamr@2: williamr@2: // Which database are we currently searching williamr@2: TInt iCurrentDb; williamr@2: williamr@2: // Transient category Uid used when creating category lists williamr@2: TUid iTransientCategoryUid; williamr@2: williamr@2: // What zoom size is used williamr@2: THlpZoomState iZoomSize; williamr@2: williamr@2: // Array to hold the bitmaps that are currently used in the help rich text williamr@2: CArrayPtr* iPictures; williamr@2: williamr@2: // Array to hold the zoom factors that correspond to each zoom size williamr@2: CArrayFix* iZoomFactors; williamr@2: }; williamr@2: williamr@4: // williamr@2: // ----> CHlpModel (inlines) williamr@4: // williamr@2: inline TInt CHlpModel::DatabaseCount() const williamr@2: { williamr@2: return iDatabases->Count(); williamr@2: } williamr@2: inline void CHlpModel::SetSearchType(TInt aSearchType) williamr@2: { williamr@2: iSearchType = aSearchType; williamr@2: } williamr@2: inline CHlpDatabase* CHlpModel::CurrentDatabase() const williamr@2: { williamr@2: return iDatabases->At(iCurrentDb); williamr@2: } williamr@2: inline TInt CHlpModel::CurrentSearchType() const williamr@2: { williamr@2: return iSearchType; williamr@2: } williamr@2: williamr@2: williamr@2: williamr@2: #endif williamr@4: