Text#
This section is about drawing text on slides.
Text is drawn on a box (or slide) by calling the .text()
method. It creates a new box containing a text.
Note for Elsie users
Calling .text()
creates a new box; this is a different behavior than in Elsie, where calling .text()
does not create a new box, which very often leads to code like .box().text()
to create a wrapping box. This is not necessary in Nelsie.
Text styles#
The drawing of a text is configured by TextStyle
instances. One of the uses is to set it as the second argument of the .text()
method.
from nelsie import TextStyle
@deck.slide()
def text_style_demo(slide):
style = TextStyle(size=100, color="green")
slide.text("Hello world!", style)
The TextStyle
constructor has the following parameters; each parameter can be `None', which means that the parameter will not be overridden by this style.
family
:str
- Name of the font or a generic family:sans-serif
,monospace
,serif
color
:str
- Color of the textsize
:float
- Size of the fontline_spacing
:float
- Line spacing relative tosize
italics
:bool
- Enable italic modeweight
:int
- Weight of the font; values 1-1000- 400 = Normal
- 700 = Bold
bold
:bool
- Shortcut that setsweight=700
underline
:bool
- Draws a line under the textoverline
:bool
- Draws a line over the textline_through
:bool
- Draws a line through a textstroke
:Stroke | None
- If notNone
, font is drawn in stroked mode (see Paths for documentation ofStroke
class)stretch
:FontStretch
:FontStretch.UltraCondensed
FontStretch.ExtraCondensed
FontStretch.Condensed
FontStretch.SemiCondensed
FontStretch.Normal
FontStretch.SemiExpanded
FontStretch.Expanded
FontStretch.ExtraExpanded
FontStretch.UltraExpanded
Named styles#
Each box can have a set of named fonts defined. When a new box is created it inherits all named styles from its parent.
@deck.slide()
def text_style_demo(slide):
slide.set_style("my-style", TextStyle(size=100, color="red"))
slide.text("Hello world!", "my-style")
Slide deck may also defines a font that is inherited by all slides.
Build-in styles#
There are three predefined text styles:
"default"
"code"
Style "default"
is special and is used as a source of default values for drawing fonts when values are not overridden by more specific fonts:
@deck.slide()
def default_style_demo(slide):
# Set default style
slide.set_style("default", TextStyle(color="blue"))
# Draw text with overriden style, color is taken from the default style
slide.text("Hello world!", TextStyle(size=100))
Style "code"
is used as a default style in .code()
method. See Code for more details. It has set monospace
font family by default.
Inline styles#
Named styles are particularly useful for modifying individual blocks of text within a single string passed to the .text()
method. To style a block of text, use the following syntax ~STYLE{TEXT}
where STYLE is a style name and TEXT is the styled text.
@deck.slide()
def inline_style_demo(slide):
slide.set_style("red", TextStyle(color="red"))
slide.set_style("big", TextStyle(size=64))
slide.set_style("mono", TextStyle(font="monospace"))
slide.text("~red{Hello} world!\n~mono{github.com/spirali/~big{nelsie}}")
Fonts#
A font can be specified by the font
parameter of TextStyle
.
Nelsie is shipped with a built-in font Dejavu Sans
as default. You can add more fonts via Resources.
You can set a different font by setting font
in text style.
Text alignment#
A text can be aligned to the left, center, and right by setting .text(align="...")
to "start"
, "center"
, or "end"
. The value "start"
is the default.
@deck.slide()
def text_align_demo(slide):
TEXT = "Line 1\nLooooong line\nThird line"
box = slide.box(gap_y=50)
box.text(TEXT, align="start")
box.text(TEXT, align="center")
box.text(TEXT, align="end")
Text box#
Calling .text()
creates a box for the text; the method takes the same arguments as .box()
to configure the underlying box.
@deck.slide()
def text_box_demo(slide):
box = slide.box(bg_color="gray")
box.text("Hello world!", bg_color="orange", m_left=50, m_top=30)
Updating style#
The .set_style()
method overrides the whole style over given name:
deck.set_style("my-style", TextStyle(color="green"))
@deck.slide()
def text_style_demo(slide):
slide.set_style("default", TextStyle(size=80))
# "my-style" now forgets the color, as we fully redefining what "my-style" is
slide.set_style("my-style", TextStyle(italic=True))
slide.text("Hello world!", "my-style")
There is method .update_style()
, if we want to "update" style, and change only some properties and keep others.
deck.set_style("my-style", TextStyle(color="green"))
@deck.slide()
def text_style_demo(slide):
slide.set_style("default", TextStyle(size=80))
# "my-style" now contains both color change to green and italic style
slide.update_style("my-style", TextStyle(italic=True))
slide.text("Hello world!", "my-style")
Setting a default style
There is an exception for style "default"
as it always needs to define all attributes. Hence .set_style()
for "default"
style always behaves as .update_style()
.
Text and StepVal
#
You may use StepVal
in .text()
:
@deck.slide()
def text_style_demo(slide):
slide.set_style("default", TextStyle(size=80))
slide.text(StepVal("Hello world!").at(2, "Hello Nelsie!"))
Text styles and StepVal
#
When a style is set through set_style
an instance of StepVal
can be used:
@deck.slide()
def text_style_demo(slide):
slide.set_style("default", TextStyle(size=80))
slide.set_style("my-style",
StepVal(TextStyle(color="orange")).at(2, TextStyle(color="blue")))
slide.text("Hello world!", "my-style")
or it is also possible to set individual values of TextStyle
:
@deck.slide()
def text_style_demo2(slide):
slide.set_style("default", TextStyle(size=80))
slide.set_style("my-style",
TextStyle(color=StepVal("orange").at(2, "blue")))
slide.text("Hello world!", "my-style")
Line steps#
You may define showing and hiding individual lines directly into the text. It is enabled by parse_steps=True
. It seaches for "@" that is a delimiter for step definition. You may the delimiter via. parse_steps=<NEW_DELIMITER>
.
@deck.slide()
def text_style_demo(slide):
slide.set_style("default", TextStyle(size=80))
slide.text("""
line1
line2 @2,4+
line3 @3""", parse_steps=True)
There are two configuration options:
e
- when line is not shown it is replaced by an empty linen
- it negates the step expression, i.e. the line is shown in the steps NOT defined in the expression.
The configuration is given immediately after "**" and followed by ;
.
@deck.slide()
def text_style_demo(slide):
slide.set_style("default", TextStyle(size=80))
slide.text("""
line1 @3+
line2 @n; 3+
line3 @e; 2,4
line4 @en; 4+
line5""", parse_steps=True)
You may also skip the step expression after "**"; Nelsie then uses the previously defined step expression.
@deck.slide()
def text_style_demo(slide):
slide.set_style("default", TextStyle(size=80))
slide.text("""
line1 @ 2+
line2 @
line3 @
""", parse_steps=True)
Automatic text stripping#
The .text()
method automatically strips whitespace from the beginning and end of the text. This can be disabled by setting .text(..., strip=False)
.