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

Undocumented classdef attributes

Posted By Yair Altman On November 21, 2012 | 19 Comments

Matlab’s new (or should I say “renewed”) object-oriented paradigm [1], uses attributes to define class behavior. Not surprisingly, some attributes used by Matlab’s internal classes are not documented in the official documentation [2] of the supported attributes. These attributes could well be useful when defining our custom classes:

MCOS (Matlab Common/Class Object System) classes

Attribute Name Class Default value if unspecified Description
CaseInsensitiveProperties logical (true/false) false If true, then such properties can be accessed using any case. For example, if the property is called myProp, then it can be called as myclass.myProp or myClass.MYPROP or any other variation.
If the class inherits hgsetget [3], then the property can also be used in this way within get/set functions:

get(myClass,'MYPROP')

If the attribute is unspecified or false, then trying to use a case-insensitive version of the property name would result in an error:

Error using MyClass/get
Property MYPROP not found in class MyClass, or is not present in all elements of the array of class MyClass.

TruncatedProperties logical (true/false) false If true, then such properties can be accessed using any substring that leads to a unique property. For example, if the property is called myProperty, then it can be called as myclass.myProperty or myClass.myProp or any other variation.
If the class inherits hgsetget [3], then the property can also be used in this way within get/set functions:

get(myClass,'myProp')

Note that if the class has another property called myProblem, then myClass.myPro would be ambiguous and result in an error message; we would need to use myClass.myProp or some other unique term:

Error using MyClass/get
Ambiguous MyClass property: 'myPro'.


If the attribute is unspecified or false, then trying to use a truncated version of the property name would result in an error:

Error using MyClass/get
Property myProp not found in class MyClass, or is not present in all elements of the array of class MyClass.

Enumeration logical (true/false) false If true, then the class appears to be an enumeration class. I am not exactly sure how this could be useful. I saw references to this attribute in the Data Aquisition Toolbox.
SupportClassFunctions logical (true/false) false As above, I am not exactly sure how this could be useful. I saw reference to this attribute in %matlabroot%/toolbox/shared/controllib/engine/ (I don’t currently have ready access to this toolbox so I can’t test).
Description char '' A string that describes the class. First mentioned here [4].
DetailedDescription char '' A string that describes the class in more detail. First mentioned here [4].

The CaseInsensitiveProperties and TruncatedProperties attributes are true for Matlab HG (Handle-Graphics) properties. Many users have come to rely on the fact that they can specify the Position property using get(gcf,'position') or set(gcf,'Pos'). It is very intuitive to use. For this reason I do not understand why MathWorks chose to set these attributes’ default value to false. At least now we can manually change this for our classes.

Sample usage (see %matlabroot%/toolbox/matlab/graphics/+graphics/+internal/@LinkAxes/LinkAxes.m and many others):

classdef (CaseInsensitiveProperties=true, TruncatedProperties=true, ConstructOnLoad=true) LinkAxes < handle
classdef (CaseInsensitiveProperties, TruncatedProperties, ConstructOnLoad) LinkAxes < handle  % equivalent alternative

I could not find any similar undocumented attributes for properties, methods, events and enumerations.
Do you know of any other useful attribute for the class, or for its constituents? If so, please post a short comment below [5].

UDD (Universal Data Dictionary, schema) classes

UDD (schema) classes have the property truncation on by default, and in fact this cannot be unset. I.e., we cannot have a variant of MCOS’s TruncatedProperties=false for schema objects:

>> hTabGroup = uitabgroup;
>> get(hTabGroup,'FlowDir')  % truncated from 'FlowDirection'
ans =
topdown

The properties do have a settable CaseSensitive meta-property [6] that we can set to ‘on/off’ (default=’off’) on a property-by-property basis. In most cases, we would naturally stick with the default behavior:

>> get(hTabGroup,'flowdir')  % case-insensitive form of 'FlowDirection'
ans =
topdown

This mean that by default, schema objects behave similarly to the ubiquitous HG behavior, whereas custom MCOS objects have a default behavior that is much stricter and needs special handling.

Categories: Medium risk of breaking in future versions, Undocumented feature


19 Comments (Open | Close)

19 Comments To "Undocumented classdef attributes"

#1 Comment By neusgaten On November 22, 2012 @ 02:00

Hi Yair,

Do you agree with me that none of the above Attributes contribute to decent programming?

#2 Comment By Yair Altman On November 22, 2012 @ 02:24

@neusgaten – While I agree that writing the case-sensitive non-truncated format of property names is generally preferable, I still think that the CaseInsensitiveProperties and TruncatedProperties attributes are useful, if only for the reason that we have to keep consistency between HG classes and user classes, and because using case-insensitive and truncated properties is such an ingrained practice for Matlab programmers in the HG context.

Regarding the other attributes, Enumeration and SupportClassFunctions, I’m not sure, but I don’t think they contribute to bad programming practices. Maybe when we will know more about them we can decide.

#3 Comment By Martin Afanasjew On November 27, 2012 @ 08:25

I really despise the possibility to abbreviate properties and ignore their proper case. While it might be convenient during code testing it really kills readability for you and those required to read your code later on. It’s also terrible once you wish to grep for these properties in a huge code base. I’m really happy that they decided to take a cleaner path for the “new” object-oriented stuff.

I really hope the sole reason why those hidden attributes exist is because The MathWorks intends to kill UDD some day and move their HG implementation to MCOS while retaining backwards compatibility for a huge part of the MATLAB community.

#4 Comment By Donn Shull On November 27, 2012 @ 12:34

@Martin The MathWorks has indicated for years that UDD is a technology that they intend to replace. While the exact path they intend to take is not clear, the development of HG2 moves forward with each release. On the Simulink side of the UDD equation, much of the new functionality is implemented in MCOS. 2012 saw the switch of Simulink.Parameter and Simulink.Signal objects move from UDD to MCOS.

With R2010b, DAStudio.Dialog, once a dialog GUI system exclusively for objects derived from the UDD DAStudio.Object began allowing its use with MCOS objects which properly implemented the getDialogSchema.m method.

So I suspect that you are right that UDD will eventually be removed from MATLAB, but the process may be a slow and gradual one.

#5 Comment By Yair Altman On November 27, 2012 @ 14:12

My 2 cents on this is that there is such an enormous code corpus implemented in UDD, that I simply can’t see everything being transitioned to MCOS anytime soon. I didn’t see any major refactoring of UDD code to MCOS so far. In fact, from one release to another I see the UDD code corpus grow, although not at the same rate as MCOS code. It would indeed be hard to justify the enormous dev effort required to redevelop & properly test all the existing UDD code in MCOS. So my personal hunch is that we will see new code being implemented in MCOS, but I suspect that existing UDD functionality will remain unchanged for some time to come.

All this excluding HG2 of course: Since HG2 is a major rework of the entire HG system, it does make sense to redo everything in MCOS, which I suspect is [13]. I for one will be happy to see the last of the unbelievably (and some might also say, unnecessarily) complex uimodes, scribe layer and their ilk. I just pray they won’t be replaced with similarly-convoluted mechanisms in HG2.

#6 Comment By Jacques On January 31, 2013 @ 22:03

it seems that it (the classdef CaseInsensitiveProperties and TruncatedProperties) does not work with dynamic properties

#7 Comment By Amro On April 13, 2013 @ 13:35

I just found an undocumented syntax to specify property types in classes:
[14]

I thought you might be interested 🙂

#8 Comment By Yair Altman On April 13, 2013 @ 13:50

@Amro – thanks, interesting!

#9 Pingback By Setting class property types | Undocumented Matlab On April 18, 2013 @ 07:12

[…] a few days ago I was pleasantly surprised to read Amro’s comment about an entirely new and undocumented aspect of Matlab MCOS classes […]

#10 Comment By Chris Hoogeboom On May 1, 2013 @ 08:44

I am currently writing a way of generating custom documentation from class files. I heavily rely on metaclass objects to do so, and have found them to be very useful. Unfortunately the Description and DetailedDescription puzzled me, until now! Thanks for this.

I am especially keen on using this for method and property descriptions. Unfortunately it seems that there is no way to specify descriptions for individual properties without a whole lot of work.

#11 Comment By Yair Altman On May 1, 2013 @ 08:48

@Chris – take a look at the [15] utility on the File Exchange – no need to reinvent the wheel…

#12 Comment By Ben Abbott On July 12, 2014 @ 17:08

Regarding SupportClassFunctions, would that allow instances of a class to be used as a function? In the same manner as core class/functions like scatteredInterpolant?

#13 Comment By Yair Altman On July 13, 2014 @ 16:12

@Ben – I don’t think I follow you – scatteredInterpolant is a simple Matlab class, not a function (see [16]).

#14 Comment By Ben Abbott On July 14, 2014 @ 05:28

@Yair – Sorry, I wasn’t clear. Each instance of scatteredInterpolant is a function.

foo = scatteredInterpolant (x, y, z); 
c = foo (a, b);

I don’t think their is a documented way to produce a class (via classdef) that supports the feature, c=foo(a,b). From the name of the attribute SupportClassFunctions I inferred this may needed to allow foo to be used as a function.

#15 Comment By Yair Altman On July 14, 2014 @ 05:53

I see what you mean, but I don’t think it is related. scatteredInterpolant simply overloaded the subsref(), subsasgn(), end() methods for this functionality. You can do it in any user class.

#16 Comment By Ben Abbott On July 14, 2014 @ 15:57

Ok that makes sense, and explains the clumsy behavior below.

>> foo(3) = scatteredInterpolant
foo = 
  1x3 scatteredInterpolant array with properties:

    Points
    Values
    Method
    ExtrapolationMethod

>> foo(3)
ans =
     []

#17 Comment By Terry Brennan On November 30, 2015 @ 22:48

The use of the Description attribute in a classdef alters the behavior of the command line help. Normally

>> help classname

echoes the comments under the classdef line and

>> help classname.classname

echoes the comments under the function constructor. When Description is specified

#18 Comment By Maarten van der Seijs On March 28, 2018 @ 14:12

I’ve been looking for ways to define custom attributes for classes and class methods/properties. I’ve noticed that some internal matlab classes define additional attributes, such as the unit test classes derived from matlab.unittest.TestCase. This can be nicely observed from its meta class:

>> mTestClass = meta.class.fromName('matlab.unittest.TestCase');
>> mTestMethod = mClass.MethodList(1)
mTestMethod = 
  method with properties:
                    Test: 0
         TestMethodSetup: 0
      TestMethodTeardown: 0
          TestClassSetup: 0
       TestClassTeardown: 0
    ParameterCombination: ''
                TestTags: {}
                    Name: 'TestCase'
             Description: ''
     DetailedDescription: ''
                     ...

The top 7 properties correspond to the method attributes that are available in the method definition blocks, for classes derived from matlab.unittest.TestCase. Apparently these have been added by subclassing the meta.method object to the new matlab.unittest.meta.method, which is indeed the meta class that is returned for classes derived from the superclass matlab.unittest.TestCase.

My question is: do you know of any (undocumented) means to define such attributes ourselves, such that you could do something like this?

classdef MyClass < MyBaseClass
    methods (CustomAttribute = "Custom attribute value")
       ...
    end
end

Any insight or directions would be highly appreciated!

#19 Comment By Sam Roberts On March 28, 2018 @ 18:59

Maarten,

No, you can’t do that, although MathWorks are considering the possibility for a future enhancement. A similar question was asked on StackOverflow a while ago ( [17]) and received a couple of answers, one of which was from Andy Campbell, a senior developer at MathWorks. See the comment thread under his answer.

In the meantime, it is sometimes possible to achieve your aims by abusing the undocumented attributes Description and DetailedDescription.
These are undocumented, but are always present (on class, method, property and event elements), and accept a string value that you can use to store essentially whatever you want. Some built-in classes such as containers.Map use them to store a description of the class.

Because they are undocumented, if you use them they will cause a red underline in the MATLAB editor (without any actual runtime error). You can suppress this using %#ok<ATUNK> at the end of the line.


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

URL to article: https://undocumentedmatlab.com/articles/undocumented-classdef-attributes

URLs in this post:

[1] object-oriented paradigm: http://www.mathworks.com/help/matlab/object-oriented-programming.html

[2] official documentation: http://www.mathworks.com/help/matlab/matlab_oop/class-attributes.html

[3] hgsetget: http://www.mathworks.com/help/matlab/ref/hgsetget.html

[4] here: http://stackoverflow.com/questions/13819469/description-and-detaileddescription-attributes-of-matlab-classes

[5] comment below: http://undocumentedmatlab.com/blog/undocumented-classdef-attributes#respond

[6] meta-property: http://undocumentedmatlab.com/blog/udd-properties/

[7] getundoc – get undocumented object properties : https://undocumentedmatlab.com/articles/getundoc-get-undocumented-object-properties

[8] Undocumented HG2 graphics events : https://undocumentedmatlab.com/articles/undocumented-hg2-graphics-events

[9] Undocumented scatter plot jitter : https://undocumentedmatlab.com/articles/undocumented-scatter-plot-jitter

[10] More undocumented timing features : https://undocumentedmatlab.com/articles/more-undocumented-timing-features

[11] HG's undocumented parameters interface : https://undocumentedmatlab.com/articles/hgs-undocumented-parameters-interface

[12] Undocumented scatter plot behavior : https://undocumentedmatlab.com/articles/undocumented-scatter-plot-behavior

[13] : https://undocumentedmatlab.com/blog/new-information-on-hg2/#HG2

[14] : http://stackoverflow.com/a/15992558/97160

[15] : http://www.mathworks.com/matlabcentral/fileexchange/25925-using-doxygen-with-matlab

[16] : http://www.mathworks.com/help/matlab/ref/scatteredinterpolant-class.html

[17] : https://stackoverflow.com/questions/26710767/which-methods-keywords-i-e-testmethodsetup-can-occur-in-matlab/26733613#26733613

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