fe::IDecorator Class Reference
[Ferry Core library]

Instructs editor how to render text. More...

Inheritance diagram for fe::IDecorator:

fe::IPluggable fe::DecoratorStub fe::IDecoratorFilter fe::DecoratorFilterStub

List of all members.

Public Member Functions

virtual bool UC_DLL_CALL decorate (FeHandle *editor, unsigned line, const byte_type *str, unsigned len, IDecoratorListener &dl)=0
virtual IFontEnumerator
*UC_DLL_CALL 		enumFonts (FeHandle *editor) const =0
virtual bool UC_DLL_CALL isFixedLineHeight (FeHandle *editor) const =0
virtual unsigned UC_DLL_CALL onTextChange (FeHandle *editor, unsigned line, unsigned byteIdx, unsigned lineFirstByteIdx)=0

Detailed Description

Instructs editor how to render text.

This is the main entity controlling how editor renders text.

Sample decorator that colors all ASCII digit chars in green and set background of all odd text lines to gray:

decorator_green_digits.png 
#include <ctype.h>
#include "fe/ferry.h"


class SampleDecorator : public fe::DecoratorStub
{
private:
    fe::DecorMetrics    styles_[2];
    const char*         styleNames_[2];

public:
    SampleDecorator()
    {
        styles_[0] = fe::DecorMetrics(fe::TextStyle::makeStyle(0, 0x008800));
        styles_[1] = fe::DecorMetrics(fe::TextStyle::makeStyle(0, 0x000000));

        styleNames_[0] = "sample:digit";
        styleNames_[1] = "sample:other";
    }

// fe::DecoratorStub overridings
public:
    virtual bool UC_DLL_CALL
    decorate(
        fe::FeHandle*           editor,
        unsigned                line,
        const fe::byte_type*    str,
        unsigned                len,
        fe::IDecoratorListener& dl)
    {
        unsigned styleIdx;

        // Iterate all bytes in the passed in text line and identify
        // those bytes that represent ascii digit characters.
        for(const fe::byte_type* estr = str + len; str != estr; ++str)
        {
            if(isdigit((unsigned char)*str))
            {
                styleIdx = 0;
            }
            else
            {
                styleIdx = 1;
            }

            // notify editor
            dl.onSubstringDecorated(
                1, styles_[styleIdx], styleNames_[styleIdx]);
        }

        if(line % 2 == 0)
        {   // Color line backgrond.
            dl.onBodyBgColor(0xCCCCCC);
            dl.onEndlBgColor(0xCCCCCC);
        }

        return true;
    }

    virtual bool UC_DLL_CALL
    isFixedLineHeight(fe::FeHandle* editor) const
    {   // Notify editor that all text lines should have
        // the same fixed height.
        return true;
    }
};

Sample decorator that uses bigger font and blue color for quoted strings: the rest text's background is colored yellow.

decorator_quoted_strings.png 
#include <string.h>

#include "fe/ferry.h"
#include "fe/ferry_extensions.h"


class SampleDecorator : public fe::DecoratorStub
{
private:
    fe::PlatformTypes::font_handle_type smallFont_;
    fe::PlatformTypes::font_handle_type bigFont_;

    fe::DecorMetrics quotedStrStyle;
    fe::DecorMetrics otherStyle;

private:
    static const fe::byte_type*
    findDoubleQuote(const fe::byte_type* str, const fe::byte_type* estr)
    {
        for(; str < estr ; ++str)
        {
            if(*str == '"')
            {
                break;
            }
        }
        return str;
    }

private:
    // No copy semantics for simplicity.
    SampleDecorator(const SampleDecorator&);
    SampleDecorator& operator=(const SampleDecorator&);

public:
    SampleDecorator()
    {
        // Create fonts. No error checks for simplicity.

        fe::FontDesc desc;

        desc.size = 10;
        desc.style = fe::FontDesc::Plain;
        strcpy(desc.faceName, "Arial");

        smallFont_ = Fe_FontCreate(desc);
        // TBD: if(0 == smallFont_) throw ...

        desc.size = 20;
        desc.style = fe::FontDesc::Bold;
        strcpy(desc.faceName, "Courier");

        bigFont_ = Fe_FontCreate(desc);
        // TBD: if(0 == bigFont_) throw ...

        // Init styles
        quotedStrStyle  =
            fe::DecorMetrics(fe::TextStyle::makeStyle(bigFont_, 0x0000FF));
        otherStyle      =
            fe::DecorMetrics(
                fe::TextStyle::makeStyle(smallFont_, 0x000000, 0xFFFF00));
    }

    virtual ~SampleDecorator()
    {
        Fe_FontDelete(smallFont_);
        Fe_FontDelete(bigFont_);
    }

// fe::DecoratorStub overridings
public:
    virtual bool UC_DLL_CALL
    decorate(
        fe::FeHandle*           editor,
        unsigned                line,
        const fe::byte_type*    str,
        unsigned                len,
        fe::IDecoratorListener& dl)
    {
        for(const fe::byte_type* estr = str + len; str <= estr; )
        {
            // Find open double quote character.
            const fe::byte_type* qstr = findDoubleQuote(str, estr);
            dl.onSubstringDecorated(qstr - str, otherStyle, "sample:other");
            if(qstr == estr)
            {
                break;
            }

            // Find close double quote character.
            str = findDoubleQuote(qstr + 1, estr) + 1;

            dl.onSubstringDecorated(
                str - qstr, quotedStrStyle, "sample:quotedStr");
        }

        return true;
    }

    virtual unsigned UC_DLL_CALL
    onTextChange(unsigned line, unsigned byteIdx, unsigned lineFirstByteIdx)
    {
        // Inform editor that entire text line in which text change event
        // occured needs new decoration and redraw.
        return lineFirstByteIdx;
    }

    virtual fe::IFontEnumerator* UC_DLL_CALL
    enumFonts(fe::FeHandle* editor) const
    {
        class FontEnumerator : public fe::IFontEnumerator
        {
        UC_DLL_INTERFACE_IMPL(IFontEnumerator)
        private:
            unsigned                            idx_;
            fe::PlatformTypes::font_handle_type a_;
            fe::PlatformTypes::font_handle_type b_;

        public:
            FontEnumerator(
                fe::PlatformTypes::font_handle_type a,
                fe::PlatformTypes::font_handle_type b)
            {
                idx_    = 0;
                a_      = a;
                b_      = b;
            }

        public:
            virtual fe::PlatformTypes::font_handle_type UC_DLL_CALL
            next()
            {
                switch(idx_++)
                {
                case 0:
                    return a_;
                case 1:
                    return b_;
                default:
                    idx_ = 2;
                    return 0;
                }
            }
        };

        // Make sure exceptions don't go outside
        try
        {
            return new FontEnumerator(smallFont_, bigFont_);
        }
        catch(...)
        {
        }
        return 0;
    }
};
Note:
There are two editor extensions providing implementations of this interface based on external syntax highlighting engines:
See also:
fe::IEditorFacade::setDecorator()

fe::IEditorFacade::getDecorator()

Member Function Documentation

virtual bool UC_DLL_CALL fe::IDecorator::decorate ( FeHandle *  editor,
unsigned  line,
const byte_type *  str,
unsigned  len,
IDecoratorListener &  dl 
) [pure virtual]

Called by the attached editor when a text line needs decoration. Implementation should guarantee that after the fe::IDecorator is attached to some editor as many times the method is called for some text line it should provide the same decoration until text change event in some preceding or this text line occurs. If this criteria can't be met implementation should return false to indicate error.

Parameters:
editor editor calling the method; never 0;
line index of a text line to decorate;
str pointer to text line data; points to the first byte of the text line; the parameter is transient, i.e. it shouldn't be used outside of the method context, otherwise it is undefined behavior;
len size of text line data in bytes; *(str + len) == 0;
dl object that collects text line decoration data; the parameter is transient, i.e. it shouldn't be used outside of the method context, otherwise it is undefined behavior.

Implemented in fe::DecoratorFilterStub, and fe::DecoratorStub.

virtual unsigned UC_DLL_CALL fe::IDecorator::onTextChange ( FeHandle *  editor,
unsigned  line,
unsigned  byteIdx,
unsigned  lineFirstByteIdx 
) [pure virtual]

Called by an editor to notify attached fe::IDecorator that text change event occurred. Implementation should return text position starting from which editor should invalidate existing text decoration. This position may not be withing a text line addressed with the line parameter, i.e. the position can be anywhere in the whole editor's text.

Parameters:
editor editor calling the method; never 0;
line index of a text line at which text change event occurred;
byteIdx index of a text position at which text change event occurred;
lineFirstByteIdx index of the first byte of a text line addressed with the line parameter;

Implemented in fe::DecoratorFilterStub, and fe::DecoratorStub.

virtual IFontEnumerator* UC_DLL_CALL fe::IDecorator::enumFonts ( FeHandle *  editor  )  const [pure virtual]

Returns pointer to heap allocated object that enumerates fonts that can be used by the fe::IDecorator to decorate text. enumFonts() can return 0. This is not an indication of error. It is caller responsibility to free returned pointer. It is legal that the fe::IDecorator will use fonts not addressed with the returned fe::IFontEnumerator object to decorate text.

Implementation should guarantee that after the fe::IDecorator is attached to some editor as many times the method is called it should return the same value.

Parameters:
editor editor calling the method; never 0.
Note:
Editor uses information about fonts that decorator provides as a hint to calculate parameters for vertical/horizontal scrolling and empty text lines height.

Implemented in fe::DecoratorFilterStub, and fe::DecoratorStub.

virtual bool UC_DLL_CALL fe::IDecorator::isFixedLineHeight ( FeHandle *  editor  )  const [pure virtual]

Implementation should return true to indicate that all text lines of the given editor should have the same fixed height. In this case the caller editor will calculate text line height using set of fonts returned with the enumFonts() call.

If implementation returns false the caller editor will calculate height of every text line individually. In this case caller editor uses set of fonts returned with the enumFonts() call to calculate height of empty text lines.

Implementation should guarantee that after the fe::IDecorator is attached to some editor as many times the method is called it should return the same value.

Parameters:
editor editor calling the method; never 0.

Implemented in fe::DecoratorFilterStub, and fe::DecoratorStub.

The documentation for this class was generated from the following file:
Generated on Tue Nov 18 21:08:23 2008 for Ferry by doxygen 1.5.7.1
 http://sourceforge.net