<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>Plugin Tutorial</title>
<link href="meego-im.css" rel="stylesheet" type="text/css">
</head><body>
<table>
<tr>
<td></td>
<td>
<a href="index.html">Home</a>
·
<a href="classes.html">API Reference</a>
·
<a href="modules.html">Modules</a>
</td>
</tr>
</table>
<!-- Generated by Doxygen 1.8.5 -->
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Plugin Tutorial </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="intro"></a>
Introduction</h1>
<p>This page is a short tutorial about creating your own input method plugin. MeeGo Touch Input Method provides a framework which developers can extend the functionality of the input method by providing a new input method user interface. The new input method is implemented as a plugin.</p>
<p>This page shows some excerpts from MeeGo Keyboard source code.</p>
<h1><a class="anchor" id="skeleton"></a>
Skeleton</h1>
<p>There are two important parts in the plugin making: the user interface of the input method, which is the part that user interact with while inputting text; and the settings, which is the part that enables user to set preferences on the input method.</p>
<h2><a class="anchor" id="ui"></a>
User interface</h2>
<p>The UI is loaded and controlled by a <a class="el" href="class_m_abstract_input_method.html" title="A base class for input methods. ">MAbstractInputMethod</a> class. </p>
<div class="fragment"><div class="line"><span class="keyword">class </span>MKeyboardHost: <span class="keyword">public</span> <a class="code" href="class_m_abstract_input_method.html">MAbstractInputMethod</a></div>
<div class="line">{</div>
<div class="line"> Q_OBJECT</div>
<div class="line"></div>
<div class="line"> <span class="keyword">public</span>:</div>
<div class="line"> MKeyboardHost(<a class="code" href="class_m_abstract_input_method_host.html">MAbstractInputMethodHost</a> *host, QWidget *mainWindow);</div>
<div class="line"> <span class="keyword">virtual</span> ~MKeyboardHost();</div>
<div class="line"> .....</div>
</div><!-- fragment --><p>The <a class="el" href="class_m_abstract_input_method.html" title="A base class for input methods. ">MAbstractInputMethod</a> itself needs to be loaded by the plugin class, which is a MInputMethodPlugin class. For the plugin system to work, class must declare proper interface using Q_INTERFACES (in the header file) and export the plugin with Q_EXPORT_PLUGIN2 (in the .cpp file):</p>
<div class="fragment"><div class="line"><span class="comment">// The header file:</span></div>
<div class="line"><span class="keyword">class </span>MKeyboardPlugin : <span class="keyword">public</span> QObject, <span class="keyword">public</span> MInputMethodPlugin</div>
<div class="line">{</div>
<div class="line"> Q_OBJECT</div>
<div class="line"> Q_INTERFACES(MInputMethodPlugin)</div>
<div class="line"></div>
<div class="line">public:</div>
<div class="line"> MKeyboardPlugin();</div>
<div class="line"> virtual ~MKeyboardPlugin();</div>
<div class="line"> .....</div>
</div><!-- fragment --> <div class="fragment"><div class="line"><span class="comment">// At the end of the .cpp file:</span></div>
<div class="line">Q_EXPORT_PLUGIN2(meego-keyboard, MKeyboardPlugin)</div>
</div><!-- fragment --><p>The UI class is created in the createInputMethod method:</p>
<div class="fragment"><div class="line"><a class="code" href="class_m_abstract_input_method.html">MAbstractInputMethod</a> *</div>
<div class="line">MKeyboardPlugin::createInputMethod(<a class="code" href="class_m_abstract_input_method_host.html">MAbstractInputMethodHost</a> *host, QWidget *mainWindow)</div>
<div class="line">{</div>
<div class="line"> <a class="code" href="class_m_abstract_input_method.html">MAbstractInputMethod</a> *<a class="code" href="minputmethodhost_8h.html#a410db7aa793210a58ec8e4e1e8f7b4dd">inputMethod</a> = <span class="keyword">new</span> MKeyboardHost(host, mainWindow);</div>
<div class="line"> <span class="keywordflow">return</span> <a class="code" href="minputmethodhost_8h.html#a410db7aa793210a58ec8e4e1e8f7b4dd">inputMethod</a>;</div>
<div class="line">}</div>
</div><!-- fragment --><p>The plugin is given a main window that should be used as a parent widget for plugin visualization. Plugin is then free to create a QWidget or QGraphicsView or similar.</p>
<p>The interaction between the UI and the application is done by employing functions provided by <a class="el" href="class_m_abstract_input_method.html" title="A base class for input methods. ">MAbstractInputMethod</a> and <a class="el" href="class_m_abstract_input_method_host.html" title="Provides an interface for input method instances to connect to the environment. ">MAbstractInputMethodHost</a>.</p>
<h2><a class="anchor" id="settings"></a>
Settings</h2>
<p>Settings is basically a QGraphicsWidget which holds items to provide user to set some preferences or behaviour of the input method. It is displayed in the control panel of the system.</p>
<p>The settings is created by subclassing MAbstractInputMethodSettings. </p>
<div class="fragment"><div class="line"></div>
<div class="line"><span class="keyword">class </span>MKeyboardSettings: <span class="keyword">public</span> QObject, <span class="keyword">public</span> MAbstractInputMethodSettings</div>
<div class="line">{</div>
<div class="line"> Q_OBJECT</div>
<div class="line"></div>
<div class="line"><span class="keyword">public</span>:</div>
<div class="line"> MKeyboardSettings();</div>
<div class="line"> .....</div>
</div><!-- fragment --><p>The actual widget shown is created in MKeyboardSettings::createContentWidget: </p>
<div class="fragment"><div class="line">QGraphicsWidget *MKeyboardSettings::createContentWidget(QGraphicsWidget *parent)</div>
<div class="line">{</div>
<div class="line"> <span class="comment">// the pointer of returned QGraphicsWidget is owned by the caller,</span></div>
<div class="line"> <span class="comment">// so we just always create a new containerWidget.</span></div>
<div class="line"> <span class="keywordflow">return</span> <span class="keyword">new</span> MKeyboardSettingsWidget(<span class="keyword">this</span>, parent);</div>
<div class="line">}</div>
</div><!-- fragment --><h1><a class="anchor" id="compilation"></a>
Compilation</h1>
<p>To use the framework you need to add <code>plugin</code> and <code>meegoimframework</code> to <code>CONFIG</code> variable in your project file. </p>
<div class="fragment"><div class="line">CONFIG += plugin meegoimframework</div>
</div><!-- fragment --><h1><a class="anchor" id="installation"></a>
Installation</h1>
<p>The plugin is installed to <code>/usr/lib/meego-im-plugins</code> directory. Depending on the user interface type, the plugin can be activated programmaticaly by setting the handler GConf key to the name of the plugin. The GConf parent key is <code>/meegotouch/inputmethods/plugins/handler</code>.</p>
<p>During runtime the plugin can be selected from control panel on the system. </p>
</div></div><!-- contents -->
<hr>
<table width="100%" cellspacing="0" border="0"><tr class="address">
<td width="30%" align="left">Copyright © 2011 Nokia Corporation</td>
<td width="40%" align="center" class="generator"><!-- Generated on Sat Nov 2 2013 03:50:25<br>Doxygen 1.8.5 --></td>
<td width="30%" align="right"><div align="right">Maliit</div></td>
</tr></table>
</body>
</html>
