From a629760ce88300e9c390479ed06c9b5408e5310c Mon Sep 17 00:00:00 2001 From: PySimpleGUI Date: Mon, 3 Aug 2020 05:35:10 -0400 Subject: [PATCH] Release 4.27.1 --- PySimpleGUI.py | 31 +++-- docs/call reference.md | 270 +++++++++++++++++++++++++---------------- docs/index.md | 45 +++++++ readme.md | 45 +++++++ 4 files changed, 276 insertions(+), 115 deletions(-) diff --git a/PySimpleGUI.py b/PySimpleGUI.py index dba8c63d..9ebe1543 100644 --- a/PySimpleGUI.py +++ b/PySimpleGUI.py @@ -1,5 +1,5 @@ #!/usr/bin/python3 -version = __version__ = "4.26.0.18 Unreleased\nNew Sponsor button, highly experimental read_all_windows(), search option for theme previewer, theme button in main, progress bar color can use new 'on' format, combined ProgressBar.update_bar with ProgressBar.update so now only update is needed, theme previewer restore previous theme, raise KeyError when find_element or window[] hits a bad key (unless find_element has silent error set), better traceback shown on key errors, fix for get item, formatting of error location information. raise key error by default, added up / down arrow bindings for spinner if enabling events, key guessing attempt for bad lookups, read_all_windows - close window when X found, new Multiline Justification parameter for both creation and update, fix for return keyboard/mouse events when reading all windows, added mousewheel for linux for return_keyboard_events, added get_globals, support for timeout=0 on read_all_windows" +version = __version__ = "4.27.1 Released 3-Aug-2020" port = 'PySimpleGUI' @@ -2164,6 +2164,8 @@ class Multiline(Element): :type pad: (int, int) or ((int, int),(int,int)) or (int,(int,int)) or ((int, int),int) :param tooltip: text, that will appear when mouse hovers over the element :type tooltip: (str) + :param justification: text justification. left, right, center. Can use single characters l, r, c. + :type justification: (str) :param right_click_menu: A list of lists of Menu items to show when this element is right clicked. See user docs for exact format. :type right_click_menu: List[List[Union[List[str],str]]] :param visible: set visibility state of the element @@ -2222,6 +2224,8 @@ class Multiline(Element): :type visible: (bool) :param autoscroll: if True then contents of element are scrolled down when new text is added to the end :type autoscroll: (bool) + :param justification: text justification. left, right, center. Can use single characters l, r, c. Sets only for this value, not entire element + :type justification: (str) """ if not self._widget_was_created(): # if widget hasn't been created yet, then don't allow @@ -2324,27 +2328,41 @@ class Multiline(Element): :type text_color: (str) :param background_color: The background color of the line :type background_color: (str) + :param justification: text justification. left, right, center. Can use single characters l, r, c. Sets only for this value, not entire element + :type justification: (str) """ _print_to_element(self, *args, end=end, sep=sep, text_color=text_color, background_color=background_color, justification=justification ) def reroute_stdout_to_here(self): + """ + Sends stdout (prints) to this element + """ self.previous_stdout = sys.stdout sys.stdout = self def reroute_stderr_to_here(self): + """ + Sends stderr to this element + """ self.previous_stderr = sys.stderr sys.stderr = self def restore_stdout(self): + """ + Restore a previously re-reouted stdout back to the original destination + """ if self.previous_stdout: sys.stdout = self.previous_stdout def restore_stderr(self): - if self.previous_stderr: - sys.stderr = self.previous_stderr + """ + Restore a previously re-reouted stderr back to the original destination + """ + if self.previous_stderr: + sys.stderr = self.previous_stderr def write(self, txt): @@ -10229,10 +10247,6 @@ def _BuildResults(form, initialize_only, top_level_form): _BuildResultsForSubform(form, initialize_only, top_level_form) if not top_level_form.LastButtonClickedWasRealtime: top_level_form.LastButtonClicked = None - # print(f'Built results = {form.ReturnValues}') - curframe = inspect.currentframe() - calframe = inspect.getouterframes(curframe, 2) - # print('caller name:', calframe[1][3]) return form.ReturnValues @@ -12915,7 +12929,6 @@ def cprint_set_output_destination(window, multiline_key): -# def cprint(*args, **kwargs): def cprint(*args, end=None, sep=' ', text_color=None, t=None, background_color=None, b=None, colors=None, c=None, window=None, key=None, justification=None): """ Color print to a multiline element in a window of your choice. @@ -12966,6 +12979,8 @@ def cprint(*args, end=None, sep=' ', text_color=None, t=None, background_color=N :param key: key of multiline to output to (if you want to override the one previously set) :type key: (Any) :param window: Window containing the multiline to output to (if you want to override the one previously set) + :param justification: text justification. left, right, center. Can use single characters l, r, c. Sets only for this value, not entire element + :type justification: (str) :type window: (Window) :return: None :rtype: None diff --git a/docs/call reference.md b/docs/call reference.md index 6ef7c941..8c44a2d9 100644 --- a/docs/call reference.md +++ b/docs/call reference.md @@ -4350,6 +4350,7 @@ Parameter Descriptions: | Union[str, Tuple[str, int]] | font | specifies the font family, size, etc | | (int, int) or ((int, int),(int,int)) or (int,(int,int)) or ((int, int),int) | pad | Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom)) | | str | tooltip | text, that will appear when mouse hovers over the element | +| str | justification | text justification. left, right, center. Can use single characters l, r, c. | | List[List[Union[List[str],str]]] | right_click_menu | A list of lists of Menu items to show when this element is right clicked. See user docs for exact format. | | bool | visible | set visibility state of the element | | Any | metadata | User metadata that can be set to ANYTHING | @@ -4422,6 +4423,7 @@ Parameter Descriptions: | str | background_color | color of background | | bool | visible | set visibility state of the element | | bool | autoscroll | if True then contents of element are scrolled down when new text is added to the end | +| str | justification | text justification. left, right, center. Can use single characters l, r, c. Sets only for this value, not entire element | ### bind @@ -4508,15 +4510,40 @@ Parameter Descriptions: | str | sep | The separation character like print uses | | str | text_color | The color of the text | | str | background_color | The background color of the line | +| str | justification | text justification. left, right, center. Can use single characters l, r, c. Sets only for this value, not entire element | ### reroute_stderr_to_here +Sends stderr to this element + +```python +reroute_stderr_to_here() +``` + ### reroute_stdout_to_here +Sends stdout (prints) to this element + +```python +reroute_stdout_to_here() +``` + ### restore_stderr +Restore a previously re-reouted stderr back to the original destination + +```python +restore_stderr() +``` + ### restore_stdout +Restore a previously re-reouted stdout back to the original destination + +```python +restore_stdout() +``` + ### set_cursor Sets the cursor for the current Element. @@ -4641,6 +4668,7 @@ Parameter Descriptions: | str | background_color | color of background | | bool | visible | set visibility state of the element | | bool | autoscroll | if True then contents of element are scrolled down when new text is added to the end | +| str | justification | text justification. left, right, center. Can use single characters l, r, c. Sets only for this value, not entire element | ## OptionMenu Element @@ -8710,7 +8738,6 @@ Window(title, ttk_theme=None, use_ttk_buttons=None, modal=False, - subwindow=False, metadata=None) ``` @@ -9914,6 +9941,23 @@ Parameter Descriptions: These are the functions available for you to call +## Multi-window Interface + +Reads a list of windows. If any of the list returns a value then the window and its event and values +are returned. + +``` +read_all_windows(timeout=None, timeout_key="__TIMEOUT__") +``` + +Parameter Descriptions: + +|Type|Name|Meaning| +|--|--|--| +| int | timeout | Time in milliseconds to delay before a returning a timeout event | +| Any | timeout_key | Key to return when a timeout happens. Defaults to the standard TIMEOUT_KEY | +| Tuple[Window, Any, (Dict or List)] | **RETURN** | A tuple with the (Window, event, values dictionary/list) + ## Button Related Button that will show a calendar chooser window. Fills in the target element with result @@ -11194,7 +11238,7 @@ Parameter Descriptions: | str | end | end character | | str | sep | separator character | | Any | key | key of multiline to output to (if you want to override the one previously set) | -| Window | window | Window containing the multiline to output to (if you want to override the one previously set) | +| str | window | Window containing the multiline to output to (if you want to override the one previously set) :param justification: text justification. left, right, center. Can use single characters l, r, c. Sets only for this value, not entire element | | None | **RETURN** | None Sets up the color print (cprint) output destination @@ -13517,111 +13561,6 @@ Parameter Descriptions: | Any | obj | The object to display | | (str) | **RETURN** | Formatted output of the object's values -## Settings - -Sets the icon which will be used any time a window is created if an icon is not provided when the -window is created. - -``` -set_global_icon(icon) -``` - -Parameter Descriptions: - -|Type|Name|Meaning| -|--|--|--| -| Union[bytes, str] | icon | Either a Base64 byte string or a filename | -| None | **RETURN** | None - -``` -set_options(icon=None, - button_color=None, - element_size=(None, None), - button_element_size=(None, None), - margins=(None, None), - element_padding=(None, None), - auto_size_text=None, - auto_size_buttons=None, - font=None, - border_width=None, - slider_border_width=None, - slider_relief=None, - slider_orientation=None, - autoclose_time=None, - message_box_line_width=None, - progress_meter_border_depth=None, - progress_meter_style=None, - progress_meter_relief=None, - progress_meter_color=None, - progress_meter_size=None, - text_justification=None, - background_color=None, - element_background_color=None, - text_element_background_color=None, - input_elements_background_color=None, - input_text_color=None, - scrollbar_color=None, - text_color=None, - element_text_color=None, - debug_win_size=(None, None), - window_location=(None, None), - error_button_color=(None, None), - tooltip_time=None, - tooltip_font=None, - use_ttk_buttons=None, - ttk_theme=None, - suppress_error_popups=None, - suppress_raise_key_errors=None, - suppress_key_guessing=None, - enable_treeview_869_patch=None) -``` - -Parameter Descriptions: - -|Type|Name|Meaning| -|--|--|--| -| Union[bytes, str] | icon | filename or base64 string to be used for the window's icon | -| Tuple[str, str] or str | button_color | Color of the button (text, background) | -| (int, int) | element_size | element size (width, height) in characters | -| (int, int) | button_element_size | Size of button | -| Tuple[int, int] | margins | (left/right, top/bottom) tkinter margins around outsize. Amount of pixels to leave inside the window's frame around the edges before your elements are shown. | -| Tuple[int, int] or ((int, int),(int,int)) | element_padding | Default amount of padding to put around elements in window (left/right, top/bottom) or ((left, right), (top, bottom)) | -| bool | auto_size_text | True if the Widget should be shrunk to exactly fit the number of chars to show | -| bool | auto_size_buttons | True if Buttons in this Window should be sized to exactly fit the text on this. | -| Union[str, Tuple[str, int]] | font | specifies the font family, size, etc | -| int | border_width | width of border around element | -| ??? | slider_border_width | ??? | -| ??? | slider_relief | ??? | -| ??? | slider_orientation | ??? | -| ??? | autoclose_time | ??? | -| ??? | message_box_line_width | ??? | -| ??? | progress_meter_border_depth | ??? | -| ??? | progress_meter_style | You can no longer set a progress bar style. All ttk styles must be the same for the window | -| ??? | progress_meter_relief | | -| ??? | progress_meter_color | ??? | -| ??? | progress_meter_size | ??? | -| Union['left', 'right', 'center'] | text_justification | Default text justification for all Text Elements in window | -| str | background_color | color of background | -| str | element_background_color | element background color | -| str | text_element_background_color | text element background color | -| idk_yetReally | input_elements_background_color | ??? | -| ??? | input_text_color | ??? | -| ??? | scrollbar_color | ??? | -| str | text_color | color of the text | -| ??? | element_text_color | ??? | -| Tuple[int, int] | debug_win_size | window size | -| ??? | window_location | (Default = (None)) | -| ??? | error_button_color | (Default = (None)) | -| int | tooltip_time | time in milliseconds to wait before showing a tooltip. Default is 400ms | -| str or Tuple[str, int] or Tuple[str, int, str] | tooltip_font | font to use for all tooltips | -| bool | use_ttk_buttons | if True will cause all buttons to be ttk buttons | -| str | ttk_theme | Theme to use with ttk widgets. Choices (on Windows) include - 'default', 'winnative', 'clam', 'alt', 'classic', 'vista', 'xpnative' | -| bool | suppress_error_popups | If True then error popups will not be shown if generated internally to PySimpleGUI | -| bool | suppress_raise_key_errors | If True then key errors won't be raised (you'll still get popup error) | -| bool | suppress_key_guessing | If True then key errors won't try and find closest matches for you | -| bool | enable_treeview_869_patch | If True, then will use the treeview color patch for tk 8.6.9 | -| None | **RETURN** | None - ### Non PEP8 version (same as PEP8 version) Sets the icon which will be used any time a window is created if an icon is not provided when the @@ -14022,6 +13961,123 @@ Parameter Descriptions: | (Dict[Any:Any]) | values_dict | A dictionary with element keys as key and value is values parm for Update call | | None | **RETURN** | None +## Configuration / Settings / Extensions + +Returns the dictionary of the global variables + +``` +get_globals() +``` + +Parameter Descriptions: + +|Type|Name|Meaning| +|--|--|--| +| Dict[str, Any] | **RETURN** | the gobals dictionary + +Sets the icon which will be used any time a window is created if an icon is not provided when the +window is created. + +``` +set_global_icon(icon) +``` + +Parameter Descriptions: + +|Type|Name|Meaning| +|--|--|--| +| Union[bytes, str] | icon | Either a Base64 byte string or a filename | +| None | **RETURN** | None + +``` +set_options(icon=None, + button_color=None, + element_size=(None, None), + button_element_size=(None, None), + margins=(None, None), + element_padding=(None, None), + auto_size_text=None, + auto_size_buttons=None, + font=None, + border_width=None, + slider_border_width=None, + slider_relief=None, + slider_orientation=None, + autoclose_time=None, + message_box_line_width=None, + progress_meter_border_depth=None, + progress_meter_style=None, + progress_meter_relief=None, + progress_meter_color=None, + progress_meter_size=None, + text_justification=None, + background_color=None, + element_background_color=None, + text_element_background_color=None, + input_elements_background_color=None, + input_text_color=None, + scrollbar_color=None, + text_color=None, + element_text_color=None, + debug_win_size=(None, None), + window_location=(None, None), + error_button_color=(None, None), + tooltip_time=None, + tooltip_font=None, + use_ttk_buttons=None, + ttk_theme=None, + suppress_error_popups=None, + suppress_raise_key_errors=None, + suppress_key_guessing=None, + enable_treeview_869_patch=None) +``` + +Parameter Descriptions: + +|Type|Name|Meaning| +|--|--|--| +| Union[bytes, str] | icon | filename or base64 string to be used for the window's icon | +| Tuple[str, str] or str | button_color | Color of the button (text, background) | +| (int, int) | element_size | element size (width, height) in characters | +| (int, int) | button_element_size | Size of button | +| Tuple[int, int] | margins | (left/right, top/bottom) tkinter margins around outsize. Amount of pixels to leave inside the window's frame around the edges before your elements are shown. | +| Tuple[int, int] or ((int, int),(int,int)) | element_padding | Default amount of padding to put around elements in window (left/right, top/bottom) or ((left, right), (top, bottom)) | +| bool | auto_size_text | True if the Widget should be shrunk to exactly fit the number of chars to show | +| bool | auto_size_buttons | True if Buttons in this Window should be sized to exactly fit the text on this. | +| Union[str, Tuple[str, int]] | font | specifies the font family, size, etc | +| int | border_width | width of border around element | +| ??? | slider_border_width | ??? | +| ??? | slider_relief | ??? | +| ??? | slider_orientation | ??? | +| ??? | autoclose_time | ??? | +| ??? | message_box_line_width | ??? | +| ??? | progress_meter_border_depth | ??? | +| ??? | progress_meter_style | You can no longer set a progress bar style. All ttk styles must be the same for the window | +| ??? | progress_meter_relief | | +| ??? | progress_meter_color | ??? | +| ??? | progress_meter_size | ??? | +| Union['left', 'right', 'center'] | text_justification | Default text justification for all Text Elements in window | +| str | background_color | color of background | +| str | element_background_color | element background color | +| str | text_element_background_color | text element background color | +| idk_yetReally | input_elements_background_color | ??? | +| ??? | input_text_color | ??? | +| ??? | scrollbar_color | ??? | +| str | text_color | color of the text | +| ??? | element_text_color | ??? | +| Tuple[int, int] | debug_win_size | window size | +| ??? | window_location | (Default = (None)) | +| ??? | error_button_color | (Default = (None)) | +| int | tooltip_time | time in milliseconds to wait before showing a tooltip. Default is 400ms | +| str or Tuple[str, int] or Tuple[str, int, str] | tooltip_font | font to use for all tooltips | +| bool | use_ttk_buttons | if True will cause all buttons to be ttk buttons | +| str | ttk_theme | Theme to use with ttk widgets. Choices (on Windows) include - 'default', 'winnative', 'clam', 'alt', 'classic', 'vista', 'xpnative' | +| bool | suppress_error_popups | If True then error popups will not be shown if generated internally to PySimpleGUI | +| bool | suppress_raise_key_errors | If True then key errors won't be raised (you'll still get popup error) | +| bool | suppress_key_guessing | If True then key errors won't try and find closest matches for you | +| bool | enable_treeview_869_patch | If True, then will use the treeview color patch for tk 8.6.9 | +| None | **RETURN** | None + ## Old Themes (Look and Feel) - Replaced by theme() Change the "color scheme" of all future PySimpleGUI Windows. diff --git a/docs/index.md b/docs/index.md index 803e4a34..a35de781 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7629,6 +7629,51 @@ k element parameter * Window.write_event_values - now requires both parms * Upgrade button typo +## 4.27.1 PySimpleGUI 3-Aug-2020 + +Multi-window support done right! +New capabilities for printing, Multiline +Main app additions +Theme searching + +* read_all_windows - function that reads all currently open windows. + * Finally the efficient multi-window solution + * No longer need to do round-robin type scheduling + * Easily convert existing programs from single to multi-windows + * Demo programs with multi-window design patterns all updated + * Ideal for "floating palette / toolbar" window adds-ons + * Can read with timeout including timeout=0 +* theme_previewer + * search option + * button in main app + * reset to previous theme following preview +* Sponsor button in main app +* Theme previewer in main app +* Progress bar + * colors can use the single string "foreground on background" color format + * update_bar combined with update for a single update interface +* Better element key error handling + * 3 options to control how lookup errors are handled + * popup now shows + * file, function, line #, actual line of code with error + * erroneous key provided + * best matching key + * will automatically try to continue with best matching key + * can assert with key error if desired (true by default) +* fix for get item +* Up/down arrow bindings for spinner if enabling events +* Multiline + * new justification parameter on creation and update + * print - justification parameter added +* cprint - justification parameter added - note tricky to set color of single word but possible +* Added mousewheel for Linux return_keyboard_events enabled +* Added get_globals function for extending easier +* Refactored callbacks +* Image element - can clear image by not setting any parameters when calling update +* Column Element's Widget member variable now being set +* Window's starting window location saved +* Early experimental "Move all windows in sync" when using grab_anywhere (coming soon) + ### Upcoming There will always be overlapping work as the ports will never actually be "complete" as there's always something new that can be built. However there's a definition for the base functionality for PySimpleGUI. This is what is being strived for with the current ports that are underway. diff --git a/readme.md b/readme.md index 803e4a34..a35de781 100644 --- a/readme.md +++ b/readme.md @@ -7629,6 +7629,51 @@ k element parameter * Window.write_event_values - now requires both parms * Upgrade button typo +## 4.27.1 PySimpleGUI 3-Aug-2020 + +Multi-window support done right! +New capabilities for printing, Multiline +Main app additions +Theme searching + +* read_all_windows - function that reads all currently open windows. + * Finally the efficient multi-window solution + * No longer need to do round-robin type scheduling + * Easily convert existing programs from single to multi-windows + * Demo programs with multi-window design patterns all updated + * Ideal for "floating palette / toolbar" window adds-ons + * Can read with timeout including timeout=0 +* theme_previewer + * search option + * button in main app + * reset to previous theme following preview +* Sponsor button in main app +* Theme previewer in main app +* Progress bar + * colors can use the single string "foreground on background" color format + * update_bar combined with update for a single update interface +* Better element key error handling + * 3 options to control how lookup errors are handled + * popup now shows + * file, function, line #, actual line of code with error + * erroneous key provided + * best matching key + * will automatically try to continue with best matching key + * can assert with key error if desired (true by default) +* fix for get item +* Up/down arrow bindings for spinner if enabling events +* Multiline + * new justification parameter on creation and update + * print - justification parameter added +* cprint - justification parameter added - note tricky to set color of single word but possible +* Added mousewheel for Linux return_keyboard_events enabled +* Added get_globals function for extending easier +* Refactored callbacks +* Image element - can clear image by not setting any parameters when calling update +* Column Element's Widget member variable now being set +* Window's starting window location saved +* Early experimental "Move all windows in sync" when using grab_anywhere (coming soon) + ### Upcoming There will always be overlapping work as the ports will never actually be "complete" as there's always something new that can be built. However there's a definition for the base functionality for PySimpleGUI. This is what is being strived for with the current ports that are underway.