Line & Pen Quick Reference

01

Line or Pen?

Use Line for one segment with two editable endpoints. Use Pen for a path that grows through several points over time, either under direct control or attached to a moving object.

Line(screen, start, end, ...)

Create one scene object between two endpoints.

Pen(screen, x, y, ...)

Create a path recorder with a current drawing position.

object.pen(...)

Attach a Pen to a movable object so later movement extends its trail.

One segment

divider = Line(
    screen, (40, 100), (300, 100),
    Color("gray"), thickness=2
)

Growing path

path = Pen(screen, 40, 100, Color("blue"), width=3)
path.start()
path.moveto(120, 60)
path.moveto(210, 130)

02

Creating Lines

Construct a Line from four coordinates or two coordinate values. Optional style arguments control its color, thickness, dash pattern, and initial visibility.

Line(screen, x1, y1, x2, y2, color=Color("black"), thickness=1, dashes=None, visible=True)

Create a Line from four endpoint coordinates.

Line(screen, pos1, pos2, color=Color("black"), thickness=1, dashes=None, visible=True)

Create a Line from two Locations or (x, y) tuples.

Example

axis = Line(screen, 60, 220, 540, 220, thickness=2)

Coordinate values

start = Location(80, 80)
end = (260, 160)
connector = Line(
    screen, start, end,
    Color("green"), thickness=3
)

03

Endpoints & movement

Read or replace either endpoint directly, translate both together, move only one by an offset, or replace the complete segment in one call.

line.pos1() · line.pos1(x, y) · line.pos1(location)

Read or replace the first endpoint.

line.pos2() · line.pos2(x, y) · line.pos2(location)

Read or replace the second endpoint.

line.location()

Return both endpoints as a (pos1, pos2) tuple.

line.move(dx, dy, point=0)

Move both endpoints, or pass point=1 or point=2 to move only one.

line.moveto(pos1, pos2) · line.moveto(x1, y1, x2, y2)

Replace both endpoints together.

line.moveto(pos1=..., pos2=..., x1=..., y1=..., x2=..., y2=...)

Replace selected endpoint values by name.

Example

connector.pos2(player.center())
connector.move(5, 0)

Move one endpoint

connector.move(0, -10, point=1)
connector.moveto(
    pos1=(20, 40),
    pos2=target.center(),
)

04

Length, rotation & pointing

A Line derives its length and rotation from its endpoints. Rotating preserves length and swings one endpoint around the other; lookat() points the selected end toward a target.

line.length()

Return the straight-line distance between the endpoints.

line.rotation(angle=None)

Read the current rotation or set an absolute angle.

line.rotate(angle_difference, point=1)

Rotate around pos1 by default, or around pos2 with point=2.

line.lookat(location, point=2) · line.lookat(x, y, point=2)

Aim the selected endpoint at a target while preserving length.

line.transform()

Return (length, rotation); setting a Line transform is unsupported.

Example

hand.rotate(6)
print(hand.length())
print(hand.rotation())

Track a target

# pos1 stays fixed; pos2 turns toward the player
pointer.lookat(player.center())

05

Style, intersections & copies

Restyle or hide a Line without recreating it, detect crossings with other geometry, and clone a segment when another independent copy is useful.

line.color(value=None) · line.thickness(value=None)

Read or change stroke color and width.

line.dashes(value=None)

Read or set an equal dash/gap length with an integer, or a custom pattern with an integer tuple.

line.visible(value=None)

Read or change whether the Line is drawn.

line.intersects(line_or_renderable)

Test whether the segment crosses another Line or a Renderable boundary.

line.intersects(points)

Test against edges formed by a list or tuple of at least two Locations.

line.clone()

Create an active independent copy on the same Screen.

ALSO SUPPORTS

front()back()remove()

Example

guide.color(Color("light gray"))
guide.thickness(2)
guide.dashes((8, 4))

Crossing test

if laser.intersects(wall):
    laser.color(Color("red"))

copy = laser.clone()
copy.move(0, 20)

06

Standalone Pens

A standalone Pen begins at a position but starts paused. Start it before moving, stop it to preserve the current stroke, and restart it to begin another stroke from the latest position.

Pen(screen, x, y, color=Color("black"), width=2, top=False)

Create a paused Pen at an initial position.

pen.start() · pen.stop()

Begin a new stroke or finish the current one.

pen.drawing(value=None)

Read drawing state, or pass True or False to start or stop.

pen.toggle()

Switch drawing state and return the new state.

pen.clear()

Remove every stroke while preserving the Pen's current position and drawing state.

pen.location()

Return the latest drawn point or paused cursor position.

Example

pen = Pen(screen, 40, 80, Color("purple"), width=4)
pen.start()
pen.moveto(140, 120)
pen.stop()

Pause and resume

pen.toggle()
print(pen.drawing())
pen.clear()

07

Building & replacing paths

While drawing, each movement adds a point to the active stroke. While stopped, movement only repositions the Pen so the next stroke can begin somewhere else.

pen.move(dx, dy)

Move relative to the current point and return the new Location.

pen.moveto(x, y) · pen.moveto(location)

Move to an absolute point and return its Location.

pen.move(dx=value, dy=value) · pen.moveto(x=value, y=value)

Change one coordinate while preserving the other.

pen.coordinates()

Return the current stroke's list of Locations.

pen.coordinates(*points)

Replace the current stroke with Locations or (x, y) tuples.

Example

pen.start()
for point in [(40, 40), (90, 20), (140, 40), (90, 80)]:
    pen.moveto(point)

Reposition without drawing

pen.stop()
pen.moveto(300, 200)
pen.start()
pen.move(50, 0)

08

Pen style & object trails

Change a Pen's shared appearance or attach one to an object. An attached Pen starts immediately and records later object movement through its x/y anchor.

pen.color(value=None) · pen.width(value=None)

Read or change the color and integer width of the Pen's strokes.

pen.top(value=None)

Read or change whether Pen strokes render above regular Screen objects.

object.pen(color=Color("black"), width=2, top=False)

Start or resume the object's attached Pen and return it.

object.pen_stop() · object.pen_clear()

Stop the attached Pen or clear all of its strokes.

object.pen_width(value=None) · object.pen_top(value=None)

Read or change attached trail width and drawing order.

Example

trail = player.pen(Color("blue"), width=3)
player.move(50, 0)
player.move(0, 40)
player.pen_stop()

Direct style control

trail.color(Color("orange"))
trail.width(5)
trail.top(True)
trail.drawing(True)