widthConstrainedDataRepresentation

Class: matlab.mixin.CustomCompactDisplayProvider
Namespace: matlab.mixin

Build compact display representation based on available character width

Since R2021b

expand all in page

Syntax

[rep,num] = widthConstrainedDataRepresentation(obj,displayConfiguration,width)
[rep,num] = widthConstrainedDataRepresentation(obj,displayConfiguration,width,Name=Value)

Description

[rep,num] = widthConstrainedDataRepresentation(obj,displayConfiguration,width) builds a compact display representation of the object array obj that is adjusted to the available character width, using the string converter method defined by the class of obj. The method returns the representation and number of elements included in the representation in rep and num, respectively. To construct a representation suitable for display within the container, the method uses the current display context as described in displayConfiguration.

widthConstrainedDataRepresentation tries to build a plain-text representation by fitting as many elements of obj within the available character width as possible. Depending on the value of width, the representation might include the data in all or a portion of obj elements. If width is not large enough to fit any array elements, then the method returns a representation using the array dimensions and class name.

[rep,num] = widthConstrainedDataRepresentation(obj,displayConfiguration,width,Name=Value) builds a compact display representation using additional options specified by one or more name-value arguments.

example

Input Arguments

expand all

Object array to display, specified as an object array of a class derived from matlab.mixin.CustomCompactDisplayProvider.

Description of the current display context, specified as a matlab.display.DisplayConfiguration object.

Available character width to display the object array, specified as a positive double scalar.

Name-Value Arguments

expand all

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: rep = widthConstrainedDataRepresentation(obj,displayConfiguration,width,Annotation="My Object") builds a width-constrained representation of obj that includes the specified annotation.

Textual representation of the data in the object array, specified as a string array with the same number of rows as obj. When you specify this argument, the method uses the specified string array instead of calling the string converter method of the class on the object array.

Use this argument when the class of the object array does not implement a string converter method or when the converter method does not create a string array suitable for use in a compact display scenario.

Descriptive comment about the object array, specified as an N-by-1 string array, where N is the number of rows in obj. The method appends the specified annotation to the text representing the data in the object array.

Minimum number of object array elements to include in the representation, specified as a positive integer scalar. If the method cannot include at least the specified number of elements, it returns a DimensionsAndClassNameRepresentation object with num set to zero.

Whether to truncate string scalars, specified as false or true. Use this argument when obj is represented as a string scalar (single-line layout) or a column vector of string scalars (columnar layout), and you want to make sure that the string scalars are displayed by the container of obj. When the value is true, the method truncates the string scalars, if necessary, so that they fit within the available width. It replaces the removed characters from the tails of the string scalars with an ellipsis symbol.

By default, widthConstrainedDataRepresentation does not truncate string scalars. If the value is false and a string scalar does not fit within the available width, the method returns a DimensionsAndClassNameRepresentation object with num set to zero.

Output Arguments

expand all

Compact display representation of the object array, returned as a matlab.display.PlainTextRepresentation or matlab.display.DimensionsAndClassNameRepresentation object.

By default, the method tries to represent obj as a PlainTextRepresentation object. It returns a DimensionsAndClassNameRepresentation object only in these situations:

  • The available character width is not large enough to display any of the data in obj and the annotation (if defined) using a PlainTextRepresentation object.

  • obj is an empty value.

  • obj must use the single-line display layout, but it is not a row vector.

  • obj must use the columnar display layout, but it is not a matrix.

Number of elements included in the compact display representation, returned as a nonnegative integer scalar.

Examples

expand all

Customize the compact display of your object array by fitting as many array elements within the available character width as possible, and also specifying an annotation that depends on the contents of the array.

In your current folder, create the Weekdays enumeration class by subclassing matlab.mixin.CustomCompactDisplayProvider. To customize the compact display for single-line and columnar layouts, place a call to the widthConstrainedDataRepresentation utility method within the compactRepresentationForSingleLine and compactRepresentationForColumn methods, respectively. Specify the Annotation name-value argument so that MATLAB® displays an annotation for each row of the object array that includes weekend days.

classdef WeekDays < matlab.mixin.CustomCompactDisplayProvider
    enumeration
        Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday
    end

    methods
        function rep = compactRepresentationForSingleLine(obj,displayConfiguration,width)
            [rep,~] = widthConstrainedDataRepresentation(obj,displayConfiguration,width, ...
                Annotation=annotation(obj));
        end
        function rep = compactRepresentationForColumn(obj,displayConfiguration,width)
            [rep,~] = widthConstrainedDataRepresentation(obj,displayConfiguration,width, ...
                Annotation=annotation(obj));
        end
        function res = annotation(obj)
            % Construct annotation as a column vector of strings
            numRows = size(obj,1);
            res = strings(numRows,1);
            for i = 1:numRows   % Add text for each row that includes weekend days
                currentRow = obj(i,:);
                if any(currentRow == WeekDays.Saturday) || any(currentRow == WeekDays.Sunday)
                    res(i) = "Includes Weekends";
                end
            end
        end
    end
end

In the Command Window, create a structure with a field that contains an array of a few Weekdays objects. MATLAB displays all the array elements in a single line. Additionally, because the array includes the enumeration member WeekDays.Saturday, MATLAB displays an annotation.

s = struct("FreeLunchDays",[WeekDays.Monday WeekDays.Wednesday WeekDays.Friday WeekDays.Saturday])
s = 

  struct with fields:

    FreeLunchDays: [Monday    Wednesday    Friday    Saturday]  (Includes Weekends)

Create another Weekdays array with many elements, so that they cannot all be displayed in a single line. When you assign this array to s.FreeLunchDays, MATLAB displays as many leading array elements as possible and uses an ellipsis symbol to represent the omitted elements.

days = repmat(WeekDays.Friday,1,52); 
s.FreeLunchDays = days
s = 

  struct with fields:

    FreeLunchDays: [Friday    Friday    Friday    Friday    Friday    Friday    Friday    Friday    …    ]

Now, test the custom compact display of WeekDays objects for columnar layout. Create a table T that contains a WeekDays array comprising a few elements. Because the available character width is large enough, MATLAB displays all the array elements in the Command Window. Additionally, because the second row of the array includes the enumeration member WeekDays.Saturday, MATLAB displays an annotation for that row.

Location = ["Boston"; "New York"];
FreeLunchDays = [WeekDays.Wednesday WeekDays.Friday; WeekDays.Thursday WeekDays.Saturday];
T = table(Location,FreeLunchDays)
T =

  2×2 table

     Location                   FreeLunchDays               
    __________    __________________________________________

    "Boston"      Wednesday    Friday                       
    "New York"    Thursday     Saturday  (Includes Weekends)

Update the FreeLunchDays variable using a WeekDays array with many elements. MATLAB displays as many leading array elements as possible and uses an ellipsis symbol to represent the omitted elements.

T.FreeLunchDays = repmat(WeekDays.Friday,2,52)
T =

  2×2 table

     Location                     FreeLunchDays                 
    __________    ______________________________________________

    "Boston"      Friday    Friday    Friday    Friday    …    
    "New York"    Friday    Friday    Friday    Friday    …

Tips

Version History

Introduced in R2021b

expand all

See Also

| |

Topics