Tod Creasey's Eclipse Blog

TextProcessor and BIDI

2007-03-28T15:24:00.000-04:00

As a follow on from my post a couple of days ago I thought I would dive a bit deeper in when to use the Text Processor.

Lets start from the javadoc:

"This class is used to process strings that have special semantic meaning (such as file paths) in RTL-oriented locales so that they render in a way that does not corrupt the semantic meaning of the string but also maintains compliance with the Unicode BiDi algorithm of rendering Bidirectional text.

Processing of the string is done by breaking it down into segments that are specified by a set of user provided delimiters. Directional punctuation characters are injected into the string in order to ensure the string retains its semantic meaning and conforms with the Unicode BiDi algorithm within each segment."

So where do I use it?
Anywhere where the string you are displaying has a series of segments where the ordering of the segments is the same no matter what language you are displaying. The most common examples are file associations, file paths, URLS and URIs.

When is it processing Strings?
The TextProcessor will do bidirectional String processing anytime you are running with your Locale set to one of the four bidirectional languages (Arabic, Farsi, Hebrew or Urdu).

Will it process if my layout is right to left?
Only if your Locale is one of the languages mentioned above.

Do these extra characters get picked up if I copy the String?
Yes. In some applications that do not try and interpret these characters (such as Notepad) they will show up as control characters.

How do I strip the extra directional characters out?
TextProcessor#deprocess(String)will allow you to remove them.

What should I do about input fields for these Strings?
The Eclipse Platform tries to avoid creating behaviour that is inconsistent with the operating system as much as possible. As a result we do not process the input String - the user gets whatever the operating system wants to show them.

Once again we would love to hear from anyone who is using our bidirectional support day to day to give us more feedback.

Bidirectional Support FAQ

2007-03-26T12:39:00.000-04:00

Here on the Platform team we have had a series of questions about how the bidirectional support in Eclipse works and I thought it was time I blogged about it. Here are some commonly asked questions:

1) What is the difference between using -dir rtl and -nl iw?

-dir rtl was a command line parameter that Help was using before the workbench added it's general BIDI support in 3.1. When we added the BIDI support ourselves we continued to support the old flag but we also felt that the -nl command line parameter made more sense. If you are using a Arabic, Farsi, Hebrew or Urdu locale as the argument to the -nl parameter you will get right to left support.

The TextProcessor does not support the -dir rtl parameter so it is recommended that you use the -nl parameter to get all of the bidi support. Note that TextProcessor will process BIDI strings whenever the Locale is bidirectional whether or not the Locale was set by -nl or taken from the OS.

So if you use -dir rtl your orientation will be set to right to left but your paths etc. will not use the text processing.

2) What is the difference between TextProcessor and Window#getDefaultOrientation ?

TextProcessor is a class supplied by OSGi to used to process strings that have special semantic meaning (such as file paths) in RTL-oriented locales so that they render in a way that does not corrupt the semantic meaning of the string but also maintains compliance with the Unicode BiDi algorithm of rendering Bidirectional text. (from the javadoc).

So for instance http://www.eclipse.org/ will render the entire String in left to right order but will process each segment right to left.

org.eclipse.jface.Window#getDefaultOrientation is a method used to determine the default orientation for windows. If it is not set the default value will be unspecified (SWT#NONE) (also from the javadoc).

Dialogs, Windows, IWorkbenchParts and FormToolkits use this value to determine their default orientation. All of these classes allow the orientation to be overridden.

3) Why do I not get bidirectional text processing in left to right orientations?

Using the TextProcessor to evaluate paths is slower than not processing them at all (of course). For performance reasons we do not use TextProcessor unless you are in a bidirectional Locale.

4) How do I set my inputs to use bidirectional support?

All input processing is done using the platform widgets. Eclipse generally does not try and work differently than the OS so we use the OS input methods.

5) What happens if I use multiple direction parameters?

There is a precedence of these parameters. As document in the help at org.eclipse.platform.doc.isv/reference/misc/bidi.html:

The orientation of the workbench is determined in one of the following ways (in order of priority):

-dir command line parameter. If the -dir command line option is used this will be the default orientation. Valid values are -dir rtl or -dir ltr.
system properties. If the system property eclipse.orientation is set this will be used. The recognized values of this property are the same as the -dir command line argument.
-nl command line parameter. If the -nl option is used and the language is Arabic, Farsi, Hebrew or Urdu the orientation will be right to left.
Failing all of the above, the platform defaults to a left to right orientation.

The TextProcessor is only checking Locale and does not use this precedence.

So...

-dir rtl will give you right to left windows but no text processing
-nl fa will give you right to left windows and text processing
-nl ur -dir ltr will give you left to right windows and text processing
Starting Eclipse in a bidirectional Locale with no arguments will give you left to right windows and text processing

6) Is right to left ever the default?
No. When we initially did this work we made right to left the default for users in the right to left locales but the overwhelming response was that they developed in left to right and then we should only switch orientation if explicitly asked to.

So if you start Eclipse on an Urdu machine with no command line arguments you will get left to right orientation. If you start Eclipse using the command line argument -nl ur on the same machine you will get right to left orientation.

7) Who uses this support?
This is actually a question for you. We know there are lots of users who use Eclipse left to right in a right to left locale but we are interesting in hearing from

Users who use right to left for their Eclipse development - especially if they want some right to left support changes in JDT or EMF.
Users who use left to right but frequently have to deal with right to left strings and find the lack of bidirectional text support problematic

If you are one of these people please log a bug to Bugzilla or add a comment to this blog.

Accessibility, Editable Text and Labels

2006-12-06T09:47:00.000-05:00

You may have noticed that throughout the Eclipse UI we will periodically use an editable Text instead of a Label. There are two reasons for this

You might want to allow the user to select the text for copying. We use it in the Resource Property Page to allow you to select the path of a resource for instance.
Accessibility. If a label needs to be read to make a dialog usable it has to be able to take focus for screen reader users. The wizard dialog error message area is an example of this. Note that we don't do this if the label is just a secondary note.

You will of course notice that there are Labels all over the place in the UI. If a label is beside an unlabelled widget (like a Text) that can take focus it will be used as the title by a screen reader.

This only works if the label and the widget that can take focus have the same parent and are one after the other in the z-order. z-order is order of creation by default - if that doesn't work for you because of how your code is structured check out Control#moveAbove or Control#moveBelow to adjust this order.

If you want more details you can check out my article on eclipse.org at or better yet vote and then go to Cori Ryan's talk at Eclipsecon .

Safer ways to parent your Shells

2006-10-12T15:54:00.000-04:00

I have recently seen a fair amount of code where people are creating Dialogs parented off of the active shell using Display#getActiveShell().

There are a lot of shells in Eclipse. Beyond the obvious ones (the Workbench Window and any modal Dialogs you have open) you can have a Shell to animate trim, a Shell to show a tool tip, a Shell for content assist and so on. If one of these is the active shell you could parent your Shell off of all sorts of things.

To be safe try and use a Shell that you are aware of - i.e. if you are creating something off of another Dialog use the Shell of that Dialog. Of course this doesn't help you for your first Dialog which should use the Workbench Window as a parent.

If you look at ProgressManagerUtil#getNonModalShell() you can see how we do it for the Progress manager.


 IWorkbenchWindow window =
   PlatformUI.getWorkbench().getActiveWorkbenchWindow();
     if (window == null) {
      IWorkbenchWindow[] windows = PlatformUI.getWorkbench().getWorkbenchWindows();
      if (windows.length > 0)
  return windows[0].getShell();
     } else
  return window.getShell();

   return null;

you still need to handle the null case but it is not particularly common that you have no Workbench windows.

To be even safer in 3.1 org.eclipse.jface.ShellProvider was implemented. This can be used to parent any window and allows you to choose the Shell when the dialog is about to be created rather than when you create the instance.

This is really handy if you want to delay opening the dialog for some reason or are concerned about the shell you have selected closing on you.

Widget tickling in JFace

2006-10-06T13:51:00.000-04:00

Some of you may have noticed that in M2 we have refactored the way refreshing happens in Table and Tree Viewers so that if you want to access the widget during a refresh you can now. This is really useful for things like using the new SWT owner draw support but also eliminates the need for the plethora of color,font, text and image providers we used to use.

We of course support your old code but if you want to check out our new streamlined code have a look at org.eclipse.jface.viewers.CellLabelProvider#update(ViewerCell cell).

Special thanks to Tom Schindl and Boris (our UI API Polizei) for all of his help hammering the new API out.

Imagine there is no Image#isDisposed....

2006-04-28T08:37:00.000-04:00

Michael Valenta and I were talking today about the Eclipse Image management story and I thought I might post a quick pointer here.

So when do you want an ImageRegistry and when do you want a ResourceManager? First off you want to use either of them to prevent the need to manage Images yourself - you can reference your Images using an ImageDescriptor or a String and let the ResourceManager clean them up when it shuts down.

The ImageRegistry allows you to register an image based on a keyword (String), the ResourceManager allows you to do so with an ImageDescriptor. The ResourceManager is the back end of the ImageRegistry. Usually you use the ImageRegistry to allow lookup based on a constant (like we do for the JFace Dialog constants) and you use the ResourceManager to do lookup based on an ImageDescriptor you are holding onto.

Many people just use the the JFace ImageRegistry or ResourceManager. That will work but if everyone did that large applications will have every image loaded for the duration of thier Eclipse session (those images are generally not disposed until shutdown of JFace). The DeviceResourceManager that JFace uses has reference counting which will cut down on some of the redundant Images but you might be surprised at the references you have if you are not thinking about it.

If you can bound the lifecycle better (especially if you are one of the cool kids who really do dynamically load and unload plug-ins) using your own LocalResourceManager parented off of the JFace one is a great way to keep your OS resource load down.

Doing that will make Stefan Xenos (the ResourceManager mastermind) almost as happy as getting him that Corvette he lusts after ...

Question from those of us not at EclipseCon

2006-03-23T10:06:00.000-05:00

As part of the imminent Eclipse Platform baby boom (6 babies just arrived or on thier way!) I am here in Ottawa working during EclipseCon so I have seen the Steve splash screen about 400 times now.

What we all want to know is where is Steve's other hand?

So how do I check I'm accessible on Windows?

2006-01-20T12:31:00.000-05:00

We get a lot of problem reports detailing that something in Eclipse is not working well with a screen reader (usually Window Eyes or JAWS).

A lot of the time the screen reader is not following the MSAA (Microsoft Active Accessibility) API and so when you find a problem you need to double check with a tool that does use it. MSAA is the API that SWT calls out to to provide accessibility information.

We found the easiest one to use is the inspect32 tool from Microsoft (Google inspect32 MSAA to find it - I won't post the link here as it may be out of date soon). Start inspect32 up, give the widget you are concerned about focus and it will tell you what MSAA information you have.

And by the way skip using the Narrator that comes for free with XP, it is not nearly robust enough for using with an SDK.

So how VIRTUAL are you?

2005-08-05T14:44:00.000-04:00

Steve Northover and I were talking this morning about some of the extra support (and fixes) we want to do in the JFace VIRTUAL support in 3.2.

One use case we hear about is that when you scroll enough on a Table it populates so much that the Table is effectively a normal Table.

If you had 1,000,000 entries this would be a problem. But does anyone actually have this case? I would be interested to hear if there is a product out there that users will periodically overpopulate thier table with scrolling.

There is one case I can see that is easy to get - that is a shift-selecting the whole table (see https://bugs.eclipse.org/bugs/show_bug.cgi?id=98248).

Accessibility: lines in the sand

2005-05-31T15:23:00.000-04:00

I have been asked a few times now about how accessibility should be tested using Eclipse. The Eclipse team is testing using the following parameters:

Windows XP High Contrast
1152x768 Display

If we don't scale right for you with this settings please log us a bug.

Icons in the nl world

2005-05-31T11:20:00.000-04:00

Eclipse 3.1 is going to support bidirectional languages (those that can type right to left as well as left to right such as Arabic). This means that for a lot of Eclipse applications you are going to want to provide alternative icons to those you ship (mostly those with a horizontal arrow or something like that).

First step is nl'ing your icon lookup. The Platform does this internally in a bunch of places by creating a URL and using the Runtime API to look it up. The secret is the $nl$ in your path - that tells the runtime to look in fragments as well.

Here is an example

String iconPath = "$nl$/icons/myicon.gif";

URL url = Platform.find( Platform.getBundle(MyPluginId), new Path(iconPath));

Image Descriptor descriptor = ImageDescriptor.createFromURL(url);

If you want to dig around more have a look at org.eclipse.ui.internal.util.BundleUtility to see how we do it.

If the icon reference is in your plugin.xml just make sure you have the $nl$ prefix on your path. We will handle this for you (and log us a bug if not!). Just make sure if you create your own extension point that it loads ImageDescriptors this way.

Second step is creating a fragment - icons are done the same way as message catalogs so no rocket science there.

Finally test it. You can switch orientation using the -dir rtl command line option or by specifying a bidirectional language using the -nl option (iw (Hebrew), ar (Arabic), fa (Farsi) or ur (Urdu)). Note we don't do this for free as a lot of users in these locales still want the left to right look.

Welcomes to Tods Eclipse Blog

2005-05-31T08:13:00.000-04:00

Welcome to my Eclipse Blog. I am going to post random snippets of info here as I come across them in my daily work on the Eclipse UI team.