# Text

Alan Perlis

A picture is worth 10K words - but only those to describe the picture. Hardly any sets of 10K words can be adequately described with pictures.

## Introduction

User interfaces can rely on textures to represent actions, but there are cases where you need to convey an idea using words.

Clutter provides an actor that allows displaying and editing arbitrary text, called ClutterText. A ClutterText actor can be positioned like any other actor; its preferred size is determined by its contents, as well as the font family and size used to render those contents.

## Drawing a shadow under the text

### Problem

You want to draw a shadow under the text displayed by a ClutterText actor.

### Solution

Override the `paint` signal of ClutterText and use the CoglPango API to paint the PangoLayout of the actor with the color of the shadow at a given offset.

A ClutterText actor painting a shadow underneath its contents

### Discussion

The ClutterText class provides an actor that transforms the PangoLayout object into an element of the Clutter scene graph. The underlying layout is painted, though, through a subset of the Cogl API, called CoglPango.

It is possible to paint PangoLayout created by a ClutterText by invoking `cogl_pango_render_layout()`:

    void
    cogl_pango_render_layout (PangoLayout *layout,
                              int          x_offset,
                              int          y_offset,
                              CoglColor   *text_color,
                              int          flags);

This function will paint the layout at the given offsets using the provided color.

The `cogl_pango_render_layout()` function will only work with PangoLayouts created by Clutter.

Since the shadow of the text is literally the same text but painted with a different color and at an offset, we can use the `paint` signal of ClutterText to paint the shadow, and then let ClutterText paint its contents on top:

    static void
    _text_paint_cb (ClutterActor *actor)
    {
      ClutterText *text = CLUTTER_TEXT (actor);

      /* Get the PangoLayout that the Text actor is going to paint... */
      PangoLayout *layout;
      layout = clutter_text_get_layout (text);

      /* ... Create the color of the shadow... */

      /* ... Finally, render the Text layout at a given
       * offset using the color of the shadow
       */
      cogl_pango_render_layout (layout,
                                SHADOW_X_OFFSET, SHADOW_Y_OFFSET,
                                &color, 0);
    }

Note that we are using the PangoLayout of the ClutterText because the ClutterText actor always keeps an updated layout internally. It is, however, possible for any ClutterActor to create a PangoLayout using `clutter_actor_create_pango_layout()`, and then paint that layout using `cogl_pango_render_layout()` in their implementation of the `paint` virtual function.

### Full example

#### Creating a shadow of a text

                FIXME: MISSING XINCLUDE CONTENT