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