From d2bb47b9a8f2d637a2c694ecd000d82a813c394e Mon Sep 17 00:00:00 2001 From: MikeTheWatchGuy Date: Tue, 3 Sep 2019 17:30:03 -0400 Subject: [PATCH] Old doc was missing the __init__ info!! Ouch! Sorry about that. --- docs/index.md | 1124 +++++++++++++++++++++++++++++++++++++++++++++++-- readme.md | 1124 +++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 2194 insertions(+), 54 deletions(-) diff --git a/docs/index.md b/docs/index.md index 1ccf0b5c..e2a23308 100644 --- a/docs/index.md +++ b/docs/index.md @@ -889,6 +889,7 @@ Features of PySimpleGUI include: - Movable windows - Animated GIFs - No async programming required (no callbacks to worry about) +- Built-in debugger and REPL - User expandable by accessing underlying GUI Framework widgets directly --- @@ -925,7 +926,7 @@ The Single Line Progress Meter is a good example. It requires one and only 1 lin Be Pythonic... -This one is difficult for me to define. The code implementing PySimpleGUI isn't PEP8 compliant, but it is consistent. The important thing was what the user saw and experienced while coding, NOT the choices for naming conventions in the implementation code. +This one is difficult for me to define. The code implementing PySimpleGUI isn't PEP8 compliant, but it is consistent. The important thing was what the user saw and experienced while coding, NOT the choices for naming conventions in the implementation code. The user interface to PySimpleGUI now has a PEP8 compliant interface. The methods are snake_case now (in addition to retaining the older CamelCase names) I ended up defining it as - attempt to use language constructs in a natural way and to exploit some of Python's interesting features. It's Python's lists and optional parameters make PySimpleGUI work smoothly. @@ -1144,11 +1145,11 @@ Then use either "high level" API calls or build your own windows. Yes, it's just that easy to have a window appear on the screen using Python. With PySimpleGUI, making a custom window appear isn't much more difficult. The goal is to get you running on your GUI within ***minutes***, not hours nor days. -***WARNING*** Do NOT use PySimpleGUI with Python 3.7.4. tkiter is having issues with that release. Things like Table colors stopped working entirely. None of us want to debug tkinter code. It's difficult enough debugging your code and PySimpleGUI code. +***WARNING*** Do NOT use PySimpleGUI with Python 3.7.3 and 3.7.4. tkiter is having issues with that release. Things like Table colors stopped working entirely. None of us want to debug tkinter code. It's difficult enough debugging your code and PySimpleGUI code. A lot of time has already been spent debugging this one so no need for you to suffer too. ### Python 3.7 -It puzzles me why a beginner would install 3.7. Or even a seasoned programmer. What specific feature of 3.7 are you using that is not in 3.6? If you are unable to answer this, then ***you should be running 3.6***, an immensely solid release of Python. If you must run 3.7, try 3.7.2 instead. It does work with PySimpleGUI with no known issues. +It puzzles me why a beginner would install 3.7. Or even a seasoned programmer. What specific feature of 3.7 are you using that is not in 3.6? If you are unable to answer this, then ***it's strongly suggested that you run 3.6***, an immensely solid release of Python with all those goodie inside like f-strings. If you must run 3.7, try 3.7.2 instead. It does work with PySimpleGUI with no known issues. ## Using - Python 2.7 @@ -2983,7 +2984,15 @@ Then when you read the `values` variable that's returned to you from calling `Wi `values[(row, col)]` Most of the time they are simple text strings. In the Demo Programs, keys are written with this convention: -`_KEY_NAME_` (underscore at beginning and end with all caps letters). You don't have to follow that convention. It's used so that you can quickly spot when a key is being used. +`_KEY_NAME_` (underscore at beginning and end with all caps letters) or '-KEY_NAME-. You don't have to follow that convention. It's used so that you can quickly spot when a key is being used. + +To find an element's key, access the member variable `.Key` for the element. This assumes you've got the element in a variable already. + +```python +text_elem = sg.Text('', key='-TEXT-') + +the_key = text_elem.Key +``` #### Visible @@ -4736,7 +4745,7 @@ The plain PySimpleGUI module has a debugger builtin. For the other ports, pleas This debugger provides you with something unique to most typical Python developers, the ability to "see" and interact with your code, **while it is running**. You can change variable values while your code continues to run. -Print statements are cool, but perhaps you're tired of seeing this: +Print statements are cool, but perhaps you're tired of seeing a printout of `event` and `values`: ``` Push Me {0: 'Input here'} Push Me {0: 'Input here'} @@ -4808,6 +4817,14 @@ One "variable" shown in the popout window that is an often asked for piece of in Exiting this window is done via the little red X, **or using the rickt-click menu** which is also used as one way to launch the Main Debugger Window +#### Ways of Launching the Popout Window + +There are 3 ways of opening the Popout window. + +1. Press the `BREAK` key on your keyboard. +2. Call the function `show_debugger_popout_window(location=(x,y))` +3. Add `Debug()` button to your layout - adds a little purple and yellow PySimpleGUI logo to your window + #### When you are asked for the "Location of your PySimpleGUI package or PySimpleGUI.py file" do this If you wish to use the debugger to find the location of THIS running program's PySimpleGUI package / the PySimpleGUI.py file, then all you need to do is: @@ -4834,6 +4851,14 @@ Ever wish you had a `repl>>>` prompt that you could run while your program is ru You'll find that this window has 2 tabs, one is labelled `Variables` and the other is labelled `REPL & Watches` +#### Ways of Opening the Main Debugger Window + +There are 3 ways to open the Main Debugger Window + +1. Press `Control` + `Break` on your PC keyboard +2. From the Popout Debug Window, right click and choose `Debugger` from the right click menu +3. From your code call `show_debugger_window(location=(x,y))` + #### The "Variables" Tab of Main Debugger Window ![SNAG-0440](https://user-images.githubusercontent.com/13696193/62797391-a01ceb80-baa9-11e9-845d-3cd02ca0dbcc.jpg) @@ -5072,6 +5097,60 @@ Without further delay... here are all of the Elements Button Element - Defines all possible buttons. The shortcuts such as Submit, FileBrowse, ... each create a Button +``` +Button(button_text="", + button_type=7, + target=(None, None), + tooltip=None, + file_types=(('ALL Files', '*.*'),), + initial_folder=None, + disabled=False, + change_submits=False, + enable_events=False, + image_filename=None, + image_data=None, + image_size=(None, None), + image_subsample=None, + border_width=None, + size=(None, None), + auto_size_button=None, + button_color=None, + font=None, + bind_return_key=False, + focus=False, + pad=None, + key=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|button_text|(str) Text to be displayed on the button| +|button_type|(int) You should NOT be setting this directly. ONLY the shortcut functions set this| +|target|Union[str, Tuple[int, int]] key or (row,col) target for the button. Note that -1 for column means 1 element to the left of this one. The constant ThisRow is used to indicate the current row. The Button itself is a valid target for some types of button| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|file_types|Tuple[Tuple[str, str], ...] the filetypes that will be used to match files. To indicate all files: (("ALL Files", "*.*"),). Note - NOT SUPPORTED ON MAC| +|initial_folder|(str) starting path for folders and files| +|disabled|(bool) If True button will be created disabled| +|click_submits|(bool) DO NOT USE. Only listed for backwards compat - Use enable_events instead| +|enable_events|(bool) Turns on the element specific events. If this button is a target, should it generate an event when filled in| +|image_filename|(str) image filename if there is a button image. GIFs and PNGs only.| +|image_data|Union[bytes, str] Raw or Base64 representation of the image to put on button. Choose either filename or data| +|image_size|Tuple[int, int] Size of the image in pixels (width, height)| +|image_subsample|(int) amount to reduce the size of the image. Divides the size by this number. 2=1/2, 3=1/3, 4=1/4, etc| +|border_width|(int) width of border around button in pixels| +|size|Tuple[int, int] (width, height) of the button in characters wide, rows high| +|auto_size_button|(bool) if True the button size is sized to fit the text| +|button_color|Tuple[str, str] (text color, background color) of button. Easy to remember which is which if you say "ON" between colors. "red" on "green". Note - Does not always work on Macs| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|bind_return_key|(bool) If True the return key will cause this button to be pressed| +|focus|(bool) if True, initial focus will be put on this button| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element to uniquely identify this element| +|visible|(bool) set visibility state of the element| + #### Click Generates a click of the button as if the user clicked the button @@ -5151,6 +5230,48 @@ Parameter Descriptions: The Button Menu Element. Creates a button that when clicked will show a menu similar to right click menu +``` +ButtonMenu(button_text, + menu_def, + tooltip=None, + disabled=False, + image_filename=None, + image_data=None, + image_size=(None, None), + image_subsample=None, + border_width=None, + size=(None, None), + auto_size_button=None, + button_color=None, + font=None, + pad=None, + key=None, + tearoff=False, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|button_text|(str) Text to be displayed on the button| +|menu_def|List[List[str]] A list of lists of Menu items to show when this element is clicked. See docs for format as they are the same for all menu types| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|disabled|(bool) If True button will be created disabled| +|image_filename|(str) image filename if there is a button image. GIFs and PNGs only.| +|image_data|Union[bytes, str] Raw or Base64 representation of the image to put on button. Choose either filename or data| +|image_size|Tuple[int, int] Size of the image in pixels (width, height)| +|image_subsample|(int) amount to reduce the size of the image. Divides the size by this number. 2=1/2, 3=1/3, 4=1/4, etc| +|border_width|(int) width of border around button in pixels| +|size|Tuple[int, int] (width, height) of the button in characters wide, rows high| +|auto_size_button|(bool) if True the button size is sized to fit the text| +|button_color|Tuple[str, str] (text color, background color) of button. Easy to remember which is which if you say "ON" between colors. "red" on "green"| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element to uniquely identify this element| +|tearoff|(bool) Determines if menus should allow them to be torn off| +|visible|(bool) set visibility state of the element| + #### SetFocus Sets the current focus to be on this element @@ -5196,6 +5317,30 @@ Parameter Descriptions: ### Canvas Element +``` +Canvas(canvas=None, + background_color=None, + size=(None, None), + pad=None, + key=None, + tooltip=None, + right_click_menu=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|canvas|(tk.Canvas) Your own tk.Canvas if you already created it. Leave blank to create a Canvas| +|background_color|(str) color of background| +|size|Tuple[int,int] (width in char, height in rows) size in pixels to make canvas| +|pad|Amount of padding to put around element| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|visible|(bool) set visibility state of the element| + #### SetFocus Sets the current focus to be on this element @@ -5226,12 +5371,46 @@ Parameter Descriptions: #### TKCanvas -#### property: TKCanvas - ### Checkbox Element Checkbox Element - Displays a checkbox and text next to it +``` +Checkbox(text, + default=False, + size=(None, None), + auto_size_text=None, + font=None, + background_color=None, + text_color=None, + change_submits=False, + enable_events=False, + disabled=False, + key=None, + pad=None, + tooltip=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|text|(str) Text to display next to checkbox| +|default|(bool). Set to True if you want this checkbox initially checked| +|size|Tuple[int, int] (width, height) width = characters-wide, height = rows-high| +|auto_size_text|(bool) if True will size the element to match the length of the text| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|background_color|(str) color of background| +|text_color|(str) color of the text| +|change_submits|(bool) DO NOT USE. Only listed for backwards compat - Use enable_events instead| +|enable_events|(bool) Turns on the element specific events. Checkbox events happen when an item changes| +|disabled|(bool) set disable state| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|visible|(bool) set visibility state of the element| + #### Get Return the current state of this checkbox @@ -5293,6 +5472,36 @@ Parameter Descriptions: A container element that is used to create a layout within your window's layout +``` +Column(layout, + background_color=None, + size=(None, None), + pad=None, + scrollable=False, + vertical_scroll_only=False, + right_click_menu=None, + key=None, + visible=True, + justification="left", + element_justification="left") +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|layout|List[List[Element]] Layout that will be shown in the Column container| +|background_color|(str) color of background of entire Column| +|size|Tuple[int, int] (width, height) size in pixels (doesn't work quite right, sometimes only 1 dimension is set by tkinter| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|scrollable|(bool) if True then scrollbars will be added to the column| +|vertical_scroll_only|(bool) if Truen then no horizontal scrollbar will be shown| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|key|(any) Value that uniquely identifies this element from all other elements. Used when Finding an element or in return values. Must be unique to the window| +|visible|(bool) set visibility state of the element| +|justification|(str) set justification for the Column itself. Note entire row containing the Column will be affected| +|element_justification|(str) All elements inside the Column will have this justification 'left', 'right', 'center' are valid values| + #### AddRow Not recommended user call. Used to add rows of Elements to the Column Element. @@ -5369,6 +5578,44 @@ Parameter Descriptions: ComboBox Element - A combination of a single-line input and a drop-down menu. User can type in their own value or choose from list. +``` +Combo(values, + default_value=None, + size=(None, None), + auto_size_text=None, + background_color=None, + text_color=None, + change_submits=False, + enable_events=False, + disabled=False, + key=None, + pad=None, + tooltip=None, + readonly=False, + font=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|values|List[Any] values to choose. While displayed as text, the items returned are what the caller supplied, not text| +|default_value|(Any) Choice to be displayed as initial value. Must match one of values variable contents| +|size|Tuple[int, int] (width, height) width = characters-wide, height = rows-high| +|auto_size_text|(bool) True if element should be the same size as the contents| +|background_color|(str) color of background| +|text_color|(str) color of the text| +|change_submits|(bool) DEPRICATED DO NOT USE. Use `enable_events` instead| +|enable_events|(bool) Turns on the element specific events. Combo event is when a choice is made| +|disabled|(bool) set disable state for element| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|tooltip|(str) text that will appear when mouse hovers over this element| +|readonly|(bool) make element readonly (user can't change). True means user cannot change| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|visible|(bool) set visibility state of the element| + #### Get Returns the current (right now) value of the Combo. DO NOT USE THIS AS THE NORMAL WAY OF READING A COMBO! @@ -5438,6 +5685,44 @@ Parameter Descriptions: A Frame Element that contains other Elements. Encloses with a line around elements and a text label. +``` +Frame(title, + layout, + title_color=None, + background_color=None, + title_location=None, + relief="groove", + size=(None, None), + font=None, + pad=None, + border_width=None, + key=None, + tooltip=None, + right_click_menu=None, + visible=True, + element_justification="left") +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|title|(str) text that is displayed as the Frame's "label" or title| +|layout|List[List[Elements]] The layout to put inside the Frame| +|title_color|(str) color of the title text| +|background_color|(str) background color of the Frame| +|title_location|(enum) location to place the text title. Choices include: TITLE_LOCATION_TOP TITLE_LOCATION_BOTTOM TITLE_LOCATION_LEFT TITLE_LOCATION_RIGHT TITLE_LOCATION_TOP_LEFT TITLE_LOCATION_TOP_RIGHT TITLE_LOCATION_BOTTOM_LEFT TITLE_LOCATION_BOTTOM_RIGHT| +|relief|(enum) relief style. Values are same as other elements with reliefs. Choices include RELIEF_RAISED RELIEF_SUNKEN RELIEF_FLAT RELIEF_RIDGE RELIEF_GROOVE RELIEF_SOLID| +|size|Tuple[int, int] (width in characters, height in rows) (note this parameter may not always work)| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|border_width|(int) width of border around element in pixels| +|key|(any) Value that uniquely identifies this element from all other elements. Used when Finding an element or in return values. Must be unique to the window| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|visible|(bool) set visibility state of the element| +|element_justification|(str) All elements inside the Frame will have this justification 'left', 'right', 'center' are valid values| + #### AddRow Not recommended user call. Used to add rows of Elements to the Frame Element. @@ -5522,6 +5807,40 @@ Parameter Descriptions: Mouse click and drag events are possible and return the (x,y) coordinates of the mouse Drawing primitives return an "id" that is referenced when you want to operation on that item (e.g. to erase it) +``` +Graph(canvas_size, + graph_bottom_left, + graph_top_right, + background_color=None, + pad=None, + change_submits=False, + drag_submits=False, + enable_events=False, + key=None, + tooltip=None, + right_click_menu=None, + visible=True, + float_values=False) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|canvas_size|Tuple[int, int] (width, height) size of the canvas area in pixels| +|graph_bottom_left|Tuple[int, int] (x,y) The bottoms left corner of your coordinate system| +|graph_top_right|Tuple[int, int] (x,y) The top right corner of your coordinate system| +|background_color|(str) background color of the drawing area| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|change_submits|(bool) * DEPRICATED DO NOT USE! Same as enable_events| +|drag_submits|(bool) if True and Events are enabled for the Graph, will report Events any time the mouse moves while button down| +|enable_events|(bool) If True then clicks on the Graph are immediately reported as an event. Use this instead of change_submits| +|key|(any) Value that uniquely identifies this element from all other elements. Used when Finding an element or in return values. Must be unique to the window| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|visible|(bool) set visibility state of the element (Default = True)| +|float_values|(bool) If True x,y coordinates are returned as floats, not ints| + #### BringFigureToFront Changes Z-order of figures on the Graph. Brings the indicated figure to the front of all other drawn figures @@ -5882,8 +6201,6 @@ Parameter Descriptions: #### TKCanvas -#### property: TKCanvas - #### Update Changes some of the settings for the Graph Element. Must call `Window.Read` or `Window.Finalize` prior @@ -5903,6 +6220,34 @@ Parameter Descriptions: Image Element - show an image in the window. Should be a GIF or a PNG only +``` +Image(filename=None, + data=None, + background_color=None, + size=(None, None), + pad=None, + key=None, + tooltip=None, + right_click_menu=None, + visible=True, + enable_events=False) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|filename|(str) image filename if there is a button image. GIFs and PNGs only.| +|data|Union[bytes, str] Raw or Base64 representation of the image to put on button. Choose either filename or data| +|background_color|color of background| +|size|Tuple[int, int] (width, height) size of image in pixels| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element to uniquely identify this element| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|visible|(bool) set visibility state of the element| +|enable_events|(bool) Turns on the element specific events. For an Image element, the event is "image clicked"| + #### SetFocus Sets the current focus to be on this element @@ -5971,6 +6316,48 @@ Parameter Descriptions: Display a single text input field. Based on the tkinter Widget `Entry` +``` +InputText(default_text="", + size=(None, None), + disabled=False, + password_char="", + justification=None, + background_color=None, + text_color=None, + font=None, + tooltip=None, + change_submits=False, + enable_events=False, + do_not_clear=True, + key=None, + focus=False, + pad=None, + right_click_menu=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|default_text|(str) Text initially shown in the input box as a default value(Default value = '')| +|size|Tuple[int, int] (width, height) w=characters-wide, h=rows-high| +|disabled|(bool) set disable state for element (Default = False)| +|password_char|(char) Password character if this is a password field (Default value = '')| +|justification|(str) justification for data display. Valid choices - left, right, center| +|background_color|(str) color of background in one of the color formats| +|text_color|(str) color of the text| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|change_submits|(bool) * DEPRICATED DO NOT USE! Same as enable_events| +|enable_events|(bool) If True then changes to this element are immediately reported as an event. Use this instead of change_submits (Default = False)| +|do_not_clear|(bool) If False then the field will be set to blank after ANY event (button, any event) (Default = True)| +|key|(any) Value that uniquely identifies this element from all other elements. Used when Finding an element or in return values. Must be unique to the window| +|focus|(bool) Determines if initial focus should go to this element.| +|pad|(int, int) or ((int, int), (int, int)) Tuple(s). Amount of padding to put around element. Normally (horizontal pixels, vertical pixels) but can be split apart further into ((horizontal left, horizontal right), (vertical above, vertical below))| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|visible|(bool) set visibility state of the element (Default = True)| + #### Get Read and return the current value of the input element. Must call `Window.Read` or `Window.Finalize` prior @@ -6034,6 +6421,49 @@ Parameter Descriptions: A List Box. Provide a list of values for the user to choose one or more of. Returns a list of selected rows when a window.Read() is executed. +``` +Listbox(values, + default_values=None, + select_mode=None, + change_submits=False, + enable_events=False, + bind_return_key=False, + size=(None, None), + disabled=False, + auto_size_text=None, + font=None, + no_scrollbar=False, + background_color=None, + text_color=None, + key=None, + pad=None, + tooltip=None, + right_click_menu=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|values|List[Any] list of values to display. Can be any type including mixed types as long as they have __str__ method| +|default_values|List[Any] which values should be initially selected| +|select_mode|[enum] Select modes are used to determine if only 1 item can be selected or multiple and how they can be selected. Valid choices begin with "LISTBOX_SELECT_MODE_" and include: LISTBOX_SELECT_MODE_SINGLE LISTBOX_SELECT_MODE_MULTIPLE LISTBOX_SELECT_MODE_BROWSE LISTBOX_SELECT_MODE_EXTENDED| +|change_submits|(bool) DO NOT USE. Only listed for backwards compat - Use enable_events instead| +|enable_events|(bool) Turns on the element specific events. Listbox generates events when an item is clicked| +|bind_return_key|(bool) If True, then the return key will cause a the Listbox to generate an event| +|size|Tuple(int, int) (width, height) width = characters-wide, height = rows-high| +|disabled|(bool) set disable state for element| +|auto_size_text|(bool) True if element should be the same size as the contents| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|background_color|(str) color of background| +|text_color|(str) color of the text| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|visible|(bool) set visibility state of the element| + #### GetListValues Returns list of Values provided by the user in the user's format @@ -6125,6 +6555,28 @@ Parameter Descriptions: can see it has a "::" which signifies the beginning of a key. The user will not see the key portion when the menu is shown. The key portion is returned as part of the event. +``` +Menu(menu_definition, + background_color=None, + size=(None, None), + tearoff=False, + pad=None, + key=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|menu_definition|List[List[Tuple[str, List[str]]]| +|background_color|(str) color of the background| +|size|Tuple[int, int] Not used in the tkinter port| +|tearoff|(bool) if True, then can tear the menu off from the window ans use as a floating window. Very cool effect| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|key|(any) Value that uniquely identifies this element from all other elements. Used when Finding an element or in return values. Must be unique to the window| +|visible|(bool) set visibility state of the element| + #### SetFocus Sets the current focus to be on this element @@ -6174,6 +6626,52 @@ Parameter Descriptions: Other PySimpleGUI ports have a separate MultilineInput and MultilineOutput elements. May want to split this one up in the future too. +``` +Multiline(default_text="", + enter_submits=False, + disabled=False, + autoscroll=False, + border_width=None, + size=(None, None), + auto_size_text=None, + background_color=None, + text_color=None, + change_submits=False, + enable_events=False, + do_not_clear=True, + key=None, + focus=False, + font=None, + pad=None, + tooltip=None, + right_click_menu=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|default_text|(str) Initial text to show| +|enter_submits|(bool) if True, the Window.Read call will return is enter key is pressed in this element| +|disabled|(bool) set disable state| +|autoscroll|(bool) If True the contents of the element will automatically scroll as more data added to the end| +|border_width|(int) width of border around element in pixels| +|size|Tuple[int, int] (width, height) width = characters-wide, height = rows-high| +|auto_size_text|(bool) if True will size the element to match the length of the text| +|background_color|(str) color of background| +|text_color|(str) color of the text| +|change_submits|(bool) DO NOT USE. Only listed for backwards compat - Use enable_events instead| +|enable_events|(bool) Turns on the element specific events. Spin events happen when an item changes| +|do_not_clear|if False the element will be cleared any time the Window.Read call returns| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element to uniquely identify this element| +|focus|(bool) if True initial focus will go to this element| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|visible|(bool) set visibility state of the element| + #### Get Return current contents of the Multiline Element @@ -6247,6 +6745,36 @@ Parameter Descriptions: choices, another little graphic is shown on the widget to indicate where you click. After clicking to activate, it looks like a Combo Box that you scroll to select a choice. +``` +OptionMenu(values, + default_value=None, + size=(None, None), + disabled=False, + auto_size_text=None, + background_color=None, + text_color=None, + key=None, + pad=None, + tooltip=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|values|List[Any] Values to be displayed| +|default_value|(Any) the value to choose by default| +|size|Tuple[int, int] (width, height) size in characters (wide) and rows (high)| +|disabled|(bool) control enabled / disabled| +|auto_size_text|(bool) True if size of Element should match the contents of the items| +|background_color|(str) color of background| +|text_color|(str) color of the text| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|tooltip|(str) text that will appear when mouse hovers over this element| +|visible|(bool) set visibility state of the element| + #### SetFocus Sets the current focus to be on this element @@ -6299,6 +6827,32 @@ Parameter Descriptions: Output Element - a multi-lined text area where stdout and stderr are re-routed to. +``` +Output(size=(None, None), + background_color=None, + text_color=None, + pad=None, + font=None, + tooltip=None, + key=None, + right_click_menu=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|size|Tuple[int, int] (w,h) w=characters-wide, h=rows-high| +|background_color|(str) color of background| +|text_color|(str) color of the text| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element to uniquely identify this element| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|visible|(bool) set visibility state of the element| + #### Get Returns the current contents of the output. Similar to Get method other Elements @@ -6339,8 +6893,6 @@ Parameter Descriptions: #### TKOut -#### property: TKOut - #### Update Changes some of the settings for the Output Element. Must call `Window.Read` or `Window.Finalize` prior @@ -6360,6 +6912,36 @@ Parameter Descriptions: A sliding Pane that is unique to tkinter. Uses Columns to create individual panes +``` +Pane(pane_list, + background_color=None, + size=(None, None), + pad=None, + orientation="vertical", + show_handle=True, + relief="raised", + handle_size=None, + border_width=None, + key=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|pane_list|List[Column] Must be a list of Column Elements. Each Column supplied becomes one pane that's shown| +|background_color|(str) color of background| +|size|Tuple[int, int] (w,h) w=characters-wide, h=rows-high How much room to reserve for the Pane| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|orientation|(str) 'horizontal' or 'vertical' or ('h' or 'v'). Direction the Pane should slide| +|show_handle|(bool) if True, the handle is drawn that makes it easier to grab and slide| +|relief|(enum) relief style. Values are same as other elements that use relief values. RELIEF_RAISED RELIEF_SUNKEN RELIEF_FLAT RELIEF_RIDGE RELIEF_GROOVE RELIEF_SOLID| +|handle_size|(int) Size of the handle in pixels| +|border_width|(int) width of border around element in pixels| +|key|(any) Value that uniquely identifies this element from all other elements. Used when Finding an element or in return values. Must be unique to the window| +|visible|(bool) set visibility state of the element| + #### SetFocus Sets the current focus to be on this element @@ -6406,6 +6988,36 @@ Parameter Descriptions: Progress Bar Element - Displays a colored bar that is shaded as progress of some operation is made +``` +ProgressBar(max_value, + orientation=None, + size=(None, None), + auto_size_text=None, + bar_color=(None, None), + style=None, + border_width=None, + relief=None, + key=None, + pad=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|max_value|(int) max value of progressbar| +|orientation|(str) 'horizontal' or 'vertical'| +|size|Tuple[int, int] Size of the bar. If horizontal (chars wide, pixels high), vert (pixels wide, rows high)| +|auto_size_text|(bool) Not sure why this is here| +|bar_color|Tuple[str, str] The 2 colors that make up a progress bar. One is the background, the other is the bar| +|style|(str) Progress bar style defined as one of these 'default', 'winnative', 'clam', 'alt', 'classic', 'vista', 'xpnative'| +|border_width|(int) The amount of pixels that go around the outside of the bar| +|relief|(str) relief style. Values are same as progress meter relief values. Can be a constant or a string: `RELIEF_RAISED RELIEF_SUNKEN RELIEF_FLAT RELIEF_RIDGE RELIEF_GROOVE RELIEF_SOLID` (Default value = DEFAULT_PROGRESS_BAR_RELIEF)| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element to uniquely identify this element| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|visible|(bool) set visibility state of the element| + #### SetFocus Sets the current focus to be on this element @@ -6468,6 +7080,44 @@ Parameter Descriptions: Radio Button Element - Used in a group of other Radio Elements to provide user with ability to select only 1 choice in a list of choices. +``` +Radio(text, + group_id, + default=False, + disabled=False, + size=(None, None), + auto_size_text=None, + background_color=None, + text_color=None, + font=None, + key=None, + pad=None, + tooltip=None, + change_submits=False, + enable_events=False, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|text|(str) Text to display next to button| +|group_id|(Any) Groups together multiple Radio Buttons. Any type works| +|default|(bool). Set to True for the one element of the group you want initially selected| +|disabled|(bool) set disable state| +|size|Tuple[int, int] (width, height) width = characters-wide, height = rows-high| +|auto_size_text|(bool) if True will size the element to match the length of the text| +|background_color|(str) color of background| +|text_color|(str) color of the text| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|change_submits|(bool) DO NOT USE. Only listed for backwards compat - Use enable_events instead| +|enable_events|(bool) Turns on the element specific events. Radio Button events happen when an item is selected| +|visible|(bool) set visibility state of the element| + #### Get A snapshot of the value of Radio Button -> (bool) @@ -6536,6 +7186,52 @@ Parameter Descriptions: A slider, horizontal or vertical +``` +Slider(range=(None, None), + default_value=None, + resolution=None, + tick_interval=None, + orientation=None, + disable_number_display=False, + border_width=None, + relief=None, + change_submits=False, + enable_events=False, + disabled=False, + size=(None, None), + font=None, + background_color=None, + text_color=None, + key=None, + pad=None, + tooltip=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|range|Union[Tuple[int, int], Tuple[float, float]] slider's range (min value, max value)| +|default_value|Union[int, float] starting value for the slider| +|resolution|Union[int, float] the smallest amount the slider can be moved| +|tick_interval|Union[int, float] how often a visible tick should be shown next to slider| +|orientation|(str) 'horizontal' or 'vertical' ('h' or 'v' also work)| +|disable_number_display|(bool) if True no number will be displayed by the Slider Element| +|border_width|(int) width of border around element in pixels| +|relief|(enum) relief style. RELIEF_RAISED RELIEF_SUNKEN RELIEF_FLAT RELIEF_RIDGE RELIEF_GROOVE RELIEF_SOLID| +|change_submits|(bool) * DEPRICATED DO NOT USE! Same as enable_events| +|enable_events|(bool) If True then moving the slider will generate an Event| +|disabled|(bool) set disable state for element| +|size|Tuple[int, int] (width in characters, height in rows)| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|background_color|(str) color of slider's background| +|text_color|(str) color of the slider's text| +|key|(any) Value that uniquely identifies this element from all other elements. Used when Finding an element or in return values. Must be unique to the window| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|visible|(bool) set visibility state of the element| + #### SetFocus Sets the current focus to be on this element @@ -6588,6 +7284,42 @@ Parameter Descriptions: A spinner with up/down buttons and a single line of text. Choose 1 values from list +``` +Spin(values, + initial_value=None, + disabled=False, + change_submits=False, + enable_events=False, + size=(None, None), + auto_size_text=None, + font=None, + background_color=None, + text_color=None, + key=None, + pad=None, + tooltip=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|values|List[Any] List of valid values| +|initial_value|(Any) Initial item to show in window. Choose from list of values supplied| +|disabled|(bool) set disable state| +|change_submits|(bool) DO NOT USE. Only listed for backwards compat - Use enable_events instead| +|enable_events|(bool) Turns on the element specific events. Spin events happen when an item changes| +|size|Tuple[int, int] (width, height) width = characters-wide, height = rows-high| +|auto_size_text|(bool) if True will size the element to match the length of the text| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|background_color|(str) color of background| +|text_color|(str) color of the text| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|visible|(bool) set visibility state of the element| + #### Get Return the current chosen value showing in spinbox. @@ -6652,6 +7384,42 @@ Parameter Descriptions: A StatusBar Element creates the sunken text-filled strip at the bottom. Many Windows programs have this line +``` +StatusBar(text, + size=(None, None), + auto_size_text=None, + click_submits=None, + enable_events=False, + relief="sunken", + font=None, + text_color=None, + background_color=None, + justification=None, + pad=None, + key=None, + tooltip=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|text|(str) Text that is to be displayed in the widget| +|size|Tuple[(int), (int)] (w,h) w=characters-wide, h=rows-high| +|auto_size_text|(bool) True if size should fit the text length| +|click_submits|(bool) DO NOT USE. Only listed for backwards compat - Use enable_events instead| +|enable_events|(bool) Turns on the element specific events. StatusBar events occur when the bar is clicked| +|relief|(enum) relief style. Values are same as progress meter relief values. Can be a constant or a string: `RELIEF_RAISED RELIEF_SUNKEN RELIEF_FLAT RELIEF_RIDGE RELIEF_GROOVE RELIEF_SOLID`| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|text_color|(str) color of the text| +|background_color|(str) color of background| +|justification|(str) how string should be aligned within space provided by size. Valid choices = `left`, `right`, `center`| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element to uniquely identify this element| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|visible|(bool) set visibility state of the element| + #### SetFocus Sets the current focus to be on this element @@ -6707,6 +7475,40 @@ Parameter Descriptions: Tab Element is another "Container" element that holds a layout and displays a tab with text. Used with TabGroup only Tabs are never placed directly into a layout. They are always "Contained" in a TabGroup layout +``` +Tab(title, + layout, + title_color=None, + background_color=None, + font=None, + pad=None, + disabled=False, + border_width=None, + key=None, + tooltip=None, + right_click_menu=None, + visible=True, + element_justification="left") +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|title|(str) text to show on the tab| +|layout|List[List[Element]] The element layout that will be shown in the tab| +|title_color|(str) color of the tab text (note not currently working on tkinter)| +|background_color|(str) color of background of the entire layout| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|disabled|(bool) If True button will be created disabled| +|border_width|(int) width of border around element in pixels| +|key|(any) Value that uniquely identifies this element from all other elements. Used when Finding an element or in return values. Must be unique to the window| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|visible|(bool) set visibility state of the element| +|element_justification|(str) All elements inside the Tab will have this justification 'left', 'right', 'center' are valid values| + #### AddRow Not recommended use call. Used to add rows of Elements to the Frame Element. @@ -6792,6 +7594,42 @@ Parameter Descriptions: TabGroup Element groups together your tabs into the group of tabs you see displayed in your window +``` +TabGroup(layout, + tab_location=None, + title_color=None, + selected_title_color=None, + background_color=None, + font=None, + change_submits=False, + enable_events=False, + pad=None, + border_width=None, + theme=None, + key=None, + tooltip=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|layout|List[List[Tab]] Layout of Tabs. Different than normal layouts. ALL Tabs should be on first row| +|tab_location|(str) location that tabs will be displayed. Choices are left, right, top, bottom, lefttop, leftbottom, righttop, rightbottom, bottomleft, bottomright, topleft, topright| +|title_color|(str) color of text on tabs| +|selected_title_color|(str) color of tab when it is selected| +|background_color|(str) color of background of tabs| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|change_submits|(bool) * DEPRICATED DO NOT USE! Same as enable_events| +|enable_events|(bool) If True then switching tabs will generate an Event| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|border_width|(int) width of border around element in pixels| +|theme|(enum) tabs can be 'themed'. These are the choices (some may not work on your OS): THEME_DEFAULT THEME_WINNATIVE THEME_CLAM THEME_ALT THEME_CLASSIC THEME_VISTA THEME_XPNATIVE| +|key|(any) Value that uniquely identifies this element from all other elements. Used when Finding an element or in return values. Must be unique to the window| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|visible|(bool) set visibility state of the element| + #### AddRow Not recommended user call. Used to add rows of Elements to the Frame Element. @@ -6881,6 +7719,70 @@ Parameter Descriptions: ### Table Element +``` +Table(values, + headings=None, + visible_column_map=None, + col_widths=None, + def_col_width=10, + auto_size_columns=True, + max_col_width=20, + select_mode=None, + display_row_numbers=False, + num_rows=None, + row_height=None, + font=None, + justification="right", + text_color=None, + background_color=None, + alternating_row_color=None, + row_colors=None, + vertical_scroll_only=True, + hide_vertical_scroll=False, + size=(None, None), + change_submits=False, + enable_events=False, + bind_return_key=False, + pad=None, + key=None, + tooltip=None, + right_click_menu=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|values|List[List[Union[str, int, float]]]| +|headings|List[str] The headings to show on the top line| +|visible_column_map|List[bool] One entry for each column. False indicates the column is not shown| +|col_widths|List[int] Number of characters that each column will occupy| +|def_col_width|(int) Default column width in characters| +|auto_size_columns|(bool) if True columns will be sized automatically| +|max_col_width|(int) Maximum width for all columns in characters| +|select_mode|(enum) Select Mode. Valid values start with "TABLE_SELECT_MODE_". Valid values are: TABLE_SELECT_MODE_NONE TABLE_SELECT_MODE_BROWSE TABLE_SELECT_MODE_EXTENDED| +|display_row_numbers|(bool) if True, the first column of the table will be the row #| +|num_rows|(int) The number of rows of the table to display at a time| +|row_height|(int) height of a single row in pixels| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|justification|(str) 'left', 'right', 'center' are valid choices| +|text_color|(str) color of the text| +|background_color|(str) color of background| +|alternating_row_color|(str) if set then every other row will have this color in the background.| +|row_colors|| +|vertical_scroll_only|(bool) if True only the vertical scrollbar will be visible| +|hide_vertical_scroll|(bool) if True vertical scrollbar will be hidden| +|size|Tuple[int, int] DO NOT USE! Use num_rows instead| +|change_submits|(bool) DO NOT USE. Only listed for backwards compat - Use enable_events instead| +|enable_events|(bool) Turns on the element specific events. Table events happen when row is clicked| +|bind_return_key|(bool) if True, pressing return key will cause event coming from Table, ALSO a left button double click will generate an event if this parameter is True| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element to uniquely identify this element| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|visible|(bool) set visibility state of the element| + #### SetFocus Sets the current focus to be on this element @@ -6937,6 +7839,44 @@ Parameter Descriptions: Text - Display some text in the window. Usually this means a single line of text. However, the text can also be multiple lines. If multi-lined there are no scroll bars. +``` +Text(text, + size=(None, None), + auto_size_text=None, + click_submits=False, + enable_events=False, + relief=None, + font=None, + text_color=None, + background_color=None, + justification=None, + pad=None, + key=None, + right_click_menu=None, + tooltip=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|text|(str) The text to display. Can include /n to achieve multiple lines| +|size|Tuple[int, int] (width, height) width = characters-wide, height = rows-high| +|auto_size_text|(bool) if True size of the Text Element will be sized to fit the string provided in 'text' parm| +|click_submits|(bool) DO NOT USE. Only listed for backwards compat - Use enable_events instead| +|enable_events|(bool) Turns on the element specific events. Text events happen when the text is clicked| +|relief|(str/enum) relief style around the text. Values are same as progress meter relief values. Should be a constant that is defined at starting with "RELIEF_" - `RELIEF_RAISED, RELIEF_SUNKEN, RELIEF_FLAT, RELIEF_RIDGE, RELIEF_GROOVE, RELIEF_SOLID`| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|text_color|(str) color of the text| +|background_color|(str) color of background| +|justification|(str) how string should be aligned within space provided by size. Valid choices = `left`, `right`, `center`| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element to uniquely identify this element| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|visible|(bool) set visibility state of the element| + #### SetFocus Sets the current focus to be on this element @@ -6992,6 +7932,60 @@ Parameter Descriptions: Tree Element - Presents data in a tree-like manner, much like a file/folder browser. Uses the TreeData class to hold the user's data and pass to the element for display. +``` +Tree(data=None, + headings=None, + visible_column_map=None, + col_widths=None, + col0_width=10, + def_col_width=10, + auto_size_columns=True, + max_col_width=20, + select_mode=None, + show_expanded=False, + change_submits=False, + enable_events=False, + font=None, + justification="right", + text_color=None, + background_color=None, + num_rows=None, + row_height=None, + pad=None, + key=None, + tooltip=None, + right_click_menu=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|data|(TreeData) The data represented using a PySimpleGUI provided TreeData class| +|headings|List[str] List of individual headings for each column| +|visible_column_map|List[bool] Determines if a column should be visible. If left empty, all columns will be shown| +|col_widths|List[int] List of column widths so that individual column widths can be controlled| +|col0_width|(int) Size of Column 0 which is where the row numbers will be optionally shown| +|def_col_width|(int) default column width| +|auto_size_columns|(bool) if True, the size of a column is determined using the contents of the column| +|max_col_width|(int) the maximum size a column can be| +|select_mode|(enum) Use same values as found on Table Element. Valid values include: TABLE_SELECT_MODE_NONE TABLE_SELECT_MODE_BROWSE TABLE_SELECT_MODE_EXTENDED| +|show_expanded|(bool) if True then the tree will be initially shown with all nodes completely expanded| +|change_submits|(bool) DO NOT USE. Only listed for backwards compat - Use enable_events instead| +|enable_events|(bool) Turns on the element specific events. Tree events happen when row is clicked| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|justification|(str) 'left', 'right', 'center' are valid choices| +|text_color|(str) color of the text| +|background_color|(str) color of background| +|num_rows|(int) The number of rows of the table to display at a time| +|row_height|(int) height of a single row in pixels| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element to uniquely identify this element| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|visible|(bool) set visibility state of the element| + #### SetFocus Sets the current focus to be on this element @@ -7050,6 +8044,12 @@ Parameter Descriptions: with possibly one or more children "Nodes". Each Node contains a key, text to display, list of values to display and an icon. The entire tree is built using a single method, Insert. Nothing else is required to make the tree. +Instantiate the object, initializes the Tree Data, creates a root node for you + +```python +TreeData() +``` + #### Insert Inserts a node into the tree. This is how user builds their tree, by Inserting Nodes @@ -7090,6 +8090,16 @@ Node(parent, Vertical Separator Element draws a vertical line at the given location. It will span 1 "row". Usually paired with Column Element if extra height is needed +``` +VerticalSeparator(pad=None) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| + #### SetFocus Sets the current focus to be on this element @@ -7122,6 +8132,82 @@ Parameter Descriptions: Represents a single Window +``` +Window(title, + layout=None, + default_element_size=(45, 1), + default_button_element_size=(None, None), + auto_size_text=None, + auto_size_buttons=None, + location=(None, None), + size=(None, None), + element_padding=None, + margins=(None, None), + button_color=None, + font=None, + progress_bar_color=(None, None), + background_color=None, + border_depth=None, + auto_close=False, + auto_close_duration=3, + icon=None, + force_toplevel=False, + alpha_channel=1, + return_keyboard_events=False, + use_default_focus=True, + text_justification=None, + no_titlebar=False, + grab_anywhere=False, + keep_on_top=False, + resizable=False, + disable_close=False, + disable_minimize=False, + right_click_menu=None, + transparent_color=None, + debugger_enabled=True, + finalize=False, + element_justification="left") +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|title|(str) The title that will be displayed in the Titlebar and on the Taskbar| +|layout|List[List[Elements]] The layout for the window. Can also be specified in the Layout method| +|default_element_size|Tuple[int, int] (width, height) size in characters (wide) and rows (high) for all elements in this window| +|default_button_element_size|Tuple[int, int] (width, height) size in characters (wide) and rows (high) for all Button elements in this window| +|auto_size_text|(bool) True if Elements in Window should be sized to exactly fir the length of text| +|auto_size_buttons|(bool) True if Buttons in this Window should be sized to exactly fit the text on this.| +|location|Tuple[int, int] (x,y) location, in pixels, to locate the upper left corner of the window on the screen. Default is to center on screen.| +|size|Tuple[int, int] (width, height) size in pixels for this window. Normally the window is autosized to fit contents, not set to an absolute size by the user| +|element_padding|Tuple[int, int] or ((int, int),(int,int)) Default amount of padding to put around elements in window (left/right, top/bottom) or ((left, right), (top, bottom))| +|margins|Tuple[int, int] (left/right, top/bottom) Amount of pixels to leave inside the window's frame around the edges before your elements are shown.| +|button_color|Tuple[str, str] (text color, button color) Default button colors for all buttons in the window| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|progress_bar_color|Tuple[str, str] (bar color, background color) Sets the default colors for all progress bars in the window| +|background_color|(str) color of background| +|border_depth|(int) Default border depth (width) for all elements in the window| +|auto_close|(bool) If True, the window will automatically close itself| +|auto_close_duration|(int) Number of seconds to wait before closing the window| +|icon|Union[str, str] Can be either a filename or Base64 value.| +|force_toplevel|(bool) If True will cause this window to skip the normal use of a hidden master window| +|alpha_channel|(float) Sets the opacity of the window. 0 = invisible 1 = completely visible. Values bewteen 0 & 1 will produce semi-transparent windows in SOME environments (The Raspberry Pi always has this value at 1 and cannot change.| +|return_keyboard_events|(bool) if True key presses on the keyboard will be returned as Events from Read calls| +|use_default_focus|(bool) If True will use the default focus algorithm to set the focus to the "Correct" element| +|text_justification|(str) Union ['left', 'right', 'center'] Default text justification for all Text Elements in window| +|no_titlebar|(bool) If true, no titlebar nor frame will be shown on window. This means you cannot minimize the window and it will not show up on the taskbar| +|grab_anywhere|(bool) If True can use mouse to click and drag to move the window. Almost every location of the window will work except input fields on some systems| +|keep_on_top|(bool) If True, window will be created on top of all other windows on screen. It can be bumped down if another window created with this parm| +|resizable|(bool) If True, allows the user to resize the window. Note the not all Elements will change size or location when resizing.| +|disable_close|(bool) If True, the X button in the top right corner of the window will no work. Use with caution and always give a way out toyour users| +|disable_minimize|(bool) if True the user won't be able to minimize window. Good for taking over entire screen and staying that way.| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|transparent_color|(str) Any portion of the window that has this color will be completely transparent. You can even click through these spots to the window under this window.| +|debugger_enabled|(bool) If True then the internal debugger will be enabled| +|finalize|(bool) If True then the Finalize method will be called. Use this rather than chaining .Finalize for cleaner code| +|element_justification|(str) All elements in the Window itself will have this justification 'left', 'right', 'center' are valid values| + #### AddRow Adds a single row of elements to a window's self.Rows variables. @@ -7156,14 +8242,6 @@ Parameter Descriptions: #### AlphaChannel -#### property: AlphaChannel - -A property that changes the current alpha channel value (internal value) - -|Name|Meaning| -|---|---| -| **return** | (float) the current alpha channel setting according to self, not read directly from tkinter | - #### BringToFront Brings this window to the top of all other windows (perhaps may not be brought before a window made to "stay @@ -7666,14 +8744,6 @@ Parameter Descriptions: #### Size -#### property: Size - -Return the current size of the window in pixels - -|Name|Meaning| -|---|---| -| **return** | Tuple[(int), (int)] the (width, height) of the window | - #### UnHide Used to bring back a window that was previously hidden using the Hide method diff --git a/readme.md b/readme.md index 1ccf0b5c..e2a23308 100644 --- a/readme.md +++ b/readme.md @@ -889,6 +889,7 @@ Features of PySimpleGUI include: - Movable windows - Animated GIFs - No async programming required (no callbacks to worry about) +- Built-in debugger and REPL - User expandable by accessing underlying GUI Framework widgets directly --- @@ -925,7 +926,7 @@ The Single Line Progress Meter is a good example. It requires one and only 1 lin Be Pythonic... -This one is difficult for me to define. The code implementing PySimpleGUI isn't PEP8 compliant, but it is consistent. The important thing was what the user saw and experienced while coding, NOT the choices for naming conventions in the implementation code. +This one is difficult for me to define. The code implementing PySimpleGUI isn't PEP8 compliant, but it is consistent. The important thing was what the user saw and experienced while coding, NOT the choices for naming conventions in the implementation code. The user interface to PySimpleGUI now has a PEP8 compliant interface. The methods are snake_case now (in addition to retaining the older CamelCase names) I ended up defining it as - attempt to use language constructs in a natural way and to exploit some of Python's interesting features. It's Python's lists and optional parameters make PySimpleGUI work smoothly. @@ -1144,11 +1145,11 @@ Then use either "high level" API calls or build your own windows. Yes, it's just that easy to have a window appear on the screen using Python. With PySimpleGUI, making a custom window appear isn't much more difficult. The goal is to get you running on your GUI within ***minutes***, not hours nor days. -***WARNING*** Do NOT use PySimpleGUI with Python 3.7.4. tkiter is having issues with that release. Things like Table colors stopped working entirely. None of us want to debug tkinter code. It's difficult enough debugging your code and PySimpleGUI code. +***WARNING*** Do NOT use PySimpleGUI with Python 3.7.3 and 3.7.4. tkiter is having issues with that release. Things like Table colors stopped working entirely. None of us want to debug tkinter code. It's difficult enough debugging your code and PySimpleGUI code. A lot of time has already been spent debugging this one so no need for you to suffer too. ### Python 3.7 -It puzzles me why a beginner would install 3.7. Or even a seasoned programmer. What specific feature of 3.7 are you using that is not in 3.6? If you are unable to answer this, then ***you should be running 3.6***, an immensely solid release of Python. If you must run 3.7, try 3.7.2 instead. It does work with PySimpleGUI with no known issues. +It puzzles me why a beginner would install 3.7. Or even a seasoned programmer. What specific feature of 3.7 are you using that is not in 3.6? If you are unable to answer this, then ***it's strongly suggested that you run 3.6***, an immensely solid release of Python with all those goodie inside like f-strings. If you must run 3.7, try 3.7.2 instead. It does work with PySimpleGUI with no known issues. ## Using - Python 2.7 @@ -2983,7 +2984,15 @@ Then when you read the `values` variable that's returned to you from calling `Wi `values[(row, col)]` Most of the time they are simple text strings. In the Demo Programs, keys are written with this convention: -`_KEY_NAME_` (underscore at beginning and end with all caps letters). You don't have to follow that convention. It's used so that you can quickly spot when a key is being used. +`_KEY_NAME_` (underscore at beginning and end with all caps letters) or '-KEY_NAME-. You don't have to follow that convention. It's used so that you can quickly spot when a key is being used. + +To find an element's key, access the member variable `.Key` for the element. This assumes you've got the element in a variable already. + +```python +text_elem = sg.Text('', key='-TEXT-') + +the_key = text_elem.Key +``` #### Visible @@ -4736,7 +4745,7 @@ The plain PySimpleGUI module has a debugger builtin. For the other ports, pleas This debugger provides you with something unique to most typical Python developers, the ability to "see" and interact with your code, **while it is running**. You can change variable values while your code continues to run. -Print statements are cool, but perhaps you're tired of seeing this: +Print statements are cool, but perhaps you're tired of seeing a printout of `event` and `values`: ``` Push Me {0: 'Input here'} Push Me {0: 'Input here'} @@ -4808,6 +4817,14 @@ One "variable" shown in the popout window that is an often asked for piece of in Exiting this window is done via the little red X, **or using the rickt-click menu** which is also used as one way to launch the Main Debugger Window +#### Ways of Launching the Popout Window + +There are 3 ways of opening the Popout window. + +1. Press the `BREAK` key on your keyboard. +2. Call the function `show_debugger_popout_window(location=(x,y))` +3. Add `Debug()` button to your layout - adds a little purple and yellow PySimpleGUI logo to your window + #### When you are asked for the "Location of your PySimpleGUI package or PySimpleGUI.py file" do this If you wish to use the debugger to find the location of THIS running program's PySimpleGUI package / the PySimpleGUI.py file, then all you need to do is: @@ -4834,6 +4851,14 @@ Ever wish you had a `repl>>>` prompt that you could run while your program is ru You'll find that this window has 2 tabs, one is labelled `Variables` and the other is labelled `REPL & Watches` +#### Ways of Opening the Main Debugger Window + +There are 3 ways to open the Main Debugger Window + +1. Press `Control` + `Break` on your PC keyboard +2. From the Popout Debug Window, right click and choose `Debugger` from the right click menu +3. From your code call `show_debugger_window(location=(x,y))` + #### The "Variables" Tab of Main Debugger Window ![SNAG-0440](https://user-images.githubusercontent.com/13696193/62797391-a01ceb80-baa9-11e9-845d-3cd02ca0dbcc.jpg) @@ -5072,6 +5097,60 @@ Without further delay... here are all of the Elements Button Element - Defines all possible buttons. The shortcuts such as Submit, FileBrowse, ... each create a Button +``` +Button(button_text="", + button_type=7, + target=(None, None), + tooltip=None, + file_types=(('ALL Files', '*.*'),), + initial_folder=None, + disabled=False, + change_submits=False, + enable_events=False, + image_filename=None, + image_data=None, + image_size=(None, None), + image_subsample=None, + border_width=None, + size=(None, None), + auto_size_button=None, + button_color=None, + font=None, + bind_return_key=False, + focus=False, + pad=None, + key=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|button_text|(str) Text to be displayed on the button| +|button_type|(int) You should NOT be setting this directly. ONLY the shortcut functions set this| +|target|Union[str, Tuple[int, int]] key or (row,col) target for the button. Note that -1 for column means 1 element to the left of this one. The constant ThisRow is used to indicate the current row. The Button itself is a valid target for some types of button| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|file_types|Tuple[Tuple[str, str], ...] the filetypes that will be used to match files. To indicate all files: (("ALL Files", "*.*"),). Note - NOT SUPPORTED ON MAC| +|initial_folder|(str) starting path for folders and files| +|disabled|(bool) If True button will be created disabled| +|click_submits|(bool) DO NOT USE. Only listed for backwards compat - Use enable_events instead| +|enable_events|(bool) Turns on the element specific events. If this button is a target, should it generate an event when filled in| +|image_filename|(str) image filename if there is a button image. GIFs and PNGs only.| +|image_data|Union[bytes, str] Raw or Base64 representation of the image to put on button. Choose either filename or data| +|image_size|Tuple[int, int] Size of the image in pixels (width, height)| +|image_subsample|(int) amount to reduce the size of the image. Divides the size by this number. 2=1/2, 3=1/3, 4=1/4, etc| +|border_width|(int) width of border around button in pixels| +|size|Tuple[int, int] (width, height) of the button in characters wide, rows high| +|auto_size_button|(bool) if True the button size is sized to fit the text| +|button_color|Tuple[str, str] (text color, background color) of button. Easy to remember which is which if you say "ON" between colors. "red" on "green". Note - Does not always work on Macs| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|bind_return_key|(bool) If True the return key will cause this button to be pressed| +|focus|(bool) if True, initial focus will be put on this button| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element to uniquely identify this element| +|visible|(bool) set visibility state of the element| + #### Click Generates a click of the button as if the user clicked the button @@ -5151,6 +5230,48 @@ Parameter Descriptions: The Button Menu Element. Creates a button that when clicked will show a menu similar to right click menu +``` +ButtonMenu(button_text, + menu_def, + tooltip=None, + disabled=False, + image_filename=None, + image_data=None, + image_size=(None, None), + image_subsample=None, + border_width=None, + size=(None, None), + auto_size_button=None, + button_color=None, + font=None, + pad=None, + key=None, + tearoff=False, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|button_text|(str) Text to be displayed on the button| +|menu_def|List[List[str]] A list of lists of Menu items to show when this element is clicked. See docs for format as they are the same for all menu types| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|disabled|(bool) If True button will be created disabled| +|image_filename|(str) image filename if there is a button image. GIFs and PNGs only.| +|image_data|Union[bytes, str] Raw or Base64 representation of the image to put on button. Choose either filename or data| +|image_size|Tuple[int, int] Size of the image in pixels (width, height)| +|image_subsample|(int) amount to reduce the size of the image. Divides the size by this number. 2=1/2, 3=1/3, 4=1/4, etc| +|border_width|(int) width of border around button in pixels| +|size|Tuple[int, int] (width, height) of the button in characters wide, rows high| +|auto_size_button|(bool) if True the button size is sized to fit the text| +|button_color|Tuple[str, str] (text color, background color) of button. Easy to remember which is which if you say "ON" between colors. "red" on "green"| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element to uniquely identify this element| +|tearoff|(bool) Determines if menus should allow them to be torn off| +|visible|(bool) set visibility state of the element| + #### SetFocus Sets the current focus to be on this element @@ -5196,6 +5317,30 @@ Parameter Descriptions: ### Canvas Element +``` +Canvas(canvas=None, + background_color=None, + size=(None, None), + pad=None, + key=None, + tooltip=None, + right_click_menu=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|canvas|(tk.Canvas) Your own tk.Canvas if you already created it. Leave blank to create a Canvas| +|background_color|(str) color of background| +|size|Tuple[int,int] (width in char, height in rows) size in pixels to make canvas| +|pad|Amount of padding to put around element| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|visible|(bool) set visibility state of the element| + #### SetFocus Sets the current focus to be on this element @@ -5226,12 +5371,46 @@ Parameter Descriptions: #### TKCanvas -#### property: TKCanvas - ### Checkbox Element Checkbox Element - Displays a checkbox and text next to it +``` +Checkbox(text, + default=False, + size=(None, None), + auto_size_text=None, + font=None, + background_color=None, + text_color=None, + change_submits=False, + enable_events=False, + disabled=False, + key=None, + pad=None, + tooltip=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|text|(str) Text to display next to checkbox| +|default|(bool). Set to True if you want this checkbox initially checked| +|size|Tuple[int, int] (width, height) width = characters-wide, height = rows-high| +|auto_size_text|(bool) if True will size the element to match the length of the text| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|background_color|(str) color of background| +|text_color|(str) color of the text| +|change_submits|(bool) DO NOT USE. Only listed for backwards compat - Use enable_events instead| +|enable_events|(bool) Turns on the element specific events. Checkbox events happen when an item changes| +|disabled|(bool) set disable state| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|visible|(bool) set visibility state of the element| + #### Get Return the current state of this checkbox @@ -5293,6 +5472,36 @@ Parameter Descriptions: A container element that is used to create a layout within your window's layout +``` +Column(layout, + background_color=None, + size=(None, None), + pad=None, + scrollable=False, + vertical_scroll_only=False, + right_click_menu=None, + key=None, + visible=True, + justification="left", + element_justification="left") +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|layout|List[List[Element]] Layout that will be shown in the Column container| +|background_color|(str) color of background of entire Column| +|size|Tuple[int, int] (width, height) size in pixels (doesn't work quite right, sometimes only 1 dimension is set by tkinter| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|scrollable|(bool) if True then scrollbars will be added to the column| +|vertical_scroll_only|(bool) if Truen then no horizontal scrollbar will be shown| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|key|(any) Value that uniquely identifies this element from all other elements. Used when Finding an element or in return values. Must be unique to the window| +|visible|(bool) set visibility state of the element| +|justification|(str) set justification for the Column itself. Note entire row containing the Column will be affected| +|element_justification|(str) All elements inside the Column will have this justification 'left', 'right', 'center' are valid values| + #### AddRow Not recommended user call. Used to add rows of Elements to the Column Element. @@ -5369,6 +5578,44 @@ Parameter Descriptions: ComboBox Element - A combination of a single-line input and a drop-down menu. User can type in their own value or choose from list. +``` +Combo(values, + default_value=None, + size=(None, None), + auto_size_text=None, + background_color=None, + text_color=None, + change_submits=False, + enable_events=False, + disabled=False, + key=None, + pad=None, + tooltip=None, + readonly=False, + font=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|values|List[Any] values to choose. While displayed as text, the items returned are what the caller supplied, not text| +|default_value|(Any) Choice to be displayed as initial value. Must match one of values variable contents| +|size|Tuple[int, int] (width, height) width = characters-wide, height = rows-high| +|auto_size_text|(bool) True if element should be the same size as the contents| +|background_color|(str) color of background| +|text_color|(str) color of the text| +|change_submits|(bool) DEPRICATED DO NOT USE. Use `enable_events` instead| +|enable_events|(bool) Turns on the element specific events. Combo event is when a choice is made| +|disabled|(bool) set disable state for element| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|tooltip|(str) text that will appear when mouse hovers over this element| +|readonly|(bool) make element readonly (user can't change). True means user cannot change| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|visible|(bool) set visibility state of the element| + #### Get Returns the current (right now) value of the Combo. DO NOT USE THIS AS THE NORMAL WAY OF READING A COMBO! @@ -5438,6 +5685,44 @@ Parameter Descriptions: A Frame Element that contains other Elements. Encloses with a line around elements and a text label. +``` +Frame(title, + layout, + title_color=None, + background_color=None, + title_location=None, + relief="groove", + size=(None, None), + font=None, + pad=None, + border_width=None, + key=None, + tooltip=None, + right_click_menu=None, + visible=True, + element_justification="left") +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|title|(str) text that is displayed as the Frame's "label" or title| +|layout|List[List[Elements]] The layout to put inside the Frame| +|title_color|(str) color of the title text| +|background_color|(str) background color of the Frame| +|title_location|(enum) location to place the text title. Choices include: TITLE_LOCATION_TOP TITLE_LOCATION_BOTTOM TITLE_LOCATION_LEFT TITLE_LOCATION_RIGHT TITLE_LOCATION_TOP_LEFT TITLE_LOCATION_TOP_RIGHT TITLE_LOCATION_BOTTOM_LEFT TITLE_LOCATION_BOTTOM_RIGHT| +|relief|(enum) relief style. Values are same as other elements with reliefs. Choices include RELIEF_RAISED RELIEF_SUNKEN RELIEF_FLAT RELIEF_RIDGE RELIEF_GROOVE RELIEF_SOLID| +|size|Tuple[int, int] (width in characters, height in rows) (note this parameter may not always work)| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|border_width|(int) width of border around element in pixels| +|key|(any) Value that uniquely identifies this element from all other elements. Used when Finding an element or in return values. Must be unique to the window| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|visible|(bool) set visibility state of the element| +|element_justification|(str) All elements inside the Frame will have this justification 'left', 'right', 'center' are valid values| + #### AddRow Not recommended user call. Used to add rows of Elements to the Frame Element. @@ -5522,6 +5807,40 @@ Parameter Descriptions: Mouse click and drag events are possible and return the (x,y) coordinates of the mouse Drawing primitives return an "id" that is referenced when you want to operation on that item (e.g. to erase it) +``` +Graph(canvas_size, + graph_bottom_left, + graph_top_right, + background_color=None, + pad=None, + change_submits=False, + drag_submits=False, + enable_events=False, + key=None, + tooltip=None, + right_click_menu=None, + visible=True, + float_values=False) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|canvas_size|Tuple[int, int] (width, height) size of the canvas area in pixels| +|graph_bottom_left|Tuple[int, int] (x,y) The bottoms left corner of your coordinate system| +|graph_top_right|Tuple[int, int] (x,y) The top right corner of your coordinate system| +|background_color|(str) background color of the drawing area| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|change_submits|(bool) * DEPRICATED DO NOT USE! Same as enable_events| +|drag_submits|(bool) if True and Events are enabled for the Graph, will report Events any time the mouse moves while button down| +|enable_events|(bool) If True then clicks on the Graph are immediately reported as an event. Use this instead of change_submits| +|key|(any) Value that uniquely identifies this element from all other elements. Used when Finding an element or in return values. Must be unique to the window| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|visible|(bool) set visibility state of the element (Default = True)| +|float_values|(bool) If True x,y coordinates are returned as floats, not ints| + #### BringFigureToFront Changes Z-order of figures on the Graph. Brings the indicated figure to the front of all other drawn figures @@ -5882,8 +6201,6 @@ Parameter Descriptions: #### TKCanvas -#### property: TKCanvas - #### Update Changes some of the settings for the Graph Element. Must call `Window.Read` or `Window.Finalize` prior @@ -5903,6 +6220,34 @@ Parameter Descriptions: Image Element - show an image in the window. Should be a GIF or a PNG only +``` +Image(filename=None, + data=None, + background_color=None, + size=(None, None), + pad=None, + key=None, + tooltip=None, + right_click_menu=None, + visible=True, + enable_events=False) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|filename|(str) image filename if there is a button image. GIFs and PNGs only.| +|data|Union[bytes, str] Raw or Base64 representation of the image to put on button. Choose either filename or data| +|background_color|color of background| +|size|Tuple[int, int] (width, height) size of image in pixels| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element to uniquely identify this element| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|visible|(bool) set visibility state of the element| +|enable_events|(bool) Turns on the element specific events. For an Image element, the event is "image clicked"| + #### SetFocus Sets the current focus to be on this element @@ -5971,6 +6316,48 @@ Parameter Descriptions: Display a single text input field. Based on the tkinter Widget `Entry` +``` +InputText(default_text="", + size=(None, None), + disabled=False, + password_char="", + justification=None, + background_color=None, + text_color=None, + font=None, + tooltip=None, + change_submits=False, + enable_events=False, + do_not_clear=True, + key=None, + focus=False, + pad=None, + right_click_menu=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|default_text|(str) Text initially shown in the input box as a default value(Default value = '')| +|size|Tuple[int, int] (width, height) w=characters-wide, h=rows-high| +|disabled|(bool) set disable state for element (Default = False)| +|password_char|(char) Password character if this is a password field (Default value = '')| +|justification|(str) justification for data display. Valid choices - left, right, center| +|background_color|(str) color of background in one of the color formats| +|text_color|(str) color of the text| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|change_submits|(bool) * DEPRICATED DO NOT USE! Same as enable_events| +|enable_events|(bool) If True then changes to this element are immediately reported as an event. Use this instead of change_submits (Default = False)| +|do_not_clear|(bool) If False then the field will be set to blank after ANY event (button, any event) (Default = True)| +|key|(any) Value that uniquely identifies this element from all other elements. Used when Finding an element or in return values. Must be unique to the window| +|focus|(bool) Determines if initial focus should go to this element.| +|pad|(int, int) or ((int, int), (int, int)) Tuple(s). Amount of padding to put around element. Normally (horizontal pixels, vertical pixels) but can be split apart further into ((horizontal left, horizontal right), (vertical above, vertical below))| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|visible|(bool) set visibility state of the element (Default = True)| + #### Get Read and return the current value of the input element. Must call `Window.Read` or `Window.Finalize` prior @@ -6034,6 +6421,49 @@ Parameter Descriptions: A List Box. Provide a list of values for the user to choose one or more of. Returns a list of selected rows when a window.Read() is executed. +``` +Listbox(values, + default_values=None, + select_mode=None, + change_submits=False, + enable_events=False, + bind_return_key=False, + size=(None, None), + disabled=False, + auto_size_text=None, + font=None, + no_scrollbar=False, + background_color=None, + text_color=None, + key=None, + pad=None, + tooltip=None, + right_click_menu=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|values|List[Any] list of values to display. Can be any type including mixed types as long as they have __str__ method| +|default_values|List[Any] which values should be initially selected| +|select_mode|[enum] Select modes are used to determine if only 1 item can be selected or multiple and how they can be selected. Valid choices begin with "LISTBOX_SELECT_MODE_" and include: LISTBOX_SELECT_MODE_SINGLE LISTBOX_SELECT_MODE_MULTIPLE LISTBOX_SELECT_MODE_BROWSE LISTBOX_SELECT_MODE_EXTENDED| +|change_submits|(bool) DO NOT USE. Only listed for backwards compat - Use enable_events instead| +|enable_events|(bool) Turns on the element specific events. Listbox generates events when an item is clicked| +|bind_return_key|(bool) If True, then the return key will cause a the Listbox to generate an event| +|size|Tuple(int, int) (width, height) width = characters-wide, height = rows-high| +|disabled|(bool) set disable state for element| +|auto_size_text|(bool) True if element should be the same size as the contents| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|background_color|(str) color of background| +|text_color|(str) color of the text| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|visible|(bool) set visibility state of the element| + #### GetListValues Returns list of Values provided by the user in the user's format @@ -6125,6 +6555,28 @@ Parameter Descriptions: can see it has a "::" which signifies the beginning of a key. The user will not see the key portion when the menu is shown. The key portion is returned as part of the event. +``` +Menu(menu_definition, + background_color=None, + size=(None, None), + tearoff=False, + pad=None, + key=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|menu_definition|List[List[Tuple[str, List[str]]]| +|background_color|(str) color of the background| +|size|Tuple[int, int] Not used in the tkinter port| +|tearoff|(bool) if True, then can tear the menu off from the window ans use as a floating window. Very cool effect| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|key|(any) Value that uniquely identifies this element from all other elements. Used when Finding an element or in return values. Must be unique to the window| +|visible|(bool) set visibility state of the element| + #### SetFocus Sets the current focus to be on this element @@ -6174,6 +6626,52 @@ Parameter Descriptions: Other PySimpleGUI ports have a separate MultilineInput and MultilineOutput elements. May want to split this one up in the future too. +``` +Multiline(default_text="", + enter_submits=False, + disabled=False, + autoscroll=False, + border_width=None, + size=(None, None), + auto_size_text=None, + background_color=None, + text_color=None, + change_submits=False, + enable_events=False, + do_not_clear=True, + key=None, + focus=False, + font=None, + pad=None, + tooltip=None, + right_click_menu=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|default_text|(str) Initial text to show| +|enter_submits|(bool) if True, the Window.Read call will return is enter key is pressed in this element| +|disabled|(bool) set disable state| +|autoscroll|(bool) If True the contents of the element will automatically scroll as more data added to the end| +|border_width|(int) width of border around element in pixels| +|size|Tuple[int, int] (width, height) width = characters-wide, height = rows-high| +|auto_size_text|(bool) if True will size the element to match the length of the text| +|background_color|(str) color of background| +|text_color|(str) color of the text| +|change_submits|(bool) DO NOT USE. Only listed for backwards compat - Use enable_events instead| +|enable_events|(bool) Turns on the element specific events. Spin events happen when an item changes| +|do_not_clear|if False the element will be cleared any time the Window.Read call returns| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element to uniquely identify this element| +|focus|(bool) if True initial focus will go to this element| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|visible|(bool) set visibility state of the element| + #### Get Return current contents of the Multiline Element @@ -6247,6 +6745,36 @@ Parameter Descriptions: choices, another little graphic is shown on the widget to indicate where you click. After clicking to activate, it looks like a Combo Box that you scroll to select a choice. +``` +OptionMenu(values, + default_value=None, + size=(None, None), + disabled=False, + auto_size_text=None, + background_color=None, + text_color=None, + key=None, + pad=None, + tooltip=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|values|List[Any] Values to be displayed| +|default_value|(Any) the value to choose by default| +|size|Tuple[int, int] (width, height) size in characters (wide) and rows (high)| +|disabled|(bool) control enabled / disabled| +|auto_size_text|(bool) True if size of Element should match the contents of the items| +|background_color|(str) color of background| +|text_color|(str) color of the text| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|tooltip|(str) text that will appear when mouse hovers over this element| +|visible|(bool) set visibility state of the element| + #### SetFocus Sets the current focus to be on this element @@ -6299,6 +6827,32 @@ Parameter Descriptions: Output Element - a multi-lined text area where stdout and stderr are re-routed to. +``` +Output(size=(None, None), + background_color=None, + text_color=None, + pad=None, + font=None, + tooltip=None, + key=None, + right_click_menu=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|size|Tuple[int, int] (w,h) w=characters-wide, h=rows-high| +|background_color|(str) color of background| +|text_color|(str) color of the text| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element to uniquely identify this element| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|visible|(bool) set visibility state of the element| + #### Get Returns the current contents of the output. Similar to Get method other Elements @@ -6339,8 +6893,6 @@ Parameter Descriptions: #### TKOut -#### property: TKOut - #### Update Changes some of the settings for the Output Element. Must call `Window.Read` or `Window.Finalize` prior @@ -6360,6 +6912,36 @@ Parameter Descriptions: A sliding Pane that is unique to tkinter. Uses Columns to create individual panes +``` +Pane(pane_list, + background_color=None, + size=(None, None), + pad=None, + orientation="vertical", + show_handle=True, + relief="raised", + handle_size=None, + border_width=None, + key=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|pane_list|List[Column] Must be a list of Column Elements. Each Column supplied becomes one pane that's shown| +|background_color|(str) color of background| +|size|Tuple[int, int] (w,h) w=characters-wide, h=rows-high How much room to reserve for the Pane| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|orientation|(str) 'horizontal' or 'vertical' or ('h' or 'v'). Direction the Pane should slide| +|show_handle|(bool) if True, the handle is drawn that makes it easier to grab and slide| +|relief|(enum) relief style. Values are same as other elements that use relief values. RELIEF_RAISED RELIEF_SUNKEN RELIEF_FLAT RELIEF_RIDGE RELIEF_GROOVE RELIEF_SOLID| +|handle_size|(int) Size of the handle in pixels| +|border_width|(int) width of border around element in pixels| +|key|(any) Value that uniquely identifies this element from all other elements. Used when Finding an element or in return values. Must be unique to the window| +|visible|(bool) set visibility state of the element| + #### SetFocus Sets the current focus to be on this element @@ -6406,6 +6988,36 @@ Parameter Descriptions: Progress Bar Element - Displays a colored bar that is shaded as progress of some operation is made +``` +ProgressBar(max_value, + orientation=None, + size=(None, None), + auto_size_text=None, + bar_color=(None, None), + style=None, + border_width=None, + relief=None, + key=None, + pad=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|max_value|(int) max value of progressbar| +|orientation|(str) 'horizontal' or 'vertical'| +|size|Tuple[int, int] Size of the bar. If horizontal (chars wide, pixels high), vert (pixels wide, rows high)| +|auto_size_text|(bool) Not sure why this is here| +|bar_color|Tuple[str, str] The 2 colors that make up a progress bar. One is the background, the other is the bar| +|style|(str) Progress bar style defined as one of these 'default', 'winnative', 'clam', 'alt', 'classic', 'vista', 'xpnative'| +|border_width|(int) The amount of pixels that go around the outside of the bar| +|relief|(str) relief style. Values are same as progress meter relief values. Can be a constant or a string: `RELIEF_RAISED RELIEF_SUNKEN RELIEF_FLAT RELIEF_RIDGE RELIEF_GROOVE RELIEF_SOLID` (Default value = DEFAULT_PROGRESS_BAR_RELIEF)| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element to uniquely identify this element| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|visible|(bool) set visibility state of the element| + #### SetFocus Sets the current focus to be on this element @@ -6468,6 +7080,44 @@ Parameter Descriptions: Radio Button Element - Used in a group of other Radio Elements to provide user with ability to select only 1 choice in a list of choices. +``` +Radio(text, + group_id, + default=False, + disabled=False, + size=(None, None), + auto_size_text=None, + background_color=None, + text_color=None, + font=None, + key=None, + pad=None, + tooltip=None, + change_submits=False, + enable_events=False, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|text|(str) Text to display next to button| +|group_id|(Any) Groups together multiple Radio Buttons. Any type works| +|default|(bool). Set to True for the one element of the group you want initially selected| +|disabled|(bool) set disable state| +|size|Tuple[int, int] (width, height) width = characters-wide, height = rows-high| +|auto_size_text|(bool) if True will size the element to match the length of the text| +|background_color|(str) color of background| +|text_color|(str) color of the text| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|change_submits|(bool) DO NOT USE. Only listed for backwards compat - Use enable_events instead| +|enable_events|(bool) Turns on the element specific events. Radio Button events happen when an item is selected| +|visible|(bool) set visibility state of the element| + #### Get A snapshot of the value of Radio Button -> (bool) @@ -6536,6 +7186,52 @@ Parameter Descriptions: A slider, horizontal or vertical +``` +Slider(range=(None, None), + default_value=None, + resolution=None, + tick_interval=None, + orientation=None, + disable_number_display=False, + border_width=None, + relief=None, + change_submits=False, + enable_events=False, + disabled=False, + size=(None, None), + font=None, + background_color=None, + text_color=None, + key=None, + pad=None, + tooltip=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|range|Union[Tuple[int, int], Tuple[float, float]] slider's range (min value, max value)| +|default_value|Union[int, float] starting value for the slider| +|resolution|Union[int, float] the smallest amount the slider can be moved| +|tick_interval|Union[int, float] how often a visible tick should be shown next to slider| +|orientation|(str) 'horizontal' or 'vertical' ('h' or 'v' also work)| +|disable_number_display|(bool) if True no number will be displayed by the Slider Element| +|border_width|(int) width of border around element in pixels| +|relief|(enum) relief style. RELIEF_RAISED RELIEF_SUNKEN RELIEF_FLAT RELIEF_RIDGE RELIEF_GROOVE RELIEF_SOLID| +|change_submits|(bool) * DEPRICATED DO NOT USE! Same as enable_events| +|enable_events|(bool) If True then moving the slider will generate an Event| +|disabled|(bool) set disable state for element| +|size|Tuple[int, int] (width in characters, height in rows)| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|background_color|(str) color of slider's background| +|text_color|(str) color of the slider's text| +|key|(any) Value that uniquely identifies this element from all other elements. Used when Finding an element or in return values. Must be unique to the window| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|visible|(bool) set visibility state of the element| + #### SetFocus Sets the current focus to be on this element @@ -6588,6 +7284,42 @@ Parameter Descriptions: A spinner with up/down buttons and a single line of text. Choose 1 values from list +``` +Spin(values, + initial_value=None, + disabled=False, + change_submits=False, + enable_events=False, + size=(None, None), + auto_size_text=None, + font=None, + background_color=None, + text_color=None, + key=None, + pad=None, + tooltip=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|values|List[Any] List of valid values| +|initial_value|(Any) Initial item to show in window. Choose from list of values supplied| +|disabled|(bool) set disable state| +|change_submits|(bool) DO NOT USE. Only listed for backwards compat - Use enable_events instead| +|enable_events|(bool) Turns on the element specific events. Spin events happen when an item changes| +|size|Tuple[int, int] (width, height) width = characters-wide, height = rows-high| +|auto_size_text|(bool) if True will size the element to match the length of the text| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|background_color|(str) color of background| +|text_color|(str) color of the text| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|visible|(bool) set visibility state of the element| + #### Get Return the current chosen value showing in spinbox. @@ -6652,6 +7384,42 @@ Parameter Descriptions: A StatusBar Element creates the sunken text-filled strip at the bottom. Many Windows programs have this line +``` +StatusBar(text, + size=(None, None), + auto_size_text=None, + click_submits=None, + enable_events=False, + relief="sunken", + font=None, + text_color=None, + background_color=None, + justification=None, + pad=None, + key=None, + tooltip=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|text|(str) Text that is to be displayed in the widget| +|size|Tuple[(int), (int)] (w,h) w=characters-wide, h=rows-high| +|auto_size_text|(bool) True if size should fit the text length| +|click_submits|(bool) DO NOT USE. Only listed for backwards compat - Use enable_events instead| +|enable_events|(bool) Turns on the element specific events. StatusBar events occur when the bar is clicked| +|relief|(enum) relief style. Values are same as progress meter relief values. Can be a constant or a string: `RELIEF_RAISED RELIEF_SUNKEN RELIEF_FLAT RELIEF_RIDGE RELIEF_GROOVE RELIEF_SOLID`| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|text_color|(str) color of the text| +|background_color|(str) color of background| +|justification|(str) how string should be aligned within space provided by size. Valid choices = `left`, `right`, `center`| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element to uniquely identify this element| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|visible|(bool) set visibility state of the element| + #### SetFocus Sets the current focus to be on this element @@ -6707,6 +7475,40 @@ Parameter Descriptions: Tab Element is another "Container" element that holds a layout and displays a tab with text. Used with TabGroup only Tabs are never placed directly into a layout. They are always "Contained" in a TabGroup layout +``` +Tab(title, + layout, + title_color=None, + background_color=None, + font=None, + pad=None, + disabled=False, + border_width=None, + key=None, + tooltip=None, + right_click_menu=None, + visible=True, + element_justification="left") +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|title|(str) text to show on the tab| +|layout|List[List[Element]] The element layout that will be shown in the tab| +|title_color|(str) color of the tab text (note not currently working on tkinter)| +|background_color|(str) color of background of the entire layout| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|disabled|(bool) If True button will be created disabled| +|border_width|(int) width of border around element in pixels| +|key|(any) Value that uniquely identifies this element from all other elements. Used when Finding an element or in return values. Must be unique to the window| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|visible|(bool) set visibility state of the element| +|element_justification|(str) All elements inside the Tab will have this justification 'left', 'right', 'center' are valid values| + #### AddRow Not recommended use call. Used to add rows of Elements to the Frame Element. @@ -6792,6 +7594,42 @@ Parameter Descriptions: TabGroup Element groups together your tabs into the group of tabs you see displayed in your window +``` +TabGroup(layout, + tab_location=None, + title_color=None, + selected_title_color=None, + background_color=None, + font=None, + change_submits=False, + enable_events=False, + pad=None, + border_width=None, + theme=None, + key=None, + tooltip=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|layout|List[List[Tab]] Layout of Tabs. Different than normal layouts. ALL Tabs should be on first row| +|tab_location|(str) location that tabs will be displayed. Choices are left, right, top, bottom, lefttop, leftbottom, righttop, rightbottom, bottomleft, bottomright, topleft, topright| +|title_color|(str) color of text on tabs| +|selected_title_color|(str) color of tab when it is selected| +|background_color|(str) color of background of tabs| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|change_submits|(bool) * DEPRICATED DO NOT USE! Same as enable_events| +|enable_events|(bool) If True then switching tabs will generate an Event| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|border_width|(int) width of border around element in pixels| +|theme|(enum) tabs can be 'themed'. These are the choices (some may not work on your OS): THEME_DEFAULT THEME_WINNATIVE THEME_CLAM THEME_ALT THEME_CLASSIC THEME_VISTA THEME_XPNATIVE| +|key|(any) Value that uniquely identifies this element from all other elements. Used when Finding an element or in return values. Must be unique to the window| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|visible|(bool) set visibility state of the element| + #### AddRow Not recommended user call. Used to add rows of Elements to the Frame Element. @@ -6881,6 +7719,70 @@ Parameter Descriptions: ### Table Element +``` +Table(values, + headings=None, + visible_column_map=None, + col_widths=None, + def_col_width=10, + auto_size_columns=True, + max_col_width=20, + select_mode=None, + display_row_numbers=False, + num_rows=None, + row_height=None, + font=None, + justification="right", + text_color=None, + background_color=None, + alternating_row_color=None, + row_colors=None, + vertical_scroll_only=True, + hide_vertical_scroll=False, + size=(None, None), + change_submits=False, + enable_events=False, + bind_return_key=False, + pad=None, + key=None, + tooltip=None, + right_click_menu=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|values|List[List[Union[str, int, float]]]| +|headings|List[str] The headings to show on the top line| +|visible_column_map|List[bool] One entry for each column. False indicates the column is not shown| +|col_widths|List[int] Number of characters that each column will occupy| +|def_col_width|(int) Default column width in characters| +|auto_size_columns|(bool) if True columns will be sized automatically| +|max_col_width|(int) Maximum width for all columns in characters| +|select_mode|(enum) Select Mode. Valid values start with "TABLE_SELECT_MODE_". Valid values are: TABLE_SELECT_MODE_NONE TABLE_SELECT_MODE_BROWSE TABLE_SELECT_MODE_EXTENDED| +|display_row_numbers|(bool) if True, the first column of the table will be the row #| +|num_rows|(int) The number of rows of the table to display at a time| +|row_height|(int) height of a single row in pixels| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|justification|(str) 'left', 'right', 'center' are valid choices| +|text_color|(str) color of the text| +|background_color|(str) color of background| +|alternating_row_color|(str) if set then every other row will have this color in the background.| +|row_colors|| +|vertical_scroll_only|(bool) if True only the vertical scrollbar will be visible| +|hide_vertical_scroll|(bool) if True vertical scrollbar will be hidden| +|size|Tuple[int, int] DO NOT USE! Use num_rows instead| +|change_submits|(bool) DO NOT USE. Only listed for backwards compat - Use enable_events instead| +|enable_events|(bool) Turns on the element specific events. Table events happen when row is clicked| +|bind_return_key|(bool) if True, pressing return key will cause event coming from Table, ALSO a left button double click will generate an event if this parameter is True| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element to uniquely identify this element| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|visible|(bool) set visibility state of the element| + #### SetFocus Sets the current focus to be on this element @@ -6937,6 +7839,44 @@ Parameter Descriptions: Text - Display some text in the window. Usually this means a single line of text. However, the text can also be multiple lines. If multi-lined there are no scroll bars. +``` +Text(text, + size=(None, None), + auto_size_text=None, + click_submits=False, + enable_events=False, + relief=None, + font=None, + text_color=None, + background_color=None, + justification=None, + pad=None, + key=None, + right_click_menu=None, + tooltip=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|text|(str) The text to display. Can include /n to achieve multiple lines| +|size|Tuple[int, int] (width, height) width = characters-wide, height = rows-high| +|auto_size_text|(bool) if True size of the Text Element will be sized to fit the string provided in 'text' parm| +|click_submits|(bool) DO NOT USE. Only listed for backwards compat - Use enable_events instead| +|enable_events|(bool) Turns on the element specific events. Text events happen when the text is clicked| +|relief|(str/enum) relief style around the text. Values are same as progress meter relief values. Should be a constant that is defined at starting with "RELIEF_" - `RELIEF_RAISED, RELIEF_SUNKEN, RELIEF_FLAT, RELIEF_RIDGE, RELIEF_GROOVE, RELIEF_SOLID`| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|text_color|(str) color of the text| +|background_color|(str) color of background| +|justification|(str) how string should be aligned within space provided by size. Valid choices = `left`, `right`, `center`| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element to uniquely identify this element| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|visible|(bool) set visibility state of the element| + #### SetFocus Sets the current focus to be on this element @@ -6992,6 +7932,60 @@ Parameter Descriptions: Tree Element - Presents data in a tree-like manner, much like a file/folder browser. Uses the TreeData class to hold the user's data and pass to the element for display. +``` +Tree(data=None, + headings=None, + visible_column_map=None, + col_widths=None, + col0_width=10, + def_col_width=10, + auto_size_columns=True, + max_col_width=20, + select_mode=None, + show_expanded=False, + change_submits=False, + enable_events=False, + font=None, + justification="right", + text_color=None, + background_color=None, + num_rows=None, + row_height=None, + pad=None, + key=None, + tooltip=None, + right_click_menu=None, + visible=True) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|data|(TreeData) The data represented using a PySimpleGUI provided TreeData class| +|headings|List[str] List of individual headings for each column| +|visible_column_map|List[bool] Determines if a column should be visible. If left empty, all columns will be shown| +|col_widths|List[int] List of column widths so that individual column widths can be controlled| +|col0_width|(int) Size of Column 0 which is where the row numbers will be optionally shown| +|def_col_width|(int) default column width| +|auto_size_columns|(bool) if True, the size of a column is determined using the contents of the column| +|max_col_width|(int) the maximum size a column can be| +|select_mode|(enum) Use same values as found on Table Element. Valid values include: TABLE_SELECT_MODE_NONE TABLE_SELECT_MODE_BROWSE TABLE_SELECT_MODE_EXTENDED| +|show_expanded|(bool) if True then the tree will be initially shown with all nodes completely expanded| +|change_submits|(bool) DO NOT USE. Only listed for backwards compat - Use enable_events instead| +|enable_events|(bool) Turns on the element specific events. Tree events happen when row is clicked| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|justification|(str) 'left', 'right', 'center' are valid choices| +|text_color|(str) color of the text| +|background_color|(str) color of background| +|num_rows|(int) The number of rows of the table to display at a time| +|row_height|(int) height of a single row in pixels| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| +|key|(Any) Used with window.FindElement and with return values to uniquely identify this element to uniquely identify this element| +|tooltip|(str) text, that will appear when mouse hovers over the element| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|visible|(bool) set visibility state of the element| + #### SetFocus Sets the current focus to be on this element @@ -7050,6 +8044,12 @@ Parameter Descriptions: with possibly one or more children "Nodes". Each Node contains a key, text to display, list of values to display and an icon. The entire tree is built using a single method, Insert. Nothing else is required to make the tree. +Instantiate the object, initializes the Tree Data, creates a root node for you + +```python +TreeData() +``` + #### Insert Inserts a node into the tree. This is how user builds their tree, by Inserting Nodes @@ -7090,6 +8090,16 @@ Node(parent, Vertical Separator Element draws a vertical line at the given location. It will span 1 "row". Usually paired with Column Element if extra height is needed +``` +VerticalSeparator(pad=None) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|pad|(int, int) or ((int, int),(int,int)) Amount of padding to put around element (left/right, top/bottom) or ((left, right), (top, bottom))| + #### SetFocus Sets the current focus to be on this element @@ -7122,6 +8132,82 @@ Parameter Descriptions: Represents a single Window +``` +Window(title, + layout=None, + default_element_size=(45, 1), + default_button_element_size=(None, None), + auto_size_text=None, + auto_size_buttons=None, + location=(None, None), + size=(None, None), + element_padding=None, + margins=(None, None), + button_color=None, + font=None, + progress_bar_color=(None, None), + background_color=None, + border_depth=None, + auto_close=False, + auto_close_duration=3, + icon=None, + force_toplevel=False, + alpha_channel=1, + return_keyboard_events=False, + use_default_focus=True, + text_justification=None, + no_titlebar=False, + grab_anywhere=False, + keep_on_top=False, + resizable=False, + disable_close=False, + disable_minimize=False, + right_click_menu=None, + transparent_color=None, + debugger_enabled=True, + finalize=False, + element_justification="left") +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|title|(str) The title that will be displayed in the Titlebar and on the Taskbar| +|layout|List[List[Elements]] The layout for the window. Can also be specified in the Layout method| +|default_element_size|Tuple[int, int] (width, height) size in characters (wide) and rows (high) for all elements in this window| +|default_button_element_size|Tuple[int, int] (width, height) size in characters (wide) and rows (high) for all Button elements in this window| +|auto_size_text|(bool) True if Elements in Window should be sized to exactly fir the length of text| +|auto_size_buttons|(bool) True if Buttons in this Window should be sized to exactly fit the text on this.| +|location|Tuple[int, int] (x,y) location, in pixels, to locate the upper left corner of the window on the screen. Default is to center on screen.| +|size|Tuple[int, int] (width, height) size in pixels for this window. Normally the window is autosized to fit contents, not set to an absolute size by the user| +|element_padding|Tuple[int, int] or ((int, int),(int,int)) Default amount of padding to put around elements in window (left/right, top/bottom) or ((left, right), (top, bottom))| +|margins|Tuple[int, int] (left/right, top/bottom) Amount of pixels to leave inside the window's frame around the edges before your elements are shown.| +|button_color|Tuple[str, str] (text color, button color) Default button colors for all buttons in the window| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|progress_bar_color|Tuple[str, str] (bar color, background color) Sets the default colors for all progress bars in the window| +|background_color|(str) color of background| +|border_depth|(int) Default border depth (width) for all elements in the window| +|auto_close|(bool) If True, the window will automatically close itself| +|auto_close_duration|(int) Number of seconds to wait before closing the window| +|icon|Union[str, str] Can be either a filename or Base64 value.| +|force_toplevel|(bool) If True will cause this window to skip the normal use of a hidden master window| +|alpha_channel|(float) Sets the opacity of the window. 0 = invisible 1 = completely visible. Values bewteen 0 & 1 will produce semi-transparent windows in SOME environments (The Raspberry Pi always has this value at 1 and cannot change.| +|return_keyboard_events|(bool) if True key presses on the keyboard will be returned as Events from Read calls| +|use_default_focus|(bool) If True will use the default focus algorithm to set the focus to the "Correct" element| +|text_justification|(str) Union ['left', 'right', 'center'] Default text justification for all Text Elements in window| +|no_titlebar|(bool) If true, no titlebar nor frame will be shown on window. This means you cannot minimize the window and it will not show up on the taskbar| +|grab_anywhere|(bool) If True can use mouse to click and drag to move the window. Almost every location of the window will work except input fields on some systems| +|keep_on_top|(bool) If True, window will be created on top of all other windows on screen. It can be bumped down if another window created with this parm| +|resizable|(bool) If True, allows the user to resize the window. Note the not all Elements will change size or location when resizing.| +|disable_close|(bool) If True, the X button in the top right corner of the window will no work. Use with caution and always give a way out toyour users| +|disable_minimize|(bool) if True the user won't be able to minimize window. Good for taking over entire screen and staying that way.| +|right_click_menu|List[List[Union[List[str],str]]] A list of lists of Menu items to show when this element is right clicked. See user docs for exact format.| +|transparent_color|(str) Any portion of the window that has this color will be completely transparent. You can even click through these spots to the window under this window.| +|debugger_enabled|(bool) If True then the internal debugger will be enabled| +|finalize|(bool) If True then the Finalize method will be called. Use this rather than chaining .Finalize for cleaner code| +|element_justification|(str) All elements in the Window itself will have this justification 'left', 'right', 'center' are valid values| + #### AddRow Adds a single row of elements to a window's self.Rows variables. @@ -7156,14 +8242,6 @@ Parameter Descriptions: #### AlphaChannel -#### property: AlphaChannel - -A property that changes the current alpha channel value (internal value) - -|Name|Meaning| -|---|---| -| **return** | (float) the current alpha channel setting according to self, not read directly from tkinter | - #### BringToFront Brings this window to the top of all other windows (perhaps may not be brought before a window made to "stay @@ -7666,14 +8744,6 @@ Parameter Descriptions: #### Size -#### property: Size - -Return the current size of the window in pixels - -|Name|Meaning| -|---|---| -| **return** | Tuple[(int), (int)] the (width, height) of the window | - #### UnHide Used to bring back a window that was previously hidden using the Hide method