[prev in list] [next in list] [prev in thread] [next in thread]
List: koffice-devel
Subject: Re: developers documentation
From: Raphael Langerhorst <raphael-langerhorst () gmx ! at>
Date: 2004-03-04 12:34:26
Message-ID: 200403041334.29704.raphael-langerhorst () gmx ! at
[Download RAW message or body]
Hi all,
I guess it's time for another update, although I wanted to have the part on
general document structure done (basically the kofficecore library) before
resending. But now I want to really well understand this topic before writing
on it... (Sunday?)
what you'll find as attachments:
1x updated Developer Guide in .kwd format (chapter numbering is not saved
in .sxw at the moment)
1x updated Developer Guide in pure text format (UTF8 and UNIX line breaks).
YOU CAN SEND PATCHES/DIFFS AGAINST THIS FILE IF YOU LIKE
1x todo list including some things found in the code while looking it through.
1x patch for a spelling mistake in koApplication.h (in a comment)
... now let's see if I can find all these things on my disk... yes, sure, all
well structured ;)
On Monday 01 March 2004 07:59, Marc Heyvaert wrote:
> .pdf would be nice. I'm reading a lot of my mail at
> work on a windows PC.
you can open the pure text document, it's UTF8 and unix style line breaks.
besides: the pdf I recently exported with OOo was around 80kB - I don't want
to flood the mailing list with that.
currently kivio and krita are not compiling (cvs 4th march, ~ 9 GMT+1):
KDE 3.2.0, Qt 3.2.3, gcc 3.2.3
Regards,
Raphael
["KOffice Development Guide.kwd" (application/x-kword)]
["KOffice Development Guide.txt" (text/plain)]
KOffice Development Guide
<raphael-langerhorst@gmx.at>
KOffice website: http://www.koffice.org
1. Before we start...
So, what does one need to know before he/she can start to work on the KOffice
source code? If you are already familiar with KDE programming you probably don't
need to read this chapter.
1.1. What you should already know before you read on
This document won't teach you C++ or programming in general, it is not in the
scope of this document. All other requirements will be covered in this chapter,
or you will be told where to find the required information.
1.2. Qt - the basis of all
Trolltech AS, the company behind Qt: http://www.trolltech.com
Qt is a library, written in C++. KDE builds on top of this library, so you
should get familiar with it. You don't need to know all about it, but you should
know the basic concepts. Launch "assistant" or go to the doc/html directory of
your compiled Qt library and click on index.html. You can also view the
documentation by visiting http://doc.trolltech.com.
The documentation delivered with Qt should be all you need to understand the
basics. In the Qt Reference Documentation you can choose from many sections. I
would suggest you read everything in "Getting Started". And if you get to the
tutorials please also try to write them yourself, this helps to understand Qt
much better - just writing code yourself. Also understand how Qt enhances the
C++ language.
After having read through all of the "Getting Started" you should at least know
about signals and slots, events, the Qt object model and maybe threads. A lot of
this is covered in the "Overview" section. Of course it depends on what you want
to work on when working on KOffce, but these things you should really know, you
can also learn about more of course - the more the better. If your time allows
write one or the other little application by yourself to get the feeling.
1.3. KDE - the basis of KOffice
The KDE community: http://www.kde.org
KDE is a desktop environment, the "K Desktop Environment" to be precise. It uses
the Qt library as a base and thus already "inherits" a lot of functionality. In
addition to Qt it adds a few additional technologies. To get familiar with these
you should go to the developer site of KDE, http://developer.kde.org, there are
lots of resources for developers. Among these is a book about KDE 2 development.
Don't worry, the technologies haven't changed very much since then, which is
probably a sign for quality. Download it and read whatever you think is of
interest. I would suggest to understand a hello world application in KDE (and of
course also in Qt - but these are very similar anyway). Technologies, which you
should know about are KParts and DCOP. Depending on what you want to do you
don't even need these but it helps to understand the source code of KOffice (and
KDE in general). Try to understand the general working of KDE and the roles of
KParts and DCOP - you will be impressed (at least I was). For your special
interest you might need some other information as well, probably the section
about KDE and CVS. The tutorial section might also be of interest.
1.4. KDevelop - THE integrated development environment
http://www.kdevelop.org
KDevelop is a great IDE for KDE programming and many other things. If you do
extensive programming then you might find the features of KDevelop usefull. You
can "import" a whole KOffice application like KSpread as a project. If you
prefer simple text editors, just take whatever you want, probably KWrite or Kate
- or vi or emacs, it's up to you. Find all information about KDE and KDevelop on
the web pages.
1.5. KBugBuster
Although it's not desireable, every application has bugs as long as it is in
development. In order to keep track of these KDE uses a bug tracking system that
can be accessed through http://bugs.kde.orgor with KBugBuster. KBugBuster
features a nice interface and thus lets you work more efficient than with the
pure web interface (but that's of course my opinion).
1.6. A few other things
1.6.1. Mailing lists
To get in touch with the developers go to the KOffice web site and join the
developer mailing list. Almost everything concerning KOffice development is
handled on this list. If you are also interested in KDE
programming in general you might find the kde-devel mailing list of interest.
Go to http://www.kde.org/mailinglistsfor a list of available mailing lists.
1.6.2. Get the source code
Have a look at the KDE homepage to learn how to get the sourcecode of a KDE
module with CVS. Checkout the KOffice module. You "need" KOffice in such a form
for your work. If this section is out of date and KDE doesn't use CVS (anymore),
it surely uses some other revision control system and you should just get
familiar with that, but a revision control system it will be.
1.6.3. How to get changes committed to CVS
When you have successfully busted a bug or have some general improvement, send a
patch to the development list of KOffice. If you want to know how a patch is
created see the documentation on the KDE developers homepage (KDE 3 Tutorial).
If that's too much then just go to your KOffice directory in a terminal and
issue "cvs diff -u -p > ~/my_patch_for_KOffice.patch"; the -u and -p options
include usefull context information, it is also easier to apply such patches
than patches generated without these options. You can also simply use the
Cervisia mode in Konqueror, note how the Cervisia menus integrate into the rest
of the Konqueror menu. There you will find a menu entry to create a patch (View
-> Difference to Repository). Patches either have the ending .diff or .patch
because of their
When posting the patch on the KOffice developer mailing list, it helps if you
put a [PATCH] at the beginning of the subject line of your email. Please also
describe what the patch changes, otherwise the people on the list might ignore
it and try to keep the patches small at a time so it's easier to see what
changes. Post one patch for every improvement or bug fix so they are easier to
manage.
2. KOffice structure, an overview
KOffice is a composition of many components, from top to bottom as they appear
in KoShell:
KoShell: a global workspace for all components and open documents
Karbon14: vector graphics
Kexi: database frontend
Kivio: flowcharts and other types of diagrams
KPresenter: presentations
KChart: a diagram generator
Krita: image manipulation
KFormula: a formula generator
Kugar: a tool for automated report generation
KSpread: spreadsheets
KWord: word processing
If you have a full installation of KOffice then you can simply launch koshell
and have you should see a list of these "Parts". By clicking on such a part a
new document is created, you can view all open documents by clicking on
"Documents" at the bottom of the parts list.
2.1. Component integration
In many components you can simply integrate other components, like a formula
into KWord or a KWord document into a spreadsheet. Note that KOffice uses an
extended component system compared to standard KParts. Thus it is possible to
integrate other components into their own frames. To check this out create a new
KWord document and integrate a KSpread component or a formula (Insert -> Object
Frame). This component system will be covered soon.
When a component (or an "object frame") is inserted and is activated by double
clicking on it, the menus and toolbars also adapt to the component. So you have
access to all actions you would have in a stand-alone document of the inserted
component. This behaviour is accomplished by the proper interaction between
KoMainWindow, KoDocument and KoView. These can all be found in lib/kofficecore.
A standard KPart integration happens when using KoShell as a workspace for
KOffice components. But you can just as well use the components independently.
All in all this gives you three levels of integration: stand-alone apps (no
integration), embedding into KoShell (using the KParts technology) and embedding
into an other KOffice component (integration provided by KoDocument). That means
great flexibility.
All components are based on core KOffice libraries. We will cover these
libraries first and then the individual components. We will of course find a lot
of common things that are used in many components.
2.2. Applications, Documents and Views
The basic application structure is given by the kofficecore library
(lib/kofficecore).
/** add additional "general structure" information here */
["todos found in KOffice code" (text/x-c++src)]
todos found in code
LIB / KOFFICECORE
koApplication.h:
// Be VERY careful with this. There is no KoApplication when embedded into e.g. konqueror
// Ah well, don't even use it at all, that would be better.
// Next version: remove completely
#define KOAPP ((KoApplication *)KApplication::kApplication())
["koApplication_h_spelling_mistake.patch" (text/x-diff)]
Index: koApplication.h
===================================================================
RCS file: /home/kde/koffice/lib/kofficecore/koApplication.h,v
retrieving revision 1.37
diff -u -3 -p -r1.37 koApplication.h
--- koApplication.h 29 Aug 2003 13:13:33 -0000 1.37
+++ koApplication.h 4 Mar 2004 12:11:54 -0000
@@ -34,7 +34,7 @@ class KoApplicationPrivate;
/**
* Base class for all KOffice apps
*
- * This class handles given arguments giving on the command line and
+ * This class handles arguments given on the command line and
* shows a generic about dialog for all KOffice apps.
*
* In addition it adds the standard directories where KOffice applications
_______________________________________________
koffice-devel mailing list
koffice-devel@mail.kde.org
https://mail.kde.org/mailman/listinfo/koffice-devel
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic