epoc32/include/mw/eiklabel.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100 (2010-03-31)
branchSymbian3
changeset 4 837f303aceeb
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) 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__