Class TKController
Extends
TKObject
.
The TKController class is the base class for all TuneKit controllers. Controllers are useful objects that control all the core functionalities of a screen or sub-screen: view-loading, interaction, navigation, etc.
Defined in: Controller.js.
Constructor Attributes | Constructor Name and Description |
---|---|
TKController (data)
|
Field Attributes | Field Name and Description |
---|---|
A list of objects defining elements to act as anchors to trigger a JavaScript callback.
|
|
A CSS selector that matches an element in the
view that acts as the back button. |
|
The animated transition to use for this controller's view when the controller becomes active.
|
|
The animated transition to use for this controller's view when the controller becomes inactive.
|
|
<static> |
TKController.
controllers
The hash in which we keep references to all controller instantiated throughout the lifecycle of the booklet.
|
The unique id for this controller's view.
|
|
The complete list of all elements that can be navigated to within this controller and all of its sub-controllers.
|
|
A list of objects defining elements to act as anchors to navigate to other controllers.
|
|
A list of objects defining elements to which we want to create an automatic reference on the controller instance.
|
|
The controller directly containing this controller instance,
null if the controller is not attached to any yet. |
|
A list of image URIs to preload.
|
|
The CSS selector for the default scrollable element.
|
|
The name of the template to be used to create the view's content.
|
Method Attributes | Method Name and Description |
---|---|
addNavigableElement (element)
Adds an element within the controller's view to the list of navigable elements.
|
|
customMetricsForElement (element)
Allows to specify custom metrics for an element displayed on screen.
|
|
elementWasActivated (element)
Triggered when an element is activated by the user, no matter what the host's input methods are as TuneKit abstracts the interaction that yields
an element's activation.
|
|
elementWasHighlighted (element, previouslyHighlightedElement)
Triggered when an element receives highlight.
|
|
elementWasHovered (element)
Triggered when an element is hovered, which only happens when a mouse is present.
|
|
elementWasUnhighlighted (element, nextHighlightedElement)
Triggered when an element loses highlight.
|
|
elementWasUnhovered (element)
Triggered when an element is not hovered any longer, which only happens when a mouse is present.
|
|
handleEvent (event)
Entry point for all event handling, since
TKController implements the DOM EventListener protocol. |
|
isDescendentOfController (purportedParentController)
Indicates whether the receiver is a descendent of the controller passed as an argument.
|
|
Indicates whether the view the controller manages was loaded yet.
|
|
keyWasPressed (key)
Triggered when a key was pressed and the receiver has expressed explicit interest in providing custom key event handling by returning
true in
the wantsToHandleKey method. |
|
preferredElementToHighlightInDirection (currentElement, direction)
Allows the controller to provide the spatial navigation manager with a prefered element to highlight, overriding the default behavior of using CSS metrics.
|
|
This method is called once the view has been loaded and allows the controller to post-process it.
|
|
removeNavigableElement (element)
Removes an element within the controller's view from the list of navigable elements.
|
|
<static> |
TKController.
resolveController (stringOrControllerReference)
A utility method to get the controller from an Object that is either the
TKController.id of a controller or a controller directly. |
This method is called when the view managed by this controller appeared on screen, probably after an animated transition.
|
|
This method is called when the view managed by this controller has disappeared from the screen, probably after an animated transition.
|
|
This method is called when the view has been fully loaded but not yet processed.
|
|
Triggered when the view is first inserted into the document.
|
|
This method is called when the view managed by this controller is about to appear on screen, probably after an animated transition.
|
|
This method is called when the view managed by this controller is about to disappear from the screen, probably after an animated transition.
|
|
wantsToHandleKey (key)
Indicates whether the controller is interested in providing event handling for the key with the given identifier.
|
- Methods borrowed from class
TKObject
: addPropertyObserver
,callMethodNameAfterDelay
,callSuper
,notifyPropertyChange
,removePropertyObserver
Class Detail
TKController(data)
- Parameters:
- {Object} data
- A hash of properties to use as this object is initialized.
- Since:
- TuneKit 1.0
Field Detail
{Array}
actions
A list of objects defining elements to act as anchors to trigger a JavaScript callback. Each object in the array is an
ad-hoc object with
selector
, action
and, optionally, arguments
properties. The selector
is a
string describing a CSS selector used to match the element within the view
that will act as a trigger for the action. The action
specifies the function to call when the action is triggered, which is either a string matching the name of a method on this controller instance or
a direct reference to a function. Optionally, the arguments
property can be specified in order to provide a list of arguments to be passed
to the callback when the action is triggered.
{String}
backButton
A CSS selector that matches an element in the
view
that acts as the back button.
{
TKTransitionDefinition
}
becomesActiveTransition
The animated transition to use for this controller's view when the controller becomes active.
{
TKTransitionDefinition
}
becomesInactiveTransition
The animated transition to use for this controller's view when the controller becomes inactive.
<static>
{Object}
TKController.controllers
The hash in which we keep references to all controller instantiated throughout the lifecycle of the booklet. Use a controller's
id
to
access the controller for that id.
{String}
id
The unique id for this controller's view. This is the same string that will be used for the
view
's HTML id
attribute, as well
as a key in the TKController.controllers
hash, and thus must be adequate for both uses. The controller's id is used in the view-loading mechanism,
such that if there is an HTML file in the booklet's views/
directory that shares the same name, it is that file that is loaded to provide
the view's content.
{Array}
navigableElements
The complete list of all elements that can be navigated to within this controller and all of its sub-controllers.
The contents of this array should not be directly manipulated, instead use the
addNavigableElement
and removeNavigableElement
methods.
{Array}
navigatesTo
A list of objects defining elements to act as anchors to navigate to other controllers. Each object in the array is an
ad-hoc object with
selector
and controller
properties. The selector
is a string describing a CSS selector used
to match the element within the view
that will act as an anchor to navigate to the controller. The controller
is either a string matching
the id
of an existing controller or an reference to a TKController
.
{Array}
outlets
A list of objects defining elements to which we want to create an automatic reference on the controller instance. Each object in
the array has a
selector
and a name
property. The selector
is a string describing a CSS selector used to match the
element within the view
to which we want to create a reference. The name
specifies the name of the JavaScript property that will be holding
that reference on the controller instance.
{
TKController
}
parentController
The controller directly containing this controller instance,
null
if the controller is not attached to any yet.
{Array}
preloads
A list of image URIs to preload.
{String}
scrollableElement
The CSS selector for the default scrollable element. If this value is non-
null
then the up and down keys scroll the element specified
by the selector.
{String}
template
The name of the template to be used to create the view's content. If there is an HTML file in the
templates/
directory with that name, the
view is loaded by cloning the content of that file and replacing the ID with that provided by the id
property.
Method Detail
addNavigableElement(element)
Adds an element within the controller's view to the list of navigable elements. Any element that is interactive should be registered as navigable, even
when a mouse is available.
- Parameters:
-
{
Element
} element - The element we wish to make navigable.
{
TKRect
}
customMetricsForElement(element)
Allows to specify custom metrics for an element displayed on screen. This method is called by the spatial navigation manager when determining what the
element to highlight is after the uses presses a directional key on the Apple remote. By default, the CSS metrics for the elements are used, but in
certain cases the author may wish to use different metrics that are more logical for the navigation. Return
null
in order to specify that
the element has no custom metrics.
- Parameters:
-
{
Element
} element - The element which the spatial navigation manager is inspecting.
- Returns:
- {
TKRect
} The custom metrics for the given element.
elementWasActivated(element)
Triggered when an element is activated by the user, no matter what the host's input methods are as TuneKit abstracts the interaction that yields
an element's activation. This method may be subclassed but it is important to call the superclass's implementation of this method as navigation anchors,
actions, etc. are handled in that method directly.
- Parameters:
-
{
Element
} element - The element that was just activated.
elementWasHighlighted(element, previouslyHighlightedElement)
Triggered when an element receives highlight.
- Parameters:
-
{
Element
} element - The element that is newly being highlighted.
-
{
Element
} previouslyHighlightedElement - The element that previously was highlighted, or
null
if there was none.
elementWasHovered(element)
Triggered when an element is hovered, which only happens when a mouse is present.
- Parameters:
-
{
Element
} element - The element that is being hovered.
elementWasUnhighlighted(element, nextHighlightedElement)
Triggered when an element loses highlight.
- Parameters:
-
{
Element
} element - The element that is newly being highlighted.
-
{
Element
} nextHighlightedElement - The element that is going to be highlighted next, or
null
if there is none.
elementWasUnhovered(element)
Triggered when an element is not hovered any longer, which only happens when a mouse is present.
- Parameters:
-
{
Element
} element - The element that is not hovered any longer.
handleEvent(event)
Entry point for all event handling, since
TKController
implements the DOM EventListener
protocol. This method may be subclassed
but it is important to call the superclass's implementation of this method as essential event routing happens there.
- Parameters:
- {Event} event
- The event.
{bool}
isDescendentOfController(purportedParentController)
Indicates whether the receiver is a descendent of the controller passed as an argument.
- Parameters:
-
{
TKController
} purportedParentController - The controller that we assume is a parent controller to the receiver.
- Returns:
- {bool} Whether the controller is a descendent of the other controller passed as a parameter.
{bool}
isViewLoaded()
Indicates whether the view the controller manages was loaded yet.
- Returns:
- {bool} Whether the view was loaded yet.
keyWasPressed(key)
Triggered when a key was pressed and the receiver has expressed explicit interest in providing custom key event handling by returning
true
in
the wantsToHandleKey
method.
- Parameters:
- {int} key
- The identifier for the key that was pressed.
{
Element
}
preferredElementToHighlightInDirection(currentElement, direction)
Allows the controller to provide the spatial navigation manager with a prefered element to highlight, overriding the default behavior of using CSS metrics.
The default implementation returns
undefined
, which indicates that the automatic behavior should be used, while returning null
means that there should be no element highlighted in the provided direction.
- Parameters:
-
{
Element
} currentElement - The element that is currently highlighted.
- {int} direction
- The direction the user is navigation towards.
- Returns:
- {
Element
} The preferred element to highlight in the provided direction.
processView()
This method is called once the view has been loaded and allows the controller to post-process it.
removeNavigableElement(element)
Removes an element within the controller's view from the list of navigable elements.
- Parameters:
-
{
Element
} element - The element we wish to remove from the navigable elements list.
<static>
{
TKController
}
TKController.resolveController(stringOrControllerReference)
A utility method to get the controller from an Object that is either the
TKController.id
of a controller or a controller directly.
- Parameters:
- {Object} stringOrControllerReference
- Either the
TKController.id
of a controller or a controller directly
- Returns:
- {
TKController
} The controller.
viewDidAppear()
This method is called when the view managed by this controller appeared on screen, probably after an animated transition.
viewDidDisappear()
This method is called when the view managed by this controller has disappeared from the screen, probably after an animated transition.
viewDidLoad()
This method is called when the view has been fully loaded but not yet processed. Override this method in order to customize the content of the view.
viewWasInsertedIntoDocument()
Triggered when the view is first inserted into the document.
viewWillAppear()
This method is called when the view managed by this controller is about to appear on screen, probably after an animated transition.
viewWillDisappear()
This method is called when the view managed by this controller is about to disappear from the screen, probably after an animated transition.
{bool}
wantsToHandleKey(key)
Indicates whether the controller is interested in providing event handling for the key with the given identifier. By default, this method returns
false
, letting the spatial navigation manager take care of the event in order to perform navigation. In case the method returns
true
, the keyWasPressed
method is called to let the controller provide its own custom key event handling.
- Parameters:
- {int} key
- The identifier for the key that was pressed.
- Returns:
- {bool} Whether the controller wants to provide its own custom key event handling.