Class Index | File Index

Classes


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.

Class Summary
Constructor Attributes Constructor Name and Description
 
TKController(data)
Field Summary
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.
 
id
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 Summary
Method Attributes Method Name and Description
 
Adds an element within the controller's view to the list of navigable elements.
 
Allows to specify custom metrics for an element displayed on screen.
 
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.
 
Triggered when an element is hovered, which only happens when a mouse is present.
 
elementWasUnhighlighted(element, nextHighlightedElement)
Triggered when an element loses highlight.
 
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.
 
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.
 
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.
 
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.

Copyright © 2009 Apple Inc. All rights reserved.