vcs.maemo.org Git - mdictionary/blob - devhowto.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-type" content="text/html; charset=iso-8859-2">
   5 <title>WhiteStork Multilingual Dictionary</title>
   6 <link rel="Stylesheet" type="text/css" href="./css/style.css">
   7 </head>
   8 <body>
   9 <table id="top">
  10 <tr><td colspan="2"><center><img src="./images/label2.png"></center></td></tr>
  11 <tr>
  12         <td id="left_border">&nbsp;</td>
  13         <td id="center">
  14                 <table id="body">
  15                 <tr>
  16                         <td id="left">
  17                                 <table class="menu">
  18                                 <tr><th>Menu</th></tr>
  19                                 <tr>
  20                                         <td>
  21                                                 <a href="index.html">About</a><br>
  22                                                 <a href="licence.html">Licence</a><br>
  23                                                 <a href="howto.html">How to...</a><br>
  24                                                 <a href="devhowto.html">For developers</a><br>
  25                                                 <a href="faq.html">FAQ</a><br>
  26                                                 <a href="http://mdictionary.garage.maemo.org/userguide/" target="blank">User Guide</a><br>
  27                                                 <a href="screen.html">Screenshots</a><br>
  28                                                 <a href="download.html">Download</a><br>
  29                                                 <a href="contact.html">Contact us</a><br>
  30                                         </td>
  31                                 </tr>
  32                                 <tr><th class="footer">&nbsp;</th></tr>
  33                                 </table>
  34                                 <br>
  35                                 <br>
  36                         </td>
  37                         <td id="content">
  38                                 <table class="menu">
  39                                 <tr><th>&nbsp;</th></tr>
  40                                 <tr>
  41
  42                                         <td class="content">
  43 <div class="faq_title">Developer's HOWTO: making Your own GUI for mDictionary</div>
  44 <p><b>mDictionary</b> is intended to be as modifiable as possible. So apart from developing Your own dictionary engines, You can also create alternative user interface, should You find ours inattractive. For the intrepid ones, I have described how to do that. In this howto, I am going to explain how to communicate GUI with the engines's manager</p>
  45
  46 <p>The only header file You need to include in Your GUI is <func>ws_dbus.h</func>. It contains all the functions necessary to communicate with the engines manager. The header file is available from our svn repository at <a href="https://garage.maemo.org">https://garage.maemo.org</a>.</p>
  47 <p>Firstly, You initialize our dbus wrapper library with <func>ws_dbus_create</func> function. You have to specify the name and the version of Your app and store the function's return value as it is necessary for further dbus wrapper communication.</p>
  48
  49 <div class="code">dbus_data = ws_dbus_create ("WhiteStorkGui", "v1.0");</div>
  50 <p>
  51 Then You configure the remote and local addresses, by using <func>ws_dbus_config</func>. The settings should be the same as in the example, below:
  52 </p>
  53 <div class="code">ws_dbus_config (dbus_data,
  54                 WS_DBUS_CONFIG_SERVICE,
  55                 "org.maemo.WhiteStorkGui");
  56 ws_dbus_config (dbus_data,
  57                 WS_DBUS_CONFIG_OBJECT,
  58                 "/org/maemo/WhiteStorkGui");
  59 ws_dbus_config (dbus_data,
  60                 WS_DBUS_CONFIG_IFACE,
  61                 "org.maemo.WhiteStorkGui");
  62 ws_dbus_config (dbus_data,
  63                 WS_DBUS_CONFIG_REMOTE_SERVICE,
  64                 "org.maemo.WhiteStorkManager");
  65 ws_dbus_config (dbus_data,
  66                 WS_DBUS_CONFIG_REMOTE_OBJECT,
  67                 "/org/maemo/WhiteStorkManager");
  68 ws_dbus_config (dbus_data,
  69                 WS_DBUS_CONFIG_REMOTE_IFACE,
  70                 "org.maemo.WhiteStorkManager");
  71 </div>
  72 <p>
  73 Now You have to call the <func>ws_dbus_connect</func> function. It's an opaque function, which allows local methods to be run remotely.
  74 </p>
  75 <div class="code">ws_dbus_connect (dbus_data);</div>
  76 <p>
  77 The only thing that's left now is specifying callback functions (with <func>ws_dbus_set_cb</func>), which are to be called
  78 whenever the manager calls a remote method.
  79 </p>
  80 <div class="code">ws_dbus_set_cb (dbus_data,
  81                 "return_words",
  82                 ws_gui_dbus_return_words,
  83                 ws_gui_app);
  84 </div>
  85
  86 <p>Callbacks definition:</p>
  87
  88 <div class="code">void ws_gui_dbus_return_words (GError *error, GArray *words, gpointer user_data);</div>
  89 <p>
  90 <div class="faq_question">
  91 Accessing received data inside a callback handling function:
  92 </div>
  93 </p>
  94 In this case, words is a <func>GArray</func> of <func>osso_rpc_t</func> values. To access the contents of an osso_rpc_t variable, You first have to check its type by accessing the type field. The value field is an union of primitives. Depending on the type, You should read the value by accessing a proper field. Here is an example:
  95
  96 <div class="code">int i;
  97 osso_rpc_t data;
  98 for (i = 0; i < words->len; ++i)
  99 {
 100
 101         data = g_array_index (words, osso_rpc_t, 0);
 102         if (data.type == DBUS_TYPE_STRING)
 103
 104         {
 105                 char *tmp_word = g_strdup(data.value.s);
 106         };
 107
 108 };
 109 </div>
 110 <div class="faq_question">
 111 <p>
 112 Calling remote methods on manager:
 113 </p>
 114 </div>
 115 <div class="code">ws_dbus_client_find_word (ws_gui_app->dbus_data, word);</div>
 116 <p>
 117 All functions containing the word client in their name, should be called from the GUI application.
 118
 119 Please refer to dbus wrapper API documentation for further info. It can be generated by issuing <func>make docs</func>
 120 command in dbus wrapper source directory.
 121 </p>
 122 </td>
 123                                 </tr>
 124                                 <tr><th class="footer">&nbsp;</th></tr>
 125                                 </table>
 126                         </td>
 127                 </tr>
 128                 <tr><td colspan="2" id="footer_border">&nbsp;</td></tr>
 129                 <tr><td colspan="2" id="footer">&copy; 2006 <a href="#top">WhiteStork Multilingual Dictionary</a></td></tr>
 130                 </table>
 131         </td>
 132         <td id="right_border">&nbsp;</td>
 133 </tr>
 134 </table>
 135
 136 </body>
 137 </html>