Merge pull request #178 from jwlodek/v0.1.5-develop

V0.1.5 develop

docs/DocstringGenerated/PyCui.md

@@ -132,13 +132,14 @@ first create an instance of this class, and then add cells + widgets to it.
  increment_loading_bar | Increments progress bar if loading bar popup is open
  stop_loading_popup | Leaves loading state, and closes popup.
  close_popup | Closes the popup, and resets focus
- _refresh_height_width | Function that updates the height and width of the CUI based on terminal window size."""
+ _refresh_height_width | Function that updates the height and width of the CUI based on terminal window size.
+ get_absolute_size | Returns dimensions of CUI
  _draw_widgets | Function that draws all of the widgets to the screen
  _draw_status_bars | Draws status bar and title bar
  _display_window_warning | Function that prints some basic error info if there is an error with the CUI
  _handle_key_presses | Function that handles all main loop key presses.
  _draw | Main CUI draw loop called by start()
- __format__ | Override of base format function. Prints list of current widgets.
+ format | Override of base format function. Prints list of current widgets.
 
 
 
@@ -1327,10 +1328,10 @@ Closes the popup, and resets focus
 def _refresh_height_width(self) -> None
 ```
 
-Function that updates the height and width of the CUI based on terminal window size."""
-
+Function that updates the height and width of the CUI based on terminal window size.
 
 
+```
 if self._simulated_terminal is None:
 if self._stdscr is None:
 term_size = shutil.get_terminal_size()
@@ -1358,9 +1359,23 @@ if self._popup is not None:
 self._popup.update_height_width()
 if self._logger._live_debug_element is not None:
 self._logger._live_debug_element.update_height_width()
+```
+
+
+
+
+
 
+
+### get_absolute_size
+
+```python
 def get_absolute_size(self) -> Tuple[int,int]:
-"""Returns dimensions of CUI
+```
+
+Returns dimensions of CUI
+
+
 
 
 #### Returns

docs/DocstringGenerated/Ui.md

@@ -1099,7 +1099,8 @@ Analogous to a RadioButton
 -----|-----
  clear | Clears all items from the Scroll Menu
  set_on_selection_change_event | Function that sets the function fired when menu selection changes.
- _process_selection_change_event | Function that executes on-selection change event either with the current menu item, or with no-args"""
+ _process_selection_change_event | Function that executes on-selection change event either with the current menu item, or with no-args
+ get_selected_item_index | Gets the currently selected item
  set_selected_item_index | Sets the currently selected item
  _scroll_up | Function that scrolls the view up in the scroll menu
  _scroll_down | Function that scrolls the view down in the scroll menu
@@ -1181,10 +1182,10 @@ Event function must take 0 or 1 parameters. If 1 parameter, the new selcted item
 def _process_selection_change_event(self)
 ```
 
-Function that executes on-selection change event either with the current menu item, or with no-args"""
-
+Function that executes on-selection change event either with the current menu item, or with no-args
 
 
+```
 # Identify num of args from callable. This allows for user to create commands that take in x, y
 # coords of the mouse press as input
 num_args = 0
@@ -1203,10 +1204,19 @@ elif num_args == 0:
 self._on_selection_change()
 else:
 raise ValueError('On selection change event must accept either 0 or 1 parameters!')
+```
+
+
+
 
 
+
+### get_selected_item_index
+```python
 def get_selected_item_index(self) -> int:
-"""Gets the currently selected item
+```
+
+Gets the currently selected item
 
 
 #### Returns
@@ -1219,6 +1229,7 @@ def get_selected_item_index(self) -> int:
 
 
 
+
 ### set_selected_item_index
 
 ```python

docs/developers.md

@@ -146,8 +146,11 @@ class ScrollMenu(Widget, py_cui.ui.MenuImplementation):
 
         super().draw()
 ```
+
 The `_handle_key_press` and `_draw` functions must be extended for your new widget. You may leave the `_handle_key_press` as above, if you don't require any keybindings for the widget. The `_draw` function must extended, as the base class does no drawing itself, instead just setting up color rules.
 
+In addition, any widget class you develop must have the arguments `(self, id, title, grid, row, column, row_span, column_span, padx, pady, logger)` in it's initializer, in that order, so that the `add_custom_widget` function will  work. Additional arguments or keyword arguments can follow these.
+
 **Step 3 - Add Key Bindings**
 
 Next, add any default key bindings you wish to have for the widget when in focus mode. In the case of the scroll menu, we wish for the arrow keys to scroll up and down, so we extend the `handle_key_press` function:
@@ -199,43 +202,20 @@ def _draw(self):
 
 Note that you should call `super()._draw()` and `self._renderer.set_color_mode(self._color)` at the start of the function (to initialize color modes), and `self._renderer.unset_color_mode(self._color)` and `self._renderer.reset_cursor(self)` to remove color settings, and place the cursor in the correct location.
 
-**Step 5 - Add a function to `PyCUI` class to add the widget**
+**Step 5 - Use the add_custom_widget function to add your widget to your TUI**
+
+Finally, you are ready to add an instance of your widget to the TUI. To do this, use the `add_custom_widget` function. See the below example adding our above widget. Optionally, you may want to add a conveniance function specifically meant to add instances of your widget to the TUI. In our example it would be `add_scroll_menu`, which can be found in `py_cui/__init__.py`.
 
-Finally, add a function to the `PyCUI` class in `__init__.py` that will add the widget to the CUI. In our case we write the following:
 ```Python
-def add_scroll_menu(self, title, row, column, row_span = 1, column_span = 1, padx = 1, pady = 0):
-
-    id = f'Widget{len(self.get_widgets().keys())}'
-    new_scroll_menu = widgets.ScrollMenu(   id, 
-                                            title, 
-                                            self._grid, 
-                                            row, 
-                                            column, 
-                                            row_span, 
-                                            column_span, 
-                                            padx, 
-                                            pady, 
-                                            self._logger)
-    self.get_widgets()[id] = new_scroll_menu
-    if self._selected_widget is None:
-        self.set_selected_widget(id)
-    self._logger.debug(f'Adding widget {title} w/ ID {id} of type {str(type(new_scroll_menu))}'
-    return new_scroll_menu
-```
-The function must:
-
-* Create an id titled 'Widget####' where #### is replaced with the number of widget
-* Add the widget to the PyCUI widgets dict with the ID as a key
-* If there is no selected widget, make this new widget the selected one
-* Return a reference to the widget
+# add_custom_widget(Widget class, title, row, column, rowspan, colspan, padx, pady)
+my_widget = root.add_custom_widget(py_cui.widgets.ScrollMenu, "My Title", 1, 1, 1, 1, 1, 1)
+```
 
-**That's it!**
+Note the `add_custom_widget` function signature expects your class that extends `Widget` as the first argument, followed by critical widget information. You can also add additional `*args` and `**kwargs` to the funtion call. The function will return an instance of the initial class with all the remaining arguments passed in in order.
 
-Your widget is now ready to be added to the CUI! Simply call the add function with appropriate parameters on the root `PyCUI` window:
+**That's it!**
 
-```Python
-root.add_scroll_menu('Demo', 1, 1)
-```
+Your widget should now be added to the CUI!
 
 ### Adding a new Popup
 

examples/popups_example.py

@@ -69,7 +69,7 @@ def quit_cui(self, to_quit):
 
     def show_text_box(self):
         # Here, reset title is a function that takes a string parameter, which will be the user entered string
-        self.master.show_text_box_popup('Please enter a new window title', self.reset_title)
+        self.master.show_text_box_popup('Please enter a new window title', self.reset_title, initial_text='New Title')
 
     def reset_title(self, new_title):
         self.master.set_title(new_title)