Skip to content

MATLAB class containing methods for programmatic uifigure modification

License

Notifications You must be signed in to change notification settings

Dev-iL/mlapptools

 
 

Repository files navigation

Minimum Version

mlapptools

mlapptools is a collection of static methods for customizing the R2016a-introduced web-based uifigure windows and associated UI elements through DOM manipulations.

For additional information, see Iliya Romm's Undocumented Matlab guest article, Customizing uifigures part 2, published Wednesday, September 7th, 2016.

Contact us

Methods

aboutJSLibs - Return the loaded versions of Dojo and React.
addClasses - Add specified CSS classes to one or more DOM nodes.
addToHead - Inject inline CSS or JS into the <head> section of the figure's HTML.
fontColor - Modify font color.
fontWeight - Modify font weight.
getChildNodeIDs - Get all children DOM nodes of a specified node.
getHTML - Return the full HTML code of a uifigure.
getParentNodeID - Get parent DOM node of a specified node.
getWebElements - Extract a webwindow handle and a widget ID from a uifigure control handle.
getWebWindow - Extract a webwindow handle from a uifigure handle.
getWidgetInfo - Gather information about a specific dijit widget.
getWidgetList - Gather information about all dijit widget in a specified uifigure.
setStyle - Modify a specified style property.
setTimeout - Override the default timeout for dojo commands, for a specific uifigure.
textAlign - Modify text alignment.
unlockUIFig - Modify this UIFigure to allow viewing it in an external browser, on release R2017b and newer.
waitForFigureReady - A blocking method that only returns after the uifigure is fully loaded.


mlapptools.aboutJSLibs()

Description

Returns a struct containing information about the Dojo toolkit and ReactJS versions loaded into the first open uifigure. If no uifigure is open, a temporary window is created, queried, then closed - indicating the default versions.

Examples
>> mlapptools.aboutJSLibs()

ans =

  struct with fields:

    dojo: '1.11.2.91fa0cb'
    react_js: '0.14.7'

mlapptools.addClasses(hUIElement, cssClasses)

Description

Adds the specified CSS class (if char vector) or classes (if cell array of char vectors) to a UI element.

Examples

Using the demo GUI generated by ./Demo/DOMdemoGUI.m

% Create a figure:
hFig = DOMdemoGUI;

% Get a handle to the webwindow and the TextArea:
[hWin, widgetID] = mlapptools.getWebElements(hFig.TextArea);

% Define inline CSS animation and add it to the figure HTML:
cssText = ['"<style>'...
    '@-webkit-keyframes mymove {50% {background-color: blue;}}'...
    '@keyframes mymove {50% {background-color: blue;}}</style>"'];
mlapptools.addToHead(hWin, cssText);

% Activate animation on control:
mlapptools.setStyle(hWin, '-webkit-animation', 'mymove 5s infinite', widgetID);

Another example is available in the blog post "Customizing web-GUI uipanel" by Khris Griffis.


mlapptools.addToHead(hWin, cssText)

Description

A method for adding inline CSS to the HTML <head> section.
See also: stringify.m.

Examples

See example for addClasses.


mlapptools.fontColor(hUIElement, color)

Description

Set the font color of the specified UI element, 'hUIElement', to the input color, color. color can be a predefined color string or a string containing a valid CSS color method call.

Valid color specifications are:

  • Hexadecimal colors - e.g. '#ff0000' for red
  • RGB colors - e.g. 'rgb(255,165,0)' for orange
  • RGBA colors - e.g. 'rgba(255,255,0,0.3)' for yellow
  • HSL colors - e.g. 'hsl(120, 100%, 50%)' for green
  • HSLA colors - e.g. 'hsla(240,100%,50%, 1.0)' for blue
  • Predefined color names - e.g. 'red', 'orange', 'yellow', 'green', 'blue', 'indigo', 'violet'. For more colors, see the predefined color names CSS color specification.
Examples

Using the demo GUI generated by ./Demo/DOMdemoGUI.m

myGUI = DOMdemoGUI;
mlapptools.fontColor(myGUI.TextArea, 'aqua');
myGUI = DOMdemoGUI;
mlapptools.fontColor(myGUI.TextArea, 'rgb(255,165,0)');

mlapptools.fontWeight(hUIElement, weight)

Description

Set the font weight of the specified UI element, hUIElement, to the input weight string or integer, weight. For this setting to have an effect, the font being used must have built-in faces that match the specified weight.

Valid font weight property values are:

  • 'normal' - Normal characters (default)
  • 'bold' - Thick characters
  • 'lighter' / 'bolder' - The closest available "lighter" or "bolder" weight, relative to the parent.
  • 100 .. 900 - Integers mapping to 'normal', 'bold', etc. Intermediate integers (and floats) are accepted but generally map to the available values
  • 'initial' - Revert to default
Examples

Using the demo GUI generated by ./Demo/DOMdemoGUI.m

myGUI = DOMdemoGUI;
mlapptools.fontWeight(myGUI.TextArea, 'bold');
myGUI = DOMdemoGUI;
mlapptools.fontWeight(myGUI.TextArea, 600);

mlapptools.getChildNodeIDs(hWin,widgetID)

Description

A method for getting all children nodes (commonly <div> elements) of a specified node. Returns a WidgetID vector.

Examples
hTG = uitabgroup(uifigure());
uitab(hTG);
[hWin, widgetID] = mlapptools.getWebElements(hTG);
[childIDs] = mlapptools.getChildNodeIDs(hWin, widgetID);
mlapptools.setStyle(hWin,'background','blue',childIDs(2));
[childIDs] = mlapptools.getChildNodeIDs(hWin, childIDs(2));
mlapptools.setStyle(hWin,'background','green',childIDs(4));

mlapptools.getHTML(hUIFigure)

Description

A method for obtaining the HTML code of a uifigure. Intended for R2017b (and onward?) where the CEF URL cannot be simply opened in a browser. The returned HTML is a deep copy, meaning that any changes will not modify the uifigure where it originated from.

Examples

Using the demo GUI generated by ./Demo/DOMdemoGUI.m

myGUI = DOMdemoGUI;
fullHTML = mlapptools.getHTML(myGUI.UIFigure);
web(['text://' fullHTML]);

mlapptools.getParentNodeID(hWin,widgetID)

Description

A method for getting the parent node (commonly <div> element) of a specified node. Returns a WidgetID scalar.

Examples

Using the demo GUI generated by ./Demo/DOMdemoGUI.m

tg = uitabgroup(uifigure());
[hWin, widgetID] = mlapptools.getWebElements(tg);
mlapptools.setStyle(hWin,'background','linear-gradient(red, pink, white)',...
  mlapptools.getParentNodeID(hWin, widgetID));

mlapptools.getWebElements(hUIElement)

Description

A method for obtaining the webwindow handle and the widget ID corresponding to the provided uifigure control. The widget ID can be used to call the 4-parameter variant of setStyle.

Examples
myGUI = DOMdemoGUI;
[hWin, widgetID] = mlapptools.getWebElements(myGUI.TextArea);

mlapptools.getWebWindow(hUIFigure)

Description

A method for getting the webwindow handle associated with the provided uifigure.

Examples

Using the demo GUI generated by ./Demo/DOMdemoGUI.m

myGUI = DOMdemoGUI;
hWin = mlapptools.getWebWindow(myGUI.UIFigure);

mlapptools.getWidgetInfo(hWin, widgetID, verbosityFlag)

Description

Query the dijit registry for a widget having a specific ID, and return its details in a scalar cell containing a struct.

Examples

Using the demo GUI generated by ./Demo/DOMdemoGUI.m

myGUI = DOMdemoGUI;
[hWin, widgetID] = mlapptools.getWebElements(myGUI.TextArea);
nfo = mlapptools.getWidgetInfo(hWin, widgetID);

mlapptools.getWidgetList(hUIFigure, verbosityFlag)

Description

Query the dijit registry for all widgets within the current page, and return them in a cell array of structs.

Examples

Using the demo GUI generated by ./Demo/DOMdemoGUI.m

myGUI = DOMdemoGUI;
nfoList = mlapptools.getWidgetList(myGUI.UIFigure);

mlapptools.setStyle(hUIElement, styleAttr, styleValue)

mlapptools.setStyle(hWin, styleAttr, styleValue, ID_object)

Description

Set the style attribute styleAttr of the specified UI element, 'hUIElement', to the value styleValue. styleAttr should be any valid CSS attribute, and styleValue a valid setting thereof.

This method provides a general interface to change CSS style attributes, with minimal input testing and error reporting, so it is up to the user to provide valid inputs.

Valid style attributes and corresponding settings can be found here.

Examples

Using the demo GUI generated by ./Demo/DOMdemoGUI.m

myGUI = DOMdemoGUI;
mlapptools.setStyle(myGUI.TextArea, 'background-image',...
 'url(https://upload.wikimedia.org/wikipedia/commons/8/80/Wikipedia-logo-v2.svg)');

mlapptools.setTimeout(hUIFig, newTimeoutInSec)

Description

Modify the amount of time allotted to dojo queries before they are considered "failed due to timeout". This value is uifigure-specific. If left unmodified, the default value is 5 seconds.

Examples
myGUI = DOMdemoGUI;
mlapptools.setTimeout(myGUI.UIFigure, 3); % This will wait less for dojo queries to finish.

mlapptools.textAlign(hUIElement, alignment)

Description

Set the horizontal text alignment of the specified UI element, hUIElement, to that specified by the input alignment string, alignment.

Valid alignment strings are:

  • 'left' - Left align (default)
  • 'center' - Center align
  • 'right' - Right align
  • 'justify' - Each line has equal width
  • 'initial' - Revert to default
Examples

Using the demo GUI generated by ./Demo/DOMdemoGUI.m

myGUI = DOMdemoGUI;
mlapptools.textAlign(myGUI.TextArea, 'center');
myGUI = DOMdemoGUI;
mlapptools.textAlign(myGUI.TextArea, 'right');

mlapptools.unlockUIFig(hUIFig)

Description

This method modifies the properties of the UIFigure controller such that opening the UIFigure in a browser (using the webwindow URL) becomes possible. This method has no effect on MATLAB releases before R2017b (where no such restriction exists in the first place).

NOTE: this method works as expected in releases ≤R2018a. In newer releases, the unlocked figure can only be viewed in the built-in web browser using web(hWW.URL,'-new'). This way one can view the source code of the webpage (useful to examine the DOM's hierarchy etc.), but not modify it (by editing the nodes manually or issuing console commands).

Examples

Using the demo GUI generated by ./Demo/DOMdemoGUI.m

% Create a uifigure:
myGUI = DOMdemoGUI;

% Attempt to open it using an external browser:
hWW = mlapptools.getWebWindow(myGUI.UIFigure);
web(hWW.URL,'-browser'); pause(3);

% "Unlock" the uifigure:
mlapptools.unlockUIFig(myGUI.UIFigure);

% Attempt to open again:
web(hWW.URL,'-browser'); % Works on R2016a-R2018a
web(hWW.URL,'-new');     % Works on all releases (probably)

The 1st browser window should be empty, whereas the 2nd should correctly show the contents of the UIFigure.


mlapptools.waitForFigureReady(hUIFig)

Description

This method pauses execution of further commands on the MATLAB thread until the asynchronous loading of the UIFigure and its webwindow has finished. It's good practice to use this method before starting to manipulate the styles of individual elements to avoid null widget reference errors.

About

MATLAB class containing methods for programmatic uifigure modification

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • MATLAB 100.0%