Undocumented Matlab
  • SERVICES
    • Consulting
    • Development
    • Training
    • Gallery
    • Testimonials
  • PRODUCTS
    • IQML: IQFeed-Matlab connector
    • IB-Matlab: InteractiveBrokers-Matlab connector
    • EODML: EODHistoricalData-Matlab connector
    • Webinars
  • BOOKS
    • Secrets of MATLAB-Java Programming
    • Accelerating MATLAB Performance
    • MATLAB Succinctly
  • ARTICLES
  • ABOUT
    • Policies
  • CONTACT
  • SERVICES
    • Consulting
    • Development
    • Training
    • Gallery
    • Testimonials
  • PRODUCTS
    • IQML: IQFeed-Matlab connector
    • IB-Matlab: InteractiveBrokers-Matlab connector
    • EODML: EODHistoricalData-Matlab connector
    • Webinars
  • BOOKS
    • Secrets of MATLAB-Java Programming
    • Accelerating MATLAB Performance
    • MATLAB Succinctly
  • ARTICLES
  • ABOUT
    • Policies
  • CONTACT

Introduction to UDD

February 16, 2011 7 Comments

I would like to welcome guest blogger Donn Shull. Donn will present a series of articles about UDD classes and objects, on which many undocumented Matlab features and functions are based.

Background on UDD

Matlab has used objects for a long time. In R8 (Matlab 5.0), their first user accessible class system was introduced. Andy Register wrote a detailed reference on using this system. Although that original system is obsolete, it is still available in R24 (R2010b).
UDD objects (also referred to as schema objects) were introduced with R12 (Matlab 6.0). UDD has been a foundation platform for a number of core Matlab technologies. MathWorks have consistently maintained that UDD is only meant for internal development and not for Matlab users. So, while UDD has no formal documentation, there are plenty of examples and tools to help us learn about it.
It is somewhat odd that despite Matlab’s new object-oriented system (MCOS)’s introduction 3 years ago, and the ongoing concurrent development of HG2 classes, the older-technology UDD is still being actively developed, as evidenced by the increasing number of UDD classes in recent releases. More background on the differences between these different sets of classes can be found here.

Why should we bother learning UDD?

There are some things to consider before deciding if you want to spend the time to learn about the UDD class system:

The case against studying UDD classes

  • There is no documentation from The MathWorks for these classes
  • You will not get any help from The MathWorks in applying these classes
  • The UDD system is now more than a decade old and may be phased out in future Matlab releases (perhaps in HG2?)

The case for studying UDD classes

  • UDD is currently the foundation of handle graphics, Java integration, COM, and Simulink
  • The m code versions of UDD may be considered a forerunner of the newer MCOS class system
  • To avoid memory leaks when using Callbacks in GUI applications you currently need to use UDD
  • UDD techniques facilitate Matlab interaction with Java GUIs
  • UDD directly supports the Matlab style method invocation as well as dot notation for methods without the need to write subsasgn and subsref routines

Tools for Learning about UDD

We start by describing some undocumented Matlab tools that will help us investigate and understand UDD classes.

  • findpackage – All UDD Classes are defined as members of a package. findpackage takes the package name as an input argument and returns a schema.package object which provides information about the package
  • findclass – This method of the schema.package object returns a schema.class object of the named class if the class exists in the package
  • classhandle – For a given UDD object classhandle returns a schema.class object with information about the class. classhandle and findclass are two ways of getting the same information about a UDD class. findclass works with a schema.package object and a class name and does not require an instance of the class. classhandle works with an instance of a class
  • findprop – This method of the schema.class object returns a schema.prop object which contains information about the named property
  • findevent – This method of the schema.class object returns a schema.prop object which contains information about the named event
  • handle – handle is a multifaceted and unique term for The MathWorks. There are both UDD and MCOS handle classes. There is a UDD handle package. In terms of the tools we need, handle is also an undocumented function which converts a numeric handle into a UDD handle object. Depending on your background you may want to think of handle as a cast operator which casts a numeric handle into a UDD object.
  • methods – This is used to display the methods of an object
  • methodsview – Provides a graphic display of an objects methods
  • uiinspect – Yair Altman’s object inspection tool, which can be used for COM, Java and Matlab classes (uiinspect will be described in a separate article in the near future).

Before we apply these tools we need to discuss the basic structure of UDD classes. Let’s compare them with the newer, well documented MCOS classes:
MCOS classes can be defined simply as a standalone class or scoped by placing the class in a package or a hierarchy of packages. With UDD, all classes must be defined in a package. UDD Packages are not hierarchical so a UDD package may not contain other packages. UDD classes can always be instantiated with syntax of packageName.className. By default MCOS classes are value classes. With MCOS you can subclass the handle class to create handle classes. UDD classes are handle classes by default, but it is possible to create UDD value classes.

Exploring some important built-in UDD Classes

The current versions of Matlab include a number of built-in UDD packages. We will use our new tools to see what we can learn about these packages. Let us begin by inspecting the two packages that form the basis of the UDD class system.

The schema package

The built-in schema package contains the classes for creating user written UDD classes. It also is used to provide meta information about UDD classes. Using findpackage we will obtain a schema.package object for the schema package and then use it obtain information about the classes it contains:

>> pkg = findpackage('schema')
pkg =
        schema.package
>> pkg.get
               Name: 'schema'
    DefaultDatabase: [1x1 handle.Database]
            Classes: [9x1 schema.class]
          Functions: [0x1 handle]
        JavaPackage: ''
         Documented: 'on'

>> pkg = findpackage('schema') pkg = schema.package >> pkg.get Name: 'schema' DefaultDatabase: [1x1 handle.Database] Classes: [9x1 schema.class] Functions: [0x1 handle] JavaPackage: '' Documented: 'on'

Note that here we have used the dot-notation pkg.get – we could also have used the Matlab notation get(pkg) instead.
We have now learned that that there are nine classes in the schema package. The information about them in a schema package’s Classes property. To see the information about individual classes we inspect this property:

>> pkg.Classes(1).get
               Name: 'class'
            Package: [1x1 schema.package]
        Description: ''
        AccessFlags: {0x1 cell}
             Global: 'off'
             Handle: 'on'
       Superclasses: [0x1 handle]
    SuperiorClasses: {0x1 cell}
    InferiorClasses: {0x1 cell}
            Methods: [4x1 schema.method]
         Properties: [13x1 schema.prop]
             Events: []
     JavaInterfaces: {0x1 cell}

>> pkg.Classes(1).get Name: 'class' Package: [1x1 schema.package] Description: '' AccessFlags: {0x1 cell} Global: 'off' Handle: 'on' Superclasses: [0x1 handle] SuperiorClasses: {0x1 cell} InferiorClasses: {0x1 cell} Methods: [4x1 schema.method] Properties: [13x1 schema.prop] Events: [] JavaInterfaces: {0x1 cell}

Not surprisingly, the first class in the schema.package is ‘class’ itself. Here we can see that schema.class has 4 methods and 13 properties. We can also see that the schema.class objects have a Name property. Let’s use that information to list all the classes in the schema package:

>> names = cell(numel(pkg.Classes), 1);
>> for index = 1:numel(names), names{index} = pkg.Classes(index).Name; end;
>> names
names =
    'class'
    'method'
    'signature'
    'package'
    'event'
    'prop'
    'type'
    'EnumType'
    'UserType'

>> names = cell(numel(pkg.Classes), 1); >> for index = 1:numel(names), names{index} = pkg.Classes(index).Name; end; >> names names = 'class' 'method' 'signature' 'package' 'event' 'prop' 'type' 'EnumType' 'UserType'

These are the base classes for the UDD package schema. To illustrate a different way to get information, let’s use the findclass method of schema.package to get information about the schema.prop class:

>> p = findclass(pkg, 'prop')
p =
        schema.class
>> get(p)
               Name: 'prop'
            Package: [1x1 schema.package]
        Description: ''
        AccessFlags: {0x1 cell}
             Global: 'off'
             Handle: 'on'
       Superclasses: [0x1 handle]
    SuperiorClasses: {0x1 cell}
    InferiorClasses: {0x1 cell}
            Methods: [2x1 schema.method]
         Properties: [9x1 schema.prop]
             Events: []
     JavaInterfaces: {0x1 cell}

>> p = findclass(pkg, 'prop') p = schema.class >> get(p) Name: 'prop' Package: [1x1 schema.package] Description: '' AccessFlags: {0x1 cell} Global: 'off' Handle: 'on' Superclasses: [0x1 handle] SuperiorClasses: {0x1 cell} InferiorClasses: {0x1 cell} Methods: [2x1 schema.method] Properties: [9x1 schema.prop] Events: [] JavaInterfaces: {0x1 cell}

The handle package

The second basic UDD package is the handle package. Handle holds a special place in Matlab and has multiple meanings: Handle is a type of Matlab object that is passed by reference; handle is a function which converts a numeric handle to an object; handle is an abstract object in the new MCOS class system and handle is also a UDD package as well as the default type for UDD objects.
There is an interesting connection between UDD and MCOS that involves handle. In Matlab releases R12 through R2007b, the UDD handle package had up to 12 classes and did not have any package functions (package functions are functions which are scoped to a package; their calling syntax is [outputs] = packageName.functionName(inputs)).
Beginning with the formal introduction of MCOS in R2008a, the abstract MCOS class handle was introduced. The MCOS handle class has 12 methods. It also turns out that beginning with R2008a, the UDD handle package has 12 package functions which are the MCOS handle methods.
The 12 UDD classes in the handle package fall into two groups: The database and transaction classes work with the schema.package to provide a UDD stack mechanism; the listener and family of EventData classes work with schema.event to provide the UDD event mechanism:

>> pkg = findpackage('handle')
pkg =
        schema.package
>> pkg.get
               Name: 'handle'
    DefaultDatabase: [1x1 handle.Database]
            Classes: [12x1 schema.class]
          Functions: [12x1 schema.method]
        JavaPackage: ''
         Documented: 'on'
>> names = cell(numel(pkg.Classes), 1);
>> for index = 1:numel(names), names{index} = pkg.Classes(index).Name; end
>> names
names =
    'Operation'
    'transaction'
    'Database'
    'EventData'
    'ClassEventData'
    'ChildEventData'
    'ParentEventData'
    'PropertyEventData'
    'PropertySetEventData'
    'listener'
    'JavaEventData'
    'subreference__'

>> pkg = findpackage('handle') pkg = schema.package >> pkg.get Name: 'handle' DefaultDatabase: [1x1 handle.Database] Classes: [12x1 schema.class] Functions: [12x1 schema.method] JavaPackage: '' Documented: 'on' >> names = cell(numel(pkg.Classes), 1); >> for index = 1:numel(names), names{index} = pkg.Classes(index).Name; end >> names names = 'Operation' 'transaction' 'Database' 'EventData' 'ClassEventData' 'ChildEventData' 'ParentEventData' 'PropertyEventData' 'PropertySetEventData' 'listener' 'JavaEventData' 'subreference__'

The hg package

Arguably the most important UDD package in Matlab is the handle graphics package hg. Among the built-in UDD packages, hg is unique in several respects. As Matlab has evolved from R12 through R2011a, the number of default classes in the hg package has nearly doubled going from 17 classes to 30 (UDD has a mechanism for automatically defining additional classes as needed during run-time).
The hg package contains a mixture of Global and non Global classes. These classes return a numeric handle, unless they have been created using package scope. The uitools m-file package provides a great example of extending built-in UDD classes with user written m-file UDD classes.
The UDD class for a Handle-Graphics object can be obtained either by explicitly creating it with the hg package, or using the handle function on the numeric handle obtained from normal hg object creation. Using figure as an example, you can either use figh = hg.figure or fig = figure followed by figh = handle(fig):

>> pkg = findpackage('hg')
pkg =
        schema.package
>> pkg.get
               Name: 'hg'
    DefaultDatabase: [1x1 handle.Database]
            Classes: [30x1 schema.class]
          Functions: [0x1 handle]
        JavaPackage: 'com.mathworks.hg'
         Documented: 'on'
>> for index = 1:numel(names), names{index} = pkg.Classes(index).Name; end
>> names
names =
    'GObject'
    'root'
    'LegendEntry'
    'Annotation'
    'figure'
    'uimenu'
    'uicontextmenu'
    'uicontrol'
    'uitable'
    'uicontainer'
    'hgjavacomponent'
    'uipanel'
    'uiflowcontainer'
    'uigridcontainer'
    'uitoolbar'
    'uipushtool'
    'uisplittool'
    'uitogglesplittool'
    'uitoggletool'
    'axes'
    'hggroup'
    'text'
    'line'
    'patch'
    'surface'
    'rectangle'
    'light'
    'image'
    'hgtransform'
    'uimcosadapter'

>> pkg = findpackage('hg') pkg = schema.package >> pkg.get Name: 'hg' DefaultDatabase: [1x1 handle.Database] Classes: [30x1 schema.class] Functions: [0x1 handle] JavaPackage: 'com.mathworks.hg' Documented: 'on' >> for index = 1:numel(names), names{index} = pkg.Classes(index).Name; end >> names names = 'GObject' 'root' 'LegendEntry' 'Annotation' 'figure' 'uimenu' 'uicontextmenu' 'uicontrol' 'uitable' 'uicontainer' 'hgjavacomponent' 'uipanel' 'uiflowcontainer' 'uigridcontainer' 'uitoolbar' 'uipushtool' 'uisplittool' 'uitogglesplittool' 'uitoggletool' 'axes' 'hggroup' 'text' 'line' 'patch' 'surface' 'rectangle' 'light' 'image' 'hgtransform' 'uimcosadapter'

So far we have just explored the very basic concepts of UDD. You may well be wondering what the big fuss is about, since the information presented so far does not have any immediately-apparent benefits.
The following set of articles will describe more advanced topics in UDD usage and customizations, using the building blocks presented today. Hopefully you will quickly understand how using UDD can help achieve some very interesting stuff with Matlab.

Related posts:

  1. UDD Properties – UDD provides a very convenient way to add customizable properties to existing Matlab object handles...
  2. Creating a simple UDD class – This article explains how to create and test custom UDD packages, classes and objects...
  3. UDD Events and Listeners – UDD event listeners can be used to listen to property value changes and other important events of Matlab objects...
  4. New information on HG2 – More information on Matlab's new HG2 object-oriented handle-graphics system...
  5. Multi-column (grid) legend – This article explains how to use undocumented axes listeners for implementing multi-column plot legends...
  6. Hierarchical Systems with UDD – UDD objects can be grouped in structured hierarchies - this article explains how...
Donn Shull Handle graphics Internal component Listener Pure Matlab schema schema.class schema.prop Undocumented feature Undocumented function
Print Print
« Previous
Next »
7 Responses
  1. Aurélien February 18, 2011 at 02:06 Reply

    Hi!

    I am really curious to read the next articles.
    By the way, it is the first time , I read that R24 stands for R2010b!

    Aurélien

    • Donn February 18, 2011 at 11:38 Reply

      Merci Aurélien,

      I hope you find the following articles interesting. The MathWorks increments the release number with each release of MATLAB. To find the release number of the version you are using you can look at the license file the release number is the number following the MLM for any of the products you have licensed.

      Donn

  2. Alexander Kosenkov February 23, 2011 at 11:47 Reply

    Hey, I have quite a rich experience with software development tools, languages, paradygms, libraries… but still…

    What does UDD stand for?!

    You mentioned this acronym 67 (sixty seven) times on this page, but it’s not getting clear =)

    • Yair Altman February 23, 2011 at 12:35 Reply

      @Alexander – excellent question. I never saw an official definition anywhere (did I forget to mention it’s undocumented?). My guess is that it stands for “Unified Data Definition” or something similar, but your guess would be as good as mine…

    • Donn February 24, 2011 at 10:22 Reply

      @Alexander – We can only infer that these classes are known as UDD classes from reading the help text and comments contained in them, noting that feature(‘SearchUDDClassesForHelp’, 1) enabled lookfor to search the H1 line of these classes until that feature was discontinued in R2010b, and that Simulink has the command obj = get_param(gco, ‘UDDObject’) for any current object in a block diagram.

      We can speculate on the meaning by noting that UDD was introduced with R12 also known as the MATLAB Version 6 series. In previous releases the handle graphics and Simulink had very different object systems. In R12 these two hierarchical objects were placed on a common object system while maintaining a fairly high degree of compatibility with the previous versions. It seems reasonable to speculate that the U in UDD stands for Unified and the pair of D’s may stand for Data Description or Data Definition, but it is only speculation.

      We might also speculate that with the explosion in MCOS usage by The MathWorks that at some future time (the MATLAB 8 series?) UDD will be replaced and handle graphics and Simulink will be placed on the new object system. Only The MathWorks knows for sure.

    • Yair Altman November 9, 2012 at 03:25 Reply

      UDD stands for “Universal Data Dictionary”, according to %matlabroot%/toolbox/matlab/general/+matlab/+depfun/+internal/MatlabType.m.

      Similarly, MCOS stands for “Matlab Common Object System”.

      Apparently, there’s also a third class type, called OOPS – perhaps this stands for “Object-Oriented Programming Schema”, possibly related to schema objects.

  3. sebbo May 16, 2013 at 06:04 Reply

    Hi all,

    is there a possibility to add something resembling a static function to a udd-class?
    I built a rather complex class involving functions not residing in the schema.m-file.
    Due to the possibility to subclass uicontainer, I chose UDD to do so.

    Now I’m wondering where to put helper-functions that are used in multiple functions, but don’t require a class-instance to work.
    Making them non-static by ignoring the class-instance argument is of course a possibility, though not a nice one.

    Any ideas welcome 🙂

Leave a Reply
HTML tags such as <b> or <i> are accepted.
Wrap code fragments inside <pre lang="matlab"> tags, like this:
<pre lang="matlab">
a = magic(3);
disp(sum(a))
</pre>
I reserve the right to edit/delete comments (read the site policies).
Not all comments will be answered. You can always email me (altmany at gmail) for private consulting.

Click here to cancel reply.

Useful links
  •  Email Yair Altman
  •  Subscribe to new posts (feed)
  •  Subscribe to new posts (reader)
  •  Subscribe to comments (feed)
 
Accelerating MATLAB Performance book
Recent Posts

Speeding-up builtin Matlab functions – part 3

Improving graphics interactivity

Interesting Matlab puzzle – analysis

Interesting Matlab puzzle

Undocumented plot marker types

Matlab toolstrip – part 9 (popup figures)

Matlab toolstrip – part 8 (galleries)

Matlab toolstrip – part 7 (selection controls)

Matlab toolstrip – part 6 (complex controls)

Matlab toolstrip – part 5 (icons)

Matlab toolstrip – part 4 (control customization)

Reverting axes controls in figure toolbar

Matlab toolstrip – part 3 (basic customization)

Matlab toolstrip – part 2 (ToolGroup App)

Matlab toolstrip – part 1

Categories
  • Desktop (45)
  • Figure window (59)
  • Guest bloggers (65)
  • GUI (165)
  • Handle graphics (84)
  • Hidden property (42)
  • Icons (15)
  • Java (174)
  • Listeners (22)
  • Memory (16)
  • Mex (13)
  • Presumed future risk (394)
    • High risk of breaking in future versions (100)
    • Low risk of breaking in future versions (160)
    • Medium risk of breaking in future versions (136)
  • Public presentation (6)
  • Semi-documented feature (10)
  • Semi-documented function (35)
  • Stock Matlab function (140)
  • Toolbox (10)
  • UI controls (52)
  • Uncategorized (13)
  • Undocumented feature (217)
  • Undocumented function (37)
Tags
ActiveX (6) AppDesigner (9) Callbacks (31) Compiler (10) Desktop (38) Donn Shull (10) Editor (8) Figure (19) FindJObj (27) GUI (141) GUIDE (8) Handle graphics (78) HG2 (34) Hidden property (51) HTML (26) Icons (9) Internal component (39) Java (178) JavaFrame (20) JIDE (19) JMI (8) Listener (17) Malcolm Lidierth (8) MCOS (11) Memory (13) Menubar (9) Mex (14) Optical illusion (11) Performance (78) Profiler (9) Pure Matlab (187) schema (7) schema.class (8) schema.prop (18) Semi-documented feature (6) Semi-documented function (33) Toolbar (14) Toolstrip (13) uicontrol (37) uifigure (8) UIInspect (12) uitools (20) Undocumented feature (187) Undocumented function (37) Undocumented property (20)
Recent Comments
  • Nicholas (3 days 23 hours ago): Hi Yair, Thanks for the reply. I am on Windows 10. I also forgot to mention that this all works wonderfully out of the editor. It only fails once compiled. So, yes, I have tried a...
  • Nicholas (3 days 23 hours ago): Hi Yair, Thanks for the reply. I am on Windows 10. I also forgot to mention that this all works wonderfully out of the editor. It only fails once compiled. So, yes, I have tried a...
  • Yair Altman (4 days 6 hours ago): Nicholas – yes, I used it in a compiled Windows app using R2022b (no update). You didn’t specify the Matlab code location that threw the error so I can’t help...
  • Nicholas (5 days 2 hours ago): Hi Yair, Have you attempted your displayWebPage utility (or the LightweightHelpPanel in general) within a compiled application? It appears to fail in apps derived from both R2022b...
  • João Neves (8 days 7 hours ago): I am on matlab 2021a, this still works: url = struct(struct(struct(struct(hF ig).Controller).PlatformHost). CEF).URL; but the html document is empty. Is there still a way to do...
  • Yair Altman (11 days 6 hours ago): Perhaps the class() function could assist you. Or maybe just wrap different access methods in a try-catch so that if one method fails you could access the data using another...
  • Jeroen Boschma (11 days 8 hours ago): Never mind, the new UI components have an HTML panel available. Works for me…
  • Alexandre (11 days 9 hours ago): Hi, Is there a way to test if data dictionnatry entry are signal, simulink parameters, variables … I need to access their value, but the access method depends on the data...
  • Nicholas (11 days 23 hours ago): In case anyone is looking for more info on the toolbar: I ran into some problems creating a toolbar with the lightweight panel. Previously, the Browser Panel had an addToolbar...
  • Jeroen Boschma (15 days 6 hours ago): I do not seem to get the scrollbars (horizontal…) working in Matlab 2020b. Snippets of init-code (all based on Yair’s snippets on this site) handles.text_explorer...
  • Yair Altman (43 days 8 hours ago): m_map is a mapping tool, not even created by MathWorks and not part of the basic Matlab system. I have no idea why you think that the customizations to the builtin bar function...
  • chengji chen (43 days 15 hours ago): Hi, I have tried the method, but it didn’t work. I plot figure by m_map toolbox, the xticklabel will add to the yticklabel at the left-down corner, so I want to move down...
  • Yair Altman (51 days 8 hours ago): @Alexander – this is correct. Matlab stopped including sqlite4java in R2021b (it was still included in 21a). You can download the open-source sqlite4java project from...
  • Alexander Eder (57 days 4 hours ago): Unfortunately Matlab stopped shipping sqlite4java starting with R2021(b?)
  • K (63 days 14 hours ago): Is there a way to programmatically manage which figure gets placed where? Let’s say I have 5 figures docked, and I split it into 2 x 1, I want to place 3 specific figures on the...
Contact us
Captcha image for Custom Contact Forms plugin. You must type the numbers shown in the image
Undocumented Matlab © 2009 - Yair Altman
This website and Octahedron Ltd. are not affiliated with The MathWorks Inc.; MATLAB® is a registered trademark of The MathWorks Inc.
Scroll to top