matlab.graphics.chartcontainer.ChartContainer class

Package: matlab.graphics.chartcontainer

Base class for developing chart objects

Description

matlab.graphics.chartcontainer.ChartContainer is a class for defining your own class of chart objects. When you define a subclass of this base class, you can use the ChartContainer properties and methods to build your chart objects. Specify this syntax on the first line of your class definition file to directly inherit from the ChartContainer class, where MyChart is the name of your object:

classdef MyChart < matlab.graphics.chartcontainer.ChartContainer

The matlab.graphics.chartcontainer.ChartContainer class is a handle class.

Class Attributes

`Abstract`	`true`
`HandleCompatible`	`true`

For information on class attributes, see Class Attributes.

Properties

expand all

`InnerPosition` — Chart size and location, excluding margins
`[left bottom width height]`

Chart size and location, excluding the margins for decorations such as axis labels and tick marks. Specify this property as a vector of form [left bottom width height]. The values are in the units specified by the Units property.

left — Distance from the left edge of the parent container to the inner-left edge of the chart that excludes the margins. Typically, the parent container is a figure, panel, or tab.
bottom — Distance from the bottom edge of the parent container to the inner-bottom edge of the chart that excludes the margins.
width — Width of the of chart, excluding the margins.
height — Height of the chart, excluding the margins.

Note

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

Attributes:

`GetAccess`	`public`
`SetAccess`	`public`
`Dependent`	`true`
`NonCopyable`	`true`

`OuterPosition` — Chart size and location, including margins
`[left bottom width height]`

Chart size and location, including the margins for decorations such as axis labels and tick marks. Specify this property as a vector of form [left bottom width height]. The values are in the units specified by the Units property.

left — Distance from the left edge of the parent container to the outer-left edge of the chart that includes the margins. Typically, the parent container is a figure, panel, or tab.
bottom — Distance from the bottom edge of the parent container to the outer-bottom edge of the chart that includes the margins.
width — Width of chart, including the margins.
height — Height of chart, including the margins.

Note

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

Attributes:

`GetAccess`	`public`
`SetAccess`	`public`
`Dependent`	`true`
`NonCopyable`	`true`

`Position` — Chart size and location, excluding margins
`[left bottom width height]`

Chart size and location, excluding the margins for decorations such as axis labels and tick marks. Specify this property as a vector of form [left bottom width height]. This property is equivalent to the InnerPosition property.

Note

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

Attributes:

`GetAccess`	`public`
`SetAccess`	`public`
`Dependent`	`true`
`NonCopyable`	`true`

`PositionConstraint` — Position to hold constant
`'outerposition'` | `'innerposition'`

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.

Attributes:

`GetAccess`	`public`
`SetAccess`	`public`
`Dependent`	`true`
`NonCopyable`	`true`

`Units` — Position units
`'normalized'` (default) | `'inches'` | `'centimeters'` | `'characters'` | `'points'` | `'pixels'`

Position units, specified as a value from the following table. To change the position of the chart in specific units, set the Units property before specifying the Position property. If you specify the Units and Position properties in a single command (using name-value pairs), be sure to specify Units before Position.

`Units`	Description
`'normalized'` (default)	Normalized with respect to the parent container, which is typically the figure, panel, or tab. The lower left corner of the container maps to `(0,0)`, and the upper right corner maps to `(1,1)`.
`'inches'`	Inches.
`'centimeters'`	Centimeters.
`'characters'`	Based on the default font of the graphics root object: Character width = width of letter `x`. Character height = distance between the baselines of two lines of text.
`'points'`	Typography points. One point equals 1/72 inch.
`'pixels'`	Distances in pixels are independent of your system resolution on Windows^® and Macintosh systems: 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.

Attributes:

`GetAccess`	`public`
`SetAccess`	`public`
`Dependent`	`true`
`NonCopyable`	`true`

`Layout` — Layout options
empty `LayoutOptions` array (default) | `TiledChartLayoutOptions`

Layout options, specified as a TiledChartLayoutOptions object. This property specifies options when an instance of your chart is a child of a tiled chart layout. If the instance is not a child of a tiled chart layout (for example, it is a child of a figure or panel), then this property is empty and has no effect. Otherwise, you can position the chart within the layout by setting the Tile and TileSpan properties on the TiledChartLayoutOptions object.

For example, this code places chart object c into the third tile of a tiled chart layout.

c.Layout.Tile = 3;

To make the chart span multiple tiles, specify the TileSpan property as a two-element vector. For example, this chart spans 2 rows and 3 columns of tiles.

c.Layout.TileSpan = [2 3];

Note

Tiled chart layouts are not supported for the axes returned by the getAxes method. Instead, you can place an instance of your chart into a tiled chart layout.

Attributes:

`GetAccess`	`public`
`SetAccess`	`public`

`Visible` — State of visibility
`'on'` (default) | on/off logical value

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 chart.
'off' — Hide the chart without deleting it. You still can access the properties of chart when it is not visible.

Attributes:

`GetAccess`	`public`
`SetAccess`	`public`
`Dependent`	`true`
`GetObservable`	`true`
`SetObservable`	`true`

`Parent` — Parent container
`Figure` object (default) | `Panel` object | `Tab` object | `TiledChartLayout` object

Parent container of the chart, specified as a Figure, Panel, Tab, or TiledChartLayout object.

Attributes:

`GetAccess`	`public`
`SetAccess`	`public`
`Transient`	`true`
`Dependent`	`true`
`GetObservable`	`true`
`SetObservable`	`true`
`NonCopyable`	`true`

`HandleVisibility` — Visibility of object handle
`'on'` (default) | `'off'`

Visibility of the chart object handle in its parent's list of children, specified as one of these values:

'on' — Chart object handle is always visible.
'off' — Chart object handle is invisible at all times. This option is useful for preventing unintended changes to the chart by another function. To temporarily hide the handle during the execution of that function, set the HandleVisibility to 'off'.
'callback' — Chart 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 in the Command Window, but it allows callback functions to access it.

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

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

Attributes:

`GetAccess`	`public`
`SetAccess`	`public`
`Dependent`	`true`
`GetObservable`	`true`
`SetObservable`	`true`

Methods

expand all

Protected Methods

Concrete Methods

`getAxes`	Get axes for chart container subclass
`getLayout`	Get tiled chart layout for chart container subclass

Abstract Methods

`setup`	Set up instance of chart container subclass
`update`	Update instance of chart container subclass after setting properties

Examples

collapse all

Smooth Line Plot

Open Script

Define a class called SmoothPlot that plots a set of data using a dotted blue line with a smoothed version of the line.

To define the class, create a file called SmoothPlot.m that contains the following class definition with these features:

XData and YData public properties that store the x- and y-coordinate data for the original line.
SmoothColor and SmoothWidth public properties that control the color and width of the smooth line.
OriginalLine and SmoothLine private properties that store the Line objects for original and smoothed data.
A setup method that initializes OriginalLine and SmoothLine.
An update method that updates the plot when the user changes the value of a property.
A createSmoothData method that calculates a smoothed version of YData.

classdef SmoothPlot < matlab.graphics.chartcontainer.ChartContainer
    properties
        XData (1,:) double = NaN
        YData (1,:) double = NaN
        SmoothColor (1,3) double {mustBeGreaterThanOrEqual(SmoothColor,0),...
            mustBeLessThanOrEqual(SmoothColor,1)} = [0.9290 0.6940 0.1250]
        SmoothWidth (1,1) double = 2
    end
    properties(Access = private,Transient,NonCopyable)
        OriginalLine (1,1) matlab.graphics.chart.primitive.Line
        SmoothLine (1,1) matlab.graphics.chart.primitive.Line
    end
    
    methods(Access = protected)
        function setup(obj)
            % Create the axes
            ax = getAxes(obj);
            
            % Create the original and smooth lines
            obj.OriginalLine = plot(ax,NaN,NaN,'LineStyle',':');
            hold(ax,'on')
            obj.SmoothLine = plot(ax,NaN,NaN);
            hold(ax,'off')
        end
        function update(obj)
            % Update line data
            obj.OriginalLine.XData = obj.XData;
            obj.OriginalLine.YData = obj.YData;
            obj.SmoothLine.XData = obj.XData;
            obj.SmoothLine.YData = createSmoothData(obj);
            
            % Update line color and width
            obj.SmoothLine.Color = obj.SmoothColor;
            obj.SmoothLine.LineWidth = obj.SmoothWidth;
        end
        function sm = createSmoothData(obj)
            % Calculate smoothed data
            v = ones(1,10)*0.1;
            sm = conv(obj.YData,v,'same');
        end
    end
end

Next, create a pair of x and y vectors. Plot x and y by calling the SmoothPlot constructor method, which is provided by the ChartContainer class. Specify the 'XData' and 'YData' name-value pair arguments and return the object as c.

x = 1:1:100;
y = 10*sin(x./5) + 8*sin(10.*x + 0.5);
c = SmoothPlot('XData',x,'YData',y);

Use c to change the color of the smooth line to red.

c.SmoothColor = [1 0 0];

More About

expand all

Enabling User-Defined Callbacks for Your Chart

When defining your class, you can include an events block to make the chart to listen to events.

If you define the events block with the HasCallbackProperty attribute, MATLAB creates a public property on the chart for each event in the block. Your users can use the properties to define callback functions that execute when the events are triggered. The name of each property is the name of the corresponding event with the letters Fcn appended to the end. For example, a chart that executes a callback function when the user clicks on the chart might define an event called Clicked. When the HasCallbackProperty attribute is specified, MATLAB automatically creates the corresponding public property called ClickedFcn on the chart object.

For example, here is an events block for a class of charts called MyChart:

events (HasCallbackProperty, NotifyAccess = protected) 
    Clicked 
end

When a user creates an instance of the chart, they can specify a handle to a function that executes when the someone clicks on the chart. In this case, the function myfunction executes.

 c = MyChart('ClickedFcn',@myfunction)

The function must support a specific syntax, which is described in Callback Definition.

To trigger the event and execute the callback function, use the notify method. For more information, see Overview Events and Listeners.

Compatibility Considerations

expand all

`ChartContainer` subclasses assign property values after the `setup` method runs

Behavior changed in R2020a

When you create an instance of ChartContainer subclass, and pass property name-value pair arguments to the constructor, the property values are assigned after the setup method runs. In R2019b, the property values are assigned before the setup method runs.

If the setup method of your class references the value of a property on the object, you can update your code in either of the following ways:

Assign a default value for the property when you define it.
Move the code that references the property to the update method.

`ActivePositionProperty` is not recommended

Not recommended starting in R2020a

Starting in R2020a, setting or getting ActivePositionProperty is not recommended. Use the PositionConstraint property instead.

There are no plans to remove ActivePositionProperty at this time, but the property is no longer listed when you call the set, get, or properties functions on the chart object.

To update your code, make these changes:

Replace all instances of ActivePositionProperty with PositionConstraint.
Replace all references to the 'position' option with the 'innerposition' option.

Documentation

matlab.graphics.chartcontainer.ChartContainer class

Description

Class Attributes

Properties

`InnerPosition` — Chart size and location, excluding margins
`[left bottom width height]`

Attributes:

`OuterPosition` — Chart size and location, including margins
`[left bottom width height]`

Attributes:

`Position` — Chart size and location, excluding margins
`[left bottom width height]`

Attributes:

`PositionConstraint` — Position to hold constant
`'outerposition'` | `'innerposition'`

Attributes:

`Units` — Position units
`'normalized'` (default) | `'inches'` | `'centimeters'` | `'characters'` | `'points'` | `'pixels'`

Attributes:

`Layout` — Layout options
empty `LayoutOptions` array (default) | `TiledChartLayoutOptions`

Attributes:

`Visible` — State of visibility
`'on'` (default) | on/off logical value

Attributes:

`Parent` — Parent container
`Figure` object (default) | `Panel` object | `Tab` object | `TiledChartLayout` object

Attributes:

`HandleVisibility` — Visibility of object handle
`'on'` (default) | `'off'`

Attributes:

Methods

Protected Methods

Examples

Smooth Line Plot

More About

Enabling User-Defined Callbacks for Your Chart

Compatibility Considerations

`ChartContainer` subclasses assign property values after the `setup` method runs

`ActivePositionProperty` is not recommended

See Also

Topics

MATLAB Documentation

Support

Documentation

matlab.graphics.chartcontainer.ChartContainer class

Description

Class Attributes

Properties

InnerPosition — Chart size and location, excluding margins [left bottom width height]

Attributes:

OuterPosition — Chart size and location, including margins [left bottom width height]

Attributes:

Position — Chart size and location, excluding margins [left bottom width height]

Attributes:

PositionConstraint — Position to hold constant 'outerposition' | 'innerposition'

Attributes:

Units — Position units 'normalized' (default) | 'inches' | 'centimeters' | 'characters' | 'points' | 'pixels'

Attributes:

Layout — Layout options empty LayoutOptions array (default) | TiledChartLayoutOptions

Attributes:

Visible — State of visibility 'on' (default) | on/off logical value

Attributes:

Parent — Parent container Figure object (default) | Panel object | Tab object | TiledChartLayout object

Attributes:

HandleVisibility — Visibility of object handle 'on' (default) | 'off'

Attributes:

Methods

Protected Methods

Examples

Smooth Line Plot

More About

Enabling User-Defined Callbacks for Your Chart

Compatibility Considerations

ChartContainer subclasses assign property values after the setup method runs

ActivePositionProperty is not recommended

See Also

Topics

MATLAB Documentation

Support

`InnerPosition` — Chart size and location, excluding margins
`[left bottom width height]`

`OuterPosition` — Chart size and location, including margins
`[left bottom width height]`

`Position` — Chart size and location, excluding margins
`[left bottom width height]`

`PositionConstraint` — Position to hold constant
`'outerposition'` | `'innerposition'`

`Units` — Position units
`'normalized'` (default) | `'inches'` | `'centimeters'` | `'characters'` | `'points'` | `'pixels'`

`Layout` — Layout options
empty `LayoutOptions` array (default) | `TiledChartLayoutOptions`

`Visible` — State of visibility
`'on'` (default) | on/off logical value

`Parent` — Parent container
`Figure` object (default) | `Panel` object | `Tab` object | `TiledChartLayout` object

`HandleVisibility` — Visibility of object handle
`'on'` (default) | `'off'`

`ChartContainer` subclasses assign property values after the `setup` method runs

`ActivePositionProperty` is not recommended