MyEclipse Logo
 

Matisse4MyEclipse (M4M) Tutorial

Outline
download the latest MyEclipse version

help and support
 

1. Preface

This document was written using MyEclipse. All screenshots are based upon the default user interface settings for MyEclipse and Windows XP. If you experience difficulty with the instruction of this document, please see the User Feedback section for how to provide feedback to the MyEclipse documentation team.

Note: Matisse4MyEclipse is only available to users with a Professional level MyEclipse subscription. A free 30-day trial of MyEclipse with professional features enabled is available from www.myeclipseide.com.


 

2. Requirements and Restrictions

Below is a list of requirements for this Tutorial:

  1. MyEclipse (see Resources for a download link)

3. Introduction

Matisse is the code name for the well-known WYSIWYG Swing user-interface designer of NetBeans 5.0. This designer includes some of the most intuitive and advanced layout and sizing controls of any Swing visual designer today. Matisse4MyEclipse is an implementation of NetBeans Matisse that integrates its functionality into MyEclipse Enterprise Workbench to enable the rapid development of Java Swing rich client applications (RCP) within the MyEclipse environment.

Based on the Netbeans implementation, Matisse4MyEclipse includes:

  • Swing/Matisse workbench perspective
  • Form Editor with visual design and source modes
  • Extensible palette of Swing and AWT controls
  • Form creation and project library configuration wizard
  • Properties view
  • Outline view
  • Preferences for operation customization
  • Numerous UI control and event configuration wizards.

The design process involves drag-and-drop placement of Swing and AWT components from the UI controls palette onto a visual form. The Form Editor provides advanced alignment guides and sizing tools to enable quick development of aesthetically pleasing user interfaces in minutes. The source mode of the Form Editor is an embedded version of the Eclipse Java Editor and allows quick viewing and modification of generated and supporting Java code.


Figure 1: Example Matisse form shown in default Swing/Matisse Perspective


4. Working with Matisse4MyEclipse

This section introduces you to the primary Matisse4MyEclipse tasks and features involved in developing and testing a Swing user-interface within the MyEclipse environment. Key facts to be familiar with as you work with Matisse4MyEclipse are:

  1. A Matisse form consists of an XML form description file and a corresponding Java source file, e.g., Contact.form & Contact.java
  2. As the Matisse form is visually edited, the corresponding Java source file is updated in real-time to produce the content and layout of the form.
  3. Generated Java source methods and fields are delineated with special Java comments that begin and end with a one-line comment including the substring //GEN-.., e.g., //GEN-BEGIN or //GEN-END. Avoid editing between these special comments otherwise there is the potential that Form Editor may overwrite these code sections during a visual editing session. 
  4. Where possible, Matisse4MyEclipse attempts to accurately replicate all of the NetBeans Swing GUI Designer functionality. In some areas this was not possible due to Eclipse user-interface and interaction conventions, integration dependencies or technology limitations. See Section 6 and the Matisse4MyEclipse release-notes for more information.

Visit the Resources section for a list of Matisse tutorials and demos.


4.1 Creating a Matisse Form

Begin by creating a Java Project. If you already have a Java project that you plan to work within skip to step-3

Creating a Java Project

  1. From the menubar select File>New>Project... and select " Java Project " to activate the Java Project Wizard.
  2. Enter the name of your Java Project (e.g., Matisse_Example) and other options followed by  Finish

Creating Matisse Form

  1. From the menubar, select File>New>Other...
  2. Select MyEclipse>Swing>Matisse Form followed by Next


Figure 2: New Wizards selection-list

  1. In the Matisse Form Wizard enter the source folder, Java package, a Java class name for the form and select the type of user-interface to create. In this example we are creating a Swing JFrame.
    Note: the Java package will be created if it does not already exist.


Figure 3: New Matisse Form Wizard

  1. Select Finish to create the form and its corresponding Java class, a.k.a. form backing class.

Upon completion of this example the following project elements were created:

    • test.example1 Java package
    • TestForm.form, the XML Matisse description file
    • TestForm.java
    • swing-layout-1.0.jar, add to the project and its build-path

Note: swing-layout-1.0.jar is required to support the advanced layout manager of the Matisse Form Editor.


Figure 4: New Matisse Form opened in Matisse Form Editor


4.2 Opening the Swing/Matisse Perspective

Matisse4MyEclipse includes a new Eclipse perspective known as the Swing/Matisse perspective. This new perspective presents an organization of the primary Matisse views and the Form Editor in a workbench layout very similar to the NetBeans 5.0 user-interface organization. The intent of this perspective is to quickly introduce new Matisse4MyEclipse users to the primary Matisse views and editors and to provide NetBeans users with a familiar user interface layout similar to NetBeans Matisse view layout.   

Note: by default the Swing/Matisse perspective will open when creating a Matisse form, see Figure 7.

Following is the process for opening the Swing/Matisse workbench perspective:

  1. From the menubar selected Windows>Open Perspective>Other


Figure 5: Accessing all perspectives

  1. Next select MyEclipse Swing/Matisse from the list of perspectives followed by OK


Figure 6: Perspectives list

  1. The workbench will be updated with the Swing/Matisse perspective's predefined views, toolbar and menubar actions. You are free to customize the perspective by adding/removing views and action-sets, and repositioning and resizing any view.


Figure 7: Swing/Matisse Perspective


4.3 Using the Matisse Form Editor - Design Mode

The Matisse Form Editor supports 2 working modes: a visual design mode and a source-editing mode. To change modes, select the tab of the desired mode in the bottom left corner of the editor (see Figure 8).

Adding UI Control to a Form 

  1. Within the Matisse Palette, select (mouse-click) the UI control you wish to add to the form
  2. Move the cursor from the Matisse Palette over the Form Editor. You will notice the mouse changes to reflect a draggable version of your active control
  3. Position the UI control to the desired location and click the mouse to drop the control (mouse-click)


Figure 8: Direct placement of UI controls on Matisse form

Repositioning a UI Control

  1. Select the UI control on the form (mouse-down).
  2. Drag the control to its new location and drop the control (mouse-up).

Resizing a UI Control

  1. Select the UI control on the form. Notice that on the control's perimeter are resize points.
  2. Drag-and-drop the resize point to the new size and direction.

Direct Text Editing

  1. The text content of UI controls such as labels, text-fields and text-areas can be directly edited by double-clicking into the text region of the control. The control will transition into an edit mode with an I-bar cursor.
  2. Once in the edit mode, you can position the I-bar cursor to any location within the text region and enter or delete text.


4.4 Editing UI Properties

UI controls have properties that control their size, position, color, text styling, and many other presentation and behavior. To modify a control's properties use the Properties View. By default this view is present in the bottom-right corner of the Swing/Matisse perspective. The Properties View enables you to view and edit the properties of the currently selected UI control of the Matisse Form Editor.


Figure 10: Properties View

Opening the Properties View

If the Properties View is not present you can open it as follows:

  1. Select the control for whose properties you are interested
  2. From the context-menu (right-click menu) choose the Properties action. The Properties View will open in the location it last appeared in the workbench.

Most properties can be directly edited by double-click selection into the property's value cell and entering the new value. Special property-selection and editing dialogs are available to facilitate the editing of properties such as fonts, colors, alignment, and even long text strings. Select the  to open the property's editor dialog. Figure 11 illustrates opening of the Font Selection Dialog.


Figure 11: Launching supporting dialog from Properties View


4.5 Using the Matisse Form Editor - Java Source Mode

The source mode of the Matisse Form Editor supports the viewing and editing the corresponding Java source of the current form. This mode is implemented using an integrated version of the Eclipse Java editor to provide a consistent and familiar Eclipse-based Java source editing experience. When in the source mode, the standard and advanced Eclipse Java editing features are available such as: code-assist, formatting, source refactoring.

The Form Editor generates the Java source code required to produce the form layout at run-time. While in design mode, as UI controls are added, removed, resized, or their properties are edited, Matisse is actively generating the corresponding Java source code. Matisse identifies regions of generated source code using special one-line comments that include the substring pattern  " //GEN-<the context>" to delimit the region. When you first switch to source mode, some code regions such as the #initComponent method are initially collapsed using code-folding.

Note: Do not edit code between the special //GEN-... comments if you plan to use the form mode to revise the form layout. Custom edits between these marker comments may be lost as new code is generated during the visual form design process.


Figure 12: Matisse Form Editor - Java Source Mode


4.6 Preview Matisse Form

The Matisse Form Editor enables the quick preview of its static form content. Select the Preview button on the Form Editor toolbar to launch a preview version of the form (see Figure 13).

Note: the preview mode is limited to viewing the user interface. No event handlers are active. To test an active version of the user interface see Testing Matisse User Interface.


Figure 13: Previewing Matisse Form


4.7  Adding an Event Listener

EventListeners enable event-handling code to be associated with UI controls for the purpose of process their events. The Form Editor provides utilities that will generate stubbed out event listeners and register them with their target UI control. The follow example illustrates creating an ActionListener for a JButton. 

  1. Select the control in the UI form (ubutton1)
  2. From the context-menu (right-click menu) select Event>Action>actionPeformed (see Figure 14a)

This will generate an example actionPeformed listener method and register the method as target callback for the button.


Figure 14a: Initiate event listener creation

 


Figure 14b: Event handler method

 


Figure 14c: Registering event handler method with button


4.8 Testing Matisse User Interface 

The Matisse Form Wizard generates a main() routing for top-level user interface components such as JFrames and Dialogs. This enables them to be launched and tested as stand-alone Java window applications. To test your form do the following:

  1. In the Java PackageExplorer view, right-click on the form's backing Java class, e.g., TestForm.java
  2. From the context-menu (right-click menu) select Run As>Java Application. This will launch the form in new Java virtual machine.    


Figure 15: Matisse Form launched as Swing application


4.9. Customizing Matisse Palette

The Matisse Palette can be extended to include your own custom forms and widgets.  Once you have created a form, you can add it to the palette through a palette manager and then these custom forms will be available during design of any new form.

Here are the steps to extending the Matisse Palette.

  1. Create a new form to be added to the paletted and save it to a project as normal.


  2. In the Matisse Palette, bring up the Palette manager from the view menu.


  3. In the Palette Manager, select the Custom folder and press the "Add Form..." button.


  4. In dialog, find the location of your custom .form that you want to add to the palette and click "OK".


  5. Notice that your custom form has been added to the Custom folder.  Now press OK to close Palette Manager.


  6. Now your custom forms will be available to be added to your forms like any other palette control.


Note: Once custom sub-forms and Java beans are added to a form, they are not refreshed during a workspace session.  Their images in the Form designer are not updated when the original forms are modified. To get them to update, a workspace restart is required.hem to update, a workspace restart is required.

5. Preferences

Matisse4MyEclipse preferences enable you to modify its customizable behaviors such as default perspective opening behavior, code generation styles and code folding.

Accessing Matisse4MyEclipse preferences

  1. From the menubar select Windows>Preferences...
  2. Select MyEclipse>Matisse4MyEclipse


Figure 16: Matisse4MyEclipse Preferences


6. Differences between Matisse4MyEclipse and NetBeans 5.0 Swing GUI Designer

This section highlights some of the most notable differences between Matisse4MyEclipse and the NetBeans 5.0 Swing Designer.

1. Drag-and-Drop UI Controls From Matisse Palette
 In order to remain consistent with all other MyEclipse visual design tools, Matisse4MyEclipse uses a slightly different interaction model than NetBeans for adding a UI control from the Matisse Palette to a form.

The Matisse4MyEclipse process is: 

Pickup UI control in Matisse Palette (mouse-click)
Move cursor over Matisse form 
Drop UI control (mouse click)  

NetBeans process is:

Select UI control in Matisse Palette (mouse down)
Move cursor over Matisse form 
Drop UI control (mouse up)  

2. Java Source Mode Editor
The Source Mode of the Form Editor is an implementation of the Eclipse Java Editor. This modification enables the Form Editor to work more naturally with all other Eclipse Java source management features.

3. Direct edit of Form Java Source File
 Matisse4MyEclipse does not guard against the opening of the backing Java source file of a Matisse form directly in the Eclipse Java Source Editor. In general this practice should be avoided in favor of using the Matisse Form Editor. 

4. Other Integration Differences
You should familiarize yourself with the Matisse4MyEclipse release notes to gain a full understanding of features that are currently being integrated and known issues.  


7. Summary

This concludes your introduction to Matisse4MyEclipse. Additional Tutorial documents are available that introduce working with Web Projects, editing, application server configuration, enterprise application projects and database development. For more information visit the MyEclipse Tutorial library.


8. User Feedback

If you have comments or suggestions regarding this document please submit them to the MyEclipse Documentation Forum .


9. Resources