Matlab’s Handle Graphics (HG) have been around for ages. Still, to this day it contains many hidden gems. Today I discuss HG’s Behavior property, which is a standard undocumented hidden property of all HG objects.
Behavior is not normally updated directly (although there is absolutely nothing to prevent this), but rather via the semi-documented built-in accessor functions hggetbehavior and hgaddbehavior. This manner of accessing Behavior is similar to its undocumented sibling property ApplicationData, which is accessed by the corresponding getappdata and setappdata functions.
Using HB behaviors
hggetbehavior with no input args displays a list of all pre-installed HG behaviors:
>> hggetbehavior Behavior Object Name Target Handle -------------------------------------------- 'Plotedit'...................Any Graphics Object 'Print'......................Any Graphics Object 'Zoom'.......................Axes 'Pan'........................Axes 'Rotate3d'...................Axes 'DataCursor'.................Axes and Axes Children 'MCodeGeneration'............Axes and Axes Children 'DataDescriptor'.............Axes and Axes Children 'PlotTools'..................Any graphics object 'Linked'.....................Any graphics object 'Brush'......................Any graphics object
hggetbehavior can be passed a specific behavior name (or cell array of names), in which case it returns the relevant behavior object handle(s):
>> hBehavior = hggetbehavior(gca, 'Zoom') hBehavior = graphics.zoombehavior >> hBehavior = hggetbehavior(gca, {'Zoom', 'Pan'}) hBehavior = handle: 1-by-2
As the name indicates, the behavior object handle controls the behavior of the relevant action. For example, the behavior object for Zoom contains the following properties:
>> hBehavior = hggetbehavior(gca, 'Zoom'); >> get(hBehavior) Enable: 1 % settable: true/false Serialize: 1 % settable: true/false Name: 'Zoom' % read-only Style: 'both' % settable: 'horizontal', 'vertical' or 'both'
By setting the behavior’s properties, we can control whether the axes will have horizontal, vertical, 2D or no zooming enabled, regardless of whether or not the toolbar/menu-bar zoom item is selected:
hBehavior.Enable = false; % or: set(hBehavior,'Enable',false) hBehavior.Style = 'horizontal'; % or: set(hBehavior,'Style','horizontal')
This mechanism is used internally by Matlab to disable zoom/pan/rotate3d (see %matlabroot%/toolbox/matlab/graphics/@graphics/@zoom/setAllowAxesZoom.m and similarly setAllowAxesPan, setAllowAxesRotate).
At this point, some readers may jump saying that we can already do this via the zoom object handle that is returned by the zoom function (where the Style property was renamed Motion, but never mind). However, I am just trying to show the general usage. Not all behaviors have similar documented customizable mechanisms. In fact, using behaviors we can control specific behaviors for separate HG handles in the same figure/axes.
For example, we can set a different callback function to different HG handles for displaying a plot data-tip (a.k.a. data cursor). I have explained in the past how to programmatically control data-tips, but doing so relies on the figure datacursormode, which is figure-wide. If we want to display different data-tips for different plot handles, we would need to add logic into our custom update function that would change the returned string based on the clicked handle. Using HG behavior we can achieve the same goal much easier:
% Use dataCursorLineFcn() for the line data-tip bh = hggetbehavior(hLine,'DataCursor'); set(bh,'UpdateFcn',@dataCursorLineFcn); % Use dataCursorAnnotationFcn() for the annotation data-tip bh = hggetbehavior(hAnnotation,'DataCursor'); set(bh,'UpdateFcn',{@dataCursorAnnotationFcn,extraData});
Note: there is also the related semi-documented function hgbehaviorfactory, which is used internally by hggetbehavior and hgaddbehavior. I do not see any need for using hgbehaviorfactory directly, only hggetbehavior and hgaddbehavior.
Custom behaviors
The standard behavior objects are UDD schema objects (i.e., the old object-oriented mechanism in MATLAB). They are generally located in a separate folder beneath %matlabroot%/toolbox/matlab/graphics/@graphics/. For example, the Zoom behavior object is located in %matlabroot%/toolbox/matlab/graphics/@graphics/@zoombehavior/. These behavior object folders generally contain a schema.m file (that defines the behavior object class and its properties), and a dosupport.m function that returns a logical flag indicating whether or not the behavior is supported for the specified handle. These are pretty standard functions, here is an example:
% Zoom behavior's schema.m: function schema % Copyright 2003-2006 The MathWorks, Inc. pk = findpackage('graphics'); cls = schema.class(pk,'zoombehavior'); p = schema.prop(cls,'Enable','bool'); p.FactoryValue = true; p = schema.prop(cls,'Serialize','MATLAB array'); p.FactoryValue = true; p.AccessFlags.Serialize = 'off'; p = schema.prop(cls,'Name','string'); p.AccessFlags.PublicSet = 'off'; p.AccessFlags.PublicGet = 'on'; p.FactoryValue = 'Zoom'; p.AccessFlags.Serialize = 'off'; % Enumeration Style Type if (isempty(findtype('StyleChoice'))) schema.EnumType('StyleChoice',{'horizontal','vertical','both'}); end p = schema.prop(cls,'Style','StyleChoice'); p.FactoryValue = 'both';
% Zoom behavior's dosupport.m: function [ret] = dosupport(~,hTarget) % Copyright 2003-2009 The MathWorks, Inc. % axes ret = ishghandle(hTarget,'axes');
All behaviors must define the Name property, and most behaviors also define the Serialize and Enable properties. In addition, different behaviors define other properties. For example, the DataCursor behavior defines the CreateNewDatatip flag and no less than 7 callbacks:
function schema % Copyright 2003-2008 The MathWorks, Inc. pk = findpackage('graphics'); cls = schema.class(pk,'datacursorbehavior'); p = schema.prop(cls,'Name','string'); p.AccessFlags.PublicSet = 'off'; p.AccessFlags.PublicGet = 'on'; p.FactoryValue = 'DataCursor'; schema.prop(cls,'StartDragFcn','MATLAB callback'); schema.prop(cls,'EndDragFcn','MATLAB callback'); schema.prop(cls,'UpdateFcn','MATLAB callback'); schema.prop(cls,'CreateFcn','MATLAB callback'); schema.prop(cls,'StartCreateFcn','MATLAB callback'); schema.prop(cls,'UpdateDataCursorFcn','MATLAB callback'); schema.prop(cls,'MoveDataCursorFcn','MATLAB callback'); p = schema.prop(cls,'CreateNewDatatip','bool'); p.FactoryValue = false; p.Description = 'True will create a new datatip for every mouse click'; p = schema.prop(cls,'Enable','bool'); p.FactoryValue = true; p = schema.prop(cls,'Serialize','MATLAB array'); p.FactoryValue = true; p.AccessFlags.Serialize = 'off';
Why am I telling you all this? Because in addition to the standard behavior objects we can also specify custom behaviors to HG handles. All we need to do is mimic one of the standard behavior object classes in a user-defined class, and then use hgaddbehavior to add the behavior to an HG handle. Behaviors are differentiated by their Name property, so we can either use a new name for the new behavior, or override a standard behavior by reusing its name.
hgaddbehavior(hLine,myNewBehaviorObject)
If you wish the behavior to be serialized (saved) to disk when saving the figure, you should add the Serialize property to the class and set it to true, then use hgaddbehavior to add the behavior to the relevant HG handle. The Serialize property is searched-for by the hgsaveStructDbl function when saving figures (I described hgsaveStructDbl here). All the standard behaviors except DataDescriptor have the Serialize property (I don’t know why DataDescriptor doesn’t).
Just for the record, you can also use MCOS (not just UDD) class objects for the custom behavior, as mentioned by the internal comment within the hgbehaviorfactory function. Most standard behaviors use UDD schema classes; an example of an MCOS behavior is PlotEdit that is found at %matlabroot%/toolbox/matlab/graphics/+graphics/+internal/@PlotEditBehavor/PlotEditBehavor.m.
ishghandle‘s undocumented type input arg
Note that the Zoom behavior’s dosupport function uses an undocumented format of the built-in ishghandle function, namely accepting a second parameter that specifies a specific handle type, which presumably needs to correspond to the handle’s Type property:
ret = ishghandle(hTarget,'axes');
The hasbehavior function
Another semi-documented built-in function called hasbehavior is located right next to hggetbehavior and hgaddbehavior in the %matlabroot%/toolbox/matlab/graphics/ folder.
Despite its name, and the internal comments that specifically mention HG behaviors, this function is entirely independent of the HG behavior mechanism described above, and in fact makes use of the ApplicationData property rather than Behavior. I have no idea why this is so. It may be a design oversight or some half-baked attempt by a Mathworker apprentice to emulate the behavior mechanism. Even the function name is misleading: in fact, hasbehavior not only checks whether a handle has some “behavior” (in the 2-input args format) but also sets this flag (in the 3-input args format).
hasbehavior is used internally by the legend mechanism, to determine whether or not an HG object (line, scatter group, patch, annotation etc.) should be added to the legend. This can be very important for plot performance, since the legend would not need to be updated whenever these objects are modified in some manner:
hLines = plot(rand(3,3)); hasbehavior(hLines(1), 'legend', false); % line will not be in legend hasbehavior(hLines(2), 'legend', true); % line will be in legend
(for anyone interested, the relevant code that checks this flag is located in %matlabroot%/toolbox/matlab/scribe/private/islegendable.m)
hasbehavior works by using a dedicated field in the handle’s ApplicationData struct with a logical flag value (true/false). The relevant field is called [name,'_hgbehavior'], where name is the name of the so-called “behavior”. In the example above, it creates a field called “legend_hgbehavior”.
Do you know of any neat uses for HG behaviors? If so, please post a comment below.
Related posts:
- Undocumented scatter plot behavior The scatter plot function has an undocumented behavior when plotting more than 100 points: it returns a single unified patch object handle, rather than a patch handle for each specific...
- Performance: accessing handle properties Handle object property access (get/set) performance can be significantly improved using dot-notation. ...
- Displaying hidden handle properties I present two ways of checking undocumented hidden properties in Matlab Handle Graphics (HG) handles...
- Waterloo graphics beta The Waterloo graphics library extends Matlab graphics with numerous customizable plots that can be embedded in Matlab figures. ...