HG's undocumented parameters interface

March 14, 2013 6 Comments

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 patch 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)
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)
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, patch 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…

6 Responses

Eric March 14, 2013 at 08:13 Reply

Is this behavior because the functions use INPUTPARSER? If so, perhaps it is true for any function that uses inputparser – I haven’t tested it out to see…

Yair Altman March 14, 2013 at 08:17 Reply

@Eric – both line, patch and inputparser are internal functions whose contents are not accessible for us to check.

ishghandle’s undocumented input parameter | Undocumented Matlab March 27, 2013 at 14:09 Reply

[…] Two weeks ago I wrote about Matlab Handle Graphics (HG) undocumented acceptance of structs as input parameter to some plotting functions. Continuing in a related matter, today I expose an undocumented input parameter for HG’s ishghandle function […]
Miguel Gaspar April 4, 2013 at 12:25 Reply
I had also noticed this sometime ago. It would seem very useful to use with:
hprops=get(h); hprops.some_property=... set(h,hprops)
hprops=get(h); hprops.some_property=... set(h,hprops)
but unfortunately get(h) returns read-only properties, which result in an error when used with set():
```
>> set(hl,linep)
??? Error using ==> set
Attempt to modify a property that is read-only.
Object Name :  line
Property Name :  'Annotation'.
```
Do you know how to overcome this?

Yair Altman April 4, 2013 at 14:30 Reply
@Miguel – why not simply pass to set only the changed properties, that you can be certain are settable? For example:
hprops = []; hprops.some_property1 = ... hprops.some_property2 = ... set(h,hprops)
hprops = []; hprops.some_property1 = ... hprops.some_property2 = ... set(h,hprops)

Miguel Gaspar April 4, 2013 at 15:38

Hi, Yair,

Thanks for your reply, and above all, thanks for the continuous stream of pearls you provide…

I would like to use the get() method for two reasons:
– symmetry: it has some aesthetic appeal, feels natural to me;
– laziness: it would allow the use of auto-complete…

not very strong reasons, specially since recent versions of Matlab provide auto-complete of property names in set/get, but still prompted me to write this function:

function hprops=getset(h)
% Returns only the settable properties for the handle graphics object h, so
% that it can be used directly in the form:
% set(h,hprops)
 
fn=fieldnames(set(h(1)));
fv=get(h,fn);
hprops=cell2struct(fv',fn,1);

Unfortunately, although this works for a vector of handles, of same type, returning a vector struct, this can’t be used in set(...):

hlines=findobj(gca,'Type','line');
lineprops=getset(hlines);
lineprops(1).LineStyle=':';
lineprops(2).LineStyle='-';
set(hlines,lineprops)

since only the last value specified for each property is used, and applied to all handle graphics objects…

A syntax for assigning different values to properties of multiple objects is available for the plot(...) function, which accepts the following:

plot(1:4, [2,4,5,8], 'r',...
     1:4, [3 2 1 4], 'g')

My preferred way of working with handle graphics is to use hg objects instead of handles, although in some cases it requires some additional steps:

hline=hg.line('XData',1:4,'YData',[2,4,5,8]);
hline.Visible=false;
hline.XData=[hline.XData,5];
hline.YData=[hline.YData,3];
hline.Visible=true;
% or:
[hline.XData,hline.YData]=deal([hline.XData,5],[hline.YData,3]);

Which method (set(…) with PV pairs, set(…) with struct, or hg objects) do you prefer?

HTML tags such as <b> or <i> are accepted.
Wrap code fragments inside <pre lang="matlab"> tags, like this:

<pre lang="matlab">
a = magic(3);
disp(sum(a))
</pre>

I reserve the right to edit/delete comments (read the site policies).
Not all comments will be answered. You can always email me (altmany at gmail) for private consulting.

Click here to cancel reply.

Rolf (18 days 13 hours ago): Disclosure: This comes from the developer/vendor of the Code Checker for MATLAB. Have a look at the Code Checker for MATLAB by MonkeyProof Solutions which has many such (configurable)...
Yair Altman (26 days 6 hours ago): In theory you could use the data: URI scheme (e.g. .load('data:text/html,<html ><body>Hello world</body></html>')), but for some reason it doesn’t work well in...
Sebastian (26 days 12 hours ago): Thanks for your update to the now unsupported `HTMLBrowserPanel`. I tried to replace it with the `LightweightHelpPanel` but the application I am working on is showing generated...
Leuze (48 days 13 hours ago): Hello, I would like to add a new object into SLDD and display columns according to my object properties <>
Eric Delgado (77 days 15 hours ago): Hey Yair, I think your site is the right place to share that I wrote ccTools, a lib that allows a lot of customizations of Matlab built-in web components (such as uifigure,...
Eric Delgado (77 days 15 hours ago): Hey guys, first of all, thanks to @Yair, your site saved me a lot of times! 🙂 That’s why I am sharing that I wrote m2mlapp (*.m => *.mlapp) file conversion, that...
François (94 days 13 hours ago): more than 10 years later it helps me after struggling few hours, so thanks you very much !
Yair Altman (95 days 11 hours ago): I am not familiar with a universal catch-all tab-completion mechanism for all functions, and it also doesn’t make much sense to me, because different functions use...
Arye (96 days 5 hours ago): hi, is there a universal functionSignature.json file that will allow my to get the function hints when opening brackets of my funcs? something that automaticly recognize my function...
Sunham (99 days 0 hours ago): This is an old article, but the issue persists even in 2023. 2023a: z = mat2cell(1:1e6,1,repmat(1,1,1e 6)); f = @() cellfun(‘isempty’, z); g = @() cellfun(@isempty,z);...
Yair Altman (108 days 14 hours ago): Robot only runs when you tell it to run a command such as keyPress. If you don’t tell it to run a command, it uses no CPU, so there’s no need to remove the Robot...
Eric (109 days 1 hour ago): Hey @Kevin, can you share your code about create group of figures in the AppContainer? The container of multiples uifigures could be an amazing improvement over AppDesigner and its...
Elsa Smith (109 days 16 hours ago): I recently used java.awt.Robot to perform GUI testing on MATLAB and found it to be an extremely easy and useful way to control mouse movements.
Elsa Smith (109 days 16 hours ago): I’m suspecting that the slow performance of my GUI may be due to the use of java.awt.Robot. Is there a way to cancel/stop/remove the robot after it has been created, or is...
Michelle Kline (110 days 9 hours ago): *edit* tip about fopen(), not about fwrite(). ‘Wb’ vs. ‘wb’

Related posts:

6 Responses

Leave a Reply