Commit c66723ad authored by Leena Miettinen's avatar Leena Miettinen
Browse files

Doc: edited for language and style

Reviewed-by: con
parent f6148f6d
......@@ -22,54 +22,60 @@
/*!
\page index.html
\title Extending Qt Creator Manual
\nextpage
Qt Creator is a cross-platform integrated development environment (IDE)
tailored to the needs of Qt developers.
It is extensible in various ways, for example the main Qt Creator
architecture is based on a plugin loader: All functionality beyond plugin
loading is implemented in plugins. But you can already extend and tweak
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
many parts of Qt Creator without the need to resort to coding in C++ and
implementing such a plugin.
This document gives you an overview of the various available mechanisms,
This document gives you an overview of the various ways in which
you can extend Qt Creator,
depending on what you want to achieve, and points you to the relevant
documentation.
\section1 Generating Domain Specific Code / Templates
\section1 Generating Domain Specific Code and Templates
If you regularly need to write the same code, be it little code snippets,
whole files or classes spread over multiple files, or complete projects.
whole files or classes spread over multiple files, or complete projects,
you can create code snippets, templates, and wizards for that purpose.
\section2 Code Snippets
Code snippets are usually a few lines of code that you regularly want to
insert into bigger parts of code, but don't want to type all the time.
Examples are while- and for-loops, if-else and try-catch constructs, and
class skeletons. Snippets are triggered the same way as normal code
completion. Qt Creator already comes with a set of preconfigured snippets,
but offers user definable snippets as well.
Typically, code snippets consist of a few lines of code that you regularly
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
normal code completion. Qt Creator contains a set of preconfigured snippets
to which you can add your own snippets.
\list
\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-editor-using.html#completing-code-snippets}
{Adding Code Snippets Through The UI}
\o \l{http://doc.qt.nokia.com/qtcreator/creator-completing-code.html#editing-code-snippets}
{Adding Code Snippets in Qt Creator}
\o \l{Code Snippet Configuration Files}
\endlist
\section2 File, Class and Project Templates
You can extend the wizards in File > New File or Project with your own
file and project templates by writing a xml description for it.
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.
\list
\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-project-wizards.html}
\o \l{http://doc.qt.nokia.com/qtcreator/creator-project-wizards.html}
{Adding New Custom Wizards}
\o \l{User Interface Text Guidelines}
\endlist
\section2 Custom wizards
\section2 Custom Wizards
If the above methods for code snippets and templates are not sufficient
for your use case, you have the option to create a custom Qt Creator plugin.
This gives you complete control over the wizard, but on the other hand
for your use case, you can create a custom Qt Creator plugin.
While this gives you complete control over the wizard, it
also requires you to write most of the UI and the logic yourself.
\list
\o \l{Creating Plugins}
......@@ -78,43 +84,46 @@
\o \l{User Interface Text Guidelines}
\endlist
\section1 Supporting additional file types
\section1 Supporting Additional File Types
If you have files with extensions or mime types that Qt Creator doesn't handle.
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.
\section2 Mime types
\section2 MIME Types
You might find that Qt Creator could handle a certain file of yours, if it
knew about the type of its contents. Typical examples would be C++ header
or source files with a file extension that is not known to Qt Creator.
You can adapt the mime type definitions in Qt Creator to your specific setup,
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,
by adding or removing file extensions and specifying magic headers.
\list
\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-mime-types.html}
{Editing Mime Types}
\o \l{Mime Type Specification Files}
\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}
\endlist
\section2 Text Highlighting and Indentation
For text files Qt Creator offers an easy way to add highlighting and
indentation for file types that are not specifically known to it -
it has a 'generic highlighting' editor that uses Kate editor's
syntax highlighting definitions, and that you can extend with your own
definitions.
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.
\list
\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-editor-options.html#generic-highlighting}
\o \l{http://doc.qt.nokia.com/qtcreator/creator-editor-options.html#generic-highlighting}
{Generic Highlighting}
\o \l{http://kate-editor.org/2005/03/24/writing-a-syntax-highlighting-file/}
{Writing a Syntax Highlighting File (Link to the Kate Editor Project)}
{Writing a Syntax Highlighting File}
\endlist
\section2 Custom Text Editors
If you need more than the mime type and/or highlighting features above,
like custom text completion, or features that rely on real semantic
analyses, you can extend Qt Creator with a text editor of your own.
Qt Creator provides special API for text editors that give you
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
a basis to build on, taking away some of the pain of implementing
a text editor from the ground up.
\list
......@@ -123,10 +132,10 @@
\o \l{Text Editors}
\endlist
\section2 Custom Non-Text Editors
\section2 Other Custom Editors
You can also add a completely custom editor where you have complete
control over appearance and behavior.
You can also add a completely custom editor to gain complete
control over its appearance and behavior.
\list
\o \l{Creating Plugins}
\o \l{Qt Creator Coding Rules}
......@@ -135,53 +144,53 @@
\section1 Running External Tools
Most software projects and development processes require a developer
to run various external tools. Many of these are directly integrated
into Qt Creator, like popular version control systems and build tool
chains, but it is impossible for a single tool to cover all the use
cases.
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.
\section2 'Simple' External Tools
\section2 Simple External Tools
In Qt Creator you can specify tools that you then can run via a
menu (or via a keyboard shortcut you assign). It has some limitations
but will be already sufficient for many things. You specify a command
to run, the arguments and input you want it to receive, and specify
what to do with the tools output, if any. For these values you can
access a set of internal Qt Creator variables, like the file name of
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
the current document or project, or the currently selected text in
a text editor. (If you find variables missing, please don't hesitate
to fill a feature suggestion.)
a text editor. If you find variables missing, please do not hesitate
to fill a feature suggestion.
The tool descriptions are saved as XML files that you can share.
\list
\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-editor-external.html}
\o \l{http://doc.qt.nokia.com/qtcreator/creator-editor-external.html}
{Using External Tools}
\o \l{External Tool Specification Files}
\endlist
\section2 'Complex' External Tools
\section2 Complex External Tools
For integrating more complex tools you should still consider if
and what the advantages are of either integrating the tool
tightly into Qt Creator, or loosely integrating by mainly
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
providing a means of starting the tool with fitting parameters.
\section3 Loosely Integrating Tools
Usually, if no interaction is needed between Qt Creator and the
If no interaction is needed between Qt Creator and the
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
at all. Starting the external tool might be possible through
the external tools specification files above, or you might need
to add a menu item to Qt Creator's menu with a plugin, if starting
the tool (and maybe handling it's output) needs more complex logic.
In that case you might also need a way to configure the tool from
inside Qt Creator, usually done by providing a preference page in
Qt Creator's preferences.
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.
\list
\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-editor-external.html}
\o \l{http://doc.qt.nokia.com/qtcreator/creator-editor-external.html}
{Using External Tools}
\o \l{External Tool Specification Files}
\o \l{Creating Plugins}
......@@ -192,22 +201,21 @@
\section3 Interacting with Tool Output
Sometimes running the tool would not need a tight integration, but
investigating the output of the tool would benefit from tighter
interaction with Qt Creator. Examples are tools that generate
lists of issues in files of the project, or in general create
output that relates to the code and where you would like to
interactively switch between the output and the corresponding
code.
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.
One way to handle that would be to let the tool create an output
file, which then is opened within Qt Creator. You provide
an (probably read-only) editor for handling this file.
For the 'list of issues' type of output you can also consider
creating task list files which are shown in the Build Issues
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
the \gui {Build Issues} output
pane.
\list
\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-task-lists.html}
\o \l{http://doc.qt.nokia.com/qtcreator/creator-task-lists.html}
{Showing Task List Files in the Build Issues Pane}
\o \l{Creating Plugins}
\o \l{Qt Creator Coding Rules}
......@@ -219,23 +227,23 @@
\section1 All Topics
\list
\o Developing Qt Creator Plugins
\o \l{Developing Qt Creator Plugins}
\list
\o Creating Plugins
\o Menus and Menu Items
\o Wizards
\o Editors
\o Text Editors
\o Options Pages
\o \l{Creating Plugins}
\o \l{Menus and Menu Items}
\o \l{Wizards}
\o \l{Editors}
\o \l{Text Editors}
\o \l{Options Pages}
\endlist
\o Reference
\list
\o Code Snippet Configuration Files
\o MIME Type Specification Files
\o External Tool Specification Files
\o Custom Wizard Specification Files
\o \l{Code Snippet Configuration Files}
\o \l{http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-latest.html}{MIME Type Specification Files}
\o \l{External Tool Specification Files}
\o \l{Custom Wizard Specification Files}
\o \l{http://kate-editor.org/2005/03/24/writing-a-syntax-highlighting-file/}{Highlight Definition Files}
\o User Interface Text Guidelines
\o \l{User Interface Text Guidelines}
\o \l{Qt Creator Coding Rules}
\o \l{Qt Creator API Reference}
\endlist
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment