<!--
  ~ Copyright 2009 the original author or authors.
  ~
  ~ Licensed under the Apache License, Version 2.0 (the "License");
  ~ you may not use this file except in compliance with the License.
  ~ You may obtain a copy of the License at
  ~
  ~      http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing, software
  ~ distributed under the License is distributed on an "AS IS" BASIS,
  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  ~ See the License for the specific language governing permissions and
  ~ limitations under the License.
  -->
<chapter id="tutorial_gradle_gui">
    <title>Using the Gradle Graphical User Interface</title>
    <para>In addition to supporting a traditional command line interface, Gradle offers
    a graphical user interface.  This is a stand alone user interface that can be launched with the
    <command>--gui</command> option.</para>
    <example>
        <title>Launching the GUI</title>
        <programlisting><![CDATA[
gradle --gui
]]></programlisting>
    </example>
    <para>Note that this command blocks until the Gradle GUI is closed.  Under *nix it is probably preferable to run
        this as a background task (<command>gradle --gui&amp;</command>)</para>
    <para>If you run this from your Gradle project working directory, you should see a tree of tasks.</para>
    <figure>
        <title>GUI Task Tree</title>
        <imageobject>
            <imagedata fileref="img/guiTaskTree.png" width="586px" depth="597px"/>
        </imageobject>
    </figure>
    <para>It is preferable to run this command from your Gradle project directory so that the settings of the UI will be
        stored in your project directory. However, you can run it then change the working directory via the Setup tab in
        the UI.
    </para>
    <para>The UI displays 4 tabs along the top and an output window along the bottom.</para>
    <section>
        <title>Task Tree</title>
        <para>
            The Task Tree shows a hierarchical display of all projects and their tasks.
            Double clicking a task executes it.
        </para>
        <para>
            There is also a filter so that uncommon tasks can be hidden. You can toggle the filter via the Filter button. 
            Editing the filter allows you to configure which tasks and projects are shown. Hidden tasks show up in red.
            Note: newly created tasks will show up by default (versus being hidden by default).
        </para>
        <para>The Task Tree context menu provides the following options:</para>
        <itemizedlist>
            <listitem><para>Execute ignoring dependencies. This does not require dependent projects to be rebuilt (same as the -a option).</para></listitem>
            <listitem><para>Add tasks to the favorites (see Favorites tab)</para></listitem>
            <listitem><para>Hide the selected tasks. This adds them to the filter.</para></listitem>
            <listitem><para>Edit the build.gradle file.
                Note: this requires Java 1.6 or higher and requires that you have .gradle files associated in your OS.
            </para></listitem>
        </itemizedlist>        
    </section>
    <section>
        <title>Favorites</title>
        <para>
            The Favorites tab is a good place to store commonly-executed commands. These can be complex commands
            (anything that's legal to Gradle) and you can provide them with a display name. This is useful for creating,
            say, a custom build command that explicitly skips tests, documentation, and samples that you could call
            “fast build”.
        </para>
        <para>
            You can reorder favorites to your liking and even export them to disk so they can imported by others.
            If you edit them, you are given options to “Always Show Live Output”.
            This only applies if you have “Only Show Output When Errors Occur”.
            This override always forces the output to be shown.
        </para>
    </section>
    <section>
        <title>Command Line</title>
        <para>
            The Command Line tab is where you can execute a single Gradle command directly.
            Just enter whatever you would normally enter after 'gradle' on the command line.  This also provides
            a place to try out commands before adding them to favorites.
        </para>
    </section>
    <section>
        <title>Setup</title>
        <para>The Setup tab allows configuration of some general settings.</para>
        <figure>
            <title>GUI Setup</title>
            <imageobject>
                <imagedata fileref="img/guiSetup.png" width="586px" depth="597px"/>
            </imageobject>
        </figure>

        <itemizedlist>
            <listitem>
                <para>Current Directory</para>
                <para>Defines the root directory of your Gradle project (typically where build.gradle is located).</para>
            </listitem>

            <listitem>
                <para>Stack Trace Output</para>
                <para>
                    This determines how much information to write out in stack traces when errors occur.
                    Note: if you specify a stack trace level on either the Command Line or Favorites tab, it will override
                    this stack trace level.
                </para>
            </listitem>

            <listitem>
                <para>Only Show Output When Errors Occur</para>
                <para>Enabling this option hides any output when a task is executed unless the build fails.</para>
            </listitem>

            <listitem>
                <para>Use Custom Gradle Executor - Advanced feature</para>
                <para>
                    This provides you with an alternate way to launch Gradle commands.
                    This is useful if your project requires some extra setup that is done inside another batch file or shell script
                    (such as specifying an init script).
                </para>
            </listitem>
        </itemizedlist>

    </section>
</chapter>
