2 * Copyright (c) 1997-1999 Nokia Corporation and/or its subsidiary(-ies).
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".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
19 #if !defined(__EIKLABEL_H__)
20 #define __EIKLABEL_H__
23 #if !defined(__EIKALIGN_H__)
27 #if !defined(__COECCNTX_H__)
33 class CEikLabelExtension;
34 class CAknPictographInterface;
37 * Enables one or more lines of text to be displayed.
39 class CEikLabel : public CEikAlignedControl, public MCoeControlContext
41 public: // new functions
45 IMPORT_C ~CEikLabel();
47 * C++ default constructor.
51 * Sets the labels alignment. Overwrites alignment set
52 * via @c CEikAlignedControl.
54 * @param aAlignment Should be one of { @c ELayoutAlignNone,
55 * @c ELayoutAlignCenter, @c ELayoutAlignLeft, @c ELayoutAlignRight,
56 * @c ELayoutAlignBidi } defined in @c Avkon.hrh.
58 IMPORT_C void SetLabelAlignment(TInt aAlignment);
61 * Sets the brush style to be used from @c aBrushStyle,
62 * this overwrites the brush style set via the Control Context.
64 * @param aBrushStyle A brush style.
66 IMPORT_C void SetBrushStyle(CWindowGc::TBrushStyle aBrushStyle);
69 * Sets the brush style to be used from the Control Context,
70 * this overwrites the brush style set via the @c CEikLabel::SetBrushStyle().
72 IMPORT_C void SetBrushStyleFromContext();
75 public: // from CCoeControl
77 * From @c CCoeControl.
79 * Sets the control's minimum required size.
81 * @return Minimum size required by the control.
83 IMPORT_C TSize MinimumSize();
85 * From @c CCoeControl.
87 * Constructs the control from a resource file.
89 * @param aReader Interprets resource data read from a resource file.
91 IMPORT_C void ConstructFromResourceL(TResourceReader& aReader);
94 * From @c CCoeControl.
96 * Gets the list of logical colours used to draw the control.
98 * @param aColorUseList The colour list.
100 IMPORT_C void GetColorUseListL(
101 CArrayFix<TCoeColorUse>& aColorUseList) const;
103 * From @c CCoeControl.
105 * Handles a change to the control's resources.
107 * @param aType A message UID value.
109 IMPORT_C void HandleResourceChange(TInt aType); // not available before Release 005u
111 * From @c CCoeControl.
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.
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.
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.
127 IMPORT_C void Draw(const TRect& aRect) const;
131 * Determines text emphasis.
138 /** Partial emphasis. */
139 EPartialEmphasis =0x10,
141 /** Full emphasis. */
144 public: // new functions
147 * Sets the label’s text.
149 * @param aText The label’s text.
150 * @panic EEikPanicLabelNullText Panics if label text has not been defined.
152 IMPORT_C void SetTextL(const TDesC& aText);
155 * Gets the label’s text.
157 * @return The label’s text.
159 inline const TDesC* Text() const;
162 * Sets a flag to indicate that the text needs to be truncated
165 IMPORT_C void CropText();
168 * Sets the buffer reserve length.
170 * @param aLength The buffer reserve length.
172 IMPORT_C void SetBufferReserveLengthL(TInt aLength);
175 * Sets the label’s font.
177 * @param aFont The label's font.
179 IMPORT_C void SetFont(const CFont* aFont);
182 * Gets the label’s font.
184 * @return The label’s font.
186 inline const CFont* Font() const;
189 * Sets the label's text emphasis.
191 * @param aEmphasis The label's text emphasis.
193 IMPORT_C void SetEmphasis(TTextEmphasis aEmphasis);
196 * Sets the gap between lines. Gap has a particular definition here.
197 * It is defined to be: "baselines separation" - @c CFont::HeightInPixels()
199 * @param aGap Pixels gap to set between lines.
201 IMPORT_C void SetPixelGapBetweenLines(TInt aGap);
204 * Gets the number of pixels between two lines of text.
206 * @return The number of pixels between two lines of text.
208 IMPORT_C TInt PixelGapBetweenLines() const;
211 * Tests whether the label is underlined.
213 * @return @c ETrue if the label is set as underlined.
214 * @return @c EFalse if the label is not set as underlined.
216 inline TBool IsUnderlined() const;
219 * Sets the label underlining.
221 * @param aUnderLining @c ETrue to set the label as underlined.
222 * @c EFalse to set the label as not underlined.
224 IMPORT_C void SetUnderlining(TBool aUnderLining);
227 * Tests label strike-through.
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
233 inline TBool IsStrikethrough() const;
236 * Sets the label strike-through.
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
242 IMPORT_C void SetStrikethrough(TBool aStrikethrough);
245 * Gets the minimum size required to draw the specified text.
247 * @param aText The text to be drawn.
248 * @return The minimum size required to draw the text.
250 IMPORT_C TSize CalcMinimumSize(TPtrC& aText) const;
253 * Gets the number of lines of text in the label.
255 * @return The number of lines of text.
257 inline TUint8 NumberOfLines();
260 * Gets the buffer reserve length.
262 * @return The buffer reserve length.
264 IMPORT_C TInt BufferReserveLength() const;
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.
274 * @param aUseConversion Whether label should perform logical to visual
277 IMPORT_C void UseLogicalToVisualConversion( TBool aUseConversion );
280 * Gets information whether label is performing logical to visual
283 * @return @c ETrue if label does logical to visual conversion.
284 * @return @c EFalse if not.
286 IMPORT_C TBool LogicalToVisualConversionUsed() const;
289 * Enables pictograph drawing in the label text.
290 * Only effective in Japanese variant.
291 * By default, it is disabled.
294 * @param aInterface Used pictograph interface owned by the caller.
296 IMPORT_C void EnablePictographsL( CAknPictographInterface& aInterface );
299 * Disables pictograph drawing in the label text.
300 * Only effective in Japanese variant.
301 * By default, it is disabled.
305 IMPORT_C void DisablePictographs();
306 public: // From CCoeControl
309 * From @c CCoeControl.
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.
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.
320 * If overriding @c HandlePointerEventL(), the implementation must include
321 * a base call to @c CCoeControl's @c HandlePointerEventL().
323 * @param aPointerEvent The pointer event.
325 IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);
326 protected: // from CCoeControl
329 * From @c CCoeControl.
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.
335 * @param aWriteStream The write stream.
337 IMPORT_C void WriteInternalStateL(RWriteStream& aWriteStream) const;
339 IMPORT_C void Reserved_2();
342 * From @c CAknControl.
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;
357 void DrawToContext( CBitmapContext& aContext,
358 const TRgb* aOverrideColor ) const;
363 * Determines whether text is drawn with underlining or strike-through.
367 /** Text is drawn with underlining. */
370 /** Text is drawn with strike-through. */
371 EStrikethrough = 0x04,
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.
382 EUseLogicalToVisualConversion = 0x08
383 // flags 0x10, 0x20, 0x40 are already used for text emphasis!
386 /** The label’s text. */
389 /** The label’s font. */
392 /** The label’s number of lines of text. */
393 TUint8 iNumberOfLines;
396 * The label’s flags. These are used to set text emphasis and
397 * characteristics, such as underlining, and strikethrough.
401 /** The number of pixels between lines of text. */
402 TInt iGapBetweenLines;
406 CEikLabelExtension* iExtension;
411 inline const TDesC* CEikLabel::Text() const
413 inline const CFont* CEikLabel::Font() const
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;}
422 #endif // __EIKLABEL_H__