DIR2MENU populates a menu by selectively replicating a folder structure.
If populating a figure menu (the default) a new figure will be created
and its handle returned. If populating a uicontextmenu, the handle of the
menu will be returned and may be used to set the uicontextmenu property
of a graphic object explicitly using the set function.
Examples:
HANDLE=DIR2MENU(PARENTDIRECTORY)
HANDLE=DIR2MENU(PARENTDIRECTORY, OPTIONS)
HANDLE=DIR2MENU(PARENTDIRECTORY, TYPE, OPTIONS)
PARENTDIRECTORY is the folder to be replicated
TYPE, if supplied, is a string: either 'figure' or 'uicontextmenu'.
Defaults to 'figure'.
OPTIONS (if supplied) is a cell array of menu properties that will be
passed by DIR2MENU to the MATLAB uimenu function when it is called.
DIR2MENU returns the handle of the figure or uicontextmenu whos menu has
been populated.
As the menu is created dynamically at run time, DIR2MENU removes the need
to edit a GUI when a new function is added to an application. They
can be added instead by using the system directory/file manager and the
folder/file naming convention described below.
--------------------------------------------------------------------------
CHANGE (Dec '06):
menu callbacks now receive hObject and EventData as the first two
arguments.
If your menu_* files tested for nargin==0, they will now need to test
for nargin==2. To reverse this change for backwards compatibility,
edit PopulateSubMenus (see comments in the function)
ADDED:
Libraries of functions stored outside of the PARENTDIRECTORY
can now be included using the 'external_' keyword as a prefix to an
m-file name.
This allows a single copy of a function library to be shared by several
applications calling dir2menu- reducing code cloning and therefore
helping with file management. This is described further below.
Tags
To help keep track of what's where, each uimenu item's Tag now contains
the folder/function name for the relevant callback(s) with full path
information.
UserData
Calls to the callback routine with a zero input can now return data in
the third output argument. These data are placed in the UserData property
for the menu item. This might be used e.g. to return an image which can
subsequently be placed in a uipanel toolbar
--------------------------------------------------------------------------
DIR2MENU(PARENTDIRECTORY) does the following:
(1). Adds all folders and subfolders of PARENTDIRECTORY to the MATLAB
search path.
(2). If type=='figure:
Creates a figure window populated initially with the default MATLAB
figure menu
If type=='uicontextmenu'
Create a uicontextmenu, adds it to the current figure (returned by gcf)
and populates it from the directory
(3). Analyzes the directory tree of PARENTDIRECTORY. Folders, subfolders
and executable files prefixed by "menu_" are added to the menu
tree in a position that corresponds to their position in the directory
tree. The menu items' labels are the same as the folder names but with the
"menu_" prefix removed. The menu is populated recursively, so you can
nest to any depth of folder/subfolder => menu/menulist organization.
In addition, if type=='figure':
"File", "Edit" and "View" items are grouped to the left of
the menu bar and "Insert", "Tools", "Desktop", "Window" and "Help" items
are grouped on the right. User supplied "menu_" prefixed items are placed
between these groups.
If present, the File, Edit, View etc folder names should not be prefixed
with "menu_".
(4). Drop down menu items may also be grouped by placing them in a folder
prefixed with "group_". These will appear with lines above and below
them.
(5). For executable files (i.e. m- or mex files), the menu item's
CallBack property is set to invoke the function. The handle of the
item and an additional MATLAB reserved variable will each be passed
implicitly by MATLAB as the first two inputs to the function(equivalent
to hObject and EventData in GUIDE-generated GUIs. EventData
will be empty - as of R2006b).
It is assumed that user data that will be passsed using the figure's
'UserData' property or application data area.
During menu creation, the functions are called with a zero input
e.g. [flag, string, itemdata]=menu_myFunc(0).
If flag==true, the menu item wil be enabled. The returned string is used
for the menu item's label. itemdata will be added to the menu item's
UserData property.
(6). When type=='figure', if the File, Edit, View, Insert, Tools,
DeskTop, Window and Help menus are empty, dir2menu leaves them as
populated by the standard MATLAB call to h=figure(). If not, the menus
are replaced by those derived from the folder tree.
Take the following example directory tree:
MyFolder.....
.
....File
. .
. ......menu_Open.m
. .
. ......menu_Import
. . .
. . ....menu_ImportAVI.m
. . .
. . ....menu_ImportWAV.m
. .
. ......group_zzzPrint
. .
. ....menu_Print.m
. .
. ....menu_PrintPreview.m
.
....menu_User
.
...menu_UserFunction.m
.
...external_ExternalFolder.m
.
.
DIR2MENU('MYFOLDER') will populate the File menu with:
1. An item labeled with the string returned by [flag, string]=menu_Open(0)
2. An item labeled "Import", which will activate a lower level menu
containing two items, labeled according to the output returned by calls
to menu_ImportAVI(0) and menu_ImportWAV(0). Selecting the items will call
menu_ImportAVI(hObject, EventData) and menuImportWAV(hObject, EventData)
respectively.
3. A print group will appear in the File menu containing two items
labeled as before with the output of menu_Print(0) and
menu_PrintPreview(0).
4. Create a "User" item on the menu bar and populate its drop down list
in this case with a two items: one labeled with the output from a call to
menu_UserFuntion(0) and the second from a call to
external_ExternalFolder() - see below for further details of
'external_' prefixed m-files.
5. Leave the standard Edit, View etc menus active
The sequence of the items in any menu list will be alphabetical by
folder/file name. As executable file names and group names are not used
as labels, you can force an order by prefixing the names with letters e.g.
in the example above, the "group_zzzPrint" list will appear at the bottom
of the File menu. Note that all names are cast to lower case before
sorting.
Any outputs from the called functions can be placed in the figure window's
UserData property or application data area e.g. for the menu_ImportAVI
function above, the function might look as follows:
function varargout=menu_ImportAVI(varargin)
if nargin==0 and varargin{1}==0
varargout{1}=true;
varargout{2}='Microsoft AVI file';
varargout{3}=imread('icon.png');
return;
end
....
....
if nargin>=2 % ***see Note
[filename pathname]=uigetfile('*.avi')
mov = aviread([pathname filesep filename]);
[h, figurehandle]=gcbo;
setappdata(figurehandle,'MyData',mov);
end
....
....
return
end
***Note: in early DIR2MENU versions, no arguments were passed when a
menu_ file was called. Now two arguments are passed implicitly by MATLAB:
hObject: the menu item's handle (as returned by gcbo)
EventData: presently empty (and MATLAB reserved)
-------------------------------------------------------------------------
Using the 'external_' prefix:
If an m_file is prefixed by 'external_', it will be called in much the
same way as a 'menu_' prefixed m-file (but in this case, without the
zero input argument). Like an menu_ m-file, an external_*.m file should
return a logical flag and the menu item label. It should, in addition,
return a string which is the full path and name of a folder lying
outside of PARENTDIRECTORY. This folder will be treated as
though it were a menu_ folder inside PARENTDIRECTORY located at the
same place in the directory tree as the 'external_' file.
e.g.
function varargout=external_MyExternalFunctions(varargin)
varargout{1}=true; % or false after a test
varargout{2}='MyLabel'; % appears on the menu
varargout{3}='c:\Program Files\MATLAB\2006b\work\CommonFunctionsToolbox';
return
end
The CommonFunctionsToolbox can be shared by several main functions each
of which calls DIR2MENU. The CommonFunctionsToolbox folder will be
treated as though it were a menu_ folder. It may therefore contain menu_
routines and folders/subfolders, group_ folders (and also further external_
m-files as everything is done recursively. Note the external_ file should
not return its own folder (or an ancestor of it), or you will enter an
infinite recursion).
DIR2MENU automatically adds CommonFunctionsToolbox and all its subfolders
to the MATLAB path. The CommonFunctionsToolbox folder need not be on the
same disc as MATLAB - or the same machine if networked.
--------------------------------------------------------------------------
See also:
UIMENU, FIGURE, GCBO, SETAPPDATA, GETAPPDATA, GUIDE,
together with
"Function Handle Callback Syntax" in the Help Search box
--------------------------------------------------------------------------
Author: Malcolm Lidierth 09/06
Copyright © The Author & King's College London 2006-2007
--------------------------------------------------------------------------