epoc32/include/app/msgbiocontrol.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100 (2010-03-31)
branchSymbian3
changeset 4 837f303aceeb
parent 2 2fe1408b6811
permissions -rw-r--r--
Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
     1 /*
     2 * Copyright (c) 2002-2006 Nokia Corporation and/or its subsidiary(-ies).
     3 * All rights reserved.
     4 * This component and the accompanying materials are made available
     5 * under the terms of "Eclipse Public License v1.0"
     6 * which accompanies this distribution, and is available
     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
     8 *
     9 * Initial Contributors:
    10 * Nokia Corporation - initial contribution.
    11 *
    12 * Contributors:
    13 *
    14 * Description:   Base class for bio controls.
    15 *
    16 */
    17 
    18 
    19 
    20 #ifndef MSGBIOCONTROL_H
    21 #define MSGBIOCONTROL_H
    22 
    23 
    24 // INCLUDES
    25 #include <msvstd.h>
    26 #include <coecntrl.h>           // for CCoeControl
    27 #include <mmsgbiocontrol.h>     // for MMsgBioControl
    28 #include <badesca.h>            // for CDesCArray
    29 #include <aknglobalnote.h>
    30 #include <msgeditor.hrh>        // for TMsgCursorLocation
    31 
    32 // FORWARD DECLARATIONS
    33 
    34 class MMsgBioControlObserver;
    35 class CMsvSession;
    36 class MMsgBioControlExtension;  
    37 
    38 
    39 // CLASS DECLARATION
    40 
    41 /**
    42  * The base class for Bio controls.
    43  */
    44 class CMsgBioControl : public CCoeControl, public MMsgBioControl
    45     {
    46 
    47     public: //construction and destruction
    48             
    49         /**
    50          * Constructor. Call this from your Bio Control constructor.
    51          * @param aObserver Reference to the Bio control observer.
    52          * @param aSession Message Server session. Ownership not transferred.
    53          * @param aId Id of the message in the server.
    54          * @param aEditorOrViewerMode Sets Bio Control into editor or viewer mode.
    55          * @param aFile Data file handle. Bio controls can also be file based. Not owned.
    56          */
    57         IMPORT_C CMsgBioControl(
    58             MMsgBioControlObserver& aObserver,
    59             CMsvSession* aSession, //ownership is NOT transferred
    60             TMsvId aId,
    61             TMsgBioMode aEditorOrViewerMode,
    62             const RFile* aFile);   //ownership is NOT transferred
    63 
    64         /**
    65          * Destructor
    66          */
    67         IMPORT_C ~CMsgBioControl();
    68 
    69     public: // static helper functions
    70 
    71         /**
    72          * Pops a confirmation query. The result is given by the return value.
    73          * The standard resource must have been loaded using
    74          * LoadStandardBioResourceL().
    75          * @param aText The text that is to be used in the query.
    76          * @return A user confirmation results in ETrue, and vice versa.
    77          */
    78         IMPORT_C static TBool ConfirmationQueryL(const TDesC& aText);
    79 
    80         /**
    81          * Pops a confirmation query. The result is given by the return value.
    82          * The standard resource must have been loaded using
    83          * LoadStandardBioResourceL(). Your resource must also be loaded, for
    84          * eg. with LoadResourceL().
    85          * CCoeEnv must exist.
    86          * @param aStringResource The string resource id.
    87          * @return A user confirmation results in ETrue, and vice versa.
    88          */
    89         IMPORT_C static TBool ConfirmationQueryL(TInt aStringResource);
    90 
    91     public: // from MMsgBioControl
    92 
    93         /**
    94          * The application can get the option menu recommendations using this
    95          * function. The function comes from MMsgBioControl. This is the
    96          * default implementation which returns the flags
    97          * EMsgBioCallBack | EMsgBioDelete | EMsgBioMessInfo | EMsgBioMove | 
    98          * EMsgBioCreateCC | EMsgBioSend | EMsgBioAddRecipient | EMsgBioSave |
    99          * EMsgBioSendingOpt | EMsgBioHelp | EMsgBioExit. 
   100          * Bio Controls should override this if it is not ok.
   101          * @return The option menu permission flags. If the flag is off it
   102          * means that the option menu command is not recommended with this
   103          * Bio Control.
   104          */
   105         IMPORT_C TUint32 OptionMenuPermissionsL() const;
   106 
   107         /**
   108          * Gives the height of the text in pixels.
   109          * It is used by the scrolling framework.
   110          * @return Height of the text in pixels.
   111          */
   112         IMPORT_C TInt VirtualHeight();
   113 
   114         /**
   115          * Gives the cursor position in pixels.
   116          * It is used by the scrolling framework.
   117          * @return Cursor position in pixels.
   118          */
   119         IMPORT_C TInt VirtualVisibleTop();
   120 
   121         /**
   122          * Tells whether the cursor is in the topmost or bottom position.
   123          * It is used by the scrolling framework.
   124          * @param aLocation Specifies either top or bottom.
   125          * @return ETrue if the cursor is in the part specified by aLocation.
   126          */
   127         IMPORT_C TBool IsCursorLocation(TMsgCursorLocation aLocation) const;
   128     
   129     public: //new functions
   130     
   131         /**
   132          * Performs the internal scrolling of control if needed.
   133          * Default implementation does not perform any scrolling and returns that
   134          * zero pixels were scrolled.
   135          * @since 3.2
   136          * @param aPixelsToScroll Amount of pixels to scroll.
   137          * @param aDirection      Scrolling direction.
   138          * @return Amount of pixels the where scrolled. Zero value means the component cannot
   139          *         be scrolled to that direction anymore and view should be moved.
   140          */
   141         IMPORT_C TInt ScrollL( TInt aPixelsToScroll, TMsgScrollDirection aDirection );
   142 
   143         /**
   144          * Prepares control for viewing.
   145          * @since 3.2
   146          * @param aEvent	The event type
   147          * @param aParam Event related parameters
   148          */
   149         IMPORT_C void NotifyViewEvent( TMsgViewEvent aEvent, TInt aParam );
   150 
   151 
   152     protected: //new functions
   153 
   154         /**
   155          * Returns true if the control has been launched as editor,
   156          * and false if it was launched as viewer.
   157          * @return ETrue or EFalse
   158          */
   159         IMPORT_C TBool IsEditor() const;
   160 
   161         /**
   162          * Is the Bio Control file based or not.
   163          * @return ETrue if is file based.
   164          */
   165         IMPORT_C TBool IsFileBased() const;
   166 
   167         /**
   168          * Accessor for MsvSession. The session exists only if the Bio Control
   169          * has been created as message server based.
   170          * @exception Panics if there is no session.
   171          * @return CMsvSession&
   172          */
   173         IMPORT_C CMsvSession& MsvSession() const;
   174 
   175         /**
   176          * Deprecated*
   177          * 
   178          * Returns name of input file.
   179          * @return Name of file.
   180          * @exception Panics if the control is not file based.
   181          */
   182         IMPORT_C const TFileName& FileName() const;
   183 
   184         /**
   185          * Deprecated* Handle is valid only at contsruction phase!!
   186          * To be removed.
   187          * Returns input file handle.
   188          * @return handle of file.
   189          * @exception Panics if the control is not file based.
   190          */
   191         IMPORT_C const RFile& FileHandle() const;
   192 
   193         /**
   194          * Loads a resource file from /system/data/ into eikon env. This
   195          * function should be used for loading the Bio Control resources.
   196          * The resources are unloaded in the destructor of this class. The
   197          * offsets are kept in iResourceOffsets.
   198          * @param aFile File name mask, for eg. "vcalbc.r??".
   199          */
   200         IMPORT_C void LoadResourceL(const TDesC& aFile);
   201 
   202         /**
   203          * Loads a resource file into eikon env. The resources are unloaded in
   204          * the destructor of this class. (the offsets are kept in
   205          * iResourceOffsets).
   206          * @param aFile File name mask, for eg. "vcalbc.r??".
   207          * @param aSearchPath Search path, for eg. "\\System\\libs\\".
   208          */
   209         IMPORT_C void LoadResourceL(const TDesC& aFile,
   210             const TDesC& aSearchPath);
   211 
   212         /**
   213          * This loads the msgeditorutils.rsc resource, which is needed by
   214          * the dialogs and notes of this class.
   215          */
   216         IMPORT_C void LoadStandardBioResourceL();
   217 
   218         /**
   219          * Adds a menu item to the menu pane which is given as a reference.
   220          * @param aMenuPane Reference to the menu pane.
   221          * @param aStringRes The string resource id.
   222          * @param aCommandOffset The offset of the command from the first free
   223          * command.
   224          * @param aPosition The inserting position. The default is at the top.
   225          */
   226         IMPORT_C void AddMenuItemL(CEikMenuPane& aMenuPane, TInt aStringRes,
   227             TInt aCommandOffset, TInt aPosition = 0);
   228 
   229         /**
   230          * Notify editor view.
   231          * This is used by the Bio Control for notifying the Editor Base
   232          * framework of an event, and usually for requesting something to
   233          * be done.
   234          */
   235         IMPORT_C TBool NotifyEditorViewL( 
   236             TMsgBioControlEventRequest aRequest,
   237             TInt aDelta = 0);
   238 
   239         /**
   240          * Call from base class if extension interface is supported.
   241          * @param Interface for bio control extension. Ownership is not taken.
   242          */
   243         IMPORT_C void SetExtension(MMsgBioControlExtension* aExt);    
   244 
   245 
   246     private: // new functions
   247 
   248         /**
   249         * Sets the bio body control reference.
   250         * Used only by CMsgBioBodyControl.
   251         * @param aBioBodyControl Address of the bio body control.
   252         */
   253         void SetBioBodyControl( MMsgBioBodyControl* aBioBodyControl );
   254 
   255         /// deprecated
   256         TBool IsNear(TInt aLafPos, TInt aPos) const;
   257 
   258     private: // not available
   259 
   260         /**
   261          * Default constructor hidden away
   262          */
   263         CMsgBioControl();
   264 
   265         /**
   266          * Copy constructor prohibited.
   267          */
   268         CMsgBioControl(const CMsgBioControl& aSource);
   269 
   270         /**
   271          * Assignment operator prohibited.
   272          */
   273         const CMsgBioControl& operator=(const CMsgBioControl& aSource);
   274 
   275     protected:
   276 
   277         /// Reference to the MMsgBioControlObserver
   278         MMsgBioControlObserver& iBioControlObserver;
   279 
   280         /// Id of the message in the server.
   281         TMsvId          iId;
   282 
   283     private:
   284 
   285         /**
   286          * Pointer to Message Server session. It is NOT owned here.
   287          * The reason for using pointer type is that the session is optional.
   288          * It can be NULL without implying any error.
   289          * This session is accessed using the function MsvSession().
   290          */
   291         CMsvSession*    iMsvSession;
   292 
   293         /// Tells if the control was launched in editor or viewer mode.
   294         TMsgBioMode iMode;
   295 
   296         /**
   297          * * Deprecated -> To be removed* 
   298          * Handle is valid only during contruction phase.
   299          * A pointer to the handle of the input file, not owned.
   300          * Accessed using FileHandle().
   301          * See also function FileBased().
   302          */
   303 		const RFile* iFile;
   304 		
   305         /**
   306          * A pointer to Bio control extension interface. It is not owned here.
   307          */
   308         MMsgBioControlExtension* iExt;
   309 
   310         // Filler needed to keep this object's size the same.
   311         // Let the compiler calculate the filler size needed using sizeof.
   312         TUint8 iBCFiller[sizeof(TFileName) - sizeof(TFileName*) - sizeof(MMsgBioControlExtension*)];
   313         
   314 
   315         /// This is the array of resource offsets.
   316         CArrayFixFlat<TInt>* iResourceOffsets;
   317 
   318         /// Pointer to the bio bodycontrol.
   319         MMsgBioBodyControl* iBioBodyControl;
   320         
   321         /// status flags
   322         TInt iBCStatusFlags;
   323 
   324     private:
   325 
   326         friend class CMsgBioBodyControl;
   327 
   328         };
   329 
   330 #endif // MSGBIOCONTROL_H
   331 
   332 // End of file