- Undocumented Matlab - https://undocumentedmatlab.com -

The hgfeval function

Posted By Yair Altman On October 27, 2010 | 2 Comments

Last week’s article about using a static GUI control [1], made use of the hgfeval function for its callback switch-yard dispatching. Today’s article will expose this important but often overlooked function.
hgfeval is a built-in semi-documented [2] function. This means that the function is explained in a comment within the hgfeval.m file (which can be seen via the edit(‘hgfeval’) command), that is nonetheless not part of the official help or doc sections. It is an unsupported function originally intended only for internal Matlab use, which of course doesn’t mean we can’t use it. hgfeval is currently used extensively within the Matlab code-base.

Callback chaining

hgfeval‘s main purpose is to programmatically (synchronously) invoke a callback, rather than it being dynamically (a-synchronously) invoked when some event occurs. This need often occurs when chaining events [3]. In a nutshell, we need to programmatically invoke Callback A (an executable code [=string], function handle, or cell array of function handle with extra parameters) within our code, which is typically located in another callback (B). For example:

function CallbackB(hObject, hEventData, varargin)
    callbackA = get(gcf, 'ButtonDownFcn');
    hgfeval(callbackA);
end

hgfeval is important when we want to force the objects passed as the callback’s first two input parameters (hObject and hEventData): hgfeval pre-pends all its extra parameters (arguments #2+) to the callback’ed function. So, calling hgfeval({@myFunc,arg1,arg2}, argA, argB) will actually invoke myFunc(argA,argB,arg1,arg2). Using this syntax we guaranty that whatever the invoked callback may be, its initial arguments will always be set to the necessary argA,argB.
This is often used in what MathWorks calls a callback-bridge. For example, in the following example we set the cbBridge function as a callback bridge for myCallback, that forces java(o) as the reference object (the invoked callback’s first argument) and e.JavaEvent as the second arg; all user args will then follow as optional additional args:

hdl = handle.listener(handle(jobj), eventName, ...
                      @(o,e)cbBridge(o,e,myCallback));
function cbBridge(o,e,myCallback)
    hgfeval(myCallback, java(o), e.JavaEvent)
end

In this example, the myCallback variable can be any valid Matlab callback specification [4]: string, function handle, or cell array.
If we had used myCallback directly, then myCallback would have been invoked with o and e rather than java(o) and e.JavaEvent. The point here is that using the callback bridge and hgfeval enabled us to tailor the parameters passed to the callback function.

Forward & backward compatibility

hgfeval has been built-in within all standard Matlab 7 releases, so while it may be discontinued in some future Matlab release, it did have a very long life span.
Even if for some reason this function is removed in some future Matlab release, it can easily be reproduced – after all, it only contains 35 very simple lines of pure Matlab code. In fact, for some project that had to rely on Matlab 6 (in which hgfeval was not yet available), it was an almost trivial task to retrofit an hgfeval look-alike (I had to remove function handles and similar minor tweaks):

%% hgfeval replacement for Matlab 6 compatibility
function hgfeval(fcn,varargin)
    if isempty(fcn),  return;  end
    if iscell(fcn)
        feval(fcn{1},varargin{:},fcn{2:end});
    elseif ischar(fcn)
        evalin('base', fcn);
    else
        feval(fcn,varargin{:});
    end
%end  %no function end in Matlab 6...

Have you ever used hgfeval in your code? If so, please share your experience in a comment below [5].

Categories: Low risk of breaking in future versions, Semi-documented function


2 Comments (Open | Close)

2 Comments To "The hgfeval function"

#1 Pingback By Matlab-Java interface using a static control | Undocumented Matlab On October 27, 2010 @ 11:09

[…] The requested Matlab function is then dynamically invoked using Matlab’s semi-documented hgfeval function, which Yair will describe in another article later this […]

#2 Pingback By Pinning annotations to graphs | Undocumented Matlab On December 12, 2012 @ 12:38

[…] down to the “Pin” menu item and take a look at its callback. We could then use the hgfeval function to execute this callback programmatically. […]


Article printed from Undocumented Matlab: https://undocumentedmatlab.com

URL to article: https://undocumentedmatlab.com/articles/hgfeval

URLs in this post:

[1] using a static GUI control: http://undocumentedmatlab.com/blog/matlab-java-interface-using-static-control/

[2] semi-documented: http://undocumentedmatlab.com/blog/legend-semi-documented-feature/#Semi-documented

[3] chaining events: http://undocumentedmatlab.com/blog/inactive-control-tooltips-event-chaining/

[4] Matlab callback specification: http://www.mathworks.com/help/matlab/creating_guis/writing-code-for-callbacks.html#f16-1001315

[5] below: http://undocumentedmatlab.com/blog/hgfeval/#respond

[6] Function definition meta-info : https://undocumentedmatlab.com/articles/function-definition-meta-info

[7] The javacomponent function : https://undocumentedmatlab.com/articles/javacomponent

[8] Undocumented feature() function : https://undocumentedmatlab.com/articles/undocumented-feature-function

[9] ismembc – undocumented helper function : https://undocumentedmatlab.com/articles/ismembc-undocumented-helper-function

[10] Function call timeline profiling : https://undocumentedmatlab.com/articles/function-call-timeline-profiling

[11] sprintfc – undocumented helper function : https://undocumentedmatlab.com/articles/sprintfc-undocumented-helper-function

Copyright © Yair Altman - Undocumented Matlab. All rights reserved.