--- /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 <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
+