MATLAB setup

Requires the following resource:

  • MATLAB Simian GUI release toolbox file.

Setup steps:

  1. Install the toolbox by double-clicking it in the MATLAB file browser or use matlab.addons.install. Refer to section Simian GUI contents for more information about its contents.

Note In all code presented in the documentation, v3_0_1 must be substituted with the version number for the actual release that is used. It is recommended to use dynamic version numbers.

Testing your setup

You can test your environment setup by running the following commands in MATLAB:

form = simian.gui_v3_0_1.Form();

If you get a Form object, your environment is setup correctly. You should also be able to start the BallThrower example locally by running the following command:

simian.local_v3_0_1.Uiformio("simian.examples_v3_0_1.ballthrower");

If you get an error, you can check this against these error messages and solutions:

  • Unable to resolve the name simian.gui_v3_0_1.Form. Ensure that the the simian-gui folder is on the MATLAB path and that the version in the namespace corresponds with your Simian GUI version.
  • Unable to resolve the name simian.local_v3_0_1.Form. Ensure that the the simian-local folder is on the MATLAB path and that the version in the namespace corresponds with your Simian GUI version.
  • Unable to resolve the name 'simian.examples_v3_0_1.ballthrower' Ensure that the the simian-examples folder is on the MATLAB path and that the version in the namespace corresponds with your Simian GUI version.

Simian GUI contents

An overview of archive contents is shown in the figure below.

  • simian-examples Folder containing the included examples.
    • +simian
      • +examples_v3_0_1
        • @BallThrower Class implementing the ball throwing model.
        • +ballthrower The BallThrower application package. It contains the guiInit.m and guiEvent.m function files that define the user interface of the application.
        • +treemap The Tree map application package. It contains the guiInit.m and guiEvent.m function files that define the user interface of the application.
  • simian-gui Folder containing the Simian GUI code.
    • +simian
      • +gui_v3_0_1 Simian GUI package where the name contains the version number. When you use Simian GUI you must ensure that the correct name is used. Refer to the deployment section for tips on making this easier.
    • config.json File containing the version number of the front-end.
  • simian-local Folder containing the code to run Simian GUI locally.
    • +simian
      • +local_v3_0_1 Simian Local package where the name contains the version number. When you use Simian GUI you must ensure that the correct name is used. Refer to the deployment section for tips on making this easier.
    • html Folder containing the front-end build for uihtml.
  • Contents.m Simian GUI version number.
  • install.p Script that sets up Simian GUI for running applications locally.
  • GettingStarted.mlx Help text for the toolbox.

Working with multiple releases

It is possible to work with, and deploy, multiple Simian GUI applications simultaneously, even if they use different Simian GUI releases. To facilitate this, the version numbers are included in the package namespace.

Therefore, the recommended approach is to dynamically select the Simian GUI package in your code.

  1. Create a function that returns the required version number, e.g.:

    function simianGui = getSimianGui()
    simianGui = "gui_v3_0_1";
end

  2. Use the function to import or call the correct version of Simian GUI:

    % Direct calls:
nr = simian.(getSimianGui()).component.Number("myKey");

% Importing:
import("simian." + getSimianGui() + ".*");
nr = component.Number("myKey");

In order to update to a new release of Simian GUI, you only have to update the string returned by this function. All other files remain unchanged.

Alternatively, when not referencing the package dynamically, all calls to Simian GUI need to be updated to the new version. This may lead to a large number of changes. Extra care is required when using version control and multiple braches are under development simultaneously.

In order to update your code to a newer Simian GUI release, use the updateVersion function included in the Simian GUI package. This function edits the version number in all m-files in a given folder and its sub-folders. For example: simian.gui_v3_0_1.updateVersion("C:\Applications\MyApp"). Save all m-files and make a back-up before you run this function!