Which is, unfortunately, exactly what happened to me yesterday.

I was about to close a figure window and accidentally closed the editor window that was behind it.

I was now in quite a jam: reopening the editor would not load all my files, but start with a blank (empty) editor. The Matlab editor, unlike modern browsers, does not have a ‘reopen last session’ option, and using the most-recently-used (MRU) files list would at best return the latest 9 files (the default Matlab preference is to have an MRU depth of only 4 files, but this is one of the very first things that I change whenever I install Matlab, along with a few other very questionable [IMHO] default preferences).

Luckily for me, there is an escape hatch: Matlab stores its Desktop windows state in a file called MATLABDesktop.xml that is located in the user’s prefdir folder. This file includes information about the position and state (docked/undocked etc.) of every Desktop window. Since the editor files are considered Desktop documents (you can see them under the Desktop’s main menu’s Window menu), they are also included in this file. When I closed the Editor, these documents were simply removed from the MATLABDesktop.xml file.

It turns out that Matlab automatically stores a backup version of this file in another file called MATLABDesktop.xml.prev, in the same prefdir folder. We can inspect the folder using our system’s file browser. For example, on Windows we could use:

winopen(prefdir)

So before doing anything else, I closed Matlab (I actually crashed it to prevent any cleanup tasks to accidentally erase this backup file, but that turned out to be an unnecessary precaution), deleted the latest MATLABDesktop.xml file, replaced it with a copy of the MATLABDesktop.xml.prev file (which I renamed MATLABDesktop.xml), and only then did I restart Matlab.

Problem solved – everything back to normal. Resume breathing. Once again I have my never-ending virtual task list in front of me as I write this.

Lessons learned:

1. don’t be too quick on the close button trigger
2. always keep a relatively recent backup copy of your important config files (BTW, I use the same advice with my FireFox browser, where I normally have dozens of open tabs – I keep a backup copy of the sessionstore.js file)
3. if you do get into a jam, don’t do anything hasty that might make recovery impossible. Calm down, look around, and maybe you’ll find an automatic backup somewhere

1. Accessing the Matlab Editor The Matlab Editor can be accessed programmatically, for a wide variety of possible uses - this article shows how....
2. Non-textual editor actions The UIINSPECT utility can be used to expand EditorMacro capabilities to non-text-insertion actions. This is how:...
3. EditorMacro – assign a keyboard macro in the Matlab editor EditorMacro is a new utility that enables setting keyboard macros in the Matlab editor. this post details its inner workings....
4. Tri-state checkbox Matlab checkboxes can easily be made to support tri-state functionality....

A few days ago, a Matlab user asked whether it is possible to solve the flashing effect whenever he cleared the Command Window. It turns out that this user runs a long process, and wanted to display interim information (progress etc.) in the Command Window. The obvious solution that he employed was to display the data in the Command Window, and then erase the window (using clc) and rewrite the data periodically.

Using control characters

Now, there are obviously other ways of doing this, the most obvious being a dedicated GUI window that displays the information and updates periodically. But to solve the user’s immediate issue, the solution I provided (acting on the 80-20 Pareto principle – a dedicated GUI window is better but would take longer to set up) was to use control characters to erase old data when displaying new data, rather than clearing the window. Here is the basic pseudo-code that I suggested (slightly modified):

reverseStr = '';
for idx = 1 : someLargeNumber
 
   % Do some computation here...
 
   % Display the progress
   percentDone = 100 * idx / someLargeNumber;
   msg = sprintf('Percent done: %3.1f', percentDone)
   fprintf([reverseStr, msg]);
   reverseStr = repmat(sprintf('\b'), 1, length(msg));
end

The idea is to use the backspace control-character (BS, or sprintf(‘\b’), or char(8)) repeatedly in order to erase the preceding characters from the Command Window, then print the new data.

(see related comments by Helge here)

Compatibility aspects

Back in the good-ol’-days, when I was hacking away c-shell scripts, ages ago when I created command-prompt C apps, and aeons ago on Vax (R.I.P.), I would have used the carriage-return control-char (CR, or sprintf(‘\r’), or char(13)) to completely erase everything up to the beginning of the current line. This would be much simpler than the repeated backspaces (using repmat in the pseudo-code above). Unfortunately, CRs behave differently in Matlab’s Command Window, causing \r to jump to the next line (similarly to \n), rather than erase to the beginning of the line. This is probably due to Java’s JTextArea’s implementation (on which the Command Window is based), and not due to Matlab itself. In any case, it shows that not all control characters behave the same way on different environments, which is actually not very surprising.

Another widely-used control character, the bell control-char (BEL, or sprintf(‘\g’), or char(7)) is not accepted at all by Matlab’s implementation of sprintf and its variants. Matlab users can always use the beep function of course, I’m just pointing this out as another inconsistency between Matlab’s *printf() implementation and that of other environments. And don’t even think of using raw device escape sequences (ah, the good-ol’-days, long gone now…).

Control characters that are accepted in Matlab and behave as expected include: FF (\f), NL (\n) and TAB (\t). These can be used in fprintf to modify the text spacing. The sprintf documentation mentions which of the control characters are accepted, so this is not, strictly speaking, an undocumented aspect. However, note that there is a discrepancy between the list of accepted control chars in the online/doc page compared to the help section (\a and \v are mentioned in the former but not in the latter).

For another type of Command Window text manipulation, namely colors, refer to my cprintf utility. For anyone who hasn’t noticed, I recently updated the utility on the Matlab File Exchange. Due to some internal modifications by MathWorks to the Command Window implementation in R2011b, cprintf no longer needs to pad color segments with spaces, and separate color segments can now be directly adjacent to each other (in R2011a and earlier, the spaces are unfortunately needed).

Have you used control characters in an innovative manner in your work? If so, please share your experience in a comment.

Happy New Year everyone!

1. cprintf – display formatted color text in the Command Window cprintf is a utility that utilized undocumented Matlab desktop functionalities to display color and underline-styled formatted text in the Command Window...
2. Changing Matlab’s Command Window colors – part 2 The Matlab Command Window enables a limited degree of inline color customization - this post describes how to use it...
3. EditorMacro v2 – setting Command Window key-bindings The EditorMacro utility was extended to support built-in Matlab Editor and Command-Window actions and key-bindings. This post describes the changes and the implementation details....
4. Changing Matlab’s Command Window colors Matlab's Command Window foreground and background colors can be modified programmatically, using some of Matlab's undocumented internal Java classes. Here's how....

>> which uisplittool
built-in (C:\Matlab\R2010b\toolbox\matlab\uitools\uisplittool)

These uitools are entirely undocumented, even today (R2010b). They puzzled me for a very long time. An acute reader (Jeremy Raymonds) suggested they are related to toolbars, like other uitools such as the uipushtool and uitoggletool. This turned out to be the missing clue that unveiled these useful tools:

So what are uisplittool and uitogglesplittool?

Both uisplittool and uitogglesplittool are basic Handle-Graphics building blocks used in Matlab toolbars, similarly to the well-documented uipushtool and uitoggletool.

uisplittool presents a simple drop-down, whereas uitogglesplittool presents a drop-down that is also selectable.

The Publish and Run controls on the Matlab Editor’s toolbar are examples of uisplittool, and so are the Brush / Select-Data control on the figure toolbar, and the plot-selection drop-down on the Matlab Desktop’s Workspace toolbar:

uisplittool in action in the Matlab Desktop

Adding uisplittool and uitogglesplittool to a toolbar

Adding a uisplittool and uitogglesplittool to a toolbar is done in a similar manner to adding uipushtools and uitoggletools:

hToolbar = findall(gcf,'tag','FigureToolBar');
hUndo=uisplittool('parent',hToolbar);       % uisplittool
hRedo=uitogglesplittool('parent',hToolbar); % uitogglesplittool

Like uipushtool and uitoggletool, uisplittool and uitogglesplittool also have unique Type property values, ‘uisplittool’ and ‘uitogglesplittool’ respectively. The handles can also be tested using the built-in isa function:

>> isa(handle(hUndo),'uisplittool')   % or: 'uitogglesplittool'
ans =
     1
>> class(handle(hUndo))
ans =
uisplittool

Just as with uipushtools and uitoggletools, the new buttons have an empty button-face appearance, until we fix their CData, Tooltip and similar settable properties:

% Load the Redo icon
icon = fullfile(matlabroot,'/toolbox/matlab/icons/greenarrowicon.gif');
[cdata,map] = imread(icon);
 
% Convert white pixels into a transparent background
map(find(map(:,1)+map(:,2)+map(:,3)==3)) = NaN;
 
% Convert into 3D RGB-space
cdataRedo = ind2rgb(cdata,map);
cdataUndo = cdataRedo(:,[16:-1:1],:);
 
% Add the icon (and its mirror image = undo) to latest toolbar
set(hUndo, 'cdata',cdataUndo, 'tooltip','undo','Separator','on', ...
           'ClickedCallback','uiundo(gcbf,''execUndo'')');
set(hRedo, 'cdata',cdataRedo, 'tooltip','redo', ...
           'ClickedCallback','uiundo(gcbf,''execRedo'')');

User-created uisplittool & uitogglesplittool toolbar buttons

Note that the controls can be created with these properties in a single command:

hUndo = uisplittool('parent',hToolbar, 'cdata',cdataRedo, ...);

Re-arranging the toolbar controls placement

Let us now re-arrange our toolbar buttons. Unfortunately, a bug causes uisplittools and uitogglesplittools to always be placed flush-left when the toolbar’s children are re-arranged (anyone at TMW reading this in time for the R2011a bug-parade selection?).

So, we can’t re-arrange the buttons at the HG-children level. Luckily, we can re-arrange directly at the Java level (note that until now, the entire discussion of uisplittool and uitogglesplittool was purely Matlab-based):

jToolbar = get(get(hToolbar,'JavaContainer'),'ComponentPeer');
jButtons = jToolbar.getComponents;
for buttonId = length(jButtons)-3 : -1 : 7  % end-to-front
   jToolbar.setComponentZOrder(jButtons(buttonId), buttonId+1);
end
jToolbar.setComponentZOrder(jButtons(end-2), 5);   % Separator
jToolbar.setComponentZOrder(jButtons(end-1), 6);   % Undo
jToolbar.setComponentZOrder(jButtons(end), 7);     % Redo
jToolbar.revalidate;

Re-arranged uisplittool & uitogglesplittool toolbar buttons
(not as simple as it may sound)

Next week, I will combine the information in this article, with last year’s articles about uiundo, and show how we can create a dynamic figure toolbar drop-down of undo/redo events. Here is a preview to whet your appetite:

undo/redo buttons implemented using uisplittool

1. uisplittool & uitogglesplittool callbacks Matlab's undocumented uisplittool and uitogglesplittool are powerful toolbar controls - this article explains how to customize their behavior...
2. Figure toolbar components Matlab's toolbars can be customized using a combination of undocumented Matlab and Java hacks. This article describes how to access existing toolbar icons and how to add non-button toolbar components....
3. uiundo – Matlab’s undocumented undo/redo manager The built-in uiundo function provides easy yet undocumented access to Matlab's powerful undo/redo functionality. This article explains its usage....
4. Customizing uiundo This article describes how Matlab's undocumented uiundo undo/redo manager can be customized...

Last week, a reader of that article posted a comment asking how to customize the context (right-click) menu with some user-defined actions. The user has found that modifying the menu via the regular table handles gets reset automatically.

Today’s article will describe an easy and effective way to add user-defined actions to the Workspace table, for specific object types.

The trick is not to modify the context-menu directly. As the reader above has noticed, this menu is automatically recreated on the fly, so no change will be persistent. Instead, we modify Matlab’s internal registry of class-specific context-menus. This is done in several prefspanel.m files in the Matlab codebase (For example: \toolbox\matlab\audiovideo\prefspanel.m and \toolbox\signal\signal\prefspanel.m).

The mechanism relies on the following Java method, which is unsupported and undocumented, yet has existed in the present form for the past several releases:

classes = {'double', 'java.lang.Object'};
menuName = 'My context-menu';
menuItems = {'Inspect', 'Properties', '-', 'class name'};
menuActions = {'inspect($1)', 'get($1)', '', 'class($1)'};
com.mathworks.mlwidgets.workspace.MatlabCustomClassRegistry.registerClassCallbacks(classes,menuName,menuItems,menuActions);

Customizable Workspace table context-menu

Once you have found your particular context-menu configuration useful, place the short customization code in your startup.m file so that the change becomes permanent in all future Matlab sessions.

A few other supporting static methods are available in the com.mathworks.mlwidgets.workspace.MatlabCustomClassRegistry class: getClassCallbacksInformation (className), registerSimilarClassCallbacks(newClassNames,definedClassName) and unregisterClassCallbacks(definedClassName). For example:

com.mathworks.mlwidgets.workspace.MatlabCustomClassRegistry.getClassCallbacksInformation('double')
 
ans =
java.lang.Object[]:
    'My context-menu'
    [4 element array]        % = menuItems
    [4 element array]        % = menuActions

1. Customizing Matlab’s Workspace table The Matlab Desktop's Workspace pane table can be customized, as described here...
2. Adding a context-menu to a uitree uitree is an undocumented Matlab function, which does not easily enable setting a context-menu. Here's how to do it....
3. Customizing menu items part 2 Matlab menu items can be customized in a variety of useful ways using their underlying Java object. ...
4. Customizing menu items part 3 Matlab menu items can easily display custom icons, using just a tiny bit of Java magic powder. ...

Matlab’s underlying Look-and-Feel

One of Matlab’s great advantages is cross-platform compatibility. Generally speaking, Matlab applications written on Windows will work as-is on Macintosh and Linux.

Java has similar cross-platform compatibilities, but enables much greater control over the look-and-feel (L&F or PLAF) of application GUI. In a nutshell, L&Fs affect the appearance and behavior of menus, controls, color schemes etc., using a properties plug-in architecture. Java programmers can choose to use either a platform-independent L&F (called the Metal L&F), or a platform-specific L&F. The benefit of using Metal is that the application looks essentially the same on all Java-supported platforms; the drawback is that they do not look like native applications on any platform…

   

Metal, Motif & Windows L&F

Matlab, whose GUI is based on Java (not surprising to readers of this website), has chosen to use a platform-specific L&F on each of the platforms on which it is supported. So, Matlab on Windows looks like a native Windows application, whereas on Macs it looks similar to Mac apps (notwithstanding the well-known X11 migration issues). Of course, this means that Windows Matlab looks and behaves differently from Mac/Linux Matlabs. Note that the differences only affect the Desktop, tools/utilities (Editor etc.) and the general L&F – it does not affect the displayed plots. In practice, the differences are visible but easily understandable.

Changing the L&F

We can get the list of available L&Fs on our system as follows (below is the list on my Windows system):

>> lafs = javax.swing.UIManager.getInstalledLookAndFeels
lafs =
javax.swing.UIManager$LookAndFeelInfo[]:
    [javax.swing.UIManager$LookAndFeelInfo]
    [javax.swing.UIManager$LookAndFeelInfo]
    [javax.swing.UIManager$LookAndFeelInfo]
    [javax.swing.UIManager$LookAndFeelInfo]
    [javax.swing.UIManager$LookAndFeelInfo]
 
>> for lafIdx = 1:length(lafs),  disp(lafs(lafIdx));  end
javax.swing.UIManager$LookAndFeelInfo[Metal javax.swing.plaf.metal.MetalLookAndFeel]
javax.swing.UIManager$LookAndFeelInfo[Nimbus com.sun.java.swing.plaf.nimbus.NimbusLookAndFeel]
javax.swing.UIManager$LookAndFeelInfo[CDE/Motif com.sun.java.swing.plaf.motif.MotifLookAndFeel]
javax.swing.UIManager$LookAndFeelInfo[Windows com.sun.java.swing.plaf.windows.WindowsLookAndFeel]
javax.swing.UIManager$LookAndFeelInfo[Windows Classic com.sun.java.swing.plaf.windows.WindowsClassicLookAndFeel]

We can change the L&F to any of the installed L&Fs, as follows:

javax.swing.UIManager.setLookAndFeel('javax.swing.plaf.metal.MetalLookAndFeel');

Although not listed in the installed L&Fs, Matlab also enables access to a 3rd-party L&F called Plastic3D by www.jgoodies.com. Plastic3D L&F generates slick stylish GUI:

javax.swing.UIManager.setLookAndFeel('com.jgoodies.looks.plastic.Plastic3DLookAndFeel')

Plastic3D L&F

The JIDE class library by www.jidesoft.com, which is bundled with Matlab, and specifically its jide-common.jar file, contains a separate set of 3rd-party L&Fs: Aqua, Eclipse (Metal & Windows variants), Office2003, VSNet (Metal & Windows variants) and Xerto. Unfortunately, in Matlab releases starting around 2009, JIDE stopped including full L&F classes in jide-common.jar, and started using L&F extensions using their com.jidesoft.plaf.LookAndFeelFactory class. I have not been able to use this class properly, but readers are welcome to try (please tell me if you succeed).

External L&Fs can also be downloaded and then used in Matlab. For example: Alloy, Synthetica and many others.

The current and standard L&Fs can be retrieved by using the respective static methods javax.swing.UIManager.getLookAndFeel() and getSystemLookAndFeelClassName().

Matlab also has a utility class com.mathworks.mwswing.plaf.PlafUtils that contains static methods that query the current L&F: isPlasticLookAndFeel(), isAquaLookAndFeel(), isMetalLookAndFeel(), isMotifLookAndFeel() and isWindowsLookAndFeel(). For some reason there is no method for the new (R2010a+) Nimbus L&F.

Nimbus L&F offers great potential for a cross-platform vectorized appearance, the ability to customize/skin pretty much every aspect of the visual appearance and component behavior, replacing Swing’s Synth L&F which was used for such customizations in earlier Matlab/Java releases. Nimbus is pre-installed as a non-default L&F in Matlab R2010a (7.10) onward, because it seems that most designers who target a single platform still prefer the native L&F.

Component-specific L&F

You can also modify the L&F of specific components, not just the entire Matlab. To do this, simply modify the L&F immediately before creating your GUI component, and restore the original L&F afterward (note how you can use either the L&F class name or its class reference):

% Update the current L&F
originalLnF = javax.swing.UIManager.getLookAndFeel;  %class
newLnF = 'javax.swing.plaf.metal.MetalLookAndFeel';  %string
javax.swing.UIManager.setLookAndFeel(newLnF);
 
% Create GUI using the modified L&F
hFig = figure(...);
hComponent = uicontrol(...);
jComponent = javacomponent(...);
 
% Ensure that the controls are fully-rendered before restoring the L&F
drawnow; pause(0.05);
 
% Restore the original L&F
javax.swing.UIManager.setLookAndFeel(originalLnF);

Components can update their L&F to the current L&F using their jComponent.updateUI() method. Components that are not specifically updated by invoking their updateUI() method will retain their existing (original) L&F – the L&F which was active when the components were created or last updated.

Fine-grained L&F property control

The default settings for the L&F can be retrieved using the static method javax.swing.UIManager.getDefaults(), which returns an enumeration of the thousand or so default settings:

>> defaults = javax.swing.UIManager.getDefaults;
>> propValues = defaults.elements; propKeys = defaults.keys;
>> while propKeys.hasMoreElements
     key = propKeys.nextElement;
     value = propValues.nextElement;
     disp([char(key) ' = ' evalc('disp(value)')]);
   end
 
com.sun.java.swing.plaf.windows.WindowsLabelUI = class com.sun.java.swing.plaf.windows.WindowsLabelUI
... (~1000 other property settings)
SplitPane.dividerSize =      5
DockableFrameTitlePane.stopAutohideIcon = javax.swing.ImageIcon@1f4e4c0
FormattedTextField.caretBlinkRate =    500
Table.gridColor = javax.swing.plaf.ColorUIResource[r=128,g=128,b=128]

Specific settings can be modified by using javax.swing.UIManager.put(key,newValue).

Have you found any useful L&F or property that you are using in your application? If so, please share them in the comments section below.

1. Modifying default toolbar/menubar actions The default Matlab figure toolbar and menu actions can easily be modified using simple pure-Matlab code. This article explains how....
2. Setting line position in an edit-box uicontrol Matlab uicontrols have many useful features that are only available via Java. Here's how to access them....
3. Setting system tray icons System-tray icons can be programmatically set and controlled from within Matlab, using new functionality available since R2007b....
4. Setting status-bar text The Matlab desktop and figure windows have a usable statusbar which can only be set using undocumented methods. This post shows how to set the status-bar text....

A few months ago, a CSSM reader asked whether it is possible to customize Matlab tab-completion for user-defined functions (see related). A similar question on StackOverflow provided the necessary solution lead:

Apparently, Matlab has a file called TC.xml in its [matlabroot '/toolbox/local/'] folder that contains the definitions of the tab-completable functions and their arguments. In order for a user-defined function’s arguments to support tab-completion, a new entry needs to be added to this XML file.

TC.xml & TC.xsd

The full syntax of the TC.xml file can be found in the TC.xsd file, which is located in the same folder as TC.xml. Here are some sample definitions from my TC.xml file (which might vary across Matlab releases):

<binding name="addpath" ctype="DIR"/>
<binding name="help"    ctype="FUN SUBFUN"/>
<binding name="clear"   ctype="FUN VAR"/>
 
<binding name="whos"    ctype="VAR">
  <arg previous="-file" ctype= "MATFILE"/>
</binding>
 
<binding name="open">
  <arg argn="1" ctype="VAR MATFILE FIGFILE MFILE MDLFILE FILE"/>
</binding>
 
<binding name="openfig">
  <arg argn="1" ctype="FIGFILE"/>
  <arg argn="2" ctype="VAR" value="new visible invisible reuse"/>
</binding>
 
<binding name="mlint"   ctype="FUN">
  <arg argn="2:10" ctype="VAR" value="-struct -string -id"/>
</binding>

The first example defines that an unlimited number of addpath arguments are all of type DIR. Therefore, when completing any argument of this function in the Command-Window, Matlab will present only relevant DIR (=folder) elements in the pop-up window (lexically sorted):

Tab-completion of type DIR

Similarly, help defines all its arguments to be a function or sub-function type, so the popup-up will only be populated with the function names currently visible in the desktop:

Tab-completion of types FUN & SUBFUN

Similarly, clear defines all its arguments as function names or variables. Note that the list of available functions and variables may change depending on the current execution stack position. The full list of supported types is defined in the TC.xsd file. It is: VAR, FUN, SUBFUN, DIR, FILE, MFILE, MATFILE, FIGFILE and MDLFILE. Addendum: Matlab release 7.10 (R2010a) added the MCOSPCG and MCOSCLASS types; release 7.13 (R2011b) added the MESSAGEID type.

The whos function defines all its arguments as VAR, except the single MATFILE argument that follows a ‘-file’ argument (look at whos‘s help page to understand why).

The open function defines tab completion only for its first argument (with plenty of possible types…). Likewise, openfig defines its first argument as a FIGFILE, and its second as VAR with a few extra special-purpose strings that are added to the popup-up menu.

Finally, the mlint example shows that multiple arguments can be defined using a single XML definition element. In this case, args #2-10 are defined as VAR (with three extra special-purpose strings), while args #1 and #11+ are defined as FUN.

The careful user can edit the TC.xml file using any text editor (I strongly suggest saving a backup first):

edit(fullfile(matlabroot,'toolbox/local/TC.xml'))

User-defined functions can easily be added to TC.xml, and we can even add/modify the built-in Matlab functions that are already defined. Note that changes to TC.xml only take effect after a Matlab restart. From then on, all future Matlab sessions will use the modification, so a really simple one-time edit can improve our workflow for a long time – at least until we upgrade Matlab, when we’ll need to redo our edits…

TabComplete utility

In order to facilitate TC.xml editing, I have created a utility called TabComplete, which is now available on the Matlab File Exchange. The use of this utility is very simple. For example:

tabcomplete test file 'DIR +data -data no_data' VAR

defines a user-defined function test that accepts a FILE argument, followed by a DIR argument with three special-purpose strings, followed by any number of VAR arguments. If I wished to define specific argument types without any default type, I would use:

tabcomplete test file 'DIR +data -data no_data' ''

Using TabComplete for user-defined functions

Addendum: Matlab releases 7.10 (R2010a) through 7.13 (R2011b) have a bug that causes Matlab to enter an endless loop (full CPU load) whenever tab-completion is requested for an argument that has possible values that are not simple terms. In the case above, “+data” and “-data” both cause this abnormal behavior. In such cases, the only remedy is to kill the Matlab process via the OS’s task manager. In Matlab R2010a-R2011b, I therefore suggest to use only simple values. This bug is apparently fixed in R2012a, making non-simple terms safe to use again. I take at least partial credit for this, having reported this bug to Mathworks in August 2011 (1-FCGDEI).

TabComplete can also be used to retrieve the current list of tab-completion definitions:

>> definitions = tabcomplete;
>> definitions(1)
ans = 
    functionName: 'addpath'
     defaultType: 'DIR'
     extraValues: ''
        platform: ''
    functionArgs: []
 
>> definitions(54)
ans = 
    functionName: 'openfig'
     defaultType: ''
     extraValues: ''
        platform: ''
    functionArgs: [1x2 struct]
>> definitions(54).functionArgs(1)
ans = 
    previousArg: ''
        argType: 'FIGFILE'
    extraValues: ''
>> definitions(54).functionArgs(2)
ans = 
    previousArg: ''
        argType: 'VAR'
    extraValues: 'new visible invisible reuse'

TabComplete has a few limitations: it does not support the -previous option described above (you can do this by manually editing TC.xml). There are also some inherent limitations in Matlab’s TC functionality: changes take effect only after a Matlab restart (there might be a way to reload the definitions in the current Matlab session, but I do not know of any); the list of standard types cannot be modified; and the default type does not support extra special-purpose strings as do the numbered arguments.

There is another very annoying limitation: by default, TC.xml only supports lowercase function names. This is stupid, since Matlab has many function names with UPPERCASE characters, and certainly user-defined function names also do. Luckily, this last limitation can easily be overcome by editing the TC.xsd file (note that this is the TC.XSD file, not the TC.XML file). Instead of:

<xsd:simpletype name="tcBindingNameType">
  <xsd:restriction base="xsd:token">
    <xsd:pattern value='[A-Za-z_0-9]+(/[a-z_0-9]+)?'/>
  </xsd:restriction>
</xsd:simpletype>

Change the xsd:pattern definition element to:

    <!-- Yair 21/2/2010: added A-Z -->
    <xsd:pattern value='[A-Za-z_0-9]+(/[A-Za-z_0-9]+)?'/>

(note the way comments can be added to the XSD/XML files)

Addendum: Matlab release 7.11 (R2011a) has fixed this XSD definition; perhaps due to this article

P.S. an entirely different customization, for user-defined class members, was presented by Michal Kutil.

1. setPrompt – Setting the Matlab Desktop prompt The Matlab Desktop's Command-Window prompt can easily be modified using some undocumented features...
2. Setting the Matlab desktop layout programmatically The Matlab desktop enables saving and switching layouts using the main menu. This post shows how to do so programmatically....
3. Setting status-bar text The Matlab desktop and figure windows have a usable statusbar which can only be set using undocumented methods. This post shows how to set the status-bar text....
4. Setting system tray icons System-tray icons can be programmatically set and controlled from within Matlab, using new functionality available since R2007b....

So the prompt can (probably) not be modified in advance, but what if it could be modified after being displayed? It is true that my cprintf utility modifies the Command-Window contents in order to display formatted text in a variety of font colors. But this case is different since cprintf runs once synchronously (user-invoked), whereas the prompt appears asynchronously multiple times.

There are two methods of handling multiple asynchronous events in Matlab: setting a callback on the object, and setting a PostSet handle.listener (or schema.listener) on the relevant object property. The first of these methods is a well-known Matlab practice, although we shall see that it uses an undocumented callback and functionality; the PostSet method is entirely undocumented and not well-known and shall be described in some later article. I decided to use the callback method to set the prompt – interested readers can try the PostSet method.

Setting the Command Window’s callback

The solution involved finding the Command-Window reference handle, and setting one of its many callbacks, in our case CaretUpdateCallback. This callback is fired whenever the desktop text is modified, which is an event we trap to replace the displayed prompt:

% Get the reference handle to the Command Window text area
jDesktop = com.mathworks.mde.desk.MLDesktop.getInstance;
try
  cmdWin = jDesktop.getClient('Command Window');
  jTextArea = cmdWin.getComponent(0).getViewport.getComponent(0);
catch
  commandwindow;
  jTextArea = jDesktop.getMainFrame.getFocusOwner;
end
 
% Instrument the text area's callback
if nargin && ~isempty(newPrompt) && ~strcmp(newPrompt,'>> ')
  set(jTextArea,'CaretUpdateCallback',{@setPromptFcn,newPrompt});
else
  set(jTextArea,'CaretUpdateCallback',[]);
end

Now that we have the Command-Window object callback set, we need to set the logic of prompt replacement – this is done in the internal Matlab function setPromptFcn. Here is its core code:

% Does the displayed text end with the default prompt?
% Note: catch a possible trailing newline
try jTextArea = jTextArea.java;  catch,  end  %#ok
cwText = get(jTextArea,'Text');
pos = strfind(cwText(max(1,end-3):end),'>> ');
if ~isempty(pos)
  % Short prompts need to be space-padded
  newLen = jTextArea.getCaretPosition;
  if length(newPrompt)<3
    newPrompt(end+1:3) = ' ';
  elseif length(newPrompt)>3
    fprintfStr = newPrompt(1:end-3);
    fprintf(fprintfStr);
    newLen = newLen + length(fprintfStr);
  end
 
  % The Command-Window text should be modified on the EDT
  awtinvoke(jTextArea,'replaceRange(Ljava.lang.String;II)',...
            newPrompt(end-2:end), newLen-3, newLen);
  awtinvoke(jTextArea,'repaint()');
end

In this code snippet, note that we space-pad prompt string that are shorter than 3 characters: this is done to prevent an internal-Matlab mixup when displaying additional text – Matlab “knows” the Command-Window’s text position and it gets mixed up if it turns out to be shorter than expected.

Also note that I use the semi-documented awtinvoke function to replace the default prompt (and an automatically-appended space) on the Event-Dispatch Thread (more on this in a future article). Since Matlab R2008a, I could use the more convenient javaMethodEDT function, but I wanted my code to work on all prior Matlab 7 versions, where javaMethodEDT was not yet available.

Preventing callback re-entry

The callback snippet above would enter an endless loop if not changed: whenever the prompt is modified the callback would have been re-fired, the prompt re-modified and so on endlessly. There are many methods of preventing callback re-entry – here’s the one I chose:

function setPromptFcn(jTextArea,eventData,newPrompt)
 
  % Prevent overlapping reentry due to prompt replacement
  persistent inProgress
  if isempty(inProgress)
    inProgress = 1;  %#ok unused
  else
    return;
  end
 
  try
    % *** Prompt modification code goes here ***
 
    % force prompt-change callback to fizzle-out...
    pause(0.02);
  catch
    % Never mind - ignore errors...
  end
 
  % Enable new callbacks now that the prompt has been modified
  inProgress = [];
 
end  % setPromptFcn

Handling multiple prompt types

I now wanted my function to handle both static prompt strings (like: ‘[Yair] ‘) and dynamic prompts (like: ‘[25-Jan-2010 01:00:51] ‘). This is done by accepting string-evaluable strings/functions:

% Try to evaluate the new prompt as a function
try
  origNewPrompt = newPrompt;
  newPrompt = feval(newPrompt);
catch
  try
    newPrompt = eval(newPrompt);
  catch
    % Never mind - probably a string...
  end
end
if ~ischar(newPrompt) && ischar(origNewPrompt)
  newPrompt = origNewPrompt;
end

File Exchange submission

I then added some edge-case error handling and wrapped everything in a single utility called setPrompt that is now available on the File Exchange.

In the future, if I find time, energy and interest, maybe I’ll combine cprintf‘s font-styling capabilities, to enable setting colored prompts.

Setting a continuously-updated timestamp prompt

Using the code above, we can now display a dynamic timestamp prompt, as follows:

setPrompt usage examples

However, the displayed timestamp is somewhat problematic in the sense that it indicates the time of prompt creation rather than the time that the associated Command-Window command was executed. In the screenshot above, [25-Jan-2010 01:29:42] is the time that the 234 command was executed, not the time that the setPrompt command was executed. This is somewhat misleading. It would be better if the last (current) timestamp was continuously updated and would therefore always display the latest command’s execution time. This can be done using a Matlab timer as follows:

% This is entered in the main function before setting the prompt:
stopPromptTimers;
if nargin && strcmpi(newPrompt,'timestamp')
  % Update initial prompt & prepare a timer to continuously update it
  newPrompt = @()(['[',datestr(now),'] ']);
  start(timer('Tag','setPromptTimer', 'Name','setPromptTimer', ...
              'ExecutionMode','fixedDelay', 'ObjectVisibility','off', ...
              'Period',0.99, 'StartDelay',0.5, ...
              'TimerFcn',{@setPromptTimerFcn,jTextArea}));
end
 
% Stop & delete any existing prompt timer(s)
function stopPromptTimers
  try
    timers = timerfindall('tag','setPromptTimer');
    if ~isempty(timers)
      stop(timers);
      delete(timers);
    end
  catch
    % Never mind...
  end
end  % stopPromptTimers
 
% Internal timer callback function
function setPromptTimerFcn(timerObj,eventData,jTextArea)
  try
    try jTextArea = jTextArea.java;  catch,  end  %#ok
    pos = getappdata(jTextArea,'setPromptPos');
    newPrompt = datestr(now);
    awtinvoke(jTextArea,'replaceRange(Ljava.lang.String;II)',...
              newPrompt, pos, pos+length(newPrompt));
    awtinvoke(jTextArea,'repaint()');
  catch
    % Never mind...
  end
end  % setPromptTimerFcn

Can you come up with some innovative prompts? If so, please share them in a comment below.

Update 2010-Jan-26: The code in this article was updated since it was first published yesterday.

1. Setting the Matlab desktop layout programmatically The Matlab desktop enables saving and switching layouts using the main menu. This post shows how to do so programmatically....
2. Setting desktop tab completions The Matlab desktop's Command-Window tab-completion can be customized for user-defined functions...
3. EditorMacro v2 – setting Command Window key-bindings The EditorMacro utility was extended to support built-in Matlab Editor and Command-Window actions and key-bindings. This post describes the changes and the implementation details....
4. Setting status-bar text The Matlab desktop and figure windows have a usable statusbar which can only be set using undocumented methods. This post shows how to set the status-bar text....

In this post I will assume Matlab release R2008a (7.6) – the adaptations for other releases should be minor at worst. First, we need to retrieve the Workspace table’s Java reference handle. In the past I’ve already shown several uses for the Matlab Desktop’s Java handle. Today we’ll use this handle to get the Workspace pane’s handle:

>> jDesktop = com.mathworks.mde.desk.MLDesktop.getInstance
jDesktop =
com.mathworks.mde.desk.MLDesktop@42d390
 
>> jWSBrowser = jDesktop.getClient('Workspace')
jWSBrowser =
com.mathworks.mde.workspace.WorkspaceBrowser[Workspace,0,24,355x707,...]
 
>> jWSTable = jWSBrowser.getComponent(0).getComponent(0).getComponent(0)
jWSTable =
com.mathworks.mlwidgets.workspace.WorkspaceTable[WorkspaceTable,0,0,352x102,...]

Next, we note that jWSTable is a simple java Swing JTable, and as such we can easily modify its column header:

jWSTable.getColumn('Bytes').setHeaderValue('KBytes');
jWSBrowser.repaint;

Modifying the column’s behavior to display 1/1024 of the initial values is more tricky. We can use a simple TableCellRenderer, replacing WorkspaceTable’s DefaultTableCellRenderer. We first create the following KBytesCellRenderer.java file:

import java.awt.*;
import javax.swing.*;
import javax.swing.SwingConstants.*;
import javax.swing.table.*;
 
public class KBytesCellRenderer extends DefaultTableCellRenderer
                                implements TableCellRenderer
{
  public Component getTableCellRendererComponent(JTable table, Object value, boolean isSelected, boolean hasFocus, int row, int column)
  {
    Component cell = super.getTableCellRendererComponent(table, value, isSelected, hasFocus, row, column);
    //System.out.println(row + "," + column + " => " + value);
    ((KBytesCellRenderer)cell).setHorizontalAlignment(TRAILING);  // TRAILING = right
 
    int bytes = Integer.parseInt(value.toString());
    ((KBytesCellRenderer)cell).setText(bytes/1024 + "");          // Bytes => KBytes
    return cell;
  }
 
  public KBytesCellRenderer()
  {
    super();
  }
}

Next, we find out our Matlab’s Java version:

>> version -java
ans =
Java 1.6.0 with Sun Microsystems Inc. Java HotSpot(TM) Client VM mixed mode

Next, we download and install a JDK version compatible with our Matlab’s Java version. You can download the latest JDK from here or here. Previous JDK versions can be downloaded from here or here (which even lets you select your requested update number). Development versions, usually fixing reported bugs, are described and can be downloaded from here. Note that you need the full JDK, not just the JVM/JRE runtime versions.

Next, we compile this file using the JDK’s Java compiler (javac) utility: In your system’s command-line (outside Matlab), type the following in the folder containing your KBytesCellRenderer.java file:

javac KBytesCellRenderer.java

If all goes well, javac will report no error and will create a KBytesCellRenderer.class file in the current folder (or you can download it directly from here).

Now copy this KBytesCellRenderer.class file to one of the folders in your Matlab’s javaclasspath (for example, C:\Program Files\Matlab\R2008a\java\patch\) and restart Matlab. Don’t worry – all this is only a one-time operation.

After restarting Matlab, we have all the chips in place, so we can place the following code in our startup.m script:

jDesktop = com.mathworks.mde.desk.MLDesktop.getInstance;
jWSBrowser = jDesktop.getClient('Workspace');
jWSTable = jWSBrowser.getComponent(0).getComponent(0).getComponent(0);
jWSTable.getColumn('Bytes').setHeaderValue('KBytes');
jWSTable.getColumn('Bytes').setCellRenderer(KBytesCellRenderer);
jWSBrowser.repaint;

Before - bytes

After - KBytes

We can use a slightly more complex CellRenderer to highlight cells with too high a value or to present thousands (comma) separator by simply modifying and recompiling KBytesCellRenderer.java, updating the class file in our javaclasspath folder and restarting Matlab. Here’s the version for the thousands separator (American locale):

import java.awt.*;
import javax.swing.*;
import javax.swing.SwingConstants.*;
import javax.swing.table.*;
import java.text.NumberFormat;
 
public class KBytesCellRenderer extends DefaultTableCellRenderer
                                implements TableCellRenderer
{
  public Component getTableCellRendererComponent(JTable table, Object value, boolean isSelected, boolean hasFocus, int row, int column)
  {
    Component cell = super.getTableCellRendererComponent(table, value, isSelected, hasFocus, row, column);
    //System.out.println(row + "," + column + " => " + value);
    ((KBytesCellRenderer)cell).setHorizontalAlignment(TRAILING);  // TRAILING = Right
 
    int bytes = Integer.parseInt(value.toString());
    NumberFormat nf = NumberFormat.getInstance();
    ((KBytesCellRenderer)cell).setText(nf.format(bytes/1024));    // Bytes => KBytes
    return cell;
  }
 
  public KBytesCellRenderer()
  {
    super();
  }
}

After - formatted KBytes

If you have created an interesting CellRenderer, I will be happy to hear about it in the comments section below.

1. Customizing Workspace context-menu Matlab's Workspace table context-menu can be configured with user-defined actions - this article explains how....
2. Customizing help popup contents The built-in HelpPopup, available since Matlab R2007b, has a back-door that enables displaying arbitrary text, HTML and URL web-pages....
3. Customizing uitree This article describes how to customize Matlab GUI tree controls created using the undocumented uitree function...
4. Customizing Matlab labels Matlab's text uicontrol is not very customizable, and does not support HTML or Tex formatting. This article shows how to display HTML labels in Matlab and some undocumented customizations...

Help popup

To programmatically display this help popup, a modeless MJDialog Java window, we need to run the following on Matlab releases that support these windows (R2007b onward):

jDesktop = com.mathworks.mde.desk.MLDesktop.getInstance;
jTextArea = jDesktop.getMainFrame.getFocusOwner;
jClassName = 'com.mathworks.mlwidgets.help.HelpPopup';
jPosition = java.awt.Rectangle(0,0,400,300);
helpTopic = 'surf';
javaMethodEDT('showHelp',jClassName,jTextArea,[],jPosition,helpTopic);

Where:
1) jPosition sets popup’s pixel size and position (X,Y,Width,Height). Remember that Java counts from the top down (contrary to Matlab) and is 0-based. Therefore, Rectangle(0,0,400,300) is a 400×300 window at the screen’s top-left corner.
2) helpTopic is the help topic of your choice (the output of the doc function). To display arbitrary text, you can create a simple .m file that only has a main help comment with your arbitrary text, which will be presented in the popup.
3) on R2011b, we could simplify the above code snippet with the following replacement:

helpUtils.errorDocCallback('surf')

4) on R2007b, we need to use the equivalent but more cumbersome awtinvoke function instead of javaMethodEDT:

jniSig = 'showHelp(Ljavax.swing.JComponent;Lcom.mathworks.mwswing.binding.KeyStrokeList;Ljava.awt.Rectangle;Ljava.lang.String;)';
awtinvoke(jClassName,jniSig,jTextArea,[],jPosition,helpTopic);

For example, if we had a sample.m file with the following contents:

function sample
% The text in this function's main comment will be presented in the
% help popup. <a href="http://UndocumentedMatlab.com">Hyperlinks</a>
% are supported, but unfortunately not full-fledged HTML.

Then we would get this result:

User-created arbitrary text

Well, it does get the message across, but looks rather dull. It would be nice if this could be improved to provide full-scale HTML support. Unfortunately, Matlab documentation says this cannot be done:

The doc function is intended only for reference pages supplied by The MathWorks. The exception is the doc UserCreatedClassName syntax. doc does not display HTML files you create yourself. To display HTML files for functions you create, use the web function.

Luckily for us, there is an undocumented back-door to do this: The idea is to search all visible Java windows for the HelpPopup, then move down its component hierarchy to the internal web browser (a com.mathworks.mlwidgets.html.HTMLBrowserPanel object), then update the content with our arbitrary HTML or a webpage URL:

% Find the Help popup window
jWindows = com.mathworks.mwswing.MJDialog.getWindows;
jPopup = [];
for idx=1 : length(jWindows)
  if strcmp(get(jWindows(idx),'Name'),'HelpPopup')
    if jWindows(idx).isVisible
      jPopup = jWindows(idx);
      break;
    end
  end
end
 
% Update the popup with selected HTML
html=['Full HTML support: <b><font color=red>bold</font></b>, '...
      '<i>italic</i>, <a href="matlab:dir">hyperlink</a>, ' ...
      'symbols (&#8704;&#946;) etc.'];
if ~isempty(jPopup)
  browser = jPopup.getContentPane.getComponent(1).getComponent(0);
  browser.setHtmlText(html);
end

Help popup with HTML content

We can display HTML content and highlight certain keywords using the setHtmlTextAndHighlightKeywords method:

browser.setHtmlTextAndHighlightKeywords(html,{'support','symbols'});

HTML content with highlighting

Instead of specifying the HTML content, we can point this browser to a web-page URL (no need for the “http://” prefix):

browser.setCurrentLocation('UndocumentedMatlab.com');

Help popup browser displaying a URL web-page

The HTMLBrowserPanel includes a full-fledged browser (which may be different across Matlab releases/platforms). This browser supports HTML, CSS, JavaScript and other web-rendering aspect that we would expect from a modern browser. Being a full-fledged browser, we have some control over its appearance e.g., addAddressBox(1,1) and other internal methods. Interested readers may use my UiInspect utility to explore these options.

As a technical note, HTMLBrowserPanel is actually only a JPanel that contains the actual Mozilla browser. Luckily for us, MathWorks extended this panel class with the useful methods presented above, that forward the user requests to the actual internal browser. This way, we don’t need to get the actual browser reference (although you can, of course).

I have created a utility function that encapsulates all the above, and enables display of Matlab doc pages, as well as arbitrary text, HTML or webpages. This popupPanel utility can now be downloaded from the Matlab File Exchange.

An interesting exercise left for the readers, is adapting the main heavy-weight documentation window to display user-created HTML help pages. This can be achieved by means very similar to those shown in this article.

Of course, as the official documentation states, we could always use the fully-supported web function to display our HTML or URLs. Under the hood, web uses exactly the same HTMLBrowserPanel as out HelpPopup. The benefit of using the methods shown here is the use of a lightweight undecorated popup window which looks well-integrated with the existing Matlab help.

Please note that the HelpPopup implementation might change without warning between Matlab releases. An entirely separate, although related, implementation is Matlab’s built-in context-sensitive help system, which I described some months ago. That implementation did not rely on Java and worked on much earlier Matlab releases.

1. Setting system tray popup messages System-tray icons and messages can be programmatically set and controlled from within Matlab, using new functionality available since R2007b....
2. Customizing Workspace context-menu Matlab's Workspace table context-menu can be configured with user-defined actions - this article explains how....
3. Rich Matlab editbox contents The Matlab editbox uicontrol does not handle HTML contents as do other uicontrols. In this article I show how this limitation can be removed....
4. Customizing Matlab’s Workspace table The Matlab Desktop's Workspace pane table can be customized, as described here...

Before we start, it should be made clear that this entire article relies on MathWorks internal implementation of the Editor and Desktop, which may change without prior notice in future Matlab releases. The code below appears to work under Matlab 6 & 7, but users who rely on forward compatibility should be aware of this warning.

We start by retrieving the Editor handle. This can be done in a number of ways. The easiest is via the Matlab desktop:

try
    % Matlab 7
    desktop = com.mathworks.mde.desk.MLDesktop.getInstance;
    jEditor = desktop.getGroupContainer('Editor').getTopLevelAncestor;
    % we get a com.mathworks.mde.desk.MLMultipleClientFrame object
catch
    % Matlab 6
    % Unfortunately, we can't get the Editor handle from the Desktop handle in Matlab 6:
    %desktop = com.mathworks.ide.desktop.MLDesktop.getMLDesktop;
 
    % So here's the workaround for Matlab 6:
    openDocs = com.mathworks.ide.editor.EditorApplication.getOpenDocuments;  % a java.util.Vector
    firstDoc = openDocs.elementAt(0);  % a com.mathworks.ide.editor.EditorViewContainer object
    jEditor = firstDoc.getParent.getParent.getParent;
    % we get a com.mathworks.mwt.MWTabPanel or com.mathworks.ide.desktop.DTContainer object
end

Now that we have the Editor handle, let’s retrieve its currently open (active) file name from the Editor’s title:

title = jEditor.getTitle;
currentFilename = char(title.replaceFirst('Editor - ',''));

The entire list of open file names can be retrieved in several ways:

% Alternative #1:
edhandle = com.mathworks.mlservices.MLEditorServices;
allEditorFilenames = char(edhandle.builtinGetOpenDocumentNames);
 
% Alternative #2:
openFiles = desktop.getWindowRegistry.getClosers.toArray.cell;
allEditorFilenames = cellfun(@(c)c.getTitle.char,openFiles,'un',0);

At the top-level Editor-window level, we can prevent its resizing, update its status bar, modify its toolbar/menu-bar, control docking and do other similar fun things:

% Actions via built-in methods:
jEditor.setResizable(0);
jEditor.setStatusText('testing 123...');
jEditor.setTitle('This is the Matlab Editor');
 
% Equivalent actions via properties:
set(jEditor, 'Resizable', 'off');
set(jEditor, 'StatusText', 'testing 123...');
set(jEditor, 'Title', 'This is the Matlab Editor');

Actually, the jEditor handle has over 300 invokable methods and close to 200 properties that we can get/set. Perhaps the easiest way to find interesting things we can programmatically do with the Editor handle, is to use my UIInspect utility on the File Exchange:

uiinspect(jEditor);  % or: jEditor.uiinspect

Matlab Editor methods, callbacks and properties as seen by uiinspect
(click to zoom)

The Editor handle is actually a container for many internal panels (toolbars etc.) and documents. The entire object hierarchy can be seen with another of my File Exchange utilities, FindJObj:

findjobj(jEditor);  % or: jEditor.findjobj

Matlab Editor object hierarchy as seen by findjboj (click to zoom)

We can modify text within the open Editor documents, and instrument these document to handle event callbacks. To see how, I refer users to my EditorMacro utility on the Matlab File Exchange.

If you find some other nifty and/or useful things that can be done using the Editor handle, please post them in the comments section below.

1. EditorMacro – assign a keyboard macro in the Matlab editor EditorMacro is a new utility that enables setting keyboard macros in the Matlab editor. this post details its inner workings....
2. Non-textual editor actions The UIINSPECT utility can be used to expand EditorMacro capabilities to non-text-insertion actions. This is how:...
3. Accessing plot brushed data Plot data brushing can be accessed programmatically using very simple pure-Matlab code...
4. Recovering previous editor state Recovering the previous state of the Matlab editor and its loaded documents is possible using a built-in backup config file. ...