From 48ef8e5827902e918be06d0c010600722781a339 Mon Sep 17 00:00:00 2001 From: MikeTheWatchGuy Date: Fri, 30 Aug 2019 21:02:42 -0400 Subject: [PATCH] TONS of changes - NEW additions PEP8, Multithreading, shortcut for FindElement AND Element.Update, HorizontalSeparator, Column justification, Sizer Element, Table.Get for Qt, Extending PySimpleGUI, ChangeLookAndFeel values --- docs/index.md | 1500 +++++++++++++------------------------------------ readme.md | 1500 +++++++++++++------------------------------------ 2 files changed, 782 insertions(+), 2218 deletions(-) diff --git a/docs/index.md b/docs/index.md index 3772a0af..1ccf0b5c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -940,9 +940,11 @@ Here are some Python-friendly aspects to PySimpleGUI: #### Lofty Goals -> Change Python +> Teach GUI Programming to Beginners -The hope is **not** that ***this*** package will become part of the Python Standard Library. The hope is that Python will become ***the*** go-to language for creating GUI programs that run on Windows, Mac, and Linux *for all levels of developer*. Perhaps this sort of package is needed to make that happen. It would be nice if there was a "unified interface" for GUIs like PySimpleGUI presents, along with the vendor specific calls. +By and large PySimpleGUI is a "pattern based" SDK. Complete beginners can copy these standard design patterns or demo programs and modify them without necessarily understanding all of the nuts and bolts of what's happening. For example, they can modify a layout by adding elements even though they may not yet grasp the list of lists concept of layouts. + +Beginners certainly can add more `if event == 'my button':` statements to the event loop that they copied from the same design pattern. They will not have to write classes to use this package. > Capture Budding Graphic Designers & Non-Programmers @@ -1064,12 +1066,13 @@ When you type sg, Python will tell you the full patch to your PySimpleGUI file / ### Finding Out Where Your PySimpleGUI Is Coming From (from within your code) -If you continue to have troubles with getting the right version of PySimpleGUI loaded, THE ***definitive*** way to determine where your program is getting PySimpleGUI from is to add a print to your program. It's that *simple*! +If you continue to have troubles with getting the right version of PySimpleGUI loaded, THE ***definitive*** way to determine where your program is getting PySimpleGUI from is to add a print to your program. It's that *simple*! You can also get the version you are running by also printing ```python import PySimpleGUI as sg print(sg) +print(sg.version) ``` Just like when using the REPL >>> to determine the location, this `print` in your code will display the same path information. @@ -1081,6 +1084,7 @@ If you're not connected to the net on your target machine, or pip isn't working, Be ***sure*** that you delete this PySimpleGUI.py file if you install a newer pip version. Often the sequence of events is that a bug you've reported was fixed and checked into GitHub. You download the PySimpleGUI.py file (or the appropriately named one for your port) and put with your app. Then later your fix is posted with a new release on PyPI. You'll want to delete the GitHub one before you install from pip. ### Prerequisites + Python 2.7 or Python 3 tkinter @@ -1140,7 +1144,7 @@ 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. +***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. ### Python 3.7 @@ -1167,8 +1171,40 @@ else: This will automatically import the correct library based on the Python version number reported by the Python interpreter. +NOTE: It's 2019 and 2.7 support is being systematically removed. This construct will be removed from the demo programs shortly. 2.7 users can still run these demos, but they will need to change the import from PySimpleGUI to PySimpleGUI27. It save 4 lines of code and an import from sys in the process. + --- +# PEP8 Bindings For Methods and Functions + +Beginning with release 4.3 of PySimpleGUI, ***all methods and function calls*** have PEP8 equivalents. This capability is only available, for the moment, on the PySimpleGUI tkinter port. It is being added, as quickly as possible, to all of the ports. + +As long as you know you're sticking with tkinter for the short term, it's safe to use the new bindings. + +## The Non-PEP8 Methods and Functions + +Why the need for these bindings? Simply put, the PySimpleGUI SDK has a PEP8 violation in the method and function names. PySimpleGUI uses CamelCase names for methods and functions. PEP8 suggests using snake_case_variables instead. + +This has not caused any problems and few complaints, but it's important the the interfaces into PySimpleGUI be compliant. Perhaps one of the reasons for lack of complaints is that the Qt library also uses SnakeCase for its methods. This practice has the effect of labelling a package as being "not Pythonic" and also suggests that ths package was originally used in another language and then ported to Python. This is exactly the situation with Qt. It was written for C++ and the interfaces continue to use C++ conventions. + +***PySimpleGUI was written in Python, for Python.*** The reason for the name problem was one of ignorance. The PEP8 convention wasn't understood by the developers when PySimpleGUI was designed and implemented. + +You can, and will be able to for some time, use both names. However, at some point in the future, the CamelCase names will disappear. A utility is planned to do the conversion for the developer when the old names are remove from PySimpleGUI. + +The help system will work with both names as will your IDE's docstring viewing. However, the result found will show the CamelCase names. For example `help(sg.Window.read)` will show the CamelCase name of the method/function. This is what will be returned: + +`Read(self, timeout=None, timeout_key='__TIMEOUT__')` + +## The Renaming Convention + +To convert a CamelCase method/function name to snake_case, you simply place an `_` where the Upper Case letter is located. If there are none, then only the first letter is changed. + +`Window.FindElement` becomes `Window.find_element` + +## Class Variables + +For the time being, class variables will remain the way they are currently. It is unusual, in PySimpleGUI, for class variables to be modified or read by the user code so the impact of leaving them is rarely seen in your code. + # High Level API Calls - Popup's "High level calls" are those that start with "Popup". They are the most basic form of communications with the user. They are named after the type of window they create, a pop-up window. These windows are meant to be short lived while, either delivering information or collecting it, and then quickly disappearing. @@ -2275,6 +2311,40 @@ If your window has no keys and it has no buttons that are "browse" type of butto Note in the list of return values in this example, many of the keys are numbers. That's because no keys were specified on any of the elements (although one was automatically made for you). If you don't specify a key for your element, then a number will be sequentially assigned. For elements that you don't plan on modifying or reading values from, like a Text Element, you can skip adding keys. For other elements, you'll likely want to add keys so that you can easily access the values and perform operations on them. +### Operations That Take a "Long Time" + +If you're a Windows user you've seen windows show in their title bar "Not Responding" which is soon followed by a Windows popop stating that "Your program has stopped responding". Well, you too can make that message and popup appear if you so wish! All you need to do is execute an operation that takes "too long" (i.e. a few seconds) inside your event loop. + +You have a couple of options for dealing this with. If your operation can be broken up into smaller parts, then you can call `Window.Refresh()` occassionally to avoid this message. If you're running a loop for example, drop that call in with your other work. This will keep the GUI happy and Window's won't complain. + +If, on the other hand, your operation is not under your control or you are unable to add `Refresh` calls, then the next option available to you is to move your long operations into a thread. + +There are a couple of demo programs available for you to see how to do this. You basically put your work into a thread. When the thread is completed, it tells the GUI by sending a message through a queue. The event loop will run with a timer set to a value that represents how "responsive" you want your GUI to be to the work completing. + +These 2 demo programs are called +```python +Demo_Threaded_Work.py - Best documented. Single thread used for long task +Demo_Multithreaded_Long_Tasks.py - Similar to above, but with less fancy GUI. Allows you to set amount of time +``` + +These 2 particular demos have a LOT of comments showing you where to add your code, etc. The amount of code to do this is actually quite small and you don't need to understand the mechanisms used if you simply follow the demo that's been prepared for you. + +### Multitheaded Programs + +While on the topic of multiple threads, another demo was prepared that shows how you can run multiple threads in your program that all communicate with the event loop in order to display something in the GUI window. Recall that for PySimpleGUI (at least the tkinter port) you cannot make PySimpleGUI calls in threads other than the main program thread. + +The key to these threaded programs is communication from the threads to your event loop. The mechanism chosen for these demonstrations uses the Python built-in `queue` module. The event loop polls these queues to see if something has been sent over from one of the threads to be displayed. + +You'll find the demo that shows multiple threads communicating with a single GUI is called: + +```python +Demo_Multithreaded_Queued.py +``` + +Once again a **warning** is in order for plain PySimpleGUI (tkinter based) - your GUI must never run as anything but the main program thread and no threads can directly call PySimpleGUI calls. + +--- + # Building Custom Windows You will find it ***much easier*** to write code using PySimpleGUI if you use an IDE such as ***PyCharm***. The features that show you documentation about the API call you are making will help you determine which settings you want to change, if any. In PyCharm, two commands are particularly helpful. @@ -2282,8 +2352,10 @@ You will find it ***much easier*** to write code using PySimpleGUI if you use an Control-Q (when cursor is on function name) brings up a box with the function definition Control-P (when cursor inside function call "()") shows a list of parameters and their default values -## Synchronous windows +## Synchronous / Asynchronous Windows + The most common use of PySimpleGUI is to display and collect information from the user. The most straightforward way to do this is using a "blocking" GUI call. Execution is "blocked" while waiting for the user to close the GUI window/dialog box. + You've already seen a number of examples above that use blocking windows. You'll know it blocks if the `Read` call has no timeout parameter. A blocking Read (one that waits until an event happens) look like this: @@ -2304,7 +2376,7 @@ You can learn more about these async / non-blocking windows toward the end of th The first step is to create the window object using the desired window customizations. -**IMPORTANT** - Many of the `Window` methods require you to either call `Window.Read` or `Window.Finalize` before you call the method. This is because these 2 calls are what actually creates the window using the underlying GUI Framework. Prior to one of those calls, the methods are likely to crash as they will not yet have their underlying widgets created. +**IMPORTANT** - Many of the `Window` methods require you to either call `Window.Read` or `Window.Finalize` (or set `finalize=True` in your `Window` call) before you call the method. This is because these 2 calls are what actually creates the window using the underlying GUI Framework. Prior to one of those calls, the methods are likely to crash as they will not yet have their underlying widgets created. ### Window Location @@ -2418,7 +2490,7 @@ Call to set the window layout. Must be called prior to `Read`. Most likely "ch window = sg.Window('My window title', layout) ``` -#### Finalize() +#### `Finalize()` or `Window` parameter `finalize=True` Call to force a window to go through the final stages of initialization. This will cause the tkinter resources to be allocated so that they can then be modified. This also causes your window to appear. If you do not want your window to appear when Finalize is called, then set the Alpha to 0 in your window's creation parameters. @@ -2436,6 +2508,8 @@ If you set the timeout = 0, then the Read will immediately return rather than wa While at this point in the documentation you've not been shown very much about each Element available, you should read this section carefully as you can use the techniques you learn in here to build better, shorter, and easier to understand PySimpleGUI code. +If it feels like this layout section is too much too soon, then come back to this section after you're learned about each Element. **Whatever order you find the least confusing is the best.** + While you've not learned about Elements yet, it makes sense for this section to be up front so that you'll have learned how to use the elements prior to learning how each element works. At this point in your PySimpleGUI education, it is better for you to grasp time efficient ways of working with Elements than what each Element does. By learning now how to assemble Elements now, you'll have a good model to put the elements you learn into. There are *several* aspects of PySimpleGUI that make it more "Pythonic" than other Python GUI SDKs. One of the areas that is unique to PySimpleGUI is how a window's "layout" is defined, specified or built. A window's "layout" is simply a list of lists of elements. As you've already learned, these lists combine to form a complete window. This method of defining a window is super-powerful because lists are core to the Python language as a whole and thus are very easy to create and manupulate. @@ -2450,7 +2524,7 @@ Many times your window definition / layout will be a static, straightforward to However, window layouts are not limited to being one of these staticly defined list of Elements. -# Generated Layouts (Please read especially if your GUI has more than 10 Elements) +# Generated Layouts (For sure want to read if you have > 5 repeating elements/rows) There are 5 specific techniques of generating layouts discussed in this section. They can be used alone or in combination with each other. @@ -2808,6 +2882,7 @@ You will find information on Elements and all other classes and functions are lo - StatusBar - Pane - Stretch (Qt only) +- Sizer (plain PySimpleGUI only) ## Common Element Parameters @@ -2945,6 +3020,58 @@ layout = [ --- +## `Window.FindElement(key)` Shortcut `Window[key]` + +There's been a fantastic leap forward in making PySimpleGUI code more compact. + +Instead of writing: +```python +window.FindElement(key).Update(new_value) + ``` + +You can now write it as: + +```python +window[key].Update(new_value) + ``` + +This change has been released to PyPI for PySimpleGUI +It **has not yet been released to PyPI** for the other ports of PySimpleGUI (Qt, Wx, Web). You'll find the change on GitHub however for Qt and Web (still working on Wx). + +MANY Thanks is owed to the person that suggested and showed me how to do this. It's an incredible find. + +## `Element.Update()` Shortcut `Element()` + +This has to be one of the strangest syntactical contructs I've ever written. + +It is best used in combination with `FindElement` (see prior section on how to shortcut `FindElement`). When used with the `FindElement` shortcut, the code to update an element can be shortened to this unusual looking call: + +```python +window[key](new_value) +``` + +Yes, that's a valid statement in Python. + +It is confusing looking however so when used, it might be a good idea to write a comment at the end of the statement to help out the poor beginner programmer coming along behind you. + +Still debating whether to begin to immediately use this for all demos going forward and also if should go back and change the docs and demo programs, essentially removing the other technique for doing an update. + +It does not have to be used in conjuction with `FindElement`. The call works on any previously made Element. Sometimes elements are created, stored into a variable and then that variable is used in the layout. For example. + +```python +graph_element = sg.Graph(...... lots of parms ......) + +layout = [[graph_element]] +. +. +. +graph_element(background_color='blue') # this calls Graph.Update for the previously defined element +``` + +Hopefully this isn't too confusing. Note that the methods these shortcuts replace will not be removed. You can continue to use the old constructs without changes. + +--- + ### Fonts Already discussed in the common parameters section. Either string or a tuple. @@ -3034,6 +3161,8 @@ layout = [[sg.Slider(range=(1,500), There is an important difference between Qt and tkinter sliders. On Qt, the slider values must be integer, not float. If you want your slider to go from 0.1 to 1.0, then make your slider go from 1 to 10 and divide by 10. It's an easy math thing to do and not a big deal. Just deal with it.... you're writing software after all. Presumably you know how to do these things. ;-) +## Radio Button Element + Creates one radio button that is assigned to a group of radio buttons. Only 1 of the buttons in the group can be selected at any one time. ```python @@ -3147,7 +3276,7 @@ layout = [[sg.Ok(), sg.Cancel()]] In reality `Button` is in fact being called on your behalf. Behind the scenes, `sg.Ok` and `sg.Cancel` call `Button` with the text set to `Ok` and `Cancel` and returning the results that then go into the layout. If you were to print the layout it will look identical to the first layout shown that has `Button` shown specifically in the layout. -### Shortcut, Pre-defined Buttons +### Button Element Shortcuts These Pre-made buttons are some of the most important elements of all because they are used so much. They all basically do the same thing, **set the button text to match the function name and set the parameters to commonly used values**. If you find yourself needing to create a custom button often because it's not on this list, please post a request on GitHub. . They include: - OK @@ -3379,6 +3508,7 @@ One use of this element is to make a "fake menu bar" that has a colored backgrou Return values for ButtonMenus are sent via the return values dictionary. If a selection is made, then an event is generated that will equal the ButtonMenu's key value. Use that key value to look up the value selected by the user. This is the same mechanism as the Menu Bar Element, but differs from the pop-up (right click) menu. ## VerticalSeparator Element + This element has limited usefulness and is being included more for completeness than anything else. It will draw a line between elements. It works best when placed between columns or elements that span multiple rows. If on a "normal" row with elements that are only 1 row high, then it will only span that one row. @@ -3389,6 +3519,16 @@ VerticalSeparator(pad=None) ![snag-0129](https://user-images.githubusercontent.com/13696193/47376041-a92a0100-d6bf-11e8-8f5b-0c0df56cf0f3.jpg) +## HorizontalSeparator Element + +In PySimpleGUI, the tkinter port, there is no `HorizontalSeparator` Element. One will be added as a "stub" so that code is portable. It will likely do nothing just like the `Stretch` Element. + +An easy way to get a horizontal line in PySimpleGUI is to use a `Text` Element that contains a line of underscores + +```python +sg.Text('_'*30) # make a horizontal line stretching 30 characters +``` + ## ProgressBar Element The `ProgressBar` element is used to build custom Progress Bar windows. It is HIGHLY recommended that you use OneLineProgressMeter that provides a complete progress meter solution for you. Progress Meters are not easy to work with because the windows have to be non-blocking and they are tricky to debug. @@ -3479,16 +3619,16 @@ ChatBot() Starting in version 2.9 you'll be able to do more complex layouts by using the Column Element. Think of a Column as a window within a window. And, yes, you can have a Column within a Column if you want. -Columns are specified in exactly the same way as a window is, as a list of lists. +Columns are specified, like all "container elements", in exactly the same way as a window, as a list of lists. -Columns are needed when you have an element that has a height > 1 line on the left, with single-line elements on the right. Here's an example of this kind of layout: +Columns are needed when you want to specify more than 1 element in a single row. + +For example, this layout has a single slider element that spans several rows followed by 7 `Text` and `Input` elements on the same row. ![column](https://user-images.githubusercontent.com/13696193/44959988-66b92480-aec5-11e8-9c26-316ed24a68c0.jpg) Without a Column Element you can't create a layout like this. But with it, you should be able to closely match any layout created using tkinter only. ---- - ```python import PySimpleGUI as sg @@ -3514,14 +3654,42 @@ layout = [[sg.Slider(range=(1,100), default_value=10, orientation='v', size=(8,2 [sg.OK()]] # Display the window and get values -# If you're willing to not use the "context manager" design pattern, then it's possible -# to collapse the window display and read down to a single line of code. -event, values = sg.Window('Compact 1-line window with column', layout).Read() + +window = sg.Window('Compact 1-line window with column', layout) +event, values = window.Read() +window.Close() sg.Popup(event, values, line_width=200) ``` +### Column Justification + +Beginning in Release 4.3 you can justify the `Column` element's row by setting the `Column`'s `justification` parameter. + +You can also justify the entire contents within a `Column` by using the Column's `element_justification` parameter. + +With these parameter's it is possible to create windows that have their contents centered. Previously this was very difficult to do. + +This is currently only available in the primary PySimpleGUI port. + +They can also be used to justify a group of elements in a particular way. + +Placing `Column` elements inside `Columns` elements make it possible to create a multitude of + +## Sizer Element + +New in 4.3 is the `Sizer` Element. This element is used to help create a container of a particular size. It can be placed inside of these PySimpleGUI items: + +* Column +* Frame +* Tab +* Window + +The implementation of a `Sizer` is quite simple. It returns an empty `Column` element that has a pad value set to the values passed into the `Sizer`. Thus isn't not a class but rather a "Shortcut function" similar to the pre-defined Buttons. + +This feature is only available in the tkinter port of PySimpleGUI at the moment. A cross port is needed. + ---- ## Frame Element (Labelled Frames, Frames with a title) @@ -3667,16 +3835,23 @@ graph+UP {'graph': (154, 254)} ## Table Element -Out of all of the Elements, it's the Table and the Tree that are the most "problematic" in the tkinter inter and Qt implementations. They're hard is my only defense. +Out of all of the Elements, it's the Table and the Tree that are the most "problematic" in the tkinter inter and Qt implementations. They have been difficult implementation. (yea.... get of over it) -### Read return values from Table Element +### `window.Read()` return values from Table Element The values returned from a `Window.Read` call for the Table Element are a list of row numbers that are currently highlighted. ---- -### Known visualization problem.... +### The Qt `Table.Get()` call -If you click on the header, it can go into spasms for some tables. I don't understand what's causing it and it's been there evidently since the first release of Tables. +New in **PySimpleGUIQt** is the addition of the `Table` method `Get`. This method returns the table that is currently being shown in the GUI. This method was required in order to obtain any edits the user may have made to the table. + +For the tkinter port, it will return the same values that was passed in when the table was created because tkinter Tables cannot be modified by the user (please file an Issue if you know a way). + +### Known `Table` visualization problem.... + +There has been an elusive problem where clicking on or near the table's header caused tkinter to go crazy and resize the columns continuously as you moved the mouse. + +This problem has existed since the first release of the `Table` element. It was fixed in release 4.3. ## Tree Element @@ -4785,6 +4960,102 @@ Exception module 'tkinter' has no attribute '__version__' ``` --- +# Extending PySimpleGUI + +PySimpleGUI doesn't and can't provide every single setting available in the underlying GUI framework. Not all tkinter options are available for a `Text` Element. Same with PySimpleGUIQt and the other ports. + +There are a few of reasons for this. + +1. Time & resource limits - The size of the PySimpleGUI development team is extremely small +2. PySimpleGUI provides a "Unified API". This means the code is, in theory, portable across all of the PySimpleGUI ports without chaning the user's code (except for the import) +3. PySimpleGUI is meant, by design, to be simple and cover 80% of the GUI problems. + +However, PySimpleGUI programs are ***not*** dead ends!! Writing PySimpleGUI code and then getting to a point where you really really feel like you need to extend the Listbox to include the ability to change the "Selected" color. Maybe that's super-critical to your project. And maybe you find out late that the base PySimpleGUI code doesn't expose that tkinter capability. Fear not! The road does continue!! + +## Widget Access + +Most of the user extensions / enhancements are at the "Element" level. You want some Element to do a trick that you cannot do using the existing PySimpleGUI APIs. It's just not possible. What to do? + +What you need is access to the underlying GUI framework's "Widget". The good news is that you HAVE that access ready and waiting for you, for all of the ports of PySimpleGUI, not just the tkinter one. + +### `Element.Widget` is The GUI Widget + +The class variable `Widget` contains the tkinter, Qt, WxPython, or Remi widget. With that variable you can modify that widget directly. + +***You must first `Read` or `Finalize` the window before accessing the `Widget` class variable*** + +The reason for the Finalize requirement is that until a Window is Read or is Finalized it is not actually created and populated with GUI Widgets. The GUI Widgets are created when you do these 2 operations. + +Side note - You can stop using the `.Finalize()` call added onto your window creation and instead use the `finalize` parameter in the `Window` call. + +OLD WAY: +```python +window = sg.Window('Window Title', layout).Finalize() + +``` + +THE NEW WAY: +```python +window = sg.Window('Window Title', layout, finalize=True) + +``` + +It's cleaner and less confusing for beginners who aren't necessarily trained in how chaining calls work. Py**Simple**GUI. + +### Example Use of `Element.Widget` + +So far there have been 2 uses of this capability. One already mentioned is adding a new capability. The other way it's been used has been to fix a bug or make a workaround for a quirky behavior. + +A recent Issue posted was that focus was always being set on a button in a tab when you switch tabs in tkinter. The user didn't want this to happen as it was putting an ugly black line around their nicely made graphical button. + +There is no current way in PySimpleGUI to "disable focus" on an Element. That's essentially what was needed, the ability to tell tkinter that this widget should never get focus. + +There is a way to tell tkinter that a widget should not get focus. The downside is that if you use your tab key to navigate, that element will never get focus. So, it's not only blocking focus for this automatic problem, but blocking it for all uses. Of course you can still click on the button. + +The way through for this user was to modify the tkinter widget directly and tell it not to get focus. This was done in a single line of code: + +```python +window[button_key].Widget.config(takefocus=0) +``` + +The absolute beauty to this solution is that tkinter does NOT need to be imported into the user's program for this statement to run. Python already know what kind of object `.Widget` is and can thus show you the various methods and class variables for that object. Most all tkinter options are strings so you don't need to import tkinter to get any enums. + +### Finding Your Element's Widget Type + +Of course, in order to call the methods or access the object's class variables, you need to know the type of the underlying Widget being used. This document could list them all, but the downside is the widget could change types (not a good thing for people using the .Widget already!). It also saves space and time in getting this documentation published and available to you. + +So, here's the way to get your element's widget's type: + +```python + print(type(window[your_element_key].Widget)) +``` + +In the case of the button example above, what is printed is: + +`` + +I don't think that could be any clearer. Your job at this point is to look at the tkinter documentation to see what the methods are for the tkinter `Button` widget. + +## Window Level Access + +For this one you'll need some specific variables for the time being as there is no `Window` class variable that holds the window's representation in the GUI library being used. + +For tkinter, at the moment, the window's root object is this: + +```python +sg.Window.TKroot +``` + +The type will vary in PySimpleGUI. It will either be: +`tkinter.Tk()` +`tkinter.Toplevel()` + +Either way you'll access it using the same `Window` variable `sg.Window.TKroot` + +Watch this space in the future for the more standardized variable name for this object. It may be something like `Window.Widget` as the Elements use or something like `Window.GUIWindow`. + +--- + ------------------ # ELEMENT AND FUNCTION CALL REFERENCE @@ -4801,60 +5072,6 @@ 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 @@ -4934,48 +5151,6 @@ 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 @@ -5021,30 +5196,6 @@ 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 @@ -5075,46 +5226,12 @@ 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 @@ -5176,36 +5293,6 @@ 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. @@ -5282,44 +5369,6 @@ 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! @@ -5389,44 +5438,6 @@ 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. @@ -5511,40 +5522,6 @@ 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 @@ -5905,6 +5882,8 @@ Parameter Descriptions: #### TKCanvas +#### property: TKCanvas + #### Update Changes some of the settings for the Graph Element. Must call `Window.Read` or `Window.Finalize` prior @@ -5924,34 +5903,6 @@ 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 @@ -6020,48 +5971,6 @@ 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 @@ -6125,49 +6034,6 @@ 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 @@ -6259,28 +6125,6 @@ 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 @@ -6330,52 +6174,6 @@ 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 @@ -6449,36 +6247,6 @@ 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 @@ -6531,31 +6299,15 @@ 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) -``` +#### Get -Parameter Descriptions: +Returns the current contents of the output. Similar to Get method other Elements + +`Get()` |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| +| **return** | (str) the current value of the output | #### SetFocus @@ -6587,6 +6339,8 @@ Parameter Descriptions: #### TKOut +#### property: TKOut + #### Update Changes some of the settings for the Output Element. Must call `Window.Read` or `Window.Finalize` prior @@ -6606,36 +6360,6 @@ 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 @@ -6682,36 +6406,6 @@ 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 @@ -6774,44 +6468,6 @@ 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) @@ -6880,52 +6536,6 @@ 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 @@ -6978,42 +6588,6 @@ 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. @@ -7078,42 +6652,6 @@ 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 @@ -7169,40 +6707,6 @@ 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. @@ -7288,42 +6792,6 @@ 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. @@ -7413,70 +6881,6 @@ 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 @@ -7533,44 +6937,6 @@ 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 @@ -7626,60 +6992,6 @@ 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 @@ -7738,12 +7050,6 @@ 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 @@ -7784,16 +7090,6 @@ 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 @@ -7826,82 +7122,6 @@ 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. @@ -7936,6 +7156,14 @@ 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 @@ -8438,6 +7666,14 @@ 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 @@ -9940,7 +9176,9 @@ There are too many to list!! There are over 170 sample programs to give you a jump start. -You will find Demo Programs located in a subfolder named "Demo Programs" under each of the PySimpleGUI ports on GitHub. +These programs are an integral part of the overall PySimpleGUI documentation and learning system. They will give you a headstart in a way you can learn from and understand. They also show you integration techiques to other packages that have been figured out for you. + +You will find Demo Programs located in a subfolder named "Demo Programs" under the top level and each of the PySimpleGUI ports on GitHub. Demo programs for plain PySimpleGUI (tkinter) https://github.com/PySimpleGUI/PySimpleGUI/tree/master/DemoPrograms @@ -9963,6 +9201,11 @@ There are not many programs under each of the port's folders because the main De * [Mido](https://github.com/olemb/mido) * [Matplotlib](https://matplotlib.org/) * [PyMuPDF](https://github.com/rk700/PyMuPDF) + * OpenCV + * pymunk + * psutil + * pygame + * Forecastio # Creating a Windows .EXE File @@ -10023,31 +9266,49 @@ For a fun time, add these lines to the top of your script ``` This will turn all of your print statements into prints that display in a window on your screen rather than to the terminal. -# Look and Feel (`ChangleLookAndFeel`) +# Look and Feel -While you can define colors for each individual element and you can even define some on a windows wide basis, but it requires setting a lot of different settings. -Dial in the look and feel that you like with the `SetOptions` function. You can change all of the defaults in one function call. One line of code to customize the entire GUI. -Or beginning in version 2.9 you can choose from a look and feel using pre-defined color schemes. Call ChangeLookAndFeel with a description string. +You can change defaults and colors of a large number of things in PySimpleGUI quite easily. + +## `ChangleLookAndFeel` + +Want a quick way of making your windows look a LOT better? Try calling `ChangeLookAndFeel`. It will, in a single call, set various color values to widgets, background, text, etc. + +Or dial in the look and feel (and a whole lot more) that you like with the `SetOptions` function. You can change all of the defaults in one function call. One line of code to customize the entire GUI. ```python sg.ChangeLookAndFeel('GreenTan') - ``` -Valid values for the description string are: +Valid look and feel values are currently: - GreenTan - LightGreen - BluePurple - Purple - BlueMono - GreenMono - BrownBlue - BrightColors - NeutralBlue - Kayak - SandyBeach - TealMono +```python +SystemDefault +Reddit +Topanga +GreenTan +Dark +LightGreen +Dark2 +Black +Tan +TanBlue +DarkTanBlue +DarkAmber +DarkBlue +Reds +Green +BluePurple +Purple +BlueMono +GreenMono +BrownBlue +BrightColors +NeutralBlue +Kayak +SandyBeach +TealMono +``` The way this call actually works is that it calls `SetOptions` with a LOT of color settings. Here is the actual call that's made. As you can see lots of stuff is defined for you. @@ -10067,7 +9328,7 @@ SetOptions(background_color=colors['BACKGROUND'], input_text_color=colors['TEXT_INPUT']) ``` -To see the latest list of color choices, take a look at the bottom of the `PySimpleGUI.py` file where you'll find the `ChangLookAndFeel` function. +To see the latest list of color choices you can call `ListOfLookAndFeelValues()` You can also combine the `ChangeLookAndFeel` function with the `SetOptions` function to quickly modify one of the canned color schemes. Maybe you like the colors but was more depth to your bezels. You can dial in exactly what you want. @@ -10095,19 +9356,40 @@ You'll quickly wonder how you ever coded without it. --- # Known Issues + +Well, there are a few quirks, and problems of course. Check the [GitHub Issues database](https://github.com/PySimpleGUI/PySimpleGUI/issues) for a list of them. + +As previously mentioned this is also where you should post all problems and enhancements. + +## MACS + tkinter = SUCKS + +Not sure why, but for over a year and a half, setting the color of buttons does not work on Macs. There have been numerous other problems. Checking the Issues database is the best place to see what they are. If there was a magic wand it would have been used long ago to fix these problems, but there does not appear to be a magic fix. + +This was already mentioned at the top of this document but want to make sure it's covered as a "known issue" + +## Multiple threads + While not an "issue" this is a ***stern warning*** ## **Do not attempt** to call `PySimpleGUI` from multiple threads! It's `tkinter` based and `tkinter` has issues with multiple threads -**Progress Meters** - the visual graphic portion of the meter may be off. May return to the native tkinter progress meter solution in the future. Right now a "custom" progress meter is used. On the bright side, the statistics shown are extremely accurate and can tell you something about the performance of your code. If you are running 2 or more progress meters at the same time using `OneLineProgressMeter`, you need to close the meter by using the "Cancel" button rather than the X +Tkinter also wants to be the MAIN thread in your code. So, if you have to run multiple threads, make sure the GUI is the main thread. -**Async windows** - these include the 'easy' windows (`OneLineProgressMeter` and EasyPrint/Print). If you start overlapping having Async windows open with normal windows then things get a littler squirrelly. Still tracking down the issues and am making it more solid every day possible. You'll know there's an issue when you see blank window. +Other than that, feel free to use threads with PySimpleGUI on all of the ports. You'll find a good example for how to run "long running tasks" in your event loop by looking at the demo program: `Demo_Multithreaded_Long_Tasks.py` -**EasyPrint** - EasyPrint is a new feature that's pretty awesome. You print and the output goes to a window, with a scroll bar, that you can copy and paste from. Being a new feature, it's got some potential problems. There are known interaction problems with other GUI windows. For example, closing a Print window can also close other windows you have open. For now, don't close your debug print window until other windows are closed too. +# Contributing -## Contributing +## Core Code -Core code pull requests are not being accepted at this time. +***Core code changes/pull requests are not being accepted at this time.*** + +## Demos + +You're welcome to share a PySimpleGUI program you've written that you think fits the model of a PySimpleGUI Demo Program. + +## GitHub Repos + +If you've created a GitHub for your project that uses PySimpleGUI then please submit it to be included in this document or on the PySimpleGUI GitHub site. Also, you'll find a lot more people will look at your code, explore your repo if you have posted **screen shots in your readme**. People *love* success stories and showing your GUI's screen shows you've been successful. Everyone wins! ## Versions |Version | Description | @@ -10914,7 +10196,7 @@ The PySimpleGUI Organization This documentation as well as all PySimpleGUI code is Copyright 2018, 2019 by PySimpleGUI.org -PySimpleGUI@PySimpleGUI.org +Send correspondance to PySimpleGUI@PySimpleGUI.com ## License diff --git a/readme.md b/readme.md index 3772a0af..1ccf0b5c 100644 --- a/readme.md +++ b/readme.md @@ -940,9 +940,11 @@ Here are some Python-friendly aspects to PySimpleGUI: #### Lofty Goals -> Change Python +> Teach GUI Programming to Beginners -The hope is **not** that ***this*** package will become part of the Python Standard Library. The hope is that Python will become ***the*** go-to language for creating GUI programs that run on Windows, Mac, and Linux *for all levels of developer*. Perhaps this sort of package is needed to make that happen. It would be nice if there was a "unified interface" for GUIs like PySimpleGUI presents, along with the vendor specific calls. +By and large PySimpleGUI is a "pattern based" SDK. Complete beginners can copy these standard design patterns or demo programs and modify them without necessarily understanding all of the nuts and bolts of what's happening. For example, they can modify a layout by adding elements even though they may not yet grasp the list of lists concept of layouts. + +Beginners certainly can add more `if event == 'my button':` statements to the event loop that they copied from the same design pattern. They will not have to write classes to use this package. > Capture Budding Graphic Designers & Non-Programmers @@ -1064,12 +1066,13 @@ When you type sg, Python will tell you the full patch to your PySimpleGUI file / ### Finding Out Where Your PySimpleGUI Is Coming From (from within your code) -If you continue to have troubles with getting the right version of PySimpleGUI loaded, THE ***definitive*** way to determine where your program is getting PySimpleGUI from is to add a print to your program. It's that *simple*! +If you continue to have troubles with getting the right version of PySimpleGUI loaded, THE ***definitive*** way to determine where your program is getting PySimpleGUI from is to add a print to your program. It's that *simple*! You can also get the version you are running by also printing ```python import PySimpleGUI as sg print(sg) +print(sg.version) ``` Just like when using the REPL >>> to determine the location, this `print` in your code will display the same path information. @@ -1081,6 +1084,7 @@ If you're not connected to the net on your target machine, or pip isn't working, Be ***sure*** that you delete this PySimpleGUI.py file if you install a newer pip version. Often the sequence of events is that a bug you've reported was fixed and checked into GitHub. You download the PySimpleGUI.py file (or the appropriately named one for your port) and put with your app. Then later your fix is posted with a new release on PyPI. You'll want to delete the GitHub one before you install from pip. ### Prerequisites + Python 2.7 or Python 3 tkinter @@ -1140,7 +1144,7 @@ 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. +***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. ### Python 3.7 @@ -1167,8 +1171,40 @@ else: This will automatically import the correct library based on the Python version number reported by the Python interpreter. +NOTE: It's 2019 and 2.7 support is being systematically removed. This construct will be removed from the demo programs shortly. 2.7 users can still run these demos, but they will need to change the import from PySimpleGUI to PySimpleGUI27. It save 4 lines of code and an import from sys in the process. + --- +# PEP8 Bindings For Methods and Functions + +Beginning with release 4.3 of PySimpleGUI, ***all methods and function calls*** have PEP8 equivalents. This capability is only available, for the moment, on the PySimpleGUI tkinter port. It is being added, as quickly as possible, to all of the ports. + +As long as you know you're sticking with tkinter for the short term, it's safe to use the new bindings. + +## The Non-PEP8 Methods and Functions + +Why the need for these bindings? Simply put, the PySimpleGUI SDK has a PEP8 violation in the method and function names. PySimpleGUI uses CamelCase names for methods and functions. PEP8 suggests using snake_case_variables instead. + +This has not caused any problems and few complaints, but it's important the the interfaces into PySimpleGUI be compliant. Perhaps one of the reasons for lack of complaints is that the Qt library also uses SnakeCase for its methods. This practice has the effect of labelling a package as being "not Pythonic" and also suggests that ths package was originally used in another language and then ported to Python. This is exactly the situation with Qt. It was written for C++ and the interfaces continue to use C++ conventions. + +***PySimpleGUI was written in Python, for Python.*** The reason for the name problem was one of ignorance. The PEP8 convention wasn't understood by the developers when PySimpleGUI was designed and implemented. + +You can, and will be able to for some time, use both names. However, at some point in the future, the CamelCase names will disappear. A utility is planned to do the conversion for the developer when the old names are remove from PySimpleGUI. + +The help system will work with both names as will your IDE's docstring viewing. However, the result found will show the CamelCase names. For example `help(sg.Window.read)` will show the CamelCase name of the method/function. This is what will be returned: + +`Read(self, timeout=None, timeout_key='__TIMEOUT__')` + +## The Renaming Convention + +To convert a CamelCase method/function name to snake_case, you simply place an `_` where the Upper Case letter is located. If there are none, then only the first letter is changed. + +`Window.FindElement` becomes `Window.find_element` + +## Class Variables + +For the time being, class variables will remain the way they are currently. It is unusual, in PySimpleGUI, for class variables to be modified or read by the user code so the impact of leaving them is rarely seen in your code. + # High Level API Calls - Popup's "High level calls" are those that start with "Popup". They are the most basic form of communications with the user. They are named after the type of window they create, a pop-up window. These windows are meant to be short lived while, either delivering information or collecting it, and then quickly disappearing. @@ -2275,6 +2311,40 @@ If your window has no keys and it has no buttons that are "browse" type of butto Note in the list of return values in this example, many of the keys are numbers. That's because no keys were specified on any of the elements (although one was automatically made for you). If you don't specify a key for your element, then a number will be sequentially assigned. For elements that you don't plan on modifying or reading values from, like a Text Element, you can skip adding keys. For other elements, you'll likely want to add keys so that you can easily access the values and perform operations on them. +### Operations That Take a "Long Time" + +If you're a Windows user you've seen windows show in their title bar "Not Responding" which is soon followed by a Windows popop stating that "Your program has stopped responding". Well, you too can make that message and popup appear if you so wish! All you need to do is execute an operation that takes "too long" (i.e. a few seconds) inside your event loop. + +You have a couple of options for dealing this with. If your operation can be broken up into smaller parts, then you can call `Window.Refresh()` occassionally to avoid this message. If you're running a loop for example, drop that call in with your other work. This will keep the GUI happy and Window's won't complain. + +If, on the other hand, your operation is not under your control or you are unable to add `Refresh` calls, then the next option available to you is to move your long operations into a thread. + +There are a couple of demo programs available for you to see how to do this. You basically put your work into a thread. When the thread is completed, it tells the GUI by sending a message through a queue. The event loop will run with a timer set to a value that represents how "responsive" you want your GUI to be to the work completing. + +These 2 demo programs are called +```python +Demo_Threaded_Work.py - Best documented. Single thread used for long task +Demo_Multithreaded_Long_Tasks.py - Similar to above, but with less fancy GUI. Allows you to set amount of time +``` + +These 2 particular demos have a LOT of comments showing you where to add your code, etc. The amount of code to do this is actually quite small and you don't need to understand the mechanisms used if you simply follow the demo that's been prepared for you. + +### Multitheaded Programs + +While on the topic of multiple threads, another demo was prepared that shows how you can run multiple threads in your program that all communicate with the event loop in order to display something in the GUI window. Recall that for PySimpleGUI (at least the tkinter port) you cannot make PySimpleGUI calls in threads other than the main program thread. + +The key to these threaded programs is communication from the threads to your event loop. The mechanism chosen for these demonstrations uses the Python built-in `queue` module. The event loop polls these queues to see if something has been sent over from one of the threads to be displayed. + +You'll find the demo that shows multiple threads communicating with a single GUI is called: + +```python +Demo_Multithreaded_Queued.py +``` + +Once again a **warning** is in order for plain PySimpleGUI (tkinter based) - your GUI must never run as anything but the main program thread and no threads can directly call PySimpleGUI calls. + +--- + # Building Custom Windows You will find it ***much easier*** to write code using PySimpleGUI if you use an IDE such as ***PyCharm***. The features that show you documentation about the API call you are making will help you determine which settings you want to change, if any. In PyCharm, two commands are particularly helpful. @@ -2282,8 +2352,10 @@ You will find it ***much easier*** to write code using PySimpleGUI if you use an Control-Q (when cursor is on function name) brings up a box with the function definition Control-P (when cursor inside function call "()") shows a list of parameters and their default values -## Synchronous windows +## Synchronous / Asynchronous Windows + The most common use of PySimpleGUI is to display and collect information from the user. The most straightforward way to do this is using a "blocking" GUI call. Execution is "blocked" while waiting for the user to close the GUI window/dialog box. + You've already seen a number of examples above that use blocking windows. You'll know it blocks if the `Read` call has no timeout parameter. A blocking Read (one that waits until an event happens) look like this: @@ -2304,7 +2376,7 @@ You can learn more about these async / non-blocking windows toward the end of th The first step is to create the window object using the desired window customizations. -**IMPORTANT** - Many of the `Window` methods require you to either call `Window.Read` or `Window.Finalize` before you call the method. This is because these 2 calls are what actually creates the window using the underlying GUI Framework. Prior to one of those calls, the methods are likely to crash as they will not yet have their underlying widgets created. +**IMPORTANT** - Many of the `Window` methods require you to either call `Window.Read` or `Window.Finalize` (or set `finalize=True` in your `Window` call) before you call the method. This is because these 2 calls are what actually creates the window using the underlying GUI Framework. Prior to one of those calls, the methods are likely to crash as they will not yet have their underlying widgets created. ### Window Location @@ -2418,7 +2490,7 @@ Call to set the window layout. Must be called prior to `Read`. Most likely "ch window = sg.Window('My window title', layout) ``` -#### Finalize() +#### `Finalize()` or `Window` parameter `finalize=True` Call to force a window to go through the final stages of initialization. This will cause the tkinter resources to be allocated so that they can then be modified. This also causes your window to appear. If you do not want your window to appear when Finalize is called, then set the Alpha to 0 in your window's creation parameters. @@ -2436,6 +2508,8 @@ If you set the timeout = 0, then the Read will immediately return rather than wa While at this point in the documentation you've not been shown very much about each Element available, you should read this section carefully as you can use the techniques you learn in here to build better, shorter, and easier to understand PySimpleGUI code. +If it feels like this layout section is too much too soon, then come back to this section after you're learned about each Element. **Whatever order you find the least confusing is the best.** + While you've not learned about Elements yet, it makes sense for this section to be up front so that you'll have learned how to use the elements prior to learning how each element works. At this point in your PySimpleGUI education, it is better for you to grasp time efficient ways of working with Elements than what each Element does. By learning now how to assemble Elements now, you'll have a good model to put the elements you learn into. There are *several* aspects of PySimpleGUI that make it more "Pythonic" than other Python GUI SDKs. One of the areas that is unique to PySimpleGUI is how a window's "layout" is defined, specified or built. A window's "layout" is simply a list of lists of elements. As you've already learned, these lists combine to form a complete window. This method of defining a window is super-powerful because lists are core to the Python language as a whole and thus are very easy to create and manupulate. @@ -2450,7 +2524,7 @@ Many times your window definition / layout will be a static, straightforward to However, window layouts are not limited to being one of these staticly defined list of Elements. -# Generated Layouts (Please read especially if your GUI has more than 10 Elements) +# Generated Layouts (For sure want to read if you have > 5 repeating elements/rows) There are 5 specific techniques of generating layouts discussed in this section. They can be used alone or in combination with each other. @@ -2808,6 +2882,7 @@ You will find information on Elements and all other classes and functions are lo - StatusBar - Pane - Stretch (Qt only) +- Sizer (plain PySimpleGUI only) ## Common Element Parameters @@ -2945,6 +3020,58 @@ layout = [ --- +## `Window.FindElement(key)` Shortcut `Window[key]` + +There's been a fantastic leap forward in making PySimpleGUI code more compact. + +Instead of writing: +```python +window.FindElement(key).Update(new_value) + ``` + +You can now write it as: + +```python +window[key].Update(new_value) + ``` + +This change has been released to PyPI for PySimpleGUI +It **has not yet been released to PyPI** for the other ports of PySimpleGUI (Qt, Wx, Web). You'll find the change on GitHub however for Qt and Web (still working on Wx). + +MANY Thanks is owed to the person that suggested and showed me how to do this. It's an incredible find. + +## `Element.Update()` Shortcut `Element()` + +This has to be one of the strangest syntactical contructs I've ever written. + +It is best used in combination with `FindElement` (see prior section on how to shortcut `FindElement`). When used with the `FindElement` shortcut, the code to update an element can be shortened to this unusual looking call: + +```python +window[key](new_value) +``` + +Yes, that's a valid statement in Python. + +It is confusing looking however so when used, it might be a good idea to write a comment at the end of the statement to help out the poor beginner programmer coming along behind you. + +Still debating whether to begin to immediately use this for all demos going forward and also if should go back and change the docs and demo programs, essentially removing the other technique for doing an update. + +It does not have to be used in conjuction with `FindElement`. The call works on any previously made Element. Sometimes elements are created, stored into a variable and then that variable is used in the layout. For example. + +```python +graph_element = sg.Graph(...... lots of parms ......) + +layout = [[graph_element]] +. +. +. +graph_element(background_color='blue') # this calls Graph.Update for the previously defined element +``` + +Hopefully this isn't too confusing. Note that the methods these shortcuts replace will not be removed. You can continue to use the old constructs without changes. + +--- + ### Fonts Already discussed in the common parameters section. Either string or a tuple. @@ -3034,6 +3161,8 @@ layout = [[sg.Slider(range=(1,500), There is an important difference between Qt and tkinter sliders. On Qt, the slider values must be integer, not float. If you want your slider to go from 0.1 to 1.0, then make your slider go from 1 to 10 and divide by 10. It's an easy math thing to do and not a big deal. Just deal with it.... you're writing software after all. Presumably you know how to do these things. ;-) +## Radio Button Element + Creates one radio button that is assigned to a group of radio buttons. Only 1 of the buttons in the group can be selected at any one time. ```python @@ -3147,7 +3276,7 @@ layout = [[sg.Ok(), sg.Cancel()]] In reality `Button` is in fact being called on your behalf. Behind the scenes, `sg.Ok` and `sg.Cancel` call `Button` with the text set to `Ok` and `Cancel` and returning the results that then go into the layout. If you were to print the layout it will look identical to the first layout shown that has `Button` shown specifically in the layout. -### Shortcut, Pre-defined Buttons +### Button Element Shortcuts These Pre-made buttons are some of the most important elements of all because they are used so much. They all basically do the same thing, **set the button text to match the function name and set the parameters to commonly used values**. If you find yourself needing to create a custom button often because it's not on this list, please post a request on GitHub. . They include: - OK @@ -3379,6 +3508,7 @@ One use of this element is to make a "fake menu bar" that has a colored backgrou Return values for ButtonMenus are sent via the return values dictionary. If a selection is made, then an event is generated that will equal the ButtonMenu's key value. Use that key value to look up the value selected by the user. This is the same mechanism as the Menu Bar Element, but differs from the pop-up (right click) menu. ## VerticalSeparator Element + This element has limited usefulness and is being included more for completeness than anything else. It will draw a line between elements. It works best when placed between columns or elements that span multiple rows. If on a "normal" row with elements that are only 1 row high, then it will only span that one row. @@ -3389,6 +3519,16 @@ VerticalSeparator(pad=None) ![snag-0129](https://user-images.githubusercontent.com/13696193/47376041-a92a0100-d6bf-11e8-8f5b-0c0df56cf0f3.jpg) +## HorizontalSeparator Element + +In PySimpleGUI, the tkinter port, there is no `HorizontalSeparator` Element. One will be added as a "stub" so that code is portable. It will likely do nothing just like the `Stretch` Element. + +An easy way to get a horizontal line in PySimpleGUI is to use a `Text` Element that contains a line of underscores + +```python +sg.Text('_'*30) # make a horizontal line stretching 30 characters +``` + ## ProgressBar Element The `ProgressBar` element is used to build custom Progress Bar windows. It is HIGHLY recommended that you use OneLineProgressMeter that provides a complete progress meter solution for you. Progress Meters are not easy to work with because the windows have to be non-blocking and they are tricky to debug. @@ -3479,16 +3619,16 @@ ChatBot() Starting in version 2.9 you'll be able to do more complex layouts by using the Column Element. Think of a Column as a window within a window. And, yes, you can have a Column within a Column if you want. -Columns are specified in exactly the same way as a window is, as a list of lists. +Columns are specified, like all "container elements", in exactly the same way as a window, as a list of lists. -Columns are needed when you have an element that has a height > 1 line on the left, with single-line elements on the right. Here's an example of this kind of layout: +Columns are needed when you want to specify more than 1 element in a single row. + +For example, this layout has a single slider element that spans several rows followed by 7 `Text` and `Input` elements on the same row. ![column](https://user-images.githubusercontent.com/13696193/44959988-66b92480-aec5-11e8-9c26-316ed24a68c0.jpg) Without a Column Element you can't create a layout like this. But with it, you should be able to closely match any layout created using tkinter only. ---- - ```python import PySimpleGUI as sg @@ -3514,14 +3654,42 @@ layout = [[sg.Slider(range=(1,100), default_value=10, orientation='v', size=(8,2 [sg.OK()]] # Display the window and get values -# If you're willing to not use the "context manager" design pattern, then it's possible -# to collapse the window display and read down to a single line of code. -event, values = sg.Window('Compact 1-line window with column', layout).Read() + +window = sg.Window('Compact 1-line window with column', layout) +event, values = window.Read() +window.Close() sg.Popup(event, values, line_width=200) ``` +### Column Justification + +Beginning in Release 4.3 you can justify the `Column` element's row by setting the `Column`'s `justification` parameter. + +You can also justify the entire contents within a `Column` by using the Column's `element_justification` parameter. + +With these parameter's it is possible to create windows that have their contents centered. Previously this was very difficult to do. + +This is currently only available in the primary PySimpleGUI port. + +They can also be used to justify a group of elements in a particular way. + +Placing `Column` elements inside `Columns` elements make it possible to create a multitude of + +## Sizer Element + +New in 4.3 is the `Sizer` Element. This element is used to help create a container of a particular size. It can be placed inside of these PySimpleGUI items: + +* Column +* Frame +* Tab +* Window + +The implementation of a `Sizer` is quite simple. It returns an empty `Column` element that has a pad value set to the values passed into the `Sizer`. Thus isn't not a class but rather a "Shortcut function" similar to the pre-defined Buttons. + +This feature is only available in the tkinter port of PySimpleGUI at the moment. A cross port is needed. + ---- ## Frame Element (Labelled Frames, Frames with a title) @@ -3667,16 +3835,23 @@ graph+UP {'graph': (154, 254)} ## Table Element -Out of all of the Elements, it's the Table and the Tree that are the most "problematic" in the tkinter inter and Qt implementations. They're hard is my only defense. +Out of all of the Elements, it's the Table and the Tree that are the most "problematic" in the tkinter inter and Qt implementations. They have been difficult implementation. (yea.... get of over it) -### Read return values from Table Element +### `window.Read()` return values from Table Element The values returned from a `Window.Read` call for the Table Element are a list of row numbers that are currently highlighted. ---- -### Known visualization problem.... +### The Qt `Table.Get()` call -If you click on the header, it can go into spasms for some tables. I don't understand what's causing it and it's been there evidently since the first release of Tables. +New in **PySimpleGUIQt** is the addition of the `Table` method `Get`. This method returns the table that is currently being shown in the GUI. This method was required in order to obtain any edits the user may have made to the table. + +For the tkinter port, it will return the same values that was passed in when the table was created because tkinter Tables cannot be modified by the user (please file an Issue if you know a way). + +### Known `Table` visualization problem.... + +There has been an elusive problem where clicking on or near the table's header caused tkinter to go crazy and resize the columns continuously as you moved the mouse. + +This problem has existed since the first release of the `Table` element. It was fixed in release 4.3. ## Tree Element @@ -4785,6 +4960,102 @@ Exception module 'tkinter' has no attribute '__version__' ``` --- +# Extending PySimpleGUI + +PySimpleGUI doesn't and can't provide every single setting available in the underlying GUI framework. Not all tkinter options are available for a `Text` Element. Same with PySimpleGUIQt and the other ports. + +There are a few of reasons for this. + +1. Time & resource limits - The size of the PySimpleGUI development team is extremely small +2. PySimpleGUI provides a "Unified API". This means the code is, in theory, portable across all of the PySimpleGUI ports without chaning the user's code (except for the import) +3. PySimpleGUI is meant, by design, to be simple and cover 80% of the GUI problems. + +However, PySimpleGUI programs are ***not*** dead ends!! Writing PySimpleGUI code and then getting to a point where you really really feel like you need to extend the Listbox to include the ability to change the "Selected" color. Maybe that's super-critical to your project. And maybe you find out late that the base PySimpleGUI code doesn't expose that tkinter capability. Fear not! The road does continue!! + +## Widget Access + +Most of the user extensions / enhancements are at the "Element" level. You want some Element to do a trick that you cannot do using the existing PySimpleGUI APIs. It's just not possible. What to do? + +What you need is access to the underlying GUI framework's "Widget". The good news is that you HAVE that access ready and waiting for you, for all of the ports of PySimpleGUI, not just the tkinter one. + +### `Element.Widget` is The GUI Widget + +The class variable `Widget` contains the tkinter, Qt, WxPython, or Remi widget. With that variable you can modify that widget directly. + +***You must first `Read` or `Finalize` the window before accessing the `Widget` class variable*** + +The reason for the Finalize requirement is that until a Window is Read or is Finalized it is not actually created and populated with GUI Widgets. The GUI Widgets are created when you do these 2 operations. + +Side note - You can stop using the `.Finalize()` call added onto your window creation and instead use the `finalize` parameter in the `Window` call. + +OLD WAY: +```python +window = sg.Window('Window Title', layout).Finalize() + +``` + +THE NEW WAY: +```python +window = sg.Window('Window Title', layout, finalize=True) + +``` + +It's cleaner and less confusing for beginners who aren't necessarily trained in how chaining calls work. Py**Simple**GUI. + +### Example Use of `Element.Widget` + +So far there have been 2 uses of this capability. One already mentioned is adding a new capability. The other way it's been used has been to fix a bug or make a workaround for a quirky behavior. + +A recent Issue posted was that focus was always being set on a button in a tab when you switch tabs in tkinter. The user didn't want this to happen as it was putting an ugly black line around their nicely made graphical button. + +There is no current way in PySimpleGUI to "disable focus" on an Element. That's essentially what was needed, the ability to tell tkinter that this widget should never get focus. + +There is a way to tell tkinter that a widget should not get focus. The downside is that if you use your tab key to navigate, that element will never get focus. So, it's not only blocking focus for this automatic problem, but blocking it for all uses. Of course you can still click on the button. + +The way through for this user was to modify the tkinter widget directly and tell it not to get focus. This was done in a single line of code: + +```python +window[button_key].Widget.config(takefocus=0) +``` + +The absolute beauty to this solution is that tkinter does NOT need to be imported into the user's program for this statement to run. Python already know what kind of object `.Widget` is and can thus show you the various methods and class variables for that object. Most all tkinter options are strings so you don't need to import tkinter to get any enums. + +### Finding Your Element's Widget Type + +Of course, in order to call the methods or access the object's class variables, you need to know the type of the underlying Widget being used. This document could list them all, but the downside is the widget could change types (not a good thing for people using the .Widget already!). It also saves space and time in getting this documentation published and available to you. + +So, here's the way to get your element's widget's type: + +```python + print(type(window[your_element_key].Widget)) +``` + +In the case of the button example above, what is printed is: + +`` + +I don't think that could be any clearer. Your job at this point is to look at the tkinter documentation to see what the methods are for the tkinter `Button` widget. + +## Window Level Access + +For this one you'll need some specific variables for the time being as there is no `Window` class variable that holds the window's representation in the GUI library being used. + +For tkinter, at the moment, the window's root object is this: + +```python +sg.Window.TKroot +``` + +The type will vary in PySimpleGUI. It will either be: +`tkinter.Tk()` +`tkinter.Toplevel()` + +Either way you'll access it using the same `Window` variable `sg.Window.TKroot` + +Watch this space in the future for the more standardized variable name for this object. It may be something like `Window.Widget` as the Elements use or something like `Window.GUIWindow`. + +--- + ------------------ # ELEMENT AND FUNCTION CALL REFERENCE @@ -4801,60 +5072,6 @@ 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 @@ -4934,48 +5151,6 @@ 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 @@ -5021,30 +5196,6 @@ 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 @@ -5075,46 +5226,12 @@ 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 @@ -5176,36 +5293,6 @@ 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. @@ -5282,44 +5369,6 @@ 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! @@ -5389,44 +5438,6 @@ 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. @@ -5511,40 +5522,6 @@ 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 @@ -5905,6 +5882,8 @@ Parameter Descriptions: #### TKCanvas +#### property: TKCanvas + #### Update Changes some of the settings for the Graph Element. Must call `Window.Read` or `Window.Finalize` prior @@ -5924,34 +5903,6 @@ 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 @@ -6020,48 +5971,6 @@ 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 @@ -6125,49 +6034,6 @@ 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 @@ -6259,28 +6125,6 @@ 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 @@ -6330,52 +6174,6 @@ 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 @@ -6449,36 +6247,6 @@ 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 @@ -6531,31 +6299,15 @@ 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) -``` +#### Get -Parameter Descriptions: +Returns the current contents of the output. Similar to Get method other Elements + +`Get()` |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| +| **return** | (str) the current value of the output | #### SetFocus @@ -6587,6 +6339,8 @@ Parameter Descriptions: #### TKOut +#### property: TKOut + #### Update Changes some of the settings for the Output Element. Must call `Window.Read` or `Window.Finalize` prior @@ -6606,36 +6360,6 @@ 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 @@ -6682,36 +6406,6 @@ 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 @@ -6774,44 +6468,6 @@ 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) @@ -6880,52 +6536,6 @@ 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 @@ -6978,42 +6588,6 @@ 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. @@ -7078,42 +6652,6 @@ 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 @@ -7169,40 +6707,6 @@ 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. @@ -7288,42 +6792,6 @@ 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. @@ -7413,70 +6881,6 @@ 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 @@ -7533,44 +6937,6 @@ 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 @@ -7626,60 +6992,6 @@ 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 @@ -7738,12 +7050,6 @@ 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 @@ -7784,16 +7090,6 @@ 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 @@ -7826,82 +7122,6 @@ 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. @@ -7936,6 +7156,14 @@ 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 @@ -8438,6 +7666,14 @@ 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 @@ -9940,7 +9176,9 @@ There are too many to list!! There are over 170 sample programs to give you a jump start. -You will find Demo Programs located in a subfolder named "Demo Programs" under each of the PySimpleGUI ports on GitHub. +These programs are an integral part of the overall PySimpleGUI documentation and learning system. They will give you a headstart in a way you can learn from and understand. They also show you integration techiques to other packages that have been figured out for you. + +You will find Demo Programs located in a subfolder named "Demo Programs" under the top level and each of the PySimpleGUI ports on GitHub. Demo programs for plain PySimpleGUI (tkinter) https://github.com/PySimpleGUI/PySimpleGUI/tree/master/DemoPrograms @@ -9963,6 +9201,11 @@ There are not many programs under each of the port's folders because the main De * [Mido](https://github.com/olemb/mido) * [Matplotlib](https://matplotlib.org/) * [PyMuPDF](https://github.com/rk700/PyMuPDF) + * OpenCV + * pymunk + * psutil + * pygame + * Forecastio # Creating a Windows .EXE File @@ -10023,31 +9266,49 @@ For a fun time, add these lines to the top of your script ``` This will turn all of your print statements into prints that display in a window on your screen rather than to the terminal. -# Look and Feel (`ChangleLookAndFeel`) +# Look and Feel -While you can define colors for each individual element and you can even define some on a windows wide basis, but it requires setting a lot of different settings. -Dial in the look and feel that you like with the `SetOptions` function. You can change all of the defaults in one function call. One line of code to customize the entire GUI. -Or beginning in version 2.9 you can choose from a look and feel using pre-defined color schemes. Call ChangeLookAndFeel with a description string. +You can change defaults and colors of a large number of things in PySimpleGUI quite easily. + +## `ChangleLookAndFeel` + +Want a quick way of making your windows look a LOT better? Try calling `ChangeLookAndFeel`. It will, in a single call, set various color values to widgets, background, text, etc. + +Or dial in the look and feel (and a whole lot more) that you like with the `SetOptions` function. You can change all of the defaults in one function call. One line of code to customize the entire GUI. ```python sg.ChangeLookAndFeel('GreenTan') - ``` -Valid values for the description string are: +Valid look and feel values are currently: - GreenTan - LightGreen - BluePurple - Purple - BlueMono - GreenMono - BrownBlue - BrightColors - NeutralBlue - Kayak - SandyBeach - TealMono +```python +SystemDefault +Reddit +Topanga +GreenTan +Dark +LightGreen +Dark2 +Black +Tan +TanBlue +DarkTanBlue +DarkAmber +DarkBlue +Reds +Green +BluePurple +Purple +BlueMono +GreenMono +BrownBlue +BrightColors +NeutralBlue +Kayak +SandyBeach +TealMono +``` The way this call actually works is that it calls `SetOptions` with a LOT of color settings. Here is the actual call that's made. As you can see lots of stuff is defined for you. @@ -10067,7 +9328,7 @@ SetOptions(background_color=colors['BACKGROUND'], input_text_color=colors['TEXT_INPUT']) ``` -To see the latest list of color choices, take a look at the bottom of the `PySimpleGUI.py` file where you'll find the `ChangLookAndFeel` function. +To see the latest list of color choices you can call `ListOfLookAndFeelValues()` You can also combine the `ChangeLookAndFeel` function with the `SetOptions` function to quickly modify one of the canned color schemes. Maybe you like the colors but was more depth to your bezels. You can dial in exactly what you want. @@ -10095,19 +9356,40 @@ You'll quickly wonder how you ever coded without it. --- # Known Issues + +Well, there are a few quirks, and problems of course. Check the [GitHub Issues database](https://github.com/PySimpleGUI/PySimpleGUI/issues) for a list of them. + +As previously mentioned this is also where you should post all problems and enhancements. + +## MACS + tkinter = SUCKS + +Not sure why, but for over a year and a half, setting the color of buttons does not work on Macs. There have been numerous other problems. Checking the Issues database is the best place to see what they are. If there was a magic wand it would have been used long ago to fix these problems, but there does not appear to be a magic fix. + +This was already mentioned at the top of this document but want to make sure it's covered as a "known issue" + +## Multiple threads + While not an "issue" this is a ***stern warning*** ## **Do not attempt** to call `PySimpleGUI` from multiple threads! It's `tkinter` based and `tkinter` has issues with multiple threads -**Progress Meters** - the visual graphic portion of the meter may be off. May return to the native tkinter progress meter solution in the future. Right now a "custom" progress meter is used. On the bright side, the statistics shown are extremely accurate and can tell you something about the performance of your code. If you are running 2 or more progress meters at the same time using `OneLineProgressMeter`, you need to close the meter by using the "Cancel" button rather than the X +Tkinter also wants to be the MAIN thread in your code. So, if you have to run multiple threads, make sure the GUI is the main thread. -**Async windows** - these include the 'easy' windows (`OneLineProgressMeter` and EasyPrint/Print). If you start overlapping having Async windows open with normal windows then things get a littler squirrelly. Still tracking down the issues and am making it more solid every day possible. You'll know there's an issue when you see blank window. +Other than that, feel free to use threads with PySimpleGUI on all of the ports. You'll find a good example for how to run "long running tasks" in your event loop by looking at the demo program: `Demo_Multithreaded_Long_Tasks.py` -**EasyPrint** - EasyPrint is a new feature that's pretty awesome. You print and the output goes to a window, with a scroll bar, that you can copy and paste from. Being a new feature, it's got some potential problems. There are known interaction problems with other GUI windows. For example, closing a Print window can also close other windows you have open. For now, don't close your debug print window until other windows are closed too. +# Contributing -## Contributing +## Core Code -Core code pull requests are not being accepted at this time. +***Core code changes/pull requests are not being accepted at this time.*** + +## Demos + +You're welcome to share a PySimpleGUI program you've written that you think fits the model of a PySimpleGUI Demo Program. + +## GitHub Repos + +If you've created a GitHub for your project that uses PySimpleGUI then please submit it to be included in this document or on the PySimpleGUI GitHub site. Also, you'll find a lot more people will look at your code, explore your repo if you have posted **screen shots in your readme**. People *love* success stories and showing your GUI's screen shows you've been successful. Everyone wins! ## Versions |Version | Description | @@ -10914,7 +10196,7 @@ The PySimpleGUI Organization This documentation as well as all PySimpleGUI code is Copyright 2018, 2019 by PySimpleGUI.org -PySimpleGUI@PySimpleGUI.org +Send correspondance to PySimpleGUI@PySimpleGUI.com ## License