# WinGrab
A simple tool to get the PID of the window under the mouse cursor, implemented in **Python**.
`wingrab` is implemented in the Python language, supports running directly and integrating into Python code,
and currently only supports Windows.
## Installation
### From pip
```bash
pip install wingrab
```
### From source code
Download the [wingrab.py](wingrab%2Fwingrab.py) and [cursor.cur](wingrab%2Fcursor.cur) files and place them in your project directory,
ensuring the `cursor.cur` file is in the same location as `wingrab.py`.
## Usage
### Run directly in CLI
**Ensure the `wingrab` package is installed via pip**, You can then run it directly in the CLI using:
```bash
py-wingrab
```
or
```bash
py-wingrab grab
```
You can run it together with some powershell commands like `Get-Process`:
```bash
Get-Process -Id $(py-wingrab)
```
If `wingrab` crashes, and the mouse cursor has changed to a cross,
run the `cleanup` command to try to restore the mouse cursor.
```bash
py-wingrab cleanup
```
### Integrate into your Python code
It is very simple to integrate `wingrab` into your Python code,
you just need to call the `grab` function in the `wingrab` package.
```python
from wingrab import wingrab
pid = wingrab.grab()
```
The `grab` function returns the PID of the window under the cursor as an integer.
Note that the `grab` will block the current thread until the user clicks the left mouse button,
so if you want to use it in a GUI application,
you had better call the `grab` function in a sub thread. (See examples below)
**Note: `wingrab` can be used in both the main thread and the sub threads,
but if you want to use it in a sub thread, make sure to call `wingrab.grab()` in the main thread first.**
To restore the global mouse cursor to the default when `wingrab` crashes, invoke the `cleanup` function.
```python
from wingrab import wingrab
wingrab.cleanup()
```
## Examples
`examples` directory contains several examples which demonstrate usage and integration methods.
You can run them directly after installing the package:
- [pyqt5_example.py](examples%2Fpyqt5_example.py): An example of using `wingrab` in the main thread of a PyQt5 application.
- [pyqt5_example_run_in_sub_thread.py](examples%2Fpyqt5_example_run_in_sub_thread.py): An example of using `wingrab` in the sub thread of a PyQt5 application.
- [tkinter_example.py](examples%2Ftkinter_example.py): An example of using `wingrab` in a Tkinter application.
- [run_in_sub_thread.py](examples%2Frun_in_sub_thread.py): An example of using `wingrab` in a sub thread of a console application.
Raw data
{
"_id": null,
"home_page": "https://github.com/JezaChen/WinGrab",
"name": "WinGrab",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.7",
"maintainer_email": null,
"keywords": "win32api windows gui",
"author": "Jianzhang Chen",
"author_email": "jezachen@163.com",
"download_url": "https://files.pythonhosted.org/packages/0e/6a/2bdabce8e5f9171b6c9c35a7843a3ce959bac9969ec7729e0041d578bbf2/wingrab-0.0.2.tar.gz",
"platform": null,
"description": "# WinGrab\r\nA simple tool to get the PID of the window under the mouse cursor, implemented in **Python**.\r\n\r\n`wingrab` is implemented in the Python language, supports running directly and integrating into Python code, \r\nand currently only supports Windows.\r\n\r\n## Installation\r\n### From pip\r\n\r\n```bash\r\npip install wingrab\r\n```\r\n\r\n### From source code\r\n\r\nDownload the [wingrab.py](wingrab%2Fwingrab.py) and [cursor.cur](wingrab%2Fcursor.cur) files and place them in your project directory, \r\nensuring the `cursor.cur` file is in the same location as `wingrab.py`.\r\n\r\n## Usage\r\n\r\n### Run directly in CLI\r\n\r\n**Ensure the `wingrab` package is installed via pip**, You can then run it directly in the CLI using:\r\n\r\n```bash\r\npy-wingrab\r\n```\r\n\r\nor\r\n\r\n```bash\r\npy-wingrab grab\r\n```\r\n\r\nYou can run it together with some powershell commands like `Get-Process`:\r\n\r\n```bash\r\nGet-Process -Id $(py-wingrab)\r\n```\r\n\r\nIf `wingrab` crashes, and the mouse cursor has changed to a cross, \r\nrun the `cleanup` command to try to restore the mouse cursor.\r\n\r\n```bash\r\npy-wingrab cleanup\r\n```\r\n\r\n### Integrate into your Python code\r\n\r\nIt is very simple to integrate `wingrab` into your Python code,\r\nyou just need to call the `grab` function in the `wingrab` package.\r\n\r\n```python\r\nfrom wingrab import wingrab\r\n\r\npid = wingrab.grab()\r\n```\r\n\r\nThe `grab` function returns the PID of the window under the cursor as an integer.\r\n\r\nNote that the `grab` will block the current thread until the user clicks the left mouse button,\r\nso if you want to use it in a GUI application,\r\nyou had better call the `grab` function in a sub thread. (See examples below)\r\n\r\n**Note: `wingrab` can be used in both the main thread and the sub threads, \r\nbut if you want to use it in a sub thread, make sure to call `wingrab.grab()` in the main thread first.**\r\n\r\nTo restore the global mouse cursor to the default when `wingrab` crashes, invoke the `cleanup` function.\r\n\r\n```python\r\nfrom wingrab import wingrab\r\n\r\nwingrab.cleanup()\r\n```\r\n\r\n## Examples\r\n\r\n`examples` directory contains several examples which demonstrate usage and integration methods. \r\nYou can run them directly after installing the package:\r\n\r\n- [pyqt5_example.py](examples%2Fpyqt5_example.py): An example of using `wingrab` in the main thread of a PyQt5 application.\r\n- [pyqt5_example_run_in_sub_thread.py](examples%2Fpyqt5_example_run_in_sub_thread.py): An example of using `wingrab` in the sub thread of a PyQt5 application.\r\n- [tkinter_example.py](examples%2Ftkinter_example.py): An example of using `wingrab` in a Tkinter application.\r\n- [run_in_sub_thread.py](examples%2Frun_in_sub_thread.py): An example of using `wingrab` in a sub thread of a console application.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "WinGrab: A simple tool to get the PID of the window under the cursor.",
"version": "0.0.2",
"project_urls": {
"Homepage": "https://github.com/JezaChen/WinGrab"
},
"split_keywords": [
"win32api",
"windows",
"gui"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4425a40ef8490616cdbd801d84f6f363d19046eea046d7780eb1cbe6d5403b38",
"md5": "a26fb469f400873887da0175bfd1a31a",
"sha256": "e0f517bb8fa17cf9fe147bfb62a5fbb657fc703d3f85edc99fe4ef72df7d29ff"
},
"downloads": -1,
"filename": "WinGrab-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a26fb469f400873887da0175bfd1a31a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.7",
"size": 8228,
"upload_time": "2024-12-14T14:35:44",
"upload_time_iso_8601": "2024-12-14T14:35:44.620091Z",
"url": "https://files.pythonhosted.org/packages/44/25/a40ef8490616cdbd801d84f6f363d19046eea046d7780eb1cbe6d5403b38/WinGrab-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0e6a2bdabce8e5f9171b6c9c35a7843a3ce959bac9969ec7729e0041d578bbf2",
"md5": "fcfd806cad739909b696b47a75931120",
"sha256": "383177b663f15903c9188cd0dbb3f5d7514b315cf2a5b4035779557db7d84daf"
},
"downloads": -1,
"filename": "wingrab-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "fcfd806cad739909b696b47a75931120",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.7",
"size": 7495,
"upload_time": "2024-12-14T14:35:47",
"upload_time_iso_8601": "2024-12-14T14:35:47.237307Z",
"url": "https://files.pythonhosted.org/packages/0e/6a/2bdabce8e5f9171b6c9c35a7843a3ce959bac9969ec7729e0041d578bbf2/wingrab-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-14 14:35:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "JezaChen",
"github_project": "WinGrab",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "wingrab"
}
JSON
