<commit_before>==========================
Getting Started Guide
==========================

Once you have installed pywinauto - how do you get going?
The very first necessary thing is to determine which accessibility 
technology (pywinauto's backend) could be used for your application.

The list of supported accessibility technologies on Windows:

 * **Win32 API** (``backend="win32"``) - a default backend for now
    - MFC, VB6, VCL, simple WinForms controls and most of the old legacy apps

 * **MS UI Automation** (``backend="uia"``)
    - WinForms, WPF, Store apps, Qt5, browsers
    
    Notes: Chrome requires ``--force-renderer-accessibility`` cmd flag before 
    starting. Custom properties and controls are not supported because of 
    comtypes Python library restrictions.

Not supported: Java AWT/Swing, GTK+, Tkinter.

AT SPI on Linux and Apple Accessibility API are in the long term plans so far.


GUI Objects Inspection / Spy Tools
----------------------------------
If you're still not sure which backend is most appropriate for you 
then try using object inspection / spy tools that are available for free:
download them from GitHub repo gui-inspect-tool_.

.. _gui-inspect-tool: https://github.com/blackrosezy/gui-inspect-tool

 * **Spy++** is included into MS Visual Studio distribution (even Express or 
   Community) and is accessible through Start menu. It uses Win32 API. It means 
   if Spy++ can show all the controls the ``"win32"`` backend is what you need. 
   *AutoIt Window Info* tool is a kind of Spy++ clone.


 * **Inspect.exe** is another great tool created by Microsoft. It's included into
   Windows SDK so that it can be found in the following location on x64 Windows: ::

        C:\Program Files (x86)\Windows Kits\<winver>\bin\x64


   Switch Inspect.exe into **UIA mode** (using MS UI Automation). If it can 
   show more controls and their properties than Spy++, probably the ``"uia"`` 
   backend is your choice.

If some or all controls are not visible to all the inspection tools it's still 
possible to control the application by generating mouse and keyboard events 
using basic modules mouse_ and keyboard_.

.. _mouse: code/pywinauto.mouse.html
.. _keyboard: code/pywinauto.keyboard.html


Entry Points for Automation
---------------------------

So you have an application, you know it supports one of the mentioned 
accessibility technologies. What's the next?

First you should start your application or connect to an existing app
instance. It can be done with an ``Application`` object. This is not just
a clone of ``subprocess.Popen``, but an entry point for further automation
limiting all the scope by process boundaries. It's useful to control
potentially few instances of an application (you work with one instance
not bothering another ones).

 ::

    from pywinauto.application import Application
    app = Application(backend="uia").start('notepad.exe')
    <commit_msg>Add py_inspect link to the Getting Started Guide.<commit_after>==========================
Getting Started Guide
==========================

Once you have installed pywinauto - how do you get going?
The very first necessary thing is to determine which accessibility 
technology (pywinauto's backend) could be used for your application.

The list of supported accessibility technologies on Windows:

 * **Win32 API** (``backend="win32"``) - a default backend for now
    - MFC, VB6, VCL, simple WinForms controls and most of the old legacy apps

 * **MS UI Automation** (``backend="uia"``)
    - WinForms, WPF, Store apps, Qt5, browsers
    
    Notes: Chrome requires ``--force-renderer-accessibility`` cmd flag before 
    starting. Custom properties and controls are not supported because of 
    comtypes Python library restrictions.

AT SPI on Linux and Apple Accessibility API are in the long term plans so far.


GUI Objects Inspection / Spy Tools
----------------------------------
If you're still not sure which backend is most appropriate for you 
then try using object inspection / spy tools that are available for free:
download them from GitHub repo gui-inspect-tool_.

.. _gui-inspect-tool: https://github.com/blackrosezy/gui-inspect-tool

 * **Spy++** is included into MS Visual Studio distribution (even Express or 
   Community) and is accessible through Start menu. It uses Win32 API. It means 
   if Spy++ can show all the controls the ``"win32"`` backend is what you need. 
   *AutoIt Window Info* tool is a kind of Spy++ clone.


 * **Inspect.exe** is another great tool created by Microsoft. It's included into
   Windows SDK so that it can be found in the following location on x64 Windows: ::

        C:\Program Files (x86)\Windows Kits\<winver>\bin\x64


   Switch Inspect.exe into **UIA mode** (using MS UI Automation). If it can 
   show more controls and their properties than Spy++, probably the ``"uia"`` 
   backend is your choice.

 * `py_inspect`_ is a prototype of multi-backend spy tool based on pywinauto.
   Switching between available backends can show you a difference in
   hierarchies with "win32" and "uia" backends. **py_inspect** is a future
   replacement of `SWAPY`_ which supports "win32" backend only at the moment
   when pywinauto==0.5.4 was out. Initial implementation of py_inspect contains
   just about 150 lines of code thanks to modern pywinauto 0.6.0+ architecture.

.. _`py_inspect`: https://github.com/pywinauto/py_inspect
.. _`SWAPY`: https://github.com/pywinauto/SWAPY

If some or all controls are not visible to all the inspection tools it's still 
possible to control the application by generating mouse and keyboard events 
using basic modules mouse_ and keyboard_.

.. _mouse: code/pywinauto.mouse.html
.. _keyboard: code/pywinauto.keyboard.html


Entry Points for Automation
---------------------------

So you have an application, you know it supports one of the mentioned 
accessibility technologies. What's the next?

First you should start your application or connect to an existing app
instance. It can be done with an ``Application`` object. This is not just
a clone of ``subprocess.Popen``, but an entry point for further automation
limiting all the scope by process boundaries. It's useful to control
potentially few instances of an application (you work with one instance
not bothering another ones).

 ::

    from pywinauto.application import Application
    app = Application(backend="uia").start('notepad.exe')
    
{'fraction_non_alphanumeric': 0.104199066874028, 'fraction_numerical': 0.006998444790046656, 'mean_word_length': 3.670297748729121, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1517419', 'n_tokens_mistral': 1737, 'n_tokens_neox': 1637, 'n_words': 834}