Matlab’s button uicontrols (pushbutton and togglebutton) are basically wrappers for a Java Swing JButton object.
This will be the first in a series of posts showing how Matlab uicontrols can be customized in ways that you may never have thought possible.
Probably the simplest undocumented customization is the control’s acceptance of HTML and CSS Strings:
tooltip = '<html>HTML-aware<br><b>tooltips</b><br><i>supported'; labelTop= '<HTML><center><FONT color="red">Hello</Font> <b>world</b>'; labelBot=['<div style="font-family:impact;color:green"><i>What a</i>'... ' <Font color="blue" face="Comic Sans MS">nice day!']; set(hButton, 'tooltip',tooltip, 'string',[labelTop '<br>' labelBot]);
Button with HTML label and tooltip
For more powerful customization, we need to access the control’s underlying JList object. We do this by using my FindJObj submission on the File Exchange:
>> jButton = java(findjobj(hButton))
jButton =
com.mathworks.hg.peer.PushButtonPeer$1[,0,0,...]
Now that we have the jButton Java object reference, we can use get and set just like any Matlab handle. To see the list of all available properties, methods and callbacks, we can use my UIINSPECT submission on the File Exchange, or use Matlab’s built-in methodsview function.
This post is too short to present all the numerous ways in which the control can be customized with the Java properties and methods. Let’s list some of the more interesting properties:
- Border – specified the border frame around the button, which is responsible for its 3D appearance. It can be modified to anything from a simple colored borderline to a recurring icon-pattern, as shown here. If set to [] then the button achieves a flat appearance, which can be useful for displaying click-able labels. For example, the blog hyperlink at the bottom of the FindJObj window is a simple button with no border, an HTML label and a callback that opens this blog webpage using the built-in web function:
Button appearing as a hyperlink label
- Cursor – this can be used to set a control-specific cursor. For example, in the hyperlink button above, the cursor was set to: java.awt.Cursor(java.awt.Cursor.HAND_CURSOR). In another post I’ll show how to set a custom cursor, like the following Matlab icon:
Custom cursor
- DisplayedMnemonicIndex – (default=-1) indicates the character position within the text label where the Mnemonic (i.e, keyboard shortcut) should be displayed. Associated property Mnemonic (default=0) indicates the ASCII code of the mnemonic. In the following case, DisplayedMnemonicIndex=3 (remember that Java indices start at 0) and Mnemonic=73 (=’r'):
Button With mnemonic
- Margin, VerticalAlignment, HorizontalAlignment – these properties enable setting the label contents with respect to its borders. For example:
Top-left with 8-pixel top margin
- Icon, DisabledIcon, DisabledSelectedIcon, PressedIcon, RolloverIcon, RolloverSelectedIcon, SelectedIcon – these icons may be set to present a different appearance depending on component state. Associated property IconTextGap (default=4) determines the gap in pixels between the icon and the button text label. Associated properties HorizontalTextPosition and VerticalTextPosition specify the label text’s alignment relative to the label icon. These two properties accept the same SwingConstants values as HorizontalAlignment and VerticalAlignment above. For example, let’s display an icon to the right and upward of the text:
myIcon = fullfile(matlabroot,'/toolbox/matlab/icons/warning.gif'); jButton.setIcon(javax.swing.ImageIcon(myIcon)); jButton.setHorizontalTextPosition(javax.swing.SwingConstants.LEFT); jButton.setVerticalTextPosition(javax.swing.SwingConstants.BOTTOM);
Button with text and icon
- MultiClickThreshhold – (default=0) sets the number of milliseconds between subsequent processed user mouse clicks on the button. Any clicks that occur within the specified number (e.g., fast double-clicks) will be considered by the component as only a single click. The default value of 0 means that all clicks will be processed separately, which is often undesirable in GUI applications. Remember that the value is in milliseconds, not seconds.
- FlyOverAppearance – boolean flag (default=false); if set, the button appearance is changed to a flat (2D) appearance with a special 3D border effect displayed on mouse hover. This appearance is useful for toolbar buttons, and is an extension by Matlab’s button implementation (does not exist in the standard Swing class).
There are quite a few other useful properties, methods (for example, jButton.doClick() to programmatically click a button) and even some 30 callbacks, detailed in a separate post. The list above is by no way comprehensive – I hope it whet your appetites for exploration using FindJObj and UIINSPECT – it’s a fun ride and the GUI rewards are worth the effort!
Please let me know of any nice customizations in your Matlab applications. Leave a comment below or drop me an email.
