From 39dfc12a9e8d2ff209d1bae9eaa212cd6bb6ec27 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Thu, 3 Aug 2023 11:29:48 +0200 Subject: [PATCH] Doc: Divide "Creating Files" into How-to topics Task-number: QTCREATORBUG-29361 Change-Id: Ib5e31777ef1649f86525b41bcfbcac52b9dd231e Reviewed-by: Eike Ziller --- .../images/qtcreator-remove-file.webp | Bin 0 -> 3892 bytes .../src/cmake/creator-projects-cmake.qdoc | 2 +- .../howto/creator-only/creator-how-tos.qdoc | 4 + .../creator-only/creator-files-creating.qdoc | 208 +++++++++++++----- .../creator-projects-creating.qdoc | 4 +- doc/qtcreator/src/qtcreator-toc.qdoc | 5 +- .../creator-only/qtquick-creating.qdoc | 2 +- .../creator-file-system-view.qdoc | 2 +- .../user-interface/creator-projects-view.qdoc | 2 +- 9 files changed, 161 insertions(+), 68 deletions(-) create mode 100644 doc/qtcreator/images/qtcreator-remove-file.webp diff --git a/doc/qtcreator/images/qtcreator-remove-file.webp b/doc/qtcreator/images/qtcreator-remove-file.webp new file mode 100644 index 0000000000000000000000000000000000000000..a96ffacad7ccacdef6114dcf7f177e24d03ee65c GIT binary patch literal 3892 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 literal 0 HcmV?d00001 diff --git a/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc b/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc index d9809f09a38..546b089898e 100644 --- a/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc +++ b/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc @@ -183,7 +183,7 @@ \section1 Managing Files - When you use project wizard templates to \l{Creating Files}{add files} to + When you use project wizard templates to \l{Create files}{add files} to a project, \QC automatically adds them to the \c {qt_add_executable()}, \c {add_executable()}, or \c {qt_add_library()} function in the CMakeLists.txt file. diff --git a/doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc b/doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc index 3d8d84882d9..9e81194b821 100644 --- a/doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc +++ b/doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc @@ -62,6 +62,10 @@ \list \li \l {Add a license header template for C++ code} \li \l {Add subprojects to projects} + \li \l {Create C++ classes} + \li \l {Create files} + \li \l {Create OpenGL fragment and vertex shaders} + \li \l {Create resource files} \li \l {Develop Qt for Python applications} \li \l {Specify project contents} \li \l {Select the build system} diff --git a/doc/qtcreator/src/projects/creator-only/creator-files-creating.qdoc b/doc/qtcreator/src/projects/creator-only/creator-files-creating.qdoc index 11319133271..2b730ee67e3 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-files-creating.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-files-creating.qdoc @@ -2,121 +2,207 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! - \previouspage creator-project-creating.html \page creator-file-creating.html - \nextpage creator-project-opening.html + \previouspage creator-how-tos.html - \title Creating Files + \ingroup creator-how-to-projects + + \title Create files + + Use wizard templates to add individual files to your \l{Creating Projects} + {projects}. + + To add files to projects, select \uicontrol File > \uicontrol {New File}, and + then select the type of the file. \image qtcreator-new-file.webp {New File wizard} - Use wizard templates to add individual files to your \l{Creating Projects} - {projects}. Select \uicontrol File > \uicontrol {New File} and - select the type of the file: + \section1 Select file type - \list - \li \uicontrol {C/C++}: header and source files for new classes. - \li \uicontrol {Modeling}: State Chart XML (SCXML) files, - Universal Modeling Language (UML) style \l {Modeling}{models}, - and scratch models that use a temporary file. - \li \uicontrol {Qt}: source and header files for item, table, + The following table lists the types of wizard templates that you can use + for creating files. The \uicontrol {New File} dialog shows detailed information about each file + wizard template. + + \table + \header + \li Category + \li Purpose + \row + \li \uicontrol {C/C++} + \li Header and source files for new classes. + \row + \li \uicontrol {Modeling} + \li State Chart XML (SCXML) files, Universal Modeling Language (UML) + style \l {Modeling}{models}, and scratch models that use a temporary + file. + \row + \li \uicontrol {Qt} + \li Source and header files for item, table, or list models, \QD forms and a matching classes for Qt Widgets projects, Qt resource files, as well as QML and JavaScript files for Qt Quick projects. - \li \uicontrol {GLSL}: fragment and vertex shaders. - \li \uicontrol {General}: markdown files, empty files that you can save - with any filename extension, and scratch buffers that use temporary - files. - \li \uicontrol {Java}: class files. - \li \uicontrol {Python}: class and script files for Python projects. - \li \uicontrol {vcpkg} (experimental): \l {Managing Packages with vcpkg} - {vcpkg package manager} manifest files (vcpkg.json). - \li \uicontrol {Nim} (experimental): empty Nim source and script files. + \row + \li \uicontrol {GLSL} + \li OpenGL fragment and vertex shaders. + \row + \li \uicontrol {General} + \li Markdown files, empty files that you can save with any filename + extension, and scratch buffers that use temporary files. + \row + \li \uicontrol {Java} + \li Class files. + \row + \li \uicontrol {Python} + \li Class and script files for Python projects. + \row + \li \uicontrol {vcpkg} (experimental) + \li \l {Managing Packages with vcpkg}{vcpkg package manager} manifest + files (vcpkg.json). + \row + \li \uicontrol {Nim} (experimental) + \li Empty Nim source and script files. + \endtable + + \sa {Create C++ classes}, {Create OpenGL fragment and vertex shaders}, + {Create resource files}, {Use project wizards} +*/ + +/*! + \page creator-how-to-create-cpp-classes.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-projects + + \title Create C++ classes + + To create a C++ header and source file for a new class that you can add to a + C++ project: + + \list 1 + \li Select \uicontrol File > \uicontrol {New File} > + \uicontrol {C++ Class Wizard} > \uicontrol Choose. + \li Specify the class name, base class, and header and source files for + the class. + \image qtcreator-cpp-class-wizard.png {Enter Class Name dialog} \endlist - The \uicontrol {New File} dialog shows detailed information about each file - wizard template. - - \section1 C++ Classes - - The \uicontrol {C++ Class Wizard} allows you to create a C++ header and source - file for a new class that you can add to a C++ project. Specify the class - name, base class, and header and source files for the class. - The wizard supports namespaces. To use a namespace, enter a qualified class name in the \uicontrol {Class name} field. For example: \c MyNamespace::MySubNamespace::MyClass. The wizard suggests existing namespaces and class names as you type. - \image qtcreator-cpp-class-wizard.png "Enter Class Name dialog" + You can also create your own project and class wizards. + + \section1 Set file naming preferences The names of the header and source file are based on the class name. To - change the default suffix of a file, select \uicontrol Edit > \uicontrol Preferences > - \uicontrol {C++} > \uicontrol {File Naming}. + change the default suffix of a file, select \uicontrol Edit > + \uicontrol Preferences > \uicontrol {C++} > \uicontrol {File Naming}. \image qtcreator-options-cpp-files.png "C++ File Naming preferences" - In the \uicontrol {License template} field, you can use + In the \uicontrol {License template} field, enter \l{Using Variables in Wizards}{predefined wizard variables} to specify the path and filename of the license to use in the source and header files. - You can create your own project and class wizards. For more information, - see \l{Adding New Custom Wizards}. + \sa {Create files}, {Use project wizards}, {Adding New Custom Wizards} +*/ - \section1 Resource Files +/*! + \page creator-how-to-create-resource-files.html + \previouspage creator-how-tos.html - \QC supports the \l{The Qt Resource System}{Qt Resource System}, which is a - platform-independent mechanism for storing files in the application's - executable. + \ingroup creator-how-to-projects - \image qtcreator-add-resource-wizard.png "New File dialog" + \title Create resource files - The wizard creates a resource collection file (.qrc) that you can manage in - the resource editor. + The \l{The Qt Resource System}{Qt Resource System} is a platform-independent + mechanism for storing files in the application's executable. - \image qtcreator-add-resource.png "Editing resource files" + To create a resource file: - Select \uicontrol {Add Files} to locate and add individual - files. + \list 1 + \li Select \uicontrol File > \uicontrol {New File} > \uicontrol {Qt} > + \uicontrol {Qt Resource File} > \uicontrol Choose. + \image qtcreator-add-resource-wizard.png {New File dialog} + \li Follow the instructions of the wizard to create a resource + collection file (.qrc). + \li Open the resource file in the resource editor. + \image qtcreator-add-resource.png "Editing resource files" + \li Select \uicontrol {Add Files} to locate and add individual files. + \endlist + + \section1 Sort resource files To list the folders and files in ascending alphabetic order in the source tree, select \uicontrol {Sort Alphabetically} in the context menu. - By default, resources are accessible in the application under the same file + \section1 Set a path prefix + + By default, resources in the application are accessible under the same file name as they have in the source tree, with a \c{:/} prefix, or by a URL with a \c qrc scheme. To specify a path prefix for all files in the \c .qrc file, select \uicontrol {Add Prefix} and enter the prefix in the \uicontrol Prefix field. + \section1 Set a locale + Some resources need to change based on the user's locale, such as translation files or icons. You can specify a locale in the \uicontrol Language field. + Use a lowercase, two-letter \l {https://www.iso.org/iso-639-language-codes.html} + {ISO 639 language code}, such as \e de, \e en, or \e fr. + + \section1 Remove resource files + Select \uicontrol Remove to remove the selected file from the resource - collection. In the \uicontrol {Remove File} dialog, select the + collection. + + In the \uicontrol {Remove File} dialog, select the \uicontrol {Delete file permanently} check box to remove the file from - the file system. To remove files that cannot be found in the file system, + the file system. + + \image qtcreator-remove-file.webp {Remove File dialog} + + To remove files that cannot be found in the file system, select \uicontrol {Remove Missing Files}. The above functions are also available in the context menu in the - \uicontrol Projects view. + \l Projects view. - \section1 OpenGL Fragment and Vertex Shaders + \sa {Create files}, {Use project wizards}, {QLocale} +*/ - Qt supports integration with OpenGL implementations on all - platforms, which allows you to display hardware accelerated 3D graphics - alongside a more conventional user interface. For more information, see - \l{Qt GUI}. +/*! + \page creator-how-to-create-opengl-shaders.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-projects + + \title Create OpenGL fragment and vertex shaders + + Qt supports integration with OpenGL implementations on all platforms, so you + can display hardware accelerated 3D graphics alongside a more conventional + user interface. For more information, see \l{Qt GUI}. You can use the QOpenGLShader class to compile OpenGL shaders written in the OpenGL Shading Language (GLSL) and in the OpenGL/ES Shading Language (GLSL/ES). QOpenGLShader and QOpenGLShaderProgram shelter you from the - details of - compiling and linking vertex and fragment shaders. + details of compiling and linking vertex and fragment shaders. - You can use \QC code editor to write fragment and vertex shaders - in GLSL or GLSL/ES. The code editor offers syntax highlighting and code - completion for the files. + To create OpenGL shaders: - \image qtcreator-new-opengl-file.png "New OpenGL file wizard" + \list 1 + \li Select \uicontrol File > \uicontrol {New File} > \uicontrol {GLSL}. + \image qtcreator-new-opengl-file.png {New OpenGL file wizard} + \li Select the type of the shader to create, and then select + \uicontrol Choose. + \li Follow the instructions of the wizard to create the shader file. + \li Open the shader file in the code editor, and write the shader code + in GLSL or GLSL/ES. The code editor offers syntax highlighting and + code completion for the files. + \endlist + + \sa {Create files}, {Use project wizards} */ diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-creating.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-creating.qdoc index c48a2ead78f..39c78dd197b 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-creating.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-creating.qdoc @@ -69,7 +69,7 @@ install and configure some additional software on the devices to be able to \l{Connecting Devices}{connect} to them from the development PC. - \sa {Manage Projects}{How-to: Manage Projects}, {Creating Files}, + \sa {Manage Projects}{How-to: Manage Projects}, {Adding Libraries to Projects}, {Opening Projects}, {Adding New Custom Wizards} */ @@ -172,7 +172,7 @@ \uicontrol Wizard. All wizard actions start with \uicontrol Impl there. \sa {Assign keyboard shortcuts}, {Activating Kits for a Project}, - {Creating Files}, {Creating Projects} + {Create files}, {Creating Projects} */ /*! diff --git a/doc/qtcreator/src/qtcreator-toc.qdoc b/doc/qtcreator/src/qtcreator-toc.qdoc index 2fa2298a6b6..08e8ee82128 100644 --- a/doc/qtcreator/src/qtcreator-toc.qdoc +++ b/doc/qtcreator/src/qtcreator-toc.qdoc @@ -25,7 +25,6 @@ \list \li \l{Creating Projects} \list - \li \l{Creating Files} \li \l{Opening Projects} \li \l{Adding Libraries to Projects} \li \l{Adding New Custom Wizards} @@ -278,6 +277,10 @@ \list \li \l {Add a license header template for C++ code} \li \l {Add subprojects to projects} + \li \l {Create C++ classes} + \li \l {Create files} + \li \l {Create OpenGL fragment and vertex shaders} + \li \l {Create resource files} \li \l {Develop Qt for Python applications} \li \l {Select the build system} \li \l {Specify project contents} diff --git a/doc/qtcreator/src/qtquick/creator-only/qtquick-creating.qdoc b/doc/qtcreator/src/qtquick/creator-only/qtquick-creating.qdoc index 4a3746f4c29..3188f73d200 100644 --- a/doc/qtcreator/src/qtquick/creator-only/qtquick-creating.qdoc +++ b/doc/qtcreator/src/qtquick/creator-only/qtquick-creating.qdoc @@ -33,7 +33,7 @@ \QC creates the necessary boilerplate files. Some of the files are specific to a particular target platform. You can use wizard templates - also to \l{Creating Files}{add files} to the projects. + also to \l{Create files}{add files} to the projects. \section1 Qt Quick Applications diff --git a/doc/qtcreator/src/user-interface/creator-file-system-view.qdoc b/doc/qtcreator/src/user-interface/creator-file-system-view.qdoc index b2a9f0dfe1d..e8d4eeb97e5 100644 --- a/doc/qtcreator/src/user-interface/creator-file-system-view.qdoc +++ b/doc/qtcreator/src/user-interface/creator-file-system-view.qdoc @@ -77,7 +77,7 @@ \if defined(qtdesignstudio) \l{Adding Files to Projects}. \else - \l{Creating Files}. + \l{Create files}. \endif \li Rename existing files. To move the file to another directory, enter the relative or absolute path to its new location in addition to the diff --git a/doc/qtcreator/src/user-interface/creator-projects-view.qdoc b/doc/qtcreator/src/user-interface/creator-projects-view.qdoc index 9d632a127e6..905c4ebe779 100644 --- a/doc/qtcreator/src/user-interface/creator-projects-view.qdoc +++ b/doc/qtcreator/src/user-interface/creator-projects-view.qdoc @@ -73,7 +73,7 @@ \if defined(qtdesignstudio) \l{Adding Files to Projects}. \else - \l{Creating Files}. + \l{Create files}. \endif \li Rename existing files. If you change the base name of a file, \QC displays a list of other files with the same base name