View source for Creating UI with the net.sf.okapi.common.ui.abstracteditor Package

==Preface==

Okapi provides a framework to allow you quickly and painlessly build rich user interfaces for various Okapi components.

The framework is pure SWT. You can use [http://www.instantiations.com/windowbuilder/swtdesigner/index.html SWT Designer] with the framework, or do things manually if you wish so.

==Parts of the Framework==

The framework is located in the <code>net.sf.okapi.common.ui.abstracteditor</code> package of the <code>okapi-core-ui</code> Maven project.

==Examples of Use==

* <code>okapi-filter-html-ui</code>
* <code>okapi-filter-plaintext-ui</code>
* <code>okapi-filter-table-ui</code>

==General Concepts==

The framework introduces the container-page-control model.

* A container is a window (shell), hosting one or more pages.
* A page is a panel (composite), hosting one or more controls, groups, or composites.
* A control is an SWT widget, like a check-box or push-button.

The framework provides the means for controls’ interoperability. A control on one page can communicate with any other control either on the same page, or on a different page in the same or a different container.

Containers can have any SWT-supported style. In Okapi parameters editors there are normally multi-tab resizable dialogs and pop-up OK/Cancel dialogs. The framework provides base classes for those.

Every tab in the multi-tab dialog is a page. The client area of the OK/Cancel dialog is also a page.

==Configuring SWT Designer==

If to create the pages you will be using the SWT Designer, you should configure Eclipse in a special way:

In <cite>Window > Preferences > WindowBuilder > SWT > Code Generation</cite>:

* check <cite>Use the existing code generation settings...</cite>
* in <cite>Default code generation settings > Variable generation</cite> activate <cite>Field</cite>
* in <cite>Default code generation settings > Statement generation</cite> activate <cite>Flat</cite> (optional)

In <cite>Window > Preferences > WindowBuilder > SWT > Code Generation > Variables > Miscellaneous</cite>:

* check <cite>Remember variable name in component</cite> ('''Important!''')

==If You Do SWT Manually==

When you create a control, don’t forget to put its name in the <code>name</code> property:

 myButton = new Button(parent, SWT.NONE);
 myButton.setData("name", "myButton");

==The Framework in a Nutshell==

* Every page is a subclass of the SWT composite plus an implementation of the <code>IDialogPage</code> interface. 
* The multi-tab parameters editors are subclasses of <code>AbstractParametersEditor</code>, OK/Cancel dialogs are subclasses of <code>AbstractBaseDialog</code>. For a query dialog there’s no need to create  a new subclass, you can call <code>SWTUtils.inputQuery()</code>, passing it a custom dialog page class.
* There are 2 kinds of communication in the framework: internal (in-page) and inter-page. Internal is the communication between controls of the same page. It’s provided by the <code>interop()</code> method of the page. Inter-page communication is provided by the editor class, and is contained in its <code>interop()</code>.
* To configure the internal interop, write a body to the auto-generated <code>interop()</code> method, and call it from event listeners of all involved controls.
* To assign rules for inter-page interop, make a body for the editor’s <code>interop()</code> method, and call <code>addSpeaker(pageClass, controlName)</code> from <code>createPages()</code>.
* <code>SWTUtils</code> provide a range of helpers to easily configure inter-page interop. A few of the helpers are: <code>enableIfSelected(target, source)</code>, <code>disableIfNotSelected(target, source)</code>.

You can omit the remainder of this document unless you have a time to try an example hands on.

==Let’s Give It a Try==

Now we will create a parameters editor with two tab pages, and a dialog box for user input, run from a button on the second page. 

The first page has a check-box controlling availability of the second page’s button.

===Creating a New Parameters Editor Project===

* Create a new Java Plug-in Project (<cite>File > New > Other > Plug-in Development > Plug-in Project</cite>)
* Give it a name, here <code>swt_test</code>
* Open the manifest <code>MANIFEST.MF</code>
* On the <cite>Dependencies</cite> tab add plug-ins:
** <code>org.eclipse.swt</code>
** <code>net.sf.okapi.common</code>
** <code>net.sf.okapi.ui.common</code>
* On the <cite>Runtime</cite> tab add <code>swt_test</code> to have your editor visible from outside.

===Creating the Main Editor Class===

* Right-click on the <code>src/swt_test</code> package, <cite>New > Class</cite>
* In <cite>Name</cite> type in the standard name for an editor class: <code>Editor</code>. For <cite>Superclass</cite> type in: <code>net.sf.okapi.common.ui.abstracteditor.AbstractParametersEditor</code> (Hint: You can click <cite>Browse</cite> and start typing <code>AbstractParametersEditor</code> in the <cite>Supeclass Selection</cite> dialog)
* Make sure <cite>Inherited abstract methods</cite> is checked, click <cite>Finish</cite>.
* Eclipse will auto-generate 4 methods in the new class:
** <code>protected void createPages(TabFolder pageContainer)</code> -- creates pages and provides references to the controls participating in inter-page interop.
** <code>public IParameters createParameters()</code> -- provides the parameters class (returns <code>new net.sf.okapi.filters.table.Parameters();</code>)
** <code>protected String getCaption()</code> -- provides the caption of your editor’s window (returns <code>My Filter Parameters</code>;)
** <code>protected void interop(Widget speaker)</code> -- provides interoperability between pages

===Creating Tabs===

* Select the <code>src/swt_test</code> package
* Create a new page.
** With SWT Designer: <cite>File > New > Other > WindowBuilder > SWT Designer > SWT > Composite</cite>.
** Manually: <cite>File > New > Class</cite>. In Superclass: <code>org.eclipse.swt.widgets.Composite</code>.
* Give it a name: <code>FirstTab</code>.
* In the editor window in class declaration after <code>extends Composite</code> type in <code>implements IDialogPage</code>. This will turn the composite into the framework’s client. You have to do it manually, because SWT Designer doesn’t handle descendants of abstract classes, and wants a direct subclass of a Composite.
* <code>IDialogPage</code> gets underlined, choose <cite>Import IDialogPage(net.sf.okapi.common.ui.abstracteditor)</cite>
* Now <code>FirstTab</code> is underlined, choose <cite>Add unimplemented methods</cite>.
* Eclipse will insert four method stubs:
** <code>public boolean canClose(boolean isOK)</code> -- returns true if the dialog can be closed at the moment; parameter indicates if the dialog is being closed with OK.
** <code>public void interop(Widget speaker)</code> -- provides interoperability between controls of this page, speaker is the control which fired the interop event.
** <code>public boolean load(Object data)</code> -- data contains the parameters being edited, controls should configure themselves according to the given parameters in this method.
** <code>public boolean save(Object data)</code> -- changes parameters referred by data according to the controls’ settings. Returns true if parameters were saved from GUI successfully.

* '''Note:''' For compound filters this method is called several times for every internal filter, so the type should be checked before typecasting to the actual parameters class). Returns true if parameters were loaded to GUI successfully.

* '''Important note:''' if the auto-generated <code>canClose()</code>, <code>load()</code>, <code>andSave()</code> return false, change it to <code>return true</code>, otherwise the editor won’t close, and load/save page errors will be displayed.

* Place groups and controls on the page. (In SWT Designer click the <cite>Design</cite> tab, and drop controls from the palette.) Here we put one group named <code>group1</code> and containing a check-box <code>check1</code> and a button <code>button1</code>. The SWT Designer will create this code, which of course can be typed in manually:

<pre>
private Group group1;
private Button check1;
private Button button1;

public FirstTab(Composite parent, int style) {

    super(parent, style);
    setLayout(new GridLayout(1, false));

    group1 = new Group(this, SWT.NONE);
    group1.setLayout(new GridLayout(2, false));
    group1.setText("First group");
    group1.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, true, 1, 1));
    group1.setData("name", "group1");

    check1 = new Button(group1, SWT.CHECK);
    check1.setText("Enable buttons");
    check1.setSelection(true);
    check1.setData("name", "check1");

    button1 = new Button(group1, SWT.NONE);
    button1.setData("name", "button1");
    button1.setText("Don't click me!");
}
</pre>

* Create the second page. Give it the name <code>SecondTab</code>. Drop a group <code>group2</code> and a button <code>button2</code>. The code is:

<pre>
private Group group2;
private Button button2;

public SecondTab(Composite parent, int style) {

    super(parent, style);
    setLayout(new GridLayout(1, false));

    group2 = new Group(this, SWT.NONE);
    group2.setLayout(new GridLayout(1, false));
    group2.setText("Second group");
    group2.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, true, 1, 1));
    group2.setData("name", "group2");

    button2 = new Button(group2, SWT.NONE);
    button2.setData("name", "button2");
    button2.setText("Click Me!");
}
</pre>

* Add the created pages to the editor. Open <code>Editor.java</code>, and add the following code to <code>createPages()</code>:

<pre>
    addPage("General", FirstTab.class);
    addPage("Options", SecondTab.class);
</pre>

===Testing===

* In <code>okapi-ui-harness</code> open <code>net.sf.okapi.testutilities.uiharness.Okapi_GUI_Tester.java</code>
* right-click on <code>Okapi_GUI_Tester.java</code>, <cite>Build Path > Configure Build Path...</cite>
* <cite>Projects</cite> tab, <cite>Add</cite>, swt_test, <cite>OK</cite>
* Add the name of the new editor class to the <code>GUI_CLASSES</code> list (lines 66 on): <code>swt_test.Editor.class.getName()</code>
* Click <tt>Ctrl+F11</tt> to run the GUI Tester, and double-click on <code>swt_test.Editor</code>. It will display a warning that parameters have not been created, and display the editor.

===Creating a User Input Dialog===

* Create a third page. Give it the name <code>LoginPage</code>.
* Type in <code>implements IInputQueryPage</code> in the class declaration.
* Add unimplemented methods.
* Change <code>return false</code> to <code>return true</code>. Or better, find a place in Eclipse where to change the default.
* Drop two labels and two text edits on it. The code is:

<pre>
private Label lblName;
private Label lblPassword;
private Text name;
private Text password;

public LoginPage(Composite parent, int style) {

    super(parent, style);
    setLayout(new GridLayout(2, false));

    lblName = new Label(this, SWT.NONE);
    lblName.setLayoutData(new GridData(SWT.RIGHT, SWT.CENTER, false, false, 1, 1));
    lblName.setData("name", "lblName");
    lblName.setText("User Name:");

    name = new Text(this, SWT.BORDER);
    name.setLayoutData(new GridData(SWT.FILL, SWT.CENTER, true, false, 1, 1));
    name.setData("name", "name");

    lblPassword = new Label(this, SWT.NONE);
    lblPassword.setLayoutData(new GridData(SWT.RIGHT, SWT.CENTER, false, false, 1, 1));
    lblPassword.setData("name", "lblPassword");
    lblPassword.setText("Password:");

    password = new Text(this, SWT.BORDER);
    password.setLayoutData(new GridData(SWT.FILL, SWT.CENTER, true, false, 1, 1));
    password.setData("name", "password");
}
</pre>

* Open the <code>SecondTab.java</code>. Assign the following code to the select event of <code>button2</code>:

<pre>
button2.addSelectionListener(new SelectionAdapter() {
    public void widgetSelected(SelectionEvent e) {

        if (SWTUtils.inputQuery(LoginPage.class, getShell(), "Enter your user name and password",  null, null)) {
        }
    }
});
</pre>

* Check in GUI Tester.

===In-Page Interop===

Now we want the checkbox on the first page control the enabled state of the button on the same first page. We need to do the two things:

* Set an event listener to the check-box to call interop:

<pre>
check1.addSelectionListener(new SelectionAdapter() {
    public void widgetSelected(SelectionEvent e) {

        interop(null);
    }
});
</pre>

* change our <code>interop()</code> method in <code>FirstTab.java</code>:

<pre>
public void interop(Widget speaker) {

    button1.setEnabled(check1.getSelection());
}
</pre>

===Inter-Page Interop===

And the final fun we want the check-box on the first page to control the enabled state of the button on the other (second) page. 

Also we want the login dialog to display a user name and password. 

And we do those thing without touching the pages’ code. We do two things in <code>swt_test.Editor.java</code>:

* Set references to the controls we want bound. Also bind them with <code>SWTUtils</code> helpers.

<pre>
protected void interop(Widget speaker) {

    Control check1 = findControl(FirstTab.class, "check1");
    Control button2 = findControl(SecondTab.class, "button2");

    Control name = findControl(LoginPage.class, "name");
    Control password = findControl(LoginPage.class, "password");

    SWTUtils.enableIfSelected(button2, check1);
    SWTUtils.disableIfNotSelected(button2, check1);

    SWTUtils.setText(name, "user");
    SWTUtils.setText(password, "********");
}
</pre>

* Set "speakers", i.e. controls initiating interop (we have only <code>check1</code> speaker):

<pre>
protected void createPages(TabFolder pageContainer) {

    addPage("General", FirstTab.class);
    addPage("Options", SecondTab.class);

    addSpeaker(FirstTab.class, "check1");
}
</pre>

==Where to Now?==

You can try the [[Table Filter]] parameters editor as it uses the framework to the upmost. The classes are located in <code>okapi-filter-table-ui</code>, also the [[Table Filter]] employs the <cite>Options</cite> tab of the [[Plain Text Filter]] (<code>okapi-filter-plaintext-ui</code>).