← Back to branch summary

~gdesklets-desklet-team/gdesklets/0.36

« back to all changes in this revision

Viewing changes to doc/book/ctrl-interface.xml

  • Committer: Robert Pastierovic
  • Date: 2007-10-07 10:08:42 UTC
  • Revision ID: pastierovic@gmail.com-20071007100842-fdvp2vzmqgh1j87k
merged 0.3x branch and basic documentation and some other changes

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/book/ctrl-interface.xml
 
1
<section id="ctrl-interface" xmlns:xi="http://www.w3.org/2001/XInclude">
 
2
  <title>Calling by Interface</title>
 
3
 
 
4
<section><title>Interfaces</title>
 
5
 
 
6
  <para>When applets make use of a control, they are interested in its
 
7
    functionality, not its particular implementation. It doesn't matter which
 
8
    control gets loaded as long as the control does exactly what was expected.
 
9
    </para>
 
10
 
 
11
  <para>The functionality is described by <emphasize>interfaces</emphasize>
 
12
    and several implementations of an interface can exist. However, control
 
13
    authors have to make sure that two different implementations of the same
 
14
    interface provide the same functionality.</para>
 
15
 
 
16
</section>
 
17
 
 
18
 
 
19
<section><title>Unique Identifiers</title>
 
20
 
 
21
  <para>To avoid confusion and incompatibility problems, interface identifiers
 
22
    have to be globally unique. You don't have to worry about this requirement,
 
23
    however, because <application>gDesklets</application> takes care about this
 
24
    for you. It determines the identifier for
 
25
    each interface and makes sure that changes in an interface lead to a
 
26
    different unique identifier.</para>
 
27
 
 
28
  <para>The interface identifiers are made up of a human-readable name given
 
29
    by the interface's author, and a random-looking string. That string is
 
30
    based on a checksum of the interface and is affected by all changes to the
 
31
    interface, except for changes in comments.</para>
 
32
 
 
33
  <para>The identifiers might look intimidating at first, but there is no magic
 
34
    behind them and the only occasion when you get into touch with them is when
 
35
    you want to <link linkend="dsp-tag-control">load a control</link> in
 
36
    an applet. In that case, just use copy&amp;paste.</para>
 
37
 
 
38
  <para>Examples for interface identifiers are:</para>
 
39
  <programlisting>
 
40
ICalendar:cfw9o85ptery8egvoff6ijswc
 
41
ISystem:4i4p0jtvdz87qx44x2dm97ltj
 
42
ITime:9y703dqtfnv4w373caserz68r
 
43
  </programlisting>
 
44
 
 
45
  <para>They can be looked up in the
 
46
    <application>gdesklets-shell</application>, or by using the tool
 
47
    <application>test-control.py</application>. There's no need to take care
 
48
    about the identifier while writing a control.</para>
 
49
 
 
50
</section>
 
51
 
 
52
</section>