1
<!-- If you want to validate or edit this document separately, uncomment
5
<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd">
9
<chapter id="prog-guide">
10
<title>Programmer's Guide</title>
12
<sect1 id="how-to-use-in-progs">
13
<title>How to use &kugar; for reporting in own programs</title>
16
<title>There are several ways to use &kugar;</title>
19
Create a temporary file and fill it with data, organized according to the
20
<link linkend="kugardata-dtd">KugarData Document Type Definition</link>. Then
21
call the <command>kugar</command> shell command (
23
<command>kugar</command>
25
<option>-d <replaceable>Kugar data file</replaceable></option>
28
<option>-r <replaceable>Kugar template file</replaceable></option>
31
) to preview and print the report.
32
See <link linkend="prog-using-for-preview">Using &kugar; shell for previewing reports</link>
33
section for a detailed description.
38
Use &kugar; directly in the application's code.
39
See <link linkend="prog-using-widget">Using a &kugar; classes for reporting</link>
40
section for a detailed description.
45
Create a &Qt; designer plugin, use it to build application &GUI; in the designer and
46
link it to the program dynamically.
47
See <link linkend="prog-designer-plugin">Creating &Qt; designer plugin</link>
48
section for a detailed description.
53
<para> The last two ways are acceptable for &Qt; and &kde; developers.
54
But &kugar; is designed to be a report generator, independent from a
55
programming language or/and <acronym>IDE</acronym>. It uses &XML;
56
format for describing report templates and data files. So any program
57
can produce output in &kugar; data file format as described in <link
58
linkend="kugardata-dtd">KugarData <acronym>DTD</acronym></link> or
59
even a report template file format (see <link
60
linkend="template-dtd">KugarTemplate <acronym>DTD</acronym></link>).
61
A &kugar; shell (report viewer) can be used to preview and print
62
generated report. </para>
66
<sect1 id="prog-using-for-preview">
67
<title>Using &kugar; shell for previewing reports</title>
70
<title>The way to create and preview (print) report is:</title>
73
Create a report template file with &kudesigner;
78
Create a data file with column values for detail bands of the report.
79
Use <link linkend="kugardata-dtd">KugarData <acronym>DTD</acronym></link> to produce correct data files.
84
Run &kugar; shell to preview and print report. For example, to do this, in c or c++
85
languages call:</para>
88
<function>system(<option>"kugar -r <replaceable>template_file.kut</replaceable>-d <replaceable>data_file.kud</replaceable>"</option>)</function>.
92
Don't forget to include <filename class="headerfile">stdlib.h</filename>.
98
<sect1 id="prog-using-widget">
99
<title>Using a &kugar; classes for reporting</title>
101
&kugar; library includes two widgets for use.
104
<classname>KReportViewer</classname> class is designed for &kde;
105
developers. It supports a &kde; printing system and &UNIX; localization
106
via <function>i18n()</function> calls.
109
<classname>MReportViewer</classname> class is designed for &Qt;
110
developers and provide real crossplatforming. It can be used not
111
only on &UNIX; platforms. but on &Windows; and &Mac; too.
114
In order to build program that uses kugar library, it should be linked
115
with <filename>libkugar.so</filename> shared library, that is provided with kugar distribution on all
119
Include files are <filename>kugarqt.h</filename> and <filename>kugar.h</filename>
120
for &Qt; and &kde; programs accordingly.
122
<para>For a detailed example of how &kugar; classes can be used, see <filename class="directory">/shell</filename>
123
directory in the &kugar; sources.
126
The <classname>MReportViewer</classname> (and <classname>KReportViewer</classname> too)
127
contains several public methods that can be used.
131
<funcdef>void <function>renderReport</function></funcdef>
134
<funcsynopsisinfo>Renders the report onto a screen.</funcsynopsisinfo>
139
<funcdef>void <function>printReport</function></funcdef>
142
<funcsynopsisinfo>Calls print dialog to print the report.</funcsynopsisinfo>
147
<funcdef>void <function>clearReport</function></funcdef>
150
<funcsynopsisinfo>Clears the report on a screen and frees report data.
151
Call this before opening the new report.</funcsynopsisinfo>
156
<funcdef>bool <function>setReportData</function></funcdef>
157
<paramdef>const QString &<parameter>data_file_name</parameter></paramdef>
159
<funcsynopsisinfo>Sets report data from <replaceable>data_file_name</replaceable> file.</funcsynopsisinfo>
164
<funcdef>bool <function>setReportData</function></funcdef>
165
<paramdef>const QIODevice &<parameter>data_io_device</parameter></paramdef>
167
<funcsynopsisinfo>Sets report data from <replaceable>data_io_device</replaceable> file.
168
IO device can be any succesor of <classname>QIODevice</classname> class.
169
For example, to fetch records directly from the database,
170
create a <classname>QIODevice</classname> successor and redefine all nessesary
177
<funcdef>bool <function>setReportTemplate</function></funcdef>
178
<paramdef>const QString &<parameter>template_file_name</parameter></paramdef>
180
<funcsynopsisinfo>Sets report template from <replaceable>template_file_name</replaceable> file.</funcsynopsisinfo>
185
<funcdef>bool <function>setReportTemplate</function></funcdef>
186
<paramdef>const QIODevice &<parameter>template_io_device</parameter></paramdef>
188
<funcsynopsisinfo>Sets report template from <replaceable>template_io_device</replaceable> file.
189
IO device can be any succesor of <classname>QIODevice</classname> class.
190
For example, to obtail report template from network storage or database,
191
create a QIODevice successor and redefine all nessesary functionality.
197
<sect1 id="prog-designer-plugin">
198
<title>Creating &Qt; designer plugin</title>
201
This is the example code of how is designer plugin created. The code below creates plugin for
202
a &kde; <classname>KReportViewer</classname> widget.
207
widget is desired, replace <classname>KReportViewer</classname> to
208
<classname>MReportViewer</classname> and <filename>kugar.h</filename> to
209
<filename>kugarqt.h</filename> in the plugin code.
212
<sect2 id="plugin-usage">
213
<title>Plugin usage</title>
215
Designer plugin will allow the usage of &Qt; Designer to place <classname>KReportViewer</classname>
216
widget onto a window and preview it correctly.
220
Programs that make use of this plugin must be linked dynamically with it.
221
The corresponding library called <filename>libkugar_plugin.so</filename>.
222
Widgets or dialogs that include <classname>KReportViewer</classname>
223
widget must include <kugar.h> in implementation and have a forward declaration
224
of <classname>class KReportViewer</classname>. Includes can be done with &Qt;
225
Designer's Object Explorer (Source tab).
231
<command>qmake</command>
232
<arg>kugar_plugin.pro</arg>
235
<command>make</command>
241
<sect2 id="plugin-code">
242
<title>Plugin code</title>
245
<title>The plugin code consists of three files:</title>
246
<segtitle><link linkend="plugin-h-source">kugar_plugin.h</link></segtitle>
247
<segtitle><link linkend="plugin-cpp-source">kugar_plugin.cpp</link></segtitle>
248
<segtitle><link linkend="plugin-pro-source">kugar_plugin.pro</link></segtitle>
250
<seg>A header file for <classname>KugarWidgetPlugin</classname>, <classname>QWidgetPlugin</classname> successor;</seg>
251
<seg>A source file for <classname>KugarWidgetPlugin</classname>, <classname>QWidgetPlugin</classname> successor;</seg>
252
<seg>Project file for <application>QMake</application> utility.</seg>
256
<sect3 id="plugin-h-source">
257
<title>kugar_plugin.h</title>
260
#include <qwidgetplugin.h>>
262
class KugarWidgetPlugin:public QWidgetPlugin
265
KugarWidgetPlugin ();
267
QStringList keys () const;
268
QWidget *create (const QString & classname, QWidget * parent =
269
0, const char *name = 0);
270
QString group (const QString &) const;
271
QIconSet iconSet (const QString &) const;
272
QString includeFile (const QString &) const;
273
QString toolTip (const QString &) const;
274
QString whatsThis (const QString &) const;
275
bool isContainer (const QString &) const;
281
<sect3 id="plugin-cpp-source">
282
<title>kugar_plugin.cpp</title>
285
#include "kugar_plugin.h"
286
#include <kugar.h>
288
static const char *kugar_pixmap[] = {
417
"QtQtQtQtQtQt.#.a.a.a.b.b.b.c.c.d.d.dQtQtQtQt",
418
"QtQtQtQtQtQt.e.f.g.g.f.g.g.h.i.j.d.k.dQtQtQt",
419
"QtQtQtQtQtQt.a.gQtQtQtQtQtQt.l.f.c.m.k.dQtQt",
420
"QtQtQtQtQt.n.n.n.n.n.o.g.pQtQt.l.bQt.m.k.dQt",
421
"QtQtQt.q.q.r.q.s.t.r.q.u.u.g.pQt.a.fQt.m.k.d",
422
"QtQt.s.s.v.w.x.y.y.t.z.A.t.B.i.p.#.a.b.c.d.d",
423
"Qt.C.C.D.E.F.G.A.H.F.I.J.K.L.M.i.p.l.N.O.P.d",
424
"Qt.s.v.Q.q.R.S.T.A.R.U.V.L.W.W.X.g.Y.f.Z.k.d",
425
".0.s.t.Q.1.U.R.2.3.S.U.4.5.6.6.7.j.8.9#..O.d",
426
".G##.V#a#b.1#c#c#d#e#f#g#h#i#j.W#k#l.9#.#m.d",
427
".G.4.F#n#c#c#c#d#d#o#p#g.x.w#i.L#q#r#.#.#s.d",
428
".e.J.J.I.3#d.H#j.6#f#p#t#n.w.E.L#q#u#.#v#w.d",
429
".G.A#x.z#y#z#A#B#B#C#D#E.4.4.6#h#F#m#v#G#H.d",
430
".o.s.A#j#E#t#I#I#I#C#A#J#p#p#K#t#F#m#v#G#H.d",
431
"Qt##.A.6.7#I#I#A.E#L#M.W#N#J#K.a.U#O#G.Q#P.d",
432
"Qt#a.M.L.J#A#I.4.E#Q.x#R#D#J#g.#.C#S.Q#T#U.d",
433
"QtQt#V.K.z#Q.s.S.x.S#B#M#W#E.a.U#X.Q#T#Y#U.d",
434
"QtQtQt.M#i#B.r#Q#Q.r#Q.z#Z.a#q#0#1#T#Y#2#3.d",
435
"QtQtQtQtQt#j.L.L.W.5#t.a.#.U#0#1#T#Y#2#4#3.d",
436
"QtQtQtQtQtQt.d#F#q#q#q.P.C#O#S.Q#T#Y#2#4#3.d",
437
"QtQtQtQtQtQt.d#5#5#6#6#0#7#w#H#P#U#U#3#3#8.d",
438
"QtQtQtQtQtQt.d.d.d.d.d.d.d.d.d.d.d.d.d.d.d.d"
441
KugarWidgetPlugin::KugarWidgetPlugin ()
445
QStringList KugarWidgetPlugin::keys () const
448
list << "KReportViewer";
452
QWidget* KugarWidgetPlugin::create (const QString & key, QWidget * parent,
455
if (key == "KReportViewer")
456
return new KReportViewer (parent, name);
460
QString KugarWidgetPlugin::group (const QString & feature) const
462
if (feature == "KReportViewer")
464
return QString::null;
467
QIconSet KugarWidgetPlugin::iconSet (const QString &) const
469
return QIconSet (QPixmap (kugar_pixmap));
472
QString KugarWidgetPlugin::includeFile (const QString & feature) const
474
if (feature == "KReportViewer")
476
return QString::null;
479
QString KugarWidgetPlugin::toolTip (const QString & feature) const
481
if (feature == "KReportViewer")
482
return "Kugar report viewer widget";
483
return QString::null;
486
QString KugarWidgetPlugin::whatsThis (const QString & feature) const
488
if (feature == "KReportViewer")
489
return "A widget to view xml reports";
490
return QString::null;
493
bool KugarWidgetPlugin::isContainer (const QString &) const
498
Q_EXPORT_PLUGIN( KugarWidgetPlugin )
502
<sect3 id="plugin-pro-source">
503
<title>kugar_plugin.pro</title>
506
SOURCES += kugar_plugin.cpp
507
HEADERS += kugar_plugin.h
509
DESTDIR = $(QTDIR)/plugins/designer
510
TARGET = kugar_plugin
512
target.path=$$plugins.path
513
isEmpty(target.path):target.path=$$QT_PREFIX/plugins
514
PROJECTNAME = KugarPlugin
516
CONFIG += qt warn_on release plugin