Class WTextRenderer
- Direct Known Subclasses:
WPdfRenderer
public abstract class WTextRenderer
extends java.lang.Object
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:
- decent rendering of inline (text) contents, floats, tables, images, ordered lists, unordered lists, in any arbitrary combination, with mixtures of font sizes, etc...
- CSS stylesheet support using in-document <style>, inline style attributes or using
setStyleSheetText()
. - support for relative and absolute positioned layout contexts
- support for (true type) fonts, font styles, font sizes and text decorations
- support for text alignment options, padding, margins, borders, background color (only on block elements) and text colors
- supports automatic and CSS page breaks (page-break-after or page-break-before)
- supports font scaling (rendering text at another DPI than the rest)
- can be used in conjunction with other drawing instructions to the same paint device.
Some of the main limitations are:
- only "display: inline" or "display: block" elements are supported. "display: none" and "display: inline-block" are not (yet) recognized.
- only colors defined in terms of RGB values are supported: CSS named colors (e.g. 'blue') are not allowed.
- Bidi (Right-to-Left) text rendering is not supported
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.
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
WTextRenderer.Node
A rendering box of a layed out DOM node. -
Constructor Summary
Constructors Modifier Constructor Description protected
WTextRenderer()
Constructor. -
Method Summary
Modifier and Type Method Description void
clearStyleSheet()
Clears the used stylesheet.abstract void
endPage(WPaintDevice device)
Stops painting on the given page.double
getFontScale()
Returns the font scaling factor.abstract double
getMargin(Side side)
Returns the margin.abstract WPainter
getPainter(WPaintDevice device)
Returns a painter for the current page.java.lang.String
getStyleSheetParseErrors()
Returns all parse error information of the last call to setStyleSheetText.WString
getStyleSheetText()
Returns the CSS in use.abstract double
pageHeight(int page)
Returns the page height.abstract double
pageWidth(int page)
Returns the page width.void
paintNode(WPainter painter, WTextRenderer.Node node)
Paints an XHTML node.double
render(java.lang.CharSequence text)
Renders an XHTML fragment.double
render(java.lang.CharSequence text, double y)
Renders an XHTML fragment.void
setFontScale(double factor)
Sets the scaling factor used for font rendering.boolean
setStyleSheetText(java.lang.CharSequence styleSheetContents)
Sets the contents of a cascading style sheet (CSS).abstract WPaintDevice
startPage(int page)
Returns a paint device to render a given page.double
textHeight(int page)
Returns the page text height.double
textWidth(int page)
Returns the page text width.boolean
useStyleSheet(java.lang.CharSequence filename)
Appends an external cascading style sheet (CSS).Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
-
Constructor Details
-
WTextRenderer
protected WTextRenderer()Constructor.
-
-
Method Details
-
render
public double render(java.lang.CharSequence text, double y)Renders an XHTML fragment.The text is rendered, starting at position
y
, and flowing down the page. New pages are created using
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.startPage()
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 bypageWidth()
,pageHeight()
andstartPage()
so that the current page is page 0. -
render
public final double render(java.lang.CharSequence text)Renders an XHTML fragment.Returns
render(text, 0)
-
setStyleSheetText
public boolean setStyleSheetText(java.lang.CharSequence styleSheetContents)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()
-
useStyleSheet
public boolean useStyleSheet(java.lang.CharSequence filename)Appends an external cascading style sheet (CSS).This is an overloaded member, provided for convenience. Equivalent to:
setStyleSheetText(styleSheetText() + <filename_contents>)
-
clearStyleSheet
public void clearStyleSheet()Clears the used stylesheet.This is an overloaded member, provided for convenience. Equivalent to:
setStyleSheetText("")
-
getStyleSheetText
Returns the CSS in use.This returns all the CSS declarations in use.
-
getStyleSheetParseErrors
public java.lang.String getStyleSheetParseErrors()Returns all parse error information of the last call to setStyleSheetText.setStyleSheetText stores all parse errors inside. Use getStyleSheetParseErrors to access information about them. Information is newline(\ n) seperated.
-
textWidth
public double textWidth(int page)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(int page)
-
textHeight
public double textHeight(int page)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(int page)
-
setFontScale
public void setFontScale(double factor)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.
-
getFontScale
public double getFontScale()Returns the font scaling factor.- See Also:
setFontScale(double factor)
-
pageWidth
public abstract double pageWidth(int page)Returns the page width.Returns the total page width (in pixel units), including horizontal margins.
-
pageHeight
public abstract double pageHeight(int page)Returns the page height.Returns the total page height (in pixel units), including vertical margins.
-
getMargin
Returns the margin.Returns the margin at given side (in pixel units).
-
startPage
Returns a paint device to render a given page.The
render()
method calls this function once for each page it wants to render. -
endPage
Stops painting on the given page. -
getPainter
Returns a painter for the current page. -
paintNode
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.
-