Renamed docs folder
This commit is contained in:
markm
parent
5ab3a06f26
commit
db1d44a7a5
7
doc_build/about.txt
Normal file
7
doc_build/about.txt
Normal file
@ -0,0 +1,7 @@
|
||||
About pywinauto
|
||||
===============
|
||||
|
||||
Pywinauto is a tool to automate Windows dialogs and controls.
|
||||
|
||||
There are also some tests supplied - but these are more
|
||||
applicable to Localisation UI testing.
|
||||
316
doc_src/HowTo.txt
Normal file
316
doc_src/HowTo.txt
Normal file
@ -0,0 +1,316 @@
|
||||
========
|
||||
How To's
|
||||
========
|
||||
|
||||
How to sepcify an usable Application instance
|
||||
---------------------------------------------
|
||||
An ``Application()`` instance is the point of contact for all work
|
||||
with the app you are automating. So the Application instance needs
|
||||
to be connected to a process. There are two ways of doing this::
|
||||
|
||||
start_(self, cmd_line, timeout = app_start_timeout):
|
||||
|
||||
or ::
|
||||
|
||||
connect_(self, **kwargs):
|
||||
|
||||
|
||||
``start_()`` is used when the application is not running and you
|
||||
need to start it. Use it in the following way::
|
||||
|
||||
app = Application()
|
||||
app.start_(r"c:\path\to\your\application -a -n -y --arguments")
|
||||
|
||||
The timeout parameter is optional, it should only be necessary to use
|
||||
it if the application takes a long time to start up.
|
||||
|
||||
``connect_()`` is used when the application to be automated is already
|
||||
running. To specify a an already runing application you need to specify
|
||||
one of the following:
|
||||
|
||||
:process: the process id of the application, e.g.
|
||||
|
||||
::
|
||||
|
||||
app = Application()
|
||||
app.connect_(process = 2341)
|
||||
|
||||
|
||||
:handle: The windows handle of a window of the application, e.g.
|
||||
|
||||
::
|
||||
|
||||
app = Application()
|
||||
app.connect_(handle = 0x010f0c)
|
||||
|
||||
|
||||
:path: The path of the executable of the process (``GetModuleFileNameEx``
|
||||
is used to find the path of each process and compared against
|
||||
the value passed in) e.g.
|
||||
|
||||
::
|
||||
|
||||
app = Application()
|
||||
app.connect_(path = r"c:\windows\system32\notepad.exe")
|
||||
|
||||
or any combination of the parameters that specify a window, these get
|
||||
passed to the ``findwindows.find_windows()`` function. e.g. ::
|
||||
|
||||
app = Application()
|
||||
app.connect_(title_re = ".*Notepad", class_name = "Notepad")
|
||||
|
||||
|
||||
|
||||
How to sepcify a dialog of the application
|
||||
------------------------------------------
|
||||
Once the application instance knows what application it is connected to
|
||||
a dialog to work on needs to be specified.
|
||||
|
||||
There are many different ways of doing this. The most common will be
|
||||
using item or attribute access to select a dialog based on it's title. e.g ::
|
||||
|
||||
dlg = app.Notepad
|
||||
|
||||
or equivalently ::
|
||||
|
||||
dlg = app['Notepad']
|
||||
|
||||
|
||||
The next easiest method is to ask for the ``top_window_()`` e.g. ::
|
||||
|
||||
dlg = app.top_window_()
|
||||
|
||||
This will return the window that has the highest Z-Order of the top-level
|
||||
windows of the application.
|
||||
|
||||
**Note**: This is currently fairly untested so I am not sure it will
|
||||
return the correct window. It will definitely be a top level window of
|
||||
the application - it just might not be the one highest in the Z-Order.
|
||||
|
||||
If this is not enough control they you can use the same parameters as
|
||||
can be passed to ``findwindows.find_windows()`` e.g. ::
|
||||
|
||||
dlg = app.window_(title_re = "Page Setup", class_name = "#32770")
|
||||
|
||||
Finally to have the most control you can use ::
|
||||
|
||||
dialogs = app.windows_()
|
||||
|
||||
this will return a list of all the visible, enabled, top level windows
|
||||
of the application. You can then use some of the methods in ``handleprops``
|
||||
module select the dialog you want. Once you have the handle you need
|
||||
then use ::
|
||||
|
||||
Application.window_(handle = win)
|
||||
|
||||
|
||||
How to specify a control on a dialog
|
||||
------------------------------------
|
||||
|
||||
There are a number of ways to specify a control, the simplest are::
|
||||
|
||||
app.dlg.control
|
||||
app['dlg']['control']
|
||||
|
||||
|
||||
The 2nd is better for non English OS's where you need to pass unicode
|
||||
strings e.g. app[u'your dlg title'][u'your ctrl title']
|
||||
|
||||
The code builds up multiple identifiers for each control from the following:
|
||||
|
||||
+ title
|
||||
+ friendly class
|
||||
+ title + friendly class
|
||||
|
||||
If the control's text is empty (after removing non char characters) text is
|
||||
not used. Instead we look for the closest control above and to the right fo
|
||||
the contol. And append the friendly class. So the list becomes
|
||||
|
||||
+ friendly class
|
||||
+ closest text + friendly class
|
||||
|
||||
Once a set of identifiers has been created for all controls in the dialog
|
||||
we disambiguate them.
|
||||
|
||||
|
||||
|
||||
|
||||
use the `WindowSpecification.print_control_identifiers()` method
|
||||
|
||||
e.g. ::
|
||||
|
||||
app.YourDialog.print_control_identifiers()
|
||||
|
||||
Sample output::
|
||||
|
||||
Button - Paper (L1075, T394, R1411, B485)
|
||||
'PaperGroupBox' 'Paper' 'GroupBox'
|
||||
Static - Si&ze: (L1087, T420, R1141, B433)
|
||||
'SizeStatic' 'Static' 'Size'
|
||||
ComboBox - (L1159, T418, R1399, B439)
|
||||
'ComboBox' 'SizeComboBox'
|
||||
Static - &Source: (L1087, T454, R1141, B467)
|
||||
'Source' 'Static' 'SourceStatic'
|
||||
ComboBox - (L1159, T449, R1399, B470)
|
||||
'ComboBox' 'SourceComboBox'
|
||||
Button - Orientation (L1075, T493, R1171, B584)
|
||||
'GroupBox' 'Orientation' 'OrientationGroupBox'
|
||||
Button - P&ortrait (L1087, T514, R1165, B534)
|
||||
'Portrait' 'RadioButton' 'PortraitRadioButton'
|
||||
Button - L&andscape (L1087, T548, R1165, B568)
|
||||
'RadioButton' 'LandscapeRadioButton' 'Landscape'
|
||||
Button - Margins (inches) (L1183, T493, R1411, B584)
|
||||
'Marginsinches' 'MarginsinchesGroupBox' 'GroupBox'
|
||||
Static - &Left: (L1195, T519, R1243, B532)
|
||||
'LeftStatic' 'Static' 'Left'
|
||||
Edit - (L1243, T514, R1285, B534)
|
||||
'Edit' 'LeftEdit'
|
||||
Static - &Right: (L1309, T519, R1357, B532)
|
||||
'Right' 'Static' 'RightStatic'
|
||||
Edit - (L1357, T514, R1399, B534)
|
||||
'Edit' 'RightEdit'
|
||||
Static - &Top: (L1195, T550, R1243, B563)
|
||||
'Top' 'Static' 'TopStatic'
|
||||
Edit - (L1243, T548, R1285, B568)
|
||||
'Edit' 'TopEdit'
|
||||
Static - &Bottom: (L1309, T550, R1357, B563)
|
||||
'BottomStatic' 'Static' 'Bottom'
|
||||
Edit - (L1357, T548, R1399, B568)
|
||||
'Edit' 'BottomEdit'
|
||||
Static - &Header: (L1075, T600, R1119, B613)
|
||||
'Header' 'Static' 'HeaderStatic'
|
||||
Edit - (L1147, T599, R1408, B619)
|
||||
'Edit' 'TopEdit'
|
||||
Static - &Footer: (L1075, T631, R1119, B644)
|
||||
'FooterStatic' 'Static' 'Footer'
|
||||
Edit - (L1147, T630, R1408, B650)
|
||||
'Edit' 'FooterEdit'
|
||||
Button - OK (L1348, T664, R1423, B687)
|
||||
'Button' 'OK' 'OKButton'
|
||||
Button - Cancel (L1429, T664, R1504, B687)
|
||||
'Cancel' 'Button' 'CancelButton'
|
||||
Button - &Printer... (L1510, T664, R1585, B687)
|
||||
'Button' 'Printer' 'PrinterButton'
|
||||
Button - Preview (L1423, T394, R1585, B651)
|
||||
'Preview' 'GroupBox' 'PreviewGroupBox'
|
||||
Static - (L1458, T456, R1549, B586)
|
||||
'PreviewStatic' 'Static'
|
||||
Static - (L1549, T464, R1557, B594)
|
||||
'PreviewStatic' 'Static'
|
||||
Static - (L1466, T586, R1557, B594)
|
||||
'Static' 'BottomStatic'
|
||||
|
||||
This exmple has been taken from test_application.py
|
||||
|
||||
**Note** The identifiers printed by this method have been run through
|
||||
the process that makes the identifier unique. So if you have 2 edit boxes,
|
||||
they will both have "Edit" listed in their identifiers. In reality though
|
||||
the first one can be refered to as "Edit", "Edit0", "Edit1" and the 2nd
|
||||
should be refered to as "Edit2"
|
||||
|
||||
**Note** You do not have to be exact!. Say we take an instance from the
|
||||
example above::
|
||||
|
||||
Button - Margins (inches) (L1183, T493, R1411, B584)
|
||||
'Marginsinches' 'MarginsinchesGroupBox' 'GroupBox'
|
||||
|
||||
Let's say that you don't like any of these
|
||||
|
||||
- ``GroupBox`` - too generic, it could be any group box
|
||||
- ``Marginsinches`` and ``MarginsinchesGroupBox`` - these just don'
|
||||
look right, it would be nicer to leave out the 'inches' part
|
||||
|
||||
Well you CAN! The code does a best match on the identifer you use against
|
||||
all the available identifiers in the dialog.
|
||||
|
||||
For example if you break into the debugger you can see how different
|
||||
identifiers can be used::
|
||||
|
||||
(Pdb) print app.PageSetup.Margins.Text()
|
||||
Margins (inches)
|
||||
(Pdb) print app.PageSetup.MarginsGroupBox.Text()
|
||||
Margins (inches)
|
||||
|
||||
|
||||
And this will also cater for typos. Though you still have to be careful
|
||||
as if there are 2 similar identifiers in the dialog the typo you have
|
||||
used might be more similar to another control then the one you were
|
||||
thinking of.
|
||||
|
||||
How to use pywinauto with application languages other than English
|
||||
------------------------------------------------------------------
|
||||
Because Python does not support unicode identifiers in code
|
||||
you cannot use attribute access to reference a control so
|
||||
you would either have to use item access or make an explicit
|
||||
calls to ``window_()``.
|
||||
|
||||
So instead of writing::
|
||||
|
||||
app.dialog_ident.control_ident.Click()
|
||||
|
||||
You would have to write::
|
||||
|
||||
app['dialog_ident']['control_ident'].Click()
|
||||
|
||||
Or use ``window_()`` explictly::
|
||||
|
||||
app.window_(title_re = "NonAsciiCharacters").window_(title = "MoreNonAsciiCharacters").Click()
|
||||
|
||||
To see an example of this see ``examples\MiscExamples.py.GetInfo()``
|
||||
|
||||
|
||||
|
||||
How to deal with controls that do not respond as expected (e.g. OwnerDraw Controls)
|
||||
------------------------------------------------------------------------------------
|
||||
|
||||
Some controls (especially Ownerdrawn controls) do not respond to events as
|
||||
expected. For example if you look at any HLP file and go to the Index Tab (click
|
||||
'Search' button) you will see a listbox. Running Spy or Winspector on this
|
||||
will show you that it is indeed a list box - but it is ownerdrawn. This means
|
||||
that the developer has told Windows that they will override how items are displayed
|
||||
and do it themselves. And in this case they have made it so that strings cannot be
|
||||
retrieved :-(.
|
||||
|
||||
So what problems does this cause? ::
|
||||
|
||||
app.HelpTopics.ListBox.Texts() # 1
|
||||
app.HelpTopics.ListBox.Select("ItemInList") # 2
|
||||
|
||||
|
||||
1. Will return a list of empty strings, all this means is that pywinauto has not
|
||||
been able to get the strings in the listbox
|
||||
|
||||
2. This will fail with an IndexError because the Select(string) method of a ListBox
|
||||
looks for the item in the Texts to know the index of the item that it should select.
|
||||
|
||||
The following workaround will work on this control ::
|
||||
|
||||
app.HelpTopics.ListBox.Select(1)
|
||||
|
||||
This will select the 2nd item in the listbox, because it is not a string lookup
|
||||
it works correctly.
|
||||
|
||||
Unfortunately not even this will always work. The developer can make it so that the
|
||||
control does not respond to standard events like Select. In this case the only way
|
||||
you can select items in the listbox is by using the keyboard simulation of TypeKeys().
|
||||
|
||||
This allows you to send any keystrokes to a control. So to select the 3rd item you
|
||||
would use::
|
||||
|
||||
app.Helptopics.ListBox1.TypeKeys("{HOME}{DOWN 2}{ENTER}")
|
||||
|
||||
|
||||
- ``{HOME}`` will make sure that the first item is highlighted.
|
||||
- ``{DOWN 2}`` will then move the highlight down 2 items
|
||||
- ``{ENTER}`` will select the highlighted item
|
||||
|
||||
If your application made extensive use of a similar control type then you could
|
||||
make using it easier by deriving a new class from ListBox, that could use extra
|
||||
knowledge about your particular application. For example in the WinHelp example
|
||||
evertime an item is highlighted in the list view, it's text is inserted into the
|
||||
Edit control above the list, and you CAN get the text of the item from there e.g. ::
|
||||
|
||||
# print the text of the item currently selected in the list box
|
||||
# (as long as you are not typing into the Edit control!)
|
||||
print app.HelpTopics.Edit.Texts()[1]
|
||||
|
||||
88
doc_src/index.txt
Normal file
88
doc_src/index.txt
Normal file
@ -0,0 +1,88 @@
|
||||
pywinauto
|
||||
(c) Mark Mc Mahon 2006
|
||||
Released under the LGPL licence
|
||||
|
||||
|
||||
What is it
|
||||
----------
|
||||
pywinauto is a set of python modules to automate the Microsoft Windows GUI.
|
||||
At it's simplest it allows you to send mouse and keyboard actions to windows
|
||||
dialogs and controls.
|
||||
|
||||
|
||||
Installation
|
||||
------------
|
||||
- Unzip the pywinauto zip file to a folder.
|
||||
- Install the following Python packages
|
||||
- ctypes http://starship.python.net/crew/theller/ctypes/
|
||||
- Sendkeys http://www.rutherfurd.net/python/sendkeys/index.html
|
||||
- *Optional* PIL http://www.pythonware.com/products/pil/index.htm
|
||||
- *Optional* elementtree http://effbot.org/downloads/
|
||||
|
||||
To check you have it installed correctly
|
||||
Run Python ::
|
||||
|
||||
>>> import application
|
||||
>>> app = application.Application()._start("notepad")
|
||||
>>> app.notepad.TypeKeys("%FX")
|
||||
|
||||
|
||||
Where to start
|
||||
--------------
|
||||
Look at the examples provided in test_application.py
|
||||
There are examples in there to work with Notepad and MSPaint.
|
||||
|
||||
|
||||
How does it work
|
||||
----------------
|
||||
A lot is done through attribute access (__getattr__) for each class. For example
|
||||
when you get the attribute of an Application or Dialog object it looks for a
|
||||
dialog or control (respectively).
|
||||
|
||||
::
|
||||
|
||||
myapp.Notepad # looks for a Window/Dialog of your app that has a title 'similar'
|
||||
# to "Notepad"
|
||||
|
||||
myapp.PageSetup.OK # looks first for a dialog with a title like "PageSetup"
|
||||
# then it looks for a control on that dialog with a title
|
||||
# like "OK"
|
||||
|
||||
This attribute resolution is delayed (currently a hard coded amount of time) until
|
||||
it succeeds. So for example if you Select a menu option and then look for the
|
||||
resulting dialog e.g. ::
|
||||
|
||||
app.Notepad.MenuSelect("File->SaveAs")
|
||||
app.SaveAs.ComboBox5.Select("UTF-8")
|
||||
app.SaveAs.edit1.SetText("Example-utf8.txt")
|
||||
app.SaveAs.Save.Click()
|
||||
|
||||
At the 2nd line the SaveAs dialog might not be open by the time this line is
|
||||
executed. So what happens is that we wait until we have a control to resolve
|
||||
before resolving the dialog. At that point if we can't find a SaveAs dialog with
|
||||
a ComboBox5 control then we wait a very short period of time and try again,
|
||||
this is repeated up to a maximum time (currently 1 second!)
|
||||
|
||||
This avoid the user having to use time.sleep or a "WaitForDialog" function.
|
||||
|
||||
|
||||
Some similar tools for comparison
|
||||
---------------------------------
|
||||
* Python tools
|
||||
- Watsup
|
||||
- winGuiAuto
|
||||
|
||||
* Other scripting language tools
|
||||
- Perl Win32::GuiTest
|
||||
- Ruby GuiTest
|
||||
- others?
|
||||
|
||||
* Other free tools
|
||||
- AutoIt
|
||||
- See collection at:
|
||||
|
||||
* Commercial tools
|
||||
- WinRunner
|
||||
- SilkTest
|
||||
- Visual Test
|
||||
- Many Others
|
||||
Loading…
Reference in New Issue
Block a user