creating-menus.md

Creating New Menu Types for Fly-Pie

There are two fundamental item types in Fly-Pie: Actions and Menus. Actions have an onSelect() method which is called when the user selects them; Menus can have child Actions or child Menus.

If you want to create a new Menu type for Fly-Pie, this guide is made for you! As an example, we will create a Menu which contains three actions, each of which shows a desktop notification when selected.

Before you start, you should read the Software Architecture Page to get an overview of the components of Fly-Pie. Then create a file src/common/menus/ExampleMenu.js with the following content. You should read the code, most of it is explained with inline comments!

//////////////////////////////////////////////////////////////////////////////////////////
//                               ___            _     ___                               //
//                               |   |   \/    | ) |  |                                 //
//                           O-  |-  |   |  -  |   |  |-  -O                            //
//                               |   |_  |     |   |  |_                                //
//                                                                                      //
//////////////////////////////////////////////////////////////////////////////////////////

// SPDX-FileCopyrightText: Your Name <your@email.com>
// SPDX-License-Identifier: MIT

"use strict";

// This is required for localization support.
const _ = imports.gettext.domain("flypie").gettext;

// We have to import the Main module optionally. This is because this file is included
// from both sides: From prefs.js and from extension.js. When included from prefs.js, the
// Main module is not available. This is not a problem, as the preferences will not call
// the createItem() methods below; they are merely interested in the menu's name, icon
// and description.
let Main = undefined;

try {
  Main = imports.ui.main;
} catch (error) {
  // Nothing to be done, we're in settings-mode.
}

// Some extension-local imports we will use further down.
import { debug } from "../utils.js";
import { ItemClass } from "../ItemClass.js";

//////////////////////////////////////////////////////////////////////////////////////////
// This simple example menu contains three actions, each of which shows a desktop       //
// notification when selected.                                                          //
//////////////////////////////////////////////////////////////////////////////////////////

// This should be always named 'menu'.
var menu = {
  // There are two fundamental item types in Fly-Pie: Actions and Menus. Actions have an
  // onSelect() method which is called when the user selects the item, Menus can have
  // child Actions or Menus. In this example we create a Menu!
  class: ItemClass.MENU,

  // This will be shown in the add-new-item-popover of the settings dialog.
  // It should be translatable.
  name: _("ExampleMenu"),

  // This is also used in the add-new-item-popover.
  icon: "accessories-clipboard",

  // Translators: Please keep this short.
  // This is the (short) description shown in the add-new-item-popover.
  subtitle: _("Foo."),

  // This is the (long) description shown when an item of this type is selected.
  description: _("Bar bar bar bar."),

  // Menus can also have a config field like actions. See the documentation on how-to
  // create custom actions for details. This example menu does not use a config field.
  // config: { ... }

  // This will be called whenever a menu is opened containing an item of this kind.
  createItem: () => {
    // This will be printed to the log when a menu is opened containing such an item.
    debug("ExampleMenu Created!");

    // This method should return an object containing a 'children' array. Each array
    // element has to have a 'name' and an 'icon'. The onSelect() function will be
    // called when the user selects the corresponding item.
    return {
      children: [
        {
          name: _("First Item"),
          icon: "♈",
          onSelect: () => {
            Main.notify(_("♈ Selected!"), _("This is the first item!"));
          },
        },
        {
          name: _("Second Item"),
          icon: "♎",
          onSelect: () => {
            Main.notify(_("♎ Selected!"), _("This is the second item!"));
          },
        },
        {
          name: _("Third Item"),
          icon: "♐",
          onSelect: () => {
            Main.notify(_("♐ Selected!"), _("This is the third item!"));
          },
        },
      ],
    };
  },
};

Once this file is in place, you just need to add the new Action to the src/common/ItemRegistry.js. To do this, add the following line to the other, similar-looking lines in getItemTypes().

ExampleMenu: menus.ExampleMenu.menu,

Finally you can restart GNOME Shell with Alt + F2, r + Enter (or logout / login on Wayland). If you now open Fly-Pie's Menu Editor, you can add your new Menu! It will not have any configuration options, as we decided not to add the data property above. You can have a look at the RecentFiles.js menus for an example using a data property.

That's it. Now you can start modifying the code!

Creating New Action Types Index Changelog