Version: 1.x

Settings

ID: vSettings | ROLE: SETTINGS | Type: Plugin

This plugin renders and manages submenus. The root menu is a small popup on desktop, and a fullscreen modal on mobile.

info

This plugin has a Registry containing all registered submenus.

const unsubscribe = player.getRegistry().subscribe(records => {
const submenus = records.vSettings;
});
// ...
unsubscribe();

Defaults#

By default there are no submenus, but you can install an additional DefaultSettings plugin to get started with the Vime defaults. The default Vime settings includes submenus for setting the playback rate, video quality and captions/subtitles.

Setup#

import { Player, Settings, DefaultSettings } from '@vime-js/complete';
// ...
const player = new Player({
target,
props: {
plugins: [Settings, DefaultSettings]
}
});

Usage#

Create a Submenu#

import { SelectSubmenu } from '@vime-js/complete';
player
.vSettings
.createSubmenu('playbackRateMenu', SelectSubmenu)
.then(submenu => {
const options = player.playbackRates.map((rate) => ({
title: (rate === 1) ? player.i18n.normal : rate,
value: rate,
}));
/**
* $set is part of the Svelte component API, you can
* individually set these props as well.
**/
submenu.$set({
title: player.i18n.speed,
value: player.playbackRate,
options: (player.playbackRates.length === 1) ? [] : options,
emptyHint: player.i18n.normal,
isLocked: !player.canSetPlaybackRate || (player.playbackRates.length === 0),
});
submenu.$on('valuechange', e => {
player.playbackRate = e.detail;
});
});
info

See SelectSubmenu for the full API.

Update a Submenu#

const submenu = player.vSettings.getSubmenu('playbackRateMenu');
const { playbackRate } = player.getStore();
playbackRate.subscribe(rate => {
submenu.value = rate;
});
// ...

Remove a Submenu#

player
.vSettings
.removeSubmenu('playbackRateMenu')
.then(() => {
// ...
});

Access Submenu via Event#

player.vSettings.$on('register', registration => {
const { id, value: submenu } = registration;
if (id === 'playbackRateMenu') {
// ...
}
});

Access Submenu via Registry#

player.vSettings.getRegistry().subscribe(menus => {
const submenu = menus.playbackRateMenu;
if (submenu) {
// ...
}
});

Store#

All properties for this plugin are backed by a store which you can access via the getStore method.

const { isMenuActive } = player.vSettings.getStore();

Props#

isMenuActive#

Type: boolean | Default: false

Whether the root settings menu is visible or not.

currentSubmenu#

Type: string|null | Default: null

The id of the currently active submenu. If it is null then no submenu is active.

Methods#

getRegistry#

Return Type: Registry

The plugin registry where submenu instances are registered.

getStore#

Return Type: object

See the store section above.

getEl#

Return Type: HTMLElement

The root component HTML element.

getId#

Return Type: string

An auto-generated id for the root menu element in the form settings-{count}. This is to distinguish between multiple player menus on the same page.

getControllerId#

Return Type: string

An auto-generated id for the root menu controller in the form settings-control-{count}.

getMenu#

Return Type: Menu

The underlying Menu instance.

getSubmenus#

Return Type: Submenu[]

The rendered submenu instances.

getSubmenu#

Parameters: (id: string) | Return Type: Submenu|undefined

The rendered submenu instance for the given id.

createSubmenu#

Parameters: (id: string, type: Component = Submenu) | Return Type: Promise<Submenu>

Creates and renders a Submenu component and returns a Promise that will resolve with the rendered instance. The type field can be used to pass in a component that extends the base Submenu.

createSubmenus#

Parameters: (ids: string[], type: Component = Submenu) | Return Type: Promise<Submenu[]>

Creates and renders a list of Submenu components and returns all their instances via a Promise. The type field can be used to pass in a component that extends the base Submenu.

removeSubmenu#

Parameters: (id: string) | Return Type: Promise<undefined>

Destroys a Submenu instance matching the given id and returns a Promise that will resolve once it has completed.

removeSubmenus#

Parameters: (ids: string[]) | Return Type: Promise<undefined>

Destroys multiple Submenu instances matching the given ids and returns a Promise that will resolve once it has completed.

Events#

Registry#

Emits Registry events.

open#

Data Type: undefined

Fired when the root menu becomes visible.

close#

Data Type: undefined

Fired when the root menu becomes hidden.

opensubmenu#

Data Type: string

Fired with the id of the submenu that's visible.

closesubmenu#

Data Type: string

Fired with the id of the submenu that's hidden.