• August 29 (full day) – Interactive Matlab GUI
• August 30 (full day) – Advanced Matlab GUI

The seminars are targeted at Matlab users who wish to improve their program’s usability and professional appearance. Basic familiarity with the Matlab environment and coding/programming is assumed. The courses will present a mix of both documented and undocumented aspects, which is not available anywhere else. The curriculum is listed below.
This is a unique opportunity to enhance your Matlab coding skills and improve your program’s usability in a couple of days.
If you are interested in either or both of these seminars, please Email me (altmany at gmail dot com).
I can also schedule a dedicated visit to your location, for onsite Matlab training customized to your organization’s specific needs. Additional information can be found on my Training page.
Around the time of the training, I will be traveling to various locations around Switzerland. If you wish to meet me in person to discuss how I could bring value to your project, then please email me (altmany at gmail):

• Geneva: Aug 22 – 27
• Bern: Aug 27 – 28
• Zürich: Aug 28 – 30
• Stuttgart: Aug 30 – 31
• Basel: Sep 1 – 3

 Email me

Interactive Matlab GUI – 29 August, 2017

1. Introduction to Matlab Graphical User Interfaces (GUI)
   • Design principles and best practices
   • Matlab GUI alternatives
   • Typical evolution of Matlab GUI developers
2. GUIDE – MATLAB’s GUI Design Editor
   • Using GUIDE to design a custom GUI
   • Available built-in MATLAB uicontrols
   • Customizing uicontrols
   • Important figure and uicontrol properties
   • GUIDE utility windows
   • The GUIDE-generated file-duo
3. Customizing GUI appearance and behavior
   • Programmatic GUI creation and control
   • GUIDE vs. m-programming
   • Attaching callback functionality to GUI components
   • Sharing data between GUI components
   • The handles data struct
   • Using handle visibility
   • Position, size and units
   • Formatting GUI using HTML
4. Uitable
   • Displaying data in a MATLAB GUI uitable
   • Controlling column data type
   • Customizing uitable appearance
   • Reading uitable data
   • Uitable callbacks
   • Additional customizations using Java
5. Matlab’s new App Designer and web-based GUI
   • App Designer environment, widgets and code
   • The web-based future of Matlab GUI and assumed roadmap
   • App Designer vs. GUIDE – pros and cons comparison
6. Performance and interactivity considerations
   • Speeding up the initial GUI generation
   • Improving GUI responsiveness
   • Actual vs. perceived performance
   • Continuous interface feedback
   • Avoiding common performance pitfalls
   • Tradeoff considerations

At the end of this seminar, you will have learned how to:

• apply GUI design principles in Matlab
• create simple Matlab GUIs
• manipulate and customize graphs, images and GUI components
• display Matlab data in a variety of GUI manners, including data tables
• decide between using GUIDE, App Designer and/or programmatic GUI
• understand tradeoffs in design and run-time performance
• comprehend performance implications, to improve GUI speed and responsiveness

Advanced Matlab GUI – 30 August, 2017

1. Advanced topics in Matlab GUI
   • GUI callback interrupts and re-entrancy
   • GUI units and resizing
   • Advanced HTML formatting
   • Using hidden (undocumented) properties
   • Listening to action and property-change events
   • Uitab, uitree, uiundo and other uitools
2. Customizing the figure window
   • Creating and customizing the figure’s main menu
   • Creating and using context menus
   • Creating and customizing figure toolbars
3. Using Java with Matlab GUI
   • Matlab and Java Swing
   • Integrating Java controls in Matlab GUI
   • Handling Java events as Matlab callbacks
   • Integrating built-in Matlab controls/widgets
   • Integrating JIDE’s advanced features and professional controls
   • Integrating 3rd-party Java components: charts/graphs/widgets/reports
4. Advanced Matlab-Java GUI
   • Customizing standard Matlab uicontrols
   • Figure-level customization (maximize/minimize, disable etc.)
   • Containers and position – Matlab vs. Java
   • Compatibility aspects and trade-offs
   • Safe programming with Java in Matlab
   • Java’s EDT and timing considerations
   • Deployment (compiler) aspects

At the end of this seminar, you will have learned how to:

• customize the figure toolbar and main menu
• use HTML to format GUI appearance
• integrate Java controls in Matlab GUI
• customize your Matlab GUI to a degree that you never knew was possible
• create a modern-looking professional GUI in Matlab

The post Matlab GUI training seminars – Zurich, 29-30 August 2017 appeared first on Undocumented Matlab.

The MLAPP file format

Apparently, *.mlapp files are simply ZIP files in disguise (note: not MAT files as for *.fig files). A typical MLAPP’s zipped contents contains the following files (note that this might be a bit different on different Matlab releases):

• [Content_Types].xml – this seems to be application-independent:

• _rels/.rels – also application-independent:

• metadata/coreProperties.xml – contains the timestamp of figure creation and last update:

  
  
     2016-08-01T18:20:26Z
     2016-08-01T18:20:27Z
  
  

• metadata/mwcoreProperties.xml – contains information on the generating Matlab release:

  
  
     application/vnd.mathworks.matlab.app
     MATLAB App
     R2016a
  
  

• metadata/mwcorePropertiesExtension.xml – more information about the generating Matlab release. Note that the version number is not exactly the same as the main Matlab version number: here we have 9.0.0.328027 whereas the main Matlab version number is 9.0.0.341360. I do not know whether this is checked anywhere.

  
  
     9.0.0.328027
  
  

• appdesigner/appModel.mat – This is a simple MAT file that holds a single Matlab object called “appData” (of type appdesigner.internal.serialization.app.AppData) the information about the uifigure, similar in concept to the *.fig files generated by the old GUIDE:

  >> d = load('C:\Yair\App3\appdesigner\appModel.mat')
  Warning: Functionality not supported with figures created with the uifigure function. For more information,
  see Graphics Support in App Designer.
  (Type "warning off MATLAB:ui:uifigure:UnsupportedAppDesignerFunctionality" to suppress this warning.)
  d =
      appData: [1x1 appdesigner.internal.serialization.app.AppData]
  >> d.appData
  ans =
    AppData with properties:
        UIFigure: [1x1 Figure]
        CodeData: [1x1 appdesigner.internal.codegeneration.model.CodeData]
        Metadata: [1x1 appdesigner.internal.serialization.app.AppMetadata]
      ToolboxVer: '2016a'
  >> d.appData.CodeData
  ans =
    CodeData with properties:
      GeneratedClassName: 'App3'
               Callbacks: [0x0 appdesigner.internal.codegeneration.model.AppCallback]
              StartupFcn: [1x1 appdesigner.internal.codegeneration.model.AppCallback]
         EditableSection: [1x1 appdesigner.internal.codegeneration.model.CodeSection]
              ToolboxVer: '2016a'
  >> d.appData.Metadata
  ans =
    AppMetadata with properties:
      GroupHierarchy: {}
          ToolboxVer: '2016a'
  

• matlab/document.xml – this file contains a copy of the figure’s classdef code in plain-text XML:

I do not know why the code is duplicated, both in document.xml and (twice!) in appModel.mat. On the face of it, this does not seem to be a wise design decision.

Editing MLAPP files outside AppDesigner

We can presumably edit the app in an external editor as follow:

1. Open the *.mlapp file in your favorite zip viewer (e.g., winzip or winrar). You may need to rename/copy the file as *.zip.
2. Edit the contents of the contained matlab/document.xml file in your favorite text editor (Matlab’s editor for example)
3. Load appdesigner/appModel.mat into Matlab workspace.
4. Go to appData.CodeData.EditableSection.Code and update the cell array with the lines of your updated code (one cell element per user-code line).
5. Do the same with appData.CodeData.GeneratedCode (if existing), which holds the same data as appData.CodeData.EditableSection.Code but also including the AppDesigner-generated [non-editable] code.
6. Save the modified appData struct back into appdesigner/appModel.mat
7. Update the zip file (*.mlapp) with the updated appModel.mat and document.xml

In theory, it is enough to extract the classdef code and same it in a simple *.m file, but then you would not be able to continue using AppDesigner to make layout modifications, and you would need to make all the changes manually in the m-file. If you wish to continue using AppDesigner after you modified the code, then you need to save it back into the *.mlapp file as explained above.
If you think this is not worth all the effort, then you’re probably right. But you must admit that it’s a bit fun to poke around…
One day maybe I’ll create wrapper utilities (mlapp2m and m2mlapp) that do all this automatically, in both directions. Or maybe one of my readers here will pick up the glove and do it sooner – are you up for the challenge?

Caveat Emptor

Note that the MLAPP file format is deeply undocumented and subject to change without prior notice in upcoming Matlab releases. In fact, MathWorker Chris Portal warns us that:

A word of caution for anyone that tries this undocumented/unsupported poking into their MLAPP file. Taking this approach will almost certainly guarantee your app to not load in one of the subsequent releases. Just something to consider in your off-roading expedition!

Then again, the same could have been said about the FIG and other binary file formats used by Matlab, which remained essentially the same for the past decade: Some internal field values may have changed but not the general format, and in any case the newer releases still accept files created with previous releases. For this reason, I speculate that future AppDesigners will accept MLAPP files created by older releases, possibly even hand-modified MLAPP files. Perhaps a CRC hash code of some sort will be expected, but I believe that any MLAPP that we modify today will still work in future releases. However, I could well be mistaken, so please be very careful with this knowledge. I trust that you can make up your own mind about whether it is worth the risk (and fun) or not.
AppDesigner is destined to gradually replace the aging GUIDE over the upcoming years. They currently coexist since AppDesigner (and its web-based uifigures) still does not contain all the functionality that GUIDE (and JFrame-based figures) provides (a few examples). I already posted a few short posts about AppDesigner (use the AppDesigner tag to list them), and today’s article is another in that series. Over the next few years I intend to publish more on AppDesigner and its associated new GUI framework (uifigures).

Zurich visit, 21-31 Aug 2016

I will be traveling to Zürich for a business trip between August 21-31. If you are in the Zürich area and wish to meet me to discuss how I could bring value to your work, then please email me (altmany at gmail).

The post AppDesigner's mlapp file format appeared first on Undocumented Matlab.

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. One might presume that this caused the highlighting tint, perhaps an HTML image painted the background? HTML labels for uicontrols 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 and fly-over appearance feature 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 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 for the ‘No’ button. Let’s compare the property values in run-time (I’m using my objDiff utility 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, 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‘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 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 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.

The post Undocumented button highlighting appeared first on Undocumented Matlab.

The clf function does not clear javacomponents (1-MNELS1)

The clf function clears the specified figure window (or the current figure [gcf] if no figure handle was specified as input) of any axes and GUI controls. At least, that what it is supposed to do and what it did pretty well until R2012a (Matlab 7.14). Apparently, in R2012b (Matlab 8.0) something broke and controls that are added to the figure window using the javacomponent function are no longer cleared by clf – all the regular Matlab axes and uicontrols are deleted, but not the Java controls.

figure;
[jButton, hContainer] = javacomponent(javax.swing.JButton('Click'), [], gcf);
drawnow;
clf  % bug - clf does not delete the jButton/hContainer component from the figure

There are several possible workarounds:

1. Keep the handles of all the relevant Java components, and then delete them directly:

   delete(hContainer)

2. Use findobj to delete all components, rather than the clf function (we use setdiff to prevent deletion of the figure window itself):

   delete(setdiff(findobj(gcf),gcf))

Note that this bug does not occur when using HG2. However, for users who use the still-standard HG1, this bug is still unfixed as of Matlab R2013b Pre-release (which is now available for download for subscribed users).

GUIDE is unusable with dbstop if error (1-MH5KVI)

In R2013a (Matlab 8.1) I encounter a recurring error when attempting to inspect properties of objects in GUIDE, when “dbstop if error” is turned on.
The error happens when I have “dbstop if error” enabled. This is an enormously helpful debugging tool, so I normally have it turned on in my startup.m file. But in R2013a, if I try to inspect an object’s properties in GUIDE, I see a problem. Matlab hits the breakpoint in %matlabroot%/toolbox/matlab/codetools/+internal/+matlab/+inspector/SceneViewerListener.m line 99 due to the fact that isvalid() is not defined for the object, and the inspector window remains blank.
How to reproduce:

• run “dbstop if error” in the Matlab command window
• open a *.fig file in the Matlab command window (e.g., “guide myApplication.fig“)
• right-click and inspect the properties for an axes (for example)
• wait for the breakpoint to occur – “K>>” in the command window; the Editor stops (green arrow) in SceneViewerListener.m line 99
• an empty inspector window is displayed

Analysis:
Because SceneViewerListener is called from Java, not Matlab, the error is thrown as an exception that is trapped by the Java code and therefore does not appear to the user unless “dbstop if error” is on. Here is the full stack trace at the point of error (see this post regarding how to generate the Java stack dump):

K>> dbstack
> In SceneViewerListener>SceneViewerListener.isBeingDeleted at 99
K>> st = java.lang.Thread.currentThread.getStackTrace; for idx = 2 : length(st), disp(st(idx)); end
com.mathworks.jmi.NativeMatlab.SendMatlabMessage(Native Method)
com.mathworks.jmi.NativeMatlab.sendMatlabMessage(NativeMatlab.java:219)
com.mathworks.jmi.MatlabLooper.sendMatlabMessage(MatlabLooper.java:120)
com.mathworks.jmi.Matlab.mtFeval(Matlab.java:1540)
com.mathworks.mlwidgets.inspector.JidePropertyViewTable.isBeingDeleted(JidePropertyViewTable.java:154)
com.mathworks.mlwidgets.inspector.JidePropertyViewTable.filterOutInvalidObjects(JidePropertyViewTable.java:170)
com.mathworks.mlwidgets.inspector.JidePropertyViewTable.setObjects_MatlabThread(JidePropertyViewTable.java:187)
com.mathworks.mlwidgets.inspector.PropertyView.setObject_MatlabThread(PropertyView.java:655)
com.mathworks.mlwidgets.inspector.PropertyView.setObject_AnyThread(PropertyView.java:591)
com.mathworks.mlwidgets.inspector.PropertyView.access$1300(PropertyView.java:37)
com.mathworks.mlwidgets.inspector.PropertyView$RegistryHandler.itemStateChanged(PropertyView.java:698)
java.awt.AWTEventMulticaster.itemStateChanged(Unknown Source)
com.mathworks.services.ObjectRegistry.fireItemEvent(ObjectRegistry.java:763)
com.mathworks.services.ObjectRegistry.setSelected(ObjectRegistry.java:700)
com.mathworks.services.ObjectRegistry.setSelected(ObjectRegistry.java:617)
com.mathworks.mde.inspector.Inspector.setSelected(Inspector.java:584)
com.mathworks.mde.inspector.Inspector.inspectObjectArray(Inspector.java:569)
com.mathworks.mde.inspector.Inspector.inspectObjectArray(Inspector.java:520)
com.mathworks.mde.inspector.Inspector$11.run(Inspector.java:478)
com.mathworks.jmi.NativeMatlab.dispatchMTRequests(NativeMatlab.java:347)

Workaround:
replace the existing code of SceneViewerListener.m:

>> edit internal.matlab.inspector.SceneViewerListener
...
if ~isvalid(selectedObject)
    beingDeleted = true;
elseif isprop(selectedObject,'BeingDeleted') && strcmp('on',selectedObject.BeingDeleted)
    beingDeleted = true;
elseif ~isempty(ancestor(selectedObject,'figure')) && strcmp('on',get(ancestor(selectedObject,'figure'),'BeingDeleted'))
    beingDeleted = true;
else
    beingDeleted = false;
end

with the following (changed lines are highlighted):

if any(~isobject(selectedObject))
    beingDeleted = false;
elseif ~isValid
    beingDeleted = true;
elseif isprop(selectedObject,'BeingDeleted') && strcmp('on',selectedObject.BeingDeleted)
    beingDeleted = true;
elseif ~isempty(ancestor(selectedObject,'figure')) && strcmp('on',get(ancestor(selectedObject,'figure'),'BeingDeleted'))
    beingDeleted = true;
else
    beingDeleted = false;
end

It looks like this bug was apparently fixed in the R2013b Pre-release without needing to modify SceneViewerListener. But if you still encounter this problem you now know what to do.
I have reported another GUIDE-related bug, but I do not have a workaround for this one: If you run the GUI from within GUIDE, and some uncaught error (exception) occurs, then from that moment onward you cannot save any modifications to the figure file in that session.
Do you know of any other undocumented bugs, preferably with workarounds? If so, please post them in a comment here.

The post A couple of internal Matlab bugs and workarounds appeared first on Undocumented Matlab.

Figure visibility

Java components can only be placed onscreen when their containing Matlab figure has been made visible. This means that calls to javacomponent cannot be placed at the GUIDE-created *_OpeningFcn() function, because that function is invoked before the figure window is made visible.
Of course, we can always force the figure to become visible by setting the figure’s Visible property to 'on' in this function, before calling our javacomponents. But IMHO, a better option would be to simply place the javacomponents in the corresponding GUIDE-created *_OutputFcn() function, which is invoked after the figure window is made visible.

Auto-hiding with parent container

Java components are not automatically hidden with their ancestor container panel. This is also the root cause of the failure of Java components to disappear when switching tabs in a uitab.
One simple workaround for this that I often use is to link the Visible properties of the javacomponent container and the parent container:

jButton = javax.swing.JButton('click me!');
[jhButton, hContainer] = javacomponent(jButton, [100,100,60,30], hParent);
setappdata(hParent, 'linked_props__', linkprop([hParent,hContainer],'Visible'));

This has indeed been fixed in R2010b. If you ask me, this should have been standard behavior of javacomponent since the very beginning…
Although there is no need for the workaround in R2010b onward, I usually keep the workaround because it doesn’t hurt and enables backward compatibility for users who may have an older Matlab release.

Possible parent container types

javacomponent accepts parent handles that are figures, toolbars, uipanels, or uicontainers (some of these are not documented as possible parents in some Matlab releases, but they are). Since R2008a, parents of type uisplittool and uitogglesplittool can also be used. Unfortunately, frames are not uicontainers and, therefore, cannot be used as javacomponent parents.
Note: Due to a bug in R2007a, javacomponents cannot be added to uicontainers, since javacomponent.m checks if isa(hParent,'uicontainer') (and similarly for 'uiflowcontainer', 'uigridcontainer'), instead of isa(hParent,'hg.uicontainer') (and similarly for the others). If we modify javacomponent.m accordingly (add “hg.” in lines 98-100), this bug will be fixed. Since R2007b, isa(…,'hg.uicontainer') is equivalent to isa(…,'uicontainer'), so this fix is unnecessary.

Input parameters

Unlike many other Matlab functions, javacomponent does not accept optional parameter-value (P-V) pairs. If we want to customize the appearance of the Java component, it is better to create it , customize it, and only then to present it onscreen using javacomponent. If we first present the component and then customize it, there might be all sorts of undesirable flicker effects while the component is changing its properties.
One of the parameters that unfortunately cannot be customized before calling javacomponent is the component’s position onscreen. javacomponent only accepts a position vector in pixel units. To modify the component to use normalized units, we need to modify the container’s properties:

jButton = javax.swing.JButton('click me!');
[jhButton, hContainer] = javacomponent(jButton, [100,100,60,30], gcf);
set(hContainer, 'Units','norm');

Similarly, we can set the container’s UserData and ApplicationData only after the call to javacomponent.

Background color

The default background color of javacomponents is a slightly different shade of gray than the default uicontrol background color. Please refer to my recent article for a detailed discussion of this issue.

Vertical alignment

Java components are slightly mis-aligned vertically with combo-box (Style=’popup’) uicontrols, even when positioned using the same Y position. This is actually due to an apparent bug in Matlab’s implementation of the combo-box uicontrol, and not in the Java component’s: Apparently, the Matlab control does not obey its specified height and uses some other default height.
If we place javacomponents side-by-side with a regular Matlab popup uicontrols and give them all the same Y position, we can see this mis-alignment. It is only a few pixels, but the effect is visible and disturbing. To fix it, we need to add a small offset to the javacomponent‘s container’s Position property to make both the initial Y position slightly lower, and the height value slightly higher than the values for the corresponding Matlab combo-box control.

Callbacks

Unlike Matlab uicontrol callbacks, Java callbacks are activated even when the affected value does not change. Therefore, setting a value in the component’s callback could well cause an infinite loop of invoked callbacks.
Matlab programmers often use the practice of modifying component value within the callback function, as a means of fixing user-entered values to be within a certain data range, or in order to format the displayed value. This is relatively harmless in Matlab (if done correctly) since updating a Matlab uicontrol‘s value to the current value does not retrigger the callback. But since this is not the case with Java callbacks, users should beware not to use the same practice there. In cases where this cannot be avoided, users should at least implement some sort of callback re-entrancy prevention logic.

EDT

Java components typically need to use the independent Java Event processing Thread (EDT). EDT is very important for Matlab GUI, as explained in this article. Failure to use EDT properly in Matlab can lead to unexpected GUI behavior and even Matlab hangs or crashes.
If the javacomponent function is called in a very specific syntax format where the first input arg is a string (the name of the Java class to be created), then the newly-created component is placed on the EDT. However, this is not the normal manner in which javacomponent is used: A much more typical use-case is where javacomponent is passed a reference handle to a previously-created Java component. In such cases, it is the user’s responsibility to place the component on the EDT. Until R2008a this should be done using the awtcreate function; since R2008b, we can use the much simpler javaObjectEDT function (javaObjectEDT actually existed since R2008a, but was buggy on that release so I suggest using it only starting in R2008b; it became documented starting in R2009a). In fact, modern javacomponent saves us the trouble, by automatically using javaObjectEDT to auto-delegate the component onto the EDT, even if we happen to have created it on the MT.
The paragraph above may lead us to believe that we only need to worry about EDT in R2008a and earlier. Unfortunately, this is not the case. Modern GUI requires using many sub-components, that are attached to their main component (e.g., CellRenderers and CellEditors). javacomponent only bothers to place the main component on the EDT – not any of the sub-components. We need to handle these separately. Liberally auto-delegating components to the EDT seems like a safe and painless habit to have.

The post Common javacomponent problems appeared first on Undocumented Matlab.

handle2struct

Under the hood, hgsave uses the semi-documented built-in handle2struct function to convert the figure handle into a Matlab struct that is then stored with a simple save (the same function that saves MAT files) function call.
The fact that handle2struct is semi-documented means that the function is explained in a help comment (which can be seen via the help command), that is nonetheless not part of the official doc sections. It is an unsupported feature originally intended only for internal Matlab use (which of course doesn’t mean we can’t use it).
handle2struct merits a dedicated mention, since I can envision several use-cases for storing only a specific GUI handle (for example, a uipanel, a specific graph, or a set of GUI controls’ state). In this case, all we need to do is to call handle2struct with the requested parent handle, then save the returned structure. So simple, so powerful. handle2struct automatically returns all the non-default property information, recursively in all the handle’s children.
Note that features that are not properties of displayed handles (camera position, 3D rotation/pan/zoom states, annotations, axes-linking etc.) are not processed by handle2struct. For storing the states of these features, you need to use some specific handling – see the code within %matlabroot%\toolbox\matlab\graphics\private\hgsaveStructDbl.m for details. Basically, hgsaveStructDbl.m reads the state of all these features and temporarily stores them in the base handle’s ApplicationData property; handle2struct then reads them as any other regular handle property data, and then hgsaveStructDbl.m clears the temporary data from the handle’s ApplicationData. We can use the same trick for any other application state, of course.

struct2handle

handle2struct has a reverse function – the semi-documented struct2handle. I use it for creating dynamic preference panels: As in Matlab’s Preferences window, I have a list of preference topics and a set of corresponding options panels. In my case, it was easy to design each panel as a separate FIG file using GUIDE. In run-time, I simply load the relevant panel from its FIG file as described above, and place it onscreen in a dedicated uipanel using struct2handle. This enables very easy maintenance of preference panels, without sacrificing any functionality.

Matlab 8: Boldly going where no FIG has gone before…

Remember my post earlier this year about the new HG2 mechanism? I speculated that when MathWorks decides to release HG2, it will define this as a major Matlab release and label it Matlab 8.0.
The source code in hgsave.m appears to confirm my speculation. Here is the relevant code section (slightly edited for clarity), which speaks for itself:

% Decide which save code path to use
if ~feature('HGUsingMatlabClasses')   % <== existing HG
    % Warn if user passed in 'all' flag
    if SaveAll
        warning( 'MATLAB:hgsave:DeprecatedOption', ...
            'The ''all'' option to hgsave will be removed in a future release.');
    end
    hgS = hgsaveStructDbl(h, SaveAll);
    SaveVer = '070000';
    SaveOldFig = true;
else   % <== HG2
    % Warn if user passed in 'all' flag
    if SaveAll
        warning( 'MATLAB:hgsave:DeprecatedOption', ...
            'The ''all'' option to hgsave has been removed.');
    end
    if SaveOldFig
        hgS = hgsaveStructClass(h);
        SaveVer = '080000';
    else
        hgO = hgsaveObject(h);
        SaveVer = '080000';
    end
end
% Revision encoded as 2 digits for major revision,
% 2 digits for minor revision, and 2 digits for
% patch revision.  This is the minimum revision
% required to fully support the file format.
% e.g. 070000 means 7.0.0

As can be seen, when Matlab starts using HG2 (perhaps in 2011?), the top-level structure node will be called "hgS_080000", indicating Matlab 8.0. QED.
As a side-note, note that in HG2/Matlab8, although the comment about using 'all' indicates that it has been removed, in practice it is still accepted (although not being used). This will enable your code to be backward-compatible whenever HG2 launches, and future-compatible today.
Have you used handle2struct or struct2handle? If so, please share your experience in a comment.
Let the upcoming 2011 be a year filled with revelations, announcements and fulfillment! Happy New Year everybody!

The post handle2struct, struct2handle & Matlab 8.0 appeared first on Undocumented Matlab.

uicontainer

Matlab’s uicontainer family (uicontainer, uiflowcontainer and uigridcontainer) consists of container objects that enable customizable layout management of contained components. Uicontainers can contain any Matlab component that may have a uipanel handle as a Parent property. This includes uicontrols, plot axes etc., as well as other uicontainers.
The basic uicontainer object appears to be little more than a transparent container for contained objects. It can be used interchangeably with uipanel, which appears to be a specialized type of a uicontainer. Indeed, as MathWorks notes:
The UICONTAINER function is undocumented, and is not intended for direct use. The UIPANEL function should be used instead, as it provides more functionality.
In some cases, Matlab itself uses uicontainer instead of uipanel: for example, ActiveX controls are enclosed within transparent uicontrol objects when added to a figure:

>> [hActivex,hContainer] = actxcontrol('OWC11.Spreadsheet.11');
>> get(hContainer,'Type')
ans =
uicontainer

uicontainer objects are not very customizable. For example, unlike uipanels, uicontainers have no titles or borders. We would therefore usually prefer to use uipanels, as Mathworks suggested above. An exception to this rule is a case where we need to derive our own customized container class. An example of this is found in %matlabroot%/toolbox/matlab/uitools/@uitools/@uitab/schema.m, which derives uicontainer to create a uitab container (which will be described in a future article).
Relatives of uicontainer are more useful in general: uiflowcontainers and uigridcontainers act similarly to Java’s layout managers – specifically, FlowLayout and GridLayout. I expect to see additional layout managers incarnated within Matlab uicontainers in future Matlab versions (perhaps in the R2010b pre-release that came out today – I can’t wait to see…).

uiflowcontainer

uiflowcontainer is a uicontainer that enables adding uicontrols to the container without specifying an exact position as would be required for uicontainer or uipanel (actually, positions may be specified, but they are simply ignored).
By default, objects are added from the top-left corner, depending on the uiflowcontainer‘s available space and dimensions: if width > height then rightward, otherwise downward. If the container’s dimensions change, for example by resizing the figure window, then the container’s components will automatically be resized accordingly:

hc = uiflowcontainer('Units','norm','Position',[.1,.1,.8,.8]);
h1 = uicontrol('string','1','parent',hc);
h2 = uicontrol('string','2','parent',hc);
h3 = uicontrol('string','3','parent',hc);

set(hc,'FlowDirection','BottomUp')
set(hc,'FlowDirection','RightToLeft')

set(h1, 'HeightLimits',[10,20], 'WidthLimits',[30,30])
set(h2, 'HeightLimits',[50,50])
set(h3, 'HeightLimits',[2,inf])   % =default value

set(h2, 'WidthLimits',[150,150])
set(h3, 'HeightLimits',[50,50])  % resize figure to see effect

uigridcontainer

uigridcontainer is similar to uiflowcontainer in its specialization of the layout: in this case, the container is divided into a transparent grid of N-by-M cells (1×1 by default), each of which can contain its own component:

hc = uigridcontainer('Units','norm','Position',[.1,.1,.8,.8]);
set(hc, 'GridSize',[2,3]);  % default GridSize is [1,1]
h1 = uicontrol('string','1','parent',hc);
h2 = uicontrol('string','2','parent',hc);
h3 = uicontrol('string','3','parent',hc);
h4 = axes('parent',hc); x = -4:.1:4; plot(h4,x,sin(x));
set(h4,'YTickLabel',[],'XTickLabel',[]);

set(hc, 'HorizontalWeight',[6,3,1], 'VerticalWeight',[0.2,0.5])
delete([h2,h3]);  % only h1,h4 remain
set(hc,'EliminateEmptySpace','on')

Other layout alternatives

Brad Phelan of XTargets has created Matlab equivalents of Java’s BorderLayout and SpringLayout. The advantage of using Brad’s layout managers is that they appear to have full Matlab interoperability, including the ability to add Matlab components, unlike Java’s layout managers.
A File Exchange contributor named Jason has added a GridBagLayout implementation, mimicking Java’s well-known GridBagLayout.
Additional and more flexible layout managers are available in Java (one of my favorites is JGoodies Forms, which is pre-bundled with Matlab). Just remember the limitation that no Matlab component (such as GUI controls or plot axes) can be added to Java containers. Therefore, feel free to use these Java containers as long as their contained GUI is limited to Java components (JButton, JComboBox etc.).

Other uitools

Today’s article about uicontainer and its relatives was the first of several posts that will describe undocumented functions that reside in the %matlabroot%/toolbox/matlab/uitools folder. Feel free to look within this folder for other interesting undocumented functions. Most of these functions are semi-documented, meaning that they have a usable help-section hidden within the m-file (type “edit uicontainer.m” for example). Many have existed more-or-less unchanged for many releases. Note that there is no guarantee that they will remain in future releases. When using unsupported functionality, always code defensively.

The post Matlab layout managers: uicontainer and relatives appeared first on Undocumented Matlab.

>> h = guide
h =
Layout Document [untitled]
>> h.getClass
ans =
class com.mathworks.toolbox.matlab.guide.LayoutEditor

This return handle can be used to access GUIDE components and functionality. We can start by inspecting the interesting GUIDE layout hierarchy using my FindJObj utility, and the associated properties and method using my UIInspect utility:

>> h.findjobj;
>> h.uiinspect;

>> findjobj(h.getFrame);
>> findjobj(h.getTopLevelWindow);

We see that the Layout Editor contains, in addition to the expected LayoutArea and two MWScrollbars, several objects that relate to a ruler. These rulers can be activated via the GUIDE menu (Tools / Grid and Rulers), or via the Matlab Command Prompt as described below:
Looking at the ruler properties in FindJObj or UIInspect, we can see a settable boolean property called “RulerState”. If we turn it on we can see that a very handy pixels-ruler appears. Once we set this property, it remains in effect for every future GUIDE session:

h.getComponent(0).getComponent(4).setRulerState(true);  % Horizontal
h.getComponent(0).getComponent(5).setRulerState(true);  % Vertical

Note: RulerState actually controls a system preference (LayoutShowRulers, a boolean flag) that controls the visibility of both rulers, and persists across Matlab/GUIDE sessions. To change the visibility of only a single ruler for this GUIDE session only, or on old Matlab versions (e.g. Matlab 7.1 aka R14 SP3) that do not have the ‘RulerState’ property, use the hide()/show()/setVisible(flag) methods, or set the ‘Visible’ property:

% Equivalent ways to show horizontal ruler for this GUIDE session only
hRuler = h.getComponent(0).getComponent(4);  % =top horizontal ruler
set(hRuler, 'Visible','on');
hRuler.setVisible(true);  % or: hRuler.setVisible(1)
hRuler.show();

hRuler = h.getComponent(0).getComponent(4);  % =top horizontal ruler
set(hRuler, 'MinorInterval',5, 'MajorInterval',25);
set(hRuler, 'LabelInterval',50, 'LabelUnit',50);
set(hRuler, 'Margin',40, 'Length',260);

• LayoutShowRulers – boolean, controls display of both rulers
• LayoutShowGuides – boolean, controls display of blue guidelines
• LayoutShowGrid – boolean, controls display of gray gridlines
• LayoutGridWidth – integer, controls the size of the grid boxes
• LayoutSnapToGrid – boolean, controls snap-to-grid behavior
• LayoutActivate – boolean, controls ability to run (activate) unsaved figures without confirmation
• LayoutChangeDefaultCallback – boolean, ??? (I can see this preference in my matlab.prf file but I have no idea what it does or how it got there…)
• LayoutExport – boolean, controls ability to export unsaved figures without confirmation
• LayoutExtension – boolean, controls display of file extension in the GUIDE window title
• LayoutFullPath – boolean, controls display of file path in the GUIDE window title
• LayoutMCodeComments – boolean, controls generation of comments for m-file callbacks
• LayoutToolBar – boolean, controls display of the GUIDE widow toolbar
• LayoutToolNames – boolean, controls display of tool names in the components palette

Have you discovered other undocumented features in GUIDE? If so, please share your findings in the comments section below.
Warning: These undocumented features are way deep in unsupported territory. They depend heavily on Matlab’s internal implementation, which may change without any prior notice between Matlab releases. They work ok on Matlab versions 7.1 (R14 SP3) through 7.6 (R2008a), and perhaps on other versions as well. However, the very next Matlab release might break these features, so beware.

The post GUIDE customization appeared first on Undocumented Matlab.