blob: ca804c4aee1063b1d7ada60d79850392c343c96c [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
<html xmlns="">
<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"/>
<h1>Fonts and Markup in RAP</h1>
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:
<pre class="lang-java">
Label boldLabel = new Label( parent, SWT.NONE );
boldLabel.setFont( new Font( parent.getDisplay(), "Arial", 16, SWT.BOLD ) );</pre>
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:
<pre>1px = 0.75pt</pre>
<pre>12pt / 0.75 = 16px</pre>
<h3>With CSS Theming</h3>
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>
<em><a href="../reference/theming/Properties.html#text-decoration">text-decoration</a></em>.
<pre class="lang-css">
Label.customLabel {
font: bold 16px Arial;
text-shadow: 2px 2px #bbbbbb;
text-decoration: underline;
<pre class="lang-java">
Label customLabel = new Label( parent, SWT.NONE );
customLabel.setData( RWT.CUSTOM_VARIANT, "customLabel" );
customLabel.setText( "This is funny!" );</pre>
<img src="../images/css-label.png"/>
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>
<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.
<h2 id="markup">Markup</h2>
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>
<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>
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:
<pre class="lang-java">
Label markupLabel = new Label( parent, SWT.NONE );
markupLabel.setData( RWT.MARKUP_ENABLED, Boolean.TRUE );
markupLabel.setText( "&lt;i&gt;This&lt;/i&gt; &lt;ins&gt;is&lt;/ins&gt; &lt;b&gt;markup!&lt;/b&gt;" );</pre>
<p><img src="../images/markup-label.png"/></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.
<h3>Advanced uses of Markup</h3>
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
<pre class="lang-java">
Label cssLabel = new Label( parent, SWT.NONE );
cssLabel.setData( RWT.MARKUP_ENABLED, Boolean.TRUE );
cssLabel.setText( "&lt;span style='font:bold 16px Arial;'&gt;This is also BOLD&lt;/span&gt;" );</pre>
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.
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.
Using the <em>&lt;br/&gt;</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 id="img">
The <em>&lt;img/&gt;</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>
(You can also de-register the resource when it is no longer needed.)
<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 &lt;img width='24' height='24' src='" + src + "'/&gt; !" );</pre>
<p><img src="../images/image-label.png"/></p>
The widget and height attributes are mandatory and do not have to match those
of the actual image.
<p id="link">
Finally, you can use markup to insert real hyperlinks (<q><em>&lt;a&gt;</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>
<a href="navigation.html#deeplinks">pointing to a fragment id</a>. Examples:
<pre class="lang-java">
Label linkLabel = new Label( parent, SWT.NONE );
linkLabel.setData( RWT.MARKUP_ENABLED, Boolean.TRUE );
"Visit &lt;a href='' target='_blank'&gt;RAP&lt;/a&gt;!"
Label navLabel = new Label( parent, SWT.NONE );
navLabel.setData( RWT.MARKUP_ENABLED, Boolean.TRUE );
navLabel.setText( "Go to &lt;a href='#navPoint'&gt;navPoint&lt;/a&gt;!" );</pre>
<h3>Markup on List, Tree and Table</h3>
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><img src="../images/markup-table.png"/></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>&lt;br/&gt;</em>, <em>&lt;span&gt;</em>
or <em>&lt;img/&gt;</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>
<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[]{
} );</pre>
While RAP does not include an markup-enabled text field, there is a rich text editor
<a href="">add-on</a> available based on the
the <a href="">CKEditor</a>.