1.1 --- a/epoc32/include/hlpmodel.h Tue Mar 16 16:12:26 2010 +0000
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,557 +0,0 @@
1.4 -// Copyright (c) 1999-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 -// All rights reserved.
1.6 -// This component and the accompanying materials are made available
1.7 -// 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
1.8 -// which accompanies this distribution, and is available
1.9 -// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.10 -//
1.11 -// Initial Contributors:
1.12 -// Nokia Corporation - initial contribution.
1.13 -//
1.14 -// Contributors:
1.15 -//
1.16 -// Description:
1.17 -//
1.18 -
1.19 -#ifndef __HLPMODEL_H
1.20 -#define __HLPMODEL_H
1.21 -
1.22 -// System includes
1.23 -#include <e32std.h>
1.24 -#include <badesca.h> // For MDesCArray
1.25 -#include <txtmrtsr.h> // For MRichTextStoreResolver
1.26 -#include <gdi.h> // For MPictureFactory
1.27 -#include <d32dbms.h>
1.28 -
1.29 -// Help model includes
1.30 -#include "hlpconstants.h"
1.31 -
1.32 -// Classes referenced
1.33 -class CRichText;
1.34 -class CHlpDatabase;
1.35 -class CHlpFileEntry;
1.36 -class CHlpSQLSearch;
1.37 -class TCoeHelpContext;
1.38 -class CParaFormatLayer;
1.39 -class CCharFormatLayer;
1.40 -class CHlpPicture;
1.41 -
1.42 -// Typedefs
1.43 -/**
1.44 -@internalComponent
1.45 -@released
1.46 -*/
1.47 -typedef CArrayPtrFlat<CHlpDatabase> CHlpDatabases;
1.48 -
1.49 -/**
1.50 -@internalComponent
1.51 -@released
1.52 -*/
1.53 -typedef CArrayPtrFlat<CHlpFileEntry> CHlpFileList;
1.54 -
1.55 -
1.56 -class MHlpModelObserver
1.57 -/** Client callback inteface to receive events from the help model.
1.58 -@publishedAll
1.59 -@released
1.60 -*/
1.61 - {
1.62 -public:
1.63 - /** Receives a help model event.
1.64 -
1.65 - @param aEvent Help model event. Events are listed in the enums that begin
1.66 - ECategoryListAvailable, and ENoRecordsFound. */
1.67 - virtual void HandleModelEventL(TInt aEvent) = 0;
1.68 - };
1.69 -
1.70 -//
1.71 -// Internal API to handle events reported by the search engine
1.72 -//
1.73 -class MHlpDbObserver
1.74 -/**
1.75 -@internalComponent
1.76 -@released
1.77 -*/
1.78 - {
1.79 -public: // TInt aEvent should be a named enum
1.80 - virtual void HandleDbEventL(TInt aEvent) = 0;
1.81 - };
1.82 -
1.83 -//
1.84 -// Search types (these should be named, but SC cannot be broken until v7.0
1.85 -//
1.86 -/** Defines the search types for use with CHlpModel::SearchL(). */
1.87 -enum
1.88 - {
1.89 - /** Gets a list of index entries for all help files.
1.90 -
1.91 - Success is indicated by an EIndexListAvailable event; failure by EIndexListNoneFound.
1.92 - The list can be retrieved using CHlpModel::LoadListL(). */
1.93 - EIndexList,
1.94 - /** Gets a list of categories for all help files.
1.95 -
1.96 - Success is indicated by an ECategoryListAvailable event; failure by ECategoryListNoneFound.
1.97 - The list can be retrieved using CHlpModel::CategoryListL(). */
1.98 - ECategoryList,
1.99 - /** Gets a list of topics for a specified category.
1.100 -
1.101 - Success is indicated by an ETopicListAvailable event; failure by ETopicListNoneFound.
1.102 - The list can be retrieved using CHlpModel::LoadListL(). */
1.103 - ETopicListForCategory,
1.104 - /** Gets a list of topics for a specified category UID.
1.105 -
1.106 - Success is indicated by an ETopicListAvailable event; failure by ETopicListNoneFound.
1.107 - The list can be retrieved using CHlpModel::LoadListL(). */
1.108 - ETopicListForCategoryUID,
1.109 - /** Searches for a topic with the specified help context.
1.110 -
1.111 - A successful search generates an ETopicAvailable event. The topic can then be retrieved
1.112 - using CHlpModel::LoadTopicL(). An unsuccessful search generates an ETopicNotFound event. */
1.113 - EContextSearch,
1.114 - /** Searches for index entries for the specified help item.
1.115 -
1.116 - A successful search generates an ETopicListAvailable event. The list can then be retrieved
1.117 - using CHlpModel::LoadListL(). An unsuccessful search generates an ETopicListNoneFound event. */
1.118 - EIndexSearch,
1.119 - /** Searches the topic titles for the specified text.
1.120 -
1.121 - A successful search generates an ESearchListAvailable event. The list can then be
1.122 - retrieved using CHlpModel::LoadListL(). An unsuccessful search generates an
1.123 - ESearchListNoneFound event. */
1.124 - EQuickSearch,
1.125 - /** Searches the full text of topics for the specified text.
1.126 -
1.127 - A successful search generates an ESearchListAvailable event. The list can then be
1.128 - retrieved using CHlpModel::LoadListL(). An unsuccessful search generates an
1.129 - ESearchListNoneFound event. */
1.130 - EFullTextSearch,
1.131 - /** Searches for a topic with the specified ID.
1.132 -
1.133 - A successful search generates an ETopicAvailable event. The topic can then be
1.134 - retrieved using CHlpModel::LoadTopicL(). An unsuccessful search generates an
1.135 - ETopicNotFound event. */
1.136 - ETopicIdSearch
1.137 - };
1.138 -
1.139 -//
1.140 -// Search progress responses (this should be scoped as members of MHlpModelObserver
1.141 -// and should also be named, but SC cannot be broken until v7.0
1.142 -//
1.143 -enum
1.144 - {
1.145 - ENoRecordsFound,
1.146 - ESearchInProgress,
1.147 - ESearchComplete
1.148 - };
1.149 -
1.150 -//
1.151 -// Search progress responses (ditto for naming and scoping)
1.152 -//
1.153 -/** Help model search result events*/
1.154 -enum
1.155 - {
1.156 - /** The search returned a category list.
1.157 -
1.158 - The list can be retrieved using CHlpModel::CategoryListL(). */
1.159 - ECategoryListAvailable,
1.160 - /** The search did not return a category list. */
1.161 - ECategoryListNoneFound,
1.162 - /** The search returned a results list.
1.163 -
1.164 - The list can be retrieved using CHlpModel::LoadListL(). */
1.165 - ESearchListAvailable,
1.166 - /** The search did not return a results list. */
1.167 - ESearchListNoneFound,
1.168 - /** The search returned a topic list.
1.169 -
1.170 - The list can be retrieved using CHlpModel::LoadListL(). */
1.171 - ETopicListAvailable, // Category expansion
1.172 - /** The search did not return a topic list. */
1.173 - ETopicListNoneFound,
1.174 - /** The search returned an index item list.
1.175 -
1.176 - The list can be retrieved using CHlpModel::LoadListL(). */
1.177 - EIndexListAvailable,
1.178 - /** The search did not return an index item list. */
1.179 - EIndexListNoneFound,
1.180 - /** The search returned a topic list from an index phrase search.
1.181 -
1.182 - The list can be retrieved using CHlpModel::LoadListL(). */
1.183 - EIndexSearchListAvailable,
1.184 - /** The search did not return a topic list from an index phrase search. */
1.185 - EIndexSearchListNoneFound,
1.186 - /** The search returned a topic.
1.187 -
1.188 - The topic can be retrieved using CHlpModel::LoadTopicL(). */
1.189 - ETopicAvailable,
1.190 - /** The search did not return a topic. */
1.191 - ETopicNotFound,
1.192 - /** The search is in progress. */
1.193 - EModelSearchInProgress,
1.194 - /** The search has been cancelled. */
1.195 - EHlpSearchCancelled
1.196 - };
1.197 -
1.198 -/** Defines help model zoom sizes. */
1.199 -enum THlpZoomState
1.200 - {
1.201 - /** Small zoom. */
1.202 - EHlpZoomStateSmall = 0,
1.203 - /** Medium zoom. */
1.204 - EHlpZoomStateMedium = 1,
1.205 - /** Large zoom. */
1.206 - EHlpZoomStateLarge = 2
1.207 - };
1.208 -
1.209 -// Constants
1.210 -const TInt KHlpModelDefaultNumberOfImagesForV6Point2Files = 1;
1.211 -const TInt KHlpModelMaximumNumberOfImagesForV6Point2Files = 3;
1.212 -//
1.213 -/** Default zoom factor for small zoom size. */
1.214 -const TInt KHlpModelZoomFactorSmall = 750;
1.215 -/** Default zoom factor for medium zoom size. */
1.216 -const TInt KHlpModelZoomFactorMedium = 1000;
1.217 -/** Default zoom factor for large zoom size. */
1.218 -const TInt KHlpModelZoomFactorLarge = 1250;
1.219 -//
1.220 -/** Default zoom factor for medium zoom size as real number. */
1.221 -const TReal KHlpModelDefaultZoomFactorAsRealNumber = 1000.0;
1.222 -
1.223 -
1.224 -class CHlpItem : public CBase
1.225 -/** Encapsulates an individual item in a help file.
1.226 -
1.227 -Note that item IDs are assigned in increasing numerical order by the help
1.228 -compiler and are not unique. Categories and help files are however specified
1.229 -by UID, and so are unique.
1.230 -@publishedAll
1.231 -@released
1.232 -*/
1.233 - {
1.234 -public:
1.235 - static CHlpItem* NewL(const TDesC& aTitle, TUint32 aId, TUid aCategoryId, TUid aHelpFileUid);
1.236 - static CHlpItem* NewLC(const TDesC& aTitle, TUint32 aId, TUid aCategoryId, TUid aHelpFileUid);
1.237 - static CHlpItem* NewLC(const TDesC& aTitle, TUint32 aId, TUid aHelpFileUid);
1.238 - IMPORT_C ~CHlpItem();
1.239 -
1.240 -public: // Access
1.241 - inline TUid CategoryUid() const
1.242 - /** Gets the item's category ID.
1.243 -
1.244 - @return Category ID */
1.245 - { return iCategoryUid; }
1.246 - inline TUid HelpFileUid() const
1.247 - /** Gets the item's help file UID.
1.248 -
1.249 - @return Help file UID */
1.250 - { return iHelpFileUid; }
1.251 - inline TUint32 Id() const
1.252 - /** Gets the item's ID.
1.253 -
1.254 - @return Item's ID */
1.255 - { return iId; }
1.256 - inline const TDesC& Title() const
1.257 - /** Gets the item's title.
1.258 -
1.259 - @return Item's title */
1.260 - { return *iTitle; }
1.261 -
1.262 -public: // These should not be public, but I can't break SC (these were inherited from
1.263 - // the previous author.
1.264 - /** Item's title */
1.265 - HBufC* iTitle;
1.266 - /** Item's ID */
1.267 - TUint32 iId;
1.268 -
1.269 -private:
1.270 - friend class CHlpList; // Needed for searching
1.271 - CHlpItem(TUint32 aId);
1.272 - CHlpItem(TUint32 aId, TUid aHelpFileUid);
1.273 - CHlpItem(TUint32 aId, TUid aCategoryId, TUid aHelpFileUid);
1.274 - void ConstructL(const TDesC& aTitle);
1.275 -
1.276 -private: // Meta data required for correct restoration of topics
1.277 - TUid iCategoryUid;
1.278 - TUid iHelpFileUid;
1.279 - };
1.280 -
1.281 -
1.282 -
1.283 -///////////////////////////////////////////////////////////////////////////////////////
1.284 -// ----> MHlpTitleArray
1.285 -///////////////////////////////////////////////////////////////////////////////////////
1.286 -class MHlpTitleArray : public MDesCArray
1.287 -/** Interface to get a topic ID from an array index.
1.288 -@publishedAll
1.289 -@released
1.290 -*/
1.291 - {
1.292 -public:
1.293 - /** Gets a topic ID for the specified index.
1.294 -
1.295 - @param aIndex Index of item to get
1.296 - @return Topic ID */
1.297 - virtual TUint32 At(TInt aIndex) const = 0;
1.298 - };
1.299 -
1.300 -
1.301 -
1.302 -///////////////////////////////////////////////////////////////////////////////////////
1.303 -// ----> CHlpList
1.304 -///////////////////////////////////////////////////////////////////////////////////////
1.305 -class CHlpList : public CBase, public MHlpTitleArray
1.306 -/** A list of help items (CHlpItem objects).
1.307 -@publishedAll
1.308 -@released
1.309 -*/
1.310 - {
1.311 -public: // Static construct / destruct
1.312 - IMPORT_C static CHlpList* NewL();
1.313 - IMPORT_C static CHlpList* NewLC();
1.314 - IMPORT_C ~CHlpList();
1.315 -
1.316 -public: // From MDesCArray
1.317 - IMPORT_C TInt MdcaCount() const;
1.318 - IMPORT_C TPtrC MdcaPoint(TInt aIndex) const;
1.319 -
1.320 -public:
1.321 - // 'At' returns topic Id, but this function is next to useless because you can't
1.322 - // uniquely identify a help topic by topic id alone. You need to know 3 things:-
1.323 - // a) topic id, 2) category id, 3) help file uid. This information is all
1.324 - // encapsulated in CHlpItem so help app authors should use 'Item' instead.
1.325 - IMPORT_C TUint32 At(TInt aIndex) const;
1.326 - IMPORT_C CHlpItem* Item(TInt aIndex) const;
1.327 - IMPORT_C TInt Find(TUint32 aId);
1.328 - IMPORT_C void Reset();
1.329 - IMPORT_C void AppendL(CHlpItem* aItem);
1.330 -
1.331 -private: // 2nd phase constructor
1.332 - void ConstructL();
1.333 -
1.334 -private:
1.335 - // This is the array of help items that were located as a result of
1.336 - // performing a search.
1.337 - CArrayPtr<CHlpItem>* iList;
1.338 - };
1.339 -
1.340 -
1.341 -
1.342 -///////////////////////////////////////////////////////////////////////////////////////
1.343 -// ----> CHlpTopic
1.344 -///////////////////////////////////////////////////////////////////////////////////////
1.345 -class CHlpTopic : public CBase
1.346 -/** Encapsulates a help topic.
1.347 -
1.348 -A help topic has text, a title, a category, and paragraph and character formatting.
1.349 -@publishedAll
1.350 -@released
1.351 -*/
1.352 - {
1.353 -public:
1.354 - IMPORT_C static CHlpTopic* NewL();
1.355 - IMPORT_C static CHlpTopic* NewLC();
1.356 - IMPORT_C ~CHlpTopic();
1.357 -
1.358 -public:
1.359 - // This function will not behave as expected in the case where it is used to
1.360 - // restore rich text that includes pictures. Instead, only the text and markup
1.361 - // will be restored. Help App authors should use 'CHlpModel::LoadTopic' instead.
1.362 - // I can't remove this as it would break S&BC.
1.363 - IMPORT_C void RestoreL(RDbView* aView);
1.364 -
1.365 - IMPORT_C CRichText* TopicText();
1.366 - IMPORT_C TDesC& TopicTitle();
1.367 - IMPORT_C TDesC& Category();
1.368 -
1.369 - inline CParaFormatLayer* ParaFormatLayer() const
1.370 - /** Gets the topic paragraph formatting.
1.371 -
1.372 - @return Topic paragraph formatting */
1.373 - { return iGlobalParaFormatLayer; }
1.374 - inline CCharFormatLayer* CharFormatLayer() const
1.375 - /** Gets the topic character formatting.
1.376 -
1.377 - @return Topic character formatting */
1.378 - { return iGlobalCharFormatLayer; }
1.379 -
1.380 -private:
1.381 - void ConstructL();
1.382 -
1.383 -private:
1.384 - friend class CHlpModel;
1.385 -
1.386 - TUint32 iTopicId;
1.387 - TBuf<KMaxTitleColumn> iTopicTitle;
1.388 - TBuf<KMaxTitleColumn> iCategory;
1.389 -
1.390 - CRichText* iTopicText;
1.391 - CParaFormatLayer* iGlobalParaFormatLayer;
1.392 - CCharFormatLayer* iGlobalCharFormatLayer;
1.393 - };
1.394 -
1.395 -
1.396 -
1.397 -
1.398 -///////////////////////////////////////////////////////////////////////////////////////
1.399 -// ----> CHlpModel
1.400 -///////////////////////////////////////////////////////////////////////////////////////
1.401 -class CHlpModel : public CBase, public MHlpDbObserver, public MPictureFactory, public MRichTextStoreResolver
1.402 -/** Help model interface.
1.403 -
1.404 -It provides functions to search help files in various ways.
1.405 -
1.406 -The interface implements MHlpDbObserver for help database events, and MRichTextStoreResolver
1.407 -and MPictureFactory to obtain pictures from rich text stores.
1.408 -@publishedAll
1.409 -@released
1.410 -*/
1.411 - {
1.412 -public: // Construct / destruct
1.413 - IMPORT_C static CHlpModel* NewL(RFs& aFs, MHlpModelObserver* aObserver);
1.414 - IMPORT_C static CHlpModel* NewLC(RFs& aFs, MHlpModelObserver* aObserver);
1.415 - IMPORT_C ~CHlpModel();
1.416 -
1.417 -public: // Opens all the help files in \System\Help
1.418 - IMPORT_C void OpenL();
1.419 - IMPORT_C void CloseL();
1.420 -
1.421 -public: // Opens specific help files
1.422 - IMPORT_C void OpenFileL(const TDesC& aFileName);
1.423 - IMPORT_C void CloseFileL(const TDesC& aFileName);
1.424 -
1.425 -public: // Specialized searching
1.426 - IMPORT_C void ContextSearchL(TCoeHelpContext& aContext);
1.427 - IMPORT_C void CategoryUIDSearchL(TUid aCategoryUID);
1.428 - IMPORT_C void TopicSearchL(const CHlpItem& aHelpItem);
1.429 - IMPORT_C void IndexSearchL(const CHlpItem& aHelpItem);
1.430 -
1.431 - // Generic searching
1.432 - IMPORT_C void SearchL(TInt aType, TUint32 aId);
1.433 - IMPORT_C void SearchL(TInt aType, HBufC* aCriterion=NULL);
1.434 - IMPORT_C void SearchL(TInt aType, const TDesC& aCriterion);
1.435 -
1.436 -public: // Cancel EFullTextSearch types - will return KErrArgument if not the correct type
1.437 - IMPORT_C TInt CancelSearch();
1.438 -
1.439 -public: // Assumes that the search has already been performed and that the view is valid
1.440 - IMPORT_C void LoadTopicL(CRichText& aRichText, TDes& aTitle);
1.441 - IMPORT_C void LoadTopicL(CRichText& aRichText);
1.442 - IMPORT_C void LoadTopicL(CHlpTopic* aTopic);
1.443 - IMPORT_C void LoadListL(CHlpList* aList);
1.444 - IMPORT_C void CategoryListL(CDesCArray* aList);
1.445 -
1.446 -public:
1.447 - IMPORT_C void SetZoomSizeL(THlpZoomState aState = EHlpZoomStateMedium);
1.448 - IMPORT_C THlpZoomState ZoomSize() const;
1.449 - IMPORT_C void SetZoomFactors(THlpZoomState aZoomState, TInt aFactor);
1.450 - TInt CurrentZoomFactor() const;
1.451 - void RemoveHelpPicture(CHlpPicture* aHelpPicture);
1.452 -
1.453 -public: // FROM MPictureFactory
1.454 - void NewPictureL(TPictureHeader& aHdr, const CStreamStore& aDeferredPictureStore) const;
1.455 -
1.456 -public: // FROM MRichTextStoreResolver
1.457 - IMPORT_C const CStreamStore& StreamStoreL(TInt aPos) const;
1.458 -
1.459 -public:
1.460 - // Check to see if any of the databases have matching meta data
1.461 - IMPORT_C TInt MatchUidL(TUid aUid);
1.462 -
1.463 - // Replace the current observer with another
1.464 - IMPORT_C void SetObserver(MHlpModelObserver* aObserver);
1.465 -
1.466 -public:
1.467 - void NotifyHelpModelDestructionToPictures();
1.468 -
1.469 -private: // Internal search API
1.470 - void DoSearchL(TInt aType, const TDesC& aCriterion);
1.471 - void DoNextSearchL();
1.472 - void ResetReadyForSearch();
1.473 - void ResetViews();
1.474 - void SetCriterionL(const TDesC& aCriterion);
1.475 -
1.476 -private: // Event management
1.477 - void HandleDbEventL(TInt aEvent);
1.478 - void ReportEventToObserverL(TInt aEvent);
1.479 -
1.480 -private: // Misc internal functions
1.481 - inline CHlpDatabase* CurrentDatabase() const;
1.482 - inline TInt DatabaseCount() const;
1.483 - inline void SetSearchType(TInt aSearchType);
1.484 - inline TInt CurrentSearchType() const;
1.485 - RDbView* CurrentView() const;
1.486 - TBool DiskPresent(TInt aDrive) const;
1.487 - CHlpFileList* BuildListForDriveLC(TDriveUnit aDrive, RFs& aFsSession) const;
1.488 - static void ResetAndDestroyArrayOfCHlpFileEntry(TAny* aObject);
1.489 -
1.490 -private:
1.491 - CHlpModel(RFs& aFs, MHlpModelObserver& aObserver);
1.492 - void ConstructL();
1.493 -
1.494 -private: // Member data
1.495 - RFs& iFsSession;
1.496 -
1.497 - // This is required in order to restore rich text pictures from the database
1.498 - CStreamStore* iCurrentRichTextStore;
1.499 -
1.500 - // Creates our SQL string based upon the search type and criteria
1.501 - CHlpSQLSearch* iSearch;
1.502 -
1.503 - // An array of all the help files currently available
1.504 - CHlpDatabases* iDatabases;
1.505 -
1.506 - // Receives help model notifications as various actions are performed
1.507 - MHlpModelObserver* iObserver;
1.508 -
1.509 - // Were any matching results found for this search
1.510 - TBool iFound;
1.511 -
1.512 - // What was being searched for
1.513 - HBufC* iCriterion;
1.514 -
1.515 - // What type of search was being performed
1.516 - TInt iSearchType;
1.517 -
1.518 - // Which database are we currently searching
1.519 - TInt iCurrentDb;
1.520 -
1.521 - // Transient category Uid used when creating category lists
1.522 - TUid iTransientCategoryUid;
1.523 -
1.524 - // What zoom size is used
1.525 - THlpZoomState iZoomSize;
1.526 -
1.527 - // Array to hold the bitmaps that are currently used in the help rich text
1.528 - CArrayPtr<CHlpPicture>* iPictures;
1.529 -
1.530 - // Array to hold the zoom factors that correspond to each zoom size
1.531 - CArrayFix<TInt>* iZoomFactors;
1.532 - };
1.533 -
1.534 -
1.535 -
1.536 -
1.537 -
1.538 -///////////////////////////////////////////////////////////////////////////////////////
1.539 -// ----> CHlpModel (inlines)
1.540 -///////////////////////////////////////////////////////////////////////////////////////
1.541 -inline TInt CHlpModel::DatabaseCount() const
1.542 - {
1.543 - return iDatabases->Count();
1.544 - }
1.545 -inline void CHlpModel::SetSearchType(TInt aSearchType)
1.546 - {
1.547 - iSearchType = aSearchType;
1.548 - }
1.549 -inline CHlpDatabase* CHlpModel::CurrentDatabase() const
1.550 - {
1.551 - return iDatabases->At(iCurrentDb);
1.552 - }
1.553 -inline TInt CHlpModel::CurrentSearchType() const
1.554 - {
1.555 - return iSearchType;
1.556 - }
1.557 -
1.558 -
1.559 -
1.560 -#endif