Skip to content

Commit

Permalink
🔀 Merge pull request #94 from Schneegans/feature/custom-config-widgets
Browse files Browse the repository at this point in the history
  • Loading branch information
@Schneegans
Schneegans authored Mar 14, 2021
2 parents 12e5e91 + bcb941d commit ff88ed6
Show file tree
Hide file tree
Showing 16 changed files with 859 additions and 846 deletions.
414 changes: 43 additions & 371 deletions assets/settings.ui
View file

Large diffs are not rendered by default.

66 changes: 44 additions & 22 deletions docs/creating-actions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@ Actions have an `onSelect()` method which is called when the user selects them;
If you want to create a new Action type for Fly-Pie, this guide is made for you!
As an example, we will create an Action which shows a notification with a user-defined message whenever it is selected.

First, create a file `src/common/actions/ExampleAction.js` with the following content.
Before you start, you should read the [Software Architecture Page](software-architecture.md) to get an overview of the components of Fly-Pie.
Then create a file `src/common/actions/ExampleAction.js` with the following content.
You should read the code, most of it is explained with inline comments!

```javascript
Expand Down Expand Up @@ -41,9 +42,10 @@ try {
}

// Some extension-local imports we will use further down.
const Me = imports.misc.extensionUtils.getCurrentExtension();
const utils = Me.imports.src.common.utils;
const ItemRegistry = Me.imports.src.common.ItemRegistry;
const Me = imports.misc.extensionUtils.getCurrentExtension();
const utils = Me.imports.src.common.utils;
const ItemRegistry = Me.imports.src.common.ItemRegistry;
const ConfigWidgetFactory = Me.imports.src.common.ConfigWidgetFactory.ConfigWidgetFactory;

//////////////////////////////////////////////////////////////////////////////////////////
// This simple example action shows a desktop notification when selected. The text of //
Expand Down Expand Up @@ -72,23 +74,40 @@ var action = {
// This is the (long) description shown when an item of this type is selected.
description: _('Bar bar bar bar.'),

// Items of this type have an additional data property which can be set by the user. The
// data value chosen by the user is passed to the createItem() method further below.
data: {

// The data type determines which widget is visible when an item of this type is
// selected in the settings dialog.
type: ItemRegistry.ItemDataType.TEXT,

// This is shown on the left above the data widget in the settings dialog.
name: _('Message'),

// Translators: Please keep this short.
// This is shown on the right above the data widget in the settings dialog.
description: _('Shown when this is activated.'),

// This is be used as data for newly created items.
default: _('Hello World!'),
// Items of this type have a custom user setting for the text to show in the
// notification. The 'config' property below defines how this data can be set.
config: {

// This is used as data for newly created items of this type. You can add any
// number of properties to this defaultData object. Just make sure that you use
// the same properties in the updateCallback further below.
defaultData: {message: _('Hello World!')},

// This is called whenever an item of this type is selected in the menu editor.
// It should return a Gtk.Widget which will be shown in the sidebar of the menu
// editor. The currently configured data object will be passed as first parameter,
// the second parameter is a callback which should be fired whenever the user
// changes something in the widgets.
getWidget(data, updateCallback) {

// Our data parameter *should* be an object containing a single "message"
// property (like the defaultData above). In order to prevent a crash
// when that's not the case (e.g. when the user edited the menu configuration
// by hand and made a mistake) we check this here.
let message = data.message || '';

// You can use Gtk here to create any widget you want. In this tutorial we will
// use the ConfigWidgetFactory to do this job. Feel free to look into this method
// to learn the details.
return ConfigWidgetFactory.createTextWidget(
_('Message'), // Shown on the left above the text entry.
_('Shown when this is activated.'), // Shown on the right above the text entry.
message, // The initial value of the entry.
(message) => { // Called whenever the text is modified.
updateCallback({message: message}); // We call the updateCallback with a new
} // data object.
);
}
},

// This will be called whenever a menu is opened containing an item of this kind.
Expand All @@ -97,10 +116,13 @@ var action = {
// This will be printed to the log when a menu is opened containing such an action.
utils.debug('ExampleAction Created!');

// Handle invalid data.
let message = data.message || '';

// The onSelect() function will be called when the user selects this action.
return {
onSelect: () => {
Main.notify(_('ExampleAction Selected!'), data);
Main.notify(_('ExampleAction Selected!'), message);
}
};
}
Expand Down
11 changes: 6 additions & 5 deletions docs/creating-menus.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@ Actions have an `onSelect()` method which is called when the user selects them;
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.

First, create a file `src/common/menus/ExampleMenu.js` with the following content.
Before you start, you should read the [Software Architecture Page](software-architecture.md) 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!

```javascript
Expand Down Expand Up @@ -72,9 +73,9 @@ var menu = {
// This is the (long) description shown when an item of this type is selected.
description: _('Bar bar bar bar.'),

// Menus can also have a data field. See the documentation on how-to create custom
// actions for details. This example menu does not use a data field.
// data: { ... }
// 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: () => {
Expand Down Expand Up @@ -117,7 +118,7 @@ Once this file is in place, you just need to add the new Action to the `src/comm
To do this, add the following line to the other, similar-looking lines in `getItemTypes()`.

```javascript
ExampleMenu: actions.ExampleMenu.menu,
ExampleMenu: menus.ExampleMenu.menu,
```

Finally you can restart GNOME Shell with <kbd>Alt</kbd> + <kbd>F2</kbd>, <kbd>r</kbd> + <kbd>Enter</kbd> (or logout / login on Wayland).
Expand Down
26 changes: 15 additions & 11 deletions docs/dbus-interface.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,13 +50,17 @@ gdbus call --session --dest org.gnome.Shell \
"name": "Up", \
"icon": "🔼️", \
"type": "Shortcut", \
"data": "<Primary><Alt>Up" \
"data": { \
"shortcut": "<Primary><Alt>Up" \
} \
}, \
{ \
"name": "Down", \
"icon": "🔽️", \
"type": "Shortcut", \
"data": "<Primary><Alt>Down" \
"data": { \
"shortcut": "<Primary><Alt>Down" \
} \
} \
] \
}'
Expand Down Expand Up @@ -86,20 +90,20 @@ The table below lists all possible item types. Some of the types require that th

| Actions | Default `data` | Description |
|------------|-----------------------|-------------|
| **`"Command"`** | `""` | This action executes a command given in `data`. This is primarily used to open applications but may have plenty of other use cases as well. |
| **`"DBusSignal"`** | `""` | This action does nothing on its own. But you can listen on the D-Bus for its activation. This can be very useful in custom menus opened via the command line. The string given in `data` will be passed as `itemID` to the `OnHover`, `OnUnhover` and `OnSelect` signals. Below this table you will find an example! |
| **`"File"`** | `""` | This action will open a file given with an absolute path in `data` with your system\'s default application. |
| **`"InsertText"`** | `""` | This action copies the text given in `data` to the clipboard and then simulates a Ctrl+V. This can be useful if you realize that you often write the same things. |
| **`"Shortcut"`** | `""` | This action simulates a key combination when activated. For example, this can be used to switch virtual desktops, control multimedia playback or to undo / redo operations. `data` should be something like `"<Primary>space"`. |
| **`"Uri"`** | `""` | When this action is activated, the URI given in `data` is opened with the default application. For http URLs, this will be your web browser. However, it is also possible to open other URIs such as `"mailto:[email protected]"`. |
| **`"Command"`** | `{"command":""}` | This action executes a command given in `data`. This is primarily used to open applications but may have plenty of other use cases as well. |
| **`"DBusSignal"`** | `{"id":""}` | This action does nothing on its own. But you can listen on the D-Bus for its activation. This can be very useful in custom menus opened via the command line. The ID string given in `data` will be passed as `itemID` to the `OnHover`, `OnUnhover` and `OnSelect` signals. Below this table you will find an example! |
| **`"File"`** | `{"file":""}` | This action will open a file given with an absolute path in `data` with your system\'s default application. |
| **`"InsertText"`** | `{"text":""}` | This action copies the text given in `data` to the clipboard and then simulates a Ctrl+V. This can be useful if you realize that you often write the same things. |
| **`"Shortcut"`** | `{"shortcut":""}` | This action simulates a key combination when activated. For example, this can be used to switch virtual desktops, control multimedia playback or to undo / redo operations. `data` should be something like `{"shortcut":"<Primary>space"}`. |
| **`"Uri"`** | `{"uri":""}` | When this action is activated, the URI given in `data` is opened with the default application. For http URLs, this will be your web browser. However, it is also possible to open other URIs such as `{"uri":"mailto:[email protected]"}`. |
| **Menus** | | |
| **`"CustomMenu"`** | _not used_ | Use the `"children"` property to add as many actions or submenus as you want! |
| **`"Bookmarks"`** | _not used_ | This menu shows an item for the trash, your desktop and each bookmarked directory. |
| **`"Devices"`** | _not used_ | This menu shows an item for each mounted volume, like USB-Sticks. |
| **`"Favorites"`** | _not used_ | This menu shows the applications you have pinned to GNOME Shell's Dash. |
| **`"FrequentlyUsed"`** | `"7"` | This menu shows a list of frequently used applications. You should limit the maximum number of shown applications to a reasonable number given in `data`. |
| **`"FrequentlyUsed"`** | `{"maxNum":7}` | This menu shows a list of frequently used applications. You should limit the maximum number of shown applications to a reasonable number given in `data`. |
| **`"MainMenu"`** | _not used_ | This menu shows all installed applications. Usually, this is very cluttered as many sections contain too many items to be used efficiently. You should rather setup your own menus! This menu is only available if the typelib for GMenu is installed on the system. Usually the package is called something like `gir1.2-gmenu-3.0`. |
| **`"RecentFiles"`** | `"7"` | This menu shows a list of recently used files. You should limit the maximum number of shown files to a reasonable number given in `data`. |
| **`"RecentFiles"`** | `{"maxNum":7}` | This menu shows a list of recently used files. You should limit the maximum number of shown files to a reasonable number given in `data`. |
| **`"RunningApps"`** | _not used_ | This menu shows all currently running applications. This is similar to the Alt+Tab window selection. As the entries change position frequently, this is actually not very effective. |
| **`"System"`** | _not used_ | This menu shows an items for screen-lock, shutdown, settings, etc. |

Expand Down Expand Up @@ -157,7 +161,7 @@ gdbus call --session --dest org.gnome.Shell \
{ \
"name": "Cat", \
"icon":"🐈", \
"data": "cat!!" \
"data": {"id": "cat!!"} \
} \
] \
} \
Expand Down
Loading

0 comments on commit ff88ed6

Please sign in to comment.