The Droplets Platform supports server-initiated changes to any part of the application GUI without user intervention. This is one of the main advantages of Droplets, as this allows Droplets UIs to run dynamically without requiring a user "Refresh".

This tutorial shows you how to enable server-side UI updates with the Droplets API. The related topic of desktop alerts is covered in the Writing Desktop Alerts tutorial.

There are two major ways of writing server-side events with Droplets:

• The Client polls the Server at regular intervals for UI updates;
• The Server posts UI updates to the Clients.

Which of these two methods you use depends largely on the circumstances. Polling the Server is usually best for regular, predictable changes like reading a periodically changing database, and allows you to serve large-scale UI updates with a minimum of server-side work. Posting to Clients, on the other hand, is often best when working with unpredictable updates that do not take place at regular intervals like the reading of changing stock prices from a data feed. Regardless, you need not worry about synchronization issues with either one of these alternatives; the Droplets UI Server takes care of this without your intervention.

Polling the Server

Setting up a poll to the Server involves a single call to setPollTime() within your Application object:

Java: Application.setPollTime(int centiseconds);
C++: TDsApplicationClass::SetPollTime(int centiseconds);

The integer argument represents the number of centiseconds (1/100ths of a second) between client polls. So an argument of 100 would cause the client to poll the server every second; 6000 would cause the client to poll every minute.

Once you've set the client to poll, you need to wire a poll listener and account for application behavior in the event of an update. This is accomplished by:

• Creating an implementation of the PollListener interface (Java) or instantiate a TEvEvent::TCb that calls your method (C++). For example,

TEvEvent::TCb::Make(*this, &MyWindow::OnPoll); (C++)

• Adding this PollListener to the application.

Java: Call the Application object's addPollListener() method
C++: GetApplication()->AddPollListener(TEvEvent::TCb::Make(*this, &MyWindow::OnPoll));

• Within the PollListener, defining application behavior in the event of a client poll.

Java: Define this behavior within the PollListener.handleClientPoll()
C++: Define this behavior within MyWindow::OnPoll()

If you want to stop the client polling at any point in your application logic, all you need do is again call setPollTime with an argument of -1:

Java: app.setPollTime(-1);
C++: App->setPollTime(-1);

You can also remove the application's PollListener at any time by calling Application.removePollListener() with your existing PollListener as an argument.

Posting to the Client

An alternate mechanism for delivering server-initiated UI updates is to post them to all clients currently presenting the application's GUI, via the Application object's postEvent() method. This may be more expensive for the UI Server if it requires that thread to poll, but often more efficient than constant client polls when UI updates are unpredictable or intermittent.

In order for the Droplets Platform to ensure the handling of all synchronization issues, you must also always use postEvent to update the GUI in the following two circumstances:

1. You've written your own threads that change the GUI periodically (for example, a thread that periodically changes the application's skin parameters);

2. Your application sessions can alter the GUIs of other sessions (for example, an online Chat application). In that case, use postEvent() on the application that is not handling a user event.

Since the Droplets UI Server takes care of all thread synchronization issues, adding event posts to your applications is a relatively simple matter:

Java

1. Write a function that performs the UI update;
2. Create an inner class that implements Java's Runnable;
3. Use this Runnable implementer's run() method to call the function created in step 1;
4. Instantiate the Runnable class;
5. Call Application.postEvent, with the Runnable instantiation as its argument.

C++

1. Write a function that performs the UI update;
2. Create a class that implements the TDsAppEvent interface
3. Implement the Execute() method of TDsAppEvent to call the function created in step 1
4. Instantiate an object of this class and call TDsApplicationClass::PostEvent with the object as a parameter

These two methods of enabling server-side events should effectively cover any situation in which you would like to post server-initiated updates to the Droplets UI. For more detailed information on working with Client Polling and Server Posting, see the Droplets API for Java and C++.