Overview

Controllers control how a story plays. They usually provide mechanisms for users to interact with your story. They may also provide visual feedback about the state of the animation.

Story Controllers

Each story may optionally have a controllers entry with a list of configured controllers to use for that story. If an empty array is given, the story won’t use any controllers. If no controllers entry is given then the story will use the default controllers.

Default Controllers

The default set of controllers is listed in an array at ProStyle.defaultControllers. All stories on an HTML page will use these controllers unless the controllers are explicitly defined for the story. These values may be overridden with JavaScript.

ProStyle.defaultControllers = [
	{controllerType: "auto"},
	{controllerType: "resize"}
]

Auto

The auto controller configures the automatic behavior of the player. Use it to make the player start and advance automatically, without user interaction.

Options

start

If true, the story will start immediately. If a number is provided, the story will start after that many seconds.

  • default value: true
{ controllerType: "auto", start: true }
{ controllerType: "auto", start: 1.5 }

stepAdvance

If true, the story will start playing the next step immediately upon reaching the end of a step. If a number is provided, the story will start the next step after that many seconds.

  • default value: false
{ controllerType: "auto", stepAdvance: true }
{ controllerType: "auto", stepAdvance: 1.5 }

The delay can optionally be overridden on the step object using an autoAdvanceDelay entry.

restart

If true, the story will restart immediately upon reaching the end of the timeline. If a number is provided, the story will restart after that many seconds.

  • default value: false
{ controllerType: "auto", restart: true }
{ controllerType: "auto", restart: 1.5 }

Debug

The debug controller displays status information in the upper-left corner of the canvas. It shows the elaspsed time, completion percentage, and the zero-based indexes of the current flow, page and step.

Options

cssClass

If provided, the div that holds the debug information will have a class attribute with this value.

  • default value: ''
{ controllerType: "debug", cssClass: 'debugBar' }

Keyboard

The keyboard controller maps user interaction to playback activity. The user presses keys on a keyboard or related device, such as a presentation clicker, to start, pause, restart, advance, or rewind the player.

There are seven actions that can be triggered. Each has a default set of key codes that trigger the action, but they can be overridden with the keys option.

ActionDescription
play Starts playback at the current position if it is currently paused.
KeyCodeKey
13Enter
116F5
pause Stops playback at the current position if it is currently playing.
KeyCodeKey
19Pause
27Escape
toggle Toggles between play and pause.
KeyCodeKey
32Space
back The playhead rewinds to the start of the current step. If the playhead is already at the start of the step, it rewinds to the start of the previous step.
KeyCodeKey
8Backspace
33Page Up
37Left
38Up
188Comma
next If the playhead is at the beginning of a step, it starts playing. Otherwise, it fast forwards to the next step and then starts playing.
KeyCodeKey
34Page Down
39Right
40Down
9Tab
start Positions the playhead at the beginning of the story.
KeyCodeKey
36Home
190Period ('blank screen' in PowerPoint)
end Positions the playhead at the end of the story.
KeyCodeKey
35End

Options

keys

The keymap can be changed by associating Keycodes with the actions. If an action is included, all of it’s default keys will be replaced. It’s possible to only override some of the actions, by omitting the others.

A keycode can only trigger one action. If it is associated with multiple, the keycode will trigger the first one found, in this order: next, toggle, play, pause, back, start, end.

{ 
	controllerType: "keyboard",
	keys: {
		play: [13,116],
		pause: [19,27],
		togglePlay: [32],
		back: [8,33,37,38,188],
		playNext: [34,39,40,9],
		start: [36,190],
		end: [35]
	} 
}

MouseMove

The mousemove controller maps mouse movement over a story to a position on its timeline. It then instantly seeks the timeline to that position. When the mouse is moved off of the story, the player starts from the current position and plays until the end of the story, unless otherwise configured with the auto controller.

The hot spot normally ranges from the left edge of the frame to the right edge. If the mouse is positioned 25% of the way across the frame, the timeline will be positioned to 25% complete. The starting and ending points of the hotspot can be configured.

The mousemove controller can be experienced by positioning your mouse over the Controllers heading at the top of this page.

Options

start

This option defines the horizontal location on the frame of the starting point. This is the point that will map to the beginning of the animation. The value is a percentage of the frame’s width.

  • default value: 0

end

This option defines the horizontal location on the frame of the ending point. This is the point that will map to the end of the animation. The value is a percentage of the frame’s width.

  • default value: 100
{ controllerType: "mousemove", start: 10, end: 50 }

MouseWheel

The mousewheel controller pauses and then seeks the timeline relative to its current position. The wheel’s direction defines whether the timeline is advanced or retreated. To experience it, position your mouse over almost any of the animations on this website, including the front page’s splash and all the examples in the gallery. Spin the wheel with or without the CTRL and ALT keys pressed.

Each wheel click moves the timeline 0.01 seconds. The CTRL and ALT keys can be pressed to alter the amount of change.

CTRL ALT Seconds
    0.01
pressed   0.001
  pressed 1
pressed pressed 0.1

Options

none


Resize

The resize controller monitors for resizing of the browser window. If the story’s canvas size changes, the resize controller rebuilds the story animation to match the new size.

Options

throttleDelay

As a browser window is resized, it fires a stream of events notifying each interim size. Rendering a ProStyle story is a relatively hefty task. Regenerating the story for every one of the events would require a lot of system resources. We use a throttle to avoid this. With throttling, the resize happens only after a period of time has elaspsed after the last resize event.

The value is a number in seconds. A value of 0 results in real-time resizing as the window edge is dragged.

  • default value: 0.01
{ controllerType: "resize", throttleDelay:1 }

Tap

The tap controller segments the canvas into four areas that can be tapped or clicked to control playback. There are two rows. The first row contains tap areas that correspond to the back, toggle, and next actions. The second row is a non-visible trackbar. The timeline will seek the story to the position relative to where on the tap area was hit. The relative sizes of the rows and the relative sizes of the tap areas on the first row are configurable.

The tap controller is used on the front page’s splash animation.

Options

playbuttonSizes

The relative sizes of the click areas is defined as three numbers in an array, corresponding to the width of the back tap area, the toggle tap area, and the next tap area. Areas can be omitted by setting the width to 0. For example, to only have back and next, use [50,0,50].

  • default value: [25,50,25]
{ controllerType: "tap", playbuttonSizes: [0,75,25] }

rowSizes

The relative sizes of the rows is defined as two numbers in an array, corresponding to the height of the play buttons row and the height of the seek row. A row can be omitted by setting the height to 0. For example, to only have the play buttons row, use [100,0].

  • default value: [75,25]
{ controllerType: "tap", rowSizes: [0,100] }

cursors

If true, the tap areas will use custom mouse cursors.

  • default value: true
{ controllerType: "tap", cursors: false }

Track

The track controller renders a trackbar at the bottom of the story. The user can seek the timeline to any position by clicking on the bar. It also provides control buttons to play and pause, rewind, and play next.

The track controller can be seen in the gallery. All gallery examples use it.

Options

color

The foreground color of the bar and buttons.

  • default value: "#BBB"
{ controllerType: "track", color: "green" }

highlightColor

The foreground color of the bar and buttons when the mouse is hovered on them.

  • default value: "#FFF"
{ controllerType: "track", highlightColor: "yellow" }

backColor

The color of the track background.

  • default value: "rgba(0,0,0,0.5)"
{ controllerType: "track", backColor: "black" }

stepColor1

Each step on the trackbar displays as a gradient between two colors. This is the left, starting color.

  • default value: "#222"
{ controllerType: "track", stepColor1: "navy" }

stepColor2

Each step on the trackbar displays as a gradient between two colors. This is the right, ending color.

  • default value: "#000"
{ controllerType: "track", stepColor2: "blue" }