creator-beautifier.qdoc 4.7 KB
Newer Older
1 2
/****************************************************************************
**
Eike Ziller's avatar
Eike Ziller committed
3 4
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing
5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
**
** This file is part of Qt Creator
**
**
** 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.
**
**
****************************************************************************/

// **********************************************************************
// 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.
// **********************************************************************

/*!
26
    \contentspage {Qt Creator Manual}
27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
    \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

55 56 57 58 59 60 61 62 63 64 65
        \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.
66

67 68
        \li Select \uicontrol Help > \uicontrol {About Plugins} > \uicontrol {C++} >
            \uicontrol Beautifier to enable the plugin.
69 70 71

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

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

75
            \image beautifier_options.png
76

Tobias Hunger's avatar
Tobias Hunger committed
77 78 79
        \li In the \uicontrol {Artistic Style command},
            \uicontrol {Clang Format command}, or
            \uicontrol {Uncrustify command} field, specify the path to the tool
80
            executable.
81

82
        \li In the \uicontrol Options group, select the configuration file that
83 84
            defines the style to use in the source files. If you select several
            options, they are applied from top down.
85

86
            \list
87

Tobias Hunger's avatar
Tobias Hunger committed
88 89
                \li Select the \uicontrol {Use file defined in project files}
                    option to use the configuration file defined in the qmake
90
                    DISTFILES variable as the configuration file for the
91
                    selected tool.
92

Tobias Hunger's avatar
Tobias Hunger committed
93 94 95
                \li Select the \uicontrol {Use $HOME} option to use the
                    specified file in the user's home directory as the
                    configuration file for the selected tool.
96

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

Tobias Hunger's avatar
Tobias Hunger committed
100 101 102 103
                    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.
104

105
                   \image beautifier_editor.png
106

Leena Miettinen's avatar
Leena Miettinen committed
107 108
            \endlist

Tobias Hunger's avatar
Tobias Hunger committed
109 110 111 112
        \li Select \uicontrol Tools > \uicontrol Beautifier >
            \uicontrol {Artistic Style}, \uicontrol ClangFormat, or
            \uicontrol Uncrustify > \uicontrol {Format Current File} to format
            the currently open file.
113 114 115 116 117

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

    \endlist
118

Tobias Hunger's avatar
Tobias Hunger committed
119 120 121 122 123
    In addition to the \uicontrol {Format Current File} command, ClangFormat
    provides 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, select the \uicontrol {Format entire file if no text was selected}
    check box in the \uicontrol {Clang Format} options.
124
*/