diff options
| author | Leena Miettinen <riitta-leena.miettinen@qt.io> | 2020-01-23 11:45:07 +0100 |
|---|---|---|
| committer | Leena Miettinen <riitta-leena.miettinen@qt.io> | 2020-01-27 09:05:07 +0000 |
| commit | 5fc456dd2283b2d1e6c4e6d34856052658f34cc4 (patch) | |
| tree | 7a7cd26a33014e401536a149fa47f6586b68c247 /doc/api | |
| parent | c9f90047ac701416e439f492069c1a0bb364fc08 (diff) | |
| download | qt-creator-5fc456dd2283b2d1e6c4e6d34856052658f34cc4.tar.gz | |
Doc: Rearrange files in the doc folder
Source and configuration files for each manual are now located in a
separate subdirectory, with common configuration files in doc/config.
doc
|_config
|_qtcreator
|_qtcreatordev
|_qtdesignstudio
Edit the config files accordingly.
Change-Id: Idc747a7c16e84f3e06add91234dc5fc908e64cc5
Reviewed-by: Eike Ziller <eike.ziller@qt.io>
Diffstat (limited to 'doc/api')
33 files changed, 0 insertions, 4647 deletions
diff --git a/doc/api/coding-style.qdoc b/doc/api/coding-style.qdoc deleted file mode 100644 index 3275dca8d4..0000000000 --- a/doc/api/coding-style.qdoc +++ /dev/null @@ -1,1397 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the Qt Creator documentation. -** -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** -****************************************************************************/ - -/*! - \previouspage qtcreator-ui-text.html - \page coding-style.html - \nextpage qtcreator-api.html - - \title Qt Creator Coding Rules - - \note This document is work in progress. - - The coding rules aim to guide Qt Creator developers, to help them write - understandable and maintainable code, and to minimize confusion and surprises. - - As usual, rules are not set in stone. If you have a good reason to break one, - do so. But first make sure that at least some other developers agree with you. - - To contribute to the main Qt Creator source, you should comply to the - following rules: - - \list - \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. - \li Write good C++ code. That is, readable, well commented when necessary, - and object-oriented. - \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. - \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. - \li Follow the guidelines in \l{Code Constructs}, \l{Formatting}, and - \l{Patterns and Practices}. - \li Document interfaces. Right now we use qdoc, but changing to doxygen - is being considered. - \endlist - - - \section1 Submitting Code - - To submit code to Qt Creator, you must understand the tools and mechanics as well as - the philosophy behind Qt development. For more information about how to set up - the development environment for working on Qt Creator and how to submit code - and documentation for inclusion, see - \l{https://wiki.qt.io/Qt_Contribution_Guidelines}{Qt Contribution Guidelines}. - - \section1 Binary and Source Compatibility - - The following list describes how the releases are numbered and defines - \e {binary compatibility} and \e {source code compatibility} between - releases: - - \list - \li \QC 3.0.0 is a \e {major release}, \QC 3.1.0 is a \e {minor - release}, and \QC 3.1.3 is a \e {patch release}. - \li \e {Backward binary compatibility} means that code linked to an - earlier version of the library still works. - \li \e {Forward binary compatibility} means that code linked to a - newer version of the library works with an older library. - \li \e {Source code compatibility} means that code compiles without - modification. - \endlist - - We do not currently guarantee binary nor source code - compatibility between major releases and minor releases. - - However, we try to preserve backward binary compatibility and - backward source code compatibility for patch releases within the same minor release: - \list - \li Soft API freeze: Starting shortly after the beta release of a minor release, - we start keeping backward source code compatibility within that minor release, - including its patch releases. This means that from that point, code that uses \QC API will - compile against the API of all coming versions of this minor release, including its - patch releases. There still might be occasional exceptions to this rule, which should - be properly communicated. - \li Hard API freeze: Starting with the release candidate of a minor release, - we keep backward source code compatibility within that minor release, including its - patch releases. We also start keeping backward binary compatibility, with the exception - that this will not be reflected in the plugins' compatVersion setting. So, \QC plugins - written against the release candidate will not actually load in the final release or - later versions, even though the binary compatibility of the libraries would - theoretically allow for it. See the section about plugin specs below. - \li Hard ABI freeze: Starting with the final release of a minor release, - we keep backward source code and binary compatibility for this release and all its - patch releases. - \endlist - - For preserving backward compatibility: - \list - \li Do not add or remove any public API (for example global functions, - public/protected/private member functions). - \li Do not reimplement functions (not even inlines, - nor protected or private functions). - \li Check - \l {https://wiki.qt.io/Binary_Compatibility_Workarounds}{Binary Compatibility Workarounds} - for ways to preserve binary compatibility. - \endlist - - For more information on binary compatibility, see - \l{http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C++}{Binary Compatibility Issues With C++}. - - From the viewpoint of \l{Plugin Specifications} this means that - \list - \li \QC plugins in patch releases will have the minor release as \c {compatVersion}. For - example the plugins from version 3.1.2 will have \c {compatVersion="3.1.0"}. - \li Pre-releases of the minor release, including the release candidate, - will still have themselves as the \c {compatVersion}, meaning that plugins compiled - against the final release will not load in the pre-releases. - \li \QC plugin developers can decide if their plugin requires a certain patch release - (or later) of other \QC plugins, or if they work with all patch releases of this minor - version, by setting the corresponding \c {version} when declaring the dependency on - the other plugin. The default for \QC plugins provided by the Qt Project is to require - the latest patch release. - \endlist - - For example, the \c {Find} plugin in \QC 3.1 beta (internal version number 3.0.82) will have - \code - <plugin name="Find" version="3.0.82" compatVersion="3.0.82"> - <dependencyList> - <dependency name="Core" version="3.0.82"/> - .... - \endcode - The \c {Find} plugin in \QC 3.1.0 final will have - \code - <plugin name="Find" version="3.1.0" compatVersion="3.1.0"> - <dependencyList> - <dependency name="Core" version="3.1.0"/> - .... - \endcode - The \c {Find} plugin in \QC 3.1.1 patch release will have version 3.1.1, will be - backward binary compatible with \c {Find} plugin version 3.1.0 (\c {compatVersion="3.1.0"}), - and will require a \c {Core} plugin that is binary backward compatible with \c {Core} - plugin version 3.1.1: - \code - <plugin name="Find" version="3.1.1" compatVersion="3.1.0"> - <dependencyList> - <dependency name="Core" version="3.1.1"/> - .... - \endcode - - \section1 Code Constructs - - Follow the guidelines for code constructs to make the code faster and - clearer. In addition, the guidelines allow you to take advantage of the strong - type checking in C++. - - \list - \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: - - \code - ++T; - --U; - - -NOT- - - T++; - U--; - \endcode - - \li Try to minimize evaluation of the same code over and over. This is - aimed especially at loops: - - \code - - Container::iterator end = large.end(); - for (Container::iterator it = large.begin(); it != end; ++it) { - ...; - } - - -NOT- - - for (Container::iterator it = large.begin(); - it != large.end(); ++it) { - ...; - } - \endcode - - - \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: - - \code - foreach (QWidget *widget, container) - doSomething(widget); - - -NOT- - - Container::iterator end = container.end(); - for (Container::iterator it = container.begin(); it != end; ++it) - doSomething(*it); - \endcode - - Make the loop variable const, if possible. This might prevent - unnecessary detaching of shared data: - - \code - foreach (const QString &name, someListOfNames) - doSomething(name); - - - NOT - - - foreach (QString name, someListOfNames) - doSomething(name); - \endcode - - \endlist - - \section1 Formatting - - \section2 Capitalizing Identifiers - - Use \l{http://en.wikipedia.org/wiki/CamelCase}{camel case} in identifiers. - - Capitalize the first word in an identifier as follows: - - \list - \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. Unscoped Enum - values contain some part of the name of the enum type. - \endlist - - \section2 Whitespace - - \list - \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 - - For pointers or references, always use a single space before an asterisk (*) - or an ampersand (&), but never after. - Avoid C-style casts when possible: - - \code - char *blockOfMemory = (char *)malloc(data.size()); - char *blockOfMemory = reinterpret_cast<char *>(malloc(data.size())); - - -NOT- - - char* blockOfMemory = (char* ) malloc(data.size()); - \endcode - - Of course, in this particulare case, using \c new might be an even better - option. - - \section3 Operator Names and Parentheses - - Do not use spaces between operator names and parentheses. The equation - marks (==) are a part of the operator name, and therefore, spaces make the - declaration look like an expression: - - \code - operator==(type) - - -NOT- - - operator == (type) - \endcode - - \section3 Function Names and Parentheses - - Do not use spaces between function names and parentheses: - - \code - void mangle() - - -NOT- - - void mangle () - \endcode - - \section3 Keywords - - Always use a single space after a keyword, and before a curly brace: - - \code - if (foo) { - } - - -NOT- - - if(foo){ - } - \endcode - - \section3 Comments - - In general, put one space after "//". To align text in multiline - comments, you can insert multiple spaces. - - \section2 Braces - - As a base rule, place the left curly brace on the same line as the - start of the statement: - - \code - if (codec) { - } - - -NOT- - - if (codec) - { - } - \endcode - - Exception: Function implementations and class declarations always have - the left brace in the beginning of a line: - - \code - static void foo(int g) - { - qDebug("foo: %i", g); - } - - class Moo - { - }; - \endcode - - Use curly braces when the body of a conditional statement contains more - than one line, and also if a single line statement is somewhat complex. - Otherwise, omit them: - - \code - if (address.isEmpty()) - return false; - - for (int i = 0; i < 10; ++i) - qDebug("%i", i); - - -NOT- - - if (address.isEmpty()) { - return false; - } - - for (int i = 0; i < 10; ++i) { - qDebug("%i", i); - } - \endcode - - Exception 1: Use braces also if the parent statement covers several - lines or if it wraps: - - \code - if (address.isEmpty() - || !isValid() - || !codec) { - return false; - } - \endcode - - \note This could be re-written as: - - \code - if (address.isEmpty()) - return false; - - if (!isValid()) - return false; - - if (!codec) - return false; - \endcode - - Exception 2: Use braces also in if-then-else blocks where either the - if-code or the else-code covers several lines: - - \code - if (address.isEmpty()) { - --it; - } else { - qDebug("%s", qPrintable(address)); - ++it; - } - - -NOT- - - if (address.isEmpty()) - --it; - else { - qDebug("%s", qPrintable(address)); - ++it; - } - \endcode - - \code - if (a) { - if (b) - ... - else - ... - } - - -NOT- - - if (a) - if (b) - ... - else - ... - \endcode - - Use curly braces when the body of a conditional statement is empty: - - \code - while (a) {} - - -NOT- - - while (a); - \endcode - - \section2 Parentheses - - Use parentheses to group expressions: - - \code - if ((a && b) || c) - - -NOT- - - if (a && b || c) - \endcode - - \code - (a + b) & c - - -NOT- - - a + b & c - \endcode - - \section2 Line Breaks - - \list - \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 - || otherOtherLongExpression) { - } - - -NOT- - - if (longExpression || - otherLongExpression || - otherOtherLongExpression) { - } - \endcode - \endlist - - \section2 Declarations - - \list - \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). - - \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. - - \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. - - \endlist - - \section3 Declaring Variables - - \list - \li Avoid global variables of class type to rule out initialization order problems. - Consider using \c Q_GLOBAL_STATIC if they cannot be avoided. - \li Declare global string literals as - \code - const char aString[] = "Hello"; - \endcode - \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. - \li Declare each variable on a separate line: - \code - QString a = "Joe"; - QString b = "Foo"; - - -NOT- - - QString a = "Joe", b = "Foo"; - \endcode - - \note \c{QString a = "Joe"} formally calls a copy constructor on a - temporary that is constructed from a string literal. Therefore, it is - potentially more expensive than direct construction by - \c {QString a("Joe")}. However, the compiler is allowed to elide the - copy (even if this has side effects), and modern compilers typically do - so. Given these equal costs, Qt Creator code favours the '=' idiom as - it is in - line with the traditional C-style initialization, it cannot be - mistaken as function declaration, and it reduces the level of nested - parantheses in more initializations. - - \li Avoid abbreviations: - - \code - int height; - int width; - char *nameOfThis; - char *nameOfThat; - - -NOT- - - int a, b; - char *c, *d; - \endcode - - \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 - \li Put the left curly brace on the same line as the \c 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 { - - void someFunction() { ... } - - } // namespace MyPlugin - \endcode - - \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 - - \li Do not use using-directives in header files. - - \li Do not rely on using-directives when defining classes and - functions, instead define it in a properly named declarative region. - - \li Do not rely on using-directives when accessing global functions. - - \li In other cases, you are encouraged to use using-directives, - as they help you avoid cluttering the code. Prefer putting all - using-directives near the top of the file, after all includes. - - \code - [in foo.cpp] - ... - #include "foos.h" - ... - #include <utils/filename.h> - ... - using namespace Utils; - - namespace Foo { - namespace Internal { - - void SomeThing::bar() - { - FileName f; // or Utils::FileName f - ... - } - ... - } // namespace Internal // or only // Internal - } // namespace Foo // or only // Foo - - -NOT- - - [in foo.h] - ... - using namespace Utils; // Wrong: no using-directives in headers - - class SomeThing - { - ... - }; - - -NOT- - - [in foo.cpp] - ... - using namespace Utils; - - #include "bar.h" // Wrong: #include after using-directive - - -NOT- - - [in foo.cpp] - ... - using namepace Foo; - - void SomeThing::bar() // Wrong if Something is in namespace Foo - { - ... - } - \endcode - - \endlist - - \section1 Patterns and Practices - - \target coding-rules-namespacing - \section2 Namespacing - - Read \l{https://wiki.qt.io/Qt_In_Namespace}{Qt In Namespace} - and keep in mind that all of Qt Creator is \e{namespace aware} code. - - The namespacing policy within Qt Creator is as follows: - \list - \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 - - Qt Creator API expects file names in portable format, that is, with slashes (/) - instead of backslashes (\\) even on Windows. To pass a file name from the user - to the API, convert it with QDir::fromNativeSeparators first. To present a file - name to the user, convert it back to native format with - QDir::toNativeSeparators. Consider using Utils::FileName::fromUserInput(QString) - and Utils::FileName::toUserOutput() for these tasks. - - Use Utils::FileName when comparing file names, because that takes case sensitivity into account. - Also make sure that you compare clean paths (QDir::cleanPath()). - - \section2 Plugin Extension Points - - A plugin extension point is an interface that is provided by one plugin - to be implemented by others. The plugin then retrieves all - implementations of the interface and uses them. That is, they \e extend the - functionality of the plugin. Typically, the - implementations of the interface are put into the global object pool - during plugin initialization, and the plugin retrieves them from the - object pool at the end of plugin initialization. - - For example, the Find plugin provides the FindFilter interface for - other plugins to implement. With the FindFilter interface, additional search - scopes can be added, that appear in the \uicontrol {Advanced Search} dialog. The - Find plugin retrieves all FindFilter implementations from the global - object pool and presents them in the dialog. The plugin forwards the - actual search request to the correct FindFilter implementation, which - then performs the search. - - \section2 Using the Global Object Pool - - You can add objects to the global object pool via - \l{ExtensionSystem::PluginManager::addObject()}, and retrieve objects - of a specific type again via - \l{ExtensionSystem::PluginManager::getObjects()}. This should mostly - be used for implementations of \l{Plugin Extension Points}. - - \note Do not put a singleton into the pool, and do not retrieve - it from there. Use the singleton pattern instead. - - \section2 C++ Features - - \list - \li Prefer \c {#pragma once} over header guards. - - \li Do not use exceptions, unless you know what you do. - - \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. - - \li Do not use virtual inheritance, unless you know what you do. - - \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. - - \li All code is ASCII only (7-bit characters only, run \c {man ascii} if unsure) - \list - \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. - \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"); - \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 - - \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 - (ISO/IEC 14882, 7.1.1/6, or see various discussions about this on the gcc - mailing lists). - \endlist - - \section3 Null Pointers - - Use nullptr for null pointer constants. - - \code - void *p = nullptr; - - -NOT- - - void *p = NULL; - - -NOT- - - void *p = '\0'; - - -NOT- - - void *p = 42 - 7 * 6; - \endcode - - \note As an exception, imported third party code as well as code - interfacing the native APIs (src/support/os_*) can use NULL or 0. - - \section2 C++11 and C++14 Features - - Code should compile with Microsoft Visual Studio 2013, g++ 4.7, and Clang 3.1. - - \section3 Lambdas - - When using lambdas, note the following: - - \list - \li You do not have to explicitly specify the return type. If you are not using one - of the previously mentioned compilers, do note that this is a C++14 feature and you - might need to enable C++14 support in your compiler. - \code - []() { - Foo *foo = activeFoo(); - return foo ? foo->displayName() : QString(); - }); - \endcode - - \li If you use static functions from the class that the lambda is located in, you have to - explicitly capture \c this. Otherwise it does not compile with g++ 4.7 and earlier. - \code - void Foo::something() - { - ... - [this]() { Foo::someStaticFunction(); } - ... - } - - -NOT- - - void Foo::something() - { - ... - []() { Foo::someStaticFunction(); } - ... - } - \endcode - \endlist - - Format the lambda according to the following rules: - - \list - \li Place the capture-list, parameter list, return type, and opening brace on the first line, - the body indented on the following lines, and the closing brace on a new line. - \code - []() -> bool { - something(); - return isSomethingElse(); - } - - -NOT- - - []() -> bool { something(); - somethingElse(); } - \endcode - - \li Place a closing parenthesis and semicolon of an enclosing function call on the same line - as the closing brace of the lambda. - \code - foo([]() { - something(); - }); - \endcode - - \li If you are using a lambda in an 'if' statement, start the lambda on a new line, to - avoid confusion between the opening brace for the lambda and the opening brace for the - 'if' statement. - \code - if (anyOf(fooList, - [](Foo foo) { - return foo.isGreat(); - }) { - return; - } - - -NOT- - - if (anyOf(fooList, [](Foo foo) { - return foo.isGreat(); - }) { - return; - } - \endcode - - \li Optionally, place the lambda completely on one line if it fits. - \code - foo([] { return true; }); - - if (foo([] { return true; })) { - ... - } - \endcode - - \endlist - - \section3 \c auto Keyword - - Optionally, you can use the \c auto keyword in the following cases. If in doubt, - for example if using \c auto could make the code less readable, do not use \c auto. - Keep in mind that code is read much more often than written. - - \list - \li When it avoids repetition of a type in the same statement. - \code - auto something = new MyCustomType; - auto keyEvent = static_cast<QKeyEvent *>(event); - auto myList = QStringList({ "FooThing", "BarThing" }); - \endcode - - \li When assigning iterator types. - \code - auto it = myList.const_iterator(); - \endcode - - \endlist - - \section3 Scoped enums - - You can use scoped enums in places where the implicit conversion to int of unscoped enums is - undesired or the additional scope is useful. - - \section3 Delegating constructors - - Use delegating constructors if multiple constructors use essentially the same code. - - \section3 Initializer list - - Use initializer lists to initialize containers, for example: - - \code - const QVector<int> values = {1, 2, 3, 4, 5}; - \endcode - - \section3 Initialization with Curly Brackets - - If you use initialization with curly brackets, follow the same rules as with - round brackets. For example: - - \code - class Values // the following code is quite useful for test fixtures - { - float floatValue = 4; // prefer that for simple types - QVector<int> values = {1, 2, 3, 4, integerValue}; // prefer that syntax for initializer lists - SomeValues someValues{"One", 2, 3.4}; // not an initializer_list - SomeValues &someValuesReference = someValues; - ComplexType complexType{values, otherValues} // constructor call - } - - object.setEntry({"SectionA", value, doubleValue}); // calls a constructor - object.setEntry({}); // calls default constructor - \endcode - - But be careful not to overuse it, to not obfuscate your code. - - \section3 Non-Static Data Member Initialization - - Use non-static data member initialization for trivial initializations, except in public - exported classes. - - \section3 Defaulted and Deleted Functions - - Consider using \c{=default} and \c{=delete} to control the special functions. - - \section3 Override - - It is recommended to use the \c{override} keyword when overriding virtual functions. Do not - use virtual on overridden functions. - - Make sure that a class uses \c{override} consistently, either for all overridden functions or - for none. - - \section3 Nullptr - - All compilers support \c{nullptr}, but there is no consensus on using it. If in doubt, ask - the maintainer of the module whether they prefer using \c{nullptr}. - - \section3 Range-Based for-Loop - - You may use range-based for-loops, but beware of the spurious detachment problem. - If the for-loop only reads the container and it is not obvious whether the - container is const or unshared, use \c{std::cref()} to ensure that the container - is not unnecessarily detached. - - \section2 Using QObject - - \list - \li Remember to add the Q_OBJECT macro to QObject subclasses that rely - on the meta object system. Meta object system related features are - the definition of signals and slots, the use of \c{qobject_cast<>}, - and others. See also \l{Casting}. - \li Prefer Qt5-style \c{connect()} calls over Qt4-style. - \li When using Qt4-style \c{connect()} calls, normalize the arguments - for signals and slots inside connect statements to safely make - signal and slot lookup a few cycles faster. You can use - $QTDIR/util/normalize to normalize existing code. For more - information, see QMetaObject::normalizedSignature. - \endlist - - \section2 File Headers - - If you create a new file, the top of the file should include a - header comment equal to the one found in other source files of Qt Creator. - - \section2 Including Headers - - \list - \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. - \li Arrange includes in an order that goes from specific to generic to - ensure that the headers are self-contained. For example: - \list - \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 - \li Enclose headers from other plugins in square brackets (<>) rather than - quotation marks ("") to make it easier to spot external dependencies in - the sources. - \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 - \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. - \li Do not use \c dynamic_cast, use \c {qobject_cast} for QObjects, or - refactor your design, for example by introducing a \c {type()} - function (see QListWidgetItem), unless you know what you do. - \endlist - - \section2 Compiler and Platform-specific Issues - - \list - \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 - QString s; - // crash at runtime - QString vs. const char * - return condition ? s : "nothing"; - \endcode - - \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 - on some architectures. For example, if a \c {const char *} is cast to a - \c {const int *}, it will crash on machines where integers have to be - aligned at two-byte or four-byte boundaries. - - Use a union to force the compiler to align variables correctly. - In the example below, you can be sure that all instances of - AlignHelper are aligned at integer-boundaries: - \code - union AlignHelper - { - char c; - int i; - }; - \endcode - - \li Stick to integral types, arrays of integral types, and structs thereof - for static declarations in headers. - For example, \c {static float i[SIZE_CONSTANT];} will not be optimized - and copied in every plugin in most cases, it would be good to avoid it. - - \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). - - Even if the execution time of the initializer is defined for - shared libraries, you will get into trouble when moving that code - in a plugin or if the library is compiled statically: - - \code - // global scope - - -NOT- - - // Default constructor needs to be run to initialize x: - static const QString x; - - -NOT- - - // Constructor that takes a const char * has to be run: - static const QString y = "Hello"; - - -NOT- - - QString z; - - -NOT- - - // Call time of foo() undefined, might not be called at all: - static const int i = foo(); - \endcode - - Things you can do: - - \code - // global scope - // No constructor must be run, x set at compile time: - static const char x[] = "someText"; - - // y will be set at compile time: - static int y = 7; - - // Will be initialized statically, no code being run. - static MyStruct s = {1, 2, 3}; - - // Pointers to objects are OK, no code needed to be run to - // initialize ptr: - static QString *ptr = 0; - - // Use Q_GLOBAL_STATIC to create static global objects instead: - - Q_GLOBAL_STATIC(QString, s) - - void foo() - { - s()->append("moo"); - } - \endcode - - \note Static objects in function scope are no problem. The constructor - will be run the first time the function is entered. The code is not - reentrant, though. - - \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: - - \code - // Condition is always true on platforms where the - // default is unsigned: - if (c >= 0) { - ... - } - \endcode - - \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. - - \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) - - -NOT- - - for (Container::const_iterator it = c.begin(); it != c.end(); ++it) - \endcode - - \li Do not inline virtual destructors in exported classes. This leads to duplicated vtables - in dependent plugins and this can also break RTTI. See - \l {https://bugreports.qt.io/browse/QTBUG-45582}{QTBUG-45582}. - \endlist - - \section2 Esthetics - - \list - \li Prefer unscoped 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 - - Inheriting from template or tool classes has the following potential - pitfalls: - - \list - \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 - - For example, library A has class \c {Q_EXPORT X: public QList<QVariant> {};} - and library B has class \c {Q_EXPORT Y: public QList<QVariant> {};}. - Suddenly, QList symbols are exported from two libraries which results in a - clash. - - - \section2 Inheritance Versus Aggregation - - \list - \li Use inheritance if there is a clear \e{is-a} relation. - \li Use aggregation for re-use of orthogonal building blocks. - \li Prefer aggregation over inheritance if there is a choice. - \endlist - - - \section2 Conventions for Public Header Files - - Our public header files have to survive the strict settings of - some of our users. All installed headers have to follow these rules: - - \list - - \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}. - - \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. - - \li Do not hide virtual functions 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 - add the following silly workaround for broken compilers: - \code - class B: public A - { - #ifdef Q_NO_USING_KEYWORD - inline int val() { return A::val(); } - #else - using A::val; - #endif - }; - \endcode - - \li Do not shadow variables (\c{-Wshadow}). - - \li Avoid things like \c {this->x = x;} if possible. - - \li Do not give variables the same name as functions declared in - your class. - - \li To improve code readability, always check whether a preprocessor - variable is defined before probing its value (\c {-Wundef}). - - \code - #if defined(Foo) && Foo == 0 - - -NOT- - - #if Foo == 0 - - -NOT- - - #if Foo - 0 == 0 - \endcode - - \li When checking for a preprocessor define using the \c {defined} - operator, always include the variable name in parentheses. - - \code - #if defined(Foo) - - -NOT- - - #if defined Foo - \endcode - - \endlist - - \section1 Class Member Names - - We use the "m_" prefix convention, except for public struct members - (typically in *Private classes and the very rare cases of really - public structures). The \c{d} and \c{q} pointers are exempt from - the "m_" rule. - - The \c{d} pointers ("Pimpls") are named "d", not "m_d". The type of the - \c{d} pointer in \c{class Foo} is \c{FooPrivate *}, where \c{FooPrivate} - is declared in the same namespace as \c{Foo}, or if \c{Foo} is - exported, in the corresponding \{Internal} namespace. - - If needed (for example when the private object needs to emit signals of - the proper class), \c{FooPrivate} can be a friend of \c{Foo}. - - If the private class needs a backreference to the real class, - the pointer is named \c{q}, and its type is \c{Foo *}. (Same convention - as in Qt: "q" looks like an inverted "d".) - - Do not use smart pointers to guard the \c{d} pointer as it imposes - a compile and link time overhead and creates fatter object - code with more symbols, leading, for instance to slowed down - debugger startup: - - \code - - ############### bar.h - - #include <QScopedPointer> - //#include <memory> - - struct BarPrivate; - - struct Bar - { - Bar(); - ~Bar(); - int value() const; - - QScopedPointer<BarPrivate> d; - //std::unique_ptr<BarPrivate> d; - }; - - ############### bar.cpp - - #include "bar.h" - - struct BarPrivate { BarPrivate() : i(23) {} int i; }; - - Bar::Bar() : d(new BarPrivate) {} - - Bar::~Bar() {} - - int Bar::value() const { return d->i; } - - ############### baruser.cpp - - #include "bar.h" - - int barUser() { Bar b; return b.value(); } - - ############### baz.h - - struct BazPrivate; - - struct Baz - { - Baz(); - ~Baz(); - int value() const; - - BazPrivate *d; - }; - - ############### baz.cpp - - #include "baz.h" - - struct BazPrivate { BazPrivate() : i(23) {} int i; }; - - Baz::Baz() : d(new BazPrivate) {} - - Baz::~Baz() { delete d; } - - int Baz::value() const { return d->i; } - - ############### bazuser.cpp - - #include "baz.h" - - int bazUser() { Baz b; return b.value(); } - - ############### main.cpp - - int barUser(); - int bazUser(); - - int main() { return barUser() + bazUser(); } - - \endcode - - Results: - - \code - - Object file size: - - 14428 bar.o - 4744 baz.o - - 8508 baruser.o - 2952 bazuser.o - - Symbols in bar.o: - - 00000000 W _ZN3Foo10BarPrivateC1Ev - 00000036 T _ZN3Foo3BarC1Ev - 00000000 T _ZN3Foo3BarC2Ev - 00000080 T _ZN3Foo3BarD1Ev - 0000006c T _ZN3Foo3BarD2Ev - 00000000 W _ZN14QScopedPointerIN3Foo10BarPrivateENS_21QScopedPointerDeleterIS2_EEEC1EPS2_ - 00000000 W _ZN14QScopedPointerIN3Foo10BarPrivateENS_21QScopedPointerDeleterIS2_EEED1Ev - 00000000 W _ZN21QScopedPointerDeleterIN3Foo10BarPrivateEE7cleanupEPS2_ - 00000000 W _ZN7qt_noopEv - U _ZN9qt_assertEPKcS1_i - 00000094 T _ZNK3Foo3Bar5valueEv - 00000000 W _ZNK14QScopedPointerIN3Foo10BarPrivateENS_21QScopedPointerDeleterIS2_EEEptEv - U _ZdlPv - U _Znwj - U __gxx_personality_v0 - - Symbols in baz.o: - - 00000000 W _ZN3Foo10BazPrivateC1Ev - 0000002c T _ZN3Foo3BazC1Ev - 00000000 T _ZN3Foo3BazC2Ev - 0000006e T _ZN3Foo3BazD1Ev - 00000058 T _ZN3Foo3BazD2Ev - 00000084 T _ZNK3Foo3Baz5valueEv - U _ZdlPv - U _Znwj - U __gxx_personality_v0 - - \endcode - - - - \section1 Documentation - - The documentation is generated from source and header files. You document - for the other developers, not for yourself. In the header files, document - interfaces. That is, what the function does, not the implementation. - - In the .cpp files, you can document the implementation if the - implementation is not obvious. - -*/ diff --git a/doc/api/creating-plugins.qdoc b/doc/api/creating-plugins.qdoc deleted file mode 100644 index c6c4fab64f..0000000000 --- a/doc/api/creating-plugins.qdoc +++ /dev/null @@ -1,76 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the Qt Creator documentation. -** -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** -****************************************************************************/ - -/*! - \page creating-plugins.html - \title Creating Plugins - - At its very core, \QC consists of a plugin loader that loads and runs a set - of plugins, which then actually provide the functionality that you know from - \QC the IDE. So, even the main application window and menus are all provided - by plugins. Plugins can use different means to provide other plugins access - to their functionality and to allow them to extend certain aspects of the - application. - - For example the \c Core plugin, which is the very basic plugin that must be - present for \QC to run at all, provides the main window itself, and API - for adding menu items, modes, editor types, navigation panels and many other - things. - - The \c TextEditor plugin provides a framework and base implementation for - different text editors with highlighting, completion and folding, that is - then used by other plugins to add more specialized text editor types to \QC, - like for editing C/C++ or \c {.pro} files. - - After reading this guide you will know what a basic plugin consists of, - how to write a plugin specification file, what the lifecycle of a plugin is, - what the general principles for extending existing plugins' functionality - and providing interfaces for other plugins are, and will be able to write - your first plugin. - - \section1 Basics - - \list - \li \l{Getting and Building Qt Creator} - \li \l{Creating Your First Plugin} - \li \l{Plugin Meta Data} - \li \l{Plugin Life Cycle} - \endlist - - \section1 Design Principles - - \list - \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 - \li \l{A Note on Binary Compatibility} - \li \l{Creating User-Installable Plugins} - \endlist -*/ diff --git a/doc/api/examples/aggregation/README b/doc/api/examples/aggregation/README deleted file mode 100644 index 8e67b60554..0000000000 --- a/doc/api/examples/aggregation/README +++ /dev/null @@ -1,21 +0,0 @@ - -Running test.sh tests several replacement patterns for a typical case -of polymorphism, and creates some statistics of the output. - -The 'critical' case is where the implementation is only instantiated -from a single location. - -'Symbols' refers to the number of additional symbols created by the -pattern (relevant for relocation on application startup and debugger -performance) - -'Size' refers to the size of the '.text' section, i.e. the 'generated -code'. - -'Debug' is the size of the .debug_info section in the binary. - - -Note that the numbers are not directly comparable. As the 'Slim' -versions push code from the implementation to the user side, the -ratio will be "better" when the the implementation is instantiated -from more than one place. diff --git a/doc/api/examples/aggregation/output.txt b/doc/api/examples/aggregation/output.txt deleted file mode 100644 index 6b75ec188d..0000000000 --- a/doc/api/examples/aggregation/output.txt +++ /dev/null @@ -1,35 +0,0 @@ -Interface/Implementation (out of line) - -Symbols: 13 -Size: 2388 -Debug: 4541 - - -Interface/Implementation (non-virtual) - -Symbols: 13 -Size: 2388 -Debug: 4431 - - -Interface/Implementation (inline) - -Symbols: 12 -Size: 2643 -Debug: 4402 - - -Merged - -Symbols: 7 -Size: 2447 -Debug: 4342 - - -Slimmest possible - -Symbols: 0 -Size: 1971 -Debug: 4246 - - diff --git a/doc/api/examples/aggregation/test.sh b/doc/api/examples/aggregation/test.sh deleted file mode 100755 index 5232ce8629..0000000000 --- a/doc/api/examples/aggregation/test.sh +++ /dev/null @@ -1,196 +0,0 @@ -#!/bin/bash - -export CXX="g++ -O3 -g " - -function stat() { - echo -e "" - echo -e "Symbols: $(nm $@ | grep ' [TVW] ' | grep _Z | grep -v "_ZNSs" | wc -l)" - echo -e "Size: $(size -d -B $@ | tail -1 | cut -c1-10)" - echo -e "Debug: $(echo "ibase=16;"$(readelf -S $@ | grep debug_info | cut -c50-56 | tr a-f A-F) | bc)" - echo -e "" - echo -e "" -# echo -e "Symbols: $(nm "$@" | grep ' [TUVW] '| grep _Z )" -} - - -function test_1() { - -echo "Interface/Implementation (out of line)" - -cat > interface_1.h <<EOF -#include <string> -struct Interface { virtual ~Interface() {} virtual std::string func() const = 0; }; -EOF - -cat > implementation_1.h <<EOF -#include "interface_1.h" -struct Implementation : Interface { std::string func() const; }; -EOF - -cat > implementation_1.cpp <<EOF -#include "implementation_1.h" -std::string Implementation::func() const { return "Test1"; } -EOF - -cat > main_1.cpp <<EOF -#include "implementation_1.h" -int main() { Interface *x = new Implementation(); return x->func().size(); } -EOF - -$CXX implementation_1.cpp main_1.cpp -o test_1 -stat test_1 - -} - - -function test_2() { - -echo "Interface/Implementation (non-virtual)" - -cat > interface_2.h <<EOF -#include <string> -struct Interface { virtual ~Interface() {} virtual std::string func() const = 0; }; -EOF - -cat > implementation_2.h <<EOF -#include "interface_2.h" -struct Implementation : Interface { - ~Implementation() {} std::string func() const { return "Test2"; } }; -EOF - -cat > main_2.cpp <<EOF -#include "implementation_2.h" -int main() { Interface *x = new Implementation(); return x->func().size(); } -EOF - -$CXX main_2.cpp -o test_2 -stat test_2 - -} - - -function test_3() { - -echo "Interface/Implementation (inline)" - -cat > interface_3.h <<EOF -#include <string> -struct Interface -{ - virtual ~Interface() {} - std::string func() const { return m_data; } - std::string m_data; -}; -EOF - -cat > implementation_3.h <<EOF -#include "interface_3.h" -struct Implementation : Interface { - Implementation() { m_data = "Test3"; } -}; -EOF - -cat > main_3.cpp <<EOF -#include "implementation_3.h" -int main() { Interface *x = new Implementation(); return x->func().size(); } -EOF - -$CXX main_3.cpp -o test_3 -stat test_3 - -} - - -function test_4() { - -echo "Merged" - -cat > interface_4.h <<EOF -#include <string> -struct Interface -{ - virtual ~Interface() {} - std::string func() const { return m_data; } - void setData(const std::string &data) { m_data = data; } -private: - std::string m_data; -}; -EOF - -cat > implementation_4.h <<EOF -#include "interface_4.h" -void setupImplementation(Interface *i) { i->setData("Test4"); } -EOF - -cat > main_4.cpp <<EOF -#include "implementation_4.h" -int main() { Interface *x = new Interface(); setupImplementation(x); return x->func().size(); } -EOF - -$CXX main_4.cpp -o test_4 -stat test_4 - -} - - -function test_5() { - -echo "Slimmest possible" - -cat > interface_5.h <<EOF -#include <string> -struct Interface -{ - std::string func() const { return m_data; } - void setData(const std::string &data) { m_data = data; } -private: - std::string m_data; -}; -EOF - -cat > main_5.cpp <<EOF -#include "interface_5.h" -int main() { Interface *x = new Interface(); x->setData("Test4"); return x->func().size(); } -EOF - -$CXX main_5.cpp -o test_5 -stat test_5 - -} - - -function test_6() { - -echo "Constructor" - -cat > interface_6.h <<EOF -#include <string> -struct Interface -{ - explicit Interface(const std::string &data) : m_data(data) {} - std::string func() const { return m_data; } -private: - const std::string m_data; -}; -EOF - -cat > main_6.cpp <<EOF -#include "interface_6.h" -int main() { Interface *x = new Interface("Test4"); return x->func().size(); } -EOF - -$CXX main_6.cpp -o test_6 -stat test_6 - -} - -function main() { - test_1 - test_2 - test_3 - test_4 - test_5 - #test_6 -} - -main diff --git a/doc/api/examples/exampleplugin/Example.json.in b/doc/api/examples/exampleplugin/Example.json.in deleted file mode 100644 index 12b8bc37a0..0000000000 --- a/doc/api/examples/exampleplugin/Example.json.in +++ /dev/null @@ -1,18 +0,0 @@ -{ -//! [1] - \"Name\" : \"Example\", - \"Version\" : \"0.0.1\", - \"CompatVersion\" : \"0.0.1\", -//! [1] -//! [2] - \"Vendor\" : \"My Company\", - \"Copyright\" : \"(C) My Company\", - \"License\" : \"BSD\", - \"Category\" : \"Examples\", - \"Description\" : \"Minimal plugin example.\", - \"Url\" : \"http://www.mycompany.com\", -//! [2] -//! [3] - $$dependencyList -//! [3] -} diff --git a/doc/api/examples/exampleplugin/example.pro b/doc/api/examples/exampleplugin/example.pro deleted file mode 100644 index c100894b7b..0000000000 --- a/doc/api/examples/exampleplugin/example.pro +++ /dev/null @@ -1,59 +0,0 @@ -#! [1] -DEFINES += EXAMPLE_LIBRARY -#! [1] - -# Example files - -#! [2] -SOURCES += exampleplugin.cpp - -HEADERS += exampleplugin.h \ - example_global.h \ - exampleconstants.h -#! [2] - -# Qt Creator linking - -#! [3] -## set the QTC_SOURCE environment variable to override the setting here -QTCREATOR_SOURCES = $$(QTC_SOURCE) -isEmpty(QTCREATOR_SOURCES):QTCREATOR_SOURCES=/Users/example/qtcreator-src - -## set the QTC_BUILD environment variable to override the setting here -IDE_BUILD_TREE = $$(QTC_BUILD) -isEmpty(IDE_BUILD_TREE):IDE_BUILD_TREE=/Users/example/qtcreator-build -#! [3] - -#! [4] -## uncomment to build plugin into user config directory -## <localappdata>/plugins/<ideversion> -## where <localappdata> is e.g. -## "%LOCALAPPDATA%\QtProject\qtcreator" on Windows Vista and later -## "$XDG_DATA_HOME/data/QtProject/qtcreator" or "~/.local/share/data/QtProject/qtcreator" on Linux -## "~/Library/Application Support/QtProject/Qt Creator" on Mac -# USE_USER_DESTDIR = yes -#! [4] - -#! [5] -###### If the plugin can be depended upon by other plugins, this code needs to be outsourced to -###### <dirname>_dependencies.pri, where <dirname> is the name of the directory containing the -###### plugin's sources. - -QTC_PLUGIN_NAME = Example -QTC_LIB_DEPENDS += \ - # nothing here at this time - -QTC_PLUGIN_DEPENDS += \ - coreplugin - -QTC_PLUGIN_RECOMMENDS += \ - # optional plugin dependencies. nothing here at this time - -###### End _dependencies.pri contents ###### -#! [5] - -#![6] -include($$QTCREATOR_SOURCES/src/qtcreatorplugin.pri) - -#![6] - diff --git a/doc/api/examples/exampleplugin/example_global.h b/doc/api/examples/exampleplugin/example_global.h deleted file mode 100644 index 00c77e6b16..0000000000 --- a/doc/api/examples/exampleplugin/example_global.h +++ /dev/null @@ -1,9 +0,0 @@ -#pragma once - -#include <QtGlobal> - -#if defined(EXAMPLE_LIBRARY) -# define EXAMPLESHARED_EXPORT Q_DECL_EXPORT -#else -# define EXAMPLESHARED_EXPORT Q_DECL_IMPORT -#endif diff --git a/doc/api/examples/exampleplugin/exampleconstants.h b/doc/api/examples/exampleplugin/exampleconstants.h deleted file mode 100644 index fced2e0429..0000000000 --- a/doc/api/examples/exampleplugin/exampleconstants.h +++ /dev/null @@ -1,10 +0,0 @@ -#pragma once - -namespace Example { -namespace Constants { - -const char ACTION_ID[] = "Example.Action"; -const char MENU_ID[] = "Example.Menu"; - -} // namespace Example -} // namespace Constants diff --git a/doc/api/examples/exampleplugin/exampleplugin.cpp b/doc/api/examples/exampleplugin/exampleplugin.cpp deleted file mode 100644 index 5adc093c46..0000000000 --- a/doc/api/examples/exampleplugin/exampleplugin.cpp +++ /dev/null @@ -1,86 +0,0 @@ -#include "exampleplugin.h" -#include "exampleconstants.h" - -#include <coreplugin/icore.h> -#include <coreplugin/icontext.h> -#include <coreplugin/actionmanager/actionmanager.h> -#include <coreplugin/actionmanager/command.h> -#include <coreplugin/actionmanager/actioncontainer.h> -#include <coreplugin/coreconstants.h> - -#include <QAction> -#include <QMessageBox> -#include <QMainWindow> -#include <QMenu> - -#include <QtPlugin> - -namespace Example { -namespace Internal { - -ExamplePlugin::ExamplePlugin() -{ - // Create your members -} - -ExamplePlugin::~ExamplePlugin() -{ - // Unregister objects from the plugin manager's object pool - // Delete members -} - -bool ExamplePlugin::initialize(const QStringList &arguments, QString *errorString) -{ - // Register objects in the plugin manager's object pool - // Load settings - // Add actions to menus - // Connect to other plugins' signals - // In the initialize function, a plugin can be sure that the plugins it - // depends on have initialized their members. - - Q_UNUSED(arguments) - Q_UNUSED(errorString) - -//! [add action] - QAction *action = new QAction(tr("Example Action"), this); - Core::Command *cmd = Core::ActionManager::registerAction(action, Constants::ACTION_ID, - Core::Context(Core::Constants::C_GLOBAL)); - cmd->setDefaultKeySequence(QKeySequence(tr("Ctrl+Alt+Meta+A"))); - connect(action, &QAction::triggered, this, &ExamplePlugin::triggerAction); -//! [add action] -//! [add menu] - Core::ActionContainer *menu = Core::ActionManager::createMenu(Constants::MENU_ID); - menu->menu()->setTitle(tr("Example")); - menu->addAction(cmd); - Core::ActionManager::actionContainer(Core::Constants::M_TOOLS)->addMenu(menu); -//! [add menu] - - return true; -} - -void ExamplePlugin::extensionsInitialized() -{ - // Retrieve objects from the plugin manager's object pool - // In the extensionsInitialized function, a plugin can be sure that all - // plugins that depend on it are completely initialized. -} - -ExtensionSystem::IPlugin::ShutdownFlag ExamplePlugin::aboutToShutdown() -{ - // Save settings - // Disconnect from signals that are not needed during shutdown - // Hide UI (if you add UI that is not in the main window directly) - return SynchronousShutdown; -} - -//! [slot implementation] -void ExamplePlugin::triggerAction() -{ - QMessageBox::information(Core::ICore::mainWindow(), - tr("Action Triggered"), - tr("This is an action from Example.")); -} -//! [slot implementation] - -} // namespace Internal -} // namespace Example diff --git a/doc/api/examples/exampleplugin/exampleplugin.h b/doc/api/examples/exampleplugin/exampleplugin.h deleted file mode 100644 index e858e92180..0000000000 --- a/doc/api/examples/exampleplugin/exampleplugin.h +++ /dev/null @@ -1,36 +0,0 @@ -#pragma once - -#include "example_global.h" - -#include <extensionsystem/iplugin.h> - -//! [namespaces] -namespace Example { -namespace Internal { -//! [namespaces] - -//! [base class] -class ExamplePlugin : public ExtensionSystem::IPlugin -{ - Q_OBJECT - Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QtCreatorPlugin" FILE "Example.json") -//! [base class] - -public: - ExamplePlugin(); - ~ExamplePlugin(); - -//! [plugin functions] - bool initialize(const QStringList &arguments, QString *errorString); - void extensionsInitialized(); - ShutdownFlag aboutToShutdown(); -//! [plugin functions] - -//! [slot] -private: - void triggerAction(); -//! [slot] -}; - -} // namespace Internal -} // namespace Example diff --git a/doc/api/external-tool-spec.qdoc b/doc/api/external-tool-spec.qdoc deleted file mode 100644 index 0f5d3ac1cc..0000000000 --- a/doc/api/external-tool-spec.qdoc +++ /dev/null @@ -1,192 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the Qt Creator documentation. -** -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** -****************************************************************************/ - -/*! - \page external-tool-spec.html - \nextpage coding-style.html - - \title External Tool Specification Files - - An external tool specification file describes a tool that can be run from - the \uicontrol { Tools > External } menu. - It specifies the name of the tool, the executable to run, optional - arguments, and how to handle the output from the tool. - - \section1 File Name - - \c {<yourtoolname>.xml} - - \section1 Location - - User specific tools are located in \c {$HOME/.config/QtProject/qtcreator/externaltools} - on Mac and Linux, and in \c {%APPDATA%\QtProject\qtcreator\externaltools} on Windows. - - System wide tools are located in \c {<Qt Creator install>/share/qtcreator/externaltools} - on Windows and Linux, and in \c {Qt Creator.app/Contents/Resources/externaltools} on Mac. - - \section1 File Format - - External tool specifications are XML files with the following structure. - - \section2 Main Tag - - The root tag is \c externaltool. It has the mandatory attribute \c id. - - \table - \header - \li Tag - \li Meaning - \row - \li externaltool - \li Root element in the XML file that specifies an external tool. - \endtable - \table - \header - \li Attribute - \li Meaning - \row - \li id - \li A string that identifies the external tool. - Two tools cannot have the same id. Required. - \endtable - - \section2 Description Tags - - You must specify a description, display name, and category for the tool. - You can translate their values into different languages by adding multiple - \c description, \c displayname, and \c category tags that contain language - codes. - - \table - \header - \li Tag - \li Meaning - \row - \li description - \li Short, one-line description of what the tool is for. Required. - \row - \li displayname - \li Name to show in the menu item for the tool. Required. - \row - \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 - \li Attribute - \li Meaning - \row - \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 - - You must add an \c executable tag under the root tag, that specifies the - executable to run, optional arguments, and how to handle the output. - - \table - \header - \li Tag - \li Meaning - \row - \li executable - \li Encloses subtags that specify what to run and which parameters to use. Required. - \endtable - \table - \header - \li Attribute - \li Meaning - \row - \li output - \li Specifies how to handle the tool's standard output stream. - Defaults to \c ShowInPane. Optional. - \row - \li error - \li Specifies how to handle the tool's standard error stream. - Defaults to \c ShowInPane. Optional. - \row - \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 - one \c path. All subtags can contain special \l{Qt Creator Variables}. - - \table - \header - \li Subtag - \li Meaning - \row - \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 - \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 - \li workingdirectory - \li The working directory for the executable. Optional. - \row - \li input - \li A potentially multiline string that is passed to the tool via standard input stream. - \endtable - - \section1 Example - - \code -<?xml version="1.0" encoding="UTF-8"?> -<externaltool id="sort"> - <description>Sorts the selected text</description> - <description xml:lang="de">Sortiert den ausgewaehlten Text</description> - <displayname>Sort Selection</displayname> - <displayname xml:lang="de">Auswahl Sortieren</displayname> - <category>Text</category> - <category xml:lang="de">Text</category> - <executable output="replaceselection" error="ignore"> - <path>sort</path> - <input>%{CurrentDocument:Selection}</input> - <workingdirectory>%{CurrentDocument:Path}</workingdirectory> - </executable> -</externaltool> - \endcode -*/ diff --git a/doc/api/first-plugin.qdoc b/doc/api/first-plugin.qdoc deleted file mode 100644 index c56b3c9c56..0000000000 --- a/doc/api/first-plugin.qdoc +++ /dev/null @@ -1,364 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the Qt Creator documentation. -** -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** -****************************************************************************/ - -/*! - \page first-plugin.html - \title Creating Your First Plugin - - This section describes how to create a \QC plugin by using the plugin - template provided by \QC, and get the first impression of what a plugin - consists of and what its general structure is. - - \section1 Creating a Plugin Project - - \QC comes with a wizard for \QC plugins, that creates a runable, \e minimal - plugin for you. We strongly suggest that you use two different \QC instances - for developing and testing your plugin with. Otherwise your plugin will also - be loaded in your development environment, which can make that unstable - while your plugin is still unstable. You can just create a copy of your \QC - build and use one for actually developing, and the other for testing your - plugin with. - - You need to make sure that you use the same \QC version that you want to - develop for to create the plugin. Because of the \l{Binary and Source - Compatibility} rules of \QC, the \QC plugin wizard creates a plugin that - might only compile and run with the same \QC version that it was created - with. - - \list 1 - \li Select \uicontrol File > \uicontrol {New File or Project} > - \uicontrol Library > \uicontrol {Qt Creator Plugin} > - \uicontrol Choose. - - \image firstplugin-wizard.png "Choose the \QC Plugin Wizard" - - The \uicontrol{Introduction and Project Location} dialog opens. - - \image firstplugin-nameandpath.png "Choose Name and Place of the Project" - - \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 \uicontrol {Kit Selection} dialog opens. - - \image firstplugin-kitselection.png "Choose the kit to build and run your project with" - - \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 - \uicontrol 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 \uicontrol {Plugin Information} dialog opens. - - \image firstplugin-pluginsetup.png "Specify Your Plugin Details" - - \li In the \uicontrol {Plugin name} field, type \uicontrol 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 The values of the following fields are mainly informational, and - are shown in the detailed view in \QC's plugin overview - (\uicontrol Help > \uicontrol {About Plugins}, or - \uicontrol {Qt Creator} > \uicontrol {About Plugins} on Mac). - - \list - \li \uicontrol {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 \uicontrol Copyright is a one-line, short copyright string. - - \li \uicontrol License is a license text. - - \li \uicontrol{Description} is a short description of what the - plugin does. - - \li \uicontrol URL is a website where the user can find more - information about the plugin and/or organization providing - it. - \endlist - - \li Set the \uicontrol {Qt Creator sources} and - \uicontrol{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 \uicontrol {Deploy into} list, select - \uicontrol {Qt Creator build}. This sets your \c {.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, - \uicontrol {Local user settings}, sets your \c {.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 \uicontrol {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 \uicontrol {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 - - If you passed the correct \QC source and build paths in the project wizard, - your plugin should just build fine when pressing the build button. When you - try to run your project, \QC will ask you for the executable to run and you - are presented the following dialog: - - \image firstplugin-runsettings.png "Specify the Executable to Run" - - Select the path to the \QC executable from the build that you specified in - the \uicontrol {Qt Creator build} setting in the project wizard and click - \uicontrol OK. \QC starts up, and you can verify that your plugin - successfully loaded by looking for a menu entry \uicontrol Tools > - \uicontrol Example and by looking for the plugin in the - \uicontrol {About Plugins} dialog. - - \image firstplugin-menuitem.png "Menu Registered by the Plugin" - - \section1 File Structure - - The plugin wizard creates a set of basic files that a plugin needs or should - have. We will have a look at some of them in detail in the following - sections, here is a short overview: - - \table - \header - \li File - - \li Role - \row - \li \c {Example.json.in} - - \li Plugin meta data template. QMake creates an \c {Example.json} - from this file, which is compiled into the plugin as meta data. - The meta data is read by \QC to find out about the plugin. - \row - \li \c {example.pro} - - \li Project file, used by QMake to generate a Makefile that then is used to - build the plugin. - \row - \li \c {example_global.h} - - \li Contains macro definitions that are useful when this plugin should export - symbols to other plugins. - \row - \li \c {exampleconstants.h} - - \li Header defining constants used by the plugin code. - \row - \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 - - \section1 qmake Project - - The qmake project file \c {example.pro} defines how your plugin should be - compiled. \QC plugins need to have a specific setup there, in addition to - telling qmake which files need to be compiled (or handled by \c moc or - \c uic). Let us have a look at what the project wizard generated for you in - detail. - - \snippet exampleplugin/example.pro 1 - - The first section of the .pro file lets the compiler pass an - \c EXAMPLE_LIBRARY define to the compiled code, which is used in the - \c {example_global.h} header, but is not really of interest for now. You - should not need to change that section of the \c {.pro} file. - - \snippet exampleplugin/example.pro 2 - - This section tells qmake about the files of your project that it should let - compile or otherwise handle. You need to expand that section with any files - you add to the project. - - \snippet exampleplugin/example.pro 3 - - To compile and deploy your plugin, the project needs access to the \QC - sources and build. This section contains the logic that looks for the - information about the location of the sources and build in the - \c {QTC_SOURCE} and \c {QTC_BUILD} environment variables. If these are not - defined, it uses the defaults you set in the project wizard. - - So, if someone else opens your plugin project on their machine, they do not - need to edit the .pro file, but instead they should set the \c {QTC_SOURCE} - and \c {QTC_BUILD} environment variables correctly for the plugin's build - environment. - - You should not need to change this section, except perhaps to adapt the - defaults. - - \snippet exampleplugin/example.pro 4 - - \QC plugins can either be installed into the \QC installation's plugin - directory (requires write access there), or to a user specific plugin - directory. The \c USE_USER_DESTDIR switch in the .pro file defines which - method is used for building the plugin (which is independent from what you - can later use for distributing your plugin to other users). - - \snippet exampleplugin/example.pro 5 - - This section defines the name and dependencies of your plugin. The - \c {QTC_PLUGIN_NAME} variable defines the name of your plugin, and the name - of the dynamic library that is created for it. The \c {QTC_LIB_DEPENDS} - variable is a list of library names of the \QC utility libraries that your - plugin depends on. Typical values would be \c aggregation, - \c extensionsystem and \c utils. The \c {QTC_PLUGIN_DEPENDS} variable - defines the \QC plugins that your plugin depends on. Almost all \QC plugins - will depend on the \c coreplugin. The \c {QTC_PLUGIN_RECOMMENDS} variable - defines the \QC plugins that your plugin optionally depends on. For more - information, see \l{Optional Dependencies}. - - \snippet exampleplugin/example.pro 6 - - The included file \c{qtcreatorplugin.pri} makes sure that you build a plugin - that is suitable for use in \QC, by using the information you gave above. - - For more information about qmake, and writing \c {.pro} files in general, - see the \l{qmake Manual}. - - \section1 Plugin Meta Data Template - - The \c {.json} file is a JSON file that contains information that is needed - by the plugin manager to find your plugin and resolve its dependencies - before actually loading your plugin's library file. We will only have a - short look at it here. For more information, see \l{Plugin Meta Data}. - - The wizard doesn't actually create a .json file directly, but instead a - \c {.json.in} file. qmake uses this to generate the actual plugin .json - meta data file, replacing variables like \c {QTCREATOR_VERSION} with their - actual values. Therefore you need to escape all backslashes and quotes in - the \c {.json.in} file (i.e. you need to write \c {\} to get a backslash - and \c{\"} to get a quote in the generated plugin JSON meta data). - - \snippet exampleplugin/Example.json.in 1 - - The first items in the meta data that is created by the wizard define the - name of your plugin, its version, and with what version of this plugin the - current version is binary compatible with. - - \snippet exampleplugin/Example.json.in 2 - - After that you'll find the information about the plugin that you gave in the - project wizard. - - \snippet exampleplugin/Example.json.in 3 - - The \c {$$dependencyList} variable is automatically replaced by the - dependency information in \c {QTC_PLUGIN_DEPENDS} and - \c {QTC_PLUGIN_RECOMMENDS} from your plugin's \c {.pro} file. - - \section1 Plugin Class - - The files \c {exampleplugin.h} and \c {exampleplugin.cpp} define the plugin - implementation of your little plugin. We'll concentrate on some highlights - here, and give pointers to more detailed information for the various parts. - - \section2 Header File - - The header file \c {exampleplugin.h} defines the interface of the plugin - class. - - \snippet exampleplugin/exampleplugin.h namespaces - - The plugin is defined in a \c {Example::Internal} namespace, which conforms - to the coding rules for \l{coding-rules-namespacing}{namespacing} - in \QC sources. - - \snippet exampleplugin/exampleplugin.h base class - - All \QC plugins must be derived from \l{ExtensionSystem::IPlugin} and - are QObjects. The \c {Q_PLUGIN_METADATA} macro is necessary to create a - valid Qt plugin. The \c IID given in the macro must be - \c {org.qt-project.Qt.QtCreatorPlugin}, to identify it as a \QC plugin, and - \c FILE must point to the plugin's meta data file as described in - \l{Plugin Meta Data}. - - \snippet exampleplugin/exampleplugin.h plugin functions - - The base class defines basic functions that are called during the life cycle - of a plugin, which are here implemented for your new plugin. These functions - and their roles are described in detail in \l{The Plugin Life Cycle}. - - \snippet exampleplugin/exampleplugin.h slot - - The plugin has an additional custom slot, that is used to pop up a dialog - when the user chooses the menu item that this plugin adds. - - \section2 Source File - - The source file contains the actual implementation of the plugin, which - registers a new menu and menu item, and opens a message box when that item - is triggered. - - All the necessary header files from the plugin code itself, from the \c - Core plugin, and from Qt are included in the beginning of the file. The - setup of the menu and menu item is done in the plugin's \c initialize - function, which is the first thing called after the plugin constructor. In - that function, the plugin can be sure that the basic setup of plugin's that - it depends on has been done, for example the Core plugin's \c ActionManager - instance has been created. - - For more information about implementing the plugin interface, see the - \l{ExtensionSystem::IPlugin} API documentation and \l{Plugin Life Cycle}. - - \snippet exampleplugin/exampleplugin.cpp add action - - This part of the code creates a new \c QAction, registers it as a new - \c Command in the action manager, and connects it to the plugin's slot. The - action manager provides a central place where the user can assign and change - keyboard shortcuts, and manages cases where for example a menu item should - be directed to different plugins under different circumstances, as well as a - few other things. This is described in more detail in - \l{Menus and Menu Items}. - - \snippet exampleplugin/exampleplugin.cpp add menu - - Here a new menu item is created, the created command added to it, and the - menu added to the \uicontrol Tools menu in the menu bar. Again, this is - covered in more detail in \l{Menus and Menu Items}. - - \snippet exampleplugin/exampleplugin.cpp slot implementation - - This part defines the code that is called when the menu item is triggered. - It uses the Qt API to open a message box that displays informative text and - an \uicontrol OK button. -*/ diff --git a/doc/api/getting-and-building.qdoc b/doc/api/getting-and-building.qdoc deleted file mode 100644 index 3fb43bea7b..0000000000 --- a/doc/api/getting-and-building.qdoc +++ /dev/null @@ -1,77 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the Qt Creator documentation. -** -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** -****************************************************************************/ - -/*! - \page getting-and-building.html - \title Getting and Building Qt Creator - - \code - TODO: This should be extended. - * Windows specific hassle, see README in \QC sources - \endcode - - There are several reasons why you might want to do your own build of \QC, - like using the most current development version and being able to tweak \QC - at one or the other place. It is also necessary if you want to create your - own \QC plugin. - - \section1 Getting Qt - - Prebuilt \QC packages usually use the latest stable release of Qt. You can - see the exact minimum requirement at the top of \QC's \c {qtcreator.pro}. - (You can find the current version in our source repository here: - \l{https://code.qt.io/cgit/qt-creator/qt-creator.git/tree/qtcreator.pro#n4}.) - - You can get prebuilt Qt packages from - \l{https://download.qt.io}{Qt Downloads}. If you want to use Qt as provided - by your Linux distribution, you need to make sure that all Qt development - packages and private header packages are also installed. - - \section1 Getting and Building \QC - - You can get the \QC sources for a specific version either by using one of - the released source bundles, or from the Git repository - \l{https://code.qt.io/cgit/qt-creator/qt-creator.git}. If you intend to - contribute to \QC itself, you should use the repository from our Gerrit - review tool as described in: - \l{https://wiki.qt.io/Setting_up_Gerrit}{Setting up Gerrit}. - - We strongly encourage you to do out-of-source builds of \QC (also called - shadow-builds). - - After you put the \QC sources somewhere (lets call the path - \c {<QtCreatorSources>}) - you build it on Linux and Mac with - - \code - cd <QtCreatorSources>/.. - mkdir qtcreator-build - cd qtcreator-build - <QtInstall>/bin/qmake -r <QtCreatorSources> - make - \endcode - - or the corresponding commands on Windows systems. -*/ diff --git a/doc/api/images/firstplugin-kitselection.png b/doc/api/images/firstplugin-kitselection.png Binary files differdeleted file mode 100644 index 4dd7786436..0000000000 --- a/doc/api/images/firstplugin-kitselection.png +++ /dev/null diff --git a/doc/api/images/firstplugin-menuitem.png b/doc/api/images/firstplugin-menuitem.png Binary files differdeleted file mode 100644 index fda6c38e46..0000000000 --- a/doc/api/images/firstplugin-menuitem.png +++ /dev/null diff --git a/doc/api/images/firstplugin-nameandpath.png b/doc/api/images/firstplugin-nameandpath.png Binary files differdeleted file mode 100644 index 6a1c4d3e41..0000000000 --- a/doc/api/images/firstplugin-nameandpath.png +++ /dev/null diff --git a/doc/api/images/firstplugin-pluginsetup.png b/doc/api/images/firstplugin-pluginsetup.png Binary files differdeleted file mode 100644 index b48fe2f3fc..0000000000 --- a/doc/api/images/firstplugin-pluginsetup.png +++ /dev/null diff --git a/doc/api/images/firstplugin-runsettings.png b/doc/api/images/firstplugin-runsettings.png Binary files differdeleted file mode 100644 index bce82e96ca..0000000000 --- a/doc/api/images/firstplugin-runsettings.png +++ /dev/null diff --git a/doc/api/images/firstplugin-summary.png b/doc/api/images/firstplugin-summary.png Binary files differdeleted file mode 100644 index 457da208db..0000000000 --- a/doc/api/images/firstplugin-summary.png +++ /dev/null diff --git a/doc/api/images/firstplugin-wizard.png b/doc/api/images/firstplugin-wizard.png Binary files differdeleted file mode 100644 index 0c0df4f7fb..0000000000 --- a/doc/api/images/firstplugin-wizard.png +++ /dev/null diff --git a/doc/api/images/riot.png b/doc/api/images/riot.png Binary files differdeleted file mode 100644 index d3c12b4570..0000000000 --- a/doc/api/images/riot.png +++ /dev/null diff --git a/doc/api/images/variablechooser.png b/doc/api/images/variablechooser.png Binary files differdeleted file mode 100644 index b11ebf6550..0000000000 --- a/doc/api/images/variablechooser.png +++ /dev/null diff --git a/doc/api/plugin-lifecycle.qdoc b/doc/api/plugin-lifecycle.qdoc deleted file mode 100644 index fa6aef6575..0000000000 --- a/doc/api/plugin-lifecycle.qdoc +++ /dev/null @@ -1,142 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the Qt Creator documentation. -** -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** -****************************************************************************/ - -/*! - \page plugin-lifecycle.html - \title Plugin Life Cycle - - To be able to write \QC plugins, you must understand the steps that the plugin - manager takes when you start or shut down \QC. This section describes - the process and the state that plugins go through in detail. - - You can get more information about what happens when you start \QC by running it with the - environment variable \c QT_LOGGING_RULES set to \c {qtc.extensionsystem*=true} which enables - logging of plugin-related debug output. - - When you start \QC, the plugin manager does the following: - - \list 1 - \li Looks in its search paths for - all dynamic libraries, and reads their meta data. All libraries without meta data - and all libraries without the \c{org.qt-project.Qt.QtCreatorPlugin} IID are ignored. - This is the first point where loading a plugin can fail in the worst case of malformed - meta data. - - \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()} - function, or, after a plugin is loaded, through the plugin's - \l{ExtensionSystem::IPlugin::pluginSpec()}{pluginSpec()} function. - - \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()} functions of - all plugins in the order of the load queue. In the \c initialize function, - 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()} function 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 - - \li Sets the plugins to \c Initialized state. - - \li Calls the \l{ExtensionSystem::IPlugin::extensionsInitialized()}{extensionsInitialized()} - functions of all plugins in \e reverse order of the load queue. After - the \c extensionsInitialized function, 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 Sets the plugins to \c Running state. - \endlist - - At the end of startup, the \c Core plugin's \l{Core::ICore} sends two signals. - Before the \QC UI is shown it sends \l{Core::ICore::coreAboutToOpen()}{coreAboutToOpen()}, - and afterwards \l{Core::ICore::coreOpened()}{coreOpened()}. - - After startup, when the event loop of \QC is running, the plugin manager calls - the \l{ExtensionSystem::IPlugin::delayedInitialize()}{delayedInitialize()} functions of all - plugins in \e reverse order of the load queue. The calls are done on the main thread, but - separated by a delay of a few milliseconds to ensure responsiveness of \QC. - In the \c delayedInitialize function, a plugin can perform non-critical initialization - that could unnecessarily delay showing the \QC UI if done during startup. - - After all delayed initializations are done the \l{ExtensionSystem::PluginManager}{PluginManager} - sends the \l{ExtensionSystem::PluginManager::initializationDone()}{initializationDone()} signal. - - Before shutdown, the \c Core plugin \l{Core::ICore} sends the - \l{Core::ICore::coreAboutToClose()}{coreAboutToClose()} signal. After that, the - plugin manager starts its shutdown sequence: - - \list 1 - \li Calls the \l{ExtensionSystem::IPlugin::aboutToShutdown()}{aboutToShutdown()} functions 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 - function. 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-metadata.qdoc b/doc/api/plugin-metadata.qdoc deleted file mode 100644 index 5a6c133526..0000000000 --- a/doc/api/plugin-metadata.qdoc +++ /dev/null @@ -1,343 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the Qt Creator documentation. -** -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** -****************************************************************************/ - -/*! - \page plugin-meta-data.html - \title Plugin Meta Data - - The meta data file of a plugin is a JSON file that contains all - information that is necessary for loading the plugin's library, - determining whether plugins are to be loaded and in which order (depending - on e.g. dependencies). In addition, it contains textual descriptions of - who created the plugin, what it is for, and where to find more information about it. - The file must be located in one of the include search paths when compiling the plugin, - and must have the \c .json extension. The JSON file is compiled into the plugin as meta data, - which then is read by \QC when loading plugins. - - \section2 Main Keys - - The main keys that are used to identify your your plugin and define default loading behavior, - consist of the mandatory keys \c Name and \c Version, and the optional keys \c CompatVersion, - \c Experimental, \c DisabledByDefault, \c Required and \c Platform. - \table - \header - \li Key - \li Value Type - \li Meaning - \row - \li Name - \li String - \li This is used as an identifier for the plugin and can e.g. - be referenced in other plugin's dependencies. - \row - \li Version - \li String - \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 - \li CompatVersion - \li String - \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 - \li Experimental - \li Boolean - \li Optional. 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 - \li DisabledByDefault - \li Boolean - \li Optional. 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. - \row - \li HiddenByDefault - \li Boolean - \li Optional. Defaults to \c false. - If set, the plugin is not shown in the default view in the - \uicontrol {About Plugins...} dialog, but only if the user requests seeing all - plugins. It is still shown with the \c{-version} command line option. - \row - \li Required - \li Boolean - \li Optional. Defaults to \c false. - Is used as a hint for the \uicontrol{About Plugins...} dialog, that the user may not - manually disable this plugin. Only used for the Core plugin. - \row - \li Platform - \li String - \li Optional. 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. - \endtable - - \section2 Plugin-describing Keys - - These are solely used for more detailed (user centric) description of the plugin. All of these - are optional. - \table - \header - \li Key - \li Value Type - \li Meaning - \row - \li Category - \li String - \li Defaults to \c Utilities. Is used to put related plugins - under the same tree node in the plugin overview \uicontrol{About Plugins...}. - \row - \li Vendor - \li String - \li String that describes the plugin creator/vendor, - like \c{MyCompany}. - \row - \li Copyright - \li String - \li A short copyright notice, like \c{(C) 2016 MyCompany}. - \row - \li License - \li String or array of strings - \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 - \li Description - \li String or array of strings - \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 - \li Url - \li String - \li Link to further information about the plugin, like - \c{http://www.mycompany-online.com/products/greatplugin}. - \endtable - - \section2 Dependencies - - A plugin can have dependencies on other plugins. These are - specified in the plugin meta data, to ensure that - these other plugins are loaded before this plugin. - - Dependencies are declared with the key \c Dependency, which contains an array of JSON objects - with required keys \c Name and \c Version, and optional key \c Type. - - The following formulas illustrate how the dependency information is matched. - In the formulas the name of the required plugin (as defined in the \c Name of the dependency - object) is denoted as \c DependencyName - and the required version of the plugin is denoted as \c DependencyVersion. - A plugin with given \c Name, \c Version and \c CompatVersion - as defined in the plugin meta data matches - the dependency if - \list - \li its \c Name matches \c DependencyName, and - \li \c {CompatVersion <= DependencyVersion <= Version}. - \endlist - For example a dependency - \code - { - "Name" : "SomeOtherPlugin", - "Version" : "2.3.0_2" - } - \endcode - would be matched by a plugin with - \code - { - "Name" : "SomeOtherPlugin", - "Version" : "3.1.0", - "CompatVersion" : "2.2.0", - ... - } - \endcode - since the name matches, and the version \c{2.3.0_2} given in the dependency tag - lies in the range of \c{2.2.0} and \c{3.1.0}. - - \table - \header - \li Key - \li Value Type - \li Meaning - \row - \li Dependencies - \li Array of dependency objects - \li Describes the dependencies on other plugins. - \endtable - - A dependency object is a JSON object with the following keys: - \table - \header - \li Key - \li Value Type - \li Meaning - \row - \li Name - \li String - \li The name of the plugin, on which this plugin relies. - \row - \li Version - \li String - \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 - \li Type - \li String - \li Optional. Value \c Required, \c Optional, or \c Test. Defines if the dependency is - a hard requirement, optional, or required for running the plugin's tests. - Defaults to \c{Required}. - \endtable - - \section3 Optional Dependencies - - A plugin can specify that a dependency on another plugin is optional, by adding - \c {"Type" : "Optional"} to the dependency object: - - \list - \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 - dependency might be loaded or not, the plugin may also not link against the dependency. - A common way to access objects from optional dependencies is to get the object from the - \l{The Plugin Manager, the Object Pool, and Registered Objects}{global object pool} - via ExtensionSystem::PluginManager::getObjectByName() and use QMetaObject functions to call - functions on it. - - \section3 Test Dependencies - - When the user runs the application with the \c{-test} command line argument, only - the specified plugins and their dependencies are loaded. This is done in order to - speed up the execution of tests by avoiding the loading of unneeded plugins. - - A plugin can specify additional dependencies that are required for running its - tests, but not for its normal execution, by declaring dependencies with - \c {"Type" : "Test"}. Test dependencies are force loaded, and do not affect load order. - - This type of dependency is not transitive. - - \section2 Command Line Arguments - - Plugins can register command line arguments that the user can give - when starting the application. These command line arguments are shown - with a one-line description when the user runs the application with - the \c{-help} command line argument, and the plugin manager does its command - line parsing and sanity checks based on that information. - If the plugin manager finds matching command line arguments for a plugin, - it passes them on to the plugin's - \l{ExtensionSystem::IPlugin::initialize()}{initialize()} function. - - Command line arguments are defined through the key \c Arguments, which contains an array - of argument objects. Each individual argument object has the required key \c Name, and - optional keys \c Parameter and \c Description. - - \table - \header - \li Key - \li Value Type - \li Meaning - \row - \li Arguments - \li Array of argument objects - \li Describes the command line arguments that the plugin wants to handle. - \endtable - - An argument object is a JSON object with the following keys: - \table - \header - \li Key - \li Value Type - \li Meaning - \row - \li Name - \li String - \li The command line argument itself, including the \c - prefix, e.g. - \c{-my-parameter}. - \row - \li Parameter - \li String - \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. - \row - \li Description - \li String - \li Optional. A (one-line) description of the argument for the command line argument help. - \endtable - - \section2 Example \c Test.json - - \code - { - "Name" : "Test", - "Version" : "1.0.1", - "CompatVersion" : "1.0.0", - "Vendor" : "My Company", - "Copyright" : "(C) 2016 MyCompany", - "License" : [ - "This is a default license bla", - "blubbblubb", - "end of terms" - ], - "Category" : "My Company Additions", - "Description" : [ - "This plugin is just a test.", - "It demonstrates the great use of the plugin meta data." - ], - "Url" : "http://www.mycompany-online.com/products/greatplugin", - "Arguments" : [ - { - "Name" : "-variant", - "Parameter" : "fancy|boring", - "Description" : "Brings up the fancy or boring user interface" - } - ], - "Dependencies" : [ - { "Name" : "SomeOtherPlugin", "Version" : "2.3.0_2" }, - { "Name" : "EvenOther", "Version" : "1.0.0" } - ] - } - \endcode - - \section2 A Note on Plugin Versions - - Plugin versions are in the form \c{x.y.z_n} where, \c x, \c y, \c z and \c n are - non-negative integer numbers. You don't have to specify the version - in this full form - any left-out part will implicitly be set to zero. - So, \c{2.10_2} is equal to \c{2.10.0_2}, and \c 1 is the same as \c{1.0.0_0}. - -*/ diff --git a/doc/api/pluginmanager.qdoc b/doc/api/pluginmanager.qdoc deleted file mode 100644 index 03ec4d190e..0000000000 --- a/doc/api/pluginmanager.qdoc +++ /dev/null @@ -1,123 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the Qt Creator documentation. -** -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** -****************************************************************************/ - -/*! - \page pluginmanager.html - \title The Plugin Manager, the Object Pool, and Registered Objects - - Usually, plugins do not need to access the plugin manager directly. - They interact with it mostly indirectly through the ExtensionSystem::IPlugin interface. - There are occasions though, where using the plugin manager API is necessary. - Plugins need to access the plugin manager's object pool to extend - some aspects of \QC, for example to add pages to the options dialog. They - can also utilize the object pool to provide extension points for other plugins - (see \l{Extending and Providing Interfaces}). - - \section1 Plugin Manager - - The plugin manager handles all the details regarding finding plugins, reading their - description files, resolving plugin dependencies, loading and initializing all plugins - in the right order, and passing on command line arguments. - - In addition, the plugin manager manages an \e{object pool}, where objects can be registered - and retrieved depending on different criteria. - - Most interaction of plugins with the plugin manager should be done through the - ExtensionSystem::IPlugin interface, but the following tables summarize some functions - and signals that can be useful for plugins. - See the ExtensionSystem::PluginManager reference documentation for the complete list. - - \table - \header - \li Function - \li Description - \row - \li instance() - \li Returns the singleton plugin manager instance, for example for connecting to signals. - \row - \li addObject() - \li Registers an object in the object pool. - Also available through ExtensionSystem::IPlugin::addObject(). - \row - \li removeObject() - \li Unregisters an object from the object pool. - Also available through ExtensionSystem::IPlugin::removeObject(). - \row - \li getObjects<T>() - \li Returns all objects of type T that are registered in the object pool. - This respects \l{Aggregations}. - \row - \li getObject<T>() - \li Returns one object of type T that is registered in the object pool. - This respects \l{Aggregations}. - \row - \li getObjectByName(const QString &name) - \li Returns one object with the given object name that is registered in the object pool. - \endtable - - \table - \header - \li Signal - \li Description - \row - \li objectAdded(QObject *object) - \li Sent after an object is registered in the object pool. - \row - \li aboutToRemoveObject(QObject *object) - \li Sent just before an object is unregistered from the object pool. - \row - \li initializationDone() - \li Sent when plugins are running and all delayed initialization is done. - \endtable - - \target object pool - \section1 Object Pool and Registered Objects - - Plugins can register objects to a common \e pool that is managed by - the plugin manager. Objects in the pool must derive from QObject, there are no other - prerequisites. - - All objects of a specified type can be retrieved from the object pool - via the \l{ExtensionSystem::PluginManager::getObjects()}{getObjects()} and - \l{ExtensionSystem::PluginManager::getObject()}{getObject()} functions. - They are aware of Aggregation::Aggregate, so these functions use the Aggregation::query() - functions instead of qobject_cast to determine the matching objects. - - It is also possible to retrieve an object with a specific object name with - \l{ExtensionSystem::PluginManager::getObjectByName()}{getObjectByName()} - (see QObject::objectName()). - - Whenever the state of the object pool changes, a corresponding - \l{ExtensionSystem::PluginManager::objectAdded()}{objectAdded()} or - \l{ExtensionSystem::PluginManager::aboutToRemoveObject()}{aboutToRemoveObject()} signal is - emitted by the plugin manager. - - A common use case for the object pool is that a plugin (or the application) provides - an \e{extension point} for other plugins, which is a class that can - be implemented and added to the object pool to be retrieved by the providing plugin. - It is also possible to use the object pool to provide access to an object without actually - linking against the providing plugin library. See \l{Extending and Providing Interfaces} - for details. -*/ diff --git a/doc/api/qtcreator-api.qdoc b/doc/api/qtcreator-api.qdoc deleted file mode 100644 index bfa1918cfc..0000000000 --- a/doc/api/qtcreator-api.qdoc +++ /dev/null @@ -1,257 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the Qt Creator documentation. -** -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** -****************************************************************************/ - -/*! - \page qtcreator-api.html - - \title Qt Creator API Reference - - The core of \QC is basically only a \l{ExtensionSystem}{plugin loader}. All - functionality is implemented in plugins. The basis of \QC is implemented in - the \l{Core}{Core} Plugin. The plugin manager provides simple means for - plugin cooperation that allow plugins to provide hooks for other plugin's - extensions. - - \section1 Libraries - - \section2 Core Libraries - - There are a few core libraries used by many parts of Qt Creator. - - \table - \header - \li Library Name - \li Description - - \row - \li \l{Aggregation} - \li Adds functionality for "glueing" QObjects of different types - together, so you can "cast" between them. - - \row - \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 - \li \l{Utils} - \li General utility library. - - \row - \li \l{QmlJS} - \li QML and JavaScript language support library. - - \endtable - - \section2 Additional libraries - - \table - \header - \li Library Name - \li Description - - \row - \li \l{qtcreatorcdbext} - \li Windows CDB debugger extension - \endtable - - \section1 Plugins - - As already mentioned, \QC is basically only a plugin loader framework - which gets its IDE functionality through plugins. The most important plugin - is the \c Core plugin which provides all the basic functionality needed - later to integrate e.g. editors or mode windows. - - \table - \header - \li Plugin Name - \li Description - - \row - \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. - - This plugin also contains classes necessary to hook into the - \l{Locator} as well as support for searching text in arbitrary - widgets. - - \row - \li \l{ProjectExplorer} - \li The project explorer plugin. Provides base classes for project - handling. - - \row - \li \l{Debugger} - \li Debugging functionality. - - \row - \li \l{VcsBase} - \li Base classes for version control support. - - \row - \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. - \endtable -*/ - -/*! - \page classes.html - \title Qt Creator Classes - - \generatelist classes -*/ - -/*! - \page namespaces.html - \title Qt Creator Namespaces - - \generatelist namespaces -*/ - -/*! - \page mainclasses.html - \title Qt Creator Main Classes - - \generatelist mainclasses - -*/ - -/*! - \page functions.html - \title Qt Creator Functions - - \generatelist functionindex -*/ - -/*! - \page common_extension_tasks.html - \title Common Extension Tasks - - This section summarizes the API functions that you can use to add UI - components to \QC. - - \table - \header - \li Task - \li Details - \li API - - \row - \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 - \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 - \li Add a mode. - \li Modes correspond to complete screens of controls, specialized - for a task. - \li \l{Core::IMode} - - \row - \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 - \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 - \li Add support for a new version control system. - \li Version control systems integrated in \QC are Bazaar, CVS, Git, - Mecurial, Perforce, and Subversion. - \li \l{Core::IVersionControl} - - \row - \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 - \li Add an options page to the \uicontrol Options dialog. - \li Add a new page to existing or new category in - \uicontrol Tools > \uicontrol Options. - \li \l{Core::IOptionsPage} - - \row - \li Add a find filter to the \uicontrol Find dialog. - \li Implement any kind of search term based search. - \li \l{Find::IFindFilter}, \l{Core::SearchResultWindow} - - \row - \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{Core::IFindSupport}, \l{Find::BaseTextFind} - - \row - \li Add a completely new project type. - \li - \li - - \row - \li Add a new type of build step. - \li - \li - - \row - \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{Core::ILocatorFilter}, \l{Core::LocatorFilterEntry}, - \l{Locator::BaseFileFilter} - - \row - \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 - \li - \li - \li - - \endtable -*/ diff --git a/doc/api/qtcreator-dev-online.qdocconf b/doc/api/qtcreator-dev-online.qdocconf deleted file mode 100644 index bf7d6c02b4..0000000000 --- a/doc/api/qtcreator-dev-online.qdocconf +++ /dev/null @@ -1,4 +0,0 @@ -# Run qdoc from the directory that contains this file. -include(../config/qtcreator-developer.qdocconf) -include($QT_INSTALL_DOCS/global/qt-html-templates-online.qdocconf) - diff --git a/doc/api/qtcreator-dev-wizards.qdoc b/doc/api/qtcreator-dev-wizards.qdoc deleted file mode 100644 index ddb11119ea..0000000000 --- a/doc/api/qtcreator-dev-wizards.qdoc +++ /dev/null @@ -1,156 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the Qt Creator documentation. -** -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** -****************************************************************************/ - -/*! - \page qtcreator-dev-wizards.html - \title Creating Wizards in Code - - \section1 Introduction - - If the functionality provided by template-based - \l{http://doc.qt.io/qtcreator/creator-project-wizards.html}{custom wizards} - is not sufficient for your case, you can write wizards in code. - - A wizard in \QC is an instance of a class implementing - the Core::IWizardFactory interface that has a creator function registered - with IWizardFactory::registerFactoryCreator. - - Implementing wizards requires: - \list - \li Writing a factory class that derives from Core::IWizardFactory. This is - a very generic interface that does not make any assumption about what - the wizard does and what its UI looks like. - - \li Providing a set of parameters that determine how the wizard shows up - in the list of wizards in the \uicontrol {New File or Project} dialog. - - When deriving from Core::IWizardFactory, the constructor has to call - the following setters provided by the base class: - - \list - \li \c setId - \li \c setWizardKind - \li \c setIcon - \li \c setDescription - \li \c setDisplayName - \li \c setCategory - \li \c setDisplayCategory - \li \c setDescriptionImage - \li \c setRequiredFeatures - \li \c setFlags - \endlist - - \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. - - \li Implementing the wizard functionality - - It is recommended to use Core::GeneratedFile to represent files - that need to be written to disk. They allow to delay writing the actual - data to disk till the wizard is done. - \endlist - - \section2 Relevant Classes - - \table - \header - \li Class - \li Description - - \row - \li Core::IWizardFactory - \li \QC wizard interface, implementations of which are registered - with ExtensionSystem::PluginManager. - - \row - \li Core::GeneratedFile - \li A file containing name, contents, and some attributes. - - \row - \li Utils::FileWizardPage - \li Introductory wizard page asking for file name and path. - - \row - \li Utils::ProjectIntroPage - \li Introductory wizard page asking for project name and path. - \endtable - - \section2 Setters and Getters of IWizardFactory - - The setters and getters listed below determine how the wizard shows up - in the list of wizards in the \uicontrol {New File or Project} dialog. - - \table - \header - \li Type - \li Parameter Name - \li Description - - \row - \li Core::IWizardFactory::WizardKind - \li kind - \li Enumeration value that indicates the type of the wizard - (\c project or \c file). - - \row - \li QIcon - \li icon - \li Icon to show. - - \row - \li QString - \li description - \li Descriptive text. - - \row - \li QString - \li displayName - \li Name to be shown in the list. - - \row - \li QString - \li id - \li Unique identifier for the wizard. It also determines the order - within a category. - - \row - \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 - \li QString - \li displayCategory - \li Description of the category. - \endtable - - All wizards that have the same category set will be grouped together in the - \uicontrol {New File or Project} dialog. - -*/ diff --git a/doc/api/qtcreator-dev.qdoc b/doc/api/qtcreator-dev.qdoc deleted file mode 100644 index 59374cc562..0000000000 --- a/doc/api/qtcreator-dev.qdoc +++ /dev/null @@ -1,258 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the Qt Creator documentation. -** -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** -****************************************************************************/ - -/*! - \page extending-index.html - \title Extending Qt Creator Manual - - \QC is a cross-platform integrated development environment (IDE) tailored to - the needs of Qt developers. - - \QC is extensible in various ways. For example, \QC architecture is based on - a plugin loader, which means that all functionality beyond plugin loading - is implemented in plugins. However, you can extend and tweak many parts of - \QC without the need to resort to coding in C++ and implementing such a - plugin. - - This document gives you an overview of the various ways in which you can - extend \QC, depending on what you want to achieve, and points you to the - relevant documentation. - - \section1 Generating Domain Specific Code and Templates - - If you regularly need to write the same code, be it little code snippets, - whole files or classes spread over multiple files, or complete projects, you - can create code snippets, templates, and wizards for that purpose. - - \section2 Snippets - - Typically, snippets consist of a few lines of code (although they can also - be plain text) that you regularly want to insert into a bigger body of code, - but do not want to type each time. For example, \c while and \c for loops, - \c if-else and \c try-catch constructs, and class skeletons. Snippets are - triggered in the same way as normal code completion (see - \l{Code Assist}{Providing Code Assist}). - \QC contains a set of preconfigured snippets groups to which you can add - your own snippets. - - \list - \li \l{http://doc.qt.io/qtcreator/creator-completing-code.html#editing-code-snippets} - {Snippets User Interface} - \li \l{Snippets}{Adding Snippets Groups} - \endlist - - \section2 File and Project Templates - - You can extend the wizards in \uicontrol File > - \uicontrol {New File or Project} with your own file and project templates by - writing JSON definition files for them. - \list - \li \l{http://doc.qt.io/qtcreator/creator-project-wizards.html} - {Adding New Custom Wizards} - \li \l{User Interface Text Guidelines} - \endlist - - \section2 Custom Wizards - - If the above methods for code snippets and templates are not sufficient for - your use case, you can create a custom \QC plugin. While this gives you - complete control over the wizard, it also requires you to write most of the - UI and the logic yourself. - - \list - \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 - - If you have files with extensions or MIME types that \QC does not handle by - default, you can edit the MIME type definitions, add highlight definition - files, and create your own text editors. - - \section2 MIME Types - - You might find that \QC could handle a particular file of yours if it knew - about the type of its contents. For example, C++ header or source files - with file extensions that are not known to \QC. You can adapt the MIME type - definitions in \QC to your specific setup, by adding or removing file - extensions and specifying magic headers. - - \list - \li \l{http://doc.qt.io/qtcreator/creator-mime-types.html} - {Editing MIME Types} - \li \l{http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-latest.html} - {MIME Type Specification Files} - \endlist - - \section2 Text Highlighting and Indentation - - For text files, \QC provides an easy way to add highlighting and indentation - for file types that are not known to it by default. Generic highlighting is - based on highlight definition files that are provided by the Kate Editor. - You can download highlight definition files for use with \QC and create - your own definition files. - - \list - \li \l{http://doc.qt.io/qtcreator/creator-editor-options.html#generic-highlighting} - {Generic Highlighting} - \li \l{http://kate-editor.org/2005/03/24/writing-a-syntax-highlighting-file/} - {Writing a Syntax Highlighting File} - \endlist - - \section2 Custom Text Editors - - If you need more advanced features than the MIME type and highlighting - features described above, such as custom text completion or features that - rely on semantic analysis, you can extend \QC with a text editor of your - own. \QC provides a special API for text editors that gives you a basis to - build on, taking away some of the pain of implementing a text editor from - the ground up. - - \list - \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 - - You can also add a completely custom editor to gain complete control over - its appearance and behavior. - - \list - \li \l{Creating Plugins} - \li \l{Qt Creator Coding Rules} - \li \l{Editors} - \endlist - - \section1 Running External Tools - - Most software projects and development processes require various external - tools. Several external tools, such as popular version control systems and - build tool chains are integrated into \QC. However, it is impossible for a - single tool to cover all the use cases, and therefore you can integrate - additional tools to \QC. - - \section2 Simple External Tools - - In \QC, you can specify tools that you can then run from a menu or by using - a keyboard shortcut that you assign. This allows you to accomplish several - things, with some limitations. You specify a command to run, arguments and - input for running it, and how to handle the output. To specify the values, - you can use a set of internal \QC variables, such as the file name of the - current document or project, or the currently selected text in a text - editor. If you find variables missing, please do not hesitate to fill a - feature suggestion. The tool descriptions are saved as XML files that you - can share. - - \list - \li \l{http://doc.qt.io/qtcreator/creator-editor-external.html} - {Using External Tools} - \li \l{External Tool Specification Files} - \endlist - - \section2 Complex External Tools - - When you plan to integrate more complex tools, carefully consider whether - there really are advantages to be gained by tightly integrating the tool - into \QC over loosely integrating it by mainly providing a means of starting - the tool with fitting parameters. - - \section3 Loosely Integrating Tools - - If no interaction is needed between \QC and the external tool, just starting - an external application with its own user interface is preferable. That way - cluttering the \QC UI is avoided, and the tool will be available with a - nice interface even without using \QC at all. - - Usually, you can use the external tool specification files to start the - tool. If starting the tool and handling its output require more complex - logic, you can add a menu item to \QC with a plugin. If you need a way to - configure the tool in \QC, you can add an \uicontrol Options page for it. - - \list - \li \l{http://doc.qt.io/qtcreator/creator-editor-external.html}{Using External Tools} - \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 - - In some cases, running an external tool would not require tight integration - with \QC, but investigating the output of the tool would benefit from it. - For example, some tools generate lists of issues in files that are part of - the project and some tools create output that is related to the code. For - these tools, it is useful to interactively switch between the output and - the corresponding code. - - One way to handle that would be to let the tool create an output file, which - is then opened within \QC. You provide an editor (probably read-only) for - handling this file. For lists of issues, consider creating task list files - which are shown in the \uicontrol Issues output pane. - - \list - \li \l{http://doc.qt.io/qtcreator/creator-task-lists.html} - {Showing Task List Files in the Issues Pane} - \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 - \li \l{Developing Qt Creator Plugins} - \list - \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 - \li Reference - \list - \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-dev.qdocconf b/doc/api/qtcreator-dev.qdocconf deleted file mode 100644 index 016bd6450f..0000000000 --- a/doc/api/qtcreator-dev.qdocconf +++ /dev/null @@ -1,3 +0,0 @@ -# Run qdoc from the directory that contains this file. -include(../config/qtcreator-developer.qdocconf) -include($QT_INSTALL_DOCS/global/qt-html-templates-offline.qdocconf) diff --git a/doc/api/qtcreator-documentation.qdoc b/doc/api/qtcreator-documentation.qdoc deleted file mode 100644 index 1d54a86912..0000000000 --- a/doc/api/qtcreator-documentation.qdoc +++ /dev/null @@ -1,343 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the Qt Creator documentation. -** -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** -****************************************************************************/ - -/*! - \previouspage external-tool-spec.html - \page qtcreator-documentation.html - \nextpage coding-style.html - - \title Writing Documentation - - When you add plugins or contribute new features to \QC, you probably want - other people to know about them and to be able to use them. Therefore, you - should also contribute documentation for them. Follow the guidelines in this - section to make sure that your documentation fits in well with the rest of - the \QC documentation. - - When you contribute a plugin, you should write documentation both for the - developers who use \QC and for the ones who develop it. - - Write the following user documentation for addition to the \QC Manual: - - \list - \li Overview topic, which describes the purpose of your plugin from the - viewpoint of \QC users - - \li Procedure topics, which describe how to use your plugin as part of \QC - - \li Reference topics, which contain information that developers - occasionally need to look up (optional) - \endlist - - Write the following developer documentation for addition to the Extending - \QC Manual: - - \list - \li Overview topic, which describes the architecture and use cases for - your plugin from the viewpoint of \QC developers - - \li API documentation, which is generated from code comments - \endlist - - \section1 Configuring the Documentation Project - - \QC documentation is written by using QDoc. For more information about using - QDoc, see the \l{http://doc.qt.io/qt-5/qdoc-index.html}{QDoc Manual}. - - QDoc finds the new topics automatically, when you place them as \c {.qdoc} - files in the correct folder. However, to make the topics accessible to - readers, you must also add them to the table of contents - (\c {doc\src\qtcreator-toc.qdoc}) and fix the next page and previous page - links to them from other topics. - - \section2 Creating Folders and Files - - These instructions apply only to the \QC Manual. Add API documentation - directly to the code source files. However, you can write an API overview - also as a separate \c {.qdoc} file. - - Create a subfolder for your documentation in the \QC project folder in the - \c {doc\src} folder. Create a separate file for each topic. - - The easiest way is probably to copy an existing file, save it as a new file, - and modify it. This way, you already have samples of the necessary bits and - pieces in place, such as topic start and end commands, copyright statement, - links to next and previous topics, and topic title. - - \section2 Integrating Topics to Documentation - - You must integrate your new topics to the \QC Manual and Extending \QC - Manual by adding links to them to the table of contents and to other - relevant topics. - - To link to the topic, you can use the topic title. For example: - - \code - \l{Integrating Topics to Documentation} - \endcode - - This does not work if topic titles are not unique. Also, if you change the - title, the link breaks. You can avoid this risk by adding the \c {\target} - command to your topic and then linking to the target. - - \section2 Updating Next and Previous Links - - When you add new topics to a document, you must also change the navigation - links of the topics around them. This is very error prone when done - manually, and therefore we have a script called \c {fixnavi.pl} for it. For - the script to work, you must add the \c {\nextpage} and \c {\previouspage} - commands to the topic, with dummy values (for example, - \c {\nextpage=anything.html}). - - \note The script creates the links according to the TOC in the topic set as - the value of the \c indexTitle configuration parameter - (\c {doc\src\qtcreator-toc.qdoc}). If your topics are not listed in the TOC, - the script removes the \c {\nextpage} and \c {\previouspage} commands from - them. - - To run the script, you must have Perl installed. If you build Qt yourself, - you should already have it. Otherwise, download and install - \l{http://www.perl.org/}{Perl}. - - To run the script, enter the following command in the doc folder: - - \list - \li nmake fixnavi (on Windows) - - \li make fixnavi (on Linux) - \endlist - - \section1 Writing Text - - Follow the guidelines for - \l{http://wiki.qt.io/Writing_Qt_Documentation}{writing Qt documentation}. - - The documentation must be grammatically correct English and use the standard - form of written language. Do not use dialect or slang words. Use idiomatic - language, that is, expressions that are characteristic for English. If - possible, ask a native English speaker for a review. - - \section2 Capitalizing Headings - - Use the book title capitalization style for all titles and section headings - (\c {\title}, \c {\section1}, \c {\section2}, and so on). For more - information, see \l{Using Book Style Capitalization}. - - \section1 Using Images - - You can illustrate your documentation by using screen shots, diagrams, and - other images. - - Use the \c {\image} and \c {\inlineimage} QDoc commands to refer to images - from the text. You do not need to add paths to image names. For example: - - \code - \image riot.png - \endcode - - \section2 Taking Screen Shots - - \QC has the native look and feel on Windows, Linux, and \macos, and therefore, - screen shots can end up looking very different, depending on who takes them - and which system they use. To try to preserve a consistent look and feel in - the \QC Manual, observe the guidelines listed in this section when taking - screen shots. - - \note Do not rely on screen shots present reasonable example values to - users, but always place example values also in the text. - - \list - \li Use the screen resolution of 1366x768 (available on the most - commonly used screens, as of this writing). - - \li Use the aspect ratio of 16:9. - - \li Open the application in the maximum size on full screen. - - \li Use your favorite tool to take the screen shot. - - \li Include only the part of the screen that you need (you can crop the - image also in the screen capture tool). - - \li To highlight parts of the screen shot, use the images of numbers - that are stored in \c{doc\images\numbers} in the \QC repository. - - \li Before you submit the images to the repository, optimize them to - save space. - \endlist - - \section2 Hightlighting Parts of the Screen - - You can use number icons in screenshots to highlight parts of the screenshot - (instead of using red arrows or borders, or something similar). You can then - refer to the numbers in text. For and example, see the - \l{http://doc.qt.io/qt-5/topics-app-development.html}{Development Tools} - topic in the Qt reference documentation. - - This improves the consistency of the look and feel of Qt documentation, - and eliminates the need to describe parts of the UI in the text, because - you can just insert the number of the element you are referring to in - brackets. - - You can find a set of images that show the numbers from 1 to 10 in the - \c doc\images\numbers directory (or in the \c qtdoc module sources in - \c doc\images\numbers). - - To use the numbers, copy-paste the number images on the screenshot to the - places that you want to refer to from text. - - \section2 Optimizing Images - - Save images in the PNG format in the \QC project folder in the - \c {doc\images} folder. Binary images can easily add megabytes to the Git - history. To keep the history as small as possible, the Git post-commit hooks - remind you to try to keep image size below 50 kilobytes. To achieve this - goal, crop images so that only relevant information is visible in them. - Before committing images, optimize them by using an image optimization tool. - - Optimization should not visibly reduce image quality. If it does, do not do - it. - - You can use a web service, such as \l{https://tinypng.com}, or an image - optimization tool to shrink the images. For example, you can use the Radical - Image Optimization Tool (RIOT) or OptiPNG on Windows, ImageOptim on - \macos, or some other tool available on Linux. - - With ImageOptim, you simply drag and drop the image files to the - application. The following section describes the settings to use for RIOT. - - \section3 Using RIOT - - Download and install \l{http://luci.criosweb.ro/riot/}{RIOT}. - - \image riot.png - - Open your images in RIOT and use the following settings for them: - - \list - \li Color reduction: Optimal 256 colors palette - - \li Reduce colors to: 256 - - \li Best compression (slow) - - \li Color quantization algorithm: NeuQuant neural-net (slow) - - \li External optimizers: OptiPNG o3 - \endlist - - Compare the initial and optimized images to check that image quality is - preserved. If the image quality deteriorates, do not use color reduction - (select the \uicontrol {True Color} option, instead). - - You can also see the sizes of the initial and optimized image. - - \section3 Using OptiPNG - - Download and install \l{https://sourceforge.net/projects/optipng/}{OptiPNG}. - - OptiPNG is a command-line tool that you can invoke from the \QC project - folder (or any folder that contains your project). To optimize a screenshot, - enter the following command (here, from the \QC project folder): - - \code - optipng -o 7 -strip all doc/images/<screenshot_name> - \endcode - - \section1 Building Documentation - - You use QDoc to build the documentation. Build the documentation from time - to time, to check its structure and the validity of the QDoc commands. - The error messages that QDoc issues are generally very useful for - troubleshooting. - - For more information about setting up the build environment if you do not - want to build the whole Qt, see - \l{https://wiki.qt.io/Building_Qt_Documentation}{Building Qt Documentation} - on the Qt wiki. - - The content and formatting of documentation are separated in QDoc. - The documentation configuration, style sheets, and templates have - changed over time, so they differ between Qt and \QC versions. Since \QC - version 3.3, only Qt 5 is supported for building documentation. The - templates to use are defined by the - \c {qt5\qtbase\doc\global\qt-html-templates-offline.qdocconf} and - \c {qt5\qtbase\doc\global\qt-html-templates-online.qdocconf} configuration - file. They are fetched from Qt sources by adding the following lines to the - qdocconf file: - - \list - \li \c {include ($QT_INSTALL_DOCS/global/qt-html-templates-offline.qdocconf)} - for help files - \li \c {include ($QT_INSTALL_DOCS/global/qt-html-templates-online.qdocconf)} - for publishing on the web - \endlist - - \note To have the correct fonts loaded for the online version, you must be - running it on a web server. - - \note If the styles look wrong to you when reading help files in \QC or \QA, - you might be looking at them in the QTextBrowser instead of the Qr WebEngine - browser. This happens if you do not have Qt WebEngine installed. - - To build documentation for the sources from the qtcreator master branch, use - build scripts defined in the doc.pri file. To build all \QC docs in the - help format and to create help files (.qch), enter the following build - commands from the project folder (after running qmake): - - \list - \li nmake docs (on Windows) - - \li make docs (on Linux and \macos) - \endlist - - The \QC Manual HTML files are generated in the \c {doc/qtcreator} directory. - The Extending \QC Manual files are generated in the - \c {doc/qtcreator-dev} directory. The help files (\c {.qch}) are generated in the - \c {share/doc/qtcreator} directory in the \QC build directory on Windows and - Linux, and in the \c {bin/Qt Creator.app/Contents/Resources/app} directory - on \macos. You can view the HTML files in a browser and the help files in - the \QC \uicontrol Help mode. For more information about adding the help - files to \QC, see - \l{http://doc.qt.io/qtcreator/creator-help.html#adding-external-documentation} - {Adding External Documentation}. - - Besides \c docs, you have the following options: - - \list - \li html_docs_qtcreator - build \QC Manual in help format, but do not - generate a help file - - \li html_docs_qtcreator-dev - build Extending \QC Manual in help - format, but do not generate a help file - - \li qch_docs_qtcreator - build \QC Manual in help format and generate - a help file (.qch) - - \li qch_docs_qtcreator-dev - build Extending \QC Manual in help format - and generate a help file (.qch) - \endlist - -*/ diff --git a/doc/api/qtcreator-ui-text.qdoc b/doc/api/qtcreator-ui-text.qdoc deleted file mode 100644 index f7fbad1809..0000000000 --- a/doc/api/qtcreator-ui-text.qdoc +++ /dev/null @@ -1,442 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the Qt Creator documentation. -** -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** -****************************************************************************/ - -/*! - \previouspage external-tool-spec.html - \page qtcreator-ui-text.html - \nextpage coding-style.html - - \title User Interface Text Guidelines - - Follow the guidelines in this section to make sure that your extensions - are consistent with the Qt Creator UI and that they can be easily - localized into different languages. - - When you write UI text, make sure that it is: - - \list - - \li Consistent with existing Qt Creator UI terms - - \li Short and concise - - \li Neutral, descriptive, and factually correct - - \li Unambigious - - \li Translatable into different languages - - \endlist - - \section1 Grammar and Style - - All UI text must be grammatically correct English and use the standard form - of written language. Do not use dialect or slang words. Use idiomatic - language, that is, expressions that are characteristic for English. - If possible, ask a native English speaker for a review. - - UI text should be concise and economically formulated. Avoid unnecessary - content words and phrases. However, it is more important that the text is - useful and easy to understand. - - Avoid addressing the user in the second person. Use a neutral tone or - passive voice but use a formal address when necessary. Avoid using the - word \e Please when addressing the user. Exceptions to this are some - copyright text and short imperative sentences that might otherwise sound - abrupt. For example, \e {Please wait.} - - Avoid abbreviations in the menu names and items. If there is no room for - the full spelling or hyphenation of a word, abbreviate the text according - to the English abbreviation rules. - - Avoid contractions. For example, write \e cannot instead of \e can't. - - \section1 Punctuation - - Avoid using punctuation marks or special characters in menu names and - items. - - Use punctuation marks as follows: - - \list - - \li Use full stops in messages. - - \li Never use full stops (.) at the end of menu item names. - - \li Place three full stops (...) at the end of menu item names that - open a dialog requiring user action. - - \li Use exclamation marks (!) only in text that demands extra attention - from the user or carries special weight. - - \li Use quotation marks ("") around variable values. For example, - \uicontrol {Close Project "qtcreator"}. - For consistency, use double quotes to emphasize or set apart file - names, directory names, URLs, and so on, in user visible strings. - - \li Do not use leading, trailing, or multiple spaces to align text in - messages, as translation tools might not handle them correctly. - - \endlist - - \section2 Writing Tooltips - - Tooltips contain useful information about icons, menu items, or other UI - elements. They appear when users place the mouse pointer over an UI - element. You can also add descriptive text to the UI that is always - visible. - - For an icon, you can use the command name as a tool tip. In that - case, use book style capitalization and do not add a period after the tool - tip. - - \image qtcreator-tooltip.png "Tooltip" - - Tooltips can also contain full sentences. Try to make them as short and - concise as possible, while still making them grammatically correct. Use - sentence style capitalization and punctuation as you would for any - sentence. - - \image qtcreator-tooltip-long.png "Sentence as a tooltip" - - \section3 Writing Tooltips in Design Mode - - In Qt Designer, use plain text for tooltips. For extra formatting, write - short, canonical HTML in the source tab of the rich text editor: - \c {<html><head/><body><b>Note:</b> text.} - - Qt Designer has a feature that simplifies the rich text (on by default), - but still, you should verify by looking at the \uicontrol Source tab. - - \section2 Writing Messages - - Check that messages are concise and economically formulated. However, it - is more important that the messages are useful and easy to understand. - - Keep the use of many new and different sentence structures to a minimum. - Reuse sentence structures that have been used in similar situations. For - example: - - \list - - \li Cannot send log as selected message type. Text is too long. - - \li Cannot receive image. - - \li Cannot insert picture. Maximum text length is 120 characters. - - \li Image name already in use. - - \li Folder name already in use. - - \endlist - - \section1 UI Text Capitalization - - Two styles are used, book title and sentence style: - - \list - - \li Example of Book Title Capitalization - - \li Example of sentence style capitalization - - \endlist - - \section2 Using Book Style Capitalization - - When using book style capitalization, capitalize all words, except - prepositions that are shorter than five letters (for example, 'with' but - 'Without'), conjunctions (for example, and, or, but), and articles (a, an, - the). - However, always capitalize the first and last word. - - Use book style capitalization for: - - \list - - \li Titles (window, dialog, group box, tab, list view columns, and so on) - - \li Functions (menu items, buttons) - - \li Selectable items (combobox items, listbox items, tree list items, and so on) - - \endlist - - \section3 Checking Book Style Capitalization - - You can use the to-title-case.js script in the \c{\doc\titlecase} - folder to check book style capitalization of UI text or headings in - documentation: - - \list 1 - - \li Open to-title-case.html in a browser. - - \li Enter the UI text in the field. - - \li Click \uicontrol Convert. - - \endlist - - The UI text with suggested book style capitalization is displayed in the - field to the right. - - \note The script is based on word lists; it does not perform grammatical - analysis. Therefore, it might get the capitalization wrong if you use a rare - meaning of a word. For example, should you mean feathers and not direction - when you write \e down. However, you should be able to trust it in most - cases in the context of writing UI text and technical documentation. - - \section2 Using Sentence Style Capitalization - - When using sentence style capitalization, capitalize only the first letter, - except proper names. - - Use sentence style capitalization for: - - \list - - \li Labels - - \li Tool tips - - \li Descriptive text - - \li Other non-heading or title text - - \endlist - - \section1 Preparing for Localization - - Qt Creator is localized into several languages. Consistency and conciseness - make UI text easier to translate. - - \section2 Marking UI Text for Translation - - Make sure the text strings presented to the user are easy to translate. - The user interface text strings are enclosed in \c tr() calls and - extracted from the source code during the translation process. Therefore, - the translator might not know the source code context of the messages. - - You can add comments that are visible in Qt Linguist ( //:) to clarify the - context. For example: - - \code - //: Contact book "Add person" button label - return tr("Add"); - \endcode - - If the class is not Q_OBJECT, use \c {QCoreApplication::translate("class - context", "message")} or consider using Q_DECLARE_TR_FUNCTIONS. Do not use - \c {QObject::tr()}, which is confusing because the messages appear grouped - by class context in Qt Linguist and messages tied to QObject do not have a - class context. - - Use \c{QDir::toNativeSeparators()} for file and directory names that you - pass to \c{tr().arg()}. - - Do not use markup that spans the whole string, because that can be confusing - for translators. For example, instead of: - - \code - tr("<html><head/><body><span>UI Text</span></body></html>") - \endcode - - use - - \code - QLatin1String("<html><head/><body><span>") + tr("UI Text") + QLatin1String("/span></body></html>") - \endcode - - \section2 Features of Languages or Writing Systems - - To allow for localization of your extensions, consider the impact that - languages and writing systems have on the implementation. - - \table - \header - \li Features of Languages or Writing Systems - - \li Impact on Implementation - \row - \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: - - \c{tr("Foo failed: %1").arg(message)} - - instead of - - \c {tr("Foo failed: ") + message} - \row - \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. - - For example, use - - \c {tr("%n files found", 0, number)} - - instead of - - \c {tr("%1 files found").arg(number)} - \row - \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. - - 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")} - \endtable - - \section1 Common Qt Creator Terms - - This section summarizes the terminology used for common Qt Creator UI - components. It also describes the conventions for naming different types of - UI components. - - Always check that the term you plan to use is not used to mean something - else in the UI. If a suitable term already exists, use it. For example, use - \e Find for searching and \e New for wizards that create new objects. - - For more information on how to add UI components, see - \l{Common Extension Tasks}. - - \table - \header - \li UI Text - - \li Usage - - \li Conventions - - \row - \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 - \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 \uicontrol Add - button in the \uicontrol Documentation options opens the - \uicontrol {Add Documentation} dialog. - \row - \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 - \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 - \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 - \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 - \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 - \uicontrol {Mode selector}. - \row - \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 - \li Sidebar - \li A view available in the \uicontrol Edit and \uicontrol 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 - \li View - \li An area of the screen that displays information for users and - provides them with functions for managing the information. - Available in \uicontrol 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 - -*/ |
