1 hlpmodel.h |
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 // |
|
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 |
|
26 // Help model includes |
|
27 #include "hlpconstants.h" |
|
28 |
|
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; |
|
38 |
|
39 // Typedefs |
|
40 /** |
|
41 @internalComponent |
|
42 @released |
|
43 */ |
|
44 typedef CArrayPtrFlat<CHlpDatabase> CHlpDatabases; |
|
45 |
|
46 /** |
|
47 @internalComponent |
|
48 @released |
|
49 */ |
|
50 typedef CArrayPtrFlat<CHlpFileEntry> CHlpFileList; |
|
51 |
|
52 |
|
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. |
|
61 |
|
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 }; |
|
66 |
|
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 }; |
|
79 |
|
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. |
|
87 |
|
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. |
|
92 |
|
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. |
|
97 |
|
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. |
|
102 |
|
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. |
|
107 |
|
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. |
|
112 |
|
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. |
|
117 |
|
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. |
|
123 |
|
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. |
|
129 |
|
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 }; |
|
135 |
|
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 }; |
|
146 |
|
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. |
|
154 |
|
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. |
|
160 |
|
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. |
|
166 |
|
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. |
|
172 |
|
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. |
|
178 |
|
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. |
|
184 |
|
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 }; |
|
194 |
|
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 }; |
|
205 |
|
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; |
|
219 |
|
220 |
|
221 class CHlpItem : public CBase |
|
222 /** Encapsulates an individual item in a help file. |
|
223 |
|
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(); |
|
236 |
|
237 public: // Access |
|
238 inline TUid CategoryUid() const |
|
239 /** Gets the item's category ID. |
|
240 |
|
241 @return Category ID */ |
|
242 { return iCategoryUid; } |
|
243 inline TUid HelpFileUid() const |
|
244 /** Gets the item's help file UID. |
|
245 |
|
246 @return Help file UID */ |
|
247 { return iHelpFileUid; } |
|
248 inline TUint32 Id() const |
|
249 /** Gets the item's ID. |
|
250 |
|
251 @return Item's ID */ |
|
252 { return iId; } |
|
253 inline const TDesC& Title() const |
|
254 /** Gets the item's title. |
|
255 |
|
256 @return Item's title */ |
|
257 { return *iTitle; } |
|
258 |
|
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; |
|
265 |
|
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); |
|
272 |
|
273 private: // Meta data required for correct restoration of topics |
|
274 TUid iCategoryUid; |
|
275 TUid iHelpFileUid; |
|
276 }; |
|
277 |
|
278 |
|
279 |
|
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. |
|
291 |
|
292 @param aIndex Index of item to get |
|
293 @return Topic ID */ |
|
294 virtual TUint32 At(TInt aIndex) const = 0; |
|
295 }; |
|
296 |
|
297 |
|
298 |
|
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(); |
|
312 |
|
313 public: // From MDesCArray |
|
314 IMPORT_C TInt MdcaCount() const; |
|
315 IMPORT_C TPtrC MdcaPoint(TInt aIndex) const; |
|
316 |
|
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); |
|
327 |
|
328 private: // 2nd phase constructor |
|
329 void ConstructL(); |
|
330 |
|
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 }; |
|
336 |
|
337 |
|
338 |
|
339 /////////////////////////////////////////////////////////////////////////////////////// |
|
340 // ----> CHlpTopic |
|
341 /////////////////////////////////////////////////////////////////////////////////////// |
|
342 class CHlpTopic : public CBase |
|
343 /** Encapsulates a help topic. |
|
344 |
|
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(); |
|
354 |
|
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); |
|
361 |
|
362 IMPORT_C CRichText* TopicText(); |
|
363 IMPORT_C TDesC& TopicTitle(); |
|
364 IMPORT_C TDesC& Category(); |
|
365 |
|
366 inline CParaFormatLayer* ParaFormatLayer() const |
|
367 /** Gets the topic paragraph formatting. |
|
368 |
|
369 @return Topic paragraph formatting */ |
|
370 { return iGlobalParaFormatLayer; } |
|
371 inline CCharFormatLayer* CharFormatLayer() const |
|
372 /** Gets the topic character formatting. |
|
373 |
|
374 @return Topic character formatting */ |
|
375 { return iGlobalCharFormatLayer; } |
|
376 |
|
377 private: |
|
378 void ConstructL(); |
|
379 |
|
380 private: |
|
381 friend class CHlpModel; |
|
382 |
|
383 TUint32 iTopicId; |
|
384 TBuf<KMaxTitleColumn> iTopicTitle; |
|
385 TBuf<KMaxTitleColumn> iCategory; |
|
386 |
|
387 CRichText* iTopicText; |
|
388 CParaFormatLayer* iGlobalParaFormatLayer; |
|
389 CCharFormatLayer* iGlobalCharFormatLayer; |
|
390 }; |
|
391 |
|
392 |
|
393 |
|
394 |
|
395 /////////////////////////////////////////////////////////////////////////////////////// |
|
396 // ----> CHlpModel |
|
397 /////////////////////////////////////////////////////////////////////////////////////// |
|
398 class CHlpModel : public CBase, public MHlpDbObserver, public MPictureFactory, public MRichTextStoreResolver |
|
399 /** Help model interface. |
|
400 |
|
401 It provides functions to search help files in various ways. |
|
402 |
|
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(); |
|
413 |
|
414 public: // Opens all the help files in \System\Help |
|
415 IMPORT_C void OpenL(); |
|
416 IMPORT_C void CloseL(); |
|
417 |
|
418 public: // Opens specific help files |
|
419 IMPORT_C void OpenFileL(const TDesC& aFileName); |
|
420 IMPORT_C void CloseFileL(const TDesC& aFileName); |
|
421 |
|
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); |
|
427 |
|
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); |
|
432 |
|
433 public: // Cancel EFullTextSearch types - will return KErrArgument if not the correct type |
|
434 IMPORT_C TInt CancelSearch(); |
|
435 |
|
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); |
|
442 |
|
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); |
|
449 |
|
450 public: // FROM MPictureFactory |
|
451 void NewPictureL(TPictureHeader& aHdr, const CStreamStore& aDeferredPictureStore) const; |
|
452 |
|
453 public: // FROM MRichTextStoreResolver |
|
454 IMPORT_C const CStreamStore& StreamStoreL(TInt aPos) const; |
|
455 |
|
456 public: |
|
457 // Check to see if any of the databases have matching meta data |
|
458 IMPORT_C TInt MatchUidL(TUid aUid); |
|
459 |
|
460 // Replace the current observer with another |
|
461 IMPORT_C void SetObserver(MHlpModelObserver* aObserver); |
|
462 |
|
463 public: |
|
464 void NotifyHelpModelDestructionToPictures(); |
|
465 |
|
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); |
|
472 |
|
473 private: // Event management |
|
474 void HandleDbEventL(TInt aEvent); |
|
475 void ReportEventToObserverL(TInt aEvent); |
|
476 |
|
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); |
|
486 |
|
487 private: |
|
488 CHlpModel(RFs& aFs, MHlpModelObserver& aObserver); |
|
489 void ConstructL(); |
|
490 |
|
491 private: // Member data |
|
492 RFs& iFsSession; |
|
493 |
|
494 // This is required in order to restore rich text pictures from the database |
|
495 CStreamStore* iCurrentRichTextStore; |
|
496 |
|
497 // Creates our SQL string based upon the search type and criteria |
|
498 CHlpSQLSearch* iSearch; |
|
499 |
|
500 // An array of all the help files currently available |
|
501 CHlpDatabases* iDatabases; |
|
502 |
|
503 // Receives help model notifications as various actions are performed |
|
504 MHlpModelObserver* iObserver; |
|
505 |
|
506 // Were any matching results found for this search |
|
507 TBool iFound; |
|
508 |
|
509 // What was being searched for |
|
510 HBufC* iCriterion; |
|
511 |
|
512 // What type of search was being performed |
|
513 TInt iSearchType; |
|
514 |
|
515 // Which database are we currently searching |
|
516 TInt iCurrentDb; |
|
517 |
|
518 // Transient category Uid used when creating category lists |
|
519 TUid iTransientCategoryUid; |
|
520 |
|
521 // What zoom size is used |
|
522 THlpZoomState iZoomSize; |
|
523 |
|
524 // Array to hold the bitmaps that are currently used in the help rich text |
|
525 CArrayPtr<CHlpPicture>* iPictures; |
|
526 |
|
527 // Array to hold the zoom factors that correspond to each zoom size |
|
528 CArrayFix<TInt>* iZoomFactors; |
|
529 }; |
|
530 |
|
531 |
|
532 |
|
533 |
|
534 |
|
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 } |
|
554 |
|
555 |
|
556 |
|
557 #endif |