From d6458df5abb99d97a4b4437fb309e88a6fc593c8 Mon Sep 17 00:00:00 2001 From: MikeTheWatchGuy Date: Mon, 5 Aug 2019 16:58:20 -0400 Subject: [PATCH] More documentation... specifically on the Graph Element (plus others) --- PySimpleGUI.py | 15 +- docs/index.md | 394 ++++++++++++++++++++++++++++++++----------------- readme.md | 394 ++++++++++++++++++++++++++++++++----------------- 3 files changed, 519 insertions(+), 284 deletions(-) diff --git a/PySimpleGUI.py b/PySimpleGUI.py index 0d5569cd..b4f630d1 100644 --- a/PySimpleGUI.py +++ b/PySimpleGUI.py @@ -1,5 +1,5 @@ #!/usr/bin/python3 -version = __version__ = "4.2.0.0 Unreleased" +version = __version__ = "4.2.0.1 Unreleased" # 888888ba .d88888b oo dP .88888. dP dP dP @@ -10852,10 +10852,9 @@ class _Debugger(): def show_debugger_window(location=(None, None), *args): """ - - :param location: - :param *args: - + Shows the large main debugger window + :param location: Tuple[int, int] Locations (x,y) on the screen to place upper left corner of the window + :param *args: Not used """ if _Debugger.debugger is None: _Debugger.debugger = _Debugger() @@ -10876,10 +10875,10 @@ def show_debugger_window(location=(None, None), *args): def show_debugger_popout_window(location=(None, None), *args): """ + Shows the smaller "popout" window. Default location is the upper right corner of your screen - :param location: - :param *args: - + :param location: Tuple[int, int] Locations (x,y) on the screen to place upper left corner of the window + :param *args: Not used """ if _Debugger.debugger is None: _Debugger.debugger = _Debugger() diff --git a/docs/index.md b/docs/index.md index 94611712..5c90b09e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -77,7 +77,7 @@ "I've been pretty amazed at how much more intuitive it is than raw tk/qt. The dude developing it is super active on the project too so if you come across situations that you just can't get the code to do what you want you can make bug/enhancement issues that are almost assured to get a meaningful response." -"This library is the easiest way of gui programming in python! I'm totally in love with it ❤️" +"This library is the easiest way of gui programming in python! I'm totally in love with it️" "Wow that readme is extensive and great." (hear the love for docs often) @@ -4985,9 +4985,11 @@ TKCanvas - not a method but a property. Returns the tkinter Canvas Widget ## Graph Element -All you math fans will enjoy this Element... and all you non-math fans will enjoy it too. +All you math fans will enjoy this Element... and all you non-math fans will enjoy it even more. -I've found nothing to be less fun than dealing with a graphic's coordinate system from a GUI Framework. It's always upside down from what I want. (0,0) is in the upper left hand corner. In short, it's a **pain in the ass**. +I've found nothing to be less fun than dealing with a graphic's coordinate system from a GUI Framework. It's always upside down from what I want. (0,0) is in the upper left hand corner.... sometimes... or was it in the lower left? In short, it's a **pain in the ass**. + +How about the ability to get your own location of (0,0) and then using those coordinates instead of what tkinter provides? This results in a very powerful capability - working in your own units, and then displaying them in an area defined in pixels. If you've ever been frustrated with where (0,0) is located on some surface you draw on, then fear not, your frustration ends right here. You get to draw using whatever coordinate system you want. Place (0,0) anywhere you want, including not anywhere on your Graph. You could define a Graph that's all negative numbers between -2.1 and -3.5 in the X axis and -3 to -8.2 in the Y axis @@ -5010,7 +5012,39 @@ You can move your figures around on the canvas by supplying the Figure ID the ** graph.MoveFigure(my_circle, 10, 10) -This Element is relatively new and may have some parameter additions or deletions. It shouldn't break your code however. +You'll also use this ID to delete individual figures you've drawn: +```python +graph.DeleteFigure(my_circle) +``` + +### Mouse Events Inside Graph Elements + +If you have eneabled events for your Graph Element, then you can receive mouse click events. If you additionally enable `drag_submits` in your creation of the Graph Element, then you will also get events when you "DRAG" inside of a window. A "Drag" is defined as a left button down and then the mouse is moved. + +When a drag event happens, the event will be the Graph Element's key. The `value` returned in the values dictionary is a tuple of the (x,y) location of the mouse currently. + +This means you'll get a "stream" of events. If the mouse moves, you'll get at LEAST 1 and likely a lot more than 1 event. + +### Mouse Up Event for Drags + +When you've got `drag_submits` enabled, there's a sticky situation that arises.... what happens when you're done dragging and you've let go of the mouse button? How is the "Mouse Up" event relayed back to your code. + +The "Mouse Up" will generate an event to you with the value: `Graph_key` + `'+UP'`. Thus, if your Graph Element has a key of `'_GRAPH_'`, then the event you will receive when the mouse button is released is: `'_GRAPH_+UP'` + +Yea, it's a little weird, but it works. It's SIMPLE too. I recommend using the `.startswith` and `.endswith` built-ins when dealing with these kinds of string values. + +Here is an example of the `events` and the `values dictionary` that was generated by clicking and dragging inside of a Graph Element with the key == 'graph': + +``` +graph {'graph': (159, 256)} +graph {'graph': (157, 256)} +graph {'graph': (157, 256)} +graph {'graph': (157, 254)} +graph {'graph': (157, 254)} +graph {'graph': (154, 254)} +graph {'graph': (154, 254)} +graph+UP {'graph': (154, 254)} +``` Creates an area for you to draw on. The MAGICAL property this Element has is that you interact with the element using your own coordinate system. This is an important point!! YOU define where the location @@ -5060,83 +5094,21 @@ Parameter Descriptions: All of the Drawing methods return a "***figure***" that can be used move and delete the drawn figure. -Draws a line from one point to another point using USER'S coordinates. Can set the color and width of line +#### DeleteFigure + +Remove from the Graph the figure represented by id. The id is given to you anytime you call a drawing primitive ``` -DrawLine(point_from, - point_to, - color="black", - width=1) +DeleteFigure(id) ``` Parameter Descriptions: |Name|Meaning| |---|---| -|point_from|Union[Tuple[int, int], Tuple[float, float]] Starting point for line| -|point_to|Union[Tuple[int, int], Tuple[float, float]] Ending point for line| -|color|(str) Color of the line| -|width|(int) width of line in pixels| -||| -| **return** | Union[int, None] id returned from tktiner or None if user closed the window. id is used when you
want to manipulate the line | +|id|(int) the id returned to you when calling one of the drawing methods| -Draws a "dot" at the point you specify using the USER'S coordinate system - -``` -DrawPoint(point, - size=2, - color="black") -``` - -Parameter Descriptions: - -|Name|Meaning| -|---|---| -|point|Union [Tuple[int, int], Tuple[float, float]] Center location using USER'S coordinate system| -|size|Union[int, float] Radius? (Or is it the diameter?) in user's coordinate values.| -|color|(str) color of the point to draw| -||| -| **return** | Union[int, None] id returned from tkinter that you'll need if you want to manipulate the point | - -Draws a circle, cenetered at the location provided. Can set the fill and outline colors - -``` -DrawCircle(center_location, - radius, - fill_color=None, - line_color="black") -``` - -Parameter Descriptions: - -|Name|Meaning| -|---|---| -|center_location|Union [Tuple[int, int], Tuple[float, float]] Center location using USER'S coordinate system| -|radius|Union[int, float] Radius in user's coordinate values.| -|fill_color|(str) color of the point to draw| -|line_color|(str) color of the outer line that goes around the circle (sorry, can't set thickness)| -||| -| **return** | Union[int, None] id returned from tkinter that you'll need if you want to manipulate the circle | - -Draws an oval based on coordinates in user coordinate system. Provide the location of a "bounding rectangle" - -``` -DrawOval(top_left, - bottom_right, - fill_color=None, - line_color=None) -``` - -Parameter Descriptions: - -|Name|Meaning| -|---|---| -|top_left|Union[Tuple[int, int], Tuple[float, float]] the top left point of bounding rectangle| -|bottom_right|Union[Tuple[int, int], Tuple[float, float]] the bottom right point of bounding rectangle| -|fill_color|(str) color of the interrior| -|line_color|(str) color of outline of oval| -||| -| **return** | Union[int, None] id returned from tkinter that you'll need if you want to manipulate the oval | +#### DrawArc Draws different types of arcs. Uses a "bounding box" to define location @@ -5162,49 +5134,29 @@ Parameter Descriptions: ||| | **return** | Union[int, None] id returned from tkinter that you'll need if you want to manipulate the arc | -Draw a rectangle given 2 points. Can control the line and fill colors +#### DrawCircle + +Draws a circle, cenetered at the location provided. Can set the fill and outline colors ``` -DrawRectangle(top_left, - bottom_right, +DrawCircle(center_location, + radius, fill_color=None, - line_color=None) + line_color="black") ``` Parameter Descriptions: |Name|Meaning| |---|---| -|top_left|Union[Tuple[int, int], Tuple[float, float]] the top left point of rectangle| -|bottom_right|Union[Tuple[int, int], Tuple[float, float]] the bottom right point of rectangle| -|fill_color|(str) color of the interior| -|line_color|(str) color of outline| +|center_location|Union [Tuple[int, int], Tuple[float, float]] Center location using USER'S coordinate system| +|radius|Union[int, float] Radius in user's coordinate values.| +|fill_color|(str) color of the point to draw| +|line_color|(str) color of the outer line that goes around the circle (sorry, can't set thickness)| ||| -| **return** | Union[int, None] id returned from tkinter that you'll need if you want to manipulate the rectangle | +| **return** | Union[int, None] id returned from tkinter that you'll need if you want to manipulate the circle | -Draw some text on your graph. This is how you label graph number lines for example - -``` -DrawText(text, - location, - color="black", - font=None, - angle=0, - text_location="center") -``` - -Parameter Descriptions: - -|Name|Meaning| -|---|---| -|text|(str) text to display| -|location|Union[Tuple[int, int], Tuple[float, float]] location to place first letter| -|color|(str) text color| -|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| -|angle|(float) Angle 0 to 360 to draw the text. Zero represents horizontal text| -|text_location|(enum) "anchor" location for the text. Values start with TEXT_LOCATION_| -||| -| **return** | Union[int, None] id returned from tkinter that you'll need if you want to manipulate the text | +#### DrawImage Places an image onto your canvas. It's a really important method for this element as it enables so much @@ -5230,36 +5182,127 @@ Parameter Descriptions: ||| | **return** | Union[int, None] id returned from tkinter that you'll need if you want to manipulate the image | +#### DrawLine + +Draws a line from one point to another point using USER'S coordinates. Can set the color and width of line + +``` +DrawLine(point_from, + point_to, + color="black", + width=1) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|point_from|Union[Tuple[int, int], Tuple[float, float]] Starting point for line| +|point_to|Union[Tuple[int, int], Tuple[float, float]] Ending point for line| +|color|(str) Color of the line| +|width|(int) width of line in pixels| +||| +| **return** | Union[int, None] id returned from tktiner or None if user closed the window. id is used when you
want to manipulate the line | + +#### DrawOval + +Draws an oval based on coordinates in user coordinate system. Provide the location of a "bounding rectangle" + +``` +DrawOval(top_left, + bottom_right, + fill_color=None, + line_color=None) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|top_left|Union[Tuple[int, int], Tuple[float, float]] the top left point of bounding rectangle| +|bottom_right|Union[Tuple[int, int], Tuple[float, float]] the bottom right point of bounding rectangle| +|fill_color|(str) color of the interrior| +|line_color|(str) color of outline of oval| +||| +| **return** | Union[int, None] id returned from tkinter that you'll need if you want to manipulate the oval | + +#### DrawPoint + +Draws a "dot" at the point you specify using the USER'S coordinate system + +``` +DrawPoint(point, + size=2, + color="black") +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|point|Union [Tuple[int, int], Tuple[float, float]] Center location using USER'S coordinate system| +|size|Union[int, float] Radius? (Or is it the diameter?) in user's coordinate values.| +|color|(str) color of the point to draw| +||| +| **return** | Union[int, None] id returned from tkinter that you'll need if you want to manipulate the point | + +#### DrawRectangle + +Draw a rectangle given 2 points. Can control the line and fill colors + +``` +DrawRectangle(top_left, + bottom_right, + fill_color=None, + line_color=None) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|top_left|Union[Tuple[int, int], Tuple[float, float]] the top left point of rectangle| +|bottom_right|Union[Tuple[int, int], Tuple[float, float]] the bottom right point of rectangle| +|fill_color|(str) color of the interior| +|line_color|(str) color of outline| +||| +| **return** | Union[int, None] id returned from tkinter that you'll need if you want to manipulate the rectangle | + +#### DrawText + +Draw some text on your graph. This is how you label graph number lines for example + +``` +DrawText(text, + location, + color="black", + font=None, + angle=0, + text_location="center") +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|text|(str) text to display| +|location|Union[Tuple[int, int], Tuple[float, float]] location to place first letter| +|color|(str) text color| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|angle|(float) Angle 0 to 360 to draw the text. Zero represents horizontal text| +|text_location|(enum) "anchor" location for the text. Values start with TEXT_LOCATION_| +||| +| **return** | Union[int, None] id returned from tkinter that you'll need if you want to manipulate the text | + +#### Erase + Erase the Graph - Removes all figures previously "drawn" using the Graph methods (e.g. DrawText) ```python Erase() ``` -Remove from the Graph the figure represented by id. The id is given to you anytime you call a drawing primitive - -``` -DeleteFigure(id) -``` - -Parameter Descriptions: - -|Name|Meaning| -|---|---| -|id|(int) the id returned to you when calling one of the drawing methods| - -Changes some of the settings for the Graph Element. Must call `Window.Read` or `Window.Finalize` prior - -``` -Update(background_color=None, visible=None) -``` - -Parameter Descriptions: - -|Name|Meaning| -|---|---| -|background_color|color of background| -|visible|(bool) control visibility of element| +#### Move Moves the entire drawing area (the canvas) by some delta from the current position. Units are indicated in your coordinate system indicated number of ticks in your coordinate system @@ -5274,6 +5317,8 @@ Parameter Descriptions: |x_direction|Union[int, float] how far to move in the "X" direction in your coordinates| |y_direction|Union[int, float] how far to move in the "Y" direction in your coordinates| +#### MoveFigure + Moves a previously drawn figure using a "delta" from current position ``` @@ -5290,6 +5335,8 @@ Parameter Descriptions: |x_direction|Union[int, float] delta to apply to position in the X direction| |y_direction|Union[int, float] delta to apply to position in the Y direction| +#### RelocateFigure + Move a previously made figure to an arbitrary (x,y) location. This differs from the Move methods because it uses absolute coordinates versus relative for Move @@ -5307,6 +5354,49 @@ Parameter Descriptions: |x|Union[int, float] location on X axis (in user coords) to move the upper left corner of the figure| |y|Union[int, float] location on Y axis (in user coords) to move the upper left corner of the figure| +#### SetFocus + +Sets the current focus to be on this Graph Element + +``` +SetFocus(force=False) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|force|(bool) if True will call focus_force otherwise calls focus_set| + +#### SetTooltip + +Called by application to change the tooltip text for an Element. Normally invoked using the Element Object such as: window.Element('key').SetToolTip('New tip'). + +``` +SetTooltip(tooltip_text) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|tooltip_text|(str) the text to show in tooltip.| + +#### Update + +Changes some of the settings for the Graph Element. Must call `Window.Read` or `Window.Finalize` prior + +``` +Update(background_color=None, visible=None) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|background_color|color of background| +|visible|(bool) control visibility of element| + ## 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. @@ -6586,11 +6676,47 @@ while True: break ``` +--- + +# The PySimpleGUI Debugger + +Starting on June 1, 2019, a built-in version of the debugger `imwatchingyou` has been shipping in every copy of PySimpleGUI. It's been largely downplayed to gauge whether or not the added code and the added feature and the use of a couple of keys, would mess up any users. + +So far no one has reported anything at all about the debugger. The assumption is that it is quietly lying dormant, waiting for you to press the `BREAK` or `CONTROL` + `BREAK` keys. It's odd no one has accidently done this and freaked out, logging an Issue. + +The plain PySimpleGUI module has a debugger builtin. For the other ports, please use the package `imwatchingyou`. + +## Preparing To Run the Debugger + +If your program is running with blocking `Read` calls, then you will want to add a timeout to your reads. This is because the debugger gets it's cycles by stealing a little bit of time from these async calls. + +Your event loop will be modified from this: +```python +while True: + event, values = window.Read() +``` + +To this: +```python +while True: + event, values = window.Read(timeout=100) + if event == sg.TIMEOUT_KEY: + continue +``` + +This event loop will do nothing at all if a timeout occurs and will execute your normal code (that follows the if statement) when there is any event that is not a timeout. + +This timeout value of 100 means that your debugger GUI will be updated 10 times a second. If this adds too much "drag" to your application, you can make the timeout larger. Try using 1000 instead of 100. + +## Debugger Windows + +There are 2 debugger windows. One is called a "Popout". The Popout window displays all of your variables + # "Demo Programs" Applications There are too many to list!! -There are over 130 sample programs to give you a jump start. +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. @@ -6608,14 +6734,6 @@ https://github.com/PySimpleGUI/PySimpleGUI/tree/master/PySimpleGUIWeb/Demo%20Pro There are not many programs under each of the port's folders because the main Demo Programs should run on all of the other platforms with minimal changes (often only the import statement changes). -## Start Here - -When you are just beginning to build your application, or to design it, look through the Demo Programs first to see if there is a program written that does what you're looking for. If so, then this program could be a good starting point. Copy it and modify it to your liking. - -Even if no program perfectly matches your situation, there are still a good number of example uses of Elements or techniques that are demonstrated. - -Maybe you're going to write a program that uses the Graph Element. In addition to reading the documentaion about the Graph Element, check to see if there's a Demo Program that uses it. At the moment there are 7 Demo programs that match "Demo_Graph_*.py" - ## Packages Used In Demos While the core PySimpleGUI code does not utilize any 3rd party packages, some of the demos do. They add a GUI to a few popular packages. These packages include: @@ -6749,7 +6867,7 @@ While not an "issue" this is a ***stern warning*** ## Contributing -A MikeTheWatchGuy production... entirely responsible for this code.... unless it causes you trouble in which case I'm not at all responsible. +Core code pull requests are not being accepted at this time. ## Versions |Version | Description | diff --git a/readme.md b/readme.md index 94611712..5c90b09e 100644 --- a/readme.md +++ b/readme.md @@ -77,7 +77,7 @@ "I've been pretty amazed at how much more intuitive it is than raw tk/qt. The dude developing it is super active on the project too so if you come across situations that you just can't get the code to do what you want you can make bug/enhancement issues that are almost assured to get a meaningful response." -"This library is the easiest way of gui programming in python! I'm totally in love with it ❤️" +"This library is the easiest way of gui programming in python! I'm totally in love with it️" "Wow that readme is extensive and great." (hear the love for docs often) @@ -4985,9 +4985,11 @@ TKCanvas - not a method but a property. Returns the tkinter Canvas Widget ## Graph Element -All you math fans will enjoy this Element... and all you non-math fans will enjoy it too. +All you math fans will enjoy this Element... and all you non-math fans will enjoy it even more. -I've found nothing to be less fun than dealing with a graphic's coordinate system from a GUI Framework. It's always upside down from what I want. (0,0) is in the upper left hand corner. In short, it's a **pain in the ass**. +I've found nothing to be less fun than dealing with a graphic's coordinate system from a GUI Framework. It's always upside down from what I want. (0,0) is in the upper left hand corner.... sometimes... or was it in the lower left? In short, it's a **pain in the ass**. + +How about the ability to get your own location of (0,0) and then using those coordinates instead of what tkinter provides? This results in a very powerful capability - working in your own units, and then displaying them in an area defined in pixels. If you've ever been frustrated with where (0,0) is located on some surface you draw on, then fear not, your frustration ends right here. You get to draw using whatever coordinate system you want. Place (0,0) anywhere you want, including not anywhere on your Graph. You could define a Graph that's all negative numbers between -2.1 and -3.5 in the X axis and -3 to -8.2 in the Y axis @@ -5010,7 +5012,39 @@ You can move your figures around on the canvas by supplying the Figure ID the ** graph.MoveFigure(my_circle, 10, 10) -This Element is relatively new and may have some parameter additions or deletions. It shouldn't break your code however. +You'll also use this ID to delete individual figures you've drawn: +```python +graph.DeleteFigure(my_circle) +``` + +### Mouse Events Inside Graph Elements + +If you have eneabled events for your Graph Element, then you can receive mouse click events. If you additionally enable `drag_submits` in your creation of the Graph Element, then you will also get events when you "DRAG" inside of a window. A "Drag" is defined as a left button down and then the mouse is moved. + +When a drag event happens, the event will be the Graph Element's key. The `value` returned in the values dictionary is a tuple of the (x,y) location of the mouse currently. + +This means you'll get a "stream" of events. If the mouse moves, you'll get at LEAST 1 and likely a lot more than 1 event. + +### Mouse Up Event for Drags + +When you've got `drag_submits` enabled, there's a sticky situation that arises.... what happens when you're done dragging and you've let go of the mouse button? How is the "Mouse Up" event relayed back to your code. + +The "Mouse Up" will generate an event to you with the value: `Graph_key` + `'+UP'`. Thus, if your Graph Element has a key of `'_GRAPH_'`, then the event you will receive when the mouse button is released is: `'_GRAPH_+UP'` + +Yea, it's a little weird, but it works. It's SIMPLE too. I recommend using the `.startswith` and `.endswith` built-ins when dealing with these kinds of string values. + +Here is an example of the `events` and the `values dictionary` that was generated by clicking and dragging inside of a Graph Element with the key == 'graph': + +``` +graph {'graph': (159, 256)} +graph {'graph': (157, 256)} +graph {'graph': (157, 256)} +graph {'graph': (157, 254)} +graph {'graph': (157, 254)} +graph {'graph': (154, 254)} +graph {'graph': (154, 254)} +graph+UP {'graph': (154, 254)} +``` Creates an area for you to draw on. The MAGICAL property this Element has is that you interact with the element using your own coordinate system. This is an important point!! YOU define where the location @@ -5060,83 +5094,21 @@ Parameter Descriptions: All of the Drawing methods return a "***figure***" that can be used move and delete the drawn figure. -Draws a line from one point to another point using USER'S coordinates. Can set the color and width of line +#### DeleteFigure + +Remove from the Graph the figure represented by id. The id is given to you anytime you call a drawing primitive ``` -DrawLine(point_from, - point_to, - color="black", - width=1) +DeleteFigure(id) ``` Parameter Descriptions: |Name|Meaning| |---|---| -|point_from|Union[Tuple[int, int], Tuple[float, float]] Starting point for line| -|point_to|Union[Tuple[int, int], Tuple[float, float]] Ending point for line| -|color|(str) Color of the line| -|width|(int) width of line in pixels| -||| -| **return** | Union[int, None] id returned from tktiner or None if user closed the window. id is used when you
want to manipulate the line | +|id|(int) the id returned to you when calling one of the drawing methods| -Draws a "dot" at the point you specify using the USER'S coordinate system - -``` -DrawPoint(point, - size=2, - color="black") -``` - -Parameter Descriptions: - -|Name|Meaning| -|---|---| -|point|Union [Tuple[int, int], Tuple[float, float]] Center location using USER'S coordinate system| -|size|Union[int, float] Radius? (Or is it the diameter?) in user's coordinate values.| -|color|(str) color of the point to draw| -||| -| **return** | Union[int, None] id returned from tkinter that you'll need if you want to manipulate the point | - -Draws a circle, cenetered at the location provided. Can set the fill and outline colors - -``` -DrawCircle(center_location, - radius, - fill_color=None, - line_color="black") -``` - -Parameter Descriptions: - -|Name|Meaning| -|---|---| -|center_location|Union [Tuple[int, int], Tuple[float, float]] Center location using USER'S coordinate system| -|radius|Union[int, float] Radius in user's coordinate values.| -|fill_color|(str) color of the point to draw| -|line_color|(str) color of the outer line that goes around the circle (sorry, can't set thickness)| -||| -| **return** | Union[int, None] id returned from tkinter that you'll need if you want to manipulate the circle | - -Draws an oval based on coordinates in user coordinate system. Provide the location of a "bounding rectangle" - -``` -DrawOval(top_left, - bottom_right, - fill_color=None, - line_color=None) -``` - -Parameter Descriptions: - -|Name|Meaning| -|---|---| -|top_left|Union[Tuple[int, int], Tuple[float, float]] the top left point of bounding rectangle| -|bottom_right|Union[Tuple[int, int], Tuple[float, float]] the bottom right point of bounding rectangle| -|fill_color|(str) color of the interrior| -|line_color|(str) color of outline of oval| -||| -| **return** | Union[int, None] id returned from tkinter that you'll need if you want to manipulate the oval | +#### DrawArc Draws different types of arcs. Uses a "bounding box" to define location @@ -5162,49 +5134,29 @@ Parameter Descriptions: ||| | **return** | Union[int, None] id returned from tkinter that you'll need if you want to manipulate the arc | -Draw a rectangle given 2 points. Can control the line and fill colors +#### DrawCircle + +Draws a circle, cenetered at the location provided. Can set the fill and outline colors ``` -DrawRectangle(top_left, - bottom_right, +DrawCircle(center_location, + radius, fill_color=None, - line_color=None) + line_color="black") ``` Parameter Descriptions: |Name|Meaning| |---|---| -|top_left|Union[Tuple[int, int], Tuple[float, float]] the top left point of rectangle| -|bottom_right|Union[Tuple[int, int], Tuple[float, float]] the bottom right point of rectangle| -|fill_color|(str) color of the interior| -|line_color|(str) color of outline| +|center_location|Union [Tuple[int, int], Tuple[float, float]] Center location using USER'S coordinate system| +|radius|Union[int, float] Radius in user's coordinate values.| +|fill_color|(str) color of the point to draw| +|line_color|(str) color of the outer line that goes around the circle (sorry, can't set thickness)| ||| -| **return** | Union[int, None] id returned from tkinter that you'll need if you want to manipulate the rectangle | +| **return** | Union[int, None] id returned from tkinter that you'll need if you want to manipulate the circle | -Draw some text on your graph. This is how you label graph number lines for example - -``` -DrawText(text, - location, - color="black", - font=None, - angle=0, - text_location="center") -``` - -Parameter Descriptions: - -|Name|Meaning| -|---|---| -|text|(str) text to display| -|location|Union[Tuple[int, int], Tuple[float, float]] location to place first letter| -|color|(str) text color| -|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| -|angle|(float) Angle 0 to 360 to draw the text. Zero represents horizontal text| -|text_location|(enum) "anchor" location for the text. Values start with TEXT_LOCATION_| -||| -| **return** | Union[int, None] id returned from tkinter that you'll need if you want to manipulate the text | +#### DrawImage Places an image onto your canvas. It's a really important method for this element as it enables so much @@ -5230,36 +5182,127 @@ Parameter Descriptions: ||| | **return** | Union[int, None] id returned from tkinter that you'll need if you want to manipulate the image | +#### DrawLine + +Draws a line from one point to another point using USER'S coordinates. Can set the color and width of line + +``` +DrawLine(point_from, + point_to, + color="black", + width=1) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|point_from|Union[Tuple[int, int], Tuple[float, float]] Starting point for line| +|point_to|Union[Tuple[int, int], Tuple[float, float]] Ending point for line| +|color|(str) Color of the line| +|width|(int) width of line in pixels| +||| +| **return** | Union[int, None] id returned from tktiner or None if user closed the window. id is used when you
want to manipulate the line | + +#### DrawOval + +Draws an oval based on coordinates in user coordinate system. Provide the location of a "bounding rectangle" + +``` +DrawOval(top_left, + bottom_right, + fill_color=None, + line_color=None) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|top_left|Union[Tuple[int, int], Tuple[float, float]] the top left point of bounding rectangle| +|bottom_right|Union[Tuple[int, int], Tuple[float, float]] the bottom right point of bounding rectangle| +|fill_color|(str) color of the interrior| +|line_color|(str) color of outline of oval| +||| +| **return** | Union[int, None] id returned from tkinter that you'll need if you want to manipulate the oval | + +#### DrawPoint + +Draws a "dot" at the point you specify using the USER'S coordinate system + +``` +DrawPoint(point, + size=2, + color="black") +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|point|Union [Tuple[int, int], Tuple[float, float]] Center location using USER'S coordinate system| +|size|Union[int, float] Radius? (Or is it the diameter?) in user's coordinate values.| +|color|(str) color of the point to draw| +||| +| **return** | Union[int, None] id returned from tkinter that you'll need if you want to manipulate the point | + +#### DrawRectangle + +Draw a rectangle given 2 points. Can control the line and fill colors + +``` +DrawRectangle(top_left, + bottom_right, + fill_color=None, + line_color=None) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|top_left|Union[Tuple[int, int], Tuple[float, float]] the top left point of rectangle| +|bottom_right|Union[Tuple[int, int], Tuple[float, float]] the bottom right point of rectangle| +|fill_color|(str) color of the interior| +|line_color|(str) color of outline| +||| +| **return** | Union[int, None] id returned from tkinter that you'll need if you want to manipulate the rectangle | + +#### DrawText + +Draw some text on your graph. This is how you label graph number lines for example + +``` +DrawText(text, + location, + color="black", + font=None, + angle=0, + text_location="center") +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|text|(str) text to display| +|location|Union[Tuple[int, int], Tuple[float, float]] location to place first letter| +|color|(str) text color| +|font|Union[str, Tuple[str, int]] specifies the font family, size, etc| +|angle|(float) Angle 0 to 360 to draw the text. Zero represents horizontal text| +|text_location|(enum) "anchor" location for the text. Values start with TEXT_LOCATION_| +||| +| **return** | Union[int, None] id returned from tkinter that you'll need if you want to manipulate the text | + +#### Erase + Erase the Graph - Removes all figures previously "drawn" using the Graph methods (e.g. DrawText) ```python Erase() ``` -Remove from the Graph the figure represented by id. The id is given to you anytime you call a drawing primitive - -``` -DeleteFigure(id) -``` - -Parameter Descriptions: - -|Name|Meaning| -|---|---| -|id|(int) the id returned to you when calling one of the drawing methods| - -Changes some of the settings for the Graph Element. Must call `Window.Read` or `Window.Finalize` prior - -``` -Update(background_color=None, visible=None) -``` - -Parameter Descriptions: - -|Name|Meaning| -|---|---| -|background_color|color of background| -|visible|(bool) control visibility of element| +#### Move Moves the entire drawing area (the canvas) by some delta from the current position. Units are indicated in your coordinate system indicated number of ticks in your coordinate system @@ -5274,6 +5317,8 @@ Parameter Descriptions: |x_direction|Union[int, float] how far to move in the "X" direction in your coordinates| |y_direction|Union[int, float] how far to move in the "Y" direction in your coordinates| +#### MoveFigure + Moves a previously drawn figure using a "delta" from current position ``` @@ -5290,6 +5335,8 @@ Parameter Descriptions: |x_direction|Union[int, float] delta to apply to position in the X direction| |y_direction|Union[int, float] delta to apply to position in the Y direction| +#### RelocateFigure + Move a previously made figure to an arbitrary (x,y) location. This differs from the Move methods because it uses absolute coordinates versus relative for Move @@ -5307,6 +5354,49 @@ Parameter Descriptions: |x|Union[int, float] location on X axis (in user coords) to move the upper left corner of the figure| |y|Union[int, float] location on Y axis (in user coords) to move the upper left corner of the figure| +#### SetFocus + +Sets the current focus to be on this Graph Element + +``` +SetFocus(force=False) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|force|(bool) if True will call focus_force otherwise calls focus_set| + +#### SetTooltip + +Called by application to change the tooltip text for an Element. Normally invoked using the Element Object such as: window.Element('key').SetToolTip('New tip'). + +``` +SetTooltip(tooltip_text) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|tooltip_text|(str) the text to show in tooltip.| + +#### Update + +Changes some of the settings for the Graph Element. Must call `Window.Read` or `Window.Finalize` prior + +``` +Update(background_color=None, visible=None) +``` + +Parameter Descriptions: + +|Name|Meaning| +|---|---| +|background_color|color of background| +|visible|(bool) control visibility of element| + ## 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. @@ -6586,11 +6676,47 @@ while True: break ``` +--- + +# The PySimpleGUI Debugger + +Starting on June 1, 2019, a built-in version of the debugger `imwatchingyou` has been shipping in every copy of PySimpleGUI. It's been largely downplayed to gauge whether or not the added code and the added feature and the use of a couple of keys, would mess up any users. + +So far no one has reported anything at all about the debugger. The assumption is that it is quietly lying dormant, waiting for you to press the `BREAK` or `CONTROL` + `BREAK` keys. It's odd no one has accidently done this and freaked out, logging an Issue. + +The plain PySimpleGUI module has a debugger builtin. For the other ports, please use the package `imwatchingyou`. + +## Preparing To Run the Debugger + +If your program is running with blocking `Read` calls, then you will want to add a timeout to your reads. This is because the debugger gets it's cycles by stealing a little bit of time from these async calls. + +Your event loop will be modified from this: +```python +while True: + event, values = window.Read() +``` + +To this: +```python +while True: + event, values = window.Read(timeout=100) + if event == sg.TIMEOUT_KEY: + continue +``` + +This event loop will do nothing at all if a timeout occurs and will execute your normal code (that follows the if statement) when there is any event that is not a timeout. + +This timeout value of 100 means that your debugger GUI will be updated 10 times a second. If this adds too much "drag" to your application, you can make the timeout larger. Try using 1000 instead of 100. + +## Debugger Windows + +There are 2 debugger windows. One is called a "Popout". The Popout window displays all of your variables + # "Demo Programs" Applications There are too many to list!! -There are over 130 sample programs to give you a jump start. +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. @@ -6608,14 +6734,6 @@ https://github.com/PySimpleGUI/PySimpleGUI/tree/master/PySimpleGUIWeb/Demo%20Pro There are not many programs under each of the port's folders because the main Demo Programs should run on all of the other platforms with minimal changes (often only the import statement changes). -## Start Here - -When you are just beginning to build your application, or to design it, look through the Demo Programs first to see if there is a program written that does what you're looking for. If so, then this program could be a good starting point. Copy it and modify it to your liking. - -Even if no program perfectly matches your situation, there are still a good number of example uses of Elements or techniques that are demonstrated. - -Maybe you're going to write a program that uses the Graph Element. In addition to reading the documentaion about the Graph Element, check to see if there's a Demo Program that uses it. At the moment there are 7 Demo programs that match "Demo_Graph_*.py" - ## Packages Used In Demos While the core PySimpleGUI code does not utilize any 3rd party packages, some of the demos do. They add a GUI to a few popular packages. These packages include: @@ -6749,7 +6867,7 @@ While not an "issue" this is a ***stern warning*** ## Contributing -A MikeTheWatchGuy production... entirely responsible for this code.... unless it causes you trouble in which case I'm not at all responsible. +Core code pull requests are not being accepted at this time. ## Versions |Version | Description |