Custom Display Interface

Default Object Display

MATLAB® adds default methods named disp and display to all MATLAB classes that do not implement their own methods with those names. These methods are not visible, but create the default simple display.

The default simple display consists of the following parts:

  • A header showing the class name, and the dimensions for nonscalar arrays.

  • A list of all nonhidden public properties, shown in the order of definition in the class.

The actual display depends on whether the object is scalar or nonscalar. Also, there are special displays for a scalar handle to a deleted object and empty object arrays. Objects in all of these states are displayed differently if the objects have no properties.

The details method creates the default detailed display. The detailed display adds these items to the simple display:

  • Use of fully qualified class names

  • Link to handle class, if the object is a handle

  • Links to methods, events, and superclasses functions executed on the object.

See Class with Default Object Display for an example of how MATLAB displays objects.

Properties Displayed by Default

MATLAB displays object properties that have public get access and are not hidden (see Property Attributes). Inherited abstract properties are excluded from display. When the object being displayed is scalar, any dynamic properties attached to the object are also included.

CustomDisplay Class

The matlab.mixin.CustomDisplay class provides an interface that you can use to customize object display for your class. To use this interface, derive your class from CustomDisplay:

classdef MyClass < matlab.mixin.CustomDisplay

The CustomDisplay class is HandleCompatibile, so you can use it in combination with both value and handle superclasses.

    Note:   You cannot use matlab.mixin.CustomDisplay to derive a custom display for enumeration classes.

disp, display, and details

The CustomDisplay class defines three sealed public methods. These methods overload three MATLAB functions: disp, display, and details. The disp and display methods behave like the equivalent MATLAB functions, but use the customizations defined by classes derived from CustomDisplay.

The details method always uses the default detailed object display and does not apply customizations defined for the class.

The CustomDisplay interface does not allow you to override disp and display. Instead, override any combination of the customization methods defined for this purpose.

Methods for Customizing Object Display

There are two groups of methods that you use to customize object display for your class:

  • Part builder methods build the strings used for the standard display. Override any of these methods to change the respective parts of the display.

  • State handler methods are called for objects in specific states, like scalar, nonscalar, and so on. Override any of these methods to handle objects in a specific state.

All of these methods have protected access and must be defined as protected in your subclass of CustomDisplay (that is, Access = protected).

Parts of an Object Display

There are three parts that makeup the standard object display — header, property list, and footer

For example, here is the standard object display for a containers.Map object:

The default object display does not include a footer. The detailed display provides more information:

Part Builder Methods

Each part of the object display has an associated method that assembles the respective part of the display.

MethodPurposeDefault
getHeader

Create the string used for the header.

Returns the string, [class(obj), ' with properties:'] linking the class name to a help popup

getPropertyGroups

Define how and what properties display, including order, values, and grouping.

Returns an array of PropertyGroup objects, which determines how to display the properties

getFooter

Create the string used for the footer.

There are two footers:

  • Simple display — Returns an empty string

  • Detailed display — Returns linked calls to methods, events, and superclasses for this class

Object States That Affect Display

There are four object states that affect how MATLAB displays objects:

  • Valid scalar object

  • Nonscalar object array

  • Empty object array

  • Scalar handle to a deleted object

State Handler Methods

Each object state has an associated method that MATLAB calls whenever displaying objects that are in that particular state.

State Handler MethodCalled for Object in This State
displayScalarObject

(isa(obj,'handle') && isvalid(obj)) && prod(size(obj)) == 1

displayNonScalarObject

prod(size(obj)) > 1

displayEmptyObject

prod(size(obj)) == 0

displayScalarHandleToDeletedObject

isa(obj,'handle') && isscalar(obj) && ~isvalid(obj)

Utility Methods

The CustomDisplay class provides utility methods that return strings that are used in various parts of the different display options. These static methods return text that simplifies the creation of customized object displays.

If the computer display does not support hypertext linking, the strings are returned without the links.

MethodInputs Outputs

convertDimensionsToString

Valid object array

Object dimensions converted to a string; determined by calling size(obj)

displayPropertyGroups

PropertyGroup array

Displays the titles and property groups defined

getClassNameForHeader

Object

Simple class name linked to the object's documentation

getDeletedHandleText

None

String'handle to deleted' linked to the documentation on deleted handles

getDetailedFooter

Object

String containing phrase 'Methods, Events, Superclasses', with each link executing the respective command on the input object

getDetailedHeader

Object

String containing linked class name, link to handle page (if handle class) and 'with properties:'

getHandleText

None

String 'handle' linked to a section of the documentation that describes handle objects

getSimpleHeader

Object

String containing linked class name and the phrase 'with properties:'

Was this topic helpful?