[wxWidgets.git] / interface / html / htmltag.h

/////////////////////////////////////////////////////////////////////////////
// Name:        html/htmltag.h
// Purpose:     documentation for wxHtmlTag class
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/**
    @class wxHtmlTag
    @headerfile htmltag.h wx/html/htmltag.h
    
    This class represents a single HTML tag. 
    It is used by @ref overview_handlers "tag handlers".
    
    @library{wxhtml}
    @category{FIXME}
*/
class wxHtmlTag 
{
public:
    /**
        Constructor. You will probably never have to construct a wxHtmlTag object
        yourself. Feel free to ignore the constructor parameters.
        Have a look at src/html/htmlpars.cpp if you're interested in creating it.
    */
    wxHtmlTag(wxHtmlTag * parent, const wxString& source, int pos,
              int end_pos, wxHtmlTagsCache* cache,
              wxHtmlEntitiesParser * entParser);

    /**
        Returns a string containing all parameters.
        
        Example : tag contains @c FONT SIZE=+2 COLOR="#000000". Call to
        tag.GetAllParams() would return @c SIZE=+2 COLOR="#000000".
    */
    const wxString GetAllParams();

    /**
        Returns beginning position of the text @e between this tag and paired
        ending tag. 
        See explanation (returned position is marked with '|'):
    */
    int GetBeginPos();

    /**
        Returns ending position of the text @e between this tag and paired
        ending tag.
        See explanation (returned position is marked with '|'):
    */
    int GetEndPos1();

    /**
        Returns ending position 2 of the text @e between this tag and paired
        ending tag.
        See explanation (returned position is marked with '|'):
    */
    int GetEndPos2();

    /**
        Returns tag's name. The name is always in uppercase and it doesn't contain
        '' or '/' characters. (So the name of @c FONT SIZE=+2 tag is "FONT"
        and name of @c /table is "TABLE")
    */
    wxString GetName();

    /**
        Returns the value of the parameter. You should check whether the
        parameter exists or not (use wxHtmlTag::HasParam) first.
        
        @param par 
        The parameter's name.
        
        @param with_quotes 
        @true if you want to get quotes as well. See example.
    */
    wxString GetParam(const wxString& par, bool with_quotes = @false);

    /**
        Interprets tag parameter @e par as colour specification and saves its value
        into wxColour variable pointed by @e clr.
        
        Returns @true on success and @false if @e par is not colour specification or
        if the tag has no such parameter.
    */
    bool GetParamAsColour(const wxString& par, wxColour * clr);

    /**
        Interprets tag parameter @e par as an integer and saves its value
        into int variable pointed by @e value.
        
        Returns @true on success and @false if @e par is not an integer or
        if the tag has no such parameter.
    */
    bool GetParamAsInt(const wxString& par, int * value);

    /**
        Returns @true if this tag is paired with ending tag, @false otherwise.
        
        See the example of HTML document:
        In this example tags HTML and BODY have ending tags, first P and BR 
        doesn't have ending tag while the second P has. The third P tag (which
        is ending itself) of course doesn't have ending tag.
    */
    bool HasEnding();

    /**
        Returns @true if the tag has a parameter of the given name. 
        Example : @c FONT SIZE=+2 COLOR="#FF00FF" has two parameters named
        "SIZE" and "COLOR".
        
        @param par 
        the parameter you're looking for.
    */
    bool HasParam(const wxString& par);

    /**
        This method scans the given parameter. Usage is exactly the same as sscanf's 
        usage except that you don't pass a string but a parameter name as the first
        argument
        and you can only retrieve one value (i.e. you can use only one "%" element
        in @e format).
        
        @param par 
        The name of the tag you want to query
        
        @param format 
        scanf()-like format string.
        
        @param value 
        pointer to a variable to store the value in
    */
    wxString ScanParam(const wxString& par, const wxChar * format,
                       void * value);
};
Commit	Line	Data
23324ae1 FM	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: html/htmltag.h
	3	// Purpose: documentation for wxHtmlTag class
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9	/**
	10	@class wxHtmlTag
	11	@headerfile htmltag.h wx/html/htmltag.h
	12
	13	This class represents a single HTML tag.
	14	It is used by @ref overview_handlers "tag handlers".
	15
	16	@library{wxhtml}
	17	@category{FIXME}
	18	*/
	19	class wxHtmlTag
	20	{
	21	public:
	22	/**
	23	Constructor. You will probably never have to construct a wxHtmlTag object
	24	yourself. Feel free to ignore the constructor parameters.
	25	Have a look at src/html/htmlpars.cpp if you're interested in creating it.
	26	*/
	27	wxHtmlTag(wxHtmlTag * parent, const wxString& source, int pos,
	28	int end_pos, wxHtmlTagsCache* cache,
	29	wxHtmlEntitiesParser * entParser);
	30
	31	/**
	32	Returns a string containing all parameters.
	33
	34	Example : tag contains @c FONT SIZE=+2 COLOR="#000000". Call to
	35	tag.GetAllParams() would return @c SIZE=+2 COLOR="#000000".
	36	*/
	37	const wxString GetAllParams();
	38
	39	/**
	40	Returns beginning position of the text @e between this tag and paired
	41	ending tag.
	42	See explanation (returned position is marked with '\|'):
	43	*/
	44	int GetBeginPos();
	45
	46	/**
	47	Returns ending position of the text @e between this tag and paired
	48	ending tag.
	49	See explanation (returned position is marked with '\|'):
	50	*/
	51	int GetEndPos1();
	52
	53	/**
	54	Returns ending position 2 of the text @e between this tag and paired
	55	ending tag.
	56	See explanation (returned position is marked with '\|'):
	57	*/
	58	int GetEndPos2();
	59
	60	/**
	61	Returns tag's name. The name is always in uppercase and it doesn't contain
	62	'' or '/' characters. (So the name of @c FONT SIZE=+2 tag is "FONT"
	63	and name of @c /table is "TABLE")
	64	*/
65	wxString GetName();
66
67	/**
68	Returns the value of the parameter. You should check whether the
69	parameter exists or not (use wxHtmlTag::HasParam) first.
70
71	@param par
72	The parameter's name.
73
74	@param with_quotes
75	@true if you want to get quotes as well. See example.
76	*/
77	wxString GetParam(const wxString& par, bool with_quotes = @false);
78
79	/**
80	Interprets tag parameter @e par as colour specification and saves its value
81	into wxColour variable pointed by @e clr.
82
83	Returns @true on success and @false if @e par is not colour specification or
84	if the tag has no such parameter.
85	*/
86	bool GetParamAsColour(const wxString& par, wxColour * clr);
87
88	/**
89	Interprets tag parameter @e par as an integer and saves its value
90	into int variable pointed by @e value.
91
92	Returns @true on success and @false if @e par is not an integer or
93	if the tag has no such parameter.
94	*/
95	bool GetParamAsInt(const wxString& par, int * value);
96
97	/**
98	Returns @true if this tag is paired with ending tag, @false otherwise.
99
100	See the example of HTML document:
101	In this example tags HTML and BODY have ending tags, first P and BR
102	doesn't have ending tag while the second P has. The third P tag (which
103	is ending itself) of course doesn't have ending tag.
104	*/
105	bool HasEnding();
106
107	/**
108	Returns @true if the tag has a parameter of the given name.
109	Example : @c FONT SIZE=+2 COLOR="#FF00FF" has two parameters named
110	"SIZE" and "COLOR".
111
112	@param par
113	the parameter you're looking for.
114	*/
115	bool HasParam(const wxString& par);
116
117	/**
118	This method scans the given parameter. Usage is exactly the same as sscanf's
119	usage except that you don't pass a string but a parameter name as the first
120	argument
121	and you can only retrieve one value (i.e. you can use only one "%" element
122	in @e format).
123
124	@param par
125	The name of the tag you want to query
126
127	@param format
128	scanf()-like format string.
129
130	@param value
131	pointer to a variable to store the value in
132	*/
133	wxString ScanParam(const wxString& par, const wxChar * format,
134	void * value);
135	};