Ctrl+K

comgui,cingui

comgui,cingui#

Purpose

General utilities for graphical user interfaces and figure formatting. Figure formatting documentation can be found in section 8.1.

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. Not that you can also specify the figure to be printed using comgui('ImWrite',FigNum). Setting of options can be done by

The low level call 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 around 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')
sdtweb('_link','comgui(''Imwrite'')','Generate');


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

ImInfo#

Command comgui('iminfo',gf) shows the structure containing all the figure formatting options for figure gf (see command PlotWd)

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],...
   'dockgroup',false, ...   % Do not dock the dock into the MATLAB desktop
   '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.
  • @PlotInfo calls iicom('PlotInfo') to initialize how data is displayed in an feplot/iiplot figure. See iiplot PlotInfo.

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 semi-column. 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.4.

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#

A key aspect of image generation is to define meta-data associated with a figure. These include, directory where the image will be saved, file name, possible inclusion in Word, PowerPoint, ... The Project tab defines the plot directory and possibly a file for inclusion. Other properties are set using the PlotWd command cingui('plotwd',gf,'@OsDic(SDT Root)',list) as illustrated below.

The list is a cell array of object set dictionnary (OsDic) entries. To analyze reference implementation of OsDic, see sdtweb('_taglist','d_imw'). 

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')))
if ispc; sdtroot('SetProject',struct('Report','sdt.docx'))
else; sdtroot('SetProject',struct('Report','sdt.pptx'))
end
help d_imw % see common calls
% Prepare for image generation.
list={ ...  % List of OsDic entries, implemented in d_imw
  'Reset', ...    % Remove preexisting information
  'ImToFigN', ... % Duplicate to new figure before ImWrite
  'FnTitle', ...  % Generate file name based on Title
  'WrW49C'        % Insert in word with 49% wide centered
  };
% Associate figure gf with project SDT Root
cingui('plotwd',gf,'@OsDic(SDT Root)',list) 
comgui('iminfo',gf) % View what was set
comgui('imwrite',gf) % Actually insert image

When initializing in a feplot figure, use cf=comgui('guifeplot -project "SDT Root"',2) to set the project information. Similarly use cf=comgui('guiiiplot -project "SDT Root"',2) to set the project information of iiplot figures.

When refining formatting beyond specifying directory, insertion file, 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. Note that the Fn.. OsDic entries allow generation of names from text present in the figure (labels, titles, ...).
  • 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 write object setting or insertion of the resulting imag(insertion into MicroSoft Word, Powerpoint, Excel, LaTex, ...). A sample entry is given by d_imw('wrw49c'). sdtacx implements translators from the base SDT format to external software. aword is an ActiveX based translator for Microsoft Word. epptx generates Microsoft power point files directly and thus works on Linux.
  • 'MultiExt',{'.png','.fig'} cell array of extensions to save multiple versions of given figure.

FitLabel#

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

Contents