Alexander Dymo <cloudtemple@mksat.net>
Phil Thompson <phil@river-bank.demon.co.uk>
Revision 1.02.00
Copyright © 2000, 2001 Phil Thompson
Copyright © 2002 Alexander Dymo
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".
Kugar is a template based XML™ report engine. Kugar Report Designer is a flexible GUI report template designer for Kugar report engine.
Table of Contents
- 1. Introduction
- 2. Tutorial
- 3. Starting Kugar and Kugar Report Designer
- 4. Report Template Designer Manual
- 5. Programmer's Guide
- 6. Credits and License
- A. Document Structure
- B. Installation
Introduction
Kugar is a report creation tool for Qt™ and KDE. It includes GUI report template designer, report engine, Konqueror part for easy report preview and a set of examples.
The Kugar Report Designer is a report template creation tool for Kugar report engine. Kugar report engine uses a XML™ based report template file (which can be created by hand or with Kugar Report Designer) and data file (also in XML™ format) to create reports. To get more information on Kugar Report Designer refer to the Report Template Designer Manual.
See The KugarTemplate Document Type Definition for an overview of template's DTD (file format), KugarData Document Type Definition and Tutorial for step-by-step explanation on how reports can be created.
Programmers should also refer to the Programmer's guide to find information about using Kugar in their own applications.
Tutorial
This tutorial attempts to be a brief introduction to Kugar.
You will create a sample report template with Kugar Report Designer, a sample data file and finally generate a complete report.
The source code for sample templates and data files can be found in sample1.kut and sample1.kud that are distributed with Kugar.
Run Kugar Designer by typing kudesigner in the shell.
After you start the designer, choose File|New and set the page size to Letter and paper orientation to Landscape. Set the left and right margins to 48, top and bottom margins to 40. All dimensions in Kugar Report Designer (page margins, sizes, positions, etc.) are set millimeters.
New report is now created and all buttons on the Items Toolbar and Sections Toolbar became now enabled (the corresponding menu items from Items and Sections are enabled too).
Now it is the time to add some sections to the report and determine their sizes. We will add report header and footer, page header and footer and a single detail section. Report headers and footers are printed at the first and last pages of the report before and after any other report data accordingly. Report footers are good places for calculated fields. Page headers and footers are printed at the top and bottom of each page. Our report will have one detail section with level 0. This means that all our data rows has identical structure (i.e. fields). If data structure is more complex or it is organized according to a master-detail relationship, more detail levels should be created. See sample3.kut and sample3.kud for an example of how that can be done. Refer to the template elements descriptions for the additional information.
Sections are added by using Sections menu or a Sections Toolbar. Now add report header and footer, page header and footer and then detail. When adding detail section, set it's level to 0 as shown on the screenshot below.
Our report should look now like this one on the screenshot.
All our sections have a predefined height - 50mm. Let's change it. To do this right mouse button on the Report Header section or click Edit Properties button on the Edit Toolbar and then choose a section. Properties window should be shown.
Now set a Report Header's height to 70. Let's perform that procedure for all other sections. Set Page Header's height to 45 and Detail's to 30. Page and Report Footers should be 32 mm height.
A report template with properly sized sections is ready to be filled with report items.
You can now add items to the sections on the report. Five different types of items can be added to the report. Label is a rectangular area that can have borders and can be filled by any kind of textual data. Text and background colors among with fonts can be changes for Label. Border line types and line colors are also customizable. Field can be placed onto a detail sections. Fields represent data fields, their values will be collected from a data file while generating a report. Counts, sums, averages, etc. for field values can be printed on the report by means of Calculated Fields. Specials are labels with predefined text, such as current date or page number. General report look can be refined with Lines.
To add a report item click the corresponding item button on the Items Toolbar and place (click) it on the section. Choosen item will be placed on the selected section with the upper left corner at the given coordinates. Other properties are set to default values and can be changed with the Report Item Options dialog (the same way we used to change section's height).
So, let's add labels to the report header and page header like shown on the screenshot below. Note, that the “Mutiny Bay Software” label has it's BorderStyle and BorderWidth set to 0 and “Software Inventory Report” - 1mm. Any colors are set as a combination of three values (RGB - red,green,blue) divided by comma.
Add also field elements to the detail section. Just assume, we have four fields - title, version, platform and copies. So, four Field elements should be placed and their Field properties set. Note, that Text property is automatically set to “[field_name]”
Out page footer is a good place to show current date and page number, so add two special fields and set their Type properties to 0 and 1. Special with Type=0 will represent date and one with Type=1 - page number. Note that special's Text property is changed automatically.
The last element to be placed is Calculated Field for “copies” field. To acquire a sum(copies) set calculated field's Field property to “copies” and CalculationType to 1 (sum function).
Finally, our report template should look like this.
Creating the report data file
Generally speaking, data files may be created in several vays. One can use xsl transformation tables to generate proper xml from another xml document (like KSpread spreadsheet), another will use own program to fetch data from a database and fill the data file. In this tutorial we will simply create it by hand. The source code for the example can be found in file sample1.kud or copied from the example below.
<?xml version=“1.0” encoding=“UTF-8”?>
<!DOCTYPE KugarData [
<!ELEMENT KugarData (Row* )>
<!ATTLIST KugarData
Template CDATA #REQUIRED>
<!ELEMENT Row EMPTY>
<!ATTLIST Row
level CDATA #REQUIRED
title CDATA #REQUIRED
version CDATA #REQUIRED
platform CDATA #REQUIRED
copies CDATA #REQUIRED>
]>
<KugarData Template="sample1.kut">
<Row level="0" title=" BRU" version="15.0" platform="x86" copies="1"/>
<Row level="0" title=" Caldera Open Linux" version="2.2" platform="x86" copies="3"/>
<Row level="0" title=" K Desktop" version="1.1.1" platform="x86" copies="1"/>
<Row level="0" title=" Netscape Communicator" version="4.6" platform="x86" copies="10"/>
<Row level="0" title=" Redhat Linux" version="5.0" platform="x86" copies="11"/>
<Row level="0" title=" Redhat Linux" version="5.1" platform="x86" copies="12"/>
<Row level="0" title=" Redhat Linux" version="5.2" platform="x86" copies="14"/>
<Row level="0" title=" Redhat Linux" version="6.0" platform="x86" copies="15"/>
<Row level="0" title=" Star Office" version="5.0" platform="x86" copies="1"/>
<Row level="0" title=" Star Office" version="5.1" platform="x86" copies="3"/>
<Row level="0" title=" Microsoft Windows NT" version="3.1" platform="x86" copies="1"/>
<Row level="0" title=" Microsoft Windows NT" version="3.51" platform="x86" copies="1"/>
<Row level="0" title=" Microsoft Windows NT" version="4.0" platform="x86" copies="1"/>
<Row level="0" title=" Microsoft Windows NT" version="5.0" platform="x86" copies="1"/>
<Row level="0" title=" Sun Solaris" version="2.5" platform="Sparc" copies="1"/>
</KugarData>
Generating report
At this moment we have a report template (sample1.kut) and a report data (sample1.kud).
To generate a report, type following command in the shell: kugar -r sample1.kut -d sample1.kud
This will bring you a Kugar shell window with the report generated.
Starting Kugar and Kugar Report Designer
The Kugar program takes two commandline arguments:
kugar [-d Kugar data file] [-r Kugar template file]
For example, kugar -d sample1.kud -r sample1.kut
The Kugar Report Designer program can be started with no arguments or with a report template file name as an argument:
kudesigner [template.kut]
Report Template Designer Manual
The Kugar Report Designer allows to interactivelly create and modify report templates, place report sections and section items onto a report.
Kugar Report Designer is a WYSIWYG application. Report page size defines the report dimensions on the screen. At the present moment, the scale is set to 100% automatically and can not be changed.
Every report template may contain following report sections:
Report Header
Page Header
Detail Header
Detail
Detail Footer
Page Footer
Report Footer
Report sections may contain following report items:
Label
Field
Calculated Field
Special Field
Line
Report sections and items can be placed onto the report template by using menus or toolbars.
Every element, such as report template, report section or an item has it's own properties. Those properties define geometrical, textual and any other parameters. Every time the element placed, a set of default properties applied. For an example, when Label is placed, it's Text property value is set to “Text”.
To change properties, use Report Item Options dialog. That dialog can be called by right mouse button click on an item or with a Edit Properties button in the Edit Toolbar. See screenshot below (properties for a Field item):
To delete an item, middle mouse button click on it or use Delete button in the Edit Toolbar.
The Kugar Report Designer menu reference
- File->New (Ctrl+N)
Bring the New Report dialog to create a new report template.
As seen on the screenshot, report page size, orientation and margins must be set before the report created.
- File->Open (Ctrl+O)
Open the previously saved report template.
- File->Open Recent
Open the report template from list of recently opened templates.
- File->Save (Ctrl+S)
Save the current report template into a text file in XML™ format.
- File->Save As
Save the current report template into a file and give it another name.
- File->Close (Ctrl+W)
Close the current report template.
- File->Print (Ctrl+P)
Print the current report template as text in XML format.
- File->Quit (Ctrl+Q)
Quit the program.
- Edit->Clear Selection
Cancel any edit action, so no properties will be edited or items deleted.
- Edit->Edit Properties
Edit properties of the selected item.
- Edit->Delete
Delete the selected item.
- Sections->Report Header
Place the Report Header section onto the report template.
- Sections->Page Header
Place the Page Header section onto the report template.
- Sections->Detail Header
Place the Detail Header section onto the report template.
Before placing the section, the Add Detail Header dialog will be shown to specify the detail level. Detail header will be added to the detail section of given level.
- Sections->Detail
Place the Detail section onto the report template.
Before placing the section, the Add Detail dialog will be shown to specify the detail level.
- Sections->Detail Footer
Place the Detail Footer section onto the report template.
Before placing the section, the Add Detail Footer dialog will be shown to specify the detail level. Detail footer will be added to the detail section of given level.
- Sections->Page Footer
Place the Page Footer section onto the report template.
- Sections->Report Footer
Place the Report Footer section onto the report template.
- Items->Clear Selection
Clear item selection, so no report item will be added to the section.
- Items->Label
Place the Label element onto the section.
- Items->Field
Place the Field element onto the section.
- Items->Calculated Field
Place the Calculated Field element onto the section.
- Items->Special Field
Place the Special Field element onto the section.
- Items->Line
Place the Line element onto the section.
Programmer's Guide
There are several ways to use Kugar
Create a temporary file and fill it with data, organized according to the KugarData Document Type Definition. Then call the kugar shell command (
) to preview and print the report. See Using Kugar shell for previewing reports section for a detailed description.kugar [-d Kugar data file] [-r Kugar template file]
Use Kugar directly in the application's code. See Using a Kugar classes for reporting section for a detailed description.
Create a Qt™ designer plugin, use it to build application GUI in the designer and link it to the program dynamically. See Creating Qt™ designer plugin section for a detailed description.
The last two ways are acceptable for Qt™ and KDE developers. But Kugar is designed to be a report generator, independent from a programming language or/and IDE. It uses XML™ format for describing report templates and data files. So any program can produce output in Kugar data file format as described in KugarData DTD or even a report template file format (see KugarTemplate DTD). A Kugar shell (report viewer) can be used to preview and print generated report.
Using Kugar shell for previewing reports
The way to create and preview (print) report is:
Create a report template file with Kugar Report Designer
Create a data file with column values for detail bands of the report. Use KugarData DTD to produce correct data files.
Run Kugar shell to preview and print report. For example, to do this, in c or c++ languages call:
system("kugar -r template_file.kut-d data_file.kud").Don't forget to include stdlib.h.
Using a Kugar classes for reporting
Kugar library includes two widgets for use.
KReportViewer class is designed for KDE developers. It supports a KDE printing system and UNIX® localization via i18n() calls.
MReportViewer class is designed for Qt™ developers and provide real crossplatforming. It can be used not only on UNIX® platforms. but on Windows® and Mac® too.
In order to build program that uses kugar library, it should be linked with libkugar.so shared library, that is provided with kugar distribution on all UNIX® plaforms.
Include files are kugarqt.h and kugar.h for Qt™ and KDE programs accordingly.
For a detailed example of how Kugar classes can be used, see /shell directory in the Kugar sources.
The MReportViewer (and KReportViewer too) contains several public methods that can be used.
void renderReport();
Renders the report onto a screen.
void printReport();
Calls print dialog to print the report.
void clearReport();
Clears the report on a screen and frees report data. Call this before opening the new report.
bool setReportData(data_file_name);
const QString &data_file_name;
Sets report data from data_file_name file.bool setReportData(data_io_device);
const QIODevice &data_io_device;
Sets report data from data_io_device file.
IO device can be any succesor of QIODevice class.
For example, to fetch records directly from the database,
create a QIODevice successor and redefine all nessesary
functionality.
bool setReportTemplate(template_file_name);
const QString &template_file_name;
Sets report template from template_file_name file.bool setReportTemplate(template_io_device);
const QIODevice &template_io_device;
Sets report template from template_io_device file.
IO device can be any succesor of QIODevice class.
For example, to obtail report template from network storage or database,
create a QIODevice successor and redefine all nessesary functionality.
Creating Qt designer plugin
This is the example code of how is designer plugin created. The code below creates plugin for a KDE KReportViewer widget.
If a Qt™ widget is desired, replace KReportViewer to MReportViewer and kugar.h to kugarqt.h in the plugin code.
Designer plugin will allow the usage of Qt™ Designer to place KReportViewer widget onto a window and preview it correctly.
Programs that make use of this plugin must be linked dynamically with it. The corresponding library called libkugar_plugin.so. Widgets or dialogs that include KReportViewer widget must include <kugar.h> in implementation and have a forward declaration of class KReportViewer. Includes can be done with Qt™ Designer's Object Explorer (Source tab).
To build plugin run:
qmake [kugar_plugin.pro]
make
The plugin code consists of three files:
kugar_plugin.h: A header file for KugarWidgetPlugin, QWidgetPlugin successor;
kugar_plugin.cpp: A source file for KugarWidgetPlugin, QWidgetPlugin successor;
kugar_plugin.pro: Project file for QMake utility.
#include <qwidgetplugin.h>>
class KugarWidgetPlugin:public QWidgetPlugin
{
public:
KugarWidgetPlugin ();
QStringList keys () const;
QWidget *create (const QString & classname, QWidget * parent =
0, const char *name = 0);
QString group (const QString &) const;
QIconSet iconSet (const QString &) const;
QString includeFile (const QString &) const;
QString toolTip (const QString &) const;
QString whatsThis (const QString &) const;
bool isContainer (const QString &) const;
};
#include "kugar_plugin.h"
#include <kugar.h>
static const char *kugar_pixmap[] = {
"22 22 127 2",
".d c #000000",
".c c #131313",
".b c #282828",
".a c #434241",
".e c #4e463a",
".# c #595551",
".G c #66553b",
"#F c #68635f",
"#R c #6b4f23",
"#q c #6e6862",
"#M c #6f5229",
".n c #6f6146",
".w c #735310",
".V c #755c2a",
".I c #775f34",
".0 c #77694a",
"#n c #7e6434",
".o c #806f50",
"#C c #835d2d",
".P c #837c75",
"#B c #85653a",
"#k c #85827e",
".x c #866d46",
".U c #877967",
".X c #888888",
".F c #89724d",
"#x c #8b6d2a",
".S c #8d7759",
".z c #8e733b",
"#L c #906e49",
"#Q c #947b56",
".r c #948058",
".J c #957844",
".4 c #987736",
".q c #998969",
".k c #999897",
".R c #9a8a75",
"#i c #9f8348",
"#I c #a37c4b",
".u c #a38d66",
".E c #a58558",
"#A c #a8834b",
".s c #a9967a",
".t c #aa9467",
".C c #ae9f8d",
"#6 c #afa49d",
"#5 c #afa9a4",
"#W c #b18e4d",
".K c #b1935a",
".B c #b39660",
"#V c #b49866",
"#a c #b49d6c",
"## c #b49d72",
".j c #b5b4b4",
"#0 c #b7a597",
".O c #b9b1a9",
".L c #bb9c61",
".M c #bb9e6b",
".A c #bca778",
"#j c #bea46b",
".T c #bfb37d",
".v c #c0b391",
".W c #c3a262",
".i c #c4c4c4",
"#m c #c5b7aa",
"#8 c #c69f80",
".D c #c6b79b",
"#3 c #c7a589",
".7 c #c7a76c",
"#u c #c7bbaf",
".6 c #c8ad74",
"#7 c #c8b7a9",
"#r c #c8beb5",
".m c #c8c8c8",
"#U c #cbad96",
"#f c #ccb681",
"#h c #cdac6c",
"#P c #cdb49f",
"#X c #cdb8a6",
"#H c #ceb7a4",
".y c #ceb892",
".N c #cecac3",
"#Z c #cfb16f",
"#O c #cfbdad",
".Z c #cfc7c0",
"#w c #d0bcab",
".5 c #d1ad6b",
"#s c #d1bfb1",
".h c #d5d5d5",
"#l c #d6cdc6",
"#D c #d8b36e",
".H c #dac592",
"#t c #dbb977",
".g c #dcdcdc",
".1 c #e0dcc1",
".f c #e0e0df",
"#1 c #e3c8b1",
"#S c #e4cdb9",
".3 c #e4d9a3",
"#4 c #e6c1a1",
"#2 c #e7c4a5",
"#K c #e9c179",
"#g c #e9c47e",
"#Y c #e9c8ac",
".2 c #eae6c0",
"#T c #ebcdb3",
".Q c #ebd4b9",
"#E c #ecca87",
"#z c #ecd799",
".l c #ececeb",
"#G c #efd7c2",
"#e c #efe3ab",
".8 c #efe8e3",
"#v c #f1dcca",
"#. c #f2e2d4",
".p c #f4f4f4",
"#y c #f5daa0",
"#J c #f6cf7f",
".9 c #f7ede4",
"#p c #f9d995",
".Y c #fcf9f6",
"#d c #fefcc5",
"#c c #fefdda",
"#b c #fefee1",
"#N c #ffd685",
"#o c #fff0a9",
"Qt c #ffffff",
"QtQtQtQtQtQt.#.a.a.a.b.b.b.c.c.d.d.dQtQtQtQt",
"QtQtQtQtQtQt.e.f.g.g.f.g.g.h.i.j.d.k.dQtQtQt",
"QtQtQtQtQtQt.a.gQtQtQtQtQtQt.l.f.c.m.k.dQtQt",
"QtQtQtQtQt.n.n.n.n.n.o.g.pQtQt.l.bQt.m.k.dQt",
"QtQtQt.q.q.r.q.s.t.r.q.u.u.g.pQt.a.fQt.m.k.d",
"QtQt.s.s.v.w.x.y.y.t.z.A.t.B.i.p.#.a.b.c.d.d",
"Qt.C.C.D.E.F.G.A.H.F.I.J.K.L.M.i.p.l.N.O.P.d",
"Qt.s.v.Q.q.R.S.T.A.R.U.V.L.W.W.X.g.Y.f.Z.k.d",
".0.s.t.Q.1.U.R.2.3.S.U.4.5.6.6.7.j.8.9#..O.d",
".G##.V#a#b.1#c#c#d#e#f#g#h#i#j.W#k#l.9#.#m.d",
".G.4.F#n#c#c#c#d#d#o#p#g.x.w#i.L#q#r#.#.#s.d",
".e.J.J.I.3#d.H#j.6#f#p#t#n.w.E.L#q#u#.#v#w.d",
".G.A#x.z#y#z#A#B#B#C#D#E.4.4.6#h#F#m#v#G#H.d",
".o.s.A#j#E#t#I#I#I#C#A#J#p#p#K#t#F#m#v#G#H.d",
"Qt##.A.6.7#I#I#A.E#L#M.W#N#J#K.a.U#O#G.Q#P.d",
"Qt#a.M.L.J#A#I.4.E#Q.x#R#D#J#g.#.C#S.Q#T#U.d",
"QtQt#V.K.z#Q.s.S.x.S#B#M#W#E.a.U#X.Q#T#Y#U.d",
"QtQtQt.M#i#B.r#Q#Q.r#Q.z#Z.a#q#0#1#T#Y#2#3.d",
"QtQtQtQtQt#j.L.L.W.5#t.a.#.U#0#1#T#Y#2#4#3.d",
"QtQtQtQtQtQt.d#F#q#q#q.P.C#O#S.Q#T#Y#2#4#3.d",
"QtQtQtQtQtQt.d#5#5#6#6#0#7#w#H#P#U#U#3#3#8.d",
"QtQtQtQtQtQt.d.d.d.d.d.d.d.d.d.d.d.d.d.d.d.d"
};
KugarWidgetPlugin::KugarWidgetPlugin ()
{
}
QStringList KugarWidgetPlugin::keys () const
{
QStringList list;
list << "KReportViewer";
return list;
}
QWidget* KugarWidgetPlugin::create (const QString & key, QWidget * parent,
const char *name)
{
if (key == "KReportViewer")
return new KReportViewer (parent, name);
return 0;
}
QString KugarWidgetPlugin::group (const QString & feature) const
{
if (feature == "KReportViewer")
return "Display";
return QString::null;
}
QIconSet KugarWidgetPlugin::iconSet (const QString &) const
{
return QIconSet (QPixmap (kugar_pixmap));
}
QString KugarWidgetPlugin::includeFile (const QString & feature) const
{
if (feature == "KReportViewer")
return "kugar.h";
return QString::null;
}
QString KugarWidgetPlugin::toolTip (const QString & feature) const
{
if (feature == "KReportViewer")
return "Kugar report viewer widget";
return QString::null;
}
QString KugarWidgetPlugin::whatsThis (const QString & feature) const
{
if (feature == "KReportViewer")
return "A widget to view xml reports";
return QString::null;
}
bool KugarWidgetPlugin::isContainer (const QString &) const
{
return FALSE;
}
Q_EXPORT_PLUGIN( KugarWidgetPlugin )
SOURCES += kugar_plugin.cpp HEADERS += kugar_plugin.h DESTDIR = $(QTDIR)/plugins/designer TARGET = kugar_plugin target.path=$$plugins.path isEmpty(target.path):target.path=$$QT_PREFIX/plugins PROJECTNAME = KugarPlugin TEMPLATE = lib CONFIG += qt warn_on release plugin unix:LIBS += -lkugar LANGUAGE = C++
Credits and License
Kugar
Copyright 2000 Mutiny Bay Software
Copyright 2000, 2001, Phil Thompson
Copyright 2002 Alexander Dymo
Portions of the documentation Copyright 2000,2001 Phil Thompson and Copyright 2002 Alexander Dymo
This program is licensed under the terms of the GNU General Public License.
This documentation is licensed under the terms of the GNU Free Documentation License.
Document Structure
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE KugarTemplate [
<!ELEMENT KugarTemplate (ReportHeader, PageHeader, DetailHeader*, Detail*, DetailFooter*, PageFooter, ReportFooter)>
<!ATTLIST KugarTemplate
PageSize CDATA #REQUIRED
PageOrientation CDATA #REQUIRED
TopMargin CDATA #REQUIRED
BottomMargin CDATA #REQUIRED
LeftMargin CDATA #REQUIRED
RightMargin CDATA #REQUIRED>
<!ELEMENT ReportHeader (Line*, Label*, Special*)>
<!ATTLIST ReportHeader
Height CDATA #REQUIRED
PrintFrequency CDATA #REQUIRED>
<!ELEMENT PageHeader (Line*, Label*, Special*)>
<!ATTLIST PageHeader
Height CDATA #REQUIRED
PrintFrequency CDATA #REQUIRED>
<!ELEMENT DetailHeader (Line*, Label*, Special*)>
<!ATTLIST DetailHeader
Height CDATA #REQUIRED
Level CDATA #REQUIRED>
<!ELEMENT Detail (Line*, Label*, Special*, Field*)>
<!ATTLIST Detail
Height CDATA #REQUIRED
Level CDATA #REQUIRED>
<!ELEMENT DetailFooter (Line*, Label*, Special*)>
<!ATTLIST DetailFooter
Height CDATA #REQUIRED
Level CDATA #REQUIRED>
<!ELEMENT PageFooter (Line*, Label*, Special*)>
<!ATTLIST PageFooter
Height CDATA #REQUIRED
PrintFrequency CDATA #REQUIRED>
<!ELEMENT ReportFooter (Line*, Label*, Special*, CalculatedField*)>
<!ATTLIST ReportFooter
Height CDATA #REQUIRED
PrintFrequency CDATA #REQUIRED>
<!ELEMENT Line EMPTY>
<!ATTLIST Line
X1 CDATA #REQUIRED
Y1 CDATA #REQUIRED
X2 CDATA #REQUIRED
Y2 CDATA #REQUIRED
Width CDATA #REQUIRED
Color CDATA #REQUIRED
Style CDATA #REQUIRED>
<!ELEMENT Label EMPTY>
<!ATTLIST Label
Text CDATA #REQUIRED
X CDATA #REQUIRED
Y CDATA #REQUIRED
Width CDATA #REQUIRED
Height CDATA #REQUIRED
BackgroundColor CDATA #REQUIRED
ForegroundColor CDATA #REQUIRED
BorderColor CDATA #REQUIRED
BorderWidth CDATA #REQUIRED
BorderStyle CDATA #REQUIRED
FontFamily CDATA #REQUIRED
FontSize CDATA #REQUIRED
FontWeight CDATA #REQUIRED
FontItalic CDATA #REQUIRED
HAlignment CDATA #REQUIRED
VAlignment CDATA #REQUIRED
WordWrap CDATA #REQUIRED>
<!ELEMENT Field EMPTY>
<!ATTLIST Field
Field CDATA #REQUIRED
Text CDATA #REQUIRED
X CDATA #REQUIRED
Y CDATA #REQUIRED
Width CDATA #REQUIRED
Height CDATA #REQUIRED
BackgroundColor CDATA #REQUIRED
ForegroundColor CDATA #REQUIRED
BorderColor CDATA #REQUIRED
BorderWidth CDATA #REQUIRED
BorderStyle CDATA #REQUIRED
FontFamily CDATA #REQUIRED
FontSize CDATA #REQUIRED
FontWeight CDATA #REQUIRED
FontItalic CDATA #REQUIRED
HAlignment CDATA #REQUIRED
VAlignment CDATA #REQUIRED
WordWrap CDATA #REQUIRED
DataType CDATA #REQUIRED
DateFormat CDATA #REQUIRED
Precision CDATA #REQUIRED
Currency CDATA #REQUIRED
NegValueColor CDATA #REQUIRED
CommaSeparator CDATA #REQUIRED>
<!ELEMENT CalculatedField EMPTY>
<!ATTLIST CalculatedField
CalculationType CDATA #REQUIRED
Field CDATA #REQUIRED
Text CDATA #REQUIRED
X CDATA #REQUIRED
Y CDATA #REQUIRED
Width CDATA #REQUIRED
Height CDATA #REQUIRED
BackgroundColor CDATA #REQUIRED
ForegroundColor CDATA #REQUIRED
BorderColor CDATA #REQUIRED
BorderWidth CDATA #REQUIRED
BorderStyle CDATA #REQUIRED
FontFamily CDATA #REQUIRED
FontSize CDATA #REQUIRED
FontWeight CDATA #REQUIRED
FontItalic CDATA #REQUIRED
HAlignment CDATA #REQUIRED
VAlignment CDATA #REQUIRED
WordWrap CDATA #REQUIRED
DataType CDATA #REQUIRED
DateFormat CDATA #REQUIRED
Precision CDATA #REQUIRED
Currency CDATA #REQUIRED
NegValueColor CDATA #REQUIRED
CommaSeparator CDATA #REQUIRED>
<!ELEMENT Special EMPTY>
<!ATTLIST Special
Type CDATA #REQUIRED
Text CDATA #REQUIRED
X CDATA #REQUIRED
Y CDATA #REQUIRED
Width CDATA #REQUIRED
Height CDATA #REQUIRED
BackgroundColor CDATA #REQUIRED
ForegroundColor CDATA #REQUIRED
BorderColor CDATA #REQUIRED
BorderWidth CDATA #REQUIRED
BorderStyle CDATA #REQUIRED
FontFamily CDATA #REQUIRED
FontSize CDATA #REQUIRED
FontWeight CDATA #REQUIRED
FontItalic CDATA #REQUIRED
HAlignment CDATA #REQUIRED
VAlignment CDATA #REQUIRED
WordWrap CDATA #REQUIRED
DateFormat CDATA #REQUIRED>
]>
KugarTemplate element
The KugarTemplate element defines report attributes relating to page size, orientation, and margins.
<!ELEMENT KugarTemplate (ReportHeader, PageHeader, DetailHeader*, Detail*, DetailFooter*, PageFooter, ReportFooter)> <!ATTLIST KugarTemplate PageSize CDATA #REQUIRED PageOrientation CDATA #REQUIRED TopMargin CDATA #REQUIRED BottomMargin CDATA #REQUIRED LeftMargin CDATA #REQUIRED RightMargin CDATA #REQUIRED>
- Elements
The KugarTemplate element contains the following elements:
- ReportHeader
The ReportHeader element defines report sections that are usually printed at the beginning of the report.
- PageHeader
The PageHeader element defines report sections that are usually printed at the top of every page of the report.
- DetailHeader
The DetailHeader element defines report sections that are printed before details of given level on the report.
- Detail
The Detail element defines the report section that contains the report data. The report can have unlimited number of details.
- DetailFooter
The DetailFooter element defines report sections that are printed after details of given level and below on the report.
- PageFooter
The PageFooter element defines report sections that are usually printed at the end of the every page in the report.
- ReportFooter
The ReportFooter element defines report sections that are usually printed at the end of the report.
- Attributes
- PageSize
Sets the size of the report page. The following values are available:
Value Page Size 0 A4 1 B5 2 Letter 3 Legal 4 Executive 5 A0 6 A1 7 A2 8 A3 9 A5 10 A6 11 A7 12 A8 13 A9 14 B0 15 B1 16 B10 17 B2 18 B3 19 B4 20 B6 21 B7 22 B8 23 B9 24 C5E 25 Comm10E 26 DLE 27 Folio 28 Ledger 29 Tabloid 30 NPageSize - PageOrientation
Sets the report page orientation.
Value Orientation 0 Portrait 1 Landscape - TopMargin
Sets the top margin of the report page.
- BottomMargin
Sets the bottom margin of the report page.
- LeftMargin
Sets the left margin of the report page.
- RightMargin
Sets the right margin of the report page.
KugarTemplate template elements
| Section bands | Section elements |
|---|---|
| ReportHeader | Line |
| PageHeader | Label |
| DetailHeader | Field |
| Detail | CalculatedField |
| DetailFooter | Special |
| PageFooter | |
| ReportFooter |
The ReportHeader and ReportFooter elements define report sections that are usually printed at the beginning and end of the report.
<!ELEMENT ReportHeader (Line*, Label*, Special*)> <!ATTLIST ReportHeader Height CDATA #REQUIRED PrintFrequency CDATA #REQUIRED>
<!ELEMENT ReportFooter (Line*, Label*, Special*, CalculatedField*)> <!ATTLIST ReportFooter Height CDATA #REQUIRED PrintFrequency CDATA #REQUIRED>
The PageHeader and PageFooter elements define report sections that are usually printed on every page of the report.
<!ELEMENT PageHeader (Line*, Label*, Special*)> <!ATTLIST PageHeader Height CDATA #REQUIRED PrintFrequency CDATA #REQUIRED>
<!ELEMENT PageFooter (Line*, Label*, Special*)> <!ATTLIST PageFooter Height CDATA #REQUIRED PrintFrequency CDATA #REQUIRED>
The DetailHeader and DetailFooter elements define report sections that are printed before and after details of given level and below on the report.
<!ELEMENT DetailHeader (Line*, Label*, Special*)> <!ATTLIST DetailHeader Height CDATA #REQUIRED Level CDATA #REQUIRED>
<!ELEMENT DetailFooter (Line*, Label*, Special*)> <!ATTLIST DetailFooter Height CDATA #REQUIRED Level CDATA #REQUIRED>
The Detail element defines the report section that contains the report data. The report can have multiple details, which accessed by detail's Level attribute.
<!ELEMENT Detail (Line*, Label*, Special*, Field*)> <!ATTLIST Detail Height CDATA #REQUIRED Level CDATA #REQUIRED>
- Attributes
- Height
Sets the height of the report section. If you don't want this,section set this value to 0.
- Level
Set the level in hierarchy of the section. Sections with higher levels will be printed before sections with lower ones. Level can be any number begining from 0. This is an attribute from a row element in a data file.
The Line element defines a report object used to draw lines on a report.
<!ELEMENT Line EMPTY>
<!ATTLIST Line
X1 CDATA #REQUIRED
Y1 CDATA #REQUIRED
X2 CDATA #REQUIRED
Y2 CDATA #REQUIRED
Width CDATA #REQUIRED
Color CDATA #REQUIRED
Style CDATA #REQUIRED>
- Attributes
- X1
Sets the starting x coordinate (relative to the section's upper left corner) for the line.
- Y1
Sets the starting y coordinate (relative to the section's upper left corner) for the line.
- X2
Sets the ending x coordinate (relative to the section's upper left corner) for the line.
- Y2
Sets the ending y coordinate (relative to the section's upper left corner) for the line.
- Width
Sets the width of the line.
- Color
Sets the color of the line. The color is defined as an RGB (Red Green Blue) value (r,g,b). r, g and b must be in the range 0..255.
- Style
Sets the drawing style for the line.
Value Line Style 0 No Pen 1 Solid 2 Dash 3 Dot 4 Dash Dot 5 Dash Dot Dot
The Label element defines a report object used to draw fixed text on a report.
<!ELEMENT Label EMPTY>
<!ATTLIST Label
Text CDATA #REQUIRED
X CDATA #REQUIRED
Y CDATA #REQUIRED
Width CDATA #REQUIRED
Height CDATA #REQUIRED
BackgroundColor CDATA #REQUIRED
ForegroundColor CDATA #REQUIRED
BorderColor CDATA #REQUIRED
BorderWidth CDATA #REQUIRED
BorderStyle CDATA #REQUIRED
FontFamily CDATA #REQUIRED
FontSize CDATA #REQUIRED
FontWeight CDATA #REQUIRED
FontItalic CDATA #REQUIRED
HAlignment CDATA #REQUIRED
VAlignment CDATA #REQUIRED
WordWrap CDATA #REQUIRED>
- Attributes
- Text
Sets the label's text.
- X
Sets the x coordinate (relative to the section's upper left corner) for positioning the label.
- Y
Sets the y coordinate (relative to the section's upper left corner) for positioning the label.
- Width
Sets the width of the label.
- Height
Sets the height of the label.
- BackgroundColor
Sets the background color of the label. The color is defined as an RGB (Red Green Blue) value (r,g,b). r, g and b must be in the range 0..255.
- ForegroundColor
Sets the foreground color of the label. The color is defined as an RGB (Red Green Blue) value (r,g,b). r, g and b must be in the range 0..255.
- BorderColor
Sets the border color of the label. The color is defined as an RGB (Red Green Blue) value (r,g,b). r, g and b must be in the range 0..255.
- BorderWidth
Sets the border width for the label.
- BorderStyle
Sets the border style for the label.
Value Border Style 0 None 1 Solid 2 Dash 3 Dot 4 Dash Dot 5 Dash Dot Dot - FontFamily
Sets the font family for the label's text.
- FontSize
Sets the font size for the label's text.
- FontWeight
Sets the font weight for the label's text.
Value Font Weight 25 Light 50 Normal 63 Demi Bold 75 Bold 87 Black - FontItalic
Sets the font italic flag for the label's text.
Value Italic 0 False 1 True - HAlignment
Sets the label's horizontal text alignment.
Value Horizontal Alignment 0 Left 1 Center 2 Right - VAlignment
Sets the label's vertical text alignment.
Value Vertical Alignment 0 Top 1 Middle 2 Bottom - WordWrap
Sets the word wrap flag for the label's text.
Value Word Wrap 0 False 1 True
The Field element defines a report object used to draw data on a report.
<!ELEMENT Field EMPTY>
<!ATTLIST Field
Field CDATA #REQUIRED
Text CDATA #REQUIRED
X CDATA #REQUIRED
Y CDATA #REQUIRED
Width CDATA #REQUIRED
Height CDATA #REQUIRED
BackgroundColor CDATA #REQUIRED
ForegroundColor CDATA #REQUIRED
BorderColor CDATA #REQUIRED
BorderWidth CDATA #REQUIRED
BorderStyle CDATA #REQUIRED
FontFamily CDATA #REQUIRED
FontSize CDATA #REQUIRED
FontWeight CDATA #REQUIRED
FontItalic CDATA #REQUIRED
HAlignment CDATA #REQUIRED
VAlignment CDATA #REQUIRED
WordWrap CDATA #REQUIRED
DataType CDATA #REQUIRED
DateFormat CDATA #REQUIRED
Precision CDATA #REQUIRED
Currency CDATA #REQUIRED
NegValueColor CDATA #REQUIRED
CommaSeparator CDATA #REQUIRED>
- Attributes
- Field
Sets the data field for the object. This is an attribute from row element in a data file.
- Text
Not used.
- X
Sets the x coordinate (relative to the section's upper left corner) for positioning the field.
- Y
Sets the y coordinate (relative to the section's upper left corner) for positioning the field.
- Width
Sets the width of the field.
- Height
Sets the height of the field.
- BackgroundColor
Sets the background color of the field. The color is defined as an RGB (Red Green Blue) value (r,g,b). r, g and b must be in the range 0..255.
- ForegroundColor
Sets the foreground color of the field. The color is defined as an RGB (Red Green Blue) value (r,g,b). r, g and b must be in the range 0..255.
- BorderColor
Sets the border color of the field. The color is defined as an RGB (Red Green Blue) value (r,g,b). r, g and b must be in the range 0..255.
- BorderWidth
Sets the border width for the field.
- BorderStyle
Sets the border style for the field.
Value Border Style 0 None 1 Solid 2 Dash 3 Dot 4 Dash Dot 5 Dash Dot Dot - FontFamily
Sets the font family for the field's text.
- FontSize
Sets the font size for the field's text.
- FontWeight
Sets the font weight for the field's text.
Value Font Weight 25 Light 50 Normal 63 Demi Bold 75 Bold 87 Black - FontItalic
Sets the font italic flag for the field's text.
Value Italic 0 False 1 True - HAlignment
Sets the field's horizontal text alignment.
Value Horizontal Alignment 0 Left 1 Center 2 Right - VAlignment
Sets the field's vertical text alignment
Value Vertical Alignment 0 Top 1 Middle 2 Bottom - WordWrap
Sets the word wrap flag for the field's text.
Value Word Wrap 0 False 1 True - DataType
Sets the field's data type.
Value Data Type 0 String 1 Integer 2 Float 3 Date 4 Currency - DateFormat
Sets the field's date format. For this to work, the format of the date from the data document must be in the format mm/dd/yyyy or mm-dd-yyyy, otherwise the original date format is used. If data type other than date, set to 0.
Value Date Format 0 m/d/yy 1 m-d-yy 2 mm/dd/yy 3 mm-dd-yy 4 m/d/yyyy 5 m-d-yyyy 6 mm/dd/yyyy 7 mm-dd-yyyy 8 yyyy/m/d 9 yyyy-m-d 10 dd.mm.yy 11 dd.mm.yyyy - Precision
Sets the field's numeric precision. If data type other than a numeric type, set to 0.
- Currency
Sets the field's currency symbol If data type other than currency, set to 36 ($). The value is a number representing a Unicode character.
- NegValueColor
Sets the color for negative numeric values. The color is defined as an RGB (Red Green Blue) value (r,g,b). r, g and b must be in the range 0..255. If data is other than a numeric type, set to 255,0,0.
- CommaSeparator
Sets whether commas are used in numeric fields. If data type other than a numeric type, set to 0.
Value Comma Separator 0 False 1 True
The CalculatedField element defines a report object used to draw calculated values on a report.
<!ELEMENT CalculatedField EMPTY>
<!ATTLIST CalculatedField
CalculationType CDATA #REQUIRED
Field CDATA #REQUIRED
Text CDATA #REQUIRED
X CDATA #REQUIRED
Y CDATA #REQUIRED
Width CDATA #REQUIRED
Height CDATA #REQUIRED
BackgroundColor CDATA #REQUIRED
ForegroundColor CDATA #REQUIRED
BorderColor CDATA #REQUIRED
BorderWidth CDATA #REQUIRED
BorderStyle CDATA #REQUIRED
FontFamily CDATA #REQUIRED
FontSize CDATA #REQUIRED
FontWeight CDATA #REQUIRED
FontItalic CDATA #REQUIRED
HAlignment CDATA #REQUIRED
VAlignment CDATA #REQUIRED
WordWrap CDATA #REQUIRED
DataType CDATA #REQUIRED
DateFormat CDATA #REQUIRED
Precision CDATA #REQUIRED
Currency CDATA #REQUIRED
NegValueColor CDATA #REQUIRED
CommaSeparator CDATA #REQUIRED>
- Attributes
- CalculationType
Sets the calculation type for the field.
Value Calculation 0 Count 1 Sum 2 Average 3 Variance 4 Std Deviation - Field
Sets the data field for the object. This is an attribute from row element in a data file.
- Text
Not used.
- X
Sets the x coordinate (relative to the section's upper left corner) for positioning the field.
- Y
Sets the y coordinate (relative to the section's upper left corner) for positioning the field.
- Width
Sets the width of the field.
- Height
Sets the height of the field.
- BackgroundColor
Sets the background color of the field. The color is defined as an RGB (Red Green Blue) value (r,g,b). r, g and b must be in the range 0..255.
- ForegroundColor
Sets the foreground color of the field. The color is defined as an RGB (Red Green Blue) value (r,g,b). r, g and b must be in the range 0..255.
- BorderColor
Sets the border color of the field. The color is defined as an RGB (Red Green Blue) value (r,g,b). r, g and b must be in the range 0..255.
- BorderWidth
Sets the border width for the field.
- BorderStyle
Sets the border style for the field.
Value Border Style 0 None 1 Solid 2 Dash 3 Dot 4 Dash Dot 5 Dash Dot Dot - FontFamily
Sets the font family for the field's text.
- FontSize
Sets the font size for the field's text.
- FontWeight
Sets the font weight for the field's text.
Value Font Weight 25 Light 50 Normal 63 Demi Bold 75 Bold 87 Black - FontItalic
Sets the font italic flag for the field's text.
Value Italic 0 False 1 True - HAlignment
Sets the field's horizontal text alignment.
Value Horizontal Alignment 0 Left 1 Center 2 Right - VAlignment
Sets the field's vertical text alignment.
Value Vertical Alignment 0 Top 1 Middle 2 Bottom - WordWrap
Sets the word wrap flag for the field's text.
Value Word Wrap 0 False 1 True - DataType
Sets the field's data type.
Value Data Type 0 String 1 Integer 2 Float 3 Date 4 Currency - DateFormat
Sets the field's date format. For this to work, the format of the date from the data document must be in the format mm/dd/yyyy or mm-dd-yyyy, otherwise the original date format is used. If data type other than date, set to 0.
Value Date Format 0 m/d/yy 1 m-d-yy 2 mm/dd/yy 3 mm-dd-yy 4 m/d/yyyy 5 m-d-yyyy 6 mm/dd/yyyy 7 mm-dd-yyyy 8 yyyy/m/d 9 yyyy-m-d 10 dd.mm.yy 11 dd.mm.yyyy - Precision
Sets the field's numeric precision. If data type other than a numeric type, set to 0.
- Currency
Sets the field's currency symbol If data type other than currency, set to 36 ($). The value is a number representing a Unicode character.
- NegValueColor
Sets the color for negative numeric values. The color is defined as an RGB (Red Green Blue) value (r,g,b). r, g and b must be in the range 0..255. If data is other than a numeric type, set to 255,0,0.
- CommaSeparator
Sets whether commas are used in numeric fields. If data type other than a numeric type, set to 0.
Value Comma Separator 0 False 1 True
The Special element defines a report object used to draw page numbers and the current date on a report.
<!ELEMENT Special EMPTY>
<!ATTLIST Special
Type CDATA #REQUIRED
Text CDATA #REQUIRED
X CDATA #REQUIRED
Y CDATA #REQUIRED
Width CDATA #REQUIRED
Height CDATA #REQUIRED
BackgroundColor CDATA #REQUIRED
ForegroundColor CDATA #REQUIRED
BorderColor CDATA #REQUIRED
BorderWidth CDATA #REQUIRED
BorderStyle CDATA #REQUIRED
FontFamily CDATA #REQUIRED
FontSize CDATA #REQUIRED
FontWeight CDATA #REQUIRED
FontItalic CDATA #REQUIRED
HAlignment CDATA #REQUIRED
VAlignment CDATA #REQUIRED
WordWrap CDATA #REQUIRED
DateFormat CDATA #REQUIRED>
- Attributes
- Type
Sets the type of special object.
Value Type 0 Current Date 1 Page Number - Text
Not used.
- X
Sets the x coordinate (relative to the section's upper left corner) for positioning the field.
- Y
Sets the y coordinate (relative to the section's upper left corner) for positioning the field.
- Width
Sets the width of the field.
- Height
Sets the height of the field.
- BackgroundColor
Sets the background color of the field. The color is defined as an RGB (Red Green Blue) value (r,g,b). r, g and b must be in the range 0..255.
- ForegroundColor
Sets the foreground color of the field. The color is defined as an RGB (Red Green Blue) value (r,g,b). r, g and b must be in the range 0..255.
- BorderColor
Sets the border color of the field. The color is defined as an RGB (Red Green Blue) value (r,g,b). r, g and b must be in the range 0..255.
- BorderWidth
Sets the border width for the field.
- BorderStyle
Sets the border style for the field.
Value Border Style 0 None 1 Solid 2 Dash 3 Dot 4 Dash Dot 5 Dash Dot Dot - FontFamily
Sets the font family for the field's text.
- FontSize
Sets the font size for the field's text.
- FontWeight
Sets the font weight for the field's text.
Value Font Weight 25 Light 50 Normal 63 Demi Bold 75 Bold 87 Black - FontItalic
Sets the font italic flag for the field's text.
Value Italic 0 False 1 True - HAlignment
Sets the field's horizontal text alignment.
Value Horizontal Alignment 0 Left 1 Center 2 Right - VAlignment
Sets the field's vertical text alignment.
Value Vertical Alignment 0 Top 1 Middle 2 Bottom - WordWrap
Sets the word wrap flag for the field's text.
Value Word Wrap 0 False 1 True - DateFormat
Sets the field's date format. For this to work, the format of the date from the data document must be in the format mm/dd/yyyy or mm-dd-yyyy, otherwise the original date format is used. If data type other than date, set to 0.
Value Date Format 0 m/d/yy 1 m-d-yy 2 mm/dd/yy 3 mm-dd-yy 4 m/d/yyyy 5 m-d-yyyy 6 mm/dd/yyyy 7 mm-dd-yyyy 8 yyyy/m/d 9 yyyy-m-d 10 dd.mm.yy 11 dd.mm.yyyy - Precision
Sets the field's numeric precision. If data type other than a numeric type, set to 0.
KugarData Document Type Definition
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE KugarData [
<!ELEMENT KugarData (Row*)>
<!ATTLIST KugarData
Template CDATA #REQUIRED>
<!ELEMENT Row EMPTY>
<!ATTLIST Row
level CDATA #REQUIRED
col1 CDATA #IMPLIED
col2 CDATA #IMPLIED
... CDATA #IMPLIED
coln CDATA #IMPLIED>
]>
KugarData element
The KugarData element defines a report's data source. The basic structure is a collection of rows and columns. This document does not define data types and their attributes. The report template defines column data type information.
The document creator can apply an XSL™ style sheet to an existing document to convert it to this format. If XSL™ is used, the creator can apply custom macros using XSL™ for column calculations, sorting, etc..
<!ELEMENT KugarData (Row*)>
<!ATTLIST KugarData
Template CDATA #REQUIRED>
<!ELEMENT Row EMPTY>
<!ATTLIST Row
level CDATA #REQUIRED
col1 CDATA #IMPLIED
col2 CDATA #IMPLIED
... CDATA #IMPLIED
coln CDATA #IMPLIED>
The KugarData element contains zero or more Row elements. A Row must contain one level attribute with value corresponding to detail level in the template. Other attributes represent data columns.
The value of the Template attribute is the URL of the report template used to format the data
- Attributes
- level
The attribute value indicates which detail in the report template is used to display data. Rows can contain various column set for various levels, so any attribute except level should be stated as #IMPLIED.
- column
The name of the attribute is the column name, and uses the format as given in the KugarData definition. The attribute name is used in the report template to bind the data to the report fields.
Installation
Kugar is part of the KDE project http://www.kde.org/.
Kugar can be found in the koffice package on ftp://ftp.kde.org/pub/kde/, the main FTP site of the KDE project.
In order to compile and install Kugar on your system, type the following in the base directory of the Kugar distribution:
% ./configure % make % make install
Since Kugar uses autoconf and automake you should have no trouble compiling it. Should you run into problems please report them to the KDE mailing lists.