3. Custom Menu

A custom menu provides the capability to easily insert predefined custom content onto a canvas from the finger menu. You can do a particular action or insert PDFs, images, browsers, videos, and notes. Custom menu also supports sub-menus for easier categorisation. For example, you can have one sub-menu for PDFs and another one for videos, or you can have one sub-menu for each project you are working on.

You can insert an item or a group of items with the tap of a button. It is possible to predefine the size, position, color and other attributes that are relevant to the items.

Custom menu

Custom menu in the finger menu.

Setting up a custom menu consists of two parts. The contents of the menu are specified in a separate configuration file in YAML format (see Defining a custom menu). This custom menu configuration file must also be specified in the Canvus client configuration file mt-canvus.ini (see Enabling a custom menu).

3.1. Enabling a custom menu

The custom menu is defined in a separate YAML that must be referenced from mt-canvus.ini.

[canvas]
; Custom menu file in YAML format used to display a user-defined menu
; structure on the finger menu.
; DEFAULT: empty
; NOTE: Backslashes in paths need special handling on Windows computers.
;       Replace each \ with \\ or /.
custom-menu=/path/to/menu.yml

Note

MT Canvus must be restarted after this setting has been modified.

3.2. Defining a custom menu

The contents of the custom menu are defined using a separate YAML file. See below for an example custom menu definition:

tooltip: 'Top-level menu'
icon: 'icons/custom.png'
items:
  - tooltip: 'Open sub-menu 1'
    icon: 'icons/submenu.png'
    items:
    - tooltip: 'Note'
      icon: 'icons/note.png'
      actions:
        - name: 'create'
          parameters:
            type: note
            text: 'Note from sub menu1'
            color: 'DarkSeaGreen'
    - tooltip: 'Video'
      icon: 'icons/video.png'
      actions:
        - name: 'create'
          parameters:
            type: video
            source: 'docs/REDWOOD - Night Garden.mp4'
            title: 'Video from sub menu1'

Tip

To make editing the custom menu easier, any changes in the YAML file are automatically reloaded. It is not necessary to restart MT Canvus after making changes. Just remember to reopen the finger menu because MT Canvus fetches the content of the YAML file when the finger menu is opened.

The custom menu is specified in YAML format. The custom menu consists of menu-items which can be nested in a tree hierarchy.

3.4. Actions

Actions are used to specify how content is created from a custom menu. Activating a menu-item can trigger one or more actions. The actions are specified using the actions attribute of a menu-item. The attribute can be used to define a list of actions to perform when the menu-item is activated.

The actions are specified by name and a list of parameters. The list of valid parameters for each action depends on the action itself. The names of valid actions are shown below:

Table of valid action names
Name Description
create Creates new content on the canvas
open-folder Opens a folder widget to given folder

3.4.1. Create

The create action can be used to create a canvas item on the canvas.

- name: 'create'
    parameters:
      type: browser
      url: 'https://www.bbc.co.uk/weather'

The following parameters are common for every create action:

type

The type of content to create from the action. The valid types are:

  • note - creates a new note
  • PDF - creates a new PDF
  • video - creates a new video
  • image - creates a new image
  • browser - creates a new browser
coordinate-system

Specifies the coordinate system in which size, scale, and location are defined in. Valid values are:

  • viewport (default) - the action is specified in the workspace’s current viewport coordinates
  • canvas - the action is specified in absolute canvas coordinates
coodinate-offset

Specifies an offset for the location. Valid values are:

  • none - no offset
  • finger - the location of the finger activating the menu-item
  • menu (default) - the center location of the finger menu
origin
Specifies the origin of the created item. Specified as two decimal values for x and y coordinate respectively. An origin of 0 0 is the upper-left corner of the widget, 0.5 0.5 is the center of the widget and 1 1 is the bottom-right corner of the widget. The default is 0 0.
location
Location of the created item specified in coordinate-system offset by coordinate-offset. Specified as two values for x and y coordinate respectively. Affected by origin.
size
Size of the created item. Specified as two values for width and height. CSS units can be used, like 50% 50% or 100px 100px. Percentage values are relative to the specified coordinate-system.
scale
Scale of the item relative to the specified coordinate-system. Default value is 1.
pinned
Should the created item be pinned or not? Specified as boolean, true or false. The default value is false.

Additional parameters depend on the type of the action.

3.4.1.1. Creating images

If the type of a create action is image, the following additional parameters are available:

source
Relative or absolute path to the image filename on the host computer. Relative paths are relative to the custom menu YAML file.
title
Title of the image.

3.4.1.2. Creating videos

If the type of the create action is video, the following additional parameters are available:

source
Relative or absolute path to the video filename on the host computer. Relative paths are relative to the custom menu YAML file.
title
Title of the video.

3.4.1.3. Creating PDFs

If the type of the create action is pdf, the following additional parameters are available:

source
Relative or absolute path to the PDF filename on the host computer. Relative paths are relative to the custom menu YAML file.
title
Title of the PDF.

3.4.1.4. Creating web browsers

If the type of the create action is browser, the following additional parameters are available:

url
The URL for the web browser.
title
Title of the web browser.

3.4.1.5. Creating notes

If the type of the create action is note, the following additional parameters are available:

text
Text shown in the note.
title
Title of the web browser.
color
Background color of the note.

3.4.2. Open folder

To open a specific folder from the host computer, use the open-folder action.

- name: 'open-folder'
    parameters:
      source: '/home/multi/Big Video Files'
      title: 'My Videos'

The following parameters can be defined for the open-folder action:

source
Relative or absolute path to the folder to open on the host computer. Relative paths are relative to the custom menu YAML file.
title
Title of the folder to open.