1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
|
<html lang="en">
<head>
<title>api - TOra</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="TOra">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="extendingtora.html#extendingtora" title="extendingtora">
<link rel="next" href="externalapi.html#externalapi" title="externalapi">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
This manual is for TOra, version 2.1.2+.-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<a name="api"></a>
<p>
Next: <a rel="next" accesskey="n" href="externalapi.html#externalapi">externalapi</a>,
Up: <a rel="up" accesskey="u" href="extendingtora.html#extendingtora">extendingtora</a>
<hr>
</div>
<h3 class="section">5.1 TOra Tool Tutorial</h3>
<p><a name="index-TOra-Tool-Tutorial-39"></a>
This tutorial will create a simple tool that can execute an SQL statement and display it's content in a list. This tutorial assumes you have knowledge of C++ and Qt programming.
<p>First of all we create an include file which defines the tool widget. This is the window that will be displayed when the a tool window is created. How that happens comes later.
<pre class="example"><pre class="verbatim">
#ifndef TOSIMPLEQUERY_H
#define TOSIMPLEQUERY_H
#include "totool.h"
class toResultView;
class QLineEdit;
class toConnection;
class toSimpleQuery : public toToolWidget {
Q_OBJECT
toResultView *Result;
QLineEdit *Statement;
private slots:
void execute(void);
public:
toSimpleQuery(QWidget *parent,toConnection &connection);
};
#endif
</pre>
</pre>
<p>If this file is put in the main TOra source directory the configure script will generate the appropriate moc file which will be needed later. If you don't know what moc is, please go back to the Qt manual to read up on slots and signals.
<p>The rest is pretty straight forward and will be much clearer after we start working our way through the implementation of this tool.
<p>The first thing we need to do is create a tool description which is done by subclassing the toTool class. This is how we implement this class for this function.
<pre class="example"><pre class="verbatim">
#include "totool.h"
#include "tosimplequery.h"
static char * tosimplequery_xpm[] = {
"16 16 3 1",
" c None",
".c #000000",
"+c #FFFFFF",
" ...... ",
" ..++++. ",
" .+.++++. ",
" .++.++++. ",
" .....++++. ",
" .++++++++. ",
" .++++++++. ",
" .++++++++. ",
" .++++++++. ",
" .++++++++. ",
" .++++++++. ",
" .++++++++. ",
" .++++++++. ",
" .++++++++. ",
" .++++++++. ",
" .......... "};
class toSimpleQueryTool : public toTool {
protected:
virtual char **pictureXPM(void)
{ return tosimplequery_xpm; }
public:
toSimpleQueryTool()
: toTool(203,"Simple Query")
{ }
virtual const char *menuItem()
{ return "Simple Query"; }
virtual QWidget *toolWindow(QWidget *parent,toConnection &connection)
{
return new toSimpleQuery(parent,connection);
}
};
static toSimpleQueryTool SimpleQueryTool;
</pre>
</pre>
<p>The first thing that happens is that we include the header file which defines the tool widget and the tool definition header files. Even if this is included in the tosimplequery.h it is good practice not to assume any extra files are included by header files.
<p>Next comes a definition of an xpm pixmap. Normally these are placed in the icons directory and then included into the file as you can see in the TOra source. This is placed inline for clarity.
<p>The next one is the big one. Here we define the tool class which has a few important virtual functions.
<dl>
<dt>‘<samp><span class="samp">pictureXPM</span></samp>’<dd>This function should if defined return a pointer to a xpm definition. This will then be used for toolbar icon, menu icon and tool window icon.
‘<samp><span class="samp">pictureXPM</span></samp>’
<br><dt>‘<samp><span class="samp">menuItem</span></samp>’<dd>Should return a string containing the name of the menu item to add to the tools menu. This is also used for a tip for the toolbar icon by default.
‘<samp><span class="samp">menuItem</span></samp>’
<br><dt>‘<samp><span class="samp">toolWindow</span></samp>’<dd>This function will create a new tool widget and return a pointer to it. It doesn't need to create a widget, then it should then return NULL. Some tools there might only be one per connection for instance.
‘<samp><span class="samp">toolWindow</span></samp>’
</dl>
<p>The number in the constructor is a priority indicator that denote where in the list of tools this tool should be inserted, between each 100 step a separator is inserted into the toolbar and menubar.
<p>And last a not so obvious line where the an instance of the tool descriptor is instantiated. This is a feature that is used a lot in TOra. This will ensure that all tools are registered when the application is started. It also works when using modules, if this is compiled as a module the tool will be instantiated on loading without any hassle with functions with predefined names and such stuff.
<p>Lastly comes the implementation of the tool widget which is not much longer. I have divided this into several parts to simplify explaining them.
<pre class="example"><pre class="verbatim">
#include <list>
#include <qtoolbar.h>
#include <qlabel.h>
#include <qtoolbutton.h>
#include <qlineedit.h>
#include "tosimplequery.h"
#include "toresultview.h"
#include "toparamget.h"
#include "tochangeconnection.h"
#include "tosimplequery.moc"
static char * execute_xpm[] = {
"16 16 3 1",
" c None",
".c #000000",
"+c #0FFE14",
" ",
" ",
" ",
" . ",
" .. ",
" .+. ",
" .++. ",
" .+++. ",
" .+++. ",
" .++. ",
" .+. ",
" .. ",
" . ",
" ",
" ",
" "};
toSimpleQuery::toSimpleQuery(QWidget *main,toConnection &connection)
: toToolWidget(SimpleQueryTool,"simplequery.html",main,connection)
{
QToolBar *toolbar=toAllocBar(this,"Simple Query",connection.description());
QPixmap executePixmap((const char **)execute_xpm);
new QToolButton(executePixmap,
"Execute current statement",
"Execute current statement",
this,SLOT(execute()),
toolbar);
toolbar->setStretchableWidget(new QLabel("",toolbar));
new toChangeConnection(toolbar);
</pre>
</pre>
<p>In this part the parent constructor is called and the toolbar is set up. Also note the inclusion of the moc file which by convention is called tosimplequery.moc. One thing worth noticing here is the toAllocBar which is used to be able to transparently support either using KToolBar or QToolBar depending on whether this is a Qt or KDE application. This is very important since TOra also supports windows to which KDE is not available.
<p>The second part is the setStretchableWidget call which is used to indicate that an empty label should be stretch instead of the tool button which just looks really weird.
<p>Also worth noting is that the toToolWidget class is derived from QVBox so any widgets constructed in this widget will be lined up vertically in the order of creation.
<p>Next up is creating our widgets and connecting them.
<pre class="example"><pre class="verbatim">
Statement=new QLineEdit(this);
Result=new toResultView(this);
connect(Statement,SIGNAL(returnPressed()),this,SLOT(execute()));
}
</pre>
</pre>
<p>This just adds two additional widgets and connect the returnPressed signal to the execute slot. One thing to realise here is that all the toResult children will use the connection of the closest parent of type toToolWidget in the widget hierarchy. And now the last thing to do is implement the execute method.
<pre class="example"><pre class="verbatim">
void toSimpleQuery::execute(void)
{
try {
QString sql=Statement->text();
toQList params=toParamGet::getParam(this,sql);
Result->query(sql,params);
} TOCATCH
}
</pre>
</pre>
<p>The toParamGet::getParam function is used to ask for bind values in the query string. To understand what I mean try executing the query "select :hello from dual" when you try the result. The toQList is simple a list of toQValue which can hold different datatypes and converting between them transparently.
<p>Now finally to compile this module you need to add the tosimplequery.cpp file to SOURCES define in the file Makefile. To build a plugin you also need to add the following line.
<pre class="example"><pre class="verbatim">
plugins/tosimplequery.tso:objs/tosimplequery.o
</pre>
</pre>
<p>This should go among the other plugin definitions and you also need to add the plugins/tosimplequery.tso to the dependencies of tora-plugin.
<p>You must rerun configure for the tosimplequery.moc file to be generated the first time. Any subsequent changes should update the moc file automatically from the Makefile.
<p>Here are the example files in their entire.
<ul>
<li><a href="tosimplequery.h">tosimplequery.h</a>
<li><a href="tosimplequery.cpp">tosimplequery.cpp</a>
</ul>
<p>Hopefully this is a starting point to help you read the rest of the documentation and start cranking out those plugins.
</body></html>
|