Skip to content

Commit 3bd1037

Browse files
Dev-iLDev-iL
committed
Made getWebElements and getWebWindow public.
+ Added relevant documentation. + Fixed bug related to a capitalization issue in `fontWeight`. + Renamed "uielement" to "uiElement" to better fit conventions. TODO: add unit tests.
1 parent d7ad40d commit 3bd1037

File tree

2 files changed

+106
-72
lines changed

2 files changed

+106
-72
lines changed

‎README.md‎

Lines changed: 42 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,8 @@ published Wednesday, September 7th, 2016.
2020
[`fontColor`](#fontColor) - Modify font color.
2121
[`fontWeight`](#fontWeight) - Modify font weight.
2222
[`getHTML`](#getHTML) - Return the full HTML code of a `uifigure`.
23+
[`getWebElements`](#getWebElements) - Get a webwindow handle and a widget ID from a `uifigure` control handle.
24+
[`getWebWindow`](#getWebWindow) - Extract a `webwindow` handle from a `uifigure` handle.
2325
[`getWidgetInfo`](#getWidgetInfo) - Get a list of widgets from the dijit registry.
2426
[`setStyle`](#setStyle) - Modify a specified style property.
2527
[`textAlign`](#textAlign) - Modify text alignment.
@@ -47,9 +49,9 @@ ans =
4749
```
4850

4951
<a name="fontColor"></a>
50-
#### *mlapptools*.**fontColor**(*uielement*, *newcolor*)
52+
#### *mlapptools*.**fontColor**(*uiElement*, *newcolor*)
5153
##### Description
52-
Set the font color of the specified UI element, `'uielement'`, to the input color, `newcolor`. `newcolor` can be a
54+
Set the font color of the specified UI element, `'uiElement'`, to the input color, `newcolor`. `newcolor` can be a
5355
predefined color string or a string containing a valid CSS color method call.
5456

5557
Valid color specifications are:
@@ -76,9 +78,9 @@ mlapptools.fontColor(myGUI.TextArea, 'rgb(255,165,0)');
7678

7779

7880
<a name="fontWeight"></a>
79-
#### *mlapptools*.**fontWeight**(*uielement*, *weight*)
81+
#### *mlapptools*.**fontWeight**(*uiElement*, *weight*)
8082
##### Description
81-
Set the font weight of the specified UI element, `uielement`, to the input weight string or integer, `weight`.
83+
Set the font weight of the specified UI element, `uiElement`, to the input weight string or integer, `weight`.
8284
For this setting to have an effect, the font being used must have built-in faces that match the specified weight.
8385

8486
Valid font weight property values are:
@@ -107,15 +109,44 @@ mlapptools.fontWeight(myGUI.TextArea, 600);
107109
#### *mlapptools*.**getHTML**(*hUIFigure*)
108110
##### Description
109111
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.
112+
simply opened in a browser. The returned HTML is a deep copy, meaning that any changes will **not** modify the `uifigure`
113+
where it originated from.
111114

112115
##### Examples
113116
Using the demo GUI generated by `./Demo/DOMdemoGUI.m`
114117
```MATLAB
115118
myGUI = DOMdemoGUI;
116-
wList = mlapptools.getWidgetInfo(myGUI.UIFigure);
119+
fullHTML = mlapptools.getHTML(myGUI.UIFigure);
120+
web(['text://' fullHTML]);
121+
```
122+
123+
124+
<a name="getWebElements"></a>
125+
#### *mlapptools*.**getWebElements**(*uiElement*)
126+
##### Description
127+
A method for obtaining the webwindow handle and the widget ID corresponding to the provided `uifigure` control. The
128+
widget ID can be used to call the 4-parameter variant of [`setStyle`](#setStyle).
129+
130+
##### Examples
131+
```MATLAB
132+
myGUI = DOMdemoGUI;
133+
[win, widgetID] = mlapptools.getWebElements(myGUI.TextArea);
134+
```
135+
136+
137+
<a name="getWebWindow"></a>
138+
#### *mlapptools*.**getWebWindow**(*hUIFigure*)
139+
##### Description
140+
A method for getting the webwindow handle associated with the provided `uifigure`.
141+
142+
##### Examples
143+
Using the demo GUI generated by `./Demo/DOMdemoGUI.m`
144+
```MATLAB
145+
myGUI = DOMdemoGUI;
146+
mlapptools.getWebWindow(myGUI.UIFigure);
117147
```
118148

149+
119150
<a name="getWidgetInfo"></a>
120151
#### *mlapptools*.**getWidgetInfo**(*hUIFigure*, *verbosityFlag*)
121152
##### Description
@@ -129,10 +160,11 @@ myGUI = DOMdemoGUI;
129160
wList = mlapptools.getWidgetInfo(myGUI.UIFigure);
130161
```
131162

163+
132164
<a name="setStyle"></a>
133-
#### *mlapptools*.**setStyle**(*uielement*, *styleAttr*, *styleValue*)
165+
#### *mlapptools*.**setStyle**(*uiElement*, *styleAttr*, *styleValue*)
134166
##### Description
135-
Set the style attribute `styleAttr` of the specified UI element, `'uielement'`, to the value `styleValue`. `styleAttr`
167+
Set the style attribute `styleAttr` of the specified UI element, `'uiElement'`, to the value `styleValue`. `styleAttr`
136168
should be any valid CSS attribute, and `styleValue` a valid setting thereof.
137169

138170
This method provides a general interface to change CSS style attributes, with minimal input testing and error reporting,
@@ -150,9 +182,9 @@ mlapptools.setStyle(myGUI.TextArea, 'background-image',...
150182

151183

152184
<a name="textAlign"></a>
153-
#### *mlapptools*.**textAlign**(*uielement*, *alignment*)
185+
#### *mlapptools*.**textAlign**(*uiElement*, *alignment*)
154186
##### Description
155-
Set the horizontal text alignment of the specified UI element, `uielement`, to that specified by the input alignment string, `alignment`.
187+
Set the horizontal text alignment of the specified UI element, `uiElement`, to that specified by the input alignment string, `alignment`.
156188

157189
Valid alignment strings are:
158190
* `'left'` - Left align (default)

‎mlapptools.m‎

Lines changed: 64 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -33,22 +33,22 @@
3333
end
3434
end % aboutDojo
3535

36-
function fontColor(uielement, newcolor)
36+
function fontColor(uiElement, newcolor)
3737
% A method for manipulating text color.
3838
newcolor = mlapptools.validateCSScolor(newcolor);
3939

40-
[win, widgetID] = mlapptools.getWebElements(uielement);
40+
[win, widgetID] = mlapptools.getWebElements(uiElement);
4141

4242
fontColorSetStr = sprintf('dojo.style(dojo.query("#%s")[0], "color", "%s")', widgetID, newcolor);
4343
win.executeJS(fontColorSetStr);
4444
end % fontColor
4545

46-
function fontWeight(uielement, weight)
46+
function fontWeight(uiElement, weight)
4747
% A method for manipulating font weight, which controls how thick or
4848
% thin characters in text should be displayed.
49-
weight = mlapptools.validatefontweight(weight);
49+
weight = mlapptools.validateFontWeight(weight);
5050

51-
[win, widgetID] = mlapptools.getWebElements(uielement);
51+
[win, widgetID] = mlapptools.getWebElements(uiElement);
5252

5353
fontWeightSetStr = sprintf('dojo.style(dojo.query("#%s")[0], "font-weight", "%s")', widgetID, weight);
5454
win.executeJS(fontWeightSetStr);
@@ -80,6 +80,54 @@ function fontWeight(uielement, weight)
8080
%}
8181
end % getHTML
8282

83+
function [win, widgetID] = getWebElements(uiElement)
84+
% A method for obtaining the webwindow handle and the widgetID corresponding
85+
% to the provided uifigure control.
86+
% Get a handle to the webwindow
87+
win = mlapptools.getWebWindow(uiElement.Parent);
88+
89+
% Find which element of the DOM we want to edit
90+
widgetID = mlapptools.getWidgetID(win, mlapptools.getDataTag(uiElement));
91+
end % getWebElements
92+
93+
function [win] = getWebWindow(hUIFig)
94+
mlapptools.toggleWarnings('off')
95+
% Make sure we got a valid handle
96+
assert(mlapptools.isUIFigure(hUIFig),...
97+
'mlapptools:getWebWindow:NotUIFigure',...
98+
'The provided window handle is not of a UIFigure.');
99+
100+
tic
101+
while true && (toc < mlapptools.QUERY_TIMEOUT)
102+
try
103+
hController = struct(struct(hUIFig).Controller);
104+
% Check for Controller version:
105+
switch subsref(ver('matlab'), substruct('.','Version'))
106+
case {'9.0','9.1'} % R2016a or R2016b
107+
win = hController.Container.CEF;
108+
otherwise % R2017a onward
109+
win = struct(hController.PlatformHost).CEF;
110+
end
111+
break
112+
catch err
113+
if strcmp(err.identifier, 'MATLAB:nonExistentField')
114+
pause(0.01)
115+
else
116+
mlapptools.toggleWarnings('on')
117+
rethrow(err)
118+
end
119+
end
120+
end
121+
mlapptools.toggleWarnings('on')
122+
123+
if toc >= mlapptools.QUERY_TIMEOUT
124+
msgID = 'mlapptools:getWidgetID:QueryTimeout';
125+
error(msgID, ...
126+
'WidgetID query timed out after %u seconds, UI needs more time to load', ...
127+
mlapptools.QUERY_TIMEOUT);
128+
end
129+
end % getWebWindow
130+
83131
function varargout = getWidgetInfo(hUIFig,verbose)
84132
% A method for gathering information about dijit widgets.
85133

@@ -176,12 +224,12 @@ function fontWeight(uielement, weight)
176224

177225
end % setStyle
178226

179-
function textAlign(uielement, alignment)
227+
function textAlign(uiElement, alignment)
180228
% A method for manipulating text alignment.
181229
alignment = lower(alignment);
182230
mlapptools.validateAlignmentStr(alignment)
183231

184-
[win, widgetID] = mlapptools.getWebElements(uielement);
232+
[win, widgetID] = mlapptools.getWebElements(uiElement);
185233

186234
alignSetStr = sprintf('dojo.style(dojo.query("#%s")[0], "textAlign", "%s")', widgetID, alignment);
187235
win.executeJS(alignSetStr);
@@ -214,63 +262,12 @@ function textAlign(uielement, alignment)
214262

215263
end % emptyStructWithFields
216264

217-
function [data_tag] = getDataTag(uielement)
265+
function [data_tag] = getDataTag(uiElement)
218266
mlapptools.toggleWarnings('off')
219-
data_tag = char(struct(uielement).Controller.ProxyView.PeerNode.getId);
267+
data_tag = char(struct(uiElement).Controller.ProxyView.PeerNode.getId);
220268
mlapptools.toggleWarnings('on')
221269
end % getDataTag
222-
223-
function [win, widgetID] = getWebElements(uielement)
224-
% Get a handle to the webwindow
225-
win = mlapptools.getWebWindow(uielement.Parent);
226-
227-
% Find which element of the DOM we want to edit
228-
data_tag = mlapptools.getDataTag(uielement);
229-
230-
% Manipulate the DOM via a JS command
231-
widgetID = mlapptools.getWidgetID(win, data_tag);
232-
end % getWebElements
233-
234-
function [win] = getWebWindow(uifigurewindow)
235-
mlapptools.toggleWarnings('off')
236-
% Test if uifigurewindow is a valid handle
237-
if ~isa(uifigurewindow,'matlab.ui.Figure') || ...
238-
isempty(struct(uifigurewindow).ControllerInfo)
239-
msgID = 'mlapptools:getWebWindow:NotUIFigure';
240-
error(msgID, 'The provided window handle is not of a UIFigure.');
241-
end
242-
243-
tic
244-
while true && (toc < mlapptools.QUERY_TIMEOUT)
245-
try
246-
hController = struct(struct(uifigurewindow).Controller);
247-
% Check for Controller version:
248-
switch subsref(ver('matlab'), substruct('.','Version'))
249-
case {'9.0','9.1'} % R2016a or R2016b
250-
win = hController.Container.CEF;
251-
otherwise % R2017a onward
252-
win = struct(hController.PlatformHost).CEF;
253-
end
254-
break
255-
catch err
256-
if strcmp(err.identifier, 'MATLAB:nonExistentField')
257-
pause(0.01)
258-
else
259-
mlapptools.toggleWarnings('on')
260-
rethrow(err)
261-
end
262-
end
263-
end
264-
mlapptools.toggleWarnings('on')
265-
266-
if toc >= mlapptools.QUERY_TIMEOUT
267-
msgID = 'mlapptools:getWidgetID:QueryTimeout';
268-
error(msgID, ...
269-
'WidgetID query timed out after %u seconds, UI needs more time to load', ...
270-
mlapptools.QUERY_TIMEOUT);
271-
end
272-
end % getWebWindow
273-
270+
274271
function [widgetID] = getWidgetID(win, data_tag)
275272
widgetquerystr = sprintf('dojo.getAttr(dojo.query("[data-tag^=''%s''] > div")[0], "widgetid")', data_tag);
276273

@@ -299,7 +296,12 @@ function textAlign(uielement, alignment)
299296
mlapptools.QUERY_TIMEOUT);
300297
end
301298
end % getWidgetID
302-
299+
300+
function tf = isUIFigure(hList)
301+
tf = arrayfun(@(x)isa(x,'matlab.ui.Figure') && ...
302+
isstruct(struct(x).ControllerInfo), hList);
303+
end
304+
303305
function toggleWarnings(togglestr)
304306
switch lower(togglestr)
305307
case 'on'

0 commit comments

Comments
 (0)