-
Data handling
-
GUI elements
-
Layout
-
Predefined variables
-
Callback definitions
Data handling
Initial call
data = data_gui3( callback, arg1 )
data
The data structure holds all data.
callback
Initial callback.
arg1
Optional parameter of initial callback.
data_gui3(@demoinit);
Register new variables.
data = data.CALL.addData( data, input )
input
n*1 cell array
every cell consist of:
1*(2-4) cell array: { 'variable name' 'default' 'constrain' 'callback' }
- variable name : STRING; Name of the variable; Must start with 'data.'
- default: Type depends on use case; This is the initial value and can be reset with
data.CALL.defaultValue; The type is fixed
- constrain: optional; Type double array with [min max] value, name of constrain callback or empty backets (== no constrain).
- callback: optional; Reference to a GUI callback function.
i = cell( {
{ 'data.tablein' 1:.1:2 @table_check @updatePlot }
{ 'data.push1' 'PUSH1' [] @pushcb}
{ 'data.p3avis' 'on' }
});
data = data.CALL.addData(data, i);
Manual update of a registered variable. Could start a callback and could update the GUI.
This function should be used in callbacks with long processing time to update a progress bar or status information.
All GUI elements will be updated not only the entryname depending one!
[data error] = data.CALL.updateEntry( data, entryname, value, docallback, updategui )
entryname
string: target variable ('data.myvalue')
value
type depends on use case
docallback
boolean: start callback is true; (and value passes constain check)
updategui
boolean: update GUI if true
error
error case if not empty, check with isempty
[data error] = data.CALL.updateEntry( data, 'data.status', 'init finished' , false, true );
Load registed variables from file system.
data = data.CALL.loadData( data, filename )
filename
string: file name with full path
data = data.CALL.loadData(data, filename);
Save registed variables into a file. If called with 2 parameters all registered variables will be saved.
data = data.CALL.saveData( data, filename, filter)
filename
string: file name with full path
filter
cell array of strings, OPTIONAL: every string must start with 'data.'.
filter = { 'data.GunOffset' 'data.E_DOG_nom' 'data.r56_DOG' 'data.t566_DOG' };
data = data.CALL.saveData(data, filename,filter);
Reset registered variable to default value.
data = data.CALL.defaultValue( data, variableName )
variableName
name of registered variable, must start with 'data.'
data = data.CALL.defaultValue( data, 'data.astra_file' );
Set new constrain. Usefull if you want to modify a slider or the number of elements in a popup box.
data = data.CALL.updateConstrain( data, entryname, constrain )
entryname
name of registered variable, must start with 'data.'
constrain
Type double array with [min max] value, name of constrain callback or empty backets (== no constrain).
data = data.CALL.updateConstrain(data, 'data.slidervalue', [1 3]);
Setup global constrain error callback. The global error callback will be called if a contrain check fails.
data = data.CALL.addDataErrorCB(data, callbackHandler)
callbackHandler
reference to an error callback
data = data.CALL.addDataErrorCB(data, @dataErrorCB);
GUI elements
Create new GUI elements.
data = data.CALL.addGui( data, input )
input
n*1 cell array
every cell consist of:
1*m cell array: { 'type' 'required parameter 1' ... 'required parameter x' 'optional property name 1' 'optional property value 1' ... }
Table of required parameters:
| Type | Parameter 1 | Parameter 2 | Parameter 3 | Parameter 4 |
|---|
| axes | tag name | parent tag name |
| checkbox | tag name | parent tag name | checkbox status |
| deref | tag name | start/stop status |
| edittext | tag name | parent tag name | text field data |
| figure | tag name |
| listbox | tag name | parent tag name | selected field | list fields text |
| menuitem | tag name | parent tag name | menu string |
| panel | tag name | parent tag name |
| popupbox | tag name | parent tag name | selected field | popup list elements |
| pushbutton | tag name | parent tag name | text |
| radiogroup | tag name | parent tag name | selected radio | radio button names |
| slider | tag name | parent tag name | slider value |
| statictext | tag name | parent tag name | text |
| table | tag name | parent tag name | table data |
| timer | tag name | start stop variable |
| togglebutton | tag name | parent tag name | status | text |
| tabgroup | tag name | parent tag name | selected tab | tab names |
| tree | tag name | parent tag name | node data | node selected |
| treedyn | tag name | parent tag name | node data | node selected |
The optional parameters must be a property name/value pair. The name/value pairs follow the original MATLAB rules. The number of required parameters depends on the GUI element type.
Additional property information:
| Color definition: |
|---|
| Free to use. Could be bound to a registered variable. |
| Property linked to registered variable. Modify with linked variable. |
| Fixed. Do not modify! |
| Type | Property | Type | Comment |
|---|
| axes | buttondownfcn | Callback | Reference to a user defined callback, called if user pressed a botton. |
| checkbox | Value | Double | |
| checkbox | Min | Double | |
| checkbox | Max | Double | |
| deref | BusyMode | String | fixed: drop |
| deref | StartDelay | Double | fixed: 0.1 |
| deref | ExecutionMode | String | fixed: singleShot |
| deref | UserData | | Do not modify |
| edittext | String | | |
| figure | CloseRequestFcn | Callback | See close figure callback for more information. |
| figure | WindowButtonUpFcn | Callback | |
| figure | WindowButtonMotionFcn | Callback | |
| figure | WindowScrollWheelFcn | Callback | |
| figure | FocusGainedCallback | Callback | |
| figure | FocusLostCallback | Callback | |
| figure | KeyPressedCallback | Callback | |
| figure | KeyReleasedCallback | Callback | |
| figure | KeyTypedCallback | Callback | |
| figure | MouseClickedCallback | Callback | |
| figure | MouseDraggedCallback | Callback | |
| figure | MouseEnteredCallback | Callback | |
| figure | MouseExitedCallback | Callback | |
| figure | MouseMovedCallback | Callback | |
| figure | MousePressedCallback | Callback | |
| figure | MouseReleasedCallback | Callback | |
| figure | MouseWheelMovedCallback | Callback | |
| figure | PropertyChangeCallback | Callback | |
| figure | UserData | Structure | Will be updated by the library! |
| listbox | Value | Double | |
| listbox | String | String,Cell | |
| menuitem | Label | String | |
| popupbox | Value | Double | |
| popupbox | String | String,Cell | |
| pushbutton | String | String | |
| radiogroup | SelectionChangeFcn | Callback | |
| radiogroup | SelectedObject | Double | |
| slider | Value | Double | |
| slider | Min | Double | |
| slider | Max | Double | |
| slider | Continuouse | Boolean | The use of this property need the findjobj funktion! |
| statictext | String | String | |
| table | Data | Double or cell array | |
| table | CellSelectionCallback | Callback | |
| timer | BusyMode | String | |
| togglebutton | String | String | |
| togglebutton | Value | Double | |
| togglebutton | Min | Double | |
| togglebutton | Max | Double | |
| tabgroup | SelectedIndex | Double | |
| tree | DragDropEnabled | Boolean | |
| tree | MultipleSelectionEnabled | Boolean | |
| treedyn | DragDropEnabled | Boolean | |
| treedyn | MultipleSelectionEnabled | Boolean | |
| * | Tag | String | Will be handled by the library! |
| * | Parent | Double | Will be handled by the library! |
| * | Interruptible | String | Will be handled by the library! |
| * | Units | String | Will be handled by the library! |
| * | Position | 3*Double | Will be handled by the library! Exception: figures can be moved with a linked variable. |
| uicontrols | Style | String | Will be handled by the library! |
function data_gui3_demo_axes
data_gui3(@startCb, mfilename);
function [data,redraw]= startCb( data, redraw, param1 )
gui = cell( {
{ 'figure' 'demoaxes1' 'Name' param1 'Toolbar' 'none'}
{ 'axes' 'axes1' 'demoaxes1' }
} );
data = data.CALL.addGui(data, gui);
layout = {{ 0 } { 'axes1' }};
data = data.CALL.addLayout( data, 'demoaxes1', layout );
plot(1:10, 11:20);
Close child figures. If you want to close the main figure use the delete function and return a false value in the redraw variable of your callback.
data = data.CALL.closeFigure( data, figurename )
figurename
string: tag name of figure or handle of figure to close
data = data.CALL.closeFigure(data, 'astrafile');
Expand a node from a dynamic tree element. The (new) nodes will be defined in the callback function.
data = data.CALL.expandTree(data, treetag, value)
treetag
string: tag name of tree
value
value entry of node
data = data.CALL.expandTree(data, 'mytree', '/');
Wrap a standard Matlab callback into a DataGUI callback. If you define a callback with the set function you need the standard matlab callback definition. But if you need to access the data structure you have to use this wrapper. This wrapper get the data structure, check if there is allready a running callback and store the modified data structure after your code was called. This function should only used with objects who are not created by the datagui3 library. Do not overwrite callbacks who are created by the datagui3 library!
matlabCallback = data.CALL.wrapCallback(dataguiCallback)
dataguiCallback
your callback in datagui style ( function [data redraw] = callbackname(data, redraw, event) )
matlabCallback
callback in matlab style ( function callbackName(src, event) )
% ...
l = line(x1,y1,'Color','b','parent',data.handles.axes1,'LineWidth',8);
set(l, 'ButtonDownFcn', data.CALL.wrapCallback(@lineCBnew) );
% ...
function [data redraw] = lineCBnew(data, redraw, event)
display(event);
Layout
Set layout of a figure.
data = data.CALL.addLayout( data, fig, layout_in )
| Layout definition | |
|---|
| Horizontal | { { S1 S2 ... Sn } { L1 L2 ... Ln } } |
| Vertical | { { S1 S2 ... Sn };{ L1 L2 ... Ln } } |
| Panel | { { TAG1 } { L1 } } |
| Stacked | { { TAG1 TAG2 ... TAGn } { L1 L2 ... Ln } } |
| Tabulator | { { TAG1 '' ... '' } { L1 L2 ... Ln } } |
Sx: size of element
Lx: Tag name of element or child layout
TAGx: Tag name of elment
'' : empty string
| Layout size definition | |
|---|
| Size > 1 | pixel |
| Size == 0 | remaining space |
| 0 < Size < 1 | fraction |
Elements who are not in the layout are not visible.
Predefined variables
All handles of GUI elements will be stored inside the data.handles. structure with the tag name as field name.
Callback definitions
First callback of the program.
function [data, redraw] = cb(data, redraw, arg1)
data
structure with all variables
redraw
If redraw is empty, the GUI will be updated after the callback is finished. Default: empty
arg1
Optional. This parameter will be defined in the initial datagui3 call. Should be used to pass initial parameter.
function data_gui3_demo
data_gui3(@demoinit, mfilename); % init data stucture
function [data,redraw]= demoinit( data, redraw, filename ) % init callback
display(filename)
User defined data constrain and convert function.
function [data, value, error] = constrain_check(data, value, error)
data
structure with all variables
value
Input value of GUI element. Must be converted to the type of the destination parameter.
error
If the callback determines an error this variable should be set with a description string. Default: empty
function data_gui3_demo_constraint
data_gui3(@demoinit1); % init data stucture
function [data redraw]= demoinit1( data, redraw ) % init callback
i = cell( {
{ 'data.v123' '' @constraint_check @valueHasNewValue}
});
data = data.CALL.addData(data, i); % add to data strukture
function [data redraw] = valueHasNewValue(data, redraw, event)
display(data.v123)
function [data value error] = constraint_check(data, value, error)
if isempty(value); return; end
if isnumeric(value); return; end % allready numeric
value = str2double(value);
if isnan(value); error = 'value is not numeric'; end
Callback of a registered variable.
function [data, redraw] = normal_callback(data, redraw, event)
data
structure with all variables
redraw
If redraw is empty, the GUI will be updated after the callback is finished. Default: empty. Should be set to an unempty value to speed up callbacks (timers etc.).
event
Structure with additional information. Depends on linked GUI element.
| event field | Description | On event/element |
|---|
| event.hObject | MATLAB handle of GUI element or timer | every |
| event.dataIndex | Internal index of registered variable | every |
| event.valueString | String of registered variable | every |
| event.jObject | Handle of JAVA element | tree, treedyn |
| event.jEvent | Data of JAVA event | tree, treedyn, JAVA event of figure (*1) |
| event.sourceNode | User data of drag and drop source | tree, treedyn |
| event.targetNode | User data of drag and drop target | tree, treedyn |
| event.parentNode | User data to parent node, when tree will be expanded | treedyn |
| event.Indices | Selected indices of a table selected event | table |
| event.X | X position of mouse | JAVA event of figure(*1), MATLAB event of figure (*2) |
| event.Y | Y position of mouse | JAVA event of figure(*1), MATLAB event of figure (*2) |
| event.VerticalScrollCount | mouse scroll wheel counter | MATLAB event of figure (*2) |
| event.VerticalScrollAmount | mouse scrool wheel amount | MATLAB event of figure (*2) |
| event.FigureX | Mouse position in figure | Mouse button down in axes |
| event.FigureY | Mouse position in figure | Mouse button down in axes |
| event.X | Mouse position in axes | Mouse button down in axes |
| event.Y | Mouse position in axes | Mouse button down in axes |
| event.axesChild | Handle of graphic element in axes | Mouse button down in axes |
(*1) JAVA event of figure is: 'FocusGainedCallback' 'FocusLostCallback' 'KeyPressedCallback' 'KeyReleasedCallback' 'KeyTypedCallback' 'MouseClickedCallback' 'MouseDraggedCallback' 'MouseEnteredCallback' 'MouseExitedCallback' 'MouseMovedCallback' 'MousePressedCallback' 'MouseReleasedCallback' 'MouseWheelMovedCallback' 'PropertyChangeCallback'
(*2) MATLAB event of figure is: 'WindowButtonUpFcn' 'WindowButtonMotionFcn' 'WindowScrollWheelFcn'
This callback will be called if a constrain check fails.
function [data, redraw]= error_callback( data, redraw, event )
data
structure with all variables
redraw
If redraw is empty, the GUI will be updated after the callback is finished. Default: empty.
event
Structure with additional information:
event.error
String: Error description
event.hObject
Handle of GUI element
event.dataIndex
Internal index of registered variable
event.valueString
Linked registered variable as string
function data_gui3_demo_constraint
data_gui3(@demoinit1); % init data stucture
function [data redraw]= demoinit1( data, redraw ) % init callback
i = cell( {
{ 'data.value123' 1 [1 3] @value_has_changed}
});
data = data.CALL.addData(data, i); % add to data strukture
data = data.CALL.addDataErrorCB(data, @dataErrorCB);
function [data redraw] = value_has_changed(data, redraw, event)
display(data.value123)
function [data redraw] = dataErrorCB(data, redraw, event)
data.statustext = ['error: ' event.error];
This callback will be called if a close callback of a figure is defined (property 'CloseRequestFcn') and the figure will be closed.
function [data, redraw, doclose]= error_callback( data, redraw, doclose )
data
structure with all variables
redraw
If redraw is empty, the GUI will be updated after the callback is finished. Default: empty.
doclose
Boolean: false : do NOT close figure; true(default) : close figure
function data_gui3_demo_figure_close_callback
data_gui3(@demoinit, mfilename); % init data stucture
function [data,redraw]= demoinit( data, redraw, filename ) % init callback
g = cell( {
{ 'figure' 'demo1fig' 'Name' 'Main Figure' 'CloseRequestFcn' @fig1close }
} );
data = data.CALL.addGui(data, g); % create gui elements
function [data redraw doclose] = fig1close(data, redraw, doclose)
if ~strcmp(questdlg('Quit'),'Yes'); doclose=false; end
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
end of document