fe::ICharacterDecoratorFactory Class Reference
[Ferry Extensions library]

Factory to create editor extensions providing custom characters decoration. More...

Inheritance diagram for fe::ICharacterDecoratorFactory:

fe::IExtensionFactory

List of all members.

Public Types

enum  CharacterClassDecorator {
  ccdDot, ccdArrow, ccdCharCodeUtf32, ccdCharCodeUtf16,
  ccdCharCodeUtf8, ccdUnknown, ccdCustom
}
 Character class decorator IDs. More...
enum  CharacterClassType { cctWhiteSpace, cctTab, cctControl, cctCustom }
 Character class type IDs. More...

Public Member Functions

virtual bool UC_DLL_CALL addCharacterClass (const ICharacterClass &cc)=0
virtual bool UC_DLL_CALL assignDecoratorToId (int ccd, ISubstringDecorator *sd)=0
virtual ICharacterClassBuilder
*UC_DLL_CALL 		createCharacterClassBuilder (int type)=0
virtual bool UC_DLL_CALL delCharacterClass (const ICharacterClass &cc)=0
virtual void UC_DLL_CALL deleteAllCharacterClasses ()=0
virtual int UC_DLL_CALL getCharacterClassDecoratorId (const ICharacterClass &cc) const =0
virtual ISubstringDecorator
*UC_DLL_CALL 		getIdDecorator (int ccd) const =0
virtual bool UC_DLL_CALL hasCharacterClass (const ICharacterClass &cc) const =0
virtual bool UC_DLL_CALL replaceCharacterClass (const ICharacterClass &from, const ICharacterClass &to)=0
virtual bool UC_DLL_CALL setCharacterClassDecoratorId (const ICharacterClass &cc, int ccd)=0

Detailed Description

Factory to create editor extensions providing custom characters decoration.

The idea of editor extensions created by this factory is to provide decoration of characters with different fe::ISubstringDecorator-based classes. Every extension created with this factory and assigned to some editor registers a filter decorator with the fe::IEditorFacade::addDecoratorFilter() call. Every time editor requests decoration for some text line the registered filter decorator examines the text line for characters that have been configured with fe::ICharacterDecoratorFactory to have custom decoration. For every matched character the filter replaces its decoration on condition the previous filter/top level decorator provided a plain (fe::TextStyle) decoration for the character.

Both predefined and user supplied implementations of fe::ISubstringDecorator class can be used for custom characters decoration.

The factory operates not with a distinct characters but with character groups, i.e. factory binds character groups with decorators so the same decorator is applied to all characters from the same group. fe::ICharacterClass and fe::ICharacterClassBuilder interfaces provide abstractions for mutable and immutable character groups. The factory operates only on immutable groups.

Instead of direct <group> - <decorator> link the more complicated relationship is used: <group> - <decorator ID> - <decorator>. This is needed to provide use of predefined and user supplied implementations of fe::ISubstringDecorator class in a single consistent way. The predefined decorators are addressed with ccdDot, ccdArrow, ccdCharCodeUtf32, ccdCharCodeUtf16 and ccdCharCodeUtf8 IDs.

The sample code below demonstrates how to configure instance of fe::ICharacterDecoratorFactory class using helper fe::CharClassConfigurator class so that the factory produce editor extensions that when attached to some editor force it to: 

#include "fe/ferry_extensions.h"

#include <memory> // std::auto_ptr


class CharClassConfiguratorError
{
public:
    explicit CharClassConfiguratorError(int reason)
    {   // ignore 'reason' value for simplicity
    }
};


StarSubstringDecorator starDecorator(
    30 /* size in pixels of a bounding box for a star figure */);


fe::IExtension*
createEditorExtension()
{
    fe::IExtension* ext = 0;

    // Create factory.
    std::auto_ptr<fe::ICharacterDecoratorFactory> factory(
        Fe_CreateCharacterDecoratorFactory());

    if(factory.get())
    {
        typedef fe::CharClassConfigurator<
            CharClassConfiguratorError> ConfiguratorType;

        // Add character class that encapsulates all control characters
        // to the factory.
        // Note: can throw CharClassConfiguratorError instance on error.
        ConfiguratorType ctrlCharsClass(
            *factory, fe::ICharacterDecoratorFactory::cctControl);
        ctrlCharsClass.commit(
            fe::ICharacterDecoratorFactory::ccdCharCodeUtf32);

        // Create empty character class.
        // Note: can throw CharClassConfiguratorError instance on error.
        ConfiguratorType customCharClass(
            *factory, fe::ICharacterDecoratorFactory::cctCustom);
        // Add 'Z' letter to the class.
        // Note: can throw CharClassConfiguratorError instance on error.
        customCharClass.addChar('Z');
        // Add both capital and small 'yat' Cyrillic characters to the class.
        // Note: can throw CharClassConfiguratorError instance on error.
        customCharClass.addChars(0x0462, 0x0463 + 1);

        enum
        {
            StarDecoratorId = fe::ICharacterDecoratorFactory::ccdCustom + 10
        };

        // Append the class to the factory.
        // Note: can throw CharClassConfiguratorError instance on error.
        customCharClass.commit(StarDecoratorId);

        // Associate custom ISubstringDecorator implementation with
        // the 'customCharClass'.
        if(!factory->assignDecoratorToId(StarDecoratorId, &starDecorator))
        {   // Error occurred
            return 0;
        }

        // Add character class that encapsulates a single TAB character
        // to the factory.
        // Note: can throw CharClassConfiguratorError instance on error.
        ConfiguratorType tabCharClass(
            *factory, fe::ICharacterDecoratorFactory::cctTab);
        tabCharClass.commit(fe::ICharacterDecoratorFactory::ccdArrow);

        // Create editor extension.
        ext = factory->createExtension();

        // At this point all ConfiguratorType instances can be destroyed as
        // they don't affect created extension.

        //
        // 1. Caller should call fe::IExtension::attachToEditor() method on
        //    the returned object to attach it to some editor.
        //
        // 2. Caller should delete returned pointer to free resources when
        //    editor extension is not needed any more.
        //
    }

    return ext;

    // At this point 'factory' will be deleted automatically.
}

The below images show how mix of binary/text data loaded in an editor is displayed before and after an editor extension created with the createEditorExtension() function is attached.

Before:

character_decorator_factory.set=false.png
After:
character_decorator_factory.set=true.png

See also:
Fe_CreateCharacterDecoratorFactory()

fe::CharClassConfigurator

Member Function Documentation

virtual bool UC_DLL_CALL fe::ICharacterDecoratorFactory::addCharacterClass ( const ICharacterClass &  cc  )  [pure virtual]

Adds new character class to the factory. Implementation should return false if the given character class has been added to the factory already of if adding failed.

Parameters:
cc character class to add.

virtual bool UC_DLL_CALL fe::ICharacterDecoratorFactory::delCharacterClass ( const ICharacterClass &  cc  )  [pure virtual]

Deletes the given character class from the factory. Implementation should return false if the given character class has not been added to the factory or if deletion failed.

Parameters:
cc character class to delete.

virtual bool UC_DLL_CALL fe::ICharacterDecoratorFactory::replaceCharacterClass ( const ICharacterClass &  from,
const ICharacterClass &  to 
) [pure virtual]

Replaces one character class with another. Implementation should return false if the from character class has not been added to the factory yet or if the to character class has been added to the factory already.

Parameters:
from character class to replace;
to replacement character class.

virtual bool UC_DLL_CALL fe::ICharacterDecoratorFactory::hasCharacterClass ( const ICharacterClass &  cc  )  const [pure virtual]

Implementation should return true if the given character class has been added to the factory already.

Parameters:
cc character class to test.

virtual void UC_DLL_CALL fe::ICharacterDecoratorFactory::deleteAllCharacterClasses (  )  [pure virtual]

Deletes all previously added character classes from the factory.

virtual bool UC_DLL_CALL fe::ICharacterDecoratorFactory::setCharacterClassDecoratorId ( const ICharacterClass &  cc,
int  ccd 
) [pure virtual]

Associates character class decorator given with an ID (ccd) with a character class (cc). Returns true on success. Returns false if the given character class has not been added to this factory yet or if the ID of a character class decorator is ccdUnknown.

The actual decorator that decorates characters from some character class is an instance of fe::ISubstringDecorator-based class. assignDecoratorToId() should be used to assign instance of some fe::ISubstringDecorator-based class to some character class decorator.

Parameters:
cc character class; the character class should have been added to this factory by the previous addCharacterClass() call;
ccd character class decorator ID; the value should be from the [ccdDot, ccdUnknown) or [ccdCustom, (unsigned)-1) ranges.

virtual int UC_DLL_CALL fe::ICharacterDecoratorFactory::getCharacterClassDecoratorId ( const ICharacterClass &  cc  )  const [pure virtual]

Returns ID of a character class decorator assigned to the given character class. Returns ccdUnknown if the given character class has not been added to this factory with the previous addCharacterClass() call.

Parameters:
cc character class.

virtual bool UC_DLL_CALL fe::ICharacterDecoratorFactory::assignDecoratorToId ( int  ccd,
ISubstringDecorator *  sd 
) [pure virtual]

Assigns the given substring decorator (sd) to the given character class decorator ID (id). Returns true on success. Returns false if the ID of a character class decorator is ccdUnknown.

The given substring decorator will be used by editor extensions created by this factory to decorate characters from character classes assigned to the given character class decorator ID with the previous setCharacterClassDecoratorId() calls.

Parameters:
ccd character class decorator ID; the value should be from the [ccdDot, ccdUnknown) or [ccdCustom, (unsigned)-1) ranges;
sd substring decorator to assign to the given ID.

virtual ISubstringDecorator* UC_DLL_CALL fe::ICharacterDecoratorFactory::getIdDecorator ( int  ccd  )  const [pure virtual]

Returns substring decorator assigned to the given character class decorator ID.

virtual ICharacterClassBuilder* UC_DLL_CALL fe::ICharacterDecoratorFactory::createCharacterClassBuilder ( int  type  )  [pure virtual]

Returns heap allocated character class builder object initialized depending on the given character class type. Implementation should return 0 if error occurred or if the value of type parameter is not a valid constant.

Parameters:
type character class type; should be one of cctWhiteSpace, cctTab, cctControl or cctCustom constants.
Note:
You normally shouldn't call this function directly, instead use fe::CharClassConfigurator helper class to configure character classes.

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