| <?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 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 target machine: |
| </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. |
| </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/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 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> |
| <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, but if you want the RAP application to provide the image, |
| you need to |
| <a href="resources.html">register it 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>Markup on List, Tree and Table</h3> |
| <p> |
| Combining the markup feature with <em>List</em>, <em>Tree</em> or <em>Table</em> |
| allows you to present your data in a much more informative and appealing way: |
| </p> |
| <p><img src="../images/markup-table.png"/></p> |
| <p> |
| After setting the <em><a href="../reference/api/org/eclipse/rap/rwt/RWT.html#MARKUP_ENABLED">RWT.MARKUP_ENABLED</a></em> property, |
| markup is enabled for all items of the widget, except for columns. |
| There is, however, one more property that might need to be set. |
| Since RAP can not easily 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> |
| <h3>Editing</h3> |
| <p> |
| While RAP does not include an markup-enabled text field, there is a rich text editor |
| <a href="http://wiki.eclipse.org/RAP/Add-Ons">add-on</a> available based on the |
| the <a href="http://www.ckeditor.com/">CKEditor</a>. |
| </p> |
| </body> |
| </html> |
