feedc0de/qt-creator
1
0
Fork 0
forked from qt-creator/qt-creator
Code Pull Requests Activity

API-Documentation: Add the Utils-library.

Browse Source 
Fix API after doc template change.
This commit is contained in:
Friedemann Kleint
2011-03-02 17:13:33 +01:00
parent b37cd3325c
commit 505256fab9
63 changed files with 458 additions and 301 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/api/api.pro
View File

@@ -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

4
doc/api/qtcreator-api.qdoc
View File

@@ -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

2
doc/api/qtcreator-api.qdocconf
View File

@@ -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 \

21
src/libs/utils/basevalidatinglineedit.cpp
View File

@@ -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 {

11
src/libs/utils/basevalidatinglineedit.h
View File

@@ -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

10
src/libs/utils/checkablemessagebox.cpp
View File

@@ -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 {

4
src/libs/utils/checkablemessagebox.h
View File

@@ -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

7
src/libs/utils/classnamevalidatinglineedit.cpp
View File

@@ -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 {

3
src/libs/utils/classnamevalidatinglineedit.h
View File

@@ -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
{

26
src/libs/utils/detailswidget.cpp
View File

@@ -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);

8
src/libs/utils/faketooltip.cpp
View File

@@ -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) :

4
src/libs/utils/faketooltip.h
View File

@@ -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

13
src/libs/utils/fancylineedit.cpp
View File

@@ -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

8
src/libs/utils/fancylineedit.h
View File

@@ -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)

9
src/libs/utils/fancymainwindow.cpp
View File

@@ -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();

4
src/libs/utils/fancymainwindow.h
View File

@@ -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

21
src/libs/utils/fileinprojectfinder.cpp
View File

@@ -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()
{
}

7
src/libs/utils/filenamevalidatinglineedit.cpp
View File

@@ -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"

4
src/libs/utils/filenamevalidatinglineedit.h
View File

@@ -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

7
src/libs/utils/filewizarddialog.cpp
View File

@@ -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) :

5
src/libs/utils/filewizarddialog.h
View File

@@ -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)

10
src/libs/utils/filewizardpage.cpp
View File

@@ -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

7
src/libs/utils/filewizardpage.h
View File

@@ -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

12
src/libs/utils/filterlineedit.cpp
View File

@@ -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"),

2
src/libs/utils/filterlineedit.h
View File

@@ -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

8
src/libs/utils/ipaddresslineedit.cpp
View File

@@ -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

5
src/libs/utils/ipaddresslineedit.h
View File

@@ -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

7
src/libs/utils/linecolumnlabel.cpp
View File

@@ -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)

3
src/libs/utils/linecolumnlabel.h
View File

@@ -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)

9
src/libs/utils/navigationtreeview.cpp
View File

@@ -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)

9
src/libs/utils/navigationtreeview.h
View File

@@ -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);

9
src/libs/utils/newclasswidget.cpp
View File

@@ -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 {

6
src/libs/utils/newclasswidget.h
View File

@@ -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)

18
src/libs/utils/parameteraction.cpp
View File

@@ -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,

9
src/libs/utils/parameteraction.h
View File

@@ -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)

9
src/libs/utils/pathchooser.cpp
View File

@@ -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...");

4
src/libs/utils/pathchooser.h
View File

@@ -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)

18
src/libs/utils/pathlisteditor.cpp
View File

@@ -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:

11
src/libs/utils/pathlisteditor.h
View File

@@ -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)

22
src/libs/utils/projectintropage.cpp
View File

@@ -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
layout, otherwise, QWizard will squeeze it due to its strange expanding
hacks.
*/
namespace Utils {
struct ProjectIntroPagePrivate

13
src/libs/utils/projectintropage.h
View File

@@ -42,19 +42,6 @@ namespace Utils {
struct ProjectIntroPagePrivate;
/* Standard wizard page for a single file letting the user choose name
* and path. Looks similar to FileWizardPage, but provides additional
* functionality:
* - Description label at the top for displaying introductory text
* - 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).
*
* Note: Careful when changing projectintropage.ui. It must have main
* geometry cleared and QLayout::SetMinimumSize constraint on the main
* layout, otherwise, QWizard will squeeze it due to its strange expanding
* hacks. */
class QTCREATOR_UTILS_EXPORT ProjectIntroPage : public QWizardPage
{
Q_OBJECT

126
src/libs/utils/qtcprocess.cpp
View File

@@ -42,68 +42,11 @@
using namespace Utils;
/**
* \fn QStringList QtcProcess::splitArgs(
* const QString &args, bool abortOnMeta, SplitError *err, const Environment *env)
*
* Splits \a args according to system shell word splitting and quoting rules.
*
* \section Unix
*
* The behavior is based on the POSIX shell and bash:
* \list
* \li Whitespace splits tokens
* \li The backslash quotes the following character
* \li A string enclosed in single quotes is not split. No shell meta
* characters are interpreted.
* \li A string enclosed in double quotes is not split. Within the string,
* the backslash quotes shell meta characters - if it is followed
* by a "meaningless" character, the backslash is output verbatim.
* \list
* If \a abortOnMeta is \c false, only the splitting and quoting rules apply,
* while other meta characters (substitutions, redirections, etc.) are ignored.
* If \a abortOnMeta is \c true, encounters of unhandled meta characters are
* treated as errors.
*
* \section Windows
*
* The behavior is defined by the Microsoft C runtime:
* \list
* \li Whitespace splits tokens
* \li A string enclosed in double quotes is not split
* \list
* \li 3N double quotes within a quoted string yield N literal quotes.
* This is not documented on MSDN.
* \endlist
* \li Backslashes have special semantics iff they are followed by a double
* quote:
* \list
* \li 2N backslashes + double quote => N backslashes and begin/end quoting
* \li 2N+1 backslashes + double quote => N backslashes + literal quote
* \endlist
* \endlist
* Qt and many other implementations comply with this standard, but many do not.
*
* If \a abortOnMeta is \c true, cmd shell semantics are applied before
* proceeding with word splitting:
* \list
* \li Cmd ignores \em all special chars between double quotes.
* Note that the quotes are \em not removed at this stage - the
* tokenization rules described above still apply.
* \li The \c circumflex is the escape char for everything including itself.
* \endlist
* As the quoting levels are independent from each other and have different
* semantics, you need a command line like \c{"foo "\^"" bar"} to get
* \c{foo " bar}.
*
* \param cmd the command to split
* \param abortOnMeta see above
* \param err if not NULL, a status code will be stored at the pointer
* target, see \ref SplitError
* \param env if not NULL, perform variable substitution with the
* given environment.
* \return a list of unquoted words or an empty list if an error occurred
*/
/*!
\class Utils::QtcProcess
\brief This class provides functionality for dealing with shell-quoted process arguments.
*/
#ifdef Q_OS_WIN
@@ -255,6 +198,65 @@ static QStringList doSplitArgs(const QString &args, QtcProcess::SplitError *err)
//not reached
}
/*!
Splits \a args according to system shell word splitting and quoting rules.
\section1 Unix
The behavior is based on the POSIX shell and bash:
\list
\i Whitespace splits tokens
\i The backslash quotes the following character
\i A string enclosed in single quotes is not split. No shell meta
characters are interpreted.
\i A string enclosed in double quotes is not split. Within the string,
the backslash quotes shell meta characters - if it is followed
by a "meaningless" character, the backslash is output verbatim.
\endlist
If \a abortOnMeta is \c false, only the splitting and quoting rules apply,
while other meta characters (substitutions, redirections, etc.) are ignored.
If \a abortOnMeta is \c true, encounters of unhandled meta characters are
treated as errors.
\section1 Windows
The behavior is defined by the Microsoft C runtime:
\list
\i Whitespace splits tokens
\i A string enclosed in double quotes is not split
\list
\i 3N double quotes within a quoted string yield N literal quotes.
This is not documented on MSDN.
\endlist
\i Backslashes have special semantics iff they are followed by a double quote:
\list
\i 2N backslashes + double quote => N backslashes and begin/end quoting
\i 2N+1 backslashes + double quote => N backslashes + literal quote
\endlist
\endlist
Qt and many other implementations comply with this standard, but many do not.
If \a abortOnMeta is \c true, cmd shell semantics are applied before
proceeding with word splitting:
\list
\i Cmd ignores \em all special chars between double quotes.
Note that the quotes are \em not removed at this stage - the
tokenization rules described above still apply.
\i The \c circumflex is the escape char for everything including itself.
\endlist
As the quoting levels are independent from each other and have different
semantics, you need a command line like \c{"foo "\^"" bar"} to get
\c{foo " bar}.
\param cmd the command to split
\param abortOnMeta see above
\param err if not NULL, a status code will be stored at the pointer
target, see \ref SplitError
\param env if not NULL, perform variable substitution with the
given environment.
\return a list of unquoted words or an empty list if an error occurred
*/
QStringList QtcProcess::splitArgs(const QString &_args, bool abortOnMeta, SplitError *err,
const Environment *env, const QString *pwd)
{

3
src/libs/utils/qtcprocess.h
View File

@@ -43,9 +43,6 @@
namespace Utils {
class AbstractMacroExpander;
/*!
This class provides functionality for dealing with shell-quoted process arguments.
*/
class QTCREATOR_UTILS_EXPORT QtcProcess : public QProcess
{
Q_OBJECT

6
src/libs/utils/savedaction.cpp
View File

@@ -48,10 +48,8 @@
#include <QtGui/QSpinBox>
#include <QtGui/QGroupBox>
using namespace Utils;
//////////////////////////////////////////////////////////////////////////
//
// SavedAction
@@ -63,9 +61,6 @@ using namespace Utils;
\brief The SavedAction class is a helper class for actions with persistent
state.
\ingroup utils
*/
SavedAction::SavedAction(QObject *parent)
@@ -426,7 +421,6 @@ void SavedAction::trigger(const QVariant &data)
QAction::trigger();
}
//////////////////////////////////////////////////////////////////////////
//
// SavedActionSet

26
src/libs/utils/ssh/sftpchannel.cpp
View File

@@ -41,8 +41,32 @@
#include <QtCore/QDir>
#include <QtCore/QFile>
namespace Utils {
/*!
\class Utils::SftpChannel
\brief This class provides SFTP operations.
Objects are created via SshConnection::createSftpChannel().
The channel needs to be initialized with
a call to initialize() and is closed via closeChannel(). After closing
a channel, no more operations are possible. It cannot be re-opened
using initialize(); use SshConnection::createSftpChannel() if you need
a new one.
After the initialized() signal has been emitted, operations can be started.
All SFTP operations are asynchronous (non-blocking) and can be in-flight
simultaneously (though callers must ensure that concurrently running jobs
are independent of each other, e.g. they must not write to the same file).
Operations are identified by their job id, which is returned by
the respective member function. If the function can right away detect that
the operation cannot succeed, it returns SftpInvalidJob. If an error occurs
later, the finished() signal is emitted for the respective job with a
non-empty error string.
Note that directory names must not have a trailing slash.
*/
namespace Utils {
namespace Internal {
namespace {
const quint32 ProtocolVersion = 3;

19
src/libs/utils/ssh/sftpchannel.h
View File

@@ -52,25 +52,6 @@ class SshChannelManager;
class SshSendFacility;
} // namespace Internal
/*
* This class provides SFTP operations.
* Objects are created via SshConnection::createSftpChannel().
* The channel needs to be initialized with
* a call to initialize() and is closed via closeChannel(). After closing
* a channel, no more operations are possible. It cannot be re-opened
* using initialize(); use SshConnection::createSftpChannel() if you need
* a new one.
* After the initialized() signal has been emitted, operations can be started.
* All SFTP operations are asynchronous (non-blocking) and can be in-flight
* simultaneously (though callers must ensure that concurrently running jobs
* are independent of each other, e.g. they must not write to the same file).
* Operations are identified by their job id, which is returned by
* the respective member function. If the function can right away detect that
* the operation cannot succeed, it returns SftpInvalidJob. If an error occurs
* later, the finished() signal is emitted for the respective job with a
* non-empty error string.
* Note that directory names must not have a trailing slash.
*/
class QTCREATOR_UTILS_EXPORT SftpChannel : public QObject
{
Q_OBJECT

9
src/libs/utils/ssh/sshconnection.cpp
View File

@@ -51,6 +51,15 @@
#include <QtNetwork/QNetworkProxy>
#include <QtNetwork/QTcpSocket>
/*!
\class Utils::SshConnection
\brief This class provides an SSH connection, implementing protocol version 2.0
It can spawn channels for remote execution and SFTP operations (version 3).
It operates asynchronously (non-blocking) and is not thread-safe.
*/
namespace Utils {
namespace {

5
src/libs/utils/ssh/sshconnection.h
View File

@@ -70,11 +70,6 @@ struct QTCREATOR_UTILS_EXPORT SshConnectionParameters
QTCREATOR_UTILS_EXPORT bool operator==(const SshConnectionParameters &p1, const SshConnectionParameters &p2);
QTCREATOR_UTILS_EXPORT bool operator!=(const SshConnectionParameters &p1, const SshConnectionParameters &p2);
/*
* This class provides an SSH connection, implementing protocol version 2.0
* It can spawn channels for remote execution and SFTP operations (version 3).
* It operates asynchronously (non-blocking) and is not thread-safe.
*/
class QTCREATOR_UTILS_EXPORT SshConnection : public QObject
{
Q_OBJECT

20
src/libs/utils/ssh/sshremoteprocess.cpp
View File

@@ -41,6 +41,26 @@
#include <QtCore/QTimer>
/*!
\class SshRemoteProcess
\brief This class implements an SSH channel for running a remote process.
Objects are created via SshConnection::createRemoteProcess.
The process is started via the start() member function.
A closeChannel() function is provided, but rarely useful, because
\list
\i a) when the process ends, the channel is closed automatically, and
\i b) closing a channel will not necessarily kill the remote process.
\endlist
Therefore, the only sensible use case for calling closeChannel() is to
get rid of an SshRemoteProces object before the process is actually started.
Note that the process does not have a terminal, so you can't use it
for applications that require one.
*/
namespace Utils {
const QByteArray SshRemoteProcess::AbrtSignal("ABRT");

13
src/libs/utils/ssh/sshremoteprocess.h
View File

@@ -50,19 +50,6 @@ class SshRemoteProcessPrivate;
class SshSendFacility;
} // namespace Internal
/*
* This class implements an SSH channel for running a remote process.
* Objects are created via SshConnection::createRemoteProcess.
* The process is started via the start() member function.
* A closeChannel() function is provided, but rarely useful, because
* a) when the process ends, the channel is closed automatically, and
* b) closing a channel will not necessarily kill the remote process.
* Therefore, the only sensible use case for calling closeChannel() is to
* get rid of an SshRemoteProces object before the process is actually started.
* Note that the process does not have a terminal, so you can't use it
* for applications that require one.
*/
class QTCREATOR_UTILS_EXPORT SshRemoteProcess : public QObject
{
Q_OBJECT

6
src/libs/utils/ssh/sshremoteprocessrunner.cpp
View File

@@ -35,6 +35,12 @@
#define ASSERT_STATE(states) assertState(states, Q_FUNC_INFO)
/*!
\class Utils::SshRemoteProcessRunner
\brief Convenience class for running a remote process over an SSH connection.
*/
namespace Utils {
class SshRemoteProcessRunnerPrivate : public QObject

1
src/libs/utils/ssh/sshremoteprocessrunner.h
View File

@@ -40,7 +40,6 @@
namespace Utils {
class SshRemoteProcessRunnerPrivate;
// Convenience class for running a remote process over an SSH connection.
class QTCREATOR_UTILS_EXPORT SshRemoteProcessRunner : public QObject
{
Q_OBJECT

23
src/libs/utils/submiteditorwidget.cpp
View File

@@ -51,6 +51,29 @@ enum { defaultLineWidth = 72 };
enum { checkableColumn = 0 };
/*!
\class Utils::SubmitEditorWidget
\brief Presents a VCS commit message in a text editor and a
checkable list of modified files in a list window.
The user can delete files from the list by unchecking them or diff the selection
by doubleclicking. A list model which contains the file in a column
specified by fileNameColumn should be set using setFileModel().
Additionally, standard creator actions can be registered:
Undo/redo will be set up to work with the description editor.
Submit will be set up to be enabled according to checkstate.
Diff will be set up to trigger diffSelected().
Note that the actions are connected by signals; in the rare event that there
are several instances of the SubmitEditorWidget belonging to the same
context active, the actions must be registered/unregistered in the editor
change event.
Care should be taken to ensure the widget is deleted properly when the
editor closes.
*/
namespace Utils {
// QActionPushButton: A push button tied to an action

18
src/libs/utils/submiteditorwidget.h
View File

@@ -53,24 +53,6 @@ namespace Utils {
class SubmitFieldWidget;
struct SubmitEditorWidgetPrivate;
/* The submit editor presents the commit message in a text editor and an
* checkable list of modified files in a list window. The user can delete
* files from the list by unchecking them or diff the selection
* by doubleclicking. A list model which contains the file in a column
* specified by fileNameColumn should be set using setFileModel().
*
* Additionally, standard creator actions can be registered:
* Undo/redo will be set up to work with the description editor.
* Submit will be set up to be enabled according to checkstate.
* Diff will be set up to trigger diffSelected().
*
* Note that the actions are connected by signals; in the rare event that there
* are several instances of the SubmitEditorWidget belonging to the same
* context active, the actions must be registered/unregistered in the editor
* change event.
* Care should be taken to ensure the widget is deleted properly when the
* editor closes. */
class QTCREATOR_UTILS_EXPORT SubmitEditorWidget : public QWidget
{
Q_OBJECT

12
src/libs/utils/submitfieldwidget.cpp
View File

@@ -55,6 +55,18 @@ static void inline setComboBlocked(QComboBox *cb, int index)
cb->blockSignals(blocked);
}
/*!
\class Utils::SubmitFieldWidget
\brief A widget for editing submit message fields like "reviewed-by:",
"signed-off-by:".
It displays them in a vertical row of combo/line edit fields
that is modeled after the target address controls of mail clients.
When choosing a different field in the combo, a new row is opened if text
has been entered for the current field. Optionally, a "Browse..." button and
completer can be added.
*/
namespace Utils {
// Field/Row entry

6
src/libs/utils/submitfieldwidget.h
View File

@@ -46,12 +46,6 @@ namespace Utils {
struct SubmitFieldWidgetPrivate;
/* A widget for editing submit message fields like "reviewed-by:",
* "signed-off-by:". It displays them in a vertical row of combo/line edit fields
* that is modeled after the target address controls of mail clients.
* When choosing a different field in the combo, a new row is opened if text
* has been entered for the current field. Optionally, a "Browse..." button and
* completer can be added. */
class QTCREATOR_UTILS_EXPORT SubmitFieldWidget : public QWidget
{
Q_OBJECT

31
src/libs/utils/synchronousprocess.cpp
View File

@@ -50,6 +50,37 @@
# include <unistd.h>
#endif
/*!
\class Utils::SynchronousProcess
\brief Runs a synchronous process in its own event loop
that blocks only user input events. Thus, it allows for the gui to
repaint and append output to log windows.
The stdOut(), stdErr() signals are emitted unbuffered as the process
writes them.
The stdOutBuffered(), stdErrBuffered() signals are emitted with complete
lines based on the '\n' marker if they are enabled using
stdOutBufferedSignalsEnabled()/setStdErrBufferedSignalsEnabled().
They would typically be used for log windows.
There is a timeout handling that takes effect after the last data have been
read from stdout/stdin (as opposed to waitForFinished(), which measures time
since it was invoked). It is thus also suitable for slow processes that continously
output data (like version system operations).
The property timeOutMessageBoxEnabled influences whether a message box is
shown asking the user if they want to kill the process on timeout (default: false).
There are also static utility functions for dealing with fully synchronous
processes, like reading the output with correct timeout handling.
Caution: This class should NOT be used if there is a chance that the process
triggers opening dialog boxes (for example, by file watchers triggering),
as this will cause event loop problems.
*/
enum { debug = 0 };
enum { syncDebug = 0 };

20
src/libs/utils/synchronousprocess.h
View File

@@ -80,26 +80,6 @@ struct QTCREATOR_UTILS_EXPORT SynchronousProcessResponse
QTCREATOR_UTILS_EXPORT QDebug operator<<(QDebug str, const SynchronousProcessResponse &);
/* SynchronousProcess: Runs a synchronous process in its own event loop
* that blocks only user input events. Thus, it allows for the gui to
* repaint and append output to log windows.
*
* The stdOut(), stdErr() signals are emitted unbuffered as the process
* writes them.
*
* The stdOutBuffered(), stdErrBuffered() signals are emitted with complete
* lines based on the '\n' marker if they are enabled using
* stdOutBufferedSignalsEnabled()/setStdErrBufferedSignalsEnabled().
* They would typically be used for log windows.
*
* There is a timeout handling that takes effect after the last data have been
* read from stdout/stdin (as opposed to waitForFinished(), which measures time
* since it was invoked). It is thus also suitable for slow processes that continously
* output data (like version system operations).
*
* The property timeOutMessageBoxEnabled influences whether a message box is
* shown asking the user if they want to kill the process on timeout (default: false). */
class QTCREATOR_UTILS_EXPORT SynchronousProcess : public QObject
{
Q_OBJECT

11
src/libs/utils/treewidgetcolumnstretcher.cpp
View File

@@ -35,8 +35,19 @@
#include <QtGui/QTreeWidget>
#include <QtGui/QHideEvent>
#include <QtGui/QHeaderView>
using namespace Utils;
/*!
\class Utils::TreeWidgetColumnStretcher
\brief The class fixes QTreeWidget to resize all columns to contents, except one
stretching column.
As opposed to standard QTreeWidget, all columns are
still interactively resizable.
*/
TreeWidgetColumnStretcher::TreeWidgetColumnStretcher(QTreeWidget *treeWidget, int columnToStretch)
: QObject(treeWidget->header()), m_columnToStretch(columnToStretch)
{

14
src/libs/utils/treewidgetcolumnstretcher.h
View File

@@ -43,21 +43,13 @@ QT_END_NAMESPACE
namespace Utils {
/*
The class fixes QTreeWidget to resize all columns to contents, except one
stretching column. As opposed to standard QTreeWidget, all columns are
still interactively resizable.
*/
class QTCREATOR_UTILS_EXPORT TreeWidgetColumnStretcher : public QObject
{
int m_columnToStretch;
const int m_columnToStretch;
public:
TreeWidgetColumnStretcher(QTreeWidget *treeWidget, int columnToStretch);
explicit TreeWidgetColumnStretcher(QTreeWidget *treeWidget, int columnToStretch);
bool eventFilter(QObject *obj, QEvent *ev);
virtual bool eventFilter(QObject *obj, QEvent *ev);
};
} // namespace Utils

10
src/libs/utils/welcomemodetreewidget.cpp
View File

@@ -46,6 +46,11 @@ enum { leftContentsMargin = 2,
bottomContentsMargin = 1,
pixmapWidth = 24 };
/*!
\class Utils::WelcomeModeLabel
\brief Label usable for headers of a Welcome page.
*/
namespace Utils {
WelcomeModeLabel::WelcomeModeLabel(QWidget *parent) :
@@ -247,6 +252,11 @@ WelcomeModeTreeWidgetPrivate::WelcomeModeTreeWidgetPrivate() :
layout->setMargin(0);
}
/*!
\class Utils::WelcomeModeTreeWidget
\brief Show an itemized list with arrows and emits a signal on click.
*/
WelcomeModeTreeWidget::WelcomeModeTreeWidget(QWidget *parent) :
QWidget(parent), m_d(new WelcomeModeTreeWidgetPrivate)
{

2
src/libs/utils/welcomemodetreewidget.h
View File

@@ -44,7 +44,6 @@ namespace Utils {
struct WelcomeModeTreeWidgetPrivate;
class WelcomeModeItemWidget;
// Label usable for headers of a Welcome page.
class QTCREATOR_UTILS_EXPORT WelcomeModeLabel : public QLabel
{
Q_OBJECT
@@ -56,7 +55,6 @@ private:
void *m_unused;
};
// WelcomeModeTreeWidget: Show an itemized list with arrows and emits a signal on click.
class QTCREATOR_UTILS_EXPORT WelcomeModeTreeWidget : public QWidget
{
Q_OBJECT

7
src/libs/utils/wizard.cpp
View File

@@ -42,6 +42,13 @@
#include <QtGui/QHBoxLayout>
#include <QtGui/QStyle>
/*! \class Utils::Wizard
\brief A wizard with a progress bar on the left.
Informs the user about the progress.
*/
namespace Utils {
class ProgressItemWidget : public QWidget