diff options
| author | Tobias Hunger <tobias.hunger@digia.com> | 2013-09-25 18:19:45 +0200 |
|---|---|---|
| committer | Tobias Hunger <tobias.hunger@digia.com> | 2013-09-26 09:56:22 +0200 |
| commit | 0479abdcd78917c52ae0d77a4e4b8994cf704336 (patch) | |
| tree | 76f779b1e0c3e020f5fc48cdff62b2ba2fe152a3 /doc | |
| parent | 529cc963b54b2d5d8ec08241c437a8a76318060b (diff) | |
| download | qt-creator-0479abdcd78917c52ae0d77a4e4b8994cf704336.tar.gz | |
QDoc: Fix QDoc warnings
This patch fixes ~1100 warnings from qdoc
Change-Id: Ia9555db675acbf8083b2f87d9855a62a3a34ccb9
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@digia.com>
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/addressbook-sdk.qdoc | 204 | ||||
| -rw-r--r-- | doc/api/coding-style.qdoc | 188 | ||||
| -rw-r--r-- | doc/api/creating-plugins.qdoc | 18 | ||||
| -rw-r--r-- | doc/api/external-tool-spec.qdoc | 124 | ||||
| -rw-r--r-- | doc/api/first-plugin.qdoc | 152 | ||||
| -rw-r--r-- | doc/api/plugin-lifecycle.qdoc | 146 | ||||
| -rw-r--r-- | doc/api/plugin-specifications.qdoc | 190 | ||||
| -rw-r--r-- | doc/api/pluginmanager.qdoc | 56 | ||||
| -rw-r--r-- | doc/api/qtcreator-api.qdoc | 174 | ||||
| -rw-r--r-- | doc/api/qtcreator-dev-wizards.qdoc | 142 | ||||
| -rw-r--r-- | doc/api/qtcreator-dev.qdoc | 102 | ||||
| -rw-r--r-- | doc/api/qtcreator-documentation.qdoc | 59 | ||||
| -rw-r--r-- | doc/api/qtcreator-ui-text.qdoc | 267 |
13 files changed, 909 insertions, 913 deletions
diff --git a/doc/addressbook-sdk.qdoc b/doc/addressbook-sdk.qdoc index 266c1598a4..e5e9ac6072 100644 --- a/doc/addressbook-sdk.qdoc +++ b/doc/addressbook-sdk.qdoc @@ -35,10 +35,10 @@ Qt, such as: \list - \o Widgets and layout managers - \o Container classes - \o Signals and slots - \o Input and output devices + \li Widgets and layout managers + \li Container classes + \li Signals and slots + \li Input and output devices \endlist All these technologies will be introduced via the Qt Creator Integrated @@ -53,13 +53,13 @@ Tutorial chapters: \list 1 - \o \l{examples/addressbook-sdk/part1}{Designing the User Interface} - \o \l{examples/addressbook-sdk/part2}{Adding Addresses} - \o \l{examples/addressbook-sdk/part3}{Navigating between Entries} - \o \l{examples/addressbook-sdk/part4}{Editing and Removing Addresses} - \o \l{examples/addressbook-sdk/part5}{Adding a Find Function} - \o \l{examples/addressbook-sdk/part6}{Loading and Saving} - \o \l{examples/addressbook-sdk/part7}{Additional Features} + \li \l{examples/addressbook-sdk/part1}{Designing the User Interface} + \li \l{examples/addressbook-sdk/part2}{Adding Addresses} + \li \l{examples/addressbook-sdk/part3}{Navigating between Entries} + \li \l{examples/addressbook-sdk/part4}{Editing and Removing Addresses} + \li \l{examples/addressbook-sdk/part5}{Adding a Find Function} + \li \l{examples/addressbook-sdk/part6}{Loading and Saving} + \li \l{examples/addressbook-sdk/part7}{Additional Features} \endlist Although this little application does not look much like a fully-fledged @@ -93,7 +93,7 @@ Begin by launching Qt Creator and use it to generate a new project. To do this, select \gui{File} > \gui{New File or Project...} > \gui{Qt Application Project} > \gui{Qt Gui Application} and - click \gui OK. Set your project name to \bold part1 with the QtCore and + click \gui OK. Set your project name to \b part1 with the QtCore and QtGui modules checked. Ensure that you select QWidget as your base class and name it \c AddressBook. @@ -101,15 +101,15 @@ \gui{Project}: \list - \o \c{main.cpp} - the file containing a \c main() function, with an - instance of \c AddressBook, - \o \c{addressbook.cpp} - the implementation file for the - \c AddressBook class, - \o \c{addressbook.h} - the definition file for the \c AddressBook - class, - \o \c{addressbook.ui} - the user interface file created with \QD, - and - \o \c{part1.pro} - the project file. + \li \c{main.cpp} - the file containing a \c main() function, with an + instance of \c AddressBook, + \li \c{addressbook.cpp} - the implementation file for the + \c AddressBook class, + \li \c{addressbook.h} - the definition file for the \c AddressBook + class, + \li \c{addressbook.ui} - the user interface file created with \QD, + and + \li \c{part1.pro} - the project file. \endlist Now that you have all the files you need, click \gui Finish so you can @@ -132,16 +132,16 @@ QLineEdit and a QTextEdit for the input fields. To create this follow the steps mentioned below: \list - \o Drag those widgets from the \gui{Widget Box} to your form. - \o In the \gui{Property Editor}, set their \gui{objectName} property to - \c nameLabel and \c addressLabel for the \l{QLabel}s, \c nameLine - for the QLineEdit and finally, \c addressText for the QTextEdit. - \o Position the widgets properly, according to the screenshot above. - \o Use a QGridLayout to position our labels and input fields in a - structured manner. QGridLayout divides the available space into - a grid and places widgets in the cells you specify with row and - column numbers. - \o Place the caption of the \c addressLabel on the top, change the + \li Drag those widgets from the \gui{Widget Box} to your form. + \li In the \gui{Property Editor}, set their \gui{objectName} property to + \c nameLabel and \c addressLabel for the \l{QLabel}s, \c nameLine + for the QLineEdit and finally, \c addressText for the QTextEdit. + \li Position the widgets properly, according to the screenshot above. + \li Use a QGridLayout to position our labels and input fields in a + structured manner. QGridLayout divides the available space into + a grid and places widgets in the cells you specify with row and + column numbers. + \li Place the caption of the \c addressLabel on the top, change the vertical alignment property to \c AlignTop. \endlist @@ -227,15 +227,15 @@ the behavior of a widget has the following advantages: \list - \o You can write implementations of virtual or pure virtual functions - to obtain exactly what you need, falling back on the base class's - implementation when necessary. - \o It allows you to encapsulate parts of the user interface within a - class, so that the other parts of the application do not need to - know about the individual widgets in the user interface. - \o The subclass can be used to create multiple custom widgets in the - same application or library, and the code for the subclass can be - reused in other projects. + \li You can write implementations of virtual or pure virtual functions + to obtain exactly what you need, falling back on the base class's + implementation when necessary. + \li It allows you to encapsulate parts of the user interface within a + class, so that the other parts of the application do not need to + know about the individual widgets in the user interface. + \li The subclass can be used to create multiple custom widgets in the + same application or library, and the code for the subclass can be + reused in other projects. \endlist Since Qt does not provided a specific address book widget, you subclass a @@ -272,29 +272,29 @@ complete the process of adding a contact. Break the existing layouts by following the steps below: \list - \o Select, \gui{Break Layout} from the context menu. You might have to - do a \gui{Select All} with \key{Ctrl+A} first.. - \o Add three push buttons and double-click on each of them to set - their text to "Add", "Submit", and "Cancel". - \o Set the \c objectName of the buttons to \c addButton, - \c submitButton and \c cancelButton respectively. - \o A \gui{Vertical Spacer} is required to ensure that the push buttons - will be laid out neatly; drag one from the \gui{Widget Box}. - \o Lay out these three push buttons and the spacer vertically, by - selecting all three of them using \key{Ctrl + click} and selecting - \gui{Lay out Vertically} from the context menu. Alternatively you - can use the \key{Ctrl+L} shortcut key. - - \note Use the spacer as you do not want the buttons to be evenly - spaced, but arranged closer to the top of the widget. - \o The figure below shows the difference between using the spacer and - not using it. - \image addressbook-tutorial-part2-stretch-effects.png - \o Select all the objects on the form using, \key{Ctrl+A} and lay them - out in a grid. - \o Lastly, set the top level widget's layout by right-clicking anywhere - on the widget and selecting \gui{Lay out Horizontally} or - \gui{Lay out Vertically}. + \li Select, \gui{Break Layout} from the context menu. You might have to + do a \gui{Select All} with \key{Ctrl+A} first.. + \li Add three push buttons and double-click on each of them to set + their text to "Add", "Submit", and "Cancel". + \li Set the \c objectName of the buttons to \c addButton, + \c submitButton and \c cancelButton respectively. + \li A \gui{Vertical Spacer} is required to ensure that the push buttons + will be laid out neatly; drag one from the \gui{Widget Box}. + \li Lay out these three push buttons and the spacer vertically, by + selecting all three of them using \key{Ctrl + click} and selecting + \gui{Lay out Vertically} from the context menu. Alternatively you + can use the \key{Ctrl+L} shortcut key. + + \note Use the spacer as you do not want the buttons to be evenly + spaced, but arranged closer to the top of the widget. + \li The figure below shows the difference between using the spacer and + not using it. + \image addressbook-tutorial-part2-stretch-effects.png + \li Select all the objects on the form using, \key{Ctrl+A} and lay them + out in a grid. + \li Lastly, set the top level widget's layout by right-clicking anywhere + on the widget and selecting \gui{Lay out Horizontally} or + \gui{Lay out Vertically}. \endlist The final design of the form is shown in the screenshot below: @@ -376,27 +376,27 @@ This function can be divided into three parts: \list 1 - \o Extract the contact's detail from \c nameLine and \c addressText - and store them in QString objects. Also validate to ensure that - you did not click \gui Submit with empty input fields; - otherwise, a QMessageBox is displayed to remind you for a name - and address. + \li Extract the contact's detail from \c nameLine and \c addressText + and store them in QString objects. Also validate to ensure that + you did not click \gui Submit with empty input fields; + otherwise, a QMessageBox is displayed to remind you for a name + and address. - \snippet examples/addressbook-sdk/part2/addressbook.cpp submitContact part1 + \snippet examples/addressbook-sdk/part2/addressbook.cpp submitContact part1 - \o Then proceed to check if the contact already exists. If it does - not exist, add the contact to \c contacts and display a - QMessageBox to inform you about this, preventing you from - adding duplicate contacts. Our \c contacts object is based on - key-value pairs or name and address, hence, you want to ensure that - \e key is unique. + \li Then proceed to check if the contact already exists. If it does + not exist, add the contact to \c contacts and display a + QMessageBox to inform you about this, preventing you from + adding duplicate contacts. Our \c contacts object is based on + key-value pairs or name and address, hence, you want to ensure that + \e key is unique. - \snippet examples/addressbook-sdk/part2/addressbook.cpp submitContact part2 + \snippet examples/addressbook-sdk/part2/addressbook.cpp submitContact part2 - \o Once you have handled both cases mentioned above, restore the - push buttons to their normal state with the following code: + \li Once you have handled both cases mentioned above, restore the + push buttons to their normal state with the following code: - \snippet examples/addressbook-sdk/part2/addressbook.cpp submitContact part3 + \snippet examples/addressbook-sdk/part2/addressbook.cpp submitContact part3 \endlist The screenshot below shows the QMessageBox object used to display @@ -457,17 +457,17 @@ need to traverse the existing contacts. To do so follow the steps mentioned below: \list - \o Add two push buttons at the bottom of your application and name - them: \gui Next and \gui Previous. - \o The buttons' \c objectName should be \c nextButton and - \c previousButton, respectively. - \o Break your top level layout by right-clicking on \c AddressBook in - the \gui{Object Inspector} and then select \gui{Lay out|Break Layout}. - \o Place the \gui Next and \gui Previous buttons in a horizontal - layout. - \o Drag and drop the buttons together with their layout into the - existing grid layout. - \o Set a top level layout for the widget again. + \li Add two push buttons at the bottom of your application and name + them: \gui Next and \gui Previous. + \li The buttons' \c objectName should be \c nextButton and + \c previousButton, respectively. + \li Break your top level layout by right-clicking on \c AddressBook in + the \gui{Object Inspector} and then select \gui{Lay out|Break Layout}. + \li Place the \gui Next and \gui Previous buttons in a horizontal + layout. + \li Drag and drop the buttons together with their layout into the + existing grid layout. + \li Set a top level layout for the widget again. \endlist The screenshot below illustrates what you will see as the button layout @@ -523,11 +523,11 @@ for \c contacts and then: \list - \o If the iterator is not at the end of \c contacts, increment it by + \li If the iterator is not at the end of \c contacts, increment it by one. - \o If the iterator is at the end of \c contacts, move it to the - beginning of \c contacts. This gives an illusion that our QMap - is working like a circularly-linked list. + \li If the iterator is at the end of \c contacts, move it to the + beginning of \c contacts. This gives an illusion that our QMap + is working like a circularly-linked list. \endlist \snippet examples/addressbook-sdk/part3/addressbook.cpp next @@ -539,11 +539,11 @@ \c contacts and then: \list - \o If the iterator is at the end of \c contacts, clear the display - and return. - \o If the iterator is at the beginning of \c contacts, move it to - the end. - \o Then decrement the iterator by one. + \li If the iterator is at the end of \c contacts, clear the display + and return. + \li If the iterator is at the beginning of \c contacts, move it to + the end. + \li Then decrement the iterator by one. \endlist \snippet examples/addressbook-sdk/part3/addressbook.cpp previous @@ -578,9 +578,9 @@ In this chapter, define the \c Mode enum with three different values: \list - \o \c{NavigationMode} - \o \c{AddingMode} - \o \c{EditingMode} + \li \c{NavigationMode} + \li \c{AddingMode} + \li \c{EditingMode} \endlist \section1 Placing Widgets on The Form diff --git a/doc/api/coding-style.qdoc b/doc/api/coding-style.qdoc index 7ea0f6eec3..6ed309f0a6 100644 --- a/doc/api/coding-style.qdoc +++ b/doc/api/coding-style.qdoc @@ -35,20 +35,20 @@ following rules: \list - \o The most important rule is: KISS (keep it short and simple). Always + \li The most important rule is: KISS (keep it short and simple). Always choose the simpler implementation option over the more complicated one. This makes maintenance a lot easier. - \o Write good C++ code. That is, readable, well commented when necessary, + \li Write good C++ code. That is, readable, well commented when necessary, and object-oriented. - \o Take advantage of Qt. Do not re-invent the wheel. Think about which parts + \li Take advantage of Qt. Do not re-invent the wheel. Think about which parts of your code are generic enough that they might be incorporated into Qt instead of Qt Creator. - \o Adapt the code to the existing structures in Qt Creator. + \li Adapt the code to the existing structures in Qt Creator. If you have improvement ideas, discuss them with other developers before writing the code. - \o Follow the guidelines in \l{Code Constructs}, \l{Formatting}, and + \li Follow the guidelines in \l{Code Constructs}, \l{Formatting}, and \l{Patterns and Practices}. - \o Document interfaces. Right now we use qdoc, but changing to doxygen + \li Document interfaces. Right now we use qdoc, but changing to doxygen is being considered. \endlist @@ -68,13 +68,13 @@ releases: \list - \o Qt Creator 2.0.0 is a \e {major release}, Qt Creator 2.1.0 is a \e {minor + \li Qt Creator 2.0.0 is a \e {major release}, Qt Creator 2.1.0 is a \e {minor release}, and Qt Creator 2.1.3 is a \e {patch release}. - \o \e {Backward binary compatibility} means that code linked to an + \li \e {Backward binary compatibility} means that code linked to an earlier version of the library still works. - \o \e {Forward binary compatibility} means that code linked to a + \li \e {Forward binary compatibility} means that code linked to a newer version of the library works with an older library. - \o \e {Source code compatibility} means that code compiles without + \li \e {Source code compatibility} means that code compiles without modification. \endlist @@ -86,11 +86,11 @@ backward source code compatibility in patch releases, so: \list - \o Do not add or remove any public API (e.g. global functions,x + \li Do not add or remove any public API (e.g. global functions,x public/protected/private methods). - \o Do not reimplement methods (not even inlines, + \li Do not reimplement methods (not even inlines, nor protected or private methods). - \o Check + \li Check \l {http://wiki.qt-project.org/index.php/Binary_Compatibility_Workarounds}{Binary Compatibility Workarounds} for ways to preserve binary compatibility. \endlist @@ -107,7 +107,7 @@ type checking in C++. \list - \o Prefer preincrement to postincrement whenever possible. + \li Prefer preincrement to postincrement whenever possible. Preincrement is potentially faster than postincrement. Just think about the obvious implementations of pre/post-increment. This rule applies to decrement too: @@ -122,7 +122,7 @@ U--; \endcode - \o Try to minimize evaluation of the same code over and over. This is + \li Try to minimize evaluation of the same code over and over. This is aimed especially at loops: \code @@ -141,7 +141,7 @@ \endcode - \o You can use the Qt \c foreach loop in non-time-critical code with a Qt + \li You can use the Qt \c foreach loop in non-time-critical code with a Qt container. It is a nice way to keep line noise down and to give the loop variable a proper name: @@ -180,19 +180,19 @@ Capitalize the first word in an identifier as follows: \list - \o Class names begin with a capital letter. - \o Function names begin with a lower case letter. - \o Variable names begin with a lower case letter. - \o Enum names and values begin with a capital letter. Enum values + \li Class names begin with a capital letter. + \li Function names begin with a lower case letter. + \li Variable names begin with a lower case letter. + \li Enum names and values begin with a capital letter. Enum values contain some part of the name of the enum type. \endlist \section2 Whitespace \list - \o Use four spaces for indentation, no tabs. - \o Use blank lines to group statements together where suited. - \o Always use only one blank line. + \li Use four spaces for indentation, no tabs. + \li Use blank lines to group statements together where suited. + \li Always use only one blank line. \endlist \section3 Pointers and References @@ -405,10 +405,10 @@ \section2 Line Breaks \list - \o Keep lines shorter than 100 characters. - \o Insert line breaks if necessary. - \o Commas go at the end of a broken line. - \o Operators start at the beginning of the new line. + \li Keep lines shorter than 100 characters. + \li Insert line breaks if necessary. + \li Commas go at the end of a broken line. + \li Operators start at the beginning of the new line. \code if (longExpression || otherLongExpression @@ -427,15 +427,15 @@ \section2 Declarations \list - \o Use this order for the access sections of your class: public, + \li Use this order for the access sections of your class: public, protected, private. The public section is interesting for every user of the class. The private section is only of interest for the implementors of the class (you). - \o Avoid declaring global objects in the declaration file of the class. + \li Avoid declaring global objects in the declaration file of the class. If the same variable is used for all objects, use a static member. - \o Use \c{class} instead of \c{struct}. Some compilers mangle that + \li Use \c{class} instead of \c{struct}. Some compilers mangle that difference into the symbol names and spit out warnings if a struct declaration is followed by a class definition. To avoid ongoing changes from one to the other we declare \c{class} the preferred way. @@ -445,16 +445,16 @@ \section3 Declaring Variables \list - \o Avoid global variables of class type to rule out initialization order problems. + \li Avoid global variables of class type to rule out initialization order problems. Consider using \c Q_GLOBAL_STATIC if they cannot be avoided. - \o Declare global string literals as + \li Declare global string literals as \code const char aString[] = "Hello"; \endcode - \o Avoid short names (such as, a, rbarr, nughdeget) whenever possible. + \li Avoid short names (such as, a, rbarr, nughdeget) whenever possible. Use single-character variable names only for counters and temporaries, where the purpose of the variable is obvious. - \o Declare each variable on a separate line: + \li Declare each variable on a separate line: \code QString a = "Joe"; QString b = "Foo"; @@ -475,7 +475,7 @@ mistaken as function declaration, and it reduces the level of nested parantheses in more initializations. - \o Avoid abbreviations: + \li Avoid abbreviations: \code int height; @@ -489,17 +489,17 @@ char *c, *d; \endcode - \o Wait with declaring a variable until it is needed. This is especially + \li Wait with declaring a variable until it is needed. This is especially important when initialization is done at the same time. \endlist \section2 Namespaces \list - \o Put the left curly brace on the same line as the \namespace keyword. - \o Do not indent declarations or definitions inside. - \o Optional, but recommended if the namespaces spans more than a few lines: - Add a comment after the right curly brace repeating the namespace. + \li Put the left curly brace on the same line as the \namespace keyword. + \li Do not indent declarations or definitions inside. + \li Optional, but recommended if the namespaces spans more than a few lines: + Add a comment after the right curly brace repeating the namespace. \code namespace MyPlugin { @@ -509,8 +509,8 @@ } // namespace MyPlugin \endcode - \o As an exception, if there is only a single class declaration inside - the namespace, all can go on a single line: + \li As an exception, if there is only a single class declaration inside + the namespace, all can go on a single line: \code namespace MyPlugin { class MyClass; } \endcode @@ -526,11 +526,11 @@ The namespacing policy within Qt Creator is as follows: \list - \o Classes/Symbols of a library or plugin that are exported for use of - other libraries or plugins are in a namespace specific to that - library/plugin, e.g. \c{MyPlugin}. - \o Classes/Symbols of a library or plugin that are not exported are in - an additional \c{Internal} namespace, e.g. \c{MyPlugin::Internal}. + \li Classes/Symbols of a library or plugin that are exported for use of + other libraries or plugins are in a namespace specific to that + library/plugin, e.g. \c{MyPlugin}. + \li Classes/Symbols of a library or plugin that are not exported are in + an additional \c{Internal} namespace, e.g. \c{MyPlugin::Internal}. \endlist \section2 Passing File Names @@ -577,35 +577,35 @@ \section2 C++ Features \list - \o Do not use exceptions, unless you know what you do. + \li Do not use exceptions, unless you know what you do. - \o Do not use RTTI (Run-Time Type Information; that is, the typeinfo + \li Do not use RTTI (Run-Time Type Information; that is, the typeinfo struct, the dynamic_cast or the typeid operators, including throwing exceptions), unless you know what you do. - \o Do not use virtual inheritance, unless you know what you do. + \li Do not use virtual inheritance, unless you know what you do. - \o Use templates wisely, not just because you can. + \li Use templates wisely, not just because you can. Hint: Use the compile autotest to see whether a C++ feature is supported by all compilers in the test farm. - \o All code is ASCII only (7-bit characters only, run \c {man ascii} if unsure) + \li All code is ASCII only (7-bit characters only, run \c {man ascii} if unsure) \list - \o Rationale: We have too many locales inhouse and an unhealthy + \li Rationale: We have too many locales inhouse and an unhealthy mix of UTF-8 and Latin1 systems. Usually, characters > 127 can be broken without you even knowing by clicking Save in your favourite editor. - \o For strings: Use \\nnn (where nnn is the octal representation - of whatever locale you want your string in) or \xnn (where nn + \li For strings: Use \\nnn (where nnn is the octal representation + of whatever locale you want your string in) or \\xnn (where nn is hexadecimal). For example: QString s = QString::fromUtf8("\\213\\005"); - \o For umlauts in documentation, or other non-ASCII characters, + \li For umlauts in documentation, or other non-ASCII characters, either use the qdoc \c {\unicode} command or use the relevant macro. For example: \c{\uuml} for \uuml. \endlist - \o Use static keywords instead of anonymous namespaces whenever possible. + \li Use static keywords instead of anonymous namespaces whenever possible. A name localized to the compilation unit with static is guaranteed to have internal linkage. For names declared in anonymous namespaces, the C++ standard unfortunately mandates external linkage @@ -640,10 +640,10 @@ \section2 Using QObject \list - \o Every QObject subclass must have a Q_OBJECT macro, even if it + \li Every QObject subclass must have a Q_OBJECT macro, even if it does not have signals or slots, if it is intended to be used with qobject_cast<>. See also \l{Casting}. - \o Normalize the arguments for signals and slots + \li Normalize the arguments for signals and slots (see \l{http://qt-project.org/doc/qt-4.8/qmetaobject.html#normalizedSignature}{QMetaObject::normalizedSignature} inside connect statements to safely make signal and slot lookup a few cycles faster. @@ -658,34 +658,34 @@ \section2 Including Headers \list - \o Use the following format to include Qt headers: + \li Use the following format to include Qt headers: \c{#include <QWhatEver>}. Do not include the module as it might have changed between Qt4 and Qt5. - \o Arrange includes in an order that goes from specific to generic to + \li Arrange includes in an order that goes from specific to generic to ensure that the headers are self-contained. For example: \list - \o \c{#include "myclass.h"} - \o \c{#include "otherclassinplugin.h"} - \o \c{#include <otherplugin/someclass.h>} - \o \c{#include <QtClass>} - \o \c{#include <stdthing>} - \o \c{#include <system.h>} + \li \c{#include "myclass.h"} + \li \c{#include "otherclassinplugin.h"} + \li \c{#include <otherplugin/someclass.h>} + \li \c{#include <QtClass>} + \li \c{#include <stdthing>} + \li \c{#include <system.h>} \endlist - \o Enclose headers from other plugins in square brackets (<>) rather than + \li Enclose headers from other plugins in square brackets (<>) rather than quotation marks ("") to make it easier to spot external dependencies in the sources. - \o Add empty lines between long blocks of \e peer headers and try to + \li Add empty lines between long blocks of \e peer headers and try to arrange the headers in alphabetic order within a block. \endlist \section2 Casting \list - \o Avoid C casts, prefer C++ casts (\c static_cast, \c const_cast, + \li Avoid C casts, prefer C++ casts (\c static_cast, \c const_cast, \c reinterpret_cast) Both \c reinterpret_cast and C-style casts are dangerous, but at least \c reinterpret_cast will not remove the const modifier. - \o Do not use \c dynamic_cast, use \c {qobject_cast} for QObjects, or + \li Do not use \c dynamic_cast, use \c {qobject_cast} for QObjects, or refactor your design, for example by introducing a \c {type()} method (see QListWidgetItem), unless you know what you do. \endlist @@ -693,7 +693,7 @@ \section2 Compiler and Platform-specific Issues \list - \o Be extremely careful when using the question mark operator. + \li Be extremely careful when using the question mark operator. If the returned types are not identical, some compilers generate code that crashes at runtime (you will not even get a compiler warning): \code @@ -702,7 +702,7 @@ return condition ? s : "nothing"; \endcode - \o Be extremely careful about alignment. + \li Be extremely careful about alignment. Whenever a pointer is cast such that the required alignment of the target is increased, the resulting code might crash at runtime @@ -721,7 +721,7 @@ }; \endcode - \o Anything that has a constructor or needs to run code to be + \li Anything that has a constructor or needs to run code to be initialized cannot be used as global object in library code, since it is undefined when that constructor or code will be run (on first usage, on library load, before \c {main()} or not at all). @@ -784,7 +784,7 @@ will be run the first time the function is entered. The code is not reentrant, though. - \o A \c char is signed or unsigned dependent on the architecture. Use signed + \li A \c char is signed or unsigned dependent on the architecture. Use signed \c char or \c uchar if you explicitly want a signed or unsigned char. The following code will break on PowerPC, for example: @@ -796,11 +796,11 @@ } \endcode - \o Avoid 64-bit enum values. The AAPCS (Procedure Call Standard + \li Avoid 64-bit enum values. The AAPCS (Procedure Call Standard for the ARM Architecture) embedded ABI hard codes all enum values to a 32-bit integer. - \o Do not mix const and non-const iterators. This will silently crash + \li Do not mix const and non-const iterators. This will silently crash on broken compilers. \code for (Container::const_iterator it = c.constBegin(); it != c.constEnd(); ++it) @@ -814,12 +814,12 @@ \section2 Esthetics \list - \o Prefer enums to define const over static const int or defines. - Enumeration values will be replaced by the compiler at compile time, - resulting in faster code. Defines are not namespace safe. - \o Prefer verbose argument names in headers. - Qt Creator will show the argument names in their completion box. - It will look better in the documentation. + \li Prefer enums to define const over static const int or defines. + Enumeration values will be replaced by the compiler at compile time, + resulting in faster code. Defines are not namespace safe. + \li Prefer verbose argument names in headers. + Qt Creator will show the argument names in their completion box. + It will look better in the documentation. \endlist \section2 Inheriting from Template or Tool Classes @@ -828,8 +828,8 @@ pitfalls: \list - \o The destructors are not virtual, which can lead to memory leaks. - \o The symbols are not exported (and mostly inline), which can lead to + \li The destructors are not virtual, which can lead to memory leaks. + \li The symbols are not exported (and mostly inline), which can lead to symbol clashes. \endlist @@ -845,16 +845,16 @@ \list - \o No C style casts (\c{-Wold-style-cast}). Use \c static_cast, \c const_cast + \li No C style casts (\c{-Wold-style-cast}). Use \c static_cast, \c const_cast or \c reinterpret_cast, for basic types, use the constructor form: \c {int(a)} instead of \c {(int)a}. For more information, see \l{Casting}. - \o No float comparisons (\c{-Wfloat-equal}). Use \c qFuzzyCompare to compare + \li No float comparisons (\c{-Wfloat-equal}). Use \c qFuzzyCompare to compare values with a delta. Use \c qIsNull to check whether a float is binary 0, instead of comparing it to 0.0, or, preferred, move such code into an implementation file. - \o Do not hide virtual methods in subclasses (\{-Woverloaded-virtual}). + \li Do not hide virtual methods in subclasses (\{-Woverloaded-virtual}). If the baseclass A has a virtual \c {int val()} and subclass B an overload with the same name, \c {int val(int x)}, the A \c val function is hidden. Use the \c using keyword to make it visible again, and @@ -870,14 +870,14 @@ }; \endcode - \o Do not shadow variables (\c{-Wshadow}). + \li Do not shadow variables (\c{-Wshadow}). - \o Avoid things like \c {this->x = x;} if possible. + \li Avoid things like \c {this->x = x;} if possible. - \o Do not give variables the same name as functions declared in + \li Do not give variables the same name as functions declared in your class. - \o To improve code readability, always check whether a preprocessor + \li To improve code readability, always check whether a preprocessor variable is defined before probing its value (\c{-Wundef}). \code @@ -892,8 +892,8 @@ #if Foo - 0 == 0 \endcode - \o When checking for a preprocessor define using the \c{defined} - operator, always include the variable name in parentheses. + \li When checking for a preprocessor define using the \c{defined} + operator, always include the variable name in parentheses. \code #if defined(Foo) diff --git a/doc/api/creating-plugins.qdoc b/doc/api/creating-plugins.qdoc index c45d9eea9a..2145724a60 100644 --- a/doc/api/creating-plugins.qdoc +++ b/doc/api/creating-plugins.qdoc @@ -44,22 +44,22 @@ \section1 Basics \list - \o \l{Getting and Building Qt Creator} - \o \l{Creating Your First Plugin} - \o \l{Plugin Specifications} - \o \l{Plugin Life Cycle} + \li \l{Getting and Building Qt Creator} + \li \l{Creating Your First Plugin} + \li \l{Plugin Specifications} + \li \l{Plugin Life Cycle} \endlist \section1 Design Principles \list - \o \l{The Plugin Manager, the Object Pool, and Registered Objects} - \o \l{Aggregations} - \o \l{Extending and Providing Interfaces} + \li \l{The Plugin Manager, the Object Pool, and Registered Objects} + \li \l{Aggregations} + \li \l{Extending and Providing Interfaces} \endlist \section1 Creating 3rd-Party Plugins \list - \o \l{A Note on Binary Compatibility} - \o \l{Creating User-Installable Plugins} + \li \l{A Note on Binary Compatibility} + \li \l{Creating User-Installable Plugins} \endlist */ diff --git a/doc/api/external-tool-spec.qdoc b/doc/api/external-tool-spec.qdoc index 6dd114fad4..314d5669ab 100644 --- a/doc/api/external-tool-spec.qdoc +++ b/doc/api/external-tool-spec.qdoc @@ -49,20 +49,20 @@ \table \header - \o Tag - \o Meaning + \li Tag + \li Meaning \row - \o externaltool - \o Root element in the XML file that specifies an external tool. + \li externaltool + \li Root element in the XML file that specifies an external tool. \endtable \table \header - \o Attribute - \o Meaning + \li Attribute + \li Meaning \row - \o id - \o A string that identifies the external tool. - Two tools cannot have the same id. Required. + \li id + \li A string that identifies the external tool. + Two tools cannot have the same id. Required. \endtable \section2 Description Tags @@ -74,30 +74,30 @@ \table \header - \o Tag - \o Meaning + \li Tag + \li Meaning \row - \o description - \o Short, one-line description of what the tool is for. Required. + \li description + \li Short, one-line description of what the tool is for. Required. \row - \o displayname - \o Name to show in the menu item for the tool. Required. + \li displayname + \li Name to show in the menu item for the tool. Required. \row - \o category - \o Name of the category to show the tool in. - This is the name of the sub menu of the \c { Tools > External } - menu where the tool is placed. For example, specify the value - \c "Text" to display the tool in the \c { Tools > External > Text } - menu. Required. + \li category + \li Name of the category to show the tool in. + This is the name of the sub menu of the \c { Tools > External } + menu where the tool is placed. For example, specify the value + \c "Text" to display the tool in the \c { Tools > External > Text } + menu. Required. \endtable \table \header - \o Attribute - \o Meaning + \li Attribute + \li Meaning \row - \o xml:lang - \o Language code (such as, \c "en" or \c "de") of the language that is used for - the description, display name, or category. Optional. + \li xml:lang + \li Language code (such as, \c "en" or \c "de") of the language that is used for + the description, display name, or category. Optional. \endtable \section2 Executable Specification Tag @@ -107,32 +107,32 @@ \table \header - \o Tag - \o Meaning + \li Tag + \li Meaning \row - \o executable - \o Encloses subtags that specify what to run and which parameters to use. Required. + \li executable + \li Encloses subtags that specify what to run and which parameters to use. Required. \endtable \table \header - \o Attribute - \o Meaning + \li Attribute + \li Meaning \row - \o output - \o Specifies how to handle the tool's standard output stream. + \li output + \li Specifies how to handle the tool's standard output stream. Defaults to \c ShowInPane. Optional. \row - \o error - \o Specifies how to handle the tool's standard error stream. - Defaults to \c ShowInPane. Optional. + \li error + \li Specifies how to handle the tool's standard error stream. + Defaults to \c ShowInPane. Optional. \row - \o modifiesdocument - \o Specifies whether Qt Creator should expect changes to the current - document. If this flag is set, Qt Creator prompts users to save - changes to the current document before running the tool, - and silently reloads the current document after the tool has finished. - Possible values are: \c "yes" or \c "no" (defaults to \c "no"). - Optional. + \li modifiesdocument + \li Specifies whether Qt Creator should expect changes to the current + document. If this flag is set, Qt Creator prompts users to save + changes to the current document before running the tool, + and silently reloads the current document after the tool has finished. + Possible values are: \c "yes" or \c "no" (defaults to \c "no"). + Optional. \endtable The \c executable tag allows the following subtags. You must specify at least @@ -140,28 +140,28 @@ \table \header - \o Subtag - \o Meaning + \li Subtag + \li Meaning \row - \o path - \o File path to the executable to run, including filename. If you - specify the executable name without a path, Qt creator checks the - system PATH environment variable for a path to the executable. You - can specify the path multiple times. Qt Creator tries to resolve the - references in the given order and runs the first executable that it - finds. Required. + \li path + \li File path to the executable to run, including filename. If you + specify the executable name without a path, Qt creator checks the + system PATH environment variable for a path to the executable. You + can specify the path multiple times. Qt Creator tries to resolve the + references in the given order and runs the first executable that it + finds. Required. \row - \o arguments - \o Command line arguments for the executable. Specify the string in the - same format (with respect to quoting and argument splitting, for - example) as you would specify it on the command line of the platform - the tool runs on. Optional. + \li arguments + \li Command line arguments for the executable. Specify the string in the + same format (with respect to quoting and argument splitting, for + example) as you would specify it on the command line of the platform + the tool runs on. Optional. \row - \o workingdirectory - \o The working directory for the executable. Optional. + \li workingdirectory + \li The working directory for the executable. Optional. \row - \o input - \o A potentially multiline string that is passed to the tool via standard input stream. + \li input + \li A potentially multiline string that is passed to the tool via standard input stream. \endtable \section1 Example diff --git a/doc/api/first-plugin.qdoc b/doc/api/first-plugin.qdoc index 1ee6868508..0f14611e58 100644 --- a/doc/api/first-plugin.qdoc +++ b/doc/api/first-plugin.qdoc @@ -36,81 +36,81 @@ your plugin with. \list 1 - \o Select \gui{File > New File or Project > Libraries > Qt Creator Plugin > Choose}. + \li Select \gui{File > New File or Project > Libraries > Qt Creator Plugin > Choose}. - \image firstplugin-wizard.png "Choose the \QC Plugin Wizard" + \image firstplugin-wizard.png "Choose the \QC Plugin Wizard" - The \gui{Introduction and Project Location} dialog opens. + The \gui{Introduction and Project Location} dialog opens. - \image firstplugin-nameandpath.png "Choose Name and Place of the Project" + \image firstplugin-nameandpath.png "Choose Name and Place of the Project" - \o Give your project a name and specify in which path - this project will be created. The actual plugin's name can be different - from the project name. You will choose that name later in the wizard. - Continue to the next page. + \li Give your project a name and specify in which path + this project will be created. The actual plugin's name can be different + from the project name. You will choose that name later in the wizard. + Continue to the next page. - The \gui{Kit Selection} dialog opens. + The \gui{Kit Selection} dialog opens. - \image firstplugin-kitselection.png "Choose the kit to build and run your project with" + \image firstplugin-kitselection.png "Choose the kit to build and run your project with" - \o Select the \l{glossary-buildandrun-kit}{kit} to build and run your project with. - For a \QC plugin this needs to be a kit with \gui{Desktop} device type, - and a Qt version that is compatible with the Qt version that your - \QC was built with (in the best case the exact same build). - If you use an incompatible Qt version to build your plugin, you - will get errors while \QC tries to load your plugin. - Continue to the next page. + \li Select the \l{glossary-buildandrun-kit}{kit} to build and run your project with. + For a \QC plugin this needs to be a kit with \gui{Desktop} device type, + and a Qt version that is compatible with the Qt version that your + \QC was built with (in the best case the exact same build). + If you use an incompatible Qt version to build your plugin, you + will get errors while \QC tries to load your plugin. + Continue to the next page. - The \gui{Plugin Information} dialog opens. + The \gui{Plugin Information} dialog opens. - \image firstplugin-pluginsetup.png "Specify Your Plugin Details" + \image firstplugin-pluginsetup.png "Specify Your Plugin Details" - \o In the \gui{Plugin name} field, type \gui{Example}. The name of the plugin - is used as its identifier, and also is the base for the file names and - classes in the code. + \li In the \gui{Plugin name} field, type \gui{Example}. The name of the plugin + is used as its identifier, and also is the base for the file names and + classes in the code. - \o The values of the following fields are mainly informational, and - are shown in the detailed view in \QC's plugin overview - (\gui{Help > About Plugins}, or \gui{Qt Creator > About Plugins} - on Mac). + \li The values of the following fields are mainly informational, and + are shown in the detailed view in \QC's plugin overview + (\gui{Help > About Plugins}, or \gui{Qt Creator > About Plugins} + on Mac). - \list - \o \gui{Vendor name} is a short one-word name of the company - or organization that created the plugin. This is also used for - the path name where the plugin will be deployed to. - \o \gui{Copyright} is a one-line, short copyright string. - \o \gui{License} is a multi-line license text (but shouldn't be pages over pages long, - since the interface doesn't allow nice reading of long texts). - \o \gui{Description} is a relatively short, but - possibly multi-line description of what the plugin does. - \o \gui{URL} is a website where the user can find more - information about the plugin and/or organization providing it. + \list + \li \gui{Vendor name} is a short one-word name of the company + or organization that created the plugin. This is also used for + the path name where the plugin will be deployed to. + \li \gui{Copyright} is a one-line, short copyright string. + \li \gui{License} is a multi-line license text (but shouldn't be pages over pages long, + since the interface doesn't allow nice reading of long texts). + \li \gui{Description} is a relatively short, but + possibly multi-line description of what the plugin does. + \li \gui{URL} is a website where the user can find more + information about the plugin and/or organization providing it. \endlist - \o Set the \gui{Qt Creator sources} and \gui{Qt Creator build} fields to - the source and build directory of the \QC - instance you want to use to test your plugin with, respectively. - If you don't do that correctly you will get compile errors for your - plugin, and your plugin might not show up in \QC at all. - - \o In the \gui{Deploy into} list, select \gui{Qt Creator build}. This sets - your .pro file up to deploy your plugin directly into your \QC build's - plugin directory (requires you to have write permissions there). - The other option, \gui{Local user settings}, sets your .pro file up to - deploy your plugin into \QC's user plugin path - (for example \c{~/.config/QtProject/qtcreator/plugins} on Unix systems). - We choose \gui{Qt Creator build} because we use a self-compiled - \QC, and want the plugin to be only loaded by that \QC - instance. - Continue to the next page. - - The \gui{Project Management} dialog opens. - - \image firstplugin-summary.png "Summary of Created Files" - - \o Review the files that will be created, choose a version control - system that \QC should use for your project (always a good idea!), - and finish the wizard. + \li Set the \gui{Qt Creator sources} and \gui{Qt Creator build} fields to + the source and build directory of the \QC + instance you want to use to test your plugin with, respectively. + If you don't do that correctly you will get compile errors for your + plugin, and your plugin might not show up in \QC at all. + + \li In the \gui{Deploy into} list, select \gui{Qt Creator build}. This sets + your .pro file up to deploy your plugin directly into your \QC build's + plugin directory (requires you to have write permissions there). + The other option, \gui{Local user settings}, sets your .pro file up to + deploy your plugin into \QC's user plugin path + (for example \c{~/.config/QtProject/qtcreator/plugins} on Unix systems). + We choose \gui{Qt Creator build} because we use a self-compiled + \QC, and want the plugin to be only loaded by that \QC + instance. + Continue to the next page. + + The \gui{Project Management} dialog opens. + + \image firstplugin-summary.png "Summary of Created Files" + + \li Review the files that will be created, choose a version control + system that \QC should use for your project (always a good idea!), + and finish the wizard. \endlist \section1 Building and Running the Plugin @@ -138,26 +138,26 @@ \table \header - \o File - \o Role + \li File + \li Role \row - \o \c{Example.pluginspec.in} - \o Template plugin specification. QMake creates a \c{Example.pluginspec} - from this file, which is read by \QC to find out about the plugin. + \li \c{Example.pluginspec.in} + \li Template plugin specification. QMake creates a \c{Example.pluginspec} + from this file, which is read by \QC to find out about the plugin. \row - \o \c{example.pro} - \o Project file, used by QMake to generate a Makefile that then is used to - build the plugin. + \li \c{example.pro} + \li Project file, used by QMake to generate a Makefile that then is used to + build the plugin. \row - \o \c{example_global.h} - \o Contains macro definitions that are useful when this plugin should export - symbols to other plugins. + \li \c{example_global.h} + \li Contains macro definitions that are useful when this plugin should export + symbols to other plugins. \row - \o \c{exampleconstants.h} - \o Header defining constants used by the plugin code. + \li \c{exampleconstants.h} + \li Header defining constants used by the plugin code. \row - \o \c{exampleplugin.h/.cpp} - \o C++ header and source files that define the plugin class that will be + \li \c{exampleplugin.h/.cpp} + \li C++ header and source files that define the plugin class that will be instanciated and run by \QC's plugin manager. \endtable diff --git a/doc/api/plugin-lifecycle.qdoc b/doc/api/plugin-lifecycle.qdoc index a9393b0132..171ab55c35 100644 --- a/doc/api/plugin-lifecycle.qdoc +++ b/doc/api/plugin-lifecycle.qdoc @@ -27,69 +27,69 @@ When you start \QC, the plugin manager does the following: \list 1 - \o Looks in its search paths for - all .pluginspec files, and reads them. This is the first point where - loading a plugin can fail in the worst case of a malformed plugin spec. - - \o Creates an instance of the \l{ExtensionSystem::PluginSpec} class for - each plugin. This class is a container for - all the information from the plugin specification, and additionally - tracks the state of the plugin. - You can get the \l{ExtensionSystem::PluginSpec} instances via the - plugin manager's \l{ExtensionSystem::PluginManager::plugins()}{plugins()} - method, or, after a plugin is loaded, through the plugin's - \l{ExtensionSystem::IPlugin::pluginSpec()}{pluginSpec()} method. - - \o Sets the plugins to \c Read state. - - \o Verifies that the dependencies of each plugin - exist and are compatible. For more information about plugin dependencies, - see \l{Plugin Specifications}. - - \o Sets the plugins to \c Resolved state. - - \o Sorts all plugins into a list that we call the \e{load queue}, where the - dependencies of a plugin are positioned after the plugin - (but not necessarily \e directly after the plugin). - It will make sure that we load - and initialize the plugins in proper order. - - \o Loads the plugins' libraries, and creates their IPlugin instances - in the order of the load queue. At this point the - plugin constructors are called. Plugins that other plugins depend on - are created first. - - \o Sets the plugins to \c Loaded state. - - \o Calls the \l{ExtensionSystem::IPlugin::initialize()}{initialize()} methods of - all plugins in the order of the load queue. In the \c initialize method, - a plugin should make sure that all exported interfaces are set up and available - to other plugins. A plugin can assume that plugins they depend on have set up - their exported interfaces. For example, the \c Core plugin sets up the - \l{Core::ActionManager}, \l{Core::EditorManager} and all other publicly available - interfaces, so other plugins can request and use them. - - The \l{ExtensionSystem::IPlugin::initialize()}{initialize()} method of a plugin - is a good place for - \list - \o registering objects in the plugin manager's object pool - (see \l{The Plugin Manager, the Object Pool, and Registered Objects}) - \o loading settings - \o adding new menus, and new actions to menus - \o connecting to other plugin's signals. + \li Looks in its search paths for + all .pluginspec files, and reads them. This is the first point where + loading a plugin can fail in the worst case of a malformed plugin spec. + + \li Creates an instance of the \l{ExtensionSystem::PluginSpec} class for + each plugin. This class is a container for + all the information from the plugin specification, and additionally + tracks the state of the plugin. + You can get the \l{ExtensionSystem::PluginSpec} instances via the + plugin manager's \l{ExtensionSystem::PluginManager::plugins()}{plugins()} + method, or, after a plugin is loaded, through the plugin's + \l{ExtensionSystem::IPlugin::pluginSpec()}{pluginSpec()} method. + + \li Sets the plugins to \c Read state. + + \li Verifies that the dependencies of each plugin + exist and are compatible. For more information about plugin dependencies, + see \l{Plugin Specifications}. + + \li Sets the plugins to \c Resolved state. + + \li Sorts all plugins into a list that we call the \e{load queue}, where the + dependencies of a plugin are positioned after the plugin + (but not necessarily \e directly after the plugin). + It will make sure that we load + and initialize the plugins in proper order. + + \li Loads the plugins' libraries, and creates their IPlugin instances + in the order of the load queue. At this point the + plugin constructors are called. Plugins that other plugins depend on + are created first. + + \li Sets the plugins to \c Loaded state. + + \li Calls the \l{ExtensionSystem::IPlugin::initialize()}{initialize()} methods of + all plugins in the order of the load queue. In the \c initialize method, + a plugin should make sure that all exported interfaces are set up and available + to other plugins. A plugin can assume that plugins they depend on have set up + their exported interfaces. For example, the \c Core plugin sets up the + \l{Core::ActionManager}, \l{Core::EditorManager} and all other publicly available + interfaces, so other plugins can request and use them. + + The \l{ExtensionSystem::IPlugin::initialize()}{initialize()} method of a plugin + is a good place for + \list + \li registering objects in the plugin manager's object pool + (see \l{The Plugin Manager, the Object Pool, and Registered Objects}) + \li loading settings + \li adding new menus, and new actions to menus + \li connecting to other plugin's signals. \endlist - \o Sets the plugins to \c Initialized state. + \li Sets the plugins to \c Initialized state. - \o Calls the \l{ExtensionSystem::IPlugin::extensionsInitialized()}{extensionsInitialized()} - methods of all plugins in \e reverse order of the load queue. After - the \c extensionsInitialized method, a plugin should be fully initialized, set up - and running. A plugin can assume that plugins that depend on it are fully set up, - and can finish the initialization of parts that can be extended by other plugins. - For example, the \c Core plugin assumes that all plugins have registered - their actions, and finishes initialization of the action manager. + \li Calls the \l{ExtensionSystem::IPlugin::extensionsInitialized()}{extensionsInitialized()} + methods of all plugins in \e reverse order of the load queue. After + the \c extensionsInitialized method, a plugin should be fully initialized, set up + and running. A plugin can assume that plugins that depend on it are fully set up, + and can finish the initialization of parts that can be extended by other plugins. + For example, the \c Core plugin assumes that all plugins have registered + their actions, and finishes initialization of the action manager. - \o Sets the plugins to \c Running state. + \li Sets the plugins to \c Running state. \endlist At the end of startup, the \c Core plugin's \l{Core::ICore} sends two signals. @@ -111,19 +111,19 @@ plugin manager starts its shutdown sequence: \list 1 - \o Calls the \l{ExtensionSystem::IPlugin::aboutToShutdown()}{aboutToShutdown()} methods of - all plugins in the order of the load queue. Plugins should perform measures - for speeding up the actual shutdown here, like disconnecting signals that - would otherwise needlessly be called. - If a plugin needs to delay the real shutdown for a while, for example if - it needs to wait for external processes to finish for a clean shutdown, - the plugin can return \l{ExtensionSystem::IPlugin::AsynchronousShutdown} from this - method. This will make the plugin manager wait with the next step, and keep the main - event loop running, until all plugins requesting AsynchronousShutdown have sent - the asynchronousShutdownFinished() signal. - - \o Destroys all plugins by deleting their \l{ExtensionSystem::IPlugin} - instances in \e reverse order of the load queue. At this point the plugin destructors - are called. Plugins should clean up after themselves by freeing memory and other resources. + \li Calls the \l{ExtensionSystem::IPlugin::aboutToShutdown()}{aboutToShutdown()} methods of + all plugins in the order of the load queue. Plugins should perform measures + for speeding up the actual shutdown here, like disconnecting signals that + would otherwise needlessly be called. + If a plugin needs to delay the real shutdown for a while, for example if + it needs to wait for external processes to finish for a clean shutdown, + the plugin can return \l{ExtensionSystem::IPlugin::AsynchronousShutdown} from this + method. This will make the plugin manager wait with the next step, and keep the main + event loop running, until all plugins requesting AsynchronousShutdown have sent + the asynchronousShutdownFinished() signal. + + \li Destroys all plugins by deleting their \l{ExtensionSystem::IPlugin} + instances in \e reverse order of the load queue. At this point the plugin destructors + are called. Plugins should clean up after themselves by freeing memory and other resources. \endlist */ diff --git a/doc/api/plugin-specifications.qdoc b/doc/api/plugin-specifications.qdoc index 1b0d48c97a..acbeca5569 100644 --- a/doc/api/plugin-specifications.qdoc +++ b/doc/api/plugin-specifications.qdoc @@ -35,50 +35,50 @@ and \c disabledByDefault. \table \header - \o Tag - \o Meaning + \li Tag + \li Meaning \row - \o plugin - \o Root element in a plugin's XML file. + \li plugin + \li Root element in a plugin's XML file. \endtable \table \header - \o Attribute - \o Meaning + \li Attribute + \li Meaning \row - \o name - \o This is used as an identifier for the plugin and can e.g. - be referenced in other plugin's dependencies. It is - also used to construct the name of the plugin library - as \c{lib[name].[dll|.so|.dylib]}. (Depending on platform. - If you use the same string as the \c TARGET in your plugin's - .pro-file, you are fine.) + \li name + \li This is used as an identifier for the plugin and can e.g. + be referenced in other plugin's dependencies. It is + also used to construct the name of the plugin library + as \c{lib[name].[dll|.so|.dylib]}. (Depending on platform. + If you use the same string as the \c TARGET in your plugin's + .pro-file, you are fine.) \row - \o version - \o Version string in the form \c{x.y.z_n}, used for identifying - the plugin. Also see \l{A Note on Plugin Versions}. + \li version + \li Version string in the form \c{x.y.z_n}, used for identifying + the plugin. Also see \l{A Note on Plugin Versions}. \row - \o compatVersion - \o Optional. If not given, it is implicitly - set to the same value as \c version. The compatibility version - states which version of this plugin the current version is - binary backward compatible with and is used to resolve dependencies - on this plugin. I.e. a \c version of \c{2.1.1} and a - \c compatVersion of \c{2.0.0} means that this version \c{2.1.1} of the plugin - is binary backward compatible with all versions of the plugin down to \c{2.0.0} - (inclusive). + \li compatVersion + \li Optional. If not given, it is implicitly + set to the same value as \c version. The compatibility version + states which version of this plugin the current version is + binary backward compatible with and is used to resolve dependencies + on this plugin. I.e. a \c version of \c{2.1.1} and a + \c compatVersion of \c{2.0.0} means that this version \c{2.1.1} of the plugin + is binary backward compatible with all versions of the plugin down to \c{2.0.0} + (inclusive). \row - \o experimental - \o Optional. Can be \c true or \c false, defaults to \c false. - Experimental plugins are not loaded by default but must be explicitly - enabled by the user. This attribute should be enabled for new plugins which have the - potential to negatively affect the user experience. + \li experimental + \li Optional. Can be \c true or \c false, defaults to \c false. + Experimental plugins are not loaded by default but must be explicitly + enabled by the user. This attribute should be enabled for new plugins which have the + potential to negatively affect the user experience. \row - \o disabledByDefault - \o Optional. Can be \c true or \c false, defaults to \c false. - If set, the respective plugin is not loaded by default but must be explicitly - enabled by the user. This should be done for plugins which are not expected - to be used by so many people as to justify the additional resource consumption. + \li disabledByDefault + \li Optional. Can be \c true or \c false, defaults to \c false. + If set, the respective plugin is not loaded by default but must be explicitly + enabled by the user. This should be done for plugins which are not expected + to be used by so many people as to justify the additional resource consumption. \endtable \section2 Plugin-describing Tags @@ -88,38 +88,38 @@ are optional. \table \header - \o Tag - \o Meaning + \li Tag + \li Meaning \row - \o category - \o Defaults to \c Utilities. Is used to put related plugins - under the same tree node in the plugin overview \gui{About Plugins...}. + \li category + \li Defaults to \c Utilities. Is used to put related plugins + under the same tree node in the plugin overview \gui{About Plugins...}. \row - \o vendor - \o String that describes the plugin creator/vendor, - like \c{MyCompany}. + \li vendor + \li String that describes the plugin creator/vendor, + like \c{MyCompany}. \row - \o copyright - \o A short copyright notice, like \c{(C) 2007-2008 MyCompany}. + \li copyright + \li A short copyright notice, like \c{(C) 2007-2008 MyCompany}. \row - \o platform - \o A regular expression that matches the names of the platforms the plugin works on. - Omitting the tag implies that the plugin is loaded on all platforms. + \li platform + \li A regular expression that matches the names of the platforms the plugin works on. + Omitting the tag implies that the plugin is loaded on all platforms. \row - \o license - \o Possibly multi-line license information about the plugin. - Should still be kept relatively short, since the UI is not - designed for long texts. + \li license + \li Possibly multi-line license information about the plugin. + Should still be kept relatively short, since the UI is not + designed for long texts. \row - \o description - \o Possibly multi-line description of what the plugin is supposed - to provide. - Should still be kept relatively short, since the UI is not - designed for long texts. + \li description + \li Possibly multi-line description of what the plugin is supposed + to provide. + Should still be kept relatively short, since the UI is not + designed for long texts. \row - \o url - \o Link to further information about the plugin, like - \c{http://www.mycompany-online.com/products/greatplugin}. + \li url + \li Link to further information about the plugin, like + \c{http://www.mycompany-online.com/products/greatplugin}. \endtable \section2 Dependencies @@ -141,8 +141,8 @@ (as defined in the attributes of the plugin's \c plugin tag) matches the dependency if \list - \o its \c name matches \c dependencyName, and - \o \c {compatVersion <= dependencyVersion <= version}. + \li its \c name matches \c dependencyName, and + \li \c {compatVersion <= dependencyVersion <= version}. \endlist For example a dependency \code @@ -157,28 +157,28 @@ \table \header - \o Tag - \o Meaning + \li Tag + \li Meaning \row - \o dependency - \o Describes a dependency on another plugin. + \li dependency + \li Describes a dependency on another plugin. \endtable \table \header - \o Attribute - \o Meaning + \li Attribute + \li Meaning \row - \o name - \o The name of the plugin, on which this plugin relies. + \li name + \li The name of the plugin, on which this plugin relies. \row - \o version - \o The version to which the plugin must be compatible to - fill the dependency, in the form \c{x.y.z_n}. - Can be empty if the version does not matter. + \li version + \li The version to which the plugin must be compatible to + fill the dependency, in the form \c{x.y.z_n}. + Can be empty if the version does not matter. \row - \o type - \o Optional. Value \c required or \c optional. Defines if the dependency is - a hard requirement or optional. Defaults to \c{required}. + \li type + \li Optional. Value \c required or \c optional. Defines if the dependency is + a hard requirement or optional. Defaults to \c{required}. \endtable \section3 Optional Dependencies @@ -187,10 +187,10 @@ \c {type="optional"} attribute to the \c dependency tag: \list - \o If the dependency can be resolved, the plugin and - its dependency are loaded and initialized as for \c required dependencies. - \o If the dependency cannot be resolved, the plugin is loaded and initialized - as if the dependency was not declared at all. + \li If the dependency can be resolved, the plugin and + its dependency are loaded and initialized as for \c required dependencies. + \li If the dependency cannot be resolved, the plugin is loaded and initialized + as if the dependency was not declared at all. \endlist The plugin is not informed about the existence of optional dependencies in any way. Since the @@ -221,26 +221,26 @@ \table \header - \o Tag - \o Meaning + \li Tag + \li Meaning \row - \o argument - \o Describes a command line argument that the plugin wants to handle. + \li argument + \li Describes a command line argument that the plugin wants to handle. \endtable \table \header - \o Attribute - \o Meaning + \li Attribute + \li Meaning \row - \o name - \o The command line argument itself, including the \c - prefix, e.g. - \c{-my-parameter}. + \li name + \li The command line argument itself, including the \c - prefix, e.g. + \c{-my-parameter}. \row - \o parameter - \o Optional. If this is given, the command line argument expects an - additional parameter, e.g. \c{-my-parameter somevalue}. The - value of this attribute is used as a very short description of the - parameter for the user. + \li parameter + \li Optional. If this is given, the command line argument expects an + additional parameter, e.g. \c{-my-parameter somevalue}. The + value of this attribute is used as a very short description of the + parameter for the user. \endtable \section2 Example \c Test.pluginspec diff --git a/doc/api/pluginmanager.qdoc b/doc/api/pluginmanager.qdoc index 1a47ee6a3a..b74d1210be 100644 --- a/doc/api/pluginmanager.qdoc +++ b/doc/api/pluginmanager.qdoc @@ -44,48 +44,48 @@ \table \header - \o Method - \o Description + \li Method + \li Description \row - \o instance() - \o Returns the singleton plugin manager instance, for example for connecting to signals. + \li instance() + \li Returns the singleton plugin manager instance, for example for connecting to signals. \row - \o addObject() - \o Registers an object in the object pool. - Also available through ExtensionSystem::IPlugin::addObject(). + \li addObject() + \li Registers an object in the object pool. + Also available through ExtensionSystem::IPlugin::addObject(). \row - \o removeObject() - \o Unregisters an object from the object pool. - Also available through ExtensionSystem::IPlugin::removeObject(). + \li removeObject() + \li Unregisters an object from the object pool. + Also available through ExtensionSystem::IPlugin::removeObject(). \row - \o getObjects<T>() - \o Returns all objects of type T that are registered in the object pool. - This respects \l{Aggregations}. + \li getObjects<T>() + \li Returns all objects of type T that are registered in the object pool. + This respects \l{Aggregations}. \row - \o getObject<T>() - \o Returns one object of type T that is registered in the object pool. - This respects \l{Aggregations}. + \li getObject<T>() + \li Returns one object of type T that is registered in the object pool. + This respects \l{Aggregations}. \row - \o getObjectByName(const QString &name) - \o Returns one object with the given object name that is registered in the object pool. + \li getObjectByName(const QString &name) + \li Returns one object with the given object name that is registered in the object pool. \row - \o getObjectByClassName(const QString &className) - \o Returns one object with the given class name that is registered in the object pool. + \li getObjectByClassName(const QString &className) + \li Returns one object with the given class name that is registered in the object pool. \endtable \table \header - \o Signal - \o Description + \li Signal + \li Description \row - \o objectAdded(QObject *object) - \o Sent after an object is registered in the object pool. + \li objectAdded(QObject *object) + \li Sent after an object is registered in the object pool. \row - \o aboutToRemoveObject(QObject *object) - \o Sent just before an object is unregistered from the object pool. + \li aboutToRemoveObject(QObject *object) + \li Sent just before an object is unregistered from the object pool. \row - \o initializationDone() - \o Sent when plugins are running and all delayed initialization is done. + \li initializationDone() + \li Sent when plugins are running and all delayed initialization is done. \endtable \target object pool diff --git a/doc/api/qtcreator-api.qdoc b/doc/api/qtcreator-api.qdoc index 464e791c5b..d7f7eda17c 100644 --- a/doc/api/qtcreator-api.qdoc +++ b/doc/api/qtcreator-api.qdoc @@ -36,26 +36,26 @@ \table \header - \o Library Name - \o Description + \li Library Name + \li Description \row - \o \l{Aggregation} - \o Adds functionality for "glueing" QObjects of different - types together, so you can "cast" between them. + \li \l{Aggregation} + \li Adds functionality for "glueing" QObjects of different + types together, so you can "cast" between them. \row - \o \l{ExtensionSystem} - \o Implements the plugin loader framework. Provides a base class for plugins and - basic mechanisms for plugin interaction like an object pool. + \li \l{ExtensionSystem} + \li Implements the plugin loader framework. Provides a base class for plugins and + basic mechanisms for plugin interaction like an object pool. \row - \o \l{Utils} - \o General utility library. + \li \l{Utils} + \li General utility library. \row - \o \l{QmlJS} - \o QML and JavaScript language support library. + \li \l{QmlJS} + \li QML and JavaScript language support library. \endtable @@ -63,12 +63,12 @@ \table \header - \o Library Name - \o Description + \li Library Name + \li Description \row - \o \l{qtcreatorcdbext} - \o Windows CDB debugger extension + \li \l{qtcreatorcdbext} + \li Windows CDB debugger extension \endtable @@ -82,38 +82,37 @@ \table \header - \o Plugin Name - \o Description + \li Plugin Name + \li Description \row - \o \l{Core} - \o The core plugin. Provides the main window and managers for editors, + \li \l{Core} + \li The core plugin. Provides the main window and managers for editors, actions, mode windows and files, just to mention the most important ones. \row - \o \l{ProjectExplorer} - \o The project explorer plugin. Provides base classes for - project handling. + \li \l{ProjectExplorer} + \li The project explorer plugin. Provides base classes for project handling. \row - \o \l{Find} - \o Support for searching text in arbitrary widgets, and arbitrary other things. + \li \l{Find} + \li Support for searching text in arbitrary widgets, and arbitrary other things. \row - \o \l{Locator} - \o Hooks for providing content for Locator. + \li \l{Locator} + \li Hooks for providing content for Locator. \row - \o \l{Debugger} - \o Debugging functionality. + \li \l{Debugger} + \li Debugging functionality. \row - \o \l{VcsBase} - \o Base classes for version control support. + \li \l{VcsBase} + \li Base classes for version control support. \row - \o \l{TextEditor} - \o This is where everything starts if you want to create a text editor. Besides + \li \l{TextEditor} + \li This is where everything starts if you want to create a text editor. Besides the base editor itself, this plugin contains APIs for supporting functionality like \l{Snippets}{snippets}, highlighting, \l{CodeAssist}{code assist}, indentation and style, and others. @@ -159,90 +158,91 @@ \table \header - \o Task - \o Details - \o API + \li Task + \li Details + \li API \row - \o Add a menu or menu item. - \o You can extend existing menus or create new ones. - \o \l{Core::ActionManager}, \l{Core::Command} + \li Add a menu or menu item. + \li You can extend existing menus or create new ones. + \li \l{Core::ActionManager}, \l{Core::Command} \row - \o Add a configurable keyboard shortcut. - \o Registering shortcuts makes it possible for users to configure them in - the common shortcut settings dialog. - \o \l{Core::ActionManager}, \l{Core::Command} + \li Add a configurable keyboard shortcut. + \li Registering shortcuts makes it possible for users to configure them in + the common shortcut settings dialog. + \li \l{Core::ActionManager}, \l{Core::Command} \row - \o Add a mode. - \o Modes correspond to complete screens of controls, specialized for a task. - \o \l{Core::IMode} + \li Add a mode. + \li Modes correspond to complete screens of controls, specialized for a task. + \li \l{Core::IMode} \row - \o Add a new editor type. - \o Such as an editor for XML files. - \o \l{Core::IEditorFactory}, \l{Core::IEditor}, \l{Core::IDocument} + \li Add a new editor type. + \li Such as an editor for XML files. + \li \l{Core::IEditorFactory}, \l{Core::IEditor}, \l{Core::IDocument} \row - \o Add a new wizard. - \o You can extend the wizards in File > New File or Project with your own - file and project templates. - \o \l{Core::IWizard}, \l{Core::StandardFileWizard}, - \l{Core::BaseFileWizard}, \l{Core::BaseFileWizardParameters} + \li Add a new wizard. + \li You can extend the wizards in File > New File or Project with your own + file and project templates. + \li \l{Core::IWizard}, \l{Core::StandardFileWizard}, + \l{Core::BaseFileWizard}, \l{Core::BaseFileWizardParameters} \row - \o Add support for a new version control system. - \o Version control systems integrated in QtCreator are Bazaar, CVS, Git, - Mecurial, Perforce, and Subversion. - \o \l{Core::IVersionControl} + \li Add support for a new version control system. + \li Version control systems integrated in QtCreator are Bazaar, CVS, Git, + Mecurial, Perforce, and Subversion. + \li \l{Core::IVersionControl} \row - \o Add a view to the navigation sidebar. - \o The one which shows the project tree, filesystem, open documents or bookmarks. - \o \l{Core::INavigationWidgetFactory} + \li Add a view to the navigation sidebar. + \li The one which shows the project tree, filesystem, open documents or bookmarks. + \li \l{Core::INavigationWidgetFactory} \row - \o Add an options page to the \gui Options dialog. - \o Add a new page to existing or new category in Tools > Options. - \o \l{Core::IOptionsPage} + \li Add an options page to the \gui Options dialog. + \li Add a new page to existing or new category in Tools > Options. + \li \l{Core::IOptionsPage} \row - \o Add a find filter to the \gui Find dialog. - \o Implement any kind of search term based search. - \o \l{Find::IFindFilter}, \l{Find::SearchResultWindow} + \li Add a find filter to the \gui Find dialog. + \li Implement any kind of search term based search. + \li \l{Find::IFindFilter}, \l{Find::SearchResultWindow} \row - \o Add support for the find tool bar to a widget. - \o The widget that has focus is asked whether it supports text search. You can - add support for widgets under your control. - \o \l{Find::IFindSupport}, \l{Find::BaseTextFind} + \li Add support for the find tool bar to a widget. + \li The widget that has focus is asked whether it supports text search. You can + add support for widgets under your control. + \li \l{Find::IFindSupport}, \l{Find::BaseTextFind} \row - \o Add a completely new project type. - \o - \o + \li Add a completely new project type. + \li + \li \row - \o Add a new type of build step. - \o - \o + \li Add a new type of build step. + \li + \li \row - \o Add a new filter to the locator. - \o For a text typed in by the user you provide a list of things to show in the popup. When the user selects an entry you are requested to do whatever you want. - \o \l{Locator::ILocatorFilter}, \l{Locator::FilterEntry}, \l{Locator::BaseFileFilter} + \li Add a new filter to the locator. + \li For a text typed in by the user you provide a list of things to show in the popup. + When the user selects an entry you are requested to do whatever you want. + \li \l{Locator::ILocatorFilter}, \l{Locator::FilterEntry}, \l{Locator::BaseFileFilter} \row - \o Show a progress indicator for a concurrently running task. - \o You can show a progress indicator for your tasks in the left hand tool bar, - and also in the application icon (on platforms that support it). - \o \l{Core::ProgressManager}, \l{Core::FutureProgress} + \li Show a progress indicator for a concurrently running task. + \li You can show a progress indicator for your tasks in the left hand tool bar, + and also in the application icon (on platforms that support it). + \li \l{Core::ProgressManager}, \l{Core::FutureProgress} \row - \o - \o - \o + \li + \li + \li \endtable */ diff --git a/doc/api/qtcreator-dev-wizards.qdoc b/doc/api/qtcreator-dev-wizards.qdoc index 6966981c77..ca31a35104 100644 --- a/doc/api/qtcreator-dev-wizards.qdoc +++ b/doc/api/qtcreator-dev-wizards.qdoc @@ -31,40 +31,40 @@ Implementing wizards requires: \list - \o Deciding on a base class: + \li Deciding on a base class: \list - \o Core::IWizard is a very generic interface that does - not make any assumption about what the wizard does and - what its UI looks like. + \li Core::IWizard is a very generic interface that does + not make any assumption about what the wizard does and + what its UI looks like. - \o Core::BaseFileWizard should be used for wizards that - generate files using a UI based on Utils::Wizard. + \li Core::BaseFileWizard should be used for wizards that + generate files using a UI based on Utils::Wizard. \endlist - \o Providing a set of parameters that determine how the wizard shows up - in the list of wizards in the \gui{New File or Project} dialog. + \li Providing a set of parameters that determine how the wizard shows up + in the list of wizards in the \gui{New File or Project} dialog. - When deriving from Core::IWizard, virtual functions returning the - values have to be implemented. + When deriving from Core::IWizard, virtual functions returning the + values have to be implemented. - When deriving from Core::BaseFileWizard, a parameter class - Core::BaseFileWizardParameters needs to be passed to the constructor, - on which the parameters can be set. This allows for easy creation - of several wizard instances with slightly different parameters. + When deriving from Core::BaseFileWizard, a parameter class + Core::BaseFileWizardParameters needs to be passed to the constructor, + on which the parameters can be set. This allows for easy creation + of several wizard instances with slightly different parameters. - \o Implementing the wizard UI + \li Implementing the wizard UI - Typically, this will be a class derived from Utils::Wizard. - Utils::Wizard extends QWizard with the functionality to show a progress - bar on the left. + Typically, this will be a class derived from Utils::Wizard. + Utils::Wizard extends QWizard with the functionality to show a progress + bar on the left. - \o Implementing the wizard functionality + \li Implementing the wizard functionality - When deriving from Core::BaseFileWizard, a list of Core::GeneratedFile - needs to be populated with the files and their contents. - \note The files are not actually written to the disk. This will be - done by Core::BaseFileWizard after performing overwrite checks and prompting - the user accordingly. + When deriving from Core::BaseFileWizard, a list of Core::GeneratedFile + needs to be populated with the files and their contents. + \note The files are not actually written to the disk. This will be + done by Core::BaseFileWizard after performing overwrite checks and prompting + the user accordingly. \endlist @@ -72,44 +72,44 @@ \table \header - \o Class - \o Description + \li Class + \li Description \row - \o Core::IWizard - \o Qt Creator wizard interface, implementations of which are registered with - ExtensionSystem::PluginManager. + \li Core::IWizard + \li Qt Creator wizard interface, implementations of which are registered with + ExtensionSystem::PluginManager. \row - \o Core::BaseFileWizard - \o Inherits Core::IWizard and provides a base class for generating files with a UI - based on QWizard. + \li Core::BaseFileWizard + \li Inherits Core::IWizard and provides a base class for generating files with a UI + based on QWizard. \row - \o Core::BaseFileWizardParameters - \o Contains parameters for Core::BaseFileWizard. + \li Core::BaseFileWizardParameters + \li Contains parameters for Core::BaseFileWizard. \row - \o Core::GeneratedFile - \o A file as produced by Core::BaseFileWizard, containing name, contents and some - attributes. + \li Core::GeneratedFile + \li A file as produced by Core::BaseFileWizard, containing name, contents and some + attributes. \row - \o Utils::FileWizardPage - \o Introductory wizard page asking for file name and path. + \li Utils::FileWizardPage + \li Introductory wizard page asking for file name and path. \row - \o Utils::FileWizardDialog - \o A wizard dialog presenting a Utils::FileWizardPage, which can be extended - by custom pages. + \li Utils::FileWizardDialog + \li A wizard dialog presenting a Utils::FileWizardPage, which can be extended + by custom pages. \row - \o Utils::ProjectIntroPage - \o Introductory wizard page asking for project name and path. + \li Utils::ProjectIntroPage + \li Introductory wizard page asking for project name and path. \row - \o ProjectExplorer::BaseProjectWizardDialog - \o Base class for project wizard dialogs, presenting + \li ProjectExplorer::BaseProjectWizardDialog + \li Base class for project wizard dialogs, presenting a Utils::ProjectIntroPage. \endtable @@ -123,45 +123,45 @@ \table \header - \o Type - \o Parameter Name - \o Description + \li Type + \li Parameter Name + \li Description \row - \o Core::IWizard::WizardKind - \o kind - \o Enumeration value that indicates the type of the wizard (project, class, file). + \li Core::IWizard::WizardKind + \li kind + \li Enumeration value that indicates the type of the wizard (project, class, file). \row - \o QIcon - \o icon - \o Icon to show. + \li QIcon + \li icon + \li Icon to show. \row - \o QString - \o description - \o Descriptive text. + \li QString + \li description + \li Descriptive text. \row - \o QString - \o displayName - \o Name to be shown in the list. + \li QString + \li displayName + \li Name to be shown in the list. \row - \o QString - \o id - \o Unique identifier for the wizard. It also determines the order within a category. + \li QString + \li id + \li Unique identifier for the wizard. It also determines the order within a category. \row - \o QString - \o category - \o Identifier of the category under which the wizard is to be listed. It also - determines the order of the categories. + \li QString + \li category + \li Identifier of the category under which the wizard is to be listed. It also + determines the order of the categories. \ \row - \o QString - \o displayCategory - \o Description of the category. + \li QString + \li displayCategory + \li Description of the category. \endtable \section1 Example diff --git a/doc/api/qtcreator-dev.qdoc b/doc/api/qtcreator-dev.qdoc index 8a421f35b3..946bd92cb7 100644 --- a/doc/api/qtcreator-dev.qdoc +++ b/doc/api/qtcreator-dev.qdoc @@ -53,9 +53,9 @@ to which you can add your own snippets. \list - \o \l{http://doc.qt.digia.com/qtcreator/creator-completing-code.html#editing-code-snippets} + \li \l{http://doc.qt.digia.com/qtcreator/creator-completing-code.html#editing-code-snippets} {Snippets User Interface} - \o \l{Snippets} {Adding Snippets Groups} + \li \l{Snippets} {Adding Snippets Groups} \endlist \section2 File, Class and Project Templates @@ -64,9 +64,9 @@ own file and project templates by writing XML definition files for them. \list - \o \l{http://doc.qt.digia.com/qtcreator/creator-project-wizards.html} + \li \l{http://doc.qt.digia.com/qtcreator/creator-project-wizards.html} {Adding New Custom Wizards} - \o \l{User Interface Text Guidelines} + \li \l{User Interface Text Guidelines} \endlist \section2 Custom Wizards @@ -76,10 +76,10 @@ 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} - \o \l{Qt Creator Coding Rules} - \o \l{Creating Wizards in Code} - \o \l{User Interface Text Guidelines} + \li \l{Creating Plugins} + \li \l{Qt Creator Coding Rules} + \li \l{Creating Wizards in Code} + \li \l{User Interface Text Guidelines} \endlist \section1 Supporting Additional File Types @@ -96,9 +96,9 @@ 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.digia.com/qtcreator/creator-mime-types.html} + \li \l{http://doc.qt.digia.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} + \li \l{http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-latest.html} {MIME Type Specification Files} \endlist @@ -110,9 +110,9 @@ 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.digia.com/qtcreator/creator-editor-options.html#generic-highlighting} + \li \l{http://doc.qt.digia.com/qtcreator/creator-editor-options.html#generic-highlighting} {Generic Highlighting} - \o \l{http://kate-editor.org/2005/03/24/writing-a-syntax-highlighting-file/} + \li \l{http://kate-editor.org/2005/03/24/writing-a-syntax-highlighting-file/} {Writing a Syntax Highlighting File} \endlist @@ -125,10 +125,10 @@ 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} - \o \l{CodeAssist} {Providing Code Assist} + \li \l{Creating Plugins} + \li \l{Qt Creator Coding Rules} + \li \l{Text Editors} + \li \l{CodeAssist} {Providing Code Assist} \endlist \section2 Other Custom Editors @@ -136,9 +136,9 @@ 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} - \o \l{Editors} + \li \l{Creating Plugins} + \li \l{Qt Creator Coding Rules} + \li \l{Editors} \endlist \section1 Running External Tools @@ -162,9 +162,9 @@ to fill a feature suggestion. The tool descriptions are saved as XML files that you can share. \list - \o \l{http://doc.qt.digia.com/qtcreator/creator-editor-external.html} + \li \l{http://doc.qt.digia.com/qtcreator/creator-editor-external.html} {Using External Tools} - \o \l{External Tool Specification Files} + \li \l{External Tool Specification Files} \endlist \section2 Complex External Tools @@ -189,13 +189,13 @@ 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.digia.com/qtcreator/creator-editor-external.html} + \li \l{http://doc.qt.digia.com/qtcreator/creator-editor-external.html} {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} + \li \l{External Tool Specification Files} + \li \l{Creating Plugins} + \li \l{Qt Creator Coding Rules} + \li \l{Menus and Menu Items} + \li \l{Options Pages} \endlist \section3 Interacting with Tool Output @@ -214,39 +214,39 @@ the \gui {Issues} output pane. \list - \o \l{http://doc.qt.digia.com/qtcreator/creator-task-lists.html} + \li \l{http://doc.qt.digia.com/qtcreator/creator-task-lists.html} {Showing Task List Files in the Issues Pane} - \o \l{Creating Plugins} - \o \l{Qt Creator Coding Rules} - \o \l{Menus and Menu Items} - \o \l{Options Pages} - \o \l{Editors} + \li \l{Creating Plugins} + \li \l{Qt Creator Coding Rules} + \li \l{Menus and Menu Items} + \li \l{Options Pages} + \li \l{Editors} \endlist \section1 All Topics \list - \o \l{Developing Qt Creator Plugins} + \li \l{Developing Qt Creator Plugins} \list - \o \l{Creating Plugins} - \o \l{Menus and Menu Items} - \o \l{Creating Wizards in Code} - \o \l{Editors} - \o \l{Text Editors} - \o \l{Options Pages} + \li \l{Creating Plugins} + \li \l{Menus and Menu Items} + \li \l{Creating Wizards in Code} + \li \l{Editors} + \li \l{Text Editors} + \li \l{Options Pages} \endlist - \o Reference + \li Reference \list - \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{http://kate-editor.org/2005/03/24/writing-a-syntax-highlighting-file/} - {Highlight Definition Files} - \o \l{Qt Creator Variables} - \o \l{User Interface Text Guidelines} - \o \l{Writing Documentation} - \o \l{Qt Creator Coding Rules} - \o \l{Qt Creator API Reference} + \li \l{http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-latest.html} + {MIME Type Specification Files} + \li \l{External Tool Specification Files} + \li \l{http://kate-editor.org/2005/03/24/writing-a-syntax-highlighting-file/} + {Highlight Definition Files} + \li \l{Qt Creator Variables} + \li \l{User Interface Text Guidelines} + \li \l{Writing Documentation} + \li \l{Qt Creator Coding Rules} + \li \l{Qt Creator API Reference} \endlist \endlist diff --git a/doc/api/qtcreator-documentation.qdoc b/doc/api/qtcreator-documentation.qdoc index e2e9150d89..c6a715a745 100644 --- a/doc/api/qtcreator-documentation.qdoc +++ b/doc/api/qtcreator-documentation.qdoc @@ -36,14 +36,13 @@ \list - \o Overview topic, which describes the purpose of your plugin from the - viewpoint of \QC users + \li Overview topic, which describes the purpose of your plugin from the + viewpoint of \QC users - \o Procedure topics, which describe how to use your plugin as part of - \QC + \li Procedure topics, which describe how to use your plugin as part of \QC - \o Reference topics, which contain information that developers - occasionally need to look up (optional) + \li Reference topics, which contain information that developers + occasionally need to look up (optional) \endlist @@ -52,10 +51,10 @@ \list - \o Overview topic, which describes the architecture and use cases for - your plugin from the viewpoint of \QC developers + \li Overview topic, which describes the architecture and use cases for + your plugin from the viewpoint of \QC developers - \o API documentation, which is generated from code comments + \li API documentation, which is generated from code comments \endlist @@ -123,9 +122,9 @@ \list - \o nmake fixnavi (on Windows) + \li nmake fixnavi (on Windows) - \o make fixnavi (on Linux) + \li make fixnavi (on Linux) \endlist @@ -229,15 +228,15 @@ \list - \o Color reduction: Optimal 256 colors palette + \li Color reduction: Optimal 256 colors palette - \o Reduce colors to: 256 + \li Reduce colors to: 256 - \o Best compression (slow) + \li Best compression (slow) - \o Color quantization algorithm: NeuQuant neural-net (slow) + \li Color quantization algorithm: NeuQuant neural-net (slow) - \o External optimizers: OptiPNG o3 + \li External optimizers: OptiPNG o3 \endlist @@ -276,8 +275,8 @@ \list - \o nmake docs (on Windows) - \o make docs (on Linux and Mac OS) + \li nmake docs (on Windows) + \li make docs (on Linux and Mac OS) \endlist @@ -296,24 +295,24 @@ \list - \o html_docs - build \QC Manual in help format, but do not generate a - help file + \li html_docs - build \QC Manual in help format, but do not generate a + help file - \o dev_html_docs - build Extending \QC Manual in help format, but do - not generate a help file + \li dev_html_docs - build Extending \QC Manual in help format, but do + not generate a help file - \o qch_docs - build \QC Manual in help format and generate a help file - (.qch) + \li qch_docs - build \QC Manual in help format and generate a help file + (.qch) - \o dev_qch_docs - build Extending \QC Manual in help format and - generate a help file (.qch) + \li dev_qch_docs - build Extending \QC Manual in help format and + generate a help file (.qch) - \o docs_online - build \QC Manual and Extending \QC Manual in online - format + \li docs_online - build \QC Manual and Extending \QC Manual in online + format - \o html_docs_online - build \QC Manual in online format + \li html_docs_online - build \QC Manual in online format - \o dev_html_docs_online - build Extending \QC Manual in online format + \li dev_html_docs_online - build Extending \QC Manual in online format \endlist diff --git a/doc/api/qtcreator-ui-text.qdoc b/doc/api/qtcreator-ui-text.qdoc index 4ca8091517..55425b7bdd 100644 --- a/doc/api/qtcreator-ui-text.qdoc +++ b/doc/api/qtcreator-ui-text.qdoc @@ -31,15 +31,15 @@ \list - \o Consistent with existing Qt Creator UI terms + \li Consistent with existing Qt Creator UI terms - \o Short and concise + \li Short and concise - \o Neutral, descriptive, and factually correct + \li Neutral, descriptive, and factually correct - \o Unambigious + \li Unambigious - \o Translatable into different languages + \li Translatable into different languages \endlist @@ -75,21 +75,21 @@ \list - \o Use full stops in messages. + \li Use full stops in messages. - \o Never user full stops (.) at the end of menu item names. + \li Never user full stops (.) at the end of menu item names. - \o Place three full stops (...) at the end of menu item names that - open a dialog requiring user action. + \li Place three full stops (...) at the end of menu item names that + open a dialog requiring user action. - \o Use exclamation marks (!) only in text that demands extra attention - from the user or carries special weight. + \li Use exclamation marks (!) only in text that demands extra attention + from the user or carries special weight. - \o Use quotation marks ("") around variable values. For example, - \gui {Close Project "qtcreator"}. + \li Use quotation marks ("") around variable values. For example, + \gui {Close Project "qtcreator"}. - \o Do not use leading, trailing, or multiple spaces to align text in - messages, as translation tools might not handle them correctly. + \li Do not use leading, trailing, or multiple spaces to align text in + messages, as translation tools might not handle them correctly. \endlist @@ -139,15 +139,15 @@ \list - \o Cannot send log as selected message type. Text is too long. + \li Cannot send log as selected message type. Text is too long. - \o Cannot receive image. + \li Cannot receive image. - \o Cannot insert picture. Maximum text length is 120 characters. + \li Cannot insert picture. Maximum text length is 120 characters. - \o Image name already in use. + \li Image name already in use. - \o Folder name already in use. + \li Folder name already in use. \endlist @@ -157,9 +157,9 @@ \list - \o Example of Book Title Capitalization + \li Example of Book Title Capitalization - \o Example of sentence style capitalization + \li Example of sentence style capitalization \endlist @@ -175,13 +175,11 @@ \list - \o Titles (window, dialog, group box, tab, list view columns, and so - on) + \li Titles (window, dialog, group box, tab, list view columns, and so on) - \o Functions (menu items, buttons) + \li Functions (menu items, buttons) - \o Selectable items (combobox items, listbox items, tree list items, - and so on) + \li Selectable items (combobox items, listbox items, tree list items, and so on) \endlist @@ -193,11 +191,11 @@ \list 1 - \o Open to-title-case.html in a browser. + \li Open to-title-case.html in a browser. - \o Enter the UI text in the field. + \li Enter the UI text in the field. - \o Click \gui Convert. + \li Click \gui Convert. \endlist @@ -219,13 +217,13 @@ \list - \o Labels + \li Labels - \o Tool tips + \li Tool tips - \o Descriptive text + \li Descriptive text - \o Other non-heading or title text + \li Other non-heading or title text \endlist @@ -262,50 +260,50 @@ \table \header - \o Features of Languages or Writing Systems - \o Impact on Implementation + \li Features of Languages or Writing Systems + \li Impact on Implementation \row - \o Word order - \o Different languages have different word order rules. + \li Word order + \li Different languages have different word order rules. - Do not use run-time concatenation. Use complete phrases - and "%1" formatting instead. For example, use: + Do not use run-time concatenation. Use complete phrases + and "%1" formatting instead. For example, use: - \c{tr("Foo failed: %1").arg(message)} + \c{tr("Foo failed: %1").arg(message)} - instead of + instead of - \c {tr("Foo failed: ") + message} + \c {tr("Foo failed: ") + message} \row - \o Singular vs. plural vs. dual forms - \o Some languages do not have plural form (for example, Chinese - and Japanese), whereas some have a different form for dual. + \li Singular vs. plural vs. dual forms + \li Some languages do not have plural form (for example, Chinese + and Japanese), whereas some have a different form for dual. - Allow room for text expansion in the layout design. Some - languages need more space to indicate plurality or duality to - convey the needed information. + Allow room for text expansion in the layout design. Some + languages need more space to indicate plurality or duality to + convey the needed information. - For example, use + For example, use - \c {tr("%n files found", 0, number)} + \c {tr("%n files found", 0, number)} - instead of + instead of - \c {tr("%1 files found").arg(number)} + \c {tr("%1 files found").arg(number)} \row - \o Gender - \o Some languages have gender (feminine, masculine, neutral), - whereas some do not (for example, Finnish) or do not use it - extensively (for example, English). + \li Gender + \li Some languages have gender (feminine, masculine, neutral), + whereas some do not (for example, Finnish) or do not use it + extensively (for example, English). - Do not reuse text strings. The same term may not work in - another context due to the gender of the base word. + Do not reuse text strings. The same term may not work in + another context due to the gender of the base word. - Articles have a grammatical gender in some languages and - sentences cannot be as easily constructed as in English. Avoid - following types of constructs: + Articles have a grammatical gender in some languages and + sentences cannot be as easily constructed as in English. Avoid + following types of constructs: - \c {tr("%1 failed").arg(someCondition ? "the operation" : "opening a file")} + \c {tr("%1 failed").arg(someCondition ? "the operation" : "opening a file")} \endtable \section1 Common Qt Creator Terms @@ -323,88 +321,87 @@ \table \header - \o UI Text - \o Usage - \o Conventions + \li UI Text + \li Usage + \li Conventions \row - \o Context menu - \o Opens when users right-click on the screen. Contents depend on - the context. - \image qtcreator-context-menu.png "Context menu" - \o You can add menu items that are relevant in a particular - context. Follow the conventions for naming menu items. + \li Context menu + \li Opens when users right-click on the screen. Contents depend on + the context. + \image qtcreator-context-menu.png "Context menu" + \li You can add menu items that are relevant in a particular + context. Follow the conventions for naming menu items. \row - \o Dialog - \o User interface element that usually contains a number of - choices or allows the user to give input to the application. - Opens when users select a menu item or button. - \image qtcreator-dialog.png "Dialog" - \o Use the menu item or button name as the dialog name. You can - also combine the menu item or button name and the name of the - object that is managed in the dialog. For example, the \gui Add - button in the \gui Documentation options opens the - \gui {Add Documentation} dialog. + \li Dialog + \li User interface element that usually contains a number of + choices or allows the user to give input to the application. + Opens when users select a menu item or button. + \image qtcreator-dialog.png "Dialog" + \li Use the menu item or button name as the dialog name. You can + also combine the menu item or button name and the name of the + object that is managed in the dialog. For example, the \gui Add + button in the \gui Documentation options opens the + \gui {Add Documentation} dialog. \row - \o Locator - \o Allows you to browse not only files, but any items defined by - locator filters. - \image qtcreator-locator.png "Locator" - \o You can add locator filters. Check that the filter is not - already in use and give the filter a descriptive name. + \li Locator + \li Allows you to browse not only files, but any items defined by + locator filters. + \image qtcreator-locator.png "Locator" + \li You can add locator filters. Check that the filter is not + already in use and give the filter a descriptive name. \row - \o Menu - \o Contains menu items that represent commands or options and that - are logically grouped and displayed. A menu can also contain - submenus. - \image qtcreator-menu.png "Menu" - \o You can create new menus. Use short, but descriptive names that - are consistent with existing menu names. Use unambigious names. + \li Menu + \li Contains menu items that represent commands or options and that + are logically grouped and displayed. A menu can also contain + submenus. + \image qtcreator-menu.png "Menu" + \li You can create new menus. Use short, but descriptive names that + are consistent with existing menu names. Use unambigious names. \row - \o Menu item - \o Represents a command or an option for users to choose. - \image qtcreator-menu-item.png "Menu item" - \o You can add new items to menus. Use short, but descriptive - names that are consistent with existing menu names. Use - unambigious names. + \li Menu item + \li Represents a command or an option for users to choose. + \image qtcreator-menu-item.png "Menu item" + \li You can add new items to menus. Use short, but descriptive + names that are consistent with existing menu names. Use + unambigious names. \row - \o Message box - \o Dialog that provides feedback to users, in the form of status - information, a warning, or an error message. - \image qtcreator-error-message.png "Message box" - Output from Qt Creator should be displayed in output panes, - instead. - \o Use the event as the title and provide a solution in the - message box. + \li Message box + \li Dialog that provides feedback to users, in the form of status + information, a warning, or an error message. + \image qtcreator-error-message.png "Message box" + Output from Qt Creator should be displayed in output panes, + instead. + \li Use the event as the title and provide a solution in the + message box. \row - \o Mode - \o Modes correspond to complete screens of controls, specialized - for a task. - \image qtcreator-mode-selector.png "Mode selector" - \o You can add a mode for a new type of editor, for example. - Use descriptive, but short mode names. They have to fit in the - \gui {Mode selector}. + \li Mode + \li Modes correspond to complete screens of controls, specialized + for a task. + \image qtcreator-mode-selector.png "Mode selector" + \li You can add a mode for a new type of editor, for example. + Use descriptive, but short mode names. They have to fit in the + \gui {Mode selector}. \row - \o Output pane - \o A pane displayed in the task pane that displays output from Qt - Creator. - \image qtcreator-output-pane.png "Output pane" - \o Use descriptive names for output panes. + \li Output pane + \li A pane displayed in the task pane that displays output from Qt Creator. + \image qtcreator-output-pane.png "Output pane" + \li Use descriptive names for output panes. \row - \o Sidebar - \o A view available in the \gui Edit and \gui Debug modes that - you can use to browse projects, files, and bookmarks, and to - view the class hierarchy. - \image qtcreator-sidebar-menu.png "Sidebar" - \o You can add views to the sidebar menu. Use descriptive names - for them. + \li Sidebar + \li A view available in the \gui Edit and \gui Debug modes that + you can use to browse projects, files, and bookmarks, and to + view the class hierarchy. + \image qtcreator-sidebar-menu.png "Sidebar" + \li You can add views to the sidebar menu. Use descriptive names + for them. \row - \o View - \o An area of the screen that displays information for users and - provides them with functions for managing the information. - Available in \gui Debug mode, for interaction with the program - that is running under the control of the debugger. - \image qtcreator-debugger-views.png "Views" - \o Use descriptive names for views. + \li View + \li An area of the screen that displays information for users and + provides them with functions for managing the information. + Available in \gui Debug mode, for interaction with the program + that is running under the control of the debugger. + \image qtcreator-debugger-views.png "Views" + \li Use descriptive names for views. \endtable */ |