| Deragon Informatique inc. |
SWT MVC Wrapper: User Guide
|
| Deragon Informatique inc. |
SWT MVC Wrapper: User Guide
|
| 1. | What Is SWT MVC Wrapper |
| 2. | Features |
| 3. | Status (currently beta) |
| 4. | Download |
| 5. | Installation |
| 6. | Usage |
| 7. | Miscellaneous |
| 8. | Screenshoots |
| 9. | To do |
| 10. | Change History |
| 10.1. | Version 0.3 beta |
| 10.2. | Version 0.2 alpha |
| 10.3. | Version 0.1 alpha |
| 11. | License |
| 12. | Contact |
|
ABANDONNED STATE |
This project is currently in an abandonned state. It works fine on Windows, but there are problems with the ComboBox on Linux. When this project was started, I hoped it would incite others to join, but this did not happened. Alone, there is not much motivation to persue. I strongly suggest you do not waste anytime investigating this library. I will probably have it removed by 2005 from SourceForge. |
SWT MVC Wrapper is a LGPL library which provides widgets that wrap around Eclipse's SWT widgets to offer a Model/View/Controller (MVC) model. SWT is a native java widget library provided by the free and easy to use Eclipse IDE. See www.eclipse.org for further details.
Currently, SWT's Button, Combo and Text widgets are wrapped.
The SourceForge page for this project can be found here.
Following is the list of features:
As the name implies, this library provides a Model/View/Controller paradigm to SWT widgets.Following is the list of current models available:
ButtonModel This model is used to follow the state of Button widgets. All types of buttons, including normal, check and radio buttons are supported. ComboModel This model is used to follow the state of Combo widgets. RadioGroupModel This model is used to follow the state of a group of radio buttons. StringModel This model is used to follow the state of a text widget that contains alphanumeric characters. NumberModel This model is used to follow the state of a text widget that contains only floating or integer values.
All the models come with a memory, i.e. they remember their original value. Thus, if you have for instance a GUI to a database, you can query your models like the following:
model.isOriginal()...and depending of the returned boolean value, update the database or not.
A side effect of this feature is the changing of the background color of widgets. By default, this feature is off. But once enabled, if the original value fills the mode, the widget's background is white. If the value has changed, the color becomes yellow (color is configurable). This is helpfull for users to quickly find at a glanced what the changed before commiting the data.
Unlike JFace, SWT MVC Wrapper widgets actually inherits from a composite, thus can be manipulated as a normal widget. The widgets do encompass SWT widgets, but their API does not show it.
Unlike SWT widgets, SWT MVC Wrapper can be subclassed. However, the API could change with time, so be prepared to refactor from time to time. I will make the most efforts to keep the API unchanged though.
A utility class named FormLayoutColumn is provided to easily create columns of pairs of labels/widgets under the FormLayout layout.Check TextFields.makeColumn() for an easy example on how to use this class.
Altough this library has no known bugs and works well, it is still considered in beta status. Why is this? Because I am the only known user of this library. There are no known bugs, but I believe that the library requires more extensive testing before being released as stable. If you use this library, please provide some feedback by writting to: hans@deragon.biz.
The latest version of SWT MVC Wrapper can be downloaded from SourceForge.
To install the library, download the zip file and install it like any other Eclipse plugin.
Lets start with an example to understand how SWT MVC Wrapper works:
StringModel model = new StringModel();
WText widget1 = new WText(parent, SWT.BORDER, model);
WText widget2 = new WText(parent, SWT.BORDER, model);
This example creates two widgets using the same model. Type in one widget, and the content of the other widget is automatically updated accordingly, like with Swing. The model is off course updated, so instead of fetching the data from the widgets, you fetch it from the model.
Easy examples are provided with the library to help new users to understand how to use the API. Following are the online version:
Unfortunately, the API is currently not documented. If enough interest for the library is expressed, efforts will be made to document the API.
Note that JFace viewers also offer an MVC model on a few controls and you might want consider using these official Eclipse classes instead of SWT MVC Wrapper. The difference is mainly that SWT MVC Wrapper is simpler, offer a few more features (and a few less), and you can subclass the libraries classes.
It might be possible that in the future, JFace viewers will be wrapped within the SWT MVC Wrapper library, offering all the benefits of both libraries.
SWT MVC Wrapper widgets are themselves Composites, unlike the JFace viewers which are only containers of widgets. Thus, you can manipulate the widgets pretty much like normal SWT widgets.
The library is kept simple for the moment. It is not expect to have an extensive MVC model as Swing provides, since there is not enough resources working on this project. However, the goal is to wrap up all the SWT widgets to provide a simple, intuitive MVC model.
In the above screenshot, anything you interact on the left column ("Original fields") is reproduced on the right column ("Mirror fields"). Intentional exception to this rule are the WRadioGroupFillLayout #1 and Wrong way with WRadioButton rows. See the code as to see why they do not behave as the other rows. The widgets normaly show up with their original background, but change to yellow when their value changed. The default behavior of the widgets are to keep their original color in all cases, but in this example, we enabled the feature.
Notice that the background color for buttons is a bit flemsy under Windows. There is nothing that can be done about that. For normal and toggle buttons, the background cannot be changed. For check and radio button, its the text area, not the graphical box or circle which color changes. The only way to correct this is to implement our own widgets, but this is out of the scope of this project. Off course, you can disable color change in your application. In fact, by default it is off.
This is the screenshot of the Text Field screen. It is accessible by pressing on the ¨Text fields¨ button on the main window. This screen is used to test the text field widgets. Some have their original values (in white), some have their value changed (in yellow). Notice the number fields (NumberModel used) with a comma as a decimal separator. I have my settings set to "French Canadian" locale, thus the comma. But the separator could be different for another locale. For instance, americains would see a dot. Numeric pad decimal separator works for all locales. WText widgets using a NumberModel can only accept digits or decimal separators. See the code.
The following are features to be added in future releases.
| 10.1. | Version 0.3 beta |
| 10.2. | Version 0.2 alpha |
| 10.3. | Version 0.1 alpha |
This software is covered by the LGPL license. For a local copy of the license, see the local file LICENSE.txt provided with the package.
If you have any questions or issues with this software, you can contact the following persons:
Author: Hans Deragon Email: hans@deragon.biz Website: www.deragon.biz