<type>documentation</type>
<domain>intro</domain>
<id>tutorial-setup-project</id>
<title>Tutorial: Set Up a Project</title>
<date>$Date$</date>
<product>per+</product>

Now we're ready to get started with some coding. The first step is to set up a project
file so that Wing can find and analyze your source code and store your work across
sessions.

If you haven't already copied the ``tutorials`` directory from your Wing installation,
please do so now as described in `Tutorial: Getting Started
<ref:intro/tutorial-getting-started>`__.

Wing starts up initially with the default project. Instead of using that, create a new
project now with ``New Project`` in the ``Project`` menu. Use the default project type 
``Empty Python Project``, leave the other settings blank, and then click on ``OK``:

.. image:: new-project.png
  :width: 484
  :height: 284
  
Wing will display a confirmation dialog after creating the new blank project:

.. image:: new-project-conf.png
  :width: 500
  :height: 208
  
Click ``Save Now`` to save the new project. Use ``tutorial.wpr`` as the project file name
and place it in the ``tutorial`` directory that you created earlier.

Next, use the ``Add Existing Directory`` item in the ``Project`` menu to add your copy of
the ``tutorials`` directory. Leave the default options checked so that all files in that
directory are added to the project.

.. image:: project.png
  :width: 227
  :height: 219

Note that most of the time when you are creating a project in Wing you will use ``New
Project`` in the ``Project`` menu and not ``Save Project As``, which we've done here just
to keep things simpler for the moment.  We'll come back to this later in the tutorial.

.. note::

  To make it easier to work on source code and read this tutorial at the same time, you may
  want to right-click on the editor tab area and select ``Split Side by Side``.

**Opening Files**

Files in your project can be opened by double-clicking in the `Project
<script:show-panel-project>`__ tool, by typing fragments into the `Open From Project
<script:open-from-project>`__ dialog, and in other ways that will be described later.

Try ``Open From Project`` now, from the ``File`` menu. Type ``ex`` as the file name
fragment and then use the arrow keys and press ``Enter`` to open the file ``example1.py``.
Now try it again with the fragment ``sub ex``. This matches only files with both ``sub``
and ``ex`` in their full path names. In larger projects, ``Open From Project`` is usually
the easiest way to open a file, so you'll probably want to learn the key binding listed
for this command in the ``File`` menu. The binding varies according to which keyboard
personality you have chosen to use.

.. image:: open-from-project.png
  :width: 333
  :height: 320

**Transient, Sticky, and Locked Files**

Wing opens files in one of several modes, in order to keep more relevant files open while
auto-closing others. To see this in action, click on ``os`` in ``import os`` at the top of
``example1.py`` and press ``F4`` to go to the definition of ``os``. The file ``os.py``
will be opened in non-sticky transient mode, so that it is automatically closed in
least-recently-used order when you navigate away from it to other files.

The mode in which a file is opened is indicated with an icon in the top right of the
editor area:

|stickpin-stuck| - The file is sticky and will be kept open until it is closed by the
user.

|stickpin-unstuck| - The file is non-sticky and may be closed when it is no longer 
visible. When a non-sticky transient file is edited, it immediately converts to sticky.

|stickpin-locked| - The file is locked in the editor, so that the editor split will not be
used to display other newly opened files. This mode is only available when multiple
editor splits are present.

.. |stickpin-unstuck| image:: unstuck_pin_16.png
  :class: inline-image
.. |stickpin-stuck| image:: stuck_pin_16.png
  :class: inline-image
.. |stickpin-locked| image:: locked_16.png
  :class: inline-image

Clicking on the stick pin icon toggles between the available modes. Right-clicking on the
icon displays a menu of recently visited files. This contains both non-sticky transient
and sticky files, while the ``Recent`` list in the ``File`` menu contains only sticky
files.

.. image:: history-menu.png
  :width: 242
  :height: 140

The number of non-sticky transient editors to keep open, in addition to those that are
visible, is set with the `Editor > Advanced > Maximum Non-Sticky Editors
<script:show_preferences_gui#prefname="gui.max-non-sticky-editors">`__ preference
(default=5).

This mechanism is also used in multi-file searching, debugging, and other features that
navigate through many files. In general you can ignore the modes and Wing will keep open
the files you are actually working on, while auto-closing those that you have only visited
briefly.

~~~if WINGPRO:
**Shared Project Files**

Wing Pro writes two files for each project, for example ``tutorial.wpr`` and
``tutorial.wpu``. If you plan to use Wing projects with a revision control system such as
``Git``, ``Mercurial``, or ``Perforce``, you should check in only the ``*.wpr`` file. 

See the `Sharing Projects <ref:proj/project-types>`__ documentation page for details.
~~~

