Document Loading

CSSBox generally expects an implementation of the DOM on its input represented by its root Document node. The way how the DOM is obtained is not important for CSSBox. However, in most situations, the DOM is obtained by parsing a HTML or XML file. Therefore, CSSBox provides a framework for binding a parser to the layout engine. Moreover it contains a default parser implementation that may be simply used or it can be easily replaced by a custom implementation when required. The default implementation is based on the NekoHTML parser and Xerces 2. The details about using a different parser are described in the Custom Document Sources and Parsers section.

With the default implementation, the following code reads and parses the document based on its URL:

//Open the network connection 
DocumentSource docSource = new DefaultDocumentSource(urlstring);

//Parse the input document
DOMSource parser = new DefaultDOMSource(docSource);
Document doc = parser.parse(); //doc represents the obtained DOM

For the initial DOM and style sheet processing, a DOMAnalyzer object is used. It is initialized with the DOM tree and the base URL:

DOMAnalyzer da = new DOMAnalyzer(doc, docSource.getURL());
da.attributesToStyles(); //convert the HTML presentation attributes to inline styles
da.addStyleSheet(null, CSSNorm.stdStyleSheet(), DOMAnalyzer.Origin.AGENT); //use the standard style sheet
da.addStyleSheet(null, CSSNorm.userStyleSheet(), DOMAnalyzer.Origin.AGENT); //use the additional style sheet
da.addStyleSheet(null, CSSNorm.formsStyleSheet(), DOMAnalyzer.Origin.AGENT); //(optional) use the forms style sheet
da.getStyleSheets(); //load the author style sheets

The attributesToStyles() method converts some HTML presentation attributes to CSS styles (e.g. the <font> tag attributes, table attributes and some more). If (X)HTML interpretation is not required, this method need not be called. When used, this method should be called before getStyleSheets() is used.

The addStyleSheet() method is used to add a style sheet to the document. The style sheet is passed as a text string containing the CSS code. In our case, we add two built-in style sheets that represent the standard document style. These style sheets are imported as the user agent style sheets according to the CSS specification. The CSSNorm.stdStyleSheet() method returns the default style sheet recommended by the CSS specification and the CSSNorm.userStyleSheet() contains some additional CSSBox definitions not covered by the standard.

Optionally, the CSSNorm.formsStyleSheet() includes a basic style of form input fields. This style sheet may be used for basic rendering of the form fields when their rendering and functionality is not implemented in any other way in the application.

Finally, the getStyleSheets() method loads and processes all the internal and external style sheets referenced from the document including the inline style definitions. In case of external style sheets, CSSBox tries to obtain the file from the corresponding URL, if accessible.

The resulting DOMAnalyzer object represents the document code together with the associated style.

Media Support

By default, the DOMAnalyzer assumes that the page is being rendered on a standard desktop computer screen. During the style sheet processing, it uses the "screen" media type and some default display feature values for evaluating the possible media queries.

A different media type or feature values may be specified by creating a new media specification represented as a MediaSpec object from the jStyleParser API. The typical usage would be the following:

//we will use the "screen" media type for rendering
MediaSpec media = new MediaSpec("screen");

//specify some media feature values
media.setDimensions(1000, 800); //set the visible area size in pixels
media.setDeviceDimensions(1600, 1200); //set the display size in pixels

//use the media specification in the analyzer
DOMAnalyzer da = new DOMAnalyzer(doc, docSource.getURL());
da.setMediaSpec(media);
//... continue with the DOMAnalyzer initialization as above

The BoxBrowser demo shows a basic usage of the media specifications in a Swing application.

Obtaining the Layout

The whole layout engine is represented by a graphical BrowserCanvas object. The simplest way of creating the layout is passing the initial viewport dimensions to the BrowserCanvas constructor. Then, the layout is computed automatically by creating an instance of this object. The remaining constructor arguments are the root DOM element, the DOMAnalyzer used for obtaining the element styles and the document base URL used for loading images and other referenced content.

BrowserCanvas browser = 
        new BrowserCanvas(da.getRoot(),
                          da,
                          new java.awt.Dimension(1000, 600),
                          url);

When further browser configuration is required, the BrowserCanvas may be created without specifying the viewport dimensions. Then, the layout is not computed automatically and it must be created by a subsequent call of the createLayout method. Before creating the layout, the browser configuration may be changed.

BrowserCanvas browser = 
        new BrowserCanvas(da.getRoot(), da, url);
//... modify the browser configuration here ...
browser.createLayout(new java.awt.Dimension(1000, 600));

Optionally, the createLayout method allows to specify different values for the preferred total canvas size and the visible area size and position] (the CSS viewport size):

BrowserCanvas browser = 
        new BrowserCanvas(da.getRoot(), da, url);
//... modify the browser configuration here ...
browser.createLayout(new java.awt.Dimension(1200, 600), new java.awt.Rectangle(0, 0, 1000, 600));

In this case, the preferred size of the resulting page is 1200x600 pixels (it may be adjusted during the layout computation based on the page contents) and the size of the visible area is 1000x600 pixels; the visible area is in the top left corner of the rendered page. The visible area size and position is used during the layout computation and it may influence the positions of positioned elements according to the CSS specification.

Setting the visible area size automatically updates the used media specification (see the previous section) so that the same size of the visible area is used for evaluating the CSS media queries. However, this behavior may be disabled by calling setAutoMediaUpdate(false) before creating the layout. In that case, the visible area size used for the layout computation may be different from the size used for media queries.

In all cases, the created browser object can be directly used for both displaying the rendered document and for obtaining the created layout model. The details of the browser configuration are described in the Configuration Options section.

Displaying the document

The BrowserCanvas class is directly derived from the Swing javax.swing.JPanel class. Therefore, it can be directly used as a Swing user interface component. The size of the component is automatically adjusted according to the resulting document layout. The basic document displaying is shown in the SimpleBrowser example.

BrowserCanvas provides a simple display of the rendered page with no interactive elements. For obtaining an interactive browser component with text selection and clickable links, the SwingBox extension should be used.

Configuration Options

Current browser configuration is represented using a BrowserConfig object that may be accessed using the browser's getConfig() method. The following configuration options are available:

browser.getConfig().setLoadImages(boolean)

Configures whether to load the referenced content images automatically. The default value is true.

browser.getConfig().setLoadBackgroundImages(boolean)

Configures whether to load the CSS background images automatically. The default value is true.

browser.getConfig().setImageLoadTimeout(int)

Configures the timeout for loading images. The default value is 500ms.

browser.getConfig().useHTML(boolean)

Configures whether the engine should use the HTML extensions or not. Currently, the HTML extensions include the following:

• Creating replaced boxes for <img> elements
• Using the <body> element background for the whole canvas according to the HTML specification
• Support for the embedded <object> elements.
• Special handling of certain elements such as named anchors.

The default value is true.

browser.getConfig().setDefaultFont(String logical, String physical)

Configures the default physical fonts that should be used instead of the logical Java families. The typical usage is the following:

        browser.getConfig().setDefaultFont(java.awt.Font.SERIF, "Times New Roman");
        browser.getConfig().setDefaultFont(java.awt.Font.SANS_SERIF, "Arial");
        browser.getConfig().setDefaultFont(java.awt.Font.MONOSPACED, "Courier New");
	

browser.getConfig().registerDocumentSource(Class<? extends DocumentSource>)

browser.getConfig().registerDOMSource(Class<? extends DOMSource>)

Register the DocumentSource and DOMSource implementation used for automatic loading of the referenced documents. See the Custom Document Sources and Parsers section for details.

Custom Document Sources and Parsers

CSSBox contains two generic abstract classes that represent the document source and the parser and provides their default implementations:

• DocumentSource represents a generic source of documents that is able to obtain a document based on its URL. The default DefaultDocumentSource implementation uses the standard Java URLConnection mechanism extended by the support of data: URL scheme.
• DOMSource represents a parser that is able to create a DOM from a document source. The default DefaultDOMSource implementation is based on the NekoHTML parser.

The default implementations may be used for obtaining the DOM from an URL easily as shown in the Document Loading section. Moreover, CSSBox uses these implementations for obtaining the documents referenced from the HTML code such as images and embedded objects.

When a different implementation of the document source or the parser is required (e.g. for obtaining the documents from a non-standard source, using a different parser implementation, etc.), it is possible to create a custom implementation of the appropriate abstract class. Then, the new implementation may be registered using the browser configuration browser.getConfig().registerDocumentSource() and browser.getConfig().registerDOMSource() methods as mentioned above in the Configuration Options section.

Basic Box Properties

The basic box properties are defined in the Box abstract class. They are mostly related to the box position and size.

Text Boxes

A text box always box corresponds to a DOM node of the type Text. It is represented as TextBox object. When the text is split to several lines, multiple boxes correspond to a single DOM node. In this case each of them contains a corresponding substring of the text.

Element Boxes

An element box corresponds to a DOM node of the type Element. It is represented as an object of the abstract ElementBox class. It can be implemented as an inline box or a block box as described below. The common methods of the element boxes are the following:

for (int i = b.getStartChild(); i < b.getEndChild(); i++)
{
    Box sub = b.getSubBox(i);
    //process the child box here...
}

Inline Boxes

Inline boxes are the element boxes with value of the CSS display: property equal to inline. These boxes are represented as the InlineBox objects. They have no special properties in addition to the properties defined in the ElementBox class.

Block Boxes

Block boxes, with the display: value set to block are represented by the BlockBox objects. In addition, the boxes with other values of the display: property are represented by several special classes derived from this class:

• ListItemBox
• TableBox
• TableCaptionBox
• TableBodyBox
• TableRowBox
• Viewport

These objects differ mainly in the way how the boxes and their contents are laid out on the page. From the resulting layout model point of view, they have no special properties in addition to the properties defined in the ElementBox class.

Fonts and Colors

For each box, a VisualContext object is defined that gathers the information about the current text font and color. This object is obtained using the getVisualContext() method of the box. Following methods can be used for obtaining the appropriate information:

getColor()

Current text color.

getFont()

Returns the current font represented as the java.awt.Font object. From this object most of the font properties can be obtained.

getFontVariant()

Current font variant in the CSS syntax - i.e. normal or small-caps.

getTextDecoration()

Current text decoration in the CSS syntax - i.e. none, underline, overline, line-through or blink.

The background color is only applicable to element boxes as mentioned in Visual Properties of the Element Box.