<?xml version="1.0" encoding="UTF-8"?><rss version="2.0"
	xmlns:content="http://purl.org/rss/1.0/modules/content/"
	xmlns:wfw="http://wellformedweb.org/CommentAPI/"
	xmlns:dc="http://purl.org/dc/elements/1.1/"
	xmlns:atom="http://www.w3.org/2005/Atom"
	xmlns:sy="http://purl.org/rss/1.0/modules/syndication/"
	xmlns:slash="http://purl.org/rss/1.0/modules/slash/"
	>

<channel>
	<title>Semi-documented feature &#8211; Undocumented Matlab</title>
	<atom:link href="https://undocumentedmatlab.com/articles/tag/semi-documented-feature/feed" rel="self" type="application/rss+xml" />
	<link>https://undocumentedmatlab.com</link>
	<description>Professional Matlab consulting, development and training</description>
	<lastBuildDate>Mon, 03 Sep 2018 15:00:22 +0000</lastBuildDate>
	<language>en-US</language>
	<sy:updatePeriod>
	hourly	</sy:updatePeriod>
	<sy:updateFrequency>
	1	</sy:updateFrequency>
	<generator>https://wordpress.org/?v=6.7.2</generator>
	<item>
		<title>Matlab toolstrip &#8211; part 1</title>
		<link>https://undocumentedmatlab.com/articles/matlab-toolstrip-part-1?utm_source=rss&#038;utm_medium=rss&#038;utm_campaign=matlab-toolstrip-part-1</link>
					<comments>https://undocumentedmatlab.com/articles/matlab-toolstrip-part-1#comments</comments>
		
		<dc:creator><![CDATA[Yair Altman]]></dc:creator>
		<pubDate>Mon, 03 Sep 2018 15:00:22 +0000</pubDate>
				<category><![CDATA[Desktop]]></category>
		<category><![CDATA[GUI]]></category>
		<category><![CDATA[High risk of breaking in future versions]]></category>
		<category><![CDATA[Semi-documented feature]]></category>
		<category><![CDATA[Toolstrip]]></category>
		<guid isPermaLink="false">http://undocumentedmatlab.com/?p=7952</guid>

					<description><![CDATA[<p>Matlab contains extensive toolstrip (ribbon) functionality that can be integrated in user programs (GUI). </p>
<p>The post <a rel="nofollow" href="https://undocumentedmatlab.com/articles/matlab-toolstrip-part-1">Matlab toolstrip &#8211; part 1</a> appeared first on <a rel="nofollow" href="https://undocumentedmatlab.com">Undocumented Matlab</a>.</p>
<div class='yarpp-related-rss'>
<h3>Related posts:</h3><ol>
<li><a href="https://undocumentedmatlab.com/articles/matlab-toolstrip-part-3-basic-customization" rel="bookmark" title="Matlab toolstrip – part 3 (basic customization)">Matlab toolstrip – part 3 (basic customization) </a> <small>Matlab toolstrips can be created and customized in a variety of ways. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/matlab-toolstrip-part-2-toolgroup-app" rel="bookmark" title="Matlab toolstrip – part 2 (ToolGroup App)">Matlab toolstrip – part 2 (ToolGroup App) </a> <small>Matlab users can create custom Apps with toolstrips and docked figures. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/matlab-toolstrip-part-8-galleries" rel="bookmark" title="Matlab toolstrip – part 8 (galleries)">Matlab toolstrip – part 8 (galleries) </a> <small>Matlab toolstrips can contain customizable gallery panels of items. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/matlab-toolstrip-part-5-icons" rel="bookmark" title="Matlab toolstrip – part 5 (icons)">Matlab toolstrip – part 5 (icons) </a> <small>Icons can be specified in various ways for toolstrip controls and the app window itself. ...</small></li>
</ol>
</div>
]]></description>
										<content:encoded><![CDATA[<p>The Matlab toolstrip (ribbon) has been around officially <a href="https://blogs.mathworks.com/loren/2012/09/12/the-matlab-r2012b-desktop-part-1-introduction-to-the-toolstrip" rel="nofollow" target="_blank">since R2012a</a>, and unofficially for <a href="https://undocumentedmatlab.com/articles/matlab-installation-woes#Java" target="_blank">a couple of years earlier</a>. Since then, I blogged about the toolstrip only rarely (<a href="https://undocumentedmatlab.com/articles/programmatic-shortcuts-manipulation-part-2" target="_blank">example</a>). I believe the time has come to start a short mini-series about this functionality, eventually showing how users can use toolstrips in their own custom applications.<br />
My plan is to start the miniseries with a discussion of the built-in showcase examples, followed by a post on the built-in classes that make up the toolstrip building-blocks. Finally, I&#8217;ll describe how toolstrips can be added to figures, not just in client/tool groups.</p>
<h3 id="showcase">Matlab&#8217;s internal showcase examples</h3>
<p>I start the discussion with a description of built-in examples for the toolstrip functionality, located in <i>%matlabroot%/toolbox/matlab/toolstrip/+matlab/+ui/+internal/+desktop/</i>. The most important of these are <i>showcaseToolGroup.m</i> and <i>showcaseMPCDesigner.m</i>, both of which use Java-based (Swing) containers and controls. Readers who wish to integrate toolstrips into their app immediately, without waiting for my followup posts in this series, are welcome to dig into the examples&#8217; source-code and replicate it in their programs:</p>
<h5 id="showcaseToolGroup">1. <code>showcaseToolGroup</code></h5>
<pre lang="matlab">h = matlab.ui.internal.desktop.showcaseToolGroup</pre>
<p><center><img decoding="async" src="https://undocumentedmatlab.com/images/showcaseToolGroup.png" alt="showcaseToolGroup built-in example" title="showcaseToolGroup built-in example" width="80%" style="max-width:1028px; max-height:455px;" /></center><br />
<span id="more-7952"></span></p>
<h5 id="showcaseMPCDesigner">2. <code>showcaseMPCDesigner</code></h5>
<pre lang="matlab">
>> h = matlab.ui.internal.desktop.showcaseMPCDesigner
h =
  showcaseMPCDesigner with properties:
    ToolGroup: [1×1 matlab.ui.internal.desktop.ToolGroup]
       Dialog: [1×1 toolpack.component.TSTearOffPopup]
      Figure1: [1×1 Figure]
      Figure2: [1×1 Figure]
</pre>
<p><center><img decoding="async" src="https://undocumentedmatlab.com/images/showcaseMPCDesigner.png" alt="showcaseMPCDesigner built-in example" title="showcaseMPCDesigner built-in example" width="80%" style="max-width:994px; max-height:552px;" /></center></p>
<h5 id="showcaseHTML">3. <code>showcaseHTML</code> and <code>showcaseCEF</code></h5>
<p>In addition to these showcase examples, the folder also contains a <i>showcaseHTML.m</i> and <i>showcaseCEF.m</i> files, that are supposed to showcase the toolstrip functionality in JavaScript-based containers (browser webpage and uifigure apps, respectively). Unfortunately, on my system running these classes displays blank, although the toolstrip is indeed created, as seen below (if you find out how to make these classes work, please let me know):</p>
<pre lang="matlab">
>> h = matlab.ui.internal.desktop.showcaseHTML
building toolstrip hierarchy...
rendering toolstrip...
h =
  Toolstrip with properties:
               SelectedTab: [1×1 matlab.ui.internal.toolstrip.Tab]
              DisplayState: 'expanded'
    DisplayStateChangedFcn: @PropertyChangedCallback
                       Tag: 'toolstrip'
>> hs = struct(h)
Warning: Calling STRUCT on an object prevents the object from hiding its implementation details and should thus be avoided.
Use DISP or DISPLAY to see the visible public details of an object. See 'help struct' for more information.
(Type "warning off MATLAB:structOnObject" to suppress this warning.)
hs =
  struct with fields:
                         SelectedTab: [1×1 matlab.ui.internal.toolstrip.Tab]
                        DisplayState: 'expanded'
              DisplayStateChangedFcn: @PropertyChangedCallback
                 DisplayStatePrivate: 'expanded'
                        QABIdPrivate: '2741bf89'
               QuickAccessBarPrivate: [1×1 matlab.ui.internal.toolstrip.impl.QuickAccessBar]
       DisplayStateChangedFcnPrivate: @PropertyChangedCallback
         SelectedTabChangedListeners: [1×1 event.listener]
                                 Tag: 'toolstrip'
                                Type: 'Toolstrip'
                          TagPrivate: 'toolstrip'
    WidgetPropertyMap_FromMCOSToPeer: [3×1 containers.Map]
    WidgetPropertyMap_FromPeerToMCOS: [3×1 containers.Map]
                              Parent: [0×0 matlab.ui.internal.toolstrip.base.Node]
                            Children: [1×1 matlab.ui.internal.toolstrip.TabGroup]
                             Parent_: []
                           Children_: [1×1 matlab.ui.internal.toolstrip.TabGroup]
                                Peer: [1×1 com.mathworks.peermodel.impl.PeerNodeImpl]
                   PropertySetSource: [1 java.util.HashMap]
                    PeerModelChannel: '/ToolstripShowcaseChannel'
                   PeerEventListener: [1×1 handle.listener]
                 PropertySetListener: [1×1 handle.listener]
>> hs.Peer
ans =
PeerNodeImpl{id='4a1e4b08', type='Toolstrip', properties={displayState=expanded, hostId=ToolStripShowcaseDIV, tag=toolstrip, QABId=2741bf89}, parent=878b0e2b, children=[
    PeerNodeImpl{id='5bb9632c', type='TabGroup', properties={QAGroupId=ea9b628c, tag=, selectedTab=f90db10c}, parent=4a1e4b08, children=[
        PeerNodeImpl{id='f90db10c', type='Tab', properties={mnemonic=, tag=tab_buttons, title=BUTTONS}, parent=5bb9632c, children=[
            PeerNodeImpl{id='1ccc9246', type='Section', properties={collapsePriority=0.0, mnemonic=, tag=sec_push, title=PUSH BUTTON}, parent=f90db10c, children=[
                PeerNodeImpl{id='8323f06e', type='Column', properties={horizontalAlignment=left, width=0.0, tag=}, parent=1ccc9246, children=[
                    PeerNodeImpl{id='af368d7b', type='PushButton', properties={textOverride=, descriptionOverride=, mnemonic=, actionId=230d471b, iconOverride=, tag=pushV, iconPathOverride=}, parent=8323f06e, children=[]}]}
                PeerNodeImpl{id='a557a712', type='Column', properties={horizontalAlignment=left, width=0.0, tag=}, parent=1ccc9246, children=[
                    PeerNodeImpl{id='f0d6a9fc', type='EmptyControl', properties={tag=}, parent=a557a712, children=[]}
                    PeerNodeImpl{id='74bc4cd2', type='PushButton', properties={textOverride=, descriptionOverride=, mnemonic=, actionId=12d6a26a, iconOverride=, tag=pushH, iconPathOverride=}, parent=a557a712, children=[]}
                    PeerNodeImpl{id='bcb5a9d0', type='EmptyControl', properties={tag=}, parent=a557a712, children=[]}]}]}
            PeerNodeImpl{id='0e515319', type='Section', properties={collapsePriority=0.0, mnemonic=, tag=sec_dropdown, title=DROP DOWN BUTTON}, parent=f90db10c, children=[
                PeerNodeImpl{id='80482225', type='Column', properties={horizontalAlignment=left, width=0.0, tag=}, parent=0e515319, children=[
                    PeerNodeImpl{id='469f469a', type='DropDownButton', properties={textOverride=, descriptionOverride=, mnemonic=, actionId=c6ca7335, iconOverride=, tag=dropdownV, iconPathOverride=}, parent=80482225, children=[]}]}
                ...
</pre>
<p>Note: <code>showcaseCEF</code> has been removed in 2018, but is available in older Matlab releases.</p>
<h3 id="levels">Levels of toolstrip encapsulation</h3>
<p>Matlab currently has several levels of encapsulation for toolstrip components:</p>
<ul>
<li>Top-level m-file classes for showcasing the toolstrip functionality and creating toolstrips in Java-based containers and web-based apps &#8211; these are located in <i>%matlabroot%/toolbox/matlab/toolstrip/+matlab/+ui/+internal/+desktop/</i></li>
<li>Mid-level m-file classes that contain the toolstrip building blocks (tabs, sections, controls) &#8211; these are located in <i>%matlabroot%/toolbox/matlab/toolstrip/+matlab/+ui/+internal/+toolstrip/</i></li>
<li>Low-level Java classes that implement the underlying user-interface for Java-based UI &#8211; these are located in <i>%matlabroot%/java/jar/toolstrip.jar</i>. I <a href="https://undocumentedmatlab.com/articles/programmatic-shortcuts-manipulation-part-2#custom" target="_blank">discussed this briefly</a> in a post few years ago.</li>
</ul>
<p>The top- and mid-level m-file classes are provided with full source code that is quite well-documented internally (as m-file source-code comments). However, note that it is not officially documented or supported (i.e., <a href="https://undocumentedmatlab.com/articles/tag/semi-documented-feature" target="_blank">semi-documented</a> in this blog&#8217;s parlance).<br />
The low-level Java classes on the other hand are compiled without available source code &#8211; we can inspect these classes (e.g., using <a href="https://undocumentedmatlab.com/articles/uiinspect" target="_blank">uiinspect</a> or <a href="https://undocumentedmatlab.com/articles/checkclass" target="_blank">checkClass</a>), but we cannot see their original source-code. Luckily, the higher-level m-file classes provide us with plenty of hints and usage examples that we could use to tailor the appearance, functionality and integration of toolstrip components into our app.</p>
<h3 id="Widgets_toolbox">Robyn Jackey&#8217;s Widgets Toolbox</h3>
<p>Users who hesitate to mess around with the built-in toolstrip functionality may find interest in MathWorker Robyn Jackey&#8217;s <a href="https://www.mathworks.com/matlabcentral/fileexchange/66235-widgets-toolbox?focused=a9526a57-50fa-052b-7343-3cbce74b2095&#038;tab=example" rel="nofollow" target="_blank">Toolstrip look-alike</a>, which is part of his open-source <a href="https://www.mathworks.com/matlabcentral/fileexchange/66235-widgets-toolbox" rel="nofollow" target="_blank">Widgets Toolbox</a> on the Matlab File Exchange. Unlike other parts of Robyn&#8217;s toolbox, which use undocumented functionality, his Toolstrip class seems to use documented components (panels, uicontrols etc.), with just a small reliance on undocumented functionality (<code>matlab.ui.*</code> for example). This has a fair chance to continue working well into future releases, even if Matlab&#8217;s built-in toolstrip functionality changes:<br />
<center><img decoding="async" src="https://undocumentedmatlab.com/images/demoToolstrip_05.png" alt="Robyn Jackey's Toolstrip look-alike" title="Robyn Jackey's Toolstrip look-alike" width="80%" style="max-width:835px; max-height:83px;" /></center></p>
<h3 id="caution">Strong caution</h3>
<p>Over the years, Matlab&#8217;s internal toolstrip interface has changed somewhat, but not dramatically. This could change at any time, since the toolstrip uses deeply undocumented functionality. What I will demonstrate over the next few posts might stop working in R2019a, or in R2025b &#8211; nobody really knows, perhaps not even MathWorks at this stage. Something that we do know for a fact is that Matlab is slowly transitioning away from Java-based user interfaces to web-based (HTML/JavaScript/CSS) interfaces, and this could have a drastic effect on the toolstrip functionality/API. It seems reasonable to assume that even if MathWorks would one day open up the toolstrip functionality, this would only be for the new web-based uifigure apps (not legacy Java-based figures), and might well have a different API than the one that I&#8217;ll discuss in this miniseries. Still, users could use the unofficial/undocumented information that I present here in their own Java figures today and quite possibly also in near-term upcoming releases.<br />
Despite the many unknowns regarding future supportability/roadmap of the built-in toolstrip API, I believe that my readers are smart enough to decide for themselves whether they want to take the associated risks to improve their Matlab programs today, or wait until a documented API will possibly be provided sometime in the future. The choice is yours, as it always is when using undocumented tips from my blog.<br />
With this warning stated, let&#8217;s start having fun with Matlab&#8217;s built-in toolstrip!</p>
<p>The post <a rel="nofollow" href="https://undocumentedmatlab.com/articles/matlab-toolstrip-part-1">Matlab toolstrip &#8211; part 1</a> appeared first on <a rel="nofollow" href="https://undocumentedmatlab.com">Undocumented Matlab</a>.</p>
<div class='yarpp-related-rss'>
<h3>Related posts:</h3><ol>
<li><a href="https://undocumentedmatlab.com/articles/matlab-toolstrip-part-3-basic-customization" rel="bookmark" title="Matlab toolstrip – part 3 (basic customization)">Matlab toolstrip – part 3 (basic customization) </a> <small>Matlab toolstrips can be created and customized in a variety of ways. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/matlab-toolstrip-part-2-toolgroup-app" rel="bookmark" title="Matlab toolstrip – part 2 (ToolGroup App)">Matlab toolstrip – part 2 (ToolGroup App) </a> <small>Matlab users can create custom Apps with toolstrips and docked figures. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/matlab-toolstrip-part-8-galleries" rel="bookmark" title="Matlab toolstrip – part 8 (galleries)">Matlab toolstrip – part 8 (galleries) </a> <small>Matlab toolstrips can contain customizable gallery panels of items. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/matlab-toolstrip-part-5-icons" rel="bookmark" title="Matlab toolstrip – part 5 (icons)">Matlab toolstrip – part 5 (icons) </a> <small>Icons can be specified in various ways for toolstrip controls and the app window itself. ...</small></li>
</ol>
</div>
]]></content:encoded>
					
					<wfw:commentRss>https://undocumentedmatlab.com/articles/matlab-toolstrip-part-1/feed</wfw:commentRss>
			<slash:comments>6</slash:comments>
		
		
			</item>
		<item>
		<title>Parsing XML strings</title>
		<link>https://undocumentedmatlab.com/articles/parsing-xml-strings?utm_source=rss&#038;utm_medium=rss&#038;utm_campaign=parsing-xml-strings</link>
					<comments>https://undocumentedmatlab.com/articles/parsing-xml-strings#comments</comments>
		
		<dc:creator><![CDATA[Yair Altman]]></dc:creator>
		<pubDate>Wed, 01 Feb 2017 09:52:45 +0000</pubDate>
				<category><![CDATA[Low risk of breaking in future versions]]></category>
		<category><![CDATA[Semi-documented feature]]></category>
		<category><![CDATA[Stock Matlab function]]></category>
		<category><![CDATA[Java]]></category>
		<category><![CDATA[Performance]]></category>
		<category><![CDATA[XML]]></category>
		<guid isPermaLink="false">http://undocumentedmatlab.com/?p=6838</guid>

					<description><![CDATA[<p>Matlab's xmlread function cannot process XML data directly, but this can easily be overcome.  </p>
<p>The post <a rel="nofollow" href="https://undocumentedmatlab.com/articles/parsing-xml-strings">Parsing XML strings</a> appeared first on <a rel="nofollow" href="https://undocumentedmatlab.com">Undocumented Matlab</a>.</p>
<div class='yarpp-related-rss'>
<h3>Related posts:</h3><ol>
<li><a href="https://undocumentedmatlab.com/articles/parsing-mlint-code-analyzer-output" rel="bookmark" title="Parsing mlint (Code Analyzer) output">Parsing mlint (Code Analyzer) output </a> <small>The Matlab Code Analyzer (mlint) has a lot of undocumented functionality just waiting to be used. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/file-deletion-memory-leaks-performance" rel="bookmark" title="File deletion memory leaks, performance">File deletion memory leaks, performance </a> <small>Matlab's delete function leaks memory and is also slower than the equivalent Java function. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/matlab-compiler-bug-and-workaround" rel="bookmark" title="Matlab compiler bug and workaround">Matlab compiler bug and workaround </a> <small>Both the Matlab compiler and the publish function have errors when parsing block-comments in Matlab m-code. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/undocumented-xml-functionality" rel="bookmark" title="Undocumented XML functionality">Undocumented XML functionality </a> <small>Matlab's built-in XML-processing functions have several undocumented features that can be used by Java-savvy users...</small></li>
</ol>
</div>
]]></description>
										<content:encoded><![CDATA[<p>I have recently consulted in a project where data was provided in XML strings and needed to be parsed in Matlab memory in an efficient manner (in other words, as quickly as possible). Now granted, XML is rather inefficient in storing data (JSON would be much better for this, for example). But I had to work with the given situation, and that required processing the XML.<br />
I basically had two main alternatives:</p>
<ul>
<li>I could either create a dedicated string-parsing function that searches for a particular pattern within the XML string, or</li>
<li>I could use a standard XML-parsing library to create the XML model and then parse its nodes</li>
</ul>
<p>The first alternative is quite error-prone, since it relies on the exact format of the data in the XML. Since the same data can be represented in multiple equivalent XML ways, making the string-parsing function robust as well as efficient would be challenging. I was <del>lazy</del> expedient, so I chose the second alternative.<br />
Unfortunately, Matlab&#8217;s <i><b>xmlread</b></i> function only accepts input filenames (of *.xml files), it cannot directly parse XML strings. Yummy!<br />
The obvious and simple solution is to simply write the XML string into a temporary *.xml file, read it with <i><b>xmlread</b></i>, and then delete the temp file:</p>
<pre lang="matlab">
% Store the XML data in a temp *.xml file
filename = [tempname '.xml'];
fid = fopen(filename,'Wt');
fwrite(fid,xmlString);
fclose(fid);
% Read the file into an XML model object
xmlTreeObject = xmlread(filename);
% Delete the temp file
delete(filename);
% Parse the XML model object
...
</pre>
<p>This works well and we could move on with our short lives. But cases such as this, where a built-in function seems to have a silly limitation, really fire up the investigative reporter in me. I decided to drill into <i><b>xmlread</b></i> to discover why it couldn&#8217;t parse XML strings directly in memory, without requiring costly file I/O. It turns out that <i><b>xmlread</b></i> accepts not just file <i>names</i> as input, but also Java object references (specifically, <a href="http://docs.oracle.com/javase/7/docs/api/java/io/File.html" rel="nofollow" target="_blank"><code>java.io.File</code></a>, <a href="http://docs.oracle.com/javase/7/docs/api/java/io/InputStream.html" rel="nofollow" target="_blank"><code>java.io.InputStream</code></a> or <a href="http://docs.oracle.com/javase/7/docs/api/org/xml/sax/InputSource.html" rel="nofollow" target="_blank"><code>org.xml.sax.InputSource</code></a>). In fact, there are quite a few other inputs that we could use, to specify a validation parser etc. &#8211; <a href="/articles/undocumented-xml-functionality" target="_blank">I wrote about this briefly</a> back in 2009 (along with other similar semi-documented input altermatives in <i><b>xmlwrite</b></i> and <i><b>xslt</b></i>).<br />
<span id="more-6838"></span><br />
In our case, we could simply send <i><b>xmlread</b></i> as input a <code><a href="http://docs.oracle.com/javase/7/docs/api/java/io/StringBufferInputStream.html" rel="nofollow" target="_blank">java.io.StringBufferInputStream</a>(xmlString)</code> object (which is an instance of <code>java.io.InputStream</code>) or <code>org.xml.sax.InputSource(java.io.StringReader(xmlString))</code>:</p>
<pre lang="matlab">
% Read the xml string directly into an XML model object
inputObject = java.io.StringBufferInputStream(xmlString);                % alternative #1
inputObject = org.xml.sax.InputSource(java.io.StringReader(xmlString));  % alternative #2
xmlTreeObject = xmlread(inputObject);
% Parse the XML model object
...
</pre>
<p>If we don&#8217;t want to depend on undocumented functionality (which might break in some future release, although it has remained unchanged for at least the past decade), and in order to improve performance even further by passing <i><b>xmlread</b></i>&#8216;s internal validity checks and processing, we can use <i><b>xmlread</b></i>&#8216;s core functionality to parse our XML string directly. We can add a fallback to the standard (fully-documented) functionality, just in case something goes wrong (which is good practice whenever using any undocumented functionality):</p>
<pre lang="matlab">
try
    % The following avoids the need for file I/O:
    inputObject = java.io.StringBufferInputStream(xmlString);  % or: org.xml.sax.InputSource(java.io.StringReader(xmlString))
    try
        % Parse the input data directly using xmlread's core functionality
        parserFactory = javaMethod('newInstance','javax.xml.parsers.DocumentBuilderFactory');
        p = javaMethod('newDocumentBuilder',parserFactory);
        xmlTreeObject = p.parse(inputObject);
    catch
        % Use xmlread's semi-documented inputObject input feature
        xmlTreeObject = xmlread(inputObject);
    end
catch
    % Fallback to standard xmlread usage, using a temporary XML file:
    % Store the XML data in a temp *.xml file
    filename = [tempname '.xml'];
    fid = fopen(filename,'Wt');
    fwrite(fid,xmlString);
    fclose(fid);
    % Read the file into an XML model object
    xmlTreeObject = xmlread(filename);
    % Delete the temp file
    delete(filename);
end
% Parse the XML model object
...
</pre>
<p>The post <a rel="nofollow" href="https://undocumentedmatlab.com/articles/parsing-xml-strings">Parsing XML strings</a> appeared first on <a rel="nofollow" href="https://undocumentedmatlab.com">Undocumented Matlab</a>.</p>
<div class='yarpp-related-rss'>
<h3>Related posts:</h3><ol>
<li><a href="https://undocumentedmatlab.com/articles/parsing-mlint-code-analyzer-output" rel="bookmark" title="Parsing mlint (Code Analyzer) output">Parsing mlint (Code Analyzer) output </a> <small>The Matlab Code Analyzer (mlint) has a lot of undocumented functionality just waiting to be used. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/file-deletion-memory-leaks-performance" rel="bookmark" title="File deletion memory leaks, performance">File deletion memory leaks, performance </a> <small>Matlab's delete function leaks memory and is also slower than the equivalent Java function. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/matlab-compiler-bug-and-workaround" rel="bookmark" title="Matlab compiler bug and workaround">Matlab compiler bug and workaround </a> <small>Both the Matlab compiler and the publish function have errors when parsing block-comments in Matlab m-code. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/undocumented-xml-functionality" rel="bookmark" title="Undocumented XML functionality">Undocumented XML functionality </a> <small>Matlab's built-in XML-processing functions have several undocumented features that can be used by Java-savvy users...</small></li>
</ol>
</div>
]]></content:encoded>
					
					<wfw:commentRss>https://undocumentedmatlab.com/articles/parsing-xml-strings/feed</wfw:commentRss>
			<slash:comments>8</slash:comments>
		
		
			</item>
		<item>
		<title>Sending email/text messages from Matlab</title>
		<link>https://undocumentedmatlab.com/articles/sending-email-text-messages-from-matlab?utm_source=rss&#038;utm_medium=rss&#038;utm_campaign=sending-email-text-messages-from-matlab</link>
					<comments>https://undocumentedmatlab.com/articles/sending-email-text-messages-from-matlab#comments</comments>
		
		<dc:creator><![CDATA[Yair Altman]]></dc:creator>
		<pubDate>Wed, 07 Dec 2016 21:24:03 +0000</pubDate>
				<category><![CDATA[GUI]]></category>
		<category><![CDATA[Java]]></category>
		<category><![CDATA[Medium risk of breaking in future versions]]></category>
		<category><![CDATA[Semi-documented feature]]></category>
		<category><![CDATA[Stock Matlab function]]></category>
		<category><![CDATA[Undocumented property]]></category>
		<guid isPermaLink="false">http://undocumentedmatlab.com/?p=6765</guid>

					<description><![CDATA[<p>Sending emails and SMS (text) messages from Matlab is easy, once you know a few quirks.</p>
<p>The post <a rel="nofollow" href="https://undocumentedmatlab.com/articles/sending-email-text-messages-from-matlab">Sending email/text messages from Matlab</a> appeared first on <a rel="nofollow" href="https://undocumentedmatlab.com">Undocumented Matlab</a>.</p>
<div class='yarpp-related-rss'>
<h3>Related posts:</h3><ol>
<li><a href="https://undocumentedmatlab.com/articles/sending-html-emails-from-matlab" rel="bookmark" title="Sending HTML emails from Matlab">Sending HTML emails from Matlab </a> <small>Matlab's sendmail only sends simple text messages by default; a simple hack can cause it to send HTML-formatted messages. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/setting-system-tray-popup-messages" rel="bookmark" title="Setting system tray popup messages">Setting system tray popup messages </a> <small>System-tray icons and messages can be programmatically set and controlled from within Matlab, using new functionality available since R2007b....</small></li>
<li><a href="https://undocumentedmatlab.com/articles/icon-images-in-matlab-uicontrols" rel="bookmark" title="Icon images &amp; text in Matlab uicontrols">Icon images &amp; text in Matlab uicontrols </a> <small>HTML can be used to add image icons to Matlab listbox and popup (drop-down) controls. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/checking-status-of-warning-messages-in-mex" rel="bookmark" title="Checking status of warning messages in MEX">Checking status of warning messages in MEX </a> <small>Undocumented Mex functions can be used to extract the state of Matlab warnings in run-time. ...</small></li>
</ol>
</div>
]]></description>
										<content:encoded><![CDATA[<p>In this day and age, applications are expected to communicate with users by sending email/text messages to alert them about applicative events (<i>&#8220;IBM stock purchased @$99.99&#8221;</i> or <i>&#8220;House is on fire!&#8221;</i>). Matlab has included the <a href="http://www.mathworks.com/help/matlab/ref/sendmail.html" rel="nofollow" target="_blank"><i><b>sendmail</b></i> function</a> to handle this for many years. Unfortunately, <i><b>sendmail</b></i> requires some tweaking to be useful on all but the most basic/insecure mail servers. Today&#8217;s post will hopefully fill the missing gaps.<br />
None of the information I&#8217;ll present today is really new &#8211; it was all there already if you just knew what to search for online. But hopefully today&#8217;s post will concentrate all these loose ends in a single place, so it may have some value:</p>
<ul>
<li><a href="#TLS">Using a secure mail server</a></li>
<li><a href="#multiple">Emailing multiple recipients</a></li>
<li><a href="#SMS">Sending text messages</a></li>
<li><a href="#panel">User configuration panel</a></li>
</ul>
<p><span id="more-6765"></span></p>
<h3 id="TLS">Using a secure mail server</h3>
<p>All modern mail servers use end-to-end TLS/SSL encryption. The <i><b>sendmail</b></i> function needs extra configuration to handle such connections, since it is configured for a non-encrypted connection by default. Here&#8217;s the code that does this for gmail, using SMTP server <code>smtp.gmail.com</code> and default port #465 (for other SMTP servers, <a href="https://www.arclab.com/en/kb/email/list-of-smtp-and-pop3-servers-mailserver-list.html" rel="nofollow" target="_blank">see here</a>):</p>
<pre lang="matlab">
setpref('Internet', 'E_mail', from_address);  % sender "from" address, typically same as username, e.g. 'xyz@gmail.com'
setpref('Internet', 'SMTP_Username', username);
setpref('Internet', 'SMTP_Password', password);
setpref('Internet', 'SMTP_Server',   'smtp.gmail.com');
props = java.lang.System.getProperties;
props.setProperty('mail.smtp.auth',                'true');  % Note: 'true' as a string, not a logical value!
props.setProperty('mail.smtp.starttls.enable',     'true');  % Note: 'true' as a string, not a logical value!
props.setProperty('mail.smtp.socketFactory.port',  '465');   % Note: '465'  as a string, not a numeric value!
props.setProperty('mail.smtp.socketFactory.class', 'javax.net.ssl.SSLSocketFactory');
sendmail(recipient, title, body, attachments);  % e.g., sendmail('recipient@gmail.com', 'Hello world', 'What a nice day!', 'C:\images\sun.jpg')
</pre>
<p>All this is not enough to enable Matlab to connect to gmail&#8217;s SMTP servers. In addition, we need to set the Google account to allow access from &#8220;less secure apps&#8221; (<a href="https://support.google.com/accounts/answer/6010255" rel="nofollow" target="_blank">details</a>, <a href="https://www.google.com/settings/security/lesssecureapps?rfn=27&#038;rfnc=1&#038;asae=2&#038;anexp=lbe-R1_C" rel="nofollow" target="_blank">direct link</a>). Without this, Google will not allow Matlab to relay emails. Other mail servers may require similar server-side account configurations to enable Matlab&#8217;s access.<br />
Note: This code snippet uses a bit of Java as you can see. Under the hood, all networking code in Matlab relies on Java, and <i><b>sendmail</b></i> is no exception. For some reason that I don&#8217;t fully understand, MathWorks chose to label the feature of using <i><b>sendmail</b></i> with secure mail servers as a feature that relies on &#8220;undocumented commands&#8221; and is therefore not listed in <i><b>sendmail</b></i>&#8216;s documentation. Considering the fact that all modern mail servers are secure, this seems to make <i><b>sendmail</b></i> rather useless without the undocumented extension. I assume that TMW are well aware of this, which is the reason they posted a partial documentation in the form of an <a href="https://www.mathworks.com/matlabcentral/answers/93383-how-do-i-use-sendmail-to-send-email-from-matlab-7-2-r2006a-via-the-gmail-server-or-yahoo-server" rel="nofollow" target="_blank">official tech-support answer</a>. I hope that one day MathWorks will incorporate it into <i><b>sendmail</b></i> as optional input args, so that using <i><b>sendmail</b></i> with secure servers would become fully documented and officially supported.</p>
<h3 id="multiple">Emailing multiple recipients</h3>
<p>To specify multiple email recipients, it is not enough to set <i><b>sendmail</b></i>&#8216;s <code>recipient</code> input arg to a string with , or ; delimiters. Instead, we need to provide a cell array of individual recipient strings. For example:</p>
<pre lang="matlab">sendmail({'recipient1@gmail.com','recipient2@gmail.com'}, 'Hello world', 'What a nice day!')</pre>
<p>Note: this feature is actually fully documented in <i><b>sendmail</b></i>&#8216;s doc-page, but for some reason I see that some users are not aware of it (to which it might be said: <i>RTFM!</i>).</p>
<h3 id="SMS">Sending phone text (SMS) messages</h3>
<p>With modern smartphones, text (SMS) messages have become rather outdated, as most users get push notifications of incoming emails. Still, for some users text messages may still be a useful. To send such messages, all we need is to determine our mobile carrier&#8217;s email gateway for SMS messages, and send a simple text message to that email address. For example, to send a text message to T-Mobile number 123-456-7890 in the US, simply email the message to 1234567890@tmomail.net (<a href="https://en.wikipedia.org/wiki/SMS_gateway#Email_clients" rel="nofollow" target="_blank">details</a>).<br />
Ke Feng posted a nice <a href="http://www.mathworks.com/matlabcentral/fileexchange/16649-send-text-message-to-cell-phone" rel="nofollow" target="_blank">Matlab File Exchange utility</a> that wraps this messaging for a wide variety of US carriers.</p>
<h3 id="panel">User configuration panel</h3>
<p>Many GUI programs contain configuration panels/tabs/windows. Enabling the user to set up their own email provider is a typical use-case for such a configuration. Naturally, you&#8217;d want your config panel not to display plain-text password, nor non-integer port numbers. You&#8217;d also want the user to be able to test the email connection.<br />
Here&#8217;s a sample implementation for such a panel that I implemented for a recent project &#8211; I plan to discuss the implementation details of the password and port (spinner) controls in my next post, so stay tuned:<br />
<center><a href="/images/email_config_panel.png" target="_blank"><img decoding="async" alt="User configuration of emails in Matlab GUI (click to zoom-in)" src="https://undocumentedmatlab.com/images/email_config_panel.png" title="User configuration of emails in Matlab GUI (click to zoom-in)" width="75%" style="max-width:842px;"></a><br />
User configuration of emails in Matlab GUI (click to zoom-in)</center></p>
<p>The post <a rel="nofollow" href="https://undocumentedmatlab.com/articles/sending-email-text-messages-from-matlab">Sending email/text messages from Matlab</a> appeared first on <a rel="nofollow" href="https://undocumentedmatlab.com">Undocumented Matlab</a>.</p>
<div class='yarpp-related-rss'>
<h3>Related posts:</h3><ol>
<li><a href="https://undocumentedmatlab.com/articles/sending-html-emails-from-matlab" rel="bookmark" title="Sending HTML emails from Matlab">Sending HTML emails from Matlab </a> <small>Matlab's sendmail only sends simple text messages by default; a simple hack can cause it to send HTML-formatted messages. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/setting-system-tray-popup-messages" rel="bookmark" title="Setting system tray popup messages">Setting system tray popup messages </a> <small>System-tray icons and messages can be programmatically set and controlled from within Matlab, using new functionality available since R2007b....</small></li>
<li><a href="https://undocumentedmatlab.com/articles/icon-images-in-matlab-uicontrols" rel="bookmark" title="Icon images &amp; text in Matlab uicontrols">Icon images &amp; text in Matlab uicontrols </a> <small>HTML can be used to add image icons to Matlab listbox and popup (drop-down) controls. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/checking-status-of-warning-messages-in-mex" rel="bookmark" title="Checking status of warning messages in MEX">Checking status of warning messages in MEX </a> <small>Undocumented Mex functions can be used to extract the state of Matlab warnings in run-time. ...</small></li>
</ol>
</div>
]]></content:encoded>
					
					<wfw:commentRss>https://undocumentedmatlab.com/articles/sending-email-text-messages-from-matlab/feed</wfw:commentRss>
			<slash:comments>6</slash:comments>
		
		
			</item>
		<item>
		<title>Types of undocumented Matlab aspects</title>
		<link>https://undocumentedmatlab.com/articles/types-of-undocumented-matlab-aspects?utm_source=rss&#038;utm_medium=rss&#038;utm_campaign=types-of-undocumented-matlab-aspects</link>
					<comments>https://undocumentedmatlab.com/articles/types-of-undocumented-matlab-aspects#respond</comments>
		
		<dc:creator><![CDATA[Yair Altman]]></dc:creator>
		<pubDate>Thu, 24 Nov 2011 18:00:36 +0000</pubDate>
				<category><![CDATA[High risk of breaking in future versions]]></category>
		<category><![CDATA[Java]]></category>
		<category><![CDATA[Low risk of breaking in future versions]]></category>
		<category><![CDATA[Medium risk of breaking in future versions]]></category>
		<category><![CDATA[Semi-documented feature]]></category>
		<category><![CDATA[Semi-documented function]]></category>
		<category><![CDATA[Undocumented feature]]></category>
		<category><![CDATA[Undocumented function]]></category>
		<category><![CDATA[Hidden property]]></category>
		<category><![CDATA[Internal component]]></category>
		<category><![CDATA[JMI]]></category>
		<category><![CDATA[Pure Matlab]]></category>
		<category><![CDATA[Undocumented property]]></category>
		<guid isPermaLink="false">http://undocumentedmatlab.com/?p=2534</guid>

					<description><![CDATA[<p>This article lists the different types of undocumented/unsupported/hidden aspects in Matlab</p>
<p>The post <a rel="nofollow" href="https://undocumentedmatlab.com/articles/types-of-undocumented-matlab-aspects">Types of undocumented Matlab aspects</a> appeared first on <a rel="nofollow" href="https://undocumentedmatlab.com">Undocumented Matlab</a>.</p>
<div class='yarpp-related-rss'>
<h3>Related posts:</h3><ol>
<li><a href="https://undocumentedmatlab.com/articles/reasons-for-undocumented-matlab-aspects" rel="bookmark" title="Reasons for undocumented Matlab aspects">Reasons for undocumented Matlab aspects </a> <small>There are many reasons for the numerous undocumented aspects in Matlab - this article explains them....</small></li>
<li><a href="https://undocumentedmatlab.com/articles/undocumented-plot-marker-types" rel="bookmark" title="Undocumented plot marker types">Undocumented plot marker types </a> <small>Undocumented plot marker styles can easily be accesses using a hidden plot-line property. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/setting-class-property-types-2" rel="bookmark" title="Setting class property types &#8211; take 2">Setting class property types &#8211; take 2 </a> <small>R2016a saw the addition of class property types. However, a better alternative has existed for many years. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/setting-class-property-types" rel="bookmark" title="Setting class property types">Setting class property types </a> <small>Matlab's class properties have a simple and effective mechanism for setting their type....</small></li>
</ol>
</div>
]]></description>
										<content:encoded><![CDATA[<p>Why are there so many undocumented aspects in Matlab?<br />
This is a great question, recently <a target="_blank" href="/articles/guide-customization/#comment-61578">asked</a> by a reader of this blog, so I wanted to expand on it in next week&#8217;s article. Before specifying the different reasons, let&#8217;s map the nature of undocumented aspects that we find in Matlab.<br />
The term <i>undocumented/unsupported</i> (as opposed to <i>mis-documentated</i> or <i>deprecated</i>) actually refers to quite a large number of different types.<br />
In the following list, the hyperlinks on the list-item titles lead to a list of corresponding articles on this website:</p>
<ul>
<li><b><a target="_blank" href="/articles/tag/undocumented-function/">Undocumented functions</a></b><br />
Matlab functions which appears nowhere in the documentation, are usually built-in functions (do not have an m-file) and can only be inferred from online CSSM posts or usage within one of the Matlab m-functions installed with Matlab (the latter being the usual case). None of these functions is officially supported by MathWorks. <a target="_blank" href="/articles/category/mex/">MEX</a> is an important source for such functions.
</li>
<li><b><a target="_blank" href="/articles/tag/semi-documented-function/">Semi-documented functions</a></b><br />
Matlab functionality which exists in Matlab m-functions installed with Matlab, but have their main comment separated from the H1 comment line, thereby hiding it from normal view (via Matlab&#8217;s <i><b>help</b></i> function). The H1 comment line itself is simply a standard warning that this function is not officially supported and may change in some future version. To see the actual help comment, simply edit the function (using Matlab&#8217;s <i><b>edit</b></i> function or any text editor) and place a comment sign (%) at the empty line between the H1 comment and the actual help section. The entire help section will then onward be visible via the <i><b>help</b></i> function:</p>
<pre lang='matlab'>
        function [tree, container] = uitree(varargin)
        % WARNING: This feature is not supported in MATLAB
        % and the API and functionality may change in a future release.
fix =>  %
        % UITREE creates a uitree component with hierarchical data in a figure window.
        %   UITREE creates an empty uitree object with default property values in
        %   a figure window.
        %...
</pre>
<p>These functions are not documented in the full documentation (via Matlab&#8217;s <i><b>doc</b></i> function, or online). The odd thing is that some of these functions may appear in the category help output (for example, <i><b>help</b>(&#8216;uitools&#8217;)</i>), and in some cases may even have a fully-visible help section (e.g., <i><b>help</b>(&#8216;setptr&#8217;)</i>), but do not have any online help documentation (<i><b>docsearch</b>(&#8216;setptr&#8217;)</i> fails, and <i><b>doc</b>(&#8216;setptr&#8217;)</i> simply displays the readable help text).<br />
All these functions are officially unsupported by MathWorks, even when having a readable help section. The rule of thumb appears to be that a Matlab function is supported only if it has online documentation. Note, however, that in some rare cases a documentation discrepancy may be due to a MathWorks documentation error, not to unsupportability&#8230;
</li>
<li><b><a target="_blank" href="/articles/tag/undocumented-function/">Helper functions</a></b><br />
Many fully-supported Matlab functions use helper functions that have a specific use in the main (documented) function(s).  Often, these helper functions are tightly-coupled to their documented parents and are useless as stand-alone functions. But quite a few of them have quite useful stand-alone use, as I&#8217;ve already shown in some past articles.
</li>
<li><b><a target="_blank" href="/articles/tag/undocumented-feature/">Undocumented features</a> and <a target="_blank" href="/articles/tag/undocumented-property/">properties</a></b><br />
Features of otherwise-documented Matlab functions, which appear nowhere in the official documentation. You guessed it – these are also not supported by MathWorks&#8230; Like undocumented functions, you can only infer such features by the occasional CSSM post or a reference somewhere in Matlab&#8217;s m-code.
</li>
<li><b><a target="_blank" href="/articles/tag/semi-documented-feature/">Semi-documented features</a></b><br />
Features of otherwise-documented Matlab functions, which are documented in a separate section beneath the main help section, and nowhere else (not in the full doc not the online documentation). If you did not know in advance that these features existed, you could only learn of them by manually looking at Matlab&#8217;s m-files (which is what I do in most cases&#8230;).
</li>
<li><b><a target="_blank" href="/articles/tag/undocumented-property/">Undocumented properties</a></b><br />
Many Matlab objects have internal properties, which can be retrieved (via Matlab&#8217;s <i><b>get</b></i> function) and/or set (via the <i><b>set</b></i> function) programmatically. All these properties are fully documented. Many objects also possess hidden properties, some of which are very interesting and useful, but which are undocumented and (oh yes) unsupported. Like undocumented features, they can only be inferred from CSSM or existing code. In a recent <a target="_blank" href="/articles/getundoc-get-undocumented-object-properties/">article</a> I described my <i><b>getundoc</b></i> utility, which lists these undocumented properties of specified objects.
</li>
<li><b><a target="_blank" href="/articles/tag/internal-component/">Internal Matlab classes</a></b><br />
Matlab uses a vast array of specialized Java classes to handle everything from algorithms to GUI. These classes are (of course) undocumented/unsupported. They can often be accessed directly from the Matlab Command Window or user m-files. GUI classes can be inferred by inspecting the figure frame&#8217;s Java components, and non-GUI classes can often be inferred from references in Matlab&#8217;s m-files.
</li>
<li><b><a target="_blank" href="/articles/tag/JMI">Matlab-Java integration</a></b><br />
Matlab&#8217;s GUI interface, as well as the Java-to-Matlab interface (JMI) is fully undocumented and unsupported. In addition to JMI, there are other mechanisms to run Matlab code from within Java (namely JMI, COM and DDE) &#8211; these are all unsupported and by-and-large undocumented.
</li>
<li><b><a target="_blank" href="/?s=UDD">Matlab&#8217;s UDD mechanism</a></b><br />
UDD (Unified Data Definition?) is used extensively in Matlab as the internal object-oriented mechanism for describing object properties and functionalities. We can use UDD for a wide variety of uses. UDD was described in a series of articles here in early 2011.
</li>
</ul>
<p>Next week I will list the reasons that cause MathWorks to decide whether a particular feature or property should be documented or not.</p>
<p>The post <a rel="nofollow" href="https://undocumentedmatlab.com/articles/types-of-undocumented-matlab-aspects">Types of undocumented Matlab aspects</a> appeared first on <a rel="nofollow" href="https://undocumentedmatlab.com">Undocumented Matlab</a>.</p>
<div class='yarpp-related-rss'>
<h3>Related posts:</h3><ol>
<li><a href="https://undocumentedmatlab.com/articles/reasons-for-undocumented-matlab-aspects" rel="bookmark" title="Reasons for undocumented Matlab aspects">Reasons for undocumented Matlab aspects </a> <small>There are many reasons for the numerous undocumented aspects in Matlab - this article explains them....</small></li>
<li><a href="https://undocumentedmatlab.com/articles/undocumented-plot-marker-types" rel="bookmark" title="Undocumented plot marker types">Undocumented plot marker types </a> <small>Undocumented plot marker styles can easily be accesses using a hidden plot-line property. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/setting-class-property-types-2" rel="bookmark" title="Setting class property types &#8211; take 2">Setting class property types &#8211; take 2 </a> <small>R2016a saw the addition of class property types. However, a better alternative has existed for many years. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/setting-class-property-types" rel="bookmark" title="Setting class property types">Setting class property types </a> <small>Matlab's class properties have a simple and effective mechanism for setting their type....</small></li>
</ol>
</div>
]]></content:encoded>
					
					<wfw:commentRss>https://undocumentedmatlab.com/articles/types-of-undocumented-matlab-aspects/feed</wfw:commentRss>
			<slash:comments>0</slash:comments>
		
		
			</item>
		<item>
		<title>Undocumented XML functionality</title>
		<link>https://undocumentedmatlab.com/articles/undocumented-xml-functionality?utm_source=rss&#038;utm_medium=rss&#038;utm_campaign=undocumented-xml-functionality</link>
					<comments>https://undocumentedmatlab.com/articles/undocumented-xml-functionality#comments</comments>
		
		<dc:creator><![CDATA[Yair Altman]]></dc:creator>
		<pubDate>Thu, 19 Nov 2009 01:12:06 +0000</pubDate>
				<category><![CDATA[Java]]></category>
		<category><![CDATA[Low risk of breaking in future versions]]></category>
		<category><![CDATA[Semi-documented feature]]></category>
		<category><![CDATA[Stock Matlab function]]></category>
		<category><![CDATA[XML]]></category>
		<guid isPermaLink="false">http://undocumentedmatlab.com/?p=751</guid>

					<description><![CDATA[<p>Matlab's built-in XML-processing functions have several undocumented features that can be used by Java-savvy users</p>
<p>The post <a rel="nofollow" href="https://undocumentedmatlab.com/articles/undocumented-xml-functionality">Undocumented XML functionality</a> appeared first on <a rel="nofollow" href="https://undocumentedmatlab.com">Undocumented Matlab</a>.</p>
<div class='yarpp-related-rss'>
<h3>Related posts:</h3><ol>
<li><a href="https://undocumentedmatlab.com/articles/parsing-xml-strings" rel="bookmark" title="Parsing XML strings">Parsing XML strings </a> <small>Matlab's xmlread function cannot process XML data directly, but this can easily be overcome. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/hidden-hg2-plot-functionality" rel="bookmark" title="Accessing hidden HG2 plot functionality">Accessing hidden HG2 plot functionality </a> <small>In HG2, some of the plot functionality is hidden in undocumented properties. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/xlsread-functionality-change-in-r2012a" rel="bookmark" title="xlsread functionality change in R2012a">xlsread functionality change in R2012a </a> <small>The functionality of the xlsread function has changed without documentation or warning in the R2012a release. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/ismembc-undocumented-helper-function" rel="bookmark" title="ismembc &#8211; undocumented helper function">ismembc &#8211; undocumented helper function </a> <small>Matlab has several undocumented internal helper functions that can be useful on their own in some cases. This post presents the ismembc function....</small></li>
</ol>
</div>
]]></description>
										<content:encoded><![CDATA[<p>Matlab&#8217;s built-in XML-processing functions have several undocumented features that can be used by Java-savvy users. We should note that the entire XML-support functionality in Matlab is java-based. I understand that some Matlab users have a general aversion to Java, some even going as far as to disable it using the -nojvm startup option. But if you disable Java, Matlab&#8217;s XML functions will simply not work. Matlab&#8217;s own <a target="_blank" rel="nofollow" href="http://www.mathworks.com/access/helpdesk/help/techdoc/ref/xmlread.html">documentation</a> points users to Sun&#8217;s official Java website for explanations of how to use the XML functionality (the link in the Matlab docpage is dead &#8211; the correct link should probably be <a target="_blank" rel="nofollow" href="https://jaxp-sources.dev.java.net/nonav/docs/api/">https://jaxp-sources.dev.java.net/nonav/docs/api/</a>, but Sun keeps changing its website so this link could also be dead soon&#8230;).<br />
Using the full Java XML parsing (<a target="_blank" rel="nofollow" href="https://jaxp.dev.java.net/">JAXP</a>) functionality is admittedly quite intimidating for the uninitiated, but extremely powerful once you understand how all the pieces fit together. Over the years, several interesting utilities were submitted to the Matlab File Exchange that simplify this intimidating post-processing. See for example <a target="_blank" rel="nofollow" href="http://www.mathworks.com/matlabcentral/fileexchange/3074-xml-parsing-tools">XML parsing tools</a>, the extremely popular <a target="_blank" rel="nofollow" href="http://www.mathworks.com/matlabcentral/fileexchange/4278-xml-toolbox">XML Toolbox</a> and <a target="_blank" rel="nofollow" href="http://www.mathworks.com/matlabcentral/fileexchange/12907-xmliotools">xml_io_tools</a>, the recent <a target="_blank" rel="nofollow" href="http://www.mathworks.com/matlabcentral/fileexchange/18253-xml-data-import">XML data import</a> and perhaps a dozen other utilities.<br />
Each of Matlab&#8217;s main built-in XML-processing functions, <b><i>xmlread</i></b>, <b><i>xmlwrite</i></b> and <b><i>xslt</i></b> has an internal set of undocumented and unsupported functionalities, which builds on their internal Java implementation. As far as I could tell, these unsupported functionalities were supported at least as early as Matlab 7.2 (R2006a), and possibly even on earlier releases. For the benefit of the Java and/or JAXP -speakers out there (it will probably not help any others), I list Matlab&#8217;s internal description of these unsupported functionalities, annotated with API hyperlinks. These description (sans the links) can be seen by simply editing the m file, as in (the R2008a variant is described below):</p>
<pre lang="matlab">edit xmlread</pre>
<h3><i>xmlread</i></h3>
<p></p>
<pre lang="matlab">function [parseResult,p] = xmlread(fileName,varargin)</pre>
<ul>
<li>FILENAME can also be an <a target="_blank" rel="nofollow" href="https://jaxp-sources.dev.java.net/nonav/docs/api/org/xml/sax/InputSource.html">InputSource</a>, <a target="_blank" rel="nofollow" href="http://java.sun.com/javase/6/docs/api/java/io/File.html">File</a>, or <a target="_blank" rel="nofollow" href="http://java.sun.com/javase/6/docs/api/java/io/InputStream.html">InputStream</a> object
</li>
<li>DOMNODE = XMLREAD(FILENAME,&#8230;,P,&#8230;) where P is a <a target="_blank" rel="nofollow" href="http://java.sun.com/javase/6/docs/api/javax/xml/parsers/DocumentBuilder.html">DocumentBuilder</a> object
</li>
<li>DOMNODE = XMLREAD(FILENAME,&#8230;,&#8217;-validating&#8217;,&#8230;) will create a validating parser if one was not provided.
</li>
<li>DOMNODE = XMLREAD(FILENAME,&#8230;,ER,&#8230;) where ER is an <a target="_blank" rel="nofollow" href="https://jaxp-sources.dev.java.net/nonav/docs/api/org/xml/sax/EntityResolver.html">EntityResolver</a> will set the EntityResolver before parsing
</li>
<li>DOMNODE = XMLREAD(FILENAME,&#8230;,EH,&#8230;) where EH is an <a target="_blank" rel="nofollow" href="https://jaxp-sources.dev.java.net/nonav/docs/api/org/xml/sax/ErrorHandler.html">ErrorHandler</a> will set the ErrorHandler before parsing
</li>
<li>[DOMNODE,P] = XMLREAD(FILENAME,&#8230;) will return a parser suitable for passing back to XMLREAD for future parses.
</li>
</ul>
<h3><i>xmlwrite</i></h3>
<p></p>
<pre lang="matlab">
function xmlwrite(FILENAME,DOMNODE);
function str = xmlwrite(DOMNODE);
function str = xmlwrite(SOURCE);
</pre>
<ul>
<li>FILENAME can also be a <a target="_blank" rel="nofollow" href="http://en.wikipedia.org/wiki/Uniform_Resource_Name">URN</a>, <a target="_blank" rel="nofollow" href="http://java.sun.com/javase/6/docs/api/java/io/OutputStream.html">java.io.OutputStream</a> or <a target="_blank" rel="nofollow" href="http://java.sun.com/javase/6/docs/api/java/io/Writer.html">java.io.Writer</a> object
</li>
<li>SOURCE can also be a SAX <a target="_blank" rel="nofollow" href="https://jaxp-sources.dev.java.net/nonav/docs/api/org/xml/sax/InputSource.html">InputSource</a>, <a target="_blank" rel="nofollow" href="https://jaxp-sources.dev.java.net/nonav/docs/api/javax/xml/transform/Source.html">JAXP Source</a>, <a target="_blank" rel="nofollow" href="http://java.sun.com/javase/6/docs/api/java/io/InputStream.html">InputStream</a>, or <a target="_blank" rel="nofollow" href="http://java.sun.com/javase/6/docs/api/java/io/Reader.html">Reader</a> object</li>
</ul>
<h3><i>xslt</i></h3>
<p></p>
<pre lang="matlab">function [xResultURI,xProcessor] = xslt(SOURCE,STYLE,DEST,varargin)</pre>
<ul>
<li>SOURCE can also be a <a target="_blank" rel="nofollow" href="http://xerces.apache.org/xerces2-j/javadocs/xni/org/apache/xerces/xni/parser/XMLInputSource.html">XSLTInputSource</a>
</li>
<li>STYLE can also be a StylesheetRoot or XSLTInputSource
</li>
<li>DEST can also be an XSLTResultTarget.  Note that RESULT may be empty in this case since it may not be possible to determine a URL. If STYLE is absent or empty, the function uses the stylesheet named in the xml-stylesheet processing instruction in the SOURCE XML file.  (This does not always work)
</li>
<li>There is also an entirely undocumented feature: passing a &#8216;-tostring&#8217; input argument transforms the inputs into a displayed text segment, rather than into a displayed URI; the transformed text is returned in the xResultURI output argument.</li>
</ul>
<p>Note: internal comments within the Matlab code seem to indicate that XSLT is <a target="_blank" rel="nofollow" href="http://saxon.sourceforge.net/">SAXON</a>-based, so interested users might use SAXON&#8217;s documentation for accessing additional XSLT-related features/capabilities (also see <a href="https://www.mathworks.com/matlabcentral/answers/264420-why-does-matlab-still-use-the-saxon-6-5-5-xslt-and-xquery-processor-when-saxon9-jar-has-already-been" rel="nofollow" target="_blank">this related thread</a>).</p>
<p>The post <a rel="nofollow" href="https://undocumentedmatlab.com/articles/undocumented-xml-functionality">Undocumented XML functionality</a> appeared first on <a rel="nofollow" href="https://undocumentedmatlab.com">Undocumented Matlab</a>.</p>
<div class='yarpp-related-rss'>
<h3>Related posts:</h3><ol>
<li><a href="https://undocumentedmatlab.com/articles/parsing-xml-strings" rel="bookmark" title="Parsing XML strings">Parsing XML strings </a> <small>Matlab's xmlread function cannot process XML data directly, but this can easily be overcome. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/hidden-hg2-plot-functionality" rel="bookmark" title="Accessing hidden HG2 plot functionality">Accessing hidden HG2 plot functionality </a> <small>In HG2, some of the plot functionality is hidden in undocumented properties. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/xlsread-functionality-change-in-r2012a" rel="bookmark" title="xlsread functionality change in R2012a">xlsread functionality change in R2012a </a> <small>The functionality of the xlsread function has changed without documentation or warning in the R2012a release. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/ismembc-undocumented-helper-function" rel="bookmark" title="ismembc &#8211; undocumented helper function">ismembc &#8211; undocumented helper function </a> <small>Matlab has several undocumented internal helper functions that can be useful on their own in some cases. This post presents the ismembc function....</small></li>
</ol>
</div>
]]></content:encoded>
					
					<wfw:commentRss>https://undocumentedmatlab.com/articles/undocumented-xml-functionality/feed</wfw:commentRss>
			<slash:comments>6</slash:comments>
		
		
			</item>
		<item>
		<title>Legend &#039;-DynamicLegend&#039; semi-documented feature</title>
		<link>https://undocumentedmatlab.com/articles/legend-semi-documented-feature?utm_source=rss&#038;utm_medium=rss&#038;utm_campaign=legend-semi-documented-feature</link>
					<comments>https://undocumentedmatlab.com/articles/legend-semi-documented-feature#comments</comments>
		
		<dc:creator><![CDATA[Yair Altman]]></dc:creator>
		<pubDate>Thu, 04 Jun 2009 23:00:22 +0000</pubDate>
				<category><![CDATA[GUI]]></category>
		<category><![CDATA[Listeners]]></category>
		<category><![CDATA[Medium risk of breaking in future versions]]></category>
		<category><![CDATA[Semi-documented feature]]></category>
		<category><![CDATA[Stock Matlab function]]></category>
		<category><![CDATA[Listener]]></category>
		<category><![CDATA[Pure Matlab]]></category>
		<category><![CDATA[scribe]]></category>
		<guid isPermaLink="false">http://undocumentedmatlab.com/?p=357</guid>

					<description><![CDATA[<p>The built-in Matlab legend function has a very useful semi-documented feature for automatic dynamic update, which is explained here.</p>
<p>The post <a rel="nofollow" href="https://undocumentedmatlab.com/articles/legend-semi-documented-feature">Legend &#039;-DynamicLegend&#039; semi-documented feature</a> appeared first on <a rel="nofollow" href="https://undocumentedmatlab.com">Undocumented Matlab</a>.</p>
<div class='yarpp-related-rss'>
<h3>Related posts:</h3><ol>
<li><a href="https://undocumentedmatlab.com/articles/multi-column-grid-legend" rel="bookmark" title="Multi-column (grid) legend">Multi-column (grid) legend </a> <small>This article explains how to use undocumented axes listeners for implementing multi-column plot legends...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/transparent-legend" rel="bookmark" title="Transparent legend">Transparent legend </a> <small>Matlab chart legends are opaque be default but can be made semi- or fully transparent. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/plot-legend-title" rel="bookmark" title="Plot legend title">Plot legend title </a> <small>Titles to plot legends are easy to achieve in HG1 (R2014a or earlier), but much more difficult in HG2 (R2014b or newer). ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/plot-legend-customization" rel="bookmark" title="Plot legend customization">Plot legend customization </a> <small>Matlab plot legends and their internal components can be customized using a variety of undocumented properties that are easily accessible. ...</small></li>
</ol>
</div>
]]></description>
										<content:encoded><![CDATA[<p>In one of my projects, I had to build a GUI in which users could interactively add and remove plot lines from an axes. The problem was that the legend needed to be kept in constant sync with the currently-displayed plot lines. This can of course be done programmatically, but a much simpler solution was to use <em><strong>legend</strong></em>&#8216;s semi-documented &#8216;-DynamicLegend&#8217; feature. Here&#8217;s a simple example:</p>
<blockquote>
<pre lang="matlab">
x=0:.01:10;
plot(x, sin(x), 'DisplayName','sin');
legend('-DynamicLegend');
hold all;   % add new plot lines on top of previous ones
plot(x, cos(x), 'DisplayName','cos');
</pre>
</blockquote>
<p>We can see how the dynamic legend automatically keeps in sync with its associated axes contents when plot lines are added/removed, even down to the zoom-box lines&#8230; The legend automatically uses the plot lines &#8216;DisplayName&#8217; property where available, or a standard &#8216;line#&#8217; nametag where not available:<br />
<center><br />
<figure style="width: 300px" class="wp-caption aligncenter"><img fetchpriority="high" decoding="async" alt="Dynamic legend" src="https://undocumentedmatlab.com/images/legend_animated.gif" title="Dynamic legend" width="300" height="308" /><figcaption class="wp-caption-text">Dynamic legend</figcaption></figure></center><br />
DynamicLegend works by attaching a listener to the axes child addition/deletion callback (actually, it works on the scribe object, which is a large topic for several future posts). It is sometimes necessary to selectively disable the dynamic behavior. For example, in my GUI I needed to plot several event lines which looked alike, and so I only wanted the first line to be added to the legend. To temporarily disable the DynamicLegend listener, do the following:</p>
<blockquote>
<pre lang="matlab">
% Try to disable this axes's legend plot-addition listener
legendAxListener = [];
try
   legendListeners = get(gca,'ScribeLegendListeners');
   legendAxListener = legendListeners.childadded;
   set(legendAxListener,'Enable','off');
catch
   % never mind...
end
% Update the axes - the legend will not be updated
...
% Re-enable the dynamic legend listener
set(legendAxListener,'Enable','on');
</pre>
</blockquote>
<p>Unfortunately, this otherwise-useful DynamicLegend feature throws errors when zooming-in on <em><strong>bar</strong></em> or <em><strong>stairs</strong></em> graphs. This can be replicated by:</p>
<blockquote>
<pre lang="matlab">
figure;
bar(magic(4));  %or: stairs(magic(3),magic(3));
legend('-DynamicLegend');
zoom on;
% Now zoom-in using the mouse to get the errors on the Command Window
</pre>
</blockquote>
<p>The fix: modify %MATLABROOT%\toolbox\matlab\scribe\@scribe\@legend\init.m line #528 as follows:</p>
<blockquote>
<pre lang="matlab">
%old:
str = [str(1:insertindex-1);{newstr};str(insertindex:length(str))];
%new:
if size(str,2)>size(str,1)
    str=[str(1:insertindex-1),{newstr},str(insertindex:length(str))];
else
    str=[str(1:insertindex-1);{newstr};str(insertindex:length(str))];
end
</pre>
</blockquote>
<p>The origin of the bug is that <em><strong>bar</strong></em> and <em><strong>stairs</strong></em> generate <em><strong>hggroup</strong></em> plot-children, which saves the legend strings column-wise rather than the expected row-wise. My fix solves this, but I do not presume this solves all possible problems in all scenarios (please report if you find anything else).<br />
p.s. &#8211; object visibility in the legend can be controlled on an object-by-object basis using the semi-documented <a target="_blank" href="/articles/handle-graphics-behavior#hasbehavior"><i><b>hasbehavior</b></i> function</a>.</p>
<h3 id="Semi-documented">Semi-documented</h3>
<p>The DynamicLegend feature is semi-documented. This means that the feature is explained in a comment within the function (which can be seen via the <strong><em>edit</em></strong>(<span style="color: rgb(160, 32, 240);">&#8216;legend&#8217;</span>) command), that is nonetheless not part of the official help or doc sections. It is an unsupported feature originally intended only for internal Matlab use (which of course doesn&#8217;t mean we can&#8217;t use it). This feature has existed many releases back (Matlab 7.1 for sure, perhaps earlier), so while it may be discontinued in some future Matlab release, it did have a very long life span&#8230; The down side is that it is not supported: I reported the bar/stairs issue back in mid-2007 and so far this has not been addressed (perhaps it will never be). Even my reported workaround in January this year went unanswered (no hard feelings&#8230;).<br />
DynamicLegend is a good example of a useful semi-documented feature. Some other examples, which I may cover in future posts, include <strong><em>text</em></strong>(&#8230;,<span style="color: rgb(160, 32, 240);">&#8216;sc&#8217;</span>), <strong><em>drawnow</em></strong>(<span style="color: rgb(160, 32, 240);">&#8216;discard&#8217;</span>), several options in <strong><em>pan</em></strong> and <strong><em>datacursormode</em></strong> etc. etc.<br />
There are also entire semi-documented functions: many of the uitools (e.g., <strong><em>uitree</em></strong>, <strong><em>uiundo</em></strong>), as well as <strong><em>hgfeval</em></strong> and others.<br />
Have you discovered any useful semi-documented feature or function? If so, then please share your finding in the comments section below.</p>
<p>The post <a rel="nofollow" href="https://undocumentedmatlab.com/articles/legend-semi-documented-feature">Legend &#039;-DynamicLegend&#039; semi-documented feature</a> appeared first on <a rel="nofollow" href="https://undocumentedmatlab.com">Undocumented Matlab</a>.</p>
<div class='yarpp-related-rss'>
<h3>Related posts:</h3><ol>
<li><a href="https://undocumentedmatlab.com/articles/multi-column-grid-legend" rel="bookmark" title="Multi-column (grid) legend">Multi-column (grid) legend </a> <small>This article explains how to use undocumented axes listeners for implementing multi-column plot legends...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/transparent-legend" rel="bookmark" title="Transparent legend">Transparent legend </a> <small>Matlab chart legends are opaque be default but can be made semi- or fully transparent. ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/plot-legend-title" rel="bookmark" title="Plot legend title">Plot legend title </a> <small>Titles to plot legends are easy to achieve in HG1 (R2014a or earlier), but much more difficult in HG2 (R2014b or newer). ...</small></li>
<li><a href="https://undocumentedmatlab.com/articles/plot-legend-customization" rel="bookmark" title="Plot legend customization">Plot legend customization </a> <small>Matlab plot legends and their internal components can be customized using a variety of undocumented properties that are easily accessible. ...</small></li>
</ol>
</div>
]]></content:encoded>
					
					<wfw:commentRss>https://undocumentedmatlab.com/articles/legend-semi-documented-feature/feed</wfw:commentRss>
			<slash:comments>21</slash:comments>
		
		
			</item>
	</channel>
</rss>
