<type>how-to</type>
<domain>install</domain>
<id>pygobject</id>
<title>Using Wing with GTK and PyGObject</title>
<date>$Date: 2012-07-03 12:21:21 -0400 (Tue, 03 Jul 2012) $</date>
<product>per+</product>
<summary>Hints for using Wing with GTK via PyGObject.</summary>

.. image:: /images/screenshots/wing7-screenshot-linen.png
  :alt: Wing Screen Shot
  :width: 574
  :height: 423
  :popup: 1

`Wing <https://wingware.com>`__ is a Python IDE that can be used to develop, test, and
debug Python code written for `GTK <https://www.gtk.org/>`__ using `PyGObject
<https://pygobject.readthedocs.io/en/latest/>`__. 

Two versions of Wing are appropriate for use with this document: Wing Pro is the
full-featured Python IDE for professional developers, and Wing Personal is a free
alternative with reduced feature set.

If you do not already have Wing installed, `download it now <https://wingware.com/downloads>`__.

This document describes how to configure Wing for GTK and PyGObject. To get started using
Wing as your Python IDE, please refer to the tutorial in Wing's ``Help`` menu or read the
`Quickstart Guide <ref:howtos/quickstart>`__.

Introduction
------------

PyGObject implements Python bindings for GTK, an open source GUI development toolkit.

While Wing does not provide a GUI builder for GTK, it does provide advanced editing,
debugging, testing, and code inspection capabilities for Python, and it can be used with
other available GUI builders, as described below.

Installation and Configuration
------------------------------

Take the following steps to set up and configure Wing for use with PyGObject:

* Install PyGObject as described in the `PyGObject documentation
  <https://pygobject.readthedocs.io/en/latest/l>`__.

* Install `Wing <https://wingware.com/downloads>`__ if you don't already have it.

* Start Wing from the Start menu on Windows, the Finder or OS X, or by typing
  ``~~FULL_EXECUTABLE~~`` on the command line on Linux.

* Select `Show Python Environment <script:show_python_environment>`__ from the ``Source``
  menu. If the Python version reported there doesn't match the one you're using with
  PyGObject, then select `Project Properties <script:view_project_properties>`__ from the
  ``Project`` menu and set `Python Executable
  <script:view_project_properties#highlighted_attrib="proj.pyexec">`__ to the full path of
  Python interpreter into which you installed PyGObject. This value can be found by running
  Python outside of Wing and executing the following commands interactively::
  
    import sys
    sys.executable

* Locate and open the Python main entry point for your PyGObject-based application and
  then select ``Add Current File`` from the ``Project`` menu to add it to your project.

* Set your Python main entry point for debugging with ``Set Current as Main Entry Point``
  in the ``Debug`` menu.

* Save your project to disk.  Use a name ending in ``.wpr``.

Test Driving the Debugger
-------------------------

Now you're ready to try out the debugger:

Start debugging with the ``Start / Continue`` item in the ``Debug`` menu. Uncheck the
``Show this dialog before each run`` checkbox at the bottom of the dialog that appears and
select ``OK``.

Your application should start up. If its main window doesn't come to front, bring it to
front from your task bar or window manager.

Next locate and open Python source code that you know will be reached when you use
your application and set a breakpoint by clicking on the margin to the left of the code. 
Then trigger the breakpoint by performing an action in your application that results
in execution of the code at that line.

From here, you can step through code or inspect the program state with ``Stack Data`` and
other tools. In Wing Pro, the ``Debug Console`` provides a command line that allows you to
interact with the current stack frame in your debug process. All the debugging tools are
available from the ``Tools`` menu.

See the `Wing Tutorial <ref:intro/tutorial>`__ and `Quick start <ref:howtos/quickstart>`__
for more information.

Improving Auto-Completion
-------------------------

PyGObject uses lazy (on-demand) loading of functionality to speed up startup of
applications that are based on it. This prevents Wing's analysis engine from inspecting
PyGObject-wrapped APIs and thus the IDE fails to offer auto-completion.

To work around this, use `Fakegir <https://github.com/strycore/fakegir>`__, which is a
tool to build a fake Python package of PyGObject modules that can be added to the `Source
Analysis > Advanced > Interface File Path
<script:show_preferences_gui#prefname="pysource.interfaces-path">`__ preference. The
parent directory of the generated gi package should be added; if the defaults are used,
the directory to add is ``~/.cache/fakegir``.

Fakegir's ``README.md`` provides usage details.

Don't add the Fakedir produced package to the ``Python Path`` defined in Wing's ``Project
Properties`` because code will not work if the fake module is actually on ``sys.path``
when importing any PyGObject-provided modules.
    
Once this is done Wing should offer auto-completion for all PyGObject-provided modules and
should be able to execute and debug your code without disruption.

Using a GUI Builder
-------------------

Wing doesn't include a GUI builder for PyGObject but it can be used with an external GUI
builder like Glade. Wing will automatically reload files that are generated by the GUI
builder.

Related Documents
-----------------

For more information see:

* `GTK <https://www.gtk.org/>`__ using `PyGObject <https://pygobject.readthedocs.io/en/latest/>`__ websites.

* `Quickstart Guide <ref:howtos/quickstart>`__ contains additional basic information
  about getting started with Wing.
  
* `Tutorial <ref:intro/tutorial>`__ provides a gentler introduction to Wing's features.

* `Wing Reference Manual <ref:manual>`__ documents Wing in detail.
