/*

* Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies). 

* All rights reserved.

* This component and the accompanying materials are made available

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

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:   Layout metrics

*

*/

#ifndef C_ALFLAYOUTMETRICS_H

#define C_ALFLAYOUTMETRICS_H

#include <e32base.h>

class CAlfTextVisual;

class CAlfEnv;

struct TMarkedVisualEntry;

/**

 *  Layout metrics utility for measuring text visuals. Measuring is

 *  is done based on text style or font id. Mesuring texts that has been 

 *  defined using font specification are not yet supported.

 *  

 *

 *  Example of use:

 *  

 *  void CHelloWorldAppUi::ConstructL()

 *     {

 *     iEnv = CAlfEnv::NewL();

 *  #ifdef __DEBUG

 *     // Enable layout metrics utility visual automarking in debug builds.

 *     iEnv->LayoutMetricsUtility()->EnableAutoMarking(); 

 *  #endif

 *     ...

 *     ...

 *     // Create some textvisuals, these will be automatically included

 *     // into metrics reports. 

 *     iTextVisual = CAlfTextVisual::AddNewL(*this, iLayout);

 *     iTextVisual->SetText(KMyText);

 *     iTextVisual->SetStyle(EAlfTextStyleSmall);

 *     ...

 *     ...

 *     }

 *

 *   // handle any menu commands

 *  void CHelloWorldAppUi::HandleCommandL(TInt aCommand)

 *     {

 *     switch(aCommand)

 *         {

 *         case EHellowWorldCmdMeasureVisuals:

 *             {

 *             // Measure currently visible text visuals

 *             iEnv->LayoutMetricsUtility()->MeasureVisuals();

 *             // Write a metrics report into a file 

 *             iEnv->LayoutMetricsUtility()->WriteReport();

 *             break;

 *             }

 *          ...

 *          ...    

 *         }

 *     ...

 *     }        

 *

 *

 *  @lib alfclient.lib

 *  @since S60 v3.2

 */

NONSHARABLE_CLASS( CAlfLayoutMetricsUtility ): public CBase

    {

public:

    /**

     * Destructor.

     */

    virtual ~CAlfLayoutMetricsUtility();

    /**

     * 2-phase constructor.

     */

    static CAlfLayoutMetricsUtility* NewL(CAlfEnv& aEnv);

    /**

     * 2-phase constructor.

     */

    static CAlfLayoutMetricsUtility* NewLC(CAlfEnv& aEnv);

    /**

     * Marks visual to be included into layout metric reports.

     * @param aLogicalName Logical name for the visual, e.q. "title_pane_t1" or "qtn_title_text"...

     *                     If NULL is given, text visual text will be used as logical name

     *                     in the reports.

     * @param aVisual      The visual to be included into reports.

     */

    IMPORT_C void MarkVisual(TDesC* aLogicalName, CAlfTextVisual* aVisual);

    /**

     * Unmarks visual, it will not be included into layout metric reports.

     * @param aVisual      The visual to be excluded from reports.

     */

    IMPORT_C void UnmarkVisual(CAlfTextVisual* aVisual);

    /**

     * Measures all currently visible visuals.

     */

    IMPORT_C void MeasureVisuals();

    /**

     * Writes a layout metric report into a file, by default C: drive is used.

     * Report contains metrics data for each visual at the time of last call to the

     * MeasureVisuals()-method.

     *

     * Report is intended to be used when text strings lenghts are decided and localized to 

     * different language variants.

     *

     * Report contains data for each measured textvisual such as:

     *

     * - Component type ("Text" for text visual)

     * - Id (Generated id number)

     * - Variety (Generated variety id number)

     * - Logical name (Given with MarkVisual()-method) 

     * - Alias (Text that the text visual shows)

     * - Font type (qfn_primary, qfn_secondary...)

     * - Text width (Text width in pixels)

     * - Text height (Text height in pixels)

     * - Visual coordinates relative to parent layout left, right, top and bottom coordinates

     * - Remarks (Free text, if any)

     * - Layout parent id (Generated id for parent layout) 

     * - Layout parent variety id (Generated variety id for parent layout) 

     * - Wheter text visual is a multi row or not 

     * - Max number of text rows 

     * - Font style 1 (plain, bold -attributes)

     * - Font style 2 (regular, italic -attributes)

     * - Font style 3 (underline, strikethrough, outline, boxed or shadow)

     * - Concatenated rows or not

     *

     */

    IMPORT_C void WriteReport();

    /**

     * Enables (or disables) automarking of visuals. If enabled, when visuals are 

     * created they are automatical marked to be included into reports.

     */

    IMPORT_C void EnableAutoMarking(TBool aEnabled=ETrue);

    /**

     * Tells if automatic visual marking is enabled.

     * @retrun ETrue if automatic visual marking is enabled, otherwise EFalse.

     */     

    IMPORT_C TBool AutoMarking();

private:

    CAlfLayoutMetricsUtility();

    void ConstructL(CAlfEnv& aEnv);

    void MarkVisualL(TDesC* aLogicalName, CAlfTextVisual* aVisual);

    void MeasureVisualsL();

    void PrintToFile( TDesC16& aBuf );

private:

    struct TMetricsPrivateData;

    TMetricsPrivateData* iMetricsData;

    };

#endif // C_ALFLAYOUTMETRICS_H