# PyWinBox
[](https://github.com/Kalmat/PyWinBox/actions/workflows/type-checking.yml)
[](https://badge.fury.io/py/PyWinBox)
Cross-Platform and multi-monitor module which allows to manage window areas (position and
size) and all their properties, as well as any rectangular area.
## Rectangular areas
You just need to instantiate the PyWinBox class, passing custom callbacks to be called when any property is
queried (onQuery) or set (onSet).
myBox = pywinbox.PyWinBox(onQuery=customOnQuery, onSet=customOnSet)
For rectangular areas, it is necessary to pass custom (not default) callbacks which actually manage the box struct values,
or the struct will be empty and useless.
## Window areas
To manage window areas, you need to also pass the window handle when instantiating the class, in the following formats:
- MS-Windows: integer (window id) or str (as returned by, e.g., PyQt's winId() method)
- Linux: integer (window id) or X-Window object
- macOS / foreign window: in case you want to manage a window from another application, you must pass target app and window names, as a tuple of strings (appName, windowTitle)
- macOS / own window: if you want to manage your own application window, you must pass NSWindow() object
(Search for cross-platform modules if you need a cross-platform handle. For instance, you can get this kind of handles
using PyWinCtl's getHandle(), getAppName() or title methods)
In this case, you can use the default methods to manage the window when its properties are queried or set:
- default OnQuery: Will update the window position and size values when any property is queried
- default OnSet: Will move and/or resize the window when any property is set
To use default methods, just pass them as None, like this:
myBox = pywinbox.PyWinBox(onQuery=None, onSet=None, handle=windowHandle)
Of course, you can also define (and pass) your own custom functions if you need to perform other actions on these events.
In this case, if your custom functions do not properly retrieve or set the actual window position and size, the
information contained in the PyWinBox class, and returned by all properties, will likely become obsolete. So, you can
use both in your custom callback:
def customOnQuery():
currBox = myBox.onQuery() # This will retrieve the current window's box
# ... do your stuff ...
return currBox
def customOnSet(newBox: Box):
myBox.onSet(newBox) # This will actually move/resize the window
# ... do your stuff ...
myBox = pywinbox.PyWinBox(onQuery=customOnQuery, onSet=customOnSet, handle=windowHandle)
## Class Properties
left, top, right, bottom
size, width, height
topleft, bottomleft, topright, bottomright
midtop, midleft, midbottom, midright
center, centerx, centery
box (left, top, width, height)
rect (left, top, right, bottom)
## Data Structs
These are useful data structs (named tuples, actually) you can use to better manage the values:
Box: left, top, width, height
Rect: left, top, right, bottom
Size: width, height
Point: x, y
## INSTALL <a name="install"></a>
To install this module on your system, you can use pip:
pip3 install pywinbox
or
python3 -m pip install pywinbox
Alternatively, you can download the wheel file (.whl) available in the [Download page](https://pypi.org/project/PyWinBox/#files) and the [dist folder](https://github.com/Kalmat/PyWinBox/tree/master/dist), and run this (don't forget to replace 'x.x.xx' with proper version number):
pip install PyWinBox-x.x.xx-py3-none-any.whl
You may want to add `--force-reinstall` option to be sure you are installing the right dependencies version.
Then, you can use it on your own projects just importing it:
import pywinbox
## SUPPORT <a name="support"></a>
In case you have a problem, comments or suggestions, do not hesitate to [open issues](https://github.com/Kalmat/PyWinBox/issues) on the [project homepage](https://github.com/Kalmat/PyWinBox)
## USING THIS CODE <a name="using"></a>
If you want to use this code or contribute, you can either:
* Create a fork of the [repository](https://github.com/Kalmat/PyWinBox), or
* [Download the repository](https://github.com/Kalmat/PyWinBox/archive/refs/heads/master.zip), uncompress, and open it on your IDE of choice (e.g. PyCharm)
Be sure you install all dependencies described on "docs/requirements.txt" by using pip
## TEST <a name="test"></a>
To test this module on your own system, cd to "tests" folder and run:
python3 test_pywinbox.py
For macOS NSWindow, you can also test using:
python3 test_MacNSBox.py
Raw data
{
"_id": null,
"home_page": "https://github.com/Kalmat/PyWinBox",
"name": "PyWinBox",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "left top right bottom size width height topleft bottomleft topright bottomright midtop midleft midbottom midright center centerx centery box rect boundingbox area",
"author": "Kalmat",
"author_email": "palookjones@gmail.com",
"download_url": "",
"platform": null,
"description": "# PyWinBox\r\n\r\n[](https://github.com/Kalmat/PyWinBox/actions/workflows/type-checking.yml)\r\n[](https://badge.fury.io/py/PyWinBox)\r\n\r\n\r\nCross-Platform and multi-monitor module which allows to manage window areas (position and\r\nsize) and all their properties, as well as any rectangular area.\r\n\r\n## Rectangular areas\r\n\r\nYou just need to instantiate the PyWinBox class, passing custom callbacks to be called when any property is \r\nqueried (onQuery) or set (onSet).\r\n\r\n myBox = pywinbox.PyWinBox(onQuery=customOnQuery, onSet=customOnSet)\r\n\r\nFor rectangular areas, it is necessary to pass custom (not default) callbacks which actually manage the box struct values, \r\nor the struct will be empty and useless.\r\n\r\n## Window areas\r\n\r\nTo manage window areas, you need to also pass the window handle when instantiating the class, in the following formats:\r\n\r\n- MS-Windows: integer (window id) or str (as returned by, e.g., PyQt's winId() method)\r\n- Linux: integer (window id) or X-Window object\r\n- macOS / foreign window: in case you want to manage a window from another application, you must pass target app and window names, as a tuple of strings (appName, windowTitle)\r\n- macOS / own window: if you want to manage your own application window, you must pass NSWindow() object\r\n\r\n(Search for cross-platform modules if you need a cross-platform handle. For instance, you can get this kind of handles\r\nusing PyWinCtl's getHandle(), getAppName() or title methods)\r\n\r\nIn this case, you can use the default methods to manage the window when its properties are queried or set: \r\n\r\n- default OnQuery: Will update the window position and size values when any property is queried\r\n- default OnSet: Will move and/or resize the window when any property is set\r\n\r\nTo use default methods, just pass them as None, like this: \r\n\r\n myBox = pywinbox.PyWinBox(onQuery=None, onSet=None, handle=windowHandle)\r\n\r\nOf course, you can also define (and pass) your own custom functions if you need to perform other actions on these events.\r\n\r\nIn this case, if your custom functions do not properly retrieve or set the actual window position and size, the \r\ninformation contained in the PyWinBox class, and returned by all properties, will likely become obsolete. So, you can\r\nuse both in your custom callback:\r\n\r\n def customOnQuery():\r\n currBox = myBox.onQuery() # This will retrieve the current window's box\r\n # ... do your stuff ...\r\n return currBox\r\n\r\n def customOnSet(newBox: Box):\r\n myBox.onSet(newBox) # This will actually move/resize the window\r\n # ... do your stuff ...\r\n\r\n myBox = pywinbox.PyWinBox(onQuery=customOnQuery, onSet=customOnSet, handle=windowHandle)\r\n\r\n\r\n## Class Properties\r\n\r\n left, top, right, bottom\r\n\r\n size, width, height\r\n\r\n topleft, bottomleft, topright, bottomright\r\n\r\n midtop, midleft, midbottom, midright\r\n\r\n center, centerx, centery\r\n\r\n box (left, top, width, height)\r\n\r\n rect (left, top, right, bottom)\r\n\r\n\r\n## Data Structs\r\n\r\nThese are useful data structs (named tuples, actually) you can use to better manage the values:\r\n\r\n Box: left, top, width, height\r\n Rect: left, top, right, bottom\r\n Size: width, height\r\n Point: x, y\r\n\r\n\r\n## INSTALL <a name=\"install\"></a>\r\n\r\nTo install this module on your system, you can use pip: \r\n\r\n pip3 install pywinbox\r\n\r\nor\r\n\r\n python3 -m pip install pywinbox\r\n\r\nAlternatively, you can download the wheel file (.whl) available in the [Download page](https://pypi.org/project/PyWinBox/#files) and the [dist folder](https://github.com/Kalmat/PyWinBox/tree/master/dist), and run this (don't forget to replace 'x.x.xx' with proper version number):\r\n\r\n pip install PyWinBox-x.x.xx-py3-none-any.whl\r\n\r\nYou may want to add `--force-reinstall` option to be sure you are installing the right dependencies version.\r\n\r\nThen, you can use it on your own projects just importing it:\r\n\r\n import pywinbox\r\n\r\n## SUPPORT <a name=\"support\"></a>\r\n\r\nIn case you have a problem, comments or suggestions, do not hesitate to [open issues](https://github.com/Kalmat/PyWinBox/issues) on the [project homepage](https://github.com/Kalmat/PyWinBox)\r\n\r\n## USING THIS CODE <a name=\"using\"></a>\r\n\r\nIf you want to use this code or contribute, you can either:\r\n\r\n* Create a fork of the [repository](https://github.com/Kalmat/PyWinBox), or \r\n* [Download the repository](https://github.com/Kalmat/PyWinBox/archive/refs/heads/master.zip), uncompress, and open it on your IDE of choice (e.g. PyCharm)\r\n\r\nBe sure you install all dependencies described on \"docs/requirements.txt\" by using pip\r\n\r\n## TEST <a name=\"test\"></a>\r\n\r\nTo test this module on your own system, cd to \"tests\" folder and run:\r\n\r\n python3 test_pywinbox.py\r\n\r\nFor macOS NSWindow, you can also test using:\r\n\r\n python3 test_MacNSBox.py\r\n",
"bugtrack_url": null,
"license": "BSD 3",
"summary": "Cross-Platform and multi-monitor toolkit to handle rectangular areas and windows box",
"version": "0.5",
"project_urls": {
"Homepage": "https://github.com/Kalmat/PyWinBox"
},
"split_keywords": [
"left",
"top",
"right",
"bottom",
"size",
"width",
"height",
"topleft",
"bottomleft",
"topright",
"bottomright",
"midtop",
"midleft",
"midbottom",
"midright",
"center",
"centerx",
"centery",
"box",
"rect",
"boundingbox",
"area"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ed35a44db00aeb10093614aee5cdbe17c4a1e84c3303595022ae40d3254c2149",
"md5": "73a9ce015512a203dce8088a1761022e",
"sha256": "c8302e0747de7e7c41a62263949fbb5250a37903eb2a9bdac1dabe1ee0239c5e"
},
"downloads": -1,
"filename": "PyWinBox-0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "73a9ce015512a203dce8088a1761022e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 50592,
"upload_time": "2023-09-06T11:40:37",
"upload_time_iso_8601": "2023-09-06T11:40:37.890630Z",
"url": "https://files.pythonhosted.org/packages/ed/35/a44db00aeb10093614aee5cdbe17c4a1e84c3303595022ae40d3254c2149/PyWinBox-0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-06 11:40:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Kalmat",
"github_project": "PyWinBox",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pywinbox"
}
JSON
