test: epoc32/include/app/hlpmodel.h@e1b950c65cb4

     1 // Copyright (c) 1999-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

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

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    16 #ifndef __HLPMODEL_H

    17 #define __HLPMODEL_H

    19 // System includes

    20 #include <e32std.h>

    21 #include <badesca.h>	// For MDesCArray

    22 #include <txtmrtsr.h>	// For MRichTextStoreResolver

    23 #include <gdi.h>		// For MPictureFactory

    24 #include <d32dbms.h>

    26 // Help model includes

    27 #include "hlpconstants.h"

    29 // Classes referenced

    30 class CRichText;

    31 class CHlpDatabase;

    32 class CHlpFileEntry;

    33 class CHlpSQLSearch;

    34 class TCoeHelpContext;

    35 class CParaFormatLayer;

    36 class CCharFormatLayer;

    37 class CHlpPicture;

    39 // Typedefs

    40 /**

    41 @internalComponent

    42 @released

    43 */

    44 typedef CArrayPtrFlat<CHlpDatabase> CHlpDatabases;

    46 /**

    47 @internalComponent

    48 @released

    49 */

    50 typedef CArrayPtrFlat<CHlpFileEntry> CHlpFileList;

    53 class MHlpModelObserver

    54 /** Client callback inteface to receive events from the help model.

    55 @publishedAll

    56 @released

    57 */

    58 	{

    59 public:

    60 	/** Receives a help model event.

    62 	@param aEvent Help model event. Events are listed in the enums that begin

    63 	ECategoryListAvailable, and ENoRecordsFound. */

    64 	virtual void HandleModelEventL(TInt aEvent) = 0;

    65 	};

    67 //

    68 // Internal API to handle events reported by the search engine

    69 //

    70 class MHlpDbObserver

    71 /**

    72 @internalComponent

    73 @released

    74 */

    75 	{

    76 public: // TInt aEvent should be a named enum

    77 	virtual void HandleDbEventL(TInt aEvent) = 0;

    78 	};

    80 //

    81 // Search types (these should be named, but SC cannot be broken until v7.0

    82 //

    83 /** Defines the search types for use with CHlpModel::SearchL(). */

    84 enum

    85 	{

    86 	/** Gets a list of index entries for all help files.

    88 	Success is indicated by an EIndexListAvailable event; failure by EIndexListNoneFound.

    89 	The list can be retrieved using CHlpModel::LoadListL(). */

    90 	EIndexList,

    91 	/** Gets a list of categories for all help files.

    93 	Success is indicated by an ECategoryListAvailable event; failure by ECategoryListNoneFound.

    94 	The list can be retrieved using CHlpModel::CategoryListL(). */

    95 	ECategoryList,

    96 	/** Gets a list of topics for a specified category.

    98 	Success is indicated by an ETopicListAvailable event; failure by ETopicListNoneFound.

    99 	The list can be retrieved using CHlpModel::LoadListL(). */

   100 	ETopicListForCategory,

   101 	/** Gets a list of topics for a specified category UID.

   103 	Success is indicated by an ETopicListAvailable event; failure by ETopicListNoneFound.

   104 	The list can be retrieved using CHlpModel::LoadListL(). */

   105 	ETopicListForCategoryUID,

   106 	/** Searches for a topic with the specified help context.

   108 	A successful search generates an ETopicAvailable event. The topic can then be retrieved

   109 	using CHlpModel::LoadTopicL(). An unsuccessful search generates an ETopicNotFound event. */

   110 	EContextSearch,

   111 	/** Searches for index entries for the specified help item.

   113 	A successful search generates an ETopicListAvailable event. The list can then be retrieved

   114 	using CHlpModel::LoadListL(). An unsuccessful search generates an ETopicListNoneFound event. */

   115 	EIndexSearch,

   116 	/** Searches the topic titles for the specified text.

   118 	A successful search generates an ESearchListAvailable event. The list can then be

   119 	retrieved using CHlpModel::LoadListL(). An unsuccessful search generates an

   120 	ESearchListNoneFound event. */

   121 	EQuickSearch,

   122 	/** Searches the full text of topics for the specified text.

   124 	A successful search generates an ESearchListAvailable event. The list can then be

   125 	retrieved using CHlpModel::LoadListL(). An unsuccessful search generates an

   126 	ESearchListNoneFound event. */

   127 	EFullTextSearch,

   128 	/** Searches for a topic with the specified ID.

   130 	A successful search generates an ETopicAvailable event. The topic can then be

   131 	retrieved using CHlpModel::LoadTopicL(). An unsuccessful search generates an

   132 	ETopicNotFound event. */

   133 	ETopicIdSearch

   134 	};

   136 //

   137 // Search progress responses (this should be scoped as members of MHlpModelObserver

   138 // and should also be named, but SC cannot be broken until v7.0

   139 //

   140 enum

   141 	{

   142 	ENoRecordsFound,

   143 	ESearchInProgress,

   144 	ESearchComplete

   145 	};

   147 //

   148 // Search progress responses (ditto for naming and scoping)

   149 //

   150 /** Help model search result events*/

   151 enum

   152 	{

   153 	/** The search returned a category list.

   155 	The list can be retrieved using CHlpModel::CategoryListL(). */

   156 	ECategoryListAvailable,

   157 	/** The search did not return a category list. */

   158 	ECategoryListNoneFound,

   159 	/** The search returned a results list.

   161 	The list can be retrieved using CHlpModel::LoadListL(). */

   162 	ESearchListAvailable,

   163 	/** The search did not return a results list. */

   164 	ESearchListNoneFound,

   165 	/** The search returned a topic list.

   167 	The list can be retrieved using CHlpModel::LoadListL(). */

   168 	ETopicListAvailable,		// Category expansion

   169 	/** The search did not return a topic list. */

   170 	ETopicListNoneFound,

   171 	/** The search returned an index item list.

   173 	The list can be retrieved using CHlpModel::LoadListL(). */

   174 	EIndexListAvailable,

   175 	/** The search did not return an index item list. */

   176 	EIndexListNoneFound,

   177 	/** The search returned a topic list from an index phrase search.

   179 	The list can be retrieved using CHlpModel::LoadListL(). */

   180 	EIndexSearchListAvailable,

   181 	/** The search did not return a topic list from an index phrase search. */

   182 	EIndexSearchListNoneFound,

   183 	/** The search returned a topic.

   185 	The topic can be retrieved using CHlpModel::LoadTopicL(). */

   186 	ETopicAvailable,

   187 	/** The search did not return a topic. */

   188 	ETopicNotFound,

   189 	/** The search is in progress. */

   190 	EModelSearchInProgress,

   191 	/** The search has been cancelled. */

   192 	EHlpSearchCancelled

   193 	};

   195 /** Defines help model zoom sizes. */

   196 enum THlpZoomState

   197 	{

   198 	/** Small zoom. */

   199 	EHlpZoomStateSmall = 0,

   200 	/** Medium zoom. */

   201 	EHlpZoomStateMedium = 1,

   202 	/** Large zoom. */

   203 	EHlpZoomStateLarge = 2

   204 	};

   206 // Constants

   207 const TInt KHlpModelDefaultNumberOfImagesForV6Point2Files = 1;

   208 const TInt KHlpModelMaximumNumberOfImagesForV6Point2Files = 3;

   209 //

   210 /** Default zoom factor for small zoom size. */

   211 const TInt KHlpModelZoomFactorSmall = 750;

   212 /** Default zoom factor for medium zoom size. */

   213 const TInt KHlpModelZoomFactorMedium = 1000;

   214 /** Default zoom factor for large zoom size. */

   215 const TInt KHlpModelZoomFactorLarge = 1250;

   216 //

   217 /** Default zoom factor for medium zoom size as real number. */

   218 const TReal KHlpModelDefaultZoomFactorAsRealNumber = 1000.0;

   221 class CHlpItem : public CBase

   222 /** Encapsulates an individual item in a help file.

   224 Note that item IDs are assigned in increasing numerical order by the help

   225 compiler and are not unique. Categories and help files are however specified

   226 by UID, and so are unique.

   227 @publishedAll

   228 @released

   229 */

   230 	{

   231 public:

   232 	static CHlpItem* NewL(const TDesC& aTitle, TUint32 aId, TUid aCategoryId, TUid aHelpFileUid);

   233 	static CHlpItem* NewLC(const TDesC& aTitle, TUint32 aId, TUid aCategoryId, TUid aHelpFileUid);

   234 	static CHlpItem* NewLC(const TDesC& aTitle, TUint32 aId, TUid aHelpFileUid);

   235 	IMPORT_C ~CHlpItem();

   237 public: // Access

   238 	inline TUid CategoryUid() const

   239 	/** Gets the item's category ID.

   241 	@return Category ID */

   242 		{ return iCategoryUid; }

   243 	inline TUid HelpFileUid() const

   244 	/** Gets the item's help file UID.

   246 	@return Help file UID */

   247 		{ return iHelpFileUid; }

   248 	inline TUint32 Id() const

   249 	/** Gets the item's ID.

   251 	@return Item's ID */

   252 		{ return iId; }

   253 	inline const TDesC& Title() const

   254 	/** Gets the item's title.

   256 	@return Item's title */

   257 		{ return *iTitle; }

   259 public: // These should not be public, but I can't break SC (these were inherited from

   260 		// the previous author.

   261 	/** Item's title */

   262 	HBufC* iTitle;

   263 	/** Item's ID */

   264 	TUint32 iId;

   266 private:

   267 	friend class CHlpList; // Needed for searching

   268 	CHlpItem(TUint32 aId);

   269 	CHlpItem(TUint32 aId, TUid aHelpFileUid);

   270 	CHlpItem(TUint32 aId, TUid aCategoryId, TUid aHelpFileUid);

   271 	void ConstructL(const TDesC& aTitle);

   273 private: // Meta data required for correct restoration of topics

   274 	TUid iCategoryUid;

   275 	TUid iHelpFileUid;

   276 	};

   280 ///////////////////////////////////////////////////////////////////////////////////////

   281 // ----> MHlpTitleArray

   282 ///////////////////////////////////////////////////////////////////////////////////////

   283 class MHlpTitleArray : public MDesCArray

   284 /** Interface to get a topic ID from an array index.

   285 @publishedAll

   286 @released

   287 */

   288 	{

   289 public:

   290 	/** Gets a topic ID for the specified index.

   292 	@param aIndex Index of item to get

   293 	@return Topic ID */

   294 	virtual TUint32 At(TInt aIndex) const = 0;

   295 	};

   299 ///////////////////////////////////////////////////////////////////////////////////////

   300 // ----> CHlpList

   301 ///////////////////////////////////////////////////////////////////////////////////////

   302 class CHlpList : public CBase, public MHlpTitleArray

   303 /** A list of help items (CHlpItem objects).

   304 @publishedAll

   305 @released

   306 */

   307 	{

   308 public: // Static construct / destruct

   309 	IMPORT_C static CHlpList* NewL();

   310 	IMPORT_C static CHlpList* NewLC();

   311 	IMPORT_C ~CHlpList();

   313 public: // From MDesCArray

   314 	IMPORT_C TInt MdcaCount() const;

   315 	IMPORT_C TPtrC MdcaPoint(TInt aIndex) const;

   317 public:

   318 	// 'At' returns topic Id, but this function is next to useless because you can't

   319 	// uniquely identify a help topic by topic id alone. You need to know 3 things:-

   320 	// a) topic id, 2) category id, 3) help file uid. This information is all

   321 	// encapsulated in CHlpItem so help app authors should use 'Item' instead.

   322 	IMPORT_C TUint32 At(TInt aIndex) const;

   323 	IMPORT_C CHlpItem* Item(TInt aIndex) const;

   324 	IMPORT_C TInt Find(TUint32 aId);

   325 	IMPORT_C void Reset();

   326 	IMPORT_C void AppendL(CHlpItem* aItem);

   328 private: // 2nd phase constructor

   329 	void ConstructL();

   331 private:

   332 	// This is the array of help items that were located as a result of

   333 	// performing a search.

   334 	CArrayPtr<CHlpItem>* iList;

   335 	};

   339 ///////////////////////////////////////////////////////////////////////////////////////

   340 // ----> CHlpTopic

   341 ///////////////////////////////////////////////////////////////////////////////////////

   342 class CHlpTopic : public CBase

   343 /** Encapsulates a help topic.

   345 A help topic has text, a title, a category, and paragraph and character formatting.

   346 @publishedAll

   347 @released

   348 */

   349 	{

   350 public:

   351 	IMPORT_C static CHlpTopic* NewL();

   352 	IMPORT_C static CHlpTopic* NewLC();

   353 	IMPORT_C ~CHlpTopic();

   355 public:

   356 	// This function will not behave as expected in the case where it is used to

   357 	// restore rich text that includes pictures. Instead, only the text and markup

   358 	// will be restored. Help App authors should use 'CHlpModel::LoadTopic' instead.

   359 	// I can't remove this as it would break S&BC.

   360 	IMPORT_C void RestoreL(RDbView* aView);

   362 	IMPORT_C CRichText* TopicText();

   363 	IMPORT_C TDesC& TopicTitle();

   364 	IMPORT_C TDesC& Category();

   366 	inline CParaFormatLayer* ParaFormatLayer() const

   367 	/** Gets the topic paragraph formatting.

   369 	@return Topic paragraph formatting */

   370 		{ return iGlobalParaFormatLayer; }

   371 	inline CCharFormatLayer* CharFormatLayer() const

   372 	/** Gets the topic character formatting.

   374 	@return Topic character formatting */

   375 		{ return iGlobalCharFormatLayer; }

   377 private:

   378 	void ConstructL();

   380 private:

   381 	friend class CHlpModel;

   383 	TUint32 iTopicId;

   384 	TBuf<KMaxTitleColumn> iTopicTitle;

   385 	TBuf<KMaxTitleColumn> iCategory;

   387 	CRichText* iTopicText;

   388 	CParaFormatLayer* iGlobalParaFormatLayer;

   389 	CCharFormatLayer* iGlobalCharFormatLayer;

   390 	};

   395 ///////////////////////////////////////////////////////////////////////////////////////

   396 // ----> CHlpModel

   397 ///////////////////////////////////////////////////////////////////////////////////////

   398 class CHlpModel : public CBase, public MHlpDbObserver, public MPictureFactory, public MRichTextStoreResolver

   399 /** Help model interface.

   401 It provides functions to search help files in various ways.

   403 The interface implements MHlpDbObserver for help database events, and MRichTextStoreResolver

   404 and MPictureFactory to obtain pictures from rich text stores.

   405 @publishedAll

   406 @released

   407 */

   408 	{

   409 public: // Construct / destruct

   410 	IMPORT_C static CHlpModel* NewL(RFs& aFs, MHlpModelObserver* aObserver);

   411 	IMPORT_C static CHlpModel* NewLC(RFs& aFs, MHlpModelObserver* aObserver);

   412 	IMPORT_C ~CHlpModel();

   414 public:	// Opens all the help files in \System\Help

   415 	IMPORT_C void OpenL();

   416 	IMPORT_C void CloseL();

   418 public: // Opens specific help files

   419 	IMPORT_C void OpenFileL(const TDesC& aFileName);

   420 	IMPORT_C void CloseFileL(const TDesC& aFileName);

   422 public: // Specialized searching

   423 	IMPORT_C void ContextSearchL(TCoeHelpContext& aContext);

   424 	IMPORT_C void CategoryUIDSearchL(TUid aCategoryUID);

   425 	IMPORT_C void TopicSearchL(const CHlpItem& aHelpItem);

   426 	IMPORT_C void IndexSearchL(const CHlpItem& aHelpItem);

   428 		// Generic searching

   429 	IMPORT_C void SearchL(TInt aType, TUint32 aId);

   430 	IMPORT_C void SearchL(TInt aType, HBufC* aCriterion=NULL);

   431 	IMPORT_C void SearchL(TInt aType, const TDesC& aCriterion);

   433 public: // Cancel EFullTextSearch types - will return KErrArgument if not the correct type

   434 	IMPORT_C TInt CancelSearch();

   436 public: // Assumes that the search has already been performed and that the view is valid

   437 	IMPORT_C void LoadTopicL(CRichText& aRichText, TDes& aTitle);

   438 	IMPORT_C void LoadTopicL(CRichText& aRichText);

   439 	IMPORT_C void LoadTopicL(CHlpTopic* aTopic);

   440 	IMPORT_C void LoadListL(CHlpList* aList);

   441 	IMPORT_C void CategoryListL(CDesCArray* aList);

   443 public:

   444 	IMPORT_C void SetZoomSizeL(THlpZoomState aState = EHlpZoomStateMedium);

   445 	IMPORT_C THlpZoomState ZoomSize() const;

   446 	IMPORT_C void SetZoomFactors(THlpZoomState aZoomState, TInt aFactor);

   447 	TInt CurrentZoomFactor() const;

   448 	void RemoveHelpPicture(CHlpPicture* aHelpPicture);

   450 public: // FROM MPictureFactory

   451 	void NewPictureL(TPictureHeader& aHdr, const CStreamStore& aDeferredPictureStore) const;

   453 public: // FROM MRichTextStoreResolver

   454 	IMPORT_C const CStreamStore& StreamStoreL(TInt aPos) const;

   456 public:

   457 	// Check to see if any of the databases have matching meta data

   458 	IMPORT_C TInt MatchUidL(TUid aUid);

   460 	// Replace the current observer with another

   461 	IMPORT_C void SetObserver(MHlpModelObserver* aObserver);

   463 public:

   464 	void NotifyHelpModelDestructionToPictures();

   466 private: // Internal search API

   467 	void DoSearchL(TInt aType, const TDesC& aCriterion);

   468 	void DoNextSearchL();

   469 	void ResetReadyForSearch();

   470 	void ResetViews();

   471 	void SetCriterionL(const TDesC& aCriterion);

   473 private: // Event management

   474 	void HandleDbEventL(TInt aEvent);

   475 	void ReportEventToObserverL(TInt aEvent);

   477 private: // Misc internal functions

   478 	inline CHlpDatabase* CurrentDatabase() const;

   479 	inline TInt DatabaseCount() const;

   480 	inline void SetSearchType(TInt aSearchType);

   481 	inline TInt CurrentSearchType() const;

   482 	RDbView* CurrentView() const;

   483 	TBool DiskPresent(TInt aDrive) const;

   484 	CHlpFileList* BuildListForDriveLC(TDriveUnit aDrive, RFs& aFsSession) const;

   485 	static void ResetAndDestroyArrayOfCHlpFileEntry(TAny* aObject);

   487 private:

   488 	CHlpModel(RFs& aFs, MHlpModelObserver& aObserver);

   489 	void ConstructL();

   491 private: // Member data

   492 	RFs& iFsSession;

   494 	// This is required in order to restore rich text pictures from the database

   495 	CStreamStore* iCurrentRichTextStore;

   497 	// Creates our SQL string based upon the search type and criteria

   498 	CHlpSQLSearch* iSearch;

   500 	// An array of all the help files currently available

   501 	CHlpDatabases* iDatabases;

   503 	// Receives help model notifications as various actions are performed

   504 	MHlpModelObserver* iObserver;

   506 	// Were any matching results found for this search

   507 	TBool iFound;

   509 	// What was being searched for

   510 	HBufC* iCriterion;

   512 	// What type of search was being performed

   513 	TInt iSearchType;

   515 	// Which database are we currently searching

   516 	TInt iCurrentDb;

   518 	// Transient category Uid used when creating category lists

   519 	TUid iTransientCategoryUid;

   521 	// What zoom size is used

   522 	THlpZoomState iZoomSize;

   524 	// Array to hold the bitmaps that are currently used in the help rich text

   525 	CArrayPtr<CHlpPicture>* iPictures;

   527 	// Array to hold the zoom factors that correspond to each zoom size

   528 	CArrayFix<TInt>* iZoomFactors;

   529 	};

   535 ///////////////////////////////////////////////////////////////////////////////////////

   536 // ----> CHlpModel (inlines)

   537 ///////////////////////////////////////////////////////////////////////////////////////

   538 inline TInt CHlpModel::DatabaseCount() const

   539 	{

   540 	return iDatabases->Count();

   541 	}

   542 inline void CHlpModel::SetSearchType(TInt aSearchType)

   543 	{

   544 	iSearchType = aSearchType;

   545 	}

   546 inline CHlpDatabase* CHlpModel::CurrentDatabase() const

   547 	{

   548 	return iDatabases->At(iCurrentDb);

   549 	}

   550 inline TInt CHlpModel::CurrentSearchType() const

   551 	{

   552 	return iSearchType;

   553 	}

   557 #endif

author	William Roberts <williamr@symbian.org>
	Wed, 31 Mar 2010 12:27:01 +0100
branch	Symbian2
changeset 3	e1b950c65cb4
parent 2	epoc32/include/hlpmodel.h@2fe1408b6811
child 4	837f303aceeb
permissions	-rw-r--r--