From 2a80ee8d632278eb7d2076abb2c6036c3741503b Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Tue, 1 Aug 2017 16:33:34 +0200 Subject: Doc: Update information about XML-based wizard templates The example wizard templates have been removed. None of the remaining XML-based wizards use generator scripts (and those are not recommended for new projects), so information about genereator scripts was removed. Change-Id: Ie84fad6a5acb39e9718358bd0b14a5caca454201 Reviewed-by: Tobias Hunger --- doc/images/qtcreator-custom-project-wizards.png | Bin 34175 -> 37418 bytes .../creator-projects-custom-wizards-xml.qdoc | 127 +++------------------ 2 files changed, 14 insertions(+), 113 deletions(-) diff --git a/doc/images/qtcreator-custom-project-wizards.png b/doc/images/qtcreator-custom-project-wizards.png index 581322b37a..43a0d0b6be 100644 Binary files a/doc/images/qtcreator-custom-project-wizards.png and b/doc/images/qtcreator-custom-project-wizards.png differ diff --git a/doc/src/projects/creator-projects-custom-wizards-xml.qdoc b/doc/src/projects/creator-projects-custom-wizards-xml.qdoc index 787a90fd32..2cb3244e74 100644 --- a/doc/src/projects/creator-projects-custom-wizards-xml.qdoc +++ b/doc/src/projects/creator-projects-custom-wizards-xml.qdoc @@ -41,29 +41,16 @@ {JSON-Based wizards} instead. XML wizards are deprecated and support for them will be removed in future versions of \QC. - To display the XML-based example wizards in \QC, rename - \c {wizard_sample.xml} as \c {wizard.xml} in the - \c {\share\qtcreator\templates\wizards\helloworld} and - \c {\share\qtcreator\templates\wizards\listmodel} folders. After - you restart \QC, the \uicontrol {Custom Classes} - and \uicontrol {Custom Projects} categories (1) appear in the \uicontrol New - dialog. For each category, an icon (2), a display name (3), and a - description (4) are displayed. - - \image qtcreator-custom-project-wizards.png "The New dialog with custom projects and classes" - - Files can be generated by using either \l{Processing Template Files} - {templates} or \l{Using Generator Scripts}{generator scripts}, where a - script is called to create the files. - - \note The generator option mainly exists to accommodate existing generator - scripts or cases where complicated algorithmic logic is required when - generating files. Writing cross-platform scripts is inherently difficult, - and therefore, it is not recommended for new wizards. + To see examples of XML-based wizards, select \uicontrol File > + \uicontrol {New File or Project} > \uicontrol Library. For each wizard, an + icon (1), a display name (2), and a description (3) are displayed. + + \image qtcreator-custom-project-wizards.png "The New dialog" + + Files can be generated by using \l{Processing Template Files}{templates}. XML-based wizard template directories contain an XML configuration file - called wizard.xml, the template source files, and optionally, the generator - script. + called wizard.xml and the template source files. \section1 Creating XML-Based Project Wizards @@ -71,10 +58,11 @@ \list 1 - \li Make a copy of the \c {share/qtcreator/templates/wizards/helloworld} - or \c {share/qtcreator/templates/wizards/listmodel} folder. + \li Make a copy of a folder in the \c share/qtcreator/templates/wizards/ + folder that contains an XML-based wizard (\c codesnippet, + \c qtcreatorplugin, or \c qtquick2-extension). - \li Modify the wizard_example.xml file. + \li Modify the wizard.xml file. \li The following code determines the type of the wizard and its place in the \uicontrol New dialog: @@ -89,8 +77,7 @@ \list - \li \c version is the version of the file contents. Do not modify - this value. + \li \c version is the version of the file contents. \li \c kind specifies the type of the wizard: \c project or \c class. @@ -146,12 +133,7 @@ \endlist - \li Files to be added to the project: - - \list - - \li Template-based: The following code specifies the files to add to - the project: + \li The following code specifies the files to add to the project: \code @@ -183,41 +165,6 @@ See also \l{Processing Template Files}. - \li Generator-script: The following code specifies that the script - \c generate.pl is to be used to create the files: - - \code - - - - - - - - \endcode - - In each argument, the field placeholders are replaced by the - field values. There are additional boolean attributes which give - fine-grained control: - - \list - - \li \c omit-empty specifies that complete argument is to be - omitted when all placeholders expand to empty values. In - the above example, the option \c --source-suffix will - not be passed to the script if the value is empty. - - \li \c write-file indicates that instead of the expanded - value, the value will be written to a temporary file and - its file name will be passed to the script instead. This - is useful for multi-line text fields. - - \endlist - - See also \l{Using Generator Scripts}. - - \endlist - \li The following code creates a page that specifies settings for the project: \code @@ -600,50 +547,4 @@ of the base class. If the validation fails, a red label displaying the message appears at the bottom of the wizard page. - \section1 Using Generator Scripts - - The values entered in the wizard page are passed to the script - as command line arguments as defined by the wizard configuration file. - - In addition, the script must implement a \c{--dry-run} command line option. - - \QC needs to know the file names before the files are created to check - whether files with identical names already exist, for example. Therefore, - script file generation is a two-step process: - - \list 1 - - \li Determine file names and attributes: The script is called with the - command line \c{--dry-run} option and the field values. It then prints - the relative path names of the files it intends to create, followed by - comma-separated attributes matching those of the \c{} element, for - example: - - \code - myclass.cpp,openeditor - myclass.h,openeditor - myproject.pro,openproject - \endcode - - \li Create files: The script is called with the parameters only in the - working directory. It then actually creates the files. If directories - are needed, the script should create them, too. - - \endlist - - The \c{scriptgeneratedproject} sample wizard illustrates the usage. - A typical script invocation for this example (obtained by running \QC with - \c{--customwizard-verbose}) looks as follows: - - \code - generate.pl --class-name=TestClass --project-name=TestProject --header-suffix=h --source-suffix=cpp --description=/tmp/qtcreatorj26629.txt - \endcode - - By default, the scripts are run in the directory corresponding to - \c %TargetPath%. This can be overridden by specifying the attribute - \c workingdirectory on the element \c generatorscript. For example, if the - script creates the project directory by itself, %Path% can be specified. In - that case, \c --dry-run should output the correct relative paths or absolute - paths constructed using the value of \c %Path%. - */ -- cgit v1.2.1