7.2.18

#### Fixed:
- Inserting rows/columns with hidden rows/columns sometimes resulted in incorrect rows/columns being displayed
- Treeview function `insert()` when using parameter `index` sometimes resulted in treeview items being displayed in the wrong locations

#### Changed:
- Using function `set_currently_selected()` or any function/setter which does the same internally will now trigger a select event like creating selection boxes does
- iids in Treeview mode are now case sensitive
- Treeview function `tree_build()` when parameter `safety` is `False` will no longer check for missing ids in the iid column
- Treeview function `get_children()` now gets item ids from the row index which provides them in the same order as in the treeview
- Add parameter `run_binding` to treeview functions `selection_add()`, `selection_set()`
- Slight color change for top left rectangle bars

#### Added:
- Initialization parameters `default_header` and `default_row_index` can now optionally be set to `None` to not display anything in empty header cells / row index cells
- Parameters `lower` and `include_text_column` to treeview function `tree_build()`
- Treeview function `bulk_insert()`
- Treeview function `get_nodes()` behaves exactly the same as `get_children()` except it retrieves item ids from the tree nodes `dict` not the row index.
- Treeview function `descendants()` which returns a generator
- Treeview property `tree_selected`

docs/CHANGELOG.md

@@ -1,5 +1,23 @@
 ### Version 7.2.18
-####
+#### Fixed:
+- Inserting rows/columns with hidden rows/columns sometimes resulted in incorrect rows/columns being displayed
+- Treeview function `insert()` when using parameter `index` sometimes resulted in treeview items being displayed in the wrong locations
+
+#### Changed:
+- Using function `set_currently_selected()` or any function/setter which does the same internally will now trigger a select event like creating selection boxes does
+- iids in Treeview mode are now case sensitive
+- Treeview function `tree_build()` when parameter `safety` is `False` will no longer check for missing ids in the iid column
+- Treeview function `get_children()` now gets item ids from the row index which provides them in the same order as in the treeview
+- Add parameter `run_binding` to treeview functions `selection_add()`, `selection_set()`
+- Slight color change for top left rectangle bars
+
+#### Added:
+- Initialization parameters `default_header` and `default_row_index` can now optionally be set to `None` to not display anything in empty header cells / row index cells
+- Parameters `lower` and `include_text_column` to treeview function `tree_build()`
+- Treeview function `bulk_insert()`
+- Treeview function `get_nodes()` behaves exactly the same as `get_children()` except it retrieves item ids from the tree nodes `dict` not the row index.
+- Treeview function `descendants()` which returns a generator
+- Treeview property `tree_selected`
 
 ### Version 7.2.17
 #### Changed:

docs/DOCUMENTATION.md

@@ -310,8 +310,8 @@ def __init__(
     header: None | list[object] = None,
     row_index: None | list[object] = None,
     index: None | list[object] = None,
-    default_header: Literal["letters", "numbers", "both"] = "letters",
-    default_row_index: Literal["letters", "numbers", "both"] = "numbers",
+    default_header: Literal["letters", "numbers", "both"] | None = "letters",
+    default_row_index: Literal["letters", "numbers", "both"] | None = "numbers",
     data_reference: None | Sequence[Sequence[object]] = None,
     data: None | Sequence[Sequence[object]] = None,
     # either (start row, end row, "rows"), (start column, end column, "rows") or
@@ -5760,6 +5760,54 @@ sheet.insert(
 )
 ```
 
+___
+
+#### **Insert multiple items**
+
+```python
+bulk_insert(
+    data: list[list[object]],
+    parent: str = "",
+    index: None | int | Literal["end"] = None,
+    iid_column: int | None = None,
+    text_column: int | None | str = None,
+    create_selections: bool = False,
+    include_iid_column: bool = True,
+    include_text_column: bool = True,
+) -> dict[str, int]
+```
+Parameters:
+- `parent` is the `iid` of the parent item (if any). If left as `""` then the items will not have a parent.
+- `index` is the row number for the items to be placed at, leave as `None` for the end.
+- `iid_column` if left as `None` iids will be automatically generated for the new items, else you can specify a column in the `data` which contains the iids.
+- `text_column`:
+    - If left as `None` there will be no displayed text next to the items.
+    - A text column can be provided in the data and `text_column` set to an `int` representing its index to provide the displayed text for the items.
+    - Or if a `str` is used all items will have that `str` as their displayed text.
+- `create_selections` when `True` selects the row that has just been created.
+- `include_iid_column` when `False` excludes the iid column from the inserted rows.
+- `include_text_column` when the `text_column` is an `int` setting this to `False` excludes that column from the treeview.
+
+Notes:
+- Returns a `dict[str, int]` of key: new iids, value: their data row number.
+
+Example:
+```python
+sheet.insert(
+    iid="top level",
+    text="Top level",
+    values=["cell A1", "cell B1"],
+)
+sheet.insert(
+    parent="top level",
+    iid="mid level",
+    text="Mid level",
+    values=["cell A2", "cell B2"],
+)
+```
+
+___
+
 #### **Build a tree from data**
 
 This takes a list of lists where sublists are rows and a few arguments to bulk insert items into the treeview. **Note that**:
@@ -5776,8 +5824,10 @@ tree_build(
     open_ids: Iterator[str] | None = None,
     safety: bool = True,
     ncols: int | None = None,
+    lower: bool = False,
     include_iid_column: bool = True,
     include_parent_column: bool = True,
+    include_text_column: bool = True,
 ) -> Sheet
 ```
 Parameters:
@@ -5791,8 +5841,10 @@ Parameters:
     - In the case of empty iid cells the row will be ignored.
     - In the case of duplicate iids they will be renamed and `"DUPLICATED_<number>"` will be attached to the end.
 - `ncols` is like maximum columns, an `int` which limits the number of columns that are included in the loaded data.
+- `lower` makes all item ids - iids lower case.
 - `include_iid_column` when `False` excludes the iid column from the inserted rows.
 - `include_parent_column` when `False` excludes the parent column from the inserted rows.
+- `include_text_column` when the `text_column` is an `int` setting this to `False` excludes that column from the treeview.
 
 Notes:
 - Returns the `Sheet` object.
@@ -5812,39 +5864,51 @@ sheet.tree_build(
 )
 ```
 
+___
+
 #### **Reset the treeview**
 
 ```python
 tree_reset() -> Sheet
 ```
 
+___
+
 #### **Get treeview iids that are open**
 
 ```python
 tree_get_open() -> set[str]
 ```
 
+___
+
 #### **Set the open treeview iids**
 
 ```python
 tree_set_open(open_ids: Iterator[str]) -> Sheet
 ```
 - Any other iids are closed as a result.
 
+___
+
 #### **Open treeview iids**
 
 ```python
 tree_open(*items, redraw: bool = True) -> Sheet
 ```
 - Opens all given iids.
 
+___
+
 #### **Close treeview iids**
 
 ```python
 tree_close(*items, redraw: bool = True) -> Sheet
 ```
 - Closes all given iids.
 
+___
+
 #### **Set or get an iids attributes**
 
 ```python
@@ -5875,20 +5939,26 @@ Notes:
 }
 ```
 
+___
+
 #### **Get an iids row number**
 
 ```python
 itemrow(item: str) -> int
 ```
 - Includes hidden rows in counting row numbers.
 
+___
+
 #### **Get a row numbers item**
 
 ```python
 rowitem(row: int, data_index: bool = False) -> str | None
 ```
 - Includes hidden rows in counting row numbers. See [here](https://github.com/ragardner/tksheet/wiki/Version-7#hiding-rows) for more information.
 
+___
+
 #### **Get treeview children**
 
 ```python
@@ -5899,6 +5969,32 @@ get_children(item: None | str = None) -> Generator[str]
     - Use an empty `str` (`""`) to get all top level iids in the treeview.
     - Use an iid to get the children for that particular iid. Does not include all descendants.
 
+```python
+get_nodes(item: None | str = None) -> Generator[str]:
+```
+- Exactly the same as above but instead of retrieving iids in the order that they appear in the treeview it retrieves iids from the internal `dict` which may not be ordered.
+
+___
+
+#### **Get item descendants**
+
+```python
+descendants(item: str, check_open: bool = False) -> Generator[str]:
+```
+- Returns a generator which yields item ids in the order that they appear in the treeview.
+
+___
+
+#### **Get the currently selected treeview item**
+
+```python
+@property
+tree_selected() -> str | None:
+```
+- Returns the item id of the currently selected box row. If nothing is selected returns `None`.
+
+___
+
 #### **Delete treeview items**
 
 ```python
@@ -5907,6 +6003,8 @@ del_items(*items) -> Sheet
 - `*items` the iids of items to delete.
 - Also deletes all item descendants.
 
+___
+
 #### **Move items to a new parent**
 
 ```python
@@ -5915,6 +6013,8 @@ set_children(parent: str, *newchildren) -> Sheet
 - `parent` the new parent for the items.
 - `*newchildren` the items to move.
 
+___
+
 #### **Move an item to a new parent**
 
 ```python
@@ -5928,34 +6028,44 @@ move(item: str, parent: str, index: int | None = None) -> Sheet
     - Use an `int` to move the item to an index within its parents children (or within top level items if moving to the top).
 - `reattach()` is exactly the same as `move()`.
 
+___
+
 #### **Check an item exists**
 
 ```python
 exists(item: str) -> bool
 ```
 - `item` - a treeview iid.
 
+___
+
 #### **Get an items parent**
 
 ```python
 parent(item: str) -> str
 ```
 - `item` - a treeview iid.
 
+___
+
 #### **Get an items index**
 
 ```python
 index(item: str) -> int
 ```
 - `item` - a treeview iid.
 
+___
+
 #### **Check if an item is currently displayed**
 
 ```python
 item_displayed(item: str) -> bool
 ```
 - `item` - a treeview iid.
 
+___
+
 #### **Display an item**
 
 Make sure an items parents are all open, does **not** scroll to the item.
@@ -5965,6 +6075,8 @@ display_item(item: str, redraw: bool = False) -> Sheet
 ```
 - `item` - a treeview iid.
 
+___
+
 #### **Scroll to an item**
 
 - Make sure an items parents are all open and scrolls to the item.
@@ -5974,6 +6086,8 @@ scroll_to_item(item: str, redraw: bool = False) -> Sheet
 ```
 - `item` - a treeview iid.
 
+___
+
 #### **Get currently selected items**
 
 ```python
@@ -5985,25 +6099,33 @@ Notes:
 Parameters:
 - `cells` when `True` any selected cells will also qualify as selected items.
 
+___
+
 #### **Set selected items**
 
 ```python
-selection_set(*items, redraw: bool = True) -> Sheet
+selection_set(*items, run_binding: bool = True, redraw: bool = True) -> Sheet
 ```
 - Sets selected rows (items).
 
+___
+
 #### **Add selected items**
 
 ```python
-selection_add(*items, redraw: bool = True) -> Sheet
+selection_add(*items, run_binding: bool = True, redraw: bool = True) -> Sheet
 ```
 
+___
+
 #### **Remove selections**
 
 ```python
 selection_remove(*items, redraw: bool = True) -> Sheet
 ```
 
+___
+
 #### **Toggle selections**
 
 ```python

tksheet/functions.py

@@ -18,6 +18,7 @@
 )
 from functools import partial
 from itertools import islice, repeat
+from typing import Literal
 
 from .formatters import (
     to_bool,
@@ -363,12 +364,15 @@ def idx_param_to_int(idx: str | int | None) -> int | None:
     return alpha2idx(idx)
 
 
-def get_n2a(n: int = 0, _type: str = "numbers") -> str:
+def get_n2a(n: int = 0, _type: Literal["letters", "numbers", "both"] | None = "numbers") -> str:
     if _type == "letters":
         return num2alpha(n)
     elif _type == "numbers":
         return f"{n + 1}"
-    return f"{num2alpha(n)} {n + 1}"
+    elif _type == "both":
+        return f"{num2alpha(n)} {n + 1}"
+    elif _type is None:
+        return ""
 
 
 def get_index_of_gap_in_sorted_integer_seq_forward(
@@ -514,6 +518,16 @@ def index_exists(seq: Sequence[object], index: int) -> bool:
         return False
 
 
+def add_to_displayed(displayed: list[int], to_add: Iterator[int]) -> list[int]:
+    # assumes to_add is sorted in reverse
+    for i in reversed(to_add):
+        ins = bisect_left(displayed, i)
+        displayed[ins:] = [e + 1 for e in islice(displayed, ins, None)]
+    for i in reversed(to_add):
+        displayed.insert(bisect_left(displayed, i), i)
+    return displayed
+
+
 def move_elements_by_mapping(
     seq: list[object],
     new_idxs: dict[int, int],