Adding new functions to MUPET GUI

This page concerns current/future developers of MUPET. If you're strictly a user, you can skip this page.

Motivation

Modern software repos inspire modular code arrangement of the source. GUI building systems like Qt (C++), Swing (Java) have a sophisticated system of locating the functions (callbacks) to invoke following a GUI action like a button press, scroll down, window resize etc. Matlab on the other hand, despite its offering of a system to build complex GUI applications, enforces that 'all' code is in a single script (.m file, linked to the app). But this is not a blockade for developers. This page discusses how to modularize the single script file for an app using the GUIDE tool.

Step 1: Choose a function that you want to modularize 'out' of the unified app script file (mupet.m, in this example). Please see the picture below, how the function 'refresh_repertoires' is selected to be moved out of the app script file.

Step 2: Choose the new location for your chosen function. Create a new script file and save your function from step 1 into the chosen location. Below, we can see that the function 'refresh_repertoires' has been moved to its own script file - refresh_repertoires.m

NOTE: There are a few functions that should not be moved out of your app script file. These functions have a function signature like the ones below (replace app with your app's name to find them):

1. app(varargin)
2. appOpening_Fcn(hObject, eventdata, handles, varargin)
3. app_OutputFcn(hObject, eventdata, handles)
4. app_initialize(handles)
5. appFigure_CreateFcn(hObject, eventdata, handles) ......

This list can be longer. To be sure a function can be removed for the purpose of modularization, cut it out of your .m and validate if the app works without any errors.

Step 3: Now we need to tell the .fig file where to find the intended functions that are invoked after a GUI event is registered. To do this: first, open the .fig file via the GUIDE tool (Right-click on the .fig file and choose "Open in GUIDE" ) then right click on the GUI element you want to link your modularized function to (in our case, the GUI element is the button with label "refresh" in 'repertoires' section in mupet.fig and the function it should invoke is 'refresh_repertoires' that we modularized in Step 1 and Step 2) and choose "Property Inspector".

Step 4: We need to change the function signature against the entries "Callback","CreateFcn" and "DeleteFcn" for a GUI element in the property inspector. The change will allow MATLAB's GUI Engine to locate the new modularized function file, technically called a callback. Below is the image, notice the callback for the case being discussed ie refresh button in repertoires section.

The value for the 'Callback' is @(hObject,eventdata)mupet('refresh_repertoires_Callback',hObject,eventdata,guidata(hObject))

Let's dissect the function signature -

1. (hObject,eventdata) provides the return type
2. mupet('refresh_repertoires_Callback',hObject,eventdata,guidata(hObject)) - tell MATLAB's GUI Engine to invoke the function 'refresh_repertoires_Callback' within mupet.m file (which happens to be our app.m). This also tells the GUI that 'refresh_repertoires_Callback' takes the arguments - (hObject,eventdata,guidata(hObject)). So if we were to build the function from reading the callback value it would be - refresh_repertoires_Callback(hObject,eventdata) in our codebase. Note that 'guidata(hObject)' is injected automatically by the MATLAB GUI Engine and shall not be an argument in the function definition.

Now let's look at how to modify this to plug our modularized function to the 'refresh' button:

The new callback reads: @(hObject,eventdata)refreshRepertoires_Callback(hObject,eventdata,guidata(hObject))

Notice how the return type and arguments to the function remain the same. What's changed is mupet('...') is not enclosing the function anymore.

This way we are telling the GUI Engine to look for the function @(hObject,eventdata)refreshRepertoires_Callback(hObject,eventdata,guidata(hObject)) not inside mupet.m (app.m for our example case) but in all locations accessible to MATLAB.

To make our modularized functions accessible to MATLAB, make sure that the directory(ies) housing the modularized function's script file is 'Added to Path' for Matlab. A smart way to do this adds a script to the appFigure's Figure_CreateFcn to add the paths of the directories holding the modularized functions when the GUI is created. In the picture below, the function 'figure1_CreateFcn' adds to the path the directories that contain the modularized functions.