creator-beautifier.qdoc 6.01 KB
Newer Older
1 2
/****************************************************************************
**
3 4
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
5
**
6
** This file is part of the Qt Creator documentation.
7
**
8 9 10 11 12 13 14
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
15
**
16
** GNU Free Documentation License Usage
17 18
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
19 20 21 22
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
23 24 25 26 27 28 29 30 31 32
**
****************************************************************************/

// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************

/*!
33
    \contentspage {Qt Creator Manual}
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61
    \previouspage creator-editor-refactoring.html
    \page creator-beautifier.html
    \nextpage creator-editor-options.html

    \title Beautifying Source Code

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

    \list

        \li \l{http://astyle.sourceforge.net}{Artistic Style}

        \li \l{http://clang.llvm.org/docs/ClangFormat.html}{ClangFormat}

        \li \l{http://uncrustify.sourceforge.net}{Uncrustify}

    \endlist

    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 options. You can use a predefined style or
    define your own style.

    To use the Beautifier plugin:

    \list 1

62 63 64 65 66 67 68 69 70 71 72
        \li Download and install the tool to use for formatting source code:

            \list
                \li \l{http://sourceforge.net/projects/astyle/files/astyle}
                    {Artistic Style}
                \li \l{http://llvm.org/releases/download.html}{ClangFormat}
                \li \l{http://sourceforge.net/projects/uncrustify/files/uncrustify}
                    {Uncrustify}
            \endlist

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

74 75
        \li Select \uicontrol Help > \uicontrol {About Plugins} > \uicontrol {C++} >
            \uicontrol Beautifier to enable the plugin.
76 77 78

        \li Restart \QC to be able to use the plugin.

Tobias Hunger's avatar
Tobias Hunger committed
79 80
        \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Beautifier
            to specify settings for the tool you want to use.
81

82
            \image beautifier_options.png
83

Tobias Hunger's avatar
Tobias Hunger committed
84 85 86
        \li In the \uicontrol {Artistic Style command},
            \uicontrol {Clang Format command}, or
            \uicontrol {Uncrustify command} field, specify the path to the tool
87
            executable.
88

89
        \li In the \uicontrol Options group, select the configuration file that
90 91
            defines the style to use in the source files. If you select several
            options, they are applied from top down.
92

93
            \list
94

Tobias Hunger's avatar
Tobias Hunger committed
95 96
                \li Select the \uicontrol {Use file defined in project files}
                    option to use the configuration file defined in the qmake
97
                    DISTFILES variable as the configuration file for the
98
                    selected tool.
99

100
                \li Select the \uicontrol {Use file in $HOME} option to use the
Tobias Hunger's avatar
Tobias Hunger committed
101 102
                    specified file in the user's home directory as the
                    configuration file for the selected tool.
103

Tobias Hunger's avatar
Tobias Hunger committed
104 105
                \li Select the \uicontrol {Use customized style} option, and
                    then \uicontrol Add to define your own style.
106

Tobias Hunger's avatar
Tobias Hunger committed
107 108 109 110
                    Define code formatting in the
                    \uicontrol {Edit Configuration} dialog. It provides syntax
                    highlighting, auto-completion, and context-sensitive help.
                    For these features, you must have the tool installed.
111

112
                   \image beautifier_editor.png
113

Leena Miettinen's avatar
Leena Miettinen committed
114 115
            \endlist

Tobias Hunger's avatar
Tobias Hunger committed
116 117 118 119
        \li Select \uicontrol Tools > \uicontrol Beautifier >
            \uicontrol {Artistic Style}, \uicontrol ClangFormat, or
            \uicontrol Uncrustify > \uicontrol {Format Current File} to format
            the currently open file.
120 121 122 123 124

            You can \l{Keyboard Shortcuts}{create keyboard shortcuts} for the
            functions.

    \endlist
125

Tobias Hunger's avatar
Tobias Hunger committed
126
    In addition to the \uicontrol {Format Current File} command, ClangFormat
127 128 129 130 131
    and Uncrustify provide the \uicontrol {Format Selected Text} command. If you
    select it when no text is selected, nothing happens. To format the entire
    file in this case when using Clang, select the
    \uicontrol {Format entire file if no text was selected} check box in the
    \uicontrol {Clang Format} options.
132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148

    To automatically format files when they are saved, select \uicontrol Tools >
    \uicontrol Beautifier > \uicontrol General:

    \list 1

        \li In the \uicontrol Tool field, select the tool for formatting.

        \li In the \uicontrol {Restrict to MIME types} field, specify a
            semicolon-separated list of MIME types. One of these types must
            match the MIME type of the file that is auto formatted.
            An empty list accepts all files.

        \li Select the \uicontrol {Restrict to files contained in the current
            project} check box to only auto format files in the current project.

    \endlist
149
*/