<?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( "&lt;i&gt;This&lt;/i&gt; &lt;ins&gt;is&lt;/ins&gt; &lt;b&gt;markup!&lt;/b&gt;" );</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( "&lt;i&gt;Markup&lt;/i&gt; inside &lt;b&gt;a tooltip&lt;/b&gt;" );</pre>
   <p>Putting a "&lt;a&gt;" 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( "&lt;span style='font:bold 16px Arial;'&gt;This is also BOLD&lt;/span&gt;" );</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>&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>
  <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, 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 &lt;img width='24' height='24' src='" + src + "'/&gt; !" );</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>&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>
    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 &lt;a href='http://www.eclipse.org/rap' 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 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>&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>
    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[]{
  "&lt;big&gt;big&lt;/big&gt;",
  "&lt;small&gt;small&lt;/small&gt;",
  "with&lt;br/&gt;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>