Button
Button documentation
PreDefinedButtons call reference
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,
default_extension = "",
disabled = False,
change_submits = False,
enable_events = False,
image_filename = None,
image_data = None,
image_size = (None, None),
image_subsample = None,
image_zoom = None,
image_source = None,
border_width = None,
size = (None, None),
s = (None, None),
auto_size_button = None,
button_color = None,
disabled_button_color = None,
highlight_colors = None,
mouseover_colors = (None, None),
use_ttk_buttons = None,
font = None,
bind_return_key = False,
focus = False,
pad = None,
p = None,
key = None,
k = None,
right_click_menu = None,
expand_x = False,
expand_y = False,
visible = True,
metadata = None
)
Parameter Descriptions
| Name | Type | Default | Description |
|---|---|---|---|
| auto_size_button | bool | None | if True the button size is sized to fit the text |
| bind_return_key | bool | False | If True then pressing the return key in an Input or Multiline Element will cause this button to appear to be clicked (generates event with this button's key |
| border_width | int | None | width of border around button in pixels |
| button_color | (str, str) or str | None | Color of button. default is from theme or the window. Easy to remember which is which if you say "ON" between colors. "red" on "green". Normally a tuple, but can be a simplified-button-color-string "foreground on background". Can be a single color if want to set only the background. |
| button_text | str | Text to be displayed on the button | |
| button_type | int | 7 | You should NOT be setting this directly. ONLY the shortcut functions set this |
| change_submits | bool | False | DO NOT USE. Only listed for backwards compat - Use enable_events instead |
| default_extension | str | If no extension entered by user, add this to filename (only used in saveas dialogs) | |
| disabled | (bool or str) | False | If True button will be created disabled. If BUTTON_DISABLED_MEANS_IGNORE then the button will be ignored rather than disabled using tkinter |
| disabled_button_color | (str, str) or str | None | colors to use when button is disabled (text, background). Use None for a color if don't want to change. Only ttk buttons support both text and background colors. tk buttons only support changing text color |
| enable_events | bool | False | Turns on the element specific events. If this button is a target, should it generate an event when filled in |
| expand_x | bool | False | If True the element will automatically expand in the X direction to fill available space |
| expand_y | bool | False | If True the element will automatically expand in the Y direction to fill available space |
| file_types | Tuple[(str, str), ...] | (('ALL Files', '. *'),) | the filetypes that will be used to match files. To indicate all files: (("ALL Files", ". *"),). |
| focus | bool | False | if True, initial focus will be put on this button |
| font | (str or (str, int[, str]) or None) | None | specifies the font family, size, etc. Tuple or Single string format 'name size styles'. Styles: italic * roman bold normal underline overstrike |
| highlight_colors | (str, str) | None | colors to use when button has focus (has focus, does not have focus). None will use colors based on theme. Only used by Linux and only for non-TTK button |
| image_data | bytes or str | None | Raw or Base64 representation of the image to put on button. Choose either filename or data |
| image_filename | str | None | image filename if there is a button image. GIFs and PNGs only. |
| image_size | (int, int) | (None, None) | Size of the image in pixels (width, height) |
| image_source | (str or bytes) | None | Image to place on button. Use INSTEAD of the image_filename and image_data. Unifies these into 1 easier to use parm |
| image_subsample | int | None | amount to reduce the size of the image. Divides the size by this number. 2=1/2, 3=1/3, 4=1/4, etc |
| image_zoom | int | None | amount to increase the size of the image. 2=twice size, 3=3 times, etc |
| initial_folder | str | None | starting path for folders and files |
| k | str or int or tuple or object | None | Same as the Key. You can use either k or key. Which ever is set will be used. |
| key | str or int or tuple or object | None | Used with window.find_element and with return values to uniquely identify this element to uniquely identify this element |
| metadata | Any | None | User metadata that can be set to ANYTHING |
| mouseover_colors | (str, str) or str | (None, None) | Important difference between Linux & Windows! Linux - Colors when mouse moved over button. Windows - colors when button is pressed. The default is to switch the text and background colors (an inverse effect) |
| p | (int, int or (int, int),(int,int) or int,(int,int)) or ((int, int),int) or int | None | Same as pad parameter. It's an alias. If EITHER of them are set, then the one that's set will be used. If BOTH are set, pad will be used |
| pad | (int, int or (int, int),(int,int) or int,(int,int)) or ((int, int),int) or int | None | Amount of padding to put around element in pixels (left/right, top/bottom) or ((left, right), (top, bottom)) or an int. If an int, then it's converted into a tuple (int, int) |
| right_click_menu | List[List[ List[str] or str ]] | None | A list of lists of Menu items to show when this element is right clicked. See user docs for exact format. |
| s | (int or None, int or None) or (None, None) or int | (None, None) | Same as size parameter. It's an alias. If EITHER of them are set, then the one that's set will be used. If BOTH are set, size will be used |
| size | (int or None, int or None) or (None, None) or int | (None, None) | (w, h) w=characters-wide, h=rows-high. If an int instead of a tuple is supplied, then height is auto-set to 1 |
| target | str or (int, int) | (None, None) | 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 | None | text, that will appear when mouse hovers over the element |
| use_ttk_buttons | bool | None | True = use ttk buttons. False = do not use ttk buttons. None (Default) = use ttk buttons only if on a Mac and not with button images |
| visible | bool | True | set visibility state of the element |
Class Properties
key
Returns key for the element. This is a READONLY property. Keys can be any hashable object (basically anything except a list... tuples are ok, but not lists)
Parameter Descriptions| Name | Type | Default | Description |
|---|---|---|---|
| RETURN | Any | The window's Key |
metadata
Metadata is an Element property that you can use at any time to hold any value
Parameter Descriptions| Name | Type | Default | Description |
|---|---|---|---|
| RETURN | Any | the current metadata value |
visible
Returns visibility state for the element. This is a READONLY property
Parameter Descriptions| Name | Type | Default | Description |
|---|---|---|---|
| RETURN | bool | Visibility state for element |
widget
Returns tkinter widget for the element. This is a READONLY property. The implementation is that the Widget member variable is returned. This is a backward compatible addition
Parameter Descriptions| Name | Type | Default | Description |
|---|---|---|---|
| RETURN | (tkinter.Widget) | The element's underlying tkinter widget |
Class Methods
def bind
def block_focus
def click
def expand
def get_next_focus
def get_previous_focus
def get_size
def get_text
def grab_anywhere_exclude
def grab_anywhere_include
def hide_row
def remove_tooltip
def save_element_screenshot_to_disk
def set_cursor
def set_focus
def set_hscroll_position
def set_right_click_menu
def set_size
def set_tooltip
def set_vscroll_position
def unbind
def unhide_row
def update
bind
Used to add tkinter events to an Element. The tkinter specific data is in the Element's member variable user_bind_event
Parameter Descriptions
| Name | Type | Default | Description |
|---|---|---|---|
| bind_string | str | The string tkinter expected in its bind function | |
| key_modifier | str | Additional data to be added to the element's key when event is returned | |
| propagate | bool | True | If True then tkinter will be told to propagate the event to the element |
block_focus
Enable or disable the element from getting focus by using the keyboard. If the block parameter is True, then this element will not be given focus by using the keyboard to go from one element to another. You CAN click on the element and utilize it.
Parameter Descriptions
| Name | Type | Default | Description |
|---|---|---|---|
| block | bool | True | if True the element will not get focus via the keyboard |
click
Generates a click of the button as if the user clicked the button Calls the tkinter invoke method for the button
expand
Causes the Element to expand to fill available space in the X and Y directions. Can specify which or both directions
Parameter Descriptions
| Name | Type | Default | Description |
|---|---|---|---|
| expand_row | bool | True | If True the row containing the element will also expand. Without this your element is "trapped" within the row |
| expand_x | bool | False | If True Element will expand in the Horizontal directions |
| expand_y | bool | False | If True Element will expand in the Vertical directions |
get_next_focus
Gets the next element that should get focus after this element.
Parameter Descriptions
| Name | Type | Default | Description |
|---|---|---|---|
| RETURN | Element | Element that will get focus after this one |
get_previous_focus
Gets the element that should get focus previous to this element.
Parameter Descriptions
| Name | Type | Default | Description |
|---|---|---|---|
| RETURN | Element | Element that should get the focus before this one |
get_size
Return the size of an element in Pixels. Care must be taken as some elements use characters to specify their size but will return pixels when calling this get_size method.
Parameter Descriptions
| Name | Type | Default | Description |
|---|---|---|---|
| RETURN | (int, int) | width and height of the element |
get_text
Returns the current text shown on a button
Parameter Descriptions
| Name | Type | Default | Description |
|---|---|---|---|
| RETURN | str | The text currently displayed on the button |
grab_anywhere_exclude
Excludes this element from being used by the grab_anywhere feature Handy for elements like a Graph element when dragging is enabled. You want the Graph element to get the drag events instead of the window dragging.
grab_anywhere_include
Includes this element in the grab_anywhere feature This will allow you to make a Multline element drag a window for example
hide_row
Hide the entire row an Element is located on. Use this if you must have all space removed when you are hiding an element, including the row container
remove_tooltip
Removes a previiously created tooltip for an element
save_element_screenshot_to_disk
Saves an image of the PySimpleGUI window provided into the filename provided
Parameter Descriptions
| Name | Type | Default | Description |
|---|---|---|---|
| RETURN | (PIL.ImageGrab or None) | A PIL ImageGrab object that can be saved or manipulated |
set_cursor
Sets the cursor for the current Element. "Cursor" is used in 2 different ways in this call. For the parameter "cursor" it's actually the mouse pointer. If you do not want any mouse pointer, then use the string "none" For the parameter "cursor_color" it's the color of the beam used when typing into an input element
Parameter Descriptions
| Name | Type | Default | Description |
|---|---|---|---|
| cursor | str | None | The tkinter cursor name |
| cursor_color | str | None | color to set the "cursor" to |
set_focus
Sets the current focus to be on this element
Parameter Descriptions
| Name | Type | Default | Description |
|---|---|---|---|
| force | bool | False | if True will call focus_force otherwise calls focus_set |
set_hscroll_position
Attempts to set the horizontal scroll postition for an element's Widget
Parameter Descriptions
| Name | Type | Default | Description |
|---|---|---|---|
| percent_from_left | float | From 0 to 1.0, the percentage from the left to move scrollbar to |
set_right_click_menu
Sets a right click menu for an element. If a menu is already set for the element, it will call the tkinter destroy method to remove it
Parameter Descriptions
| Name | Type | Default | Description |
|---|---|---|---|
| menu | List[List[ List[str] or str ]] | None | A list of lists of Menu items to show when this element is right clicked. See user docs for exact format. |
set_size
Changes the size of an element to a specific size. It's possible to specify None for one of sizes so that only 1 of the element's dimensions are changed.
Parameter Descriptions
| Name | Type | Default | Description |
|---|---|---|---|
| size | (int, int) | (None, None) | The size in characters, rows typically. In some cases they are pixels |
set_tooltip
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').
Parameter Descriptions
| Name | Type | Default | Description |
|---|---|---|---|
| tooltip_text | str or None | the text to show in tooltip. If None then no tip will be shown |
set_vscroll_position
Attempts to set the vertical scroll postition for an element's Widget
Parameter Descriptions
| Name | Type | Default | Description |
|---|---|---|---|
| percent_from_top | float | From 0 to 1.0, the percentage from the top to move scrollbar to |
unbind
Removes a previously bound tkinter event from an Element.
Parameter Descriptions
| Name | Type | Default | Description |
|---|---|---|---|
| bind_string | str | The string tkinter expected in its bind function |
unhide_row
Unhides (makes visible again) the row container that the Element is located on. Note that it will re-appear at the bottom of the window / container, most likely.
update
Changes some of the settings for the Button Element. Must call Window.Read or Window.Finalize prior
Changes will not be visible in your window until you call window.read or window.refresh.
If you change visibility, your element may MOVE. If you want it to remain stationary, use the "layout helper" function "pin" to ensure your element is "pinned" to that location in your layout so that it returns there when made visible.
update(
text = None,
button_color = (None, None),
disabled = None,
image_source = None,
image_data = None,
image_filename = None,
visible = None,
image_subsample = None,
image_zoom = None,
disabled_button_color = (None, None),
image_size = None
)
Parameter Descriptions
| Name | Type | Default | Description |
|---|---|---|---|
| button_color | (str, str) or str | (None, None) | Color of button. default is from theme or the window. Easy to remember which is which if you say "ON" between colors. "red" on "green". Normally a tuple, but can be a simplified-button-color-string "foreground on background". Can be a single color if want to set only the background. |
| disabled | (bool or str) | None | True/False to enable/disable at the GUI level. Use BUTTON_DISABLED_MEANS_IGNORE to ignore clicks (won't change colors) |
| disabled_button_color | (str, str) | (None, None) | colors to use when button is disabled (text, background). Use None for a color if don't want to change. Only ttk buttons support both text and background colors. tk buttons only support changing text color |
| image_data | bytes or str | None | Raw or Base64 representation of the image to put on button. Choose either filename or data |
| image_filename | str | None | image filename if there is a button image. GIFs and PNGs only. |
| image_size | (int, int) | None | Size of the image in pixels (width, height) |
| image_source | (str or bytes) | None | Image to place on button. Use INSTEAD of the image_filename and image_data. Unifies these into 1 easier to use parm |
| image_subsample | int | None | amount to reduce the size of the image. Divides the size by this number. 2=1/2, 3=1/3, 4=1/4, etc |
| image_zoom | int | None | amount to increase the size of the image. 2=twice size, 3=3 times, etc |
| text | str | None | sets button text |
| visible | bool | None | control visibility of element |