Displaying hidden handle properties

Matlab Handle Graphics (HG) is a great way to manipulate GUI objects. HG handles often have some undocumented hidden properties. One pretty well-known example is the JavaFrame property of the figure handle, which enables access to the GUI’s underlying Java peer object. We can use hidden properties just like any other handle property, using the built-in get and set functions.

But how can we know about these properties? Here are two methods to do so. Like the hidden properties, these two methods are themselves undocumented…

1. use the desktop’s hidden HideUndocumented property:

set(0,'HideUndocumented','off');

From now on, when displaying handle properties using get and set you’ll see the hidden properties.

Note that some of the properties might display a warning indication:

>> get(gcf)
	Alphamap = [ (1 by 64) double array]
	BackingStore = on
	CloseRequestFcn = closereq
	Color = [0.8 0.8 0.8]
	Colormap = [ (64 by 3) double array]
	CurrentAxes = []
	CurrentCharacter =
	CurrentKey =
	CurrentModifier = [ (1 by 0) cell array]
	CurrentObject = []
	CurrentPoint = [0 0]
	DithermapWarning: figure Dithermap is no longer useful
 with TrueColor displays, and will be removed in a future release.
 = [ (64 by 3) double array]
        ...

2. Access the properties’ definition in the handle’s class definition:

>> ch = classhandle(handle(gcf));
>> props = get(ch,'Properties');
>> propsVisibility = get(props,'Visible')';
>> hiddenProps = props(strcmp(propsVisibility,'off'));
>> sort(get(hiddenProps,'Name'))
ans =
    'ALimInclude'
    'ActivePositionProperty'
    'ApplicationData'
    'BackingStore'
    'Behavior'
    'CLimInclude'
    'CurrentKey'
    'CurrentModifier'
    'Dithermap'
    'DithermapMode'
    'ExportTemplate'
    'HelpFcn'
    'HelpTopicKey'
    'HelpTopicMap'
    'IncludeRenderer'
    'JavaFrame'
    'OuterPosition'
    'PixelBounds'
    'PrintTemplate'
    'Serializable'
    'ShareColors'
    'UseHG2'
    'WaitStatus'
    'XLimInclude'
    'YLimInclude'
    'ZLimInclude'

Different HG handles have different hidden properties. Not all these properties are useful. For example, I have found the PixelBounds property to be problematic – (it sometimes reports incorrect values!). Other properties (like Dithermap or ShareColors) are deprecated and display a warning wherever they are accessed.

But every so often we find a hidden property that can be of some actual benefit. Let’s take the figure handle’s OuterPosition property for example. It provides the figure’s external position values, including the space used by the window frame, toolbars etc., whereas the regular documented Position property only reports the internal bounds:

>> get(gcf,'pos')
ans =
   232   246   560   420
>> get(gcf,'outer')
ans =
   228   242   568   502

In future posts I will sometimes use such hidden properties. You can find the latest list by looking at this blog’s “Hidden property” category page.

Note: Like the rest of Matlab’s undocumented items, all hidden properties are undocumented, unsupported and may well change in future Matlab releases so use them with care.

Did you find any useful hidden property? If so, then please leave your finding in the comments section below.

Related posts:

  1. Performance: accessing handle properties Handle object property access (get/set) performance can be significantly improved using dot-notation. ...
  2. Handle Graphics Behavior HG behaviors are an important aspect of Matlab graphics that enable custom control of handle functionality. ...
  3. UDD Properties UDD provides a very convenient way to add customizable properties to existing Matlab object handles...
  4. getundoc – get undocumented object properties getundoc is a very simple utility that displays the hidden (undocumented) properties of a specified handle object....
  5. Displaying animated GIFs It is possible to easily display animated images in Matlab figure windows. ...
  6. Plot LimInclude properties The plot objects' XLimInclude, YLimInclude, ZLimInclude, ALimInclude and CLimInclude properties are an important feature, that has both functional and performance implications....

Categories: Hidden property, High risk of breaking in future versions

Tags: , , , , ,

Bookmark and SharePrint Print

14 Responses to Displaying hidden handle properties

  1. Hi Yair. The OuterPosition property of figures is documented, although I see that get(gcf) doesn’t display it by default. I don’t know the reason for the discrepancy.

    • Yair Altman says:

      Thanks Steve – that’s a nice catch that I probably would never have seen…
      Hidden but documented: that’s a new one – I learn something new each day :-)

  2. One nice little property of axes (using R2009a) is ‘ContentsVisible’. Seems to be a nice way of toggling off the visibility contents of an axes while you update it.


    plot(1:5)
    t = text('Parent',gca,'String','Some Text');
    set(gca,'ContentsVisible','off')
    hold on
    plot(5:-1:0)
    set(t,'Position',[3,3])
    set(gca,'ContentsVisible','on')

    Sure it can be done numerous other ways but one scenario I have encountered is having a bunch of objects in an axes that have a mixture of visible states. You want to hide the contents while some update goes on. You have to find all the visible children, turn them off, keep that list in memory to only restore the visible stuff. The above seems much cleaner. I have not run into any gotchas yet.

    Thanks for the great website. You’ve been a great help over the last couple of years.

    Matt

  3. Jason McMains says:

    Yair, I’ve been looking around your getjframe program to get more of these “hidden handle properties.” This adds a lot of great extra functionality! Thanks for that! My question is that for some reason if I set the figure as invisible, all of those hidden callbacks, ie ‘WindowStateChangedCallback’ stop running. Any ideas?

    Thanks
    Jason

    • Yair Altman says:

      @Jason – the Java properties & callbacks are only relevant for visible figure frames. After all, how can you minimize/maximize a hidden frame??? Still, you can access these properties if you simply keep the figure visible and just set its position to somewhere off-screen (say, x=y=9999). The figure will remain visible although effectively hidden from view; it will remain displayed in the taskbar for this reason.

    • Jason McMains says:

      @Yair Unfortunately part of the code I’m working on is to “minimize to the system tray” like I can do in outlook and some other programs, which involves setting the visibility off to remove it from the task bar. I’ve gotten it to work some of the time, but certain sequences of commands still mess it up. The system tray icon is a great extra resource by the way, thanks for that little piece of wisdom:)

    • Jason McMains says:

      @Yair, I finally think I figured out the problem, but its just a simple logic fix, every time I set the figure back to visible, I get the javaframe, and include that as the callback argument, and remove the old javaframe.

  4. Cris says:

    Hey Yair, nice blog!

    The ‘ApplicationData’ property might not be documented, but the GETAPPDATA and SETAPPDATA access functions are. It’s just a better structured implementation of the ‘UserData’ property. I still prefer using ‘UserData’ just because it’s more flexible. You get an error if you try to write anything that is not a stuct into ‘ApplicationData’.

  5. Pingback: Customizing print setup | Undocumented Matlab

  6. Pingback: Axes LooseInset property | Undocumented Matlab

  7. Pingback: Matlab’s HG2 mechanism | Undocumented Matlab

  8. Pingback: FIG files format | Undocumented Matlab

  9. Pingback: getundoc – get undocumented object properties | Undocumented Matlab

  10. Ramiro Massol says:

    hi Yair
    Just to let you know new bad news about Matlab. I was testing the pre-release of Matlab 2014b. The “set(0,’HideUndocumented’,'off’);” does not work anymore, which may mean that all the undocumented properties and functions relying on them may not work anymore (for instance, uicomponent does not work).
    best

Leave a Reply

Your email address will not be published. Required fields are marked *

*

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