← Back to branch summary

~ubuntu-branches/debian/sid/kdevelop/sid

« back to all changes in this revision

Viewing changes to doc/api/HowToAddPlugins.dox

  • Committer: Bazaar Package Importer
  • Author(s): Jeremy Lainé
  • Date: 2006-05-23 18:39:42 UTC
  • Revision ID: james.westby@ubuntu.com-20060523183942-hucifbvh68k2bwz7
Tags: upstream-3.3.2
Import upstream version 3.3.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/api/HowToAddPlugins.dox
 
1
/** \file HowToAddPlugins.dox
 
2
  * \brief How to extend KDevelop via plugins
 
3
  */
 
4
 
 
5
/** \page howToAddPlugins How to extend KDevelop via plugins
 
6
 
 
7
\section createDesktop Step 1: Make your plugin loadable
 
8
 
 
9
For a plugin <code>foo</code>, create a file <code>foo.desktop</code> which contains KDevelop/Part in its list of ServiceTypes.
 
10
 
 
11
  - See <code>parts/doctreeview/kdevdoctreeview.desktop</code> for an example.
 
12
  .
 
13
 
 
14
If you install this file into <code>\$(kde_servicesdir)</code>, your plugin will automatically be loaded.
 
15
 
 
16
\subsection changeLoading How to change the default loading
 
17
 
 
18
You can change the default loading by changing some settings in your <code>foo.desktop</code> file:
 
19
 
 
20
  - Set <code>X-KDevelop-Scope=</code> to <code>Global</code> or
 
21
    <code>Project</code>
 
22
    - <b>Note:</b> This property is <i>not</i> optional
 
23
        .
 
24
  - You can add a list of programming languages which are supported by your
 
25
    plugin
 
26
        - If your plugin works with all languages leave the
 
27
          <code>X-KDevelop-ProgrammingLanguages=</code> field empty
 
28
          <i>(optional)</i>
 
29
        .
 
30
  - You can add a list of keywords.
 
31
    - The plugin will only be loaded if all keywords match with the
 
32
        <code>Keywords=</code> field in the projectfile <i>(optional)</i>.
 
33
        .
 
34
  .
 
35
 
 
36
An example from the Java Debugger Plugin:
 
37
 
 
38
<code><pre>
 
39
    #######################
 
40
    X-KDevelop-Scope=Project
 
41
    X-KDevelop-ProgrammingLanguages=Java
 
42
    Keywords=
 
43
    ##########################
 
44
</pre></code>
 
45
    
 
46
 
 
47
\section createFactory Step 2: Make the plugin accessible by the factory
 
48
 
 
49
Create a factory class <code>FooFactory</code> which inherits
 
50
<code>KDevFactory</code>. Put a section
 
51
 
 
52
<code><pre>
 
53
    extern "C" {
 
54
        void *init_libfoo()
 
55
        {
 
56
            return new FooFactory;
 
57
        }
 
58
    }
 
59
</pre></code>
 
60
 
 
61
into the source file, so that the factory can be accessed by KDE's library
 
62
loader. Keep in mind that the name of the method <code>init_libfoo()</code> is
 
63
required for a library with the name <code>libfoo.so</code>.
 
64
 
 
65
This may be simplified by the use of the
 
66
<code>K_EXPORT_COMPONENT_FACTORY</code> macro which is defined in
 
67
<code>klibloader.h</code>:
 
68
 
 
69
<code>
 
70
K_EXPORT_COMPONENT_FACTORY( libfoo, FooFactory );
 
71
</code>
 
72
 
 
73
  - <i>Note:</i> Your factory must reimplement the
 
74
    <code>createPartObject()</code> method of <code>KDevFactory</code> and
 
75
        produce the part there.
 
76
  .
 
77
 
 
78
See <code>parts/doctreeview/doctreeviewfactory.cpp</code> for an example.
 
79
 
 
80
 
 
81
\section implementPart Step 3: Implement your part.
 
82
 
 
83
Your part must be derived from <code>KDevPlugin</code>.
 
84
 
 
85
  - KDevPlugin takes two arguments:
 
86
    - 1) A <i>parent</i> argument. This also comes from
 
87
          <code>createPartObject()</code>.
 
88
        - 2) A <i>name</i>, which in turn is given to the <code>QObject</code>
 
89
          constructor.
 
90
        .
 
91
  .
 
92
 
 
93
\subsection accessIDE How to access other IDE components
 
94
 
 
95
A part can access other components of the IDE via some accessors
 
96
of <code>KDevPlugin</code>:
 
97
 
 
98
  - The <i>application core</i> via <code>core()</code>,
 
99
  - the <i>build tools</i> via <code>project()</code>,
 
100
  - the <i>programming language specific stuff</i> via
 
101
    <code>languageSupport()</code>,
 
102
  - the <i>make frontend</i> via <code>makeFrontend()</code>,
 
103
  - the part which displays <i>appication output</i> via
 
104
    <code>appFrontend()</code>,
 
105
    and finally
 
106
  - the <i>symbol database</i> via <code>classStore()</code>.
 
107
  .
 
108
 
 
109
In order to see what these components provide, see <code>lib/interfaces/kdev*.h</code>.
 
110
 
 
111
\subsection userPrefs How to store user preferences
 
112
 
 
113
Parts can also store user preferences on a per-project basis. To this
 
114
end, they can access a <code>QDomDocument</code> representing the project file
 
115
(which is stored as xml) via <code>document()</code>.
 
116
 
 
117
Take attention to the issue that the project file usually is shared in a team of
 
118
developers (e.g. via version control application CVS). So some user preferences might be
 
119
very individual, and some may be valid for all of the team - project-wide so to speak.
 
120
 
 
121
That's why the KDevelop architecture makes a difference here and supports two files
 
122
which will be stored in the project root directory. They are the project file (*.kdevelop)
 
123
and the session (*.kdevses) file. The later is for individual settings, not to be thought
 
124
to be shared.
 
125
 
 
126
\subsection domProject Project file (*.kdevelop)
 
127
 
 
128
For your convenience, you don't have to use the quite complex DOM API. Strings
 
129
can very easily be read from and written to this document using the
 
130
<code>DomUtil</code> class. Here, entries are identified by a 'path' in the
 
131
document. You can think of the DOM document as representing a file system
 
132
rooted in the <code>dom</code> document node.
 
133
 
 
134
For example, the <code>autoproject</code> part uses the statement
 
135
 
 
136
<code><pre>
 
137
    QString cflags = DomUtil::readEntry( *part->document(),
 
138
                                         "/kdevautoproject/cflags" );
 
139
</pre></code>
 
140
 
 
141
to read the <code>CFLAGS</code> variable set by the user, and uses the statement similar to
 
142
 
 
143
<code><pre>
 
144
    DomUtil::writeEntry( *part->document(),
 
145
                         "kdevautoproject/cflags",
 
146
                         "--no-exceptions" );
 
147
</pre></code>
 
148
 
 
149
to write it back.
 
150
 
 
151
  - <i>Note:</i> In order to avoid conflicts between different plugins, you
 
152
    should use your part name as top-level 'directory' in the configuration
 
153
        tree.
 
154
  .
 
155
 
 
156
\subsection sessionAccess Project session file (*.kdevses)
 
157
 
 
158
The base class of all KDevelop plugins is KDevPlugin. It provides two virtual methods 
 
159
restorePartialProjectSession(..) and savePartialProjectSession(..)
 
160
that you should reimplement in your special plugin to attach to session loading and saving.
 
161
 
 
162
When KDevelop loads or closes a project, the program's project session manager
 
163
(class ProjectSession) calls them for each plugin. That manager gives a QDOM node to the
 
164
plugin where it can read out or build up its partial DOM subtree with the session settings.
 
165
That subtree will be stored in the .kdevses file by that session manager.
 
166
 
 
167
For example each programmer has set breakpoints in different files than the other ones of
 
168
the team. So the debugger plugin saves them to project session file:
 
169
 
 
170
<code><pre>
 
171
void DebuggerPart::savePartialProjectSession(QDomElement* el)
 
172
{
 
173
    gdbBreakpointWidget->savePartialProjectSession(el);
 
174
}
 
175
void GDBBreakpointWidget::savePartialProjectSession(QDomElement* el)
 
176
{
 
177
    QDomDocument domDoc = el->ownerDocument();
 
178
    if (domDoc.isNull()) return;
 
179
    QDomElement breakpointListEl = domDoc.createElement("breakpointList");
 
180
    for ( int row = 0; row < m_table->numRows(); row++ )
 
181
    {
 
182
        BreakpointTableRow* btr = (BreakpointTableRow *) m_table->item(row, Control);
 
183
        Breakpoint* bp = btr->breakpoint();
 
184
        QDomElement breakpointEl = domDoc.createElement("breakpoint"+QString::number(row));
 
185
        breakpointEl.setAttribute("type", bp->type());
 
186
        breakpointEl.setAttribute("location", bp->location(false));
 
187
        breakpointEl.setAttribute("enabled", bp->isEnabled());
 
188
        breakpointEl.setAttribute("condition", bp->conditional());
 
189
        breakpointListEl.appendChild(breakpointEl);
 
190
    }
 
191
    if (!breakpointListEl.isNull()) el->appendChild(breakpointListEl);
 
192
}
 
193
 
 
194
}
 
195
</pre></code>
 
196
 
 
197
Note that the .kdevses is related to a project. User settings equal for all projects don't
 
198
belong to here. You save them to ~/.kde/share/config/kdeveloprc via class KConfig of the
 
199
kdecore library.
 
200
 
 
201
Document your part in the way described at \ref howToDocument (doc/api/HowToDocument.dox file).
 
202
 
 
203
*/
 
204