Web<ToolKit> Interface Conventions

Element Copy and Destruction

All Web<ToolKit> copy constructors and assignment operators implement deep copying; that is, all data members within an object, as well as objects pointed to by the data members, are copied. Likewise, all Web<ToolKit> destructors implement deep destruction; that is, all data members within an object, as well as objects pointed to by the data members, are destroyed.

All Web<ToolKit> element classes, that is, classes derived directly or indirectly from os_element , provide a clone() member function. This function takes no arguments and returns the base class pointer os_element* to a heap-based, deep copy of the element object. The caller is responsible for deleting the copy.

HTML Conversion

A Web<ToolKit> element object, that is, an instance of any class derived directly or indirectly from os_element , can be converted to HTML using one of the following two methods.

• Member function void print( ostream& os ) const
• Global function operator<<( ostream& os , const os_element& element )

With both methods, the generated HTML is inserted into the specified output stream.

Shortcut Interfaces

Most Web<ToolKit> collection class interfaces that accept a const os_element& argument are overloaded to provide a version that will accept a const string& argument. In such instances, the second form of the function is analogous to calling the first form with an os_text object constructed from the string object. The second form is provided as a convenient shortcut. The following example

os_paragraph p;

p.add( "A text string." );

is equivalent to

os_paragraph p;

p.add( os_text( "A text string." ) );

Inserting Elements into Groups

Web<ToolKit> classes derived from os_element_group , or the classes os_page , os_checkbox_group , os_radio_group , and os_table_row , provide two groups of interfaces to insert an element into the collection: add() member functions and operator<< . Although these functions are frequently overloaded within a class to accept different types of elements, their basic functionality remains the same. In both cases, elements are inserted into a collection by copying the element passed to the function using clone() . Additionally, all copies are deep copies; that is, the element and any subelements that it may contain are copied.

The add() member functions add a deep copy of the element passed to the function and return a base class pointer to the copy of the element within the collection.

os_paragraph p;

p.add( "Text inserted into a paragraph via add." );

The insertion operators ( operator<< ) insert a deep copy of the element passed to the operator and return a reference to the containing object. This allows insertion operations to be chained, similar to the way operations can be chained when using the insertion operator to send an object to a C++ iostream, such as cout .

os_paragraph p;

p << "Text inserted into a paragraph via operator<<."
<< os_break()
<< os_bold( "Bold text inserted into a paragraph via
operator<<" );

Element Modifiers

Many Web<ToolKit> element classes provide modifiers, which are functions to set the attributes of the element. These functions always return a reference to the element object, which allows modifier function calls to be chained to set multiple attributes within a single statement, as in the following example.

os_table table;

table.cell_spacing(5).cell_padding(3).width("100%");