Undocumented classdef attributes

November 21, 2012 20 Comments

Matlab’s new (or should I say “renewed”) object-oriented paradigm, uses attributes to define class behavior. Not surprisingly, some attributes used by Matlab’s internal classes are not documented in the official documentation 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, 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, 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.

DetailedDescription char '' A string that describes the class in more detail. First mentioned here.

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.

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 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.

20 Responses

neusgaten November 22, 2012 at 02:00 Reply

Hi Yair,

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

Yair Altman November 22, 2012 at 02:24 Reply

@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.

Martin Afanasjew November 27, 2012 at 08:25 Reply

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.

Donn Shull November 27, 2012 at 12:34 Reply

@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.

Yair Altman November 27, 2012 at 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 what MathWorks is doing. 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.

Jacques January 31, 2013 at 22:03 Reply

it seems that it (the classdef CaseInsensitiveProperties and TruncatedProperties) does not work with dynamic properties
Amro April 13, 2013 at 13:35 Reply

I just found an undocumented syntax to specify property types in classes:
http://stackoverflow.com/a/15992558/97160

I thought you might be interested 🙂

Yair Altman April 13, 2013 at 13:50 Reply

@Amro – thanks, interesting!

Setting class property types | Undocumented Matlab April 18, 2013 at 07:12 Reply

[…] a few days ago I was pleasantly surprised to read Amro’s comment about an entirely new and undocumented aspect of Matlab MCOS classes […]
Chris Hoogeboom May 1, 2013 at 08:44 Reply

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.

Yair Altman May 1, 2013 at 08:48 Reply

@Chris – take a look at the Doxygen for Matlab utility on the File Exchange – no need to reinvent the wheel…

Ben Abbott July 12, 2014 at 17:08 Reply

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?

Yair Altman July 13, 2014 at 16:12 Reply

@Ben – I don’t think I follow you – scatteredInterpolant is a simple Matlab class, not a function (see here).
Ben Abbott July 14, 2014 at 05:28 Reply
@Yair – Sorry, I wasn’t clear. Each instance of scatteredInterpolant is a function.
foo = scatteredInterpolant (x, y, z); c = foo (a, b);
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.
Yair Altman July 14, 2014 at 05:53 Reply

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.

Ben Abbott July 14, 2014 at 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 = []
>> foo(3) = scatteredInterpolant foo = 1x3 scatteredInterpolant array with properties: Points Values Method ExtrapolationMethod >> foo(3) ans = []

Terry Brennan November 30, 2015 at 22:48 Reply
The use of the Description attribute in a classdef alters the behavior of the command line help. Normally
>> help classname
>> help classname
echoes the comments under the classdef line and
>> help classname.classname
>> help classname.classname
echoes the comments under the function constructor. When Description is specified

Maarten van der Seijs March 28, 2018 at 14:12 Reply

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!

Sam Roberts March 28, 2018 at 18:59 Reply

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 (https://stackoverflow.com/questions/26710767/which-methods-keywords-i-e-testmethodsetup-can-occur-in-matlab/26733613#26733613) 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.

Jan October 26, 2021 at 18:49

Any updates on this development? I just raised a similar question there: https://www.mathworks.com/matlabcentral/answers/1571813-custom-class-properties-and-method-attributes?s_tid=mlc_ans_email_view#comment_1801123 and after searching for “Description attribute” I ended up here 😀

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.

MCOS (Matlab Common/Class Object System) classes

UDD (Universal Data Dictionary, schema) classes

Related posts:

20 Responses

Leave a Reply