Class

WebTimer

Description

Creates a client-side (browser) timer that executes code based on the time set. This control has no visual user interface but it appears on the Shelf in the Web Page Layout Editor.

Methods

Name

Parameters

Returns

Shared

CallLater

afterMilliseconds As Integer, method As Timer.TimerCallLater

✓

afterMilliseconds As Integer, method As Timer.TimerCallLaterWithValue, value As Variant

✓

Close

ExecuteJavaScript

Script As String

GotoURL

Url As String, inNewWindow As Boolean = False

Reset

UpdateBrowser

Events

Name

Parameters

Returns

Closed

Opening

Run

Enumerations

WebTimer.Locations

Locations

Locations where a timer can run.

Enum

Description

Browser

The timer runs in the web browser.

Server

The timer runs on the server.

WebTimer.RunModes

RunModes

Designates the minimum interval at which a timer can run.

Enum

Description

Multiple

The timer will repeatedly execute the Action event every Period milliseconds. This is the default mode.

Off

The timer will not execute the Action event at all.

Single

Time timer will execute the Action event just once.

Property descriptions

WebTimer.ControlID

ControlID As String

Identifies the control on a per session basis.

This property is read-only.

WebTimer.Enabled

Enabled As Boolean

When True the WebControl is drawn enabled and responds to user action. When False, the control appears as disabled and does not respond to user actions.

In the case of WebTimer, when set to False this disables and stops the WebTimer. When set to True, it starts the WebTimer.

Disable a button when a check box value changes:

If AllowSaveCheckBox.Value Then
  SaveButton.Enabled = True
Else
  AllowSaveButton.Enabled = False
End If

WebTimer.Location

Location As Locations

Indicates where the timer will run. See Locations for details.

You should only set this property in the Inspector for the WebTimer. Changing it in code has no effect.

WebTimer.Name

Name As String

The name of the control.

This property is read-only.

WebTimer.PanelIndex

PanelIndex As Integer

If the control has been placed on a WebTabPanel or WebPagePanel control, this is the panel (page/tab) that the control is on. If the control is not on a panel, it returns -1.

The first panel is numbered zero. If the control has been placed on a panel of a WebTabPanel or WebPagePanel control, it returns the panel number. If the control is not on a WebPagePanel or WebTabPanel, it returns -1. If you change the PanelIndex to a nonexistent panel, the control will disappear until you give it a PanelIndex value that corresponds to a panel that exists.

If you are looking to change the currently selected panel (page/tab), use SelectedPanelIndex.

This code displays the panel index of the control that is on the page.

MessageBox(Me.SelectedPanelIndex.ToString)

WebTimer.Page

Page As WebPage

Identifies the web page that contains the control.

This property is read-only.

WebTimer.Parent

Parent As WebControl

Used to get the control's parent control or page. If the parent control is a WebContainer, then it returns the WebContainer. If it is on a WebPage, it returns the WebPage.

This property is read-only.

WebTimer.Period

Period As Integer

The time (in milliseconds) between executions. The default is 1000 (1 second).

Timers are not precise. For example a value of 1000 will cause the timer to be called about once a second, not precisely every second. Other factors such as OS, the browser and other tasks they may be doing can all affect how often a timer is called. It is possible to set Period to a value that is too low to be reached by the computer that is running the application. In this case the timer will run less often than you might expect.

Periods of less than or equal to zero default to a value of 1 millisecond.

Set the period to so that the timer runs every 5 seconds or so:

Me.Period = 5000

WebTimer.RunMode

RunMode As RunModes

Designates the frequency at which the timer will run.

Sets a timer to run just once:

Timer1.RunMode = WebTimer.RunModes.Single

Method descriptions

WebTimer.CallLater

CallLater(afterMilliseconds As Integer, method As Timer.TimerCallLater)

Used to call a method (without parameters), within the current Session context, once after the specified delay in milliseconds.

CallLater(afterMilliseconds As Integer, method As Timer.TimerCallLaterWithValue, value As Variant)

Used to call a method (with a parameter), within the current Session context, once after the specified delay in milliseconds.

This method is shared.

To pass a parameter to your CallLater method, the method signature must exactly match the WebTimer Delegate signature. Specifically this means that the method must have a single parameter that is of type Variant. No other type will work (even if it can convert to Variant).

Refer to the sample below to see how this is done.

Suppose you want to display some help text for a few seconds and then hide it. You can do this by creating a method to clear a Label (ClearLabel):

Sub ClearLabel
  MyLabel.Text = ""
End Sub

In the initial method, you set the Label help text and then use CallLater to set it to clear it after 2 seconds:

MyLabel.Text = "Help text goes here"
WebTimer.CallLater(2000, AddressOf ClearLabel)

Suppose you want to display some help text for a few seconds and then replace it with different text. You can do this by creating a method that takes the text to display as a parameter (SetLabel). Remember the Delegate method parameter must be of type Variant as shown here:

Sub SetLabel(helpText As Variant)
  MyLabel.Text = helpText
End Sub

In the initial method, you set up the Label help text and use CallLater to change it after 2 seconds:

MyLabel.Text = "First help text goes here"
WebTimer.CallLater(2000, AddressOf SetLabel, "Second help text goes here")

WebTimer.Close

Close

Removes the control from the page.

WebTimer.ExecuteJavaScript

ExecuteJavaScript(Script As String)

Executes the JavaScript passed. The JavaScript passed can call a JavaScript function in a WebPageSource control.

The Xojo web framework uses EcmaScript 6 which is more strict than previous versions of JavaScript. For more details, see the EcmaScript 6 documentation.

This code in the Pressed event of a Button displays an alert using JavaScript:

Me.ExecuteJavaScript("alert('Hello!');")

This code will select the text in a WebTextField (or WebTextArea):

WebTextField1.ExecuteJavascript("document.getElementById('" + _
  WebTextField1.ControlID + "_inner').select();")

WebTimer.GotoURL

GotoURL(Url As String, inNewWindow As Boolean = False)

Opens the passed URL in place of the current web page or downloads a file. If InNewWindow is True, the browser is asked to open the URL in a new window.

If the browser has popup windows disabled and InNewWindow is True, the method silently fails and the page is not shown.

If InNewWindow is False, the running web app is replaced with the specified URL. If you want to display an external web site within your web app, use the WebHTMLViewer control.

Display a web site in a new popup window:

Me.GotoURL("http://www.wikipedia.org", True)

WebTimer.Reset

Reset

Resets the WebTimer and restarts it.

This code restarts the timer:

Timer1.Reset

WebTimer.UpdateBrowser

UpdateBrowser

Forces the current values of the control to be sent to the browser.

This method is useful when you are computing values in a loop and wish to update the browser immediately rather than wait until the current method ends.

This code iterates through a RowSet of database rows, updates a ProgressBar and then forces the updated ProgressBar to be sent to the browser via UpdateBrowser.

ProgressBar1.MaximumValue = SalesData.RowCount
For Each row As DatabaseRow in SalesData
 AnalyzeSales(row)
 ProgressBar1.Value = ProgressBar1.Value + 1
 ProgressBar1.UpdateBrowser
Next

Event descriptions

WebTimer.Closed

Closed

The control has been removed from the browser either because the page has closed or the control's Close method was called.

WebTimer.Opening

Opening

The control has been created and the page is opening but has not been sent to the browser yet.

The Opening event handler can be used to initialize non-visual properties and settings for controls.

In most cases, you should use the Shown event to initialize controls.

WebTimer.Run

Run

Executes each time the Period property elapses.

In the Run event handler, you put the code that you want to run when the Timer period is reached. This example shows the current date and time (including seconds) in a Label each time the timer period is reached:

Label1.Text = DateTime.Now.ToString

Notes

The WebTimer is very similar to the desktop Timer control. The important difference is that the WebTimer is part of the page. As a result, it is controlled from the page, which is on the client side.

A WebTimer can be used to update controls on the page, for example. A regular Timer control will only execute server-side, so it cannot contact the client. If you need to update a control on a page from a regular Timer, consider using the UpdateBrowser method.

Sample code

The WebTimer provides the same functionality as the Desktop Timer control. This example updates the text on a label (SecondsPassedLabel) on the web page using the WebTimer. This code in the WebTimer updates the label:

SecondsPassedLabel.Text = Str(SecondsPassedLabel.Text.ToInteger + 1)

You can also add a button to start and stop the timer. This code is in the WebButton.Pressed event:

If Me.Caption = "Start" Then
  Timer1.RunMode = WebTimer.RunModes.Multiple
  Me.Caption = "Stop" ' button caption
Else
  SecondsPassedLabel.Text = "0"
  Timer1.RunMode = WebTimer.RunModes.Off  ' Turn off the timer
  Me.Caption = "Start"
End If

Compatibility

Web projects on all supported operating systems.

See also

WebControl parent class; Timer, WebView