summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorLina Kemmel2013-05-29 09:46:41 (EDT)
committer Markus Keller2013-05-29 09:47:57 (EDT)
commit20d0261dbb01b159755935a17f239f2c20fd3822 (patch)
treef6e820b5260f974506bf3b1f66829670eb2b11f7
parent9669255542c2a0cea41e12d4857160d29b03a89c (diff)
downloadeclipse.platform.common-20d0261dbb01b159755935a17f239f2c20fd3822.zip
eclipse.platform.common-20d0261dbb01b159755935a17f239f2c20fd3822.tar.gz
eclipse.platform.common-20d0261dbb01b159755935a17f239f2c20fd3822.tar.bz2
Bug 403066: [Bidi] Update documentation for bidi APIs and command line options
-rw-r--r--bundles/org.eclipse.platform.doc.isv/reference/misc/bidi.html120
-rw-r--r--bundles/org.eclipse.platform.doc.isv/reference/misc/runtime-options.html20
2 files changed, 136 insertions, 4 deletions
diff --git a/bundles/org.eclipse.platform.doc.isv/reference/misc/bidi.html b/bundles/org.eclipse.platform.doc.isv/reference/misc/bidi.html
index 8284148..af7ef78 100644
--- a/bundles/org.eclipse.platform.doc.isv/reference/misc/bidi.html
+++ b/bundles/org.eclipse.platform.doc.isv/reference/misc/bidi.html
@@ -1,7 +1,7 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
<head>
-<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2006. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
+<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2013. 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-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link REL="STYLESHEET" HREF="../../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
@@ -40,12 +40,124 @@ inherit this default orientation.</p>
<p><img src="bidi.png" alt="bidi image"></p>
<p><strong>Figure 1 - Screen shot of right to left orientation of the resource
perspective in English</strong></p>
+<h2>Base Text Direction (BTD)</h2>
+<p>Base direction of text (a.k.a. "paragraph direction", "reading order") refers to the overall
+ progression of text in display and it should be controlled independently of the workbench
+ orientation.</p>
+<p>In the context of non-bidi scripts the preferred BTD is LTR. In the context of bidi scripts
+ the preferred BTD is RTL. And in case of mixed text content the preferred BTD is auto (a.k.a.
+ "contextual"). When this type of BTD is effective, the BTD is derived from the directionality
+ of the first strong bidi character.</p>
+<p>An appropriate base text direction is essential for text readability.</p>
+<h3>Default Base Text Direction</h3>
+<p>The default BTD of the workbench can be set with the
+ <b>-bidi "on=y;textDir=[ltr|rtl|auto]"</b> command line option:</p>
+<ul>
+ <li><strong>-bidi "on=y;textDir=ltr</strong> sets the default BTD to left-to-right.</li>
+ <li><strong>-bidi "on=y;textDir=rtl</strong> sets the default BTD to right-to-left.</li>
+ <li><strong>-bidi "on=y;textDir=auto</strong> sets the default BTD to auto (contextual).
+ </li>
+</ul>
+<p>If not specified on the command line, the default text direction is inherited from the workbench
+ orientation.</p>
+<p>In JFace, the default BTD can be retrieved by calling
+ <code>org.eclipse.jface.util.BidiUtils#getTextDirection()</code>. Standalone JFace applications can set
+ the default text direction by calling <code>org.eclipse.jface.util.BidiUtils#setTextDirection()</code>.
+ Then, to apply the default text direction, an application can call
+ <code>org.eclipse.jface.util.BidiUtils#applyBidiProcessing()</code>.</p>
+<p>Example:</p>
+<p><code>
+&nbsp;&nbsp;public static void main(String[] args) {<br><span style="color:blue;">
+&nbsp;&nbsp;&nbsp;&nbsp;BidiUtils.setBidiSupport(true);<br>
+&nbsp;&nbsp;&nbsp;&nbsp;BidiUtils.setTextDirection(BidiUtils.RIGHT_TO_LEFT);</span><br>
+&nbsp;&nbsp;&nbsp;&nbsp;Display display = new Display();<br>
+&nbsp;&nbsp;&nbsp;&nbsp;Shell shell = new Shell(display);<br>
+&nbsp;&nbsp;&nbsp;&nbsp;shell.setLayout(new RowLayout(SWT.VERTICAL));<br>
+&nbsp;&nbsp;&nbsp;&nbsp;Button button = new Button(shell, SWT.PUSH);<br>
+&nbsp;&nbsp;&nbsp;&nbsp;button.setText("RTL button!!!");<br>
+&nbsp;&nbsp;&nbsp;&nbsp;Text text = new Text(shell, SWT.NONE);<br>
+&nbsp;&nbsp;&nbsp;&nbsp;text.setText("RTL text!!!");<br><span style="color:blue;">
+&nbsp;&nbsp;&nbsp;&nbsp;BidiUtils.applyTextDirection(shell, BidiUtils.BTD_DEFAULT);<br></span>
+&nbsp;&nbsp;&nbsp;&nbsp;shell.pack();<br>
+&nbsp;&nbsp;&nbsp;&nbsp;shell.open();<br>
+&nbsp;&nbsp;&nbsp;&nbsp;while (!shell.isDisposed()) {<br>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (!display.readAndDispatch()) display.sleep();<br>
+&nbsp;&nbsp;&nbsp;&nbsp;}<br>
+&nbsp;&nbsp;&nbsp;&nbsp;display.dispose();<br>
+&nbsp;&nbsp;}</code>
+</p>
+<h3>Base text direction in individual controls</h3>
+<p>In SWT, base text direction can be set at a control (either leaf or composite) level.
+ Composites propagate the BTD to their children. The base text direction can be applied as follows:
+</p>
+<ul>
+ <li>upon control creation, by applying <code>org.eclipse.swt.SWT.FLIP_TEXT_DIRECTION</code>
+ style, which indicates that the base text direction should be opposite to the control
+ orientation.</li>
+ <li>on an existing control, by calling <code>org.eclipse.swt.widgets.Control#setTextDirection()</code>.
+ The valid argument values are
+ <code>org.eclipse.swt.SWT.LEFT_TO_RIGHT</code> and <code>org.eclipse.swt.SWT.RIGHT_TO_LEFT</code>.
+ </li>
+</ul>
+<p>Note that at present this is implemented on the win32 platform only.</p>
+<p>Example:</p>
+<p><code>
+&nbsp;&nbsp;public static void main(String[] args) {<br>
+&nbsp;&nbsp;&nbsp;&nbsp;Display display = new Display();<br>
+&nbsp;&nbsp;&nbsp;&nbsp;Shell shell = new Shell(display);<br>
+&nbsp;&nbsp;&nbsp;&nbsp;shell.setText("RTL shell!!!");<br>
+&nbsp;&nbsp;&nbsp;&nbsp;shell.setTextDirection(SWT.RIGHT_TO_LEFT);<br>
+&nbsp;&nbsp;&nbsp;&nbsp;shell.setLayout(new RowLayout(SWT.VERTICAL));<br>
+&nbsp;&nbsp;&nbsp;&nbsp;Button button = new Button(shell, SWT.PUSH);<br>
+&nbsp;&nbsp;&nbsp;&nbsp;button.setText("RTL button!!!");<br>
+&nbsp;&nbsp;&nbsp;&nbsp;button.setTextDirection(SWT.RIGHT_TO_LEFT);<br>
+&nbsp;&nbsp;&nbsp;&nbsp;Text text = new Text(shell, SWT.NONE);<br>
+&nbsp;&nbsp;&nbsp;&nbsp;text.setText("LTR text!!!");<br><span style="color:blue;">
+&nbsp;&nbsp;&nbsp;&nbsp;text.setTextDirection(SWT.LEFT_TO_RIGHT);<br>
+&nbsp;&nbsp;&nbsp;&nbsp;Label label = new Label(shell, SWT.FLIP_TEXT_DIRECTION);<br></span>
+&nbsp;&nbsp;&nbsp;&nbsp;label.setText("RTL label!!!");<br>
+&nbsp;&nbsp;&nbsp;&nbsp;shell.pack();<br>
+&nbsp;&nbsp;&nbsp;&nbsp;shell.open();<br>
+&nbsp;&nbsp;&nbsp;&nbsp;while (!shell.isDisposed()) {<br>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if(!display.readAndDispatch()) display.sleep();<br>
+&nbsp;&nbsp;&nbsp;&nbsp;}<br>
+&nbsp;&nbsp;&nbsp;&nbsp;display.dispose();<br>
+&nbsp;&nbsp;}</code>
+</p>
+<p>JFace applications can set the base text direction on an SWT control by calling
+ <code>org.eclipse.jface.util.BidiUtils#applyTextDirection()</code>, which for
+ <code>org.eclipse.swt.widgets.Text</code> and <code>org.eclipse.swt.custom.StyledText</code>
+ takes effect on win32 and gtk platforms through invocation of the
+ <code>org.eclipse.swt.events.SegmentListener</code> or
+ <code>org.eclipse.swt.custom.BidiSegmentListener</code> mechanism, and for other controls it
+ works on win32 platform, calling <code>org.eclipse.swt.widgets.Control#setTextDirection()</code>
+ API.</p>
+<p>Example:</p>
+<p><code>
+&nbsp;&nbsp;public static void main(String [] args) {<br>
+&nbsp;&nbsp;&nbsp;&nbsp;Display display = new Display();<br>
+&nbsp;&nbsp;&nbsp;&nbsp;Shell shell = new Shell(display);<br>
+&nbsp;&nbsp;&nbsp;&nbsp;shell.setLayout(new RowLayout(SWT.VERTICAL));<br>
+&nbsp;&nbsp;&nbsp;&nbsp;Button button = new Button(shell, SWT.PUSH);<br>
+&nbsp;&nbsp;&nbsp;&nbsp;button.setText("RTL button!!!");<br>
+&nbsp;&nbsp;&nbsp;&nbsp;Text text = new Text(shell, SWT.NONE);<br>
+&nbsp;&nbsp;&nbsp;&nbsp;text.setText("Auto text!!!");<br><span style="color:blue;">
+&nbsp;&nbsp;&nbsp;&nbsp;BidiUtils.applyTextDirection(shell, BidiUtils.RIGHT_TO_LEFT);<br>
+&nbsp;&nbsp;&nbsp;&nbsp;BidiUtils.applyTextDirection(text, BidiUtils.AUTO);<br></span>
+&nbsp;&nbsp;&nbsp;&nbsp;shell.pack();<br>
+&nbsp;&nbsp;&nbsp;&nbsp;shell.open();<br>
+&nbsp;&nbsp;&nbsp;&nbsp;while (!shell.isDisposed()) {<br>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (!display.readAndDispatch()) display.sleep();<br>
+&nbsp;&nbsp;&nbsp;&nbsp;}<br>
+&nbsp;&nbsp;&nbsp;&nbsp;display.dispose();<br>
+&nbsp;&nbsp;}</code>
+</p>
<h2>Enabling Text Processing</h2>
-<p>The orientation of the workbench is independant of the special case processing
+<p>The orientation of the workbench is also independent of the special case processing
for bidirectional languages. If the language of the current Locale is Hebrew,
Arabic, Farsi or Urdu text processing will be enabled. Text processing is used
- to handle special case characters that should not be processed as birdirectional
- text such as path seperators. See <code>org.eclipse.osgi.util.TextProcessor</code>
+ to handle special case characters that should not be processed as bidirectional
+ text such as path separators. See <code>org.eclipse.osgi.util.TextProcessor</code>
for more details. </p>
<h2>Enabling your plug-in for looking up alternate icons</h2>
<p>In many cases your icons will not make any sense in right to left mode. In
diff --git a/bundles/org.eclipse.platform.doc.isv/reference/misc/runtime-options.html b/bundles/org.eclipse.platform.doc.isv/reference/misc/runtime-options.html
index b6a2a75..6e2b6d8 100644
--- a/bundles/org.eclipse.platform.doc.isv/reference/misc/runtime-options.html
+++ b/bundles/org.eclipse.platform.doc.isv/reference/misc/runtime-options.html
@@ -144,6 +144,9 @@ capable of detecting Sun VMs on all platforms.<br>
Also used as the title of error dialogs opened by the launcher. When not set, the name is the name of the executable.</dd>
<dt>-nl &lt;locale&gt; (OSGi)</dt>
<dd>equivalent to setting <a href="#osginl">osgi.nl</a> to &lt;locale&gt;</dd>
+ <dt>-nlExtensions &lt;nlExtensions&gt; (OSGi)</dt>
+ <dd>indicates NL extensions and is equivalent to setting
+ <a href="#osginlextensions">osgi.nl.extensions</a> to &lt;nlExtensions&gt;</dd>
<dt>-noExit (OSGi)</dt>
<dd>equivalent to setting <a href="#osginoshutdown">osgi.noShutdown</a> to &quot;true&quot;</dd>
<dt>-noLazyRegistryCacheLoading (Runtime) </dt>
@@ -204,6 +207,17 @@ in <a href="#eclipsevm">eclipse.vm</a>.</dd>
<dt>-ws &lt;window system&gt; (OSGi) </dt>
<dd>equivalent to setting <a href="#osgiws">osgi.ws</a> to &lt;window system&gt;</dd>
</dl>
+<h3>Bidirectional Support</h3>
+<dl>
+ <dt>-dir &lt;dir&gt;</dt>
+ <dd>indicates the orientation of the workbench and is equivalent to setting
+ <a href="#eclipseorientation">eclipse.orientation</a> to &lt;dir&gt;.</dd>
+ <dt>-bidi &lt;value&gt;</dt>
+ <dd>Indicates the default base text direction and whether special bidi processing
+ should be enabled.</dd>
+ <dd>Valid arguments are <b>&quot;on=[y|n];textDir=[ltr|rtl|auto]&quot;,</b>.</dd>
+ <dd>Example: <b>-bidi &quot;on=y;textDir=rtl&quot;</b></dd>
+ </dl>
<h3>Obsolete command line arguments </h3>
<p>The following command line arguments are no longer relevant or have been superseded
and are consumed by the runtime and not passed on to the application being
@@ -386,6 +400,8 @@ in <a href="#eclipsevm">eclipse.vm</a>.</dd>
<dd>lists the VM arguments used to run Eclipse. This
information is used to construct relaunch command
lines.</dd>
+ <dt><a name="eclipseorientation" id="eclipseorientation"></a>eclipse.orientation {-dir}</dt>
+ <dd>the workbench orientation which can be <b>ltr</b> (left-to-right) or <b>rtl</b> (right-to-left).</dd>
<dt><a name="equinoxsecurityvm"></a>equinox.security.vm</dt>
<dd>If set to &quot;server&quot;, security modules will not attempt to substitute VM's JAAS processing.</dd>
<dt><a name="osgiadaptor"></a>osgi.adaptor</dt>
@@ -685,6 +701,10 @@ will force eclipse to reinitialize these caches.</dd>
<dt><a name="osginl"></a>osgi.nl {-nl}</dt>
<dd>the name of the locale on which Eclipse platform will run. NL values should
follow the standard Java locale naming conventions.</dd>
+ <dt><a name="osginlextensions"></a>osgi.nl.extensions {-nlExtensions}</dt>
+ <dd>the NL extensions, such as collation rules (sorting, searching, grouping), calendar system (locale)
+ and currency format. This is a list of <a href="http://userguide.icu-project.org/locale#TOC-Keywords">keyword</a>=value pairs. For example:
+ <pre>-nlExtensions &quot;@collation=phonebook;calendar=hebrew;currency=USD&quot;</pre></dd>
<dt><a name="osginluser"></a>osgi.nl.user</dt>
<dd>the name of the locale when the user explicitly adds -nl to the command-line arguments.</dd>
<dt><a name="osginoshutdown"></a>osgi.noShutdown {-noExit}</dt>