Main Content

New in R2022b: GridSizeChangedFcn
tiledlayout() creates a TiledChartLayout object that defines a gridded layout of axes within a figure. When using the 'flow' option, the grid size becomes dynamic and updates as axes are added or as the figure size changes. These features were introduced in R2019b and if you're still stuck on using subplot, you're missing out on several other great features of tiledlayout.
Starting in MATLAB R2022b you can define a callback function that responds to changes to the grid size in flow arrangements by setting the new gridSizeChangedFcn.
Use case
I often use a global legend to represent data across all axes within a figure. When the figure is tall and narrow, I want the legend to be horizontally oriented at the bottom of the figure but when the figure is short and wide, I prefer a vertically oriented legend on the right of the figure. By using the gridSizeChangedFcn, now I can update the legend location and orientation when the grid size changes.
Demo
gridSizeChangeFcn works like all other graphics callback functions. In this demo, I've named the gridSizeChangedFcn "updateLegendLayout", assigned by an anonymous function. The first input is the TiledChartLayout object and the second input is the event object that indicates the old and new grid sizes. The legend handle is also passed into the function. Since all of the tiles contain the same groups of data, the legend is based on data in the last tile.
As long as the legend is valid, the gridSizeChangedFcn updates the location and orientation of the legend so that when the grid is tall, the legend will be horizontal at the bottom of the figure and when the grid is wide, the legend will be vertical at the right of the figure.
Since the new grid size is available as a property in the TiledChartLayout object, I chose not to use the event argument. This way I can directly call the callback function at the end to update the legend without having to create an event.
Run this example from an m-file. Then change the width or height of the figure to demonstrate the legend adjustments.
% Prepare data
data1 = sort(randn(6))*10;
data2 = sort(randn(6))*10;
labels = ["A","B","C","D","E","F"];
groupLabels = categorical(["Control", "Test"]);
% Generate figure
fig = figure;
tcl = tiledlayout(fig, "flow", TileSpacing="compact", Padding="compact");
nTiles = height(data1);
h = gobjects(1,nTiles);
for i = 1:nTiles
ax = nexttile(tcl);
groupedData = [data1(i,:); data2(i,:)];
h = bar(ax,groupLabels, groupedData, "grouped");
title(ax,"condition " + i)
end
title(tcl,"GridSizeChangedFcn Demo")
ylabel(tcl,"Score")
legh = legend(h, labels);
title(legh,"Factors")
% Define and call the GridSizeChangeFcn
tcl.GridSizeChangedFcn = @(tclObj,event)updateLegendLayout(tclObj,event,legh);
updateLegendLayout(tcl,[],legh);
% Manually resize the vertical and horizontal dimensions of the figure
function updateLegendLayout(tclObj,~,legh)
% Evoked when the TiledChartLayout grid size changes in flow arrangements.
% tclObj - TiledChartLayout object
% event - (unused in this demo) contains old and new grid size
% legh - legend handle
if isgraphics(legh,'legend')
if tclObj.GridSize(1) > tclObj.GridSize(2)
legh.Layout.Tile = "south";
legh.Orientation = "horizontal";
else
legh.Layout.Tile = "east";
legh.Orientation = "vertical";
end
end
end
Give it a shot in MATLAB R2022b
  • Replace the legend with a colorbar to update the location and orientation of the colorbar.
  • Define a GridSizeChangedFcn within the loop so that it is called every time a tile is added.
  • Create a figure with many tiles (~20) and dynamically set a color to each row of axes.
  • Assign xlabels only to the bottom row of tiles and ylabels to only the left column of tiles.
Learn about other new features
This article is attached as a live script.
Adam Danz
Adam Danz
Last activity on 17 Oct 2023

New in R2021a: LimitsChangedFcn

New in R2021a, LimitsChangedFcn

LimitsChangedFcn is a callback function that responds to changes to axis limits ( release notes ). The function responds to axis interaction such as panning and zooming, programmatically setting the axis limits, or when axis limits are automatically adjusted by other processes.

LimitsChangedFcn is a property of ruler objects which are properties of axes and can be independently set for each axis. For example,

ax = gca(); 
ax.XAxis.LimitsChangedFcn = ... % Responds to changes to XLim
ax.YAxis.LimitsChangedFcn = ... % Responds to changes to YLim
ax.ZAxis.LimitsChangedFcn = ... % Responds to changes to ZLim

Previously, a listener could be assigned to respond to changes to axis limits. Here are some examples.

However, LimitsChangedFcn responds more reliably than a listener that responds to setting/getting axis limits. For example, after zooming or panning the axes in the demo below, the listener does not respond to the Restore View button in the axis toolbar but LimitsChangedFcn does! After restoring the view, try zooming out which does not result in changes to axis limits yet the listener will respond but the LimitsChangedFcn will not. Adding objects to axes after an axis-limit listener is set will not trigger the listener even if the added object expands the axis limits ( why not? ) but LimitsChangedFcn will!

ax = gca(); 
ax.UserData.Listener = addlistener(ax,'XLim','PostSet',@(~,~)disp('Listener')); 
ax.XAxis.LimitsChangedFcn = @(~,~)disp('LimitsChangedFcn')

How to use LimitsChangedFcn

The LimitsChangedFcn works like any other callback. For review,

The first input to the LimitsChangedFcn callback function is the handle to the axis ruler object that was changed.

The second input is a structure that contains the old and new limits. For example,

    LimitsChanged with properties:
      OldLimits: [0 1]
      NewLimits: [0.25 0.75]
         Source: [1×1 NumericRuler]
      EventName: 'LimitsChanged'

Importantly, since LimitsChangedFcn is a property of the axis rulers rather than the axis object, changes to the axes may clear the LimitsChangedFcn property if the axes aren't held using hold on. For example,

% Axes not held
ax = gca(); 
ax.XAxis.LimitsChangedFcn = @(ruler,~)title(ancestor(ruler,'axes'),'LimitsChangedFcn fired!'); 
plot(ax, 1:5, rand(1,5), 'o')
ax.XAxis.LimitsChangedFcn

ans =
    0×0 empty char array

% Axes held
ax = gca(); 
hold(ax,'on')
ax.XAxis.LimitsChangedFcn = @(ruler,~)title(ancestor(ruler,'axes'),'LimitsChangedFcn fired!'); 
plot(ax, 1:5, rand(1,5), 'o')
ax.XAxis.LimitsChangedFcn

ans =
  function_handle with value:
    @(ruler,~)title(ancestor(ruler,'axes'),'LimitsChangedFcn fired!')

Demo

In this simple app a LimitsChangedFcn callback function is assigned to the x and y axes. The function does two things:

  1. Text boxes showing the current axis limits are updated
  2. The prying eyes that are centered on the axes will move to the new axis center

This demo also uses Name=Value syntax and emoji text objects !

Create app

h.fig = uifigure(Name="LimitsChangedFcn Demo", ...
    Resize="off");
h.fig.Position(3:4) = [500,260];
movegui(h.fig)
h.ax = uiaxes(h.fig,...
    Units="pixels", ...
    Position=[200 26 250 208], ...
    Box="on");
grid(h.ax,"on")
title(h.ax,"I'm following you!")
h.eyeballs = text(h.ax, .5, .5, ...
    char([55357 56385 55357 56385]), ...
    HorizontalAlignment="center", ...
    FontSize=40);
h.label = uilabel(h.fig, ...
    Text="Axis limits", ...
    Position=[25 212 160 15], ...
    FontWeight="bold",...
    HorizontalAlignment="center");
h.xtxt = uitextarea(h.fig, ...
    position=[25 191 160 20], ...
    HorizontalAlignment="center", ...
    WordWrap="off", ...
    Editable="off",...
    FontName=get(groot, 'FixedWidthFontName'));
h.ytxt = uitextarea(h.fig, ...
    position=[25 165 160 20], ...
    HorizontalAlignment="center", ...
    WordWrap="off", ...
    Editable="off", ...
    FontName=get(groot, 'FixedWidthFontName'));
h.label = uilabel(h.fig, ...
    Text=['X',newline,newline,'Y'], ...
    Position=[10 170 15 38], ...
    FontWeight="bold");

Set LimitsChangedFcn of x and y axes

h.ax.XAxis.LimitsChangedFcn = @(hObj,data)limitsChangedCallbackFcn(hObj,data,h,'x');
h.ax.YAxis.LimitsChangedFcn = @(hObj,data)limitsChangedCallbackFcn(hObj,data,h,'y');

Update text fields

xlim(h.ax, [-100,100])
ylim(h.ax, [-100,100])

Define LimitsChangedFcn

function limitsChangedCallbackFcn(rulerHand, limChgData, handles, xy)
% limitsChangedCallbackFcn() responds to changes to x or y axis limits.
% - rulerHand: Ruler handle for x or y axis that was changed (not used in this demo)
% - limChgData: LimitsChanged data structure
% - handles: structure of App handles
% - xy: either 'x' or 'y' identifying rulerHand
switch lower(xy)
    case 'x'
        textHandle = handles.xtxt;
        positionIndex = 1; 
    case 'y'
        textHandle = handles.ytxt;
        positionIndex = 2; 
    otherwise
        error('xy is a character ''x'' or ''y''.')
end
% Update text boxes showing rounded axis limits
textHandle.Value = sprintf('[%.3f, %.3f]',limChgData.NewLimits);
% Move the eyes to the new center position
handles.eyeballs.Position(positionIndex) = limChgData.NewLimits(1)+range(limChgData.NewLimits)/2; % for linear scales only!
drawnow
end

See attached mlx file for a copy of this thread.

Highlight Icon image