A recent CSSM thread about implementing a system-wide GUI help system got me working on a post to present Matlab’s built-in hidden/unsupported mechanism for context-sensitive help. There are many different ways in which such a system can be implemented (read that thread for some ideas), so Matlab users are by no means limited to Matlab’s built-in implementation. However, the built-in system certainly merits consideration for its simplicity and usefulness.
We start with Matlab’s cshelp function (%matlabroot%\toolbox\matlab\uitools\cshelp.m). cshelp is semi-documented, meaning that it has a help section but no doc, online help or official support. This useful function was grandfathered (made obsolete) in Matlab 7.4 (R2007a) for an unknown reason and to my knowledge without any replacement. cshelp is entirely based on m-code (no hidden internal or Java code) and is surprisingly compact and readable.
cshelp basically attaches two new properties (CSHelpMode and CSHelpData) to the specified figure (this is done using the schema.prop mechanism which will be described in a separate post), temporarily disables all active uicontrols, modifies the figure’s WindowButtonDownFcn callback and sets the mouse cursor (using setptr – another semi-documented function) to an arrow with a question mark.
Clicking any object in the figure’s main area (beneath the toolbar), causes the modified WindowButtonDownFcn callback to run whatever is stored in the figure’s HelpFcn property (string, @function_handle or {@function_handle, params, …} format). Here is a simple example taken from CSSM (thanks Jérôme):
Hfcn = 'str=get(gco,''type''); title([''Type :'' str])'; set(gcf,'HelpFcn',Hfcn); th = 0:0.314:2*pi; plot(th,sin(th),'r-','linewidth',4); uicontrol('units','normalized', 'position',[.45 .02 .1 .05]); cshelp(gcf); set(gcf,'CSHelpMode','on'); |
In order to exit CSHelp mode, the figure’s CSHelpMode property must be set to ‘off’. However, remember that all the figure’s uicontrols are disabled in CSHelp mode. Therefore, the user may use one or more of the following methods (other tactics are also possible, but the ones below seem intuitive):
- Set the figure’s KeyPressFcn callback property to catch events (e.g., <ESC> key presses) and reset the CSHelpMode property from within the callback
- Reset the CSHelpMode property at the end of the HelpFcn callback
- Add a CS Help entry/exit option to the figure’s Help main menu
- Add a CS Help entry/exit button to the figure toolbar
The following code sample implements all of these suggested tactics (the code to synchronize the states of the menu item and toolbar button is not presented):
% Set the <esc> key press to exit CSHelp mode keyFcn = ['if strcmp(get(gcbf,''CurrentKey''),''escape''), ' ... 'set(gcbf,''CSHelpMode'',''off''); ' ... 'end']; set(gcf,'keyPressFcn',keyFcn); % Exit CSHelp mode at the end of the CSHelp callback helpFcn = 'title([''Type :'' get(gco,''type'')]); set(gcbf,''CSHelpMode'',''off'');'; set(gcf,'HelpFcn',helpFcn); % Add a CSHelp button to the figure toolbar % Note: retrieve the button icon from the CSHelp cursor icon hToolbar = findall(allchild(gcf),'flat','type','uitoolbar'); oldPtr = getptr(gcf); ptrData = setptr('help'); set(gcf, oldPtr{:}); icon(:,:,1) = ptrData{4}/2; % Convert into RGB TrueColor icon icon(:,:,2) = ptrData{4}/2; icon(:,:,3) = ptrData{4}/2; cbFcn = 'set(gcbf,''CSHelpMode'',get(gcbo,''state''))'; csName = 'Context-sensitive help'; uitoggletool(hToolbar,'CData',icon, 'ClickedCallback',cbFcn, 'TooltipString',csName); % Add a CSHelp menu option to the Help main menu % Note: unlike other main menus, the Help menu tag is empty, so % ^^^^ findall(gcf,'tag','figMenuHelp') is empty... Therefore, % we find this menu by accessing the Help/About menu item helpAbout = findall(gcf,'tag','figMenuHelpAbout'); helpMenu = get(helpAbout,'parent'); cbFcn = ['if strcmp(get(gcbo,''Checked''),''on''), ' ... 'set(gcbo,''Checked'',''off''); ' ... 'else, ' ... 'set(gcbo,''Checked'',''on''); ' ... 'end; ' ... 'set(gcbf,''CSHelpMode'',get(gcbo,''checked''))']; uimenu(helpMenu,'Label',csName,'Callback',cbFcn,'Separator','on'); |
cshelp has an additional optional argument, accepting another figure handle. This handle, if specified and valid, indicates a parent figure whose CSHelpMode, HelpFcn and HelpTopicMap properties should be shared with this figure (this is done using the handle.listener mechanism which will be described in a separate post). This option is useful when creating a multi-window GUI-wide context-sensitive help system. The user may then activate context-sensitive help in figure A and select the requested context object in figure B.
cshelp would normally be coupled with Matlab’s help system for non-trivial GUI implementations. The undocumented and hidden properties HelpTopicKey (of all handles) and HelpTopicMap (of figures), enable easy tie-in to the CSHelp system. A simplified sample is presented below:
Hfcn=['helpview(get(gco,''HelpTopicKey''),''CSHelpWindow'');'... 'set(gcbf,''CSHelpMode'',''off'');' ]; set(gcf,'HelpFcn',Hfcn); th = 0:0.314:2*pi; hLine = plot(th,sin(th),'r-','linewidth',4); set(hLine,'HelpTopicKey','MyCSHelpFile.html#Line'); set(gca, 'HelpTopicKey','MyCSHelpFile.html#Axes'); |
cshelp is by no way limited to presenting Matlab documentation: Refer to helpview‘s help section for an in-depth description of help maps and help topics. In a nutshell, helpview accepts any HTML webpage filepath (or webpage internal (#) reference), followed by optional parameter ‘CSHelpWindow’ (that indicates that the specified help page should be displayed in a stand-alone popup window rather than in the desktop’s standard Help tab), and optional extra parameters specifying the popup window’s figure handle and position. The webpage filepath parameter may be replaced by two string parameters, HelpTopicMap filepath and HelpTopicKey. Note that helpview itself is another semi-documented function.
Hi Yair,
This is completely off topic but you mentioned schema.prop and so I was hoping you’d be able to help with two posts I recently made on CSSM. No one has replied to either yet.
http://tinyurl.com/mt2ncl
http://tinyurl.com/nls6r4
The classes mentioned in the first post are using the schema.m mechanism.
Thanks for your help,
Ashish.
Yair,
Thanks again, I’ve been looking for an ability like this for a while. The only thing I will point out is that this seems to have an adverse effect with the tabbed panels. When I turn on CSHelp and try to switch tabs I get the following error:
??? No appropriate method or public field updateVisibility for class hg.hgjavacomponent.
Error in ==> uitools.uitabgroup.schema>onSelChanged at 211
children(i).updateVisibility();
Any Ideas?
Thanks
Jason
@Jason – the updateVisibility function is an m-file (%matlabroot%\toolbox\matlab\uitools\@uitools\@uitab\updateVisibility.m) that is responsible for hiding the previous tab’s components and unhiding the new tab’s components, whenever the active tab is changed (selected). Each tab is considered a “child” of the tabgroup and automatically has the updateVisibility() function defined as a private function. It appears that CSHelp adds extra children that do not have this updateVisibility() function defined.
I think the simplest workaround is simply to add a try-catch block around the offending line (%matlabroot%\toolbox\matlab\uitools\@uitools\@uitabgroup\schema.m line #211 [for Matlab R2008a]):
Wow, this is great. I’m not at MATLAB right now, so I can’t try this out, but it’s good to hear that helpview accepts any HTML file path, since I’ve spent about a week typing up full ‘Help’ documentation in HTML to be called via the web function. But using the web function to open my HTML pages doesn’t seem to give me the ability to easily control the help documentation (e.g. close the help window from within the GUI, open the help page to a specific section controlled by the user, etc.). It sounds like I’ll be able to do these things with cshelp and helpview.
Thanks for the detailed response!
@Yair,
Is there a way to reroute where that callback goes to something in the current directory? I’m deploying this on a network, so if others use it, they would have to update that location as well. (plus my company blocks us from modifying the matlab root directory 🙁 )
Thanks Again
Jason
Jason – you can replicate the entire uitab/uitabgroup code base (m-files and their associated private folders) to a network-accessible central location, which you would then be able to modify.
You’ll need to ensure that your Matlab path uses the new location rather than the default one – perhaps the best way to ensure this is to simply rename the files (and associate private folders) to uitab_new/uitabgroup_new, or something similar.
works great, I had to do alot of modifying of the schema and other mfiles throughout to change uitab to uitab_new, but it was well worth it.
Another help viewer is the one that pops up when I click F1 on a marked Matlab keyword – I like the design of that one the most. Is it possible to (ab)use it and have it pop up with information of my choice? I cannot find out how it is called up.
Dani – yes: you can popup this HelpPopup window using the following:
where:
1) jPosition sets popup’s pixel size and position (X,Y,Width,Height). Remember that Java counts from the top down (opposite to Matlab) and is 0-based. Therefore, Rectangle(0,0,400,300) is a 400×300 window at the screen’s top-left corner.
2) helpTopic is the help topic of your choice (the output of the doc function). To display arbitrary text, create an HTML doc page. A much easier alternative is to create a simple .m file that only has a main help comment with your arbitrary text, which will be presented in the popup.
Note: on pre-R2008a releases you need to use the equivalent but more cumbersome awtinvoke function instead of javaMethodEDT.
I have expanded my answer to Dani’s question into a full article ( https://undocumentedmatlab.com/blog/customizing-help-popup-contents) and companion utility (popupPanel – http://www.mathworks.com/matlabcentral/fileexchange/25975).
Enjoy 🙂