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

Customizing help popup contents

November 30, 2009 9 Comments

A few days ago, I was asked by a reader how to programmatically display the popup help window and customize it with arbitrary contents. This help window displays the doc-page associated with the current Command Window or Editor text.

Help popup
Help popup

To programmatically display this help popup, a modeless MJDialog Java window, we need to run the following on Matlab releases that support these windows (R2007b onward):

jDesktop = com.mathworks.mde.desk.MLDesktop.getInstance;
jTextArea = jDesktop.getMainFrame.getFocusOwner;
jClassName = 'com.mathworks.mlwidgets.help.HelpPopup';
jPosition = java.awt.Rectangle(0,0,400,300);
helpTopic = 'surf';
javaMethodEDT('showHelp',jClassName,jTextArea,[],jPosition,helpTopic);

jDesktop = com.mathworks.mde.desk.MLDesktop.getInstance; jTextArea = jDesktop.getMainFrame.getFocusOwner; jClassName = 'com.mathworks.mlwidgets.help.HelpPopup'; jPosition = java.awt.Rectangle(0,0,400,300); helpTopic = 'surf'; javaMethodEDT('showHelp',jClassName,jTextArea,[],jPosition,helpTopic);

Where:
1) jPosition sets popup’s pixel size and position (X,Y,Width,Height). Remember that Java counts from the top down (contrary 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, you can create a simple .m file that only has a main help comment with your arbitrary text, which will be presented in the popup.
3) on R2011b, we could simplify the above code snippet with the following replacement:

helpUtils.errorDocCallback('surf')

helpUtils.errorDocCallback('surf')

4) on R2007b, we need to use the equivalent but more cumbersome awtinvoke function instead of javaMethodEDT:

jniSig = 'showHelp(Ljavax.swing.JComponent;Lcom.mathworks.mwswing.binding.KeyStrokeList;Ljava.awt.Rectangle;Ljava.lang.String;)';
awtinvoke(jClassName,jniSig,jTextArea,[],jPosition,helpTopic);

jniSig = 'showHelp(Ljavax.swing.JComponent;Lcom.mathworks.mwswing.binding.KeyStrokeList;Ljava.awt.Rectangle;Ljava.lang.String;)'; awtinvoke(jClassName,jniSig,jTextArea,[],jPosition,helpTopic);

For example, if we had a sample.m file with the following contents:

function sample
% The text in this function's main comment will be presented in the
% help popup. <a href="https://undocumentedmatlab.com">Hyperlinks</a>
% are supported, but unfortunately not full-fledged HTML.

function sample % The text in this function's main comment will be presented in the % help popup. <a href="https://undocumentedmatlab.com">Hyperlinks</a> % are supported, but unfortunately not full-fledged HTML.

Then we would get this result:

User-created arbitrary text
User-created arbitrary text

Well, it does get the message across, but looks rather dull. It would be nice if this could be improved to provide full-scale HTML support. Unfortunately, Matlab documentation says this cannot be done:
The doc function is intended only for reference pages supplied by The MathWorks. The exception is the doc UserCreatedClassName syntax. doc does not display HTML files you create yourself. To display HTML files for functions you create, use the web function.
Luckily for us, there is an undocumented back-door to do this: The idea is to search all visible Java windows for the HelpPopup, then move down its component hierarchy to the internal web browser (a com.mathworks.mlwidgets.html.HTMLBrowserPanel object), then update the content with our arbitrary HTML or a webpage URL:

% Find the Help popup window
jWindows = com.mathworks.mwswing.MJDialog.getWindows;
jPopup = [];
for idx=1 : length(jWindows)
  if strcmp(get(jWindows(idx),'Name'),'HelpPopup')
    if jWindows(idx).isVisible
      jPopup = jWindows(idx);
      break;
    end
  end
end
% Update the popup with selected HTML
html=['Full HTML support: <b><font color=red>bold</font></b>, '...
      '<i>italic</i>, <a href="matlab:dir">hyperlink</a>, ' ...
      'symbols (&#8704;&#946;) etc.'];
if ~isempty(jPopup)
  browser = jPopup.getContentPane.getComponent(1).getComponent(0);
  browser.setHtmlText(html);
end

% Find the Help popup window jWindows = com.mathworks.mwswing.MJDialog.getWindows; jPopup = []; for idx=1 : length(jWindows) if strcmp(get(jWindows(idx),'Name'),'HelpPopup') if jWindows(idx).isVisible jPopup = jWindows(idx); break; end end end % Update the popup with selected HTML html=['Full HTML support: <b><font color=red>bold</font></b>, '... '<i>italic</i>, <a href="matlab:dir">hyperlink</a>, ' ... 'symbols (&#8704;&#946;) etc.']; if ~isempty(jPopup) browser = jPopup.getContentPane.getComponent(1).getComponent(0); browser.setHtmlText(html); end

Help popup with HTML content
Help popup with HTML content

We can display HTML content and highlight certain keywords using the setHtmlTextAndHighlightKeywords method:

browser.setHtmlTextAndHighlightKeywords(html,{'support','symbols'});

browser.setHtmlTextAndHighlightKeywords(html,{'support','symbols'});

HTML content with highlighting
HTML content with highlighting

Instead of specifying the HTML content, we can point this browser to a web-page URL (no need for the “http://” prefix):

browser.setCurrentLocation('UndocumentedMatlab.com');

browser.setCurrentLocation('UndocumentedMatlab.com');

Help popup browser displaying a URL web-page
Help popup browser displaying a URL web-page

The HTMLBrowserPanel includes a full-fledged browser (which may be different across Matlab releases/platforms). This browser supports HTML, CSS, JavaScript and other web-rendering aspect that we would expect from a modern browser. Being a full-fledged browser, we have some control over its appearance e.g., addAddressBox(1,1) and other internal methods. Interested readers may use my UiInspect utility to explore these options.
As a technical note, HTMLBrowserPanel is actually only a JPanel that contains the actual Mozilla browser. Luckily for us, MathWorks extended this panel class with the useful methods presented above, that forward the user requests to the actual internal browser. This way, we don’t need to get the actual browser reference (although you can, of course).
I have created a utility function that encapsulates all the above, and enables display of Matlab doc pages, as well as arbitrary text, HTML or webpages. This popupPanel utility can now be downloaded from the Matlab File Exchange.
An interesting exercise left for the readers, is adapting the main heavy-weight documentation window to display user-created HTML help pages. This can be achieved by means very similar to those shown in this article.
Of course, as the official documentation states, we could always use the fully-supported web function to display our HTML or URLs. Under the hood, web uses exactly the same HTMLBrowserPanel as out HelpPopup. The benefit of using the methods shown here is the use of a lightweight undecorated popup window which looks well-integrated with the existing Matlab help.
Please note that the HelpPopup implementation might change without warning between Matlab releases. An entirely separate, although related, implementation is Matlab’s built-in context-sensitive help system, which I described some months ago. That implementation did not rely on Java and worked on much earlier Matlab releases.

Related posts:

  1. Matlab toolstrip – part 9 (popup figures) – Custom popup figures can be attached to Matlab GUI toolstrip controls. ...
  2. Setting system tray popup messages – System-tray icons and messages can be programmatically set and controlled from within Matlab, using new functionality available since R2007b....
  3. Rich-contents log panel – Matlab listboxes and editboxes can be used to display rich-contents HTML-formatted strings, which is ideal for log panels. ...
  4. Aligning uicontrol contents – Matlab uicontrols can often be customized using plain HTML/CSS, without need for advanced Java. ...
  5. Rich Matlab editbox contents – The Matlab editbox uicontrol does not handle HTML contents as do other uicontrols. In this article I show how this limitation can be removed....
  6. Customizing Workspace context-menu – Matlab's Workspace table context-menu can be configured with user-defined actions - this article explains how....
Desktop HTML Java Undocumented feature
Print Print
« Previous
Next »
9 Responses
  1. Nathan January 27, 2010 at 16:18 Reply

    I’m having troubles using this in a GUI that I’m coding by hand.
    As a “help” pushbutton callback, I have the following code:

    function [] = pb_call5(varargin)
      jDesktop = com.mathworks.mde.desk.MLDesktop.getInstance;
      jClassName = 'com.mathworks.mlwidgets.help.HelpPopup';
      jPosition = java.awt.Rectangle(200,200,650,600);
      jTextArea = jDesktop.getMainFrame.getFocusOwner;
      helpTopic = 'LiqVapGui';
      javaMethodEDT('showHelp',jClassName,jTextArea,[],jPosition,helpTopic);
    end

    function [] = pb_call5(varargin) jDesktop = com.mathworks.mde.desk.MLDesktop.getInstance; jClassName = 'com.mathworks.mlwidgets.help.HelpPopup'; jPosition = java.awt.Rectangle(200,200,650,600); jTextArea = jDesktop.getMainFrame.getFocusOwner; helpTopic = 'LiqVapGui'; javaMethodEDT('showHelp',jClassName,jTextArea,[],jPosition,helpTopic); end

    However, I am receiving an error stating that
    “??? Error using ==> javaMethodEDT
    Java exception occurred:
    java.lang.IllegalArgumentException: ‘parent’ cannot be null”

    When stepping through the debugger, I find that jTextArea is empty. However, if I re-type that line while in debug mode, it works just fine. Do you know any way that I can fix this problem?

    -Nathan

    • Yair Altman January 27, 2010 at 16:40 Reply

      @Nathan – I assume you haven’t placed this in your GUIDE-generated _OpeningFcn(), as explained elsewhere. Another cause of this might be that when you run the code, jTextArea is still unavailable by the time the javaMethodEDT is called. In step-by-step debugging this is not an issue, since there is plenty of time for jTextArea to be set. It is also possible that there is no FocusOwner in the Desktop (unlike the case of step-by-step debugging) – this can be forced using the commandwindow function. As a final alternative, try using the getClient() approach to getting the Command-window TextArea, as I explained in my recent setPrompt article:

      jDesktop = com.mathworks.mde.desk.MLDesktop.getInstance;
      try
        cmdWin = jDesktop.getClient('Command Window');
        jTextArea = cmdWin.getComponent(0).getViewport.getComponent(0);
      catch
        commandwindow;
        jTextArea = jDesktop.getMainFrame.getFocusOwner;
      end

      jDesktop = com.mathworks.mde.desk.MLDesktop.getInstance; try cmdWin = jDesktop.getClient('Command Window'); jTextArea = cmdWin.getComponent(0).getViewport.getComponent(0); catch commandwindow; jTextArea = jDesktop.getMainFrame.getFocusOwner; end

      • Nathan January 27, 2010 at 17:08

        I am not using GUIDE (as implied by “coding by hand”), but your getClient() method worked for me. Thanks for the quick response and your help. This website is very insightful.

        -Nathan

  2. Peng Liu July 25, 2019 at 11:00 Reply

    Hi Yair,

    When I try to use html in help popup, I was told there is no setHtmlText of browser. So I ask myself is there any update in matlab 2017b. But I tried getComponent with other indices which doesn’t work. Maybe you would have a clue. Thanks a lot.

    browser = jPopup.getContentPane.getComponent(1).getComponent(0);
    browser.setHtmlText(html);

    browser = jPopup.getContentPane.getComponent(1).getComponent(0); browser.setHtmlText(html);

    • Yair Altman July 26, 2019 at 13:12 Reply

      @Peng – the code above was relevant as of the time I wrote the article, 10 years ago (2009). In recent Matlab releases the code needs to be modified a bit:

      browser = jPopup.getContentPane.getComponent(1).getComponent(1).getComponent.getBrowser;
      browser.loadHTML(html)  % to display a string containing HTML code
      browser.loadURL(url)    % to display an online webpage (e.g. 'google.com')

      browser = jPopup.getContentPane.getComponent(1).getComponent(1).getComponent.getBrowser; browser.loadHTML(html) % to display a string containing HTML code browser.loadURL(url) % to display an online webpage (e.g. 'google.com')

  3. Peter August 11, 2020 at 22:14 Reply

    I have a problem with putting this into the startup.m to be executed at the beginning of the MATLAB session.

    jDesktop = com.mathworks.mde.desk.MLDesktop.getInstance;
    try
        cmdWin = jDesktop.getClient('Command Window');
        jTextArea = cmdWin.getComponent(0).getViewport.getComponent(0);
    catch
        commandwindow;
        jTextArea = jDesktop.getMainFrame.getFocusOwner;
    end
    jClassName = 'com.mathworks.mlwidgets.help.HelpPopup';
    jPosition = java.awt.Rectangle(0, 0, 400, 300);
    helpTopic = 'surf';
    % Variant 1:
    javaMethodEDT('showHelp', jClassName, jTextArea, [], jPosition, helpTopic);
    % Variant 2:
    %jniSig = 'showHelp(Ljavax.swing.JComponent;Lcom.mathworks.mwswing.binding.KeyStrokeList;Ljava.awt.Rectangle;Ljava.lang.String;)';
    %awtinvoke(jClassName,jniSig,jTextArea,[],jPosition,helpTopic);

    jDesktop = com.mathworks.mde.desk.MLDesktop.getInstance; try cmdWin = jDesktop.getClient('Command Window'); jTextArea = cmdWin.getComponent(0).getViewport.getComponent(0); catch commandwindow; jTextArea = jDesktop.getMainFrame.getFocusOwner; end jClassName = 'com.mathworks.mlwidgets.help.HelpPopup'; jPosition = java.awt.Rectangle(0, 0, 400, 300); helpTopic = 'surf'; % Variant 1: javaMethodEDT('showHelp', jClassName, jTextArea, [], jPosition, helpTopic); % Variant 2: %jniSig = 'showHelp(Ljavax.swing.JComponent;Lcom.mathworks.mwswing.binding.KeyStrokeList;Ljava.awt.Rectangle;Ljava.lang.String;)'; %awtinvoke(jClassName,jniSig,jTextArea,[],jPosition,helpTopic);

    My startup script uses similar code that opens and closes a dummy popup with custom window size that would be applied for subsequent F1-popups.
    In R2018a and R2020b Prerelease the above example works well as standalone code. Nevertheless, when used in startup.m it does not create a popup during the startup (and for variant 1 it also results in “java.lang.IllegalArgumentException: ‘parent’ cannot be null” exception). I remember that in some earlier releases a similar solution used to work (pause(1) or drawnow were helpful in case of errors), but now I cannot find any fix. Maybe you would know if it is still possible to open a popup with the desired size during MATLAB startup.

    • Yair Altman August 14, 2020 at 16:13 Reply

      @Peter – the graphics system might not be fully initialized by the time that the startup script is being executed by the Matlab engine. I suggest placing the relevant code in a small function and in startup.m simply start a single-shot timer with a StartDelay of several seconds, that will run the new function in its TimerFcn callback.

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 (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
  • Amin zaami (10 hours 23 minutes ago): I have the same problem as Nicholas, The function works fine on R2022, but when compiled it fails (I used com.mathworks.mlwidgets.help.L ightweightHelpPanel), I tried compiling...
  • Rolf (18 days 16 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 10 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 15 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 16 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 19 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 19 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 16 hours ago): more than 10 years later it helps me after struggling few hours, so thanks you very much !
  • Yair Altman (95 days 15 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 9 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 3 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 18 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 5 hours 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 19 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 20 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...
Contact us
Captcha image for Custom Contact Forms plugin. You must type the numbers shown in the image
Undocumented Matlab © 2009 - Yair Altman
This website and Octahedron Ltd. are not affiliated with The MathWorks Inc.; MATLAB® is a registered trademark of The MathWorks Inc.
Scroll to top