Desktop – Undocumented Matlab

Matlab toolstrip – part 2 (ToolGroup App)

Yair Altman — Wed, 05 Dec 2018 17:00:48 +0000

A while ago I posted the first of my planned miniseries on the Matlab toolstrip (ribbon). Today I will expand that post by discussing how toolstrips can be added to Matlab GUIs. This post will remain at a high-level as the previous post, with followup posts drilling into the technical details of the toolstrip components (inner packages and classes).
We can add a Matlab toolstrip to 3 types of Matlab GUI windows:

To a Java-based Matlab figure (so-called “legacy” figures, created using GUIDE or the figure function)
To a container window of docked Java-based figures, typically called an “App” (marketing name) or “Tool Group” (internal technical name)
To a JavaScript/HTML-based Matlab figure (so called “web” figures, created using App Designer or the uifigure function)

Today I will show how to add a basic dynamic toolstrip to a ToolGroup (App, window type #2):

ToolGroup with clients and dynamic toolstrip

Figure containers (“Tool Groups”)

Most Matlab users are familiar with window types #1 and #3 (legacy and web-based figures), but type #2 may seem strange. In fact, it shouldn’t be: All the Matlab “Apps” and Desktop components use such a container of docked clients. For example, both the Matlab Editor and Desktop are containers of individual client windows (individual files in the Editor; Command Window, Workspace etc. in the desktop).
Similarly, when we dock figures, they dock as client windows into a container called “Figures” (this can be controlled programmatically: see my setFigDockGroup utility on the File Exchange). This is the basis for all Matlab “Apps”, as far as I am aware (some Apps may possibly use a different GUI container, after all there are ~100 Matlab Apps and I’m not familiar with all of them). Such Apps are basically stand-alone Tool Groups (client container windows) that contain one or more docked figures, a toolstrip, and a side-panel with controls (so-called “Data Browser”).
Note: MathWorks uses confusing terminology here, using the same term “App” for both MathWorks-created GUIs containers (that have toolstrips, Data Browser and docked figures) and also user-created utilities on the File Exchange (that do not have these). Unfortunately, MathWorks has chosen not [yet] to release to the general public its set of tools that enable creating true “Apps”, i.e. those that have a toolstrip, Data Browser and docked figures.
Today’s post will attempt to fill this gap, by showing how we can create user Apps that have a toolstrip and docked figures. I will ignore the Data Browser today, and will describe it in a future post. Since docking figures into a standalone user-created container is a solved problem (using my setFigDockGroup utility), this post will focus on adding a toolstrip to such a container.
A ToolGroup object (matlab.ui.internal.desktop.ToolGroup) is created either implicitly (by docking a figure into a group that has a new name), or explicitly (by invoking its constructor):

% Create a new non-visible empty App (Tool Group)
hToolGroup = matlab.ui.internal.desktop.ToolGroup('Toolstrip example on UndocumentedMatlab.com');

Some things only work properly after the app is displayed, so let’s display the ToolGroup (however, note that for improved performance it is better to do whatever customizations and GUI updates that you can before the app is made visible):

% Display the ToolGroup window
hToolGroup.open();

Basic empty ToolGroup (without toolstrip or clients)

An annoying quirk with ToolGroups is that they automatically close when their reference handle is deleted from Matlab memory. The specific behavior changes depending on the contents of the container and the Matlab release, but in general it’s safest to preserve the hToolGroup variable, to prevent the window from closing, when this variable goes out of scope, when the function (in which we create the ToolGroup) returns. There are many ways to persist this variable. Here’s one alternative, in which we persist it in itself (or rather, attached to its internal Java peer control):

% Store toolgroup reference handle so that app will stay in memory
jToolGroup = hToolGroup.Peer;
internal.setJavaCustomData(jToolGroup, hToolGroup);

internal.setJavaCustomData is an undocumented Matlab function that adds a new custom property to a Java reference handle. In our case, it adds a CustomData property to the jToolGroup handle and sets its value to the Matlab hToolGroup handle. The source code for internal.setJavaCustomData is available in %matlabroot%/toolbox/shared/controllib/general/+internal/setJavaCustomData.m and is very simple: it essentially uses the old schema-based schema.prop method for adding new properties to handles. Schema is an old deprecated mechanism that is mostly replaced by the newer MCOS (Matlab Class Object System), but for some specific cases such as this it’s still very useful (the standard addprop function can add new properties to Matlab GUI handles, but not to Java reference handles).
Finally, let’s discard the Data Browser side panel (I’ll discuss it in a separate future post):

% Discard the Data-browser left panel
hToolGroup.disableDataBrowser();

Adding a toolstrip to the ToolGroup

Now that we have the basic container ready, let’s add a toolstrip. To simplify matters in this introductory post (after all, I have still not described the internal packages and classes that make up a toolstrip), we’ll use some of the tabs used in the showcaseToolGroup example that I discussed in my previous post. You can see the relevant source code in %matlabroot%/toolbox/matlab/toolstrip/+matlab/+ui/+internal/+desktop/*.m, in case you want to jump ahead and customize your own toolstrip tabs, groups and buttons. In the code snippet below, we first create an empty TabGroup, then add toolstrip tabs into it, and finally add this TabGroup into our ToolGroup using its addTabGroup(hTabGroup) method:

% Create a new tab group
%hTabGroup = matlab.ui.internal.desktop.showcaseBuildTabGroup('swing');
hTabGroup = matlab.ui.internal.toolstrip.TabGroup();
hTab1 = matlab.ui.internal.desktop.showcaseBuildTab_Buttons('swing');
hTabGroup.add(hTab1);
%hTabGroup.add(matlab.ui.internal.desktop.showcaseBuildTab_Gallery());
hTabGroup.add(matlab.ui.internal.desktop.showcaseBuildTab_Layout('swing'));
% Select tab #1 (common)
hTabGroup.SelectedTab = hTab1;
% Add the tab group to the built-in toolstrip
hToolGroup.addTabGroup(hTabGroup);

We now have an “App” that has a toolstrip, but no clients (yet), and a hidden Data Browser side-panel:

Now let’s add some clients (docked figures):

Adding clients (docked figures) to the ToolGroup

There are two easy variants for adding docked figures in a ToolGroup: The easiest is to use the ToolGroup’s addFigure(hFigure) method:

% Create a figure and dock it into the tool-group
hFig1 = figure('Name','3D');
surf(peaks);
hToolGroup.addFigure(hFig1);

The second variant enables to dock a figure that has a specific set of toolstrip tabs attached to it. These tabs will only display in the toolstrip when that particular figure has focus. We do this by creating a new TabGroup (just as we have done above), and then add the figure and TabGroup to the container using the ToolGroup’s addClientTabGroup(hFigure,hTabGroup) method:

% Create the 2nd figure
hFig2 = figure('Name','2D');
plot(rand(5)); drawnow
% Add a few tabs that are only relevant to this specific figure
hTabGroup2 = matlab.ui.internal.toolstrip.TabGroup();
hTab2 = matlab.ui.internal.desktop.showcaseBuildTab_Selections();
hTabGroup2.add(hTab2);
hTabGroup2.add(matlab.ui.internal.desktop.showcaseBuildTab_EditValue());
% Add the figure and tabs to the ToolGroup
hToolGroup.addClientTabGroup(hFig2, hTabGroup2);

ToolGroup with clients and dynamic toolstrip

In this example, the “Selection” and “Values” toolstrip tabs only appear when the 2nd figure (“2D”) has focus. A similar behavior exists in the Matlab Desktop and Editor, where some tabs are only shown when certain clients have focus.

Removing the View tab

Note that the “View” toolstrip tab (which enables setting the appearance of the docked figures: layout, tab positions (top/bottom/left/right), ordering etc.) is automatically added to the toolstrip and always appears last. We can remove this View tab using the ToolGroup’s hideViewTab() method. The tab will not immediately be removed, only when the toolstrip is repainted, for example, when we switch focus between the docked figures:

hToolGroup.hideViewTab;  % toolstrip View tab is still visible at this point
figure(hFig1);  % change focus to hFig1 - toolstrip is repainted without View tab

Conclusion

It’s relatively easy to dock figures into a standalone “App” window that has a custom toolstrip, which can even be dynamically modified based on the figure which is currently in focus. Naturally, this has little benefit if we cannot customize the toolstrip components: labels, icons, control type, grouping and most importantly – callbacks. This topic deserves a dedicated post, which I plan to be the next in this miniseries. Stay tuned – hopefully the next post will not take me as long to publish as this post (I was quite busy recently)…

The post Matlab toolstrip – part 2 (ToolGroup App) appeared first on Undocumented Matlab.

Matlab toolstrip – part 1

Yair Altman — Mon, 03 Sep 2018 15:00:22 +0000

The Matlab toolstrip (ribbon) has been around officially since R2012a, and unofficially for a couple of years earlier. Since then, I blogged about the toolstrip only rarely (example). I believe the time has come to start a short mini-series about this functionality, eventually showing how users can use toolstrips in their own custom applications.
My plan is to start the miniseries with a discussion of the built-in showcase examples, followed by a post on the built-in classes that make up the toolstrip building-blocks. Finally, I’ll describe how toolstrips can be added to figures, not just in client/tool groups.

Matlab’s internal showcase examples

I start the discussion with a description of built-in examples for the toolstrip functionality, located in %matlabroot%/toolbox/matlab/toolstrip/+matlab/+ui/+internal/+desktop/. The most important of these are showcaseToolGroup.m and showcaseMPCDesigner.m, both of which use Java-based (Swing) containers and controls. Readers who wish to integrate toolstrips into their app immediately, without waiting for my followup posts in this series, are welcome to dig into the examples’ source-code and replicate it in their programs:

1. `showcaseToolGroup`

h = matlab.ui.internal.desktop.showcaseToolGroup

2. `showcaseMPCDesigner`

>> h = matlab.ui.internal.desktop.showcaseMPCDesigner
h =
  showcaseMPCDesigner with properties:
    ToolGroup: [1×1 matlab.ui.internal.desktop.ToolGroup]
       Dialog: [1×1 toolpack.component.TSTearOffPopup]
      Figure1: [1×1 Figure]
      Figure2: [1×1 Figure]

3. `showcaseHTML` and `showcaseCEF`

In addition to these showcase examples, the folder also contains a showcaseHTML.m and showcaseCEF.m files, that are supposed to showcase the toolstrip functionality in JavaScript-based containers (browser webpage and uifigure apps, respectively). Unfortunately, on my system running these classes displays blank, although the toolstrip is indeed created, as seen below (if you find out how to make these classes work, please let me know):

>> h = matlab.ui.internal.desktop.showcaseHTML
building toolstrip hierarchy...
rendering toolstrip...
h =
  Toolstrip with properties:
               SelectedTab: [1×1 matlab.ui.internal.toolstrip.Tab]
              DisplayState: 'expanded'
    DisplayStateChangedFcn: @PropertyChangedCallback
                       Tag: 'toolstrip'
>> hs = struct(h)
Warning: Calling STRUCT on an object prevents the object from hiding its implementation details and should thus be avoided.
Use DISP or DISPLAY to see the visible public details of an object. See 'help struct' for more information.
(Type "warning off MATLAB:structOnObject" to suppress this warning.)
hs =
  struct with fields:
                         SelectedTab: [1×1 matlab.ui.internal.toolstrip.Tab]
                        DisplayState: 'expanded'
              DisplayStateChangedFcn: @PropertyChangedCallback
                 DisplayStatePrivate: 'expanded'
                        QABIdPrivate: '2741bf89'
               QuickAccessBarPrivate: [1×1 matlab.ui.internal.toolstrip.impl.QuickAccessBar]
       DisplayStateChangedFcnPrivate: @PropertyChangedCallback
         SelectedTabChangedListeners: [1×1 event.listener]
                                 Tag: 'toolstrip'
                                Type: 'Toolstrip'
                          TagPrivate: 'toolstrip'
    WidgetPropertyMap_FromMCOSToPeer: [3×1 containers.Map]
    WidgetPropertyMap_FromPeerToMCOS: [3×1 containers.Map]
                              Parent: [0×0 matlab.ui.internal.toolstrip.base.Node]
                            Children: [1×1 matlab.ui.internal.toolstrip.TabGroup]
                             Parent_: []
                           Children_: [1×1 matlab.ui.internal.toolstrip.TabGroup]
                                Peer: [1×1 com.mathworks.peermodel.impl.PeerNodeImpl]
                   PropertySetSource: [1 java.util.HashMap]
                    PeerModelChannel: '/ToolstripShowcaseChannel'
                   PeerEventListener: [1×1 handle.listener]
                 PropertySetListener: [1×1 handle.listener]
>> hs.Peer
ans =
PeerNodeImpl{id='4a1e4b08', type='Toolstrip', properties={displayState=expanded, hostId=ToolStripShowcaseDIV, tag=toolstrip, QABId=2741bf89}, parent=878b0e2b, children=[
    PeerNodeImpl{id='5bb9632c', type='TabGroup', properties={QAGroupId=ea9b628c, tag=, selectedTab=f90db10c}, parent=4a1e4b08, children=[
        PeerNodeImpl{id='f90db10c', type='Tab', properties={mnemonic=, tag=tab_buttons, title=BUTTONS}, parent=5bb9632c, children=[
            PeerNodeImpl{id='1ccc9246', type='Section', properties={collapsePriority=0.0, mnemonic=, tag=sec_push, title=PUSH BUTTON}, parent=f90db10c, children=[
                PeerNodeImpl{id='8323f06e', type='Column', properties={horizontalAlignment=left, width=0.0, tag=}, parent=1ccc9246, children=[
                    PeerNodeImpl{id='af368d7b', type='PushButton', properties={textOverride=, descriptionOverride=, mnemonic=, actionId=230d471b, iconOverride=, tag=pushV, iconPathOverride=}, parent=8323f06e, children=[]}]}
                PeerNodeImpl{id='a557a712', type='Column', properties={horizontalAlignment=left, width=0.0, tag=}, parent=1ccc9246, children=[
                    PeerNodeImpl{id='f0d6a9fc', type='EmptyControl', properties={tag=}, parent=a557a712, children=[]}
                    PeerNodeImpl{id='74bc4cd2', type='PushButton', properties={textOverride=, descriptionOverride=, mnemonic=, actionId=12d6a26a, iconOverride=, tag=pushH, iconPathOverride=}, parent=a557a712, children=[]}
                    PeerNodeImpl{id='bcb5a9d0', type='EmptyControl', properties={tag=}, parent=a557a712, children=[]}]}]}
            PeerNodeImpl{id='0e515319', type='Section', properties={collapsePriority=0.0, mnemonic=, tag=sec_dropdown, title=DROP DOWN BUTTON}, parent=f90db10c, children=[
                PeerNodeImpl{id='80482225', type='Column', properties={horizontalAlignment=left, width=0.0, tag=}, parent=0e515319, children=[
                    PeerNodeImpl{id='469f469a', type='DropDownButton', properties={textOverride=, descriptionOverride=, mnemonic=, actionId=c6ca7335, iconOverride=, tag=dropdownV, iconPathOverride=}, parent=80482225, children=[]}]}
                ...

Note: showcaseCEF has been removed in 2018, but is available in older Matlab releases.

Levels of toolstrip encapsulation

Matlab currently has several levels of encapsulation for toolstrip components:

Top-level m-file classes for showcasing the toolstrip functionality and creating toolstrips in Java-based containers and web-based apps – these are located in %matlabroot%/toolbox/matlab/toolstrip/+matlab/+ui/+internal/+desktop/
Mid-level m-file classes that contain the toolstrip building blocks (tabs, sections, controls) – these are located in %matlabroot%/toolbox/matlab/toolstrip/+matlab/+ui/+internal/+toolstrip/
Low-level Java classes that implement the underlying user-interface for Java-based UI – these are located in %matlabroot%/java/jar/toolstrip.jar. I discussed this briefly in a post few years ago.

The top- and mid-level m-file classes are provided with full source code that is quite well-documented internally (as m-file source-code comments). However, note that it is not officially documented or supported (i.e., semi-documented in this blog’s parlance).
The low-level Java classes on the other hand are compiled without available source code – we can inspect these classes (e.g., using uiinspect or checkClass), but we cannot see their original source-code. Luckily, the higher-level m-file classes provide us with plenty of hints and usage examples that we could use to tailor the appearance, functionality and integration of toolstrip components into our app.

Robyn Jackey’s Widgets Toolbox

Users who hesitate to mess around with the built-in toolstrip functionality may find interest in MathWorker Robyn Jackey’s Toolstrip look-alike, which is part of his open-source Widgets Toolbox on the Matlab File Exchange. Unlike other parts of Robyn’s toolbox, which use undocumented functionality, his Toolstrip class seems to use documented components (panels, uicontrols etc.), with just a small reliance on undocumented functionality (matlab.ui.* for example). This has a fair chance to continue working well into future releases, even if Matlab’s built-in toolstrip functionality changes:

Strong caution

Over the years, Matlab’s internal toolstrip interface has changed somewhat, but not dramatically. This could change at any time, since the toolstrip uses deeply undocumented functionality. What I will demonstrate over the next few posts might stop working in R2019a, or in R2025b – nobody really knows, perhaps not even MathWorks at this stage. Something that we do know for a fact is that Matlab is slowly transitioning away from Java-based user interfaces to web-based (HTML/JavaScript/CSS) interfaces, and this could have a drastic effect on the toolstrip functionality/API. It seems reasonable to assume that even if MathWorks would one day open up the toolstrip functionality, this would only be for the new web-based uifigure apps (not legacy Java-based figures), and might well have a different API than the one that I’ll discuss in this miniseries. Still, users could use the unofficial/undocumented information that I present here in their own Java figures today and quite possibly also in near-term upcoming releases.
Despite the many unknowns regarding future supportability/roadmap of the built-in toolstrip API, I believe that my readers are smart enough to decide for themselves whether they want to take the associated risks to improve their Matlab programs today, or wait until a documented API will possibly be provided sometime in the future. The choice is yours, as it always is when using undocumented tips from my blog.
With this warning stated, let’s start having fun with Matlab’s built-in toolstrip!

The post Matlab toolstrip – part 1 appeared first on Undocumented Matlab.

Spicing up the Matlab Editor

Yair Altman — Thu, 29 Mar 2018 21:34:20 +0000

I’d like to introduce guest blogger Andreas Justin, who will discuss some way-cool features in his Editor Plugin utility. Many of his feature implementations are not Editor-specific and can be reused in other Matlab-Desktop applications, for example dockable panels, and integration with Matlab’s main Preferences window.
Note: I will be traveling to the USA in June, and to Spain in August. If you would like me to visit your location for onsite consulting or training, then please let me know.
Happy Easter/Passover!

Overview

Editor-plugin's cool logo

Compared to other IDE like IntellIJ, Eclipse and many more, Matlab’s editor seems somewhat outdated. Especially writing Object-Oriented code in Matlab is kind of a hassle. To make Matlab more user friendly, I’ve written a Java app that adds important features to the editor – Features such as navigating inside Class-code and in Inherited members; Searching through methods and instantly jumping to desired location; Reopening an editor that was closed by accident; Storing bookmarks between Matlab sessions; and Live Templates using commands directly written in the editor, replaced by pre-defined text.

The default Keyboard shortcuts listed below for the features can be customized. Most variables can be customized as well (I will point out which variables are not [yet] customizable).
Most GUIs have a search field. Within this search field you can move the list or the tree up and down using arrow keys, or hit to return to editor. These search fields allow you to enter regular expressions to limit results shown in list or tree. Also, most GUIs are dockable.
The Editor-Plugin utility is open-source. It is available on GitHub and also mirrored on the Matlab File Exchange. A detailed setup guide is provided on the utility’s wiki section in GitHub.
If you discover any problem or have any suggestion for improvement, please visit the utility’s Issues section on GitHub, where all open/closed issues can be tracked and discussed.
A brief overview of some of the features is presented below. For a detailed explanation of these and other features (which are not listed below), please review the Features section of the utility’s wiki (you guessed it: on GitHub…).

Editing

Delete / duplicate lines – CTRL + SHIFT + Y or D allows you to delete or duplicate current line.
Move lines up or down – CTRL + ALT + UP or DOWN allows you to move selected lines up or down.
Live (auto-replace) templates – Live Templates are editor commands you can design to insert predefined code. Here’s an example for the command %this% (delivered within the package). When you type a command into the editor the string will get replaced by the predefined text. This predefined text may include variables depending on what you want to achieve. %this% was designed to insert the fully qualified name of the current class you’re in (or function, or script).
Clipboard Stack – CTRL + SHIFT + V opens the Clipboard Stack, where the last 10 copied/cut text are stored and can be directly inserted into the current editor position. The Clipboard Stack only stores text copied from editor.

Auto switch current folder and detail viewer – Switching editor tabs will update the Desktop’s current folder and detail viewer. This behavior can be directly changed in the detail viewer bar.
Use the new icons in the Desktop’s Current Folder panel: to toggle detail viewer and to toggle following the current editor file.
File Structure – I personally use this one the most: CTRL + F12 will show a GUI that let you search methods and properties including inherited ones.
Navigation History – Every editor file that is opened is stored in the navigation history. Up to 50 editor file paths are stored. If you have a 5-Button Mouse, you can navigate through previous location (backward and forward).
Recently Closed – CTRL + SHIFT + T will show a GUI that allows you to reopen closed editors this or last session.
Bookmarks – CTRL + SHIFT + F2 will show a GUI that allows you to name, search and delete bookmarks. Matlab has this nice feature to delete bookmarks after closing the editor. This feature will store all bookmarks. If an editor or Matlab is closed and opened later. All Bookmarks will be restored.
This feature has some issues though. The most obvious first: if the source file has been changed outside of Matlab, the bookmark does not get updated, and may point to the wrong line, or gets deleted. Also on some Systems the default shortcut does not work. But there are workarounds.

Other useful features

Dockable Windows – As mentioned before, most GUIs are dockable.
Preferences – Preferences panel integrated in Matlab’s main Preferences window.
Execute current line – SHIFT + F9 allows you to execute the current line. This is equivalent to selecting the entire line, then clicking F9, and is similar in concept to the editor’s built-in ability to execute the current cell-block.
VarDiff – Select two variables in the workspace and compare them using Matlab’s internal comparison feature (adding a custom hook to the Workspace context-menu was discussed by Yair back in 2010).
KeyPressListener – Allows you to create custom keyboard shortcuts for your own functions. A similar functionality was discussed by Yair back in 2009.

As noted above, a detailed explanation of these and other features is provided in the Features section of the utility’s wiki. If you discover any problem or have any suggestion for improvement, please visit the utility’s Issues section on GitHub, where issues can be tracked and discussed.

The post Spicing up the Matlab Editor appeared first on Undocumented Matlab.

The HotLinks feature

Yair Altman — Tue, 24 Oct 2017 12:43:13 +0000

Back in 2010, I posted about Matlab’s undocumented feature function. One of the features that I mentioned was 'HotLinks'. A few days ago I had an occasion to remember this feature when a StackOverflow user complained that the headers of table outputs in the Matlab console appear with HTML tags () in his diary output. He asked whether it was possible to turn off this automated headers markup.
There are several ways this problem can be solved, ranging from creating a custom table display function, to modifying the table’s internal disp method (%matlabroot%/toolbox/matlab/datatypes/@tabular/disp.m), to using this method’s second optional argument (disp(myTable,false)). Note that simply subclassing the table class to overload disp() will not work because the table class is Sealed, but we could instead subclass table‘s superclass (tabular) just like table does.
Inside the disp.m method mentioned above, the headers markup is controlled (around line 45, depending on your Matlab release) by matlab.internal.display.isHot. Unfortunately, there is no corresponding setHot() method, nor corresponding m- or p-code that can be inspected. But the term “Hot” rang a bell, and then I remembered my old post about the HotLinks feature, which is apparently reflected by matlab.internal.display.isHot.

feature('HotLinks',false); % temporarily disable bold headers and hyperlinks (matlab.internal.display.isHot=false) disp(myTable) myTable % this calls disp() implicitly feature('HotLinks',true); % restore the standard behavior (markup displayed, matlab.internal.display.isHot=true)

Searching for “isHot” or “HotLinks” under the Matlab installation folder, we find that this feature is used in hundreds of places (the exact number depends on your installed toolboxes). The general use appears to be to disable/enable output of hyperlinks to the Matlab console, such as when you display a Matlab class, when its class name is hyperlinked and so is the “Show all properties” message at the bottom. But in certain cases, such as for the table output above, the feature is also used to determine other types of markup (bold headers in this case).

>> feature('HotLinks',0) % temporarily disable bold headers and hyperlinks >> groot ans = Graphics Root with properties: CurrentFigure: [0×0 GraphicsPlaceholder] ScreenPixelsPerInch: 96 ScreenSize: [1 1 1366 768] MonitorPositions: [2×4 double] Units: 'pixels' Use GET to show all properties >> feature('HotLinks',1) % restore the standard behavior (markup displayed) >> groot ans = Graphics Root with properties: CurrentFigure: [0×0 GraphicsPlaceholder] ScreenPixelsPerInch: 96 ScreenSize: [1 1 1366 768] MonitorPositions: [2×4 double] Units: 'pixels' Show all properties

There’s nothing really earth shuttering in all this, but the HotLinks feature could be useful when outputting console output into a diary file. Of course, if diary would have automatically stripped away markup tags we would not need to resort to such hackery. Then again, this is not the only problem with diary, which is long-overdue an overhaul.

The post The HotLinks feature appeared first on Undocumented Matlab.

Related posts:

Undocumented feature() function Matlab's undocumented feature function enables access to some internal experimental features...

Undocumented feature list A list of undocumented MATLAB features can be retrieved. Here's how... ...

Legend '-DynamicLegend' semi-documented feature The built-in Matlab legend function has a very useful semi-documented feature for automatic dynamic update, which is explained here....

Creating a simple UDD class This article explains how to create and test custom UDD packages, classes and objects...

User-defined tab completions – take 2

Yair Altman — Wed, 12 Jul 2017 13:00:30 +0000

Back in 2010, I posted about Matlab’s undocumented mechanism for setting Matlab desktop tab-completions. That mechanism used a couple of internal files (TC.xml and TC.xsd) to describe the various possible options that are auto-completed (or displayed in a small tooltip window) when the user clicks the key on partially-entered function input parameters.

Using TabComplete for user-defined functions

Unfortunately, this mechanism apparently broke in R2016a and was replaced with a new mechanism, as explained below.
The new mechanism relies on a file called functionSignatures.json which exists in every single folder that contains Matlab files that have functions whose input parameters ought to be tab-completable.
The new mechanism offers far greater versatility and flexability in defining the input types and inter-relationsships compared to the old TC.*-based mechanism. Another important benefit is that we can now add custom user-defined functionSignatures.json files to our user folders, next to our m-files, without having to modify any Matlab system file.

Note that you may need to restart Matlab the first time that you create a functionSignatures.json file. But once it’s created, you can modify it within a Matlab session and the changes take effect immediately.
Note: Credit for first posting about this new mechanism goes to Nicholas Mati. I’ve known about this new mechanism for over a year, but I never found the time to write about it until now, so Nicholas gets credit for breaking the scoop. The discussion below uses and expands Nicholas’ original post.

Syntax

The functionSignatures.json file has the general form:

{ "FunctionName1": { "key1":"val1", "key2":"val2", "keyn":"valn" }, "FunctionName2": { "key1":"val1", "key2":"val2", "keyn":"valn" } }

A number of keys are supported including “platform“, “setsAns“, “inputs“, and “outputs“, although inputs and outputs are by far the most common (and presumably only inputs are relevant for tab-completion). These keys take an array of (or a single) object value(s). The objects typically take one of the following forms:

{"name":"variable_name", "kind":"kind_option", "type":"string_or_array_of_type"} {"mutuallyExclusiveGroup": [ ... ] } {"name":"varargin", "kind":"optional", "multiplicity":"append"}

The value for “kind” can be “required”, “optional”, “positional”, “flag”, “namevalue” or “platform” (and perhaps a few other lesser-used kinds):

“required” means that the specified input is mandatory

“optional” means that it can be added or omitted

“positional” means that it’s an optional input but if it is specified then it must appear at the specified position relative to the previous (earlier) inputs

“flag” means that it’s an optional input flag, from a predefined list of one or more single-token strings. For example, in regexp(s1,s2,'once') the last input arg ('once') is such a flag.

“namevalue” means that it follows Matlab’s standard practice of using P-V pairs (parameter name followed by its value). For example, func('propName',propValue)

“platform” indicates that this input is only available on the specified platform(s)

These “kind”s are all explained below.
The value for “type” can be a string such as “char” or “numeric” or “filepath”, or a more complicated JSON array (see below).
In addition to “name”, “kind” and “type”, we can also define a “default” value (e.g. "default":"false") and a “display” string. While these are [currently] not used by Desktop tab-completion, they might be used by other components such as the JIT compiler or the Editor, if not today then perhaps in a future release.
Note that while pure JSON format does not accept comments, Matlab’s functionSignatures.json does accept C++-style comments, as discovered by Heiko in a comment below. To add a comment, simply add // comment text at the end of any line, or /* comment text */ anywhere within a line.

Usage examples

Multiple examples of functionSignatures.json files can be found in subfolders of %matlabroot%/toolbox/matlab. For example, here’s the tab-completion definition for the visdiff function, which displays a visual comparison between two files, and resides in %matlabroot%/toolbox/shared/comparisons/functionSignatures.json:

{ "visdiff": { "inputs": [ {"name":"filename1", "kind":"required", "type":"filepath"}, {"name":"filename2", "kind":"required", "type":"filepath"}, {"name":"type", "kind":"positional", "type":"choices={'text', 'binary'}"} ] } }

As can be seen in this example, the first and second inputs are expected to be a filename, whereas the third input is one of the two predefined strings ‘text’ or ‘binary’. This third input has “kind”:”positional”, meaning that it is optional, but if it is provided then it must be in the 3rd position and cannot appear sooner. Moreover, if the user specifies any input argument to the “right” of a positional input, then the positional argument becomes required, not optional.
Whereas a “positional” parameter has a specific position in the args list (#3 in the case of visdiff above), an “optional” parameter may appear anywhere in the list of inputs.
Here’s a more complex example, for the built-in regexprep function (in %matlabroot%/toolbox/matlab/strfun/functionSignatures.json). This example shows how to limit the input to certain data types and how to specify optional input flags with pre-defined choices:

"regexprep": { "inputs": [ {"name":"str", "kind":"required", "type":[["char"], ["cell"], ["string"]]}, {"name":"expression", "kind":"required", "type":[["char"], ["cell"], ["string"]]}, {"name":"replace", "kind":"required", "type":[["char"], ["cell"], ["string"]]}, {"name":"optMatch", "kind":"flag", "display":"", "type":[["char", "choices={'all','once'}"], ["numeric", "scalar"]], "default":"'all'"}, {"name":"optWarnings", "kind":"flag", "display":"", "type":["char", "choices={'nowarnings','warnings'}"], "default":"'nowarnings'"}, {"name":"optCase", "kind":"flag", "display":"", "type":["char", "choices={'matchcase','ignorecase','preservecase'}"], "default":"'matchcase'"}, {"name":"optEmptyMatch", "kind":"flag", "display":"", "type":["char", "choices={'noemptymatch','emptymatch'}"], "default":"'noemptymatch'"}, {"name":"optDotAll", "kind":"flag", "display":"", "type":["char", "choices={'dotall','dotexceptnewline'}"], "default":"'dotall'"}, {"name":"optStringAnchors", "kind":"flag", "display":"", "type":["char", "choices={'stringanchors','lineanchors'}"], "default":"'stringanchors'"}, {"name":"optSpacing", "kind":"flag", "display":"", "type":["char", "choices={'literalspacing','freespacing'}"], "default":"'literalspacing'"} ], "outputs": [ {"name":"newStr", "type":[["char"], ["cell"], ["string"]]} ] },

Here’s an even more complex example, this time for the codegen function (in %matlabroot%/toolbox/coder/matlabcoder/functionSignatures.json, part of the Matlab Coder toolbox). This example shows how to limit the filenames to certain extensions and how to specify name-value input pairs:

"codegen": { "inputs": [ {"name":"compile_only", "kind":"flag", "type":"choices={'-c'}"}, {"name":"config_flag", "kind":"flag", "type":"choices={'-config:mex','-config:lib','-config:dll','-config:exe','-config:hdl'}"}, {"name":"debug", "kind":"flag", "type":"choices={'-g'}"}, {"name":"report", "kind":"flag", "type":"choices={'-report'}"}, {"name":"launchreport", "kind":"flag", "type":"choices={'-launchreport'}"}, {"name":"file", "kind":"flag", "type":"filepath=*.m,*.mlx,*.c,*.cpp,*.h,*.o,*.obj,*.a,*.so,*.lib,*.tmf", "multiplicity":"append"}, {"name":"-d", "kind":"namevalue", "type":"folderpath"}, {"name":"-I", "kind":"namevalue", "type":"folderpath"}, {"name":"-globals", "kind":"namevalue"}, {"name":"-o", "kind":"namevalue", "type":[["char"], ["filepath"]]}, {"name":"-O", "kind":"namevalue", "type":"choices={'enable:inline','disable:inline','enable:blas','disable:blas','enable:openmp','disable:openmp'}"}, {"name":"-args", "kind":"namevalue", "type":[["identifier=variable"], ["char"]]}, {"name":"-config", "kind":"namevalue", "type":[["identifier=variable"], ["char"]]}, {"name":"verbose", "kind":"flag", "type":"choices={'-v'}"}, {"name":"singleC", "kind":"flag", "type":"choices={'-singleC'}"}, {"name":"-test", "kind":"namevalue", "type":"identifier=function"} ] },

Argument types

As noted above, we use "type":... to specify the expected data type of each parameter. This can be a simple string such as “char”, “cellstr”, “numeric”, “table”, “categorical”, “filepath”, “folderpath”, “matlabpath”, class name, or a more complicated JSON array. For example:

"type":["numeric","scalar"]

"type":["numeric","numel=3",">=4"]

"type":[["char"], ["cellstr"], ["numeric"], ["logical","vector"]]

"type":[["char", "choices={'-ascii'}"]]

"type":[["filepath"], ["matlabpath=*.m,*.mlx"], ["char"]]

"type":"identifier=variable,function,localfunction,package,classdef"

"type":"matlab.graphics.axis.Axes"

"type":"choices={'yes','no','maybe'}"

We can even specify on-the-fly Matlab computation that returns a cell-array of values, for example a list of available fonts via "type":"choices=listfonts". A more complex example is the definition of the rmfield function, where the possible input choices for the second input arg (highlighted) depend on the struct that is provided in the first input arg (by running the fieldnames function on it):

"rmfield": { "inputs": [ {"name":"s", "kind":"required", "type":"struct"}, {"name":"field", "kind":"required", "type":"choices=fieldnames(s)"} ], "outputs": [ {"name":"s", "type":"struct"} ] },

Alternative inputs

Multiple alternative inputs can be specified in the functionSignatures.json file. The easiest way to do so is to simply create multiple different definitions for the same function, one beneath the other. Matlab’s tab-completion parser is smart enough to combine those definitions and proceed with the most appropriate one based on the user-entered inputs.
For example, in the same Coder file above we find 6 alternative definitions. If (for example) we start typing coder('-ecoder', and click , Matlab would automatically auto-complete the second input to “false”, and then another click would set the third input to the required ‘-new’ parameter (see highlighted lines below):

... "coder": { "inputs": [ {"name":"projectname", "kind":"required", "type":"filepath=*.prj"} ] }, "coder": { "inputs": [ {"name":"-open", "kind":"namevalue", "type":"filepath=*.prj"} ] }, "coder": { "inputs": [ {"name":"-build", "kind":"namevalue", "type":"filepath=*.prj"} ] }, "coder": { "inputs": [ {"name":"-new", "kind":"namevalue", "type":[["filepath=*.prj"], ["char"]]} ] }, "coder": { "inputs": [ {"name":"ecoderFlag", "kind":"required", "type":"choices={'-ecoder'}"}, {"name":"ecoderValue", "kind":"required", "type":[["logical"], ["choices={'false'}"]]}, {"name":"newFlag", "kind":"required", "type":"choices={'-new'}"}, {"name":"newvalue", "kind":"required", "type":[["filepath=*.prj"], ["char"]]} ] }, "coder": { "inputs": [ {"name":"tocodeFlag", "kind":"required", "type":"choices={'-tocode'}"}, {"name":"tocodevalue", "kind":"required", "type":"filepath=*.prj"}, {"mutuallyExclusiveGroup": [ [], [ {"name":"scriptFlag", "kind":"required", "type":"choices={'-script'}"}, {"name":"scriptname", "kind":"required", "type":[["filepath=*.m"], ["char"]]} ] ] } ] }

This example also shows, in the last definition for the coder function, another mechanism for specifying alternative inputs, using “mutuallyExclusiveGroup” (aka “MEGs”). A MEG is defined using an array of options, enclosed in square brackets ([]). Each of the MEG options is exclusive to each of the others, meaning that we can only work with one of them and not the others. This is equivalent to duplicating the definition as we saw above, and saves us some copy-paste (in some cases a lot of copy-pastes, especially with multiple and/or nested MEGs). However, MEGs have a major drawback of reduced readability. I believe that in most cases we only have a single MEG and few input args, and in such cases it makes more sense to use repeated function defs rather than a MEG. The Matlab signature files contain numerous usage examples for either of these two mechanisms.

Platform dependencies

If a specific function (or a specific signature variant) depends on the running platform, this can be specified via the “platform” directive. For example, the winopen function only works on Windows, but not on Linux/Mac. Its corresponding signature definition is:

"winopen": { "platform":"win32,win64", "inputs": [ {"name":"filename", "kind":"required", "type":"filepath"}, {"name":"varargin", "kind":"optional", "multiplicity":"append"} ] }

Platform dependence could also be specified at the parameter level, not just the entire function level. For example, in the xlsread function (defined in %matlabroot%/toolbox/matlab/iofun/functionSignatures.json), we see that the usage variant xlsread(filename,-1) is only available on Windows (note that the numeric value is defined as "<=-1", not necessarily -1), and so is the “functionHandle” input (which is called processFcn in the documentation – for some reason that escapes me the names of many input args do not match in the documentation and functionSignature):

"xlsread": { "inputs": [ {"name":"filename", "kind":"required", "type":"filepath=*.xls,*.xlsx,*.xlsb,*.csv"}, {"mutuallyExclusiveGroup": [ {"name":"openExcel", "kind":"required", "display":"", "type":["numeric", "<=-1"], "platform":"win64,win32"}, {"name":"xlRange", "kind":"required", "type":["char", "@(x) isempty(x) || ~isempty(strfind(x, ':'))"], "default":"''"}, [ {"name":"sheet", "kind":"positional", "type":[["char", "choices=matlab.internal.language.introspective.tabcompletion.xlsread_vsheet(filename)"], ["numeric", ">=1"]], "default":"1"}, {"name":"xlRange", "kind":"positional", "type":"char", "default":"''"}, {"name":"basic", "kind":"positional", "display":"", "type":["char", "choices={'basic',''}"]}, {"name":"functionHandle", "kind":"positional", "type":"function_handle", "platform":"win64,win32"} ] ] } ], ...

Parsing errors

The new mechanism is not very user-friendly when you get something wrong. In the best case, it issues a cryptic error message (see below), and in the worst case it simply ignores the changes and the user has no idea why the new custom tab-completion is not working as intended.
The most likely causes of such problems are:

The most common problem is that you placed the functionSignatures.json file in a different folder than the Matlab function. For example, if the myFunction() function is defined in myFunction.m, then the tab-completion of this function MUST be located in a functionSignatures.json file that resides in the same folder, not anywhere else on the Matlab path. In other words, the Matlab path is NOT relevant for tab-completion.

Your functionSignatures.json file does not follow the [extremely strict] syntax rules above, to the letter. For example, forgetting the top or final curly braces, forgetting a comma or adding an extra one, or not closing all brackets/braces properly.

You mistyped one or more of the input parameters, types or options.

In case of a parsing error, you’d see a red error message on the Matlab console the next time that you try to use tab-completion:
Error parsing JSON data; Boost reports "(189): expected ',' or ']'".
Unfortunately the error message only tells us the problematic line location within the functionSignatures.json file, but not the file’s location, so if we haven’t recently edited this file we’d need to find it in the relevant folder. For example:

edit(fullfile(fileparts(which('myFunction')), 'functionSignatures.json')

Moreover, when a JSON syntax error (such as the one above) occurs, the entire file is not parsed, not just the definition that caused the error.
Another limitation of tab-completion is that it does not work while the main Matlab thread is working (e.g., during a uiwait or waitfor). This may be somewhat misleading since most editor/debugging actions do work.
Arguably, this new tab-completion mechanism could be made more programmer-friendly. Perhaps this will improve in a future Matlab release.
Addendum: MathWorks has now made this functionality supported and documented. Read about it here.
For a related mechanism, see my article on tab-completion for class properties and methods from 2014, which is apparently still relevant and functional.

The post User-defined tab completions – take 2 appeared first on Undocumented Matlab.

Related posts:

Setting desktop tab completions The Matlab desktop's Command-Window tab-completion can be customized for user-defined functions...

Enabling user callbacks during zoom/pan Matlab zoom, pan and rotate3d modes hijack the user's figure callbacks, but this can be overridden. ...

Removing user preferences from deployed apps An unsupported MathWorks Technical Solution explains how to remove private information from deployed (compiled) matlab applications. ...

Creating a simple UDD class This article explains how to create and test custom UDD packages, classes and objects...

Working with non-standard DPI displays

Yair Altman — Wed, 09 Nov 2016 21:47:27 +0000

With high-density displays becoming increasingly popular, some users set their display’s DPI to a higher-than-standard (i.e., >100%) value, in order to compensate for the increased pixel density to achieve readable interfaces. This OS setting tells the running applications that there are fewer visible screen pixels, and these are spread over a larger number of physical pixels. This works well for most cases (at least on recent OSes, it was a bit buggy in non-recet ones). Unfortunately, in some cases we might actually want to know the screen size in physical, rather than logical, pixels. Apparently, Matlab root’s ScreenSize property only reports the logical (scaled) pixel size, not the physical (unscaled) one:

>> get(0,'ScreenSize') % with 100% DPI (unscaled standard) ans = 1 1 1366 768 >> get(0,'ScreenSize') % with 125% DPI (scaled) ans = 1 1 1092.8 614.4

The same phenomenon also affects other related properties, for example MonitorPositions.
Raimund Schlüßler, a reader on this blog, was kind enough to point me to this problem and its workaround, which I thought worthy to share here: To get the physical screen-size, use the following builtin Java command:

>> jScreenSize = java.awt.Toolkit.getDefaultToolkit.getScreenSize jScreenSize = java.awt.Dimension[width=1366,height=768] >> width = jScreenSize.getWidth width = 1366 >> height = jScreenSize.getHeight height = 768

Also see the related recent article on an issue with the DPI-aware feature starting with R2015b.

Upcoming travels – London/Belfast, Zürich & Geneva

I will shortly be traveling to consult some clients in Belfast (via London), Zürich and Geneva. If you are in the area and wish to meet me to discuss how I could bring value to your work, then please email me (altmany at gmail):

Belfast: Nov 28 – Dec 1 (flying via London)

Zürich: Dec 11-12

Geneva: Dec 13-15

The post Working with non-standard DPI displays appeared first on Undocumented Matlab.

Related posts:

Customizing the standard figure toolbar, menubar The standard figure toolbar and menubar can easily be modified to include a list of recently-used files....

Customizing figure toolbar background Setting the figure toolbar's background color can easily be done using just a tiny bit of Java magic powder. This article explains how. ...

Faster findjobj the ubiquitous findjobj utility has been significantly improved for speed for the most common use case. ...

FindJObj – find a Matlab component's underlying Java object The FindJObj utility can be used to access and display the internal components of Matlab controls and containers. This article explains its uses and inner mechanism....

Handling red Java console errors

Yair Altman — Wed, 29 Jun 2016 17:00:51 +0000

Anyone who has worked with non-trivial Matlab GUIs knows that from time to time we see various red Java stack-trace errors appear in the Matlab console (Command Window). These errors do not appear often when using documented Matlab controls, but they do from time to time. The errors appear significantly more frequently when working with undocumented Java-based hacks that I often show on this blog, and especially when working with complex controls such as uitable or uitree. Such controls have a very large code-base under the hood, and the Matlab code and data sometimes clashes with the asynchronous Java methods that run on a separate thread. Such clashes and race conditions often lead to red Java stack-trace errors that are spewed onto the Matlab console. For example:

Exception in thread "AWT-EventQueue-0" java.lang.NullPointerException at com.jidesoft.plaf.basic.BasicCellSpanTableUI.paint(Unknown Source) at javax.swing.plaf.ComponentUI.update(Unknown Source) at javax.swing.JComponent.paintComponent(Unknown Source) at com.jidesoft.grid.CellStyleTable.paintComponent(Unknown Source) at javax.swing.JComponent.paint(Unknown Source) at javax.swing.JComponent.paintToOffscreen(Unknown Source) ... Exception in thread "AWT-EventQueue-0" java.lang.ArrayIndexOutOfBoundsException: 1 >= 0 at java.util.Vector.elementAt(Unknown Source) at javax.swing.table.DefaultTableColumnModel.getColumn(Unknown Source) at com.jidesoft.grid.ContextSensitiveTable.getCellRenderer(Unknown Source) at com.jidesoft.grid.CellSpanTable.getCellRenderer(Unknown Source) at com.jidesoft.grid.TreeTable.getActualCellRenderer(Unknown Source) at com.jidesoft.grid.GroupTable.getCellRenderer(Unknown Source) at com.jidesoft.grid.JideTable.b(Unknown Source) at com.jidesoft.grid.CellSpanTable.calculateRowHeight(Unknown Source) ...

In almost all such Java error messages, the error is asynchronous to the Matlab code and does not interrupt it. No error exception is thrown (or can be trapped), and the Matlab code proceeds without being aware that anything is wrong. In fact, in the vast majority of such cases, nothing is visibly wrong – the program somehow overcomes the reported problem and there are no visible negative effects on the GUI. In other words, these error messages are harmless and can almost always be ignored. Still, if we could only stop those annoying endless red stack-trace messages in the Matlab console!

Note that today’s post only discusses untrappable asynchronous Java error messages, not synchronous errors that can be trapped in Matlab via try-catch. These synchronous errors are often due to programmatic errors (e.g., bad method input args or an empty reference handle) and can easily be handled programmatically. On the other hand, the asynchronous errors are non-trappable, so they are much more difficult to isolate and fix.
In many of the cases, the error occurs when the control’s underlying data model is changed by the Matlab code, and some of the controls’s Java methods are not synced with the new model by the time they run. This can be due to internal bugs in the Matlab or Java control’s implementation, or to simple race conditions that occur between the Matlab thread and the Java Event Dispatch Thread (EDT). As noted here, such race conditions can often be solved by introducing a simple delay into the Matlab code:

javaControl.doSomething(); pause(0.05); drawnow; javaControl.doSomethingElse();

In addition, asking Matlab to run the Java component’s methods on the EDT can also help solve race conditions:

javaControl = javaObjectEDT(javaControl);

Unfortunately, sometimes both of these are not enough. In such cases, one of the following ideas might help:

Add fprintf(' \b') to your Matlab code: this seemingly innocent hack of displaying a space & immediately erasing it with backspace, appears to force the Java engine to flush its event queue and synchronize things, thereby avoiding the annoying Java console errors. I know it sounds like adding a sprinkle of useless black magic to the code, but it does really work in some cases!
javaControl.doSomething(); pause(0.05); drawnow; % this never hurt anyone! fprintf(' \b'); javaControl.doSomethingElse();

It is also possible to directly access the console text area and remove all the text after a certain point. Note that I strongly discourage messing around with the console text in this manner, since it might cause problems with Matlab’s internals. Still, if you are adventurous enough to try, then here’s an example:
jCmdWinDoc = com.mathworks.mde.cmdwin.CmdWinDocument.getInstance; currentPos = cmdWinDoc.getLength; javaControl.doSomething(); pause(0.05); drawnow; % this never hurt anyone! javaControl.doSomethingElse(); pause(0.1); % let the java error time to display itself in the console jCmdWinDoc.remove(currentPos, cmdWinDoc.getLength-currentPos);

When all else fails, consider simply clearing the Matlab console using the Matlab clc command a short while after updating the Java control. This will erase the red Java errors, along with everything else in the console, so naturally it cannot be freely used if you use the console to display useful information to the user.

It should be emphasized: not all of these suggested remedies work in all cases; in some cases some of them work, and in other cases others might work. There does not seem to be a general panacea to this issue. The main purpose of the article was to list the possible solutions in a single place, so that users could try them out and select those that work for each specific case.
Do you know of any other (perhaps better) way of avoiding or hiding such asynchronous Java console errors? If so, then please post a comment below.

The post Handling red Java console errors appeared first on Undocumented Matlab.

Related posts:

Converting Java vectors to Matlab arrays Converting Java vectors to Matlab arrays is pretty simple - this article explains how....

Matlab callbacks for Java events in R2014a R2014a changed the way in which Java objects expose events as Matlab callbacks. ...

The Java import directive The import function can be used to clarify Java code used in Matlab. ...

Using Java Collections in Matlab Java includes a wide selection of data structures that can easily be used in Matlab programs - this article explains how. ...

Viewing saved profiling results

Yair Altman — Wed, 18 May 2016 18:00:37 +0000

Many Matlab users know and utilize Matlab’s built-in Profiler tool to identify performance bottlenecks and code-coverage issues. Unfortunately, not many are aware of the Profiler’s programmatic interface. In past articles as well as my performance book I explained how we can use this programmatic interface to save profiling results and analyze it offline. In fact, I took this idea further and even created a utility (profile_history) that displays the function call timeline in a standalone Matlab GUI, something that is a sorely missed feature in the built-in profiler:

Function call timeline profiling (click for full-size image)
Today I will discuss a related undocumented feature of the Profiler: loading and viewing pre-saved profiling results.

Programmatic access to profiling results

Matlab’s syntax for returning the detailed profiling results in a data struct is clearly documented in the profile function’s doc page. Although the documentation does not explain the resulting struct and sub-struct fields, they have meaningful names and we can relatively easily infer what each of them means (I added a few annotation comments for clarity):

>> profile('on','-history') >> surf(peaks); drawnow >> profile('off') >> profData = profile('info') profData = FunctionTable: [26x1 struct] FunctionHistory: [2x56 double] ClockPrecision: 4.10517962829241e-07 ClockSpeed: 2501000000 Name: 'MATLAB' Overhead: 0 >> profData.FunctionTable(1) ans = CompleteName: 'C:\Program Files\Matlab\R2016a\toolbox\matlab\specgraph\peaks.m>peaks' FunctionName: 'peaks' FileName: 'C:\Program Files\Matlab\R2016a\toolbox\matlab\specgraph\peaks.m' Type: 'M-function' Children: [1x1 struct] Parents: [0x1 struct] ExecutedLines: [9x3 double] IsRecursive: 0 TotalRecursiveTime: 0 PartialData: 0 NumCalls: 1 TotalTime: 0.0191679078068094 >> profData.FunctionTable(1).Children ans = Index: 2 % index in profData.FunctionTable array NumCalls: 1 TotalTime: 0.00136415141013509 >> profData.FunctionTable(1).ExecutedLines % line number, number of calls, duration in secs ans = 43 1 0.000160102031282782 44 1 2.29890096200918e-05 45 1 0.00647592190637408 56 1 0.0017093970724654 57 1 0.00145036019621044 58 1 0.000304193859437286 60 1 4.39254290955326e-05 62 1 3.44835144301377e-05 63 1 0.000138755093778411 >> profData.FunctionHistory(:,1:5) ans = 0 0 1 1 0 % 0=enter, 1=exit 1 2 2 1 6 % index in profData.FunctionHistory array

As we can see, this is pretty intuitive so far.

Loading and viewing saved profiling results

If we wish to save these results results in a file and later load and display them in the Profiler’s visualization browser, then we need to venture deeper into undocumented territory. It seems that while retrieving the profiling results (via profile(‘info’)) is fully documented, doing the natural complementary action (namely, loading this data into the viewer) is not. For the life of me I cannot understand the logic behind this decision, but that’s the way it is.
Luckily, the semi-documented built-in function profview does exactly what we need: profview accepts 2 input args (function name and the profData struct) and displays the resulting profiling info. The first input arg (function name) accepts either a string (e.g., 'peaks' or 'view>isAxesHandle'), or the numeric value 0 which signifies the home (top-level) page:

profView(0, profData); % display profiling home (top-level) page profview('peaks', profData); % display a specific profiling page

I use the 0 input value much more frequently than the string inputs, because I often don’t know which functions exactly were profiled, and starting at the home page enables me to easily drill-down the profiling results interactively.

Loading saved profiling results from a different computer

Things get slightly complicated if we try to load saved profiling results from a different computer. If the other computer has exactly the same folder structure as our computer, and all our Matlab functions reside in exactly the same disk folders/path, then everything will work out of the box. The problem is that in general the other computer will have the functions in different folders. When we then try to load the profData on our computer, it will not find the associated Matlab functinos in order to display the line-by-line profiling results. We will only see the profiling data at the function level, not line level. This significantly reduces the usefulness of the profiling data. The Profiler page will display the following error message:

This file was modified during or after profiling. Function listing disabled.
We can solve this problem in either of two ways:

Modify our profData to use the correct folder path on the local computer, rather than the other computer’s path (which is invalid on the local computer). For example:
% Save the profData on computer #1: profData = profile('info'); save('profData.mat', 'profData'); % Load the profData on computer #2: fileData = load('profData.mat'); profData = fileData.profData; path1 = 'N:\Users\Juan\programs\myProgram'; path2 = 'C:\Yair\consulting\clients\Intel\code'; for idx = 1 : numel(profData.FunctionTable) funcData = profData.FunctionTable(idx); funcData.FileName = strrep(funcData.FileName, path1, path2); funcData.CompleteName = strrep(funcData.CompleteName, path1, path2); profData.FunctionTable(idx) = funcData; end % note: this loop can be vectorized if you wish

As an alternative, we can modify Matlab’s profview.m function (%matlabroot%/toolbox/matlab/codetools/profview.m) to search for the function’s source code in the current Matlab path, if the specified direct path is not found (note that changing profview.m may require administrator priviledges). For example, the following is the code from R2016a’s profview.m file, line #506:
% g894021 - Make sure the MATLAB code file still exists if ~exist(fullName, 'file') [~,fname,fext] = fileparts(fullName); % Yair fname = which([fname fext]); % Yair if isempty(fname) % Yair mFileFlag = 0; else % Yair fullName = fname; % Yair end % Yair end

These two workarounds complement each other: the first workaround does not require changing any installed Matlab code, and so is platform- and release-independent, but would require rerunning the code snippet for each and every profiling data file that we receive from external computers. On the other hand, the second workaround is a one-time operation that should work for multiple saved profiling results, although we would need to redo it whenever we install Matlab.

Additional profview customizations

Modifying the profview.m function can be used for different improvements as well.
For example, several years ago I explained how this function can be modified to display 1 ms timing resolutions, rather than the default 10 mS.
Another customization that I often do after I install Matlab is to change the default setting of truncating function lines longer than 40 characters – I typically modify this to 60 or 80 (depending on the computer monitor’s size…). All we need to do is to update the truncateDisplayName sub-function within profview.m as follows (taken from R2016a again, line #1762):

function shortFileName = truncateDisplayName(longFileName,maxNameLen) %TRUNCATEDISPLAYNAME Truncate the name if it gets too long maxNameLen = max(60,maxNameLen); % Yair shortFileName = escapeHtml(longFileName); if length(longFileName) > maxNameLen, shortFileName = char(com.mathworks.util.FileUtils.truncatePathname( ... shortFileName, maxNameLen)); end

You can see additional undocumented profiling features in the “Related posts” section below, as well as in Chapter 2 of my book “Accelerating MATLAB Performance“.
Do you have any other customization to the profiling results? If so, please share it in a comment.

The post Viewing saved profiling results appeared first on Undocumented Matlab.

Related posts:

Function call timeline profiling A new utility enables to interactively explore Matlab function call timeline profiling. ...

Profiling Matlab memory usage mtic and mtoc were a couple of undocumented features that enabled users of past Matlab releases to easily profile memory usage. ...

Undocumented Profiler options part 4 Several undocumented features of the Matlab Profiler can make it much more useful - part 4 of series. ...

Undocumented Profiler options part 3 An undocumented feature of the Matlab Profiler can report call history timeline - part 3 of series. ...

Programmatic shortcuts manipulation – part 2

Yair Altman — Wed, 30 Dec 2015 16:42:52 +0000

Today I will expand last week’s post on customizing Matlab Desktop’s shortcuts. I will show that we can incorporate non-standard controls, and add tooltips and user callbacks in undocumented ways that are not available using the interactive Desktop GUI.

Custom shortcut controls

Today’s article will focus on the new toolstrip interface of Matlab release R2012b and later; adaptation of the code to R2012a and earlier is relatively easy (in fact, simpler than the toolstrip-based code below).

Displaying the Shortcuts panel

Before we begin to modify shortcuts in the Toolstrip’s shortcuts menu, we need to ensure that the Shortcuts panel is visible and active (in current focus), otherwise our customizations will be ignored or cause an error. There is probably a more direct way of doing this, but a simple way that I found was to edit the current Desktop’s layout to include a directive to display the Shortcuts tab, and then load that layout:

jDesktop = com.mathworks.mde.desk.MLDesktop.getInstance; hMainFrame = com.mathworks.mde.desk.MLDesktop.getInstance.getMainFrame; jToolstrip = hMainFrame.getToolstrip; isOk = jToolstrip.setCurrentTab('shortcuts'); if ~isOk % i.e., Shortcuts tab is NOT displayed % Save the current Desktop layout jDesktop.saveLayout('Yair'); pause(0.15); % Update the layout file to display the Shortcuts tab filename = fullfile(prefdir, 'YairMATLABLayout.xml'); fid = fopen(filename, 'rt'); txt = fread(fid, '*char')'; fclose(fid); txt = regexprep(txt,'(ShowShortcutsTab=)"[^"]*"',''); txt = regexprep(txt,'(]*)>','$1 ShowShortcutsTab="yes">'); fid = fopen(filename, 'wt'); fwrite(fid,txt); fclose(fid); % Load the modified layout jDesktop.restoreLayout('Yair'); pause(0.15); % The shortcuts tab should now be visible, so transfer focus to that tab jToolstrip.setCurrentTab('shortcuts'); end

Custom controls

As I explained in last week’s post, we can use scUtils.addShortcutToBottom to add a simple push-button shortcut to the relevant category panel within the Shortcuts toolstrip tab. To add custom controls, we can simply add the controls to the relevant shortcut category panel container (a com.mathworks.toolstrip.components.TSPanel object). The standard shortcuts are typically placed in the Shortcuts tab’s second TSPanel (“general”), and other categories have TSPanels of their own.
Now here’s the tricky part about TSPanels: we cannot directly add components to the sectino panel (that would be too easy…): the section panels are composed of an array of internal TSPanels, and we need to add the new controls to those internal panels. However, these panels only contain 3 empty slots. If we try to add more than 3 components, the 4th+ component(s) will simply not be displayed. In such cases, we need to create a new TSPanel to display the extra components.
Here then is some sample code to add a combo-box (drop-down) control:

% First, get the last internal TSPanel within the Shortcuts tab's "general" section panel % Note: jToolstrip was defined in the previous section above jShortcutsTab = jToolstrip.getModel.get('shortcuts').getComponent; jSectionPanel = jShortcutsTab.getSectionComponent(1).getSection.getComponent; % the TSPanel object "general" jContainer = jSectionPanel.getComponent(jSectionPanel.getComponentCount-1); % If the last internal TSPanel is full, then prepare a new internal TSPanel next to it if jContainer.getComponentCount >= 3 % Create a new empty TSPanel and add it to the right of the last internal TSPanel jContainer = com.mathworks.toolstrip.components.TSPanel; jContainer.setPreferredSize(java.awt.Dimension(100,72)); jSectionPanel.add(jContainer); jSectionPanel.repaint(); jSectionPanel.revalidate(); end % Create the new control with a custom tooltip and callback function optionStrings = {'Project A', 'Project B', 'Project C'}; jCombo = com.mathworks.toolstrip.components.TSComboBox(optionStrings); jCombo = handle(javaObjectEDT(jCombo), 'callbackproperties')); set(jCombo, 'ActionPerformedCallback', @myCallbackFunction); jCombo.setToolTipText('Select the requested project'); % Now add the new control to the internal TSPanel jContainer.add(jCombo); jContainer.repaint(); jContainer.revalidate();

Custom shortcut controls

Matlab’s internal com.mathworks.toolstrip.components package contains many embeddable controls, including the following (I emphasized those that I think are most useful within the context of the Shortcuts panel): TSButton, TSCheckBox, TSComboBox, TSDropDownButton (a custom combo-box component), TSFormattedTextField, TSLabel, TSList, TSRadioButton, TSScrollPane, TSSlider, TSSpinner, TSSplitButton, TSTextArea, TSTextField, and TSToggleButton. These controls are in most cases simple wrappers of the corresponding Java Swing controls. For example, TSSpinner extends the standard Swing JSpinner control. In some cases, the controls are more complex: for example, the TSSplitButton is similar to Matlab’s uisplittool control.

Toolstrip controls

In fact, these controls can be used even outside the toolstrip, embedded directly in our Matlab figure GUI, using the javacomponent function. For example:

dataModel = javax.swing.SpinnerNumberModel(125, 15, 225, 0.5); % defaultValue, minValue, maxValue, stepSize jSpinner = com.mathworks.toolstrip.components.TSSpinner(dataModel); jSpinner = handle(javaObjectEDT(jSpinner), 'CallbackProperties'); [hjSpinner, hContainer] = javacomponent(jSpinner, [10,10,60,20], gcf);

You can find additional interesting components within the %matlabroot%/java/jar/toolstrip.jar file, which can be opened in any zip file utility or Java IDE. In fact, whatever controls that you see Matlab uses in its Desktop toolstrip (including galleries etc.) can be replicated in custom tabs, sections and panels of our own design.
Matlab Desktop’s interactive GUI only enables creating simple push-button shortcuts having string callbacks (that are eval‘ed in run-time). Using the undocumented programmatic interface that I just showed, we can include more sophisticated controls, as well as customize those controls in ways that are impossible via the programmatic GUI: add tooltips, set non-string (function-handle) callbacks, enable/disable controls, modify icons in run-time etc.
For example (intentionally showing two separate ways of setting the component properties):

% Toggle-button jTB = handle(javaObjectEDT(com.mathworks.toolstrip.components.TSToggleButton('Toggle button')), 'CallbackProperties') jTB.setSelected(true) jTB.setToolTipText('toggle me!') jTB.ActionPerformedCallback = @(h,e)doSomething(); jContainer.add(jTB); % Check-box jCB = handle(javaObjectEDT(com.mathworks.toolstrip.components.TSCheckBox('selected !')), 'CallbackProperties'); set(jCB, 'Selected', true, 'ToolTipText','Please select me!', 'ActionPerformedCallback',{@myCallbackFunction,extraData}); jContainer.add(jCB);

(resulting in the screenshot at the top of this post)
Important note: none of these customizations is saved to file. Therefore, they need to be redone programmatically for each separate Matlab session. You can easily do that by calling the relevant code in your startup.m file.
If you wish me to assist with any customization of the Desktop shortcuts, or any other Matlab aspect, then contact me for a short consultancy.
Happy New Year everybody!

The post Programmatic shortcuts manipulation – part 2 appeared first on Undocumented Matlab.

Related posts:

Programmatic shortcuts manipulation – part 1 Matlab Desktop shortcuts can be programmatically accessed and customized. ...

Command Window text manipulation Special control characters can be used to format text output in Matlab's Command Window. ...

Matlab toolstrip – part 5 (icons) Icons can be specified in various ways for toolstrip controls and the app window itself. ...

Matlab toolstrip – part 4 (control customization) Matlab toolstrip components (controls) can be customized in various ways, including user-defined callbacks. ...

Programmatic shortcuts manipulation – part 1

Yair Altman — Wed, 23 Dec 2015 11:08:05 +0000

User-defined shortcuts can interactively be added to the Matlab Desktop to enable easy access to often-used scripts (e.g., clearing the console, running a certain program, initializing data etc.). Similarly, we can place shortcuts in the help browser to quickly access often-used pages. Unfortunately, both of these shortcut functionalities, like many other functionalities of the Matlab Desktop and related tools (Editor, Browser, Profiler etc.), have no documented programmatic access.
Such programmatic access is often useful. For example, a large company for which I consult is using centralized updates to users’ shortcuts, in order to manage and expose new features for all Matlab users from a central location. It is easy to send updates and manage a few users, but when your organization has dozens of Matlab users, centralized management becomes a necessity. It’s a pity that companies need to resort to external consultants and undocumented hacks to achieve this, but I’m not complaining since it keeps me occupied…

Shortcuts in Matlab R2012a and earlier

Shortcuts in Matlab R2012b and newer

Today’s post will describe “regular” shortcuts – those that are simple clickable buttons. Next week I will show how we can extend this to incorporate other types of shortcut controls, as well as some advanced customizations.

The shortcuts.xml file

It turns out that the shortcults toolbar (on R2012a and earlier) or toolstrip group (on R2012b onward) is a reflection of the contents of the [prefdir ‘\shortcuts.xml’] file (depending on your version, the file might be named somewhat differently, i.e. shortcuts_2.xml). This file can be edited in any text editor, Matlab’s editor included. So a very easy way to programmatically affect the shortcuts is to update this file. Here is a sample of this file:

My Shortcuts Help Browser Favorites Help Using the Desktop Help icon helpview([docroot '/mapfiles/matlab_env.map'], 'matlabenvironment_desktop'); true CSSM Help icon disp('No callback specified for this shortcut') true UndocML MATLAB icon web('undocumentedMatlab.com') true My favorite program C:\Yair\program\icon.gif cd('C:\Yair\program'); myProgram(123); true ...

The file is only loaded once during Matlab startup, so any changes made to it will only take effect after Matlab restarts.

Updating the shortcuts in the current Matlab session

We can update the shortcuts directly, in the current Matlab session, using the builtin com.mathworks.mlwidgets.shortcuts.ShortcutUtils class. This class has existed largely unchanged for numerous releases (at least as far back as R2008b).
For example, to add a new shortcut to the toolbar:

name = 'My New Shortcut'; cbstr = 'disp(''My New Shortcut'')'; % will be eval'ed when clicked iconfile = 'c:\path\to\icon.gif'; % default icon if it is not found isEditable = 'true'; scUtils = com.mathworks.mlwidgets.shortcuts.ShortcutUtils; category = scUtils.getDefaultToolbarCategoryName; scUtils.addShortcutToBottom(name,cbstr,iconfile,category,isEditable);

The shortcut’s icon can either be set to a specific icon filepath (e.g., ‘C:\Yair\program\icon.jpg’), or to one of the predefined names: ‘Help icon’, ‘Standard icon’, ‘MATLAB icon’ or ‘Simulink icon’. The editable parameter does not seem to have a visible effect that I could see.
The category name can either be set to the default name using scUtils.getDefaultToolbarCategoryName (‘Shortcuts’ on English-based Matlab R2012b onward), or it can be set to any other name (e.g., ‘My programs’). To add a shortcut to the Help Browser (also known as a “Favorite”), simply set the category to scUtils.getDefaultHelpCategoryName (=’Help Browser Favorites’ on English-based Matlab installations); to add the shortcut to the ‘Start’ button, set the category to ‘Shortcuts’. When you use a non-default category name on R2012a and earlier, you will only see the shortcuts via Matlab’s “Start” button (as seen in the screenshot below); on R2012b onward you will see it as a new category group within the Shortcuts toolstrip (as seen in the screenshot above). For example:

scUtils = com.mathworks.mlwidgets.shortcuts.ShortcutUtils; scUtils.addShortcutToBottom('clear', 'clear; clc', 'Standard icon', 'Special commands', 'true');

Custom category in Matlab R2010a

To remove a shortcut, use the removeShortcut(category,shortcutName) method (note: this method does not complain if the specified shortcut does not exist):

scUtils.removeShortcut('Shortcuts', 'My New Shortcut');

The addShortcutToBottom() method does not override existing shortcuts. Therefore, to ensure that we don’t add duplicate shortcuts, we must first remove the possibly-existing shortcut using removeShortcut() before adding it. Since removeShortcut() does not complain if the specific shortcut is not found, we can safely use it without having to loop over all the existing shortcuts. Alternately, we could loop over all existing category shortcuts checking their label, and adding a new shortcut only if it is not already found, as follows:

scUtils = com.mathworks.mlwidgets.shortcuts.ShortcutUtils; category = scUtils.getDefaultToolbarCategoryName; scVector = scUtils.getShortcutsByCategory(category); scArray = scVector.toArray; % Java array foundFlag = 0; for scIdx = 1:length(scArray) scName = char(scArray(scIdx)); if strcmp(scName, 'My New Shortcut') foundFlag = 1; break; % alternatively: scUtils.removeShortcut(category, scName); end end if ~foundFlag scUtils.addShortcutToBottom(scName, callbackString, iconString, category, 'true'); end

As noted above, we can add categories by simply specifying a new category name in the call to scUtils.addShortcutToBottom(). We can also add and remove categories directly, as follows (beware: when removing a category, it is removed together with all its contents):

scUtils.addNewCategory('category name'); scUtils.removeShortcut('category name', []); % entire category will be deleted

Shortcut tools on the Matlab File Exchange

Following my advice on StackOverflow back in 2010, Richie Cotton wrapped the code snippets above in a user-friendly utility (set of independent Matlab functions) that can now be found on the Matlab File Exchange and on his blog. Richie tested his toolbox on Matlab releases as old as R2008b, but the functionality may also work on even older releases.

Shortcuts panel embedded in Matlab GUI

Shortcuts are normally visible in the toolbar and the Matlab start menu (R2012a and earlier) or the Matlab Desktop’s toolstrip (R2012b onward). However, using com.mathworks.mlwidgets.shortcuts.ShortcutTreePanel, the schortcuts can also be displayed in any user GUI, complete with right-click context-menu:

jShortcuts = com.mathworks.mlwidgets.shortcuts.ShortcutTreePanel; [jhShortcuts,hPanel] = javacomponent(jShortcuts, [10,10,300,200], gcf);

Shortcuts panel in Matlab figure GUI

Stay tuned…

Next week I will expand the discussion of Matlab shortcuts with the following improvements:

Displaying non-standard controls as shortcuts: checkboxes, drop-downs (combo-boxes) and toggle-buttons

Customizing the shortcut tooltip (replacing the default tooltip that simply repeats the callback string)

Customizing the shortcut callback (rather than using an eval-ed callback string)

Enabling/disabling shortcuts in run-time

Merry Christmas everyone!

The post Programmatic shortcuts manipulation – part 1 appeared first on Undocumented Matlab.

Related posts:

Programmatic shortcuts manipulation – part 2 Non-standard shortcut controls and customizations can easily be added to the Matlab desktop. ...

Command Window text manipulation Special control characters can be used to format text output in Matlab's Command Window. ...

Plot-type selection components Several built-in components enable programmatic plot-type selection in Matlab GUI - this article explains how...

R2009b keyboard bindings The new Matlab release R2009b includes the ability to customize keyboard bindings for the editor and Command Window. However, there are still some uses for the EditorMacro utility and its variants....

Desktop – Undocumented Matlab

Matlab toolstrip – part 2 (ToolGroup App)

Figure containers (“Tool Groups”)

Adding a toolstrip to the ToolGroup

Adding clients (docked figures) to the ToolGroup

Removing the View tab

Conclusion

Related posts:

Matlab toolstrip – part 1

Matlab’s internal showcase examples

1. showcaseToolGroup

2. showcaseMPCDesigner

3. showcaseHTML and showcaseCEF

Levels of toolstrip encapsulation

Robyn Jackey’s Widgets Toolbox

Strong caution

Related posts:

Spicing up the Matlab Editor

Overview

Editing

Navigation

Other useful features

Related posts:

The HotLinks feature

Related posts:

User-defined tab completions – take 2

Syntax

Usage examples

Argument types

Alternative inputs

Platform dependencies

Parsing errors

Related posts:

Working with non-standard DPI displays

Upcoming travels – London/Belfast, Zürich & Geneva

Related posts:

Handling red Java console errors

Related posts:

Viewing saved profiling results

Programmatic access to profiling results

Loading and viewing saved profiling results

Loading saved profiling results from a different computer

Additional profview customizations

Related posts:

Programmatic shortcuts manipulation – part 2

Displaying the Shortcuts panel

Custom controls

Related posts:

Programmatic shortcuts manipulation – part 1

The shortcuts.xml file

Updating the shortcuts in the current Matlab session

Shortcut tools on the Matlab File Exchange

Shortcuts panel embedded in Matlab GUI

Stay tuned…

Related posts:

1. `showcaseToolGroup`

2. `showcaseMPCDesigner`

3. `showcaseHTML` and `showcaseCEF`