Extend the custom Jump List API
Add `app.getJumpListSettings()` and `app.setJumpList(callback)` that make it possible to fully customize the Jump List of an Electron app. It is now possible to: - Add tasks to the standard `Tasks` category. - Add separators to the standard `Tasks` category. - Add custom categories containing tasks and file links. - Add system managed Recent/Frequent categories. - Remove the custom Jump List.
This commit is contained in:
Vadim Macagon
parent
b5dec9990e
commit
c64294cf60
7 changed files with 897 additions and 41 deletions
146
docs/api/app.md
146
docs/api/app.md
|
|
@ -527,6 +527,151 @@ Adds `tasks` to the [Tasks][tasks] category of the JumpList on Windows.
|
|||
|
||||
Returns `true` when the call succeeded, otherwise returns `false`.
|
||||
|
||||
**Note:** If you'd like to customize the Jump List even more use
|
||||
`app.setJumpList(categories)` instead.
|
||||
|
||||
### `app.getJumpListSettings()` _Windows_
|
||||
|
||||
Returns an Object with the following properties:
|
||||
|
||||
* `minItems` Integer - The minimum number of items that will be shown in the
|
||||
Jump List (for a more detailed description of this value see the
|
||||
[MSDN docs][JumpListBeginListMSDN]).
|
||||
* `removedItems` Array - Array of `JumpListItem` objects that correspond to
|
||||
items that the user has explicitly removed from custom categories in the
|
||||
Jump List. These items must not be re-added to the Jump List in the **next**
|
||||
call to `app.setJumpList()`, Windows will not display any custom category
|
||||
that contains any of the removed items.
|
||||
|
||||
### `app.setJumpList(categories)` _Windows_
|
||||
|
||||
* `categories` Array or `null` - Array of `JumpListCategory` objects.
|
||||
|
||||
Sets or removes a custom Jump List for the application, and returns one of the
|
||||
following strings:
|
||||
|
||||
* `ok` - Nothing went wrong.
|
||||
* `error` - One or more errors occured, enable runtime logging to figure out
|
||||
the likely cause.
|
||||
* `invalidSeparatorError` - An attempt was made to add a separator to a
|
||||
custom category in the Jump List. Separators are only allowed in the
|
||||
standard `Tasks` category.
|
||||
* `fileTypeRegistrationError` - An attempt was made to add a file link to
|
||||
the Jump List for a file type the app isn't registered to handle.
|
||||
* `customCategoryAccessDeniedError` - Custom categories can't be added to the
|
||||
Jump List due to user privacy or group policy settings.
|
||||
|
||||
If `categories` is `null` the previously set custom Jump List (if any) will be
|
||||
replaced by the standard Jump List for the app (managed by Windows).
|
||||
|
||||
`JumpListCategory` objects should have the following properties:
|
||||
|
||||
* `type` String - One of the following:
|
||||
* `tasks` - Items in this category will be placed into the standard `Tasks`
|
||||
category. There can be only one such category, and it will always be
|
||||
displayed at the bottom of the Jump List.
|
||||
* `frequent` - Displays a list of files frequently opened by the app, the
|
||||
name of the category and its items are set by Windows.
|
||||
* `recent` - Displays a list of files recently opened by the app, the name
|
||||
of the category and its items are set by Windows. Items may be added to
|
||||
this category indirectly using `app.addRecentDocument(path)`.
|
||||
* `custom` - Displays tasks or file links, `name` must be set by the app.
|
||||
* `name` String - Must be set if `type` is `custom`, otherwise it should be
|
||||
omitted.
|
||||
* `items` Array - Array of `JumpListItem` objects if `type` is `tasks` or
|
||||
`custom`, otherwise it should be omitted.
|
||||
|
||||
**Note:** If a `JumpListCategory` object has neither the `type` nor the `name`
|
||||
property set then its `type` is assumed to be `tasks`. If the `name` property
|
||||
is set but the `type` property is omitted then the `type` is assumed to be
|
||||
`custom`.
|
||||
|
||||
**Note:** Users can remove items from custom categories, and Windows will not
|
||||
allow a removed item to be added back into a custom category until **after**
|
||||
the next successful call to `app.setJumpList(categories)`. Any attempt to
|
||||
re-add a removed item to a custom category earlier than that will result in the
|
||||
entire custom category being omitted from the Jump List. The list of removed
|
||||
items can be obtained using `app.getJumpListSettings()`.
|
||||
|
||||
`JumpListItem` objects should have the following properties:
|
||||
|
||||
* `type` String - One of the following:
|
||||
* `task` - A task will launch an app with specific arguments.
|
||||
* `separator` - Can be used to separate items in the standard `Tasks`
|
||||
category.
|
||||
* `file` - A file link will open a file using the app that created the
|
||||
Jump List, for this to work the app must be registered as a handler for
|
||||
the file type (though it doesn't have to be the default handler).
|
||||
* `path` String - Path of the file to open, should only be set if `type` is
|
||||
`file`.
|
||||
* `program` String - Path of the program to execute, usually you should
|
||||
specify `process.execPath` which opens the current program. Should only be
|
||||
set if `type` is `task`.
|
||||
* `args` String - The command line arguments when `program` is executed. Should
|
||||
only be set if `type` is `task`.
|
||||
* `title` String - The text to be displayed for the item in the Jump List.
|
||||
Should only be set if `type` is `task`.
|
||||
* `description` String - Description of the task (displayed in a tooltip).
|
||||
Should only be set if `type` is `task`.
|
||||
* `iconPath` String - The absolute path to an icon to be displayed in a
|
||||
Jump List, which can be an arbitrary resource file that contains an icon
|
||||
(e.g. `.ico`, `.exe`, `.dll`). You can usually specify `process.execPath` to
|
||||
show the program icon.
|
||||
* `iconIndex` Integer - The index of the icon in the resource file. If a
|
||||
resource file contains multiple icons this value can be used to specify the
|
||||
zero-based index of the icon that should be displayed for this task. If a
|
||||
resource file contains only one icon, this property should be set to zero.
|
||||
|
||||
Here's a very simple example of creating a custom Jump List:
|
||||
|
||||
```javascript
|
||||
const {app} = require('electron')
|
||||
|
||||
app.setJumpList([
|
||||
{
|
||||
type: 'custom',
|
||||
name: 'Recent Projects',
|
||||
items: [
|
||||
{ type: 'file', path: 'C:\\Projects\\project1.proj' },
|
||||
{ type: 'file', path: 'C:\\Projects\\project2.proj' }
|
||||
]
|
||||
},
|
||||
{ // has a name so `type` is assumed to be "custom"
|
||||
name: 'Tools',
|
||||
items: [
|
||||
{
|
||||
type: 'task', title: 'Tool A',
|
||||
program: process.execPath, args: '--run-tool-a',
|
||||
icon: process.execPath, iconIndex: 0,
|
||||
description: 'Runs Tool A'
|
||||
},
|
||||
{
|
||||
type: 'task', title: 'Tool B',
|
||||
program: process.execPath, args: '--run-tool-b',
|
||||
icon: process.execPath, iconIndex: 0,
|
||||
description: 'Runs Tool B'
|
||||
}
|
||||
]
|
||||
},
|
||||
{ type: 'frequent' },
|
||||
{ // has no name and no type so `type` is assumed to be "tasks"
|
||||
items: [
|
||||
{
|
||||
type: 'task', title: 'New Project',
|
||||
program: process.execPath, args: '--new-project',
|
||||
description: 'Create a new project.'
|
||||
},
|
||||
{ type: 'separator' },
|
||||
{
|
||||
type: 'task', title: 'Recover Project',
|
||||
program: process.execPath, args: '--recover-project',
|
||||
description: 'Recover Project'
|
||||
}
|
||||
]
|
||||
}
|
||||
])
|
||||
```
|
||||
|
||||
### `app.makeSingleInstance(callback)`
|
||||
|
||||
* `callback` Function
|
||||
|
|
@ -771,3 +916,4 @@ Sets the `image` associated with this dock icon.
|
|||
[handoff]: https://developer.apple.com/library/ios/documentation/UserExperience/Conceptual/Handoff/HandoffFundamentals/HandoffFundamentals.html
|
||||
[activity-type]: https://developer.apple.com/library/ios/documentation/Foundation/Reference/NSUserActivity_Class/index.html#//apple_ref/occ/instp/NSUserActivity/activityType
|
||||
[unity-requiremnt]: ../tutorial/desktop-environment-integration.md#unity-launcher-shortcuts-linux
|
||||
[JumpListBeginListMSDN]: https://msdn.microsoft.com/en-us/library/windows/desktop/dd378398(v=vs.85).aspx
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue