| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 transitional//EN"> |
| <html> |
| <head> |
| <title>Text Element (Eclipse BIRT ROM Documentation)</title> |
| <link rel="stylesheet" href="../style/style.css" type="text/css"/> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| </head> |
| <body> |
| <p class="title">Eclipse BIRT Report Object Model (ROM)</p> |
| <p class="subtitle">Text Element</p> |
| <h1>Element Overview</h1> |
| <div class="section-text"> |
| Displays a multi-line block of text defined within the |
| report. Can contain embedded formatting and value expressions.</div> |
| <h3>Details</h3> |
| |
| <table class="detail-table"> |
| <tr><td>Display Name:</td> |
| <td>Text</td></tr> |
| <tr><td>Since:</td> |
| <td>1.0</td></tr> |
| <tr><td>XML Element:</td> |
| <td><code>text</code></td></tr> |
| <tr><td>Extends:</td> |
| <td><a href="ReportItem.html">ReportItem</a></td></tr> |
| <tr><td>Extendable:</td> |
| <td>Yes</td></tr> |
| <tr><td>Abstract:</td> |
| <td>No</td></tr> |
| <tr><td>Name Space:</td> |
| <td>Report Items</td></tr> |
| <tr><td>Name Requirement:</td> |
| <td>Optional</td></tr> |
| <tr><td>Allows User Properties:</td> |
| <td>Yes</td></tr> |
| <tr><td>Has Style:</td> |
| <td>Yes</td></tr> |
| <tr><td>Default Style:</td> |
| <td><a href="../styles.html#text">text</a></td></tr> |
| </table> |
| |
| <h3>Property Summary</h3> |
| |
| <dl class="section-text"> |
| <dt><a href="#Property-content">content</a></dt> |
| <dd>The text for the item.</dd> |
| <dt><a href="#Property-contentID">contentID</a></dt> |
| <dd>Resource key for the content.</dd> |
| <dt><a href="#Property-contentType">contentType</a></dt> |
| <dd>The formatting within the text: HTML or plain text.</dd> |
| </dl> |
| |
| <h3>Method Summary</h3> |
| |
| <dl class="section-text"> |
| <dt><a href="#Method-onCreate">onCreate</a></dt> |
| <dd>Script executed when the element is created in the Factory.</dd> |
| <dt><a href="#Method-onPageBreak">onPageBreak</a></dt> |
| <dd></dd> |
| <dt><a href="#Method-onPrepare">onPrepare</a></dt> |
| <dd>It is for a script startup phase. No data binding yet. The design of an element can be changed here.</dd> |
| <dt><a href="#Method-onRender">onRender</a></dt> |
| <dd>Script executed when the element is prepared for rendering in the Presentation engine.</dd> |
| </dl> |
| |
| <h3>Inherited Properties</h3> |
| |
| <p class="section-text"> |
| <a href="ReportItem.html#Property-bookmark">bookmark</a>, |
| <a href="ReportItem.html#Property-boundDataColumns">boundDataColumns</a>, |
| <a href="ReportElement.html#Property-comments">comments</a>, |
| <a href="ReportItem.html#Property-cube">cube</a>, |
| <a href="DesignElement.html#Property-customXml">customXml</a>, |
| <a href="ReportItem.html#Property-dataBindingRef">dataBindingRef</a>, |
| <a href="ReportItem.html#Property-dataSet">dataSet</a>, |
| <a href="ReportElement.html#Property-displayName">displayName</a>, |
| <a href="ReportElement.html#Property-displayNameID">displayNameID</a>, |
| <a href="ReportElement.html#Property-eventHandlerClass">eventHandlerClass</a>, |
| <a href="ReportElement.html#Property-extends">extends</a>, |
| <a href="ReportItem.html#Property-height">height</a>, |
| <a href="ReportElement.html#Property-name">name</a>, |
| <a href="ReportItem.html#Property-paramBindings">paramBindings</a>, |
| <a href="DesignElement.html#Property-propertyMasks">propertyMasks</a>, |
| <a href="ReportItem.html#Property-refTemplateParameter">refTemplateParameter</a>, |
| <a href="ReportItem.html#Property-style">style</a>, |
| <a href="ReportItem.html#Property-toc">toc</a>, |
| <a href="DesignElement.html#Property-userProperties">userProperties</a>, |
| <a href="ReportElement.html#Property-viewAction">viewAction</a>, |
| <a href="ReportItem.html#Property-visibility">visibility</a>, |
| <a href="ReportItem.html#Property-width">width</a>, |
| <a href="ReportItem.html#Property-x">x</a>, |
| <a href="ReportItem.html#Property-y">y</a>, |
| <a href="ReportItem.html#Property-zIndex">zIndex</a> |
| </p> |
| <h3>Style Properties</h3> |
| |
| <p class="section-text"> |
| <a href="Style.html#Property-backgroundAttachment">backgroundAttachment</a>, |
| <a href="Style.html#Property-backgroundColor">backgroundColor</a>, |
| <a href="Style.html#Property-backgroundImage">backgroundImage</a>, |
| <a href="Style.html#Property-backgroundPositionX">backgroundPositionX</a>, |
| <a href="Style.html#Property-backgroundPositionY">backgroundPositionY</a>, |
| <a href="Style.html#Property-backgroundRepeat">backgroundRepeat</a>, |
| <a href="Style.html#Property-borderBottomColor">borderBottomColor</a>, |
| <a href="Style.html#Property-borderBottomStyle">borderBottomStyle</a>, |
| <a href="Style.html#Property-borderBottomWidth">borderBottomWidth</a>, |
| <a href="Style.html#Property-borderLeftColor">borderLeftColor</a>, |
| <a href="Style.html#Property-borderLeftStyle">borderLeftStyle</a>, |
| <a href="Style.html#Property-borderLeftWidth">borderLeftWidth</a>, |
| <a href="Style.html#Property-borderRightColor">borderRightColor</a>, |
| <a href="Style.html#Property-borderRightStyle">borderRightStyle</a>, |
| <a href="Style.html#Property-borderRightWidth">borderRightWidth</a>, |
| <a href="Style.html#Property-borderTopColor">borderTopColor</a>, |
| <a href="Style.html#Property-borderTopStyle">borderTopStyle</a>, |
| <a href="Style.html#Property-borderTopWidth">borderTopWidth</a>, |
| <a href="Style.html#Property-canShrink">canShrink</a>, |
| <a href="Style.html#Property-color">color</a>, |
| <a href="Style.html#Property-display">display</a>, |
| <a href="Style.html#Property-fontFamily">fontFamily</a>, |
| <a href="Style.html#Property-fontSize">fontSize</a>, |
| <a href="Style.html#Property-fontStyle">fontStyle</a>, |
| <a href="Style.html#Property-fontVariant">fontVariant</a>, |
| <a href="Style.html#Property-fontWeight">fontWeight</a>, |
| <a href="Style.html#Property-highlightRules">highlightRules</a>, |
| <a href="Style.html#Property-letterSpacing">letterSpacing</a>, |
| <a href="Style.html#Property-lineHeight">lineHeight</a>, |
| <a href="Style.html#Property-marginBottom">marginBottom</a>, |
| <a href="Style.html#Property-marginLeft">marginLeft</a>, |
| <a href="Style.html#Property-marginRight">marginRight</a>, |
| <a href="Style.html#Property-marginTop">marginTop</a>, |
| <a href="Style.html#Property-masterPage">masterPage</a>, |
| <a href="Style.html#Property-orphans">orphans</a>, |
| <a href="Style.html#Property-paddingBottom">paddingBottom</a>, |
| <a href="Style.html#Property-paddingLeft">paddingLeft</a>, |
| <a href="Style.html#Property-paddingRight">paddingRight</a>, |
| <a href="Style.html#Property-paddingTop">paddingTop</a>, |
| <a href="Style.html#Property-pageBreakAfter">pageBreakAfter</a>, |
| <a href="Style.html#Property-pageBreakBefore">pageBreakBefore</a>, |
| <a href="Style.html#Property-pageBreakInside">pageBreakInside</a>, |
| <a href="Style.html#Property-showIfBlank">showIfBlank</a>, |
| <a href="Style.html#Property-textAlign">textAlign</a>, |
| <a href="Style.html#Property-textIndent">textIndent</a>, |
| <a href="Style.html#Property-textLineThrough">textLineThrough</a>, |
| <a href="Style.html#Property-textOverline">textOverline</a>, |
| <a href="Style.html#Property-textTransform">textTransform</a>, |
| <a href="Style.html#Property-textUnderline">textUnderline</a>, |
| <a href="Style.html#Property-verticalAlign">verticalAlign</a>, |
| <a href="Style.html#Property-whiteSpace">whiteSpace</a>, |
| <a href="Style.html#Property-widows">widows</a>, |
| <a href="Style.html#Property-wordSpacing">wordSpacing</a> |
| </p> |
| <h3>Description</h3> |
| |
| <div class="section-text"> |
| <p>The text item allows the developer to provide the text as |
| part of the report design. The text can be localized. Text can be in HTML or |
| plain text format. HTML text can contain placeholders for data and expressions: |
| something line the mail merge feature of a word processing program. "Mail merge" |
| is feature in which a standard block of text contains "place holders" for data |
| retrieved from a database. It is often used to create form letters, or to format |
| specific blocks of text within a report. For example, a report can use the text |
| item to display a single line with the US-style city/state/zip address line:</p> |
| |
| <pre class="code-block"><value-of>row.city</value-of>, |
| <value-of>row.state</value-of> |
| <value-of>row.zipcode</value-of></pre> |
| |
| <p>Which might appear as:</p> |
| |
| <pre class="code-block">South San Francisco, CA 94080</pre> |
| |
| <p>Another example is "mail-merge", i.e., to incorporate |
| personalized data into a block of text. Mail-merge is especially powerful when |
| combined with sections to create conditional paragraphs that further customize |
| each letter.</p> |
| |
| <p>The Text item provides many powerful features:</p> |
| |
| <ul> |
| <li>Ability to enter formatted text that contains markers for data fields, expressions, and so on. |
| When run, the value of each field is concatenated with any static text to produce the final output.</li> |
| |
| <li>Control text formatting on a character-by-character basis within a single text control. For example, displaying one word in a paragraph in a different font and color from the rest.</li> |
| |
| <li>Automatically adjust element size based on content.</li> |
| |
| <li>A single text element can span multiple pages to accommodate large amounts of text.</li> |
| |
| <li>Specify formatting using embedded HTML.</li> |
| |
| </ul> |
| |
| <p>The text object is designed to allow continuous flow of |
| text. Creating the same effect with a set of report items (such as labels and |
| data items) has the well-known problems that the appearance varies depending on |
| characteristics of the printer or display format. (Font widths & heights vary |
| across presentation formats, making it difficult to align free-form labels and |
| data items.) The user can combine a series of text elements, each in a separate |
| section, to create conditional blocks of text.</p> |
| |
| <p>BIRT leverages HTML and other open standards for |
| rendering. For the most part, formatting within a block of text is simply passed |
| to the browser or other formatting engine for processing.</p> |
| |
| <p>A text item can be used to create report headings and |
| other textual content. Using a text item is often easier than using a grid, |
| free-form or other container. With text, the item contains text instead of |
| rectangular report items. Text is placed onto lines. Lines grow and shrink |
| depending on the size of their contents just as in Word or HTML. Text can be |
| centered, or can be left or right justified. ROM provides control over line |
| spacing, paragraph spacing and similar properties.</p> |
| |
| <p>For example:</p> |
| |
| <pre class="code-block"><center><b><span style=�font-size: larger�> |
| Monthly Sales Summary</span><br> |
| For the month of: |
| <value-of>Date.monthName( params.MonthParam )</value-of>, |
| <value-of>Date.year( params.MonthParam )</value-of> |
| <\b></center></pre> |
| |
| <p>Displays a report title that looks like this:</p> |
| |
| <p style="text-align: center"><b> |
| <span style="font-size: 14.0pt">Monthly Sales Summary</span></b></p> |
| <p style="text-align: center"><b>For the month of: November, 2004</b></p></div> |
| <h3>See Also</h3> |
| |
| <div class="section-text"> |
| <p>Label Item element</p> |
| <p>Multi-line Data element</p> |
| <p>Style element, especially the Font and Text properties.</p> |
| <p>HTML Support section below.</p> |
| <p>Embedded Expressions section.</p></div> |
| <h1>Property Detail</h1> |
| |
| <h2><a name="Property-content">content Property</a></h2> |
| |
| <p class="section-text">The text for the item.</p> |
| <h3>Details</h3> |
| |
| <table class="detail-table"> |
| <tr><td>Type:</td> |
| <td><a href="../types.html#literalString">literalString</a></td></tr> |
| <tr><td>Since:</td> |
| <td>1.0</td></tr> |
| <tr><td>Required:</td> |
| <td>No</td></tr> |
| <tr><td>Display Name:</td> |
| <td>Content</td></tr> |
| <tr><td>JavaScript Type:</td> |
| <td></td></tr> |
| <tr><td>Default Value:</td> |
| <td>None</td></tr> |
| <tr><td>Inherited:</td> |
| <td>Yes</td></tr> |
| <tr><td>Runtime Settable:</td> |
| <td>No</td></tr> |
| <tr><td>Property Sheet Visibility:</td> |
| <td>Visible</td></tr> |
| <tr><td>Property Sheet Group:</td> |
| <td>Top</td></tr> |
| </table> |
| |
| <h3>Description</h3> |
| |
| <div class="section-text"> |
| <p>The text for the item. See the <code>contentType</code> property for how to identify the text |
| formatting. The text can be externalized.</p></div> |
| <h3>See Also</h3> |
| |
| <div class="section-text"> |
| <p> </p></div> |
| |
| <hr> |
| <h2><a name="Property-contentID">contentID Property</a></h2> |
| |
| <p class="section-text">Resource key for the content.</p> |
| <h3>Details</h3> |
| |
| <table class="detail-table"> |
| <tr><td>Type:</td> |
| <td><a href="../types.html#resourceKey">resourceKey</a></td></tr> |
| <tr><td>Since:</td> |
| <td>1.0</td></tr> |
| <tr><td>Required:</td> |
| <td>No</td></tr> |
| <tr><td>Display Name:</td> |
| <td>Content key</td></tr> |
| <tr><td>JavaScript Type:</td> |
| <td></td></tr> |
| <tr><td>Default Value:</td> |
| <td>None</td></tr> |
| <tr><td>Inherited:</td> |
| <td>Yes</td></tr> |
| <tr><td>Runtime Settable:</td> |
| <td>Yes</td></tr> |
| <tr><td>Property Sheet Visibility:</td> |
| <td>Visible</td></tr> |
| <tr><td>Property Sheet Group:</td> |
| <td>Top</td></tr> |
| </table> |
| |
| |
| <hr> |
| <h2><a name="Property-contentType">contentType Property</a></h2> |
| |
| <p class="section-text">The formatting within the text: HTML or plain text.</p> |
| <h3>Details</h3> |
| |
| <table class="detail-table"> |
| <tr><td>Type:</td> |
| <td><a href="../types.html#choice">choice</a> (textContentType)</td></tr> |
| <tr><td>Since:</td> |
| <td>1.0</td></tr> |
| <tr><td>Required:</td> |
| <td>No</td></tr> |
| <tr><td>Display Name:</td> |
| <td>Content type</td></tr> |
| <tr><td>JavaScript Type:</td> |
| <td></td></tr> |
| <tr><td>Default Value:</td> |
| <td>auto</td></tr> |
| <tr><td>Inherited:</td> |
| <td>Yes</td></tr> |
| <tr><td>Runtime Settable:</td> |
| <td>No</td></tr> |
| <tr><td>Property Sheet Visibility:</td> |
| <td>Visible</td></tr> |
| <tr><td>Property Sheet Group:</td> |
| <td>Top</td></tr> |
| </table> |
| |
| <h3>Choices</h3> |
| |
| <table class="section-table"> |
| <thead><tr><td>Name</td><td>Display Name</td> |
| <td>Value</td><td>Description</td></tr></thead> |
| <tbody> |
| <tr><td>auto</td> |
| <td>Auto</td> |
| <td>auto</td> |
| <td>BIRT will infer the |
| format as explained below.</td></tr> |
| <tr><td>plain</td> |
| <td>Plain</td> |
| <td>plain</td> |
| <td>Plain text with no |
| formatting.</td></tr> |
| <tr><td>html</td> |
| <td>HTML</td> |
| <td>html</td> |
| <td>Formatting using a |
| subset of HTML tags.</td></tr> |
| </tbody></table><br> |
| <h3>Description</h3> |
| |
| <div class="section-text"> |
| <p>The user can explicitly identify the format of the text |
| using the Content Type property. Or, the user can set the property to "auto", |
| (or omit the property) and BIRT will infer the format from the text itself.</p> |
| |
| <p>BIRT determines the text format by examining the first |
| few characters of the string. If the first characters are "<HTML>" (in either |
| upper case or lower case), then the string is assumed to be HTML. Otherwise, the |
| text is plain text. Any white space before these characters is ignored. That is, |
| "<html>" and " <html>" are both taken to indicate that the text is formatted |
| in HTML.</p></div> |
| <h1>Method Detail</h1> |
| |
| <h2><a name="Method-onCreate">onCreate Method</a></h2> |
| |
| <p class="section-text">Script executed when the element is created in the Factory.</p> |
| <h3>Synopsis |
| </h3> |
| |
| <p class="section-text"><code>None obj.onCreate( )</code></p> |
| <h3>Details |
| </h3> |
| |
| <table class="detail-table"> |
| <tr><td>Since:</td> |
| <td>1.0</td></tr> |
| <tr><td>Context:</td> |
| <td>factory</td></tr> |
| <tr><td>Arguments:</td> |
| <td>None</td></tr> |
| <tr><td>Return Type:</td> |
| <td>None</td></tr> |
| </table> |
| |
| <h3>Description</h3> |
| |
| <div class="section-text"> |
| <p>Executed when the element is created in the Factory. Called after the item is created, but before |
| the item is saved to the report document file. See the scripting spec for additional information |
| about this script. Applications should perform visual customization in the on-render script instead.</p></div> |
| |
| <hr> |
| <h2><a name="Method-onPageBreak">onPageBreak Method</a></h2> |
| |
| <p class="section-text"></p> |
| <h3>Synopsis |
| </h3> |
| |
| <p class="section-text"><code>None obj.onPageBreak( )</code></p> |
| <h3>Details |
| </h3> |
| |
| <table class="detail-table"> |
| <tr><td>Since:</td> |
| <td>2.1</td></tr> |
| <tr><td>Context:</td> |
| <td>presentation</td></tr> |
| <tr><td>Arguments:</td> |
| <td>None</td></tr> |
| <tr><td>Return Type:</td> |
| <td>None</td></tr> |
| </table> |
| |
| |
| <hr> |
| <h2><a name="Method-onPrepare">onPrepare Method</a></h2> |
| |
| <p class="section-text">It is for a script startup phase. No data binding yet. The design of an element can be changed here.</p> |
| <h3>Synopsis |
| </h3> |
| |
| <p class="section-text"><code>None obj.onPrepare( )</code></p> |
| <h3>Details |
| </h3> |
| |
| <table class="detail-table"> |
| <tr><td>Since:</td> |
| <td>2.0</td></tr> |
| <tr><td>Context:</td> |
| <td>startup</td></tr> |
| <tr><td>Arguments:</td> |
| <td>None</td></tr> |
| <tr><td>Return Type:</td> |
| <td>None</td></tr> |
| </table> |
| |
| <h3>Description</h3> |
| |
| <div class="section-text"> |
| <p>It is for a script startup phase. No data binding yet. The design of an element can be changed here.</p></div> |
| |
| <hr> |
| <h2><a name="Method-onRender">onRender Method</a></h2> |
| |
| <p class="section-text">Script executed when the element is prepared for rendering in the Presentation engine.</p> |
| <h3>Synopsis |
| </h3> |
| |
| <p class="section-text"><code>None obj.onRender( )</code></p> |
| <h3>Details |
| </h3> |
| |
| <table class="detail-table"> |
| <tr><td>Since:</td> |
| <td>1.0</td></tr> |
| <tr><td>Context:</td> |
| <td>presentation</td></tr> |
| <tr><td>Arguments:</td> |
| <td>None</td></tr> |
| <tr><td>Return Type:</td> |
| <td>None</td></tr> |
| </table> |
| |
| <h3>Description</h3> |
| |
| <div class="section-text"> |
| <p>Executed when the element is prepared for rendering in the Presentation engine. Changes made to the |
| element are written to the target output format, but not saved to the report document file. This is the |
| preferred place for visual customizations.</p></div> |
| </body> |
| </html> |
