Multiline

Multiline documentation

Multiline Element - Display and/or read multiple lines of text. This is both an input and output element. 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,
    autoscroll_only_at_bottom = False,
    border_width = None,
    size = (None, None),
    s = (None, None),
    setting = None,
    auto_size_text = None,
    background_color = None,
    text_color = None,
    selected_text_color = None,
    selected_background_color = None,
    horizontal_scroll = False,
    change_submits = False,
    enable_events = False,
    do_not_clear = True,
    key = None,
    k = None,
    write_only = False,
    auto_refresh = False,
    reroute_stdout = False,
    reroute_stderr = False,
    reroute_cprint = False,
    echo_stdout_stderr = False,
    focus = False,
    font = None,
    pad = None,
    p = None,
    tooltip = None,
    justification = None,
    no_scrollbar = False,
    wrap_lines = None,
    sbar_trough_color = None,
    sbar_background_color = None,
    sbar_arrow_color = None,
    sbar_width = None,
    sbar_arrow_width = None,
    sbar_frame_color = None,
    sbar_relief = None,
    expand_x = False,
    expand_y = False,
    rstrip = True,
    right_click_menu = None,
    visible = True,
    metadata = None
)

Parameter Descriptions

Name	Type	Default	Description
auto_refresh	bool	False	If True then anytime the element is updated, the window will be refreshed so that the change is immediately displayed
auto_size_text	bool	None	if True will size the element to match the length of the text
autoscroll	bool	False	If True the contents of the element will automatically scroll as more data added to the end
autoscroll_only_at_bottom	bool	False	If True the contents of the element will automatically scroll only if the scrollbar is at the bottom of the multiline
background_color	str	None	color of background
border_width	int	None	width of border around element in pixels
change_submits	bool	False	DO NOT USE. Only listed for backwards compat - Use enable_events instead
default_text	Any		Initial text to show
disabled	bool	False	set disable state
do_not_clear	bool	True	if False the element will be cleared any time the Window.read call returns
echo_stdout_stderr	bool	False	If True then output to stdout and stderr will be output to this element AND also to the normal console location
enable_events	bool	False	If True then any key press that happens when the element has focus will generate an event.
enter_submits	bool	False	if True, the Window.read call will return is enter key is pressed in this element
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
focus	bool	False	if True initial focus will go to this element
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
horizontal_scroll	bool	False	Controls if a horizontal scrollbar should be shown. If True a horizontal scrollbar will be shown in addition to vertical
justification	str	None	text justification. left, right, center. Can use single characters l, r, c.
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
no_scrollbar	bool	False	If False then a vertical scrollbar will be shown (the default)
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)
reroute_cprint	bool	False	If True your cprint calls will output to this element. It's the same as you calling cprint_set_output_destination
reroute_stderr	bool	False	If True then all output to stderr will be output to this element
reroute_stdout	bool	False	If True then all output to stdout will be output to this element
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.
rstrip	bool	True	If True the value returned in will have whitespace stripped from the right side
s	(int, int) or (None, None) or int or (None, 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
sbar_arrow_color	str	None	Scrollbar color of the arrow at the ends of the scrollbar (it looks like a button). Switches to background color when mouse is over
sbar_arrow_width	int	None	Scrollbar width of the arrow on the scrollbar. It will potentially impact the overall width of the scrollbar
sbar_background_color	str	None	Scrollbar color of the background of the arrow buttons at the ends AND the color of the "thumb" (the thing you grab and slide). Switches to arrow color when mouse is over
sbar_frame_color	str	None	Scrollbar Color of frame around scrollbar (available only on some ttk themes)
sbar_relief	str	None	Scrollbar relief that will be used for the "thumb" of the scrollbar (the thing you grab that slides). Should be a constant that is defined at starting with "RELIEF_" - RELIEF_RAISED, RELIEF_SUNKEN, RELIEF_FLAT, RELIEF_RIDGE, RELIEF_GROOVE, RELIEF_SOLID
sbar_trough_color	str	None	Scrollbar color of the trough
sbar_width	int	None	Scrollbar width in pixels
selected_background_color	str	None	Color of background when it is selected (using mouse or control+A, etc)
selected_text_color	str	None	Color of text when it is selected (using mouse or control+A, etc)
setting	Any	None	If not None, then this element will be saved in a settings file using the key for the element
size	(int, int) or (None, None) or int or (None, 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
text_color	str	None	color of the text
tooltip	str	None	text, that will appear when mouse hovers over the element
visible	bool	True	set visibility state of the element
wrap_lines	bool	None	If True, the lines will be wrapped automatically. Other parms affect this setting, but this one will override them all. Default is it does nothing and uses previous settings for wrapping.
write_only	bool	False	If True then no entry will be added to the values dictionary when the window is read

Class Properties

 key
 metadata
 visible
 widget

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)

key

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

metadata

Parameter Descriptions

Name	Type	Default	Description
RETURN	Any		the current metadata value

visible

Returns visibility state for the element. This is a READONLY property

visible

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

widget

Parameter Descriptions

Name	Type	Default	Description
RETURN	(tkinter.Widget)		The element's underlying tkinter widget

Class Methods

 def bind
 def block_focus
 def expand
 def flush
 def get
 def get_next_focus
 def get_previous_focus
 def get_size
 def grab_anywhere_exclude
 def grab_anywhere_include
 def hide_row
 def print
 def remove_tooltip
 def reroute_stderr_to_here
 def reroute_stdout_to_here
 def restore_stderr
 def restore_stdout
 def save_element_screenshot_to_disk
 def set_cursor
 def set_focus
 def set_hscroll_position
 def set_ibeam_color
 def set_right_click_menu
 def set_size
 def set_tooltip
 def set_vscroll_position
 def unbind
 def unhide_row
 def update
 def write

bind

Used to add tkinter events to an Element. The tkinter specific data is in the Element's member variable user_bind_event

bind(
    bind_string,
    key_modifier,
    propagate = True
)

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.

block_focus(
    block = True
)

Parameter Descriptions

Name	Type	Default	Description
block	bool	True	if True the element will not get focus via the keyboard

expand

Causes the Element to expand to fill available space in the X and Y directions. Can specify which or both directions

expand(
    expand_x = False,
    expand_y = False,
    expand_row = True
)

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

flush

Flush parameter was passed into a print statement. For now doing nothing. Not sure what action should be taken to ensure a flush happens regardless.

flush()

get

Return current contents of the Multiline Element

get()

Parameter Descriptions

Name	Type	Default	Description
RETURN	str		current contents of the Multiline Element (used as an input type of Multiline

get_next_focus

Gets the next element that should get focus after this element.

get_next_focus()

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.

get_previous_focus()

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.

get_size()

Parameter Descriptions

Name	Type	Default	Description
RETURN	(int, int)		width and height of the element

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_exclude()

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

grab_anywhere_include()

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

hide_row()

print

Print like Python normally prints except route the output to a multiline element and also add colors if desired

colors -(str, str) or str. A combined text/background color definition in a single parameter

There are also "aliases" for text_color, background_color and colors (t, b, c) t - An alias for color of the text (makes for shorter calls) b - An alias for the background_color parameter c - (str, str) - "shorthand" way of specifying color. (foreground, backgrouned) c - str - can also be a string of the format "foreground on background" ("white on red")

With the aliases it's possible to write the same print but in more compact ways: cprint('This will print white text on red background', c=('white', 'red')) cprint('This will print white text on red background', c='white on red') cprint('This will print white text on red background', text_color='white', background_color='red') cprint('This will print white text on red background', t='white', b='red')

print(
    args = *<1 or N objects>,
    end = None,
    sep = None,
    text_color = None,
    background_color = None,
    justification = None,
    font = None,
    colors = None,
    t = None,
    b = None,
    c = None,
    autoscroll = True
)

Parameter Descriptions

Name	Type	Default	Description
args	Any		The arguments to print
autoscroll	bool	True	If True the contents of the element will automatically scroll as more data added to the end
b	str	None	The background color of the line
background_color	str	None	The background color of the line
c	str or str, str	None	Either a tuple or a string that has both the text and background colors or just tex color (same as the color parm)
colors	str or str, str	None	Either a tuple or a string that has both the text and background colors. Or just the text color
end	str	None	The end char to use just like print uses
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 for the args being printed
justification	str	None	text justification. left, right, center. Can use single characters l, r, c. Sets only for this value, not entire element
sep	str	None	The separation character like print uses
t	str	None	Color of the text
text_color	str	None	The color of the text

remove_tooltip

Removes a previiously created tooltip for an element

remove_tooltip()

reroute_stderr_to_here

Sends stderr to this element

reroute_stderr_to_here()

reroute_stdout_to_here

Sends stdout (prints) to this element

reroute_stdout_to_here()

restore_stderr

Restore a previously re-reouted stderr back to the original destination

restore_stderr()

restore_stdout

Restore a previously re-reouted stdout back to the original destination

restore_stdout()

save_element_screenshot_to_disk

Saves an image of the PySimpleGUI window provided into the filename provided

save_element_screenshot_to_disk(
    filename = None
)

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

set_cursor(
    cursor = None,
    cursor_color = None
)

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

set_focus(
    force = False
)

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

set_hscroll_position(
    percent_from_left
)

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_ibeam_color

Sets the color of the I-Beam that is used to "insert" characters. This is oftens called a "Cursor" by many users. To keep from being confused with tkinter's definition of cursor (the mouse pointer), the term ibeam is used in this case.

set_ibeam_color(
    ibeam_color = None
)

Parameter Descriptions

Name	Type	Default	Description
ibeam_color	str	None	color to set the "I-Beam" used to indicate where characters will be inserted

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

set_right_click_menu(
    menu = None
)

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.

set_size(
    size = (None, None)
)

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').

set_tooltip(
    tooltip_text
)

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

set_vscroll_position(
    percent_from_top
)

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.

unbind(
    bind_string
)

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.

unhide_row()

update

Changes some of the settings for the Multiline Element. Must call Window.read or set finalize=True when creating window.

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(
    value = None,
    disabled = None,
    append = False,
    font = None,
    text_color = None,
    background_color = None,
    text_color_for_value = None,
    background_color_for_value = None,
    visible = None,
    autoscroll = None,
    justification = None,
    font_for_value = None
)

Parameter Descriptions

Name	Type	Default	Description
append	bool	False	if True then new value will be added onto the end of the current value. if False then contents will be replaced.
autoscroll	bool	None	if True then contents of element are scrolled down when new text is added to the end
background_color	str	None	color of background
background_color_for_value	str	None	color of the new background of the text being added (the value paramter)
disabled	bool	None	disable or enable state of the element
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 for the entire element
font_for_value	str or (str, int)	None	specifies the font family, size, etc. Tuple or Single string format 'name size styles'. Styles: italic * roman bold normal underline overstrike for the value being updated
justification	str	None	text justification. left, right, center. Can use single characters l, r, c. Sets only for this value, not entire element
text_color	str	None	color of the text
text_color_for_value	str	None	color of the new text being added (the value paramter)
value	Any	None	new text to display
visible	bool	None	set visibility state of the element

write

Called by Python (not tkinter?) when stdout or stderr wants to write

write(
    txt
)

Parameter Descriptions

Name	Type	Default	Description
txt	str		text of output