1 /*

     2 * Copyright (c) {Year(s)} {Copyright owner}.

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of the "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/sfl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * {Name} {Company} ? Initial contribution

    11 *

    12 * Contributors:

    13 * {Name} {Company} ? {{Description of contribution}}

    14 *

    15 * Description:

    16 * {{Description of the file}}

    17 *

    18 */

    19 

    20 

    21 #ifndef __HSPUBLISHER_H__

    22 #define __HSPUBLISHER_H__

    23 

    24 //  System includes 

    25 #include <e32base.h>	

    26 #include <fbs.h>

    27 

    28 // User includes

    29 

    30 // Forward declarations

    31 class CHsPublisherImpl;

    32 class MHsWidgetObserver;

    33 

    34 //  Constants

    35 

    36 //  Class Definitions

    37 NONSHARABLE_CLASS( CHsPublisher ) : public CBase

    38     {

    39 public:

    40     // constructors and destructor

    41 

    42     /**

    43      * Constructor

    44      * 

    45      * @param aObserver Widget observer interface

    46      * @param aEnablePersist ETrue if publisher wants to save published data to SQL database for later usage.

    47      *        This option should be used with caution as it taxes runtime performance and resources.               

    48      */

    49     static CHsPublisher* NewL( 

    50         MHsWidgetObserver& aObserver, 

    51         TBool aEnablePersist = EFalse );

    52     

    53     /**

    54      * Constructor

    55      * 

    56      * @param aObserver Widget observer interface

    57      * @param aEnablePersist ETrue if publisher wants to save published data to SQL database for later usage.

    58      *        This option should be used with caution as it taxes runtime performance and resources.                

    59      */

    60     static CHsPublisher* NewLC(            

    61         MHsWidgetObserver& aObserver,

    62         TBool aEnablePersist = EFalse );

    63         

    64     /**

    65      * Destructor

    66      */

    67     ~CHsPublisher();

    68 

    69 public:

    70     // new functions

    71     

    72     /**

    73      * Publishes text to a <text> element in widget

    74      * 

    75      * @param aWidgetId Widget Id identifying the widget instance.

    76      * @param aElementId Element id identifying the text element in the widget.

    77      * @param aText Text to set.     

    78      * @return System wide error code.

    79      */

    80     TInt PublishText( 

    81         const TDesC& aWidgetId, 

    82         const TDesC8& aElementId, 

    83         const TDesC& aText );

    84 

    85     /**

    86      * Publishes image to an <image> element in widget

    87      * 

    88      * @param aWidgetId Widget Id identifying the widget instance.

    89      * @param aElementId Element id identifying the iamge element in the widget.

    90      * @param aImage Image to set.

    91      * @param aMask Mask to set. 

    92      * @return System wide error code.

    93      */    

    94     TInt PublishImage( 

    95         const TDesC& aWidgetId, 

    96         const TDesC8& aElementId,

    97         const CFbsBitmap* aImage,

    98         const CFbsBitmap* aMask );

    99 

   100     /**

   101      * Publishes image to an <image> element in widget

   102      * 

   103      * @param aWidgetId Widget Id identifying the widget instance.

   104      * @param aElementId Element id identifying the image element in the widget.

   105      * @param aImageHandle Image handle.

   106      * @param aMaskHandle Mask handle.

   107      * @return System wide error code.

   108      */        

   109     TInt PublishImage( 

   110         const TDesC& aWidgetId,      

   111         const TDesC8& aElementId, 

   112         TInt aImageHandle, 

   113         TInt aMaskHandle );

   114 

   115     /**

   116      * Publishes image to an <image> element in the widget.

   117      * 

   118      * @param aWidgetId Widget Id identifying the widget instance.

   119      * @param aElementId Element id identifying the image element in the widget.

   120      * @param aSource Source for the image. Supported source formats are:

   121      * - Filesystem path, i.e. _LIT( KMyImagePath, "c:\\data\\Installs\\MyWidget\\image.jpg");

   122      * - skin(<majorId> <minorId>), i.e. _LIT( KMySkinImage, "skin(270501603 8586)" );

   123      * - mif(<MifFileName.mif> <bitmapId> <maskId>), i.e. _LIT( KMyMifImage, "mif(c:\\data\\Installs\\MyWidget\\mymwidget.mif 16384 16385" );

   124      */                

   125     TInt PublishImage( 

   126         const TDesC& aWidgetId,           

   127         const TDesC8& aElementId, 

   128         const TDesC& aSource );

   129     

   130     /**

   131      * Publishes stream to a <data> element in widget

   132      * 

   133      * @param aWidgetId Widget Id identifying the widget instance.

   134      * @param aElementId Element id identifying the data element in the widget.

   135      * @param aStream The stream as descriptor.         

   136      * @return System wide error code.

   137      */            

   138     TInt PublishStream(

   139         const TDesC& aWidgetId,

   140         const TDesC8& aElementId,

   141         const TDesC8& aStream );

   142 

   143     /**

   144      * Cleans published text from a <text> element.

   145      * 

   146      * @param aWidgetId Widget Id identifying the widget instance.

   147      * @param aElementId Element id identifying the data element in the widget.

   148      * @return System wide error code.     

   149      */

   150     TInt CleanText( const TDesC& aWidgetId,    

   151         const TDesC8& aElementId );

   152 

   153     /**

   154      * Cleans published image from an <image> element.

   155      * 

   156      * @param aWidgetId Widget Id identifying the widget instance.

   157      * @param aElementId Element id identifying the data element in the widget.

   158      * @return System wide error code.     

   159      */    

   160     TInt CleanImage( const TDesC& aWidgetId,    

   161         const TDesC8& aElementId );

   162     

   163     /**

   164      * Starts a publish transaction. Transaction must be committed  

   165      * with CommitTransaction method.

   166      * 

   167      * @param aWidget Widget Id identifying the transaction for widget instance.

   168      * @return System wide error code.

   169      */                

   170     TInt StartTransaction( 

   171         const TDesC& aWidgetId );

   172     

   173     /**

   174      * Commits the publish transaction and flushes changes to Homescreen.

   175      * 

   176      * @param aWidget Widget Id identifying the transaction for the widget instance.

   177      * @return System wide error code.

   178      */            

   179     TInt CommitTransaction( 

   180         const TDesC& aWidgetId );    

   181        

   182 private:

   183     // private constructors

   184     

   185     /**

   186      * C++ default constructor

   187      */

   188     CHsPublisher();

   189     

   190     /**

   191      * 2nd phase constructor

   192      */

   193     void ConstructL( 

   194         MHsWidgetObserver& aObserver,

   195         TBool aEnablePersist );

   196     

   197 private:

   198     // data

   199         

   200     /** HS publisher implementation, owned */

   201     CHsPublisherImpl* iImpl;

   202     };

   203 

   204 #endif  // __HSPUBLISHER_H__

   205 

   206 // End of file