Text Formatting

The Screen’s draw.text() method has a very rich set of methods for position and formatting of text. Some examples:

screen.draw.text("Text color", (50, 30), color="orange")
screen.draw.text("Font name and size", (20, 100), fontname="Boogaloo", fontsize=60)
screen.draw.text("Positioned text", topright=(840, 20))
screen.draw.text("Allow me to demonstrate wrapped text.", (90, 210), width=180, lineheight=1.5)
screen.draw.text("Outlined text", (400, 70), owidth=1.5, ocolor=(255,255,0), color=(0,0,0))
screen.draw.text("Drop shadow", (640, 110), shadow=(2,2), scolor="#202020")
screen.draw.text("Color gradient", (540, 170), color="red", gcolor="purple")
screen.draw.text("Transparency", (700, 240), alpha=0.1)
screen.draw.text("Vertical text", midleft=(40, 440), angle=90)
screen.draw.text("All together now:\nCombining the above options",
    midbottom=(427,460), width=360, fontname="Boogaloo", fontsize=48,
    color="#AAFF00", gcolor="#66AA00", owidth=1.5, ocolor="black", alpha=0.8)

In its simplest usage, screen.draw.text requires the string you want to draw, and the position. You can either do this by passing coordinates as the second argument (which is the top left of where the text will appear), or use the positioning keyword arguments (described later):

screen.draw.text("hello world", (20, 100))

screen.draw.text takes many optional keyword arguments, described below.

Font name and size

Fonts are loaded from a directory named fonts, in a similar way to the handling of images and sounds. Fonts must be in .ttf format. For example:

screen.draw.text("hello world", (100, 100), fontname="Viga", fontsize=32)

Keyword arguments:

• fontname: filename of the font to draw. By default, use the system font.
• fontsize: size of the font to use, in pixels. Defaults to 24.
• antialias: whether to render with antialiasing. Defaults to True.

Color and background color

screen.draw.text("hello world", (100, 100), color=(200, 200, 200), background="gray")

Keyword arguments:

• color: foreground color to use. Defaults to white.
• background: background color to use. Defaults to None.

color (as well as background, ocolor, scolor, and gcolor) can be an (r, g, b) sequence such as (255,127,0), a pygame.Color object, a color name such as "orange", an HTML hex color string such as "#FF7F00", or a string representing a hex color number such as "0xFF7F00".

background can also be None, in which case the background is transparent. Unlike pygame.font.Font.render, it’s generally not more efficient to set a background color when calling screen.draw.text. So only specify a background color if you actually want one.

Colors with alpha transparency are not supported (except for the special case of invisible text with outlines or drop shadows - see below). See the alpha keyword argument for transparency.

Positioning

screen.draw.text("hello world", centery=50, right=300)
screen.draw.text("hello world", midtop=(400, 0))

Keyword arguments:

top left bottom right
topleft bottomleft topright bottomright
midtop midleft midbottom midright
center centerx centery

Positioning keyword arguments behave like the corresponding properties of pygame.Rect. Either specify two arguments, corresponding to the horizontal and vertical positions of the box, or a single argument that specifies both.

If the position is overspecified (e.g. both left and right are given), then extra specifications will be (arbitrarily but deterministically) discarded. For constrained text, see the section on screen.draw.textbox below.

Word wrap

screen.draw.text("splitting\nlines", (100, 100))
screen.draw.text("splitting lines", (100, 100), width=60)

Keyword arguments:

• width: maximum width of the text to draw, in pixels. Defaults to None.
• widthem: maximum width of the text to draw, in font-based em units. Defaults to None.
• lineheight: vertical spacing between lines, in units of the font’s default line height. Defaults to 1.0.

screen.draw.text will always wrap lines at newline (\n) characters. If width or widthem is set, it will also try to wrap lines in order to keep each line shorter than the given width. The text is not guaranteed to be within the given width, because wrapping only occurs at space characters, so if a single word is too long to fit on a line, it will not be broken up. Outline and drop shadow are also not accounted for, so they may extend beyond the given width.

You can prevent wrapping on a particular space with non-breaking space characters (\u00A0).

Text alignment

screen.draw.text("hello\nworld", bottomright=(500, 400), align="left")

Keyword argument:

• align: horizontal positioning of lines with respect to each other. Defaults to None.

align determines how lines are positioned horizontally with respect to each other, when more than one line is drawn. Valid values for align are the strings "left", "center", or "right", a numerical value between 0.0 (for left alignment) and 1.0 (for right alignment), or None.

If align is None, the alignment is determined based on other arguments, in a way that should be what you want most of the time. It depends on any positioning arguments (topleft, centerx, etc.), anchor, and finally defaults to "left". I suggest you generally trust the default alignment, and only specify align if something doesn’t look right.

Outline

screen.draw.text("hello world", (100, 100), owidth=1, ocolor="blue")

Keyword arguments:

• owidth: outline thickness, in outline units. Defaults to None.
• ocolor: outline color. Defaults to "black".

The text will be outlined if owidth is specified. The outlining is a crude manual method, and will probably look bad at large sizes. The units of owidth are chosen so that 1.0 is a good typical value for outlines. Specifically, they’re the font size divided by 24.

As a special case, setting color to a transparent value (e.g. (0,0,0,0)) while using outilnes will cause the text to be invisible, giving a hollow outline. (This feature is not compatible with gcolor.)

Valid values for ocolor are the same as for color.

Drop shadow

screen.draw.text("hello world", (100, 100), shadow=(1.0,1.0), scolor="blue")

Keyword arguments:

• shadow: (x,y) values representing the drop shadow offset, in shadow units. Defaults to None.
• scolor: drop shadow color. Defaults to "black".

The text will have a drop shadow if shadow is specified. It must be set to a 2-element sequence representing the x and y offsets of the drop shadow, which can be positive, negative, or 0. For example, shadow=(1.0,1.0) corresponds to a shadow down and to the right of the text. shadow=(0,-1.2) corresponds to a shadow higher than the text.

The units of shadow are chosen so that 1.0 is a good typical value for the offset. Specifically, they’re the font size divided by 18.

As a special case, setting color to a transparent value (e.g. (0,0,0,0)) while using drop shadow will cause the text to be invisible, giving a hollow shadow. (This feature is not compatible with gcolor.)

Valid values for scolor are the same as for color.

Gradient color

screen.draw.text("hello world", (100, 100), color="black", gcolor="green")

Keyword argument:

• gcolor: Lower gradient stop color. Defaults to None.

Specify gcolor to color the text with a vertical color gradient. The text’s color will be color at the top and gcolor at the bottom. Positioning of the gradient stops and orientation of the gradient are hard coded and cannot be specified.

Requries pygame.surfarray module, which uses numpy or Numeric library.

Alpha transparency

screen.draw.text("hello world", (100, 100), alpha=0.5)

Keyword argument:

• alpha: alpha transparency value, between 0 and 1. Defaults to 1.0.

In order to maximize reuse of cached transparent surfaces, the value of alpha is rounded.

Requires pygame.surfarray module, which uses numpy or Numeric library.

Anchored positioning

screen.draw.text("hello world", (100, 100), anchor=(0.3,0.7))

Keyword argument:

• anchor: a length-2 sequence of horizontal and vertical anchor fractions. Defaults to (0.0, 0.0).

anchor specifies how the text is anchored to the given position, when no positioning keyword arguments are passed. The two values in anchor can take arbitrary values between 0.0 and 1.0. An anchor value of (0,0), the default, means that the given position is the top left of the text. A value of (1,1) means the given position is the bottom right of the text.

Rotation

screen.draw.text("hello world", (100, 100), angle=10)

Keyword argument:

• angle: counterclockwise rotation angle in degrees. Defaults to 0.

Positioning of rotated surfaces is tricky. When drawing rotated text, the anchor point, the position you actually specify, remains fixed, and the text rotates around it. For instance, if you specify the top left of the text to be at (100, 100) with an angle of 90, then the Surface will actually be drawn so that its bottom left is at (100, 100).

If you find that confusing, try specifying the center. If you anchor the text at the center, then the center will remain fixed, no matter how you rotate it.

In order to maximize reuse of cached rotated surfaces, the value of angle is rounded to the nearest multiple of 3 degrees.

Constrained text

screen.draw.textbox("hello world", (100, 100, 200, 50))

screen.draw.textbox requires two arguments: the text to be drawn, and a pygame.Rect or a Rect-like object to stay within. The font size will be chosen to be as large as possible while staying within the box. Other than fontsize and positional arguments, you can pass all the same keyword arguments to screen.draw.textbox as to screen.draw.text.