Tarantella Administration Guide > Applets > registerProperty (X emulator applet)

registerProperty (X emulator applet)

Syntax

void registerProperty(window, property)

Description

The registerProperty method registers an interest a particular X property. You'll need to use this method if you want to use getProperty to retrieve a property's value.

window is the name of the X window whose properties you're interested in. (This name is contained in the X window's WM_NAME X property.) Use an empty string ("") to specify the root window.

property is the name of the X property you want to register. For example, the WM_COMMAND X property contains the command used to start the application that the X window is displaying.

If you're using X properties to communicate between an application and the client device, you'll probably need to write code to run on the client which "polls" a particular X property periodically. In this case, your code will call the getProperty method frequently. Thus, it's important that the getProperty method should not be a slow operation.

Registering properties lets Tarantella cache these properties' value on the client device. These cached values are updated whenever the corresponding X properties change. The getProperty method can now use the cached value rather than querying the application itself -- a much faster operation.

Note If you use the getProperty method to retrieve a property's value without first registering it, getProperty returns null. You don't need to register an X property in order to change its value with the setProperty method.

Once you've finished with a particular X property, you can use the unregisterProperty to tell Tarantella to stop checking for changes in that particular property. This helps keep performance overheads to a minimum.

Examples

<SCRIPT LANGUAGE="JavaScript">

function register() {

   // Register an interest in the X property WM_COMMAND

   var XEmulatorApplet = document.applets["Tarantella X Emulator"];
   XEmulatorApplet.registerProperty("xterm", "WM_COMMAND");
}

function unregister() {

   // Unregister the X property WM_COMMAND

   var XEmulatorApplet = document.applets["Tarantella X Emulator"];
   XEmulatorApplet.unregisterProperty("xterm", "WM_COMMAND");
}

function showProperty() {
   var XEmulatorApplet = document.applets["Tarantella X Emulator"];
   var value = null;

   // Retrieve the value of the X property WM_COMMAND

   value = XEmulatorApplet.getProperty("xterm", "WM_COMMAND");

   // If WM_COMMAND is set, display it value. Otherwise, display an
   // error message.

   if (value != null) {
       alert("The X property WM_COMMAND has the value " + value);
   } else {
       alert("Couldn't access the X property WM_COMMAND");
   }
}

</SCRIPT>

<FORM>
 <INPUT TYPE=button VALUE="Register" onclick="register()">
 <INPUT TYPE=button VALUE="Get Property Value" onclick="showProperty()">
 <INPUT TYPE=button VALUE="Unregister" onclick="unregister()">
</FORM>

This example adds three buttons beneath the X emulator applet:

• The Register button registers the X property WM_COMMAND for the window xterm when a user clicks it.
• The Get Property Value button displays the value of the X property WM_COMMAND when a user clicks it, if the property is currently registered. Otherwise, it displays an error message.
• The Unregister button unregisters the X property when a user clicks it.

Note This example assumes the window name is xterm. You will need to change the code if you're using a different window name.

Add the code to the HTML document containing the X emulator applet (xde.html, in the sco/tta/standard webtop theme), after the TTAAPPLET declaration.