Revision as of 11:45, 14 October 2010

Menu and Toolbar Rendering

We need to work through the many scenarios we have for menus and toolbars, and make sure that we cover off all of them (or decide against them) to support both our e4 menus story and the compatibility menus/actions story.

e4 RCP Menus

In e4 Menus, they can be defined in 3 places in the model, and have contributions added to them.  MMenu supports 4 types, MHandledMenuItem, MDirectMenuItem, MMenuSeparator, and sub MMenus.

1. An MMenu can be defined on an MWindow.  This will be rendered as an SWT Menu bar.
   
2. An MMenu with tag "ViewMenu" can be added to an MPart.  This is rendered as an SWT Menu and needs to be shown when the view dropdown menu is provided.  We also tag it with ContributionsAnalyzer.MC_MENU when in a CompatibilityView
   
3. an MPopupMenu can be added to an MPart.  This is rendered as an SWT Menu.  The EMenuService take a Control and the MPopupMenu and associates the SWT Menu with the control after it's rendered.
   

We then support MMenuContributions.  They were processed and added to the model on SWT.Show events, and then removed in an asyncExec(*) after the SWT.Hide.

e4 RCP Toolbars

In e4 Toolbars, they can be added to the MTrimBars of an MTrimmedWindow.  They can also be added to an MPart, although in the editor case they're still ignored.

MToolBars support MHandledToolItems, MDirectToolItems, MToolBarSeparators, and MToolControls.

MToolBars support additions through MToolBarContributions.  They're applied in the ToolBarRenderer.processContents(*) after the regular children have been processed.  The visibility of the contributions is controled by a RunAndTrack on its visibleWhen.

The view toolbars are also managed by some interaction by the StackRenderer which generates an MRenderedToolBar.

Compatibility Menus

For the compatibility layer, we support MRenderedMenu where we stick a MenuManager into the model as a transient object. This is usually done in the CompatibilityView as well, so the view IActionBars MenuManager (which was provided to the view when it was created) has a model element. The MenuServiceFilter would add MMenuContributions to it on an SWT.Show.

For compatibility layer popup menus, we create an MRenderedMenu to hold the MenuManager that was passed in through org.eclipse.ui.internal.PartSite.registerContextMenu(MenuManager, ISelectionProvider) with one child, an MPopupMenu that can be processed by the MenuServiceFilter.

We don't support the EditorMenuManager correctly, which in 3.x is a way for an editor to programmaticly add to the main menu bar.

Compatibility Toolbars

In the compatibility layer, the IActionBars ToolBarManager for view toolbars is added to an MRenderedToolBar as a transient object in the CompatibilityView code.  The RenderedToolBarRenderer won't process any children, but will add MToolBarContributions and maintain their visibility through a RunAndTrack.  The RenderedToolBarRenderer also contains code to add a ToolItem directly to the SWT ToolBar (outside of both the model and the ToolBarManager).

We don't support the editor IActionBars ToolBarManager, which talks to the CoolBarManager in 3.x and updates it post-e4-processing in 4.x

Improvements in e4 processing

Some stability of ordering and optimizations can be realized in the e4 processing of MMenus and MToolBars by refining the way contributions are handled.

1. MMenuContributions are added to the MMenu model once, instead of being continually added and removed by the MenuServiceFilter.  The added items have them visibility and their enabled state updated on the show of that menu only, avoiding generating RunAndTracks.
2. MToolBarContributions are added similar to #1.  Changing to one RunAndTrack per MTBC for visibility instead of one RunAndTrack per tool item will reduce the number of RATs in the system, and a timer to re-assess enabled state for all of the ToolItems.  Another option is to do both visibility and enabled state from the timer.

Compatibility Usecases

We have a number of usecases to support the compatility layer.  They fall into 2 categories.  Programmatic changes  and extension points.

Progamatically we update  the main menu, main coolbar, actionSets through the perspective API, view dropdown menu, view toolbar, editor menu (a sub-manager that wraps the main menu), editor toolbar (is provided as a single toolbar in the coolbar), a programmatic EditorActionBarContributor, and context menus registered through the part site.

For extensions, we have much more control about what we do with them and how we intepret them.  actionSets go into the main menu and main coolbar, viewActions into the view dropdown menu or view toolbar.  editorActions go into the main menu/main coolbar when an editor is visible. popupMenus/viewerContributions can target a specific registered context menu that's been tagged with the ID, and popupMenus/objectContributions are filtered and applied to all registered context menus.  org.eclipse.ui.menus allows commands to be placed in any of the above menus/toolbars.

Main Menu

When each WorkbenchWindow is created, the ActionBarAdvisor is run on an empty MenuManager and fills in the "skeleton" that all of the extensions can see.  Then org.eclipse.ui.menus/menuContributions are applied, followed by org.eclipse.ui.actionSets.  We control the lifecycle of this MenuManager, although it is exposed programmaticly through the SubMenuManager/EditorMenuManager available to editors through the IEditorActionBars.

In the compatibility layer, we then call org.eclipse.ui.internal.WorkbenchWindow.fill(MMenu, IMenuManager) to translate the IContributionItems to model:

• MenuManager -> MMenu
• CommandContributionItem -> MHandledMenuItem
• ActionContributionItem -> mostly MHandledMenuItems, some MDirectMenuItems
• group markers -> MMenuSeparator
• general IContributionItem -> MRenderedMenuItem.  This is passed to a RenderedMenuItemRenderer for some magic

The actionSets and editorActions are turned into MMenuContributions with appropriate visibleWhen, and applied currently by the MenuServiceFilter.  We don't currently deal well with EditorMenuManager changes that happen after the fact.

Main Toolbar

Similar to the Main Menu, we create the main CoolBarManager and run the ActionBarAdvisor.  Then menus/menuContributions are applied, followed by actionSets.  We control the lifecycle of this CoolBarManager