Last week I explained ^[1] how to customize Matlab’s menu items using some undocumented tricks that do not need Java. Today I will show how using just a tiny bit of Java magic powder we can add much more complex customizations to menu items. Menu customizations are explored in depth in section 4.6 of my book ^[2].

Accessing the underlying Java object

Matlab menus (uimenu) are basically simple wrappers for the much more powerful and flexible Java Swing JMenu and JMenuItem ^[3] on which they are based. Many important functionalities that are available in Java menus are missing from the Matlab uimenus.
Getting the Java reference for the figure window’s main menu is very easy:

jFrame = get(handle(hFig),'JavaFrame');
try
    % R2008a and later
    jMenuBar = jFrame.fHG1Client.getMenuBar;
catch
    % R2007b and earlier
    jMenuBar = jFrame.fFigureClient.getMenuBar;
end

Note that we have used the figure handle’s hidden JavaFrame property ^[4], accessed through the reference’s handle() wrapper, to prevent an annoying warning message.
There are many customizations that can only be done using the Java handle: setting icons, several dozen callback types, tooltips, background color, font, text alignment, and so on. etc. Interested readers may wish to get/set/inspect/methodsview/uiinspect ^[5] the jSave reference handle and/or to read the documentation for JMenuItem ^[6]. Some useful examples are provided below.

Dynamic menu behavior

As a first example of Java-based customization, let us add DHTML-like behavior to the menu, such that the menu items will automatically be displayed when the mouse hovers over the item, without waiting for a user mouse click. First, get the jMenuBar reference as described above. Now, set the MouseEnteredCallback to automatically simulate a user mouse click on each menu item using its doClick() method. Setting the callback should be done separately to each of the top-level menu components:

for menuIdx = 1 : jMenuBar.getComponentCount
    jMenu = jMenuBar.getComponent(menuIdx-1);
    hjMenu = handle(jMenu,'CallbackProperties');
    set(hjMenu,'MouseEnteredCallback','doClick(gcbo)');
end

Note that using this mechanism may be awkward if the top-level menu does not have a sub-menu but is rather a stand-alone menu item. For example, if the top-level menu-item “Help” is a stand-alone menu button (i.e., there are no help menu-items, just the single Help item), then moving the mouse over this item will trigger the help event, although the user did not actually click on the item. To prevent this behavior, we should modify the code snippet above to only work on those menu items that have sub-items.

Custom accelerator shortcut keys

As another example, Matlab automatically assigns a non-modifiable keyboard accelerator key modifier of , while JMenus allow any combination of Alt/Ctrl/Shift/Meta (depending on the platform). Let us modify the default File/Save accelerator key from ‘Ctrl-S’ to ‘Alt-Shift-S’ as an example. We need a reference for the “Save” menu item. Note that unlike regular Java components, menu items are retrieved using the getMenuComponent() method and not getComponent():

% File main menu is the first main menu item => index=0
jFileMenu = jMenuBar.getComponent(0);
% Save menu item is the 5th menu item (separators included)
jSave = jFileMenu.getMenuComponent(4); %Java indexes start with 0!
inspect(jSave) 	% just to be sure: label='Save' => good!
% Finally, set a new accelerator key for this menu item:
jAccelerator = javax.swing.KeyStroke.getKeyStroke('alt shift S');
jSave.setAccelerator(jAccelerator);

That is all there is to it – the label is modified automatically to reflect the new keyboard accelerator key. More info on setting different combinations of accelerator keys and modifiers can be found in the official Java documentation for KeyStroke ^[7].

% Simulate mouse clicks to force the File main-menu to open & close
jFileMenu.doClick; % open the File menu
jFileMenu.doClick; % close the menu
% Now the Save menu is accessible:
jSave = jFileMenu.getMenuComponent(4);

Tooltip and highlight

For some unknown reason, MathWorks did not include a tooltip property in its Matlab menu handle, contrary to all the other Matlab GUI components. So we must use the Java handle, specifically the ToolTipText property:

jSave.setToolTipText('modified menu item with tooltip');

Java menu items also contain a property called Armed, which is a logical value (default=false). When turned on, the menu item is highlighted just as when it is selected (see the Save As… menu item in the screenshot above). On a Windows system, this means a blue background:

jSave.setArmed(true);

When the item is actually selected and then de-selected, Armed reverts to a false (off) value. Alternating the Armed property value can achieve an effect of flashing the menu item.

Callbacks

In addition to the standard Swing control callbacks discussed in an earlier article ^[8], menu items possess several additional callbacks that are specific to menu items, including:

• ActionPerformedCallback – fired when the menu item is invoked
• StateChangedCallback – fired when the menu item is selected or deselected
• MenuDragMouseXXXCallback (XXX=Dragged/Entered/Exited/Released) – fired when the menu item is dragged, for the corresponding event
• MenuKeyXXXCallback (XXX=Pressed/Released/Typed) – fired when a keyboard click event occurs (the menu item’s accelerator was typed)

Using these callbacks, together with the 30-odd standard Swing callbacks, we can control our menu’s behavior to a much higher degree than possible using the standard Matlab handle.
Next week, I will conclude this mini-series with an article explaining how to customize menu item icons.

14 Comments To "Customizing menu items part 2"

#1 Comment By Attilio Funel On June 19, 2012 @ 03:39

 
myGUI = figure('Visible','on','Name','Urania alternativa DB Utility',...
                    'MenuBar','none', ...            %No menu bar 
                    'NumberTitle', 'off', ...
                    'Position',[360,500,450,285]);
set(myGUI,'CloseRequestFcn',@EditMenuExitFunction);
ChangeIcon(myGUI);
        
jFrame = get(handle(myGUI),'JavaFrame');
try
    jMenuBar = jFrame.fHG1Client.getMenuBar;
catch
end
             
editMenu = uimenu(myGUI,'Label','Edit');
jEditMenu = jMenuBar.getComponent(0);
hjMenu = handle(jEditMenu,'CallbackProperties');
set(hjMenu,'MouseEnteredCallback','doClick(gcbo)');
editMenuOpen = uimenu(editMenu, 'Label', 'Open DB', ..., 
                    'Accelerator', 'O',...
                    'Callback', @EditMenuOpenFunction);

#2 Comment By Attilio Funel On June 19, 2012 @ 06:10

#3 Comment By Yair Altman On June 19, 2012 @ 08:15

#4 Comment By Attilio Funel On June 20, 2012 @ 02:23

editMenu = uimenu(myGUI,'Label','Edit');
editMenuOpen = uimenu(editMenu, 'Label', 'Open DB', ..., 
                    'Accelerator', 'O',...
                    'Callback', @EditMenuOpenFunction);
drawnow;
editMenuSave = uimenu(editMenu, 'Label', 'Save DB', ...
                    'Accelerator', 'S', ...
                    'Callback', @EditMenuSaveFunction, ...
                    'Enable', 'off');

%Se ho acceduto come attiliosfunel abilito "Save"
if(strcmp(accessedUserName, 'attiliosfunel') == true)
    set(editMenuSave,'Enable','on');
end
drawnow;
editMenuClose = uimenu(editMenu, 'Label', 'Close DB', ...
                    'Callback', @EditMenuCloseFunction, ...
                    'Accelerator', 'C');
drawnow;
editMenuExit = uimenu(editMenu, 'Label', 'Exit', ...
                    'Accelerator', 'X', ...
                    'Callback', @EditMenuExitFunction);
drawnow;
pause(0.1);

%Handle della finestra
jFrame = get(handle(myGUI),'JavaFrame');
try
   jMenuBar = jFrame.fHG1Client.getMenuBar;
catch ERROR_GET_HANDLE_WINDOW
end
            
jEditMenu = jMenuBar.getComponent(0);
jEditMenu.getComponentCount

#5 Comment By Yair Altman On June 20, 2012 @ 02:29

#6 Comment By sebbo On December 4, 2012 @ 05:30

while true
    menu.doClick()
    pause(1);
end

#7 Comment By Roger Svensson On August 22, 2013 @ 09:01

javax.swing.MenuSelectionManager.defaultManager().clearSelectedPath();

#8 Comment By Stephan Heise On October 30, 2013 @ 05:18

#9 Comment By Yair Altman On October 30, 2013 @ 07:21

#10 Comment By Stephan Heise On November 7, 2013 @ 00:30

#11 Comment By Yair Altman On November 11, 2013 @ 03:47

#12 Comment By Thierry Dalon On November 28, 2013 @ 01:21

public void setAccelerator(KeyStroke keyStroke)
setAccelerator is not defined for JMenu. Use setMnemonic instead.
Overrides:
setAccelerator in class JMenuItem
Parameters:
keyStroke - the keystroke combination which will invoke the JMenuItem's actionlisteners without navigating the menu hierarchy
Throws:
Error - if invoked -- this method is not defined for JMenu. Use setMnemonic instead

#13 Comment By Yair Altman On November 28, 2013 @ 01:43

#14 Comment By Thierry Dalon On November 28, 2013 @ 04:15