comgui,cingui

Contents Functions

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 borders.
All To remove all rows/columns with equal colors throughtout 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

predefining properties in a comgui PlotWd call (including the file name as illustrated under comgui ImFtitle.
or using the obsolete strategies of setting ua.ImWrite in the iiplot PlotInfo so that the proper data is used when a curve is displayed in iiplot or setting ImWrite in comgui def.Legend so that the proper configuration is used when a def is displayed in feplot.

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=1 uses java to do a screen capture of the figure content. .Java=2 captures the figure with the figure border, .Java=3 can be used to capture the dock containing the current figure. .Java=4 captures the content of the current tab in a tabbed pane without column headers.
.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.

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')
 sdtweb('_link','comgui(''Imwrite'')','Generate');

 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

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.
@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

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')})
figure(1);plot(sin(linspace(0,4*pi)'*[1:3]))
cingui('objset',1,{'@OsDic(SDT Root)',{'feplotA','grid','LiMarker'}})
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

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.

Accepted fields of the PlotWd structure are

.wd target directory (optional if a .Project is given)
.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.
.MultiExt={'.png','.fig'} cell array of extensions to save mutiple versions of given figure.

When initializing in a feplot figure, cf.def.PlotWd, cf.mdl.PlotWd are used first if they exist. Objects with tag iicom_imwrite or PlotWd are used next (and generated by objSet commands if they do not exist).

t=linspace(0,pi); % basic plot
gf=1;figure(gf);clf;plot(t,sin(t));
title('TestFigure');legend('a');
% Define the target 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)
comgui('iminfo',gf) % View what was set
comgui('imwrite',gf) % Actually insert image

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

FitLabel

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