Remote Control Mechanism

In order to control other dizmos in a meaningful way, especially using the Navigator, a concise interface has been provided. The interface consists of several tree nodes in dizmos and a library to provide a helper layer for developers to use. The library is optional, although strongly encouraged. If something on the underlying tree nodes changes, the library, towards the outside, will allow the continued usage without change in code.

The mechanism uses steps and total steps, in a simplified manner, to provide a way of controlling a dizmo. The developer then needs only to use the helper function to control the dizmo and allow another dizmo at the same time to control it too. Through this unified interface, most race conditions are accounted for.

For example, if a user has several images in a dizmo that can be moved through by another dizmo, the developer would assign a step (from 1 to the maximum amount of images) to each image and then use the helper libraries functions to listen for when a new image should be displayed. To make this work properly, the developer should also use the Controller class to control the dizmo. This means using the setter calls to skip between images and using the callbacks to listen to those steps.

Helper Library

The helper library provides two main entry points: DizmoHelper.Controller and DizmoHelper.RemoteController. Both libraries can be provided through dizmoViewer and do not need to be included in your HTML file. To load them, add the following key to your package.json file:

"settings": {
    "helper_version" : "1.0"
}

DizmoHelper.Controller

The controller class provides a singleton to be used by a dizmo that can be controlled by other dizmos (for example the Navigator dizmo). To use this class, call DizmoHelper.Controller.init() once. You can then provide several callbacks to the class which are called when certain events happen. If you want to stop using the class while the dizmo is running, you can issue a call to DizmoHelper.Controller.deinit() which will stop the event handlers from being fired and reset the values to the defaults.

If a function is unavailable or an invalid value is entered, an error will be thrown. This is mainly due to the fact that another dizmo needs the values properly set to be able to control this dizmo. So to avoid confusion and not working configurations, values and functions will be enforced in the DizmoHelper.Controller

DizmoHelper.Controller.init()

Initialize the class with default values and start listening on changes. The class will start with a step of 0 and total steps of 0, to represent no steps are available in this dizmo. The global timer and and animation flag are also set to false. A call to this function is mandatory if you want to use the library

DizmoHelper.Controller.deinit()

De-initialize the class, resets the values to the defaults and prevents events from being fired. If you want to use the class again, a call to DizmoHelper.Controller.init() has to be made.

Step Callbacks

All the step callbacks receive the current step and the old step as parameters. It is generally advised to use the positional callbacks DizmoHelper.Controller.onFirstStep, DizmoHelper.Controller.onPreviousStep, DizmoHelper.Controller.onNextStep, DizmoHelper.Controller.onLastStep and not the general DizmoHelper.Controller.onStep.

DizmoHelper.Controller.onStep(callback)

The callback provided to this function is invoked whenever a step has occurred. This callback does not provide a direction, meaning if it was the previous or next step, last or first is not counted. To get a more accurate callback, use the respective positional callbacks.

DizmoHelper.Controller.onFirstStep(callback)

A callback that is invoked whenever the first step in the dizmo is reached.

DizmoHelper.Controller.onPreviousStep(callback)

A callback that is invoked when the previous step (i.e.: one smaller than the old one) has been reached. This is not called when reaching the first step. In that case DizmoHelper.Controller.onFirstStep is called instead.

DizmoHelper.Controller.onNextStep(callback)

A callback that is invoked when the next step (i.e.: one higher than the old one) has been reached. This is not called when reaching the last step. In that case DizmoHelper.Controller.onLastStep is called instead.

DizmoHelper.Controller.onLastStep(callback)

A callback that is invoked whenever the last step in the dizmo is reached.

Setters

DizmoHelper.Controller.setTotalSteps(steps)

Set the total steps available in this dizmo. Negative numbers are not allowed here. A step of 0 or 1 means that the dizmo should be treated as if it has no steps.

DizmoHelper.Controller.setStep(step)

Set the current step. This function only accepts a range between 1 and the total steps set through DizmoHelper.Controller.setTotalSteps. If the total steps are 0 or 1, this function will not accept any value. To control the dizmo effectively, please use the positional calls DizmoHelper.Controller.firstStep, DizmoHelper.Controller.previousStep, DizmoHelper.Controller.nextStep and DizmoHelper.Controller.lastStep.

DizmoHelper.Controller.firstStep()

Jump to the first step in the dizmo. This will be unavailable if total steps is 0 or 1.

DizmoHelper.Controller.previousStep()

Jump to the previous step. If the first step is reached and this is called it will again jump to the first step (meaning no event will be fired). This function will be unavailable if total steps is 0 or 1.

DizmoHelper.Controller.nextStep()

Jump to the next step. If the last step is reached and this is called it will again jump to the last step (meaning no event will be fired). This function will be unavailable if total steps is 0 or 1.

DizmoHelper.Controller.lastStep()

Jump to the last step in the dizmo. This function will be unavailable if total steps is 0 or 1.

Other Functions

DizmoHelper.Controller.getTotalSteps()

Return the total steps available in this dizmo.

DizmoHelper.Controller.getStep()

Return the current step.

DizmoHelper.Controller.startAnimation()

Should be called when an animation has started to tell listening dizmos not to move another step.

DizmoHelper.Controller.stopAnimation()

Should be called once the animation has finished, so that listening dizmos know that the next step can be done.

DizmoHelper.Controller.enableGlobalTimer()

Enable the usage of a global timer.

DizmoHelper.Controller.disableGlobalTimer()

Disable the usage of a global timer.

DizmoHelper.Controller.startGlobalTimer()

Should be called when the timer for this dizmo has started.

DizmoHelper.Controller.stopGlobalTimer()

Should be called when the timer for this dizmo has stopped.

DizmoHelper.RemoteController

This class is used by the Navigator to control another dizmo that uses the DizmoHelper.Controller class (or adheres to its standards in regards to tree nodes). This class required a dizmo identifier with the dizmo to control. After that it works very similar to the DizmoHelper.Controller class in that it provides the same functions (mostly).

This class will not throw errors if a function is unavailable (it will still throw errors if a value is entered wrong). It will instead just "swallow" the command and ignore it. This is mainly due to the nature of this, as it needs other dizmos to behave correctly, we don’t want to break a controlling dizmo just because a to be controlled dizmo is not behaving correctly.

DizmoHelper.RemoteController()

The contructor receives a parameter object that must contain a dizmo instance refering to the dizmo that should be controlled: {dizmo: dizmoinstace}. The three callbacks onAnimationStarted, onTimerStarted, onTimerStopped also have to be provided through the configuration object, but are not required.

    DizmoHelper.RemoteController({
        dizmo: someDizmoInstance,
        onAnimationStarted: function() {},
        onAnimationStopped: function() {},
        onTimerStarted: function() {},
        onTimerStopped: function()
    })

Control Functions

DizmoHelper.RemoteController.setStep()

Set the step to an arbitrary number. If total steps are set to 0 or 1, this function will be unavailable. It is also advised to use the directional functions DizmoHelper.RemoteController.firstStep, DizmoHelper.RemoteController.previousStep, DizmoHelper.RemoteController.nextStep and DizmoHelper.RemoteController.lastStep to control the dizmo.

DizmoHelper.RemoteController.firstStep()

Go to the first step in the remotely controlled dizmo. This will be unavailable if the total steps of the remotely controlled dizmo is 0 or 1.

DizmoHelper.RemoteController.previousStep()

Go to the previous step in the remotely controlled dizmo. This will be unavailable if the total steps of the remotely controlled dizmo is 0 or 1.

DizmoHelper.RemoteController.nextStep()

Go to the next step in the remotely controlled dizmo. This will be unavailable if the total steps of the remotely controlled dizmo is 0 or 1.

DizmoHelper.RemoteController.lastStep()

Go to the last step in the remotely controlled dizmo. This will be unavailable if the total steps of the remotely controlled dizmo is 0 or 1.

Others

DizmoHelper.RemoteController.getStep()

Returns the current step of the controlled dizmo as a number.

DizmoHelper.RemoteController.getTotalSteps()

Returns the total steps of the controlled dizmo as a number.

DizmoHelper.RemoteController.timerEnabled()

If the timer is enabled in the controlled dizmo. This is important as you don’t have to worry about timers if this is set to false.

Tree Nodes

As mentioned above, one does not have to use this helper class to make use of the functionality provided through it (although it is strongly recommended). To control a dizmo from somewhere else, all that is needed are the following 5 tree nodes that reside in the public tree. If a dizmo uses this interface to control itself, it can easily be controlled by any other dizmo accessing this interface.

public/controller/animationRunning // Will be set to true if an animation in the dizmo is running
public/controller/step             // The current step the dizmo is on (or should be on)
public/controller/totalSteps       // The total steps available in the dizmo
public/controller/timerRunning     // Will be set to true/false if a timer is running
public/controller/timerEnabled     // Will be set to true/false if a timer is available (enabled)