| Name | dearpygui-grid JSON |
| Version |
1.0.1
JSON |
| download |
| home_page | |
| Summary | Layout manager for Dear PyGui. |
| upload_time | 2023-12-27 03:06:06 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.10 |
| license | |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# DearPyGui-Grid
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Basic Usage](#basic-usage)
- [Padding & Offsets](#padding--offsets)
DearPyGui-Grid is a layout management tool for [Dear PyGui](https://github.com/hoffstadt/DearPyGui). `Grid` does *not* create or use items for layout aids. Instead, it emulates a table-like structure and works by leveraging common configuration options supported by most items.
<br>
## Features
* create simple to complex layouts *without* the messy web of group, table, theme, and spacer items
* position widgets in individual cells or over a cell range
* supports overlapping widgets
* edge-level padding customization per-slot (row/column) or per widget
* control spacing between rows and columns
* static and dynamic sizing (policy emulation)
* optional overlay outlining the grid and its' slots - useful for debugging or designing layouts
<br>
## Installation
Using Python 3.10 (or newer), DearPyGui-Grid can be installed via `pip`:
```python
python -m pip install dearpygui-grid
```
<br>
## Usage
#### Basic Usage
A layout object is created by instantiating the `Grid` class. The first two arguments set the initial number of columns and rows in the layout. The third argument, `target`, is the id of the grid's "reference" item. This item is used to help the grid determine its' content position and size when drawn, and is non-optional in most cases. `Grid` also accepts several keyword-only arguments. These, along with `cols`, `rows`, and `target`, can be updated later via the `.configure` method.
Next, we'll add some button items to the new window and attach them to the 3x3 grid in a cross pattern. This is done using the `.push` method; passing it the id of the item to attach in addition to the cell coordinates - indices of the column and row respectively - that the item will occupy. Column and row indices are zero-indexed.
Lastly, we need to tell Dear PyGui when to draw the grid. This can be done by registering the grid instance itself as a callback. An on-resize or when-visible handler is usually sufficient. While running the script below, you should see a rather seamless cross of buttons. You'll also see the grid at work when attempting to resize the window.
```python
import dearpygui.dearpygui as dpg
import dearpygui_grid as dpg_grid
dpg.create_context()
dpg.setup_dearpygui()
dpg.create_viewport()
dpg.show_viewport()
window = dpg.add_window(width=400, height=400, no_scrollbar=True, no_title_bar=True)
grid = dpg_grid.Grid(3, 3, window)
grid.push(dpg.add_button(parent=window), 1, 0) # middle col, top row
grid.push(dpg.add_button(parent=window), 0, 1) # left col, middle row
grid.push(dpg.add_button(parent=window), 1, 1) # middle col, middle row
grid.push(dpg.add_button(parent=window), 2, 1) # right col, middle row
grid.push(dpg.add_button(parent=window), 1, 2) # middle col, bottom row
with dpg.item_handler_registry() as window_hr:
dpg.add_item_visible_handler(callback=grid)
dpg.bind_item_handler_registry(window, window_hr)
dpg.start_dearpygui()
```
<div>
<p align="center">
<img src="https://github.com/Atlamillias/dearpygui-grid/blob/main/docs/images/basic_usage_ex1_overlay.png"/>
<img src="https://github.com/Atlamillias/dearpygui-grid/blob/main/docs/images/basic_usage_ex1.png"/>
</p>
<p style="font-size:12px;text-align:center;font-style:italic;"></p>
<br>
</div>
#### Padding & Offsets
In the example above, the target window item is configured using the `no_scrollbar` and `no_title_bar` settings. If you try running the script without them, you'll see that the grid does not take into account the size of the window's title bar, meaning that it will slightly overlap any content in the top row. Additionally, the content in the window consumes enough space for the scrollbar to display which, again, clips our content. But, what if you want the grid to behave *with* the scrollbar and title bar? Fortunately, this can also be managed by applying offsets, padding, and spacing to the layout.
| Attribute | Value Type | Length | Description |
| :--------: | :------------: | :--------: | :---------: |
| `.offsets` | `array[float]` | 4 | Space between the left, upper, right, and lower inner walls of the grid and its' content region. |
| `.padding` | `array[float]` | 4 | Space between the left, upper, right, and lower inner walls of the grid's slots and their content region. |
| `.spacing` | `array[float]` | 2 | Space between the outer walls of the grid's slots from other slots. |
Applying an 8-pixel offset will be more than sufficient to shrink the content region enough so the scrollbar isn't visible. To allow the grid's content to be shown below the title bar and not under it, a 26-pixel offset is applied to the grid's upper border. A value of 26 is used because the height of the title bar using Dear PyGui's internal default theme is 18 pixels - the 8 additional pixels are added to make the layout uniform by matching the offsets applied to the other borders.
```python
import dearpygui.dearpygui as dpg
import dearpygui_grid as dpg_grid
dpg.create_context()
dpg.setup_dearpygui()
dpg.create_viewport()
dpg.show_viewport()
window = dpg.add_window(width=400, height=400)
grid = dpg_grid.Grid(3, 3, window)
# Can optionally be applied per component, as `grid.offsets[i] = ...`
grid.offsets = 8, 18 + 8, 8, 8
grid.push(dpg.add_button(parent=window), 1, 0) # middle col, top row
grid.push(dpg.add_button(parent=window), 0, 1) # left col, middle row
grid.push(dpg.add_button(parent=window), 1, 1) # middle col, middle row
grid.push(dpg.add_button(parent=window), 2, 1) # right col, middle row
grid.push(dpg.add_button(parent=window), 1, 2) # middle col, bottom row
with dpg.item_handler_registry() as window_hr:
dpg.add_item_visible_handler(callback=grid)
dpg.bind_item_handler_registry(window, window_hr)
dpg.start_dearpygui()
```
<div>
<p align="center">
<img src="https://github.com/Atlamillias/dearpygui-grid/blob/main/docs/images/padding_&_offsets_ex1_overlay.png"/>
<img src="https://github.com/Atlamillias/dearpygui-grid/blob/main/docs/images/padding_&_offsets_ex1.png"/>
</p>
<p style="font-size:12px;text-align:center;font-style:italic;"></p>
<br>
</div>
While `.offsets` "pads" the grid's content, `.padding` affects the content of its' slots - columns and rows - similarly. Specifically, it affects the content of its' *cells* since, unlike the grid, each slot only has two boundries; left and right for columns, top and bottom for rows. When drawn, the grid calculates the size, position, and offsets (padding) of each cell using the settings of the parenting column and row.
Using the same example once more, left-edge and right-edge column padding (the first and third component of `.padding` respectively) is set to 10. To make it easier to see how the adjustment affects the layout, row upper-edge and lower-edge padding is not changed.
```python
import dearpygui.dearpygui as dpg
import dearpygui_grid as dpg_grid
dpg.create_context()
dpg.setup_dearpygui()
dpg.create_viewport()
dpg.show_viewport()
window = dpg.add_window(width=400, height=400)
grid = dpg_grid.Grid(3, 3, window)
grid.offsets = 8, 18 + 8, 8, 8
grid.padding[0] = 10 # column left-edge
grid.padding[2] = 10 # column right-edge
grid.push(dpg.add_button(parent=window), 1, 0) # middle col, top row
grid.push(dpg.add_button(parent=window), 0, 1) # left col, middle row
grid.push(dpg.add_button(parent=window), 1, 1) # middle col, middle row
grid.push(dpg.add_button(parent=window), 2, 1) # right col, middle row
grid.push(dpg.add_button(parent=window), 1, 2) # middle col, bottom row
with dpg.item_handler_registry() as window_hr:
dpg.add_item_visible_handler(callback=grid)
dpg.bind_item_handler_registry(window, window_hr)
dpg.start_dearpygui()
```
<div>
<p align="center">
<img src="https://github.com/Atlamillias/dearpygui-grid/blob/main/docs/images/padding_&_offsets_ex2_overlay.png"/>
<img src="https://github.com/Atlamillias/dearpygui-grid/blob/main/docs/images/padding_&_offsets_ex2.png"/>
</p>
<p style="font-size:12px;text-align:center;font-style:italic;"></p>
<br>
</div>
>***Note**: The amount of space between slots can be also adjusted. The value found on the `.spacing` attribute is a 2-length array containing the spacing values for columns and rows respectively. It is effectively a different form of padding; a combination of a grid offset and slot padding value.*
<br>
Raw data
{
"_id": null,
"home_page": "",
"name": "dearpygui-grid",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "",
"author": "",
"author_email": "Anthony Doupe <atlamillias@outlook.com>",
"download_url": "https://files.pythonhosted.org/packages/2e/d6/0c219f460fd910c35ad09c7db814075f8d23f30aa9edefcc5b5295ba36ca/dearpygui-grid-1.0.1.tar.gz",
"platform": null,
"description": "# DearPyGui-Grid\r\n- [Features](#features)\r\n- [Installation](#installation)\r\n- [Usage](#usage)\r\n - [Basic Usage](#basic-usage)\r\n - [Padding & Offsets](#padding--offsets)\r\n\r\n\r\nDearPyGui-Grid is a layout management tool for [Dear PyGui](https://github.com/hoffstadt/DearPyGui). `Grid` does *not* create or use items for layout aids. Instead, it emulates a table-like structure and works by leveraging common configuration options supported by most items.\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n<br>\r\n\r\n## Features\r\n* create simple to complex layouts *without* the messy web of group, table, theme, and spacer items\r\n* position widgets in individual cells or over a cell range\r\n* supports overlapping widgets\r\n* edge-level padding customization per-slot (row/column) or per widget\r\n* control spacing between rows and columns\r\n* static and dynamic sizing (policy emulation)\r\n* optional overlay outlining the grid and its' slots - useful for debugging or designing layouts\r\n\r\n<br>\r\n\r\n## Installation\r\n\r\nUsing Python 3.10 (or newer), DearPyGui-Grid can be installed via `pip`:\r\n\r\n```python\r\npython -m pip install dearpygui-grid\r\n```\r\n\r\n<br>\r\n\r\n## Usage\r\n\r\n#### Basic Usage\r\n\r\nA layout object is created by instantiating the `Grid` class. The first two arguments set the initial number of columns and rows in the layout. The third argument, `target`, is the id of the grid's \"reference\" item. This item is used to help the grid determine its' content position and size when drawn, and is non-optional in most cases. `Grid` also accepts several keyword-only arguments. These, along with `cols`, `rows`, and `target`, can be updated later via the `.configure` method.\r\n\r\nNext, we'll add some button items to the new window and attach them to the 3x3 grid in a cross pattern. This is done using the `.push` method; passing it the id of the item to attach in addition to the cell coordinates - indices of the column and row respectively - that the item will occupy. Column and row indices are zero-indexed.\r\n\r\n\r\nLastly, we need to tell Dear PyGui when to draw the grid. This can be done by registering the grid instance itself as a callback. An on-resize or when-visible handler is usually sufficient. While running the script below, you should see a rather seamless cross of buttons. You'll also see the grid at work when attempting to resize the window.\r\n\r\n\r\n```python\r\nimport dearpygui.dearpygui as dpg\r\nimport dearpygui_grid as dpg_grid\r\n\r\n\r\ndpg.create_context()\r\ndpg.setup_dearpygui()\r\ndpg.create_viewport()\r\ndpg.show_viewport()\r\n\r\nwindow = dpg.add_window(width=400, height=400, no_scrollbar=True, no_title_bar=True)\r\n\r\ngrid = dpg_grid.Grid(3, 3, window)\r\n\r\ngrid.push(dpg.add_button(parent=window), 1, 0) # middle col, top row\r\ngrid.push(dpg.add_button(parent=window), 0, 1) # left col, middle row\r\ngrid.push(dpg.add_button(parent=window), 1, 1) # middle col, middle row\r\ngrid.push(dpg.add_button(parent=window), 2, 1) # right col, middle row\r\ngrid.push(dpg.add_button(parent=window), 1, 2) # middle col, bottom row\r\n\r\nwith dpg.item_handler_registry() as window_hr:\r\n dpg.add_item_visible_handler(callback=grid)\r\ndpg.bind_item_handler_registry(window, window_hr)\r\n\r\ndpg.start_dearpygui()\r\n\r\n```\r\n<div>\r\n <p align=\"center\">\r\n <img src=\"https://github.com/Atlamillias/dearpygui-grid/blob/main/docs/images/basic_usage_ex1_overlay.png\"/>\r\n <img src=\"https://github.com/Atlamillias/dearpygui-grid/blob/main/docs/images/basic_usage_ex1.png\"/>\r\n </p>\r\n <p style=\"font-size:12px;text-align:center;font-style:italic;\"></p>\r\n <br>\r\n</div>\r\n\r\n#### Padding & Offsets\r\n\r\nIn the example above, the target window item is configured using the `no_scrollbar` and `no_title_bar` settings. If you try running the script without them, you'll see that the grid does not take into account the size of the window's title bar, meaning that it will slightly overlap any content in the top row. Additionally, the content in the window consumes enough space for the scrollbar to display which, again, clips our content. But, what if you want the grid to behave *with* the scrollbar and title bar? Fortunately, this can also be managed by applying offsets, padding, and spacing to the layout.\r\n\r\n| Attribute | Value Type | Length | Description |\r\n| :--------: | :------------: | :--------: | :---------: |\r\n| `.offsets` | `array[float]` | 4 | Space between the left, upper, right, and lower inner walls of the grid and its' content region. |\r\n| `.padding` | `array[float]` | 4 | Space between the left, upper, right, and lower inner walls of the grid's slots and their content region. |\r\n| `.spacing` | `array[float]` | 2 | Space between the outer walls of the grid's slots from other slots. |\r\n\r\nApplying an 8-pixel offset will be more than sufficient to shrink the content region enough so the scrollbar isn't visible. To allow the grid's content to be shown below the title bar and not under it, a 26-pixel offset is applied to the grid's upper border. A value of 26 is used because the height of the title bar using Dear PyGui's internal default theme is 18 pixels - the 8 additional pixels are added to make the layout uniform by matching the offsets applied to the other borders.\r\n\r\n```python\r\nimport dearpygui.dearpygui as dpg\r\nimport dearpygui_grid as dpg_grid\r\n\r\n\r\ndpg.create_context()\r\ndpg.setup_dearpygui()\r\ndpg.create_viewport()\r\ndpg.show_viewport()\r\n\r\nwindow = dpg.add_window(width=400, height=400)\r\n\r\ngrid = dpg_grid.Grid(3, 3, window)\r\n# Can optionally be applied per component, as `grid.offsets[i] = ...`\r\ngrid.offsets = 8, 18 + 8, 8, 8\r\n\r\ngrid.push(dpg.add_button(parent=window), 1, 0) # middle col, top row\r\ngrid.push(dpg.add_button(parent=window), 0, 1) # left col, middle row\r\ngrid.push(dpg.add_button(parent=window), 1, 1) # middle col, middle row\r\ngrid.push(dpg.add_button(parent=window), 2, 1) # right col, middle row\r\ngrid.push(dpg.add_button(parent=window), 1, 2) # middle col, bottom row\r\n\r\nwith dpg.item_handler_registry() as window_hr:\r\n dpg.add_item_visible_handler(callback=grid)\r\ndpg.bind_item_handler_registry(window, window_hr)\r\n\r\ndpg.start_dearpygui()\r\n\r\n```\r\n<div>\r\n <p align=\"center\">\r\n <img src=\"https://github.com/Atlamillias/dearpygui-grid/blob/main/docs/images/padding_&_offsets_ex1_overlay.png\"/>\r\n <img src=\"https://github.com/Atlamillias/dearpygui-grid/blob/main/docs/images/padding_&_offsets_ex1.png\"/>\r\n </p>\r\n <p style=\"font-size:12px;text-align:center;font-style:italic;\"></p>\r\n <br>\r\n</div>\r\n\r\nWhile `.offsets` \"pads\" the grid's content, `.padding` affects the content of its' slots - columns and rows - similarly. Specifically, it affects the content of its' *cells* since, unlike the grid, each slot only has two boundries; left and right for columns, top and bottom for rows. When drawn, the grid calculates the size, position, and offsets (padding) of each cell using the settings of the parenting column and row.\r\n\r\nUsing the same example once more, left-edge and right-edge column padding (the first and third component of `.padding` respectively) is set to 10. To make it easier to see how the adjustment affects the layout, row upper-edge and lower-edge padding is not changed.\r\n\r\n```python\r\nimport dearpygui.dearpygui as dpg\r\nimport dearpygui_grid as dpg_grid\r\n\r\n\r\ndpg.create_context()\r\ndpg.setup_dearpygui()\r\ndpg.create_viewport()\r\ndpg.show_viewport()\r\n\r\nwindow = dpg.add_window(width=400, height=400)\r\n\r\ngrid = dpg_grid.Grid(3, 3, window)\r\ngrid.offsets = 8, 18 + 8, 8, 8\r\ngrid.padding[0] = 10 # column left-edge\r\ngrid.padding[2] = 10 # column right-edge\r\n\r\ngrid.push(dpg.add_button(parent=window), 1, 0) # middle col, top row\r\ngrid.push(dpg.add_button(parent=window), 0, 1) # left col, middle row\r\ngrid.push(dpg.add_button(parent=window), 1, 1) # middle col, middle row\r\ngrid.push(dpg.add_button(parent=window), 2, 1) # right col, middle row\r\ngrid.push(dpg.add_button(parent=window), 1, 2) # middle col, bottom row\r\n\r\nwith dpg.item_handler_registry() as window_hr:\r\n dpg.add_item_visible_handler(callback=grid)\r\ndpg.bind_item_handler_registry(window, window_hr)\r\n\r\ndpg.start_dearpygui()\r\n\r\n```\r\n<div>\r\n <p align=\"center\">\r\n <img src=\"https://github.com/Atlamillias/dearpygui-grid/blob/main/docs/images/padding_&_offsets_ex2_overlay.png\"/>\r\n <img src=\"https://github.com/Atlamillias/dearpygui-grid/blob/main/docs/images/padding_&_offsets_ex2.png\"/>\r\n </p>\r\n <p style=\"font-size:12px;text-align:center;font-style:italic;\"></p>\r\n <br>\r\n</div>\r\n\r\n>***Note**: The amount of space between slots can be also adjusted. The value found on the `.spacing` attribute is a 2-length array containing the spacing values for columns and rows respectively. It is effectively a different form of padding; a combination of a grid offset and slot padding value.*\r\n\r\n<br>\r\n",
"bugtrack_url": null,
"license": "",
"summary": "Layout manager for Dear PyGui.",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/Atlamillias/DearPyGui-Grid"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7e4af6d7aa5f9174d130e819cc473612fbd981ae7285c7a5e4838360f435df6e",
"md5": "36826aae197fa7a4650e6a61056e184b",
"sha256": "97f24edfbc71c73c4b08dca9c54a6a549aacac57f275d0194eda5ee8f1cffeaa"
},
"downloads": -1,
"filename": "dearpygui_grid-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "36826aae197fa7a4650e6a61056e184b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 19215,
"upload_time": "2023-12-27T03:06:04",
"upload_time_iso_8601": "2023-12-27T03:06:04.189531Z",
"url": "https://files.pythonhosted.org/packages/7e/4a/f6d7aa5f9174d130e819cc473612fbd981ae7285c7a5e4838360f435df6e/dearpygui_grid-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2ed60c219f460fd910c35ad09c7db814075f8d23f30aa9edefcc5b5295ba36ca",
"md5": "04ad3b270b30ad603b6b5982205e81b5",
"sha256": "bfe5dec2f9996813f7d8244549bdd7d8867a150884d806f6ed1ec03ddb561405"
},
"downloads": -1,
"filename": "dearpygui-grid-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "04ad3b270b30ad603b6b5982205e81b5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 19229,
"upload_time": "2023-12-27T03:06:06",
"upload_time_iso_8601": "2023-12-27T03:06:06.459457Z",
"url": "https://files.pythonhosted.org/packages/2e/d6/0c219f460fd910c35ad09c7db814075f8d23f30aa9edefcc5b5295ba36ca/dearpygui-grid-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-27 03:06:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Atlamillias",
"github_project": "DearPyGui-Grid",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "dearpygui-grid"
}
