Undocumented button highlighting

One of my consulting clients approached me yesterday with a mystery: In his GUIDE-generated GUI, one of the buttons had a bluish tint, and no obvious property seemed to control this or to differentiate it from its sibling controls. Here’s a parred-down version of his GUI:

So while it was very nice to have a highlighted button in this manner, the fact that he did not know why it happened and how to control it was a bit unsettling. Which is where I came in, and it turns out that the solution to the mystery is simple and very easy to use. My client now happily switches button highlights on and off, just for the fun of it…
Before I describe the solution (spoiler alert: scroll down), I think it is instructional to understand the unsuccessful attempts, so here goes:

Various alternatives

Our first attempts to understand the situation were to modify the button control’s obvious suspect properties:

• String – the button had an HTML label ^[1]. One might presume that this caused the highlighting tint, perhaps an HTML image ^[2] painted the background? HTML labels for uicontrols ^[3] are really cool so it would be a pity to have to stop using them. Fortunately, replacing the HTML label with a simple string had no effect, so we can keep using HTML labels safely and freely. But we’re still left with our mystery, so moving on…
• Border – yet another suspect: the control’s border ^[4] and fly-over appearance feature ^[5] affects its appearance. This also proved a dead-end: all the buttons had simple default borders, nothing special about the highlighted one.
• Background – another dead end: while we could indeed set a non-standard button color, this property does not enable the tinting effect (lighter half at top, darker at bottom). Needless to say, in our case this property had the default (gray) value.
• Selected – this property does not really highlight the control, but rather draws a thick dashed border around it (see below).
• focus – by calling uicontrol(hButton) we can have Matlab set the focus on the button. The Operating System then automatically kicks in to add some shading effect. This finally looked close, but again, it was just not quite right.

Solution of the highlighting mystery

So maybe GUIDE attached some funky property value to the control? Let’s investigate. Remembering that the GUIDE-generated *.fig file is simply a standard MAT file ^[6] with a different extension, we can load it into the Matlab workspace and dissect it. Drilling down the GUI hierarchy we find:

>> data = load('myGUI.fig', '-mat')
data =
    hgS_070000: [1x1 struct]
>> d.hgS_070000.children(9).properties
ans =
              Units: 'pixels'
           Callback: [function_handle]
           Position: [20 20 60 20]
             String: 'Yes'
              Value: 1
    ApplicationData: [1x1 struct]
>> d.hgS_070000.children(10).properties
ans =
              Units: 'pixels'
           Callback: [function_handle]
           Position: [100 20 60 20]
             String: 'No'
    ApplicationData: [1x1 struct]

When we compare the information that GUIDE stored for the two buttons we see that it stored an extra Value property for the ‘Yes’ button, and used the default HG value ^[7] for the ‘No’ button. Let’s compare the property values in run-time (I’m using my objDiff utility ^[8] for this):

>> hButton1 = findall(gcf, 'String', 'Yes');
>> hButton2 = findall(gcf, 'String', 'No');
>> props1 = get(hButton1);
>> props2 = get(hButton2);
>> objdiff(props1, props2)
ans =
      Extent: {[0 0 24 19]  [0 0 17 19]}
    Position: {[20 20 60 20]  [100 20 60 20]}
      String: {'Yes'  'No'}
       Value: {[1]  [0]}

This pretty much nails it: pushbutton highlighting is controlled via the Value property. According to the official documentation ^[9], the Value property has no meaning for push-buttons, only for other uicontrol styles. This is obviously not so:

set(hButton, 'Value', 1);   % Turn button highlighting on
set(hButton, 'Value', 0);   % Turn button highlighting off (can use any value ~=1)

Under the hood

Under the hood, updating the Value property sets the pushbutton’s underlying Java control ^[10]‘s Selected property to true. Note that the Java Selected property is entirely unrelated to Matlab’s Selected property (which has no underlying Java counterpart). I do not understand the design decision that let to this, but since it has been like this for many years I see little chance that it will be changed in the near future.
In any case, the Java Selected property indeed has a visual effect, but the actual effect depends on the current operating system and Look-&-Feel (LnF). You can play around with the LnF ^[11] to achieve various other alternative highlighting effects, or customize one of your own.

Advanced Matlab GUI course – London 12-14 March, 2014

If this topic has piqued your interest, consider joining my Advanced Matlab GUI course ^[12] in London on 12-14 March, 2014. In this course/seminar I will explore numerous other ways by which we can customize Matlab’s GUI and graphics in ways that you never knew were even possible! This is a unique opportunity to take your Matlab skills to a higher level within just a few days. This training is not offered anywhere else.