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".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
21 #include <badesca.h> // For MDesCArray
22 #include <txtmrtsr.h> // For MRichTextStoreResolver
23 #include <gdi.h> // For MPictureFactory
26 // Help model includes
27 #include "hlpconstants.h"
34 class TCoeHelpContext;
35 class CParaFormatLayer;
36 class CCharFormatLayer;
44 typedef CArrayPtrFlat<CHlpDatabase> CHlpDatabases;
50 typedef CArrayPtrFlat<CHlpFileEntry> CHlpFileList;
53 class MHlpModelObserver
54 /** Client callback inteface to receive events from the help model.
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;
68 // Internal API to handle events reported by the search engine
76 public: // TInt aEvent should be a named enum
77 virtual void HandleDbEventL(TInt aEvent) = 0;
81 // Search types (these should be named, but SC cannot be broken until v7.0
83 /** Defines the search types for use with CHlpModel::SearchL(). */
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(). */
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(). */
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. */
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. */
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. */
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. */
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. */
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
148 // Search progress responses (ditto for naming and scoping)
150 /** Help model search result events*/
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. */
171 /** The search returned an index item list.
173 The list can be retrieved using CHlpModel::LoadListL(). */
175 /** The search did not return an index item list. */
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(). */
187 /** The search did not return a topic. */
189 /** The search is in progress. */
190 EModelSearchInProgress,
191 /** The search has been cancelled. */
195 /** Defines help model zoom sizes. */
199 EHlpZoomStateSmall = 0,
201 EHlpZoomStateMedium = 1,
203 EHlpZoomStateLarge = 2
207 const TInt KHlpModelDefaultNumberOfImagesForV6Point2Files = 1;
208 const TInt KHlpModelMaximumNumberOfImagesForV6Point2Files = 3;
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;
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.
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();
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.
253 inline const TDesC& Title() const
254 /** Gets the item's title.
256 @return Item's title */
259 public: // These should not be public, but I can't break SC (these were inherited from
260 // the previous author.
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
280 ///////////////////////////////////////////////////////////////////////////////////////
281 // ----> MHlpTitleArray
282 ///////////////////////////////////////////////////////////////////////////////////////
283 class MHlpTitleArray : public MDesCArray
284 /** Interface to get a topic ID from an array index.
290 /** Gets a topic ID for the specified index.
292 @param aIndex Index of item to get
294 virtual TUint32 At(TInt aIndex) const = 0;
299 ///////////////////////////////////////////////////////////////////////////////////////
301 ///////////////////////////////////////////////////////////////////////////////////////
302 class CHlpList : public CBase, public MHlpTitleArray
303 /** A list of help items (CHlpItem objects).
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;
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
332 // This is the array of help items that were located as a result of
333 // performing a search.
334 CArrayPtr<CHlpItem>* iList;
339 ///////////////////////////////////////////////////////////////////////////////////////
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.
351 IMPORT_C static CHlpTopic* NewL();
352 IMPORT_C static CHlpTopic* NewLC();
353 IMPORT_C ~CHlpTopic();
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; }
381 friend class CHlpModel;
384 TBuf<KMaxTitleColumn> iTopicTitle;
385 TBuf<KMaxTitleColumn> iCategory;
387 CRichText* iTopicText;
388 CParaFormatLayer* iGlobalParaFormatLayer;
389 CCharFormatLayer* iGlobalCharFormatLayer;
395 ///////////////////////////////////////////////////////////////////////////////////////
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.
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);
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);
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;
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);
464 void NotifyHelpModelDestructionToPictures();
466 private: // Internal search API
467 void DoSearchL(TInt aType, const TDesC& aCriterion);
468 void DoNextSearchL();
469 void ResetReadyForSearch();
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);
488 CHlpModel(RFs& aFs, MHlpModelObserver& aObserver);
491 private: // Member data
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
509 // What was being searched for
512 // What type of search was being performed
515 // Which database are we currently searching
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;
535 ///////////////////////////////////////////////////////////////////////////////////////
536 // ----> CHlpModel (inlines)
537 ///////////////////////////////////////////////////////////////////////////////////////
538 inline TInt CHlpModel::DatabaseCount() const
540 return iDatabases->Count();
542 inline void CHlpModel::SetSearchType(TInt aSearchType)
544 iSearchType = aSearchType;
546 inline CHlpDatabase* CHlpModel::CurrentDatabase() const
548 return iDatabases->At(iCurrentDb);
550 inline TInt CHlpModel::CurrentSearchType() const