TiledChartLayout Properties

Tiled chart layout appearance and behavior

expand all in page

A tiled chart layout is a container for displaying a tiling of plots in a figure. Each tile can contain an axes object for displaying a plot. By changing property values, you can modify certain aspects of the layout.

t = tiledlayout(2,2);
t.TileSpacing = 'compact';

Layout

expand all

Grid size, specified as a vector of the form [m n], where m is the number of rows and n is the number of columns. You can set this property only when all the tiles in the layout are empty. When you set this property, MATLAB® sets the TileArrangement property to 'fixed'.

The value of this property might change automatically for layouts that have the TileArrangement property set to 'flow'. For example, if the parent container resizes or the number of axes in the layout changes, the grid size updates to accommodate those changes.

This property is read-only.

Tile arrangement, returned as one of these values:

  • 'fixed' — The layout has a fixed number of rows and columns as determined by the GridSize property. An m-by-n layout with this tile arrangement can display up to m*n plots.

  • 'flow' — The layout has a variable number of rows and columns that can display any number of plots. Each time you call nexttile, the layout reflows as needed to accommodate the new axes while maintaining an aspect ratio of roughly 4:3 for all the tiles.

MATLAB sets the value of this property to 'fixed' if you manually set the GridSize property.

Tile spacing, specified as 'normal', 'compact', or 'none'. Use this property to control the spacing between the tiles. The layout provides space for all decorations, such as axis labels, regardless of the value of this property.

This table shows how each value affects the appearance of a 2-by-2 layout.

ValueAppearance

'normal'

'compact'

'none'

Padding around the perimeter of the layout, specified as 'normal', 'compact', or 'none'. The layout provides space for all decorations, such as axis labels, regardless of the value of this property.

This table shows how each value affects the appearance of a 2-by-2 layout.

ValueAppearance

'normal'

'compact'

'none'

Labels

expand all

Text object for a shared title. To add a shared title, set the String property of the Text object. To change the title appearance, such as the font style or color, set other properties. For example, create a shared title for a 2-by-2 layout that has a bold font weight.

t = tiledlayout(2,2);
t.Title.String = 'My Title';
t.Title.FontWeight = 'bold';

Alternatively, pass the TiledChartLayout object to the title function.

title(t,'My Title','FontWeight','normal')

For a complete list of properties that you can specify, see Text Properties.

Note

The Text object is not contained in the Children property of the layout, so it cannot be returned by the findobj function.

Text object for the shared subtitle. To add a subtitle, set the String property of the text object. To change its appearance, such as the font angle, set other properties. For a complete list, see Text Properties.

t = tiledlayout(2,2);
t.Subtitle.String = 'An Insightful Subtitle';
t.Subtitle.FontAngle = 'italic';

Alternatively, the subtitle function to add a subtitle and control the appearance.

subtitle('An Insightful Subtitle','FontAngle','italic')

Or use the title function, and specify two character vector input arguments and two output arguments. Then set properties on the second text object returned by the function.

[tt,s] = title(t,'Clever Title','An Insightful Subtitle');
s.FontAngle = 'italic';

Note

This text object is not contained in the axes Children property, cannot be returned by findobj, and does not use default values defined for text objects.

Text object for a shared x-axis label. To add a shared x-axis label, set the String property of the text object. To change the label appearance, such as the font size, set other properties. For example, create a shared x-axis label with a 14-point font for a 2-by-2 layout. 

t = tiledlayout(2,2);
t.XLabel.String = 'My x-Axis Label';
t.XLabel.FontSize = 14;

Alternatively, pass the TiledChartLayout object to the xlabel function.

xlabel(t,'My x-Axis Label','FontSize',14)

For a complete list of properties you can specify, see Text Properties.

Note

The Text object is not contained in the axes Children property, so it cannot be returned by findobj.

Text object for a shared y-axis label. To add a shared y-axis label, set the String property of the text object. To change the label appearance, such as the font size, set other properties. For example, create a shared y-axis label with a 14-point font for a 2-by-2 layout. 

t = tiledlayout(2,2);
t.YLabel.String = 'My y-Axis Label';
t.YLabel.FontSize = 14;

Alternatively, pass the TiledChartLayout object to the ylabel function.

ylabel(t,'My y-Axis Label','FontSize',14)

For a complete list of properties you can specify, see Text Properties.

Note

The Text object is not contained in the axes Children property, so it cannot be returned by findobj.

Position

expand all

Outer size and location, including the margins for decorations such titles and axis labels, specified as a four-element vector of the form [left bottom width height]. The values in the vector are in the units specified by the Units property. The default value of [0 0 1 1] includes the whole interior of the container.

  • The left and bottom elements define the distance from the lower left corner of the container (typically a figure, panel, or tab) to the lower left corner of the outer position boundary.

  • The width and height elements are the outer position boundary dimensions.

In the following layout, the blue rectangle represents the OuterPosition property, and the red rectangle represents the InnerPosition and Position properties (which have the same value).

2-by-2 layout with a blue rectangle that surrounds the four axes and labels. A red rectangle surrounds the four plot boxes only.

Note

Setting this property has no effect when the parent container is a TiledChartLayout.

Inner size and location, excluding the margins for decorations such titles and axis labels, specified as a four-element vector of the form [left bottom width height]. This property is equivalent to the Position property.

Note

Setting this property has no effect when the parent container is a TiledChartLayout.

Inner size and location, excluding the margins for decorations such titles and axis labels, specified as a four-element vector of the form [left bottom width height]. The values in the vector are in the units specified by the Units property.

  • The left and bottom elements define the distance from the lower left corner of the container (typically a figure, panel, or tab) to the lower left corner of the position boundary.

  • The width and height elements are the position boundary dimensions. For axes in a 3-D view, the Position property is the smallest rectangle that encloses the axes.

In the following layout, the blue rectangle represents the OuterPosition property, and the red rectangle represents the InnerPosition and Position properties (which have the same value).

2-by-2 layout with a blue rectangle that surrounds the four axes and labels. A red rectangle surrounds the four plot boxes only.

Note

Setting this property has no effect when the parent container is a TiledChartLayout.

Position property to hold constant when adding, removing, or changing decorations, specified as one of the following values:

  • 'outerposition' — The OuterPosition property remains constant when you add, remove, or change decorations such as a title or an axis label. If any positional adjustments are needed, MATLAB adjusts the InnerPosition property.

  • 'innerposition' — The InnerPosition property remains constant when you add, remove, or change decorations such as a title or an axis label. If any positional adjustments are needed, MATLAB adjusts the OuterPosition property.

Note

Setting this property has no effect when the parent container is a TiledChartLayout.

Position units, specified as one of the values in this table.

UnitsDescription
'normalized' (default)Normalized with respect to the parent container, which is usually the figure. The lower left corner of the figure maps to (0,0) and the upper right corner maps to (1,1).
'inches'Inches.
'centimeters'Centimeters.
'characters'

Based on the default system font character size.

  • Character width = width of letter x.

  • Character height = distance between the baselines of two lines of text.

'points'Points. One point equals 1/72 inch.
'pixels'

Pixels.

  • On Windows® systems, a pixel is 1/96th of an inch.

  • On Macintosh systems, a pixel is 1/72nd of an inch.

  • On Linux® systems, the size of a pixel is determined by your system resolution.

All units are measured from the lower-left corner of the parent container.

This property affects other properties, such as the Position property. If you change the units, then return the units to the default value after completing your computation to prevent affecting other functions that assume the default value.

If you specify the Position and Units properties as Name,Value pairs when creating the object, then the order of specification matters. For example, to set the position in specific units, then you must set the Units property before the Position property.

Layout options, specified as a TiledChartLayoutOptions object or a GridLayoutOptions object. Use this property to position a nested layout within its parent layout. For instance, to position a layout within another tiled chart layout, set the Tile and TileSpan properties on the TiledChartLayoutOptions object.

For example, this code positions layout2 into the third tile of layout1.

layout1 = tiledlayout(2,2);
layout2 = tiledlayout(layout1,1,3);
layout2.Layout.Tile = 3;

To make the nested layout span multiple tiles, specify the TileSpan property as a two-element vector. For example, this code spans layout2 across one row and two columns of tiles.

layout2.Layout.TileSpan = [1 2];
If you fill all the tiles in both layouts, the composite layout looks like this:

2-by-2 layout with a nested 1-by-3 layout in the second row.

To place the layout into a grid layout within an app, specify this property as a GridLayoutOptions object. For more information about working with grid layouts in apps, see uigridlayout.

If the layout is not a child of another layout (for example, if it is a child of a figure or panel), then this property is empty and has no effect.

Interactivity

expand all

Shared data exploration toolbar, specified as an AxesToolbar object returned by the axtoolbar function. The toolbar appears in the top-right corner of the of the layout when you hover over it.

By default, there is no shared toolbar, and each of the individual axes objects has its own toolbar. When you create a shared toolbar, the toolbars on the individual axes objects become hidden. If you do not want any toolbars in the layout, leave this property empty and set the set the Visible property of the AxesToolbar object to 'off' for each axes.

t = tiledlayout(2,1);
ax = nexttile;
ax.Toolbar.Visible = 'off';

State of visibility, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

  • 'on' — Display the object.

  • 'off' — Hide the object without deleting it. You still can access the properties of an invisible object.

Callbacks

expand all

Object creation function, specified as one of these values:

  • Function handle.

  • Cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

  • Character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback as a function handle, cell array, or character vector, see Callback Definition.

This property specifies a callback function to execute when MATLAB creates the object. MATLAB initializes all property values before executing the CreateFcn callback. If you do not specify the CreateFcn property, then MATLAB executes a default creation function.

Setting the CreateFcn property on an existing component has no effect.

If you specify this property as a function handle or cell array, you can access the object that is being created using the first argument of the callback function. Otherwise, use the gcbo function to access the object.

Object deletion function, specified as one of these values:

  • Function handle.

  • Cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

  • Character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback as a function handle, cell array, or character vector, see Callback Definition.

This property specifies a callback function to execute when MATLAB deletes the object. MATLAB executes the DeleteFcn callback before destroying the properties of the object. If you do not specify the DeleteFcn property, then MATLAB executes a default deletion function.

If you specify this property as a function handle or cell array, you can access the object that is being deleted using the first argument of the callback function. Otherwise, use the gcbo function to access the object.

Callback Execution Control

expand all

Callback interruption, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

This property determines if a running callback can be interrupted. There are two callback states to consider:

  • The running callback is the currently executing callback.

  • The interrupting callback is a callback that tries to interrupt the running callback.

Whenever MATLAB invokes a callback, that callback attempts to interrupt the running callback (if one exists). The Interruptible property of the object owning the running callback determines if interruption is allowed.

  • A value of 'on' allows other callbacks to interrupt the object's callbacks. The interruption occurs at the next point where MATLAB processes the queue, such as when there is a drawnow, figure, uifigure, getframe, waitfor, or pause command.

    • If the running callback contains one of those commands, then MATLAB stops the execution of the callback at that point and executes the interrupting callback. MATLAB resumes executing the running callback when the interrupting callback completes.

    • If the running callback does not contain one of those commands, then MATLAB finishes executing the callback without interruption.

  • A value of 'off' blocks all interruption attempts. The BusyAction property of the object owning the interrupting callback determines if the interrupting callback is discarded or put into a queue.

Note

Callback interruption and execution behave differently in these situations:

  • If the interrupting callback is a DeleteFcn, CloseRequestFcn or SizeChangedFcn callback, then the interruption occurs regardless of the Interruptible property value.

  • If the running callback is currently executing the waitfor function, then the interruption occurs regardless of the Interruptible property value.

  • Timer objects execute according to schedule regardless of the Interruptible property value.

When an interruption occurs, MATLAB does not save the state of properties or the display. For example, the object returned by the gca or gcf command might change when another callback executes.

Callback queuing, specified as 'queue' or 'cancel'. The BusyAction property determines how MATLAB handles the execution of interrupting callbacks. There are two callback states to consider:

  • The running callback is the currently executing callback.

  • The interrupting callback is a callback that tries to interrupt the running callback.

Whenever MATLAB invokes a callback, that callback attempts to interrupt a running callback. The Interruptible property of the object owning the running callback determines if interruption is permitted. If interruption is not permitted, then the BusyAction property of the object owning the interrupting callback determines if it is discarded or put in the queue. These are possible values of the BusyAction property:

  • 'queue' — Puts the interrupting callback in a queue to be processed after the running callback finishes execution.

  • 'cancel' — Does not execute the interrupting callback.

This property is read-only.

Deletion status, returned as an on/off logical value of type matlab.lang.OnOffSwitchState.

MATLAB sets the BeingDeleted property to 'on' when the DeleteFcn callback begins execution. The BeingDeleted property remains set to 'on' until the component object no longer exists.

Check the value of the BeingDeleted property to verify that the object is not about to be deleted before querying or modifying it.

Parent/Child

expand all

Parent container, specified as a Figure, Panel, Tab, TiledChartLayout, or GridLayout object.

Children, returned as an array of graphics objects. Use this property to view a list of the children or to reorder the children by setting the property to a permutation of itself.

You cannot add or remove children using the Children property. To add a child to this list, set the Parent property of the child graphics object to the TiledChartLayout object.

Visibility of the object handle in the Children property of the parent, specified as one of these values:

  • 'on' — Object handle is always visible.

  • 'off' — Object handle is invisible at all times. This option is useful for preventing unintended changes by another function. Set the HandleVisibility to 'off' to temporarily hide the handle during the execution of that function.

  • 'callback' — Object handle is visible from within callbacks or functions invoked by callbacks, but not from within functions invoked from the command line. This option blocks access to the object at the command line, but permits callback functions to access it.

If the object is not listed in the Children property of the parent, then functions that obtain object handles by searching the object hierarchy or querying handle properties cannot return it. Examples of such functions include the get, findobj, gca, gcf, gco, newplot, cla, clf, and close functions.

Hidden object handles are still valid. Set the root ShowHiddenHandles property to 'on' to list all object handles regardless of their HandleVisibility property setting.

Identifiers

expand all

This property is read-only.

Type of graphics object returned as 'tiledlayout'.

Object identifier, specified as a character vector or string scalar. You can specify a unique Tag value to serve as an identifier for an object. When you need access to the object elsewhere in your code, you can use the findobj function to search for the object based on the Tag value.

User data, specified as any MATLAB array. For example, you can specify a scalar, vector, matrix, cell array, character array, table, or structure. Use this property to store arbitrary data on an object.

If you are working in App Designer, create public or private properties in the app to share data instead of using the UserData property. For more information, see Share Data Within App Designer Apps.

See Also

|

Introduced in R2019b

MATLAB Documentation

Support