Custom Display Interface

Command Window Display

MATLAB^® displays information in the command window when a statement that is not terminated with a semicolon returns a variable. For example, this statement creates a structure with a field that contains the number 7.

a.field1 = 7

MATLAB displays the variable name, class, and the value.

a = 

  struct with fields:

    field1: 7

MATLAB provides user-defined classes with similar display functionality. User-defined classes can customize how MATLAB displays objects of the class using the API provided by the matlab.mixin.CustomDisplay class. To use this API, derive your class from matlab.mixin.CustomDisplay.

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 function 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 HandleCompatible, 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 interface does not allow you to override disp, display, and details. 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:

Standard display for containers.Map object

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

Detailed display for array of containers.Map objects

You can customize how MATLAB displays objects as a result of expressions that display objects in the command window such as unterminated statements that return objects or calls to disp and display. The results displayed when calling details on an object or object array are not changed by the CustomDisplay API.

Part Builder Methods

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

Method	Purpose	Default
`getHeader`	Create the text used for the header.	Returns the `char` vectors, `[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 text used for the footer.	There are two footers: Simple display — Returns an empty `char` vector 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 Method	Called 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.

Method	Inputs	Outputs
`convertDimensionsToString`	Valid object array	Object dimensions converted to a `char` vector; 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	Text `'handle to deleted'` linked to the documentation on deleted handles
`getDetailedFooter`	Object	Text containing phrase `'Methods, Events, Superclasses'`, with each link executing the respective command on the input object
`getDetailedHeader`	Object	Text containing linked class name, link to handle page (if handle class) and `'with properties:'`
`getHandleText`	None	Text `'handle'` linked to a section of the documentation that describes handle objects
`getSimpleHeader`	Object	Text containing linked class name and the phrase `'with properties:'`