Package net.sf.jasperreports.engine

Interface JRCommonText

  • All Superinterfaces:
    JRBoxContainer, JRCommonElement, JRParagraphContainer, JRStyleContainer
    All Known Subinterfaces:
    JRPrintText, JRStaticText, JRTextElement, JRTextField
    All Known Implementing Classes:
    JRBasePrintText, JRBaseStaticText, JRBaseTextElement, JRBaseTextField, JRDesignStaticText, JRDesignTextElement, JRDesignTextField, JRFillStaticText, JRFillTextElement, JRFillTextField, JRRecordedValuesPrintText, JRTemplatePrintText, JRTemplateText
    public interface JRCommonText
extends JRCommonElement, JRBoxContainer, JRParagraphContainer
    Common interface of design and print text elements.

    There are two kinds of text elements in JasperReports: static texts and text fields. As their names suggest, the first are text elements with fixed, static content, they do not change during the report-filling process, and they are used especially for introducing labels into the final document. Text fields, however, have an associated expression that is evaluated at runtime to produce the text content that will be displayed. Both types of text elements share some properties, and those are introduced using a <textElement> tag.

    Rotating Text

    The rotation attribute (see getRotation()), available for text elements, allows changing the text direction by rotating it 90 degrees to the right or to the left, or by rotating it 180 degrees to be rendered upside down. Possible values are:
    • None - this is the default value
    • Left
    • Right
    • UpsideDown

    Text Markup

    Normally, all the text content in a text element has the style specified by the text element attributes (text fore color, text background color, font name, font size, etc.). But in some cases, users will want to highlight a few words inside a text element, usually by changing the text fore color, changing the font style using an underline, or by making it bold or italic. In such cases, the text content of that particular text element will no longer be pure text. It will be specially structured XML content that includes style information in the text itself, or some other form of markup language.

    All text elements have an option attribute called markup (see getMarkup()) which can be used to specified the type of markup language that will be used inside the text element, to format its content.

    The following are the predefined values possible for the markup attribute:

    • none - There are no markup tags. The content of the text element is plain text.This is the default value.
    • styled - The content of the text element is styled text, an proprietary XML type of markup text described below.
    • html - The content of the text element is Hyper Text Markup Language.
    • rtf - The content of the text element is Rich Text Format.

    Styled Text

    The JasperReports proprietary markup language is called styled text and is an XML based format in which the style of any portion of text inside a text element can be changed by embedding that portion inside a <style> tag or other simple HTML tag from the following list: <b>, <u>, <i>, <font>, <sup>, <sub>, <li>, or <br>. As already mentioned, for styled text elements, the content is considered XML, and the engine tries to parse it to extract the style information at runtime. If the parsing fails for any reason, including malformed XML tags, then the engine will simply render that content as pure text, not styled text.

    The XML structure of styled text is very simple and consists only of embedded <style> tags and simple HTML tags. Those tags can be nested on an unlimited number of levels to override certain style settings for the embedded text.

    The <style> tag has various attributes for altering the color, font, or other style properties of the text. From the standard HTML <font> tag, only the fontFace, color and size attributes are recognized by the JasperReports engine.

    All style attributes inside a <style> or <font> tag are optional because each individual style property is inherited from the overall text element or from the parent <style> tag when nested <style> tags are used. Special XML characters like &, <, >, ", and ' must be XML-encoded when placed inside a text field.

    To see how the markup and styled text features work in JasperReports, check the /demo/samples/markup sample provided with the project source files.

    Author:
    Lucian Chirita (lucianc@users.sourceforge.net)