Master Detail

Master-Detail Eclipse Forms

I just finished working on the editor which uses the Master-Detail pattern of the eclipse forms. During which I faced several problems like:

• In my master block, when the size of table-viewer increased, the master block shows the scrollbar instead of table-viewer. Also, it made the length of the detail and master parts equal which made my editor unusable
• Detail part having scroll problems like the one mentioned above
• Setting the details part data-dynamically was yet another area where I faced a lot of problem

In this blog, I will be giving a brief introduction about the master-detail pattern and will be addressing the problems mentioned above.

The article by Dejan Glozic is really helpful and explains the basics of the eclipse forms. I’ll be explaining the stuff using FUSE Integration Designer(FID) which is an open source and available for download. And the screen-shots will be from the Messaging module of the FID using the example of JMS Messages.

In computer user interface design, a master-detail page is one where a master object and its related detail object are represented on the same page. The detail objects are displayed based on the current record selection in the master object. A master object can be a form, list or tree of items, and a detail section can be a form, list or tree of items typically placed either below or next to the master object. Selecting an item from the master list causes the details of that item to be populated in the detail pane.

Master/Details block

'Master/Details' is a pattern used throughout the UI world. It consists of a list or a tree ('master') and a set of properties ('details') driven by the selection in the master. Eclipse Forms provide the implementation of the pattern as a useful building block with the following properties:

• While 'details' part is managed by the class itself, the master part factory method is abstract and must be implemented by the subclass
• Master and details parts are children of a sash form and the ratio of the form space allocated for each can be changed by moving the sash.
• As usual with a sash form, master and details parts can be organized horizontally or vertically in the form.

The idea of master/details block is to create a tree or a table section that fires the selection notification via the managed form. If the details part can handle the selected object, it should switch to the page for it and display properties. When building on top of the provided master/details block, subclasses should:

• Create the master part (the one that drives the details)
• Contribute actions to the form tool bar (consumes upper-right portion of the form in the title area)
• Register details pages, one for each distinct input that can arrive from the master part

We will show how this looks in practice source code that accompanies FID. It creates a table for the master part and hooks the received JMS Messages. Details pages are registered to handle selections of these types. Pages can contain any number of controls - they are created on demand in the provided parent. The details area scrolls separately from the master area.

This part can now be used anywhere, but in this example it was placed inside an editor. Details pages registered with the Details part need to implement IDetailsPage interface.

The page is first initialized with the managed form to get access to the toolkit and other objects. It is then asked to create contents in the provided parent. It should also set focus on the first control when asked, be able to refresh, commit, dispose and react to the input changes. As long as objects selected in the master part are of a compatible type, the page will stay visible and inputChanged will be called.

Let's see how all this looks in practice:

One of the received messages is selected in the master part. The appropriate page for the type is loaded in the details part. The ratio of parts on the page can be changed by scrolling the sash (visible when mouse goes over the area between the parts). Also note actions in the upper-right corner of the form - this is the form tool bar.

To create the master block you need to do extend MasterDetailPage which look this:

In createMasterPart method of MessagesMasterBlock you can do something like this to create the composite using FormToolkit:

FormToolkit toolkit = managedForm.getToolkit();

Section messageTableSection = toolkit.createSection(parent, Section.DESCRIPTION | Section.TITLE_BAR);

messageTableSection.setText("Received Messages");

messageTableSection.setDescription("Description");

messageTableSection.marginWidth = 10;

messageTableSection.marginHeight = 5;

Composite tableComposite = toolkit.createComposite(messageTableSection, SWT.NONE);

// add components here

messageTableSection.setClient(tableComposite);

tableSection = new SectionPart(messageTableSection);

managedForm.addPart(tableSection);

Also you can create the toolbar via getting the toolbar from ManagedForm and adding the IAction onto that one:

ScrolledForm form = managedForm.getForm();

toolBarManager = form.getToolBarManager();

The above snippet is used inside createToolbarAction method. Also you can register you pages statically:

detailsPart.registerPage(Object.class, new DefaultDetailPart());

This will complete your MasterBlock, now we are left with details part.

And for details page you need to implement IDetailPage interface which look like this:

The details is more of editor and contains the method to that like commit, isdirty, isStale, setInput these are all trivial. The main method here selection change, it is called whenever there’s a selection change in the Master part. You are having ISelection instance and can retrieve the Master object.

In the createContents method you’ll something like we did in createMasterPart method above.

Now we go through some of the problems and their solutions:

Q:  Dynamically choosing the detail pages based on the Selection?
You have to implement the IDetailsPageProvider having two methods, one which returns the page key for the provided object
Object getPageKey(Object object);
where parameter is selected object and the other one returns the instance of IDetailPage given the key returned by getPageKey
IDetailsPage getPage(Object key);



Q: Scroll bar is missing/not coming on overflow in details part/composite?
The problem here is not with master detail neither you have to change anything on sashform, all you have to do is set the hint height e.g.
Composite composite = new Composite(parent, SWT.BORDER);
GridLayout layout = new GridLayout(1, false);
composite.setLayout(layout);
setupViewer(composite);
GridData gridData = new GridData(SWT.FILL, SWT.FILL, true, true);
gridData.heightHint = 200;
tableViewer.getTable().setLayoutData(gridData);

The above solution will work for detail page also if message is usage as in the screenshot shown below.

The figure above is showing scroll bars in master and detail section

Sashform.setWeights (int[]) will do the job for you e.g. sashForm.setWeights(new Int[]{1,4});