Outputting Text |
The print function
The print function places text in a scrolling text region at the bottom of the window. Consider the following statements:
v = vec(1,2,3)
print("This is a test.")
print("The vector v =", v, ".")
These statements produce this output:
This is a test.
The vector v = < 1, 2, 3>.
The first print statement creates the scrolling text region. Later print statements add to the existing text, with end-of-line breaks after each print, and with spaces between items listed in a print statement.
You can print multiline text like the following:
print('''This is a test
of multiline text which
displays as shown.''')
You can change the end of line ('\n" by default) and the item separator (" " by default). Consider the following print statements:
v = vec(1,2,3)
print("Look:", end="---")
print("v =", v, ".", sep="_", end="!!")
These statements produce this output:
Look:---v =_< 1, 2, 3 >_.!!
The elements "sep=..., end=..." must be the last arguments in the print statement.
String formatting
The easiest way to format a string is to use what are called "f-strings", so-called because the string is preceded by "f" or, equivalently, "F":
V = 13.47
units = 'liters'
s = f"There are {V:.1f} {units}."
print(s) # "There are 13.5 liters."
The string begins with an initial "f" (or "F"). Quantities within braces are evaluated and converted to strings. The form {V:.1f} means "evaluate the variable V and display it in fixed format, with 1 digit after the decimal point. The value 13.47 is rounded to 13.5. If you specify {V:12.3f}, what will be displayed is " 13.470", with 6 spaces before the number, plus the 6 digits of "13.470" (3 after the decimal point), for a total of 12 characters.
A variable quantity such as V above can be a call to a function, whether your own function or a built-in function such as sqrt(). In fact, you can have entire expressions within braces, such as "10*V + sqrt(pi)".
There are many formats available in addtion to fixed format numbers: b for binary (base 2), o for octal (base 8), x for hexidecimal (base 16; 28 displays as 1c), d for decimal integer, e for exponential (e.g. 5.32e-7), c for character code (e.g. converts "b" to 97), % for percent (displays 0.34 as 34%). The E exponential format gives 5.32E-7 and the X hexidecimal format gives 1C. The g format (g for general) is particularly useful because it flips between fixed and exponential formats depending on the size of the number.
An older form of string formatting
Here is an older form of string formatting):
V = 13.47
s = "There are {:.1f} {}."
p = s.format(V, 'liters')
print(p) # "There are 13.5 liters."
Or more compactly,
print( "There are {:.1f} {}.".format(V, 'liters') )
The element "{:.1f}" indicates "fixed format" with ".1" indicating that one digit should be shown after the decimal point. The value 13.47 is rounded to 13.5. If you specify "{:12.3f}", what will be displayed is " 13.470", with 6 spaces before the number, plus the 6 digits of "13.470" (3 after the decimal point), for a total of 12 characters.
The element "{}" indicates that the default method for representing an argument should be used. In this case "liters" is displayed.
There are many formats available: b for binary (base 2), o for octal (base 8), x for hexidecimal (base 16; 28 displays as 1c), d for decimal integer, e for exponential (e.g. 5.32e-7), c for character code (e.g. converts "b" to 97), % for percent (displays 0.34 as 34%). The E exponential format gives 5.32E-7 and the X hexidecimal format gives 1C.
The g format (g for general) is particularly useful because it flips between fixed and exponential formats depending on the size of the number.
The following statement
print("The {} {} {}.".format("quick","brown","fox"))
produces "The quick brown fox". You can specify a different order of the arguments. The following statement
print("The {2} {0} {1}.".format("quick","brown","fox"))
produces "The fox quick brown." In other words, {N} refers to the Nth argument, counting from zero.
Moreover, you can combine specifying which argument to display with the format to use:
s = "Here are fixed format ({0:.3f}) and exponential format ({0:.3e}) versions.".format(127.73)
Print options (not currently available in VPython 7)
With print_options you can change the default size of the print region, allow the user to edit the text, clear the text from the region, destroy the region, or obtain the current contents of the print region.
The following statement changes both the width (default 640) and height (default 100) of the print region. If you execute this before your first print statement, the initial size will be 500 by 300. If you execute this after executing print statements, the size of the region will change (but will retain its contents).
print_options(width=500, height=300)
By default, the text in the print region is read-only; the user cannot edit the text. If you want the user to be able to edit the text, do this:
print_options(readonly=False)
In any case, the user can select text and copy the text with ctrl-c.
By default, numbers are displayed with six digits, such as 123.456 or 1.23456e+8. You can specify the number of digits to display:
print_options(digits=4)
You can clear out all the text from the region like this:
print_options(clear=True)
You can delete the region from the screen with this statement:
print_options(delete=True)
After deleting the region, another print statement will recreate it, with the previously specified width and height.
By default the print area appears underneath the canvas (pos = 'bottom') but you can make it appear to the right of the canvas with the following statement (you may have to include something like width=100, because if the window is too narrow to fit the canvas and the text area side by side, the text area goes below the canvas):
print_options(pos='right')
You can also place the print area at a specifiable place on the page:
print_options(place=scene.title_anchor)
print_options(place=scene.caption_anchor)
You can obtain the current contents of the print region as a character string:
text = print_options(contents=True)
The text is extracted before processing clear or destroy requests. If you don't request the contents, print_options returns the empty character string ""'.
You can of course combine any options in one statement:
print_options(width=150, readonly=False)
Additional text output methods
The canvas documentation explains how to add text above a canvas (scene.title) or below a canvas (scene.caption). The wtext object lets you place dynamically modifiable text in the middle of the caption or title of a canvas.
The Example program ScrollingText shows how to create a scrolling text object that you can send output to and type into, using the HTML element "textarea". This is the mechanism used by print.
alert('The mass is '+m+' kg.')
This pauses execution and displays the string in a dialog box. Numeric values are converted to strings.
$('body').append('This is a test.<br>')
...
$('body').append('This is only a test.<br>')
These statements add text to the bottom of the web page. The <br> element makes a line break,
console.log('A scalar', a+10, 'and a vector', v.toString())
The output in the console is the following:
A scalar 15 and a vector < 10, 20, 30 >
Successive console.log outputs
appear as new lines.
Using console.log requires opening the browser's "console". To enable the console, in Chrome or Edge press shift-ctrl-j on Windows or Ubuntu, or option-cmd-j on Mac. In Firefox on Windows choose Firefox > Web Developer > Web Console, and on Ubuntu choose Tools > Web Developer > Web Console. The output will be found at the end of the console output
In some of these output options, to display the value of a vector v you have to write v.toString(), but this is done automatically by the print statement.