Creating Menus for Equo Applications

One of the features of the Equo Framework is its capability to incorporate custom natives menues.

Equo offers several possibilities to add new menus to your applications:

  • Using the EquoApplicationBuilder, that will build a static menu.

@Override
public EquoApplicationBuilder buildApp(EquoApplicationBuilder appBuilder) {
  return appBuilder.withUI("index.html")
    .withMainMenu("Equo")
      .addMenuItem("Static Menu")
      .onClick(new Runnable() {

          @Override
          public void run() {
            try {
              MessageDialog.openInformation(null, "info dialog", "Clicked button!");
            } catch (Exception e) {
              e.printStackTrace();
            }
          }
        })
    .start();
}
...
  • Creating an EquoMenu and adding it dynamically.

...

final Menu model1 = Menu.create();

model1.withMainMenu("Equo").addMenuItem("Dynamic menu")
  .onClick(new Runnable() {

    @Override
    public void run() {
      System.out.println("Clicked button!");
    }
  });

return appBuilder.withUI("index.html").withMainMenu("Menu Test").addMenuItem("Change menu").onClick(new Runnable() {
  @Override
  public void run() {
    model1.setApplicationMenu();
  }
}).start();
import { Menu } from "@equo/equo-application-menu";
...

  Menu.create()
    .withMainMenu("Equo")
      .addMenuItem("Dynamic menu")
      .onClick(() => { console.log("Your Equo app is awesome!") })
    .setApplicationMenu();

...

All of the above options for adding new menus to your applications offer the same methods to build a menu. You can read about EquoMenu on its Java Documentation and Javascript API Documentation

Menu variants

Within the menus there are three types of variants:

  1. Main menu: a top-level menu. This are the ones visible in the top application bar (1). They are created with the method withMainMenu.

  2. Menu: a common menu inside another menu (2). They are created with the method addMenu.

  3. Menu item: the menu elements that have defined actions to be executed when clicked on (3). They are created with the method addMenuItem.

menu variants

Creating a Menu

Here we will show how to create a new menu using just some of the available methods. As we have said before, all the options presented for the construction of menus for Equo applications share the same name in their methods, so this example will always be functional.

  • Simple menu

...
  withMainMenu("Equo")
    .addMenuItem("Dynamic menu")
    .onClick(() => { console.log("Your Equo app is awesome!") })
    .withShortcut("M1+Q")
    .withIcon("/PATH/TO/YOURIMAGE")
    .setApplicationMenu()
  • Complex menu

...
  withMainMenu("Equo")
    .addMenuItem("Dynamic menu")
    .onClick(() => {  console.log("Your Equo app is awesome!") })
    .withShortcut("M1+Q")
    .withIcon("/PATH/TO/YOURIMAGE")
    .addMenu("Group menu")
      .addMenuItem("Other dynamic menu")
      .onClick(() => {  console.log("Your Equo app is awesome from other menu") })
      .withShortcut("M1+T")
      .withIcon("/PATH/TO/YOURIMAGE")
    .setApplicationMenu()

For more information about how to use shortcuts and icons read Key sequences for shortcuts and Menu icons.

Key sequences for Menu shortcuts

In an Equo application, shortcuts are defined by key sequences. A key sequence consist of one or more key strokes. Key strokes consist of one or more keys held down at the same time. There should be zero or more modifier keys, and one other key. The keys are separated by the + character.

Equo recognizes the modifiers M1, M2, M3, and M4. The "M" modifier key is a platform-independent way of representing keys. Review the table below to understand what the "M" modifier represents in each platform:

Modifier Key macOS Other platforms

M1

COMMAND

CTRL

M2

SHIFT

SHIFT

M3

OPTION

ALT

M4

CTRL

Undefined

The actual key is generally specified simply in uppercase. For example F or J, are examples of such keys.

Using Menu icons

To use icons in your menus you will need to take these aspects into account:

  • Add your images to resource folder and use the relative path to your image.

  • Use .png, .jpg, .bmp or .gif extensions.

  • Use an image size of 15px*15px.

For example, we will use the redo and undo images to better explain the following code.

.
├── pom.xml
└── src
    ├── main
    │   ├── resources
   ...  |   └── icons
       ...      ├── redo.png
                └── undo.png

Example code.

...
withMainMenu("Edit")
  .addMenuItem("Undo").withIcon("icons/undo.png")
  .addMenuItem("Redo").withIcon("icons/redo.png")
...

menu icons