1 /*

     2 * Copyright (c) 1997-1999 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:

    15 *

    16 */

    17 

    18 

    19 #if !defined(__EIKLABEL_H__)

    20 #define __EIKLABEL_H__

    21 

    22 

    23 #if !defined(__EIKALIGN_H__)

    24 #include <eikalign.h>

    25 #endif

    26 

    27 #if !defined(__COECCNTX_H__)

    28 #include <coeccntx.h>

    29 #endif

    30 

    31 #include <bidi.h>

    32 

    33 class CEikLabelExtension;

    34 class CAknPictographInterface;

    35 

    36 /**

    37  * Enables one or more lines of text to be displayed.

    38  */

    39 class CEikLabel : public CEikAlignedControl, public MCoeControlContext

    40 	{

    41 public:  // new functions

    42     /**

    43      * Destructor.

    44      */

    45     IMPORT_C ~CEikLabel();

    46     /** 

    47      * C++ default constructor.

    48      */

    49     IMPORT_C CEikLabel();

    50     /**

    51      * Sets the labels alignment. Overwrites alignment set

    52      * via @c CEikAlignedControl.

    53      * 

    54      * @param aAlignment Should be one of { @c ELayoutAlignNone, 

    55      *        @c ELayoutAlignCenter, @c ELayoutAlignLeft, @c ELayoutAlignRight,

    56      *        @c ELayoutAlignBidi } defined in @c Avkon.hrh.

    57      */

    58     IMPORT_C void SetLabelAlignment(TInt aAlignment);

    59 

    60     /**

    61      * Sets the brush style to be used from @c aBrushStyle, 

    62      * this overwrites the brush style set via the Control Context.

    63      * 

    64      * @param aBrushStyle A brush style.

    65      */

    66     IMPORT_C void SetBrushStyle(CWindowGc::TBrushStyle aBrushStyle);

    67 

    68     /**

    69      * Sets the brush style to be used from the Control Context, 

    70      * this overwrites the brush style set via the @c CEikLabel::SetBrushStyle().

    71      */

    72     IMPORT_C void SetBrushStyleFromContext();

    73 

    74 

    75 public:  // from CCoeControl

    76     /** 

    77      * From @c CCoeControl.

    78      *

    79      * Sets the control's minimum required size.

    80      *

    81      * @return Minimum size required by the control.

    82      */

    83     IMPORT_C TSize MinimumSize();

    84     /**

    85      * From @c CCoeControl.

    86      * 

    87      * Constructs the control from a resource file.

    88      *

    89      * @param aReader Interprets resource data read from a resource file.

    90      */

    91     IMPORT_C void ConstructFromResourceL(TResourceReader& aReader);

    92     

    93     /**

    94      * From @c CCoeControl.

    95      *

    96      * Gets the list of logical colours used to draw the control.

    97      *

    98      * @param aColorUseList The colour list.

    99      */

   100     IMPORT_C void GetColorUseListL(

   101                         CArrayFix<TCoeColorUse>& aColorUseList) const;

   102     /**

   103      * From @c CCoeControl.

   104      *

   105      * Handles a change to the control's resources.

   106      *

   107      * @param aType A message UID value.

   108      */

   109     IMPORT_C void HandleResourceChange(TInt aType);			// not available before Release 005u

   110     /**

   111      * From @c CCoeControl.

   112      *

   113      * Draw a control - called by window server. All controls, except blank 

   114      * controls, should implement this function. The default implementation 

   115      * draws a blank control.

   116      *

   117      * This function is used for window server-initiated redrawing of controls,

   118      * and for some application-initiated drawing. It should be implemented by 

   119      * each control, but is only called from within @c CCoeControl's member 

   120      * functions, and not from the derived class. For this reason it is a 

   121      * private member function of @c CCoeControl.

   122      *

   123      * @param aRect The region of the control to be redrawn. Co-ordinates are 

   124      *        relative to the control's origin (top left corner).

   125      * @panic EEikPanicLabelNullText Panics if label text has not been defined.

   126      */

   127     IMPORT_C void Draw(const TRect& aRect) const;

   128 

   129 public:  

   130     /**

   131      * Determines text emphasis.

   132      */

   133     enum TTextEmphasis

   134         {

   135         /** No emphasis. */

   136         ENoEmphasis         =0x00,

   137         

   138         /** Partial emphasis. */

   139         EPartialEmphasis    =0x10,

   140         

   141         /** Full emphasis. */

   142         EFullEmphasis	 =0x20

   143         };

   144 public:  // new functions

   145     

   146     /**

   147      * Sets the label’s text.

   148      *

   149      * @param aText The label’s text.

   150      * @panic EEikPanicLabelNullText Panics if label text has not been defined.

   151      */

   152     IMPORT_C void SetTextL(const TDesC& aText);

   153     

   154     /**

   155      * Gets the label’s text.

   156      *

   157      * @return The label’s text.

   158      */

   159     inline const TDesC* Text() const;

   160     

   161     /**

   162      * Sets a flag to indicate that the text needs to be truncated

   163      * with 3 dots.

   164      */

   165     IMPORT_C void CropText();

   166     

   167     /**

   168      * Sets the buffer reserve length.

   169      *

   170      * @param aLength The buffer reserve length.

   171      */

   172     IMPORT_C void SetBufferReserveLengthL(TInt aLength);

   173     

   174     /**

   175      * Sets the label’s font.

   176      *

   177      * @param aFont The label's font.

   178      */

   179     IMPORT_C void SetFont(const CFont* aFont);

   180     

   181     /**

   182      * Gets the label’s font.

   183      *

   184      * @return The label’s font.

   185      */

   186     inline const CFont* Font() const;

   187     

   188     /**

   189      * Sets the label's text emphasis.

   190      *

   191      * @param aEmphasis The label's text emphasis.

   192      */

   193     IMPORT_C void SetEmphasis(TTextEmphasis aEmphasis);

   194     

   195     /**

   196      * Sets the gap between lines. Gap has a particular definition here.

   197      * It is defined to be: "baselines separation" - @c CFont::HeightInPixels()

   198      * 

   199      * @param aGap Pixels gap to set between lines.

   200      */

   201     IMPORT_C void SetPixelGapBetweenLines(TInt aGap);

   202     

   203     /**

   204      * Gets the number of pixels between two lines of text.

   205      *

   206      * @return The number of pixels between two lines of text.

   207      */

   208     IMPORT_C TInt PixelGapBetweenLines() const;

   209 

   210     /**

   211      * Tests whether the label is underlined.

   212      *

   213      * @return @c ETrue if the label is set as underlined.

   214      * @return @c EFalse if the label is not set as underlined.

   215      */

   216     inline TBool IsUnderlined() const;

   217     

   218     /**

   219      * Sets the label underlining.

   220      *

   221      * @param aUnderLining @c ETrue to set the label as underlined. 

   222      *        @c EFalse to set the label as not underlined.

   223      */

   224     IMPORT_C void SetUnderlining(TBool aUnderLining);

   225     

   226     /**

   227      * Tests label strike-through.

   228      *

   229      * @return @c ETrue if the label is set to be drawn with a line through it.

   230      * @return @c EFalse if the label is not set to be drawn with a line 

   231      *            through it.

   232      */

   233     inline TBool IsStrikethrough() const;

   234     

   235     /**

   236      * Sets the label strike-through.

   237      *

   238      * @param aStrikethrough @c ETrue to set the label to be drawn with a line 

   239      *        through it. @c EFalse to set the label to not be drawn with a 

   240      *        line through it.

   241      */

   242     IMPORT_C void SetStrikethrough(TBool aStrikethrough);

   243     

   244     /**

   245      * Gets the minimum size required to draw the specified text.

   246      *

   247      * @param aText The text to be drawn.

   248      * @return The minimum size required to draw the text.

   249      */

   250     IMPORT_C TSize CalcMinimumSize(TPtrC& aText) const;

   251     

   252     /**

   253      * Gets the number of lines of text in the label.

   254      *

   255      * @return The number of lines of text.

   256      */

   257     inline TUint8 NumberOfLines();

   258     

   259     /**

   260      * Gets the buffer reserve length.

   261      *

   262      * @return The buffer reserve length.

   263      */

   264     IMPORT_C TInt BufferReserveLength() const;

   265 

   266     /**

   267      * Enables or disables logical to visual conversion when label text

   268      * is drawn. By default, it is enabled.

   269      * If you perform the conversion yourself and give visual text

   270      * (in scrictly left-to-right order) to label, you

   271      * should disable the conversion in label. Note that label does not perform

   272      * cropping if logical to visual conversion is disabled.

   273      *

   274      * @param aUseConversion Whether label should perform logical to visual

   275      *        conversion or not.

   276      */

   277     IMPORT_C void UseLogicalToVisualConversion( TBool aUseConversion );

   278 

   279     /**

   280      * Gets information whether label is performing logical to visual

   281      * conversion or not.

   282      *

   283      * @return @c ETrue if label does logical to visual conversion.

   284      * @return @c EFalse if not.

   285      */

   286     IMPORT_C TBool LogicalToVisualConversionUsed() const;

   287 

   288     /**

   289      * Enables pictograph drawing in the label text.

   290      * Only effective in Japanese variant.

   291      * By default, it is disabled.

   292      *

   293      * @since S60 2.6

   294      * @param aInterface Used pictograph interface owned by the caller.

   295      */

   296     IMPORT_C void EnablePictographsL( CAknPictographInterface& aInterface );

   297 

   298     /**

   299      * Disables pictograph drawing in the label text.

   300      * Only effective in Japanese variant.

   301      * By default, it is disabled.

   302      *

   303      * @since S60 2.6

   304      */

   305     IMPORT_C void DisablePictographs();

   306 public: // From CCoeControl

   307 

   308     /**

   309      * From @c CCoeControl.

   310      *

   311      * Handles pointer events. This function gets called whenever a pointer 

   312      * event occurs in the control, i.e. when the pointer is within the 

   313      * control's extent, or when the control has grabbed the pointer. 

   314      * The control should implement this function to handle pointer events.

   315      * 

   316      * Note: events of type @c EButton1Down are processed before 

   317      * @c HandlePointerEventL() is called, in order to transfer keyboard focus 

   318      * to the control in which the @c EButton1Down event occurred.

   319      *

   320      * If overriding @c HandlePointerEventL(), the implementation must include 

   321      * a base call to @c CCoeControl's @c HandlePointerEventL().

   322      *

   323      * @param aPointerEvent The pointer event.

   324      */

   325     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

   326 protected: // from CCoeControl

   327 

   328     /**

   329      * From @c CCoeControl.

   330      *

   331      * Writes the internal state of the control and its components to a stream.

   332      * Does nothing in release mode.

   333      * Designed to be overidden and base called by subclasses.

   334      *

   335      * @param aWriteStream The write stream.

   336      */

   337     IMPORT_C void WriteInternalStateL(RWriteStream& aWriteStream) const;

   338 private:

   339     IMPORT_C void Reserved_2();

   340 private:

   341     /**

   342      * From @c CAknControl.

   343      */

   344     IMPORT_C void* ExtensionInterface( TUid aInterface );

   345 private: // new functions

   346     TInt HeightInPixels() const;

   347     TInt WidthInPixels(TPtrC& aText) const;

   348     TInt HeightInPixels(const TDesC& aText) const;

   349     void SetupGcForEmphasis(CGraphicsContext& aGc) const;

   350     TBool CheckAndCreateExtension();

   351     void ConvertColorsForOutlineEffect(TRgb& aFillColor, TRgb& aOutlineColor) const;

   352 

   353 public:

   354     /**

   355      * @internal

   356      */

   357     void DrawToContext( CBitmapContext& aContext, 

   358         const TRgb* aOverrideColor ) const;

   359 

   360 protected:

   361     

   362     /**

   363      * Determines whether text is drawn with underlining or strike-through.

   364      */

   365     enum TLabelFlags

   366         {

   367         /** Text is drawn with underlining. */

   368         EUnderlining                  = 0x02,

   369         

   370         /** Text is drawn with strike-through. */

   371         EStrikethrough                = 0x04,

   372 

   373         /** 

   374          * Determines that bi-directional algorithm still needs to be run

   375          * against the set text string. This flag allows app to do

   376          * logical-to-visual conversion in the application side -- since the

   377          * bi-directional algorithm can only be run once for every text string,

   378          * we need flagging like this to control whether the algorithm is run

   379          * inside label or whether the application has already run it and we

   380          * should not return the algorithm.

   381          */

   382         EUseLogicalToVisualConversion = 0x08

   383         // flags 0x10, 0x20, 0x40 are already used for text emphasis!

   384         };

   385     

   386     /** The label’s text. */

   387     HBufC* iText;

   388     

   389     /** The label’s font. */

   390     const CFont* iFont;

   391     

   392     /** The label’s number of lines of text. */

   393     TUint8 iNumberOfLines;

   394     

   395     /**

   396      * The label’s flags. These are used to set text emphasis and 

   397      * characteristics, such as underlining, and strikethrough.

   398      */

   399     TUint8 iLabFlags;

   400 

   401     /** The number of pixels between lines of text. */

   402     TInt iGapBetweenLines;

   403 

   404 private:

   405     TInt iReserveLength;

   406     CEikLabelExtension* iExtension;

   407     TInt iSpare[2];

   408     };

   409 

   410 

   411 inline const TDesC* CEikLabel::Text() const

   412 	{ return(iText); }

   413 inline const CFont* CEikLabel::Font() const

   414 	{ return(iFont); }

   415 inline TBool CEikLabel::IsUnderlined() const

   416     {return iLabFlags&EUnderlining;}

   417 inline TBool CEikLabel::IsStrikethrough() const

   418     {return iLabFlags&EStrikethrough;}

   419 inline TUint8 CEikLabel::NumberOfLines()

   420 	{return iNumberOfLines;}	

   421 

   422 #endif // __EIKLABEL_H__