7.3  Using Controls

7.3.1  Calling by Interface

When calling a control, gDesklets expects an interface identifier. It is up to gDesklets to pick a fitting control for you. But since you're interested in the functionality, not in the particular implementation, you don't have to worry about what you will get.

For example, to call a control which implements the Time interface, you can write:

<control id="myctrl" interface="ITime:9y703dqtfnv4w373caserz68r"/>
  

The id attribute specifies the ID under which you later want to access the control in your applet. Controls are no display elements, thus this ID will not be put into the Dsp namespace, but is directly accessible.

7.3.2  Properties

Controls are property-based. There are properties where you can read from, and properties where you can write to. You can use the gdesklets-shell to look up the available properties of a control and their descriptions.

By setting properties, you can e.g. change the state of a control. Controls can thus be seen as state-machines. Here is an example of using properties:

<display>

  <control id="mytime" interface="ITime:9y703dqtfnv4w373caserz68r"/>

  <label id="lbl1"/>
  <label id="lbl2" relative-to="lbl1, y"/>

  <script>
    mytime.timezone = "Europe/Berlin"
    Dsp.lbl1.value = "Berlin: " + str(mytime.time)

    mytime.timezone = "Asia/Shanghai"
    Dsp.lbl2.value = "Shanghai: " + str(mytime.time)
  </script>

</display>

  

State changes are not permanent and only last until you reload or close the applet. See Preferences for how to save the state of a control across sessions.

7.3.3  Watching Properties

The values of properties can change from time to time. For instance, the time property of the Time control changes its value once a second to reflect the current time.

It would be tedious and resource-consuming to write a loop for polling the properties at regular intervals. Controls can notify you about property changes, so that you just have to bind an action handler to the property itself.

Every control provides the bind(property, handler) method, with which you can bind action handlers to properties. The handler will always be called automatically every time the property's value changes. That way you can watch the properties in which you are interested in. Not all properties support this, though. For some properties it does not make any sense to be watchable.

...

def date_change_handler(new_value):

   print "The date has changed to %d/%d/%d." % new_value


time.bind("date", date_change_handler)

...
  

Your handler function takes one argument which is the new value of the property that is being watched.