Undocumented classdef attributes

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 NameClassDefault value if unspecifiedDescription
CaseInsensitivePropertieslogical (true/false)falseIf 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.

TruncatedPropertieslogical (true/false)falseIf 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.

Enumerationlogical (true/false)falseIf 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.
SupportClassFunctionslogical (true/false)falseAs 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).
Descriptionchar''A string that describes the class. First mentioned here.
DetailedDescriptionchar''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.

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

Tags: , , ,

Bookmark and SharePrint Print

17 Responses to Undocumented classdef attributes

  1. neusgaten says:

    Hi Yair,

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

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

  2. Martin Afanasjew says:

    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 says:

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

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

  3. Jacques says:

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

  4. Amro says:

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

    I thought you might be interested :)

  5. Pingback: Setting class property types | Undocumented Matlab

  6. Chris Hoogeboom says:

    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.

  7. Ben Abbott says:

    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?

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

    • Ben Abbott says:

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

    • 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 says:

      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 =
           []
  8. Terry Brennan says:

    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

Leave a Reply


Your email address will not be published. Required fields are marked *