Contents     Functions              PDF Index

comgui,cingui

Purpose

General utilities for graphical user interfaces.

Syntax

 comgui('Command', ...)
cingui('Command', ...)


comgui is an open source function that the user is expected to call directly while cingui is closed source and called internally by SDT.

ImCrop

Image cropping utilities. This function allows cropping uniform borders and uniform rows or columns in an image.

Syntax is a=comgui('ImCrop',a)'

Image a can be either

• an image defined by an m-by-n-by 3 matrix, or a line cell array of such images
• a structure from getFrame with fields cdata containing m-by-n-by 3 matrices
• a file name or a line cell array of file names. By default if a file name is given the file is replaced by saving the cropped image.
• a composite cell array line with file names and images. By default if a file name is given the file is replaced by saving the cropped image.

The following command options are available

• Borders To only crop image from the first border.
• AllBorders To only crop image from all borders.
• BorderNum To only crop image from the first N borders, given as parameter.
• UpToBorder To crop until a border is found in the limit of 20 pix from the edges of the original image. (Useful for java capture of figures)
• All To remove all rows/columns with equal colors throughout the image.
• Equal To apply the same cropping to all images in the cell array input, by intersecting cropping rows and columns.
• -noSave Not to erase images provided in file names.
• Rot90 can be used to rotate the image by ± 90 degrees before cropping

You can include cropping options within an ImWrite call by defining a .CropOpt field in the option structure.

ImWrite, ...

ImwriteFileName.ext does a clean print of the current figure. The preferred strategy is to predefine options, so that comgui('ImWrite') alone is sufficient to generate a figure. This can be done by

comgui('ImWrite',gf,RO) with a figure handle given in gf and options stored in the RO structure, is the most general. gf can be omitted and will be taken to be gcf.

RO can be omitted if options are given as strings in the command. Thus ImWrite-NoCrop is the same as using RO.NoCrop=1.

For details for multi-image capture strategies (for example a set of modeshapes), see iicom ImWrite.

Acceptable options are detailed below.

• .FileName The default extension is .png. With no file name a dialog opens to select one. RO.FileName can be a cell array for a ImFtitle call.
• .NoCrop=1 avoids the default behavior where white spaces are eliminated around bitmap images.
• .FTitle=1 uses the title/legend information to generate a file name starting with the provided filename.

A typical example would be comgui('imwrite-FTitle plots/root') which will generate a root_detail.png file in local directory plots.

For a given plot, comgui('imFTitle') can be used to check the target name.

Using a cell .FileName calls comgui ImFtitle to let you build the file name from elements within the figure.

• .LaTeX=1 displays LATEX commands to be used to include the figure in a file.
• .objSet provides an comgui objSet style. You can also combine predefined styles using a cell of the form {'@OsDic(SDT Root)',{'fmt1','fmt2'}}. The '@ToFig' can be used to clone the figure before printing to avoid modifying its appearance.
• .clipboard copies to clipboard.
• .Java To use screenshot strategies of the system current monitor display using java. This implies in particular that the content to capture is visible on screen when the command is used.
• .Java=1 uses java to do a screen capture of the figure content (undocked figure).
• .Java=2 captures the figure with the figure border (undocked figure). Use 2.2 to perform a clean crop arround the figure (if windows in your OS are surrounded by an unicolor rectangle)
• .Java=3 captures the dock containing the current figure.
• .Java=4 captures the content of the current tab in a tabbed pane without column headers.
• .Java=5 captures the pane containing the current tab (add the tab layout).
• .Java=6 captures the content of the current tab in a tabbed pane with column headers.
• .Java=7 captures the content of the tile containing the figure (figure + figure headers).
• .Java=8 captures the ExploTree of the UI.
• .JavaT To capture figures contents using java object methods (works for tables only)
• .open=1 opens the image in a browser.
• .Crop='all' modifies the cropping option, see comgui ImCrop. Use 'no' to avoid cropping.
• .MultiExt={'.png','.fig'} will allow saving of multiple versions of the same image.
• .wobjSet is used to insert the image into the current Microsoft Word file directly. d_imw('get','WrW49C') gives a sample format.

It is also possible to directly capture a graphical java object which contains getVisibleRect and getLocationOnScreen properties. Simply provide the java object as instead of a figure handle.

sdtweb sdt % Open sdt.html in the help browser
pause(2); % Wait for the display
desktop = com.mathworks.mde.desk.MLDesktop.getInstance;
r1=desktop.getGroupContainer('Help') % Get the java container of the help browser
% Save the HelpBrowser capture in the tempdir with name testjavacapture.png
comgui('imwrite testjavacapture',r1);


ImFtitle, ...

ImFtitle generates a file name for the figure based on current displayed content. Text is searched in objects with tags legend, ii_legend, in the axes title. By default all the text is concatenated and that can generate excessively long names so finer control is achieved by providing the FileName as a cell array in the comgui PlotWd call. The underlying mechanism to generate the string is described in comgui objString.

 figure(1);clf; t=linspace(0,2*pi);h=plot(t,[1:3]'*sin(t));
legend('a','b','c');title('MyTit');
% Define target plot directory in the figure
cingui('objset',1,{'@PlotWd',sdtdef('tempdir')})

% Check name generation, from string
comgui('imftitle',1,{'@PlotWd','@title','.png'})
% Do a direct call with name building
comgui('imwrite',struct('FileName',{{'@PlotWd','@title','.png'}}))

% Predefine the figure save name in the userdata.Imwrite of current axis
comgui('PlotWd',1,'FileName', ...
{'@Plotwd','@title', ... % Search for plotwd, use title name
'@legend(1:2)','.png'}); % use first legend entry
comgui('imInfo') % See parameters
% check image name, display clickable link for image generation
comgui('imftitle')

d_imw('Fn') % Standard names styles for tile name generation


dock

SDT uses some docking utilities that are not supported by MATLAB. The actual implementation is thus likely to undergo changes.

 gf=11;figure(gf);clf; t=linspace(0,2*pi);h=plot(t,[1:3]'*sin(t));
figure(12);plot(rand(3));figure(13);mesh(peaks);
% set the dock name and position
comgui('objset',[11 12 13],{'@dock',{'name','MAC', ...
'arrangement',[1 1 2;1 1 3], ... % Automated tile merging
'position',[0 0 600 400],...
'tileWidth',[.4 .6], ... % Fraction of columns
'tileHeight',[.3 .7]}}); % Fraction of rows
pos=feval(iimouse('@getGroupPosition'),'MAC'); % group screen position
figure(14); % Add a new figure in specified tile
cingui('objset',14,{'@Dock',{'Name','MAC','Tile',11}});

feval(iimouse('@deleteGroup'),'MAC') % Delete group (and figures)


Capture of a dock group figure is possible with comgui imwrite-Java3

guifeplot,iiplot

 cf=comgui('guifeplot -reset -project "SDT Root"',2);
comgui('iminfo',cf) % View what was set


Is used to force a clean open of an feplot figure. The option -reset is used to force emptying of the figure. The option -project is used to combine a call to comgui PlotWd to define the project.

Formatting styles sdtroot OsDic are also stored in the project.

objSet (handle formatting)

cingui('objSet',h,Prop) is the base SDT mechanism to generalize the MATLAB set command. It allows recursion into objects and on the fly replacement. Prop is a cell array of tag-value pairs classical in MATLAB handle properties with possible modifications. Three base mechanisms are object search, expansion and verification.

Object search '@tag',value applies property/values pairs stored in value to an object to determined on the fly. For example '@xlabel' applies to the xlabel of the current axis.

• @xlabel accepts a value that is a cell array that will be propagated for all x labels. A typical example would be {'@xlabel',{'FontSize',12}}. Other accepted components are @ylabel, @zlabel, @title, @axes, @text,
• @axes, @figure will search for parent or child axes objects
• @tag is assumed to search for object with the given tag, so that its properties can be set. For example {'@ii_legend',{'FontSize',12}} will set the fontsize of an object with tag ii_legend.
• @tag(val) allows the selection of a specific object by index when multiple objects with the same tag are found.
• @ImFtitle is used to store the cell array for image name generation see comgui ImFtitle. This must be set after displaying title and legend entries, since the information is stored in these objects.
• @legend generates the usual MATLAB legend
• @ii_legend allows a tick generation callback, see ii_plp Legend
• @TickFcn allows a tick generation callback, see ii_plp TickFcn
• @ColorBar allows handles properties of colorbar. This is illustrated under fecom ColorBar, but can be used for any figure.
• @dock handles docking operations, see comgui dock.
• @ToFig replicate the figure before applying operations. Property {'cf',val} can be used to force replication into figure val (use NaN for a new figure). Property {'PostFcn',val} can be used to allow execution of a callback after the figure replication. Property {'leg',1} uses the iiplot ii_legend object, while 2 transforms to a MATLAB legend.

Expansion modifies the current property/value list by replacing a given entry.

• '@OsDic(SDT Root)',{'val1','val2'} seeks objset values in the sdtroot OsDic.
• '','@tag' is first expanded by inserting a series of tag-value pairs resulting from the replacement of @tag.

The two uses are illustrated below

% Define OsDic entries in project
sdtroot('SetOsDic',{'feplotA',{'Position',[NaN NaN 500 300]};
'font12',{'@axes',{'fontsize',12},'@title',{'fontsize',12}}
'grid',{'@axes',{'xgrid','on','ygrid','on','zgrid','on'}}
});
sdtroot('setOsDic', ... % Define a line sequence
{'LiMarker',setlines(jet(5),{'-','--','-.'},'+ox*sdv^><ph')})
% Example of apply call
figure(1);plot(sin(linspace(0,4*pi)'*[1:3]))
cingui('objset',1,{'@OsDic(SDT Root)',{'feplotA','grid','LiMarker'}})
% Get OsDic data for given entry
sdtroot('cbosdicget',[],'ImLW75') % in project
cingui('fobjset','RepRef',{'@OsDic',{'feplotA','grid'}})
cingui('fobjset','RepRef',{'','@Rep{SmallWide}'})


Value replacement/verification performs checks/callbacks to determine the actual value to be used in the MATLAB set.

• position accepts NaN for reuse of current values. Thus [NaN NaN 300 100] only sets width and height.
• @def The value is a default stored in sdt_table_generation('Command'). One can search values by name within a cell array. This is in particular used for preset report formats @Rep{SmallWide} in comgui ImWrite.
• xlim, ... clim accept callbacks for the setting of limits. 'set(ga,”clim”,[-1 1]*max(abs(get(ga,”clim”))))' is a typical example setting symmetric color limits.
• '@setlines(”marker”)' or '@out=setlines(”marker”);' are two variants where the value is obtained as the result of a callback. Note that the variant with @out must end with a semicolumn. This is illustrated in the example below.
 figure(1);t=linspace(0,2*pi);h=plot(t,[1:3]'*sin(t));
cingui('objset',1, ...       % Handle to the object to modify
{'','@Rep{SmallWide}', ... % Predefined figure type
'@line','@setlines(''marker'')'}) % Line sequencing
cingui('fobjset','RepRef',{'','@Rep{SmallWide}'})


objString (string generation for title and file)

cingui('objString',h,SCell) is a mechanism to generate strings based on a set of properties. Elements of SCell are replaced when starting by an @, with implemented methods being

• @PlotWd is the base mechanism to find the plotting directory, see comgui PlotWd.

@PlotWd/relpath is accepted in name generation to allow simple generation of relative paths.

• @tag(1:2) allows selection of a subset of objects when multiple exist. Typical are @legend(1) to select the first string of a MATLAB legend, or @ii_legend(1) for an SDT ii_plp Legend entry. @headsub for the text used by feplot to display titles.
• @colorbar seeks the string associated with a colorbar
• @cf.mdl.name or any variant based on @cf can be used to retrieve data in an SDT handle pointer.

This is used by comgui ImFtitle to generate figure names, but can also be used elsewhere (fe_range, ...). For example in title generation.

 figure(1);clf;
t=linspace(0,2*pi);h=plot(t,[1:3]'*sin(t));title('MyTit')
legend('a','b','c');
SCell=   {'@Plotwd/plots', ... % Search for plotwd/plot
'@title', ... % use title name
'.png'}; % extension
cingui('objstring',1,SCell) % Handle of base object


ParamEdit

cingui('ParamEdit') calls are used to clarify filling of options data structures as detailed in section 7.17.3.

def.Legend

The def.Legend field is used to control dynamic generation of text associated with a given display. It is stored using the classical form of property/value pairs stored in a cell array, whose access can be manual or more robustly done with sdsetprop.

Accepted properties any text property (see doc text) and the specific, case sensitive, properties

• set gives the initialization command in a string. This command if of the form 'legend -corner .01 .01 -reset' with
• cornerx y gives the position of the legend corner with respect to the current axis.
• -reset option deletes any legend existing in the current axis.
• string gives a cell array of string whose rows correspond to lines of the legend. $title is replaced by the string that would classically be displayed as label by feplot. Individual formatting of rows can be given as a cell array in the second column. For example {'\eta_1',{'interpreter','tex'}}.  [model,def]=hexa8('testeig');cf=feplot(model); cf.data.root='\it MyCube'; def.Legend={'set','legend -corner .1 .9 -reset', ... % Init 'string',{'$title';'@cf.data.root'}, ... % The legend strings
'FontSize',12} % Other test properties
cf.def=def;


PlotWd

Determination of the target directory for plotting is a key aspect of image generation. The normal procedure is to associate a figure with a project working directory as illustrated below. When initializing in a feplot figure, use cf=comgui('guifeplot -project "SDT Root"',2) to set the project information. Note that the older strategy using cf.def.PlotWd, cf.mdl.PlotWd are still used first if they exist. Similarly use cf=comgui('guiiiplot -project "SDT Root"',2) to set the project information of iiplot figures.

Accepted property/value pairs (a structure can also be used but this is not the norm)

• '@OsDic(SDT Root)',list is used to extract property/values from the dictionnary. The (SDT Root) is the name of the figure from which dictionnary and project information is to be obtained from. The Project values is set.
• Project tag of project interface. Default would be SDT Root
• FileName cell array describing file name generation, see example in comgui ImFtitle
• objSet cell array of objset commands to be performed before generating an image. This typically begins by a @ToFig to avoid modifying the original figure.
• wobjSet cell array of commands for insertion of the resulting image into MicroSoft Word, Powerpoint,Excel, LaTex, ... A sample entry is given by d_imw('wrw49c').
• 'MultiExt',{'.png','.fig'} cell array of extensions to save mutiple versions of given figure.
t=linspace(0,pi); % basic plot
gf=1;figure(gf);clf;plot(t,sin(t));
title('TestFigure');legend('a');
% Define the project directory
sdtroot('SetProject',struct('PlotWd',sdtdef('tempdir')))
% Prepare for image generation.
list={ ...  % List of OsDic entries, implemented in d_imw
'ImToFigN', ... % Duplicate to new figure before ImWrite
'FnTitle', ...  % Generate file name based on Title
'WrW49C'        % Insert in word with 49% wide centered
};
cingui('plotwd',gf,'@OsDic(SDT Root)',list) % Associate figure gf with project SDT Root
comgui('iminfo',gf) % View what was set
comgui('imwrite',gf) % Actually insert image


FitLabel

comgui('fitlabel') attempts to replace axes of the current figure so that xlabel, ylabel, ... are not cropped.