From 2fd5057604ea1e29df73dee5181153fe6cd3fe68 Mon Sep 17 00:00:00 2001 From: Leandro Melo Date: Fri, 27 May 2011 14:30:17 +0200 Subject: [PATCH] Documentation: Snippets support Change-Id: I40dd20a7da93ab7af3044d9bebf49e15dbfb7aa4 Reviewed-on: http://codereview.qt.nokia.com/184 Reviewed-by: Leena Miettinen --- doc/api/external-tool-spec.qdoc | 1 - doc/api/qtcreator-api.qdoc | 4 +- doc/api/qtcreator-code-snippet-config.qdoc | 41 ------------ doc/api/qtcreator-dev.qdoc | 13 ++-- .../texteditor/snippets/isnippetprovider.cpp | 65 +++++++++++++++++++ .../texteditor/snippets/snippeteditor.cpp | 7 ++ 6 files changed, 81 insertions(+), 50 deletions(-) delete mode 100644 doc/api/qtcreator-code-snippet-config.qdoc diff --git a/doc/api/external-tool-spec.qdoc b/doc/api/external-tool-spec.qdoc index f036a43b813..8e6362a9a99 100644 --- a/doc/api/external-tool-spec.qdoc +++ b/doc/api/external-tool-spec.qdoc @@ -21,7 +21,6 @@ /*! \contentspage{index.html}{Qt Creator} - \previouspage qtcreator-code-snippet-config.html \page external-tool-spec.html \nextpage coding-style.html diff --git a/doc/api/qtcreator-api.qdoc b/doc/api/qtcreator-api.qdoc index 707c653b822..b2bbb68b87d 100644 --- a/doc/api/qtcreator-api.qdoc +++ b/doc/api/qtcreator-api.qdoc @@ -115,8 +115,8 @@ \o \l{TextEditor} \o 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 snippets, highlighting, \l{CodeAssist}{code assist}, indentation and style, - and others. + like \l{Snippets}{snippets}, highlighting, \l{CodeAssist}{code assist}, indentation + and style, and others. \endtable */ diff --git a/doc/api/qtcreator-code-snippet-config.qdoc b/doc/api/qtcreator-code-snippet-config.qdoc deleted file mode 100644 index cbd110acfdb..00000000000 --- a/doc/api/qtcreator-code-snippet-config.qdoc +++ /dev/null @@ -1,41 +0,0 @@ -/**************************************************************************** -** -** This file is part of Qt Creator -** -** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies). -** -** Contact: Nokia Corporation (info@qt.nokia.com) -** -** -** GNU Free Documentation License -** -** 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. -** -** If you have questions regarding the use of this file, please contact -** Nokia at qt-info@nokia.com. -** -****************************************************************************/ - -/*! - \previouspage - \page qtcreator-code-snippet-config.html - \title Code Snippet Configuration Files - \nextpage - - You can use code snippet configuration files to . - - Name the configuration files as follows: - - Copy the configuration files to the following directory: - - - - \section1 File Syntax - - - -*/ diff --git a/doc/api/qtcreator-dev.qdoc b/doc/api/qtcreator-dev.qdoc index 9fafb633a71..864dfd91044 100644 --- a/doc/api/qtcreator-dev.qdoc +++ b/doc/api/qtcreator-dev.qdoc @@ -45,19 +45,21 @@ whole files or classes spread over multiple files, or complete projects, you can create code snippets, templates, and wizards for that purpose. - \section2 Code Snippets + \section2 Snippets - Typically, code snippets consist of a few lines of code that you regularly + 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. Qt Creator contains a set of preconfigured snippets + normal code completion (see \l{Code Assist}{Providing Code Assist}). + Qt Creator contains a set of preconfigured snippets groups to which you can add your own snippets. \list \o \l{http://doc.qt.nokia.com/qtcreator/creator-completing-code.html#editing-code-snippets} - {Adding Code Snippets in Qt Creator} - \o \l{Code Snippet Configuration Files} + {Snippets User Interface} + \o \l{Snippets} {Adding Snippets Groups} \endlist \section2 File, Class and Project Templates @@ -239,7 +241,6 @@ \endlist \o Reference \list - \o \l{Code Snippet Configuration Files} \o \l{http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-latest.html} {MIME Type Specification Files} \o \l{External Tool Specification Files} diff --git a/src/plugins/texteditor/snippets/isnippetprovider.cpp b/src/plugins/texteditor/snippets/isnippetprovider.cpp index 07008b64f9c..298ed819d49 100644 --- a/src/plugins/texteditor/snippets/isnippetprovider.cpp +++ b/src/plugins/texteditor/snippets/isnippetprovider.cpp @@ -34,8 +34,73 @@ using namespace TextEditor; +/*! + \group Snippets + \title Snippets for Editors + + Snippets typically consist of chunks of code in a programming language (although they + can also be plain text) which you would like to avoid re-typing every time. They + are triggered in the same way as the completions (see \l{CodeAssist}{Providing + Code Assist}). + + In order to create a new group of snippets two steps are necessary: + \list + \o Implement the TextEditor::ISnippetProvider interface and register it in + the extension system. + \o Create an XML configuration file and place it in the + /share/qtcreator/snippets directory. As an example of the file format + please take a look at the already available ones. The meaning and consistency rules + of the fields are described below: + \list + \o group - This is the group in which the snippet belongs in the user interface. + It must match TextEditor::ISnippetProvider::groupId(). + \o id - A unique string that identifies this snippet among all others available. + The recommended practice is to prefix it with the group so it is easier to have + such control on a file level. + \o trigger - The sequence of characters to be compared by the completion engine + in order to display this snippet as a code assist proposal. + \o complement - Additional information that is displayed in the code assist + proposal so it is possible to disambiguate similar snippets that have the + same trigger. + \endlist + \endlist + + All XML configuration files found in the directory mentioned above are parsed by + Qt Creator. However, only the ones which are associated with known groups (specified + by a provider) are taken into consideration. +*/ + +/*! + \class TextEditor::ISnippetProvider + \brief The ISnippetProvider class acts as an interface for providing groups of snippets. + \ingroup Snippets + + Known implementors of this interface are the CppSnippetProvider, the QmlJSSnippetProvider, + and the PlainTextSnippetProvider. +*/ + ISnippetProvider::ISnippetProvider() : QObject() {} ISnippetProvider::~ISnippetProvider() {} + +/*! + \fn QString TextEditor::ISnippetProvider::groupId() const + + Returns the unique group id to which this provider is associated. +*/ + +/*! + \fn QString TextEditor::ISnippetProvider::displayName() const + + Returns the name to be displayed in the user interface for snippets that belong to the group + associated with this provider. +*/ + +/*! + \fn void TextEditor::ISnippetProvider::decorateEditor(SnippetEditorWidget *editor) const + + This is a hook which allows you to apply customizations such as highlighting or indentation + to the snippet editor. +*/ diff --git a/src/plugins/texteditor/snippets/snippeteditor.cpp b/src/plugins/texteditor/snippets/snippeteditor.cpp index 25ffd408e83..1efe2d2f816 100644 --- a/src/plugins/texteditor/snippets/snippeteditor.cpp +++ b/src/plugins/texteditor/snippets/snippeteditor.cpp @@ -41,6 +41,13 @@ using namespace TextEditor; +/*! + \class TextEditor::SnippetEditorWidget + \brief The SnippetEditorWidget class is a lightweight editor for code snippets + with basic support for syntax highlighting, indentation, and others. + \ingroup Snippets +*/ + SnippetEditor::SnippetEditor(SnippetEditorWidget *editor) : BaseTextEditor(editor) {