Wt  4.0.2
Classes | Public Member Functions | Protected Member Functions | List of all members
Wt::Render::WTextRenderer Class Referenceabstract

An XHTML renderering engine. More...

#include <Wt/Render/WTextRenderer.h>

Inheritance diagram for Wt::Render::WTextRenderer:
Inheritance graph
[legend]

Classes

class  Node
 A rendering box of a layed out DOM node. More...
 

Public Member Functions

virtual ~WTextRenderer ()
 Destructor.
 
double render (const WString &text, double y=0)
 Renders an XHTML fragment. More...
 
bool setStyleSheetText (const WString &contents)
 Sets the contents of a cascading style sheet (CSS). More...
 
bool useStyleSheet (const WString &filename)
 Appends an external cascading style sheet (CSS). More...
 
void clearStyleSheet ()
 Clears the used stylesheet. More...
 
WString styleSheetText () const
 Returns the CSS in use. More...
 
std::string getStyleSheetParseErrors () const
 Returns all parse error information of the last call to setStyleSheetText. More...
 
double textWidth (int page) const
 Returns the page text width. More...
 
double textHeight (int page) const
 Returns the page text height. More...
 
void setFontScale (double scale)
 Sets the scaling factor used for font rendering. More...
 
double fontScale () const
 Returns the font scaling factor. More...
 
virtual double pageWidth (int page) const =0
 Returns the page width. More...
 
virtual double pageHeight (int page) const =0
 Returns the page height. More...
 
virtual double margin (Side side) const =0
 Returns the margin. More...
 
virtual WPaintDevicestartPage (int page)=0
 Returns a paint device to render a given page. More...
 
virtual void endPage (WPaintDevice *device)=0
 Stops painting on the given page.
 
virtual WPaintergetPainter (WPaintDevice *device)=0
 Returns a painter for the current page.
 
virtual void paintNode (WPainter &painter, const Node &node)
 Paints an XHTML node. More...
 

Protected Member Functions

 WTextRenderer ()
 Constructor.
 

Detailed Description

An XHTML renderering engine.

This class implements a rendering engine for a (subset of) XHTML/CSS. Its intended use is to be able to accurately render the output of the WTextEdit widget (although it handles a more general subset of XHTML/CSS than is required to do just that). Its focus is on high-quality rendering of text-like contents.

The following are the main features:

Some of the main limitations are:

The renderer is not CSS compliant (simply because it is still lacking alot of features), but the subset of CSS that is supported is a pragmatic choice. If things are lacking, let us known in the bug tracker.

This class is an abstract class. A concrete class implements the pure virtual methods to create an appropriate WPaintDevice for each page and to provide page dimension information.

All coordinates and dimensions in the API below are pixel coordinates.

Member Function Documentation

void Wt::Render::WTextRenderer::clearStyleSheet ( )

Clears the used stylesheet.

This is an overloaded member, provided for convenience. Equivalent to:

See also
setStyleSheetText()
double Wt::Render::WTextRenderer::fontScale ( ) const

Returns the font scaling factor.

See also
setFontScale().
std::string Wt::Render::WTextRenderer::getStyleSheetParseErrors ( ) const

Returns all parse error information of the last call to setStyleSheetText.

setStyleSheetText stores all parse errors inside. Use getStyleSheetParseErrors to access information about them. Icon::Information is newline(\ n) separated.

See also
setStyleSheetText(const WString& contents)
virtual double Wt::Render::WTextRenderer::margin ( Side  side) const
pure virtual

Returns the margin.

Returns the margin at given side (in pixel units).

Implemented in Wt::Render::WPdfRenderer.

virtual double Wt::Render::WTextRenderer::pageHeight ( int  page) const
pure virtual

Returns the page height.

Returns the total page height (in pixel units), including vertical margins.

Implemented in Wt::Render::WPdfRenderer.

virtual double Wt::Render::WTextRenderer::pageWidth ( int  page) const
pure virtual

Returns the page width.

Returns the total page width (in pixel units), including horizontal margins.

Implemented in Wt::Render::WPdfRenderer.

void Wt::Render::WTextRenderer::paintNode ( WPainter painter,
const Node node 
)
virtual

Paints an XHTML node.

The default implementation paints the node conforming to the XHTML specification.

You may want to specialize this method if you wish to customize (or ignore) the rendering for certain nodes or node types, or if you want to capture the actual layout positions for other processing.

The node information contains the layout position at which the node is being painted.

double Wt::Render::WTextRenderer::render ( const WString text,
double  y = 0 
)

Renders an XHTML fragment.

The text is rendered, starting at position y, and flowing down the page. New pages are created using startPage() to render more contents on a next page. The return value is the position at which rendering stopped on the last page on which was rendered.

This y position and returned position are text coordinates, which differ from page coordinates in that they exclude margins.

The function returns the end position. You may call this function multiple times.

Each invocation to render() has the effect of resetting the logical page numbering used by pageWidth(), pageHeight() and startPage() so that the current page is page 0.

void Wt::Render::WTextRenderer::setFontScale ( double  scale)

Sets the scaling factor used for font rendering.

A scaling can be set for text. The scaling factor has as effect that text font sizes are modified by the scale. Also CSS length units that are defined in terms of font units ("em" and "ex") are scaled accordingly.

The default value is 1.

bool Wt::Render::WTextRenderer::setStyleSheetText ( const WString contents)

Sets the contents of a cascading style sheet (CSS).

This sets the text contents to be used as CSS. Any previous CSS declarations are discarded. Returns true if parsing was successful, false if otherwise. If parsing failed, the stylesheet text that was already in use will not have been changed. Use getStyleSheetParseErrors to access parse error information.

Warning
Only the following CSS selector features are supported:
  • tag selectors: e.g. span or *
  • class name selectors: .class
  • id selectors: #id
  • descendant selectors: h1 h2 h3 {}
  • multiples: h1, h2, h3 {}
    h1.a1#one.a2 h3#two.c {}
See also
getStyleSheetParseErrors()
virtual WPaintDevice* Wt::Render::WTextRenderer::startPage ( int  page)
pure virtual

Returns a paint device to render a given page.

The render() method calls this function once for each page it wants to render.

Implemented in Wt::Render::WPdfRenderer.

WString Wt::Render::WTextRenderer::styleSheetText ( ) const

Returns the CSS in use.

This returns all the CSS declarations in use.

See also
setStyleSheetText()
double Wt::Render::WTextRenderer::textHeight ( int  page) const

Returns the page text height.

This returns the height of the page in which text needs to be rendered, excluding vertical margins, in pixels.

See also
textWidth()
double Wt::Render::WTextRenderer::textWidth ( int  page) const

Returns the page text width.

This returns the width of the page in which text needs to be rendered, excluding horizontal margins, in pixels.

See also
textHeight()
bool Wt::Render::WTextRenderer::useStyleSheet ( const WString filename)

Appends an external cascading style sheet (CSS).

This is an overloaded member, provided for convenience. Equivalent to:

setStyleSheetText(styleSheetText() + <filename_contents>)
See also
setStyleSheetText()

Generated on Fri Nov 24 2017 for the C++ Web Toolkit (Wt) by doxygen 1.8.11