+
+ WRTKit is a JavaScript library for widgets running in the S60 Web Runtime (WRT)
+ that simplifies creation of user interfaces. User interfaces created with the
+ WRTKit automatically scales to any screen resolution, handle screen rotation
+ and resizes, work in both the tab and pointer navigation modes, and more.
+ Typically user interfaces that use the WRTKit can be created with just a few lines
+ of JavaScript code, yet still achieve a professional and consistent look and feel.
+
+
+
+
+ The look of a user interface created by the WRTKit is defined entirely using
+ Cascading Style Sheets (CSS) and image files. This allows easy customization of
+ a widget's look without the need to touch any code.
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_ActionControl_Class-GUID-6a7cb034-d676-4119-b799-7b3e3b5948e4.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_ActionControl_Class-GUID-6a7cb034-d676-4119-b799-7b3e3b5948e4.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,86 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+WRTKit ActionControl Class
+
+
+
+
+
+
+WRTKit ActionControl Class
+
+
+
+
+Description
+
+
+
+
+ The ActionControl class is an abstract base class for action controls like buttons.
+ ActionControl class does not introduce any new public methods or properties over
+ those inherited from its superclass. Don't instantiate ActionControl directly but
+ rather one of its subclasses.
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Actions-GUID-38771443-166b-4112-9569-c07229cd7449.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Actions-GUID-38771443-166b-4112-9569-c07229cd7449.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,94 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Actions
+
+
+
+
+
+
+Actions
+
+
+
+
+
+ Widgets can let users trigger actions in many ways. One way is by inserting menu
+ items in the Options menu, using the menu object that the S60 Web Runtime
+ defines. Another way is to use links that call JavaScript functions. Such links
+ could for example be included as part of content in a ContentPanel control.
+ Links belong more to web pages than widgets or applications, however, and are
+ not recommended except in cases when they result in a web URL being opened up in
+ a web browser (i.e. using the widget.openURL() method).
+
+
+
+
+ The third way is to use one of the WRTKit action controls: FormButton and
+ NavigationButton. Both controls are very similar in usage but differ greatly in
+ presentation and intended use. The FormButton control is meant to be used in
+ situations where pressing the button would result in some kind of process taking
+ place, e.g. settings being saved. The NavigationButton control is intended for
+ moving between views inside the widget, or other similar type of actions.
+ FormButton controls look similar to buttons in a PC application or "Submit"-
+ buttons on a web page. NavigatationButton controls don't really have a
+ counterpart in the PC application domain, but is common in mobile device
+ application that have large user interfaces that are split into several views.
+
+
+
Figure 1.
+NavigationButton controls
+
+
+
+
+
+
+
+ In an email widget, NavigationButton controls could be used so that there would
+ be a "Folders"-view where each folder (e.g. Inbox, Sent, Trash, etc.) would have
+ a corresponding NavigationButton. Clicking on the button for a folder would open
+ up that folder in a new view. FormButton controls could be used for example in a
+ view that lets users write new emails to trigger sending of the written email. A
+ FormButton in a view like that could have "Send" as the button text.
+
+
+
Figure 2.
+FormButton controls
+
+
+
+
+
+
+
+ The FormButton and NavigationButton controls fire events with the event type
+ "ActionPerformed" whenever a user presses the button. The event can be turned
+ into a function call to a callback function of the developer's choice by
+ registering the function to the control for the "ActionPerformed" event type.
+ This is done using the addEventListener() method that all controls inherit from
+ the UIElement base class.
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_ContentPanel_Class-GUID-bff5ac77-a652-480a-be3e-e3ca6283a45b.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_ContentPanel_Class-GUID-bff5ac77-a652-480a-be3e-e3ca6283a45b.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,548 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+WRTKit ContentPanel Class
+
+
+
+
+
+
+WRTKit ContentPanel Class
+
+
+
+
+Description
+
+
+
+
+ The ContentPanel class implements a control that is used to display arbitrary
+ XHTML content. The content panel can either be foldable (allows users to
+ toggle it open and close) or static. Like all controls the content panel has
+ an optional caption. But unlike for other controls, this caption area is an
+ interactive area that can be used to expand and collapse a foldable content
+ panel. Thus, foldable content panel should always have captions.
+
+
+ Creates a new instance of the ContentPanel class.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+id
+
+
+
+
+
+ Unique identifier for the control. Can be retrieved using the id property defined
+ in the UIElement class that this control inherits from. Useful for example to
+ identify the source of an event in event callback functions or to apply a CSS
+ rule to only this particular control. The identifier can be null, in which case
+ no id will be set for the control.
+
+
+
+
+
+
+
+
+caption
+
+
+
+
+
+ The caption text for the control. A null caption can be used to hide the
+ caption area. This is not recommended if the content panel is folding since
+ users cannot expand or collapse a foldable content panel without the caption
+ area being present.
+
+
+
+
+
+
+
+
+content
+
+
+
+
+
+ The content for the panel. If the argument is omitted or null then the content
+ area will be empty.
+
+
+
+
+
+
+
+
+foldable
+
+
+
+
+
+ Specifies the foldability of the content panel. Specify true to make the content
+ panel foldable and false to make it static. If the argument is omitted or null
+ then the content panel will default to being static.
+
+
+
+
+
+
+
+
+expanded
+
+
+
+
+
+ Specifies the expanded state of a foldable content panel. Specify true to make
+ the content panel expanded and false to make it collapse. If the argument is
+ omitted or null then the content panel will default to being expanded.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ A new instance of the ContentPanel class.
+
+
+
+
+
+Example code
+
+
+
+
+ Creating a foldable content panel with content:
+
+
+
+
+var panel1 = new ContentPanel("panel1", "Example Panel", "This is some content");
+
+
+
+
+ Creating a static content panel with content:
+
+
+
+
+var panel2 = new ContentPanel("panel2", "Example Panel", "This is some content", false);
+
+
+
+
+ Creating a foldable content panel and given it content in a separate step:
+
+
+
+
+var panel3 = new ContentPanel("panel3", "Example Panel");
+panel3.setContent("This is some content");
+
+
+
+
+
+
+
+
+
+
+
+getContent()
+
+
+
+
+Syntax
+
+
+
+[String] ContentPanel.getContent(void)
+
+
+
+
+Description
+
+
+
+
+ Retrieves the current content (an XHTML fragment) of the content panel.
+
+
+
+
+
+Arguments
+
+
+
+
+ This method does not take any arguments.
+
+
+
+
+
+Return value
+
+
+
+
+ The current content of the content area.
+
+
+
+
+
+
+
+
+
+
+
+setContent()
+
+
+
+
+Syntax
+
+
+
+[void] ContentPanel.setContent(String content)
+
+
+
+
+Description
+
+
+
+
+ Sets the content for the content panel as a fragment of XHTML. If null is
+ specified as the content then the content area will be empty.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+content
+
+
+
+
+
+ A fragment of XHTML to set as content for the content area of the content panel.
+ A null value can be used to make the content area empty.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ This method does not return a value.
+
+
+
+
+
+
+
+
+
+
+
+isExpanded()
+
+
+
+
+Syntax
+
+
+
+[Boolean] ContentPanel.isExpanded(void)
+
+
+
+
+Description
+
+
+
+
+ Retrieves the expanded state of the content area.
+
+
+
+
+
+Arguments
+
+
+
+
+ This method does not take any arguments.
+
+
+
+
+
+Return value
+
+
+
+
+ The current expanded state of the content area; true if expanded, false if collapsed.
+
+
+
+
+
+
+
+
+
+
+
+setExpanded()
+
+
+
+
+Syntax
+
+
+
+[void] ContentPanel.setExpanded(Boolean state)
+
+
+
+
+Description
+
+
+
+
+ Sets the expanded state of the content area for a foldable content panel.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+state
+
+
+
+
+
+ The new expanded state for the content area; true to expand, false to collapse.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ This method does not return a value.
+
+
+
+
+
+
+
+
+
+
+
+contentElement
+
+
+
+
+Syntax
+
+
+
+[HTMLElement] ContentPanel.contentElement
+
+
+
+
+Description
+
+
+
+
+ The contentElement property allows direct access to the content of a content
+ panel. Typically content is set to a content panel using the setContent() method,
+ passing it an XHTML fragment as a string but if DOM methods are preferred then the
+ contentElement can be used as a root HTML element to attach content to, e.g.
+ using the DOM appendChild() method.
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Control_Class-GUID-6ddb8154-3fed-40fc-b282-85e6d3ad494f.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Control_Class-GUID-6ddb8154-3fed-40fc-b282-85e6d3ad494f.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,609 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+WRTKit Control Class
+
+
+
+
+
+
+WRTKit Control Class
+
+
+
+
+Description
+
+
+
+
+ The Control class is an abstract base class for user interface controls.
+ Don't instantiate Control directly but rather one of its subclasses.
+
+
+ Retrieves the current caption of the control.
+ The value is an XHTML string.
+
+
+
+
+
+Arguments
+
+
+
+
+ This method does not take any arguments.
+
+
+
+
+
+Return value
+
+
+
+
+ The current caption of the control or null if the control doesn't have a caption.
+
+
+
+
+
+
+
+
+
+
+
+setCaption()
+
+
+
+
+Syntax
+
+
+
+[void] Control.setCaption(String caption)
+
+
+
+
+Description
+
+
+
+
+ Sets the caption for the control. If null is specified as the caption
+ then the caption is removed (entirely hidden) for the control.
+ The value is an XHTML string.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+caption
+
+
+
+
+
+ The new caption for the control or null for no caption.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ This method does not return a value.
+
+
+
+
+
+
+
+
+
+
+
+isEnabled()
+
+
+
+
+Syntax
+
+
+
+[Boolean] Control.isEnabled(void)
+
+
+
+
+Description
+
+
+
+
+ Retrieves the enabled state of the control.
+
+
+
+
+
+Arguments
+
+
+
+
+ This method does not take any arguments.
+
+
+
+
+
+Return value
+
+
+
+
+ The current enabled state of the control.
+
+
+
+
+
+
+
+
+
+
+
+setEnabled()
+
+
+
+
+Syntax
+
+
+
+[void] Control.setEnabled(Boolean state)
+
+
+
+
+Description
+
+
+
+
+ Sets the enabled state for the control.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+state
+
+
+
+
+
+ The new enabled state for the control; true to enable, false to disable.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ This method does not return a value.
+
+
+
+
+
+
+
+
+
+
+
+isFocusable()
+
+
+
+
+Syntax
+
+
+
+[Boolean] Control.isFocusable(void)
+
+
+
+
+Description
+
+
+
+
+ Retrieves the focusable state of a control. The focusable state tells
+ whether the control can be focused or not. E.g. a label control cannot
+ be focused because it does not have any interactive action to perform.
+
+
+
+
+
+Arguments
+
+
+
+
+ This method does not take any arguments.
+
+
+
+
+
+Return value
+
+
+
+
+ The focusable state of the control.
+
+
+
+
+
+
+
+
+
+
+
+isFocused()
+
+
+
+
+Syntax
+
+
+
+[Boolean] Control.isFocused(void)
+
+
+
+
+Description
+
+
+
+
+ Retrieves the focused state of the control.
+
+
+
+
+
+Arguments
+
+
+
+
+ This method does not take any arguments.
+
+
+
+
+
+Return value
+
+
+
+
+ The current focused state of the control.
+
+
+
+
+
+
+
+
+
+
+
+setFocused()
+
+
+
+
+Syntax
+
+
+
+[void] Control.setFocused(Boolean state)
+
+
+
+
+Description
+
+
+
+
+ Sets the focused state for the control. Note that it's not always possible
+ to carry out the request to focus a control. E.g. a control might not be
+ visible or the focus might be locked to another control.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+state
+
+
+
+
+
+ The new focused state for the control; true to focus, false to blur.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ This method does not return a value.
+
+
+
+
+
+
+
+
+
+
+
+updateStyleFromState()
+
+
+
+
+Syntax
+
+
+
+[void] Control.updateStyleFromState()
+
+
+
+
+Description
+
+
+
+
+ Called to let the control update its style to match its internal state.
+ The method doesn't need to be called manually as the toolkit takes care of
+ calling it whenever the state of a control changes. Override this method
+ if you wish to implement custom styling for a control. Typically using
+ CSS rules will be sufficient for customizing looks so only use this method
+ when CSS is insufficient.
+
+
+
+
+
+Arguments
+
+
+
+
+ This method does not take any arguments.
+
+
+
+
+
+Return value
+
+
+
+
+ This method does not return a value.
+
+
+
+
+
+
+
+
+
+
+
+view
+
+
+
+
+Syntax
+
+
+
+[View] Control.view
+
+
+
+
+Description
+
+
+
+
+ The view property references the view that the control is attached to.
+ If the control has not been attached to any view then the property is null.
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Control_states-GUID-f98575ac-f913-466d-a790-0ff0207463a3.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Control_states-GUID-f98575ac-f913-466d-a790-0ff0207463a3.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,144 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Control states
+
+
+
+
+
+
+Control states
+
+
+
+
+
+ Controls can be in a number of different states. Some of the states are specific
+ to a particular type of control (e.g. whether a checkbox is checked) and some
+ are common to all controls. Some states can be explicitly set while others are
+ implicit based on some user action (e.g. moving the pointer over a control).
+ The states can be retrieved using "getter" functions and in cases when a state
+ can be explicitly set there is a "setter" function that allows the state to be
+ manipulated. The following presents the common control states.
+
+
+
+Focusable
+
+
+
+
+ The focusable state is a boolean (i.e. true or false) value that indicates
+ whether the control can receive the focus and receive input or not. Some
+ non-interactive controls like labels are never focusable, others are focusable
+ unless the control has specifically been disabled, and some are always
+ focusable. E.g. textfields can be focused even when disabled in order to be able
+ to copy text from them to the clipboard.
+
+
+
+
+
+Focused
+
+
+
+
+ The focused state is a boolean value that specifies if a control is currently
+ selected for interaction. The focused typically changes implicitly through user
+ actions like moving the 4-way controller, however the focus can also be
+ explicitly set. Unlike other states, setting the focus to a control is more like
+ a request than an absolute command because it is not always possible to actually
+ set the focus to the control to which it is requested. For example if a control
+ is not focusable or not visible on the screen, the focus cannot be set to it.
+
+
+ Hovering means that the pointer arrow is over a control. It is always implicit
+ and changes based on pointer movement. The hovering state is a boolean value.
+ The hovering state is rarely needed outside a control itself, which uses it to
+ determine how the control draws itself.
+
+
+
+
+
+Enabled
+
+
+
+
+ Controls are always enabled by default, but can be disabled to prevent
+ interaction. Disabling a control doesn't hide it but rather causes it to be
+ displayed in some way (typically with dimmer or duller colors) that indicates to
+ users that it cannot be used. Toggling the enabled state is always an explicit
+ action. The enabled state is a boolean value. Note that toggling the enabled
+ state can have an effect on other things. Focus is typically lost from controls
+ that are disabled and they become non-focusable.
+
+
+ Certain controls like textfields cannot be interacted with despite being
+ focused. Instead the focus merely indicates that they are selected for
+ interaction. In order to actually interact with them they have to be "activated"
+ by pressing a selection button. The reason for this is that the same 4-way
+ controller keys are used for navigating between controls and within a control.
+ When a control such as a textfield is activated, all key presses are consumed by
+ the control. Activation of a control is transparent to the WRTKit and due to
+ this cannot be queried nor commanded. Also note that activation is not needed on
+ PC computers and thus will not occur when testing a WRTKit user interface in a
+ PC browser.
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Creating_a_widget_that_uses_the_WRTKit-GUID-8d71ee32-1826-4141-8fb6-76420a5472a4.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Creating_a_widget_that_uses_the_WRTKit-GUID-8d71ee32-1826-4141-8fb6-76420a5472a4.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,197 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Creating a widget that uses the WRTKit
+
+
+
+
+
+
+Creating a widget that uses the WRTKit
+
+
+
+
+
+ To create a widget the uses the WRTKit for its user interface, start by copying
+ the WRTKit directory from the Library directory in the WRTKit to the root
+ directory of the widget you are making. The root directory of your widget is
+ the directory where your Info.plist and main HTML file is located.
+
+
+
+
+ The main HTML file should include a script tag that loads the file
+ WRTKit/WRTKit.js in order to include and initialize the WRTKit library in your
+ widget. The widget typically should have no content at all between its
+ <body> and </body> tags. You also want to include the JavaScript
+ script file where your own widget's code is located, and you want to define some
+ entry point function that gets called when the widget is loaded, e.g. using the
+ onload event that you can define for the body tag. This should result in an HTML
+ file that looks something like this:
+
+
+ In this example the code for your own widget is in a file called YourOwnWidgetCode.js
+ and the entry point function that gets called when the widget has loaded all files is
+ called init(). Next, we want to create that function.
+
+
+
+
+ All widgets that use the WRTKit need to create an instance of the UIManager class, as
+ well as at least one view. Creating the UIManager is a simple matter of instantiating
+ the WRTKit UIManager class. You should retain the reference to that instance in a
+ global variable or some other place that is accessible to the code that will need to
+ use the UIManager's services. To do this, you would first declare the global variable
+ to hold your UIManager instance:
+
+
+
+
+// Reference to the user interface manager.
+var uiManager;
+
+
+
+
+ With the variable declared you can then add the following code to the init() function
+ to create an instance of the UIManager class and retain a reference to that instance
+ in the uiManager variable:
+
+
+
+
+// create the user interface manager
+uiManager = new UIManager();
+
+
+
+
+ Now that we have a user interface manager instance we can create a new view and set it
+ to the screen. In order to be able to access that view outside the init() function, we
+ should crate a global variable for it just like we did for the UIManager instance:
+
+
+
+
+// Reference to the main view.
+var mainView;
+
+
+
+
+ In this example we will create a ListView that has a unique identifier "example" and
+ a view caption "Example View". The unique identifier can be used to set CSS rules that
+ are targeted to a particular view. It is often not needed and can be specified as null.
+ The view caption is shown at the top of list views and is helpful to show users what
+ the view is for.
+
+
+
+
+// create the main view
+mainView = new ListView("example", "Example View");
+
+
+
+
+ We are now ready to command the view to the screen:
+
+
+
+
+// show the mainView
+uiManager.setView(mainView);
+
+
+
+
+ The example widget would now be displaying an empty list view with "Example View" in
+ its view caption and would be ready for more functionality. Let's add a button to the
+ view. You would normally do this before the view is shown. Our example button has a
+ unique identifier "exampleButton" and text "Press me!" on the face of the button.
+
+
+
+
+// add a button to the main view
+var exampleButton = new FormButton("exampleButton", "Press me!");
+mainView.addControl(exampleButton);
+
+
+
+
+ The main view now contains a button. If we wanted to be informed when the button is
+ pressed we could create a new function and register it as an "event listener". First
+ the callback function definition:
+
+
+
+
+// Callback function that gets called when the example button is pressed.
+function exampleButtonPressed(event) {
+ // popup a notification dialog when the button is pressed
+ uiManager.showNotification(3000, "info", "You pressed the button!");
+}
+
+
+
+
+ Now that we have a function to call when the button is pressed we can register the
+ event listener. You should write this code in the init() function, for example right
+ after you created the button:
+
+
+
+
+// add an event listener
+exampleButton.addEventListener("ActionPerformed", exampleButtonPressed);
+
+
+
+
+ The same idea applies even to much more complex user interfaces. You create views and
+ controls, add the controls to the views, command a view to be displayed using the
+ UIManager, and get notified of user actions using event listeners that you can
+ register to the controls.
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Creating_the_Hello_World_widget-GUID-d638159a-d12b-476c-a74c-99055672b7be.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Creating_the_Hello_World_widget-GUID-d638159a-d12b-476c-a74c-99055672b7be.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,534 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Creating the Hello World widget
+
+
+
+
+
+
+Creating the Hello World widget
+
+
+
+
+What goes in the widget?
+
+
+
+
+ One of the main reasons why Hello World is a good example to start with is
+ because it is a minimal widget and shows the minimal set of steps that you
+ would go through to create a widget that uses the WRTKit for its user interface.
+ We will create just two files, an HTML file called HelloWorld.html and a JavaScript
+ file called HelloWorld.js and both will be very short.
+
+
+
+
+ Before we'll start writing code let's talk about what exactly it is that we want
+ to build. A typical Hello World application simply displays the text Hello World
+ with the minimal amount of code. But because using the WRTKit is so simple, we'll
+ go one step further and make it a bit fancier.
+
+
+
+
+ WRTKit user interfaces are composed of views and controls. A view is one logical
+ group of stuff that you can see on the screen. A view can be longer than what fits
+ on the screen at once in which case the user has to scroll, but it's still one view.
+ For example in a web browser application you might have one view for the bookmarks,
+ another for settings and a third view for viewing actual web pages. Controls are
+ user interface elements like buttons, text fields, checkboxes, etc. that either
+ let the user perform some kind of interactive action or simply shows some information.
+ When you create a user interface with the WRTKit you create one or more controls,
+ one or more views, and place the controls on the views. After this, all you have to
+ do is ask one of the views to be displayed and the rest happens automatically.
+
+
+
+
+ Since this is a very simple widget we will just have one view and we'll call it
+ the "main view". Instead of just saying "Hello World" we will let the user input
+ their name and then click a button to popup a dialog that says hello to the user
+ by name. E.g. if the user enters "John" we will popup "Hello John!". But we will
+ also create some error handling so that if the user doesn't input a name we will
+ popup a warning dialog that says "Please enter your name!" instead.
+
+
+
+
+
+The HelloWorld.html file
+
+
+
+
+ As mentioned earlier, you create user interfaces using JavaScript rather than
+ HTML when you use the WRTKit. Because of this it's perhaps not so surprising
+ that the HTML file is extremely short. What might come as a surprise however is
+ that it's extremely short and nearly identical no matter what kind of widget
+ you are building if you are using the WRTKit. In fact it typically only has
+ about 10 lines of code, including the DOCTYPE declaration! Here's what it looks
+ like:
+
+
+ We're using XHTML 1.0 so the DOCTYPE declaration is for XHTML 1.0 Strict. And
+ because this is XHTML we also have the normal XML declaration (<?xml...).
+ After that the content should be familiar even if you've used previously only
+ used HTML rather than XHTML. We have a normal html root level tag with a head
+ and body. Note that in XHTML tags are case sensitive and should be in lowercase
+ as in the example above. The xmlns attribute is a name space declaration that
+ states that all the tags used here are part of the XHTML standard.
+
+
+
+
+ Because we're creating a widget and not a web page we don't need to have a title. If you
+ want you can define one here but you won't see it anywhere. Next comes an important
+ bit:
+<script type="text/javascript" src="WRTKit/WRTKit.js"></script>.
+ That piece of code instructs the Web Runtime to load a JavaScript file called WRTKit.js
+ from a directory called WRTKit. The WRTKit.js file takes care of loading the WRTKit and
+ including all the files that are needed by it. Those files are all inside the WRTKit
+ directory and you don't need to concern yourself with them at this point. In fact
+ all you need to do to use the WRTKit in a widget is to copy the WRTKit directory into
+ your own widget's root directory and then include the XHTML script tag presented above
+ that loads the WRTKit/WRTKit.js JavaScript file. If you are creating a widget of your own
+ you can find the WRTKit directory in the Library directory in the WRTKit SDK. But for your
+ convenience it has already been copied to the Hello World example.
+
+
+
+
+ Notice that there's another script tag too, this one loading a file called HelloWorld.js.
+ This is where we'll put all the JavaScript code that implements our Hello World widget.
+ We could have just written the JavaScript code inline between a <script> and
+ </script> tag in the HelloWorld.html file but the HTML file is less cluttered if
+ we move all JavaScript to a separate file.
+
+
+
+
+ Finally let's look at the body tag. There are two things of interest here. First of all
+ there's no content between <body> and </body>. That's because all of the
+ content will be created by the WRTKit using JavaScript. And that leads us to the other
+ point of interest in the body: the
+onload="init()" attribute of the
+ body tag. This sets up an event handler that gets called after the widget has loaded
+ all of its content. The event handler calls a JavaScript function called init(). This
+ is the point where we jump from the HTML to JavaScript. From this point on everything
+ will be JavaScript and the place where it all starts is the init() function that gets
+ called thanks to this little onload event handler for the body tag.
+
+
+
+
+
+The HelloWorld.js file
+
+
+
+
+ The HTML file that we created above set things up so that there is a function call
+ to a function named "init()" when the widget is done loading. No such function exists
+ a this point so we have to create it. The init() function is the entry point to our
+ JavaScript and this is also where we will start the implementation.
+
+
+
+
+ The S60 Web Runtime supports two kinds of user interface interaction: tab and
+ pointer. The WRTKit supports but methods but usually the tab interaction method
+ (also known as "navigation mode") is preferred. Unfortunately the pointer based
+ navigation mode is the default so we'll have to disable it and switch to the tab
+ navigation mode. Also by default the softkey bar is hidden, which we don't want
+ because we want to give the user a clue about how to exit the widget. The good news
+ is that these two tweaks are easy to do and only requires two simple method calls.
+ The bad news is that those method calls are done through objects that only exist
+ in the Web Runtime but not in a PC web browser. Due to this, we'll create the
+ init() function as follows:
+
+
+
+
+// Called from the onload event handler to initialize the widget.
+function init() {
+ // set tab-navigation mode and show softkeys
+ // (only if we are in the WRT environment)
+ if (window.widget) {
+ widget.setNavigationEnabled(false);
+ menu.showSoftkeys();
+ }
+}
+
+
+
+
+ We wrapped the calls to disable the pointer navigation and show the softkeys
+ in an if-clause that checks if there's such an object available as window.widget.
+ This will evaluate to false on a PC web browser but true in the S60 Web Runtime.
+
+
+
+
+ Now that we've tuned the Web Runtime to our liking we can create the actual
+ user interface. We'll create four things: the so-called "user interface manager"
+ that is in charge of managing views and other user interface resources, the main
+ view for the widget, a text field where users can enter their name, and finally
+ a button that they can click on to popup a notification dialog that says "Hello"
+ Notice that we don't have to create the notification dialog because this is done
+ for us by the user interface manager.
+
+
+
+
+ Before we create those four objects we will declare four global variables so that
+ we can access those objects elsewhere in the widget. So let's add the following
+ to the top of the file (outside the init() function):
+
+
+
+
+// References to the WRTKit user interface manager and main view.
+var uiManager;
+var mainView;
+
+// References to controls in the main view.
+var helloButton;
+var nameField;
+
+
+
+
+ Now that we have some variables that can track the objects we are about to create
+ we can actually craete those objects. We'll create the objects inside the init()
+ function so that the user interface gets created right after the widget has loaded.
+
+
+
+
+ The first thing we create is the user interface manager. This is quite simple and
+ requires only a single line of code:
+
+
+
+
+// create UI manager
+uiManager = new UIManager();
+
+
+
+
+ Next we'll create the main view. The WRTKit allows all kinds of views to be created
+ if one has special needs for how user interface controls should be laid out. However
+ in the vast majority of cases the ListView class will be sufficient and that's what
+ we'll create this time too:
+
+
+
+
+// create main view
+mainView = new ListView(null, "Hello World");
+
+
+
+
+ The first argument to the ListView constructor is a unique identifier for the view.
+ All user interface elements in the WRTKit can have a unique identifier. The identifier
+ is helpful if you want to specifically target a view or control with some CSS style
+ rule or if you want to identify the source of an event in an event listener callback,
+ etc. However we don't need it here so we don't bother giving our main view a unique
+ id and just pass a null identifier value instead. The second argument is a caption for
+ the view. We'll just call our view "Hello World". The caption will be displayed at the
+ very top of the screen when we display the main view. But before we do that, let's
+ create the rest of the user interface.
+
+
+
+
+ The widget should have a text field to let users enter their name and a button to
+ trigger the greeting popup. Both the text field and the button are WRTKit controls
+ and will be created and added to the main view that we just created. There are two
+ kinds of buttons in the WRTKit though, form buttons and navigation buttons. Form
+ buttons are meant to trigger actions whereas navigation buttons are meant for
+ situations where clicking it would result in moving from one view to another. Clearly
+ therefore, we want a form button in this case.
+
+
+
+
+ Creating the textfield and form button is done as follows:
+
+
+
+
+// add a text field to the view
+nameField = new TextField(null, "Enter your name");
+mainView.addControl(nameField);
+
+// add a button to the view
+helloButton = new FormButton(null, "Say Hello!");
+mainView.addControl(helloButton);
+
+
+
+
+ The first argument for both the textfield and button is the same as for the view:
+ an optional unique identifier. We won't need it here either so rather than scratching
+ our heads trying to come up with a unique identifier that we'll end up ignoring we'll
+ just define it as null. The second argument for the textfield constructor is a caption.
+ All controls except buttons have captions and this is the second argument in all
+ constructors for controls with captions. The caption is displayed above the control
+ and tells the user what the control does. In our case we want to have a textfield where
+ the user should enter the name so we'll use "Enter your name" as the control caption.
+ The second argument for the button constructor is the text for the button. The button
+ text for form buttons should be a verb or other descriptive text that lets the user know
+ what happens if the button is pressed. We'll put "Say Hello!" on our button.
+
+
+
+
+ After we have created a control we can add it to a view. Custom views can have their
+ own ways to do so but in the case of the default ListView that you'll use in most cases
+ you add a control by calling the addControl() method.
+
+
+
+
+ The user interface for the main view is now ready and we can show it. Showing a view
+ is done by calling setView() in the user interface manager. So we'll add one more line
+ of code to the end of the init() function:
+
+
+
+
+// display the main view
+uiManager.setView(mainView);
+
+
+
+
+ If you zipped up the widget directory, renamed it HelloWorld.wgz and installed the
+ widget on an emulator or handset, or just simply ran it in a PC web browser, you'd
+ notice that the user interface seems to work. There's just one problem. Clicking on
+ the button doesn't do anything! But don't worry, we're about to fix that.
+
+
+
+
+
+Handling events
+
+
+
+
+ The thing that is missing is that we have no way of knowing when the button was
+ pressed. And without knowing when it's pressed we can't react to the press and
+ show a greeting. A user interface action such as pressing a button is called an
+ "event". In the WRTKit events are reported to "listener" functions that developers
+ can register to controls. The way this is done is by creating a function that you
+ want to get called when an event occurrs, and then calling addEventListener() on
+ the control whose events you are interested in, passing the function to that method.
+ However there are many types of events and you are almost surely not interested in
+ all of them. Because of this you can specify the type of event that you want to get
+ notified about by giving the event type name to the addEventListener() method. The
+ event types and their names are described in the
+
+WRTKit API Reference
+ for each control. Note that because controls inherit from other classes they also
+ inherit event types.
+
+
+
+
+ The event type that we're interested in here is "ActionPerformed". That event is
+ fired by form buttons whenever a user clicks on them. In order to get notified
+ of this event we'll need two things: create a function that will get called when
+ the event occurs and register that function as an event listener to our button.
+ Let's create the function first but leave the implementation empty for now:
+
+
+
+
+// Called when the hello-button is clicked.
+function helloButtonClicked(event) {}
+
+
+
+
+ Now that we have the event handler callback function we can add the event listener
+ registration code. Let's put that right after where we create the button in
+ the init() function:
+
+
+ Now our helloButtonClicked() function will get called whenever the button is
+ clicked. Notice that the function has an argument called event. This argument
+ will receive an event object that describes the event that occurred. This can
+ be useful if you have an event handler function that handles many different
+ events. The event object contains three properties that you can examine to
+ decide on what to do: a property called "source" that points back to the control
+ or view from where the event was fired, a property called "type" that contains
+ the event type name for this event, and a property called "value" that has
+ helpful additional info that depends on the event type. You'll find more detailed
+ information about this in the API Reference.
+
+
+
+
+
+Notification popup dialogs
+
+
+
+
+ All that remains now is to write the code that shows the greeting popup dialog
+ when the button is pressed. This code will naturally go in the helloButtonClicked()
+ function.
+
+
+
+
+ Using notification popup dialogs is very easy with the WRTKit. The user interface
+ manager has two methods: showNotification() and hideNotification() that are used
+ to show and hide notification popup dialogs. The showNotification() method takes
+ four arguments: displayTime, type, text and progress. The displayTime argument is
+ used to supply a time (in milliseconds) for how long the notification popup should
+ be shown for. We want our greeting to be visible for 3 seconds so we'll pass 3000
+ to this argument. The type argument is a string that tells the method what kind of
+ popup to show, which determines the visual style of the popup. We'll be using two types:
+ "info" and "warning". The "info" type for when we show the greeting and "warning" if
+ the user didn't enter a name and we want to show a notification dialog that complains
+ about this. The text argument is simply the text to show in the notification dialog.
+ And finally the progess argument is a decimal number between 0.0 and 1.0 that is
+ used in progress dialogs to display how far along a process is.
+
+
+
+
+ A progress of 0.0 means "0% progress" and 1.0 means "100% progress". So for example
+ if some process is 25% completed, you'd pass 0.25 to this argument. If you don't know
+ how long a process will take you can pass a negative number. This will result in an
+ animated progress bar that has a visual style that indicates that the progress is
+ unknown. Typically you'd use the "wait" notification type is you want to show a
+ progress dialog. If you don't want to show any progress information in the dialog,
+ such as in our case, you can omit the progress argument or pass a null to it.
+
+
+
+
+ Before we can write our code we need one more thing. We need to know what the user
+ wrote in the name textfield. This value can be retrieved by calling the getText()
+ method for the textfield. We're now ready to write the code for the helloButtonClicked()
+ function:
+
+
+
+
+var name = nameField.getText();
+if (name.length == "") {
+ uiManager.showNotification(3000, "warning", "Please enter your name!");
+} else {
+ uiManager.showNotification(3000, "info", "Hello " + name + "!");
+}
+
+
+
Figure 1.
+The Hello World widget
+
+
+
+
+
+
+
+
+Wrapping up
+
+
+
+
+ The Hello World widget is now done and you can zip it up, rename it to HelloWorld.wgz
+ and deploy it on a handset or emulator. But before that, let's try it in a normal PC
+ browser. Testing in a PC browser is useful because it allows you to use deubugging tools
+ (like the Firebug JavaScript debugger for Firefox) in case something isn't working. Using
+ a PC browser to test is also very fast because you don't have to install the widget to
+ the emulator or handset. Just hit reload in the web browser when you make a change and
+ you can see the results immediately. Of course there are features that will be missing
+ in a web browser, such as that you won't have access to the Options menu or any other
+ advanced widget functionality. But for the purpose of rapidly testing user interfaces
+ it can be very helpful.
+
+
+
+
+ There are a couple of points that are good to note now that the widget is ready.
+ First of all, your widget now works with both the pointer and tab navigation modes. If
+ you comment out the
+widget.setNavigationEnabled(false) call in the init()
+ function you can try this out. Second, your widget works resolution independently.
+ You can try this either by resizing the PC browser window or by trying the widget out
+ with different resolutions in the S60 emulator. Third, the widget correctly handles
+ screen rotations and other resizes, e.g. if the softkey bar is hidden / shown. Fourth,
+ the widget looks can be customized without needing to touch any code - simply by changing
+ the UI.css and image files that you can find in the WRTKit/Resources directory.
+
+
+
+
+ But perhaps more important than any of the above is the fact that the WRTKit simplifies
+ the separation of user interface code from data and logic code. That's not something
+ that is apparent in a simple widget like this one, but it becomes very important as
+ you create something more complex and especially if the user interface contains elements
+ that are created dynamically for example based on data that has been fetched from the
+ Internet using AJAX.
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Customizing_the_WRTKit_look-GUID-43369c51-23cf-41ac-a2f4-6320dc6eda9a.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Customizing_the_WRTKit_look-GUID-43369c51-23cf-41ac-a2f4-6320dc6eda9a.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,105 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Customizing the WRTKit look
+
+
+
+
+
+
+Customizing the WRTKit look
+
+
+
+
+
+ All visuals in the WRTKit are defined using CSS and images that are
+ located inside the WRTKit library in the Resources directory. The
+ code that implements the WRTKit user interface elements does not
+ actually know or care what the user interface looks like. Instead
+ the code creates an HTML element hierarchy to implement each control
+ and view and then sets CSS style class names to these elements.
+ Whenever the state changes (e.g. the control gets focused) the class
+ names are updated to reflect the new state. The CSS in the Resources
+ directory defines the style rules for the class names and visuals
+ are applied to the controls and views like for any other CSS styled
+ HTML elements. This results in a system where only CSS and images
+ need to be modified in order to implement a new look for a custom
+ WRTKit user interface - but no JavaScript code.
+
+
+
+
+ All CSS rules for the WRTKit are defined in a file called UI.css in
+ the WRTKit library Resources directory. This file defines hundreds
+ of style classes and can seem intimidating and complex, but the
+ principle behind the classes is actually very simple. Each HTML
+ element in each control has a common class and a set of state-
+ specific classes. E.g. the text element in the NavigationButton
+ control has "NavigationButtonText", "NavigationButtonTextNormal",
+ "NavigationButtonTextFocus", etc. The classes are applied based on
+ the current state of that element. So in our example if the button
+ was focused, the text element would be assigned the CSS classes
+ "NavigationButtonText" and "NavigationButtonTextFocus". Two classes
+ define all of the styling for the text element portion of the
+ NavigationButton control in the focused state.
+
+
+
+
+ Using two classes at the same time is convenient because it allows
+ common elements to be defined in the common class and only special
+ adaptations of that common rule in the state-specific class. One
+ pattern that is repeated throughout the WRTKit is to define a
+ background image in the common class and an image position offset in
+ the state-specific class. This makes switching from one state to
+ another (e.g. when a checkbox is checked) very straight forward.
+ Even if the graphics appear to change, no images need to be loaded
+ or switched but instead just the image offset changes and the result
+ is that the graphics have changed.
+
+
+
+
+ Controls and views use HTML element hierarchies that are fine
+ grained enough that various kinds of layout customizations can be
+ applied without having CSS styles affect parts of a control that
+ they were not intended to affect. The result is more CSS rules and
+ more expansive element hierarchies, but also more freedom and
+ flexibility.
+
+
+
+
+ In most cases all that is needed to change the visuals of a WRTKit
+ user interface is to modify the images in the Resource directory and
+ update the color definitions for controls in the CSS file. The image
+ files that supply graphics to views and controls in the Resource
+ directory are named with clear names to make customization easy.
+ Just make a backup copy of the default graphics and CSS styles and
+ experiment! You will probably be surprised at how easy it is to make
+ a custom user interface theme!
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Design_considerations-GUID-cd4c583d-e6d8-4aab-b2d8-dba09dd7a009.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Design_considerations-GUID-cd4c583d-e6d8-4aab-b2d8-dba09dd7a009.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,114 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+WRTKit design considerations
+
+
+
+
+
+
+WRTKit design considerations
+
+
+
+
+User interface design
+
+
+
+
+ The WRTKit uses views and controls as the basis for all user
+ interfaces, and those views and controls have a look and feel that
+ is more similar to mobile device applications than to web pages,
+ despite the fact that the underlying technology is HTML, CSS and
+ JavaScript. The WRTKit supports both the tab and pointer based
+ navigations modes but staying true with the application-like look
+ and feel, it's often a good idea to use the tab navigation mode as
+ that will probably be more familiar to users.
+
+
+
+
+ Consistency and clarity help guiding the user through the widget
+ user interface. As the saying goes, less is more. Instead of having
+ a huge user interface that users must scroll through to get to what
+ they want, consider dividing the user interface into multiple views
+ that only contain controls and functionality that logically fits
+ together. Use NavigationButton controls or the Options menu for
+ navigation between the views.
+
+
+
+
+ Keep in mind that the right softkey can be programmatically changed.
+ You can take advantage of this, for example so that you use it to
+ allow users to return back to the previous or parent view.
+
+
+
+
+ Consider placing all configurable options in a view that the user
+ can access from the Options menu. If there are more configurable
+ options than what fits within one or two screenfuls then it's
+ probably a good idea to split them into multiple views.
+
+
+
+
+ Errors happen so keep those in mind when designing the widget.
+ The WRTKit offers easy to use notification popup dialogs that
+ can be used to show error messages in a way that will be familiar
+ to the user.
+
+
+
+
+
+Security
+
+
+
+
+ Most of methods in the WRTKit that accept strings as parameters
+ use XHTML in their values. This allows the use of custom styles
+ and other rich content in control and view captions, label
+ values, content in content panels, and more. But like always
+ when dealing with untrusted data from the Internet, you have to
+ be careful with the data that you display in the user interface
+ so that you don't end up placing malicious HTML (e.g. with
+ script tags containing hostile code) into your user interface.
+
+
+
+
+ Always filter the content that you fetch using AJAX to make sure
+ that no HTML tags have been injected into that content. This is
+ a good idea in any case even if there are no malicious intents,
+ since arbitrary HTML mixed into content can easily cause your
+ user interface to behave in unpredictable ways.
+
+
+ The Developer's Guide is intended for developer's who wish to use
+ the WRTKit to develop user interfaces in their own widgets. The
+ guide is divided into three parts: an overview of what the WRTKit
+ is and how it works, a more detailed description of the various
+ components in the WRTKit and the components fit together, and
+ finally a description of common WRTKit tasks.
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Developing_widgets_using_the_WRTKit-GUID-a321db96-0a01-4e55-b24b-96905f40cb5c.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Developing_widgets_using_the_WRTKit-GUID-a321db96-0a01-4e55-b24b-96905f40cb5c.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,72 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Developing widgets using the WRTKit
+
+
+
+
+
+
+Developing widgets using the WRTKit
+
+
+
+
+
+ This section of the Developer's Guide describes the WRTKit in detail,
+ presents the various components that make up the WRTKit library and
+ explains hwo the components fit together.
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Displaying_content-GUID-57647864-5231-47e5-8ad5-f2adb1848760.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Displaying_content-GUID-57647864-5231-47e5-8ad5-f2adb1848760.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,85 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Displaying content
+
+
+
+
+
+
+Displaying content
+
+
+
+
+
+ The WRTKit contains two controls that are intended simply for displaying content
+ of some kind. The simplest of these is the Label control, which is simply
+ showing a piece of text below its caption. Labels are useful in situations where
+ there is some short data that needs to be shown without requiring any kind of
+ interactivity. E.g. in an address book widget, each information field for a
+ contact could be shown using its own label. One label for the contact's name,
+ one for the phone number, etc. The control caption would indicate what the
+ information is (e.g. "Name") and the label's value would indicate the actual
+ piece of data (e.g. "John Smith").
+
+
+
+
+ For situations where the content is more complex or longer, the WRTKit offers a
+ control called ContentPanel. The ContentPanel control can be foldable or non-
+ foldable. In its non-foldable mode a ContentPanel is similar to the label
+ control and shows a caption and a content area. In the foldable mode the caption
+ area is interactive and can be used to collapse and expand the content area.
+ This helps shortening the space that the content takes up on in a view, while
+ still allowing users to expand interesting content for a closer look. E.g. an
+ email reader widget could use this to show each email in a folder in its own
+ content panel so that the control caption is the email subject and the content
+ area contains the full email.
+
+
+
Figure 1.
+Foldable content panel
+
+
+
+
+
+
+
+ Foldable ContentPanel controls can be created either in expanded or collapsed
+ mode and can be programmatically expanded and collapsed in addition to allowing
+ users to manually expand and collapse them.
+
+
+
+
+ If a non-folding ContentPanel control is used without a caption, it is for all
+ practical purposes just a canvas to which any content can be inserted. The
+ content in the content panel area is defined as an XHTML fragment and can be used
+ to include arbitrarily complex content, e.g. content that contains images,
+ JavaScript code, etc.
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Feed_updates-GUID-25cd0e54-0516-4469-965e-c5781cf44dc9.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Feed_updates-GUID-25cd0e54-0516-4469-965e-c5781cf44dc9.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,633 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Feed updates
+
+
+
+
+
+
+Feed updates
+
+
+
+
+Fetching news items
+
+
+
+
+ Before we can show any news items we have to fetch them. So let's take
+ a break in implementing the user interface and write the code that fetches
+ the news items. The majority of that code is in the FeedUpdateBroker.js file
+ in a JavaScript class called FeedUpdateBroker. We'll only be using one single
+ method from that class: fetchFeed(). But how do we hook that up to our widget?
+
+
+
+
+ The actual call to fetchFeed() will be done from the timer function updateFeedTimerFunc()
+ that runs once a second. There we'll need an if-clause that checks if it's time
+ to update the feeds, if another update is already going on, if we have a valid URL
+ that we can fetch and if we're in the main view. If all of these tests tell us
+ that it's time to update the feed, we'll check if the feed update was manually
+ commanded or automatically triggered because it was time to update the feed in
+ the background. If this is a manual update then we'll popup a progress notification
+ dialog. Next we'll create a new instance of the FeedUpdateBroker class and call
+ the fetchFeed() method to start the AJAX-based RSS feed update. We need to pass
+ two arguments to this method: the feed URL that we have in the feedURL variable
+ and a callback function that should be called when the update is completed.
+
+
+
+
+ We don't have that function yet so that's the first thing we need to implement.
+ We'll leave it empty for now but return to it in a bit:
+
+
+
+
+// Callback function that gets called when a feed update has completed.
+function feedUpdateCompleted(event) {
+}
+
+
+
+
+ After we call the fetchFeed() function we'll schedule the next feed update. In
+ theory we shouldn't do this until the feed update completes since there is a risk
+ that we do two updates at the same time. But because we're adding a check to
+ only do feed updates if another update isn't on-going this risk isn't actually
+ real. Now that we have a plan for how to update the feed, let's write the code.
+ First we need to declare a variable for the feed update broker instance that
+ we'll create:
+
+
+ Then the actual implementation for the updateFeedTimerFunc() timer function:
+
+
+
+
+// Timer function for feed updates - called once every second.
+function updateFeedTimerFunc() {
+ var now = new Date().getTime();
+
+ // check if a feed update has been scheduled, if it's time to update now,
+ // and if there's no update currently in progress and if we're in the main view
+ if ((feedURL != null) &&
+ (feedUpdateTime != -1) &&
+ (now > feedUpdateTime) &&
+ (feedUpdateBroker == null) &&
+ (uiManager.getView() == mainView)) {
+ // show progress dialog if this is a commanded feed update
+ if (feedUpdateCommanded) {
+ // no auto hiding, wait-type notification, unknown progress
+ uiManager.showNotification(-1, "wait", "Loading feed...", -1);
+ }
+
+ // fetch the feed from the specified URL
+ feedUpdateBroker = new FeedUpdateBroker();
+ feedUpdateBroker.fetchFeed(feedURL, feedUpdateCompleted);
+
+ if (feedUpdateFrequency != -1) {
+ // schedule next update
+ feedUpdateTime = now + feedUpdateFrequency;
+ } else {
+ // feed update frequency is "never"
+ feedUpdateTime = -1;
+ }
+ }
+}
+
+
+
+
+ The progress dialog is created so that it has a display time of -1 so that
+ it doesn't automatically hide but rather has to be commanded to go away. The
+ notification dialog type is "wait" and we'll give a progress of -1 since we
+ don't know how far along in the feed updating process we are. A negative
+ progress value like -1 means "unknown progress" and will result in an animated
+ progress indicator that shows that something is going on but the exact time
+ that it will take is unknown.
+
+
+
+
+ Our feed updating should now be working and whenever a feed update is completed
+ there should be a call to the empty feedUpdateCompleted() function. Let's
+ continue the implementation there.
+
+
+
+
+ When the feedUpdateCompleted() function is called it receives an event object
+ from the FeedUpdateBroker. This object contains a status that is either "ok"
+ or "error", a "lastModifiedTime" string that contains the time when the RSS
+ feed was last modified to help us decide if there are any new news items to
+ display, as well as an array of news item objects in a property called "items".
+ If the status is "error" then we'll show an error notification dialog. Keep in
+ mind that there might or might not be a progress dialog already showing at this
+ time. Either way we can just call the showNotification() function in the user
+ interface manager because if another dialog is already visible then it will simply
+ replace it with the one that we asked it to show. If the status is "ok" then we'll
+ call hideNotification() in the user interface manager. This will hide the progress
+ dialog if it's showing and if the dialog wasn't showing then the call will just
+ be ignored.
+
+
+
+
+ We'll then need to compare the lastModifiedTime against the last news feed that
+ we have. That means we'll need to track the lastModifiedTime of whatever news
+ feed that we are showing, and that means we need a new global variable:
+
+
+
+
+// Time when the feed was last modified.
+var feedLastModified = null;
+
+
+
+
+ If the lastModifiedTime is different from the one that we are storing in the
+ feedLastModified variable then we know that there's new news items to show.
+ If this is the case then we'll update the feedLastModified time and set the news
+ items to the main view. We could do something fancy and only update the news items
+ that have been modified but to keep the tutorial simple we'll just simply remove
+ all the current items and replace them with the new items and then focus the first
+ of the items. But before we move on to that we'll write as much as we can of the
+ feedUpdateCompleted() function:
+
+
+
+
+// Callback function that gets called when a feed update has completed.
+function feedUpdateCompleted(event) {
+ if (event.status == "ok") {
+ // if there aren't any feed items yet, we'll hide the progress dialog
+ if (feedUpdateCommanded) {
+ uiManager.hideNotification();
+ }
+
+ // check if the feed has updated
+ if (event.lastModified != feedLastModified) {
+ // remember the last modified timestamp
+ feedLastModified = event.lastModified;
+
+ // update news item controls here
+ }
+ } else {
+ // show error message
+ uiManager.showNotification(3000, "warning", "Error while updating feed!<br/>(check network settings)");
+ }
+
+ // null the broker reference to indicate that there's no current
+ // update in progress
+ feedUpdateBroker = null;
+
+ // reset commanded feed update flag
+ feedUpdateCommanded = false;
+}
+
+
+
+
+ We wrote a comment "update news item controls here" at the spot where we will
+ actually create and add news feed items to the main view. We'll replace that in
+ a bit with the actual code to do the job, but first we need to write some code
+ that we'll need to do that.
+
+
+
+
+
+Showing news items
+
+
+
+
+ The news feed items will be shown using ContentPanel controls. We'll need a way
+ to keep track of the ones we're showing so that we can easily remove them when
+ there is new news items to show. Let's create an array to track them:
+
+
+
+
+// Reference to current feed items controls.
+var feedItemControls = [];
+
+
+
+
+ Now we can implement a function that will remove all controls that are tracked
+ by this array from the main view. We'll use this as the first step when we want
+ to display news items.
+
+
+
+
+// Removes feed items.
+function removeFeedItems() {
+ // remove all current feed items from the main view
+ for (var i = 0; i < feedItemControls.length; i++) {
+ mainView.removeControl(feedItemControls[i]);
+ }
+
+ // reset feed item control array
+ feedItemControls = [];
+}
+
+
+
+
+ The function simply loops through the array and calls the removeControl() method
+ in the main view to remove each of the feed item controls from the view, one at a time.
+ Finally we'll reset the feedItemControls array so that it reflects the fact that
+ there are no more controls in the main view.
+
+
+
+
+ What about adding news items? We'll do that in a function that we'll call from the
+ feedUpdateCompleted() function. Let's call the function setFeedItems(). The function
+ will start by calling the removeFeedItems() function we just created to empty the
+ main view from news items before we start adding new ones to it. After this we'll
+ loop through the news feed items that were handed to us from the FeedUpdateBroker.
+ For each one we need a ContentPanel control. We'll be recycling the controls instead
+ of constantly creating new ones over and over again as new news items come in. To
+ this end we'll need a way to track ContentPanel controls that we have already
+ created. We'll do this by creating an array called feedItemControlPool, which will
+ be a global variable:
+
+
+
+
+// Feed item control pool.
+var feedItemControlPool = [];
+
+
+
+
+ If we have enough controls in the pool we'll just take them from there. Otherwise
+ we'll create a new ContentPanel and add it to the pool. Either way we'll end up with
+ a ContentPanel control that is ready to be used. We'll need to reset its state since we
+ recycled it, so we make sure it's collapsed rather than expanded, we'll set its caption
+ to the title of the news item and we'll generate some HTML from the news item summary
+ that we'll set as the content for the ContentPanel. And then finally we'll add the
+ ContentPanel to the main view.
+
+
+
+
+ Lets create the code but skip the HTML for the news item summary for now:
+
+
+
+
+// Sets feed items.
+function setFeedItems(items) {
+ // start by removing all current feed items
+ removeFeedItems();
+
+ // create new feed items and add them to the main view
+ // use feed item pool to recycle controls
+ for (var i = 0; i < items.length; i++) {
+ // get a feed item control from the pool or create one and
+ // place it in the pool if there aren't enough feed item controls
+ var feedItemControl;
+ if (i == feedItemControlPool.length) {
+ feedItemControl = new ContentPanel(null, null, null, true);
+ feedItemControlPool.push(feedItemControl);
+ } else {
+ feedItemControl = feedItemControlPool[i];
+ }
+
+ // initialize feed item control
+ var item = items[i];
+ feedItemControl.setCaption(item.title);
+ feedItemControl.setContent("placeholder");
+ feedItemControl.setExpanded(false);
+
+ // add the feed item control to the main view
+ feedItemControls.push(feedItemControl);
+ mainView.addControl(feedItemControl);
+ }
+}
+
+
+
+
+ The items argument contains the array of news items that we received in the event
+ object argument to the feedUpdateCompleted() callback function. The items are in
+ the "items" property of the event object. Note how the feedItemControl is either
+ created or taken from the feedItemControlPool. If it's created it is given four
+ arguments: a null unique identifier because we don't need one, a null caption and
+ a null content because we will set both every time before we show it, and finally
+ a value of true to the "foldable" argument in the ContentPanel constructor. This
+ flag determines whether the ContentPanel can be folded (expanded and collapsed) or
+ not. We want a foldable one so we pass true to this argument.
+
+
+
+
+ Once we have the ContentPanel (either from the pool or newly created) we set its
+ state: caption, content and expanded state. Note that for now we'll just set a
+ placeholder string as the content. Also note that we set the expanded state to false
+ to collapse the news items by default. Finally we add the content panels to the main
+ view and to the feedItemControls array that tracks all the ContentPanels that we use
+ for the news items.
+
+
+
+
+ Now that we have written the code to create and add news items to the main view
+ we have to hook that up to the feedUpdateCompleted() function. Remember we added
+ a comment in the spot where we should return to do this? Let's replace that comment
+ with the following:
+
+
+
+
+// set feed items to the main view
+setFeedItems(event.items);
+
+// focus the first feed item control
+// (but only if we are in the main view)
+if (uiManager.getView() == mainView && feedItemControls.length > 0) {
+ feedItemControls[0].setFocused(true);
+}
+
+
+
+
+ We just call the setFeedItems() function we just wrote, passing it the feed items
+ that the FeedUpdateBroker fetched and parsed for us, and then if we're in the main
+ view we'll focus the first of the news feed item controls.
+
+
+
+
+ Now that we have all the code needed to fetch and update news feed items we'll go
+ back and add some more functionality to a function we wrote a little bit earlier:
+ the saveSettingsClicked() function.
+
+
+
+
+ The functionality that we're adding will handle updates of the feed items in the
+ main view after the user has modified the settings. We didn't write this earlier
+ because we didn't have all the necessary support code in place but we can add it now.
+ First we add some code to the end of the saveSettingsClicked() function to force an
+ update of the news items after the users saves the settings:
+
+
+
+
+// update the feed
+feedLastModified = null;
+updateFeed();
+
+
+
+
+ We update the feed by setting the feedLastModified variable to null to force an update
+ and then calling updateFeed(). This causes an immediate feed update and we also get the
+ progress notification dialog, which is what we want because this was a manual
+ update that was caused by the user clicking "save".
+
+
+
+
+ Let's also add some code that checks if a new feed was selected and removes all the
+ news items from the main view if the user selected a new feed. To do this we'll first
+ copy the old feedURL to a variable that we'll call oldFeedURL at the very beginning
+ of the function:
+
+
+
+
+// remember the old feed URL
+var oldFeedURL = feedURL;
+
+
+
+
+ Then we'll add the following just before we show the main view:
+
+
+
+
+// remove all feed items if the user selected a new feed
+if (feedURL != oldFeedURL) {
+ removeFeedItems();
+}
+
+
+
+
+ We can now test this in a PC browser, handset or emulator. Everything should work
+ except that there's still nothing but a placeholder for the actual content in each
+ ContentPanel. You can still expand and collapse the ContentPanels and the settings
+ and automatic and manual updates are working. We're almost done but we still need
+ to implement the code that will actually show news item summaries in the content
+ panels.
+
+
+
+
+ Remember we said that we would implement news items so that there's a link from
+ each news item to the website where the full article is. When you open links
+ to external websites in the S60 Web Runtime you should use the widget.openURL()
+ function. But PC browsers don't have that function so we'll need to create a wrapper
+ function that either calls widget.openURL() if we're in the Web Runtime or just
+ opens a new window if we're in a PC browser.
+
+
+ Content in a ContentPanel control is a fragment of HTML. In other words it's a
+ piece of HTML that will be inserted into the control using code. That means that
+ in order to display the news item we will have to generate some HTML for it.
+ We need a function that will take a news item object and return some HTML that
+ we can give to thet setContent() method in the ContentPanel control. Let's write
+ that function:
+
+
+ The function uses the properties in the news item object that the FeedUpdateBroker
+ created for us. There's a date property that has the publish date of the news item.
+ There's a description that contains the actual summary, and there's a URL that points
+ to the website where the full article is. Note that we're using the openURL() wrapper
+ function that we just wrote for the link to the full article.
+
+
+
+
+ Our HTML is very simple: three div-tags that have the date, description and a link as
+ their content. And ech of them has a CSS class so that we can match them with some
+ style rules. Since we have three different pieces of data we need three CSS rules:
+ FeedItemDate for the date, FeedItemDescription for the news item summary and finally
+ FeedItemLink for the link to the website. Let's create these in the RSSReader.css
+ stylesheet file:
+
+
+
+
+
+/* Feed item date */
+.FeedItemDate {
+ font-style: italic;
+}
+
+/* Feed item text */
+.FeedItemDescription {
+ padding: 4px 0px;
+}
+
+/* Feed item links */
+.FeedItemLink {
+
+}
+
+/* Anchor tags in the context of a feed item link */
+.FeedItemLink a {
+ text-decoration: underline;
+ font-weight: bold;
+ color: rgb(0,0,255);
+}
+
+/* Focused anchor tags */
+.FeedItemLink a:focus {
+ background: rgb(0,0,255);
+ color: rgb(255,255,255);
+}
+
+
+
+
+ The rule for links can be left empty because we will just use default ContentPanel
+ content styling. However we'll change the way the link looks in the context of that
+ FeedItemLink div. We'll make links blue, bold and underlined in their normal state
+ and inverse with a blue background and white text color when focused.
+
+
+
+
+ Now that we have a function that generates HTML for the ContentPanel we can remove
+ the placeholder content replace it with a call to our function:
+
+
+ We're done! Now you can try the widget in a PC browser and then on the handset
+ or emulator.
+
+
+
Figure 1.
+RSS Reader main view
+
+
+
+
+
+
+
+
+What we have learned
+
+
+
+
+ The RSS Reader tutorial has taught us several things. We have learned to create a widget
+ that has more than just one view. We have learned how to use several new WRTKit controls.
+ We used the SelectionList, SelectionMenu and FormButton controls in our settings view,
+ and in the main view we used the ContentPanel control that allowed us to add our own
+ content as a seamless part of the rest of the user interface using HTML fragments that
+ we styled with CSS rules. We have learned to modify a view while the widget runs by adding
+ and removing controls. And we have learned how to separate our widget code so that the
+ user interface code doesn't contain any logic code and so that the logic code doesn't
+ contain any user interface code.
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_FormButton_Class-GUID-9f99492d-b232-4a78-baed-bd284839b367.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_FormButton_Class-GUID-9f99492d-b232-4a78-baed-bd284839b367.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,278 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+WRTKit FormButton Class
+
+
+
+
+
+
+WRTKit FormButton Class
+
+
+
+
+Description
+
+
+
+
+ The FormButton class implements a control that is intended for use in form-style
+ user interfaces. A form button is typically used to let users trigger actions.
+
+[FormButton] new FormButton(String id, String text)
+
+
+
+
+Description
+
+
+
+
+ Creates a new instance of the FormButton class.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+id
+
+
+
+
+
+ Unique identifier for the control. Can be retrieved using the id property defined
+ in the UIElement class that this control inherits from. Useful for example to
+ identify the source of an event in event callback functions or to apply a CSS
+ rule to only this particular control. The identifier can be null, in which case
+ no id will be set for the control.
+
+
+
+
+
+
+
+
+text
+
+
+
+
+
+ Text that is displayed on the face of the button. Typically this should be
+ a verb that indicates what happens when the button is pressed.
+ The value is an XHTML string.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ A new instance of the FormButton class.
+
+
+
+
+
+
+
+
+
+
+
+getText()
+
+
+
+
+Syntax
+
+
+
+[String] FormButton.getText(void)
+
+
+
+
+Description
+
+
+
+
+ Retrieves the current text of the button.
+ The value is an XHTML string.
+
+
+
+
+
+Arguments
+
+
+
+
+ This method does not take any arguments.
+
+
+
+
+
+Return value
+
+
+
+
+ The current text of the button.
+
+
+
+
+
+
+
+
+
+
+
+setText()
+
+
+
+
+Syntax
+
+
+
+[void] FormButton.setText(String text)
+
+
+
+
+Description
+
+
+
+
+ Sets the text of the button. The text is displayed on the face
+ of the button and indicates what happens when the button is pressed.
+ The value is an XHTML string.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+text
+
+
+
+
+
+ The text to be displayed on the face of the button. Passing null
+ results in no text.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ This method does not return a value.
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Handling_events-GUID-a1a86c8a-6e66-4dc8-8967-b5c9c7bc6563.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Handling_events-GUID-a1a86c8a-6e66-4dc8-8967-b5c9c7bc6563.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,123 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Handling events
+
+
+
+
+
+
+Handling events
+
+
+
+
+
+ Event handling in the WRTKit is based on the "observer pattern",
+ meaning that events are reported from the event source to observers
+ that are said to be "listening" to event notifications. An event
+ listener is simply a JavaScript function that takes a single
+ argument: the event message. In fact even that single argument is
+ optional and if the function is not interested in the event message
+ then it can simply ignore it.
+
+
+
+
+ All views and controls inherit from a common base class called
+ "UIElement" that defines the mechanics for event observation and
+ notification. From the point of view of event listeners, the most
+ important methods are addEventListener() and removeEventListener().
+ These two methods are used to register and unregister listener
+ functions from a view or control.
+
+
+
+
+ There are different types of events though, and event listeners are
+ typically not interested in receiving notifications of all events.
+ For example an event listener that wants to know when a button has
+ been pressed doesn't usually care if the pointer is currently
+ hovering above the button or not. Filtering of event notifications
+ works based on event type names. E.g. in this case the event
+ listener would have been added so that it should be called only for
+ events of the "ActionPerformed" type. The event type is given to the
+ addEventListener() function when a listener is registered. If a
+ listener function really wants to be notified of all event types
+ then null can be specified as the event type. Note that the event
+ type must also be specified when an event listener is unregistered.
+
+
+
+
+ The code below shows a typical event listener function:
+
+
+
+
+// Callback for event notifications.
+function handleEvent(event) {
+ // handle event here
+}
+
+
+
+
+ The event message is passed to the first argument (called event in
+ this case) of the event handler function. The event message is a
+ JavaScript object with three properties: type, source and value. The
+ type property specifies the event type name and is useful if a
+ listener function is listening to several types of events. The
+ source argument is a reference to the source view or control that
+ sent out the event notification. If a listener function is listening
+ to events from many different controls then this is useful to figure
+ out in which of the controls the event occurred. Here the unique
+ identifier of views and controls can come in handy to identify the
+ source without needing to retain references to all the source
+ controls. Finally the value property is a event-type specific
+ property that contains some information about the event. For example
+ if the event type is "TextChanged" from a text entry control then
+ the value would be the new text value that the user has typed into
+ the control.
+
+
+
+
+ The code below demonstrates how to add and remove an event listener
+ to/from a control. The example assumes that the control has already
+ been created and that the ctrl variable refers to it.
+
+
+
+
+// add listener to ctrl
+// function to add is handleEvent() for event type "ActionPerformed"
+ctrl.addEventListener("ActionPerformed", handleEvent);
+
+// remove listener from ctrl
+// function to remove is handleEvent() for event type "ActionPerformed"
+ctrl.removeEventListener("ActionPerformed", handleEvent);
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Hello_World_Tutorial-GUID-67e0a561-48ac-4938-8f1b-852422b71380.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Hello_World_Tutorial-GUID-67e0a561-48ac-4938-8f1b-852422b71380.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,114 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Hello World
+
+
+
+
+
+
+Hello World
+
+
+
+
+
+ Whenever you are learning a new programming language or API, the first example
+ you will find is usually called "Hello World" and the WRTKit is no exception.
+ Like most "Hello World" applications this one will be very simple and short, but
+ before we start we'll take a look at what we will need to build the example.
+
+
+
+
+ The WRTKit already contains all the files that will be created in this tutorial.
+ If you go to the "Examples" directory in the WRTKit SDK you will find a directory
+ called "HelloWorld". This directory contains all the files necessary for the widget
+ and all you have to do to try it out on a handset or S60 emulator is to zip up the
+ directory, rename the file to "HelloWorld.wgz" and follow the usual steps to install
+ a widget on the handset or emulator.
+
+
+
+
+ The WRTKit Hello World widget is very similar to any other S60 Web Runtime widget.
+ You have an Info.plist file that defines the metadata for the widget, such as its
+ name, version and main HTML file and you have the icon of the widget in a file called
+ Icon.png. The main HTML file for the Hello World widget is called "HelloWorld.html".
+ But it's here that things start to get a little bit different because we're using
+ the WRTKit to create our user interface.
+
+
+
+
+ If we didn't use the WRTKit then the HelloWorld.html file would probably contain
+ the text "Hello World" between the <body> and </body> tags, and that
+ would be it. But when you use the WRTKit you create your user interface using
+ JavaScript rather than HTML. This might sound scary and difficult at first but it
+ actually saves you a lot of typing and gives you a lot of things for free that
+ you would otherwise have to take care of yourself. Our Hello World widget will be
+ quite a bit fancier than one created with just HTML and it will still be very
+ short and simple.
+
+
+
+
+ The directory also contains a HelloWorld.js file and a WRTKit directory but we
+ will not talk about those quite yet.
+
+
+
+
+ Even though we have already created all the files for you, you might want to
+ type in the code yourself. Either way you will need a text editor. Any text editor
+ will do really but it will make your life considerably easier if you have one that
+ is specialized for programming and offers syntax highlighting for HTML, CSS
+ and JavaScript.
+
+
+
+
+ Finally, you will need a handset or emulator that includes the S60 Web Runtime.
+ You can actually work with the WRTKit even without the S60 Web Runtime because
+ the WRTKit works in a normal standards-compliant web browser such as Firefox.
+ But since a PC computer and web browser is quite different from a mobile device
+ it is still recommended that you test your widget on actual devices in order
+ to get a feel for what the widget will actually look and feel like. For quick
+ tests in a PC web browser though, all you have to do is open up the main HTML file
+ in the browser and things should work without any changes to the code.
+
+
+
+
+ No other tools or libraries are needed and you're now set to start working on
+ the Hello World widget.
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_High_level_view_of_the_WRTKit-GUID-a3abe57e-9a71-4f94-923a-b84ccd1b0905.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_High_level_view_of_the_WRTKit-GUID-a3abe57e-9a71-4f94-923a-b84ccd1b0905.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,115 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+High level view of the WRTKit
+
+
+
+
+
+
+High level view of the WRTKit
+
+
+
+
+
+ User interfaces in the WRTKit are based on the concepts of "views" and "controls".
+ A control is a user interface element that the user can view or interact with,
+ e.g. buttons, checkboxes, textfields, etc. Views are containers for controls and
+ deal with the layout of controls on the screen in such a way that the user can
+ interact with them in an easy way. Views are conceptually similar to windows in
+ PC applications, but on a mobile device views typically fill the entire screen
+ and only one view can thus be visible at any given time. The WRTKit allows views
+ and controls to be interacted with in both the tab and pointer navigation modes
+ and the navigation mode can even be switched at runtime.
+
+
+
Figure 1.
+WRTKit-based widget user interface
+
+
+
+
+
+
+
+ The WRTKit is an object oriented user interface toolkit, which means that views
+ and controls are implemented as JavaScript classes that are instantiated to
+ objects when they are needed. In order to create a view with two buttons, for
+ example, a developer writes JavaScript code that instantiates one view
+ object and two button objects, and then calls a method in the view object asking
+ it to add the buttons to itself. Being object oriented, the created WRTKit
+ objects fully maintain their own state and take care of drawing themselves
+ properly on the screen in all situations. So for example if one of the buttons
+ is focused, the button modifies its own looks so that it appears focused
+ on the screen. Because the objects know their own state, they can be queried for
+ properties as needed. E.g. a textfield can be asked what text it currently
+ contains, a button can be asked if it is enabled, and so on.
+
+
+
+
+ Controls in the WRTKit have captions that can be used to show what the control
+ does. E.g. a textfield that is meant to be used to enter a password could have a
+ caption "Password". Captions are optional but should be used unless there is a
+ very good reason not to. The only controls that do not have captions are
+ buttons, since they have a text on the face of the button that accomplishes the
+ same thing.
+
+
+
+
+ WRTKit user interfaces are managed by a class that is aptly named "UIManager".
+ Every widget that uses the WRTKit for its user interface creates a single
+ instance of this class and then uses that UIManager instance to command views to
+ be displayed. The UIManager takes care of all the heavy lifting that is necessary
+ to bring a new view to the screen. The UIManager also handles other user
+ interface duties such as management of notification popup dialogs and view
+ scrollbars.
+
+
+
+
+ Controls and views can notify the outside world when some event occurrs, e.g.
+ when a button is pressed or someone toggles a checkbox. The WRTKit follows the
+ so called "observer pattern" in its implementation of event notifications. This
+ simply means that a control or view can be asked to call a particular JavaScript
+ function (which is the "observer" or "listener") when an specific type of event
+ occurrs. The WRTKit allows a control or view to have any number of concurrently
+ registered listeners and listeners can either ask to be notified of only a
+ particular type of event or about all events.
+
+
+
+
+ The WRTKit library is physically a set of JavaScript, CSS and image files that
+ are located within a directory called "WRTKit". That directory is copied into
+ the root directory of widgets that wish to use the library. A widget only needs
+ to include a single JavaScript file ("WRTKit/WRTKit.js") from the directory in
+ order to include and initialize the full WRTKit for use in the widget. Once the
+ WRTKit has been added to the widget and initialized, the widget can start using
+ the JavaScript classes that the library defines.
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Introduction_to_the_WRTKit-GUID-dcf05457-f800-4f05-b284-a4e24ab8be79.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Introduction_to_the_WRTKit-GUID-dcf05457-f800-4f05-b284-a4e24ab8be79.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,111 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Introduction to the WRTKit
+
+
+
+
+
+
+Introduction to the WRTKit
+
+
+
+
+
+ The S60 Web Runtime allows developers to use familiar web technologies like
+ HTML, CSS and JavaScript to create applications called "widgets" very easily.
+ But because widgets are based on web technologies they look and behave more like
+ web pages than S60 applications by default, which is not always desirable.
+
+
+
+
+ Web pages use a document metaphor where content can be laid out arbitrarily.
+ Interaction with the web page is based on using a mouse or other similar device
+ to place a pointer arrow on elements on the web page and activating them by
+ pressing a button. When the pointer is over some user interface element it is
+ said to be "hovering". The element that the pointer is hovering over is often
+ displayed in a distinct style to show that it could be activated if the mouse
+ button was pressed.
+
+
+
+
+ Mobile device applications, on the other hand, have limitations that make this
+ methapor less than ideal. The screen is small so discipline is needed to lay out
+ user interface elements in a way that is easy to understand for the user. The
+ physical controls on a mobile device are also not very suitable for moving
+ around a pointer arrow on the screen. Instead of having a pointer to select
+ elements the concept of "focus" is used. One of the elements on the screen is
+ considered selected and this selection can be moved between the user interface
+ elements using a 4-way controller. The element that is selected is said to be
+ "focused". Like for hovering, the focused element is displayed with a distinct
+ style to set it apart from other elements. This interaction method is called
+ "tab navigation" due to the fact that the tab key was originally used to move
+ the focus on PC computers.
+
+
+
+
+ The S60 Web Runtime supports both the pointer-based and tab-based interaction
+ modes so that you can choose the one that fits your widget best. But while
+ simple user interfaces are easy to implement in both modes, more sophisticated
+ application-like user interfaces can be quite tricky. Hover and focus must be
+ handled correctly and the hover and focus states must be displayed consistently
+ throughout the user interface. Different screen sizes as well as screen resizes
+ and rotations must be taken into account. User interface controls like buttons,
+ checkboxes and scrollbars must be able to take on a look that fits the overall
+ visual theme of the widget, for example that of a commercial brand.
+
+
+
+
+ The WRTKit is a complete library of JavaScript code, CSS style rules and
+ graphical elements that are required to implement the kind of sophisticated,
+ customizable, application-like user interfaces that are described above. It
+ gives widget developers an easy way to create high quality user interfaces
+ without having to worry about the problems that would otherwise plague their
+ widgets.
+
+
+
+
+ When the WRTKit is used in a widget, complex and fully featured user interfaces
+ can be created with just a few lines of JavaScript code. The WRTKit takes care
+ of generating all the HTML and CSS automatically behind the scenes. What's more,
+ the visual look of the user interfaces created by the WRTKit is controlled
+ entirely using CSS, allowing complete customization without touching any code.
+ WRTKit user interfaces also work in standards-compliant PC web browsers,
+ enabling rapid development and debugging using familiar web development tools.
+
+
+
Figure 1.
+WRTKit-based widget user interface
+
+
+
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Label_Class-GUID-64730e7f-835f-443a-9322-6753fa72fd09.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Label_Class-GUID-64730e7f-835f-443a-9322-6753fa72fd09.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,295 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+WRTKit Label Class
+
+
+
+
+
+
+WRTKit Label Class
+
+
+
+
+Description
+
+
+
+
+ The Label class implements a control that displays a simple piece of text. A label
+ is used in situations where there's a caption-value pair that needs to be displayed,
+ e.g. "Name: John Smith".
+
+[Label] new Label(String id, String caption, String text)
+
+
+
+
+Description
+
+
+
+
+ Creates a new instance of the Label class.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+id
+
+
+
+
+
+ Unique identifier for the control. Can be retrieved using the id property defined
+ in the UIElement class that this control inherits from. Useful for example to
+ identify the source of an event in event callback functions or to apply a CSS
+ rule to only this particular control. The identifier can be null, in which case
+ no id will be set for the control.
+
+
+
+
+
+
+
+
+caption
+
+
+
+
+
+ The caption text for the control. A null caption can be used to hide the
+ caption area. This is not recommended for a label since without a caption
+ the value of the label doesn't make sense to the user.
+ The value is an XHTML string.
+
+
+
+
+
+
+
+
+text
+
+
+
+
+
+ The content for the label. If the argument is omitted or null then the content
+ area will be empty. The value is an XHTML string.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ A new instance of the Label class.
+
+
+
+
+
+
+
+
+
+
+
+getText()
+
+
+
+
+Syntax
+
+
+
+[String] Label.getText(void)
+
+
+
+
+Description
+
+
+
+
+ Retrieves the current text value of the label.
+ The value is an XHTML string.
+
+
+
+
+
+Arguments
+
+
+
+
+ This method does not take any arguments.
+
+
+
+
+
+Return value
+
+
+
+
+ The current text value of the label.
+
+
+
+
+
+
+
+
+
+
+
+setText()
+
+
+
+
+Syntax
+
+
+
+[void] Label.setText(String text)
+
+
+
+
+Description
+
+
+
+
+ Sets the text value of the label.
+ The value is an XHTML string.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+text
+
+
+
+
+
+ The text to be displayed as the value of the label. Passing null
+ results in no text.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ This method does not return a value.
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_ListView_Class-GUID-a7f24a67-d46c-4156-8276-a97b945235d6.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_ListView_Class-GUID-a7f24a67-d46c-4156-8276-a97b945235d6.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,555 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+WRTKit ListView Class
+
+
+
+
+
+
+WRTKit ListView Class
+
+
+
+
+Description
+
+
+
+
+ The ListView is a view that arranges controls in a vertical stack similar to
+ native S60 user interfaces.
+
+[ListView] new ListView(String id, String caption)
+
+
+
+
+Description
+
+
+
+
+ Creates a new instance of the ListView class.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+id
+
+
+
+
+
+ Unique identifier for the view. Can be retrieved using the id property defined
+ in the UIElement class that this control inherits from. Useful for example to
+ identify the source of an event in event callback functions or to apply a CSS
+ rule to only this particular view. The identifier can be null, in which case
+ no id will be set for the view.
+
+
+
+
+
+
+
+
+caption
+
+
+
+
+
+ The caption text for the view. A null caption can be used to hide the
+ caption area. Pass an empty string to this argument in order to show the
+ caption area but without text. This can be used if a custom image should
+ be shown instead of text for the view caption. The image can then be
+ defined using CSS by providing a background for the .ListViewCaptionText
+ CSS rule. By specifying the rule only for the id that was specified with
+ the id argument a custom background can be given to a particular view.
+ The value is an XHTML string.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ A new instance of the ListView class.
+
+
+
+
+
+
+
+
+
+
+
+getCaption()
+
+
+
+
+Syntax
+
+
+
+[String] ListView.getCaption(void)
+
+
+
+
+Description
+
+
+
+
+ Retrieves the current caption of the view.
+ The value is an XHTML string.
+
+
+
+
+
+Arguments
+
+
+
+
+ This method does not take any arguments.
+
+
+
+
+
+Return value
+
+
+
+
+ The current caption of the view or null if the view doesn't have a caption.
+
+
+
+
+
+
+
+
+
+
+
+setCaption()
+
+
+
+
+Syntax
+
+
+
+[void] ListView.setCaption(String caption)
+
+
+
+
+Description
+
+
+
+
+ Sets the caption for the view. A null caption can be used to hide the caption area.
+ The value is an XHTML string.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+caption
+
+
+
+
+
+ The new caption for the view or null for no caption.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ This method does not return a value.
+
+
+
+
+
+
+
+
+
+
+
+getControls()
+
+
+
+
+Syntax
+
+
+
+[Array] ListView.getControls(void)
+
+
+
+
+Description
+
+
+
+
+ Retrieves the controls of this view.
+
+
+
+
+
+Arguments
+
+
+
+
+ This method does not take any arguments.
+
+
+
+
+
+Return value
+
+
+
+
+ An array with the controls of this view or an empty array if the view
+ doesn't have any controls.
+
+
+
+
+
+
+
+
+
+
+
+addControl()
+
+
+
+
+Syntax
+
+
+
+[void] ListView.addControl(Control control)
+
+
+
+
+Description
+
+
+
+
+ Adds a control to the view. The control is added last, below the currently
+ last control.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+control
+
+
+
+
+
+ The control to add to the view.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ This method does not return a value.
+
+
+
+
+
+
+
+
+
+
+
+insertControl()
+
+
+
+
+Syntax
+
+
+
+[void] ListView.insertControl(Control control, Control beforeControl)
+
+
+
+
+Description
+
+
+
+
+ Inserts a control to the view. The control is added before the control that is
+ specified using the beforeControl argument.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+control
+
+
+
+
+
+ The control to add to the view.
+
+
+
+
+
+
+
+
+beforeControl
+
+
+
+
+
+ The control that should be immediately after the added control after
+ the new control is added to the view. If the argument is null or otherwise
+ invalid (e.g. not a control in this view) then the new control is added last.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ This method does not return a value.
+
+
+
+
+
+
+
+
+
+
+
+removeControl()
+
+
+
+
+Syntax
+
+
+
+[void] ListView.removeControl(Control control)
+
+
+
+
+Description
+
+
+
+
+ Removes a control from the view.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+control
+
+
+
+
+
+ The control to remove from the view.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ This method does not return a value.
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_NavigationButton_Class-GUID-3c5aaba9-899d-463a-8337-b6f7c09e190b.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_NavigationButton_Class-GUID-3c5aaba9-899d-463a-8337-b6f7c09e190b.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,418 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+WRTKit NavigationButton Class
+
+
+
+
+
+
+WRTKit NavigationButton Class
+
+
+
+
+Description
+
+
+
+
+ The NavigationButton class implements a control that is intended for use in navigation
+ menu -style user interfaces. A navigation button is typically used to let users move
+ between views.
+
+[NavigationButton] new NavigationButton(String id, String image, String text)
+
+
+
+
+Description
+
+
+
+
+ Creates a new instance of the NavigationButton class.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+id
+
+
+
+
+
+ Unique identifier for the control. Can be retrieved using the id property defined
+ in the UIElement class that this control inherits from. Useful for example to
+ identify the source of an event in event callback functions or to apply a CSS
+ rule to only this particular control. The identifier can be null, in which case
+ no id will be set for the control.
+
+
+
+
+
+
+
+
+image
+
+
+
+
+
+ Icon image that is displayed on the face of the button. No size is enforced but
+ the image should be about 30x30 pixels. PNG images with transparency are
+ recommended. If null is passed for the image then no image will be displayed.
+
+
+
+
+
+
+
+
+text
+
+
+
+
+
+ Text that is displayed on the face of the button. Typically this should be
+ the view that the widget navigates to when the button is pressed.
+ The value is an XHTML string.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ A new instance of the NavigationButton class.
+
+
+
+
+
+
+
+
+
+
+
+getText()
+
+
+
+
+Syntax
+
+
+
+[String] NavigationButton.getText(void)
+
+
+
+
+Description
+
+
+
+
+ Retrieves the current text of the button.
+ The value is an XHTML string.
+
+
+
+
+
+Arguments
+
+
+
+
+ This method does not take any arguments.
+
+
+
+
+
+Return value
+
+
+
+
+ The current text of the button.
+
+
+
+
+
+
+
+
+
+
+
+setText()
+
+
+
+
+Syntax
+
+
+
+[void] NavigationButton.setText(String text)
+
+
+
+
+Description
+
+
+
+
+ Sets the text of the button. The text is displayed on the face
+ of the button and typically should indicate where the widget navigates
+ when the button is pressed.
+ The value is an XHTML string.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+text
+
+
+
+
+
+ The text to be displayed on the face of the button. Passing null
+ results in no text.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ This method does not return a value.
+
+
+
+
+
+
+
+
+
+
+
+getImage()
+
+
+
+
+Syntax
+
+
+
+[String] NavigationButton.getImage(void)
+
+
+
+
+Description
+
+
+
+
+ Retrieves the icon image URL of the button.
+
+
+
+
+
+Arguments
+
+
+
+
+ This method does not take any arguments.
+
+
+
+
+
+Return value
+
+
+
+
+ The icon image URL of the button or null if none.
+
+
+
+
+
+
+
+
+
+
+
+setImage()
+
+
+
+
+Syntax
+
+
+
+[void] NavigationButton.setImage(String image)
+
+
+
+
+Description
+
+
+
+
+ Sets the icon image URL for the button. Passing null to this method
+ hides the icon image.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+image
+
+
+
+
+
+ The URL of the icon image to display on the button or null for no image.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ This method does not return a value.
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Notification_popups-GUID-8696212c-4114-412a-9990-ef9755fc1942.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Notification_popups-GUID-8696212c-4114-412a-9990-ef9755fc1942.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,59 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Notification popups
+
+
+
+
+
+
+Notification popups
+
+
+
+
+
+ In addition to managing views, the UIManager also handles notification popup
+ dialogs. Notification popups are used for showing brief messages to the user to
+ indicate activities and events, such as warnings, information messages or the
+ progress of some process. Using notification popups is extremely simple and only
+ requires two methods. Popups can be shown using one method and hidden with
+ another. Popups can also be set to auto-hide after a specified amount of time.
+
+
+
+
+ There are three different types of notification popups: "info", "warning" and
+ "wait". The type affects only the appearance of the popup. The "wait" type is
+ intended for use with progress indication.
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Overview_of_the_WRTKit-GUID-14c414f6-a220-40b6-8614-df13141495ab.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Overview_of_the_WRTKit-GUID-14c414f6-a220-40b6-8614-df13141495ab.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,54 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Overview of the WRTKit
+
+
+
+
+
+
+Overview of the WRTKit
+
+
+
+
+
+ This section of the Developer's Guide gives an overview of what the
+ WRTKit is and how it's used, explains the core terminology and
+ outlines some design considerations for widgets that use the WRTKit.
+
+
+ The RSS Reader example is the first complete, working widget that actually
+ does something useful that you will create using the WRTKit. It is quite a bit
+ more complex than the Hello World example, but then again it also contains
+ a lot more functionality.
+
+
+
+
+ For the Hello World widget we covered a lot of very fine details but for the
+ RSS Reader it is assumed that the reader already knows the basics of how to
+ create a widget, deploy it, test it, and so on. If you skipped the Hello World
+ tutorial and feel that you're not comfortable with the basics of creating
+ widgets yet then it's recommended that you go back and read the Hello World
+ widget tutorial first and then come back and continue with the RSS Reader.
+
+
+
+
+ The RSS Reader that we're going to build in this tutorial will have two views:
+ a main view that displays news items from an RSS feed and a settings view where
+ the user can configure what news feed should be displayed in the main view and
+ how often it should be updated from the Internet. We will let users choose from
+ a list of feeds that we will pre-configure. In principle you can use whatever
+ RSS feeds you want in your own widget but it's probably best to test first with
+ the ones we have in our example since they have been tested and known to work.
+
+
+
+
+ The actual news feed items will be displayed as a list of foldable content
+ panels on the main view. The panels allow the user to see the headline for each
+ piece of news and clicking on the headline will expand the news item so that the
+ actual story summary can be read. At the bottom of the summary we'll place a
+ link to the full story in a similar fashion to many other RSS reader applications.
+
+
+
+
+ We will also implement a couple of features to make the widget more user friendly.
+ For example the first time when the widget is started we'll go directly to the
+ settings view to let the user configure the widget before the first use. We'll
+ also show helpful information such as loading progress and any error messages in
+ notification popup windows. And of course all configuration settings will be
+ persistent so that the user doesn't have to re-configure the widget every time
+ its started.
+
+
+
+
+ In order to make the widget similar to other S60 applications, we will tweak
+ the softkeys and Options menu so that the settings view can be reached from the
+ menu and so that the right softkey will let the user go back from the settings
+ view to the main view. In the main view the right softkey will be used to exit
+ the widget. We will also allow the user to manually force a refresh of the news
+ items by adding a "Refresh" option to the options menu.
+
+
+
+
+ And last but not least, we'll implement the widget so that it will work in a
+ standards-compliant PC web browser such as Firefox. This will allow you to test
+ and debug the widget quickly as you develop it on your PC.
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_RSS_Reader_first_steps-GUID-db42b227-1647-4020-bdb9-dacb26771779.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_RSS_Reader_first_steps-GUID-db42b227-1647-4020-bdb9-dacb26771779.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,236 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+First steps
+
+
+
+
+
+
+First steps
+
+
+
+
+Preparations
+
+
+
+
+ You can find the ready made RSS Reader example in the Examples/RSSReader directory
+ in the WRTKit SDK. In there you can find the by-now familiar widget files: Info.plist
+ for the widget metadata, Icon.png for the S60 application grid icon, and the WRTKit
+ directory for the WRTKit user interface toolkit. You will also find the main HTML
+ file RSSReader.html, a CSS file called RSSReader.css and two JavaScript files
+ RSSReader.js and FeedUpdateBroker.js. As with all WRTKit -based widgets, we will
+ be focusing on the JavaScript files but before we get to those, let's see take a
+ look at the main HTML file:
+
+
+ You probably immediately noticed that the file is almost identical to the HTML file
+ for the Hello World widget. This is despite that the RSS Reader is much more complex.
+ In fact the only differences are that we are including the two JavaScript files
+ FeedUpdateBroker.js and RSSReader.js instead of HelloWorld.js as in the Hello World
+ widget. That, and the fact that we have a CSS stylesheet file that we also import here,
+ called RSSReader.css. Like for the Hello World widget we have an onload-event handler
+ that calls a function called init() in the JavaScript to allow us to initialize the
+ widget after everything is loaded.
+
+
+
+
+ You can either examine the ready made files or create your own files as you read the
+ tutorial. The tutorial assumes that you will create your own. If you're doing that then
+ now would be a good time to create a working directory for your own widget, call it
+ RSSReader and copy the WRTKit directory, Info.plist, Icon.png and the FeedUpdateBroker.js
+ file to the your own working directory. The FeedUpdateBroker.js is an AJAX-based RSS
+ fetcher and parser that we will be using in this example. It doesn't really have anything
+ to do with the WRTKit or the user interface for the RSS Reader but we need it in order
+ to be able to fetch and parse RSS feed news items. We will not create it in this tutorial
+ and thus you should just copy it to your own widget working directory.
+
+
+
+
+ At this point you can also create an empty placeholder for the CSS stylesheet file
+ (RSSReader.css) so that you have the file ready for when we'll create some CSS rules
+ for the widget. Also create an empty placeholder for the RSSReader.js file where the
+ majority of the widget's code will go. We'll return to this in a little bit!
+
+
+
+
+
+Architecture
+
+
+
+
+ Before we write any code, let's talk about what the architecture of the RSS Reader
+ will be like. As we previously mentioned, the widget will have two views. A main
+ view for showing feed news items and a settings view to allow users to configure
+ what RSS feed to show and how often to update it. We also said that we'll have a
+ custom Options menu.
+
+
+
+
+ The entire code that implements fetching and parsing RSS feeds will be implemented
+ in the file FeedUpdateBroker.js. The widget code will use it through only one single
+ method: fetchFeed(). The way this works is that we will pass the URL of the RSS
+ feed to the method, as well as a function that will get called when the fetch has
+ been completed. Note that this call is asynchronous - it will immediately return
+ after it's called and the actual outcome of the fetch will not be known until the
+ callback method is called. As an argument to the callback we will receive an object
+ with three properties: status, lastModified and items. The status property will
+ contain a value of either "ok" or "error" depending on the outcome. The lastModified
+ will be present in case the fetch was successful and contains a timestamp that
+ indicates when the RSS feed was last updated. This will allow us to determine whether
+ there is any new news items or not so that we only update the user interface if there
+ really is something to update. Finally the third property "items" contains an array
+ of parsed RSS news items. Each of these is a JavaScript object that has four
+ properties: title for the news item headline, date to indicate when it was created,
+ description for the news item summary, and link with an URL to the full story.
+
+
+
+
+ We will setup a timer in the widget that will run a function once every second. In
+ this function we will compare the current time to a scheduled "next update" time.
+ If we have reached the next update time, we will use the feed update broker to fetch
+ the RSS news items of the feed that we're interested in. When the feed has been
+ fetched and parsed a callback method will be called and we will react to the callback
+ by either showing an error message (if the update failed), ignoring the callback (if
+ there was no new news items for us), or update the user interface (if there's new
+ news items to show).
+
+
+
+
+ We also want to be able to update the news items on request and for that we will
+ put an option in the Options menu that triggers a function that sets the next
+ scheduled update time to be immediately. That way the normal update timer will
+ immediately get triggered and cause an update.
+
+
+
+
+ We will also set the "next update" time whenever the feed update broker is used
+ to fetch new news items. That way we will get an automatic periodic update of the
+ news that will run in the background but can also be triggered to run immediately
+ if the user asks it to be.
+
+
+
+
+ In order to fetch and update news items with this mechanism we need two things:
+ the URL to the RSS feed and the interval between the automatic updates. These are
+ also the two properties that we will allow the user to configure in the settings
+ view. The properties will be stored in the widget preferences store and updated
+ there whenever the user saves the settings. The settings will be read when the
+ widget starts.
+
+
+
+
+ When the news items are fetched we will display a notification popup dialog to
+ indicate that the loading is in progress. The main reason why this is important
+ is because the loading takes some time and if we don't react immediately to the
+ user's action then the user will feel like the widget is not responsive. However
+ we don't want to popup a progress dialog every time the widget loads news in the
+ background. That would be really annoying when the user is reading news! This
+ means that we have to know whether the update was triggered manually or if it
+ was scheduled. We'll use a flag to track this and popup the dialog only if the
+ update was commanded by the user.
+
+
+
+
+ The settings view will contain four controls: a selection control to select the
+ feed URL, another selection control to select the feed update frequency, a save
+ button and a cancel button.
+
+
+
+
+ The main view in turn will contain a variable amount of controls: one for each
+ news item. The control that we will use is a ContentPanel control, which allows
+ us to collapse and expand the content so that we can display a compact list of
+ news headlines yet allow the user to open up a particular piece of news that
+ is interesting and read the summay or go to the website where the full news
+ story can be found. The news item controls will have the news headline as the
+ caption in the control. Unlike for other controls, ContentPanel captions are
+ interactive and can be clicked. When clicked they will toggle the content area
+ of the panel. We will put the actual news story summary in this content area.
+ The news story summary will be a fragment of HTML that we will construct from
+ each news story. The HTML will also include a link to the website where the
+ full story is located. The HTML will be styled by CSS rules that we will write
+ to the RSSReader.css file.
+
+
+
+
+ Because we don't know how many news stories we will have at any given time, we
+ will add and remove ContentPanel controls to the main view dynamically whenever
+ there's some update in the RSS feed. But we're environmentally conscious so
+ we'll recycle the ContentPanels. There's no need to throw them away even if they
+ are not needed. So once we have created them we will put them in a pool so that
+ we can recycle them. Later on if we need more ContentPanels will look for them
+ in the pool first and only if there are no ready ContentPanel controls for us
+ will we create more controls (and place them in the pool). Strictly speaking such
+ recycling is not necessary but it doesn't complicate the code much and it's a good
+ skill to know.
+
+
+
+
+ Finally, as we move between the main view and settings view we will need to
+ change the right softkey so that it's "Exit" in the main view and "Cancel" in
+ the settings view.
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_RSS_Reader_user_interface-GUID-1083a0c4-a953-4b6e-a4d0-45a031e51c35.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_RSS_Reader_user_interface-GUID-1083a0c4-a953-4b6e-a4d0-45a031e51c35.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,631 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+RSS Reader user interface
+
+
+
+
+
+
+RSS Reader user interface
+
+
+
+
+Preferences
+
+
+
+
+ Now it's time to write some code so let's open up RSSReader.js. The first thing
+ we will do is implement the init() function that gets called when the widget has
+ loaded. We will begin by setting up the timer-based updating mechanism for the
+ feed updates by declaring four variables that we'll need for that:
+
+
+
+
+// Feed update timer identifier.
+var updateTimerId = null;
+
+// Feed URL and update frequency (in milliseconds; -1 if no auto update).
+var feedURL = null;
+var feedUpdateFrequency = -1;
+
+// Next scheduled update time; -1 if never.
+var feedUpdateTime = -1;
+
+
+
+
+ We know that we'll need to get some working values for the feed URL and feed update
+ frequency variables and we know that they will be configurable values so let's write
+ the code for this:
+
+
+
+
+// Called from the onload event handler to initialize the widget.
+function init() {
+ // load preferences
+ loadPreferences();
+
+ // start feed update timer (called once every second)
+ updateTimerId = setInterval(updateFeedTimerFunc, 1000);
+}
+
+// Loads widget preferences.
+function loadPreferences() {
+ if (window.widget) {
+ // read feed URL and update frequency from the widget settings
+ feedURL = widget.preferenceForKey("FeedURL");
+ var feedUpdateFrequencyStr = widget.preferenceForKey("FeedUpdateFrequency");
+ feedUpdateFrequency = (feedUpdateFrequencyStr == null) ? -1 : parseInt(feedUpdateFrequencyStr);
+ }
+}
+
+// Timer function for feed updates - called once every second.
+function updateFeedTimerFunc() {
+
+}
+
+
+
+
+ The init() function does two things at this point. First it calls our newly created
+ loadPreferences() function that takes care of reading some values for the feedURL
+ and feedUpdateFrequency variables. After this it starts up an interval timer that
+ calls updateFeedTimerFunc() once every second. The function doesn't do anything
+ yet but we'll get to that in a bit. The timer identifier is stored in the updateTimerId
+ variable. If no configuration is found, feedURL will have a value of null and
+ feedUpdateFrequency will have a value of -1. Note that all preferences are stored
+ as strings so we need to parse the string value to an integer. Also note that we
+ wrapped the preference loading code in an if-clause that checks if we are in the
+ S60 Web Runtime environment. This allows us to run the code in a PC browser without
+ getting an error message about the widget -related methods that don't exist outside
+ of the S60 Web Runtime.
+
+
+
+
+ While we're on the topic of preferences we'll write a save counterpart for the
+ loadPreferences() function.
+
+
+
+
+// Saves widget preferences.
+function savePreferences() {
+ if (window.widget) {
+ // save settings in widget preferences store
+ widget.setPreferenceForKey(feedURL, "FeedURL");
+ widget.setPreferenceForKey(feedUpdateFrequency.toString(), "FeedUpdateFrequency");
+ }
+}
+
+
+
+
+ We're now almost done with the timer mechanism that will update the RSS feed but
+ we are missing one thing: a way to manually schedule an immediate update of the
+ feeds. Let's add a flag that we can use to track if an update was triggered
+ automatically or manually:
+
+
+
+
+// Flag that tracks if a feed update is commanded or automatic.
+var feedUpdateCommanded = false;
+
+
+
+
+ And now let's add a function that can be called to schedule an immediate update:
+
+
+ The function just sets the next update time to 0 so that the next time the
+ timer function runs it will notice that it's time to schedule a feed update.
+ The function also sets the feedUpdateCommanded flag to true so that the
+ updating mechanism will know that this was a manual update.
+
+
+
+
+
+Creating the user interface
+
+
+
+
+ Now let's create the user interface. We'll start by declaring three variables
+ where we will hold references to the user interface manager, main view and settings
+ view. Note that these should be outside the init() function.
+
+
+
+
+// References to the WRTKit user interface manager and views.
+var uiManager;
+var mainView;
+var settingsView;
+
+
+
+
+ We want our user interface to be in tab navigation mode and we want the softkey
+ bar to be visible. The code for this is the same as in the Hello World example.
+ Next we create the user interface manager, main view and settings view by adding
+ the following code to the init() function:
+
+
+
+
+if (window.widget) {
+ // set tab-navigation mode and show softkeys
+ widget.setNavigationEnabled(false);
+ menu.showSoftkeys();
+}
+
+// create UI manager
+uiManager = new UIManager();
+
+// create main view
+mainView = new ListView();
+
+// create settings view
+settingsView = new ListView(null, "Settings");
+
+
+
+
+ You might have noticed that we didn't supply any arguments to the ListView constructor
+ when the main view was created. The reason for this is that we will set the view caption
+ dynamically depending on the news feed we are following. And since we don't need the
+ unique identifier for the main view we don't even have to pass null to it. Remember: in
+ JavaScript if you don't pass an argument it will be undefined, which is equal to null.
+
+
+
+
+ The main view will not get populated with controls until we have some news feed items
+ to display, but we can go ahead and create the settings view. Again, we will first
+ declare variables to hold references to the controls and again, they should be declared
+ outside the init() method so that they are accessible elsewhere in the widget code:
+
+
+ Now that we have variables to receive the control references we can go ahead and create
+ them and add them to the settings view. We will create a SelectionMenu control to let
+ the user select the RSS feed to show, a SelectionList control to allow selection of
+ the feed update frequency and two form buttons: "Save" and "Cancel". The SelectionMenu
+ and SelectionList controls are identical from a developer's point of view but look
+ very different. The SelectionMenu takes up very little space in the view but when clicked
+ it pops up a list of options that the user can select from. This is good if theres a lot
+ of options and we don't want to use up a lot of space from the view. The SelectionList
+ is the exact opposite and shows all the options right there in the view. This is good
+ if the widget is in pointer navigation mode or if there are very few options.
+
+
+
+
+ Options for the SelectionMenu and SelectionList controls are defined as an array of
+ JavaScript objects that have two properties: value and text. The value property contains
+ the actual data of the option and the text property contains the string to display to
+ the user. Before we create the controls we need to create the option arrays for the
+ RSS feed options and update frequency options. These will simply be hard coded arrays
+ that are defined using JavaScript object notation (JSON) and we'll place them at the top
+ of the widget code so that they can be easily customized later on:
+
+
+ The RSS feeds are all from the Nokia Nseries WOM World website but you could put any
+ RSS feed URLs here that you like. However it is probably a good idea to stick with
+ these for now since we know that they work. Later when the widget is completed you can try
+ with other feeds. Note how the value is a URL but the text to display is a human readable
+ name for the RSS feeds.
+
+
+
+
+ The update frequency options are defined in milliseconds and there is one option with a
+ magic value of -1 for "never". Here too you'll notice the difference between the value
+ (an integer in this case) and the human readable text.
+
+
+
+
+ Now that we have the option arrays we can create the controls for the settings view by
+ adding the following code to the init() function:
+
+
+
+
+ // feed selection control
+ feedSelection = new SelectionMenu(null, "Select feed", feedOptions);
+ settingsView.addControl(feedSelection);
+
+ // feed update frequency selection control
+ feedUpdateFrequencySelection = new SelectionList(null, "Check for updates", updateFrequencyOptions);
+ settingsView.addControl(feedUpdateFrequencySelection);
+
+ // save settings button
+ settingsSaveButton = new FormButton(null, "Save");
+ settingsView.addControl(settingsSaveButton);
+
+ // cancel settings button
+ settingsCancelButton = new FormButton(null, "Cancel");
+ settingsView.addControl(settingsCancelButton);
+
+
+
+
+ The two first arguments for the SelectionMenu and SelectionList constructors are the
+ same as for most other controls: a unique identifier and a control caption. The third
+ argument points to the array of options that the controls should display. You could
+ also have omitted that argument from the constructor and instead called setOptions()
+ later on, but why do it in two steps when you can do it in one?
+
+
+
+
+ The user interface views are now done (minus the actual news items to display in the main
+ view of course) but we still have some things to implement for the user interface. The
+ buttons in the settings view don't do anything yet so let's fix that.
+
+
+
+
+ The cancel button should take the user to the main view and the save button should
+ start using the newly configured settings, save them, and then go to the main view.
+ Our plan to implement this is to create a function for showing the main view, called
+ "showMainView()", a similar function for showing the settings view that we will call
+ "showSettings()", and a function that will be called when the save button is clicked
+ called "saveSettingsClicked()". We will then add event listeners to the two buttons
+ so that clicking the save button will result in a call to the saveSettingsClicked()
+ function and clicking the cancel button will result in a call to the showMainView()
+ function. Let's create empty placeholders for the functions first:
+
+
+
+
+// Callback for settings view save button.
+function saveSettingsClicked() {
+}
+
+// Show main view.
+function showMainView() {
+}
+
+// Show settings view.
+function showSettings() {
+}
+
+
+
+
+ Now that we have those functions let's register the event listeners to the form
+ buttons by adding these two lines of code immediately after where the buttons
+ are created:
+
+
+ We are now ready to implement the functions to show the main view, settings view
+ and react to the save button click. But we won't implement those just yet because
+ we want to do one more thing before that. Let's create the custom Options menu.
+ The Options menu isn't using any WRTKit code but rather the standard S60 Web Runtime
+ widget menu functionality. We'll have two menu items: "Refresh" to schedule an immediate
+ news feed update and "Settings" to go to the settings view. The Web Runtime Options
+ menu works so that a callback function gets called when the user selections an Options
+ menu item. In order to recognize which menu item was selected we'll need a unique
+ identifier for each of them. Let's create those:
+
+
+
+
+// Constants for menu item identifiers.
+var MENU_ITEM_SETTINGS = 0;
+var MENU_ITEM_REFRESH = 1;
+
+
+
+
+ Next we'll create the callback function that will be called when the menu items are
+ selected:
+
+
+
+
+// Callback for when menu items are selected.
+function menuItemSelected(id) {
+ switch (id) {
+ case MENU_ITEM_SETTINGS:
+ showSettings();
+ break;
+ case MENU_ITEM_REFRESH:
+ updateFeed();
+ break;
+ }
+}
+
+
+
+
+ This function gets the menu item identifier passed to it when the user selects
+ a menu item. The switch-case will branch off to call showSettings() if the "Settings"
+ menu item was selected and updateFeed() if the "Refresh" menu item was selected.
+ But we haven't actually created the menu yet so let's do that by adding this to the
+ init() function right after where we show the softkey bar. We want to have this piece
+ of code inside the if-clause that checks if we're in the S60 Web Runtime because we
+ don't have the Options menu functionality on a PC browser.
+
+
+
+
+// create menu
+var settingsMenuItem = new MenuItem("Settings", MENU_ITEM_SETTINGS);
+settingsMenuItem.onSelect = menuItemSelected;
+menu.append(settingsMenuItem);
+var refreshMenuItem = new MenuItem("Refresh", MENU_ITEM_REFRESH);
+refreshMenuItem.onSelect = menuItemSelected;
+menu.append(refreshMenuItem);
+
+
+
+
+ The code simply creates two MenuItem objects, gives them a label and a unique
+ identifier, specifies the callback function to call when selected and then adds
+ them to the Options menu. The menu object is a global object that automatically
+ exists in the S60 Web Runtime.
+
+
+
+
+ Now let's return to the three functions we created but didn't implement. We will
+ start with the showMainMenu() function. This function should perform all necessary
+ steps to show the main menu. This includes the following: setting a caption for
+ the main view, setting the right softkey to be the default "Exit" label and
+ functionality, and then actually showing the main view by calling setView() in the
+ user interface manager. We'll get the main view caption by checking which of the
+ RSS feeds the user has currently selected. We do this by looping through the feed
+ options and looking for the feed URL that is currently in use. If we can't find one
+ we'll default to "RSS Reader".
+
+
+
+
+// Show main view.
+function showMainView() {
+ // set main view caption from feed name
+ var feedName = null;
+ for (var i = 0; i < feedOptions.length; i++) {
+ if (feedOptions[i].value == feedURL) {
+ feedName = feedOptions[i].text;
+ break;
+ }
+ }
+ var mainViewCaption = (feedName == null) ? "RSS Reader" : feedName;
+ mainView.setCaption(mainViewCaption);
+
+ // set right softkey to "exit"
+ if (window.widget) {
+ menu.setRightSoftkeyLabel("", null);
+ }
+
+ // show the main view
+ uiManager.setView(mainView);
+}
+
+
+
+
+ When the settings view is shown we first want to place the controls into
+ a state that reflects the current configuration. In other words we want
+ the currently configured feed to be the one that's selected in the feed selection
+ control. In the same way the currently configured feed update frequency should
+ be selected in the feed update frequency selection control. There is a very
+ convenient method available for this called getOptionForValue(). Using that
+ function we can pass the currently configured feed URL and feed update frequency
+ and get back the options object that corresponds to the configuration value.
+ After this we can use that options object when we call setSelected() to select
+ that option.
+
+
+
+
+ If there is no valid configuration then we disable the cancel button and make
+ the right softkey be "Exit". This is useful when the widget is started for the
+ first time so that user has to enter a valid configuration before starting to
+ use the widget. If there is a valid configuration we set the right softkey to
+ "Cancel" and make it call the showMainView() function that we just created. The
+ "Cancel" button will also be enabled.
+
+
+
+
+ Finally we'll switch to the settings view by calling setView() in the user
+ interface manager.
+
+
+
+
+// Show settings view.
+function showSettings() {
+ // URL (use first available feed if null)
+ var feedOption = (feedURL == null) ? feedOptions[0] : feedSelection.getOptionForValue(feedURL);
+ feedSelection.setSelected(feedOption);
+
+ // frequency
+ var feedUpdateFrequencyOption = feedUpdateFrequencySelection.getOptionForValue(feedUpdateFrequency);
+ feedUpdateFrequencySelection.setSelected(feedUpdateFrequencyOption);
+
+ if (feedURL == null) {
+ // no valid configuration
+ // disable cancel button - set right softkey to "exit"
+ settingsCancelButton.setEnabled(false);
+ if (window.widget) {
+ menu.setRightSoftkeyLabel("", null);
+ }
+ } else {
+ // we have a valid configuration
+ // enable cancel button - set right softkey to "cancel"
+ settingsCancelButton.setEnabled(true);
+ if (window.widget) {
+ menu.setRightSoftkeyLabel("Cancel", showMainView);
+ }
+ }
+
+ // show the settings view
+ uiManager.setView(settingsView);
+}
+
+
+
+
+ The third function to implement is the callback for when the save button is clicked.
+ First we take the selected options from the feed selection and feed update frequency
+ selection controls. Those selected values are copied to the feedURL and feedUpdateFrequency
+ variables that are used by the widget during runtime. Next the settings are saved using
+ the savePreferences() function that we implemented earlier. And finally we call the
+ showMainView() method so that the widget shows the main view with the news items.
+
+
+
+
+// Callback for settings view save button.
+function saveSettingsClicked() {
+ // update feed URL
+ var selectedFeed = feedSelection.getSelected();
+ feedURL = (selectedFeed != null) ? selectedFeed.value : null;
+
+ // update frequency
+ var selectedFrequency = feedUpdateFrequencySelection.getSelected();
+ feedUpdateFrequency = (selectedFrequency != null) ? selectedFrequency.value : -1;
+
+ // save preferences
+ savePreferences();
+
+ // return to main view
+ showMainView();
+}
+
+
+
+
+ The user interface is now nearly done but the init() function needs one more
+ thing. We need to show a view after the function is done initializing
+ the widget. The view to show depeneds on whether we have a valid
+ configuration or not. If we do then we'll show the main view. If not then
+ we'll show the settings view. Let's add this code to the end of the init()
+ function, just before we start the update timer:
+
+
+
+
+// display the main view if a feed has been configured
+// otherwise show the settings view
+if (feedURL != null) {
+ showMainView();
+ updateFeed();
+} else {
+ showSettings();
+}
+
+
+
+
+ You can now go ahead and try out the widget either on a handset, emulator
+ or in a PC browser. You should have a working settings view and when clicking
+ the save button in the settings view you should end up in the main view. From
+ there you can go to the settings by selecting "Settings" in the Options menu.
+
+
+
+
+ There are no news items to show yet but that's our next task.
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_SelectionControl_Class-GUID-35c4291f-dc3a-439c-890f-1d140864aca0.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_SelectionControl_Class-GUID-35c4291f-dc3a-439c-890f-1d140864aca0.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,564 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+WRTKit SelectionControl Class
+
+
+
+
+
+
+WRTKit SelectionControl Class
+
+
+
+
+Description
+
+
+
+
+ The SelectionControl class is an abstract base class for all controls that lets
+ the user select one or more options from a set of options.
+
+
+
+
+ The options in a selection control are simple option objects with two properties:
+ value and text. An option is specified using JavaScript object notation (JSON) as
+
+{ value: "value here", text: "Text for value goes here" }. The value
+ property specifies the actual value of the option whereas the text property specifies
+ how the option is shown to the user in the control. E.g. the value could be a boolean
+ value while the text could be "Yes" or "No". The text value is an XHTML string.
+
+
+
+
+ Don't instantiate SelectionControl directly but rather one of its subclasses.
+
+
+ Returns a boolean value that indicates whether the the specified option
+ is currently selected. Options are objects with two properties: value and text.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+option
+
+
+
+
+
+ The option to check the selected state for.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ True if the specified option is selected, false if not.
+
+
+ Retrieves the currently selected option or options. If the control is a multiple
+ selection control then an array of selected options is returned (an empty array if
+ no options are selected). If the control is a single selection control then the
+ single selection option is returned, or null if no options are selected.
+ Options are objects with two properties: value and text.
+
+
+
+
+
+Arguments
+
+
+
+
+ This method does not take any arguments.
+
+
+
+
+
+Return value
+
+
+
+
+ An array containing the currently selected options for multiple selection controls.
+ For single selection controls the return value is the selected option. If no options
+ are selected then an empty array is returned for multiple selection controls and null
+ is returned for single selection controls.
+
+
+ Sets the currently selected options for a selection control. The selected options
+ should be a subset of the options contain within the control. For a multiple selection
+ control an array of options should be specified. For a single selection control the
+ single option that should be selected should be specified without being contained in
+ an array. To select zero options pass an empty array for multiple selection controls
+ and null for single selection controls. Options are objects with two properties:
+ value and text.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+selected
+
+
+
+
+
+ The options to select. For multiple selection controls this argument
+ should be an array of the options to select or an empty array to select
+ zero elements. For single selection controls it should be a single option
+ object or null for no selected options.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ This method does not return a value.
+
+
+
+
+
+
+
+
+
+
+
+getOptions()
+
+
+
+
+Syntax
+
+
+
+[Array] SelectionControl.getOptions(void)
+
+
+
+
+Description
+
+
+
+
+ Retrieves the options available to the user in the control. The options are
+ returned as an array of option objects. Options are objects with two properties:
+ value and text.
+
+
+
+
+
+Arguments
+
+
+
+
+ This method does not take any arguments.
+
+
+
+
+
+Return value
+
+
+
+
+ An array containing the options in the control.
+
+
+ Sets the options that this control should give the user. Calling this method
+ replaces the current options with the specified new ones. If one or more selected
+ options are no longer part of the available options after calling this method
+ then they will automatically be removed from the selected set. The options
+ are given as an array of option objects. Options are objects with two properties:
+ value and text. The text value is an XHTML string.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+options
+
+
+
+
+
+ An array of options to give the user. These options replace the
+ current options in the control.
+
+
+ Retrieves the option in the selection control that has a value that matches
+ the specified one. If multiple options have the same value then the first matching
+ one is returned. If there is no match then null is returned.
+
+
+
+
+ This method is a useful helper method for situations where a specific value in the
+ options should be programmatically selected.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+value
+
+
+
+
+
+ The value to search for among the options in the selection control.
+ The value can be of any JavaScript type.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ The first option in this selection control that has a value that matches the
+ specified one, or null if no matching option is found.
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_SelectionList_Class-GUID-c3be7a8a-9028-4cec-a0c0-d355d0621b37.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_SelectionList_Class-GUID-c3be7a8a-9028-4cec-a0c0-d355d0621b37.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,217 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+WRTKit SelectionList Class
+
+
+
+
+
+
+WRTKit SelectionList Class
+
+
+
+
+Description
+
+
+
+
+ The SelectionList class is an implementation of a selection control that displays
+ a list of options to the user. Options are displayed as radio buttons or checkboxes
+ depending on if the control is in single or multiple-selection mode. Selection lists
+ are useful in situations where the widget is used in pointer navigation mode or if
+ there is a small amount of options.
+
+
+ Creates a new instance of the SelectionList class.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+id
+
+
+
+
+
+ Unique identifier for the control. Can be retrieved using the id property defined
+ in the UIElement class that this control inherits from. Useful for example to
+ identify the source of an event in event callback functions or to apply a CSS
+ rule to only this particular control. The identifier can be null, in which case
+ no id will be set for the control.
+
+
+
+
+
+
+
+
+caption
+
+
+
+
+
+ The caption text for the control. A null caption can be used to hide the
+ caption area. The value is an XHTML string.
+
+
+
+
+
+
+
+
+options
+
+
+
+
+
+ An array of options that the selection list should display to the user.
+ If the argument is omitted or null the control will not display any
+ options. The options can be set or changed later by calling setOptions().
+ Options are objects with two properties: value and text. Use JavaScript
+ object notation (JSON) to construct option objects, e.g.
+
+{ value: "value here", text: "Text for value goes here" }.
+ The text value is an XHTML string.
+
+
+
+
+
+
+
+
+multipleSelection
+
+
+
+
+
+ The multipleSelection argument is a boolean flag that determines whether
+ the control should be in multipleSelection mode or not. Use true to put
+ the control in multiple selection mode and false to put it in single
+ selection mode. If this argument is omitted the control will go to single
+ selection mode by default.
+
+
+
+
+
+
+
+
+selected
+
+
+
+
+
+ The selected argument specifies which of the options should be selected at
+ creation time. For multiple selection controls this should be given as an
+ array of option objects with an empty array if no options should be selected.
+ For single selection controls this should be the single option object that
+ should be selected or null if no option should be selected. If the argument
+ is omitted or null no options will be selected.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ A new instance of the SelectionList class.
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_SelectionMenu_Class-GUID-3ae54fdf-e938-400b-969d-e41575331aa0.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_SelectionMenu_Class-GUID-3ae54fdf-e938-400b-969d-e41575331aa0.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,225 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+WRTKit SelectionMenu Class
+
+
+
+
+
+
+WRTKit SelectionMenu Class
+
+
+
+
+Description
+
+
+
+
+ The SelectionMenu class is an implementation of a selection control that lets
+ users select options from a popup menu.
+
+
+
+
+ The SelectionMenu control has two modes: a display mode and a selection mode.
+ Normally the display mode is shown and users can see what the currently selected
+ options are. When a user selects the control a menu pops up that displays the
+ available options. The user can then select the option (or options) from this
+ menu. After the selection is done the menu goes away and the control returns to
+ display mode. The SelectionMenu control is useful in situations where there
+ are many options and showing them all uses up too much space.
+
+
+ Creates a new instance of the SelectionMenu class.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+id
+
+
+
+
+
+ Unique identifier for the control. Can be retrieved using the id property defined
+ in the UIElement class that this control inherits from. Useful for example to
+ identify the source of an event in event callback functions or to apply a CSS
+ rule to only this particular control. The identifier can be null, in which case
+ no id will be set for the control.
+
+
+
+
+
+
+
+
+caption
+
+
+
+
+
+ The caption text for the control. A null caption can be used to hide the
+ caption area. The value is an XHTML string.
+
+
+
+
+
+
+
+
+options
+
+
+
+
+
+ An array of options that the selection menu should display to the user.
+ If the argument is omitted or null the control will not display any
+ options. The options can be set or changed later by calling setOptions().
+ Options are objects with two properties: value and text. Use JavaScript
+ object notation (JSON) to construct option objects, e.g.
+
+{ value: "value here", text: "Text for value goes here" }.
+ The text value is an XHTML string.
+
+
+
+
+
+
+
+
+multipleSelection
+
+
+
+
+
+ The multipleSelection argument is a boolean flag that determines whether
+ the control should be in multipleSelection mode or not. Use true to put
+ the control in multiple selection mode and false to put it in single
+ selection mode. If this argument is omitted the control will go to single
+ selection mode by default.
+
+
+
+
+
+
+
+
+selected
+
+
+
+
+
+ The selected argument specifies which of the options should be selected at
+ creation time. For multiple selection controls this should be given as an
+ array of option objects with an empty array if no options should be selected.
+ For single selection controls this should be the single option object that
+ should be selected or null if no option should be selected. If the argument
+ is omitted or null no options will be selected.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ A new instance of the SelectionMenu class.
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Selections-GUID-23145d13-f2e7-48be-b24b-bc49754b2919.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Selections-GUID-23145d13-f2e7-48be-b24b-bc49754b2919.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,113 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Selections
+
+
+
+
+
+
+Selections
+
+
+
+
+
+ Selection of one or more options from a set of options is one of the most common
+ use cases in a user interface. The WRTKit supports this use case with two
+ controls, SelectionList and SelectionMenu, each of which can be in either
+ "single selection" or "multiple selection" mode. The two controls differe only
+ in look and interaction but not in their APIs.
+
+
+
+
+ The SelectionList control shows an expanded list of all of its options in the
+ view. If the control is in single selection mode then each option is presented
+ with a "radio button", of which only one can be selected at a time. This ensures
+ that only one of the options can be selected by the user. If the SelectionList
+ control is in multiple selection mode then each option is presented with a
+ "checkbox". Any amount (including zero) of checkboxes can be checked at time,
+ allowing users to select multiple options. The SelectionList control is a hybrid
+ between the traditional way of showing radio buttons and checkboxes in a web
+ environment and the way that an S60 application shows single and multiple choice
+ selections. The SelectionList is recommeded to be used when the widget is using
+ the pointer navigation mode or when there are only a few options.
+
+
+
Figure 1.
+SelectionList controls
+
+
+
+
+
+
+
+ The SelectionMenu control is more similar to the way normal S60 applications
+ allow users to make single or multiple choices. The SelectionMenu takes up only
+ minimally of space in its normal state, but when activated it pops up up a list
+ of options with either radio buttons (for single selection) or checkboxes (for
+ multiple selection) that the user can select. The SelectionMenu control is good
+ for the tab navigation mode or if there are many options that would use up lots
+ of space on the screen using the SelectionList control.
+
+
+
Figure 2.
+SelectionMenu control
+
+
+
+
+
+
+
+ Options in the selection controls are specified as an array of JavaScript
+ objects, where each object represents one option. Each option object has two
+ properties: value and text. The value property can be any JavaScript value,
+ including object references and is used to represent the concrete value of the
+ option. The text property is used to display the option in the user interface.
+ The value could for example be a boolean true or false while the
+ text could be "Yes" or "No".
+
+
+
+
+ The set of currently selected options can be set or retrieved from a selection
+ control using getter and setter methods. For single selection controls the
+ selected option is specified as a single reference to one of the options in the
+ control. For multiple selection the selected options are specified as an array
+ of references to zero or more of the options in the control. Note that the
+ references to the options must refer to the very same options that are in the
+ control - not other instances of the options even if they are identical in value
+ and/or text.
+
+
+
+
+ Selection controls fire "SelectionChanged" events when the user makes a
+ selection in the control.
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Separator-GUID-ec82d9ea-6b88-48c6-92c2-09a4dd56b31a.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Separator-GUID-ec82d9ea-6b88-48c6-92c2-09a4dd56b31a.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,56 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Separator
+
+
+
+
+
+
+Separator
+
+
+
+
+
+ There is a special Separator control that has no other functionality except to
+ act as a visual separator between controls. By adding an instance of a Separator
+ control in a view it is possible to split the view visually so that it better
+ groups related controls together and makes the view easier to comprehend.
+
+
+
Figure 1.
+Two separators in a view
+
+
+
+
+
+
+
+ Separator controls do not have any control specific API except for their
+ constructor.
+
+
+ Creates a new instance of the Separator class.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+id
+
+
+
+
+
+ Unique identifier for the control. Can be retrieved using the id property defined
+ in the UIElement class that this control inherits from. Useful for example to
+ identify the source of an event in event callback functions or to apply a CSS
+ rule to only this particular control. The identifier can be null, in which case
+ no id will be set for the control.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ A new instance of the Separator class.
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Showing_content_in_a_view-GUID-7020d9ea-747d-42f3-b47c-16ad1f45db82.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Showing_content_in_a_view-GUID-7020d9ea-747d-42f3-b47c-16ad1f45db82.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,130 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Showing content in a view
+
+
+
+
+
+
+Showing content in a view
+
+
+
+
+
+ The WRTKit has two controls for showing content inside a view. The
+ first of the controls is called Label and is useful for simple and
+ short information to be displayed, coupled with the control caption
+ that describes the information.
+
+
+
Figure 1.
+Label control
+
+
+
+
+
+
+
+ The second control is called ContentPanel and is more sophisticated
+ than the Label control. ContentPanel controls can be created as
+ foldable, which means that they can expand and collapse their
+ content areas. Users can toggle the expanded and collapsed state by
+ clicking on the caption area of the ContentPanel.
+
+
+
Figure 2.
+Foldable content panel
+
+
+
+
+
+
+
+ The code below creates a Label control and a foldable ContentPanel
+ control and adds them to a view. The code assumes that a view has
+ already been created and that a variable called exampleView refers
+ to it.
+
+
+ The first and second arguments are the same in the constructors for
+ both controls. The first is a unique identifier for the control and
+ the second is the control caption. The third argument is also the
+ same but is omitted for the label and null for the content panel
+ since in both cases we don't specify any content at this point. The
+ fourth argument for the content panel is a boolean that specifies
+ whether the control should be foldable or not.
+
+
+
+
+ The value for a label can be set and retrieved using the getText() and
+ setText() methods. For content panels the content in the content area
+ can be set and retrieved using getContent() and setContent(). The
+ content is defined as an XHTML fragment and can contain arbitrarily
+ complex XHTML, including images or even JavaScript.
+
+
+
+
+// set the text for the label
+nameLabel.setText("John Smith");
+
+// set content for the content panel
+infoPanel.setContent("<b>This is bolded!</b><br/>This is plain text on the second line.");
+
+
+
+
+ Foldable ContentPanel controls can be programmatically collapsed or
+ expanded using the setExpanded() method. The expanded state can be
+ retrieved using the isExpanded() method.
+
+
+
+
+// retrieve the expanded state
+var expanded = infoPanel.isExpanded();
+
+// collapse the content panel
+infoPanel.setExpanded(false);
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Terminology-GUID-ebd8d7c4-03f6-498d-becc-eb8d4081ed8b.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Terminology-GUID-ebd8d7c4-03f6-498d-becc-eb8d4081ed8b.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,155 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Terminology
+
+
+
+
+
+
+Terminology
+
+
+
+
+Control
+
+
+
+
+ A control is a user interface element that the user can interact with. Controls
+ are used in PC applications, in web pages and in mobile device applications. In
+ web pages controls are often known as "form controls". Common controls include
+ textfields, textareas, buttons, checkboxes, radio buttons, scrollbars, labels
+ and progress bars, among others. Not all controls are interactive, e.g. labels
+ simply display a value. Controls are contained within some kind of user
+ interface container such as a view or window.
+
+
+
+
+ In the WRTKit, controls are JavaScript objects that contain the state and
+ implement the behavior of the control. Controls take care of drawing themselves,
+ including changing their appearence as a result of various state changes.
+
+
+
+
+
+View
+
+
+
+
+ A container for user interface elements such as controls. On a mobile device
+ user interface views typically fill the entire screen and thus only one view can
+ be shown at a time. Views in a mobile device tend to lay out the elements it
+ contains in a vertical list that can be scrolled up and down if there is more
+ content in the view than what fits on the screen at a time.
+
+
+
+
+ In the WRTKit, views are responsible for laying out controls. Custom views can
+ be created to support advanced layouts but in the vast majority of cases the
+ default ListView is sufficient. WRTKit views are JavaScript objects.
+
+
+
+
+
+Event
+
+
+
+
+ An event is a notification of some occurrence in a user interface element, such
+ as a view or control. Events are typically propagated to application code as
+ messages or function calls or a combination of the two.
+
+
+
+
+ The WRTKit uses a model known as the "observer pattern" to deliver event
+ messages, which are JavaScript objects, to event listeners, which are JavaScript
+ callback functions. WRTKit events have a type name that can be used to
+ distinguish between different types of events. E.g. a button press produces an
+ "ActionPerformed" event.
+
+
+
+
+
+Focus
+
+
+
+
+ The control that is currently selected to receive input is said to be focused.
+ Controls can be focused in both the tab and pointer navigation modes. In the tab
+ mode the focus is moved between controls using the 4-way controller. In
+ the pointer mode the focus is moved between controls by moving the pointer to
+ "hover" above a control and then pressing a selection button to select that
+ control. Focused controls are displayed in a distinct way from other controls to
+ indicate that they are ready to be interacted with.
+
+
+
+
+
+Hovering
+
+
+
+
+ In pointer navigation mode, the pointer is said to be "hovering" above a control
+ if the pointer is located inside the control's area on the screen. Hovering is
+ similar to focus, but differs because hovering in itself does not select a
+ control for interaction. Rather a selection key must be pressed in order to
+ focus the control that the pointer is currently hovering over. Hover is
+ indicated by displaying a control in a distinct way from other controls.
+
+
+
+
+
+Navigation mode
+
+
+
+
+ A navigation mode refers to a method of selecting what user interface element to
+ interact with. The S60 Web Runtime supports two navigation modes: "tab" and
+ "pointer". In the tab mode, focus is moved between controls using the 4-way
+ controller. In pointer mode there is a pointer arrow on the screen that can be
+ moved freely using the 4-way controller. A control is focused by moving the
+ pointer arrow so that it hovers above a control, and then pressing a selection
+ key to select that control. In tab mode a control can be either in normal or
+ focused state, whereas in the pointer mode a control can be in normal, hover or
+ focused state.
+
+[TextArea] new TextArea(String id, String caption, String text, Integer rows)
+
+
+
+
+Description
+
+
+
+
+ Creates a new instance of the TextArea class.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+id
+
+
+
+
+
+ Unique identifier for the control. Can be retrieved using the id property defined
+ in the UIElement class that this control inherits from. Useful for example to
+ identify the source of an event in event callback functions or to apply a CSS
+ rule to only this particular control. The identifier can be null, in which case
+ no id will be set for the control.
+
+
+
+
+
+
+
+
+caption
+
+
+
+
+
+ The caption text for the control. A null caption can be used to hide the
+ caption area. The value is an XHTML string.
+
+
+
+
+
+
+
+
+text
+
+
+
+
+
+ The text to display in the text area. If the argument is omitted or null then
+ the text area will not contain any text when created.
+ The value is a plain text string (not XHTML).
+
+
+
+
+
+
+
+
+rows
+
+
+
+
+
+ The argument specifies how many rows the text area should have. If omitted the
+ text area will default to have 3 rows of text. Note that it is still possible
+ to enter more than 3 lines of text. The rows define the height of the text area
+ and thus how many lines of text are visible without scrolling.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ A new instance of the TextArea class.
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_TextEntryControl_Class-GUID-07359ff7-6015-4d2c-a9bf-b345fcf49090.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_TextEntryControl_Class-GUID-07359ff7-6015-4d2c-a9bf-b345fcf49090.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,209 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+WRTKit TextEntryControl Class
+
+
+
+
+
+
+WRTKit TextEntryControl Class
+
+
+
+
+Description
+
+
+
+
+ The TextEntryControl class is an abstract base class for controls that let a user
+ enter text. Don't instantiate TextEntryControl directly but rather one of its subclasses.
+
+
+ Retrieves the current text of the text entry control.
+ The value is a plain text string (not XHTML).
+
+
+
+
+
+Arguments
+
+
+
+
+ This method does not take any arguments.
+
+
+
+
+
+Return value
+
+
+
+
+ The current text of the text entry control.
+
+
+
+
+
+
+
+
+
+
+
+setText()
+
+
+
+
+Syntax
+
+
+
+[void] TextEntryControl.setText(String text)
+
+
+
+
+Description
+
+
+
+
+ Sets the text value of the text entry control. The text is displayed in the
+ editable area of the control and can be edited by the user provided that
+ the control is not disabled. Setting a text value of null results in no
+ text being shown. The value is a plain text string (not XHTML).
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+text
+
+
+
+
+
+ The text value to set to the text entry control. A value of null
+ results in no text being shown.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ This method does not return a value.
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_TextField_Class-GUID-799b7dea-1e4d-4147-bc27-acc4b91d8bf9.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_TextField_Class-GUID-799b7dea-1e4d-4147-bc27-acc4b91d8bf9.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,189 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+WRTKit TextField Class
+
+
+
+
+
+
+WRTKit TextField Class
+
+
+
+
+Description
+
+
+
+
+ The TextField class implements a single line text entry control. The control
+ is useful for situations where text is relatively short and doesn't need to
+ span multiple lines. The text field also supports masked entry, which is good
+ in situations where passwords or other secret text is entered.
+
+[TextField] new TextField(String id, String caption, String text, Boolean masked)
+
+
+
+
+Description
+
+
+
+
+ Creates a new instance of the TextField class.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+id
+
+
+
+
+
+ Unique identifier for the control. Can be retrieved using the id property defined
+ in the UIElement class that this control inherits from. Useful for example to
+ identify the source of an event in event callback functions or to apply a CSS
+ rule to only this particular control. The identifier can be null, in which case
+ no id will be set for the control.
+
+
+
+
+
+
+
+
+caption
+
+
+
+
+
+ The caption text for the control. A null caption can be used to hide the
+ caption area. The value is an XHTML string.
+
+
+
+
+
+
+
+
+text
+
+
+
+
+
+ The text to display in the text field. If the argument is omitted or null then
+ the text field will not contain any text when created.
+ The value is a plain text string (not XHTML).
+
+
+
+
+
+
+
+
+masked
+
+
+
+
+
+ If the masked argument is true then the text field will be created in masked
+ text entry mode. If the argument is omitted or false then the control will be
+ created in normal text entry mode.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ A new instance of the TextField class.
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Text_entry-GUID-b52e3343-5a39-4a83-ae97-461a53761207.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Text_entry-GUID-b52e3343-5a39-4a83-ae97-461a53761207.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,74 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Text entry
+
+
+
+
+
+
+Text entry
+
+
+
+
+
+ The WRTKit has two controls for text entry needs. For situations when only a
+ single line of text is needed there's the TextField control. The TextField
+ control supports "masked text entry", meaning that any text that is entered into
+ the control is masked so it cannot be read. The mask is implemented so that
+ every typed character is shown as an asterisk (*) character.
+
+
+
+
+ When longer or multi-line text entry is needed, the TextArea control
+ can be used instead of the single-line TextField. The TextArea size
+ can be defined in number of rows when the control is created. If the
+ argument for rows is omitted a default of 3 rows will be used.
+ Longer text can still be entered - the size refers to number of rows
+ that are visible without scrolling. Note that TextArea controls do
+ not support masked text entry.
+
+
+
Figure 1.
+TextField and TextArea controls
+
+
+
+
+
+
+
+ The text in TextField and TextArea controls can be retrieved and set using
+ getter and setter methods.
+
+
+
+
+ Text entry controls fire "TextChanged" events when the user edits the text in
+ the control.
+
+
+ If you've completed the Hello World and RSS Reader tutorials and feel that you
+ understand them well but still want to learn more, then this tutorial is for you!
+ The Travel Companion widget that we will create in this tutorial is something that
+ would be very useful for anyone who travels a lot. It's a widget that offers many
+ helpful features for travellers: a world clock that allows the user to simultaneously
+ follow the time at home and at the destination, a 5-day weather forecast for the
+ destination city and the current weather for both the home and destination cities,
+ a currency converter, and a summary of the current news headlines.
+
+
+
+
+ But because this tutorial is about using the WRTKit for developing widget user interfaces
+ we will not implement all the code that is required to actually carry out all the
+ functionality that was described above. Instead we will have a Travel Companion "engine"
+ that will provide all these services for us so that we can focus on the user interface.
+ The engine that we will use (that has been created for this example) is a mock engine,
+ meaning that it mimics what the real Travel Companion engine would do, but actually it
+ just returns hard coded weather forecasts and exchange rates. That's all we need for this
+ tutorial, but after you've created the widget you can modify the engine so that it
+ actually fetches news headlines, currency exchange rates and weather forecasts from
+ various data sources online. There are plenty of free services that you can integrate to.
+ And here's the best part: because we will implement the user interface so that it's
+ cleanly separated from the engine, you won't have to change a single line of the user
+ interface code after you change the engine to use real world data!
+
+
+
+
+ Our widget will have no less than five views: one main view, three functional views and
+ a settings view. The main view exists purely for navigational purposes. Because the widget
+ is so complex we want to give the user an overview of what's available and an easy way of
+ getting to everything. The three functional views include an information view that gives
+ the user the most important information in a single glance, a currency converter view,
+ and a five day weather forecast view. And finally the settings view lets the user configure
+ the home and local cities, daylight saving time and temperature unit (Celsius or
+ Fahrenheit) to use in the weather forecast.
+
+
+
+
+ The tutorial will teach several important things. First of all, we'll learn how to
+ create widgets that have multiple views. Second, we'll learn how to separate the code
+ in the widget so that the user interface doesn't need to know anything about how the
+ business logic works, and vice versa. Third, we'll create a navigational view using
+ the NavigationButton control. Fourth, we'll customize the look of the widget to include
+ a logo for our application in the list view caption area. And finally, we'll learn how
+ to update the content in the user interface using a timer. We'll use the timer to keep
+ the world clock, weather forecast and news headlines up to date. This is very important
+ because widgets are often used so that the user starts them and then just keeps them
+ running for days on end. If we didn't refresh the user interface then the information
+ would quickly get old and the user would be forced to do manual refreshes.
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Travel_Companion_functionality-GUID-384f2430-3de9-4006-ac8e-86c5774c3a79.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Travel_Companion_functionality-GUID-384f2430-3de9-4006-ac8e-86c5774c3a79.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,854 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Functionality
+
+
+
+
+
+
+Functionality
+
+
+
+
+Weather forecast
+
+
+
+
+ Let's continue by implementing the weather forecast view. This view will
+ be entirely composed of non-foldable ContentPanel controls. We'll have one
+ panel that displays the city for which the forecast is for and one panel
+ for each day of the five-day forecast. In order to make it easy to change
+ the number of days the forecast is for we'll store references to the forecast
+ panels in an array. Thus, we need to add two global variables to the widget:
+
+
+ The next step is to create the actual view in the createWeatherView() function.
+ Of course the actual content for the content panels won't be known until at
+ runtime when we know what city the forecast is for and what the actual weather
+ forecast is. Still, we can create the actual content panels and just set their
+ content later so this is not a problem.
+
+
+
+
+// Creates the weather view.
+function createWeatherView() {
+ // empty caption text to display the caption bar - custom background using CSS
+ weatherView = new ListView(null, "");
+
+ // heading panel for city
+ weatherCityPanel = new ContentPanel();
+ weatherView.addControl(weatherCityPanel);
+
+ // create five content panels - one for each day in the 5-day forecast
+ weatherContentPanels = [];
+ for (var i = 0; i < 5; i++) {
+ var weatherContentPanel = new ContentPanel();
+ weatherView.addControl(weatherContentPanel)
+ weatherContentPanels.push(weatherContentPanel);
+ }
+}
+
+
+
+
+ When we show the weather view we have to check what the current local city
+ is and set the weatherCityPanel's content to a suitable HTML fragment that
+ will work as a heading for the weather forecast. In addition to that we'll
+ have to retrieve the weather forecast from the business logic engine and then
+ create HTML from that for each day in the forecast and set it to the five
+ content panels that we are storing references to in the weatherContentPanels
+ array. The caption for the weather forecast panels will be a string that
+ indicates the day that the forecast is for.
+
+
+
+
+ Creating the HTML fragment for the forecast heading doesn't sound so hard
+ but generating HTML for a weather forecast for five days sounds a bit tricky.
+ Let's create a separate function to do that. Remember that the weather object
+ that the engine is returning to us has two properties: temperature and type.
+ The temperature is in the preferred temperature unit and the type is one of
+ the type codes, e.g. "Sunny". We'll use it to match it up with a weather icon.
+
+
+
+
+// Returns HTML for one day of weather forecast.
+function getHTMLForWeather(weather) {
+ // build weather icon file name string
+ var weatherIcon = "Weather" + weather.type + ".png";
+
+ // build temperature string
+ var temperatureStr = weather.temperature + "°" + engine.getTemperatureUnit().toUpperCase();
+
+ // build weather HTML
+ var weatherBuf = "";
+ weatherBuf += "<table class=\"WeatherForecastDayTable\"><tr>";
+ weatherBuf += "<td class=\"WeatherForecastIconCell\">";
+ weatherBuf += "<img src=\"" + weatherIcon + "\"/>";
+ weatherBuf += "</td>";
+ weatherBuf += "<td class=\"WeatherForecastTemperatureCell\">";
+ weatherBuf += temperatureStr;
+ weatherBuf += "</td>";
+ weatherBuf += "</tr></table>";
+
+ return weatherBuf;
+}
+
+
+
+
+ The HTML that we are generating is a table with a single row with two cells.
+ The left cell has the weather icon image and the right cell has the temperature.
+ We are using three CSS style rules for the table and we naturally need to create
+ those too in the TravelCompanion.css file:
+
+
+
+
+/* Table for one day of weather forecast information */
+.WeatherForecastDayTable {
+ margin: auto;
+ border-spacing: 0px;
+}
+
+/* Table cell for weather icon */
+.WeatherForecastIconCell {
+ line-height: 1px;
+ font-size: 1px;
+ vertical-align: middle;
+}
+
+/* Table cell for temperature information */
+.WeatherForecastTemperatureCell {
+ padding: 0px 0px 0px 10px;
+ vertical-align: middle;
+}
+
+
+
+
+ Now we have a way to turn a weather forecast into HTML that we can use in a
+ ContentPanel control. We'll do that in a function we call updateWeatherForecast().
+ The caption for each weather forecast panel will indicate the day that the
+ forecast is for. The first weather object in the array that the engine returns
+ is for today and the subsequent ones are for coming days.
+
+
+
+
+// Updates the weather forecast.
+function updateWeatherForecast() {
+ // get local time and weather
+ var localTime = engine.getLocalTime();
+ var localWeather = engine.getLocalWeather();
+
+ // set the weather for each day in the forecast
+ for (var i = 0; i < 5; i++) {
+ // figure out day name
+ var day = (localTime.day + i) % 7;
+ var dayName = localTime.dayNames[day];
+
+ // set weather to content panel
+ weatherContentPanels[i].setCaption((i == 0 ? "Today, " : "") + dayName);
+ weatherContentPanels[i].setContent(getHTMLForWeather(localWeather[i]));
+ }
+}
+
+
+
+
+ We are now ready to implement the showWeatherView() function:
+
+
+
+
+// Displays the weather view.
+function showWeatherView() {
+ // set heading city panel
+ weatherCityPanel.setContent("<div class=\"WeatherCityPanel\">" + engine.getLocalCity().name + " 5-day Forecast("</div>");
+
+ // update the weather forecast before showing the view
+ updateWeatherForecast();
+
+ setSubViewSoftkeys();
+ uiManager.setView(weatherView);
+}
+
+
+
+
+ The weatherCityPanel gets a heading that matches the currently configured local city.
+ We're using another CSS rule for that so we'll have to add it to our stylesheet:
+
+
+ The weather forecast view and functionality is now ready to be tested.
+
+
+
+
+
+Currency converter
+
+
+
+
+ It's time to move on to the currency converter. This view is going to have two
+ TextField controls. One for home currency and one for local currency. In addition
+ there will be two FormButton controls to convert from the home currency to the
+ local currency, and vice versa. We'll need references to the textfields so that
+ we can retrieve their values when the form buttons are pressed:
+
+
+ Creating the view is quite straight forward:
+
+
+
+
+// Creates the converter view.
+function createConverterView() {
+ // empty caption text to display the caption bar - custom background using CSS
+ converterView = new ListView(null, "");
+
+ // home money
+ homeMoneyField = new TextField();
+ converterView.addControl(homeMoneyField);
+
+ // local money
+ localMoneyField = new TextField();
+ converterView.addControl(localMoneyField);
+
+ // home to local
+ var homeToLocalButton = new FormButton(null, "Convert Home to Local");
+ converterView.addControl(homeToLocalButton);
+
+ // local to home
+ var localToHomeButton = new FormButton(null, "Convert Local to Home");
+ converterView.addControl(localToHomeButton);
+}
+
+
+
+
+ Notice that the textfields don't have any caption or text at this point. We will
+ set that just before the view is displayed because the caption will depend on
+ what the home and local cities are configured to.
+
+
+
+
+ Also notice that we don't have any event listeners for the buttons at this point.
+ That's because we haven't actually written any functions that will implement
+ the currency conversion yet. But before we do that we'll implement the
+ function to show the view:
+
+
+ You can now test the view but it won't actually convert any currency until
+ we give our form buttons event listeners and write the code that will be
+ called when the buttons are pressed.
+
+
+
+
+ We'll implement that in two functions. One to convert from home to local and
+ another to convert in the other direction. The functions take the current
+ text value from the corresponding field and then pass it to the engine to do
+ the conversion. The result is then placed in the other of the two fields,
+ formatted so that the result has exactly two digits.
+
+
+
+
+// Called when the user clicks on the "convert home to local" button
+// in the converter view. (rounds to two decimals)
+function convertHomeToLocalMoney() {
+ var homeMoney = parseFloat(homeMoneyField.getText());
+ var localMoney = engine.convertHomeToLocalMoney(homeMoney).toFixed(2);
+ localMoneyField.setText(localMoney);
+}
+
+// Called when the user clicks on the "convert local to home" button
+// in the converter view. (rounds to two decimals)
+function convertLocalToHomeMoney() {
+ var localMoney = parseFloat(localMoneyField.getText());
+ var homeMoney = engine.convertLocalToHomeMoney(localMoney).toFixed(2);
+ homeMoneyField.setText(homeMoney);
+}
+
+
+
+
+ Now that the functions are implemented we can add the event listeners to our
+ form buttons. We'll add this code right after where the buttons are created in
+ the createConverterView() function:
+
+
+ The currency converter is now working and it's time to test it. Try it with
+ different currencies by changing the home and local cities in the settings view.
+
+
+ The information view is a summary of relevant information that the user is
+ will often need. Here we'll have a world clock that shows the home and local
+ time, the current weather at home and in the local city, as well as the
+ latest news headlines. We will use ContentPanel controls for all of these.
+ One for the home time, one for the local time, one for the home weather, one
+ for the local weather, and one for all the news headlines.
+
+
+
+
+ We'll need to access all of these content panels from outside the view creation
+ function so we'll need global variables to hold references to them:
+
+
+ We can now proceed and actually implement the creation of the information view:
+
+
+
+
+// Creates the info view.
+function createInfoView() {
+ // empty caption text to display the caption bar - custom background using CSS
+ infoView = new ListView(null, "");
+
+ // home city time
+ homeCityTimePanel = new ContentPanel();
+ infoView.addControl(homeCityTimePanel);
+
+ // local city time
+ localCityTimePanel = new ContentPanel();
+ infoView.addControl(localCityTimePanel);
+
+ // separator
+ infoView.addControl(new Separator());
+
+ // home city weather
+ homeCityWeatherPanel = new ContentPanel();
+ infoView.addControl(homeCityWeatherPanel);
+
+ // local city weather
+ localCityWeatherPanel = new ContentPanel();
+ infoView.addControl(localCityWeatherPanel);
+
+ // separator
+ infoView.addControl(new Separator());
+
+ // news headlines
+ newsHeadlinesPanel = new ContentPanel();
+ infoView.addControl(newsHeadlinesPanel);
+}
+
+
+
+
+ We already have a function that turns a weather forecast into HTML but we
+ don't have similar functions for time or for news headlines. We'll need
+ that when we want to put content into the time and headline content panels
+ so let's write those functions next.
+
+
+
+
+ For time we'll need a function that takes a DateTime object and returns
+ HTML that we can use in the content panel in the information view.
+
+
+ Next up is the function for turning the latest news headlines into HTML.
+ For each news headline we'll generate a div that contains the actual
+ news headline plus a link to the website where the full news article is.
+ Opening URLs should be done using the widget.openURL() method in the
+ S60 Web Runtime but since we don't have that functionality in a PC browser
+ we'll write a wrapper for the function just like we did for the RSS Reader:
+
+
+ The div that encloses each news headline uses a CSS rule called NewsHeadline.
+ As with all other CSS rules that we use we'll define this one too in
+ the TravelCompanion.css stylesheet file. We also need to add rules for what
+ links should look like in the context of a news headline. We define the link
+ as bold underlined blue text in its normal state and inverse with blue background
+ and white text when focused.
+
+
+
+
+/* News headline */
+.NewsHeadline {
+ padding: 0px 0px 10px 0px;
+}
+
+/* Anchor tags in the context of a news headline link */
+.NewsHeadline a {
+ text-decoration: underline;
+ font-weight: bold;
+ color: rgb(0,0,255);
+}
+
+/* Focused anchor tags */
+.NewsHeadline a:focus {
+ background: rgb(0,0,255);
+ color: rgb(255,255,255);
+}
+
+
+
+
+ Now we should have everything we need to be able to update the information
+ view content panels when the view is shown. It's time to implement the
+ showInfoView() function:
+
+
+
+
+// Displays the info view.
+function showInfoView() {
+ // set current information to controls
+ var homeCity = engine.getHomeCity();
+ var localCity = engine.getLocalCity();
+
+ // set time
+ var homeTime = engine.getHomeTime();
+ var localTime = engine.getLocalTime();
+ homeCityTimePanel.setCaption(homeCity.name + " Time");
+ homeCityTimePanel.setContent(getHTMLForTime(homeTime));
+ localCityTimePanel.setCaption(localCity.name + " Time");
+ localCityTimePanel.setContent(getHTMLForTime(localTime));
+
+ // set weather
+ var homeWeather = engine.getHomeWeather();
+ var localWeather = engine.getLocalWeather();
+ homeCityWeatherPanel.setCaption(homeCity.name + " Weather");
+ homeCityWeatherPanel.setContent(getHTMLForWeather(homeWeather[0]));
+ localCityWeatherPanel.setCaption(localCity.name + " Weather");
+ localCityWeatherPanel.setContent(getHTMLForWeather(localWeather[0]));
+
+ // set headline
+ var newsHeadlines = engine.getNewsHeadlines();
+ newsHeadlinesPanel.setCaption("News Headlines");
+ newsHeadlinesPanel.setContent(getHTMLForNewsHeadlines(newsHeadlines));
+
+ setSubViewSoftkeys();
+ uiManager.setView(infoView);
+}
+
+
+
+
+ If you try the view now, everything will seem to work fine. But there
+ is a big problem! We set the content in the content panels when the
+ view is shown but if we stay in the view for an hour the clocks will
+ still show the same time as when we showed the view. What's worse, it's
+ not just the information view that has this problem. The weather forecast
+ view is equally broken.
+
+
+
+
+
+Updating views with a timer
+
+
+
+
+ In order to keep the views up to date we'll need to start a timer that
+ periodically calls a function where we examine whether it's been long
+ enough since the last update of a view that it's time to update the
+ content in that view. Note that we only need to update a view using the
+ timer if the view is actually visible.
+
+
+
+
+ That sounds good at first but some things have to be updated more
+ frequently than others. The clocks in our information view have to not
+ only be updated once a minute but immediately when the minute changes.
+ Such accuracy is not needed for the weather forecasts or news headlines.
+ For them it's fine if they are updated once per hour. Except that weather
+ forecasts also have to be updated when the day rolls over to the next as
+ otherwise the forecast will show the wrong day. Because the home and local
+ cities can be in different timezones their days will roll over at
+ different times and thus we have to track these separately.
+
+
+
+
+ It turns out that we need no less than five variables to track this.
+ We need one to track the last minute that has been updated to the clocks,
+ one variable is needed to track when the weather was last updated, one
+ to track the day in the home city when the home city weather forecast
+ was updated, one to track the same but for the local city, and one to
+ track when the news headlines were updated. Let's declare those variables
+ and initialize them:
+
+
+
+
+// Tracks last updated minute on the clocks.
+var lastUpdatedClockMinute = -1;
+
+// Tracks last update time for weather.
+var weatherLastUpdated = -1;
+
+// Tracks the days when the weather was last updated.
+var lastUpdatedHomeWeatherDay = -1;
+var lastUpdatedLocalWeatherDay = -1;
+
+// Tracks last update time for news headlines.
+var newsHeadlinesLastUpdated = -1;
+
+
+
+
+ We'll use the time in millieconds to remember update times and compare
+ how long it's been since an update happened. Since we'll use this quite
+ a lot, let's create a small helper function for it:
+
+
+
+
+// Returns the current time in milliseconds.
+function getTimeMillis() {
+ return new Date().getTime();
+}
+
+
+
+
+ When we show a view we have to update the appropriate tracking variables
+ so the widget will properly keep track of when a view was updated. That
+ means that we have to add the following to just before we show the
+ information view in showInfoView():
+
+
+ Now our tracking variables should be updated to the right times whenever views
+ are shown but we still don't have a timer to handle the automatic updating
+ of the views.
+
+
+
+
+ We'll set this timer up so that the timer callback function is called once
+ every second so that we can make sure that the clocks don't fall behind. We'll
+ track the timer identifier in a variable:
+
+
+ We'll make the timer call a function called updateViews() that we will
+ create shortly but first let's start the timer as the last thing in the
+ init() function:
+
+
+
+
+// start timer that keeps views up to date
+timerId = setInterval(updateViews, 1000);
+
+
+
+
+ The updateViews() function needs to check what view we are currently in and do
+ the appropriate checks depending on the view. If we're in the information view
+ then we have three things to check. The first thing is to check if the minute
+ has changed on the clock. The second is to check if it's been over 60 minutes
+ since the weather was updated or if either the home or local city has rolled
+ over to the next day. And finally the third to thing to check is if it's been
+ over 60 minutes since the news headlines were updated.
+
+
+
+
+ If we are in the weather view then we check if it's been over 60 minutes since
+ the weather was updated or if the local city has rolled over to the next day.
+ Note that the weather forecast view only displays the local weather forecast
+ so we don't have to check for if the home city has rolled over to the next day.
+
+
+
+
+ The implementation of the function is therefore as follows:
+
+
+
+
+// Timer callback function that gets called once every second to keep views up to date.
+function updateViews() {
+
+ // get the current view
+ var currentView = uiManager.getView();
+
+ // get home and local time as well as time in milliseconds
+ var homeTime = engine.getHomeTime();
+ var localTime = engine.getLocalTime();
+ var now = getTimeMillis();
+
+ if (currentView == infoView) {
+ // only update the clocks if the minute has changed
+ if (homeTime.minutes != lastUpdatedClockMinute) {
+ lastUpdatedClockMinute = homeTime.minute;
+ homeCityTimePanel.setContent(getHTMLForTime(homeTime));
+ localCityTimePanel.setContent(getHTMLForTime(localTime));
+ }
+
+ // update weather if it hasn't been updated in the last hour or if the day has changed
+ if ((now > weatherLastUpdated + (1000 * 60 * 60)) ||
+ (homeTime.day != lastUpdatedHomeWeatherDay) ||
+ (localTime.day != lastUpdatedLocalWeatherDay)) {
+ weatherLastUpdated = now;
+ lastUpdatedHomeWeatherDay = homeTime.day;
+ lastUpdatedLocalWeatherDay = localTime.day;
+ var homeWeather = engine.getHomeWeather();
+ var localWeather = engine.getLocalWeather();
+ homeCityWeatherPanel.setContent(getHTMLForWeather(homeWeather[0]));
+ localCityWeatherPanel.setContent(getHTMLForWeather(localWeather[0]));
+ }
+
+ // update news headlines if they haven't been updated in the last hour
+ if (now > newsHeadlinesLastUpdated + (1000 * 60 * 60)) {
+ newsHeadlinesLastUpdated = now;
+ var newsHeadlines = engine.getNewsHeadlines();
+ newsHeadlinesPanel.setContent(getHTMLForNewsHeadlines(newsHeadlines));
+ }
+ } else if (currentView == weatherView) {
+ // update weather if it hasn't been updated in the last hour or if the day has changed
+ if ((now > weatherLastUpdated + (1000 * 60 * 60)) ||
+ (localTime.day != lastUpdatedLocalWeatherDay)) {
+ weatherLastUpdated = now;
+ lastUpdatedLocalWeatherDay = localTime.day;
+ updateWeatherForecast();
+ }
+ }
+}
+
+
+
Figure 2.
+Travel Companion information view
+
+
+
+
+
+
+
+
+What we have learned
+
+
+
+
+ The Travel Companion widget is now completed! We have learned to implement
+ complex widgets with multiple views using the WRTKit. We have also learned
+ how to keep information in views up to date using a timer. And we implemented
+ the widget without any dependencies to how the business logic engine was
+ implemented. That will come in handy if you want to continue developing this
+ widget by substituting the mock engine with one that actually uses real
+ world data. You are now ready to tackle any challenge using the WRTKit!
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Travel_Companion_planning_the_widget-GUID-891068c7-c802-4da7-8674-8e8292aef7eb.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Travel_Companion_planning_the_widget-GUID-891068c7-c802-4da7-8674-8e8292aef7eb.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,437 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Planning the widget
+
+
+
+
+
+
+Planning the widget
+
+
+
+
+Designing the user interface
+
+
+
+
+ Because the Travel Companion is such a complex widget it is important to plan
+ both the user interface and implementation carefully before starting to write
+ any code. What are the most common use cases that we want to address with this
+ widget? How will typical users be using the widget? What kind of future features
+ might there be and can we plan for those already?
+
+
+
+
+ Because the Travel Companion widget offers so much functionality and information
+ it is important to present it in such a way that it doesn't overwhelm the user.
+ To give the user a better idea of what is available and how to get to everything,
+ we'll have a main view with nothing but navigation buttons to the other views in
+ the widget. We'll implement this view using WRTKit NavigationButton controls and
+ we will give each button its own icon so that the user can quickly see what the
+ view is about.
+
+
+
+
+ After some planning and talking to potential users we have decided to create
+ a summary view that we will call "information view". This view will include the
+ most important information in a single place so that the user can view it quickly
+ without having to press any buttons to navigate around the widget. We'll put a
+ world clock here, the current weather at home and at the local destination, and
+ the latest news headlines. The information view will be entirely composed from
+ WRTKit ContentPanel controls.
+
+
+
+
+ In addition to the information view we'll have two more specialized views. We'll
+ have a currency converter with two TextField controls (one for the home currency
+ and one for the local) and two FormButton controls. One button will convert
+ from the home currency to local currency and the other button will convert in the
+ other direction. The second specialized view is a five day weather forecast. Like
+ the information view this will be using ContentPanel controls and we will share
+ the weather content used for the information view for this view.
+
+
+
+
+ Finally we'll have a settings view that is accessible from the main view just like
+ the other views in the widget. In many other widgets we might want to hide access
+ to the settings view to the Options menu but in this case one of the common use
+ cases is to configure where in the world you are so rather than hiding access to
+ the view we want to present it clearly in the main view. The settings view will
+ use SelectionMenu controls to allow users to select their home and local cities,
+ SelectionList controls with a single option that will be presented as a checkbox
+ to configure whether the cities are in daylight saving time or not, and a
+ SelectionList control that lets the user select the temperature unit to use in
+ the weather forecasts. Finally there will be two FormButton controls to let the
+ user save or cancel any settings changes.
+
+
+
+
+ When the widget starts will setup a timer that will call a timer callback function
+ once every second. In the callback function we will check what view is currently
+ active and we'll update the views (e.g. clock) so that the views stays up to date
+ even if the user doesn't do anything. After all, the most common use case is to
+ just have the information view open and not do anything other than glance at the
+ information that is displayed.
+
+
+
+
+
+Travel Companion widget files
+
+
+
+
+ All the files - HTML, CSS, JavaScript and images - have been created for you.
+ You can find the completed widget with all its files in the Examples/TravelCompanion
+ directory in the WRTKit SDK. The tutorial will assume that you will create your
+ own Travel Companion widget by following the instructions but if you prefer you can
+ just open up the ready made files and examine them as you read the tutorial. If you
+ are creating the widget from scratch by following the tutorial's instructions then
+ we suggest that you create a working directory for the new widget and copy over all
+ other ready made files except TravelCompanion.js. All of our work will be on this
+ file, but before we move on to that file we'll take a look at what other files the
+ widget is using.
+
+
+
+
+ Since we're using the WRTKit to implement our user interface we have the WRTKit
+ library with all its files in a directory called "WRTKit".
+
+
+
+
+ Like all widgets the Travel Companion has an Info.plist widget metadata file and an
+ icon in a file called Icon.png. You'll also notice that there's a bunch of png
+ image files in the widget directory. There's a file called ListViewCaptionLogo.png
+ that we will use as a custom graphical element in the view caption in all of our
+ views. Four png files have names starting with "Nav" and the rest start with
+ "Weather". The image files that have names starting with "Nav" are icons for the
+ NavigationButton controls for the main view. They are simply images that are
+ 30 by 30 pixels in size and have some graphical motif that captures what the button
+ does. Note that the size of images used for navigation buttons doesn't have to be
+ exactly 30 by 30 pixels - you can use any size you like. The images with names
+ starting with "Weather" are images used in the weather forecasts. There is one image
+ for each kind of weather that can be forecasted: rain, snow, sunshine, clouds, etc.
+
+
+
+
+ You'll find two JavaScript files: Engine.js and TravelCompanion.js. The Engine.js
+ file has the implementation of the business logic and the TravelCompanion.js file
+ implements the widget and its user interface. Finally there is the main widget HTML
+ file called TravelCompanion.html and a CSS file called TravelCompanion.css that
+ contains all the style rules used in the widget - above that what the WRTKit defines
+ by default, which is actually nearly everything!
+
+
+
+
+ Let's take a quick peek at TravelCompanion.html:
+
+
+ If you've gone through the Hello World and/or RSS Reader tutorials then this should
+ look very familiar. The file has no content, includes the WRTKit.js file from the
+ WRTKit library directory, includes the JavaScript files that we are using to implement
+ the Travel Companion widget, includes the TravelCompanion.css stylesheet file, and
+ finally calls a function called init() when the widget has loaded everything.
+
+
+
+
+
+The Travel Companion Engine
+
+
+
+
+ Following good software engineering principles, we are implementing the Travel Companion
+ widget so that the user interface is decoupled from the implementation of the actual
+ business logic that knows weather forecasts, calculates currency conversions, etc. The
+ logic is outside of the scope for this tutorial since we're interested in learning about
+ how to use the WRTKit - not how to convert euros to dollars. Because of this we will not
+ look at all at how the business logic is implemented but we will take a close look at
+ the interface between the user interface and the business logic engine. In fact, the
+ implementation of the engine for this example is a mock implementation and only mimics
+ what a real engine would do. But since this is only an example that's quite alright.
+ The engine interface, however, is identical to what it would be even if the engine would
+ have a real implementation.
+
+
+
+
+ The engine is implemented as a JavaScript class that you instantiate before using.
+ The reason for being implemented as a class is simply so that the engine can better
+ encapsulate its internal data and provide a kind of name space for its methods.
+
+
+
+
+ The core concept in the Travel Companion engine is that of cities. The engine supports
+ a list of cities and one will always be a "home city" and one a "local city". The
+ same city can be both home and local. Home refers to the city where the user lives
+ and local refers to the city where the user is currently located. The engine doesn't
+ know the daylight saving time schedules for cities so this is configured manually by
+ the user: one setting for the home city and one for the local city. The engine handles
+ all preferences but the user interface must tell it to save preferences if some
+ preference is modified. Preferences are automatically loaded when the engine is
+ created, which should happen when the widget starts so that all the settings are
+ available immediately.
+
+
+
+
+ A city in the engine is a JavaScript object. A city object has the following public
+ properties: name for the city name, currency for the three-letter currency abbreviation,
+ and timezone for the timezone code (e.g. GMT). Cities are created and managed entirely
+ by the engine.
+
+
+
+
+ Below is a complete list of the public engine APIs that are related to preferences and
+ cities:
+
+
+ Of course the engine isn't just about preferences. Its actual purpose is to perform
+ various operations related to these cities, such as converting currencies, figuring
+ out what the time is in a foreign city, etc. To simplify the usage of the engine,
+ the public methods related to these operations are defined in terms of the home and
+ local city as it is configured at the time when the method is called.
+
+
+
+
+ Here's the full list of the actual operation methods that the engine supports:
+
+
+
+
+ Currency conversions between home and local:
+
+
+ The DateTime object returned by getHomeTime() and getLocalTime() is a JavaScript
+ object that contains the following properties: year, month, date, day, hours, minutes,
+ seconds, timezone. All properties are integers except the timezone, which is a string
+ that represents the timezone code, e.g. "EET" for "Eastern European Time". Month and
+ day are zero-based to simplify their use as indexes in arrays that contains the month
+ and week day names. These arrays can be found in the DateTime object. The array for
+ week day names is called dayNames and the array for month names is called monthNames.
+ Day 0 is Sunday and month 0 is January. To find out the name of the day represented
+ by a DateTime object you would do the following:
+
+
+ The array returned by the getHomeWeather() and getLocalWeather() methods contains
+ the weather for the next five days so that the first element is the weather today,
+ the second is the weather tomorrow, etc. Each item is a JavaScript object that
+ has two properties: temperature, which is an integer in the preferred temperature
+ unit, and type, which is a string that describes the weather. The type string is
+ one of the following: "Sunny", "PartlyCloudy", "Cloudy", "Rain", "Sleet" or Snow".
+ There is a weather type image for each of these, named so that there is a "Weather"
+ prefix in front of the weather type and a ".png" suffix after it, e.g. "WeatherSunny.png".
+
+
+
+
+ Retrieving an array of the latest news headlines:
+
+
+
+
+[Array] Engine.getNewsHeadlines(void)
+
+
+
+
+ Each item in the array that the getNewsHeadlines() method returns is a JavaScript
+ object that describes one news headline. Each news headline object has two
+ properties: headline for the actual news headline text and url for the website
+ address where the full news article is located.
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Travel_Companion_user_interface-GUID-989d17cc-f019-46bb-b6f5-49166e258aca.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Travel_Companion_user_interface-GUID-989d17cc-f019-46bb-b6f5-49166e258aca.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,698 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Travel Companion user interface
+
+
+
+
+
+
+Travel Companion user interface
+
+
+
+
+Handling multiple views
+
+
+
+
+ The Travel Companion widget will follow many of the same patterns that the Hello World
+ and RSS Reader widgets have followed. The entry point to the widget is the init() function
+ that we call from the onload event handler in the main HTML file TravelCompanion.html.
+ We will implement the init() function along with the rest of the widget and user interface
+ in the TravelCompanion.js file. Let's start with the init() function so that we get the
+ widget up and running.
+
+
+
+
+ From previous widgets we already know a lot of things about the WRTKit and about what
+ we will need. For example we know that we will have a user interface manager and that
+ we'll need a reference to each of the views that our widget uses. And since we have
+ designed the Travel Companion widget we know what views we will have. Before we write the
+ init() function we can go ahead and declare the variables that we will use to refer to
+ the views and the user interface manager. And while we're at it we can also declare the
+ variable that we'll use to refer to the Travel Companion engine. All of these variables
+ are globals and thus go outside the init() function:
+
+
+
+
+// Reference to travel companion engine that implements the business logic.
+var engine;
+
+// Reference to the WRTKit user interface manager.
+var uiManager;
+
+// References to views.
+var mainView;
+var infoView;
+var converterView;
+var weatherView;
+var settingsView;
+
+
+
+
+ Previously we've written the init() function so that it creates the entire user interface
+ but because the Travel Companion widget has a much larger user interface than anything
+ we've done before, it's probably a good idea to split things up into smaller functions
+ so we don't end up with a huge init() function that will be hard to read and maintain.
+ Let's create a function for the creation of each view, and then one function that will
+ call these view creation functions and setup all other things that we need for the user
+ interface, such as the Options menu. We'll just create stub functions for now but we
+ will soon get to implement the functions:
+
+
+
+
+// Creates the user interface.
+function createUI() {
+}
+
+// Creates the main view.
+function createMainView() {
+}
+
+// Creates the info view.
+function createInfoView() {
+}
+
+// Creates the converter view.
+function createConverterView() {
+}
+
+// Creates the weather view.
+function createWeatherView() {
+}
+
+// Creates the settings view.
+function createSettingsView() {
+}
+
+
+
+
+ In the RSS Reader widget we used functions called showMainView() and showSettings() to
+ move between views. That allowed us to implement all the logic that was required when
+ moving between views in one place regardless of what action triggered the change of
+ views. We'll do the same thing in the Travel Companion widget but this time we'll need
+ five functions since we have five views. Let's create stubs for these too at this stage
+ so that the functions exist if we need to refer to them.
+
+
+
+
+// Displays the main view.
+function showMainView() {
+}
+
+// Displays the info view.
+function showInfoView() {
+}
+
+// Displays the converter view.
+function showConverterView() {
+}
+
+// Displays the weather view.
+function showWeatherView() {
+}
+
+// Displays the settings view.
+function showSettingsView() {
+}
+
+
+
+
+ Since we will create each user interface view in its own function our init() function
+ will be much simpler than in previous widgets. We will create the business logic engine,
+ create the user interface by calling createUI() and then display the main view.
+
+
+
+
+// Called from the onload event handler to initialize the widget.
+function init() {
+ // initialize the business logic engine
+ engine = new Engine();
+
+ // create the user interface
+ createUI();
+
+ // display the main view
+ showMainView();
+}
+
+
+
+
+ Let's get started with creating the user interface by returning to the createUI()
+ function. We'll want to widget to show the softkey bar and we'll want it to be in
+ tab navigation mode instead of the default pointer navigation mode. We then need
+ to create the user interface manager and the five views that this widget has. Of
+ course those five views are actually created by the five create-functions that we
+ just wrote stubs for so we just need to call those functions from createUI().
+
+
+
+
+// Creates the user interface.
+function createUI() {
+ if (window.widget) {
+ // set tab-navigation mode and show softkeys
+ widget.setNavigationEnabled(false);
+ menu.showSoftkeys();
+ }
+
+ // create UI manager
+ uiManager = new UIManager();
+
+ // create views
+ createMainView();
+ createInfoView();
+ createConverterView();
+ createWeatherView();
+ createSettingsView();
+}
+
+
+
+
+ Because we created the stub functions for moving between views, we can also create
+ the Options menu now. We'll only add one item to the menu in addition to the default
+ "Exit" menu item. The item we'll add is one that will take the user to the settings
+ view. We'll first need to create a global menu item identifier:
+
+
+
+
+// Constants for menu item identifiers.
+var MENU_ITEM_SETTINGS = 0;
+
+
+
+
+ Now that we have the menu item identifier we can actually create the menu item. Because
+ the Options menu functionality is only available in the S60 Web Runtime and not in PC
+ browsers we'll add that code in the same if-clause where we set the navigation mode and
+ show the softkey bar.
+
+
+
+
+// create menu
+var settingsMenuItem = new MenuItem("Settings", MENU_ITEM_SETTINGS);
+settingsMenuItem.onSelect = menuItemSelected;
+menu.append(settingsMenuItem);
+
+
+
+
+ When the menu item is selected it calls a function called menuItemSelected(). Let's
+ create that function and handle the case when the settings menu item is selected.
+ When it is, we want to call showSettingsView() so that the user ends up in the settings
+ view as expected:
+
+
+
+
+// Callback for when menu items are selected.
+function menuItemSelected(id) {
+ switch (id) {
+ case MENU_ITEM_SETTINGS:
+ showSettingsView();
+ break;
+ }
+}
+
+
+
+
+ The framework that we'll need when implementing the actual views is now nearly complete.
+ But before we move on let's talk about how we'll be using softkeys in the Travel
+ Companion widget.
+
+
+
+
+ In the main view we want the right softkey to be the default "Exit". But in the
+ four functional views we don't want it to exit the widget but rather to return to
+ the main view. We'll thus use "Back" as the title in the functional views, except
+ in the settings view where we'll use "Cancel".
+
+
+
+
+ Let's create three functions that will handle setting the widget right softkey to
+ these configurations. The functions will check if we're actually in the S60 Web
+ Runtime before attempting to change the right softkey in order to make the widget
+ also work in a PC browser for testing purposes.
+
+
+
+
+// Sets the softkeys for the main view.
+function setMainViewSoftkeys() {
+ if (window.widget) {
+ // set right softkey to "exit"
+ menu.setRightSoftkeyLabel("", null);
+ }
+}
+
+// Sets the softkeys for sub views.
+function setSubViewSoftkeys() {
+ if (window.widget) {
+ // set right softkey to "back" (to main view)
+ menu.setRightSoftkeyLabel("Back", showMainView);
+ }
+}
+
+// Sets the softkeys for settings view.
+function setSettingsViewSoftkeys() {
+ if (window.widget) {
+ // set right softkey to "cancel" (returns to main view)
+ menu.setRightSoftkeyLabel("Cancel", showMainView);
+ }
+}
+
+
+
+
+
+Main view
+
+
+
+
+ Let's create our main view now so that we get something visible. The main view is
+ of course created in the function createMainView() for which we already created a
+ stub function. The main view will have four WRTKit NavigationButton controls in it,
+ one for each of the views (not counting the main view itself) in the widget. Using
+ the NavigationButton control is just like using a FormButton, with the difference
+ that it looks different and can have an icon image in addition to just text. Earlier
+ when we looked at the files that were in the Examples/TravelCompanion directory we
+ noticed that there were four icons there. Now it's time to use them as icons in the
+ navigation buttons.
+
+
+
+
+ We will add event listerners to the buttons so that when they are clicked (when they
+ emit an ActionPerformed event) they will call the functions we have created for
+ moving between views. At this point the functions are just stubs, but we will of
+ course fix that later.
+
+
+
+
+ We've had captions for the views that we've created so far in the Hello World and
+ RSS Reader widgets and the Travel Companion will also have view captions. However
+ for the Travel Companion we'll use an image as our view caption. We will set the
+ view caption to an empty string because if it's undefined or null then the view
+ caption area will be hidden. Then we will create a CSS rule for the ListViewCaptionText
+ class that is used by the area where the caption text goes in a list view. Because
+ our CSS rule is defined after the default WRTKit CSS rule for ListViewCaptionText,
+ our rule will be override the default one. Let's open up TravelCompanion.css and
+ create this rule:
+
+
+
+
+/* Place logo in list view caption */
+.ListViewCaptionText {
+ background: url("ListViewCaptionLogo.png") no-repeat;
+ height: 35px;
+}
+
+
+
+
+ We specified a height in addition to the background image. The height is needed
+ so that the caption text area won't collapse to zero height since it won't contain
+ any text. We're now ready to implement the createMainView() function:
+
+
+
+
+// Creates the main view.
+function createMainView() {
+ // empty caption text to display the caption bar - custom background using CSS
+ mainView = new ListView(null, "");
+
+ // info
+ var navToInfoButton = new NavigationButton(null, "NavInfoIcon.png", "Information");
+ navToInfoButton.addEventListener("ActionPerformed", showInfoView);
+ mainView.addControl(navToInfoButton);
+
+ // converter
+ var navToConverterButton = new NavigationButton(null, "NavConverterIcon.png", "Currency Converter");
+ navToConverterButton.addEventListener("ActionPerformed", showConverterView);
+ mainView.addControl(navToConverterButton);
+
+ // weather
+ var navToWeatherButton = new NavigationButton(null, "NavWeatherIcon.png", "Weather Forecast");
+ navToWeatherButton.addEventListener("ActionPerformed", showWeatherView);
+ mainView.addControl(navToWeatherButton);
+
+ // settings
+ var navToSettingsButton = new NavigationButton(null, "NavSettingsIcon.png", "Settings");
+ navToSettingsButton.addEventListener("ActionPerformed", showSettingsView);
+ mainView.addControl(navToSettingsButton);
+}
+
+
+
+
+ We now have a main view and our widget even calls showMainView() when it starts
+ but nothing will actually show up yet because we haven't implemented the showMainView()
+ function yet. Let's do that now:
+
+
+
+
+// Displays the main view.
+function showMainView() {
+ setMainViewSoftkeys();
+ uiManager.setView(mainView);
+}
+
+
+
+
+ The function calls the setMainViewSoftkeys() function to put the right softkey
+ in the proper state and then asks the user interface manager to show the main
+ view. Remember that we're already calling the showMainView() function from the
+ init() function so we can go ahead and test this now in a PC browser, emulator
+ or handset. Notice the custom list view caption image and the navigation button
+ icons. Clicking the navigation buttons doesn't do anything yet because we don't
+ have any other views yet and the functions to show other views except the main
+ view aren't implemented. But then again, because we wrote stub functions we are
+ also not getting any error messages.
+
+
+
Figure 1.
+Travel Companion main view
+
+
+
+
+
+
+
+
+Settings view
+
+
+
+
+ It's a good idea to implement the settings view as early as possible because
+ that allows you to test the rest of the widget more easily. In order to get
+ the settings view up and running we'll need to do three things. First of all
+ we'll need to implement the createSettingsView() function so that the widget
+ actually has a settings view. Second, we'll need to implement the actions
+ that can be performed in that view. There are two actions: "Save" and "Cancel".
+ Of these, save is the tricker one and we'll implement it in a function that
+ we will call saveSettingsClicked(). The cancel action will simply take us back
+ to the main view and will be handled by the showMainView() function that we
+ have already implemented. And third, we need to implement the showSettingsView()
+ function so that clicking on the settings navigation button in the main view
+ takes us to the settings view and sets it up correctly so that the view
+ reflects the current preferences.
+
+
+
+
+ The settings view will have four sections that we will separate using a WRTKit
+ Separator control. The first section lets the user select the home city and the
+ whether the home city is in daylight saving time. Here we'll use a SelectionMenu
+ control for the city selection and a SelectionList control with a single option
+ for the daylight saving time option. We could have used a SelectionList with
+ two options "Daylight saving time" and "Normal time". Since the selection would
+ have been a single selection this would have resulted in two radio buttons. But
+ partly for the sake of usability and partly to show how to do it, we'll implement
+ it so that it's a single checkbox instead. Thus, we'll use a SelectionList with
+ a single option but we'll get the checkboxes instead of radio buttons by putting
+ the SelectionList in multiple selection mode. Because there's only one option
+ there will only be one checkbox.
+
+
+
+
+ The second section is just like the first one but for the local city. The third
+ section is for the temperature unit selection (Celsius or Fahrenheit) and we'll
+ implement it as a single selection SelectionList control. And finally the fourth
+ section is for the Save and Cancel FormButton controls.
+
+
+
+
+ The options for the selection controls will be created just before we create
+ the controls themselves. The daylight saving time and temperature unit options
+ are just static JSON defined option lists since we know what the options are.
+ But for the city selection we'll create it dynamically by asking the business
+ logic engine for a list of all the supported cities. We'll then create one option
+ for each city.
+
+
+
+
+ Because we'll need to access the controls in the settings view from outside the
+ creation function we'll need to create global references to them:
+
+
+ We can now implement the settings view creation function:
+
+
+
+
+// Creates the settings view.
+function createSettingsView() {
+ // empty caption text to display the caption bar - custom background using CSS
+ settingsView = new ListView(null, "");
+
+ // create city options from cities array
+ var cityOptions = [];
+ var cities = engine.getCities();
+ for (var i = 0; i < cities.length; i++) {
+ cityOptions.push({ value: cities[i], text: cities[i].name });
+ }
+
+ // create DST option
+ dstOptions = [ { value: true, text: "DST (+1h)" } ];
+
+ // home city
+ homeCitySelection = new SelectionMenu(null, "Home City", cityOptions);
+ settingsView.addControl(homeCitySelection);
+
+ // home city DST (using a multiple selection but only one option to get a single checkbox)
+ homeCityDSTSelection = new SelectionList(null, "Daylight Saving Time (home)", dstOptions, true);
+ settingsView.addControl(homeCityDSTSelection);
+
+ // separator
+ settingsView.addControl(new Separator());
+
+ // local city
+ localCitySelection = new SelectionMenu(null, "Local City", cityOptions);
+ settingsView.addControl(localCitySelection);
+
+ // local city DST (using a multiple selection but only one option to get a single checkbox)
+ localCityDSTSelection = new SelectionList(null, "Daylight Saving Time (local)", dstOptions, true);
+ settingsView.addControl(localCityDSTSelection);
+
+ // separator
+ settingsView.addControl(new Separator());
+
+ // temperature unit
+ var temperatureUnitOptions = [ { value: "c", text: "Celsius" }, { value: "f", text: "Fahrenheit" } ];
+ temperatureUnitSelection = new SelectionList(null, "Temperature Unit", temperatureUnitOptions);
+ settingsView.addControl(temperatureUnitSelection);
+
+ // separator
+ settingsView.addControl(new Separator());
+
+ // save button
+ var saveSettingsButton = new FormButton(null, "Save");
+ saveSettingsButton.addEventListener("ActionPerformed", saveSettingsClicked);
+ settingsView.addControl(saveSettingsButton);
+
+ // cancel button
+ var cancelSettingsButton = new FormButton(null, "Cancel");
+ cancelSettingsButton.addEventListener("ActionPerformed", showMainView);
+ settingsView.addControl(cancelSettingsButton);
+}
+
+
+
+
+ Note that we used the actual city as the value for the city options. You can
+ use anything you want for the value property for a selection control option
+ and in this case we used the actual city object because it will come in handy
+ later when we want to set the home and local cities that the user has selected
+ to the engine.
+
+
+
+
+ Our save button calls the saveSettingsClicked() function we talked about earlier
+ but we haven't created that function yet. We'll continue implementing the user
+ interface by writing this function.
+
+
+
+
+ You'll recall that the business logic engine actually stores all the preferences
+ so all we really need to do is read what values have been selected in the settings
+ view, telling these values to the engine, calling the savePreferences() method in
+ the engine to persist the settings, and then return to the main view.
+
+
+
+
+// Called when the user clicks on the "save" button in the settings view.
+function saveSettingsClicked() {
+ // update the selected home city
+ var selectedHomeCityOption = homeCitySelection.getSelected();
+ if (selectedHomeCityOption != null) {
+ engine.setHomeCity(selectedHomeCityOption.value);
+ }
+
+ // update the selected local city
+ var selectedLocalCityOption = localCitySelection.getSelected();
+ if (selectedLocalCityOption != null) {
+ engine.setLocalCity(selectedLocalCityOption.value);
+ }
+
+ // update home and local city DST
+ // there's only one checkbox but we are using a multiple-selection menu.
+ // if the selected array has one element then the checkbox is checked.
+ engine.setHomeCityDST(homeCityDSTSelection.getSelected().length == 1);
+ engine.setLocalCityDST(localCityDSTSelection.getSelected().length == 1);
+
+ // update temperature unit
+ var selectedTemperatureUnitOption = temperatureUnitSelection.getSelected();
+ if (selectedTemperatureUnitOption != null) {
+ engine.setTemperatureUnit(selectedTemperatureUnitOption.value);
+ }
+
+ // save settings
+ engine.savePreferences();
+
+ // go back to the main view
+ showMainView();
+}
+
+
+
+
+ We're writing defensive code here and making sure that the selection controls
+ actually have anything selected at all. This should never be possible with
+ single selection control if they have one option already selected, but we'll
+ use the principle of "better safe than sorry".
+
+
+
+
+ Notice that the daylight saving time selection is checked by asking for the
+ selected options array (we're using a multiple selection control) and checking
+ if there is exactly one selected option. We don't care about the actual selected
+ option because we know that there's only one. Either it's selected or it's not.
+
+
+
+
+ We have now implemented two of the three steps we said were necessary to get the
+ settings view fully functional. Let's implement the final step: showing the view.
+ Showing the settings view is done by first updating the settings view controls
+ to reflect the current configuration, setting the right softkey to the state that
+ it should be in for the settings view and then asking the user interface manager
+ to show the settings view.
+
+
+
+
+// Displays the settings view.
+function showSettingsView() {
+ // update settings view controls to match current configuration
+ // the DST selected sets are either the options array with its single option or an empty array
+
+ // home city and DST setting
+ homeCitySelection.setSelected(homeCitySelection.getOptionForValue(engine.getHomeCity()));
+ homeCityDSTSelection.setSelected(engine.getHomeCityDST() ? homeCityDSTSelection.getOptions() : []);
+
+ // local city and DST setting
+ localCitySelection.setSelected(localCitySelection.getOptionForValue(engine.getLocalCity()));
+ localCityDSTSelection.setSelected(engine.getLocalCityDST() ? localCityDSTSelection.getOptions() : []);
+
+ // temperature unit
+ temperatureUnitSelection.setSelected(temperatureUnitSelection.getOptionForValue(engine.getTemperatureUnit()));
+
+ setSettingsViewSoftkeys();
+ uiManager.setView(settingsView);
+}
+
+
+
+
+ We're using the convenient getOptionForValue() function that all selection controls
+ have to retrieve the right option to select for each of the selection controls. The
+ way we handle the daylight saving time selection controls may seem a little strange
+ at first but remember that we only have a single option and thus if that option should
+ be selected then the selected options array is identical with the options array - both
+ are arrays containing the one and same option. Selection controls always copy the options
+ and selected options arrays when the setOptions() and setSelected() methods are called
+ so there is no problem in passing the options array as the selected options array.
+
+
+
+
+ The settings view is now completed. You can try it out and play with it, change the
+ settings, open it up again, change some more settings, cancel the changes, etc. to
+ verify that it's working as it should.
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Tutorials-GUID-506c11e3-e6f3-43ec-9495-fcfa638b7e08.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Tutorials-GUID-506c11e3-e6f3-43ec-9495-fcfa638b7e08.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,104 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+WRTKit Tutorials
+
+
+
+
+
+
+WRTKit Tutorials
+
+
+
+
+
+ The WRTKit tutorials guide you through the process of using the WRTKit user
+ interface toolkit to build widgets. Even if you're familiar with widget
+ development or a veteran HTML, CSS and JavaSCript developer, these tutorials
+ will probably be useful to you as they focus on using the WRTKit to create
+ and manage the user interface.
+
+
+
+
+ There are three tutorials all in all and in each one we will take a look at one
+ of the examples that are included with the WRTKit SDK.
+
+
+
+
+ The first one is a gentle start where we will create the classic "Hello World"
+ application but using the WRTKit for the user interface. This is a good starting
+ point because it covers the basics of using the WRTKit, how to organize files,
+ how to initialize the user interface toolkit, and such topics.
+
+
+
+
+ The next tutorial is an actual useful widget: an RSS Reader. As with all WRTKit
+ tutorials we will focus on the user interface portion of this widget, but you
+ will also learn how to integrate a WRTKit -based user interface with data that
+ has been pulled in using AJAX. Feel free to use this example widget as a basis
+ for your own RSS Reader.
+
+
+
+
+ In the third tutorial we'll create create a widget called "Travel Companion"
+ in order to learn how to use the WRTKit to build complex widgets with multiple
+ views, showing complex custom content, using timers to automatically update
+ views in the background, as well as how to separate the user interface code from
+ the back-end logic code and data. Since the tutorial is about how to use the
+ WRTKit we will not actually create any real back-end logic but rather use a
+ mock back-end that will give us data that looks real but is actually hard-coded.
+
+
+
+
+ If you want you can complete the widget to make it work against actual data
+ sources on the Internet. Since the user interface is entirely separated from
+ the back-end logic you should be able to do this without touching any of the
+ user interface code!
+
+
+
+
+ When you go through the tutorials it could be a good idea to have your code
+ editor open so that you can inspect the example widget code as you read about
+ it. We will be talking a lot about the various classes and methods in the WRTKit
+ so having the
+
+WRTKit API Reference
+ open is probably also a good idea.
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_UIElement_Class-GUID-37b82f75-720c-4f54-9769-cda18453ffa3.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_UIElement_Class-GUID-37b82f75-720c-4f54-9769-cda18453ffa3.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,322 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+WRTKit UIElement Class
+
+
+
+
+
+
+WRTKit UIElement Class
+
+
+
+
+Description
+
+
+
+
+ The UIElement class is the base class for all user interface elements
+ such as views and controls. Don't instantiate UIElement directly but rather
+ use one of its subclasses.
+
+
+ Allows retrieval of the currently registered event listeners for this user interface element.
+
+
+
+
+
+Arguments
+
+
+
+
+ This method does not take any arguments.
+
+
+
+
+
+Return value
+
+
+
+
+ An array of event listeners currently registered to the user interface element.
+
+
+
+
+
+
+
+
+
+
+
+addEventListener()
+
+
+
+
+Syntax
+
+
+
+[void] UIElement.addEventListener(String eventType, Function listener)
+
+
+
+
+Description
+
+
+
+
+ Allows registration of a callback function to a user interface element in order to get
+ notifications of events in the user interface element. Event registration can be done
+ for a specific type of event or for all events.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+eventType
+
+
+
+
+
+ The name of the event type the listener should be called for or null if
+ all event types. The available event type names depend on the actual user
+ interface element class that this method is caled for.
+
+
+
+
+ The most common event type names are ActionPerformed for button control clicks,
+ SelectionChanged for selection controls, FocusStateChanged for all controls to
+ indicate that focus was gained or lost and FocusedControlChanged for views to
+ announce that a new control has been brought into (or out of) focus.
+
+
+
+
+
+
+
+
+listener
+
+
+
+
+
+ The function that should be called when the specified event type occurs.
+ The function should be defined with a single argument that will receive the
+ event object. The object has three properties: source, type and value. The
+ source property specifies the user interface element (e.g. control) from where
+ the event originated. The type property contains the event type name. The
+ contents of the value property depends between event types but contains
+ additional information about the event. For example if the value changes in
+ a selection control then the value property contains the new value.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ This method does not return a value.
+
+
+
+
+
+
+
+
+
+
+
+removeEventListener()
+
+
+
+
+Syntax
+
+
+
+[void] UIElement.removeEventListener(String eventType, Function listener)
+
+
+
+
+Description
+
+
+
+
+ Allows a specific event listener to be unregistered from a user interface control.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+eventType
+
+
+
+
+
+ The event type name of the listener that should be removed. Use the exact
+ same event type name as when adding the event listener.
+
+
+
+
+
+
+
+
+listener
+
+
+
+
+
+ The callback function of the listener that should be removed.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ This method does not return a value.
+
+
+
+
+
+
+
+
+
+
+
+id
+
+
+
+
+Syntax
+
+
+
+[String] UIElement.id
+
+
+
+
+Description
+
+
+
+
+ The id property is a unique identifier for the user interface element.
+ The identifier is used for the root HTML element in the element hierarchy
+ that defines the user interface element and is useful for example in
+ specifying specific CSS rules for a particular user interface element.
+ The identifier can also be used to recognize the source of an event in an
+ event callback by accessing the id property of the source property in the
+ event object passed to the event listener callback.
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_UIManager_Class-GUID-937146c8-3889-40f5-b9f7-0f774ac9f5fe.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_UIManager_Class-GUID-937146c8-3889-40f5-b9f7-0f774ac9f5fe.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,451 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+WRTKit UIManager Class
+
+
+
+
+
+
+WRTKit UIManager Class
+
+
+
+
+Description
+
+
+
+
+ The UIManager class manages a set of views and related user interface elements
+ such as the scrollbar that indicates the scroll position for the current view,
+ as well as notification popup dialogs.
+
+
+
+
+ A typical WRTKit user interface consists of one or more views that are commanded
+ to be displayed using the UIManager. When a view is commanded to be shown, the
+ UIManager will remove the currently displayed view (if any) and attach the
+ requested view. The UIManager creates and maintains the state of a scrollbar so
+ that it matches the scrolling position and viewport extent at any given
+ time, regardless of what goes on in the view (e.g. added or removed content),
+ screen rotations and resizes, etc.
+
+[UIManager] new UIManager(HTMLElement viewParentElement, HTMLElement scrollbarParentElement)
+
+
+
+
+Description
+
+
+
+
+ Creates a new instance of the ContentPanel class.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+viewParentElement
+
+
+
+
+
+ The HTML element to attachs views to. Normally this argument would be
+ omitted, which causes the UIManager to create its own view parent alement
+ that attaches to the document body element. You only need to supply an
+ HTML element to this argument in rare cases when it's not desirable to
+ have views take up the entire document area.
+
+
+
+
+
+
+
+
+scrollbarParentElement
+
+
+
+
+
+ The HTML element to attachs the scrollbar to. Normally this argument would be
+ omitted, which causes the UIManager to create its own scrollbar parent alement
+ that attaches to the document body element. You only need to supply an
+ HTML element to this argument in rare cases when it's not desirable to
+ have the scrollbar in its default location.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ A new instance of the UIManager class.
+
+
+
+
+
+
+
+
+
+
+
+getView()
+
+
+
+
+Syntax
+
+
+
+[String] UIManager.getView(void)
+
+
+
+
+Description
+
+
+
+
+ Retrieves the current view.
+
+
+
+
+
+Arguments
+
+
+
+
+ This method does not take any arguments.
+
+
+
+
+
+Return value
+
+
+
+
+ The current view or null if none.
+
+
+
+
+
+
+
+
+
+
+
+setView()
+
+
+
+
+Syntax
+
+
+
+[void] UIManager.setView(View view)
+
+
+
+
+Description
+
+
+
+
+ Sets the view to display. Calling this method removes the current view and
+ displays the specified one instead. If null is passed as the argument to this
+ method then the current view is removed but no new view is displayed instead.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+view
+
+
+
+
+
+ The new view to display or null to simply remove the current view.
+
+
+ Displays a notification popup dialog. If a dialog is already showing then calling this
+ method again will change the content of the already displayed notification popup.
+
+
+
+
+
+Arguments
+
+
+
+
+
+
+
+displayTime
+
+
+
+
+
+ The duration that the dialog should be displayed before automatically hiding.
+ Specified in milliseconds (i.e. 1000ms = 1s). If the notification dialog should
+ not automatically hide then a negative value can be specified.
+
+
+
+
+
+
+
+
+type
+
+
+
+
+
+ Type of notification to display. This argument affects the look of the dialog
+ and should have a value of either "info", "warning" or "wait". "Info" should be
+ used for informational popups, "warning" for errors and other warning messages
+ and "wait" for progress dialogs. If the argument is null then no type icon
+ will be shown in the dialog.
+
+
+
+
+
+
+
+
+text
+
+
+
+
+
+ The text to display in the popup dialog. If the argument is null then no text
+ will be shown, however this is not recommended as it would be unclear to the
+ user.
+
+
+
+
+
+
+
+
+progress
+
+
+
+
+
+ This argument should be omitted except when a progress dialog is desired, i.e.
+ when used with the "wait" type. The value of progress should be a floating
+ point number between 0.0 and 1.0, where 0.0 means "0% progress" and 1.0 means
+ "100% progress". A negative number means "unknown progress" and results in a
+ different progress bar style than for known progress.
+
+
+
+
+
+
+
+
+
+
+Return value
+
+
+
+
+ This method does not return a value.
+
+
+
+
+
+
+
+
+
+
+
+hideNotification()
+
+
+
+
+Syntax
+
+
+
+[void] UIManager.hideNotification()
+
+
+
+
+Description
+
+
+
+
+ Hides the currently displayed notification popup dialog, if any. If this method
+ is called when no notification dialog is displayed then the method call is simply
+ ignored but no harm is done.
+
+
+
+
+
+Arguments
+
+
+
+
+ This method does not take any arguments.
+
+
+
+
+
+Return value
+
+
+
+
+ This method does not return a value.
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Using_buttons-GUID-8b14cec9-92cc-4bde-83c2-ad0a30a84942.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Using_buttons-GUID-8b14cec9-92cc-4bde-83c2-ad0a30a84942.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,92 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Using buttons
+
+
+
+
+
+
+Using buttons
+
+
+
+
+
+ You can let users trigger actions by placing a FormButton or
+ NavigationButton control in a view. Use FormButtons for actions that
+ start some process and NavigationButton controls for situations
+ where pressing the button should take the viewer to another view.
+
+
+
Figure 1.
+FormButton controls
+
+
+
+
+
+
+
+ You can find out when a button has been pressed by registering a
+ callback function as an event listener to the button. The event type
+ for button presses is "ActionPerformed". You can use whatever name
+ you like for the callback function. The function is passed the event
+ object as an argument. A typical callback function looks like this:
+
+
+
+
+// Callback function for button presses.
+function buttonPressed(event) {
+ // implement what happens when the button is pressed here
+}
+
+
+
+
+ Creating a button, registering the event listener and adding the
+ button to a view is demonstrated below. The example creates a
+ FormButton:
+
+
+ Note that the example assumes that a view has already been created
+ and that the "exampleView" variable refers to that view. "button1"
+ is a unique identifier for the button that allows it to be identified
+ for example if several different controls are using a shared event
+ listener function. The event listener function could examine the event
+ object and check the identifier of the source control for the event.
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Using_notification_popups-GUID-39c7a69a-9334-45d1-92f6-8c239831a0a2.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Using_notification_popups-GUID-39c7a69a-9334-45d1-92f6-8c239831a0a2.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,116 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Using notification popups
+
+
+
+
+
+
+Using notification popups
+
+
+
+
+
+ Notification popup dialogs are an easy way to show information to
+ users. In the WRTKit notification popups are used using two methods
+ in the UIManager class: showNotification() and hideNotification().
+ If a notification is already showing when another is commanded to be
+ shown then the current notification is replaced with the new one.
+ Notifications can be either auto-hiding after a specified time or
+ manually hidden by calling hideNotification(). Auto-hiding is an
+ easy way in situations where a message just needs to be shown but
+ doesn't require user acknowledgement, e.g. to let the user know that
+ new content has loaded or similar.
+
+
+ The API for showNotification() takes four arguments: displayTime,
+ type, text and progress. The "displayTime" argument is an integer
+ that specifies how long the notification popup dialog should be
+ shown for before automatically hiding. The value is given in
+ milliseconds (1000ms = 1s) and negative values can be used to
+ specify that the dialog should not automatically hide. The second
+ argument "type" is used to specify a visual style for the popup.
+ There are three types of notifications: "info", "warning" and
+ "wait". Info is intended for informative messages, warning for
+ errors or other similar negative messages and finally wait is
+ intended for dialogs that are letting the user know that some
+ process (e.g. loading data from the Internet) is taking a long time.
+ The fourth argument "progress" is a decimal number that should be
+ omitted or null in all other cases except when the dialog should be
+ a progress dialog (typically notifications of type "wait"). For
+ progress dialogs the value should be between 0.0 and 1.0 to specify
+ how far along the process is (0.0 for "0% done" and 1.0 for "100%
+ done"). A negative value can be specified if the progress is
+ unknown, resulting in an animated progress bar that indicates that
+ the wait time and progress is not known.
+
+
+
+
+ The code below show various examples of how to show notification
+ popup dialogs. The examples assume that the UIManager has been
+ instantiated and that a variable called uiManager refers to that
+ instance.
+
+
+
+
+// show an info notification - auto-hide in 3 seconds
+uiManager.showNotification(3000, "info", "Informative message here");
+
+// show a warning notification - no auto-hide
+uiManager.showNotification(-1, "warning", "Warning message here");
+
+// show a progress notification - no auto-hide, 40% progress
+uiManager.showNotification(-1, "wait", "Loading...", 0.4);
+
+// show a progress notification - no auto-hide, unknown progress
+uiManager.showNotification(-1, "wait", "Loading...", -1.0);
+
+
+
+
+ The example below shows how to hide a notification. If no
+ notification is showing when the method is called then the
+ call is ignored.
+
+
+
+
+// hide the current notification (if any)
+uiManager.hideNotification();
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Using_selection_controls-GUID-5e36d276-cce8-4bc9-bcba-78e721adb8c6.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Using_selection_controls-GUID-5e36d276-cce8-4bc9-bcba-78e721adb8c6.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,211 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Using selection controls
+
+
+
+
+
+
+Using selection controls
+
+
+
+
+
+ Selection controls are used to let users make selections among a set
+ of options. The WRTKit has two controls: SelectionList and
+ SelectionMenu that have an identical API but differ in look and
+ feel. The SelectionList shows all the options and selections
+ directly in the view while the SelectionMenu only shows the selected
+ options and opens up a menu with the options when the user activates
+ the control. Selection controls can either be in single or multiple
+ selection mode. In single selection mode only one of the options can
+ be selected at a time while in multiple selection mode any number
+ (including zero) can be selected.
+
+
+
Figure 1.
+SelectionList controls
+
+
+
+
+
+
+
+ The SelectionList control is recommended to be used with the pointer
+ navigation mode or if there are few options to choose from. The
+ SelectionMenu control is recommended for large numbers of options or in
+ the tab navigation mode.
+
+
+
Figure 2.
+SelectionMenu control
+
+
+
+
+
+
+
+ The options of a selection control are defined as an array of option
+ objects, each with two properties: value and text. The value
+ property can be any JavaScript value and represent the concrete
+ value of the option, while the text property is a string that is
+ shown in the user interface for the option.
+
+
+
+
+ Option arrays can conveniently be created using JavaScript object
+ notation (JSON) for example as follows:
+
+
+ The selected options are defined differently depending on whether
+ the selection control is in single or multiple selection mode. In
+ single selection mode the selected option is defined as a reference
+ to the option in the control that should be selected. In multiple
+ selection mode the selected options set is defined as an array of
+ references to options in the control. Note that the references must
+ be to one of the options objects defined for the control. It is not
+ sufficient to define new option objects that happen to be identical
+ to the ones in the control.
+
+
+
+
+// create a set of two selected options for multiple selection control
+var selectedOptions = [ options[1], options[2] ];
+
+
+
+
+ Note that the selectedOptions array is constructed so that the two
+ elements in the array refer to the "Tea" and "Water" options in the
+ options array.
+
+
+
+
+ The code below creates a SelectionList control in multiple selection
+ mode and initializes it with the options and selectedOptions arrays
+ created above. The code assumes that a view has already been created
+ and that a variable called exampleView refers to it.
+
+
+
+
+// create selection list control
+var drinkList = new SelectionList("selection1", "Favorite drinks",
+ options, true, selectedOptions);
+exampleView.addControl(drinkList);
+
+
+
+
+ "selection1" is a unique identifier for the control, "Favorite
+ drinks" is the control caption, the option argument refers to the
+ options array that we previously created, the following argument
+ determines whether the control is in multiple selection mode, and
+ finally the selectedOptions argument refers to the array with
+ selected options and defines which of the options in the control
+ should be selected by default.
+
+
+
+
+ All of the arguments are optional and can be specified later as
+ needed. For example if the options are not known when the control
+ is created, or if the options change, they can be set using the
+ setOptions() method. In the same way the selected options can be
+ set using the setSelected() method.
+
+
+
+
+// set options
+drinkList.setOptions(options);
+
+// set selected options
+drinkList.setSelected(selectedOptions);
+
+
+
+
+ The currently selected options can be retrieved using the
+ getSelected() method. As mentioned earlier, in single selection mode
+ the selected is just a single reference to an option (or null if no
+ option is selected), while in multiple selection mode it's an array
+ with references to the selected options. If no options are selected
+ in multiple selection mode then the array is empty.
+
+
+
+
+// find out which options are currently selected
+var selected = drinkList.getSelected();
+
+
+
+
+ Selection controls fire "SelectionChanged" events when a user changes
+ the selection of options in a control. These events can be handled
+ using by registering an event listener to the control. The code below
+ shows what a typical callback function would look like:
+
+
+
+
+// Callback function for selection change events.
+function favoriteDrinkChanged(event) {
+ // implement what happens when the selection changed here
+}
+
+
+
+
+ Registering the event listener function is done as follows, for
+ example right after the control was created:
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Using_text_entry_controls-GUID-76aeb0e3-698d-41de-a34b-8fea6d8e00d2.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Using_text_entry_controls-GUID-76aeb0e3-698d-41de-a34b-8fea6d8e00d2.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,125 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Using text entry controls
+
+
+
+
+
+
+Using text entry controls
+
+
+
+
+
+ The WRTKit supports two controls for text entry: TextField for
+ a single line of text and TextArea for multiple lines of text.
+ The API for both controls is identical, except for the constructor.
+ The TextField can be created in masked mode, which is useful for
+ entry of text that should not be displayed (e.g. passwords). For
+ every character that is typed in masked mode, an asterisk is shown
+ instead in the text field. While a TextArea control can hold an
+ unlimited number of lines of text, its height (as number of rows
+ to display without scrolling) is specified when it is constructed.
+
+
+
Figure 1.
+TextField and TextArea controls
+
+
+
+
+
+
+
+ TextField and TextArea controls are created and added to views like
+ any other controls in the WRTKit. The code assumes that a view has
+ already been created and that a variable called exampleView refers
+ to it.
+
+
+
+
+// create textfield
+var nameField = new TextField("field1", "Enter your name");
+exampleView.addControl(nameField);
+
+
+
+
+ "field1" is a unique identifier for the control and "Enter your
+ name" is the control caption. An optional third argument to the
+ constructor can be used to specify the text to display in the
+ control, however the text can also be set at any time later on using
+ the setText() method as follows:
+
+
+
+
+// set the text in the textfield
+nameField.setText("John Smith");
+
+
+
+
+ The current text in a text entry control can be retrieved using the
+ getText() method:
+
+
+
+
+// get the current text from the textfield
+var text = nameField.getText();
+
+
+
+
+ Text entry controls fire "TextChanged" events when a user edits the
+ text in a control. These events can be handled using by registering
+ an event listener to the control. The code below shows what a
+ typical callback function would look like:
+
+
+
+
+// Callback function for text changed events.
+function nameChanged(event) {
+ // implement what happens when the text changed here
+}
+
+
+
+
+ Registering the event listener function is done as follows, for
+ example right after the control was created:
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_View_Class-GUID-e673fe1a-cf46-46f5-b243-ce7422c69cc5.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_View_Class-GUID-e673fe1a-cf46-46f5-b243-ce7422c69cc5.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,203 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+WRTKit View Class
+
+
+
+
+
+
+WRTKit View Class
+
+
+
+
+Description
+
+
+
+
+ The View class is an abstract base class for all views. Views are containers for controls
+ and are used to collect the set of controls that constitutes a logical view in a
+ widget user interface. The displayed view is controlled by the UIManager. Don't
+ instantiate View directly but rather one of its subclasses, e.g. ListView.
+
+
+ Retrieves the currently focused control in the view or null if none.
+
+
+
+
+
+Arguments
+
+
+
+
+ This method does not take any arguments.
+
+
+
+
+
+Return value
+
+
+
+
+ The current focused control or null if none.
+
+
+
+
+
+
+
+
+
+
+
+focusFirstControl()
+
+
+
+
+Syntax
+
+
+
+[Control] View.focusFirstControl(void)
+
+
+
+
+Description
+
+
+
+
+ Attempts to focus the first focusable control in the view. Note that
+ this method call might fail to actually focus the control in certain
+ circumstances, such as when the view is not visible or if no focusable
+ control exists.
+
+
+
+
+ This method is rarely needed because focus handling is to a high degree
+ handled automatically by the user interface toolkit. For example when
+ a new view is displayed the first focusable control is automatically
+ given focus.
+
+
+
+
+
+Arguments
+
+
+
+
+ This method does not take any arguments.
+
+
+
+
+
+Return value
+
+
+
+
+ This method does not return a value.
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Views_and_the_UIManager-GUID-f95b4ad6-0e86-4023-8371-3ff2a45e95fe.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.doc.WRTKit/html/WRTKit_Views_and_the_UIManager-GUID-f95b4ad6-0e86-4023-8371-3ff2a45e95fe.html Fri Mar 05 19:31:41 2010 -0800
@@ -0,0 +1,89 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Views and the UIManager
+
+
+
+
+
+
+Views and the UIManager
+
+
+
+
+
+ All WRTKit user interfaces are divided into "views". The concept of
+ a view is simply a set of user interface elements, such as buttons,
+ textfields, etc., that are hosted in a container. The WRTKit
+ architecture defines a contract for views through a base class
+ called View and implements a concrete view class called ListView
+ that lays out controls vertically. This layout is similar to what is
+ commonly used in mobile device user interfaces and is thus
+ sufficient for the vast majority of widget user interfaces. However
+ the WRTKit allows developers to create their own custom views if
+ some other kind of layout is preferred instead. Creating a custom
+ view is an advanced topic that isn't covered here, but roughly
+ speaking it is a simple matter of creating a subclass of the View
+ class (just like ListView) and implementing all the functions that
+ the View class defines, plus whatever custom layout the developer
+ wants.
+
+
+
+
+ Because the ListView uses a vertical list layout for controls,
+ adding controls can be done either to the end of the list or by
+ inserting before a specified control in the list. There is no need
+ to worry about actual control locations, coordinates or anything of
+ that sort. The ListViews handles all of this automatically.
+
+
+
+
+ In addition to controls, the ListView has a view caption that is
+ displayed at the very top of the view. The caption is optional but
+ is good to include in order to show what a particular view is about.
+ E.g. a view for settings could have a caption "Settings".
+
+
+
Figure 1.
+ListView with caption
+
+
+
+
+
+
+
+ Only one view can be visible at any given time, as is common in
+ mobile device applications. Views are commanded to be shown using a
+ class called UIManager, which attaches the view to the "view root".
+ The view root is an HTML element that can be specified to the
+ UIManager when it is created, but typically this argument is
+ omitted, resulting in the UIManager creating a view root element
+ that makes views take up the entire screen.
+
-
- WRTKit is a JavaScript library for widgets running in the S60 Web Runtime (WRT)
- that simplifies creation of user interfaces. User interfaces created with the
- WRTKit automatically scales to any screen resolution, handle screen rotation
- and resizes, work in both the tab and pointer navigation modes, and more.
- Typically user interfaces that use the WRTKit can be created with just a few lines
- of JavaScript code, yet still achieve a professional and consistent look and feel.
-
-
-
-
- The look of a user interface created by the WRTKit is defined entirely using
- Cascading Style Sheets (CSS) and image files. This allows easy customization of
- a widget's look without the need to touch any code.
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_ActionControl_Class-GUID-6a7cb034-d676-4119-b799-7b3e3b5948e4.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_ActionControl_Class-GUID-6a7cb034-d676-4119-b799-7b3e3b5948e4.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,86 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-WRTKit ActionControl Class
-
-
-
-
-
-
-WRTKit ActionControl Class
-
-
-
-
-Description
-
-
-
-
- The ActionControl class is an abstract base class for action controls like buttons.
- ActionControl class does not introduce any new public methods or properties over
- those inherited from its superclass. Don't instantiate ActionControl directly but
- rather one of its subclasses.
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Actions-GUID-38771443-166b-4112-9569-c07229cd7449.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Actions-GUID-38771443-166b-4112-9569-c07229cd7449.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,94 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Actions
-
-
-
-
-
-
-Actions
-
-
-
-
-
- Widgets can let users trigger actions in many ways. One way is by inserting menu
- items in the Options menu, using the menu object that the S60 Web Runtime
- defines. Another way is to use links that call JavaScript functions. Such links
- could for example be included as part of content in a ContentPanel control.
- Links belong more to web pages than widgets or applications, however, and are
- not recommended except in cases when they result in a web URL being opened up in
- a web browser (i.e. using the widget.openURL() method).
-
-
-
-
- The third way is to use one of the WRTKit action controls: FormButton and
- NavigationButton. Both controls are very similar in usage but differ greatly in
- presentation and intended use. The FormButton control is meant to be used in
- situations where pressing the button would result in some kind of process taking
- place, e.g. settings being saved. The NavigationButton control is intended for
- moving between views inside the widget, or other similar type of actions.
- FormButton controls look similar to buttons in a PC application or "Submit"-
- buttons on a web page. NavigatationButton controls don't really have a
- counterpart in the PC application domain, but is common in mobile device
- application that have large user interfaces that are split into several views.
-
-
-
Figure 1.
-NavigationButton controls
-
-
-
-
-
-
-
- In an email widget, NavigationButton controls could be used so that there would
- be a "Folders"-view where each folder (e.g. Inbox, Sent, Trash, etc.) would have
- a corresponding NavigationButton. Clicking on the button for a folder would open
- up that folder in a new view. FormButton controls could be used for example in a
- view that lets users write new emails to trigger sending of the written email. A
- FormButton in a view like that could have "Send" as the button text.
-
-
-
Figure 2.
-FormButton controls
-
-
-
-
-
-
-
- The FormButton and NavigationButton controls fire events with the event type
- "ActionPerformed" whenever a user presses the button. The event can be turned
- into a function call to a callback function of the developer's choice by
- registering the function to the control for the "ActionPerformed" event type.
- This is done using the addEventListener() method that all controls inherit from
- the UIElement base class.
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_ContentPanel_Class-GUID-bff5ac77-a652-480a-be3e-e3ca6283a45b.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_ContentPanel_Class-GUID-bff5ac77-a652-480a-be3e-e3ca6283a45b.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,548 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-WRTKit ContentPanel Class
-
-
-
-
-
-
-WRTKit ContentPanel Class
-
-
-
-
-Description
-
-
-
-
- The ContentPanel class implements a control that is used to display arbitrary
- XHTML content. The content panel can either be foldable (allows users to
- toggle it open and close) or static. Like all controls the content panel has
- an optional caption. But unlike for other controls, this caption area is an
- interactive area that can be used to expand and collapse a foldable content
- panel. Thus, foldable content panel should always have captions.
-
-
- Creates a new instance of the ContentPanel class.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-id
-
-
-
-
-
- Unique identifier for the control. Can be retrieved using the id property defined
- in the UIElement class that this control inherits from. Useful for example to
- identify the source of an event in event callback functions or to apply a CSS
- rule to only this particular control. The identifier can be null, in which case
- no id will be set for the control.
-
-
-
-
-
-
-
-
-caption
-
-
-
-
-
- The caption text for the control. A null caption can be used to hide the
- caption area. This is not recommended if the content panel is folding since
- users cannot expand or collapse a foldable content panel without the caption
- area being present.
-
-
-
-
-
-
-
-
-content
-
-
-
-
-
- The content for the panel. If the argument is omitted or null then the content
- area will be empty.
-
-
-
-
-
-
-
-
-foldable
-
-
-
-
-
- Specifies the foldability of the content panel. Specify true to make the content
- panel foldable and false to make it static. If the argument is omitted or null
- then the content panel will default to being static.
-
-
-
-
-
-
-
-
-expanded
-
-
-
-
-
- Specifies the expanded state of a foldable content panel. Specify true to make
- the content panel expanded and false to make it collapse. If the argument is
- omitted or null then the content panel will default to being expanded.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- A new instance of the ContentPanel class.
-
-
-
-
-
-Example code
-
-
-
-
- Creating a foldable content panel with content:
-
-
-
-
-var panel1 = new ContentPanel("panel1", "Example Panel", "This is some content");
-
-
-
-
- Creating a static content panel with content:
-
-
-
-
-var panel2 = new ContentPanel("panel2", "Example Panel", "This is some content", false);
-
-
-
-
- Creating a foldable content panel and given it content in a separate step:
-
-
-
-
-var panel3 = new ContentPanel("panel3", "Example Panel");
-panel3.setContent("This is some content");
-
-
-
-
-
-
-
-
-
-
-
-getContent()
-
-
-
-
-Syntax
-
-
-
-[String] ContentPanel.getContent(void)
-
-
-
-
-Description
-
-
-
-
- Retrieves the current content (an XHTML fragment) of the content panel.
-
-
-
-
-
-Arguments
-
-
-
-
- This method does not take any arguments.
-
-
-
-
-
-Return value
-
-
-
-
- The current content of the content area.
-
-
-
-
-
-
-
-
-
-
-
-setContent()
-
-
-
-
-Syntax
-
-
-
-[void] ContentPanel.setContent(String content)
-
-
-
-
-Description
-
-
-
-
- Sets the content for the content panel as a fragment of XHTML. If null is
- specified as the content then the content area will be empty.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-content
-
-
-
-
-
- A fragment of XHTML to set as content for the content area of the content panel.
- A null value can be used to make the content area empty.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- This method does not return a value.
-
-
-
-
-
-
-
-
-
-
-
-isExpanded()
-
-
-
-
-Syntax
-
-
-
-[Boolean] ContentPanel.isExpanded(void)
-
-
-
-
-Description
-
-
-
-
- Retrieves the expanded state of the content area.
-
-
-
-
-
-Arguments
-
-
-
-
- This method does not take any arguments.
-
-
-
-
-
-Return value
-
-
-
-
- The current expanded state of the content area; true if expanded, false if collapsed.
-
-
-
-
-
-
-
-
-
-
-
-setExpanded()
-
-
-
-
-Syntax
-
-
-
-[void] ContentPanel.setExpanded(Boolean state)
-
-
-
-
-Description
-
-
-
-
- Sets the expanded state of the content area for a foldable content panel.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-state
-
-
-
-
-
- The new expanded state for the content area; true to expand, false to collapse.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- This method does not return a value.
-
-
-
-
-
-
-
-
-
-
-
-contentElement
-
-
-
-
-Syntax
-
-
-
-[HTMLElement] ContentPanel.contentElement
-
-
-
-
-Description
-
-
-
-
- The contentElement property allows direct access to the content of a content
- panel. Typically content is set to a content panel using the setContent() method,
- passing it an XHTML fragment as a string but if DOM methods are preferred then the
- contentElement can be used as a root HTML element to attach content to, e.g.
- using the DOM appendChild() method.
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Control_Class-GUID-6ddb8154-3fed-40fc-b282-85e6d3ad494f.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Control_Class-GUID-6ddb8154-3fed-40fc-b282-85e6d3ad494f.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,609 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-WRTKit Control Class
-
-
-
-
-
-
-WRTKit Control Class
-
-
-
-
-Description
-
-
-
-
- The Control class is an abstract base class for user interface controls.
- Don't instantiate Control directly but rather one of its subclasses.
-
-
- Retrieves the current caption of the control.
- The value is an XHTML string.
-
-
-
-
-
-Arguments
-
-
-
-
- This method does not take any arguments.
-
-
-
-
-
-Return value
-
-
-
-
- The current caption of the control or null if the control doesn't have a caption.
-
-
-
-
-
-
-
-
-
-
-
-setCaption()
-
-
-
-
-Syntax
-
-
-
-[void] Control.setCaption(String caption)
-
-
-
-
-Description
-
-
-
-
- Sets the caption for the control. If null is specified as the caption
- then the caption is removed (entirely hidden) for the control.
- The value is an XHTML string.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-caption
-
-
-
-
-
- The new caption for the control or null for no caption.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- This method does not return a value.
-
-
-
-
-
-
-
-
-
-
-
-isEnabled()
-
-
-
-
-Syntax
-
-
-
-[Boolean] Control.isEnabled(void)
-
-
-
-
-Description
-
-
-
-
- Retrieves the enabled state of the control.
-
-
-
-
-
-Arguments
-
-
-
-
- This method does not take any arguments.
-
-
-
-
-
-Return value
-
-
-
-
- The current enabled state of the control.
-
-
-
-
-
-
-
-
-
-
-
-setEnabled()
-
-
-
-
-Syntax
-
-
-
-[void] Control.setEnabled(Boolean state)
-
-
-
-
-Description
-
-
-
-
- Sets the enabled state for the control.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-state
-
-
-
-
-
- The new enabled state for the control; true to enable, false to disable.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- This method does not return a value.
-
-
-
-
-
-
-
-
-
-
-
-isFocusable()
-
-
-
-
-Syntax
-
-
-
-[Boolean] Control.isFocusable(void)
-
-
-
-
-Description
-
-
-
-
- Retrieves the focusable state of a control. The focusable state tells
- whether the control can be focused or not. E.g. a label control cannot
- be focused because it does not have any interactive action to perform.
-
-
-
-
-
-Arguments
-
-
-
-
- This method does not take any arguments.
-
-
-
-
-
-Return value
-
-
-
-
- The focusable state of the control.
-
-
-
-
-
-
-
-
-
-
-
-isFocused()
-
-
-
-
-Syntax
-
-
-
-[Boolean] Control.isFocused(void)
-
-
-
-
-Description
-
-
-
-
- Retrieves the focused state of the control.
-
-
-
-
-
-Arguments
-
-
-
-
- This method does not take any arguments.
-
-
-
-
-
-Return value
-
-
-
-
- The current focused state of the control.
-
-
-
-
-
-
-
-
-
-
-
-setFocused()
-
-
-
-
-Syntax
-
-
-
-[void] Control.setFocused(Boolean state)
-
-
-
-
-Description
-
-
-
-
- Sets the focused state for the control. Note that it's not always possible
- to carry out the request to focus a control. E.g. a control might not be
- visible or the focus might be locked to another control.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-state
-
-
-
-
-
- The new focused state for the control; true to focus, false to blur.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- This method does not return a value.
-
-
-
-
-
-
-
-
-
-
-
-updateStyleFromState()
-
-
-
-
-Syntax
-
-
-
-[void] Control.updateStyleFromState()
-
-
-
-
-Description
-
-
-
-
- Called to let the control update its style to match its internal state.
- The method doesn't need to be called manually as the toolkit takes care of
- calling it whenever the state of a control changes. Override this method
- if you wish to implement custom styling for a control. Typically using
- CSS rules will be sufficient for customizing looks so only use this method
- when CSS is insufficient.
-
-
-
-
-
-Arguments
-
-
-
-
- This method does not take any arguments.
-
-
-
-
-
-Return value
-
-
-
-
- This method does not return a value.
-
-
-
-
-
-
-
-
-
-
-
-view
-
-
-
-
-Syntax
-
-
-
-[View] Control.view
-
-
-
-
-Description
-
-
-
-
- The view property references the view that the control is attached to.
- If the control has not been attached to any view then the property is null.
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Control_states-GUID-f98575ac-f913-466d-a790-0ff0207463a3.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Control_states-GUID-f98575ac-f913-466d-a790-0ff0207463a3.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,144 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Control states
-
-
-
-
-
-
-Control states
-
-
-
-
-
- Controls can be in a number of different states. Some of the states are specific
- to a particular type of control (e.g. whether a checkbox is checked) and some
- are common to all controls. Some states can be explicitly set while others are
- implicit based on some user action (e.g. moving the pointer over a control).
- The states can be retrieved using "getter" functions and in cases when a state
- can be explicitly set there is a "setter" function that allows the state to be
- manipulated. The following presents the common control states.
-
-
-
-Focusable
-
-
-
-
- The focusable state is a boolean (i.e. true or false) value that indicates
- whether the control can receive the focus and receive input or not. Some
- non-interactive controls like labels are never focusable, others are focusable
- unless the control has specifically been disabled, and some are always
- focusable. E.g. textfields can be focused even when disabled in order to be able
- to copy text from them to the clipboard.
-
-
-
-
-
-Focused
-
-
-
-
- The focused state is a boolean value that specifies if a control is currently
- selected for interaction. The focused typically changes implicitly through user
- actions like moving the 4-way controller, however the focus can also be
- explicitly set. Unlike other states, setting the focus to a control is more like
- a request than an absolute command because it is not always possible to actually
- set the focus to the control to which it is requested. For example if a control
- is not focusable or not visible on the screen, the focus cannot be set to it.
-
-
- Hovering means that the pointer arrow is over a control. It is always implicit
- and changes based on pointer movement. The hovering state is a boolean value.
- The hovering state is rarely needed outside a control itself, which uses it to
- determine how the control draws itself.
-
-
-
-
-
-Enabled
-
-
-
-
- Controls are always enabled by default, but can be disabled to prevent
- interaction. Disabling a control doesn't hide it but rather causes it to be
- displayed in some way (typically with dimmer or duller colors) that indicates to
- users that it cannot be used. Toggling the enabled state is always an explicit
- action. The enabled state is a boolean value. Note that toggling the enabled
- state can have an effect on other things. Focus is typically lost from controls
- that are disabled and they become non-focusable.
-
-
- Certain controls like textfields cannot be interacted with despite being
- focused. Instead the focus merely indicates that they are selected for
- interaction. In order to actually interact with them they have to be "activated"
- by pressing a selection button. The reason for this is that the same 4-way
- controller keys are used for navigating between controls and within a control.
- When a control such as a textfield is activated, all key presses are consumed by
- the control. Activation of a control is transparent to the WRTKit and due to
- this cannot be queried nor commanded. Also note that activation is not needed on
- PC computers and thus will not occur when testing a WRTKit user interface in a
- PC browser.
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Creating_a_widget_that_uses_the_WRTKit-GUID-8d71ee32-1826-4141-8fb6-76420a5472a4.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Creating_a_widget_that_uses_the_WRTKit-GUID-8d71ee32-1826-4141-8fb6-76420a5472a4.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,197 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Creating a widget that uses the WRTKit
-
-
-
-
-
-
-Creating a widget that uses the WRTKit
-
-
-
-
-
- To create a widget the uses the WRTKit for its user interface, start by copying
- the WRTKit directory from the Library directory in the WRTKit to the root
- directory of the widget you are making. The root directory of your widget is
- the directory where your Info.plist and main HTML file is located.
-
-
-
-
- The main HTML file should include a script tag that loads the file
- WRTKit/WRTKit.js in order to include and initialize the WRTKit library in your
- widget. The widget typically should have no content at all between its
- <body> and </body> tags. You also want to include the JavaScript
- script file where your own widget's code is located, and you want to define some
- entry point function that gets called when the widget is loaded, e.g. using the
- onload event that you can define for the body tag. This should result in an HTML
- file that looks something like this:
-
-
- In this example the code for your own widget is in a file called YourOwnWidgetCode.js
- and the entry point function that gets called when the widget has loaded all files is
- called init(). Next, we want to create that function.
-
-
-
-
- All widgets that use the WRTKit need to create an instance of the UIManager class, as
- well as at least one view. Creating the UIManager is a simple matter of instantiating
- the WRTKit UIManager class. You should retain the reference to that instance in a
- global variable or some other place that is accessible to the code that will need to
- use the UIManager's services. To do this, you would first declare the global variable
- to hold your UIManager instance:
-
-
-
-
-// Reference to the user interface manager.
-var uiManager;
-
-
-
-
- With the variable declared you can then add the following code to the init() function
- to create an instance of the UIManager class and retain a reference to that instance
- in the uiManager variable:
-
-
-
-
-// create the user interface manager
-uiManager = new UIManager();
-
-
-
-
- Now that we have a user interface manager instance we can create a new view and set it
- to the screen. In order to be able to access that view outside the init() function, we
- should crate a global variable for it just like we did for the UIManager instance:
-
-
-
-
-// Reference to the main view.
-var mainView;
-
-
-
-
- In this example we will create a ListView that has a unique identifier "example" and
- a view caption "Example View". The unique identifier can be used to set CSS rules that
- are targeted to a particular view. It is often not needed and can be specified as null.
- The view caption is shown at the top of list views and is helpful to show users what
- the view is for.
-
-
-
-
-// create the main view
-mainView = new ListView("example", "Example View");
-
-
-
-
- We are now ready to command the view to the screen:
-
-
-
-
-// show the mainView
-uiManager.setView(mainView);
-
-
-
-
- The example widget would now be displaying an empty list view with "Example View" in
- its view caption and would be ready for more functionality. Let's add a button to the
- view. You would normally do this before the view is shown. Our example button has a
- unique identifier "exampleButton" and text "Press me!" on the face of the button.
-
-
-
-
-// add a button to the main view
-var exampleButton = new FormButton("exampleButton", "Press me!");
-mainView.addControl(exampleButton);
-
-
-
-
- The main view now contains a button. If we wanted to be informed when the button is
- pressed we could create a new function and register it as an "event listener". First
- the callback function definition:
-
-
-
-
-// Callback function that gets called when the example button is pressed.
-function exampleButtonPressed(event) {
- // popup a notification dialog when the button is pressed
- uiManager.showNotification(3000, "info", "You pressed the button!");
-}
-
-
-
-
- Now that we have a function to call when the button is pressed we can register the
- event listener. You should write this code in the init() function, for example right
- after you created the button:
-
-
-
-
-// add an event listener
-exampleButton.addEventListener("ActionPerformed", exampleButtonPressed);
-
-
-
-
- The same idea applies even to much more complex user interfaces. You create views and
- controls, add the controls to the views, command a view to be displayed using the
- UIManager, and get notified of user actions using event listeners that you can
- register to the controls.
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Creating_the_Hello_World_widget-GUID-d638159a-d12b-476c-a74c-99055672b7be.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Creating_the_Hello_World_widget-GUID-d638159a-d12b-476c-a74c-99055672b7be.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,534 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Creating the Hello World widget
-
-
-
-
-
-
-Creating the Hello World widget
-
-
-
-
-What goes in the widget?
-
-
-
-
- One of the main reasons why Hello World is a good example to start with is
- because it is a minimal widget and shows the minimal set of steps that you
- would go through to create a widget that uses the WRTKit for its user interface.
- We will create just two files, an HTML file called HelloWorld.html and a JavaScript
- file called HelloWorld.js and both will be very short.
-
-
-
-
- Before we'll start writing code let's talk about what exactly it is that we want
- to build. A typical Hello World application simply displays the text Hello World
- with the minimal amount of code. But because using the WRTKit is so simple, we'll
- go one step further and make it a bit fancier.
-
-
-
-
- WRTKit user interfaces are composed of views and controls. A view is one logical
- group of stuff that you can see on the screen. A view can be longer than what fits
- on the screen at once in which case the user has to scroll, but it's still one view.
- For example in a web browser application you might have one view for the bookmarks,
- another for settings and a third view for viewing actual web pages. Controls are
- user interface elements like buttons, text fields, checkboxes, etc. that either
- let the user perform some kind of interactive action or simply shows some information.
- When you create a user interface with the WRTKit you create one or more controls,
- one or more views, and place the controls on the views. After this, all you have to
- do is ask one of the views to be displayed and the rest happens automatically.
-
-
-
-
- Since this is a very simple widget we will just have one view and we'll call it
- the "main view". Instead of just saying "Hello World" we will let the user input
- their name and then click a button to popup a dialog that says hello to the user
- by name. E.g. if the user enters "John" we will popup "Hello John!". But we will
- also create some error handling so that if the user doesn't input a name we will
- popup a warning dialog that says "Please enter your name!" instead.
-
-
-
-
-
-The HelloWorld.html file
-
-
-
-
- As mentioned earlier, you create user interfaces using JavaScript rather than
- HTML when you use the WRTKit. Because of this it's perhaps not so surprising
- that the HTML file is extremely short. What might come as a surprise however is
- that it's extremely short and nearly identical no matter what kind of widget
- you are building if you are using the WRTKit. In fact it typically only has
- about 10 lines of code, including the DOCTYPE declaration! Here's what it looks
- like:
-
-
- We're using XHTML 1.0 so the DOCTYPE declaration is for XHTML 1.0 Strict. And
- because this is XHTML we also have the normal XML declaration (<?xml...).
- After that the content should be familiar even if you've used previously only
- used HTML rather than XHTML. We have a normal html root level tag with a head
- and body. Note that in XHTML tags are case sensitive and should be in lowercase
- as in the example above. The xmlns attribute is a name space declaration that
- states that all the tags used here are part of the XHTML standard.
-
-
-
-
- Because we're creating a widget and not a web page we don't need to have a title. If you
- want you can define one here but you won't see it anywhere. Next comes an important
- bit:
-<script type="text/javascript" src="WRTKit/WRTKit.js"></script>.
- That piece of code instructs the Web Runtime to load a JavaScript file called WRTKit.js
- from a directory called WRTKit. The WRTKit.js file takes care of loading the WRTKit and
- including all the files that are needed by it. Those files are all inside the WRTKit
- directory and you don't need to concern yourself with them at this point. In fact
- all you need to do to use the WRTKit in a widget is to copy the WRTKit directory into
- your own widget's root directory and then include the XHTML script tag presented above
- that loads the WRTKit/WRTKit.js JavaScript file. If you are creating a widget of your own
- you can find the WRTKit directory in the Library directory in the WRTKit SDK. But for your
- convenience it has already been copied to the Hello World example.
-
-
-
-
- Notice that there's another script tag too, this one loading a file called HelloWorld.js.
- This is where we'll put all the JavaScript code that implements our Hello World widget.
- We could have just written the JavaScript code inline between a <script> and
- </script> tag in the HelloWorld.html file but the HTML file is less cluttered if
- we move all JavaScript to a separate file.
-
-
-
-
- Finally let's look at the body tag. There are two things of interest here. First of all
- there's no content between <body> and </body>. That's because all of the
- content will be created by the WRTKit using JavaScript. And that leads us to the other
- point of interest in the body: the
-onload="init()" attribute of the
- body tag. This sets up an event handler that gets called after the widget has loaded
- all of its content. The event handler calls a JavaScript function called init(). This
- is the point where we jump from the HTML to JavaScript. From this point on everything
- will be JavaScript and the place where it all starts is the init() function that gets
- called thanks to this little onload event handler for the body tag.
-
-
-
-
-
-The HelloWorld.js file
-
-
-
-
- The HTML file that we created above set things up so that there is a function call
- to a function named "init()" when the widget is done loading. No such function exists
- a this point so we have to create it. The init() function is the entry point to our
- JavaScript and this is also where we will start the implementation.
-
-
-
-
- The S60 Web Runtime supports two kinds of user interface interaction: tab and
- pointer. The WRTKit supports but methods but usually the tab interaction method
- (also known as "navigation mode") is preferred. Unfortunately the pointer based
- navigation mode is the default so we'll have to disable it and switch to the tab
- navigation mode. Also by default the softkey bar is hidden, which we don't want
- because we want to give the user a clue about how to exit the widget. The good news
- is that these two tweaks are easy to do and only requires two simple method calls.
- The bad news is that those method calls are done through objects that only exist
- in the Web Runtime but not in a PC web browser. Due to this, we'll create the
- init() function as follows:
-
-
-
-
-// Called from the onload event handler to initialize the widget.
-function init() {
- // set tab-navigation mode and show softkeys
- // (only if we are in the WRT environment)
- if (window.widget) {
- widget.setNavigationEnabled(false);
- menu.showSoftkeys();
- }
-}
-
-
-
-
- We wrapped the calls to disable the pointer navigation and show the softkeys
- in an if-clause that checks if there's such an object available as window.widget.
- This will evaluate to false on a PC web browser but true in the S60 Web Runtime.
-
-
-
-
- Now that we've tuned the Web Runtime to our liking we can create the actual
- user interface. We'll create four things: the so-called "user interface manager"
- that is in charge of managing views and other user interface resources, the main
- view for the widget, a text field where users can enter their name, and finally
- a button that they can click on to popup a notification dialog that says "Hello"
- Notice that we don't have to create the notification dialog because this is done
- for us by the user interface manager.
-
-
-
-
- Before we create those four objects we will declare four global variables so that
- we can access those objects elsewhere in the widget. So let's add the following
- to the top of the file (outside the init() function):
-
-
-
-
-// References to the WRTKit user interface manager and main view.
-var uiManager;
-var mainView;
-
-// References to controls in the main view.
-var helloButton;
-var nameField;
-
-
-
-
- Now that we have some variables that can track the objects we are about to create
- we can actually craete those objects. We'll create the objects inside the init()
- function so that the user interface gets created right after the widget has loaded.
-
-
-
-
- The first thing we create is the user interface manager. This is quite simple and
- requires only a single line of code:
-
-
-
-
-// create UI manager
-uiManager = new UIManager();
-
-
-
-
- Next we'll create the main view. The WRTKit allows all kinds of views to be created
- if one has special needs for how user interface controls should be laid out. However
- in the vast majority of cases the ListView class will be sufficient and that's what
- we'll create this time too:
-
-
-
-
-// create main view
-mainView = new ListView(null, "Hello World");
-
-
-
-
- The first argument to the ListView constructor is a unique identifier for the view.
- All user interface elements in the WRTKit can have a unique identifier. The identifier
- is helpful if you want to specifically target a view or control with some CSS style
- rule or if you want to identify the source of an event in an event listener callback,
- etc. However we don't need it here so we don't bother giving our main view a unique
- id and just pass a null identifier value instead. The second argument is a caption for
- the view. We'll just call our view "Hello World". The caption will be displayed at the
- very top of the screen when we display the main view. But before we do that, let's
- create the rest of the user interface.
-
-
-
-
- The widget should have a text field to let users enter their name and a button to
- trigger the greeting popup. Both the text field and the button are WRTKit controls
- and will be created and added to the main view that we just created. There are two
- kinds of buttons in the WRTKit though, form buttons and navigation buttons. Form
- buttons are meant to trigger actions whereas navigation buttons are meant for
- situations where clicking it would result in moving from one view to another. Clearly
- therefore, we want a form button in this case.
-
-
-
-
- Creating the textfield and form button is done as follows:
-
-
-
-
-// add a text field to the view
-nameField = new TextField(null, "Enter your name");
-mainView.addControl(nameField);
-
-// add a button to the view
-helloButton = new FormButton(null, "Say Hello!");
-mainView.addControl(helloButton);
-
-
-
-
- The first argument for both the textfield and button is the same as for the view:
- an optional unique identifier. We won't need it here either so rather than scratching
- our heads trying to come up with a unique identifier that we'll end up ignoring we'll
- just define it as null. The second argument for the textfield constructor is a caption.
- All controls except buttons have captions and this is the second argument in all
- constructors for controls with captions. The caption is displayed above the control
- and tells the user what the control does. In our case we want to have a textfield where
- the user should enter the name so we'll use "Enter your name" as the control caption.
- The second argument for the button constructor is the text for the button. The button
- text for form buttons should be a verb or other descriptive text that lets the user know
- what happens if the button is pressed. We'll put "Say Hello!" on our button.
-
-
-
-
- After we have created a control we can add it to a view. Custom views can have their
- own ways to do so but in the case of the default ListView that you'll use in most cases
- you add a control by calling the addControl() method.
-
-
-
-
- The user interface for the main view is now ready and we can show it. Showing a view
- is done by calling setView() in the user interface manager. So we'll add one more line
- of code to the end of the init() function:
-
-
-
-
-// display the main view
-uiManager.setView(mainView);
-
-
-
-
- If you zipped up the widget directory, renamed it HelloWorld.wgz and installed the
- widget on an emulator or handset, or just simply ran it in a PC web browser, you'd
- notice that the user interface seems to work. There's just one problem. Clicking on
- the button doesn't do anything! But don't worry, we're about to fix that.
-
-
-
-
-
-Handling events
-
-
-
-
- The thing that is missing is that we have no way of knowing when the button was
- pressed. And without knowing when it's pressed we can't react to the press and
- show a greeting. A user interface action such as pressing a button is called an
- "event". In the WRTKit events are reported to "listener" functions that developers
- can register to controls. The way this is done is by creating a function that you
- want to get called when an event occurrs, and then calling addEventListener() on
- the control whose events you are interested in, passing the function to that method.
- However there are many types of events and you are almost surely not interested in
- all of them. Because of this you can specify the type of event that you want to get
- notified about by giving the event type name to the addEventListener() method. The
- event types and their names are described in the
-
-WRTKit API Reference
- for each control. Note that because controls inherit from other classes they also
- inherit event types.
-
-
-
-
- The event type that we're interested in here is "ActionPerformed". That event is
- fired by form buttons whenever a user clicks on them. In order to get notified
- of this event we'll need two things: create a function that will get called when
- the event occurs and register that function as an event listener to our button.
- Let's create the function first but leave the implementation empty for now:
-
-
-
-
-// Called when the hello-button is clicked.
-function helloButtonClicked(event) {}
-
-
-
-
- Now that we have the event handler callback function we can add the event listener
- registration code. Let's put that right after where we create the button in
- the init() function:
-
-
- Now our helloButtonClicked() function will get called whenever the button is
- clicked. Notice that the function has an argument called event. This argument
- will receive an event object that describes the event that occurred. This can
- be useful if you have an event handler function that handles many different
- events. The event object contains three properties that you can examine to
- decide on what to do: a property called "source" that points back to the control
- or view from where the event was fired, a property called "type" that contains
- the event type name for this event, and a property called "value" that has
- helpful additional info that depends on the event type. You'll find more detailed
- information about this in the API Reference.
-
-
-
-
-
-Notification popup dialogs
-
-
-
-
- All that remains now is to write the code that shows the greeting popup dialog
- when the button is pressed. This code will naturally go in the helloButtonClicked()
- function.
-
-
-
-
- Using notification popup dialogs is very easy with the WRTKit. The user interface
- manager has two methods: showNotification() and hideNotification() that are used
- to show and hide notification popup dialogs. The showNotification() method takes
- four arguments: displayTime, type, text and progress. The displayTime argument is
- used to supply a time (in milliseconds) for how long the notification popup should
- be shown for. We want our greeting to be visible for 3 seconds so we'll pass 3000
- to this argument. The type argument is a string that tells the method what kind of
- popup to show, which determines the visual style of the popup. We'll be using two types:
- "info" and "warning". The "info" type for when we show the greeting and "warning" if
- the user didn't enter a name and we want to show a notification dialog that complains
- about this. The text argument is simply the text to show in the notification dialog.
- And finally the progess argument is a decimal number between 0.0 and 1.0 that is
- used in progress dialogs to display how far along a process is.
-
-
-
-
- A progress of 0.0 means "0% progress" and 1.0 means "100% progress". So for example
- if some process is 25% completed, you'd pass 0.25 to this argument. If you don't know
- how long a process will take you can pass a negative number. This will result in an
- animated progress bar that has a visual style that indicates that the progress is
- unknown. Typically you'd use the "wait" notification type is you want to show a
- progress dialog. If you don't want to show any progress information in the dialog,
- such as in our case, you can omit the progress argument or pass a null to it.
-
-
-
-
- Before we can write our code we need one more thing. We need to know what the user
- wrote in the name textfield. This value can be retrieved by calling the getText()
- method for the textfield. We're now ready to write the code for the helloButtonClicked()
- function:
-
-
-
-
-var name = nameField.getText();
-if (name.length == "") {
- uiManager.showNotification(3000, "warning", "Please enter your name!");
-} else {
- uiManager.showNotification(3000, "info", "Hello " + name + "!");
-}
-
-
-
Figure 1.
-The Hello World widget
-
-
-
-
-
-
-
-
-Wrapping up
-
-
-
-
- The Hello World widget is now done and you can zip it up, rename it to HelloWorld.wgz
- and deploy it on a handset or emulator. But before that, let's try it in a normal PC
- browser. Testing in a PC browser is useful because it allows you to use deubugging tools
- (like the Firebug JavaScript debugger for Firefox) in case something isn't working. Using
- a PC browser to test is also very fast because you don't have to install the widget to
- the emulator or handset. Just hit reload in the web browser when you make a change and
- you can see the results immediately. Of course there are features that will be missing
- in a web browser, such as that you won't have access to the Options menu or any other
- advanced widget functionality. But for the purpose of rapidly testing user interfaces
- it can be very helpful.
-
-
-
-
- There are a couple of points that are good to note now that the widget is ready.
- First of all, your widget now works with both the pointer and tab navigation modes. If
- you comment out the
-widget.setNavigationEnabled(false) call in the init()
- function you can try this out. Second, your widget works resolution independently.
- You can try this either by resizing the PC browser window or by trying the widget out
- with different resolutions in the S60 emulator. Third, the widget correctly handles
- screen rotations and other resizes, e.g. if the softkey bar is hidden / shown. Fourth,
- the widget looks can be customized without needing to touch any code - simply by changing
- the UI.css and image files that you can find in the WRTKit/Resources directory.
-
-
-
-
- But perhaps more important than any of the above is the fact that the WRTKit simplifies
- the separation of user interface code from data and logic code. That's not something
- that is apparent in a simple widget like this one, but it becomes very important as
- you create something more complex and especially if the user interface contains elements
- that are created dynamically for example based on data that has been fetched from the
- Internet using AJAX.
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Customizing_the_WRTKit_look-GUID-43369c51-23cf-41ac-a2f4-6320dc6eda9a.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Customizing_the_WRTKit_look-GUID-43369c51-23cf-41ac-a2f4-6320dc6eda9a.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,105 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Customizing the WRTKit look
-
-
-
-
-
-
-Customizing the WRTKit look
-
-
-
-
-
- All visuals in the WRTKit are defined using CSS and images that are
- located inside the WRTKit library in the Resources directory. The
- code that implements the WRTKit user interface elements does not
- actually know or care what the user interface looks like. Instead
- the code creates an HTML element hierarchy to implement each control
- and view and then sets CSS style class names to these elements.
- Whenever the state changes (e.g. the control gets focused) the class
- names are updated to reflect the new state. The CSS in the Resources
- directory defines the style rules for the class names and visuals
- are applied to the controls and views like for any other CSS styled
- HTML elements. This results in a system where only CSS and images
- need to be modified in order to implement a new look for a custom
- WRTKit user interface - but no JavaScript code.
-
-
-
-
- All CSS rules for the WRTKit are defined in a file called UI.css in
- the WRTKit library Resources directory. This file defines hundreds
- of style classes and can seem intimidating and complex, but the
- principle behind the classes is actually very simple. Each HTML
- element in each control has a common class and a set of state-
- specific classes. E.g. the text element in the NavigationButton
- control has "NavigationButtonText", "NavigationButtonTextNormal",
- "NavigationButtonTextFocus", etc. The classes are applied based on
- the current state of that element. So in our example if the button
- was focused, the text element would be assigned the CSS classes
- "NavigationButtonText" and "NavigationButtonTextFocus". Two classes
- define all of the styling for the text element portion of the
- NavigationButton control in the focused state.
-
-
-
-
- Using two classes at the same time is convenient because it allows
- common elements to be defined in the common class and only special
- adaptations of that common rule in the state-specific class. One
- pattern that is repeated throughout the WRTKit is to define a
- background image in the common class and an image position offset in
- the state-specific class. This makes switching from one state to
- another (e.g. when a checkbox is checked) very straight forward.
- Even if the graphics appear to change, no images need to be loaded
- or switched but instead just the image offset changes and the result
- is that the graphics have changed.
-
-
-
-
- Controls and views use HTML element hierarchies that are fine
- grained enough that various kinds of layout customizations can be
- applied without having CSS styles affect parts of a control that
- they were not intended to affect. The result is more CSS rules and
- more expansive element hierarchies, but also more freedom and
- flexibility.
-
-
-
-
- In most cases all that is needed to change the visuals of a WRTKit
- user interface is to modify the images in the Resource directory and
- update the color definitions for controls in the CSS file. The image
- files that supply graphics to views and controls in the Resource
- directory are named with clear names to make customization easy.
- Just make a backup copy of the default graphics and CSS styles and
- experiment! You will probably be surprised at how easy it is to make
- a custom user interface theme!
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Design_considerations-GUID-cd4c583d-e6d8-4aab-b2d8-dba09dd7a009.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Design_considerations-GUID-cd4c583d-e6d8-4aab-b2d8-dba09dd7a009.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,114 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-WRTKit design considerations
-
-
-
-
-
-
-WRTKit design considerations
-
-
-
-
-User interface design
-
-
-
-
- The WRTKit uses views and controls as the basis for all user
- interfaces, and those views and controls have a look and feel that
- is more similar to mobile device applications than to web pages,
- despite the fact that the underlying technology is HTML, CSS and
- JavaScript. The WRTKit supports both the tab and pointer based
- navigations modes but staying true with the application-like look
- and feel, it's often a good idea to use the tab navigation mode as
- that will probably be more familiar to users.
-
-
-
-
- Consistency and clarity help guiding the user through the widget
- user interface. As the saying goes, less is more. Instead of having
- a huge user interface that users must scroll through to get to what
- they want, consider dividing the user interface into multiple views
- that only contain controls and functionality that logically fits
- together. Use NavigationButton controls or the Options menu for
- navigation between the views.
-
-
-
-
- Keep in mind that the right softkey can be programmatically changed.
- You can take advantage of this, for example so that you use it to
- allow users to return back to the previous or parent view.
-
-
-
-
- Consider placing all configurable options in a view that the user
- can access from the Options menu. If there are more configurable
- options than what fits within one or two screenfuls then it's
- probably a good idea to split them into multiple views.
-
-
-
-
- Errors happen so keep those in mind when designing the widget.
- The WRTKit offers easy to use notification popup dialogs that
- can be used to show error messages in a way that will be familiar
- to the user.
-
-
-
-
-
-Security
-
-
-
-
- Most of methods in the WRTKit that accept strings as parameters
- use XHTML in their values. This allows the use of custom styles
- and other rich content in control and view captions, label
- values, content in content panels, and more. But like always
- when dealing with untrusted data from the Internet, you have to
- be careful with the data that you display in the user interface
- so that you don't end up placing malicious HTML (e.g. with
- script tags containing hostile code) into your user interface.
-
-
-
-
- Always filter the content that you fetch using AJAX to make sure
- that no HTML tags have been injected into that content. This is
- a good idea in any case even if there are no malicious intents,
- since arbitrary HTML mixed into content can easily cause your
- user interface to behave in unpredictable ways.
-
-
- The Developer's Guide is intended for developer's who wish to use
- the WRTKit to develop user interfaces in their own widgets. The
- guide is divided into three parts: an overview of what the WRTKit
- is and how it works, a more detailed description of the various
- components in the WRTKit and the components fit together, and
- finally a description of common WRTKit tasks.
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Developing_widgets_using_the_WRTKit-GUID-a321db96-0a01-4e55-b24b-96905f40cb5c.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Developing_widgets_using_the_WRTKit-GUID-a321db96-0a01-4e55-b24b-96905f40cb5c.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,72 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Developing widgets using the WRTKit
-
-
-
-
-
-
-Developing widgets using the WRTKit
-
-
-
-
-
- This section of the Developer's Guide describes the WRTKit in detail,
- presents the various components that make up the WRTKit library and
- explains hwo the components fit together.
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Displaying_content-GUID-57647864-5231-47e5-8ad5-f2adb1848760.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Displaying_content-GUID-57647864-5231-47e5-8ad5-f2adb1848760.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,85 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Displaying content
-
-
-
-
-
-
-Displaying content
-
-
-
-
-
- The WRTKit contains two controls that are intended simply for displaying content
- of some kind. The simplest of these is the Label control, which is simply
- showing a piece of text below its caption. Labels are useful in situations where
- there is some short data that needs to be shown without requiring any kind of
- interactivity. E.g. in an address book widget, each information field for a
- contact could be shown using its own label. One label for the contact's name,
- one for the phone number, etc. The control caption would indicate what the
- information is (e.g. "Name") and the label's value would indicate the actual
- piece of data (e.g. "John Smith").
-
-
-
-
- For situations where the content is more complex or longer, the WRTKit offers a
- control called ContentPanel. The ContentPanel control can be foldable or non-
- foldable. In its non-foldable mode a ContentPanel is similar to the label
- control and shows a caption and a content area. In the foldable mode the caption
- area is interactive and can be used to collapse and expand the content area.
- This helps shortening the space that the content takes up on in a view, while
- still allowing users to expand interesting content for a closer look. E.g. an
- email reader widget could use this to show each email in a folder in its own
- content panel so that the control caption is the email subject and the content
- area contains the full email.
-
-
-
Figure 1.
-Foldable content panel
-
-
-
-
-
-
-
- Foldable ContentPanel controls can be created either in expanded or collapsed
- mode and can be programmatically expanded and collapsed in addition to allowing
- users to manually expand and collapse them.
-
-
-
-
- If a non-folding ContentPanel control is used without a caption, it is for all
- practical purposes just a canvas to which any content can be inserted. The
- content in the content panel area is defined as an XHTML fragment and can be used
- to include arbitrarily complex content, e.g. content that contains images,
- JavaScript code, etc.
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Feed_updates-GUID-25cd0e54-0516-4469-965e-c5781cf44dc9.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Feed_updates-GUID-25cd0e54-0516-4469-965e-c5781cf44dc9.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,633 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Feed updates
-
-
-
-
-
-
-Feed updates
-
-
-
-
-Fetching news items
-
-
-
-
- Before we can show any news items we have to fetch them. So let's take
- a break in implementing the user interface and write the code that fetches
- the news items. The majority of that code is in the FeedUpdateBroker.js file
- in a JavaScript class called FeedUpdateBroker. We'll only be using one single
- method from that class: fetchFeed(). But how do we hook that up to our widget?
-
-
-
-
- The actual call to fetchFeed() will be done from the timer function updateFeedTimerFunc()
- that runs once a second. There we'll need an if-clause that checks if it's time
- to update the feeds, if another update is already going on, if we have a valid URL
- that we can fetch and if we're in the main view. If all of these tests tell us
- that it's time to update the feed, we'll check if the feed update was manually
- commanded or automatically triggered because it was time to update the feed in
- the background. If this is a manual update then we'll popup a progress notification
- dialog. Next we'll create a new instance of the FeedUpdateBroker class and call
- the fetchFeed() method to start the AJAX-based RSS feed update. We need to pass
- two arguments to this method: the feed URL that we have in the feedURL variable
- and a callback function that should be called when the update is completed.
-
-
-
-
- We don't have that function yet so that's the first thing we need to implement.
- We'll leave it empty for now but return to it in a bit:
-
-
-
-
-// Callback function that gets called when a feed update has completed.
-function feedUpdateCompleted(event) {
-}
-
-
-
-
- After we call the fetchFeed() function we'll schedule the next feed update. In
- theory we shouldn't do this until the feed update completes since there is a risk
- that we do two updates at the same time. But because we're adding a check to
- only do feed updates if another update isn't on-going this risk isn't actually
- real. Now that we have a plan for how to update the feed, let's write the code.
- First we need to declare a variable for the feed update broker instance that
- we'll create:
-
-
- Then the actual implementation for the updateFeedTimerFunc() timer function:
-
-
-
-
-// Timer function for feed updates - called once every second.
-function updateFeedTimerFunc() {
- var now = new Date().getTime();
-
- // check if a feed update has been scheduled, if it's time to update now,
- // and if there's no update currently in progress and if we're in the main view
- if ((feedURL != null) &&
- (feedUpdateTime != -1) &&
- (now > feedUpdateTime) &&
- (feedUpdateBroker == null) &&
- (uiManager.getView() == mainView)) {
- // show progress dialog if this is a commanded feed update
- if (feedUpdateCommanded) {
- // no auto hiding, wait-type notification, unknown progress
- uiManager.showNotification(-1, "wait", "Loading feed...", -1);
- }
-
- // fetch the feed from the specified URL
- feedUpdateBroker = new FeedUpdateBroker();
- feedUpdateBroker.fetchFeed(feedURL, feedUpdateCompleted);
-
- if (feedUpdateFrequency != -1) {
- // schedule next update
- feedUpdateTime = now + feedUpdateFrequency;
- } else {
- // feed update frequency is "never"
- feedUpdateTime = -1;
- }
- }
-}
-
-
-
-
- The progress dialog is created so that it has a display time of -1 so that
- it doesn't automatically hide but rather has to be commanded to go away. The
- notification dialog type is "wait" and we'll give a progress of -1 since we
- don't know how far along in the feed updating process we are. A negative
- progress value like -1 means "unknown progress" and will result in an animated
- progress indicator that shows that something is going on but the exact time
- that it will take is unknown.
-
-
-
-
- Our feed updating should now be working and whenever a feed update is completed
- there should be a call to the empty feedUpdateCompleted() function. Let's
- continue the implementation there.
-
-
-
-
- When the feedUpdateCompleted() function is called it receives an event object
- from the FeedUpdateBroker. This object contains a status that is either "ok"
- or "error", a "lastModifiedTime" string that contains the time when the RSS
- feed was last modified to help us decide if there are any new news items to
- display, as well as an array of news item objects in a property called "items".
- If the status is "error" then we'll show an error notification dialog. Keep in
- mind that there might or might not be a progress dialog already showing at this
- time. Either way we can just call the showNotification() function in the user
- interface manager because if another dialog is already visible then it will simply
- replace it with the one that we asked it to show. If the status is "ok" then we'll
- call hideNotification() in the user interface manager. This will hide the progress
- dialog if it's showing and if the dialog wasn't showing then the call will just
- be ignored.
-
-
-
-
- We'll then need to compare the lastModifiedTime against the last news feed that
- we have. That means we'll need to track the lastModifiedTime of whatever news
- feed that we are showing, and that means we need a new global variable:
-
-
-
-
-// Time when the feed was last modified.
-var feedLastModified = null;
-
-
-
-
- If the lastModifiedTime is different from the one that we are storing in the
- feedLastModified variable then we know that there's new news items to show.
- If this is the case then we'll update the feedLastModified time and set the news
- items to the main view. We could do something fancy and only update the news items
- that have been modified but to keep the tutorial simple we'll just simply remove
- all the current items and replace them with the new items and then focus the first
- of the items. But before we move on to that we'll write as much as we can of the
- feedUpdateCompleted() function:
-
-
-
-
-// Callback function that gets called when a feed update has completed.
-function feedUpdateCompleted(event) {
- if (event.status == "ok") {
- // if there aren't any feed items yet, we'll hide the progress dialog
- if (feedUpdateCommanded) {
- uiManager.hideNotification();
- }
-
- // check if the feed has updated
- if (event.lastModified != feedLastModified) {
- // remember the last modified timestamp
- feedLastModified = event.lastModified;
-
- // update news item controls here
- }
- } else {
- // show error message
- uiManager.showNotification(3000, "warning", "Error while updating feed!<br/>(check network settings)");
- }
-
- // null the broker reference to indicate that there's no current
- // update in progress
- feedUpdateBroker = null;
-
- // reset commanded feed update flag
- feedUpdateCommanded = false;
-}
-
-
-
-
- We wrote a comment "update news item controls here" at the spot where we will
- actually create and add news feed items to the main view. We'll replace that in
- a bit with the actual code to do the job, but first we need to write some code
- that we'll need to do that.
-
-
-
-
-
-Showing news items
-
-
-
-
- The news feed items will be shown using ContentPanel controls. We'll need a way
- to keep track of the ones we're showing so that we can easily remove them when
- there is new news items to show. Let's create an array to track them:
-
-
-
-
-// Reference to current feed items controls.
-var feedItemControls = [];
-
-
-
-
- Now we can implement a function that will remove all controls that are tracked
- by this array from the main view. We'll use this as the first step when we want
- to display news items.
-
-
-
-
-// Removes feed items.
-function removeFeedItems() {
- // remove all current feed items from the main view
- for (var i = 0; i < feedItemControls.length; i++) {
- mainView.removeControl(feedItemControls[i]);
- }
-
- // reset feed item control array
- feedItemControls = [];
-}
-
-
-
-
- The function simply loops through the array and calls the removeControl() method
- in the main view to remove each of the feed item controls from the view, one at a time.
- Finally we'll reset the feedItemControls array so that it reflects the fact that
- there are no more controls in the main view.
-
-
-
-
- What about adding news items? We'll do that in a function that we'll call from the
- feedUpdateCompleted() function. Let's call the function setFeedItems(). The function
- will start by calling the removeFeedItems() function we just created to empty the
- main view from news items before we start adding new ones to it. After this we'll
- loop through the news feed items that were handed to us from the FeedUpdateBroker.
- For each one we need a ContentPanel control. We'll be recycling the controls instead
- of constantly creating new ones over and over again as new news items come in. To
- this end we'll need a way to track ContentPanel controls that we have already
- created. We'll do this by creating an array called feedItemControlPool, which will
- be a global variable:
-
-
-
-
-// Feed item control pool.
-var feedItemControlPool = [];
-
-
-
-
- If we have enough controls in the pool we'll just take them from there. Otherwise
- we'll create a new ContentPanel and add it to the pool. Either way we'll end up with
- a ContentPanel control that is ready to be used. We'll need to reset its state since we
- recycled it, so we make sure it's collapsed rather than expanded, we'll set its caption
- to the title of the news item and we'll generate some HTML from the news item summary
- that we'll set as the content for the ContentPanel. And then finally we'll add the
- ContentPanel to the main view.
-
-
-
-
- Lets create the code but skip the HTML for the news item summary for now:
-
-
-
-
-// Sets feed items.
-function setFeedItems(items) {
- // start by removing all current feed items
- removeFeedItems();
-
- // create new feed items and add them to the main view
- // use feed item pool to recycle controls
- for (var i = 0; i < items.length; i++) {
- // get a feed item control from the pool or create one and
- // place it in the pool if there aren't enough feed item controls
- var feedItemControl;
- if (i == feedItemControlPool.length) {
- feedItemControl = new ContentPanel(null, null, null, true);
- feedItemControlPool.push(feedItemControl);
- } else {
- feedItemControl = feedItemControlPool[i];
- }
-
- // initialize feed item control
- var item = items[i];
- feedItemControl.setCaption(item.title);
- feedItemControl.setContent("placeholder");
- feedItemControl.setExpanded(false);
-
- // add the feed item control to the main view
- feedItemControls.push(feedItemControl);
- mainView.addControl(feedItemControl);
- }
-}
-
-
-
-
- The items argument contains the array of news items that we received in the event
- object argument to the feedUpdateCompleted() callback function. The items are in
- the "items" property of the event object. Note how the feedItemControl is either
- created or taken from the feedItemControlPool. If it's created it is given four
- arguments: a null unique identifier because we don't need one, a null caption and
- a null content because we will set both every time before we show it, and finally
- a value of true to the "foldable" argument in the ContentPanel constructor. This
- flag determines whether the ContentPanel can be folded (expanded and collapsed) or
- not. We want a foldable one so we pass true to this argument.
-
-
-
-
- Once we have the ContentPanel (either from the pool or newly created) we set its
- state: caption, content and expanded state. Note that for now we'll just set a
- placeholder string as the content. Also note that we set the expanded state to false
- to collapse the news items by default. Finally we add the content panels to the main
- view and to the feedItemControls array that tracks all the ContentPanels that we use
- for the news items.
-
-
-
-
- Now that we have written the code to create and add news items to the main view
- we have to hook that up to the feedUpdateCompleted() function. Remember we added
- a comment in the spot where we should return to do this? Let's replace that comment
- with the following:
-
-
-
-
-// set feed items to the main view
-setFeedItems(event.items);
-
-// focus the first feed item control
-// (but only if we are in the main view)
-if (uiManager.getView() == mainView && feedItemControls.length > 0) {
- feedItemControls[0].setFocused(true);
-}
-
-
-
-
- We just call the setFeedItems() function we just wrote, passing it the feed items
- that the FeedUpdateBroker fetched and parsed for us, and then if we're in the main
- view we'll focus the first of the news feed item controls.
-
-
-
-
- Now that we have all the code needed to fetch and update news feed items we'll go
- back and add some more functionality to a function we wrote a little bit earlier:
- the saveSettingsClicked() function.
-
-
-
-
- The functionality that we're adding will handle updates of the feed items in the
- main view after the user has modified the settings. We didn't write this earlier
- because we didn't have all the necessary support code in place but we can add it now.
- First we add some code to the end of the saveSettingsClicked() function to force an
- update of the news items after the users saves the settings:
-
-
-
-
-// update the feed
-feedLastModified = null;
-updateFeed();
-
-
-
-
- We update the feed by setting the feedLastModified variable to null to force an update
- and then calling updateFeed(). This causes an immediate feed update and we also get the
- progress notification dialog, which is what we want because this was a manual
- update that was caused by the user clicking "save".
-
-
-
-
- Let's also add some code that checks if a new feed was selected and removes all the
- news items from the main view if the user selected a new feed. To do this we'll first
- copy the old feedURL to a variable that we'll call oldFeedURL at the very beginning
- of the function:
-
-
-
-
-// remember the old feed URL
-var oldFeedURL = feedURL;
-
-
-
-
- Then we'll add the following just before we show the main view:
-
-
-
-
-// remove all feed items if the user selected a new feed
-if (feedURL != oldFeedURL) {
- removeFeedItems();
-}
-
-
-
-
- We can now test this in a PC browser, handset or emulator. Everything should work
- except that there's still nothing but a placeholder for the actual content in each
- ContentPanel. You can still expand and collapse the ContentPanels and the settings
- and automatic and manual updates are working. We're almost done but we still need
- to implement the code that will actually show news item summaries in the content
- panels.
-
-
-
-
- Remember we said that we would implement news items so that there's a link from
- each news item to the website where the full article is. When you open links
- to external websites in the S60 Web Runtime you should use the widget.openURL()
- function. But PC browsers don't have that function so we'll need to create a wrapper
- function that either calls widget.openURL() if we're in the Web Runtime or just
- opens a new window if we're in a PC browser.
-
-
- Content in a ContentPanel control is a fragment of HTML. In other words it's a
- piece of HTML that will be inserted into the control using code. That means that
- in order to display the news item we will have to generate some HTML for it.
- We need a function that will take a news item object and return some HTML that
- we can give to thet setContent() method in the ContentPanel control. Let's write
- that function:
-
-
- The function uses the properties in the news item object that the FeedUpdateBroker
- created for us. There's a date property that has the publish date of the news item.
- There's a description that contains the actual summary, and there's a URL that points
- to the website where the full article is. Note that we're using the openURL() wrapper
- function that we just wrote for the link to the full article.
-
-
-
-
- Our HTML is very simple: three div-tags that have the date, description and a link as
- their content. And ech of them has a CSS class so that we can match them with some
- style rules. Since we have three different pieces of data we need three CSS rules:
- FeedItemDate for the date, FeedItemDescription for the news item summary and finally
- FeedItemLink for the link to the website. Let's create these in the RSSReader.css
- stylesheet file:
-
-
-
-
-
-/* Feed item date */
-.FeedItemDate {
- font-style: italic;
-}
-
-/* Feed item text */
-.FeedItemDescription {
- padding: 4px 0px;
-}
-
-/* Feed item links */
-.FeedItemLink {
-
-}
-
-/* Anchor tags in the context of a feed item link */
-.FeedItemLink a {
- text-decoration: underline;
- font-weight: bold;
- color: rgb(0,0,255);
-}
-
-/* Focused anchor tags */
-.FeedItemLink a:focus {
- background: rgb(0,0,255);
- color: rgb(255,255,255);
-}
-
-
-
-
- The rule for links can be left empty because we will just use default ContentPanel
- content styling. However we'll change the way the link looks in the context of that
- FeedItemLink div. We'll make links blue, bold and underlined in their normal state
- and inverse with a blue background and white text color when focused.
-
-
-
-
- Now that we have a function that generates HTML for the ContentPanel we can remove
- the placeholder content replace it with a call to our function:
-
-
- We're done! Now you can try the widget in a PC browser and then on the handset
- or emulator.
-
-
-
Figure 1.
-RSS Reader main view
-
-
-
-
-
-
-
-
-What we have learned
-
-
-
-
- The RSS Reader tutorial has taught us several things. We have learned to create a widget
- that has more than just one view. We have learned how to use several new WRTKit controls.
- We used the SelectionList, SelectionMenu and FormButton controls in our settings view,
- and in the main view we used the ContentPanel control that allowed us to add our own
- content as a seamless part of the rest of the user interface using HTML fragments that
- we styled with CSS rules. We have learned to modify a view while the widget runs by adding
- and removing controls. And we have learned how to separate our widget code so that the
- user interface code doesn't contain any logic code and so that the logic code doesn't
- contain any user interface code.
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_FormButton_Class-GUID-9f99492d-b232-4a78-baed-bd284839b367.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_FormButton_Class-GUID-9f99492d-b232-4a78-baed-bd284839b367.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,278 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-WRTKit FormButton Class
-
-
-
-
-
-
-WRTKit FormButton Class
-
-
-
-
-Description
-
-
-
-
- The FormButton class implements a control that is intended for use in form-style
- user interfaces. A form button is typically used to let users trigger actions.
-
-[FormButton] new FormButton(String id, String text)
-
-
-
-
-Description
-
-
-
-
- Creates a new instance of the FormButton class.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-id
-
-
-
-
-
- Unique identifier for the control. Can be retrieved using the id property defined
- in the UIElement class that this control inherits from. Useful for example to
- identify the source of an event in event callback functions or to apply a CSS
- rule to only this particular control. The identifier can be null, in which case
- no id will be set for the control.
-
-
-
-
-
-
-
-
-text
-
-
-
-
-
- Text that is displayed on the face of the button. Typically this should be
- a verb that indicates what happens when the button is pressed.
- The value is an XHTML string.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- A new instance of the FormButton class.
-
-
-
-
-
-
-
-
-
-
-
-getText()
-
-
-
-
-Syntax
-
-
-
-[String] FormButton.getText(void)
-
-
-
-
-Description
-
-
-
-
- Retrieves the current text of the button.
- The value is an XHTML string.
-
-
-
-
-
-Arguments
-
-
-
-
- This method does not take any arguments.
-
-
-
-
-
-Return value
-
-
-
-
- The current text of the button.
-
-
-
-
-
-
-
-
-
-
-
-setText()
-
-
-
-
-Syntax
-
-
-
-[void] FormButton.setText(String text)
-
-
-
-
-Description
-
-
-
-
- Sets the text of the button. The text is displayed on the face
- of the button and indicates what happens when the button is pressed.
- The value is an XHTML string.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-text
-
-
-
-
-
- The text to be displayed on the face of the button. Passing null
- results in no text.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- This method does not return a value.
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Handling_events-GUID-a1a86c8a-6e66-4dc8-8967-b5c9c7bc6563.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Handling_events-GUID-a1a86c8a-6e66-4dc8-8967-b5c9c7bc6563.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,123 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Handling events
-
-
-
-
-
-
-Handling events
-
-
-
-
-
- Event handling in the WRTKit is based on the "observer pattern",
- meaning that events are reported from the event source to observers
- that are said to be "listening" to event notifications. An event
- listener is simply a JavaScript function that takes a single
- argument: the event message. In fact even that single argument is
- optional and if the function is not interested in the event message
- then it can simply ignore it.
-
-
-
-
- All views and controls inherit from a common base class called
- "UIElement" that defines the mechanics for event observation and
- notification. From the point of view of event listeners, the most
- important methods are addEventListener() and removeEventListener().
- These two methods are used to register and unregister listener
- functions from a view or control.
-
-
-
-
- There are different types of events though, and event listeners are
- typically not interested in receiving notifications of all events.
- For example an event listener that wants to know when a button has
- been pressed doesn't usually care if the pointer is currently
- hovering above the button or not. Filtering of event notifications
- works based on event type names. E.g. in this case the event
- listener would have been added so that it should be called only for
- events of the "ActionPerformed" type. The event type is given to the
- addEventListener() function when a listener is registered. If a
- listener function really wants to be notified of all event types
- then null can be specified as the event type. Note that the event
- type must also be specified when an event listener is unregistered.
-
-
-
-
- The code below shows a typical event listener function:
-
-
-
-
-// Callback for event notifications.
-function handleEvent(event) {
- // handle event here
-}
-
-
-
-
- The event message is passed to the first argument (called event in
- this case) of the event handler function. The event message is a
- JavaScript object with three properties: type, source and value. The
- type property specifies the event type name and is useful if a
- listener function is listening to several types of events. The
- source argument is a reference to the source view or control that
- sent out the event notification. If a listener function is listening
- to events from many different controls then this is useful to figure
- out in which of the controls the event occurred. Here the unique
- identifier of views and controls can come in handy to identify the
- source without needing to retain references to all the source
- controls. Finally the value property is a event-type specific
- property that contains some information about the event. For example
- if the event type is "TextChanged" from a text entry control then
- the value would be the new text value that the user has typed into
- the control.
-
-
-
-
- The code below demonstrates how to add and remove an event listener
- to/from a control. The example assumes that the control has already
- been created and that the ctrl variable refers to it.
-
-
-
-
-// add listener to ctrl
-// function to add is handleEvent() for event type "ActionPerformed"
-ctrl.addEventListener("ActionPerformed", handleEvent);
-
-// remove listener from ctrl
-// function to remove is handleEvent() for event type "ActionPerformed"
-ctrl.removeEventListener("ActionPerformed", handleEvent);
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Hello_World_Tutorial-GUID-67e0a561-48ac-4938-8f1b-852422b71380.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Hello_World_Tutorial-GUID-67e0a561-48ac-4938-8f1b-852422b71380.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,114 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hello World
-
-
-
-
-
-
-Hello World
-
-
-
-
-
- Whenever you are learning a new programming language or API, the first example
- you will find is usually called "Hello World" and the WRTKit is no exception.
- Like most "Hello World" applications this one will be very simple and short, but
- before we start we'll take a look at what we will need to build the example.
-
-
-
-
- The WRTKit already contains all the files that will be created in this tutorial.
- If you go to the "Examples" directory in the WRTKit SDK you will find a directory
- called "HelloWorld". This directory contains all the files necessary for the widget
- and all you have to do to try it out on a handset or S60 emulator is to zip up the
- directory, rename the file to "HelloWorld.wgz" and follow the usual steps to install
- a widget on the handset or emulator.
-
-
-
-
- The WRTKit Hello World widget is very similar to any other S60 Web Runtime widget.
- You have an Info.plist file that defines the metadata for the widget, such as its
- name, version and main HTML file and you have the icon of the widget in a file called
- Icon.png. The main HTML file for the Hello World widget is called "HelloWorld.html".
- But it's here that things start to get a little bit different because we're using
- the WRTKit to create our user interface.
-
-
-
-
- If we didn't use the WRTKit then the HelloWorld.html file would probably contain
- the text "Hello World" between the <body> and </body> tags, and that
- would be it. But when you use the WRTKit you create your user interface using
- JavaScript rather than HTML. This might sound scary and difficult at first but it
- actually saves you a lot of typing and gives you a lot of things for free that
- you would otherwise have to take care of yourself. Our Hello World widget will be
- quite a bit fancier than one created with just HTML and it will still be very
- short and simple.
-
-
-
-
- The directory also contains a HelloWorld.js file and a WRTKit directory but we
- will not talk about those quite yet.
-
-
-
-
- Even though we have already created all the files for you, you might want to
- type in the code yourself. Either way you will need a text editor. Any text editor
- will do really but it will make your life considerably easier if you have one that
- is specialized for programming and offers syntax highlighting for HTML, CSS
- and JavaScript.
-
-
-
-
- Finally, you will need a handset or emulator that includes the S60 Web Runtime.
- You can actually work with the WRTKit even without the S60 Web Runtime because
- the WRTKit works in a normal standards-compliant web browser such as Firefox.
- But since a PC computer and web browser is quite different from a mobile device
- it is still recommended that you test your widget on actual devices in order
- to get a feel for what the widget will actually look and feel like. For quick
- tests in a PC web browser though, all you have to do is open up the main HTML file
- in the browser and things should work without any changes to the code.
-
-
-
-
- No other tools or libraries are needed and you're now set to start working on
- the Hello World widget.
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_High_level_view_of_the_WRTKit-GUID-a3abe57e-9a71-4f94-923a-b84ccd1b0905.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_High_level_view_of_the_WRTKit-GUID-a3abe57e-9a71-4f94-923a-b84ccd1b0905.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,115 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-High level view of the WRTKit
-
-
-
-
-
-
-High level view of the WRTKit
-
-
-
-
-
- User interfaces in the WRTKit are based on the concepts of "views" and "controls".
- A control is a user interface element that the user can view or interact with,
- e.g. buttons, checkboxes, textfields, etc. Views are containers for controls and
- deal with the layout of controls on the screen in such a way that the user can
- interact with them in an easy way. Views are conceptually similar to windows in
- PC applications, but on a mobile device views typically fill the entire screen
- and only one view can thus be visible at any given time. The WRTKit allows views
- and controls to be interacted with in both the tab and pointer navigation modes
- and the navigation mode can even be switched at runtime.
-
-
-
Figure 1.
-WRTKit-based widget user interface
-
-
-
-
-
-
-
- The WRTKit is an object oriented user interface toolkit, which means that views
- and controls are implemented as JavaScript classes that are instantiated to
- objects when they are needed. In order to create a view with two buttons, for
- example, a developer writes JavaScript code that instantiates one view
- object and two button objects, and then calls a method in the view object asking
- it to add the buttons to itself. Being object oriented, the created WRTKit
- objects fully maintain their own state and take care of drawing themselves
- properly on the screen in all situations. So for example if one of the buttons
- is focused, the button modifies its own looks so that it appears focused
- on the screen. Because the objects know their own state, they can be queried for
- properties as needed. E.g. a textfield can be asked what text it currently
- contains, a button can be asked if it is enabled, and so on.
-
-
-
-
- Controls in the WRTKit have captions that can be used to show what the control
- does. E.g. a textfield that is meant to be used to enter a password could have a
- caption "Password". Captions are optional but should be used unless there is a
- very good reason not to. The only controls that do not have captions are
- buttons, since they have a text on the face of the button that accomplishes the
- same thing.
-
-
-
-
- WRTKit user interfaces are managed by a class that is aptly named "UIManager".
- Every widget that uses the WRTKit for its user interface creates a single
- instance of this class and then uses that UIManager instance to command views to
- be displayed. The UIManager takes care of all the heavy lifting that is necessary
- to bring a new view to the screen. The UIManager also handles other user
- interface duties such as management of notification popup dialogs and view
- scrollbars.
-
-
-
-
- Controls and views can notify the outside world when some event occurrs, e.g.
- when a button is pressed or someone toggles a checkbox. The WRTKit follows the
- so called "observer pattern" in its implementation of event notifications. This
- simply means that a control or view can be asked to call a particular JavaScript
- function (which is the "observer" or "listener") when an specific type of event
- occurrs. The WRTKit allows a control or view to have any number of concurrently
- registered listeners and listeners can either ask to be notified of only a
- particular type of event or about all events.
-
-
-
-
- The WRTKit library is physically a set of JavaScript, CSS and image files that
- are located within a directory called "WRTKit". That directory is copied into
- the root directory of widgets that wish to use the library. A widget only needs
- to include a single JavaScript file ("WRTKit/WRTKit.js") from the directory in
- order to include and initialize the full WRTKit for use in the widget. Once the
- WRTKit has been added to the widget and initialized, the widget can start using
- the JavaScript classes that the library defines.
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Introduction_to_the_WRTKit-GUID-dcf05457-f800-4f05-b284-a4e24ab8be79.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Introduction_to_the_WRTKit-GUID-dcf05457-f800-4f05-b284-a4e24ab8be79.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,111 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Introduction to the WRTKit
-
-
-
-
-
-
-Introduction to the WRTKit
-
-
-
-
-
- The S60 Web Runtime allows developers to use familiar web technologies like
- HTML, CSS and JavaScript to create applications called "widgets" very easily.
- But because widgets are based on web technologies they look and behave more like
- web pages than S60 applications by default, which is not always desirable.
-
-
-
-
- Web pages use a document metaphor where content can be laid out arbitrarily.
- Interaction with the web page is based on using a mouse or other similar device
- to place a pointer arrow on elements on the web page and activating them by
- pressing a button. When the pointer is over some user interface element it is
- said to be "hovering". The element that the pointer is hovering over is often
- displayed in a distinct style to show that it could be activated if the mouse
- button was pressed.
-
-
-
-
- Mobile device applications, on the other hand, have limitations that make this
- methapor less than ideal. The screen is small so discipline is needed to lay out
- user interface elements in a way that is easy to understand for the user. The
- physical controls on a mobile device are also not very suitable for moving
- around a pointer arrow on the screen. Instead of having a pointer to select
- elements the concept of "focus" is used. One of the elements on the screen is
- considered selected and this selection can be moved between the user interface
- elements using a 4-way controller. The element that is selected is said to be
- "focused". Like for hovering, the focused element is displayed with a distinct
- style to set it apart from other elements. This interaction method is called
- "tab navigation" due to the fact that the tab key was originally used to move
- the focus on PC computers.
-
-
-
-
- The S60 Web Runtime supports both the pointer-based and tab-based interaction
- modes so that you can choose the one that fits your widget best. But while
- simple user interfaces are easy to implement in both modes, more sophisticated
- application-like user interfaces can be quite tricky. Hover and focus must be
- handled correctly and the hover and focus states must be displayed consistently
- throughout the user interface. Different screen sizes as well as screen resizes
- and rotations must be taken into account. User interface controls like buttons,
- checkboxes and scrollbars must be able to take on a look that fits the overall
- visual theme of the widget, for example that of a commercial brand.
-
-
-
-
- The WRTKit is a complete library of JavaScript code, CSS style rules and
- graphical elements that are required to implement the kind of sophisticated,
- customizable, application-like user interfaces that are described above. It
- gives widget developers an easy way to create high quality user interfaces
- without having to worry about the problems that would otherwise plague their
- widgets.
-
-
-
-
- When the WRTKit is used in a widget, complex and fully featured user interfaces
- can be created with just a few lines of JavaScript code. The WRTKit takes care
- of generating all the HTML and CSS automatically behind the scenes. What's more,
- the visual look of the user interfaces created by the WRTKit is controlled
- entirely using CSS, allowing complete customization without touching any code.
- WRTKit user interfaces also work in standards-compliant PC web browsers,
- enabling rapid development and debugging using familiar web development tools.
-
-
-
Figure 1.
-WRTKit-based widget user interface
-
-
-
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Label_Class-GUID-64730e7f-835f-443a-9322-6753fa72fd09.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Label_Class-GUID-64730e7f-835f-443a-9322-6753fa72fd09.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,295 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-WRTKit Label Class
-
-
-
-
-
-
-WRTKit Label Class
-
-
-
-
-Description
-
-
-
-
- The Label class implements a control that displays a simple piece of text. A label
- is used in situations where there's a caption-value pair that needs to be displayed,
- e.g. "Name: John Smith".
-
-[Label] new Label(String id, String caption, String text)
-
-
-
-
-Description
-
-
-
-
- Creates a new instance of the Label class.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-id
-
-
-
-
-
- Unique identifier for the control. Can be retrieved using the id property defined
- in the UIElement class that this control inherits from. Useful for example to
- identify the source of an event in event callback functions or to apply a CSS
- rule to only this particular control. The identifier can be null, in which case
- no id will be set for the control.
-
-
-
-
-
-
-
-
-caption
-
-
-
-
-
- The caption text for the control. A null caption can be used to hide the
- caption area. This is not recommended for a label since without a caption
- the value of the label doesn't make sense to the user.
- The value is an XHTML string.
-
-
-
-
-
-
-
-
-text
-
-
-
-
-
- The content for the label. If the argument is omitted or null then the content
- area will be empty. The value is an XHTML string.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- A new instance of the Label class.
-
-
-
-
-
-
-
-
-
-
-
-getText()
-
-
-
-
-Syntax
-
-
-
-[String] Label.getText(void)
-
-
-
-
-Description
-
-
-
-
- Retrieves the current text value of the label.
- The value is an XHTML string.
-
-
-
-
-
-Arguments
-
-
-
-
- This method does not take any arguments.
-
-
-
-
-
-Return value
-
-
-
-
- The current text value of the label.
-
-
-
-
-
-
-
-
-
-
-
-setText()
-
-
-
-
-Syntax
-
-
-
-[void] Label.setText(String text)
-
-
-
-
-Description
-
-
-
-
- Sets the text value of the label.
- The value is an XHTML string.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-text
-
-
-
-
-
- The text to be displayed as the value of the label. Passing null
- results in no text.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- This method does not return a value.
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_ListView_Class-GUID-a7f24a67-d46c-4156-8276-a97b945235d6.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_ListView_Class-GUID-a7f24a67-d46c-4156-8276-a97b945235d6.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,555 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-WRTKit ListView Class
-
-
-
-
-
-
-WRTKit ListView Class
-
-
-
-
-Description
-
-
-
-
- The ListView is a view that arranges controls in a vertical stack similar to
- native S60 user interfaces.
-
-[ListView] new ListView(String id, String caption)
-
-
-
-
-Description
-
-
-
-
- Creates a new instance of the ListView class.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-id
-
-
-
-
-
- Unique identifier for the view. Can be retrieved using the id property defined
- in the UIElement class that this control inherits from. Useful for example to
- identify the source of an event in event callback functions or to apply a CSS
- rule to only this particular view. The identifier can be null, in which case
- no id will be set for the view.
-
-
-
-
-
-
-
-
-caption
-
-
-
-
-
- The caption text for the view. A null caption can be used to hide the
- caption area. Pass an empty string to this argument in order to show the
- caption area but without text. This can be used if a custom image should
- be shown instead of text for the view caption. The image can then be
- defined using CSS by providing a background for the .ListViewCaptionText
- CSS rule. By specifying the rule only for the id that was specified with
- the id argument a custom background can be given to a particular view.
- The value is an XHTML string.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- A new instance of the ListView class.
-
-
-
-
-
-
-
-
-
-
-
-getCaption()
-
-
-
-
-Syntax
-
-
-
-[String] ListView.getCaption(void)
-
-
-
-
-Description
-
-
-
-
- Retrieves the current caption of the view.
- The value is an XHTML string.
-
-
-
-
-
-Arguments
-
-
-
-
- This method does not take any arguments.
-
-
-
-
-
-Return value
-
-
-
-
- The current caption of the view or null if the view doesn't have a caption.
-
-
-
-
-
-
-
-
-
-
-
-setCaption()
-
-
-
-
-Syntax
-
-
-
-[void] ListView.setCaption(String caption)
-
-
-
-
-Description
-
-
-
-
- Sets the caption for the view. A null caption can be used to hide the caption area.
- The value is an XHTML string.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-caption
-
-
-
-
-
- The new caption for the view or null for no caption.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- This method does not return a value.
-
-
-
-
-
-
-
-
-
-
-
-getControls()
-
-
-
-
-Syntax
-
-
-
-[Array] ListView.getControls(void)
-
-
-
-
-Description
-
-
-
-
- Retrieves the controls of this view.
-
-
-
-
-
-Arguments
-
-
-
-
- This method does not take any arguments.
-
-
-
-
-
-Return value
-
-
-
-
- An array with the controls of this view or an empty array if the view
- doesn't have any controls.
-
-
-
-
-
-
-
-
-
-
-
-addControl()
-
-
-
-
-Syntax
-
-
-
-[void] ListView.addControl(Control control)
-
-
-
-
-Description
-
-
-
-
- Adds a control to the view. The control is added last, below the currently
- last control.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-control
-
-
-
-
-
- The control to add to the view.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- This method does not return a value.
-
-
-
-
-
-
-
-
-
-
-
-insertControl()
-
-
-
-
-Syntax
-
-
-
-[void] ListView.insertControl(Control control, Control beforeControl)
-
-
-
-
-Description
-
-
-
-
- Inserts a control to the view. The control is added before the control that is
- specified using the beforeControl argument.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-control
-
-
-
-
-
- The control to add to the view.
-
-
-
-
-
-
-
-
-beforeControl
-
-
-
-
-
- The control that should be immediately after the added control after
- the new control is added to the view. If the argument is null or otherwise
- invalid (e.g. not a control in this view) then the new control is added last.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- This method does not return a value.
-
-
-
-
-
-
-
-
-
-
-
-removeControl()
-
-
-
-
-Syntax
-
-
-
-[void] ListView.removeControl(Control control)
-
-
-
-
-Description
-
-
-
-
- Removes a control from the view.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-control
-
-
-
-
-
- The control to remove from the view.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- This method does not return a value.
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_NavigationButton_Class-GUID-3c5aaba9-899d-463a-8337-b6f7c09e190b.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_NavigationButton_Class-GUID-3c5aaba9-899d-463a-8337-b6f7c09e190b.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,418 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-WRTKit NavigationButton Class
-
-
-
-
-
-
-WRTKit NavigationButton Class
-
-
-
-
-Description
-
-
-
-
- The NavigationButton class implements a control that is intended for use in navigation
- menu -style user interfaces. A navigation button is typically used to let users move
- between views.
-
-[NavigationButton] new NavigationButton(String id, String image, String text)
-
-
-
-
-Description
-
-
-
-
- Creates a new instance of the NavigationButton class.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-id
-
-
-
-
-
- Unique identifier for the control. Can be retrieved using the id property defined
- in the UIElement class that this control inherits from. Useful for example to
- identify the source of an event in event callback functions or to apply a CSS
- rule to only this particular control. The identifier can be null, in which case
- no id will be set for the control.
-
-
-
-
-
-
-
-
-image
-
-
-
-
-
- Icon image that is displayed on the face of the button. No size is enforced but
- the image should be about 30x30 pixels. PNG images with transparency are
- recommended. If null is passed for the image then no image will be displayed.
-
-
-
-
-
-
-
-
-text
-
-
-
-
-
- Text that is displayed on the face of the button. Typically this should be
- the view that the widget navigates to when the button is pressed.
- The value is an XHTML string.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- A new instance of the NavigationButton class.
-
-
-
-
-
-
-
-
-
-
-
-getText()
-
-
-
-
-Syntax
-
-
-
-[String] NavigationButton.getText(void)
-
-
-
-
-Description
-
-
-
-
- Retrieves the current text of the button.
- The value is an XHTML string.
-
-
-
-
-
-Arguments
-
-
-
-
- This method does not take any arguments.
-
-
-
-
-
-Return value
-
-
-
-
- The current text of the button.
-
-
-
-
-
-
-
-
-
-
-
-setText()
-
-
-
-
-Syntax
-
-
-
-[void] NavigationButton.setText(String text)
-
-
-
-
-Description
-
-
-
-
- Sets the text of the button. The text is displayed on the face
- of the button and typically should indicate where the widget navigates
- when the button is pressed.
- The value is an XHTML string.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-text
-
-
-
-
-
- The text to be displayed on the face of the button. Passing null
- results in no text.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- This method does not return a value.
-
-
-
-
-
-
-
-
-
-
-
-getImage()
-
-
-
-
-Syntax
-
-
-
-[String] NavigationButton.getImage(void)
-
-
-
-
-Description
-
-
-
-
- Retrieves the icon image URL of the button.
-
-
-
-
-
-Arguments
-
-
-
-
- This method does not take any arguments.
-
-
-
-
-
-Return value
-
-
-
-
- The icon image URL of the button or null if none.
-
-
-
-
-
-
-
-
-
-
-
-setImage()
-
-
-
-
-Syntax
-
-
-
-[void] NavigationButton.setImage(String image)
-
-
-
-
-Description
-
-
-
-
- Sets the icon image URL for the button. Passing null to this method
- hides the icon image.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-image
-
-
-
-
-
- The URL of the icon image to display on the button or null for no image.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- This method does not return a value.
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Notification_popups-GUID-8696212c-4114-412a-9990-ef9755fc1942.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Notification_popups-GUID-8696212c-4114-412a-9990-ef9755fc1942.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,59 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Notification popups
-
-
-
-
-
-
-Notification popups
-
-
-
-
-
- In addition to managing views, the UIManager also handles notification popup
- dialogs. Notification popups are used for showing brief messages to the user to
- indicate activities and events, such as warnings, information messages or the
- progress of some process. Using notification popups is extremely simple and only
- requires two methods. Popups can be shown using one method and hidden with
- another. Popups can also be set to auto-hide after a specified amount of time.
-
-
-
-
- There are three different types of notification popups: "info", "warning" and
- "wait". The type affects only the appearance of the popup. The "wait" type is
- intended for use with progress indication.
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Overview_of_the_WRTKit-GUID-14c414f6-a220-40b6-8614-df13141495ab.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Overview_of_the_WRTKit-GUID-14c414f6-a220-40b6-8614-df13141495ab.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,54 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Overview of the WRTKit
-
-
-
-
-
-
-Overview of the WRTKit
-
-
-
-
-
- This section of the Developer's Guide gives an overview of what the
- WRTKit is and how it's used, explains the core terminology and
- outlines some design considerations for widgets that use the WRTKit.
-
-
- The RSS Reader example is the first complete, working widget that actually
- does something useful that you will create using the WRTKit. It is quite a bit
- more complex than the Hello World example, but then again it also contains
- a lot more functionality.
-
-
-
-
- For the Hello World widget we covered a lot of very fine details but for the
- RSS Reader it is assumed that the reader already knows the basics of how to
- create a widget, deploy it, test it, and so on. If you skipped the Hello World
- tutorial and feel that you're not comfortable with the basics of creating
- widgets yet then it's recommended that you go back and read the Hello World
- widget tutorial first and then come back and continue with the RSS Reader.
-
-
-
-
- The RSS Reader that we're going to build in this tutorial will have two views:
- a main view that displays news items from an RSS feed and a settings view where
- the user can configure what news feed should be displayed in the main view and
- how often it should be updated from the Internet. We will let users choose from
- a list of feeds that we will pre-configure. In principle you can use whatever
- RSS feeds you want in your own widget but it's probably best to test first with
- the ones we have in our example since they have been tested and known to work.
-
-
-
-
- The actual news feed items will be displayed as a list of foldable content
- panels on the main view. The panels allow the user to see the headline for each
- piece of news and clicking on the headline will expand the news item so that the
- actual story summary can be read. At the bottom of the summary we'll place a
- link to the full story in a similar fashion to many other RSS reader applications.
-
-
-
-
- We will also implement a couple of features to make the widget more user friendly.
- For example the first time when the widget is started we'll go directly to the
- settings view to let the user configure the widget before the first use. We'll
- also show helpful information such as loading progress and any error messages in
- notification popup windows. And of course all configuration settings will be
- persistent so that the user doesn't have to re-configure the widget every time
- its started.
-
-
-
-
- In order to make the widget similar to other S60 applications, we will tweak
- the softkeys and Options menu so that the settings view can be reached from the
- menu and so that the right softkey will let the user go back from the settings
- view to the main view. In the main view the right softkey will be used to exit
- the widget. We will also allow the user to manually force a refresh of the news
- items by adding a "Refresh" option to the options menu.
-
-
-
-
- And last but not least, we'll implement the widget so that it will work in a
- standards-compliant PC web browser such as Firefox. This will allow you to test
- and debug the widget quickly as you develop it on your PC.
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_RSS_Reader_first_steps-GUID-db42b227-1647-4020-bdb9-dacb26771779.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_RSS_Reader_first_steps-GUID-db42b227-1647-4020-bdb9-dacb26771779.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,236 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-First steps
-
-
-
-
-
-
-First steps
-
-
-
-
-Preparations
-
-
-
-
- You can find the ready made RSS Reader example in the Examples/RSSReader directory
- in the WRTKit SDK. In there you can find the by-now familiar widget files: Info.plist
- for the widget metadata, Icon.png for the S60 application grid icon, and the WRTKit
- directory for the WRTKit user interface toolkit. You will also find the main HTML
- file RSSReader.html, a CSS file called RSSReader.css and two JavaScript files
- RSSReader.js and FeedUpdateBroker.js. As with all WRTKit -based widgets, we will
- be focusing on the JavaScript files but before we get to those, let's see take a
- look at the main HTML file:
-
-
- You probably immediately noticed that the file is almost identical to the HTML file
- for the Hello World widget. This is despite that the RSS Reader is much more complex.
- In fact the only differences are that we are including the two JavaScript files
- FeedUpdateBroker.js and RSSReader.js instead of HelloWorld.js as in the Hello World
- widget. That, and the fact that we have a CSS stylesheet file that we also import here,
- called RSSReader.css. Like for the Hello World widget we have an onload-event handler
- that calls a function called init() in the JavaScript to allow us to initialize the
- widget after everything is loaded.
-
-
-
-
- You can either examine the ready made files or create your own files as you read the
- tutorial. The tutorial assumes that you will create your own. If you're doing that then
- now would be a good time to create a working directory for your own widget, call it
- RSSReader and copy the WRTKit directory, Info.plist, Icon.png and the FeedUpdateBroker.js
- file to the your own working directory. The FeedUpdateBroker.js is an AJAX-based RSS
- fetcher and parser that we will be using in this example. It doesn't really have anything
- to do with the WRTKit or the user interface for the RSS Reader but we need it in order
- to be able to fetch and parse RSS feed news items. We will not create it in this tutorial
- and thus you should just copy it to your own widget working directory.
-
-
-
-
- At this point you can also create an empty placeholder for the CSS stylesheet file
- (RSSReader.css) so that you have the file ready for when we'll create some CSS rules
- for the widget. Also create an empty placeholder for the RSSReader.js file where the
- majority of the widget's code will go. We'll return to this in a little bit!
-
-
-
-
-
-Architecture
-
-
-
-
- Before we write any code, let's talk about what the architecture of the RSS Reader
- will be like. As we previously mentioned, the widget will have two views. A main
- view for showing feed news items and a settings view to allow users to configure
- what RSS feed to show and how often to update it. We also said that we'll have a
- custom Options menu.
-
-
-
-
- The entire code that implements fetching and parsing RSS feeds will be implemented
- in the file FeedUpdateBroker.js. The widget code will use it through only one single
- method: fetchFeed(). The way this works is that we will pass the URL of the RSS
- feed to the method, as well as a function that will get called when the fetch has
- been completed. Note that this call is asynchronous - it will immediately return
- after it's called and the actual outcome of the fetch will not be known until the
- callback method is called. As an argument to the callback we will receive an object
- with three properties: status, lastModified and items. The status property will
- contain a value of either "ok" or "error" depending on the outcome. The lastModified
- will be present in case the fetch was successful and contains a timestamp that
- indicates when the RSS feed was last updated. This will allow us to determine whether
- there is any new news items or not so that we only update the user interface if there
- really is something to update. Finally the third property "items" contains an array
- of parsed RSS news items. Each of these is a JavaScript object that has four
- properties: title for the news item headline, date to indicate when it was created,
- description for the news item summary, and link with an URL to the full story.
-
-
-
-
- We will setup a timer in the widget that will run a function once every second. In
- this function we will compare the current time to a scheduled "next update" time.
- If we have reached the next update time, we will use the feed update broker to fetch
- the RSS news items of the feed that we're interested in. When the feed has been
- fetched and parsed a callback method will be called and we will react to the callback
- by either showing an error message (if the update failed), ignoring the callback (if
- there was no new news items for us), or update the user interface (if there's new
- news items to show).
-
-
-
-
- We also want to be able to update the news items on request and for that we will
- put an option in the Options menu that triggers a function that sets the next
- scheduled update time to be immediately. That way the normal update timer will
- immediately get triggered and cause an update.
-
-
-
-
- We will also set the "next update" time whenever the feed update broker is used
- to fetch new news items. That way we will get an automatic periodic update of the
- news that will run in the background but can also be triggered to run immediately
- if the user asks it to be.
-
-
-
-
- In order to fetch and update news items with this mechanism we need two things:
- the URL to the RSS feed and the interval between the automatic updates. These are
- also the two properties that we will allow the user to configure in the settings
- view. The properties will be stored in the widget preferences store and updated
- there whenever the user saves the settings. The settings will be read when the
- widget starts.
-
-
-
-
- When the news items are fetched we will display a notification popup dialog to
- indicate that the loading is in progress. The main reason why this is important
- is because the loading takes some time and if we don't react immediately to the
- user's action then the user will feel like the widget is not responsive. However
- we don't want to popup a progress dialog every time the widget loads news in the
- background. That would be really annoying when the user is reading news! This
- means that we have to know whether the update was triggered manually or if it
- was scheduled. We'll use a flag to track this and popup the dialog only if the
- update was commanded by the user.
-
-
-
-
- The settings view will contain four controls: a selection control to select the
- feed URL, another selection control to select the feed update frequency, a save
- button and a cancel button.
-
-
-
-
- The main view in turn will contain a variable amount of controls: one for each
- news item. The control that we will use is a ContentPanel control, which allows
- us to collapse and expand the content so that we can display a compact list of
- news headlines yet allow the user to open up a particular piece of news that
- is interesting and read the summay or go to the website where the full news
- story can be found. The news item controls will have the news headline as the
- caption in the control. Unlike for other controls, ContentPanel captions are
- interactive and can be clicked. When clicked they will toggle the content area
- of the panel. We will put the actual news story summary in this content area.
- The news story summary will be a fragment of HTML that we will construct from
- each news story. The HTML will also include a link to the website where the
- full story is located. The HTML will be styled by CSS rules that we will write
- to the RSSReader.css file.
-
-
-
-
- Because we don't know how many news stories we will have at any given time, we
- will add and remove ContentPanel controls to the main view dynamically whenever
- there's some update in the RSS feed. But we're environmentally conscious so
- we'll recycle the ContentPanels. There's no need to throw them away even if they
- are not needed. So once we have created them we will put them in a pool so that
- we can recycle them. Later on if we need more ContentPanels will look for them
- in the pool first and only if there are no ready ContentPanel controls for us
- will we create more controls (and place them in the pool). Strictly speaking such
- recycling is not necessary but it doesn't complicate the code much and it's a good
- skill to know.
-
-
-
-
- Finally, as we move between the main view and settings view we will need to
- change the right softkey so that it's "Exit" in the main view and "Cancel" in
- the settings view.
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_RSS_Reader_user_interface-GUID-1083a0c4-a953-4b6e-a4d0-45a031e51c35.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_RSS_Reader_user_interface-GUID-1083a0c4-a953-4b6e-a4d0-45a031e51c35.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,631 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-RSS Reader user interface
-
-
-
-
-
-
-RSS Reader user interface
-
-
-
-
-Preferences
-
-
-
-
- Now it's time to write some code so let's open up RSSReader.js. The first thing
- we will do is implement the init() function that gets called when the widget has
- loaded. We will begin by setting up the timer-based updating mechanism for the
- feed updates by declaring four variables that we'll need for that:
-
-
-
-
-// Feed update timer identifier.
-var updateTimerId = null;
-
-// Feed URL and update frequency (in milliseconds; -1 if no auto update).
-var feedURL = null;
-var feedUpdateFrequency = -1;
-
-// Next scheduled update time; -1 if never.
-var feedUpdateTime = -1;
-
-
-
-
- We know that we'll need to get some working values for the feed URL and feed update
- frequency variables and we know that they will be configurable values so let's write
- the code for this:
-
-
-
-
-// Called from the onload event handler to initialize the widget.
-function init() {
- // load preferences
- loadPreferences();
-
- // start feed update timer (called once every second)
- updateTimerId = setInterval(updateFeedTimerFunc, 1000);
-}
-
-// Loads widget preferences.
-function loadPreferences() {
- if (window.widget) {
- // read feed URL and update frequency from the widget settings
- feedURL = widget.preferenceForKey("FeedURL");
- var feedUpdateFrequencyStr = widget.preferenceForKey("FeedUpdateFrequency");
- feedUpdateFrequency = (feedUpdateFrequencyStr == null) ? -1 : parseInt(feedUpdateFrequencyStr);
- }
-}
-
-// Timer function for feed updates - called once every second.
-function updateFeedTimerFunc() {
-
-}
-
-
-
-
- The init() function does two things at this point. First it calls our newly created
- loadPreferences() function that takes care of reading some values for the feedURL
- and feedUpdateFrequency variables. After this it starts up an interval timer that
- calls updateFeedTimerFunc() once every second. The function doesn't do anything
- yet but we'll get to that in a bit. The timer identifier is stored in the updateTimerId
- variable. If no configuration is found, feedURL will have a value of null and
- feedUpdateFrequency will have a value of -1. Note that all preferences are stored
- as strings so we need to parse the string value to an integer. Also note that we
- wrapped the preference loading code in an if-clause that checks if we are in the
- S60 Web Runtime environment. This allows us to run the code in a PC browser without
- getting an error message about the widget -related methods that don't exist outside
- of the S60 Web Runtime.
-
-
-
-
- While we're on the topic of preferences we'll write a save counterpart for the
- loadPreferences() function.
-
-
-
-
-// Saves widget preferences.
-function savePreferences() {
- if (window.widget) {
- // save settings in widget preferences store
- widget.setPreferenceForKey(feedURL, "FeedURL");
- widget.setPreferenceForKey(feedUpdateFrequency.toString(), "FeedUpdateFrequency");
- }
-}
-
-
-
-
- We're now almost done with the timer mechanism that will update the RSS feed but
- we are missing one thing: a way to manually schedule an immediate update of the
- feeds. Let's add a flag that we can use to track if an update was triggered
- automatically or manually:
-
-
-
-
-// Flag that tracks if a feed update is commanded or automatic.
-var feedUpdateCommanded = false;
-
-
-
-
- And now let's add a function that can be called to schedule an immediate update:
-
-
- The function just sets the next update time to 0 so that the next time the
- timer function runs it will notice that it's time to schedule a feed update.
- The function also sets the feedUpdateCommanded flag to true so that the
- updating mechanism will know that this was a manual update.
-
-
-
-
-
-Creating the user interface
-
-
-
-
- Now let's create the user interface. We'll start by declaring three variables
- where we will hold references to the user interface manager, main view and settings
- view. Note that these should be outside the init() function.
-
-
-
-
-// References to the WRTKit user interface manager and views.
-var uiManager;
-var mainView;
-var settingsView;
-
-
-
-
- We want our user interface to be in tab navigation mode and we want the softkey
- bar to be visible. The code for this is the same as in the Hello World example.
- Next we create the user interface manager, main view and settings view by adding
- the following code to the init() function:
-
-
-
-
-if (window.widget) {
- // set tab-navigation mode and show softkeys
- widget.setNavigationEnabled(false);
- menu.showSoftkeys();
-}
-
-// create UI manager
-uiManager = new UIManager();
-
-// create main view
-mainView = new ListView();
-
-// create settings view
-settingsView = new ListView(null, "Settings");
-
-
-
-
- You might have noticed that we didn't supply any arguments to the ListView constructor
- when the main view was created. The reason for this is that we will set the view caption
- dynamically depending on the news feed we are following. And since we don't need the
- unique identifier for the main view we don't even have to pass null to it. Remember: in
- JavaScript if you don't pass an argument it will be undefined, which is equal to null.
-
-
-
-
- The main view will not get populated with controls until we have some news feed items
- to display, but we can go ahead and create the settings view. Again, we will first
- declare variables to hold references to the controls and again, they should be declared
- outside the init() method so that they are accessible elsewhere in the widget code:
-
-
- Now that we have variables to receive the control references we can go ahead and create
- them and add them to the settings view. We will create a SelectionMenu control to let
- the user select the RSS feed to show, a SelectionList control to allow selection of
- the feed update frequency and two form buttons: "Save" and "Cancel". The SelectionMenu
- and SelectionList controls are identical from a developer's point of view but look
- very different. The SelectionMenu takes up very little space in the view but when clicked
- it pops up a list of options that the user can select from. This is good if theres a lot
- of options and we don't want to use up a lot of space from the view. The SelectionList
- is the exact opposite and shows all the options right there in the view. This is good
- if the widget is in pointer navigation mode or if there are very few options.
-
-
-
-
- Options for the SelectionMenu and SelectionList controls are defined as an array of
- JavaScript objects that have two properties: value and text. The value property contains
- the actual data of the option and the text property contains the string to display to
- the user. Before we create the controls we need to create the option arrays for the
- RSS feed options and update frequency options. These will simply be hard coded arrays
- that are defined using JavaScript object notation (JSON) and we'll place them at the top
- of the widget code so that they can be easily customized later on:
-
-
- The RSS feeds are all from the Nokia Nseries WOM World website but you could put any
- RSS feed URLs here that you like. However it is probably a good idea to stick with
- these for now since we know that they work. Later when the widget is completed you can try
- with other feeds. Note how the value is a URL but the text to display is a human readable
- name for the RSS feeds.
-
-
-
-
- The update frequency options are defined in milliseconds and there is one option with a
- magic value of -1 for "never". Here too you'll notice the difference between the value
- (an integer in this case) and the human readable text.
-
-
-
-
- Now that we have the option arrays we can create the controls for the settings view by
- adding the following code to the init() function:
-
-
-
-
- // feed selection control
- feedSelection = new SelectionMenu(null, "Select feed", feedOptions);
- settingsView.addControl(feedSelection);
-
- // feed update frequency selection control
- feedUpdateFrequencySelection = new SelectionList(null, "Check for updates", updateFrequencyOptions);
- settingsView.addControl(feedUpdateFrequencySelection);
-
- // save settings button
- settingsSaveButton = new FormButton(null, "Save");
- settingsView.addControl(settingsSaveButton);
-
- // cancel settings button
- settingsCancelButton = new FormButton(null, "Cancel");
- settingsView.addControl(settingsCancelButton);
-
-
-
-
- The two first arguments for the SelectionMenu and SelectionList constructors are the
- same as for most other controls: a unique identifier and a control caption. The third
- argument points to the array of options that the controls should display. You could
- also have omitted that argument from the constructor and instead called setOptions()
- later on, but why do it in two steps when you can do it in one?
-
-
-
-
- The user interface views are now done (minus the actual news items to display in the main
- view of course) but we still have some things to implement for the user interface. The
- buttons in the settings view don't do anything yet so let's fix that.
-
-
-
-
- The cancel button should take the user to the main view and the save button should
- start using the newly configured settings, save them, and then go to the main view.
- Our plan to implement this is to create a function for showing the main view, called
- "showMainView()", a similar function for showing the settings view that we will call
- "showSettings()", and a function that will be called when the save button is clicked
- called "saveSettingsClicked()". We will then add event listeners to the two buttons
- so that clicking the save button will result in a call to the saveSettingsClicked()
- function and clicking the cancel button will result in a call to the showMainView()
- function. Let's create empty placeholders for the functions first:
-
-
-
-
-// Callback for settings view save button.
-function saveSettingsClicked() {
-}
-
-// Show main view.
-function showMainView() {
-}
-
-// Show settings view.
-function showSettings() {
-}
-
-
-
-
- Now that we have those functions let's register the event listeners to the form
- buttons by adding these two lines of code immediately after where the buttons
- are created:
-
-
- We are now ready to implement the functions to show the main view, settings view
- and react to the save button click. But we won't implement those just yet because
- we want to do one more thing before that. Let's create the custom Options menu.
- The Options menu isn't using any WRTKit code but rather the standard S60 Web Runtime
- widget menu functionality. We'll have two menu items: "Refresh" to schedule an immediate
- news feed update and "Settings" to go to the settings view. The Web Runtime Options
- menu works so that a callback function gets called when the user selections an Options
- menu item. In order to recognize which menu item was selected we'll need a unique
- identifier for each of them. Let's create those:
-
-
-
-
-// Constants for menu item identifiers.
-var MENU_ITEM_SETTINGS = 0;
-var MENU_ITEM_REFRESH = 1;
-
-
-
-
- Next we'll create the callback function that will be called when the menu items are
- selected:
-
-
-
-
-// Callback for when menu items are selected.
-function menuItemSelected(id) {
- switch (id) {
- case MENU_ITEM_SETTINGS:
- showSettings();
- break;
- case MENU_ITEM_REFRESH:
- updateFeed();
- break;
- }
-}
-
-
-
-
- This function gets the menu item identifier passed to it when the user selects
- a menu item. The switch-case will branch off to call showSettings() if the "Settings"
- menu item was selected and updateFeed() if the "Refresh" menu item was selected.
- But we haven't actually created the menu yet so let's do that by adding this to the
- init() function right after where we show the softkey bar. We want to have this piece
- of code inside the if-clause that checks if we're in the S60 Web Runtime because we
- don't have the Options menu functionality on a PC browser.
-
-
-
-
-// create menu
-var settingsMenuItem = new MenuItem("Settings", MENU_ITEM_SETTINGS);
-settingsMenuItem.onSelect = menuItemSelected;
-menu.append(settingsMenuItem);
-var refreshMenuItem = new MenuItem("Refresh", MENU_ITEM_REFRESH);
-refreshMenuItem.onSelect = menuItemSelected;
-menu.append(refreshMenuItem);
-
-
-
-
- The code simply creates two MenuItem objects, gives them a label and a unique
- identifier, specifies the callback function to call when selected and then adds
- them to the Options menu. The menu object is a global object that automatically
- exists in the S60 Web Runtime.
-
-
-
-
- Now let's return to the three functions we created but didn't implement. We will
- start with the showMainMenu() function. This function should perform all necessary
- steps to show the main menu. This includes the following: setting a caption for
- the main view, setting the right softkey to be the default "Exit" label and
- functionality, and then actually showing the main view by calling setView() in the
- user interface manager. We'll get the main view caption by checking which of the
- RSS feeds the user has currently selected. We do this by looping through the feed
- options and looking for the feed URL that is currently in use. If we can't find one
- we'll default to "RSS Reader".
-
-
-
-
-// Show main view.
-function showMainView() {
- // set main view caption from feed name
- var feedName = null;
- for (var i = 0; i < feedOptions.length; i++) {
- if (feedOptions[i].value == feedURL) {
- feedName = feedOptions[i].text;
- break;
- }
- }
- var mainViewCaption = (feedName == null) ? "RSS Reader" : feedName;
- mainView.setCaption(mainViewCaption);
-
- // set right softkey to "exit"
- if (window.widget) {
- menu.setRightSoftkeyLabel("", null);
- }
-
- // show the main view
- uiManager.setView(mainView);
-}
-
-
-
-
- When the settings view is shown we first want to place the controls into
- a state that reflects the current configuration. In other words we want
- the currently configured feed to be the one that's selected in the feed selection
- control. In the same way the currently configured feed update frequency should
- be selected in the feed update frequency selection control. There is a very
- convenient method available for this called getOptionForValue(). Using that
- function we can pass the currently configured feed URL and feed update frequency
- and get back the options object that corresponds to the configuration value.
- After this we can use that options object when we call setSelected() to select
- that option.
-
-
-
-
- If there is no valid configuration then we disable the cancel button and make
- the right softkey be "Exit". This is useful when the widget is started for the
- first time so that user has to enter a valid configuration before starting to
- use the widget. If there is a valid configuration we set the right softkey to
- "Cancel" and make it call the showMainView() function that we just created. The
- "Cancel" button will also be enabled.
-
-
-
-
- Finally we'll switch to the settings view by calling setView() in the user
- interface manager.
-
-
-
-
-// Show settings view.
-function showSettings() {
- // URL (use first available feed if null)
- var feedOption = (feedURL == null) ? feedOptions[0] : feedSelection.getOptionForValue(feedURL);
- feedSelection.setSelected(feedOption);
-
- // frequency
- var feedUpdateFrequencyOption = feedUpdateFrequencySelection.getOptionForValue(feedUpdateFrequency);
- feedUpdateFrequencySelection.setSelected(feedUpdateFrequencyOption);
-
- if (feedURL == null) {
- // no valid configuration
- // disable cancel button - set right softkey to "exit"
- settingsCancelButton.setEnabled(false);
- if (window.widget) {
- menu.setRightSoftkeyLabel("", null);
- }
- } else {
- // we have a valid configuration
- // enable cancel button - set right softkey to "cancel"
- settingsCancelButton.setEnabled(true);
- if (window.widget) {
- menu.setRightSoftkeyLabel("Cancel", showMainView);
- }
- }
-
- // show the settings view
- uiManager.setView(settingsView);
-}
-
-
-
-
- The third function to implement is the callback for when the save button is clicked.
- First we take the selected options from the feed selection and feed update frequency
- selection controls. Those selected values are copied to the feedURL and feedUpdateFrequency
- variables that are used by the widget during runtime. Next the settings are saved using
- the savePreferences() function that we implemented earlier. And finally we call the
- showMainView() method so that the widget shows the main view with the news items.
-
-
-
-
-// Callback for settings view save button.
-function saveSettingsClicked() {
- // update feed URL
- var selectedFeed = feedSelection.getSelected();
- feedURL = (selectedFeed != null) ? selectedFeed.value : null;
-
- // update frequency
- var selectedFrequency = feedUpdateFrequencySelection.getSelected();
- feedUpdateFrequency = (selectedFrequency != null) ? selectedFrequency.value : -1;
-
- // save preferences
- savePreferences();
-
- // return to main view
- showMainView();
-}
-
-
-
-
- The user interface is now nearly done but the init() function needs one more
- thing. We need to show a view after the function is done initializing
- the widget. The view to show depeneds on whether we have a valid
- configuration or not. If we do then we'll show the main view. If not then
- we'll show the settings view. Let's add this code to the end of the init()
- function, just before we start the update timer:
-
-
-
-
-// display the main view if a feed has been configured
-// otherwise show the settings view
-if (feedURL != null) {
- showMainView();
- updateFeed();
-} else {
- showSettings();
-}
-
-
-
-
- You can now go ahead and try out the widget either on a handset, emulator
- or in a PC browser. You should have a working settings view and when clicking
- the save button in the settings view you should end up in the main view. From
- there you can go to the settings by selecting "Settings" in the Options menu.
-
-
-
-
- There are no news items to show yet but that's our next task.
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_SelectionControl_Class-GUID-35c4291f-dc3a-439c-890f-1d140864aca0.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_SelectionControl_Class-GUID-35c4291f-dc3a-439c-890f-1d140864aca0.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,564 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-WRTKit SelectionControl Class
-
-
-
-
-
-
-WRTKit SelectionControl Class
-
-
-
-
-Description
-
-
-
-
- The SelectionControl class is an abstract base class for all controls that lets
- the user select one or more options from a set of options.
-
-
-
-
- The options in a selection control are simple option objects with two properties:
- value and text. An option is specified using JavaScript object notation (JSON) as
-
-{ value: "value here", text: "Text for value goes here" }. The value
- property specifies the actual value of the option whereas the text property specifies
- how the option is shown to the user in the control. E.g. the value could be a boolean
- value while the text could be "Yes" or "No". The text value is an XHTML string.
-
-
-
-
- Don't instantiate SelectionControl directly but rather one of its subclasses.
-
-
- Returns a boolean value that indicates whether the the specified option
- is currently selected. Options are objects with two properties: value and text.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-option
-
-
-
-
-
- The option to check the selected state for.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- True if the specified option is selected, false if not.
-
-
- Retrieves the currently selected option or options. If the control is a multiple
- selection control then an array of selected options is returned (an empty array if
- no options are selected). If the control is a single selection control then the
- single selection option is returned, or null if no options are selected.
- Options are objects with two properties: value and text.
-
-
-
-
-
-Arguments
-
-
-
-
- This method does not take any arguments.
-
-
-
-
-
-Return value
-
-
-
-
- An array containing the currently selected options for multiple selection controls.
- For single selection controls the return value is the selected option. If no options
- are selected then an empty array is returned for multiple selection controls and null
- is returned for single selection controls.
-
-
- Sets the currently selected options for a selection control. The selected options
- should be a subset of the options contain within the control. For a multiple selection
- control an array of options should be specified. For a single selection control the
- single option that should be selected should be specified without being contained in
- an array. To select zero options pass an empty array for multiple selection controls
- and null for single selection controls. Options are objects with two properties:
- value and text.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-selected
-
-
-
-
-
- The options to select. For multiple selection controls this argument
- should be an array of the options to select or an empty array to select
- zero elements. For single selection controls it should be a single option
- object or null for no selected options.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- This method does not return a value.
-
-
-
-
-
-
-
-
-
-
-
-getOptions()
-
-
-
-
-Syntax
-
-
-
-[Array] SelectionControl.getOptions(void)
-
-
-
-
-Description
-
-
-
-
- Retrieves the options available to the user in the control. The options are
- returned as an array of option objects. Options are objects with two properties:
- value and text.
-
-
-
-
-
-Arguments
-
-
-
-
- This method does not take any arguments.
-
-
-
-
-
-Return value
-
-
-
-
- An array containing the options in the control.
-
-
- Sets the options that this control should give the user. Calling this method
- replaces the current options with the specified new ones. If one or more selected
- options are no longer part of the available options after calling this method
- then they will automatically be removed from the selected set. The options
- are given as an array of option objects. Options are objects with two properties:
- value and text. The text value is an XHTML string.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-options
-
-
-
-
-
- An array of options to give the user. These options replace the
- current options in the control.
-
-
- Retrieves the option in the selection control that has a value that matches
- the specified one. If multiple options have the same value then the first matching
- one is returned. If there is no match then null is returned.
-
-
-
-
- This method is a useful helper method for situations where a specific value in the
- options should be programmatically selected.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-value
-
-
-
-
-
- The value to search for among the options in the selection control.
- The value can be of any JavaScript type.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- The first option in this selection control that has a value that matches the
- specified one, or null if no matching option is found.
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_SelectionList_Class-GUID-c3be7a8a-9028-4cec-a0c0-d355d0621b37.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_SelectionList_Class-GUID-c3be7a8a-9028-4cec-a0c0-d355d0621b37.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,217 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-WRTKit SelectionList Class
-
-
-
-
-
-
-WRTKit SelectionList Class
-
-
-
-
-Description
-
-
-
-
- The SelectionList class is an implementation of a selection control that displays
- a list of options to the user. Options are displayed as radio buttons or checkboxes
- depending on if the control is in single or multiple-selection mode. Selection lists
- are useful in situations where the widget is used in pointer navigation mode or if
- there is a small amount of options.
-
-
- Creates a new instance of the SelectionList class.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-id
-
-
-
-
-
- Unique identifier for the control. Can be retrieved using the id property defined
- in the UIElement class that this control inherits from. Useful for example to
- identify the source of an event in event callback functions or to apply a CSS
- rule to only this particular control. The identifier can be null, in which case
- no id will be set for the control.
-
-
-
-
-
-
-
-
-caption
-
-
-
-
-
- The caption text for the control. A null caption can be used to hide the
- caption area. The value is an XHTML string.
-
-
-
-
-
-
-
-
-options
-
-
-
-
-
- An array of options that the selection list should display to the user.
- If the argument is omitted or null the control will not display any
- options. The options can be set or changed later by calling setOptions().
- Options are objects with two properties: value and text. Use JavaScript
- object notation (JSON) to construct option objects, e.g.
-
-{ value: "value here", text: "Text for value goes here" }.
- The text value is an XHTML string.
-
-
-
-
-
-
-
-
-multipleSelection
-
-
-
-
-
- The multipleSelection argument is a boolean flag that determines whether
- the control should be in multipleSelection mode or not. Use true to put
- the control in multiple selection mode and false to put it in single
- selection mode. If this argument is omitted the control will go to single
- selection mode by default.
-
-
-
-
-
-
-
-
-selected
-
-
-
-
-
- The selected argument specifies which of the options should be selected at
- creation time. For multiple selection controls this should be given as an
- array of option objects with an empty array if no options should be selected.
- For single selection controls this should be the single option object that
- should be selected or null if no option should be selected. If the argument
- is omitted or null no options will be selected.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- A new instance of the SelectionList class.
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_SelectionMenu_Class-GUID-3ae54fdf-e938-400b-969d-e41575331aa0.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_SelectionMenu_Class-GUID-3ae54fdf-e938-400b-969d-e41575331aa0.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,225 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-WRTKit SelectionMenu Class
-
-
-
-
-
-
-WRTKit SelectionMenu Class
-
-
-
-
-Description
-
-
-
-
- The SelectionMenu class is an implementation of a selection control that lets
- users select options from a popup menu.
-
-
-
-
- The SelectionMenu control has two modes: a display mode and a selection mode.
- Normally the display mode is shown and users can see what the currently selected
- options are. When a user selects the control a menu pops up that displays the
- available options. The user can then select the option (or options) from this
- menu. After the selection is done the menu goes away and the control returns to
- display mode. The SelectionMenu control is useful in situations where there
- are many options and showing them all uses up too much space.
-
-
- Creates a new instance of the SelectionMenu class.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-id
-
-
-
-
-
- Unique identifier for the control. Can be retrieved using the id property defined
- in the UIElement class that this control inherits from. Useful for example to
- identify the source of an event in event callback functions or to apply a CSS
- rule to only this particular control. The identifier can be null, in which case
- no id will be set for the control.
-
-
-
-
-
-
-
-
-caption
-
-
-
-
-
- The caption text for the control. A null caption can be used to hide the
- caption area. The value is an XHTML string.
-
-
-
-
-
-
-
-
-options
-
-
-
-
-
- An array of options that the selection menu should display to the user.
- If the argument is omitted or null the control will not display any
- options. The options can be set or changed later by calling setOptions().
- Options are objects with two properties: value and text. Use JavaScript
- object notation (JSON) to construct option objects, e.g.
-
-{ value: "value here", text: "Text for value goes here" }.
- The text value is an XHTML string.
-
-
-
-
-
-
-
-
-multipleSelection
-
-
-
-
-
- The multipleSelection argument is a boolean flag that determines whether
- the control should be in multipleSelection mode or not. Use true to put
- the control in multiple selection mode and false to put it in single
- selection mode. If this argument is omitted the control will go to single
- selection mode by default.
-
-
-
-
-
-
-
-
-selected
-
-
-
-
-
- The selected argument specifies which of the options should be selected at
- creation time. For multiple selection controls this should be given as an
- array of option objects with an empty array if no options should be selected.
- For single selection controls this should be the single option object that
- should be selected or null if no option should be selected. If the argument
- is omitted or null no options will be selected.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- A new instance of the SelectionMenu class.
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Selections-GUID-23145d13-f2e7-48be-b24b-bc49754b2919.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Selections-GUID-23145d13-f2e7-48be-b24b-bc49754b2919.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,113 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Selections
-
-
-
-
-
-
-Selections
-
-
-
-
-
- Selection of one or more options from a set of options is one of the most common
- use cases in a user interface. The WRTKit supports this use case with two
- controls, SelectionList and SelectionMenu, each of which can be in either
- "single selection" or "multiple selection" mode. The two controls differe only
- in look and interaction but not in their APIs.
-
-
-
-
- The SelectionList control shows an expanded list of all of its options in the
- view. If the control is in single selection mode then each option is presented
- with a "radio button", of which only one can be selected at a time. This ensures
- that only one of the options can be selected by the user. If the SelectionList
- control is in multiple selection mode then each option is presented with a
- "checkbox". Any amount (including zero) of checkboxes can be checked at time,
- allowing users to select multiple options. The SelectionList control is a hybrid
- between the traditional way of showing radio buttons and checkboxes in a web
- environment and the way that an S60 application shows single and multiple choice
- selections. The SelectionList is recommeded to be used when the widget is using
- the pointer navigation mode or when there are only a few options.
-
-
-
Figure 1.
-SelectionList controls
-
-
-
-
-
-
-
- The SelectionMenu control is more similar to the way normal S60 applications
- allow users to make single or multiple choices. The SelectionMenu takes up only
- minimally of space in its normal state, but when activated it pops up up a list
- of options with either radio buttons (for single selection) or checkboxes (for
- multiple selection) that the user can select. The SelectionMenu control is good
- for the tab navigation mode or if there are many options that would use up lots
- of space on the screen using the SelectionList control.
-
-
-
Figure 2.
-SelectionMenu control
-
-
-
-
-
-
-
- Options in the selection controls are specified as an array of JavaScript
- objects, where each object represents one option. Each option object has two
- properties: value and text. The value property can be any JavaScript value,
- including object references and is used to represent the concrete value of the
- option. The text property is used to display the option in the user interface.
- The value could for example be a boolean true or false while the
- text could be "Yes" or "No".
-
-
-
-
- The set of currently selected options can be set or retrieved from a selection
- control using getter and setter methods. For single selection controls the
- selected option is specified as a single reference to one of the options in the
- control. For multiple selection the selected options are specified as an array
- of references to zero or more of the options in the control. Note that the
- references to the options must refer to the very same options that are in the
- control - not other instances of the options even if they are identical in value
- and/or text.
-
-
-
-
- Selection controls fire "SelectionChanged" events when the user makes a
- selection in the control.
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Separator-GUID-ec82d9ea-6b88-48c6-92c2-09a4dd56b31a.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Separator-GUID-ec82d9ea-6b88-48c6-92c2-09a4dd56b31a.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,56 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Separator
-
-
-
-
-
-
-Separator
-
-
-
-
-
- There is a special Separator control that has no other functionality except to
- act as a visual separator between controls. By adding an instance of a Separator
- control in a view it is possible to split the view visually so that it better
- groups related controls together and makes the view easier to comprehend.
-
-
-
Figure 1.
-Two separators in a view
-
-
-
-
-
-
-
- Separator controls do not have any control specific API except for their
- constructor.
-
-
- Creates a new instance of the Separator class.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-id
-
-
-
-
-
- Unique identifier for the control. Can be retrieved using the id property defined
- in the UIElement class that this control inherits from. Useful for example to
- identify the source of an event in event callback functions or to apply a CSS
- rule to only this particular control. The identifier can be null, in which case
- no id will be set for the control.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- A new instance of the Separator class.
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Showing_content_in_a_view-GUID-7020d9ea-747d-42f3-b47c-16ad1f45db82.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Showing_content_in_a_view-GUID-7020d9ea-747d-42f3-b47c-16ad1f45db82.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,130 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Showing content in a view
-
-
-
-
-
-
-Showing content in a view
-
-
-
-
-
- The WRTKit has two controls for showing content inside a view. The
- first of the controls is called Label and is useful for simple and
- short information to be displayed, coupled with the control caption
- that describes the information.
-
-
-
Figure 1.
-Label control
-
-
-
-
-
-
-
- The second control is called ContentPanel and is more sophisticated
- than the Label control. ContentPanel controls can be created as
- foldable, which means that they can expand and collapse their
- content areas. Users can toggle the expanded and collapsed state by
- clicking on the caption area of the ContentPanel.
-
-
-
Figure 2.
-Foldable content panel
-
-
-
-
-
-
-
- The code below creates a Label control and a foldable ContentPanel
- control and adds them to a view. The code assumes that a view has
- already been created and that a variable called exampleView refers
- to it.
-
-
- The first and second arguments are the same in the constructors for
- both controls. The first is a unique identifier for the control and
- the second is the control caption. The third argument is also the
- same but is omitted for the label and null for the content panel
- since in both cases we don't specify any content at this point. The
- fourth argument for the content panel is a boolean that specifies
- whether the control should be foldable or not.
-
-
-
-
- The value for a label can be set and retrieved using the getText() and
- setText() methods. For content panels the content in the content area
- can be set and retrieved using getContent() and setContent(). The
- content is defined as an XHTML fragment and can contain arbitrarily
- complex XHTML, including images or even JavaScript.
-
-
-
-
-// set the text for the label
-nameLabel.setText("John Smith");
-
-// set content for the content panel
-infoPanel.setContent("<b>This is bolded!</b><br/>This is plain text on the second line.");
-
-
-
-
- Foldable ContentPanel controls can be programmatically collapsed or
- expanded using the setExpanded() method. The expanded state can be
- retrieved using the isExpanded() method.
-
-
-
-
-// retrieve the expanded state
-var expanded = infoPanel.isExpanded();
-
-// collapse the content panel
-infoPanel.setExpanded(false);
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Terminology-GUID-ebd8d7c4-03f6-498d-becc-eb8d4081ed8b.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Terminology-GUID-ebd8d7c4-03f6-498d-becc-eb8d4081ed8b.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,155 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Terminology
-
-
-
-
-
-
-Terminology
-
-
-
-
-Control
-
-
-
-
- A control is a user interface element that the user can interact with. Controls
- are used in PC applications, in web pages and in mobile device applications. In
- web pages controls are often known as "form controls". Common controls include
- textfields, textareas, buttons, checkboxes, radio buttons, scrollbars, labels
- and progress bars, among others. Not all controls are interactive, e.g. labels
- simply display a value. Controls are contained within some kind of user
- interface container such as a view or window.
-
-
-
-
- In the WRTKit, controls are JavaScript objects that contain the state and
- implement the behavior of the control. Controls take care of drawing themselves,
- including changing their appearence as a result of various state changes.
-
-
-
-
-
-View
-
-
-
-
- A container for user interface elements such as controls. On a mobile device
- user interface views typically fill the entire screen and thus only one view can
- be shown at a time. Views in a mobile device tend to lay out the elements it
- contains in a vertical list that can be scrolled up and down if there is more
- content in the view than what fits on the screen at a time.
-
-
-
-
- In the WRTKit, views are responsible for laying out controls. Custom views can
- be created to support advanced layouts but in the vast majority of cases the
- default ListView is sufficient. WRTKit views are JavaScript objects.
-
-
-
-
-
-Event
-
-
-
-
- An event is a notification of some occurrence in a user interface element, such
- as a view or control. Events are typically propagated to application code as
- messages or function calls or a combination of the two.
-
-
-
-
- The WRTKit uses a model known as the "observer pattern" to deliver event
- messages, which are JavaScript objects, to event listeners, which are JavaScript
- callback functions. WRTKit events have a type name that can be used to
- distinguish between different types of events. E.g. a button press produces an
- "ActionPerformed" event.
-
-
-
-
-
-Focus
-
-
-
-
- The control that is currently selected to receive input is said to be focused.
- Controls can be focused in both the tab and pointer navigation modes. In the tab
- mode the focus is moved between controls using the 4-way controller. In
- the pointer mode the focus is moved between controls by moving the pointer to
- "hover" above a control and then pressing a selection button to select that
- control. Focused controls are displayed in a distinct way from other controls to
- indicate that they are ready to be interacted with.
-
-
-
-
-
-Hovering
-
-
-
-
- In pointer navigation mode, the pointer is said to be "hovering" above a control
- if the pointer is located inside the control's area on the screen. Hovering is
- similar to focus, but differs because hovering in itself does not select a
- control for interaction. Rather a selection key must be pressed in order to
- focus the control that the pointer is currently hovering over. Hover is
- indicated by displaying a control in a distinct way from other controls.
-
-
-
-
-
-Navigation mode
-
-
-
-
- A navigation mode refers to a method of selecting what user interface element to
- interact with. The S60 Web Runtime supports two navigation modes: "tab" and
- "pointer". In the tab mode, focus is moved between controls using the 4-way
- controller. In pointer mode there is a pointer arrow on the screen that can be
- moved freely using the 4-way controller. A control is focused by moving the
- pointer arrow so that it hovers above a control, and then pressing a selection
- key to select that control. In tab mode a control can be either in normal or
- focused state, whereas in the pointer mode a control can be in normal, hover or
- focused state.
-
-[TextArea] new TextArea(String id, String caption, String text, Integer rows)
-
-
-
-
-Description
-
-
-
-
- Creates a new instance of the TextArea class.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-id
-
-
-
-
-
- Unique identifier for the control. Can be retrieved using the id property defined
- in the UIElement class that this control inherits from. Useful for example to
- identify the source of an event in event callback functions or to apply a CSS
- rule to only this particular control. The identifier can be null, in which case
- no id will be set for the control.
-
-
-
-
-
-
-
-
-caption
-
-
-
-
-
- The caption text for the control. A null caption can be used to hide the
- caption area. The value is an XHTML string.
-
-
-
-
-
-
-
-
-text
-
-
-
-
-
- The text to display in the text area. If the argument is omitted or null then
- the text area will not contain any text when created.
- The value is a plain text string (not XHTML).
-
-
-
-
-
-
-
-
-rows
-
-
-
-
-
- The argument specifies how many rows the text area should have. If omitted the
- text area will default to have 3 rows of text. Note that it is still possible
- to enter more than 3 lines of text. The rows define the height of the text area
- and thus how many lines of text are visible without scrolling.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- A new instance of the TextArea class.
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_TextEntryControl_Class-GUID-07359ff7-6015-4d2c-a9bf-b345fcf49090.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_TextEntryControl_Class-GUID-07359ff7-6015-4d2c-a9bf-b345fcf49090.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,209 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-WRTKit TextEntryControl Class
-
-
-
-
-
-
-WRTKit TextEntryControl Class
-
-
-
-
-Description
-
-
-
-
- The TextEntryControl class is an abstract base class for controls that let a user
- enter text. Don't instantiate TextEntryControl directly but rather one of its subclasses.
-
-
- Retrieves the current text of the text entry control.
- The value is a plain text string (not XHTML).
-
-
-
-
-
-Arguments
-
-
-
-
- This method does not take any arguments.
-
-
-
-
-
-Return value
-
-
-
-
- The current text of the text entry control.
-
-
-
-
-
-
-
-
-
-
-
-setText()
-
-
-
-
-Syntax
-
-
-
-[void] TextEntryControl.setText(String text)
-
-
-
-
-Description
-
-
-
-
- Sets the text value of the text entry control. The text is displayed in the
- editable area of the control and can be edited by the user provided that
- the control is not disabled. Setting a text value of null results in no
- text being shown. The value is a plain text string (not XHTML).
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-text
-
-
-
-
-
- The text value to set to the text entry control. A value of null
- results in no text being shown.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- This method does not return a value.
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_TextField_Class-GUID-799b7dea-1e4d-4147-bc27-acc4b91d8bf9.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_TextField_Class-GUID-799b7dea-1e4d-4147-bc27-acc4b91d8bf9.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,189 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-WRTKit TextField Class
-
-
-
-
-
-
-WRTKit TextField Class
-
-
-
-
-Description
-
-
-
-
- The TextField class implements a single line text entry control. The control
- is useful for situations where text is relatively short and doesn't need to
- span multiple lines. The text field also supports masked entry, which is good
- in situations where passwords or other secret text is entered.
-
-[TextField] new TextField(String id, String caption, String text, Boolean masked)
-
-
-
-
-Description
-
-
-
-
- Creates a new instance of the TextField class.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-id
-
-
-
-
-
- Unique identifier for the control. Can be retrieved using the id property defined
- in the UIElement class that this control inherits from. Useful for example to
- identify the source of an event in event callback functions or to apply a CSS
- rule to only this particular control. The identifier can be null, in which case
- no id will be set for the control.
-
-
-
-
-
-
-
-
-caption
-
-
-
-
-
- The caption text for the control. A null caption can be used to hide the
- caption area. The value is an XHTML string.
-
-
-
-
-
-
-
-
-text
-
-
-
-
-
- The text to display in the text field. If the argument is omitted or null then
- the text field will not contain any text when created.
- The value is a plain text string (not XHTML).
-
-
-
-
-
-
-
-
-masked
-
-
-
-
-
- If the masked argument is true then the text field will be created in masked
- text entry mode. If the argument is omitted or false then the control will be
- created in normal text entry mode.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- A new instance of the TextField class.
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Text_entry-GUID-b52e3343-5a39-4a83-ae97-461a53761207.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Text_entry-GUID-b52e3343-5a39-4a83-ae97-461a53761207.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,74 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Text entry
-
-
-
-
-
-
-Text entry
-
-
-
-
-
- The WRTKit has two controls for text entry needs. For situations when only a
- single line of text is needed there's the TextField control. The TextField
- control supports "masked text entry", meaning that any text that is entered into
- the control is masked so it cannot be read. The mask is implemented so that
- every typed character is shown as an asterisk (*) character.
-
-
-
-
- When longer or multi-line text entry is needed, the TextArea control
- can be used instead of the single-line TextField. The TextArea size
- can be defined in number of rows when the control is created. If the
- argument for rows is omitted a default of 3 rows will be used.
- Longer text can still be entered - the size refers to number of rows
- that are visible without scrolling. Note that TextArea controls do
- not support masked text entry.
-
-
-
Figure 1.
-TextField and TextArea controls
-
-
-
-
-
-
-
- The text in TextField and TextArea controls can be retrieved and set using
- getter and setter methods.
-
-
-
-
- Text entry controls fire "TextChanged" events when the user edits the text in
- the control.
-
-
- If you've completed the Hello World and RSS Reader tutorials and feel that you
- understand them well but still want to learn more, then this tutorial is for you!
- The Travel Companion widget that we will create in this tutorial is something that
- would be very useful for anyone who travels a lot. It's a widget that offers many
- helpful features for travellers: a world clock that allows the user to simultaneously
- follow the time at home and at the destination, a 5-day weather forecast for the
- destination city and the current weather for both the home and destination cities,
- a currency converter, and a summary of the current news headlines.
-
-
-
-
- But because this tutorial is about using the WRTKit for developing widget user interfaces
- we will not implement all the code that is required to actually carry out all the
- functionality that was described above. Instead we will have a Travel Companion "engine"
- that will provide all these services for us so that we can focus on the user interface.
- The engine that we will use (that has been created for this example) is a mock engine,
- meaning that it mimics what the real Travel Companion engine would do, but actually it
- just returns hard coded weather forecasts and exchange rates. That's all we need for this
- tutorial, but after you've created the widget you can modify the engine so that it
- actually fetches news headlines, currency exchange rates and weather forecasts from
- various data sources online. There are plenty of free services that you can integrate to.
- And here's the best part: because we will implement the user interface so that it's
- cleanly separated from the engine, you won't have to change a single line of the user
- interface code after you change the engine to use real world data!
-
-
-
-
- Our widget will have no less than five views: one main view, three functional views and
- a settings view. The main view exists purely for navigational purposes. Because the widget
- is so complex we want to give the user an overview of what's available and an easy way of
- getting to everything. The three functional views include an information view that gives
- the user the most important information in a single glance, a currency converter view,
- and a five day weather forecast view. And finally the settings view lets the user configure
- the home and local cities, daylight saving time and temperature unit (Celsius or
- Fahrenheit) to use in the weather forecast.
-
-
-
-
- The tutorial will teach several important things. First of all, we'll learn how to
- create widgets that have multiple views. Second, we'll learn how to separate the code
- in the widget so that the user interface doesn't need to know anything about how the
- business logic works, and vice versa. Third, we'll create a navigational view using
- the NavigationButton control. Fourth, we'll customize the look of the widget to include
- a logo for our application in the list view caption area. And finally, we'll learn how
- to update the content in the user interface using a timer. We'll use the timer to keep
- the world clock, weather forecast and news headlines up to date. This is very important
- because widgets are often used so that the user starts them and then just keeps them
- running for days on end. If we didn't refresh the user interface then the information
- would quickly get old and the user would be forced to do manual refreshes.
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Travel_Companion_functionality-GUID-384f2430-3de9-4006-ac8e-86c5774c3a79.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Travel_Companion_functionality-GUID-384f2430-3de9-4006-ac8e-86c5774c3a79.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,854 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Functionality
-
-
-
-
-
-
-Functionality
-
-
-
-
-Weather forecast
-
-
-
-
- Let's continue by implementing the weather forecast view. This view will
- be entirely composed of non-foldable ContentPanel controls. We'll have one
- panel that displays the city for which the forecast is for and one panel
- for each day of the five-day forecast. In order to make it easy to change
- the number of days the forecast is for we'll store references to the forecast
- panels in an array. Thus, we need to add two global variables to the widget:
-
-
- The next step is to create the actual view in the createWeatherView() function.
- Of course the actual content for the content panels won't be known until at
- runtime when we know what city the forecast is for and what the actual weather
- forecast is. Still, we can create the actual content panels and just set their
- content later so this is not a problem.
-
-
-
-
-// Creates the weather view.
-function createWeatherView() {
- // empty caption text to display the caption bar - custom background using CSS
- weatherView = new ListView(null, "");
-
- // heading panel for city
- weatherCityPanel = new ContentPanel();
- weatherView.addControl(weatherCityPanel);
-
- // create five content panels - one for each day in the 5-day forecast
- weatherContentPanels = [];
- for (var i = 0; i < 5; i++) {
- var weatherContentPanel = new ContentPanel();
- weatherView.addControl(weatherContentPanel)
- weatherContentPanels.push(weatherContentPanel);
- }
-}
-
-
-
-
- When we show the weather view we have to check what the current local city
- is and set the weatherCityPanel's content to a suitable HTML fragment that
- will work as a heading for the weather forecast. In addition to that we'll
- have to retrieve the weather forecast from the business logic engine and then
- create HTML from that for each day in the forecast and set it to the five
- content panels that we are storing references to in the weatherContentPanels
- array. The caption for the weather forecast panels will be a string that
- indicates the day that the forecast is for.
-
-
-
-
- Creating the HTML fragment for the forecast heading doesn't sound so hard
- but generating HTML for a weather forecast for five days sounds a bit tricky.
- Let's create a separate function to do that. Remember that the weather object
- that the engine is returning to us has two properties: temperature and type.
- The temperature is in the preferred temperature unit and the type is one of
- the type codes, e.g. "Sunny". We'll use it to match it up with a weather icon.
-
-
-
-
-// Returns HTML for one day of weather forecast.
-function getHTMLForWeather(weather) {
- // build weather icon file name string
- var weatherIcon = "Weather" + weather.type + ".png";
-
- // build temperature string
- var temperatureStr = weather.temperature + "°" + engine.getTemperatureUnit().toUpperCase();
-
- // build weather HTML
- var weatherBuf = "";
- weatherBuf += "<table class=\"WeatherForecastDayTable\"><tr>";
- weatherBuf += "<td class=\"WeatherForecastIconCell\">";
- weatherBuf += "<img src=\"" + weatherIcon + "\"/>";
- weatherBuf += "</td>";
- weatherBuf += "<td class=\"WeatherForecastTemperatureCell\">";
- weatherBuf += temperatureStr;
- weatherBuf += "</td>";
- weatherBuf += "</tr></table>";
-
- return weatherBuf;
-}
-
-
-
-
- The HTML that we are generating is a table with a single row with two cells.
- The left cell has the weather icon image and the right cell has the temperature.
- We are using three CSS style rules for the table and we naturally need to create
- those too in the TravelCompanion.css file:
-
-
-
-
-/* Table for one day of weather forecast information */
-.WeatherForecastDayTable {
- margin: auto;
- border-spacing: 0px;
-}
-
-/* Table cell for weather icon */
-.WeatherForecastIconCell {
- line-height: 1px;
- font-size: 1px;
- vertical-align: middle;
-}
-
-/* Table cell for temperature information */
-.WeatherForecastTemperatureCell {
- padding: 0px 0px 0px 10px;
- vertical-align: middle;
-}
-
-
-
-
- Now we have a way to turn a weather forecast into HTML that we can use in a
- ContentPanel control. We'll do that in a function we call updateWeatherForecast().
- The caption for each weather forecast panel will indicate the day that the
- forecast is for. The first weather object in the array that the engine returns
- is for today and the subsequent ones are for coming days.
-
-
-
-
-// Updates the weather forecast.
-function updateWeatherForecast() {
- // get local time and weather
- var localTime = engine.getLocalTime();
- var localWeather = engine.getLocalWeather();
-
- // set the weather for each day in the forecast
- for (var i = 0; i < 5; i++) {
- // figure out day name
- var day = (localTime.day + i) % 7;
- var dayName = localTime.dayNames[day];
-
- // set weather to content panel
- weatherContentPanels[i].setCaption((i == 0 ? "Today, " : "") + dayName);
- weatherContentPanels[i].setContent(getHTMLForWeather(localWeather[i]));
- }
-}
-
-
-
-
- We are now ready to implement the showWeatherView() function:
-
-
-
-
-// Displays the weather view.
-function showWeatherView() {
- // set heading city panel
- weatherCityPanel.setContent("<div class=\"WeatherCityPanel\">" + engine.getLocalCity().name + " 5-day Forecast("</div>");
-
- // update the weather forecast before showing the view
- updateWeatherForecast();
-
- setSubViewSoftkeys();
- uiManager.setView(weatherView);
-}
-
-
-
-
- The weatherCityPanel gets a heading that matches the currently configured local city.
- We're using another CSS rule for that so we'll have to add it to our stylesheet:
-
-
- The weather forecast view and functionality is now ready to be tested.
-
-
-
-
-
-Currency converter
-
-
-
-
- It's time to move on to the currency converter. This view is going to have two
- TextField controls. One for home currency and one for local currency. In addition
- there will be two FormButton controls to convert from the home currency to the
- local currency, and vice versa. We'll need references to the textfields so that
- we can retrieve their values when the form buttons are pressed:
-
-
- Creating the view is quite straight forward:
-
-
-
-
-// Creates the converter view.
-function createConverterView() {
- // empty caption text to display the caption bar - custom background using CSS
- converterView = new ListView(null, "");
-
- // home money
- homeMoneyField = new TextField();
- converterView.addControl(homeMoneyField);
-
- // local money
- localMoneyField = new TextField();
- converterView.addControl(localMoneyField);
-
- // home to local
- var homeToLocalButton = new FormButton(null, "Convert Home to Local");
- converterView.addControl(homeToLocalButton);
-
- // local to home
- var localToHomeButton = new FormButton(null, "Convert Local to Home");
- converterView.addControl(localToHomeButton);
-}
-
-
-
-
- Notice that the textfields don't have any caption or text at this point. We will
- set that just before the view is displayed because the caption will depend on
- what the home and local cities are configured to.
-
-
-
-
- Also notice that we don't have any event listeners for the buttons at this point.
- That's because we haven't actually written any functions that will implement
- the currency conversion yet. But before we do that we'll implement the
- function to show the view:
-
-
- You can now test the view but it won't actually convert any currency until
- we give our form buttons event listeners and write the code that will be
- called when the buttons are pressed.
-
-
-
-
- We'll implement that in two functions. One to convert from home to local and
- another to convert in the other direction. The functions take the current
- text value from the corresponding field and then pass it to the engine to do
- the conversion. The result is then placed in the other of the two fields,
- formatted so that the result has exactly two digits.
-
-
-
-
-// Called when the user clicks on the "convert home to local" button
-// in the converter view. (rounds to two decimals)
-function convertHomeToLocalMoney() {
- var homeMoney = parseFloat(homeMoneyField.getText());
- var localMoney = engine.convertHomeToLocalMoney(homeMoney).toFixed(2);
- localMoneyField.setText(localMoney);
-}
-
-// Called when the user clicks on the "convert local to home" button
-// in the converter view. (rounds to two decimals)
-function convertLocalToHomeMoney() {
- var localMoney = parseFloat(localMoneyField.getText());
- var homeMoney = engine.convertLocalToHomeMoney(localMoney).toFixed(2);
- homeMoneyField.setText(homeMoney);
-}
-
-
-
-
- Now that the functions are implemented we can add the event listeners to our
- form buttons. We'll add this code right after where the buttons are created in
- the createConverterView() function:
-
-
- The currency converter is now working and it's time to test it. Try it with
- different currencies by changing the home and local cities in the settings view.
-
-
- The information view is a summary of relevant information that the user is
- will often need. Here we'll have a world clock that shows the home and local
- time, the current weather at home and in the local city, as well as the
- latest news headlines. We will use ContentPanel controls for all of these.
- One for the home time, one for the local time, one for the home weather, one
- for the local weather, and one for all the news headlines.
-
-
-
-
- We'll need to access all of these content panels from outside the view creation
- function so we'll need global variables to hold references to them:
-
-
- We can now proceed and actually implement the creation of the information view:
-
-
-
-
-// Creates the info view.
-function createInfoView() {
- // empty caption text to display the caption bar - custom background using CSS
- infoView = new ListView(null, "");
-
- // home city time
- homeCityTimePanel = new ContentPanel();
- infoView.addControl(homeCityTimePanel);
-
- // local city time
- localCityTimePanel = new ContentPanel();
- infoView.addControl(localCityTimePanel);
-
- // separator
- infoView.addControl(new Separator());
-
- // home city weather
- homeCityWeatherPanel = new ContentPanel();
- infoView.addControl(homeCityWeatherPanel);
-
- // local city weather
- localCityWeatherPanel = new ContentPanel();
- infoView.addControl(localCityWeatherPanel);
-
- // separator
- infoView.addControl(new Separator());
-
- // news headlines
- newsHeadlinesPanel = new ContentPanel();
- infoView.addControl(newsHeadlinesPanel);
-}
-
-
-
-
- We already have a function that turns a weather forecast into HTML but we
- don't have similar functions for time or for news headlines. We'll need
- that when we want to put content into the time and headline content panels
- so let's write those functions next.
-
-
-
-
- For time we'll need a function that takes a DateTime object and returns
- HTML that we can use in the content panel in the information view.
-
-
- Next up is the function for turning the latest news headlines into HTML.
- For each news headline we'll generate a div that contains the actual
- news headline plus a link to the website where the full news article is.
- Opening URLs should be done using the widget.openURL() method in the
- S60 Web Runtime but since we don't have that functionality in a PC browser
- we'll write a wrapper for the function just like we did for the RSS Reader:
-
-
- The div that encloses each news headline uses a CSS rule called NewsHeadline.
- As with all other CSS rules that we use we'll define this one too in
- the TravelCompanion.css stylesheet file. We also need to add rules for what
- links should look like in the context of a news headline. We define the link
- as bold underlined blue text in its normal state and inverse with blue background
- and white text when focused.
-
-
-
-
-/* News headline */
-.NewsHeadline {
- padding: 0px 0px 10px 0px;
-}
-
-/* Anchor tags in the context of a news headline link */
-.NewsHeadline a {
- text-decoration: underline;
- font-weight: bold;
- color: rgb(0,0,255);
-}
-
-/* Focused anchor tags */
-.NewsHeadline a:focus {
- background: rgb(0,0,255);
- color: rgb(255,255,255);
-}
-
-
-
-
- Now we should have everything we need to be able to update the information
- view content panels when the view is shown. It's time to implement the
- showInfoView() function:
-
-
-
-
-// Displays the info view.
-function showInfoView() {
- // set current information to controls
- var homeCity = engine.getHomeCity();
- var localCity = engine.getLocalCity();
-
- // set time
- var homeTime = engine.getHomeTime();
- var localTime = engine.getLocalTime();
- homeCityTimePanel.setCaption(homeCity.name + " Time");
- homeCityTimePanel.setContent(getHTMLForTime(homeTime));
- localCityTimePanel.setCaption(localCity.name + " Time");
- localCityTimePanel.setContent(getHTMLForTime(localTime));
-
- // set weather
- var homeWeather = engine.getHomeWeather();
- var localWeather = engine.getLocalWeather();
- homeCityWeatherPanel.setCaption(homeCity.name + " Weather");
- homeCityWeatherPanel.setContent(getHTMLForWeather(homeWeather[0]));
- localCityWeatherPanel.setCaption(localCity.name + " Weather");
- localCityWeatherPanel.setContent(getHTMLForWeather(localWeather[0]));
-
- // set headline
- var newsHeadlines = engine.getNewsHeadlines();
- newsHeadlinesPanel.setCaption("News Headlines");
- newsHeadlinesPanel.setContent(getHTMLForNewsHeadlines(newsHeadlines));
-
- setSubViewSoftkeys();
- uiManager.setView(infoView);
-}
-
-
-
-
- If you try the view now, everything will seem to work fine. But there
- is a big problem! We set the content in the content panels when the
- view is shown but if we stay in the view for an hour the clocks will
- still show the same time as when we showed the view. What's worse, it's
- not just the information view that has this problem. The weather forecast
- view is equally broken.
-
-
-
-
-
-Updating views with a timer
-
-
-
-
- In order to keep the views up to date we'll need to start a timer that
- periodically calls a function where we examine whether it's been long
- enough since the last update of a view that it's time to update the
- content in that view. Note that we only need to update a view using the
- timer if the view is actually visible.
-
-
-
-
- That sounds good at first but some things have to be updated more
- frequently than others. The clocks in our information view have to not
- only be updated once a minute but immediately when the minute changes.
- Such accuracy is not needed for the weather forecasts or news headlines.
- For them it's fine if they are updated once per hour. Except that weather
- forecasts also have to be updated when the day rolls over to the next as
- otherwise the forecast will show the wrong day. Because the home and local
- cities can be in different timezones their days will roll over at
- different times and thus we have to track these separately.
-
-
-
-
- It turns out that we need no less than five variables to track this.
- We need one to track the last minute that has been updated to the clocks,
- one variable is needed to track when the weather was last updated, one
- to track the day in the home city when the home city weather forecast
- was updated, one to track the same but for the local city, and one to
- track when the news headlines were updated. Let's declare those variables
- and initialize them:
-
-
-
-
-// Tracks last updated minute on the clocks.
-var lastUpdatedClockMinute = -1;
-
-// Tracks last update time for weather.
-var weatherLastUpdated = -1;
-
-// Tracks the days when the weather was last updated.
-var lastUpdatedHomeWeatherDay = -1;
-var lastUpdatedLocalWeatherDay = -1;
-
-// Tracks last update time for news headlines.
-var newsHeadlinesLastUpdated = -1;
-
-
-
-
- We'll use the time in millieconds to remember update times and compare
- how long it's been since an update happened. Since we'll use this quite
- a lot, let's create a small helper function for it:
-
-
-
-
-// Returns the current time in milliseconds.
-function getTimeMillis() {
- return new Date().getTime();
-}
-
-
-
-
- When we show a view we have to update the appropriate tracking variables
- so the widget will properly keep track of when a view was updated. That
- means that we have to add the following to just before we show the
- information view in showInfoView():
-
-
- Now our tracking variables should be updated to the right times whenever views
- are shown but we still don't have a timer to handle the automatic updating
- of the views.
-
-
-
-
- We'll set this timer up so that the timer callback function is called once
- every second so that we can make sure that the clocks don't fall behind. We'll
- track the timer identifier in a variable:
-
-
- We'll make the timer call a function called updateViews() that we will
- create shortly but first let's start the timer as the last thing in the
- init() function:
-
-
-
-
-// start timer that keeps views up to date
-timerId = setInterval(updateViews, 1000);
-
-
-
-
- The updateViews() function needs to check what view we are currently in and do
- the appropriate checks depending on the view. If we're in the information view
- then we have three things to check. The first thing is to check if the minute
- has changed on the clock. The second is to check if it's been over 60 minutes
- since the weather was updated or if either the home or local city has rolled
- over to the next day. And finally the third to thing to check is if it's been
- over 60 minutes since the news headlines were updated.
-
-
-
-
- If we are in the weather view then we check if it's been over 60 minutes since
- the weather was updated or if the local city has rolled over to the next day.
- Note that the weather forecast view only displays the local weather forecast
- so we don't have to check for if the home city has rolled over to the next day.
-
-
-
-
- The implementation of the function is therefore as follows:
-
-
-
-
-// Timer callback function that gets called once every second to keep views up to date.
-function updateViews() {
-
- // get the current view
- var currentView = uiManager.getView();
-
- // get home and local time as well as time in milliseconds
- var homeTime = engine.getHomeTime();
- var localTime = engine.getLocalTime();
- var now = getTimeMillis();
-
- if (currentView == infoView) {
- // only update the clocks if the minute has changed
- if (homeTime.minutes != lastUpdatedClockMinute) {
- lastUpdatedClockMinute = homeTime.minute;
- homeCityTimePanel.setContent(getHTMLForTime(homeTime));
- localCityTimePanel.setContent(getHTMLForTime(localTime));
- }
-
- // update weather if it hasn't been updated in the last hour or if the day has changed
- if ((now > weatherLastUpdated + (1000 * 60 * 60)) ||
- (homeTime.day != lastUpdatedHomeWeatherDay) ||
- (localTime.day != lastUpdatedLocalWeatherDay)) {
- weatherLastUpdated = now;
- lastUpdatedHomeWeatherDay = homeTime.day;
- lastUpdatedLocalWeatherDay = localTime.day;
- var homeWeather = engine.getHomeWeather();
- var localWeather = engine.getLocalWeather();
- homeCityWeatherPanel.setContent(getHTMLForWeather(homeWeather[0]));
- localCityWeatherPanel.setContent(getHTMLForWeather(localWeather[0]));
- }
-
- // update news headlines if they haven't been updated in the last hour
- if (now > newsHeadlinesLastUpdated + (1000 * 60 * 60)) {
- newsHeadlinesLastUpdated = now;
- var newsHeadlines = engine.getNewsHeadlines();
- newsHeadlinesPanel.setContent(getHTMLForNewsHeadlines(newsHeadlines));
- }
- } else if (currentView == weatherView) {
- // update weather if it hasn't been updated in the last hour or if the day has changed
- if ((now > weatherLastUpdated + (1000 * 60 * 60)) ||
- (localTime.day != lastUpdatedLocalWeatherDay)) {
- weatherLastUpdated = now;
- lastUpdatedLocalWeatherDay = localTime.day;
- updateWeatherForecast();
- }
- }
-}
-
-
-
Figure 2.
-Travel Companion information view
-
-
-
-
-
-
-
-
-What we have learned
-
-
-
-
- The Travel Companion widget is now completed! We have learned to implement
- complex widgets with multiple views using the WRTKit. We have also learned
- how to keep information in views up to date using a timer. And we implemented
- the widget without any dependencies to how the business logic engine was
- implemented. That will come in handy if you want to continue developing this
- widget by substituting the mock engine with one that actually uses real
- world data. You are now ready to tackle any challenge using the WRTKit!
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Travel_Companion_planning_the_widget-GUID-891068c7-c802-4da7-8674-8e8292aef7eb.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Travel_Companion_planning_the_widget-GUID-891068c7-c802-4da7-8674-8e8292aef7eb.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,437 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Planning the widget
-
-
-
-
-
-
-Planning the widget
-
-
-
-
-Designing the user interface
-
-
-
-
- Because the Travel Companion is such a complex widget it is important to plan
- both the user interface and implementation carefully before starting to write
- any code. What are the most common use cases that we want to address with this
- widget? How will typical users be using the widget? What kind of future features
- might there be and can we plan for those already?
-
-
-
-
- Because the Travel Companion widget offers so much functionality and information
- it is important to present it in such a way that it doesn't overwhelm the user.
- To give the user a better idea of what is available and how to get to everything,
- we'll have a main view with nothing but navigation buttons to the other views in
- the widget. We'll implement this view using WRTKit NavigationButton controls and
- we will give each button its own icon so that the user can quickly see what the
- view is about.
-
-
-
-
- After some planning and talking to potential users we have decided to create
- a summary view that we will call "information view". This view will include the
- most important information in a single place so that the user can view it quickly
- without having to press any buttons to navigate around the widget. We'll put a
- world clock here, the current weather at home and at the local destination, and
- the latest news headlines. The information view will be entirely composed from
- WRTKit ContentPanel controls.
-
-
-
-
- In addition to the information view we'll have two more specialized views. We'll
- have a currency converter with two TextField controls (one for the home currency
- and one for the local) and two FormButton controls. One button will convert
- from the home currency to local currency and the other button will convert in the
- other direction. The second specialized view is a five day weather forecast. Like
- the information view this will be using ContentPanel controls and we will share
- the weather content used for the information view for this view.
-
-
-
-
- Finally we'll have a settings view that is accessible from the main view just like
- the other views in the widget. In many other widgets we might want to hide access
- to the settings view to the Options menu but in this case one of the common use
- cases is to configure where in the world you are so rather than hiding access to
- the view we want to present it clearly in the main view. The settings view will
- use SelectionMenu controls to allow users to select their home and local cities,
- SelectionList controls with a single option that will be presented as a checkbox
- to configure whether the cities are in daylight saving time or not, and a
- SelectionList control that lets the user select the temperature unit to use in
- the weather forecasts. Finally there will be two FormButton controls to let the
- user save or cancel any settings changes.
-
-
-
-
- When the widget starts will setup a timer that will call a timer callback function
- once every second. In the callback function we will check what view is currently
- active and we'll update the views (e.g. clock) so that the views stays up to date
- even if the user doesn't do anything. After all, the most common use case is to
- just have the information view open and not do anything other than glance at the
- information that is displayed.
-
-
-
-
-
-Travel Companion widget files
-
-
-
-
- All the files - HTML, CSS, JavaScript and images - have been created for you.
- You can find the completed widget with all its files in the Examples/TravelCompanion
- directory in the WRTKit SDK. The tutorial will assume that you will create your
- own Travel Companion widget by following the instructions but if you prefer you can
- just open up the ready made files and examine them as you read the tutorial. If you
- are creating the widget from scratch by following the tutorial's instructions then
- we suggest that you create a working directory for the new widget and copy over all
- other ready made files except TravelCompanion.js. All of our work will be on this
- file, but before we move on to that file we'll take a look at what other files the
- widget is using.
-
-
-
-
- Since we're using the WRTKit to implement our user interface we have the WRTKit
- library with all its files in a directory called "WRTKit".
-
-
-
-
- Like all widgets the Travel Companion has an Info.plist widget metadata file and an
- icon in a file called Icon.png. You'll also notice that there's a bunch of png
- image files in the widget directory. There's a file called ListViewCaptionLogo.png
- that we will use as a custom graphical element in the view caption in all of our
- views. Four png files have names starting with "Nav" and the rest start with
- "Weather". The image files that have names starting with "Nav" are icons for the
- NavigationButton controls for the main view. They are simply images that are
- 30 by 30 pixels in size and have some graphical motif that captures what the button
- does. Note that the size of images used for navigation buttons doesn't have to be
- exactly 30 by 30 pixels - you can use any size you like. The images with names
- starting with "Weather" are images used in the weather forecasts. There is one image
- for each kind of weather that can be forecasted: rain, snow, sunshine, clouds, etc.
-
-
-
-
- You'll find two JavaScript files: Engine.js and TravelCompanion.js. The Engine.js
- file has the implementation of the business logic and the TravelCompanion.js file
- implements the widget and its user interface. Finally there is the main widget HTML
- file called TravelCompanion.html and a CSS file called TravelCompanion.css that
- contains all the style rules used in the widget - above that what the WRTKit defines
- by default, which is actually nearly everything!
-
-
-
-
- Let's take a quick peek at TravelCompanion.html:
-
-
- If you've gone through the Hello World and/or RSS Reader tutorials then this should
- look very familiar. The file has no content, includes the WRTKit.js file from the
- WRTKit library directory, includes the JavaScript files that we are using to implement
- the Travel Companion widget, includes the TravelCompanion.css stylesheet file, and
- finally calls a function called init() when the widget has loaded everything.
-
-
-
-
-
-The Travel Companion Engine
-
-
-
-
- Following good software engineering principles, we are implementing the Travel Companion
- widget so that the user interface is decoupled from the implementation of the actual
- business logic that knows weather forecasts, calculates currency conversions, etc. The
- logic is outside of the scope for this tutorial since we're interested in learning about
- how to use the WRTKit - not how to convert euros to dollars. Because of this we will not
- look at all at how the business logic is implemented but we will take a close look at
- the interface between the user interface and the business logic engine. In fact, the
- implementation of the engine for this example is a mock implementation and only mimics
- what a real engine would do. But since this is only an example that's quite alright.
- The engine interface, however, is identical to what it would be even if the engine would
- have a real implementation.
-
-
-
-
- The engine is implemented as a JavaScript class that you instantiate before using.
- The reason for being implemented as a class is simply so that the engine can better
- encapsulate its internal data and provide a kind of name space for its methods.
-
-
-
-
- The core concept in the Travel Companion engine is that of cities. The engine supports
- a list of cities and one will always be a "home city" and one a "local city". The
- same city can be both home and local. Home refers to the city where the user lives
- and local refers to the city where the user is currently located. The engine doesn't
- know the daylight saving time schedules for cities so this is configured manually by
- the user: one setting for the home city and one for the local city. The engine handles
- all preferences but the user interface must tell it to save preferences if some
- preference is modified. Preferences are automatically loaded when the engine is
- created, which should happen when the widget starts so that all the settings are
- available immediately.
-
-
-
-
- A city in the engine is a JavaScript object. A city object has the following public
- properties: name for the city name, currency for the three-letter currency abbreviation,
- and timezone for the timezone code (e.g. GMT). Cities are created and managed entirely
- by the engine.
-
-
-
-
- Below is a complete list of the public engine APIs that are related to preferences and
- cities:
-
-
- Of course the engine isn't just about preferences. Its actual purpose is to perform
- various operations related to these cities, such as converting currencies, figuring
- out what the time is in a foreign city, etc. To simplify the usage of the engine,
- the public methods related to these operations are defined in terms of the home and
- local city as it is configured at the time when the method is called.
-
-
-
-
- Here's the full list of the actual operation methods that the engine supports:
-
-
-
-
- Currency conversions between home and local:
-
-
- The DateTime object returned by getHomeTime() and getLocalTime() is a JavaScript
- object that contains the following properties: year, month, date, day, hours, minutes,
- seconds, timezone. All properties are integers except the timezone, which is a string
- that represents the timezone code, e.g. "EET" for "Eastern European Time". Month and
- day are zero-based to simplify their use as indexes in arrays that contains the month
- and week day names. These arrays can be found in the DateTime object. The array for
- week day names is called dayNames and the array for month names is called monthNames.
- Day 0 is Sunday and month 0 is January. To find out the name of the day represented
- by a DateTime object you would do the following:
-
-
- The array returned by the getHomeWeather() and getLocalWeather() methods contains
- the weather for the next five days so that the first element is the weather today,
- the second is the weather tomorrow, etc. Each item is a JavaScript object that
- has two properties: temperature, which is an integer in the preferred temperature
- unit, and type, which is a string that describes the weather. The type string is
- one of the following: "Sunny", "PartlyCloudy", "Cloudy", "Rain", "Sleet" or Snow".
- There is a weather type image for each of these, named so that there is a "Weather"
- prefix in front of the weather type and a ".png" suffix after it, e.g. "WeatherSunny.png".
-
-
-
-
- Retrieving an array of the latest news headlines:
-
-
-
-
-[Array] Engine.getNewsHeadlines(void)
-
-
-
-
- Each item in the array that the getNewsHeadlines() method returns is a JavaScript
- object that describes one news headline. Each news headline object has two
- properties: headline for the actual news headline text and url for the website
- address where the full news article is located.
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Travel_Companion_user_interface-GUID-989d17cc-f019-46bb-b6f5-49166e258aca.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Travel_Companion_user_interface-GUID-989d17cc-f019-46bb-b6f5-49166e258aca.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,698 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Travel Companion user interface
-
-
-
-
-
-
-Travel Companion user interface
-
-
-
-
-Handling multiple views
-
-
-
-
- The Travel Companion widget will follow many of the same patterns that the Hello World
- and RSS Reader widgets have followed. The entry point to the widget is the init() function
- that we call from the onload event handler in the main HTML file TravelCompanion.html.
- We will implement the init() function along with the rest of the widget and user interface
- in the TravelCompanion.js file. Let's start with the init() function so that we get the
- widget up and running.
-
-
-
-
- From previous widgets we already know a lot of things about the WRTKit and about what
- we will need. For example we know that we will have a user interface manager and that
- we'll need a reference to each of the views that our widget uses. And since we have
- designed the Travel Companion widget we know what views we will have. Before we write the
- init() function we can go ahead and declare the variables that we will use to refer to
- the views and the user interface manager. And while we're at it we can also declare the
- variable that we'll use to refer to the Travel Companion engine. All of these variables
- are globals and thus go outside the init() function:
-
-
-
-
-// Reference to travel companion engine that implements the business logic.
-var engine;
-
-// Reference to the WRTKit user interface manager.
-var uiManager;
-
-// References to views.
-var mainView;
-var infoView;
-var converterView;
-var weatherView;
-var settingsView;
-
-
-
-
- Previously we've written the init() function so that it creates the entire user interface
- but because the Travel Companion widget has a much larger user interface than anything
- we've done before, it's probably a good idea to split things up into smaller functions
- so we don't end up with a huge init() function that will be hard to read and maintain.
- Let's create a function for the creation of each view, and then one function that will
- call these view creation functions and setup all other things that we need for the user
- interface, such as the Options menu. We'll just create stub functions for now but we
- will soon get to implement the functions:
-
-
-
-
-// Creates the user interface.
-function createUI() {
-}
-
-// Creates the main view.
-function createMainView() {
-}
-
-// Creates the info view.
-function createInfoView() {
-}
-
-// Creates the converter view.
-function createConverterView() {
-}
-
-// Creates the weather view.
-function createWeatherView() {
-}
-
-// Creates the settings view.
-function createSettingsView() {
-}
-
-
-
-
- In the RSS Reader widget we used functions called showMainView() and showSettings() to
- move between views. That allowed us to implement all the logic that was required when
- moving between views in one place regardless of what action triggered the change of
- views. We'll do the same thing in the Travel Companion widget but this time we'll need
- five functions since we have five views. Let's create stubs for these too at this stage
- so that the functions exist if we need to refer to them.
-
-
-
-
-// Displays the main view.
-function showMainView() {
-}
-
-// Displays the info view.
-function showInfoView() {
-}
-
-// Displays the converter view.
-function showConverterView() {
-}
-
-// Displays the weather view.
-function showWeatherView() {
-}
-
-// Displays the settings view.
-function showSettingsView() {
-}
-
-
-
-
- Since we will create each user interface view in its own function our init() function
- will be much simpler than in previous widgets. We will create the business logic engine,
- create the user interface by calling createUI() and then display the main view.
-
-
-
-
-// Called from the onload event handler to initialize the widget.
-function init() {
- // initialize the business logic engine
- engine = new Engine();
-
- // create the user interface
- createUI();
-
- // display the main view
- showMainView();
-}
-
-
-
-
- Let's get started with creating the user interface by returning to the createUI()
- function. We'll want to widget to show the softkey bar and we'll want it to be in
- tab navigation mode instead of the default pointer navigation mode. We then need
- to create the user interface manager and the five views that this widget has. Of
- course those five views are actually created by the five create-functions that we
- just wrote stubs for so we just need to call those functions from createUI().
-
-
-
-
-// Creates the user interface.
-function createUI() {
- if (window.widget) {
- // set tab-navigation mode and show softkeys
- widget.setNavigationEnabled(false);
- menu.showSoftkeys();
- }
-
- // create UI manager
- uiManager = new UIManager();
-
- // create views
- createMainView();
- createInfoView();
- createConverterView();
- createWeatherView();
- createSettingsView();
-}
-
-
-
-
- Because we created the stub functions for moving between views, we can also create
- the Options menu now. We'll only add one item to the menu in addition to the default
- "Exit" menu item. The item we'll add is one that will take the user to the settings
- view. We'll first need to create a global menu item identifier:
-
-
-
-
-// Constants for menu item identifiers.
-var MENU_ITEM_SETTINGS = 0;
-
-
-
-
- Now that we have the menu item identifier we can actually create the menu item. Because
- the Options menu functionality is only available in the S60 Web Runtime and not in PC
- browsers we'll add that code in the same if-clause where we set the navigation mode and
- show the softkey bar.
-
-
-
-
-// create menu
-var settingsMenuItem = new MenuItem("Settings", MENU_ITEM_SETTINGS);
-settingsMenuItem.onSelect = menuItemSelected;
-menu.append(settingsMenuItem);
-
-
-
-
- When the menu item is selected it calls a function called menuItemSelected(). Let's
- create that function and handle the case when the settings menu item is selected.
- When it is, we want to call showSettingsView() so that the user ends up in the settings
- view as expected:
-
-
-
-
-// Callback for when menu items are selected.
-function menuItemSelected(id) {
- switch (id) {
- case MENU_ITEM_SETTINGS:
- showSettingsView();
- break;
- }
-}
-
-
-
-
- The framework that we'll need when implementing the actual views is now nearly complete.
- But before we move on let's talk about how we'll be using softkeys in the Travel
- Companion widget.
-
-
-
-
- In the main view we want the right softkey to be the default "Exit". But in the
- four functional views we don't want it to exit the widget but rather to return to
- the main view. We'll thus use "Back" as the title in the functional views, except
- in the settings view where we'll use "Cancel".
-
-
-
-
- Let's create three functions that will handle setting the widget right softkey to
- these configurations. The functions will check if we're actually in the S60 Web
- Runtime before attempting to change the right softkey in order to make the widget
- also work in a PC browser for testing purposes.
-
-
-
-
-// Sets the softkeys for the main view.
-function setMainViewSoftkeys() {
- if (window.widget) {
- // set right softkey to "exit"
- menu.setRightSoftkeyLabel("", null);
- }
-}
-
-// Sets the softkeys for sub views.
-function setSubViewSoftkeys() {
- if (window.widget) {
- // set right softkey to "back" (to main view)
- menu.setRightSoftkeyLabel("Back", showMainView);
- }
-}
-
-// Sets the softkeys for settings view.
-function setSettingsViewSoftkeys() {
- if (window.widget) {
- // set right softkey to "cancel" (returns to main view)
- menu.setRightSoftkeyLabel("Cancel", showMainView);
- }
-}
-
-
-
-
-
-Main view
-
-
-
-
- Let's create our main view now so that we get something visible. The main view is
- of course created in the function createMainView() for which we already created a
- stub function. The main view will have four WRTKit NavigationButton controls in it,
- one for each of the views (not counting the main view itself) in the widget. Using
- the NavigationButton control is just like using a FormButton, with the difference
- that it looks different and can have an icon image in addition to just text. Earlier
- when we looked at the files that were in the Examples/TravelCompanion directory we
- noticed that there were four icons there. Now it's time to use them as icons in the
- navigation buttons.
-
-
-
-
- We will add event listerners to the buttons so that when they are clicked (when they
- emit an ActionPerformed event) they will call the functions we have created for
- moving between views. At this point the functions are just stubs, but we will of
- course fix that later.
-
-
-
-
- We've had captions for the views that we've created so far in the Hello World and
- RSS Reader widgets and the Travel Companion will also have view captions. However
- for the Travel Companion we'll use an image as our view caption. We will set the
- view caption to an empty string because if it's undefined or null then the view
- caption area will be hidden. Then we will create a CSS rule for the ListViewCaptionText
- class that is used by the area where the caption text goes in a list view. Because
- our CSS rule is defined after the default WRTKit CSS rule for ListViewCaptionText,
- our rule will be override the default one. Let's open up TravelCompanion.css and
- create this rule:
-
-
-
-
-/* Place logo in list view caption */
-.ListViewCaptionText {
- background: url("ListViewCaptionLogo.png") no-repeat;
- height: 35px;
-}
-
-
-
-
- We specified a height in addition to the background image. The height is needed
- so that the caption text area won't collapse to zero height since it won't contain
- any text. We're now ready to implement the createMainView() function:
-
-
-
-
-// Creates the main view.
-function createMainView() {
- // empty caption text to display the caption bar - custom background using CSS
- mainView = new ListView(null, "");
-
- // info
- var navToInfoButton = new NavigationButton(null, "NavInfoIcon.png", "Information");
- navToInfoButton.addEventListener("ActionPerformed", showInfoView);
- mainView.addControl(navToInfoButton);
-
- // converter
- var navToConverterButton = new NavigationButton(null, "NavConverterIcon.png", "Currency Converter");
- navToConverterButton.addEventListener("ActionPerformed", showConverterView);
- mainView.addControl(navToConverterButton);
-
- // weather
- var navToWeatherButton = new NavigationButton(null, "NavWeatherIcon.png", "Weather Forecast");
- navToWeatherButton.addEventListener("ActionPerformed", showWeatherView);
- mainView.addControl(navToWeatherButton);
-
- // settings
- var navToSettingsButton = new NavigationButton(null, "NavSettingsIcon.png", "Settings");
- navToSettingsButton.addEventListener("ActionPerformed", showSettingsView);
- mainView.addControl(navToSettingsButton);
-}
-
-
-
-
- We now have a main view and our widget even calls showMainView() when it starts
- but nothing will actually show up yet because we haven't implemented the showMainView()
- function yet. Let's do that now:
-
-
-
-
-// Displays the main view.
-function showMainView() {
- setMainViewSoftkeys();
- uiManager.setView(mainView);
-}
-
-
-
-
- The function calls the setMainViewSoftkeys() function to put the right softkey
- in the proper state and then asks the user interface manager to show the main
- view. Remember that we're already calling the showMainView() function from the
- init() function so we can go ahead and test this now in a PC browser, emulator
- or handset. Notice the custom list view caption image and the navigation button
- icons. Clicking the navigation buttons doesn't do anything yet because we don't
- have any other views yet and the functions to show other views except the main
- view aren't implemented. But then again, because we wrote stub functions we are
- also not getting any error messages.
-
-
-
Figure 1.
-Travel Companion main view
-
-
-
-
-
-
-
-
-Settings view
-
-
-
-
- It's a good idea to implement the settings view as early as possible because
- that allows you to test the rest of the widget more easily. In order to get
- the settings view up and running we'll need to do three things. First of all
- we'll need to implement the createSettingsView() function so that the widget
- actually has a settings view. Second, we'll need to implement the actions
- that can be performed in that view. There are two actions: "Save" and "Cancel".
- Of these, save is the tricker one and we'll implement it in a function that
- we will call saveSettingsClicked(). The cancel action will simply take us back
- to the main view and will be handled by the showMainView() function that we
- have already implemented. And third, we need to implement the showSettingsView()
- function so that clicking on the settings navigation button in the main view
- takes us to the settings view and sets it up correctly so that the view
- reflects the current preferences.
-
-
-
-
- The settings view will have four sections that we will separate using a WRTKit
- Separator control. The first section lets the user select the home city and the
- whether the home city is in daylight saving time. Here we'll use a SelectionMenu
- control for the city selection and a SelectionList control with a single option
- for the daylight saving time option. We could have used a SelectionList with
- two options "Daylight saving time" and "Normal time". Since the selection would
- have been a single selection this would have resulted in two radio buttons. But
- partly for the sake of usability and partly to show how to do it, we'll implement
- it so that it's a single checkbox instead. Thus, we'll use a SelectionList with
- a single option but we'll get the checkboxes instead of radio buttons by putting
- the SelectionList in multiple selection mode. Because there's only one option
- there will only be one checkbox.
-
-
-
-
- The second section is just like the first one but for the local city. The third
- section is for the temperature unit selection (Celsius or Fahrenheit) and we'll
- implement it as a single selection SelectionList control. And finally the fourth
- section is for the Save and Cancel FormButton controls.
-
-
-
-
- The options for the selection controls will be created just before we create
- the controls themselves. The daylight saving time and temperature unit options
- are just static JSON defined option lists since we know what the options are.
- But for the city selection we'll create it dynamically by asking the business
- logic engine for a list of all the supported cities. We'll then create one option
- for each city.
-
-
-
-
- Because we'll need to access the controls in the settings view from outside the
- creation function we'll need to create global references to them:
-
-
- We can now implement the settings view creation function:
-
-
-
-
-// Creates the settings view.
-function createSettingsView() {
- // empty caption text to display the caption bar - custom background using CSS
- settingsView = new ListView(null, "");
-
- // create city options from cities array
- var cityOptions = [];
- var cities = engine.getCities();
- for (var i = 0; i < cities.length; i++) {
- cityOptions.push({ value: cities[i], text: cities[i].name });
- }
-
- // create DST option
- dstOptions = [ { value: true, text: "DST (+1h)" } ];
-
- // home city
- homeCitySelection = new SelectionMenu(null, "Home City", cityOptions);
- settingsView.addControl(homeCitySelection);
-
- // home city DST (using a multiple selection but only one option to get a single checkbox)
- homeCityDSTSelection = new SelectionList(null, "Daylight Saving Time (home)", dstOptions, true);
- settingsView.addControl(homeCityDSTSelection);
-
- // separator
- settingsView.addControl(new Separator());
-
- // local city
- localCitySelection = new SelectionMenu(null, "Local City", cityOptions);
- settingsView.addControl(localCitySelection);
-
- // local city DST (using a multiple selection but only one option to get a single checkbox)
- localCityDSTSelection = new SelectionList(null, "Daylight Saving Time (local)", dstOptions, true);
- settingsView.addControl(localCityDSTSelection);
-
- // separator
- settingsView.addControl(new Separator());
-
- // temperature unit
- var temperatureUnitOptions = [ { value: "c", text: "Celsius" }, { value: "f", text: "Fahrenheit" } ];
- temperatureUnitSelection = new SelectionList(null, "Temperature Unit", temperatureUnitOptions);
- settingsView.addControl(temperatureUnitSelection);
-
- // separator
- settingsView.addControl(new Separator());
-
- // save button
- var saveSettingsButton = new FormButton(null, "Save");
- saveSettingsButton.addEventListener("ActionPerformed", saveSettingsClicked);
- settingsView.addControl(saveSettingsButton);
-
- // cancel button
- var cancelSettingsButton = new FormButton(null, "Cancel");
- cancelSettingsButton.addEventListener("ActionPerformed", showMainView);
- settingsView.addControl(cancelSettingsButton);
-}
-
-
-
-
- Note that we used the actual city as the value for the city options. You can
- use anything you want for the value property for a selection control option
- and in this case we used the actual city object because it will come in handy
- later when we want to set the home and local cities that the user has selected
- to the engine.
-
-
-
-
- Our save button calls the saveSettingsClicked() function we talked about earlier
- but we haven't created that function yet. We'll continue implementing the user
- interface by writing this function.
-
-
-
-
- You'll recall that the business logic engine actually stores all the preferences
- so all we really need to do is read what values have been selected in the settings
- view, telling these values to the engine, calling the savePreferences() method in
- the engine to persist the settings, and then return to the main view.
-
-
-
-
-// Called when the user clicks on the "save" button in the settings view.
-function saveSettingsClicked() {
- // update the selected home city
- var selectedHomeCityOption = homeCitySelection.getSelected();
- if (selectedHomeCityOption != null) {
- engine.setHomeCity(selectedHomeCityOption.value);
- }
-
- // update the selected local city
- var selectedLocalCityOption = localCitySelection.getSelected();
- if (selectedLocalCityOption != null) {
- engine.setLocalCity(selectedLocalCityOption.value);
- }
-
- // update home and local city DST
- // there's only one checkbox but we are using a multiple-selection menu.
- // if the selected array has one element then the checkbox is checked.
- engine.setHomeCityDST(homeCityDSTSelection.getSelected().length == 1);
- engine.setLocalCityDST(localCityDSTSelection.getSelected().length == 1);
-
- // update temperature unit
- var selectedTemperatureUnitOption = temperatureUnitSelection.getSelected();
- if (selectedTemperatureUnitOption != null) {
- engine.setTemperatureUnit(selectedTemperatureUnitOption.value);
- }
-
- // save settings
- engine.savePreferences();
-
- // go back to the main view
- showMainView();
-}
-
-
-
-
- We're writing defensive code here and making sure that the selection controls
- actually have anything selected at all. This should never be possible with
- single selection control if they have one option already selected, but we'll
- use the principle of "better safe than sorry".
-
-
-
-
- Notice that the daylight saving time selection is checked by asking for the
- selected options array (we're using a multiple selection control) and checking
- if there is exactly one selected option. We don't care about the actual selected
- option because we know that there's only one. Either it's selected or it's not.
-
-
-
-
- We have now implemented two of the three steps we said were necessary to get the
- settings view fully functional. Let's implement the final step: showing the view.
- Showing the settings view is done by first updating the settings view controls
- to reflect the current configuration, setting the right softkey to the state that
- it should be in for the settings view and then asking the user interface manager
- to show the settings view.
-
-
-
-
-// Displays the settings view.
-function showSettingsView() {
- // update settings view controls to match current configuration
- // the DST selected sets are either the options array with its single option or an empty array
-
- // home city and DST setting
- homeCitySelection.setSelected(homeCitySelection.getOptionForValue(engine.getHomeCity()));
- homeCityDSTSelection.setSelected(engine.getHomeCityDST() ? homeCityDSTSelection.getOptions() : []);
-
- // local city and DST setting
- localCitySelection.setSelected(localCitySelection.getOptionForValue(engine.getLocalCity()));
- localCityDSTSelection.setSelected(engine.getLocalCityDST() ? localCityDSTSelection.getOptions() : []);
-
- // temperature unit
- temperatureUnitSelection.setSelected(temperatureUnitSelection.getOptionForValue(engine.getTemperatureUnit()));
-
- setSettingsViewSoftkeys();
- uiManager.setView(settingsView);
-}
-
-
-
-
- We're using the convenient getOptionForValue() function that all selection controls
- have to retrieve the right option to select for each of the selection controls. The
- way we handle the daylight saving time selection controls may seem a little strange
- at first but remember that we only have a single option and thus if that option should
- be selected then the selected options array is identical with the options array - both
- are arrays containing the one and same option. Selection controls always copy the options
- and selected options arrays when the setOptions() and setSelected() methods are called
- so there is no problem in passing the options array as the selected options array.
-
-
-
-
- The settings view is now completed. You can try it out and play with it, change the
- settings, open it up again, change some more settings, cancel the changes, etc. to
- verify that it's working as it should.
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Tutorials-GUID-506c11e3-e6f3-43ec-9495-fcfa638b7e08.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Tutorials-GUID-506c11e3-e6f3-43ec-9495-fcfa638b7e08.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,104 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-WRTKit Tutorials
-
-
-
-
-
-
-WRTKit Tutorials
-
-
-
-
-
- The WRTKit tutorials guide you through the process of using the WRTKit user
- interface toolkit to build widgets. Even if you're familiar with widget
- development or a veteran HTML, CSS and JavaSCript developer, these tutorials
- will probably be useful to you as they focus on using the WRTKit to create
- and manage the user interface.
-
-
-
-
- There are three tutorials all in all and in each one we will take a look at one
- of the examples that are included with the WRTKit SDK.
-
-
-
-
- The first one is a gentle start where we will create the classic "Hello World"
- application but using the WRTKit for the user interface. This is a good starting
- point because it covers the basics of using the WRTKit, how to organize files,
- how to initialize the user interface toolkit, and such topics.
-
-
-
-
- The next tutorial is an actual useful widget: an RSS Reader. As with all WRTKit
- tutorials we will focus on the user interface portion of this widget, but you
- will also learn how to integrate a WRTKit -based user interface with data that
- has been pulled in using AJAX. Feel free to use this example widget as a basis
- for your own RSS Reader.
-
-
-
-
- In the third tutorial we'll create create a widget called "Travel Companion"
- in order to learn how to use the WRTKit to build complex widgets with multiple
- views, showing complex custom content, using timers to automatically update
- views in the background, as well as how to separate the user interface code from
- the back-end logic code and data. Since the tutorial is about how to use the
- WRTKit we will not actually create any real back-end logic but rather use a
- mock back-end that will give us data that looks real but is actually hard-coded.
-
-
-
-
- If you want you can complete the widget to make it work against actual data
- sources on the Internet. Since the user interface is entirely separated from
- the back-end logic you should be able to do this without touching any of the
- user interface code!
-
-
-
-
- When you go through the tutorials it could be a good idea to have your code
- editor open so that you can inspect the example widget code as you read about
- it. We will be talking a lot about the various classes and methods in the WRTKit
- so having the
-
-WRTKit API Reference
- open is probably also a good idea.
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_UIElement_Class-GUID-37b82f75-720c-4f54-9769-cda18453ffa3.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_UIElement_Class-GUID-37b82f75-720c-4f54-9769-cda18453ffa3.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,322 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-WRTKit UIElement Class
-
-
-
-
-
-
-WRTKit UIElement Class
-
-
-
-
-Description
-
-
-
-
- The UIElement class is the base class for all user interface elements
- such as views and controls. Don't instantiate UIElement directly but rather
- use one of its subclasses.
-
-
- Allows retrieval of the currently registered event listeners for this user interface element.
-
-
-
-
-
-Arguments
-
-
-
-
- This method does not take any arguments.
-
-
-
-
-
-Return value
-
-
-
-
- An array of event listeners currently registered to the user interface element.
-
-
-
-
-
-
-
-
-
-
-
-addEventListener()
-
-
-
-
-Syntax
-
-
-
-[void] UIElement.addEventListener(String eventType, Function listener)
-
-
-
-
-Description
-
-
-
-
- Allows registration of a callback function to a user interface element in order to get
- notifications of events in the user interface element. Event registration can be done
- for a specific type of event or for all events.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-eventType
-
-
-
-
-
- The name of the event type the listener should be called for or null if
- all event types. The available event type names depend on the actual user
- interface element class that this method is caled for.
-
-
-
-
- The most common event type names are ActionPerformed for button control clicks,
- SelectionChanged for selection controls, FocusStateChanged for all controls to
- indicate that focus was gained or lost and FocusedControlChanged for views to
- announce that a new control has been brought into (or out of) focus.
-
-
-
-
-
-
-
-
-listener
-
-
-
-
-
- The function that should be called when the specified event type occurs.
- The function should be defined with a single argument that will receive the
- event object. The object has three properties: source, type and value. The
- source property specifies the user interface element (e.g. control) from where
- the event originated. The type property contains the event type name. The
- contents of the value property depends between event types but contains
- additional information about the event. For example if the value changes in
- a selection control then the value property contains the new value.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- This method does not return a value.
-
-
-
-
-
-
-
-
-
-
-
-removeEventListener()
-
-
-
-
-Syntax
-
-
-
-[void] UIElement.removeEventListener(String eventType, Function listener)
-
-
-
-
-Description
-
-
-
-
- Allows a specific event listener to be unregistered from a user interface control.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-eventType
-
-
-
-
-
- The event type name of the listener that should be removed. Use the exact
- same event type name as when adding the event listener.
-
-
-
-
-
-
-
-
-listener
-
-
-
-
-
- The callback function of the listener that should be removed.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- This method does not return a value.
-
-
-
-
-
-
-
-
-
-
-
-id
-
-
-
-
-Syntax
-
-
-
-[String] UIElement.id
-
-
-
-
-Description
-
-
-
-
- The id property is a unique identifier for the user interface element.
- The identifier is used for the root HTML element in the element hierarchy
- that defines the user interface element and is useful for example in
- specifying specific CSS rules for a particular user interface element.
- The identifier can also be used to recognize the source of an event in an
- event callback by accessing the id property of the source property in the
- event object passed to the event listener callback.
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_UIManager_Class-GUID-937146c8-3889-40f5-b9f7-0f774ac9f5fe.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_UIManager_Class-GUID-937146c8-3889-40f5-b9f7-0f774ac9f5fe.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,451 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-WRTKit UIManager Class
-
-
-
-
-
-
-WRTKit UIManager Class
-
-
-
-
-Description
-
-
-
-
- The UIManager class manages a set of views and related user interface elements
- such as the scrollbar that indicates the scroll position for the current view,
- as well as notification popup dialogs.
-
-
-
-
- A typical WRTKit user interface consists of one or more views that are commanded
- to be displayed using the UIManager. When a view is commanded to be shown, the
- UIManager will remove the currently displayed view (if any) and attach the
- requested view. The UIManager creates and maintains the state of a scrollbar so
- that it matches the scrolling position and viewport extent at any given
- time, regardless of what goes on in the view (e.g. added or removed content),
- screen rotations and resizes, etc.
-
-[UIManager] new UIManager(HTMLElement viewParentElement, HTMLElement scrollbarParentElement)
-
-
-
-
-Description
-
-
-
-
- Creates a new instance of the ContentPanel class.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-viewParentElement
-
-
-
-
-
- The HTML element to attachs views to. Normally this argument would be
- omitted, which causes the UIManager to create its own view parent alement
- that attaches to the document body element. You only need to supply an
- HTML element to this argument in rare cases when it's not desirable to
- have views take up the entire document area.
-
-
-
-
-
-
-
-
-scrollbarParentElement
-
-
-
-
-
- The HTML element to attachs the scrollbar to. Normally this argument would be
- omitted, which causes the UIManager to create its own scrollbar parent alement
- that attaches to the document body element. You only need to supply an
- HTML element to this argument in rare cases when it's not desirable to
- have the scrollbar in its default location.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- A new instance of the UIManager class.
-
-
-
-
-
-
-
-
-
-
-
-getView()
-
-
-
-
-Syntax
-
-
-
-[String] UIManager.getView(void)
-
-
-
-
-Description
-
-
-
-
- Retrieves the current view.
-
-
-
-
-
-Arguments
-
-
-
-
- This method does not take any arguments.
-
-
-
-
-
-Return value
-
-
-
-
- The current view or null if none.
-
-
-
-
-
-
-
-
-
-
-
-setView()
-
-
-
-
-Syntax
-
-
-
-[void] UIManager.setView(View view)
-
-
-
-
-Description
-
-
-
-
- Sets the view to display. Calling this method removes the current view and
- displays the specified one instead. If null is passed as the argument to this
- method then the current view is removed but no new view is displayed instead.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-view
-
-
-
-
-
- The new view to display or null to simply remove the current view.
-
-
- Displays a notification popup dialog. If a dialog is already showing then calling this
- method again will change the content of the already displayed notification popup.
-
-
-
-
-
-Arguments
-
-
-
-
-
-
-
-displayTime
-
-
-
-
-
- The duration that the dialog should be displayed before automatically hiding.
- Specified in milliseconds (i.e. 1000ms = 1s). If the notification dialog should
- not automatically hide then a negative value can be specified.
-
-
-
-
-
-
-
-
-type
-
-
-
-
-
- Type of notification to display. This argument affects the look of the dialog
- and should have a value of either "info", "warning" or "wait". "Info" should be
- used for informational popups, "warning" for errors and other warning messages
- and "wait" for progress dialogs. If the argument is null then no type icon
- will be shown in the dialog.
-
-
-
-
-
-
-
-
-text
-
-
-
-
-
- The text to display in the popup dialog. If the argument is null then no text
- will be shown, however this is not recommended as it would be unclear to the
- user.
-
-
-
-
-
-
-
-
-progress
-
-
-
-
-
- This argument should be omitted except when a progress dialog is desired, i.e.
- when used with the "wait" type. The value of progress should be a floating
- point number between 0.0 and 1.0, where 0.0 means "0% progress" and 1.0 means
- "100% progress". A negative number means "unknown progress" and results in a
- different progress bar style than for known progress.
-
-
-
-
-
-
-
-
-
-
-Return value
-
-
-
-
- This method does not return a value.
-
-
-
-
-
-
-
-
-
-
-
-hideNotification()
-
-
-
-
-Syntax
-
-
-
-[void] UIManager.hideNotification()
-
-
-
-
-Description
-
-
-
-
- Hides the currently displayed notification popup dialog, if any. If this method
- is called when no notification dialog is displayed then the method call is simply
- ignored but no harm is done.
-
-
-
-
-
-Arguments
-
-
-
-
- This method does not take any arguments.
-
-
-
-
-
-Return value
-
-
-
-
- This method does not return a value.
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Using_buttons-GUID-8b14cec9-92cc-4bde-83c2-ad0a30a84942.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Using_buttons-GUID-8b14cec9-92cc-4bde-83c2-ad0a30a84942.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,92 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Using buttons
-
-
-
-
-
-
-Using buttons
-
-
-
-
-
- You can let users trigger actions by placing a FormButton or
- NavigationButton control in a view. Use FormButtons for actions that
- start some process and NavigationButton controls for situations
- where pressing the button should take the viewer to another view.
-
-
-
Figure 1.
-FormButton controls
-
-
-
-
-
-
-
- You can find out when a button has been pressed by registering a
- callback function as an event listener to the button. The event type
- for button presses is "ActionPerformed". You can use whatever name
- you like for the callback function. The function is passed the event
- object as an argument. A typical callback function looks like this:
-
-
-
-
-// Callback function for button presses.
-function buttonPressed(event) {
- // implement what happens when the button is pressed here
-}
-
-
-
-
- Creating a button, registering the event listener and adding the
- button to a view is demonstrated below. The example creates a
- FormButton:
-
-
- Note that the example assumes that a view has already been created
- and that the "exampleView" variable refers to that view. "button1"
- is a unique identifier for the button that allows it to be identified
- for example if several different controls are using a shared event
- listener function. The event listener function could examine the event
- object and check the identifier of the source control for the event.
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Using_notification_popups-GUID-39c7a69a-9334-45d1-92f6-8c239831a0a2.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Using_notification_popups-GUID-39c7a69a-9334-45d1-92f6-8c239831a0a2.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,116 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Using notification popups
-
-
-
-
-
-
-Using notification popups
-
-
-
-
-
- Notification popup dialogs are an easy way to show information to
- users. In the WRTKit notification popups are used using two methods
- in the UIManager class: showNotification() and hideNotification().
- If a notification is already showing when another is commanded to be
- shown then the current notification is replaced with the new one.
- Notifications can be either auto-hiding after a specified time or
- manually hidden by calling hideNotification(). Auto-hiding is an
- easy way in situations where a message just needs to be shown but
- doesn't require user acknowledgement, e.g. to let the user know that
- new content has loaded or similar.
-
-
- The API for showNotification() takes four arguments: displayTime,
- type, text and progress. The "displayTime" argument is an integer
- that specifies how long the notification popup dialog should be
- shown for before automatically hiding. The value is given in
- milliseconds (1000ms = 1s) and negative values can be used to
- specify that the dialog should not automatically hide. The second
- argument "type" is used to specify a visual style for the popup.
- There are three types of notifications: "info", "warning" and
- "wait". Info is intended for informative messages, warning for
- errors or other similar negative messages and finally wait is
- intended for dialogs that are letting the user know that some
- process (e.g. loading data from the Internet) is taking a long time.
- The fourth argument "progress" is a decimal number that should be
- omitted or null in all other cases except when the dialog should be
- a progress dialog (typically notifications of type "wait"). For
- progress dialogs the value should be between 0.0 and 1.0 to specify
- how far along the process is (0.0 for "0% done" and 1.0 for "100%
- done"). A negative value can be specified if the progress is
- unknown, resulting in an animated progress bar that indicates that
- the wait time and progress is not known.
-
-
-
-
- The code below show various examples of how to show notification
- popup dialogs. The examples assume that the UIManager has been
- instantiated and that a variable called uiManager refers to that
- instance.
-
-
-
-
-// show an info notification - auto-hide in 3 seconds
-uiManager.showNotification(3000, "info", "Informative message here");
-
-// show a warning notification - no auto-hide
-uiManager.showNotification(-1, "warning", "Warning message here");
-
-// show a progress notification - no auto-hide, 40% progress
-uiManager.showNotification(-1, "wait", "Loading...", 0.4);
-
-// show a progress notification - no auto-hide, unknown progress
-uiManager.showNotification(-1, "wait", "Loading...", -1.0);
-
-
-
-
- The example below shows how to hide a notification. If no
- notification is showing when the method is called then the
- call is ignored.
-
-
-
-
-// hide the current notification (if any)
-uiManager.hideNotification();
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Using_selection_controls-GUID-5e36d276-cce8-4bc9-bcba-78e721adb8c6.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Using_selection_controls-GUID-5e36d276-cce8-4bc9-bcba-78e721adb8c6.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,211 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Using selection controls
-
-
-
-
-
-
-Using selection controls
-
-
-
-
-
- Selection controls are used to let users make selections among a set
- of options. The WRTKit has two controls: SelectionList and
- SelectionMenu that have an identical API but differ in look and
- feel. The SelectionList shows all the options and selections
- directly in the view while the SelectionMenu only shows the selected
- options and opens up a menu with the options when the user activates
- the control. Selection controls can either be in single or multiple
- selection mode. In single selection mode only one of the options can
- be selected at a time while in multiple selection mode any number
- (including zero) can be selected.
-
-
-
Figure 1.
-SelectionList controls
-
-
-
-
-
-
-
- The SelectionList control is recommended to be used with the pointer
- navigation mode or if there are few options to choose from. The
- SelectionMenu control is recommended for large numbers of options or in
- the tab navigation mode.
-
-
-
Figure 2.
-SelectionMenu control
-
-
-
-
-
-
-
- The options of a selection control are defined as an array of option
- objects, each with two properties: value and text. The value
- property can be any JavaScript value and represent the concrete
- value of the option, while the text property is a string that is
- shown in the user interface for the option.
-
-
-
-
- Option arrays can conveniently be created using JavaScript object
- notation (JSON) for example as follows:
-
-
- The selected options are defined differently depending on whether
- the selection control is in single or multiple selection mode. In
- single selection mode the selected option is defined as a reference
- to the option in the control that should be selected. In multiple
- selection mode the selected options set is defined as an array of
- references to options in the control. Note that the references must
- be to one of the options objects defined for the control. It is not
- sufficient to define new option objects that happen to be identical
- to the ones in the control.
-
-
-
-
-// create a set of two selected options for multiple selection control
-var selectedOptions = [ options[1], options[2] ];
-
-
-
-
- Note that the selectedOptions array is constructed so that the two
- elements in the array refer to the "Tea" and "Water" options in the
- options array.
-
-
-
-
- The code below creates a SelectionList control in multiple selection
- mode and initializes it with the options and selectedOptions arrays
- created above. The code assumes that a view has already been created
- and that a variable called exampleView refers to it.
-
-
-
-
-// create selection list control
-var drinkList = new SelectionList("selection1", "Favorite drinks",
- options, true, selectedOptions);
-exampleView.addControl(drinkList);
-
-
-
-
- "selection1" is a unique identifier for the control, "Favorite
- drinks" is the control caption, the option argument refers to the
- options array that we previously created, the following argument
- determines whether the control is in multiple selection mode, and
- finally the selectedOptions argument refers to the array with
- selected options and defines which of the options in the control
- should be selected by default.
-
-
-
-
- All of the arguments are optional and can be specified later as
- needed. For example if the options are not known when the control
- is created, or if the options change, they can be set using the
- setOptions() method. In the same way the selected options can be
- set using the setSelected() method.
-
-
-
-
-// set options
-drinkList.setOptions(options);
-
-// set selected options
-drinkList.setSelected(selectedOptions);
-
-
-
-
- The currently selected options can be retrieved using the
- getSelected() method. As mentioned earlier, in single selection mode
- the selected is just a single reference to an option (or null if no
- option is selected), while in multiple selection mode it's an array
- with references to the selected options. If no options are selected
- in multiple selection mode then the array is empty.
-
-
-
-
-// find out which options are currently selected
-var selected = drinkList.getSelected();
-
-
-
-
- Selection controls fire "SelectionChanged" events when a user changes
- the selection of options in a control. These events can be handled
- using by registering an event listener to the control. The code below
- shows what a typical callback function would look like:
-
-
-
-
-// Callback function for selection change events.
-function favoriteDrinkChanged(event) {
- // implement what happens when the selection changed here
-}
-
-
-
-
- Registering the event listener function is done as follows, for
- example right after the control was created:
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Using_text_entry_controls-GUID-76aeb0e3-698d-41de-a34b-8fea6d8e00d2.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Using_text_entry_controls-GUID-76aeb0e3-698d-41de-a34b-8fea6d8e00d2.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,125 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Using text entry controls
-
-
-
-
-
-
-Using text entry controls
-
-
-
-
-
- The WRTKit supports two controls for text entry: TextField for
- a single line of text and TextArea for multiple lines of text.
- The API for both controls is identical, except for the constructor.
- The TextField can be created in masked mode, which is useful for
- entry of text that should not be displayed (e.g. passwords). For
- every character that is typed in masked mode, an asterisk is shown
- instead in the text field. While a TextArea control can hold an
- unlimited number of lines of text, its height (as number of rows
- to display without scrolling) is specified when it is constructed.
-
-
-
Figure 1.
-TextField and TextArea controls
-
-
-
-
-
-
-
- TextField and TextArea controls are created and added to views like
- any other controls in the WRTKit. The code assumes that a view has
- already been created and that a variable called exampleView refers
- to it.
-
-
-
-
-// create textfield
-var nameField = new TextField("field1", "Enter your name");
-exampleView.addControl(nameField);
-
-
-
-
- "field1" is a unique identifier for the control and "Enter your
- name" is the control caption. An optional third argument to the
- constructor can be used to specify the text to display in the
- control, however the text can also be set at any time later on using
- the setText() method as follows:
-
-
-
-
-// set the text in the textfield
-nameField.setText("John Smith");
-
-
-
-
- The current text in a text entry control can be retrieved using the
- getText() method:
-
-
-
-
-// get the current text from the textfield
-var text = nameField.getText();
-
-
-
-
- Text entry controls fire "TextChanged" events when a user edits the
- text in a control. These events can be handled using by registering
- an event listener to the control. The code below shows what a
- typical callback function would look like:
-
-
-
-
-// Callback function for text changed events.
-function nameChanged(event) {
- // implement what happens when the text changed here
-}
-
-
-
-
- Registering the event listener function is done as follows, for
- example right after the control was created:
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_View_Class-GUID-e673fe1a-cf46-46f5-b243-ce7422c69cc5.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_View_Class-GUID-e673fe1a-cf46-46f5-b243-ce7422c69cc5.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,203 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-WRTKit View Class
-
-
-
-
-
-
-WRTKit View Class
-
-
-
-
-Description
-
-
-
-
- The View class is an abstract base class for all views. Views are containers for controls
- and are used to collect the set of controls that constitutes a logical view in a
- widget user interface. The displayed view is controlled by the UIManager. Don't
- instantiate View directly but rather one of its subclasses, e.g. ListView.
-
-
- Retrieves the currently focused control in the view or null if none.
-
-
-
-
-
-Arguments
-
-
-
-
- This method does not take any arguments.
-
-
-
-
-
-Return value
-
-
-
-
- The current focused control or null if none.
-
-
-
-
-
-
-
-
-
-
-
-focusFirstControl()
-
-
-
-
-Syntax
-
-
-
-[Control] View.focusFirstControl(void)
-
-
-
-
-Description
-
-
-
-
- Attempts to focus the first focusable control in the view. Note that
- this method call might fail to actually focus the control in certain
- circumstances, such as when the view is not visible or if no focusable
- control exists.
-
-
-
-
- This method is rarely needed because focus handling is to a high degree
- handled automatically by the user interface toolkit. For example when
- a new view is displayed the first focusable control is automatically
- given focus.
-
-
-
-
-
-Arguments
-
-
-
-
- This method does not take any arguments.
-
-
-
-
-
-Return value
-
-
-
-
- This method does not return a value.
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff -r 716254ccbcc0 -r 7848c135d915 org.symbian.wrttools.doc.WRTKit/html/WRTKit_Views_and_the_UIManager-GUID-f95b4ad6-0e86-4023-8371-3ff2a45e95fe.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Views_and_the_UIManager-GUID-f95b4ad6-0e86-4023-8371-3ff2a45e95fe.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,89 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Views and the UIManager
-
-
-
-
-
-
-Views and the UIManager
-
-
-
-
-
- All WRTKit user interfaces are divided into "views". The concept of
- a view is simply a set of user interface elements, such as buttons,
- textfields, etc., that are hosted in a container. The WRTKit
- architecture defines a contract for views through a base class
- called View and implements a concrete view class called ListView
- that lays out controls vertically. This layout is similar to what is
- commonly used in mobile device user interfaces and is thus
- sufficient for the vast majority of widget user interfaces. However
- the WRTKit allows developers to create their own custom views if
- some other kind of layout is preferred instead. Creating a custom
- view is an advanced topic that isn't covered here, but roughly
- speaking it is a simple matter of creating a subclass of the View
- class (just like ListView) and implementing all the functions that
- the View class defines, plus whatever custom layout the developer
- wants.
-
-
-
-
- Because the ListView uses a vertical list layout for controls,
- adding controls can be done either to the end of the list or by
- inserting before a specified control in the list. There is no need
- to worry about actual control locations, coordinates or anything of
- that sort. The ListViews handles all of this automatically.
-
-
-
-
- In addition to controls, the ListView has a view caption that is
- displayed at the very top of the view. The caption is optional but
- is good to include in order to show what a particular view is about.
- E.g. a view for settings could have a caption "Settings".
-
-
-
Figure 1.
-ListView with caption
-
-
-
-
-
-
-
- Only one view can be visible at any given time, as is common in
- mobile device applications. Views are commanded to be shown using a
- class called UIManager, which attaches the view to the "view root".
- The view root is an HTML element that can be specified to the
- UIManager when it is created, but typically this argument is
- omitted, resulting in the UIManager creating a view root element
- that makes views take up the entire screen.
-
