<type>documentation</type>
<domain>proj</domain>
<id>file-properties</id>
<title>File Properties</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>per+</product>

Properties can be set for individual files to define how Wing reads and inspects the
file, how it is displayed in the editor, and to override some of the properties in
`Project Properties <ref:proj/project-properties>`__  when the file
~~~if WINGPRO:
is debugged, executed, or run as a test.
~~~
~~~if not WINGPRO:
is debugged or executed.
~~~

File properties are set by right-clicking on a file in the editor and selecting
``Properties``, or by by right-clicking on the ``Project`` tool and selecting ``File
Properties``.

Any string value for a property may contain environment and special variable 
references, as described in `Environment Variable Expansion <ref:proj/variable-expansion>`__.

File Attributes
...............

Properties on this tab affect how Wing reads and inspects the file:

**File Type** specifies the file type for a given file, overriding the type determined
automatically from its file extension and/or content. This property should be used only
when the `Files > Files Types > Extra File Types
<script:show_preferences_gui#prefname="main.extra-mime-types">`__ preference cannot be
used to map the file extension to a mime type.

**Encoding** specifies the text encoding for a file when it cannot be determined from the
file's contents. For Python code, it is better to use a `PEP 263
<https://www.python.org/dev/peps/pep-0263/>`__ ``coding`` comment, rather than setting
this property, and in almost all cases the encoding should be ``utf-8``. Similarly, the
standard encoding specifier should be used in HTML, XML, and gettext PO files. This is
because saving a file without specifying the encoding inside the file may make it
impossible for other editors or other Wing projects to read the file. Wing stores the
encoding selected by this property in the project, but no mark is written into the source
file itself, except in cases where the selected encoding naturally uses a Byte Order Mark
(BOM), such as for utf_16_le, utf_16_be, utf_32_le, or utf_32_be.

When this property is altered for an already-open file, Wing will ask whether it should
reload the file using the new encoding, save using the new encoding, or to cancel the
change. Choose to reload if the file was opened initially with the wrong encoding.

The encoding cannot be altered with this property if the file contains an encoding
comment. In that case, the file should edited to change the encoding comment and Wing
will save the file using the new encoding.

**Line Ending Style** specifies which type of line ending to use in the file. When
altered, the file will be opened in an editor and converted to the selected style. The
change does not take effect until the file is saved to disk.
  
**Indent Style** can be used in non-Python files to change the type of indent entered into
the file for newly added lines. For Python files, the only way to alter indentation in a
file is with the `Indentation Tool <ref:edit/indentation-manager>`__, accessed from the
``Convert Indents`` button shown next to this property.
  
**Read-only on Disk** changes the file's permissions on disk. Permissions are changed only
for the owner of the file. On Linux and macOS, group and world permissions are never
altered.

Editor
......

These properties define how the file is displayed in the editor:

**Show Whitespace** overrides the `Editor > Show White Space
<script:show_preferences_gui#prefname="edit.show-whitespace">`__ preference on a per-file
basis.  When enabled, Wing shows spaces and tabs as visible characters in the editor.
  
**Show EOL** overrides the `Editor > Show EOL
<script:show_preferences_gui#prefname="edit.show-eol">`__ preference on a per-file basis.
When enabled, Wing shows end-of-line (EOL) characters as visible characters in the editor.

**Show Indent Guides** overrides the `Editor > Indentation > Show Indent Guides
<script:show_preferences_gui#prefname="edit.show-indent-guides">`__ preference on a
per-file basis.  When enabled, Wing shows vertical indent guides in the editor.
  
**Ignore Indent Errors** overrides the `Editor > Indentation > Show Python Indent Warning
Dialog <script:show_preferences_gui#prefname="edit.show-python-indent-warnings">`__
preference on a per-file basis.  When checked, Wing will never report indent errors
for the current file.
  
**Ignore EOL Errors** is used when the project's `Line Ending Policy
<script:view_project_properties#highlighted_attrib="proj.line-ending-policy">`__ is set to
``Warn About Conflicts``, in order to disable warnings for this file.

**Ensure Ending EOL** overrides the `Editor > Ensure File Ends With EOL When Saving 
<script:show_preferences_gui#prefname="edit.ensure-ending-eol-on-save">`__ preference
on a per-file basis.  When enabled, Wing makes sure there is an end-of-line (EOL) at 
the end of any file it saves to disk.

Debug/Execute
.............

This tab is used to control debug and execution environment for the file:

**Environment** specifies the environment to use when debugging or executing the file and
sets run arguments for it. By default, the environment defined in `Project Properties
<ref:proj/project-properties>`__ will be used with the specified run arguments.
Alternatively, the file may be launched as a named module using ``python -m`` with the
specified run arguments or launched with a different environment defined by a `launch
configuration <ref:proj/launch-configs>`__.

**Show this dialog before each run** controls whether this tab is shown in the ``Debug
Environment`` dialog each time this file is debugged.  If run arguments often need to be
changed, it may be easier to use `Named Entry Points <ref:debug/named-entry-points>`__ to
set up different arguments for the same file.

~~~if WINGPRO:
Testing
.......

In Wing Pro, the testing tab contains a subset of the fields described for the
`Project Properties <ref:proj/project-properties>`__ ``Testing`` tab.

**Test Framework** selects which test framework should be used with a test file.

**Environment** specifies the environment and command line arguments to use
when running this file as a test file.

~~~

