libs/main/Mainpage.dox

0001 /**
0002  * \mainpage Calligra Core library called: 'KoMain'
0003  *
0004  * The "KoMain" library provides the basic model-view implementation for
0005  * Calligra applications. It is not the base library for all Calligra libraries,
0006  * but the base library for applications.
0007  *
0008  * Some frequently asked questions and answers:
0009 -------------------------------------------------------------------------
0010 | This document answers some questions about how the startup of Calligra
0011 | applications works. This file was put together by
0012 | Eric R. Turner <eric.r.turner@bitbreather.com>
0013 | from the answers given by David Faure <faure@kde.org>
0014 -------------------------------------------------------------------------
0015
0016 Q: Where is the pointer to the application's instance of KAboutData
0017 data stored?
0018
0019 A: In a static member of the KCmdLineArgs class.
0020
0021
0022
0023 Q: One of the arguments to KAboutData's constructor is the program
0024 name. Will this be used later to run the program?
0025
0026 A: No (by the time the KAboutData's constructor is called, the program
0027 is already running). The program name is in fact the "instance name",
0028 which is used to locate the application's own data
0029 (/share/apps/\<application name\>/...) and many other things.
0030
0031
0032
0033 Q: What is the "+[file]" option passed to KCmdLineArgs?
0034
0035 A: KCmdLineOptions describe the KCmdLineArgs. "+[file]" means that the
0036 command line arguments can be one or more file names, and that these
0037 arguments are optional.
0038
0039
0040
0041 Q: What is I18N_NOOP()?
0042
0043 A: I18N_NOOP() marks the options description for translation to other
0044 languages.
0045
0046
0047
0048 Q: What is a KoApplicationInterface used for?
0049
0050 A: It allows a Calligra application to participate in Inter-Process
0051 Communication and Remote Procedure Calls via DCOP.
0052
0053
0054
0055 Q: What is the .desktop file?
0056
0057 A: It's responsible for the menu entry, standard KDE stuff. In Calligra
0058 we add a few useful tags to it, in particular the "native mime type"
0059 of the component (e.g. application/vnd.oasis.opendocument.text for Calligra Words).
0060
0061
0062
0063 Q: Is the .desktop file generated by hand?
0064
0065 A: Yes.
0066
0067
0068
0069 Q: What's a KoDocumentEntry? I couldn't find it in lib/calligracore.
0070
0071 A: KoDocumentEntry describes a Calligra component (i.e. it's a
0072 representation in memory of the data contained in the .desktop
0073 file). It's in calligracore/koQueryTrader.h.
0074
0075
0076
0077 Q: Is the show() method of KoMainWindow where the application actually
0078 appears to the user?
0079
0080 A: Yes.
0081
0082
0083
0084 Q: How does KoMainWindow->show() bring up the correct application (how
0085 does it know we want to show one app or another)?
0086
0087 A: The KoMainWindow is the same for all. But KoDocumentEntry was
0088 created from specific application data, and koQueryTrader klopens the
0089 library containing this component. The very same mechanism is used to
0090 1) embed other components inside the app, 2) create any kind of
0091 calligra document, e.g. in koshell. All the Calligra applications are in
0092 fact very small wrappers that simply dlopen their own compnent - with
0093 the code in calligracore, which can also dlopen ANY component.
0094
0095
0096
0097 Q: The KoApplication object doesn't store pointers to the KoDocument
0098 nd KoMainWindow objects. Do these objects communicate with each other
0099 later on, and if so, is that done through DCOP?
0100
0101 A: The KoMainWindow knows about the KoDocument[s] inside it. The
0102 KoMainWindows are in a static linked list, if one really wants to
0103 iterateover all windows in the application, but this is rarely needed.
0104
0105
0106 Q: How does KoMainWindow relate to KoDocument and KoView?
0107
0108 A: Calligra applications reimplement KoDocument and KoView. But the
0109 KoMainWindow is the same class for all, since it doesn't have any
0110 app-specific stuff. It's GUI, i.e. menus and toolbars, are provided by
0111 1) itself (the standard stuff like the File and Help menus), 2) the
0112 document's actions, and 3) the view's actions.
0113
0114
0115
0116 Q: How do KoDocument and KoView relate to each other?
0117
0118 A: KoDocument can have one or more KoViews, which allows the user to
0119 have multiple views of the same document. In a single KoMainWindow
0120 this might be accomplished using the "split view" feature. KoView[s]
0121 of the same document can be in separate KoMainWindow[s].
0122
0123  */
0124
0125 // DOXYGEN_SET_PROJECT_NAME = KoMain
0126 // DOXYGEN_SET_IGNORE_PREFIX = Ko K