• Immutable Page
  • Info
  • Attachments

CompText

class CompText
{
    public:
        /**
         * Flags to be passed into the flags field of CompTextAttrib
         */
        typedef enum {
            StyleBold      = (1 << 0), /**< render the text in bold */
            StyleItalic    = (1 << 1), /**< render the text italic */
            Ellipsized     = (1 << 2), /**< ellipsize the text if the
                                            specified maximum size is
                                            too small */
            WithBackground = (1 << 3), /**< render a rounded rectangle as
                                            background behind the text */
            NoAutoBinding  = (1 << 4) /**< do not automatically bind the
                                           rendered text pixmap to a texture */
        } Flags;

        typedef struct {
            const char     *family;    /**< font family */
            int            size;       /**< font size in points */
            unsigned short color[4];   /**< font color (RGBA) */

            unsigned int   flags;      /**< rendering flags, see above */

            int            maxWidth;   /**< maximum width of the
                                            generated pixmap */
            int            maxHeight;  /**< maximum height of the
                                            generated pixmap */

            int            bgHMargin;  /**< horizontal margin in pixels
                                            (offset of text into background) */
            int            bgVMargin;  /**< vertical margin */
            unsigned short bgColor[4]; /**< background color (RGBA) */
        } Attrib;

        CompText ();
        ~CompText();

        bool renderText (CompString   text,
                         const Attrib &attrib);


        bool renderWindowTitle (Window       window,
                                bool         renderViewportNumber,
                                const Attrib &attrib);

        void clear ();

        Pixmap getPixmap ();
        int getWidth () const;
        int getHeight () const;

        void draw (float x,
                   float y,
                   float alpha) const;

    private:
        int width;
        int height;

        Pixmap          pixmap;
        GLTexture::List texture;
};

Setting up the rendering

The first thing you will want to do before rendering any text is to create a CompText::Attrib which describes some properties of your text; font family, font size, font color etc.

Property Name

Function

.family

Specify a font to use for rendering. The font is specified as a char *, so you need to know in advance which fonts are supported by the system. If unsure, use the default

.size

How large in font-point size the text should be

.color

A 4-byte array describing the red, green, blue and alpha of the text itself (not the background)

.flags

Bitmask to control basic text rendering

Bold Text

Italic Text

Ellipsize text if render size is too small

Rounded rectangle behind text

Do not automatically bind text pixmap to texture

StyleBold

StyleItalitc

Ellipsized

WithBackground

NoAutoBinding

.maxWidth

The maximum width the rendered pixmap is allowed to be

.maxHeight

The maximum height the rendered pixmap is allowed to be

.bgHMargin

Amount of horizontal space between right side of background and text

.bgVMargin

Amount of vertical space between the top of the background and the text

.bgColor

A 4-byte array describing the red, green, blue and alpha values of the background to the text

Not all attributes must be set, if an attribute is not set, then the default will be used. Once you have finished constructing the CompText::Attrib, you can save it and render any text or window titles to a CompText object.

Rendering text

Once a CompText::Attrib is set up, you can use ::renderText (CompString &, const Attrib &) to render any text and save it in the CompText object.

/!\ Each CompText object only saves the last rendered text and background image in it's own class. If you need to render multiple bits of text on screen and draw them all, then you should use multiple objects.

Rendering a window title

In most cases, you will likely want to display the title of the selected window on-screen. Rather than going through the complicated process of retrieving the utf8 atom from X11, you can use ::renderWindowTitle (Window, bool, const Attrib &); where Window is the X11 id of the window and bool viewportNumber is whether to also render the corresponding viewport number of the window to the text.

Drawing the text on-screen

/!\ The ::draw () method cannot be used if NoAutoBinding was passed to .flags in CompText::Attrib

Once the text is rendered, you can draw it on screen. CompText includes a convenience function to do this for you, ::draw (int, int, float);, where you specify the x, y co-ordinates of the text and the opacity (0 to 1) of the text when rendered on screen. Note that this function does not set up an OpenGL Context for you to render to, you must handle that yourself in your ::paintOutput and then call ::draw.

Binding the text yourself

In some cases, you may wish to use the text pixmap directly and bind this to your own texture, rather than using CompText. The Group Plugin is a good example of a plugin that does this.

In that case, you must pass NoAutoBinding to .flags in your CompText::Attrib. In this case, the rendered pixmap is not bound to a texture, and will not be destroyed when the text is re-rendered. You can retrieve the rendered pixmap with ::getPixmap and it's resultant dimentions with ::getWidth and ::getHeight.

/!\ Failure to call XDestroyPixmap (pixmap); in this case will result in a memory leak!

Development/zero-nine/PluginsClasses/Text (last edited 2010-10-03 15:43:08 by 124-169-58-87)