Summary: Ctors | Methods | Inherited Methods

TextRenderer

public class TextRenderer
extends Object

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

This class is deprecated.
use the Jetpack Wear Watch Face libraries instead.

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 WatchFaceService.Engine.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

`Object`	`clone()`
`boolean`	`equals(Object arg0)`
`void`	`finalize()`
`final Class<?>`	`getClass()`
`int`	`hashCode()`
`final void`	`notify()`
`final void`	`notifyAll()`
`String`	`toString()`
`final void`	`wait(long arg0, int arg1)`
`final void`	`wait(long arg0)`
`final void`	`wait()`

Public constructors

TextRenderer

public TextRenderer ()

Public methods

draw

public 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

public boolean hasText ()

Returns true if text has been set on this renderer.

Returns
`boolean`

isLtr

public boolean isLtr ()

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

Returns
`boolean`

requestUpdateLayout

public 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

public void setAlignment (Layout.Alignment alignment)

Sets the alignment of the text.

Parameters
`alignment`	`Layout.Alignment`

setEllipsize

public 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 TextUtils.TruncateAt.END.

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

Parameters
`ellipsize`	`TextUtils.TruncateAt`

setGravity

public 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 Gravity.CENTER.

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

setInAmbientMode

public 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

public 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

public 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

public void setPaint (TextPaint paint)

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

Parameters
`paint`	`TextPaint`

setRelativePadding

public 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

public 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`