// 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 <e32std.h>+
−
#include <badesca.h>	// For MDesCArray+
−
#include <txtmrtsr.h>	// For MRichTextStoreResolver+
−
#include <gdi.h>		// For MPictureFactory+
−
#include <d32dbms.h>+
−
// 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<CHlpDatabase> CHlpDatabases;+
−
+
−
/**+
−
@publishedAll+
−
@released+
−
*/+
−
typedef CArrayPtrFlat<CHlpFileEntry> 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<CHlpItem>* 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<KMaxTitleColumn> iTopicTitle;+
−
	TBuf<KMaxTitleColumn> 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<CHlpPicture>* iPictures;+
−
+
−
	// Array to hold the zoom factors that correspond to each zoom size+
−
	CArrayFix<TInt>* 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+
−
+
−