Beautifying Source Code

You can use the experimental Beautifier plugin to format your source code by using the following external tools:

The Beautifier plugin parses the source code into component structures, such as assignment statements, if blocks, loops, and so on, and formats them as specified in the Beautifier preferences. You can use a predefined style or define your own style.

Note: Enable the Beautifier plugin to use it. Since Qt Creator 10.0.0, the ClangFormat plugin is enabled by default. Select Preferences > C++ > Formatting mode > Disable to turn off ClangFormat if you enable Beautifier because combining them can lead to unexpected results.

To use the Beautifier plugin:

  1. Download and install the tool to use for formatting source code:

    You might have to build the tools from sources for some platforms.

  2. Select Preferences > Beautifier to specify settings for beautifying files.
  3. Select the Automatic formatting on file save check box to automatically beautify files when you save them using the tool you select in the Tool field.

    {General Beautifier preferences}

  4. In the Restrict to MIME types field, define the MIME types of the files to beautify, separated by semicolons. Leave the field empty to apply the tool on all files.

    This setting is applied only when automatically beautifying files on save. To restrict the MIME types when selecting the menu item to format the currently open file, specify this option in the tool-specific tab.

  5. Select the Restrict to files contained in the current project check box to only beautify files that belong to the current project.
  6. Select Artistic Style, ClangFormat, or Uncrustify to specify settings for the tool you want to use.

    "Uncrustify Beautifier preferences"

  7. In the Configuration group, specify the path to the tool executable in the Artistic Style command, ClangFormat command, or Uncrustify command field.
  8. In the Restrict to MIME types field, define the MIME types of the files to beautify. This setting is applied when you select the menu item to format the currently open file.
  9. In the Options group, select the configuration file that defines the style to use in the source files. If you select several options, they are applied from top down. The available options depend on the tool.
    • Select Use file *.astylerc defined in project files or Use file uncrustify.cfg defined in project files, to use the configuration file defined in the project file as the configuration file for the selected tool.
    • Select Use specific config file or Use file specific uncrustify.cfg to use the specified file as the configuration file for the selected tool.
    • Select Use file uncrustify.cfg in <$HOME> or Use file .astylerc or acstylerc in <$HOME> to use the specified file in the user's home directory as the configuration file for the selected tool.
    • For ClangFormat, you can use a predefined style, by selecting the Use predefined style radio button, and then selecting the style to use from the list of available styles.

      "ClangFormat Beautifier preferences"

      Select File to load the style configuration from the .clang-format or _clang-format file located in the same directory as the source file or in one of its parent directories.

      To specify a fallback style to use if the style configuration file is not available, use the Fallback style combo box. Select Default to use the default style. Select None to skip formatting.

    • Select the Use customized style option, and then Add to define your own style.

      Define code formatting in the Add Configuration dialog. It offers syntax highlighting, auto-completion, and context-sensitive help. For these features, you must have the tool installed.

      "Add Configuration dialog"

  10. Select Preferences > Beautifier > Artistic Style, ClangFormat, or Uncrustify > Format Current File to format the currently open file.

    You can create keyboard shortcuts for the functions.

In addition, ClangFormat has the Format at Cursor command. If you select it when no text is selected, the syntactic entity under the cursor is formatted. The Disable Formatting for Selected Text command wraps selected lines within // clang-format off and // clang-format on.

Uncrustify has the Format Selected Text command. If you select it when no text is selected, the whole file is formatted by default. To disable this behavior, deselect the Format entire file if no text was selected check box.

See also Enable and disable plugins.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.