- Undocumented Matlab - https://undocumentedmatlab.com -

New information on HG2

Posted By Yair Altman On May 10, 2010 | 1 Comment

Last week I posted a couple of articles on the undocumented feature function [1] and Matlab’s apparent move towards a class-based Handle-Graphics system [2] called HG2.
Apparently I caused a bit of a stir…
This is normally a weekly blog. But I wanted to share some additional relevant information as well as some interesting tips I received in private communications. Please note that much of the following is speculation or guesswork and may be incorrect or even entirely wacky. Please read the following with more than the usual grain of skepticism…


A bit of historical background: Matlab’s existing Handle Graphics system is based on UDD (Universal Data Dictionary) objects. Prior to Matlab Release 12 (a.k.a. 6.0) back in 2000, Matlab was written exclusively in C and HG and Simulink used differing approaches to objects in the MathWorks codebase. UDD was then added for R12 using C++ code with C wrappers for internal use by the MathWorks developers. UDD enabled a new unified approach for HG and Simulink (recall the major overhaul to the Matlab interface in that release, which also modified the GUI to be Java-based). While the HG handles remained numeric, behind the scenes they relied on the new UDD system, which remained undocumented.
Matlab users who wished to leverage UDD classes could (and still can) access it via some undocumented interface functions: handle, handle.listener, handle.event, classhandle, schema.prop, schema.class, schema.event (and other schema.* functions), findprop, findclass, findevent and several others. Some of these functions were mentioned in past articles on this blog, and others will perhaps be explained in future articles. You can find numerous mentions and usage examples of UDD in the Matlab codebase that is part of each Matlab installation.
In /toolbox/matlab/helptools/+helpUtils/@HelpProcess/getHelpText.m we can see a related feature (feature(‘SearchUUDClassesForHelp’, flag)) which can apparently be used to allow access to the h1 line and help text for UDD methods. Unfortunately, I have not found any relevant UDD candidates for this. I would be very happy to hear if you know of any objects/methods which have a UDD help section.


Perhaps Matlab’s Class Object System (MCOS), first introduced in R14 [3] (a.k.a. 7.0, released in 2004) grew out of the UDD beginnings, and perhaps it was developed separately. The fact is that it shared several terms and concepts (“schema”, properties meta-data, events) with UDD, although no direct interaction between UDD and MCOS exists, AFAIK.
As an interesting side-note, MCOS was introduced as an opt-in beta-testing feature in R14SP2 (7.0.4, released in 2005). This beta feature cannot be found in the official online version of the R14SP2 release notes [4], but can be found in the hardcover version pages 10-11:

New syntax and features for creating and working with classes in MATLAB. For R14SP2, these features are at a Beta level. If you are interested in being a Beta tester for these features, see “Beta Test the MATLAB Class System” on page 11.
Beta Test the MATLAB Class System. MATLAB 7.0.4 includes a Beta version of new syntax and features for working with classes in MATLAB, which simplify and expand object-oriented programming capabilities in MATLAB. Participation in this Beta program is open only to customers who are current
on their maintenance for MATLAB. Trial passcodes will not be made available for this Beta test. If you are interested in being a Beta tester for these features, register on the MathWorks Web site, at http://www.mathworks.com/products/beta/r14sp2/signup_newfeatures.html [5].

(needless to say, this webpage was since removed…)
The MCOS syntax has changed between releases and was not very stable, until it was formally introduced in R2008a (a.k.a. 7.6, released in 2008). You can look at /toolbox/matlab/iofun/@memmapfile/memmapfile.m to see the MCOS evolution from R14 onward.


The new HG2 appears to be a merger of MCOS and UDD, using MCOS infrastructure for UDD classes and properties, finally throwing away the old numeric handles and C wrappers for the more powerful object-oriented approach.
For the transition period between HG and HG2, there seems to be a dedicated feature: feature(‘HGtoCOS’, handle) apparently converts a UDD (“HG”) handle into an HG2 (“COS”) handle. You can also use feature(‘HGtoCOS’, 0) to obtain an MCOS object of the desktop (=handle 0). Here is a sample result on a Matlab 2009 release:

>> hFig = figure
hFig =
>> fmcos = feature('HGtoCOS', hFig)
fmcos =
  gbtmcos.figure handle
  Package: gbtmcos
                 Alphamap: [1x64 double]
             BeingDeleted: 'off'
               BusyAction: 'queue'
            ButtonDownFcn: []
                 Children: [0x1 double]
                 Clipping: 'on'
          CloseRequestFcn: 'closereq'
                    Color: [0.8000 0.8000 0.8000]
                 Colormap: [64x3 double]
                      ...  (all the regular figure properties)

Note that in that here, the new object package was called GBTMCOS – perhaps meaning a GBT version of the MCOS system. This corresponds to the feature(‘useGBT2’) that I reported in the features article [1]. I have absolutely no idea what GBT stands for, whether it is a synonym for HG2 or not exactly, and what the differences are between GBT1.5 and GBT2. In any case, in R2010a, the same feature(‘HGtoCOS’, handle) code returns a ui.figure object: “GBTMCOS” was simply renamed “UI”.
I do not know how to convert an HG2 back to a UDD/HG handle. None of the following appears to work:

>> fmcos.getdoubleimpl
ans =
>> fmcos.double
ans =
>> double(fmcos)
ans =
>> handle(fmcos)
??? Error using ==> handle
Cannot convert to handle.

I would love to hear any additional information on these subjects, either anonymously or on record. You can use either a direct mail (see link at the top-right of this page) or the comments section [6].

Categories: Figure window, Handle graphics, High risk of breaking in future versions, Undocumented feature, Undocumented function

1 Comment (Open | Close)

1 Comment To "New information on HG2"

#1 Pingback By HG2 update | Undocumented Matlab On May 15, 2013 @ 18:04

[…] Exactly three years ago, I posted information (here and here) about Matlab’s upcoming new graphics engine, so-called HG2 (Handle Graphics version 2). […]

Article printed from Undocumented Matlab: https://undocumentedmatlab.com

URL to article: https://undocumentedmatlab.com/articles/new-information-on-hg2

URLs in this post:

[1] the undocumented feature function: http://undocumentedmatlab.com/blog/undocumented-feature-function/

[2] class-based Handle-Graphics system: http://undocumentedmatlab.com/blog/matlab-hg2/

[3] first introduced in R14: https://www.mathworks.com/matlabcentral/newsreader/view_thread/97653#247876

[4] official online version of the R14SP2 release notes: http://www.mathworks.com/access/helpdesk/help/techdoc/rn/bqsq452.html

[5] http://www.mathworks.com/products/beta/r14sp2/signup_newfeatures.html: http://www.mathworks.com/products/beta/r14sp2/signup_newfeatures.html

[6] comments section: #respond

[7] Performance: accessing handle properties : https://undocumentedmatlab.com/articles/performance-accessing-handle-properties

[8] Creating a simple UDD class : https://undocumentedmatlab.com/articles/creating-a-simple-udd-class

[9] Adding dynamic properties to graphic handles : https://undocumentedmatlab.com/articles/adding-dynamic-properties-to-graphic-handles

[10] Draggable plot data-tips : https://undocumentedmatlab.com/articles/draggable-plot-data-tips

[11] Matlab's HG2 mechanism : https://undocumentedmatlab.com/articles/matlab-hg2

[12] Introduction to UDD : https://undocumentedmatlab.com/articles/introduction-to-udd

Copyright © Yair Altman - Undocumented Matlab. All rights reserved.