Undocumented Matlab
  • SERVICES
    • Consulting
    • Development
    • Training
    • Gallery
    • Testimonials
  • PRODUCTS
    • IQML: IQFeed-Matlab connector
    • IB-Matlab: InteractiveBrokers-Matlab connector
    • EODML: EODHistoricalData-Matlab connector
    • Webinars
  • BOOKS
    • Secrets of MATLAB-Java Programming
    • Accelerating MATLAB Performance
    • MATLAB Succinctly
  • ARTICLES
  • ABOUT
    • Policies
  • CONTACT
  • SERVICES
    • Consulting
    • Development
    • Training
    • Gallery
    • Testimonials
  • PRODUCTS
    • IQML: IQFeed-Matlab connector
    • IB-Matlab: InteractiveBrokers-Matlab connector
    • EODML: EODHistoricalData-Matlab connector
    • Webinars
  • BOOKS
    • Secrets of MATLAB-Java Programming
    • Accelerating MATLAB Performance
    • MATLAB Succinctly
  • ARTICLES
  • ABOUT
    • Policies
  • CONTACT

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
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)

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…

Related posts:

  1. Undocumented plot marker types – Undocumented plot marker styles can easily be accesses using a hidden plot-line property. ...
  2. cellfun – undocumented performance boost – Matlab's built-in cellfun function has an undocumented option to significantly improve performance in some cases....
  3. tic / toc – undocumented option – Matlab's built-in tic/toc functions have an undocumented option enabling multiple nested clockings...
  4. Matlab-Latex interface – Matlab's support for Latex has some hidden quirks ...
  5. JMI – Java-to-Matlab Interface – JMI enables calling Matlab functions from within Java. This article explains JMI's core functionality....
  6. Undocumented view transformation matrix – Matlab's view function returns an undocumented output transformation matrix....
Handle graphics Pure Matlab Undocumented feature
Print Print
« Previous
Next »
6 Responses
  1. 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.

  2. 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 […]

  3. 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);

        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)

        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')

        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]);

        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?

Leave a Reply
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.

Useful links
  •  Email Yair Altman
  •  Subscribe to new posts (email)
  •  Subscribe to new posts (feed)
  •  Subscribe to new posts (reader)
  •  Subscribe to comments (feed)
 
Accelerating MATLAB Performance book
Recent Posts

Speeding-up builtin Matlab functions – part 3

Improving graphics interactivity

Interesting Matlab puzzle – analysis

Interesting Matlab puzzle

Undocumented plot marker types

Matlab toolstrip – part 9 (popup figures)

Matlab toolstrip – part 8 (galleries)

Matlab toolstrip – part 7 (selection controls)

Matlab toolstrip – part 6 (complex controls)

Matlab toolstrip – part 5 (icons)

Matlab toolstrip – part 4 (control customization)

Reverting axes controls in figure toolbar

Matlab toolstrip – part 3 (basic customization)

Matlab toolstrip – part 2 (ToolGroup App)

Matlab toolstrip – part 1

Categories
  • Desktop (45)
  • Figure window (59)
  • Guest bloggers (65)
  • GUI (165)
  • Handle graphics (84)
  • Hidden property (42)
  • Icons (15)
  • Java (174)
  • Listeners (22)
  • Memory (16)
  • Mex (13)
  • Presumed future risk (394)
    • High risk of breaking in future versions (100)
    • Low risk of breaking in future versions (160)
    • Medium risk of breaking in future versions (136)
  • Public presentation (6)
  • Semi-documented feature (10)
  • Semi-documented function (35)
  • Stock Matlab function (140)
  • Toolbox (10)
  • UI controls (52)
  • Uncategorized (13)
  • Undocumented feature (217)
  • Undocumented function (37)
Tags
ActiveX (6) AppDesigner (9) Callbacks (31) Compiler (10) Desktop (38) Donn Shull (10) Editor (8) Figure (19) FindJObj (27) GUI (141) GUIDE (8) Handle graphics (78) HG2 (34) Hidden property (51) HTML (26) Icons (9) Internal component (39) Java (178) JavaFrame (20) JIDE (19) JMI (8) Listener (17) Malcolm Lidierth (8) MCOS (11) Memory (13) Menubar (9) Mex (14) Optical illusion (11) Performance (78) Profiler (9) Pure Matlab (187) schema (7) schema.class (8) schema.prop (18) Semi-documented feature (6) Semi-documented function (33) Toolbar (14) Toolstrip (13) uicontrol (37) uifigure (8) UIInspect (12) uitools (20) Undocumented feature (187) Undocumented function (37) Undocumented property (20)
Recent Comments
  • Josh (12 hours 10 minutes ago): Dear Yair, Small typo; you wrote >>Move lines up or down – CTRL + ALT + UP or DOWN allows you to move selected lines up or down but it’s actually ALT+SHIFT then UP/DOWN...
  • Yair Altman (7 days 6 hours ago): You can try to increase the Java heap memory size in the Matlab preferences (General => Java Heap Memory). Any changes to the settings will only take effect after restarting...
  • Thomas (7 days 8 hours ago): Hello, thanks for sharing! I currently receive the following memory error message when using savezip with a big object (Matlab R2020b, Windows 10). Error using...
  • Yair Altman (10 days 15 hours ago): Yerlan – either use menuItem1.setEnabled(0) or set(menuItem1,'Enabled',0)
  • Manzn (10 days 18 hours ago): Thank you man! you saved me, when there was no more light 😀
  • Yerlan (11 days 23 hours ago): Hello Mr. Altman, how can I disable menu items in the context menu? E.g. when I am trying to do this: menuItems = jmenu.getSubElements; menuItem1 = menuItems(1);...
  • Yair Altman (12 days 15 hours ago): Thanks for the note Eric – you forgot the crucial call to jTable.setLabelTable(labelTabl e) – I added it into your code snippet above.
  • Erik (14 days 2 hours ago): Thank you for this — I don’t know if this has been mentioned anywhere else before, but it could be useful to mention how to add custom labels to a jslider. I did the...
  • turhv (26 days 21 hours ago): very nice! work perfectly to me in MATLAB 2019a. thanks!!!
  • Jianfei (60 days 0 hours ago): I have tried the MathWorks CheckBoxList in Matlab 2015b. For whatever the reason, I can’t change the font properties. I can change the font color, but changing font properties...
  • Donato Coppola (65 days 20 hours ago): Hi Yair, I have a problem with the double format. When I run the treeTable function, the numbers in double format cells are displayed with comma as decimal separator. How can...
  • Kim (71 days 10 hours ago): Yair, the following didn’t work for me either: jh.setBorderPainted(false); Regards, Kim
  • Adil (73 days 11 hours ago): Thank you for the blog, it was useful for me. I have a file named App_project.mlapp.zip and when I extract it through Winzip it gives all the files exactly as you described above. I...
  • Mr Ashley Trowell (75 days 21 hours ago): Thank you so much for this analysis. Also, I find it somewhat horrifying. The take away seems to be to use && / || and NOT and / or. Thanks a bunch! ~Ashley
  • Matt (80 days 23 hours ago): Late reply I know, but you can call custom shortcuts with alt-#. Hold down Alt to see what number is assigned to the shortcuts you’ve created. Now if there was a way to create a...
Contact us
Undocumented Matlab © 2009 - Yair Altman
Scroll to top