## Tag Handlers

The wxHTML library provides architecture of pluggable tag handlers. Tag handler is class that understands particular HTML tag (or tags) and is able to interpret it.

wxHtmlWinParser has static table of modules. Each module contains one or more tag handlers. Each time a new wxHtmlWinParser object is constructed all modules are scanned and handlers are added to wxHtmlParser's list of available handlers (note: wxHtmlParser's list is non-static).

How it works

Common tag handler's HandleTag method works in four steps:

1. Save state of parent parser into local variables
2. Change parser state according to tag's params
3. Parse text between the tag and paired ending tag (if present)
4. Restore original parser state

See wxHtmlWinParser for methods for modifying parser's state. In general you can do things like opening/closing containers, changing colors, fonts etc.

Providing own tag handlers

You should create new .cpp file and place following lines into it:

    #include <mod_templ.h>
    #include <forcelink.h>
    FORCE_LINK_ME(yourmodulefilenamewithoutcpp)

Then you must define handlers and one module.

Tag handlers

The handler is derived from wxHtmlWinTagHandler (or directly from wxHtmlTagHandler)

You can use set of macros to define the handler (see src/mod_*.cpp files for details). Handler definition must start with TAG_HANDLER_BEGIN macro and end with TAG_HANDLER_END macro. I strongly recommend to have a look at include/wxhtml/mod_templ.h file. Otherwise you won't understand the structure of macros. See macros reference:

TAG_HANDLER_BEGIN(name, tags)

Starts handler definition. name is handler identifier (in fact part of class name), tags is string containing list of tags supported by this handler (in uppercase). This macro derives new class from wxHtmlWinTagHandler and implements it is GetSupportedTags method.

Example: TAG_HANDLER_BEGIN(FONTS, "B,I,U,T")

TAG_HANDLER_VARS

This macro starts block of variables definitions. (Variables are identical to class attributes.) Example:

    TAG_HANDLER_BEGIN(VARS_ONLY, "CRAZYTAG")
        TAG_HANDLER_VARS
            int my_int_var;
    	wxString something_else;
    TAG_HANDLER_END(VARS_ONLY)

This macro is used only in rare cases.

TAG_HANDLER_CONSTR(name)

This macro supplies object constructor. name is same name as the one from TAG_HANDLER_BEGIN macro. Body of constructor follow after this macro (you must use and ). Example:

    TAG_HANDLER_BEGIN(VARS2, "CRAZYTAG")
        TAG_HANDLER_VARS
            int my_int_var;
        TAG_HANDLER_CONSTR(vars2)
            { // !!!!!!
    	    my_int_var = 666;
    	} // !!!!!!
    TAG_HANDLER_END(VARS2)

Never used in wxHTML :-)

TAG_HANDLER_PROC(varib)

This is very important macro. It defines HandleTag method. varib is name of parameter passed to the method, usually tag. Body of method follows after this macro. Note than you must use and ! Example:

    TAG_HANDLER_BEGIN(TITLE, "TITLE")
        TAG_HANDLER_PROC(tag)
            {
    	    printf("TITLE found...\n");
    	}
    TAG_HANDLER_END(TITLE)

TAG_HANDLER_END(name)

Ends definition of tag handler name.

Tags Modules

You can use set of 3 macros TAGS_MODULE_BEGIN, TAGS_MODULE_ADD and TAGS_MODULE_END to inherit new module from wxHtmlTagsModule and to create instance of it. See macros reference:

TAGS_MODULE_BEGIN(modname)

Begins module definition. modname is part of class name and must be unique.

TAGS_MODULE_ADD(name)

Adds the handler to this module. name is the identifier from TAG_HANDLER_BEGIN.

TAGS_MODULE_END(modname)

Ends the definition of module.

Example:

    TAGS_MODULE_BEGIN(Examples)
        TAGS_MODULE_ADD(VARS_ONLY)
        TAGS_MODULE_ADD(VARS2)
        TAGS_MODULE_ADD(TITLE)
    TAGS_MODULE_END(Examples)