|
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 "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 #ifndef __HLPMODEL_H |
|
17 #define __HLPMODEL_H |
|
18 |
|
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> |
|
25 // Help model includes |
|
26 #include "hlpconstants.h" |
|
27 |
|
28 // Classes referenced |
|
29 class CRichText; |
|
30 class CHlpDatabase; |
|
31 class CHlpFileEntry; |
|
32 class CHlpSQLSearch; |
|
33 class TCoeHelpContext; |
|
34 class CParaFormatLayer; |
|
35 class CCharFormatLayer; |
|
36 class CHlpPicture; |
|
37 |
|
38 // Typedefs |
|
39 /** |
|
40 @publishedAll |
|
41 @released |
|
42 */ |
|
43 typedef CArrayPtrFlat<CHlpDatabase> CHlpDatabases; |
|
44 |
|
45 /** |
|
46 @publishedAll |
|
47 @released |
|
48 */ |
|
49 typedef CArrayPtrFlat<CHlpFileEntry> CHlpFileList; |
|
50 #ifdef SYMBIAN_ENABLE_SPLIT_HEADERS |
|
51 /** Maximum Title column. |
|
52 @publishedAll |
|
53 @released |
|
54 */ |
|
55 const TInt KMaxTitleColumn = 120; |
|
56 #endif |
|
57 |
|
58 #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS |
|
59 /** |
|
60 @internalComponent |
|
61 @released |
|
62 */ |
|
63 const TInt KHlpModelDefaultNumberOfImagesForV6Point2Files = 1; |
|
64 /** |
|
65 @internalComponent |
|
66 @released |
|
67 */ |
|
68 const TInt KHlpModelMaximumNumberOfImagesForV6Point2Files = 3; |
|
69 // |
|
70 /** Default zoom factor for small zoom size. |
|
71 @internalComponent |
|
72 @released |
|
73 */ |
|
74 const TInt KHlpModelZoomFactorSmall = 750; |
|
75 /** Default zoom factor for medium zoom size. |
|
76 @internalComponent |
|
77 @released |
|
78 */ |
|
79 const TInt KHlpModelZoomFactorMedium = 1000; |
|
80 /** Default zoom factor for large zoom size. |
|
81 @internalComponent |
|
82 @released |
|
83 */ |
|
84 const TInt KHlpModelZoomFactorLarge = 1250; |
|
85 |
|
86 /** Default zoom factor for medium zoom size as real number. |
|
87 @internalComponent |
|
88 @released |
|
89 */ |
|
90 const TReal KHlpModelDefaultZoomFactorAsRealNumber = 1000.0; |
|
91 |
|
92 #endif //SYMBIAN_ENABLE_SPLIT_HEADERS |
|
93 |
|
94 class MHlpModelObserver |
|
95 /** Client callback inteface to receive events from the help model. |
|
96 @publishedAll |
|
97 @released |
|
98 */ |
|
99 { |
|
100 public: |
|
101 /** Receives a help model event. |
|
102 |
|
103 @param aEvent Help model event. Events are listed in the enums that begin |
|
104 ECategoryListAvailable, and ENoRecordsFound. */ |
|
105 virtual void HandleModelEventL(TInt aEvent) = 0; |
|
106 }; |
|
107 |
|
108 |
|
109 class MHlpDbObserver |
|
110 /** Internal API to handle events reported by the search engine |
|
111 @publishedAll |
|
112 @released |
|
113 */ |
|
114 { |
|
115 public: // TInt aEvent should be a named enum |
|
116 virtual void HandleDbEventL(TInt aEvent) = 0; |
|
117 }; |
|
118 |
|
119 // |
|
120 // Search types (these should be named, but SC cannot be broken until v7.0 |
|
121 // |
|
122 /** Defines the search types for use with CHlpModel::SearchL(). |
|
123 @publishedAll |
|
124 @released |
|
125 */ |
|
126 enum |
|
127 { |
|
128 /** Gets a list of index entries for all help files. |
|
129 |
|
130 Success is indicated by an EIndexListAvailable event; failure by EIndexListNoneFound. |
|
131 The list can be retrieved using CHlpModel::LoadListL(). */ |
|
132 EIndexList, |
|
133 /** Gets a list of categories for all help files. |
|
134 |
|
135 Success is indicated by an ECategoryListAvailable event; failure by ECategoryListNoneFound. |
|
136 The list can be retrieved using CHlpModel::CategoryListL(). */ |
|
137 ECategoryList, |
|
138 /** Gets a list of topics for a specified category. |
|
139 |
|
140 Success is indicated by an ETopicListAvailable event; failure by ETopicListNoneFound. |
|
141 The list can be retrieved using CHlpModel::LoadListL(). */ |
|
142 ETopicListForCategory, |
|
143 /** Gets a list of topics for a specified category UID. |
|
144 |
|
145 Success is indicated by an ETopicListAvailable event; failure by ETopicListNoneFound. |
|
146 The list can be retrieved using CHlpModel::LoadListL(). */ |
|
147 ETopicListForCategoryUID, |
|
148 /** Searches for a topic with the specified help context. |
|
149 |
|
150 A successful search generates an ETopicAvailable event. The topic can then be retrieved |
|
151 using CHlpModel::LoadTopicL(). An unsuccessful search generates an ETopicNotFound event. */ |
|
152 EContextSearch, |
|
153 /** Searches for index entries for the specified help item. |
|
154 |
|
155 A successful search generates an ETopicListAvailable event. The list can then be retrieved |
|
156 using CHlpModel::LoadListL(). An unsuccessful search generates an ETopicListNoneFound event. */ |
|
157 EIndexSearch, |
|
158 /** Searches the topic titles for the specified text. |
|
159 |
|
160 A successful search generates an ESearchListAvailable event. The list can then be |
|
161 retrieved using CHlpModel::LoadListL(). An unsuccessful search generates an |
|
162 ESearchListNoneFound event. */ |
|
163 EQuickSearch, |
|
164 /** Searches the full text of topics for the specified text. |
|
165 |
|
166 A successful search generates an ESearchListAvailable event. The list can then be |
|
167 retrieved using CHlpModel::LoadListL(). An unsuccessful search generates an |
|
168 ESearchListNoneFound event. */ |
|
169 EFullTextSearch, |
|
170 /** Searches for a topic with the specified ID. |
|
171 |
|
172 A successful search generates an ETopicAvailable event. The topic can then be |
|
173 retrieved using CHlpModel::LoadTopicL(). An unsuccessful search generates an |
|
174 ETopicNotFound event. */ |
|
175 ETopicIdSearch |
|
176 }; |
|
177 |
|
178 // |
|
179 // Search progress responses (this should be scoped as members of MHlpModelObserver |
|
180 // and should also be named, but SC cannot be broken until v7.0 |
|
181 // |
|
182 /** Search progress responses |
|
183 @publishedAll |
|
184 @released |
|
185 */ |
|
186 enum |
|
187 { |
|
188 ENoRecordsFound, |
|
189 ESearchInProgress, |
|
190 ESearchComplete |
|
191 }; |
|
192 |
|
193 // |
|
194 // Search progress responses (ditto for naming and scoping) |
|
195 // |
|
196 /** Help model search result events |
|
197 @publishedAll |
|
198 @released |
|
199 */ |
|
200 enum |
|
201 { |
|
202 /** The search returned a category list. |
|
203 |
|
204 The list can be retrieved using CHlpModel::CategoryListL(). */ |
|
205 ECategoryListAvailable, |
|
206 /** The search did not return a category list. */ |
|
207 ECategoryListNoneFound, |
|
208 /** The search returned a results list. |
|
209 |
|
210 The list can be retrieved using CHlpModel::LoadListL(). */ |
|
211 ESearchListAvailable, |
|
212 /** The search did not return a results list. */ |
|
213 ESearchListNoneFound, |
|
214 /** The search returned a topic list. |
|
215 |
|
216 The list can be retrieved using CHlpModel::LoadListL(). */ |
|
217 ETopicListAvailable, // Category expansion |
|
218 /** The search did not return a topic list. */ |
|
219 ETopicListNoneFound, |
|
220 /** The search returned an index item list. |
|
221 |
|
222 The list can be retrieved using CHlpModel::LoadListL(). */ |
|
223 EIndexListAvailable, |
|
224 /** The search did not return an index item list. */ |
|
225 EIndexListNoneFound, |
|
226 /** The search returned a topic list from an index phrase search. |
|
227 |
|
228 The list can be retrieved using CHlpModel::LoadListL(). */ |
|
229 EIndexSearchListAvailable, |
|
230 /** The search did not return a topic list from an index phrase search. */ |
|
231 EIndexSearchListNoneFound, |
|
232 /** The search returned a topic. |
|
233 |
|
234 The topic can be retrieved using CHlpModel::LoadTopicL(). */ |
|
235 ETopicAvailable, |
|
236 /** The search did not return a topic. */ |
|
237 ETopicNotFound, |
|
238 /** The search is in progress. */ |
|
239 EModelSearchInProgress, |
|
240 /** The search has been cancelled. */ |
|
241 EHlpSearchCancelled |
|
242 }; |
|
243 |
|
244 // Constants |
|
245 |
|
246 /** Defines help model zoom sizes. |
|
247 @publishedAll |
|
248 @released |
|
249 */ |
|
250 enum THlpZoomState |
|
251 { |
|
252 /** Small zoom. */ |
|
253 EHlpZoomStateSmall = 0, |
|
254 /** Medium zoom. */ |
|
255 EHlpZoomStateMedium = 1, |
|
256 /** Large zoom. */ |
|
257 EHlpZoomStateLarge = 2 |
|
258 }; |
|
259 |
|
260 |
|
261 class CHlpItem : public CBase |
|
262 /** Encapsulates an individual item in a help file. |
|
263 |
|
264 Note that item IDs are assigned in increasing numerical order by the help |
|
265 compiler and are not unique. Categories and help files are however specified |
|
266 by UID, and so are unique. |
|
267 @publishedAll |
|
268 @released |
|
269 */ |
|
270 { |
|
271 public: |
|
272 static CHlpItem* NewL(const TDesC& aTitle, TUint32 aId, TUid aCategoryId, TUid aHelpFileUid); |
|
273 static CHlpItem* NewLC(const TDesC& aTitle, TUint32 aId, TUid aCategoryId, TUid aHelpFileUid); |
|
274 static CHlpItem* NewLC(const TDesC& aTitle, TUint32 aId, TUid aHelpFileUid); |
|
275 IMPORT_C ~CHlpItem(); |
|
276 |
|
277 public: // Access |
|
278 inline TUid CategoryUid() const |
|
279 /** Gets the item's category ID. |
|
280 |
|
281 @return Category ID */ |
|
282 { return iCategoryUid; } |
|
283 inline TUid HelpFileUid() const |
|
284 /** Gets the item's help file UID. |
|
285 |
|
286 @return Help file UID */ |
|
287 { return iHelpFileUid; } |
|
288 inline TUint32 Id() const |
|
289 /** Gets the item's ID. |
|
290 |
|
291 @return Item's ID */ |
|
292 { return iId; } |
|
293 inline const TDesC& Title() const |
|
294 /** Gets the item's title. |
|
295 |
|
296 @return Item's title */ |
|
297 { return *iTitle; } |
|
298 |
|
299 public: // These should not be public, but I can't break SC (these were inherited from |
|
300 // the previous author. |
|
301 /** Item's title */ |
|
302 HBufC* iTitle; |
|
303 /** Item's ID */ |
|
304 TUint32 iId; |
|
305 |
|
306 private: |
|
307 friend class CHlpList; // Needed for searching |
|
308 CHlpItem(TUint32 aId); |
|
309 CHlpItem(TUint32 aId, TUid aHelpFileUid); |
|
310 CHlpItem(TUint32 aId, TUid aCategoryId, TUid aHelpFileUid); |
|
311 void ConstructL(const TDesC& aTitle); |
|
312 |
|
313 private: // Meta data required for correct restoration of topics |
|
314 TUid iCategoryUid; |
|
315 TUid iHelpFileUid; |
|
316 }; |
|
317 |
|
318 |
|
319 |
|
320 // |
|
321 // ----> MHlpTitleArray |
|
322 // |
|
323 class MHlpTitleArray : public MDesCArray |
|
324 /** Interface to get a topic ID from an array index. |
|
325 @publishedAll |
|
326 @released |
|
327 */ |
|
328 { |
|
329 public: |
|
330 /** Gets a topic ID for the specified index. |
|
331 |
|
332 @param aIndex Index of item to get |
|
333 @return Topic ID */ |
|
334 virtual TUint32 At(TInt aIndex) const = 0; |
|
335 }; |
|
336 |
|
337 |
|
338 |
|
339 // |
|
340 // ----> CHlpList |
|
341 // |
|
342 class CHlpList : public CBase, public MHlpTitleArray |
|
343 /** A list of help items (CHlpItem objects). |
|
344 @publishedAll |
|
345 @released |
|
346 */ |
|
347 { |
|
348 public: // Static construct / destruct |
|
349 IMPORT_C static CHlpList* NewL(); |
|
350 IMPORT_C static CHlpList* NewLC(); |
|
351 IMPORT_C ~CHlpList(); |
|
352 |
|
353 public: // From MDesCArray |
|
354 IMPORT_C TInt MdcaCount() const; |
|
355 IMPORT_C TPtrC MdcaPoint(TInt aIndex) const; |
|
356 |
|
357 public: |
|
358 // 'At' returns topic Id, but this function is next to useless because you can't |
|
359 // uniquely identify a help topic by topic id alone. You need to know 3 things:- |
|
360 // a) topic id, 2) category id, 3) help file uid. This information is all |
|
361 // encapsulated in CHlpItem so help app authors should use 'Item' instead. |
|
362 IMPORT_C TUint32 At(TInt aIndex) const; |
|
363 IMPORT_C CHlpItem* Item(TInt aIndex) const; |
|
364 IMPORT_C TInt Find(TUint32 aId); |
|
365 IMPORT_C void Reset(); |
|
366 IMPORT_C void AppendL(CHlpItem* aItem); |
|
367 |
|
368 private: // 2nd phase constructor |
|
369 void ConstructL(); |
|
370 |
|
371 private: |
|
372 // This is the array of help items that were located as a result of |
|
373 // performing a search. |
|
374 CArrayPtr<CHlpItem>* iList; |
|
375 }; |
|
376 |
|
377 |
|
378 |
|
379 // |
|
380 // ----> CHlpTopic |
|
381 // |
|
382 class CHlpTopic : public CBase |
|
383 /** Encapsulates a help topic. |
|
384 |
|
385 A help topic has text, a title, a category, and paragraph and character formatting. |
|
386 @publishedAll |
|
387 @released |
|
388 */ |
|
389 { |
|
390 public: |
|
391 IMPORT_C static CHlpTopic* NewL(); |
|
392 IMPORT_C static CHlpTopic* NewLC(); |
|
393 IMPORT_C ~CHlpTopic(); |
|
394 |
|
395 public: |
|
396 // This function will not behave as expected in the case where it is used to |
|
397 // restore rich text that includes pictures. Instead, only the text and markup |
|
398 // will be restored. Help App authors should use 'CHlpModel::LoadTopic' instead. |
|
399 // I can't remove this as it would break S&BC. |
|
400 IMPORT_C void RestoreL(RDbView* aView); |
|
401 |
|
402 IMPORT_C CRichText* TopicText(); |
|
403 IMPORT_C TDesC& TopicTitle(); |
|
404 IMPORT_C TDesC& Category(); |
|
405 |
|
406 inline CParaFormatLayer* ParaFormatLayer() const |
|
407 /** Gets the topic paragraph formatting. |
|
408 |
|
409 @return Topic paragraph formatting */ |
|
410 { return iGlobalParaFormatLayer; } |
|
411 inline CCharFormatLayer* CharFormatLayer() const |
|
412 /** Gets the topic character formatting. |
|
413 |
|
414 @return Topic character formatting */ |
|
415 { return iGlobalCharFormatLayer; } |
|
416 |
|
417 private: |
|
418 void ConstructL(); |
|
419 |
|
420 private: |
|
421 friend class CHlpModel; |
|
422 |
|
423 TUint32 iTopicId; |
|
424 TBuf<KMaxTitleColumn> iTopicTitle; |
|
425 TBuf<KMaxTitleColumn> iCategory; |
|
426 |
|
427 CRichText* iTopicText; |
|
428 CParaFormatLayer* iGlobalParaFormatLayer; |
|
429 CCharFormatLayer* iGlobalCharFormatLayer; |
|
430 }; |
|
431 |
|
432 |
|
433 |
|
434 |
|
435 // |
|
436 // ----> CHlpModel |
|
437 // |
|
438 class CHlpModel : public CBase, public MHlpDbObserver, public MPictureFactory, public MRichTextStoreResolver |
|
439 /** Help model interface. |
|
440 |
|
441 It provides functions to search help files in various ways. |
|
442 |
|
443 The interface implements MHlpDbObserver for help database events, and MRichTextStoreResolver |
|
444 and MPictureFactory to obtain pictures from rich text stores. |
|
445 @publishedAll |
|
446 @released |
|
447 */ |
|
448 { |
|
449 public: // Construct / destruct |
|
450 IMPORT_C static CHlpModel* NewL(RFs& aFs, MHlpModelObserver* aObserver); |
|
451 IMPORT_C static CHlpModel* NewLC(RFs& aFs, MHlpModelObserver* aObserver); |
|
452 IMPORT_C ~CHlpModel(); |
|
453 |
|
454 public: // Opens all the help files in \System\Help |
|
455 IMPORT_C void OpenL(); |
|
456 IMPORT_C void CloseL(); |
|
457 |
|
458 public: // Opens specific help files |
|
459 IMPORT_C void OpenFileL(const TDesC& aFileName); |
|
460 IMPORT_C void CloseFileL(const TDesC& aFileName); |
|
461 |
|
462 public: // Specialized searching |
|
463 IMPORT_C void ContextSearchL(TCoeHelpContext& aContext); |
|
464 IMPORT_C void CategoryUIDSearchL(TUid aCategoryUID); |
|
465 IMPORT_C void TopicSearchL(const CHlpItem& aHelpItem); |
|
466 IMPORT_C void IndexSearchL(const CHlpItem& aHelpItem); |
|
467 |
|
468 // Generic searching |
|
469 IMPORT_C void SearchL(TInt aType, TUint32 aId); |
|
470 IMPORT_C void SearchL(TInt aType, HBufC* aCriterion=NULL); |
|
471 IMPORT_C void SearchL(TInt aType, const TDesC& aCriterion); |
|
472 |
|
473 public: // Cancel EFullTextSearch types - will return KErrArgument if not the correct type |
|
474 IMPORT_C TInt CancelSearch(); |
|
475 |
|
476 public: // Assumes that the search has already been performed and that the view is valid |
|
477 IMPORT_C void LoadTopicL(CRichText& aRichText, TDes& aTitle); |
|
478 IMPORT_C void LoadTopicL(CRichText& aRichText); |
|
479 IMPORT_C void LoadTopicL(CHlpTopic* aTopic); |
|
480 IMPORT_C void LoadListL(CHlpList* aList); |
|
481 IMPORT_C void CategoryListL(CDesCArray* aList); |
|
482 |
|
483 public: |
|
484 IMPORT_C void SetZoomSizeL(THlpZoomState aState = EHlpZoomStateMedium); |
|
485 IMPORT_C THlpZoomState ZoomSize() const; |
|
486 IMPORT_C void SetZoomFactors(THlpZoomState aZoomState, TInt aFactor); |
|
487 TInt CurrentZoomFactor() const; |
|
488 void RemoveHelpPicture(CHlpPicture* aHelpPicture); |
|
489 |
|
490 public: // FROM MPictureFactory |
|
491 void NewPictureL(TPictureHeader& aHdr, const CStreamStore& aDeferredPictureStore) const; |
|
492 |
|
493 public: // FROM MRichTextStoreResolver |
|
494 IMPORT_C const CStreamStore& StreamStoreL(TInt aPos) const; |
|
495 |
|
496 public: |
|
497 // Check to see if any of the databases have matching meta data |
|
498 IMPORT_C TInt MatchUidL(TUid aUid); |
|
499 |
|
500 // Replace the current observer with another |
|
501 IMPORT_C void SetObserver(MHlpModelObserver* aObserver); |
|
502 |
|
503 public: |
|
504 void NotifyHelpModelDestructionToPictures(); |
|
505 |
|
506 private: // Internal search API |
|
507 void DoSearchL(TInt aType, const TDesC& aCriterion); |
|
508 void DoNextSearchL(); |
|
509 void ResetReadyForSearch(); |
|
510 void ResetViews(); |
|
511 void SetCriterionL(const TDesC& aCriterion); |
|
512 |
|
513 private: // Event management |
|
514 void HandleDbEventL(TInt aEvent); |
|
515 void ReportEventToObserverL(TInt aEvent); |
|
516 |
|
517 private: // Misc internal functions |
|
518 inline CHlpDatabase* CurrentDatabase() const; |
|
519 inline TInt DatabaseCount() const; |
|
520 inline void SetSearchType(TInt aSearchType); |
|
521 inline TInt CurrentSearchType() const; |
|
522 RDbView* CurrentView() const; |
|
523 TBool DiskPresent(TInt aDrive) const; |
|
524 CHlpFileList* BuildListForDriveLC(TDriveUnit aDrive, RFs& aFsSession) const; |
|
525 static void ResetAndDestroyArrayOfCHlpFileEntry(TAny* aObject); |
|
526 |
|
527 private: |
|
528 CHlpModel(RFs& aFs, MHlpModelObserver& aObserver); |
|
529 void ConstructL(); |
|
530 |
|
531 private: // Member data |
|
532 RFs& iFsSession; |
|
533 |
|
534 // This is required in order to restore rich text pictures from the database |
|
535 CStreamStore* iCurrentRichTextStore; |
|
536 |
|
537 // Creates our SQL string based upon the search type and criteria |
|
538 CHlpSQLSearch* iSearch; |
|
539 |
|
540 // An array of all the help files currently available |
|
541 CHlpDatabases* iDatabases; |
|
542 |
|
543 // Receives help model notifications as various actions are performed |
|
544 MHlpModelObserver* iObserver; |
|
545 |
|
546 // Were any matching results found for this search |
|
547 TBool iFound; |
|
548 |
|
549 // What was being searched for |
|
550 HBufC* iCriterion; |
|
551 |
|
552 // What type of search was being performed |
|
553 TInt iSearchType; |
|
554 |
|
555 // Which database are we currently searching |
|
556 TInt iCurrentDb; |
|
557 |
|
558 // Transient category Uid used when creating category lists |
|
559 TUid iTransientCategoryUid; |
|
560 |
|
561 // What zoom size is used |
|
562 THlpZoomState iZoomSize; |
|
563 |
|
564 // Array to hold the bitmaps that are currently used in the help rich text |
|
565 CArrayPtr<CHlpPicture>* iPictures; |
|
566 |
|
567 // Array to hold the zoom factors that correspond to each zoom size |
|
568 CArrayFix<TInt>* iZoomFactors; |
|
569 }; |
|
570 |
|
571 // |
|
572 // ----> CHlpModel (inlines) |
|
573 // |
|
574 inline TInt CHlpModel::DatabaseCount() const |
|
575 { |
|
576 return iDatabases->Count(); |
|
577 } |
|
578 inline void CHlpModel::SetSearchType(TInt aSearchType) |
|
579 { |
|
580 iSearchType = aSearchType; |
|
581 } |
|
582 inline CHlpDatabase* CHlpModel::CurrentDatabase() const |
|
583 { |
|
584 return iDatabases->At(iCurrentDb); |
|
585 } |
|
586 inline TInt CHlpModel::CurrentSearchType() const |
|
587 { |
|
588 return iSearchType; |
|
589 } |
|
590 |
|
591 |
|
592 |
|
593 #endif |
|
594 |