HG’s undocumented parameters interface

Continuing last week’s article on Matlab Handle Graphics’ (HG) undocumented Behavior functionality, today I describe another undocumented aspect of HG. Some of the low-level HG functions, such as line and path receive their input parameters in one of two formats:

HG line created using either of the input formats

• The regular fully-documented P-V pairs format:

  line('Marker','*', 'MarkerSize',8, 'MarkerEdgeColor','b', ...
       'Color','r', 'XData',1:5, 'YData',3:7)

• An undocumented struct-fields format:

  lineprops.Marker = '*';
  lineprops.MarkerSize = 15;
  lineprops.MarkerEdgeColor = 'b';
  lineprops.color = 'r';
  lineprops.xdata = 1:5;
  lineprops.ydata = 3:7;
   
  line(lineprops)

A sample usage of using the input struct technique can be seen (for example) in %matlabroot%/toolbox/matlab/graphics/@graphics/@datatip/datatip.m. I have also used it in my IB-Marlab application, which connects Matlab to Interactive Brokers. The idea is to make it easy for users to use whichever input format they feel more comfortable with: both P-V pairs or struct fields are supported.

Both input formats can be interchanged and mixed. We should just note that the latest (right-most) property is updated last and overrides any previous value of the same property. Here are some examples — can you guess the results of each of them?

line(lineprops, 'MarkerEdgeColor','g', 'MarkerSize',7)
line('MarkerEdgeColor','g', lineprops, 'MarkerSize',7)
line('MarkerEdgeColor','g', 'MarkerSize',7, lineprops)
line(1:4, 2:5, 'MarkerEdgeColor','g', 'MarkerSize',7, lineprops)
line(1:4, 2:5, 'MarkerEdgeColor','g', lineprops, 'MarkerSize',7)
line(1:4, 2:5, lineprops, 'MarkerEdgeColor','g', 'MarkerSize',7)

While the struct format is documented (although not widely-used) in the set function, it is not documented for line, path and other functions. Nor is it documented that we can mix the struct format with the P-V pairs format.

Note that not all HG functions support the struct input format. For example, line does, but plot does not. I do not understand the reason for this. It would seem reasonable for MathWorks to include this useful struct format for all their HG functions, and since set already supports it the extra effort would have been trivial. Maybe this will still happen in some future Matlab release…

1. ishghandle’s undocumented input parameter The built-in function ishghandle accepts a second input argument with the expected handle type....
2. getundoc – get undocumented object properties getundoc is a very simple utility that displays the hidden (undocumented) properties of a specified handle object....
3. 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...
4. Undocumented scatter plot jitter Matlab's scatter plot can automatically jitter data to enable better visualization of distribution density. ...