htmlObject

htmlObject
Base class for all html++ objects

Description

htmlObject is the parent class for nearly all html++ objects, with the exception of String and CNVList. It's purpose is to encapsulate functionality and features common to html++ objects, such as defining HTML start and end tag names, streaming output, and management of name/value attribute lists.

htmlObject is a general purpose base class, and is not intended for direct instantiation. Instead, it is designed for use as a base class from which other html++ classes are derived, and from which user-defined classes may be created. It is designed to support a single object, hence there is no support for streaming insertion of other objects, or an Add() method. Classes that must manage groups of htmlObject-derived objects (such as htmlPage), inherit from the htmlGroup class.

It is the responsibility of derived classes to implement their own set of features and functionality. However, for duties that are common to more more than one such class, private methods are included for routine features such as using color or setting alignment options (e.g., htmlTable, htmlText, etc.). It is up to the derived class to provide it's own interface to these private methods.

htmlObject maintains tag attributes as a list of name/value string pairs, and provides the SetAttribute(), GetAttribute(), ClearAttribute(), and AttributeExists() methods as the interface to the list. Derived classes use these methods to implement their own specific attributes, so it is not necessary to use them directly. As the HTML specification changes, new attributes can be supported by all html++ class by simply using the SetAttribute() method.

Declaration

#include <dcmicro/htmlpp/htmlobj.h>

Hierarchy

See Also

htmlGroup

Related Constants/Definitions

typedef enum {

   full_search = 0,

   shallow_search

} SearchDepth ;

Constructors

htmlObject()

Constructs an empty object.

htmlObject( const String& start_tag, const String& end_tag )

Constructs an empty object using the specified start and end HTML tag names. If end_tag is an empty string, start_tag will be used for both.

htmlObject( const htmlObject& rhs )

Copy Constructor.

Destructors

virtual ~htmlObject()

Destroys the object.

Member Methods

=       htmlObject& operator= ( const htmlObject& rhs )

Replaces object contents with a copy of rhs and returns a reference to the object.

=       htmlObject& operator= ( const String& text )

Converts text to an htmlText object, and replaces group contents with a copy of it. A reference to the object is returned.

<<       ostream& operator<< ( ostream& os,

      const htmlObject& element )

Streaming output of the element object to stream os.

SetAttribute    void SetAttribute( const String& attribute,

      const String& value )

Store attribute and value as a pair in the object's name/value attribute list. If value is an empty string, the pair will be removed from the list.

SetAttribute    void SetAttribute( const String& attribute, int value )

Convert value to a string, and store attribute and value as a pair in the object's name/value attribute list.

ClearAttribute void ClearAttribute(const String& attribute )

Removes the specified attribute from the object's name/value attribute list.

GetAttribute    String GetAttribute( const String& attribute ) const

Retrieves the value for the specified attribute from the object's name/value attribute list as a string. If no attribute exists, an empty string is returned.

GetAttributeAsInt int GetAttribute( const String& attribute ) const

Retrieves the value for the specified attribute from the object's name/value attribute list as an integer. If no attribute exists, zero is returned.

AttributeExists Boolean AttributeExists( const String& attribute ) const

Returns TRUE is a name/value pair exists for attribute in the object's name/value attribute list, or FALSE if the attribute does not exist.

Key       void Key( const String& key_name )

Sets the key name for the object to the string key_name, used to identify and locate the object in find/replace operations.

Find       virtual htmlObject FAR * Find( const String& key_name,

      SearchDepth depth = full_search )

Searches the object and any objects it contains for the first occurrance of an object with a matching key_name, returning a base-class pointer to it or NULL if no match is found. If depth is full_search (the default) a deep search of all objects will be performed. If depth is shallow_search, only first-level objects within the object will be searched.

Replace    virtual int Replace( const String& key_name,

      const htmlObject& replacement_element,

      SearchDepth depth = full_search )

Searches the object and any objects it contains for all occurrances of objects with a matching key_name, replacing them with replacement_element. An integer represeting the number of replacements is returned, zero if no replacements were performed. If depth is full_search (the default) a deep search of all objects will be performed. If depth is shallow_search, only first-level objects within the object will be searched. To effectively remove an object, replace it with an empty object such as htmlText(). For an example of using Replace(), refer to the example program for htmlContainer.

Replace    virtual int Replace( const String& key_name,

      const String& replacement_text,

      SearchDepth depth = full_search )

Identical to the Replace() method above, but converts replacement_text to an htmlText object before performing any replacements.

TagName    void TagName( const char * tag, Boolean has_end = TRUE )

TagName    void TagName( const String& tag, Boolean has_end = TRUE )

Sets the HTML tag name for the object to tag. If has_end is TRUE, the object contents will include a </tag> feature when output via the Print() method. This method is used internally but is documented to make creation of user-defined derived classes easier.

TagName    String TagName() const

Returns the HTML tag name of the object, or an empty string if not set. This method is used internally but is documented to make creation of user-defined derived classes easier.

Print       virtual void Print( ostream& os ) const

Outputs the object to os. This method may be overridden to define custom stream output behavior, such as adding additional linefeeds or including special formatting. The default implementation of this method simply executes the PrintStart() and PrintEnd() methods. Derived classes that override this method will typically nest their custom printing functionality between calls to PrintStart() and PrintEnd().

PrintStart    void PrintStart( ostream& os ) const

Outputs the leading tag for the object, including any attributes defined in the object's name/value pair list, to os (e.g., <tagname attrib1=value1 attrib2=value2>). This method is used internally by the Print() method of derived classes, and is documented to make creation of user-defined classes easier.

PrintEnd    void PrintEnd( ostream& os ) const

Outputs the ending tag for the object to os (e.g., </tagname>), if the object has a non-empty end tag string. This method is used internally by the Print() method of derived classes, and is documented to make creation of user-defined classes easier.

Clone    virtual htmlObject FAR * Clone() const

Returns a base-class pointer to a deep copy of the object.

Example Use

This class is not intended for direct use.

©1998 DC Micro Development. All rights reserved.
No portion of this document may be c opied or reproduced without expressed written consent.
html++ is a trademark of DC Micro Development.

	htmlObject is the parent class for nearly all html++ objects, with the exception of String and CNVList. It's purpose is to encapsulate functionality and features common to html++ objects, such as defining HTML start and end tag names, streaming output, and management of name/value attribute lists.

	htmlObject is a general purpose base class, and is not intended for direct instantiation. Instead, it is designed for use as a base class from which other html++ classes are derived, and from which user-defined classes may be created. It is designed to support a single object, hence there is no support for streaming insertion of other objects, or an Add() method. Classes that must manage groups of htmlObject-derived objects (such as htmlPage), inherit from the htmlGroup class.

	It is the responsibility of derived classes to implement their own set of features and functionality. However, for duties that are common to more more than one such class, private methods are included for routine features such as using color or setting alignment options (e.g., htmlTable, htmlText, etc.). It is up to the derived class to provide it's own interface to these private methods.

	htmlObject maintains tag attributes as a list of name/value string pairs, and provides the SetAttribute(), GetAttribute(), ClearAttribute(), and AttributeExists() methods as the interface to the list. Derived classes use these methods to implement their own specific attributes, so it is not necessary to use them directly. As the HTML specification changes, new attributes can be supported by all html++ class by simply using the SetAttribute() method.

	htmlObject( const String& *start_tag, const String& end_tag* )

	Constructs an empty object using the specified start and end HTML tag names. If end_tag is an empty string, start_tag will be used for both.

	Replaces object contents with a copy of rhs and returns a reference to the object.

	Converts text to an htmlText object, and replaces group contents with a copy of it. A reference to the object is returned.

	<<	ostream& operator<< ( ostream& os,
		const htmlObject& *element* )

	SetAttribute	void SetAttribute( const String& *attribute*,
		const String& *value* )

	Store attribute and value as a pair in the object's name/value attribute list. If value is an empty string, the pair will be removed from the list.

	Convert value to a string, and store attribute and value as a pair in the object's name/value attribute list.

	ClearAttribute	void ClearAttribute(const String& *attribute* )

	Removes the specified attribute from the object's name/value attribute list.

	GetAttribute	String GetAttribute( const String& *attribute* ) const

	Retrieves the value for the specified attribute from the object's name/value attribute list as a string. If no attribute exists, an empty string is returned.

	GetAttributeAsInt	int GetAttribute( const String& *attribute* ) const

	AttributeExists	Boolean AttributeExists( const String& *attribute* ) const

	Returns TRUE is a name/value pair exists for attribute in the object's name/value attribute list, or FALSE if the attribute does not exist.

	Sets the key name for the object to the string key_name, used to identify and locate the object in find/replace operations.

	Find	virtual htmlObject FAR * Find( const String& *key_name*,
		SearchDepth *depth* = full_search )

	Searches the object and any objects it contains for the first occurrance of an object with a matching key_name, returning a base-class pointer to it or NULL if no match is found. If depth is full_search (the default) a deep search of all objects will be performed. If depth is shallow_search, only first-level objects within the object will be searched.

	Replace	virtual int Replace( const String& *key_name*,
		const htmlObject& *replacement_element*,
		SearchDepth *depth* = full_search )

	Replace	virtual int Replace( const String& *key_name*,
		const String& *replacement_text*,
		SearchDepth *depth* = full_search )

	Identical to the Replace() method above, but converts replacement_text to an htmlText object before performing any replacements.

	TagName	void TagName( const char * *tag, Boolean has_end* = TRUE )
	TagName	void TagName( const String& *tag, Boolean has_end* = TRUE )

	Sets the HTML tag name for the object to tag. If has_end is TRUE, the object contents will include a </tag> feature when output via the Print() method. This method is used internally but is documented to make creation of user-defined derived classes easier.

	Returns the HTML tag name of the object, or an empty string if not set. This method is used internally but is documented to make creation of user-defined derived classes easier.

	Outputs the object to os. This method may be overridden to define custom stream output behavior, such as adding additional linefeeds or including special formatting. The default implementation of this method simply executes the PrintStart() and PrintEnd() methods. Derived classes that override this method will typically nest their custom printing functionality between calls to PrintStart() and PrintEnd().

	Outputs the leading tag for the object, including any attributes defined in the object's name/value pair list, to os (e.g., <tagname attrib1=value1 attrib2=value2>). This method is used internally by the Print() method of derived classes, and is documented to make creation of user-defined classes easier.

	Outputs the ending tag for the object to os (e.g., </tagname>), if the object has a non-empty end tag string. This method is used internally by the Print() method of derived classes, and is documented to make creation of user-defined classes easier.