qtcreator-dev.qdoc 10.2 KB
Newer Older
1
2
3
4
5
6
/****************************************************************************
**
** This file is part of Qt Creator
**
** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
**
7
** Contact: Nokia Corporation (qt-info@nokia.com)
8
9
10
11
12
13
14
15
16
17
**
**
** GNU Free Documentation License
**
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
** If you have questions regarding the use of this file, please contact
18
** Nokia at qt-info@nokia.com.
19
20
21
22
23
24
25
**
****************************************************************************/

/*!
    \page index.html
    \title Extending Qt Creator Manual

con's avatar
con committed
26
27
28
    Qt Creator is a cross-platform integrated development environment (IDE)
    tailored to the needs of Qt developers.

29
30
31
32
    Qt Creator is extensible in various ways. For example, Qt Creator
    architecture is based on a plugin loader, which means that all
    functionality beyond plugin
    loading is implemented in plugins. However, you can extend and tweak
con's avatar
con committed
33
34
35
    many parts of Qt Creator without the need to resort to coding in C++ and
    implementing such a plugin.

36
37
    This document gives you an overview of the various ways in which
    you can extend Qt Creator,
con's avatar
con committed
38
39
40
    depending on what you want to achieve, and points you to the relevant
    documentation.

41
    \section1 Generating Domain Specific Code and Templates
con's avatar
con committed
42
43

    If you regularly need to write the same code, be it little code snippets,
44
45
    whole files or classes spread over multiple files, or complete projects,
    you can create code snippets, templates, and wizards for that purpose.
con's avatar
con committed
46

Leandro Melo's avatar
Leandro Melo committed
47
    \section2 Snippets
con's avatar
con committed
48

Leandro Melo's avatar
Leandro Melo committed
49
50
    Typically, snippets consist of a few lines of code (although they
    can also be plain text) that you regularly
51
52
53
    want to insert into a bigger body of code, but do not want to type each
    time. For example, \c while and \c for loops, \c if-else and \c try-catch
    constructs, and class skeletons. Snippets are triggered in the same way as
Leandro Melo's avatar
Leandro Melo committed
54
55
    normal code completion (see \l{Code Assist}{Providing Code Assist}).
    Qt Creator contains a set of preconfigured snippets groups
56
57
    to which you can add your own snippets.

con's avatar
con committed
58
    \list
59
    \o \l{http://doc.qt.nokia.com/qtcreator/creator-completing-code.html#editing-code-snippets}
Leandro Melo's avatar
Leandro Melo committed
60
61
         {Snippets User Interface}
    \o \l{Snippets} {Adding Snippets Groups}
con's avatar
con committed
62
63
64
65
    \endlist

    \section2 File, Class and Project Templates

66
67
68
    You can extend the wizards in \gui {File > New File or Project} with your
    own
    file and project templates by writing XML definition files for them.
con's avatar
con committed
69
    \list
70
    \o \l{http://doc.qt.nokia.com/qtcreator/creator-project-wizards.html}
con's avatar
con committed
71
72
73
74
         {Adding New Custom Wizards}
    \o \l{User Interface Text Guidelines}
    \endlist

75
    \section2 Custom Wizards
con's avatar
con committed
76
77

    If the above methods for code snippets and templates are not sufficient
78
79
    for your use case, you can create a custom Qt Creator plugin.
    While this gives you complete control over the wizard, it
con's avatar
con committed
80
81
82
83
    also requires you to write most of the UI and the logic yourself.
    \list
    \o \l{Creating Plugins}
    \o \l{Qt Creator Coding Rules}
84
    \o \l{Creating Wizards in Code}
con's avatar
con committed
85
86
87
    \o \l{User Interface Text Guidelines}
    \endlist

88
    \section1 Supporting Additional File Types
con's avatar
con committed
89

90
91
92
    If you have files with extensions or MIME types that Qt Creator does not
    handle by default, you can edit the MIME type definitions, add highlight
    definition files, and create your own text editors.
con's avatar
con committed
93

94
    \section2 MIME Types
con's avatar
con committed
95

96
97
98
99
    You might find that Qt Creator could handle a particular file of yours if
    it knew about the type of its contents. For example, C++ header or source
    files with file extensions that are not known to Qt Creator. You can adapt
    the MIME type definitions in Qt Creator to your specific setup,
con's avatar
con committed
100
101
    by adding or removing file extensions and specifying magic headers.
    \list
102
103
104
105
    \o \l{http://doc.qt.nokia.com/qtcreator/creator-mime-types.html}
         {Editing MIME Types}
    \o \l{http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-latest.html}
         {MIME Type Specification Files}
con's avatar
con committed
106
107
108
109
    \endlist

    \section2 Text Highlighting and Indentation

110
111
112
113
114
    For text files, Qt Creator provides an easy way to add highlighting and
    indentation for file types that are not known to it by default.
    Generic highlighting is based on highlight definition files that are
    provided by the Kate Editor. You can download highlight definition files
    for use with Qt Creator and create your own definition files.
con's avatar
con committed
115
    \list
116
    \o \l{http://doc.qt.nokia.com/qtcreator/creator-editor-options.html#generic-highlighting}
con's avatar
con committed
117
118
         {Generic Highlighting}
    \o \l{http://kate-editor.org/2005/03/24/writing-a-syntax-highlighting-file/}
119
         {Writing a Syntax Highlighting File}
con's avatar
con committed
120
121
122
123
    \endlist

    \section2 Custom Text Editors

124
125
126
127
    If you need more advanced features than the MIME type and highlighting
    features described above, such as custom text completion or features that
    rely on semantic analysis, you can extend Qt Creator with a text editor of
    your own. Qt Creator provides a special API for text editors that gives you
con's avatar
con committed
128
129
130
131
132
133
    a basis to build on, taking away some of the pain of implementing
    a text editor from the ground up.
    \list
    \o \l{Creating Plugins}
    \o \l{Qt Creator Coding Rules}
    \o \l{Text Editors}
134
    \o \l{CodeAssist} {Providing Code Assist}
con's avatar
con committed
135
136
    \endlist

137
    \section2 Other Custom Editors
con's avatar
con committed
138

139
140
    You can also add a completely custom editor to gain complete
    control over its appearance and behavior.
con's avatar
con committed
141
142
143
144
145
146
147
148
    \list
    \o \l{Creating Plugins}
    \o \l{Qt Creator Coding Rules}
    \o \l{Editors}
    \endlist

    \section1 Running External Tools

149
150
151
152
153
    Most software projects and development processes require various external
    tools. Several external tools, such as popular version control systems and
    build tool chains are integrated into Qt Creator. However, it is impossible
    for a single tool to cover all the use cases, and therefore you can
    integrate additional tools to Qt Creator.
con's avatar
con committed
154

155
    \section2 Simple External Tools
con's avatar
con committed
156

157
158
159
160
161
162
    In Qt Creator, you can specify tools that you can then run from a
    menu or by using a keyboard shortcut that you assign. This allows you to
    accomplish several things, with some limitations. You specify a command
    to run, arguments and input for running it, and how to handle the output.
    To specify the values, you can use a set of internal Qt Creator variables,
    such as the file name of
con's avatar
con committed
163
    the current document or project, or the currently selected text in
164
165
    a text editor. If you find variables missing, please do not hesitate
    to fill a feature suggestion.
con's avatar
con committed
166
167
    The tool descriptions are saved as XML files that you can share.
    \list
168
    \o \l{http://doc.qt.nokia.com/qtcreator/creator-editor-external.html}
con's avatar
con committed
169
170
171
172
         {Using External Tools}
    \o \l{External Tool Specification Files}
    \endlist

173
    \section2 Complex External Tools
con's avatar
con committed
174

175
176
177
    When you plan to integrate more complex tools, carefully consider whether
    there really are advantages to be gained by tightly integrating the tool
    into Qt Creator over loosely integrating it by mainly
con's avatar
con committed
178
179
180
181
    providing a means of starting the tool with fitting parameters.

    \section3 Loosely Integrating Tools

182
    If no interaction is needed between Qt Creator and the
con's avatar
con committed
183
184
185
186
    external tool, just starting an external
    application with its own user interface is preferable. That way
    cluttering the Qt Creator UI is avoided, and the tool will be
    available with a nice interface even without using Qt Creator
187
188
189
190
191
192
193
    at all.

    Usually, you can use the external tool specification files to start the
    tool. If starting the tool and handling its output require more complex
    logic, you can add a menu item to Qt Creator with a plugin.
    If you need a way to configure the tool in Qt Creator, you can add an
    \gui Options page for it.
194
    \list
195
    \o \l{http://doc.qt.nokia.com/qtcreator/creator-editor-external.html}
con's avatar
con committed
196
197
198
199
200
201
202
203
204
         {Using External Tools}
    \o \l{External Tool Specification Files}
    \o \l{Creating Plugins}
    \o \l{Qt Creator Coding Rules}
    \o \l{Menus and Menu Items}
    \o \l{Options Pages}
    \endlist

    \section3 Interacting with Tool Output
205

206
207
208
209
210
211
    In some cases, running an external tool would not require tight
    integration with Qt Creator, but investigating the output of the tool would
    benefit from it. For example, some tools generate lists of issues in files
    that are part of the project and some tools create output that is related
    to the code. For these tools, it is useful to interactively switch between
    the output and the corresponding code.
con's avatar
con committed
212
213

    One way to handle that would be to let the tool create an output
214
215
216
    file, which is then opened within Qt Creator. You provide
    an editor (probably read-only) for handling this file.
    For lists of issues, consider creating task list files which are shown in
217
    the \gui {Issues} output
con's avatar
con committed
218
219
    pane.
    \list
220
    \o \l{http://doc.qt.nokia.com/qtcreator/creator-task-lists.html}
221
         {Showing Task List Files in the Issues Pane}
con's avatar
con committed
222
223
224
225
226
227
228
229
230
231
    \o \l{Creating Plugins}
    \o \l{Qt Creator Coding Rules}
    \o \l{Menus and Menu Items}
    \o \l{Options Pages}
    \o \l{Editors}
    \endlist

    \section1 All Topics

    \list
232
        \o  \l{Developing Qt Creator Plugins}
233
            \list
234
235
                \o  \l{Creating Plugins}
                \o  \l{Menus and Menu Items}
Leena Miettinen's avatar
Leena Miettinen committed
236
                \o  \l{Creating Wizards in Code}
237
238
239
                \o  \l{Editors}
                \o  \l{Text Editors}
                \o  \l{Options Pages}
240
241
242
            \endlist
        \o  Reference
            \list
Leena Miettinen's avatar
Leena Miettinen committed
243
244
                \o  \l{http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-latest.html}
                    {MIME Type Specification Files}
245
                \o  \l{External Tool Specification Files}
Leena Miettinen's avatar
Leena Miettinen committed
246
247
                \o  \l{http://kate-editor.org/2005/03/24/writing-a-syntax-highlighting-file/}
                    {Highlight Definition Files}
248
                \o  \l{Qt Creator Variables}
249
                \o  \l{User Interface Text Guidelines}
250
                \o  \l{Writing Documentation}
251
252
253
254
255
256
                \o  \l{Qt Creator Coding Rules}
                \o  \l{Qt Creator API Reference}
        \endlist

    \endlist
*/