TextRenderer

public class TextRenderer
extends Object

java.lang.Object
   ↳ android.support.wearable.complications.rendering.TextRenderer


Renders text onto a canvas.

Watch faces can use TextRenderer to render text on a canvas within specified bounds. This is intended for use when rendering complications. The layout is only recalculated if the text, the bounds, or the drawing properties change, allowing this to be called efficiently on every frame.

TextRenderer also ensures that a minimum number of characters are always displayed, by shrinking the text size if necessary to make the characters fit. The default is to always show at least 7 characters, which matches the requirement for the 'short text' fields of complications.

To use, instantiate a TextRenderer object and set the TextPaint that should be used. Only instantiate and set the paint once on each text renderer - you should not do this within the draw method. Each distinct piece of text should have its own TextRenderer - so for example you might need one for the 'short text' field, and one for the 'short title' field:

   mTitleRenderer = new TextRenderer();
   mTitleRenderer.setPaint(mTitlePaint);
   mTextRenderer = new TextRenderer();
   mTextRenderer.setPaint(mTextPaint);

When drawing a frame, set the current text value on the text renderer (using the current time so that any time-dependent text has an up-to-date value), and then call draw on the renderer with the bounds you need:

   // Set the text every time you draw, even if the ComplicationData has not changed, in case
   // the text includes a time-dependent value.
   mTitleRenderer.setText(
       ComplicationText.getText(context, complicationData.getShortTitle(), currentTimeMillis));
   mTextRenderer.setText(
       ComplicationText.getText(context, complicationData.getShortText(), currentTimeMillis));

   // Assuming both the title and text exist.
   mTitleRenderer.draw(canvas, titleBounds);
   mTextRenderer.draw(canvas, textBounds);

The layout of the text may be customised by calling methods such as setAlignment(Layout.Alignment), setGravity(int), and setRelativePadding(float, float, float, float). These methods may be called on every frame - the layout will only be recalculated if necessary.

If the properties of the TextPaint or content of the text have changed, then the TextRenderer may not be aware that the layout needs to be updated. In this case a layout update should be forced by calling requestUpdateLayout().

TextRenderer also hides characters and styling that may not be suitable for display in ambient mode - for example full color emoji. To allow this to work, watch faces must call setInAmbientMode(boolean) on every TextRenderer whenever the watch enters or exits ambient mode (i.e. whenever onAmbientModeChanged(boolean) is called).

Summary

Public constructors

TextRenderer()

Public methods

void draw(Canvas canvas, Rect bounds)

Draws the text onto the canvas within the specified bounds.

boolean hasText()

Returns true if text has been set on this renderer.

boolean isLtr()

Returns true if the text will be drawn by this renderer in a left-to-right direction.

void requestUpdateLayout()

Requests that the text be laid out again when draw is next called.

void setAlignment(Layout.Alignment alignment)

Sets the alignment of the text.

void setEllipsize(TextUtils.TruncateAt ellipsize)

Sets how the text should be ellipsized if it does not fit in the specified number of lines.

void setGravity(int gravity)

Sets the gravity that will be used to position the text within the bounds.

void setInAmbientMode(boolean inAmbientMode)

Sets if the watch face is in ambient mode.

void setMaxLines(int maxLines)

Sets the maximum number of lines of text that will be drawn.

void setMinimumCharactersShown(int minCharactersShown)

Sets the minimum number of characters to be shown.

void setPaint(TextPaint paint)

Sets the paint that will be used to draw the text.

void setRelativePadding(float start, float top, float end, float bottom)

Sets the padding which will be applied to the bounds before the text is drawn.

void setText(CharSequence text)

Sets the text that will be drawn by this renderer.

Inherited methods

From class java.lang.Object

Public constructors

TextRenderer

TextRenderer ()

Public methods

draw

void draw (Canvas canvas, 
                Rect bounds)

Draws the text onto the canvas within the specified bounds.

This will only lay the text out again if the width of the bounds has changed or if the parameters have changed. If the properties of the paint have changed, and setPaint(TextPaint) has not been called, requestUpdateLayout() must be called.

Parameters
canvas Canvas: the canvas that the text will be drawn onto

bounds Rect: boundaries of the text within specified canvas

hasText

boolean hasText ()

Returns true if text has been set on this renderer.

Returns
boolean

isLtr

boolean isLtr ()

Returns true if the text will be drawn by this renderer in a left-to-right direction.

Returns
boolean

requestUpdateLayout

void requestUpdateLayout ()

Requests that the text be laid out again when draw is next called. This must be called if the properties of the paint or the content of the text have changed but setPaint(TextPaint) has not been called.

setAlignment

void setAlignment (Layout.Alignment alignment)

Sets the alignment of the text.

Parameters
alignment Layout.Alignment

setEllipsize

void setEllipsize (TextUtils.TruncateAt ellipsize)

Sets how the text should be ellipsized if it does not fit in the specified number of lines. The default is END.

Pass in null to cause text to be truncated but not ellipsized.

Parameters
ellipsize TextUtils.TruncateAt

setGravity

void setGravity (int gravity)

Sets the gravity that will be used to position the text within the bounds.

Note that the text should be considered to fill the available width, which means that this cannot be used to position the text horizontally. Use setAlignment(Layout.Alignment) instead for horizontal position.

If not called, the default is CENTER.

Parameters
gravity int: Gravity to position text, should be one of the constants specified in Gravity class.

setInAmbientMode

void setInAmbientMode (boolean inAmbientMode)

Sets if the watch face is in ambient mode. Watch faces should call this function while going in and out of ambient mode. This allows TextRenderer to remove special characters and styling that may not be suitable for displaying in ambient mode.

Parameters
inAmbientMode boolean

setMaxLines

void setMaxLines (int maxLines)

Sets the maximum number of lines of text that will be drawn. The default is 1 and if a non-positive number is given, it will be ignored.

Parameters
maxLines int

setMinimumCharactersShown

void setMinimumCharactersShown (int minCharactersShown)

Sets the minimum number of characters to be shown. If available space is too narrow, font size may be decreased to ensure showing at least this many characters. The default is 7 which is the number of characters that should always be displayed without truncation when rendering the short text or short title fields of a complication.

Parameters
minCharactersShown int

setPaint

void setPaint (TextPaint paint)

Sets the paint that will be used to draw the text.

Parameters
paint TextPaint

setRelativePadding

void setRelativePadding (float start, 
                float top, 
                float end, 
                float bottom)

Sets the padding which will be applied to the bounds before the text is drawn. The start and end parameters should be given as a proportion of the width of the bounds, and the top and bottom parameters should be given as a proportion of the height of the bounds.

Parameters
start float

top float

end float

bottom float

setText

void setText (CharSequence text)

Sets the text that will be drawn by this renderer.

If the text contains spans, some of them may not be rendered by this class. Supported spans are ForegroundColorSpan, LocaleSpan, SubscriptSpan, SuperscriptSpan, StrikethroughSpan, TypefaceSpan and UnderlineSpan.

Parameters
text CharSequence