The Tools menu contains a collection of auxiliary features that are implemented using the command-driven nature of the application. AFPoly users can add their own tools under the Users menu, which will then be accessible directly from the application GUI. The User Tools are added on startup of the application, but can be refreshed by selecting Refresh Users from the Users menu. This way, the User Tools can be modified without restarting AFPoly.
The tools that are added to the Users menu are defined in User Tool definition m-files, which are located in the folder specified by the APPINFO.UsersPath field in the AFPoly initialization file. There is an optional input argument for the 'reusers' command to specify this folder; otherwise the current users path is used. This folder must be defined as a directory in the MATLAB search path so that the User Tool definition m-files can be found. A User Tool definition m-file must have the naming convention of afpoly_user_owner.m, where owner is typically the last name of the person creating the User Tools, but it could also be a name of a group (e.g., "test_group") of users for a collection of User Tools that a group might use, or it could be the name of a project for which some User Tools are specifically created. The User Tools can be organized in any manner that the users determine. Any number of owners can add their own User Tools to the Users menu, with a User Tool definition m-file for each owner. Although the User Tools definition m-files must reside in the APPFINO.UsersPath folder, the m-files that the User Tools callback functions call may reside anywhere in the MATLAB search path.
A template for a User Tools definition m-file is shown below. This file can also be found in the afpoly/tools folder in the IMAT installation location. Assigning the APPFINO.UsersPath to the folder in which this file is located will add its User Tools to the Users menu.
function [TOOLS,TDATA,OWNER] = afpoly_user_template
% AFPoly User Tools Definition Function for Template
OWNER = 'Template';
TOOLS = {};
TDATA = []; % assign TDATA as empty if not used
TDATA.ThenNow = datestr(now);
% beep
TOOLS{end+1}.Owner = OWNER;
TOOLS{end+0}.Label = 'Beep';
TOOLS{end+0}.Tag = 'Beep';
TOOLS{end+0}.Callback = 'beep';
% afpoly usertool template
TOOLS{end+1}.Owner = OWNER;
TOOLS{end+0}.Label = 'User Tool Template';
TOOLS{end+0}.Tag = 'UserToolTemplate';
This block defines the upper-level menu for the submenus below, the Callback field is not required.*
TOOLS{end}.SubMenu{ 1}.Owner = OWNER;
TOOLS{end}.SubMenu{end+0}.Label = 'ARG1=1 ARG2=2';
TOOLS{end}.SubMenu{end+0}.Tag = 'ARGS=12';
TOOLS{end}.SubMenu{end+0}.Callback = {'afpoly_usertool_template',1,2};
TOOLS{end}.SubMenu{end+1}.Owner = OWNER;
TOOLS{end}.SubMenu{end+0}.Label = 'ARG1=3 ARG2=4';
TOOLS{end}.SubMenu{end+0}.Tag = 'ARGS=34';
TOOLS{end}.SubMenu{end+0}.Callback = {'afpoly_usertool_template',3,4};
% edit user tools m-file
TOOLS{end+1}.Owner = OWNER;
TOOLS{end+0}.Label = 'Edit User Tools M-File';
TOOLS{end+0}.Tag = 'EditUserToolsMFile';
TOOLS{end+0}.Callback = sprintf('edit %s',mfilename);
TOOLS{end+0}.Separator = 'on';
The Separator field is an optional menu object property.
The User Tools that appear in the Users menu are defined by blocks of the above cells of structures. The four fields of Owner, Label, Tag, and Callback are required*. Additional properties of the menu object can also be set by including additional fields. The field names must be menu object properties, and the values assigned to the fields must be valid entries for the corresponding property. Refer to the reference page on "Uimenu Properties" in the MATLAB Help browser for more information on specifying menu object properties. OWNER is a string that appears in the Users menu. The user tools defined in the Users Tool definition m-file appear as submenus under the Owner menu. The Label field is a string that appears in the menu for each User Tool. The Tag field is a string, and the Tag and Owner fields are used to give the menu object an identifying name, or tag. The User Tools can have one layer of submenus, as defined by the SubMenus fields above. The Callback field is not required for the upper-level menu containing the submenus.
The Callback field is the routine (a MATLAB command, m-file script or function) that is executed when the User Tool menu item is selected. Refer to the reference page on "Callbacks: An Overview" in the MATLAB Help browser for more information on defining callbacks. There is a special case of defining the callback as a cell, such as
TOOLS{end}.SubMenu{end+0}.Callback = {'afpoly_usertool_template',1,2};
The first element of the callback cell is the name of a function or a function handle. The other elements of the callback cell define additional input arguments (e.g., 1 and 2 as above) that are passed to the function. Refer to the reference page on "Function Handle Callbacks" in the MATLAB Help browser for more information on defining callbacks in this manner. The template user tool callback function afpoly_usertool_template.m can also be found in the afpoly/tools folder in the IMAT installation location. The input arguments to the User Tool function are as defined in the user tool template function
function afpoly_usertool_template(happ,hcbo,arg1,arg2)
where happ is the handle of the AFPoly figure from which the User Tool callback was invoked, and hcbo is the handle of the menu object that invoked the User Tool callback. The remaining input arguments (arg1 and arg2) are passed from the User Tool callback definition.
TDATA is any MATLAB variable type, but most likely a structure, that contains some data or information that may be used and possibly modified by a User Tool m-file. TDATA is stored in the application figure and can be retrieved in a User Tool m-file with the getToolsData command. If the contents of TDATA are modified in a User Tool m-file, it can be stored back into the application with the setToolsData command. In this way, a User Tool can have some memory when being called repeatedly, or several User Tools could interact and share information with one another.
The functions in the afpoly/tools folder are delivered as text m-files and can be used as examples for user tools. Typing help tools at the MATLAB command prompt will display a list of the functions in the afpoly/tools folder. These functions contain help comments that describe their usage and these tools can be called directly from the MATLAB command line or from a user tool function.