Skip to content

Commit 722625a

Browse files
Dev-iLDev-iL
committed
Updated README.md
- Added a "shield" indicating the required MATLAB versions. - Reordered methods lexicographically. - Added link for `aboutDojo`. - Added explanation and usage example for `getHTML` and `getWidgetInfo`. - `fontWeight`- Clarified when this method has an effect; mentioned that `'lighter'` is also accepted. - Removed some of the internal documentation in `mlapptools.m`.
1 parent 33c410b commit 722625a

File tree

2 files changed

+113
-46
lines changed

2 files changed

+113
-46
lines changed

‎README.md‎

Lines changed: 108 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,92 @@
1+
![Minimum Version](https://img.shields.io/badge/Requires-R2016a%20%28v9.0%29%20or%20newer-orange.svg)
2+
13
# mlapptools
2-
`mlapptools` is an example set of static MATLAB methods for manipulating the DOM underlying the App Designer UI elements formally introduced in R2016a.
4+
`mlapptools` is a collection of static methods for customizing the R2016a-introduced web-based `uifigure` windows and
5+
associated UI elements through DOM manipulations.
6+
7+
For additional information, see Iliya Romm's Undocumented Matlab guest article,
8+
[*Customizing uifigures part 2*](http://undocumentedmatlab.com/blog/customizing-uifigures-part-2),
9+
published Wednesday, September 7th, 2016.
10+
11+
#### Contact us
12+
- Feature requests/suggestions and bug repots - please feel free to
13+
[open an issue](https://github.com/StackOverflowMATLABchat/mlapptools/issues) in the repository.
14+
- General discussion - [_MATLAB and Octave_ chatroom on Stack Overflow](https://chat.stackoverflow.com/rooms/81987/).
15+
- Specific questions about manipulating uifigures / App Designer apps -
16+
[`matlab-app-designer` tag on Stack Overflow](https://stackoverflow.com/questions/tagged/matlab-app-designer).
17+
18+
## Methods
19+
[`aboutDojo`](#aboutDojo) - Return the Dojo toolkit version.
20+
[`fontColor`](#fontColor) - Modify font color.
21+
[`fontWeight`](#fontWeight) - Modify font weight.
22+
[`getHTML`](#getHTML) - Return the full HTML code of a `uifigure`.
23+
[`getWidgetInfo`](#getWidgetInfo) - Get a list of widgets from the dijit registry.
24+
[`setStyle`](#setStyle) - Modify a specified style property.
25+
[`textAlign`](#textAlign) - Modify text alignment.
26+
27+
<a name="aboutDojo"></a>
28+
#### *mlapptools*.**aboutDojo**()
29+
##### Description
30+
Returns a `struct` containing version information about the Dojo toolkit loaded into the first open `uifigure`.
31+
If no `uifigure` is open, a temporary window is created, queried, then closed - indicating the default Dojo version.
332

4-
For additional information, see Iliya Romm's Undocumented Matlab guest article, [*Customizing uifigures part 2*](http://undocumentedmatlab.com/blog/customizing-uifigures-part-2), published Wednesday, September 7th, 2016.
33+
##### Examples
534

6-
## Methods
7-
[`textAlign`](#textAlign) - Modify text alignment
8-
[`fontWeight`](#fontWeight) - Modify font weight
9-
[`fontColor`](#fontColor) - Modify font folor
10-
[`setStyle`](#setStyle) - Modify a specified style property
11-
`aboutDojo` - Return version information about the Dojo toolkit.
35+
```matlab
36+
>> mlapptools.aboutDojo()
1237
13-
<a name="textAlign"></a>
14-
#### *mlapptools*.**textAlign**(*uielement*, *alignment*)
38+
ans =
39+
40+
struct with fields:
41+
42+
major: 1
43+
minor: 11
44+
patch: 2
45+
flag: ''
46+
revision: '91fa0cb'
47+
```
48+
49+
<a name="fontColor"></a>
50+
#### *mlapptools*.**fontColor**(*uielement*, *newcolor*)
1551
##### Description
16-
Set the horizontal text alignment of the specified UI element, `uielement`, to that specified by the input alignment string, `alignment`.
52+
Set the font color of the specified UI element, `'uielement'`, to the input color, `newcolor`. `newcolor` can be a
53+
predefined color string or a string containing a valid CSS color method call.
1754

18-
Valid alignment strings are:
19-
* `'left'` - Left align (default)
20-
* `'center'` - Center align
21-
* `'right'` - Right align
22-
* `'justify'` - Each line has equal width
23-
* `'initial'` - Revert to default
55+
Valid color specifications are:
56+
* Hexadecimal colors - e.g. `'#ff0000'` for red
57+
* RGB colors - e.g. `'rgb(255,165,0)'` for orange
58+
* RGBA colors - e.g. `'rgba(255,255,0,0.3)'` for yellow
59+
* HSL colors - e.g. `'hsl(120, 100%, 50%)'` for green
60+
* HSLA colors - e.g. `'hsla(240,100%,50%, 1.0)'` for blue
61+
* Predefined color names - e.g. `'red'`, `'orange'`, `'yellow'`, `'green'`, `'blue'`, `'indigo'`, `'violet'`.
62+
For more colors, see the predefined color names [CSS color specification](https://www.w3.org/TR/css3-color/).
2463

2564
##### Examples
2665
Using the demo GUI generated by `./Demo/DOMdemoGUI.m`
2766

2867
```MATLAB
2968
myGUI = DOMdemoGUI;
30-
mlapptools.textAlign(myGUI.TextArea, 'center');
69+
mlapptools.fontColor(myGUI.TextArea, 'aqua');
3170
```
3271

3372
```MATLAB
3473
myGUI = DOMdemoGUI;
35-
mlapptools.textAlign(myGUI.TextArea, 'right');
74+
mlapptools.fontColor(myGUI.TextArea, 'rgb(255,165,0)');
3675
```
3776

77+
3878
<a name="fontWeight"></a>
3979
#### *mlapptools*.**fontWeight**(*uielement*, *weight*)
4080
##### Description
4181
Set the font weight of the specified UI element, `uielement`, to the input weight string or integer, `weight`.
82+
For this setting to have an effect, the font being used must have built-in faces that match the specified weight.
4283

4384
Valid font weight property values are:
4485
* `'normal'` - Normal characters (default)
4586
* `'bold'` - Thick characters
46-
* `'bolder'` - Thicker characters
47-
* `[400, 600, 800]` - Integers mapping to `'normal'`, `'bold'`, and `'bolder'`. Intermediate integers (and floats) are accepted but generally map to these 3 values
87+
* `'lighter'` / `'bolder'` - The closest available "lighter" or "bolder" weight, relative to the parent.
88+
* `100 .. 900` - Integers mapping to `'normal'`, `'bold'`, etc.
89+
Intermediate integers (and floats) are accepted but generally map to the available values
4890
* `'initial'` - Revert to default
4991

5092
##### Examples
@@ -60,38 +102,41 @@ myGUI = DOMdemoGUI;
60102
mlapptools.fontWeight(myGUI.TextArea, 600);
61103
```
62104

63-
<a name="fontColor"></a>
64-
#### *mlapptools*.**fontColor**(*uielement*, *newcolor*)
65-
##### Description
66-
Set the font color of the specified UI element, `'uielement'`, to the input color, `newcolor`. `newcolor` can be a predefined color string or a string containing a valid CSS color method call.
67105

68-
Valid color specifications are:
69-
* Hexadecimal colors - e.g. `'#ff0000'` for red
70-
* RGB colors - e.g. `'rgb(255,165,0)'` for orange
71-
* RGBA colors - e.g. `'rgba(255,255,0,0.3)'` for yellow
72-
* HSL colors - e.g. `'hsl(120, 100%, 50%)'` for green
73-
* HSLA colors - e.g. `'hsla(240,100%,50%, 1.0)'` for blue
74-
* Predefined color names - e.g. `'red'`, `'orange'`, `'yellow'`, `'green'`, `'blue'`, `'indigo'`, `'violet'`. For more colors, see the predefined color names [CSS color specification](https://www.w3.org/TR/css3-color/).
106+
<a name="getHTML"></a>
107+
#### *mlapptools*.**getHTML**(*hUIFigure*)
108+
##### Description
109+
A method for obtaining the HTML code of a uifigure. Intended for R2017b (and onward?) where the CEF URL cannot be
110+
simply opened in a browser.
75111

76112
##### Examples
77113
Using the demo GUI generated by `./Demo/DOMdemoGUI.m`
78-
79114
```MATLAB
80115
myGUI = DOMdemoGUI;
81-
mlapptools.fontColor(myGUI.TextArea, 'aqua');
116+
wList = mlapptools.getWidgetInfo(myGUI.UIFigure);
82117
```
83118

119+
<a name="getWidgetInfo"></a>
120+
#### *mlapptools*.**getWidgetInfo**(*hUIFigure*, *verbosityFlag*)
121+
##### Description
122+
Query the [dijit registry](https://dojotoolkit.org/reference-guide/dijit/registry.html#dijit-registry) for all widgets
123+
within the current page, and return them in a cell array of structs.
124+
125+
##### Examples
126+
Using the demo GUI generated by `./Demo/DOMdemoGUI.m`
84127
```MATLAB
85128
myGUI = DOMdemoGUI;
86-
mlapptools.fontColor(myGUI.TextArea, 'rgb(255,165,0)');
129+
wList = mlapptools.getWidgetInfo(myGUI.UIFigure);
87130
```
88131

89132
<a name="setStyle"></a>
90133
#### *mlapptools*.**setStyle**(*uielement*, *styleAttr*, *styleValue*)
91134
##### Description
92-
Set the style attribute `styleAttr` of the specified UI element, `'uielement'`, to the value `styleValue`. `styleAttr` should be any valid CSS attribute, and `styleValue` a valid setting thereof.
135+
Set the style attribute `styleAttr` of the specified UI element, `'uielement'`, to the value `styleValue`. `styleAttr`
136+
should be any valid CSS attribute, and `styleValue` a valid setting thereof.
93137

94-
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.
138+
This method provides a general interface to change CSS style attributes, with minimal input testing and error reporting,
139+
so it is up to the user to provide valid inputs.
95140

96141
Valid style attributes and corresponding settings can be found [here](https://www.w3schools.com/cssref/).
97142

@@ -101,4 +146,30 @@ Using the demo GUI generated by `./Demo/DOMdemoGUI.m`
101146
myGUI = DOMdemoGUI;
102147
mlapptools.setStyle(myGUI.TextArea, 'background-image',...
103148
'url(https://upload.wikimedia.org/wikipedia/commons/8/80/Wikipedia-logo-v2.svg)');
149+
```
150+
151+
152+
<a name="textAlign"></a>
153+
#### *mlapptools*.**textAlign**(*uielement*, *alignment*)
154+
##### Description
155+
Set the horizontal text alignment of the specified UI element, `uielement`, to that specified by the input alignment string, `alignment`.
156+
157+
Valid alignment strings are:
158+
* `'left'` - Left align (default)
159+
* `'center'` - Center align
160+
* `'right'` - Right align
161+
* `'justify'` - Each line has equal width
162+
* `'initial'` - Revert to default
163+
164+
##### Examples
165+
Using the demo GUI generated by `./Demo/DOMdemoGUI.m`
166+
167+
```MATLAB
168+
myGUI = DOMdemoGUI;
169+
mlapptools.textAlign(myGUI.TextArea, 'center');
170+
```
171+
172+
```MATLAB
173+
myGUI = DOMdemoGUI;
174+
mlapptools.textAlign(myGUI.TextArea, 'right');
104175
```

‎mlapptools.m‎

Lines changed: 5 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,10 @@
11
classdef (Abstract) mlapptools
2-
% MLAPPTOOLS A collection of static methods for customizing various aspects
3-
% MATLAB App Designer UIFigures.
2+
% MLAPPTOOLS is a collection of static methods for customizing the
3+
% R2016a-introduced web-based uifigure windows and associated UI elements
4+
% through DOM manipulations.
45
%
5-
% MLAPPTOOLS methods:
6-
% textAlign - utility method for modifying text alignment.
7-
% fontWeight - utility method for modifying font weight (bold etc.).
8-
% fontColor - utility method for modifying font color.
9-
% setStyle - utility method for modifying styles that do not (yet) have a
10-
% dedicated mutator.
11-
% aboutDojo - returns version information about the Dojo toolkit.
6+
% See README.md for detailed documentation and examples.
7+
128

139
properties (Access = private, Constant = true)
1410
QUERY_TIMEOUT = 5; % Dojo query timeout period, seconds

0 commit comments

Comments
 (0)