textual_canvas.canvas

Provides a simple character cell-based canvas widget for Textual applications.

Canvas

Canvas(
    width,
    height,
    canvas_color=None,
    pen_color=None,
    name=None,
    id=None,
    classes=None,
    disabled=False,
)

Bases: ScrollView

A simple character-cell canvas widget.

The widget is designed such that there are two 'pixels' per character cell; one being the top half of the cell, the other being the bottom. While not exactly square, this will make it more square than using a whole cell as a simple pixel.

The origin of the canvas is the top left corner.

Parameters:

Name	Type	Description	Default
width	int	The width of the canvas.	required
height	int	The height of the canvas.	required
canvas_color	Color | None	An optional default colour for the canvas.	None
pen_color	Color | None	The optional default colour for the pen.	None
name	str | None	The name of the canvas widget.	None
id	str | None	The ID of the canvas widget in the DOM.	None
classes	str | None	The CSS classes of the canvas widget.	None
disabled	bool	Whether the canvas widget is disabled or not.	False

If canvas_color is omitted, the widget's background styling will be used.

If pen_color is omitted, the widget's color styling will be used.

height property

height

The height of the canvas in 'pixels'.

width property

width

The width of the canvas in 'pixels'.

batch_refresh

batch_refresh()

A context manager that suspends all calls to refresh until the end of the batch.

Ordinarily set_pixels will call refresh once it has updated all of the pixels it has been given. Sometimes you may want to perform a number of draw operations and having refresh called between each one would be inefficient given you've not drawing.

Use this context manager to batch up your drawing operations.

Example

canvas = self.query_one(Canvas)
with canvas.batch_refresh():
    canvas.draw_line(10, 10, 10, 20)
    canvas.draw_line(10, 20, 20, 20)
    canvas.draw_line(20, 20, 20, 10)
    canvas.draw_line(20, 10, 10, 10)

Note

All drawing methods have a refresh parameter. If that is set to True in any of your calls those calls will still force a refresh.

clear

clear(color=None, width=None, height=None)

Clear the canvas.

Parameters:

Name	Type	Description	Default
color	Color | None	Optional default colour for the canvas.	None
width	int | None	Optional width for the canvas.	None
height	int | None	Optional height for the canvas.	None

Returns:

Type	Description
Self	The canvas.

If the color isn't provided, then the color used when first making the canvas is used, this in turn becomes the new default color (and will then be used for subsequent clears, unless another color is provided).

Explicitly setting the colour to None will set the canvas colour to whatever the widget's background colour is.

If width or height are omitted then the current value for those dimensions will be used.

clear_pixel

clear_pixel(x, y, refresh=None)

Clear the colour of a specific pixel on the canvas.

Parameters:

Name	Type	Description	Default
x	int	The horizontal location of the pixel.	required
y	int	The vertical location of the pixel.	required
refresh	bool | None	Should the widget be refreshed?	None

Raises:

Type	Description
CanvasError	If the pixel location is not within the canvas.

Note

The origin of the canvas is the top left corner.

clear_pixels

clear_pixels(locations, refresh=None)

Clear the colour of a collection of pixels on the canvas.

Parameters:

Name	Type	Description	Default
locations	Iterable[tuple[int, int]]	An iterable of tuples of x and y location.	required
refresh	bool | None	Should the widget be refreshed?	None

Returns:

Type	Description
Self	The canvas.

Raises:

Type	Description
CanvasError	If any pixel location is not within the canvas.

Note

The origin of the canvas is the top left corner.

draw_circle

draw_circle(
    center_x, center_y, radius, color=None, refresh=None
)

Draw a circle

Parameters:

Name	Type	Description	Default
center_x	int	The horizontal position of the center of the circle.	required
center_y	int	The vertical position of the center of the circle.	required
radius	int	The radius of the circle.	required
color	Color | None	The colour to draw circle in.	None
refresh	bool | None	Should the widget be refreshed?	None

Returns:

Type	Description
Self	The canvas.

Note

The origin of the canvas is the top left corner.

draw_line

draw_line(x0, y0, x1, y1, color=None, refresh=None)

Draw a line between two points.

Parameters:

Name	Type	Description	Default
x0	int	Horizontal location of the starting position.	required
y0	int	Vertical location of the starting position.	required
x1	int	Horizontal location of the ending position.	required
y1	int	Vertical location of the ending position.	required
color	Color | None	The color to set the pixel to.	None
refresh	bool | None	Should the widget be refreshed?	None

Returns:

Type	Description
Self	The canvas.

Note

The origin of the canvas is the top left corner.

draw_rectangle

draw_rectangle(
    x, y, width, height, color=None, refresh=None
)

Draw a rectangle.

Parameters:

Name	Type	Description	Default
x	int	Horizontal location of the top left corner of the rectangle.	required
y	int	Vertical location of the top left corner of the rectangle.	required
width	int	The width of the rectangle.	required
height	int	The height of the rectangle.	required
color	Color | None	The color to draw the rectangle in.	None
refresh	bool | None	Should the widget be refreshed?	None

Returns:

Type	Description
Self	The canvas.

Note

The origin of the canvas is the top left corner.

get_pixel

get_pixel(x, y)

Get the pixel at the given location.

Parameters:

Name	Type	Description	Default
x	int	The horizontal location of the pixel.	required
y	int	The vertical location of the pixel.	required

Returns:

Type	Description
Color	The colour of the pixel at that location.

Raises:

Type	Description
CanvasError	If the pixel location is not within the canvas.

Note

The origin of the canvas is the top left corner.

set_pen

set_pen(color)

Set the default pen colour.

Parameters:

Name	Type	Description	Default
color	Color | None	A colour to use by default when drawing a pixel.	required

Returns:

Type	Description
Self	The canvas.

Note

Setting the colour to None specifies that the widget's currently-styled color should be used.

set_pixel

set_pixel(x, y, color=None, refresh=None)

Set the colour of a specific pixel on the canvas.

Parameters:

Name	Type	Description	Default
x	int	The horizontal location of the pixel.	required
y	int	The vertical location of the pixel.	required
color	Color | None	The color to set the pixel to.	None
refresh	bool | None	Should the widget be refreshed?	None

Raises:

Type	Description
CanvasError	If the pixel location is not within the canvas.

Note

The origin of the canvas is the top left corner.

set_pixels

set_pixels(locations, color=None, refresh=None)

Set the colour of a collection of pixels on the canvas.

Parameters:

Name	Type	Description	Default
locations	Iterable[tuple[int, int]]	An iterable of tuples of x and y location.	required
color	Color | None	The color to set the pixel to.	None
refresh	bool | None	Should the widget be refreshed?	None

Returns:

Type	Description
Self	The canvas.

Raises:

Type	Description
CanvasError	If any pixel location is not within the canvas.

Note

The origin of the canvas is the top left corner.

CanvasError

Bases: Exception

Type of errors raised by the Canvas widget.