Dominant Argument in Overloaded Graphics Functions

Graphics Object Precedence

MATLAB^® graphics objects have the same precedence as user-defined objects. If you want to implement a method that accepts a graphics object as its first argument (for example, an axes handle), define the MATLAB graphics class as inferior to your class.

Dominant Argument

When evaluating expression involving objects of more than one class, MATLAB uses the dominant argument to determine which method or function to call.

Here is how MATLAB dispatches in response to a function call:

Determine the dominant argument based on the class of arguments.
If there is a dominant argument, call the method of the dominant class.
If arguments are of equal precedence, use the leftmost argument as the dominant argument.
If the class of the dominant argument does not define a method with the name of the called function, call the first function on the path with that name.

Defining Class Precedence

Specify the relative precedence of MATLAB classes using the InferiorClasses class attribute. Here is the basic syntax:

classdef (InferiorClasses = {?class1,?class2}) ClassName

The following definition of the TemperatureData class implements a specialized version of plot to graph temperature data. The class plot method supports a variable number of input arguments to allow an axes handle as the first argument:

plot(obj)
plot(ax,obj)

obj is an instance of the TemperatureData class and ax is an axes handle.

MATLAB calls the plot method in both cases because the TemperatureData class specifies the matlab.graphics.axis.Axes as inferior.

classdef (InferiorClasses = {?matlab.graphics.axis.Axes}) TemperatureData
   properties
      Time
      Temperature
   end
   methods
      function obj = TemperatureData(x,y)
         obj.Time = x;
         obj.Temperature = y;
      end
      function plot(varargin)
         if nargin == 1
            obj = varargin{1};
            plot(obj.Time,obj.Temperature)
         elseif nargin == 2
            ax = varargin{1};
            obj = varargin{2};
            plot(ax,obj.Time,obj.Temperature)
         elseif nargin > 2
            ax = varargin{1};
            obj = varargin{2};
            plot(ax,obj.Time,obj.Temperature,varargin{3:end})
         end
         datetick('x')
         xlabel('Time')
         ylabel('Temperature')
      end
   end
end

The following call to plot dispatches to the TemperatureData plot method, not the built-in plot function, because the TemperatureData object is dominant over the axes object.

x = 1:10;
y = rand(1,10)*100;
ax = axes;
td = TemperatureData(x,y);
plot(ax,td)

Calls to Inferior-Class Methods

When you declare a class as inferior to your class, and both classes define a method with the same name, MATLAB dispatches to your class method regardless of argument order.

Suppose the TemperatureData class that is described in the previous section defines a set method. If you attempt to assign an object of the TemperatureData class to the UserData property of an axes object:

td = TemperatureData(x,y);
set(gca,'UserData',td)

The results is a call to the TemperatureData set method. MATLAB does not call the built-in set function.

To support the use of a set function with inferior classes, implement a set method in your class that calls the built-in set function when the first argument is an object of the inferior class.

function set(varargin)
   if isa(varargin{1},'matlab.graphics.axis.Axes')
      builtin('set',varargin{:})
   else
   ...
end

Documentation