| <?xml version="1.0" encoding="UTF-8" ?> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta name="copyright" content="Copyright (c) 2013, 2019 EclipseSource. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page."/> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> |
| <title>Fonts and Markup in RAP</title> |
| <link rel="stylesheet" href="../../../PRODUCT_PLUGIN/book.css" type="text/css"/> |
| </head> |
| <body> |
| |
| <h1>Fonts and Markup in RAP</h1> |
| <h2>Fonts</h2> |
| <p> |
| Using SWT API it is possible to apply any |
| <em><a href="../reference/api/org/eclipse/swt/graphics/Font.html">Font</a></em> |
| (including bold and italic styles) |
| to almost any widget, as long as it is installed on the client device: |
| </p> |
| <pre class="lang-java"> |
| Label boldLabel = new Label( parent, SWT.NONE ); |
| boldLabel.setFont( new Font( parent.getDisplay(), "Arial", 16, SWT.BOLD ) );</pre> |
| <p> |
| Note that the font height is measured in pixels in RAP (for historical reasons), |
| while SWT uses points. Usually, you can convert the values using this equation: |
| </p> |
| <pre>1px = 0.75pt</pre> |
| <p>therefore</p> |
| <pre>12pt / 0.75 = 16px</pre> |
| <h3>With CSS Theming</h3> |
| <p> |
| While the SWT API can only modify one widget at a time, the RAP |
| <a href="theming.html">CSS theming API</a> is |
| designed to change the appearance for <i>all</i> widget of a given class. However, |
| specific instances can still be targeted using |
| <a href="theming.html#variants">custom variants</a>. |
| The theming API also features some additional properties like |
| <em><a href="../reference/theming/Properties.html#text-shadow">text-shadow</a></em> |
| and |
| <em><a href="../reference/theming/Properties.html#text-decoration">text-decoration</a></em>. |
| </p> |
| <p><b>CSS:</b></p> |
| <pre class="lang-css"> |
| Label.customLabel { |
| font: bold 16px Arial; |
| text-shadow: 2px 2px #bbbbbb; |
| text-decoration: underline; |
| }</pre> |
| <p><b>Java:</b></p> |
| <pre class="lang-java"> |
| Label customLabel = new Label( parent, SWT.NONE ); |
| customLabel.setData( RWT.CUSTOM_VARIANT, "customLabel" ); |
| customLabel.setText( "This is funny!" );</pre> |
| <p><b>Result:</b></p> |
| <p> |
| <img src="../images/css-label.png"/> |
| </p> |
| <p> |
| The properties |
| <em><a href="../reference/theming/Properties.html#font">font</a></em>, |
| <em><a href="../reference/theming/Properties.html#text-shadow">text-shadow</a></em> |
| and |
| <em><a href="../reference/theming/Properties.html#text-decoration">text-decoration</a></em> |
| are available on nearly all themeable widgets. Note that <em>text-shadow</em> is not |
| supported in Internet Explorer 8.0 and below. |
| </p> |
| <h2 id="markup">Markup</h2> |
| <p> |
| While SWT and theming API are able to change the font of any widget, they can usually only change the |
| font for the <i>entire</i> widget. (Tree and table items can change single cells.) |
| Using the RAP-exclusive (not supported in SWT) |
| <i>markup</i> feature, it is possible to change only parts of the text. |
| This is currently supported on |
| <em><a href="../reference/api/org/eclipse/swt/widgets/Label.html">Label</a></em>, |
| <em><a href="../reference/api/org/eclipse/swt/custom/CLabel.html">CLabel</a></em>, |
| <em><a href="../reference/api/org/eclipse/swt/widgets/ToolTip.html">ToolTip</a></em>, |
| <em><a href="../reference/api/org/eclipse/swt/widgets/List.html">List</a></em>, |
| <em><a href="../reference/api/org/eclipse/swt/widgets/Tree.html">Tree</a></em> |
| and |
| <em><a href="../reference/api/org/eclipse/swt/widgets/Table.html">Table</a></em>. |
| Before you can use markup in your widget, |
| you must first enable it explicitly using the |
| <em><a href="../reference/api/org/eclipse/rap/rwt/RWT.html#MARKUP_ENABLED">RWT.MARKUP_ENABLED</a></em> |
| constant |
| as shown below, directly after calling the constructor. (It may not be possible to enable |
| this feature later on, and it can not be disabled again.) Afterwards, a |
| <a href="../reference/api/org/eclipse/rap/rwt/RWT.html#MARKUP_ENABLED">subset of HTML tags</a> |
| can be freely used in the widgets text property: |
| </p> |
| <pre class="lang-java"> |
| Label markupLabel = new Label( parent, SWT.NONE ); |
| markupLabel.setData( RWT.MARKUP_ENABLED, Boolean.TRUE ); |
| markupLabel.setText( "<i>This</i> <ins>is</ins> <b>markup!</b>" );</pre> |
| <p><b>Result:</b></p> |
| <p><img src="../images/markup-label.png"/></p> |
| <p> |
| To achieve similar effects in SWT, the application would have to draw on the widget using a |
| <em><a href="../reference/api/org/eclipse/swt/events/PaintEvent.html">PaintEvent</a></em>, |
| which is not supported in RAP except on |
| <em><a href="../reference/api/org/eclipse/swt/widgets/Canvas.html">Canvas</a></em>. |
| The markup is validated when the text is set on the widget, and incorrect or unsupported markup |
| will cause an <em>IllegalArgumentException</em>. Using markup without enabling the feature |
| first will not cause an exception, just display the text as is. |
| </p> |
| <p> |
| The <em>ToolTipText</em> |
| <a href="../reference/api/org/eclipse/swt/widgets/Control.html#setToolTipText-java.lang.String-">property</a> |
| also supports markup if enabled with <a href="../reference/api/org/eclipse/rap/rwt/RWT.html#TOOLTIP_MARKUP_ENABLED"> |
| TOOLTIP_MARKUP_ENABLED</a>: |
| </p> |
| <pre class="lang-java"> |
| someWidget.setData( RWT.TOOLTIP_MARKUP_ENABLED, Boolean.TRUE ); |
| someWidget.setToolTipText( "<i>Markup</i> inside <b>a tooltip</b>" );</pre> |
| <p>Putting a "<a>" tag in the <em>toolTipText</em> slightly alters the behavior of the |
| tooltip: Normally a tooltip immediately disappears if the mouse cursor hovers it (assuming |
| the user may be aiming for the underlying widget). But since anchor elements are interactive, the |
| tooltip stays until the link is clicked or the mouse cursor is moves away from the tooltip. |
| </p> |
| <h3>Advanced uses of Markup</h3> |
| <p> |
| If the physical and logical tags allowed in the markup are not sufficient for your needs, |
| you may also use a <em>style</em> attribute to specify <i>any</i> CSS code supported by the |
| browser. |
| </p> |
| <pre class="lang-java"> |
| Label cssLabel = new Label( parent, SWT.NONE ); |
| cssLabel.setData( RWT.MARKUP_ENABLED, Boolean.TRUE ); |
| cssLabel.setText( "<span style='font:bold 16px Arial;'>This is also BOLD</span>" );</pre> |
| <p> |
| Unlike the HTML tags, the style properties are <i>not</i> validated on the server. Invalid |
| syntax within the <em>style</em> attribute will likely be ignored by the browser, as will |
| unsupported properties. Using CSS3 properties is therefore not recommended when targeting |
| older browser. |
| </p> |
| <p> |
| The markup feature may not only be used to change the font of the text, but can also insert |
| elements that are not pure text. |
| </p> |
| <p> |
| Using the <em><br/></em> tag, it is possible to add line breaks. |
| While this is also possible without markup on <em>Label</em>, this is a new feature for |
| <em>List</em>, <em>Tree</em> and <em>Table</em>. |
| </p> |
| <p id="img"> |
| The <em><img/></em> |
| tag can insert images anywhere into your text. You can use any URL as |
| the source, and any static images should preferably be provided by another servlet or server. |
| However, if you need the RAP application to provide the image, it has to be registered |
| <a href="resources.html">as a resource</a> |
| first. |
| (You can also de-register the resource when it is no longer needed.) |
| </p> |
| <pre class="lang-java"> |
| Label label = new Label( parent, SWT.NONE ); |
| label.setData( RWT.MARKUP_ENABLED, Boolean.TRUE ); |
| String src = RWT.getResourceManager().getLocation( "icon.png" ); |
| label.setText( "This is the world <img width='24' height='24' src='" + src + "'/> !" );</pre> |
| <p><b>Result:</b></p> |
| <p><img src="../images/image-label.png"/></p> |
| <p><br/> |
| The widget and height attributes are mandatory and do not have to match those |
| of the actual image. |
| </p> |
| <p id="link"> |
| Finally, you can use markup to insert real hyperlinks (<q><em><a></em></q>)into your application. |
| If you do not want to close the UI when the user clicks it, make sure to also set the target |
| property. Alternatively, you can integrate the link with the |
| <em><a href="../reference/api/org/eclipse/rap/rwt/client/service/BrowserNavigation.html">BrowserNavigation</a></em> |
| by |
| <a href="navigation.html#deeplinks">pointing to a fragment id</a>. Examples: |
| </p> |
| <pre class="lang-java"> |
| Label linkLabel = new Label( parent, SWT.NONE ); |
| linkLabel.setData( RWT.MARKUP_ENABLED, Boolean.TRUE ); |
| linkLabel.setText( |
| "Visit <a href='http://www.eclipse.org/rap' target='_blank'>RAP</a>!" |
| ); |
| |
| Label navLabel = new Label( parent, SWT.NONE ); |
| navLabel.setData( RWT.MARKUP_ENABLED, Boolean.TRUE ); |
| navLabel.setText( "Go to <a href='#navPoint'>navPoint</a>!" );</pre> |
| <h3 id="grid">Markup on List, Tree, Table, and Grid</h3> |
| <p> |
| After setting the <em><a href="../reference/api/org/eclipse/rap/rwt/RWT.html#MARKUP_ENABLED">RWT.MARKUP_ENABLED</a></em> |
| property of a <em>Tree</em>/<em>Table</em>/<em>Grid</em>/<em>List</em> widget to <em>Boolean.TRUE</em>, |
| markup is enabled for all its items, except columns. |
| There is, however, one more property that might need to be set. |
| Since RAP can not predict how high items with markup are going to be, it will |
| not include it in the layout calculations for the height of the rows. This may result in cut off |
| content, especially if <em><br/></em>, <em><span></em> |
| or <em><img/></em> tags are used. To fix this, you can set the height the rows should |
| have manually using the |
| <em><a href="../reference/api/org/eclipse/rap/rwt/RWT.html#CUSTOM_ITEM_HEIGHT">RWT.CUSTOM_ITEM_HEIGHT</a></em> |
| constant: |
| </p> |
| <pre class="lang-java"> |
| List markupList = new List( parent, SWT.BORDER ); |
| markupList.setData( RWT.MARKUP_ENABLED, Boolean.TRUE ); |
| markupList.setData( RWT.CUSTOM_ITEM_HEIGHT, new Integer( 40 ) ); |
| markupList.setItems( new String[]{ |
| "<big>big</big>", |
| "<small>small</small>", |
| "with<br/>break" |
| } );</pre> |
| <p> |
| <em>RWT.CUSTOM_ITEM_HEIGHT</em> applies only to <em>Tree</em>, <em>Table</em> and <em>List</em>. |
| For <em>Grid</em>, use its <em>setItemHeight</em> method. |
| </p> |
| <p> |
| When calculating the value for the item height, account for the cell/item |
| padding defined in the |
| <a href="../reference/theming/List.html#List-Item">List</a>/<a href="../reference/theming/Tree.html#Tree-Cell">Tree</a>/<a href="../reference/theming/Table.html#Table-Cell">Table</a> |
| <a href="theming.html">theming</a>. |
| If the HTML content is smaller than the inner cell/item height (i.e. with subtracted padding), |
| it will be top-aligned and leaving empty space at the bottom. |
| If it is higher, the content will be top-aligned (still respecting padding) and cut off at the bottom. |
| </p> |
| <p> |
| <strong>Note:</strong> To achieve more complex layouts within an item, consider |
| using <a href="tree-table.html#templates">templates</a> instead. |
| </p> |
| <p> |
| All widgets that support markup and selection also support a special kind of hyperlink |
| that can be intercepted with a selection event. Read more about it |
| <a href="navigation.html#selection-link">in the article on browser navigation</a>. |
| </p> |
| <h3>Editing</h3> |
| <p> |
| While RAP does not include a markup-enabled text field, there is a port of the Nebula |
| <a href="../reference/api/org/eclipse/nebula/widgets/grid/RichTextEditor.html"><em>RichTextEditor</em></a> based on the |
| the <a href="http://www.ckeditor.com/">CKEditor</a> included in RAP. |
| </p> |
| </body> |
| </html> |
