Class: Controller

Controller.Controller(preferences, presentation, selection, viewport, player)

Sozi editor UI controller.

A Controller instance manages the user interface of the editor and updates the presentation data in reaction to user actions.

Constructor

new Controller(preferences, presentation, selection, viewport, player)

Initialize a new Sozi editor UI controller.

Parameters:
Name Type Description
preferences module:model/Preferences.Preferences

The object that holds the user settings of the editor.
presentation module:model/Presentation.Presentation

The Sozi presentation opened in the editor.
selection module:model/Selection.Selection

The object that represents the selection in the timeline.
viewport module:player/Viewport.Viewport

The object that displays a preview of the presentation.
player module:player/Player.Player

The object that animates the presentation.
Source:

Extends

  • EventEmitter

Members

(readonly) canFitElement :boolean

true if the "Fit Element" function is available.

This property is true when the outline element of each selected layer belongs to this layer.

Type:
  • boolean
Source:

defaultLayers :Array.<module:model/Presentation.Layer>

The layers that fall in the "default" row of the timeline.

Type:
Source:

(readonly) defaultLayersAreSelected :boolean

true if all layers in the "default" set are selected.

Type:
  • boolean
Source:

editableLayers :Array.<module:model/Presentation.Layer>

The layers that have been added to the timeline.

Type:
Source:

exporting :boolean

True if an export operation is in progress.

Type:
  • boolean
Source:

(readonly) hasDefaultLayer :boolean

true if there is at least one layer in the "default" set.

Type:
  • boolean
Source:

hasFocus :boolean

True if the current window has the focus.

Type:
  • boolean
Source:

(nullable) notificationTimeout :number

The timeout ID of the current notification.

Type:
  • number
Source:

player :module:player/Player.Player

The object that animates the presentation.

Type:
Source:

preferences :module:model/Preferences.Preferences

The object that holds the user settings of the editor.

Type:
Source:

presentation :module:model/Presentation.Presentation

The Sozi presentation opened in the editor.

Type:
Source:

redoStack :Array

The stack of operations that can be redone.

Type:
  • Array
Source:

selection :module:model/Selection.Selection

The object that represents the selection in the timeline.

Type:
Source:

storage :module:Storage.Storage

The object that manages the file I/O.

Type:
Source:

undoStack :Array

The stack of operations that can be undone.

Type:
  • Array
Source:

viewport :module:player/Viewport.Viewport

The object that displays a preview of the presentation.

Type:
Source:

Methods

activate()

Finalize the initialization of the application.

Load and apply the user preferences. Activate the storage instance.

Source:

addAllLayers()

Add all layers to the timeline.

This method takes all layers from the "default" layer set and moves them to the "editable" layer set.

This operation modifies the editor state and does not affect the actual presentation. This action does not support undo and redo.

Source:
Fires:

addCustomFile(path)

Add a custom stylesheet or script to the current presentation.

This action supports undo and redo.

Parameters:
Name Type Description
path string

The path of the file to add.
Source:
Fires:

addFrame()

Add a new frame to the presentation.

A new frame is added to the presentation after the currently selected frame. If no frame is selected, the new frame is added at the end of the presentation.

This action supports undo and redo.

Source:
Fires:

addLayer(layerIndex)

Add a layer to the timeline.

This method takes a layers from the "default" layer set and moves it to the "editable" layer set.

This operation modifies the editor state and does not affect the actual presentation. This action does not support undo and redo.

Parameters:
Name Type Description
layerIndex number

The index of the layer to add.
Source:
Fires:

addLayerToSelection(layer)

Add a layer to the selection.

This method adds the given layer to the selection if it is not already present.

Parameters:
Name Type Description
layer module:model/Presentation.Layer

The layer to select.
Source:
Fires:

applyPreferences(changedopt)

Update the user interface after modifying the preferences.

Parameters:
Name Type Attributes Default Description
changed string | object <optional>
 "all"

A dictionay that maps changed property names to a boolean true.
Source:
Fires:

autoselectOutlineElement()

Find and assign an outline element to the current frame in the selected layers.

Source:
See:

copyLayer(groupId)

Copy the properties of a given layer into the selected layers.

This method copies the layer properties and geometrical transformations for the given layer in the selected frames, into the selected layers in the same frames.

This action supports undo and redo.

Parameters:
Name Type Description
groupId number

The ID of the SVG group for the layer to copy.
Source:
Fires:

deleteFrames()

Delete the selected frames from the presentation.

This action supports undo and redo.

Source:
Fires:

error(body)

Show a notification with an error message.

Parameters:
Name Type Description
body string

The message to display.
Source:

(async) exportToPDF()

Export the current presentation to PDF.

Source:

(async) exportToPPTX()

Export the current presentation to PPTX.

Source:

(async) exportToVideo()

Export the current presentation to video.

Source:

fitElement()

Use the element with the user-provided ID as an outline element.

Source:
See:

fromStorable(storable)

Copy the properties of the given object into this instance.

This method will build the list of editable layers managed by this controller, from a list of group IDs provided by the given object.

Parameters:
Name Type Description
storable object

A plain object with the properties to copy.
Source:

getCameraProperty(property) → {Array}

Get a property of the selected cameras in the selected frames.

This method is used in the Properties view to assign getters to HTML fields that represent camera properties.

Parameters:
Name Type Description
property string

The name of the property to get.
Source:
Returns:

The values of the property in the selected cameras.

Type
Array

getCustomFiles() → {Array.<string>}

Get the list of custom stylesheets and scripts added to the current presentation.

Source:
Returns:
  • An array of file paths.
Type
Array.<string>

getFrameProperty(property) → {Array}

Get a property of the selected frames.

This method is used in the Properties view to assign getters to HTML fields that represent frame properties.

Parameters:
Name Type Description
property string

The name of the property to get.
Source:
Returns:

The values of the property in the selected frames.

Type
Array

getLayerProperty(property) → {Array}

Get a property of the selected layers in the selected frames.

This method is used in the Properties view to assign getters to HTML fields that represent layer properties.

Parameters:
Name Type Description
property string

The name of the property to get.
Source:
Returns:

The values of the property in the selected layers.

Type
Array

getLayersAtIndex(layerIndex) → {Array.<module:model/Presentation.Layer>}

Get the layers at the given index.

This method will return an array containing either a single layer, or the layers in the "default" set.

Parameters:
Name Type Description
layerIndex number

The index of the layer to get, or a negative number for the "default" layers.
Source:
Returns:

The layer(s) at the given index.

Type
Array.<module:model/Presentation.Layer>

getPreference(key) → {any}

Get a property of the preferences object.

This method is used in the Properties view to assign getters to HTML fields that represent preferences.

Parameters:
Name Type Description
key string

The name of the property to get.
Source:
Returns:
  • The value of the property in the preferences.
Type
any

getPresentationProperty(property) → {any}

Get a property of the current presentation.

This method is used in the Properties view to assign getters to HTML fields that represent presentation properties.

Parameters:
Name Type Description
property string

The name of the property to get.
Source:
Returns:
  • The value of the property.
Type
any

getShortcut(action) → {string}

Get the keyboard shortcut for a given action.

This method is used in the Properties view to assign getters to HTML fields that represent keyboard shortcut preferences.

Parameters:
Name Type Description
action string

A supported keyboard action name.
Source:
Returns:
  • A shortcut definition.
Type
string

gettext(s) → {string}

The function that returns translated text in the current language.

Parameters:
Name Type Description
s string

The text to translate.
Source:
Returns:

The translated text.

Type
string

hideNotification()

Hide all notifications.

Source:

info(body, force)

Show a notification with an information message.

Parameters:
Name Type Default Description
body string

The message to display.
force boolean false

Ignore the user preferences for notifications.
Source:

moveFrames(toFrameIndex)

Move the selected frames to the given location.

This action supports undo and redo.

Parameters:
Name Type Description
toFrameIndex number

The new index of the first frame in the selection.
Source:
Fires:

onFileChange(fileDescriptor)

Process an SVG document change event.

Depending on the user preferences, this method will reload the presentation, or prompt the user.

Parameters:
Name Type Description
fileDescriptor any

The file that changed recently.
Source:

onFrameChange()

On frame change, recompute the reference element.

Source:
Listens to Events:

onLoad()

Finalize the loading of a presentation.

This method is called by a Storage instance when the SVG and JSON files of a presentation have been loaded. It sets a default selection if needed, and shows the current frame.

Source:

onRepaint()

Update the visible frame on repaint.

This method is called each time this controller emits the "repaint" event. If the currently selected frame is different from the currently visible frame, it will move to the selected frame.

Source:
Listens to Events:

perform(onDo, onUndo, updateSelection, events)

Perform an operation with undo/redo support.

This method call onDo, adds an operation record to the undo stack, and clears the redo stack.

Parameters:
Name Type Description
onDo function

The function that performs the operation.
onUndo function

The function that undoes the operation.
updateSelection boolean

If true, restore the selection when undoing.
events Array.<string>

Emit the given events when performing of undoing the operation.
Source:

redo()

Redo an operation.

This method pops and executes an operation from the redo stack. It updates the selection and emits events as specified in the corresponding call to perform. The operation record is pushed to the undo stack

Source:

reload()

Reload the presentation.

This method delegates the operation to its Storage instance.

Source:

removeCustomFile(index)

Remove a custom stylesheet or script from the current presentation.

This action supports undo and redo.

Parameters:
Name Type Description
index number

The index of the entry to remove in the custom file list.
Source:
Fires:

removeLayer(layerIndex)

Remove a layer from the timeline.

This method takes a layers from the "editable" layer list and moves it to the "default" layer set.

This operation modifies the editor state and does not affect the actual presentation. This action does not support undo and redo.

Parameters:
Name Type Description
layerIndex number

The index of the layer to remove.
Source:
Fires:

removeLayerFromSelection(layer)

Remove a layer from the selection.

This method removes the given layer to the selection if it is present.

Parameters:
Name Type Description
layer module:model/Presentation.Layer

The layer to deselect.
Source:
Fires:

resetLayer()

Reset the selected layers to their initial state.

This method puts all selected layers, in all selected frames, in the same state as if the SVG was just opened. Users can perform this operation to recover from a sequence of transformations that resulted in an undesired layer state.

This action supports undo and redo.

Source:
Fires:

(async) save()

Save the presentation.

This method delegates the operation to its Storage instance and triggers a repaint so that the UI shows the correct "saved" status.

Source:
See:
Fires:

selectAllFrames()

Select all frames.

This methods adds all the frames of the presentation to the selection.

Source:
Fires:

selectFrame(index)

Select a single frame.

This method adds the frame at the given index to the selection, and removes the other previously selected frames.

Parameters:
Name Type Description
index number

The index of the frame to select. A negative number counts backwards from the end.
Source:
Fires:

selectLayers(layers)

Select the given layers.

This methods adds the given layers to the selection and removes the other previously selected layers.

Parameters:
Name Type Description
layers Array.<module:model/Presentation.Layer>

The layers to select.
Source:
Fires:

selectRelativeFrame(relativeIndex)

Select a specific frame at a relative location from the current frame.

The absolute index of the frame to select is the sum of the current frame index and the given relative index.

Parameters:
Name Type Description
relativeIndex number

The relative location of the frame to select with respect to the current frame.
Source:
Fires:

setAspectHeight(height)

Set the height component (denominator) of the current aspect ratio of the preview area.

This action supports undo and redo.

Parameters:
Name Type Description
height number

The desired height.
Source:
Fires:

setAspectWidth(width)

Set the width component (numerator) of the current aspect ratio of the preview area.

This action supports undo and redo.

Parameters:
Name Type Description
width number

The desired width.
Source:
Fires:

setCameraProperty(property, newValue)

Set a property of the selected cameras in the selected frames.

This method is used in the Properties view to assign setters to HTML fields that represent camera properties.

This action supports undo and redo.

Parameters:
Name Type Description
property string

The name of the property to set.
newValue any

The new value of the property.
Source:
Fires:

setDragMode(dragMode)

Set the effect of dragging in the preview area.

Parameters:
Name Type Description
dragMode string

The new drag mode.
Source:
See:
Fires:

setFrameProperty(property, newValue)

Set a property of the selected frames.

This method is used in the Properties view to assign setters to HTML fields that represent frame properties.

This action supports undo and redo.

Parameters:
Name Type Description
property string

The name of the property to set.
newValue any

The new value of the property.
Source:
Fires:

setLayerProperty(property, newValue)

Set a property of the selected layers in the selected frames.

This method is used in the Properties view to assign setters to HTML fields that represent layer properties.

This action supports undo and redo.

Parameters:
Name Type Description
property string

The name of the property to set.
newValue any

The new value of the property.
Source:
Fires:

setOutlineElement(outlineElement)

Set the given element as the outline element of the selected layers in the current frame.

This action supports undo and redo.

Parameters:
Name Type Description
outlineElement SVGElement

The element to use as an outline of the selected layers.
Source:
Fires:

setPreference(key, newValue)

Set a property of the preferences object.

This method is used in the Properties view to assign setters to HTML fields that represent preferences.

This operation cannot be undone.

Parameters:
Name Type Description
key string

The name of the property to set.
newValue any

The new value of the property.
Source:
Fires:

setPresentationProperty(property, newValue)

Set a property of the current presentation.

This method is used in the Properties view to assign setters to HTML fields that represent presentation properties.

This action supports undo and redo.

Parameters:
Name Type Description
property string

The name of the property to set.
newValue any

The new value of the property.
Source:
Fires:

setShortcut(action, newValue)

Set a keyboard shortcut for a given action.

This method is used in the Properties view to assign setters to HTML fields that represent keyboard shortcut preferences.

This operation cannot be undone.

Parameters:
Name Type Description
action string

A supported keyboard action name.
newValue any

A shortcut definition.
Source:

showNotification(severity, body)

Show a notification.

The presentation editor does not use the operating system's notification system. This method will display a notification inside the application.

A notification will be hidden after a given time. Consecutive notifications are concatenated if they happen in a short period of time.

Parameters:
Name Type Description
severity string

The severity of the event to signal ("error" or "info").
body string

An HTML string to show in the notification area.
Source:

toggleExportState()

Toggle the "exporting" state

Source:

toStorable() → {object}

Convert this instance to a plain object that can be stored as JSON.

The result contains all the properties needed by the editor to restore the state of this instance.

Source:
Returns:
  • A plain object with the properties needed by the editor.
Type
object

undo()

Undo an operation.

This method pops and executes an operation from the undo stack. It updates the selection and emits events as specified in the corresponding call to perform. The operation record is pushed to the redo stack

Source:

updateCameraSelection()

Select the cameras corresponding to the selected layers.

For each selected layer, this method sets the selected property of the corresponding camera in the current viewport.

Source:

updateCameraStates()

Update the cameras in the current selection based on the current viewport state.

This method is called after a user action that modifies the cameras in the viewport. It copies the camera states of the viewport to the camera states of the selected layers of the presentation.

This action supports undo and redo.

Source:
Fires:

updateFrameSelection(single, sequence, frameIndex)

Update the selection with the given frame.

This method adds or removes frames to/from the selection depending on the selection mode specified by the parameters single and sequence. If single and sequence are false, select only the given frame and all layers.

Parameters:
Name Type Description
single boolean

If true, add or remove one frame to/from the selection.
sequence boolean

If true, add or remove consecutive frames, starting from the current frame up/down to the given index.
frameIndex number

The index of a frame in the presentation.
Source:
Fires:

updateLayerAndFrameSelection(single, sequence, layers, frameIndex)

Update the selection with the given layers and a given frame.

This method adds or removes frames and layers to/from the selection depending on the selection mode specified by the parameters single and sequence. If single and sequence are false, select only the given frame and layers.

Parameters:
Name Type Description
single boolean

If true, add or remove the given layers and frame to/from the selection.
sequence boolean

If true, add or remove consevutive frames and layers starting from the current frame and layer.
layers Array.<module:model/Presentation.Layer>

The layers to select or deselect.
frameIndex number

The index of the frame in the presentation
Source:
To Do:
  • Sequence mode is not supported for layers.
Fires:

updateLayerSelection(single, sequence, layers)

Update the selection with the given layer.

This method adds or removes layers to/from the selection depending on the selection mode specified by the parameters single and sequence. If single and sequence are false, select only the given layers and all frames.

Parameters:
Name Type Description
single boolean

If true, add or remove the given layers to/from the selection.
sequence boolean

If true, add or remove consecutive layers, starting from the current layer up/down to the given layers.
layers Array.<module:model/Presentation.Layer>

The layers to select or deselect.
Source:
To Do:
  • Sequence mode is not supported yet.
Fires:

updateLayerVisibility(layers)

Toggle the visibility of the given layers.

If the layers becomes visible, they are added to the selection, otherwise, they are removed from the selection.

Parameters:
Name Type Description
layers Array.<module:model/Presentation.Layer>

The layers to show or hide.
Source:
Fires: