Commit 505256fa authored by Friedemann Kleint's avatar Friedemann Kleint

API-Documentation: Add the Utils-library.

Fix API after doc template change.
parent b37cd332
......@@ -37,8 +37,6 @@ equals(QMAKE_DIR_SEP, /) { # unix, mingw+msys
HELP_FILES = $$PWD/qtcreator-api.qdocconf
HELP_DEP_FILES = $$PWD/qtcreator-api.qdoc \
$$PWD/coding-style.qdoc \
$$PWD/../qt-defines.qdocconf \
$$PWD/../qt-html-templates.qdocconf \
$$PWD/qtcreator-api.qdocconf
docs.name = CREATE API DOC
......
......@@ -60,6 +60,10 @@
\o Implements the plugin loader framework. Provides a base class for plugins and
basic mechanisms for plugin interaction like an object pool.
\row
\o \l{Utils}
\o General utility library.
\endtable
\section2 Additional libraries
......
......@@ -9,6 +9,7 @@ headerdirs = . \
../../src/libs/aggregation \
../../src/libs/cplusplus \
../../src/libs/extensionsystem \
../../src/libs/utils \
../../src/libs/qtcreatorcdbext \
../../src/plugins/coreplugin \
../../src/plugins/find \
......@@ -19,6 +20,7 @@ sourcedirs = . \
../../src/libs/aggregation \
../../src/libs/cplusplus \
../../src/libs/extensionsystem \
../../src/libs/utils \
../../src/libs/qtcreatorcdbext \
../../src/plugins/coreplugin \
../../src/plugins/find \
......
......@@ -37,6 +37,27 @@
enum { debug = 0 };
/*!
\namespace Utils
General utility library namespace
*/
/*! \class Utils::BaseValidatingLineEdit
\brief Base class for line edits that perform validation.
Performs validation in a virtual validate() function to be implemented in
derived classes.
When invalid, the text color will turn red and a tooltip will
contain the error message. This approach is less intrusive than a
QValidator which will prevent the user from entering certain characters.
The widget has a concept of an "initialText" which can be something like
"<Enter name here>". This results in state 'DisplayingInitialText', which
is not valid, but is not marked red.
*/
namespace Utils {
struct BaseValidatingLineEditPrivate {
......
......@@ -42,17 +42,6 @@ namespace Utils {
struct BaseValidatingLineEditPrivate;
/**
* Base class for validating line edits that performs validation in a virtual
* validate() function to be implemented in derived classes.
* When invalid, the text color will turn red and a tooltip will
* contain the error message. This approach is less intrusive than a
* QValidator which will prevent the user from entering certain characters.
*
* The widget has a concept of an "initialText" which can be something like
* "<Enter name here>". This results in state 'DisplayingInitialText', which
* is not valid, but is not marked red.
*/
class QTCREATOR_UTILS_EXPORT BaseValidatingLineEdit : public QLineEdit
{
Q_OBJECT
......
......@@ -37,6 +37,16 @@
#include <QtGui/QPushButton>
#include <QtCore/QDebug>
/*!
\class Utils::CheckableMessageBox
\brief A messagebox suitable for questions with a
"Do not ask me again" checkbox.
Emulates the QMessageBox API with
static conveniences. The message label can open external URLs.
*/
namespace Utils {
struct CheckableMessageBoxPrivate {
......
......@@ -44,10 +44,6 @@ namespace Utils {
struct CheckableMessageBoxPrivate;
/* A messagebox suitable for questions with a
* "Do not ask me again" checkbox. Emulates the QMessageBox API with
* static conveniences. The message label can open external URLs. */
class QTCREATOR_UTILS_EXPORT CheckableMessageBox : public QDialog
{
Q_OBJECT
......
......@@ -38,6 +38,13 @@
#include <QtCore/QDebug>
#include <QtCore/QRegExp>
/*!
\class Utils::ClassNameValidatingLineEdit
\brief A Line edit that validates a C++ class name and emits a signal
to derive suggested file names from it.
*/
namespace Utils {
struct ClassNameValidatingLineEditPrivate {
......
......@@ -41,9 +41,6 @@ namespace Utils {
struct ClassNameValidatingLineEditPrivate;
/* A Line edit that validates a C++ class name and emits a signal
* to derive suggested file names from it. */
class QTCREATOR_UTILS_EXPORT ClassNameValidatingLineEdit
: public Utils::BaseValidatingLineEdit
{
......
......@@ -44,19 +44,27 @@
#include <QtGui/QScrollArea>
#include <QtGui/QApplication>
/*!
\class Utils::DetailsWidget
\brief Widget a button to expand a 'Details' area.
This widget is using a grid layout and places the items
in the following way:
\code
+------------+-------------------------+---------------+
+summaryLabel| toolwidget | detailsButton |
+------------+-------------------------+---------------+
| widget |
+------------+-------------------------+---------------+
\endcode
*/
namespace Utils {
static const int MARGIN=8;
// This widget is using a grid layout and places the items
// in the following way:
//
// +------------+-------------------------+---------------+
// +summaryLabel| toolwidget | detailsButton |
// +------------+-------------------------+---------------+
// | widget |
// +------------+-------------------------+---------------+
struct DetailsWidgetPrivate {
DetailsWidgetPrivate(QWidget *parent);
......
......@@ -36,6 +36,14 @@
#include <QtGui/QStyleOption>
#include <QtGui/QStylePainter>
/*!
\class Utils::FakeToolTip
\brief A widget that pretends to be a tooltip.
By default it has Qt::WA_DeleteOnClose set.
*/
namespace Utils {
FakeToolTip::FakeToolTip(QWidget *parent) :
......
......@@ -40,10 +40,6 @@
namespace Utils {
/**
* A widget that pretends to be a tooltip. By default it has
* Qt::WA_DeleteOnClose set.
*/
class QTCREATOR_UTILS_EXPORT FakeToolTip : public QWidget
{
Q_OBJECT
......
......@@ -46,6 +46,19 @@
#include <QtGui/QStyle>
#include <QtGui/QPaintEvent>
/*!
\class Utils::FancyLineEdit
\brief A line edit with an embedded pixmap on one side that is connected to
a menu.
Additionally, it can display a grayed hintText (like "Type Here to")
when not focused and empty. When connecting to the changed signals and
querying text, one has to be aware that the text is set to that hint
text if isShowingHintText() returns true (that is, does not contain
valid user input).
*/
enum { margin = 6 };
#define ICONBUTTON_HEIGHT 18
......
......@@ -66,14 +66,6 @@ private:
QPixmap m_pixmap;
};
/* A line edit with an embedded pixmap on one side that is connected to
* a menu. Additionally, it can display a grayed hintText (like "Type Here to")
* when not focused and empty. When connecting to the changed signals and
* querying text, one has to be aware that the text is set to that hint
* text if isShowingHintText() returns true (that is, does not contain
* valid user input).
*/
class QTCREATOR_UTILS_EXPORT FancyLineEdit : public QLineEdit
{
Q_DISABLE_COPY(FancyLineEdit)
......
......@@ -49,6 +49,15 @@ static const char dockWidgetActiveState[] = "DockWidgetActiveState";
namespace Utils {
/*! \class Utils::FancyMainWindow
\brief MainWindow with dock widgets and additional "lock" functionality
(locking the dock widgets in place) and "reset layout" functionality.
The dock actions and the additional actions should be accessible
in a Window-menu.
*/
struct FancyMainWindowPrivate
{
FancyMainWindowPrivate();
......
......@@ -46,10 +46,6 @@ namespace Utils {
struct FancyMainWindowPrivate;
// MainWindow with dock widgets and additional "lock" functionality
// (locking the dock widgets in place) and "reset layout" functionality.
// The dock actions and the additional actions should be accessible
// in a Window-menu.
class QTCREATOR_UTILS_EXPORT FancyMainWindow : public QMainWindow
{
Q_OBJECT
......
......@@ -38,21 +38,24 @@
namespace Utils {
/**
\class FileInProjectFinder
/*!
\class Utils::FileInProjectFinder
Helper class to find the 'original' file in the project directory for a given file path.
\brief Helper class to find the 'original' file in the project directory for a given file path.
Often files are copied in the build + deploy process. findFile() searches for an existing file
in the project directory for a given file path:
E.g. following file paths:
C:/app-build-desktop/qml/app/main.qml (shadow build directory)
C:/Private/e3026d63/qml/app/main.qml (Application data folder on Symbian device)
/Users/x/app-build-desktop/App.app/Contents/Resources/qml/App/main.qml (folder on Mac OS X)
should all be mapped to
$PROJECTDIR/qml/app/main.qml
*/
\list
\i C:/app-build-desktop/qml/app/main.qml (shadow build directory)
\i C:/Private/e3026d63/qml/app/main.qml (Application data folder on Symbian device)
\i /Users/x/app-build-desktop/App.app/Contents/Resources/qml/App/main.qml (folder on Mac OS X)
\endlist
should all be mapped to $PROJECTDIR/qml/app/main.qml
*/
FileInProjectFinder::FileInProjectFinder()
{
}
......
......@@ -37,6 +37,13 @@
#include <QtCore/QRegExp>
#include <QtCore/QDebug>
/*!
\class Utils::FileNameValidatingLineEdit
\brief A control that let's the user choose a (base) file name, based on a QLineEdit. Has
some validation logic for embedding into QWizardPage.
*/
namespace Utils {
#define WINDOWS_DEVICES "CON|AUX|PRN|COM1|COM2|LPT1|LPT2|NUL"
......
......@@ -38,10 +38,6 @@
namespace Utils {
/**
* A control that let's the user choose a file name, based on a QLineEdit. Has
* some validation logic for embedding into QWizardPage.
*/
class QTCREATOR_UTILS_EXPORT FileNameValidatingLineEdit : public BaseValidatingLineEdit
{
Q_OBJECT
......
......@@ -36,6 +36,13 @@
#include <QtGui/QAbstractButton>
/*!
\class Utils::FileWizardDialog
\brief Standard wizard for a single file letting the user choose name
and path. Custom pages can be added via Core::IWizardExtension.
*/
namespace Utils {
FileWizardDialog::FileWizardDialog(QWidget *parent) :
......
......@@ -41,11 +41,6 @@ namespace Utils {
class FileWizardPage;
/*
Standard wizard for a single file letting the user choose name
and path. Custom pages can be added via Core::IWizardExtension.
*/
class QTCREATOR_UTILS_EXPORT FileWizardDialog : public Wizard {
Q_OBJECT
Q_DISABLE_COPY(FileWizardDialog)
......
......@@ -34,6 +34,16 @@
#include "filewizardpage.h"
#include "ui_filewizardpage.h"
/*!
\class Utils::FileWizardPage
\brief Standard wizard page for a single file letting the user choose name
and path.
The name and path labels can be changed. By default they are simply "Name:"
and "Path:".
*/
namespace Utils {
struct FileWizardPagePrivate
......
......@@ -42,13 +42,6 @@ namespace Utils {
struct FileWizardPagePrivate;
/**
* Standard wizard page for a single file letting the user choose name
* and path. Sets the "FileNames" QWizard field.
*
* The name and path labels can be changed. By default they are simply "Name:"
* and "Path:".
*/
class QTCREATOR_UTILS_EXPORT FileWizardPage : public QWizardPage
{
Q_OBJECT
......
......@@ -33,15 +33,21 @@
#include "filterlineedit.h"
/*!
\class Utils::FilterLineEdit
\brief A fancy line edit customized for filtering purposes with a clear button.
*/
namespace Utils {
FilterLineEdit::FilterLineEdit(QWidget *parent) :
FancyLineEdit(parent),
m_lastFilterText(text())
{
// KDE has custom icons for this. Notice that icon namings are counter intuitive
// If these icons are not avaiable we use the freedesktop standard name before
// falling back to a bundled resource
// KDE has custom icons for this. Notice that icon namings are counter intuitive.
// If these icons are not available we use the freedesktop standard name before
// falling back to a bundled resource.
QIcon icon = QIcon::fromTheme(layoutDirection() == Qt::LeftToRight ?
QLatin1String("edit-clear-locationbar-rtl") :
QLatin1String("edit-clear-locationbar-ltr"),
......
......@@ -38,8 +38,6 @@
namespace Utils {
/* A fancy line edit customized for filtering purposes with a clear button. */
class QTCREATOR_UTILS_EXPORT FilterLineEdit : public FancyLineEdit
{
Q_OBJECT
......
......@@ -35,6 +35,14 @@
#include <QtGui/QRegExpValidator>
/*!
\class Utils::IpAddressLineEdit
\brief A QLineEdit widget that validates the IP address inserted.
The valid address example is 192.168.1.12 or 192.168.1.12:8080.
*/
namespace Utils {
// ------------------ IpAddressLineEditPrivate
......
......@@ -42,11 +42,6 @@ namespace Utils {
class IpAddressLineEditPrivate;
/**
* A LineEdit widget that validates the IP address inserted.
* The valid address example is 192.168.1.12 or 192.168.1.12:8080
*/
class QTCREATOR_UTILS_EXPORT IpAddressLineEdit : public QLineEdit
{
Q_OBJECT
......
......@@ -33,6 +33,13 @@
#include "linecolumnlabel.h"
/*!
\class Utils::LineColumnLabel
\brief A label suitable for displaying cursor positions, etc. with a fixed
width derived from a sample text.
*/
namespace Utils {
LineColumnLabel::LineColumnLabel(QWidget *parent)
......
......@@ -39,9 +39,6 @@
namespace Utils {
/* A label suitable for displaying cursor positions, etc. with a fixed
* with derived from a sample text. */
class QTCREATOR_UTILS_EXPORT LineColumnLabel : public QLabel
{
Q_DISABLE_COPY(LineColumnLabel)
......
......@@ -40,6 +40,15 @@
#include <QtGui/QKeyEvent>
#endif
/*!
\class Utils::NavigationTreeView
\brief General TreeView for any Side Bar widget.
Common initialization etc, e.g. Mac specific behaviour.
\sa Core::NavigationView, Core::INavigationWidgetFactory
*/
namespace Utils {
NavigationTreeView::NavigationTreeView(QWidget *parent)
......
......@@ -40,18 +40,11 @@
namespace Utils {
/*!
\class NavigationTreeView
\sa Core::NavigationView, Core::INavigationWidgetFactory
General TreeView for any Side Bar widget. Common initialization etc, e.g. Mac specific behaviour.
*/
class QTCREATOR_UTILS_EXPORT NavigationTreeView : public QTreeView
{
Q_OBJECT
public:
NavigationTreeView(QWidget *parent = 0);
explicit NavigationTreeView(QWidget *parent = 0);
protected:
void focusInEvent(QFocusEvent *event);
......
......@@ -45,6 +45,15 @@
enum { debugNewClassWidget = 0 };
/*! \class Utils::NewClassWidget
\brief Utility widget for 'New Class' wizards
Utility widget for 'New Class' wizards. Prompts the user
to enter a class name (optionally derived from some base class) and file
names for header, source and form files. Has some smart logic to derive
the file names from the class name. */
namespace Utils {
struct NewClassWidgetPrivate {
......
......@@ -46,12 +46,6 @@ namespace Utils {
struct NewClassWidgetPrivate;
/**
* NewClassWidget: Utility widget for 'New Class' wizards. Prompts the user
* to enter a class name (optionally derived from some base class) and file
* names for header, source and form files. Has some smart logic to derive
* the file names from the class name.
*/
class QTCREATOR_UTILS_EXPORT NewClassWidget : public QWidget
{
Q_DISABLE_COPY(NewClassWidget)
......
......@@ -33,6 +33,24 @@
#include "parameteraction.h"
/*!
\class Utils::ParameterAction
\brief Intended for actions that act on a 'current',
string-type parameter (typically a file name), for example 'Save file %1'.
The action has 2 states:
\list
\o <no current parameter> displaying "Do XX" (empty text)
\o <parameter present> displaying "Do XX with %1".
\endlist
Provides a slot to set the parameter, changing display
and enabled state accordingly.
The text passed in should already be translated; parameterText
should contain a %1 where the parameter is to be inserted.
*/
namespace Utils {
ParameterAction::ParameterAction(const QString &emptyText,
......
......@@ -40,15 +40,6 @@
namespace Utils {
/* ParameterAction: Intended for actions that act on a 'current',
* string-type parameter (typically file name) and have 2 states:
* 1) <no current parameter> displaying "Do XX" (empty text)
* 2) <parameter present> displaying "Do XX with %1".
* Provides a slot to set the parameter, changing display
* and enabled state accordingly.
* The text passed in should already be translated; parameterText
* should contain a %1 where the parameter is to be inserted. */
class QTCREATOR_UTILS_EXPORT ParameterAction : public QAction
{
Q_ENUMS(EnablingMode)
......
......@@ -52,6 +52,15 @@
#include <QtGui/QLineEdit>
#include <QtGui/QPushButton>
/*!
\class Utils::PathChooser
\brief A control that let's the user choose a path, consisting of a QLineEdit and
a "Browse" button.
Has some validation logic for embedding into QWizardPage.
*/
/*static*/ const char * const Utils::PathChooser::browseButtonLabel =
#ifdef Q_WS_MAC
QT_TRANSLATE_NOOP("Utils::PathChooser", "Choose...");
......
......@@ -49,10 +49,6 @@ namespace Utils {
class Environment;
class PathChooserPrivate;
/**
* A control that let's the user choose a path, consisting of a QLineEdit and
* a "Browse" button. Has some validation logic for embedding into QWizardPage.
*/
class QTCREATOR_UTILS_EXPORT PathChooser : public QWidget
{
Q_DISABLE_COPY(PathChooser)
......
......@@ -50,6 +50,24 @@
#include <QtCore/QDir>
#include <QtCore/QDebug>
/*!
\class Utils::PathListEditor
\brief A control that let's the user edit a list of (directory) paths
using the platform separator (';',':').
Typically used for
path lists controlled by environment variables, such as
PATH. It is based on a QPlainTextEdit as it should
allow for convenient editing and non-directory type elements like
\code
"etc/mydir1:$SPECIAL_SYNTAX:/etc/mydir2".
\endcode
When pasting text into it, the platform separator will be replaced
by new line characters for convenience.
*/
namespace Utils {
// ------------ PathListPlainTextEdit:
......
......@@ -47,17 +47,6 @@ namespace Utils {
struct PathListEditorPrivate;
/**
* A control that let's the user edit a list of (directory) paths
* using the platform separator (';',':'). Typically used for
* path lists controlled by environment variables, such as
* PATH. It is based on a QPlainTextEdit as it should
* allow for convenient editing and non-directory type elements like
* "etc/mydir1:$SPECIAL_SYNTAX:/etc/mydir2".
* When pasting text into it, the platform separator will be replaced
* by new line characters for convenience.
*/
class QTCREATOR_UTILS_EXPORT PathListEditor : public QWidget
{
Q_DISABLE_COPY(PathListEditor)
......
......@@ -39,6 +39,28 @@
#include <QtCore/QDir>
#include <QtCore/QFileInfo>
/*!
\class Utils::ProjectIntroPage
\brief Standard wizard page for a project, letting the user choose name
and path.
Looks similar to FileWizardPage, but provides additional
functionality:
\list
\o Description label at the top for displaying introductory text
\o It does on the fly validation (connected to changed()) and displays
warnings/errors in a status label at the bottom (the page is complete
when fully validated, validatePage() is thus not implemented).
\endlist
Note: Careful when changing projectintropage.ui. It must have main
geometry cleared and QLayout::SetMinimumSize constraint on the main