PDF Index|
Contents
Functions
PDF Index |
The initialization of GUI button/cells is performed using a but structure with fields .type, .name, ... Available types (string in but.type) are
Each parameter or action is thus associated to a button of the types presented above. The parameter definition then depends on the type, as presented.
To ease the development of GUIs, buttons are stored in DefBut structures. Initialization of the DefBut is usually done in using a file see section 8.2.3.
DefBut.MyField will usually group all buttons needed for a given part of the interface. Notable exceptions are
The set of parameters is divided into families and defined by a keyword and a type. Each family can be easily displayed in separated tabs of the GUI, and constitute relevant sets of parameters regarding human readability.
For generalization purposes, execution actions follow the same definition as parameters, and are linked to a family, keyword and type.
The families and keywords are left free as long as they are compatible with the definition of MATLAB struct fields. The parameter type allows defining which kind of action the user is provided for edition. This is realized in the display by adapted buttons.
Each parameter can be defined as a structure, nested in a structure containing the parameter families as fields. The generation of such structure is handled by sdt_locale so that the definition consists in the generation of a csv file in ASCII format.
The input csv file layout allows defining a parameter, or button with a header line starting with h; defining its type and the fields to be provided, and an instance line starting with n; providing the fields value. Fields that are invariant for the whole class can be defined in the header line. Comments are possible with lines starting with c;.
The following example illustrates the definition of each type of buttons
c; Sample definition of each class c; sample string buttons, with dependencies handled by function my_ui h;type=string;name;format;value;ToolTip;SetFcn='' n;Family.SampleStrS;%s;"st1";"a string input button with no dependencies" n;Family.SampleStrG;%g;1;"a numeric input button with no dependencies" c; sample pop button h;type=pop;name;value;choices;choicesTag;ToolTip;SetFcn='' n;Familiy.SamplePop;1;{'choice1','choice2'};{'c1','c2'};"2 choice menu with default choice1" c; sample push button h;type=push;name;callback;value;ToolTip; n;Family.SamplePush;my_fun('exec');"Push this button";"push button triggering my_fun" c; sample check button h;type=check;name;value;enable;ToolTip;SetFcn='' n;Famimty.SampleCheck;0;"on";"check button, set 0, with conditional enabling and no dependencies"
The csv file should be named after the GUI handling function my_ui, a standard language identifier and extension .csv. Here for example my_ui_en-us.cvs for english-US or my_ui_fr-fr.cvs for french.
Generation of the parameter structure classically named DefBut can then be obtained by
DefBut=sdt_locale('defCSV','my_ui_en-us.csv');
At this state of definition, DefBut is a standard MATLAB struct corresponding to the documented fields. To transform it into a java object linked to the GUI figure of handle GuiGF, command cinguj ObjEditJ must be used
[r1j,r1]=cinguj('objEditJ',DefBut.Family,GuiGF);
The first output is r1j, which is an EditT Java object. This object will be used for dependencies handling and can be edited using sdcedit. The second output r1 contains copies of each parameters in a struct with fields the parameter names. The parameters are in their Java form that is to say editable buttons of class CinCell.
After generating the Java objects containing the parameters, one can store them in the GUI figure for further access. The data are stored in the GUI figure that is initialized by cinguj ObjFigInit.
GuiGF=cinguj('objFigInit',... struct('tag','my_ui','noMenu',1,'name','my_ui'));
The handle should be stored UI.gf field of persistent variable UI in my_ui. One can also recover this pointer at any time by using GuiGF=findall(0,'tag','my_ui'). It is thus critical to ensure the unicity of the GUI figure tag.
Efficient data storage in a figure is handled in SDT through the use of v_handle uo object. Access to this pointer is possible at any time using
uo = v_handle('uo',GuiGF);
It is recommended to package the access to the java data pointer in a command uo=my_ui('vh').
Automatic storage of the data pointer is performed at display. The pointer is handled as a MATLAB struct with fields corresponding to the parameter families. The objects stored are then either the EditT containing the full parameter family or a struct of CinCell, respectively corresponding to the first and second outputs of the ObjEditJ command.
A very low level way of storing invisible data is to edit the uo object directly by doing
r1=get(GuiGF,'UserData'); r1.(family)=r1j; set(GuiGF,'UserData',[],'UserData',r1);
where family is the parameter family, r1j the EditT object generated by ObjEditJ and GuiGF the handle to the GUI figure. It is however recommended to let it be stored automatically at display.
To recover data in a RunOpt MATLAB struct format from EditT or CinCell objects, command fe_defCleanEntry must be used.
fe_defCleanEntry no longer returns the full structure for a button, so that the command r1=cinguj('ObjToStruct',ob); should be used.
To get the current data (.data{.val} of pop button, one use r1=feval(sdtroot('@obGet'),ob,'data');.
It is recommended to build a call my_ui('GetTab') that will rethrow the RunOpt structure corresponding to a Tab from the GUI figure.
% get Java pointer and desired tab field out=my_ui('vh'); tab=varargin{carg}; carg=carg+1; % convert to a RunOpt structure out=fe_def('cleanentry',out.(tab));
Direct access to a parameter can also be usefully packaged in my_ui('GetTab.Param'), with
% get Java pointer and desired tab field out=my_ui('vh'); tab=varargin{carg}; carg=carg+1; % parse tab to see if subfields are desired tab=textscan(tab,'%s','Delimiter','.'); tab=tab{1}; % convert to a RunOpt structure out=fe_def('cleanentry',out.(tab{1})); % output only the desired subfield if it was specified if length(tab)>1; tab(1)=[]; while ~isempty(tab)&&~isempty(out); out=out.(tab{1}); st(1)=[]; end end
To display the parameters in the GUI figure, one has to generate a structure that will be interpreted as a JTable that will be included to the JTabbedPane object, that is to say the tabbed area of the GUI figure. This structure contains the fields
Generation of the table field can be done automatically with a call to sdt_dialogs uatable
ua.table=sdt_dialogs('uatable-end0','info',name,r1j);
with name the field relative to ua.name and r1j the EditT object (with .Peer defined). This will yield a tab with three columns, the first one being the parameter names, the second one the editable buttons as CinCell objects and the third one being the parameter ToolTip.
More complex layouts can be obtained by generating the table manually, exploiting the second output of the ObjEditJ command to fill in table positions. This allows generating the table by directly positioning the CinCell objects called by their names.
By adding a field level to ua, and calling cingujTabbedPaneAddTree a tree will be displayed instead of a table in the GUI figure. Field level has two columns and as many lines as the table. The first column provides the level of the table line in the tree as an integer. The second column indicates whether the line has to be expanded is set to 1, or not if set to 0.
Once ua is filled display is performed using cinguj TabbedPaneAdd
[ua,ga]=cinguj('TabbedPaneAdd','my_ui',ua);
Command TabbedPaneAdd outputs ua that contains the displayed objects and their information. This can be accessed any time using field tStack of the GUI figure userdata, uf=clean_get_uf(GuiGF), and ga that is the handle to the figure axis containing the tab.
Display can be tuned to the user will by editing the displayed objects. All display information is accessed through a call to clean_get_uf, using GuiGF the GUI figure handle as input argument.
uf = clean_get_uf(GuiGF);
uf is a user data structure with fields
The seventh column of uf.tStack contains information relative to each of the tab objects of the JTabbedPane. It is commonly named ub and contains the following fields
Each tabbed pane can be tweaked regarding the displayed column dimensions.
In the case of a GUI displaying user input objects the table itself does not need to be interactive. (This is different from a results table that will be analyzed by the user). It is thus recommended to deactivate the table selection interactivity using
ub.JTable.setRowSelectionAllowed(false); ub.JTable.setColumnSelectionAllowed(false); ub.JTable.setCellSelectionEnabled(false);
Columns width can be set using a line array with as many columns as columns in the table and providing in pixels the minimal width a column should have to cingujtableColWidth. The value can be set to -1 if the user wishes to let free the width of a column.
% for 3 columns table, last one left free ColWidth=[150 300 -1]; cinguj('tableColWidth',ub.JTable,ColWidth);
Row height can be set (same for all lines) by calling the setRowHeight method of JTable. The value is in pixel.
% getting the intial row height r1 = ub.JTable.getRowHeight % setting a new row height to 22px ub.JTable.setRowHeight(22)
To ease up navigation between tabs, one can use an exploration tree in the GUI figure. Tabs can then be opened by clicking in the tree that should list all available tabs (or parameter families).
The exploration tree is commonly named PTree, and has to be defined in the .csv file. It should contain push type buttons with callbacks triggering the opening of the desired tab.
c; sample PTree defintion
h;type=push;name;callback;value;ToolTip;
n;PTree.Family;my_ui('InitFamily');"Family";"Open corresponding family tab"
To properly handle an exploration tree, one has to initialize it when the GuiGF figure is opened, that is to say after the cinguj ObjFigInit call. The initialization should be handled by a call of the type mu_ui('InitPTree').
Low level access to the exploration tree is handled by a subfunction of cinguj named treeF. The subfunction handle can be accessed using treeF=cinguj('@treeF');. It is recommended to store the variable treeF containing the subfunction handle in a persistent variable of the GUI function my_ui.
% option initialization RunOpt=struct('NoInit',0,'lastname',''); % for all fields of DefBut.PTree, sort the buttons r1=fieldnames(DefBut.PTree); table=cell(length(r1),2); for j1=1:length(r1);table(j1,:)={DefBut.PTree.(r1{j1}) [1 1]}; end % generate clean table and corresponding levels level=vertcat(table{:,2}); table=table(:,1); % generate the tree ua ua=struct('table',{table},'level',level,'name','my_ui',... 'ParentPanel',GuiGF,'ToolTip','The GUI exploration tree','NeedClose',2); % display the tree in the GUI figure [tree,gf]=cinguj('tabbedpaneAddTree','my_ui',ua); % tweak the tree to enable selected tab field highlighting tree.getSelectionModel.setSelectionMode( ... javax.swing.tree.TreeSelectionModel.SINGLE_TREE_SELECTION) % refresh cingui('resize',GuiGF);
The exploration tree thus defined highlights its node corresponding to the currently displayed tab. This tasks is performed automatically by cinguj when clicking on a button of a tree.
To access the tree object and its highlighted field, one can do
[RunOpt.lastname,tree]=treeF('explolastname',GuiGF);
To switch the highlighted field to a new name newname and get the tree node object, one can do
node=treeF('scrollToNameSelect',tree,newname);
To quickly find CinCell buttons in an interface, subfunction getCell of sdcedit can be used.
getCell=sdcedit('@getCell'); [obj,tab,name]=getCell(r1j,'propi','vali',...,stOpt)
Actions to check or get specific fields of a cell array of CinCell buttons are also available using commands
% r1=getCell('getfield st',obj); % outputs field st of obj (CinCell) or {obj} % r1=getCell('isfield st',obj); % outputs logical checking presence of field st in obj
