turtle — графика черепашки

Запуск среды черепашки

В оболочке Python импортируйте все объекты модуля turtle:

from turtle import *

Если возникнет ошибка No module named '_tkinter', вам придётся установить в своей системе Tk interface package.

Основы рисования

Переместите черепашку вперёд на 100 шагов:

forward(100)

Вы должны увидеть линию, нарисованную черепашкой в восточном направлении (скорее всего, в новом окне на экране). Измените направление черепашки, повернув её на 120 градусов влево (против часовой стрелки):

left(120)

Продолжим и нарисуем треугольник:

forward(100)
left(120)
forward(100)

Обратите внимание, как черепашка, изображённая в виде стрелки, указывает в разные стороны, когда вы управляете ею.

Поэкспериментируйте с этими командами, а также с backward() и right().

home()

pos()

clearscreen()

Создание алгоритмических узоров

С помощью циклов можно создавать геометрические узоры:

for steps in range(100):
    for c in ('blue', 'red', 'green'):
        color(c)
        forward(steps)
        right(30)

— разумеется, их ограничивает только воображение!

Давайте нарисуем звезду в верхней части этой страницы. Нам нужны красные линии с жёлтой заливкой:

color('red')
fillcolor('yellow')

Подобно тому как up() и down() определяют, будут ли рисоваться линии, заливку можно включать и выключать:

begin_fill()

Теперь создадим цикл:

start = pos()

while True:
    forward(200)
    left(170)
    if distance(start) < 1:
        break

distance(start) < 1 — хороший способ узнать, когда черепашка вернулась в исходную позицию.

Наконец, завершим заливку:

end_fill()

(Обратите внимание: заливка выполняется только при вызове команды end_fill().)

Начните как можно быстрее

Одно из преимуществ графики черепашки — мгновенная наглядная обратная связь, которую дают простые команды. Это отличный способ познакомить детей с идеями программирования, затратив минимум усилий (конечно, не только детей).

Модуль turtle делает это возможным, предоставляя все основные функции в виде функций, доступных с помощью from turtle import *. Такой подход описан в учебном пособии по графике черепашки.

Стоит отметить, что у многих команд черепашки есть ещё более краткие варианты, например fd() вместо forward(). Они особенно полезны при обучении тех, кто ещё не умеет печатать.

Для работы графики черепашки в вашей системе должен быть установлен Tk interface package. Имейте в виду, что установить его бывает непросто, поэтому проверьте это заранее, если планируете знакомить учащихся с графикой черепашки.

Автоматическое начало и завершение заливки

Начиная с Python 3.14, вы можете использовать fill() в качестве менеджера контекста вместо begin_fill() и end_fill(), чтобы автоматически начинать и завершать заливку. Пример:

with fill():
    for i in range(4):
        forward(100)
        right(90)

forward(200)

Приведённый выше код эквивалентен следующему:

begin_fill()
for i in range(4):
    forward(100)
    right(90)
end_fill()

forward(200)

Использование пространства имён модуля turtle

Использовать from turtle import * удобно, но учтите: при этом импортируется довольно много объектов, и, если вы занимаетесь чем-либо, кроме графики черепашки, есть риск конфликта имён (это особенно актуально, если вы используете графику черепашки в скрипте, который может импортировать другие модули).

Решение — использовать import turtle: fd() станет turtle.fd(), width() станет turtle.width() и так далее. (Если многократный ввод «turtle» утомляет, используйте, например, import turtle as t.)

Использование графики черепашки в скрипте

Рекомендуется использовать пространство имён модуля turtle, как описано выше. Например:

import turtle as t
from random import random

for i in range(100):
    steps = int(random() * 100)
    angle = int(random() * 360)
    t.right(angle)
    t.fd(steps)

Однако потребуется сделать ещё один шаг: как только скрипт завершится, Python также закроет окно черепашки. Добавьте:

t.mainloop()

в конец скрипта. Теперь скрипт будет ждать закрытия окна и не завершится, пока его не остановят, например закрыв окно графики черепашки.

Использование объектно-ориентированной графики черепашки

Если речь не идёт о самых простых ознакомительных примерах или о том, чтобы как можно быстрее опробовать команды, обычно удобнее и значительно эффективнее использовать объектно-ориентированный подход к графике черепашки. Например, он позволяет одновременно отображать на экране нескольких черепашек.

В этом подходе различные команды черепашки являются методами объектов (в основном объектов Turtle). Объектно-ориентированный подход можно использовать в оболочке, но чаще его применяют в скриптах Python.

Таким образом, приведённый выше пример будет выглядеть так:

from turtle import Turtle
from random import random

t = Turtle()
for i in range(100):
    steps = int(random() * 100)
    angle = int(random() * 360)
    t.right(angle)
    t.fd(steps)

t.screen.mainloop()

Обратите внимание на последнюю строку. t.screen — это экземпляр Screen, в котором существует экземпляр Turtle; он создаётся автоматически вместе с черепашкой.

Экран черепашки можно настроить, например, так:

t.screen.title('Object-oriented turtle demo')
t.screen.bgcolor("orange")

Методы Turtle

Перемещение черепашки

Перемещение и рисование

Определение состояния черепашки

Настройка и измерение

Управление пером

Состояние рисования

Управление цветом

Заливка

Дополнительные параметры рисования

Состояние черепашки

Видимость

Внешний вид

Использование событий

Специальные методы Turtle

Методы TurtleScreen/Screen

Управление окном

Управление анимацией

Использование событий экрана

Настройки и специальные методы

Методы ввода

Методы, относящиеся только к Screen

Перемещение черепахи

turtle.forward(distance)

turtle.fd(distance)

Параметры:

distance – число (целое или с плавающей точкой)

Переместить черепаху вперёд на указанное расстояние distance в направлении её движения.

>>> turtle.position()
(0.00,0.00)
>>> turtle.forward(25)
>>> turtle.position()
(25.00,0.00)
>>> turtle.forward(-75)
>>> turtle.position()
(-50.00,0.00)

turtle.back(distance)

turtle.bk(distance)

turtle.backward(distance)

Параметры:

distance – число

Переместить черепаху назад на расстояние distance, в направлении, противоположном её движению. Не менять направление черепахи.

>>> turtle.position()
(0.00,0.00)
>>> turtle.backward(30)
>>> turtle.position()
(-30.00,0.00)

turtle.right(angle)

turtle.rt(angle)

Параметры:

angle – число (целое или с плавающей точкой)

Повернуть черепаху вправо на angle единиц. (По умолчанию единицы измеряются в градусах, но их можно задать с помощью функций degrees() и radians().) Ориентация угла зависит от режима черепахи; см. mode().

>>> turtle.heading()
22.0
>>> turtle.right(45)
>>> turtle.heading()
337.0

turtle.left(angle)

turtle.lt(angle)

Параметры:

angle – число (целое или с плавающей точкой)

Повернуть черепаху влево на angle единиц. (По умолчанию единицы измеряются в градусах, но их можно задать с помощью функций degrees() и radians().) Ориентация угла зависит от режима черепахи; см. mode().

>>> turtle.heading()
22.0
>>> turtle.left(45)
>>> turtle.heading()
67.0

turtle.goto(x, y=None)

turtle.setpos(x, y=None)

turtle.setposition(x, y=None)

Параметры:

• x – число или пара/вектор чисел
• y – число или None

Если y — None, x должен быть парой координат или Vec2D (например, полученным с помощью pos()).

Переместить черепаху в абсолютную позицию. Если перо опущено, нарисовать линию. Не менять ориентацию черепахи.

>>> tp = turtle.pos()
>>> tp
(0.00,0.00)
>>> turtle.setpos(60,30)
>>> turtle.pos()
(60.00,30.00)
>>> turtle.setpos((20,80))
>>> turtle.pos()
(20.00,80.00)
>>> turtle.setpos(tp)
>>> turtle.pos()
(0.00,0.00)

turtle.teleport(x, y=None, *, fill_gap=False)

Параметры:

• x – число или None
• y – число или None
• fill_gap – логическое значение

Переместить черепаху в абсолютную позицию. В отличие от goto(x, y), линия не будет нарисована. Ориентация черепахи не изменится. Если в данный момент выполняется заливка, многоугольник или многоугольники, из которых черепаха телепортируется, будут залиты после её ухода, а после телепортации заливка начнётся снова. Это поведение можно отключить с помощью fill_gap=True: во время телепортации воображаемая линия будет служить границей заливки, как при goto(x, y).

>>> tp = turtle.pos()
>>> tp
(0.00,0.00)
>>> turtle.teleport(60)
>>> turtle.pos()
(60.00,0.00)
>>> turtle.teleport(y=10)
>>> turtle.pos()
(60.00,10.00)
>>> turtle.teleport(20, 30)
>>> turtle.pos()
(20.00,30.00)

Добавлено в версии 3.12.

turtle.setx(x)

Параметры:

x – число (целое или с плавающей точкой)

Установить первую координату черепахи равной x, оставив вторую координату без изменений.

>>> turtle.position()
(0.00,240.00)
>>> turtle.setx(10)
>>> turtle.position()
(10.00,240.00)

turtle.sety(y)

Параметры:

y – число (целое или с плавающей точкой)

Установить вторую координату черепахи равной y, оставив первую координату без изменений.

>>> turtle.position()
(0.00,40.00)
>>> turtle.sety(-10)
>>> turtle.position()
(0.00,-10.00)

turtle.setheading(to_angle)

turtle.seth(to_angle)

Параметры:

to_angle – число (целое или с плавающей точкой)

Установить ориентацию черепахи равной to_angle. Ниже приведены некоторые распространённые направления в градусах:

стандартный режим	режим Logo
0 — восток	0 — север
90 — север	90 — восток
180 — запад	180 — юг
270 — юг	270 — запад

>>> turtle.setheading(90)
>>> turtle.heading()
90.0

turtle.home()

Переместить черепаху в начало координат — точку (0,0) — и установить её направление в исходную ориентацию (зависящую от режима; см. mode()).

>>> turtle.heading()
90.0
>>> turtle.position()
(0.00,-10.00)
>>> turtle.home()
>>> turtle.position()
(0.00,0.00)
>>> turtle.heading()
0.0

turtle.circle(radius, extent=None, steps=None)

Параметры:

• radius – число
• extent – число (или None)
• steps – целое число (или None)

Нарисовать окружность заданного радиуса radius. Её центр находится на расстоянии radius единиц слева от черепахи; extent — угол — определяет, какая часть окружности будет нарисована. Если extent не задан, нарисовать всю окружность. Если extent не равен полной окружности, один конец дуги совпадает с текущим положением пера. Нарисовать дугу против часовой стрелки, если radius положителен, иначе — по часовой стрелке. В завершение направление черепахи изменяется на величину extent.

Поскольку окружность аппроксимируется вписанным правильным многоугольником, параметр steps задаёт количество используемых шагов. Если он не указан, его значение вычисляется автоматически. Можно использовать для рисования правильных многоугольников.

>>> turtle.home()
>>> turtle.position()
(0.00,0.00)
>>> turtle.heading()
0.0
>>> turtle.circle(50)
>>> turtle.position()
(-0.00,0.00)
>>> turtle.heading()
0.0
>>> turtle.circle(120, 180)  # draw a semicircle
>>> turtle.position()
(0.00,240.00)
>>> turtle.heading()
180.0

turtle.dot()

turtle.dot(size)

turtle.dot(color, /)

turtle.dot(size, color, /)

turtle.dot(size, r, g, b, /)

Параметры:

• size – целое число >= 1 (если задано)
• color – строка с обозначением цвета или числовой кортеж цвета

Нарисовать круговую точку диаметром size, используя цвет color. Если size не задан, используется максимум из pensize+4 и 2*pensize.

>>> turtle.home()
>>> turtle.dot()
>>> turtle.fd(50); turtle.dot(20, "blue"); turtle.fd(50)
>>> turtle.position()
(100.00,-0.00)
>>> turtle.heading()
0.0

turtle.stamp()

Поставить на холсте отпечаток фигуры черепахи в её текущем положении. Вернуть stamp_id этого отпечатка; его можно удалить вызовом clearstamp(stamp_id).

>>> turtle.color("blue")
>>> stamp_id = turtle.stamp()
>>> turtle.fd(50)

turtle.clearstamp(stampid)

Параметры:

stampid – целое число; должно быть значением, возвращённым предыдущим вызовом stamp()

Удалить отпечаток с указанным stampid.

>>> turtle.position()
(150.00,-0.00)
>>> turtle.color("blue")
>>> astamp = turtle.stamp()
>>> turtle.fd(50)
>>> turtle.position()
(200.00,-0.00)
>>> turtle.clearstamp(astamp)
>>> turtle.position()
(200.00,-0.00)

turtle.clearstamps(n=None)

Параметры:

n – целое число (или None)

Удалить все отпечатки черепахи или первые/последние n отпечатков. Если n равно None, удалить все отпечатки; если n > 0, удалить первые n отпечатков, иначе, если n < 0, удалить последние n отпечатков.

>>> for i in range(8):
...     unused_stamp_id = turtle.stamp()
...     turtle.fd(30)
>>> turtle.clearstamps(2)
>>> turtle.clearstamps(-2)
>>> turtle.clearstamps()

turtle.undo()

Отменить (повторно) последнее действие или последние действия черепахи. Количество доступных действий отмены определяется размером буфера отмены.

>>> for i in range(4):
...     turtle.fd(50); turtle.lt(80)
...
>>> for i in range(8):
...     turtle.undo()

turtle.speed(speed=None)

Параметры:

speed – целое число в диапазоне 0..10 или строковое значение скорости (см. ниже)

Установить скорость черепахи в виде целого значения в диапазоне 0..10. Если аргумент не указан, вернуть текущую скорость.

Если задано число больше 10 или меньше 0.5, скорость устанавливается равной 0. Строковые значения скорости преобразуются в значения скорости следующим образом:

• “fastest”: 0
• “fast”: 10
• “normal”: 6
• “slow”: 3
• “slowest”: 1

Скорости от 1 до 10 обеспечивают всё более быструю анимацию рисования линий и поворотов черепахи.

Внимание: speed = 0 означает, что анимация не выполняется. Команды forward/back перемещают черепаху скачком, а left/right мгновенно поворачивают её.

>>> turtle.speed()
3
>>> turtle.speed('normal')
>>> turtle.speed()
6
>>> turtle.speed(9)
>>> turtle.speed()
9

Сведения о состоянии черепахи

turtle.position()

turtle.pos()

Вернуть текущее положение черепахи (x,y) в виде вектора Vec2D.

>>> turtle.pos()
(440.00,-0.00)

turtle.towards(x, y=None)

Параметры:

• x – число, пара/вектор чисел или экземпляр черепахи
• y – число, если x — число, иначе None

Вернуть угол между линией от положения черепахи до положения, заданного координатами (x,y), вектором или другой черепахой. Значение зависит от исходной ориентации черепахи, которая определяется режимом — “standard”/”world” или “logo”.

>>> turtle.goto(10, 10)
>>> turtle.towards(0,0)
225.0

turtle.xcor()

Вернуть координату x черепахи.

>>> turtle.home()
>>> turtle.left(50)
>>> turtle.forward(100)
>>> turtle.pos()
(64.28,76.60)
>>> print(round(turtle.xcor(), 5))
64.27876

turtle.ycor()

Вернуть координату y черепахи.

>>> turtle.home()
>>> turtle.left(60)
>>> turtle.forward(100)
>>> print(turtle.pos())
(50.00,86.60)
>>> print(round(turtle.ycor(), 5))
86.60254

turtle.heading()

Вернуть текущее направление черепахи (значение зависит от режима черепахи; см. mode()).

>>> turtle.home()
>>> turtle.left(67)
>>> turtle.heading()
67.0

turtle.distance(x, y=None)

Параметры:

• x – число, пара/вектор чисел или экземпляр черепахи
• y – число, если x — число, иначе None

Вернуть расстояние от черепахи до точки (x,y), заданного вектора или другой указанной черепахи в единицах шага черепахи.

>>> turtle.home()
>>> turtle.distance(30,40)
50.0
>>> turtle.distance((30,40))
50.0
>>> joe = Turtle()
>>> joe.forward(77)
>>> turtle.distance(joe)
77.0

Настройки измерений

turtle.degrees(fullcircle=360.0)

Параметры:

fullcircle – число

Задать единицы измерения углов, то есть количество «градусов» в полной окружности. Значение по умолчанию — 360 градусов.

>>> turtle.home()
>>> turtle.left(90)
>>> turtle.heading()
90.0

>>> # Change angle measurement unit to grad (also known as gon,
>>> # grade, or gradian and equals 1/100-th of the right angle.)
>>> turtle.degrees(400.0)
>>> turtle.heading()
100.0
>>> turtle.degrees(360)
>>> turtle.heading()
90.0

turtle.radians()

Установить радианы в качестве единиц измерения углов. Эквивалентно degrees(2*math.pi).

>>> turtle.home()
>>> turtle.left(90)
>>> turtle.heading()
90.0
>>> turtle.radians()
>>> turtle.heading()
1.5707963267948966

Управление пером

Состояние черепахи

Обработка событий

turtle.onclick(fun, btn=1, add=None)

Параметры:

• fun — функция с двумя аргументами, которая будет вызвана с координатами точки щелчка на холсте
• btn — номер кнопки мыши, по умолчанию 1 (левая кнопка мыши)
• add — True или False — если True, будет добавлена новая привязка, иначе она заменит предыдущую

Привязывает fun к событиям щелчка мышью по этой черепахе. Если fun — None, существующие привязки удаляются. Пример для анонимной черепахи, то есть процедурный способ:

>>> def turn(x, y):
...     left(180)
...
>>> onclick(turn)  # Now clicking into the turtle will turn it.
>>> onclick(None)  # event-binding will be removed

turtle.onrelease(fun, btn=1, add=None)

Параметры:

• fun — функция с двумя аргументами, которая будет вызвана с координатами точки щелчка на холсте
• btn — номер кнопки мыши, по умолчанию 1 (левая кнопка мыши)
• add — True или False — если True, будет добавлена новая привязка, иначе она заменит предыдущую

Привязывает fun к событиям отпускания кнопки мыши над этой черепахой. Если fun — None, существующие привязки удаляются.

>>> class MyTurtle(Turtle):
...     def glow(self,x,y):
...         self.fillcolor("red")
...     def unglow(self,x,y):
...         self.fillcolor("")
...
>>> turtle = MyTurtle()
>>> turtle.onclick(turtle.glow)     # clicking on turtle turns fillcolor red,
>>> turtle.onrelease(turtle.unglow) # releasing turns it to transparent.

turtle.ondrag(fun, btn=1, add=None)

Параметры:

• fun — функция с двумя аргументами, которая будет вызвана с координатами точки щелчка на холсте
• btn — номер кнопки мыши, по умолчанию 1 (левая кнопка мыши)
• add — True или False — если True, будет добавлена новая привязка, иначе она заменит предыдущую

Привязывает fun к событиям перемещения мыши над этой черепахой. Если fun — None, существующие привязки удаляются.

Примечание: каждой последовательности событий перемещения мыши над черепахой предшествует событие щелчка мышью по этой черепахе.

>>> turtle.ondrag(turtle.goto)

После этого щелчок и перетаскивание черепахи будут перемещать её по экрану, позволяя рисовать от руки (если перо опущено).

Специальные методы Turtle

turtle.poly()

Записывает вершины многоугольника, нарисованного в блоке with turtle.poly():. Первая и последняя вершины будут соединены.

>>> with turtle.poly():
...     turtle.forward(100)
...     turtle.right(60)
...     turtle.forward(100)

Добавлено в версии 3.14.

turtle.begin_poly()

Начинает запись вершин многоугольника. Текущая позиция черепахи становится первой вершиной многоугольника.

turtle.end_poly()

Останавливает запись вершин многоугольника. Текущая позиция черепахи становится последней вершиной многоугольника. Она будет соединена с первой вершиной.

turtle.get_poly()

Возвращает последний записанный многоугольник.

>>> turtle.home()
>>> turtle.begin_poly()
>>> turtle.fd(100)
>>> turtle.left(20)
>>> turtle.fd(30)
>>> turtle.left(60)
>>> turtle.fd(50)
>>> turtle.end_poly()
>>> p = turtle.get_poly()
>>> register_shape("myFavouriteShape", p)

turtle.clone()

Создаёт и возвращает копию черепахи с теми же положением, направлением и свойствами.

>>> mick = Turtle()
>>> joe = mick.clone()

turtle.getturtle()

turtle.getpen()

Возвращает сам объект Turtle. Единственное разумное применение — использовать его как функцию для возврата «анонимной черепахи»:

>>> pet = getturtle()
>>> pet.fd(50)
>>> pet
<turtle.Turtle object at 0x...>

turtle.getscreen()

Возвращает объект TurtleScreen, на котором черепаха рисует. После этого для данного объекта можно вызывать методы TurtleScreen.

>>> ts = turtle.getscreen()
>>> ts
<turtle._Screen object at 0x...>
>>> ts.bgcolor("pink")

turtle.setundobuffer(size)

Параметры:

size — целое число или None

Задаёт или отключает буфер отмены действий. Если size — целое число, создаётся пустой буфер отмены указанного размера. size задаёт максимальное количество действий черепахи, которые можно отменить с помощью метода/функции undo(). Если size — None, буфер отмены отключается.

>>> turtle.setundobuffer(42)

turtle.undobufferentries()

Возвращает количество записей в буфере отмены.

>>> while undobufferentries():
...     undo()

Составные фигуры

Чтобы использовать составные фигуры черепахи, состоящие из нескольких многоугольников разных цветов, необходимо явно использовать вспомогательный класс Shape, как описано ниже:

1. Создайте пустой объект Shape типа «compound».

2. Добавьте к этому объекту нужное количество компонентов с помощью метода addcomponent().

   Например:

   >>> s = Shape("compound")
   >>> poly1 = ((0,0),(10,-5),(0,10),(-10,-5))
   >>> s.addcomponent(poly1, "red", "blue")
   >>> poly2 = ((0,0),(10,-5),(-10,-5))
   >>> s.addcomponent(poly2, "blue", "red")
   

3. Теперь добавьте Shape в список фигур экрана и используйте его:

   >>> register_shape("myshape", s)
   >>> shape("myshape")
   

Управление окном

turtle.bgcolor()

turtle.bgcolor(color, /)

turtle.bgcolor(r, g, b, /)

Возвращает или задаёт цвет фона TurtleScreen.

Допускаются четыре формата ввода:

bgcolor()

Возвращает текущий цвет фона в виде строки спецификации цвета или кортежа (см. пример). Может использоваться в качестве аргумента другого вызова color/pencolor/fillcolor/bgcolor.

bgcolor(colorstring)

Задаёт цвет фона равным colorstring — строке спецификации цвета Tk, например "red", "yellow" или "#33cc8c".

bgcolor((r, g, b))

Задаёт цвет фона как цвет RGB, представленный кортежем из значений r, g и b. Каждое из значений r, g и b должно находиться в диапазоне 0..colormode, где colormode равен 1.0 или 255 (см. colormode()).

bgcolor(r, g, b)

Задаёт цвет фона как цвет RGB, представленный значениями r, g и b. Каждое из значений r, g и b должно находиться в диапазоне 0..colormode.

>>> screen.bgcolor("orange")
>>> screen.bgcolor()
'orange'
>>> screen.bgcolor("#800080")
>>> screen.bgcolor()
(128.0, 0.0, 128.0)

turtle.bgpic(picname=None)

Параметры:

picname — строка, имя файла изображения (PNG, GIF, PGM и PPM), "nopic" или None

Задаёт фоновое изображение или возвращает имя текущего фонового изображения. Если picname — имя файла, соответствующее изображение задаётся в качестве фона. Если picname равен "nopic", фоновое изображение удаляется, если оно есть. Если picname равен None, возвращается имя файла текущего фонового изображения.

>>> screen.bgpic()
'nopic'
>>> screen.bgpic("landscape.gif")
>>> screen.bgpic()
"landscape.gif"

turtle.clear()

Примечание

Этот метод TurtleScreen доступен как глобальная функция только под именем clearscreen. Глобальная функция clear — другая функция, производная от метода Turtle clear.

turtle.clearscreen()

Удаляет все рисунки и всех черепах с TurtleScreen. Сбрасывает пустой теперь TurtleScreen в исходное состояние: белый фон, без фонового изображения, без привязок событий и с включённой трассировкой.

turtle.reset()

Примечание

Этот метод TurtleScreen доступен как глобальная функция только под именем resetscreen. Глобальная функция reset — другая функция, производная от метода Turtle reset.

turtle.resetscreen()

Сбрасывает всех черепах на экране в исходное состояние.

turtle.screensize(canvwidth=None, canvheight=None, bg=None)

Параметры:

• canvwidth — положительное целое число, новая ширина холста в пикселях
• canvheight — положительное целое число, новая высота холста в пикселях
• bg — строка спецификации цвета или кортеж цвета, новый цвет фона

Если аргументы не заданы, возвращает текущие значения (canvaswidth, canvasheight). В противном случае изменяет размер холста, на котором рисуют черепахи. Размер окна рисования не изменяется. Чтобы увидеть скрытые части холста, используйте полосы прокрутки. С помощью этого метода можно сделать видимыми те части рисунка, которые раньше находились за пределами холста.

>>> screen.screensize()
(400, 300)
>>> screen.screensize(2000,1500)
>>> screen.screensize()
(2000, 1500)

например, чтобы найти случайно сбежавшую черепаху ;-)

turtle.setworldcoordinates(llx, lly, urx, ury)

Параметры:

• llx — число, координата x левого нижнего угла холста
• lly — число, координата y левого нижнего угла холста
• urx — число, координата x правого верхнего угла холста
• ury — число, координата y правого верхнего угла холста

Задаёт пользовательскую систему координат и при необходимости переключает режим на «world». При этом выполняется screen.reset(). Если режим «world» уже активен, все рисунки перерисовываются в соответствии с новыми координатами.

ВНИМАНИЕ: в пользовательских системах координат углы могут выглядеть искажёнными.

>>> screen.reset()
>>> screen.setworldcoordinates(-50,-7.5,50,7.5)
>>> for _ in range(72):
...     left(10)
...
>>> for _ in range(8):
...     left(45); fd(2)   # a regular octagon

Управление анимацией

turtle.no_animation()

Временно отключает анимацию черепахи. Код, записанный внутри блока no_animation, не будет анимироваться; после выхода из блока кода рисунок появится.

>>> with screen.no_animation():
...     for dist in range(2, 400, 2):
...         fd(dist)
...         rt(90)

Добавлено в версии 3.14.

turtle.delay(delay=None)

Параметры:

delay — положительное целое число

Задаёт или возвращает задержку рисования в миллисекундах. (Это приблизительный интервал времени между двумя последовательными обновлениями холста.) Чем больше задержка рисования, тем медленнее анимация.

Необязательный аргумент:

>>> screen.delay()
10
>>> screen.delay(5)
>>> screen.delay()
5

turtle.tracer(n=None, delay=None)

Параметры:

• n — неотрицательное целое число
• delay — неотрицательное целое число

Включает или отключает анимацию черепахи и задаёт задержку обновления рисунков. Если задано n, фактически выполняется только каждое n-е обычное обновление экрана. (Это можно использовать для ускорения рисования сложной графики.) При вызове без аргументов возвращает текущее сохранённое значение n. Второй аргумент задаёт значение задержки (см. delay()).

>>> screen.tracer(8, 25)
>>> dist = 2
>>> for i in range(200):
...     fd(dist)
...     rt(90)
...     dist += 2

turtle.update()

Выполняет обновление TurtleScreen. Используется, когда трассировка отключена.

См. также метод RawTurtle/Turtle speed().

Использование событий экрана

turtle.listen(xdummy=None, ydummy=None)

Устанавливает фокус на TurtleScreen (для получения событий клавиатуры). Предусмотрены фиктивные аргументы, чтобы можно было передать listen() методу onclick.

turtle.onkey(fun, key)

turtle.onkeyrelease(fun, key)

Параметры:

• fun — функция без аргументов или None
• key — строка: клавиша (например, «a») или символ клавиши (например, «space»)

Привязывает fun к событию отпускания клавиши key. Если fun равен None, привязки событий удаляются. Примечание: чтобы регистрировать события клавиатуры, TurtleScreen должен иметь фокус. (См. метод listen().)

>>> def f():
...     fd(50)
...     lt(60)
...
>>> screen.onkey(f, "Up")
>>> screen.listen()

turtle.onkeypress(fun, key=None)

Параметры:

• fun — функция без аргументов или None
• key — строка: клавиша (например, «a») или символ клавиши (например, «space»)

Привязывает fun к событию нажатия клавиши key, если клавиша задана, или к событию нажатия любой клавиши, если клавиша не задана. Примечание: чтобы регистрировать события клавиатуры, TurtleScreen должен иметь фокус. (См. метод listen().)

>>> def f():
...     fd(50)
...
>>> screen.onkey(f, "Up")
>>> screen.listen()

turtle.onclick(fun, btn=1, add=None)

turtle.onscreenclick(fun, btn=1, add=None)

Параметры:

• fun — функция с двумя аргументами, которая будет вызвана с координатами точки щелчка на холсте
• btn — номер кнопки мыши; по умолчанию 1 (левая кнопка мыши)
• add — True или False — если True, будет добавлена новая привязка, в противном случае она заменит прежнюю

Привязывает fun к событиям щелчка мышью на этом экране. Если fun равен None, существующие привязки удаляются.

Пример для экземпляра TurtleScreen с именем screen и экземпляра Turtle с именем turtle:

>>> screen.onclick(turtle.goto) # Subsequently clicking into the TurtleScreen will
>>>                             # make the turtle move to the clicked point.
>>> screen.onclick(None)        # remove event binding again

Примечание

Этот метод TurtleScreen доступен как глобальная функция только под именем onscreenclick. Глобальная функция onclick — другая функция, производная от метода Turtle onclick.

turtle.ontimer(fun, t=0)

Параметры:

• fun — функция без аргументов
• t — число >= 0

Устанавливает таймер, который вызывает fun через t миллисекунд.

>>> running = True
>>> def f():
...     if running:
...         fd(50)
...         lt(60)
...         screen.ontimer(f, 250)
>>> f()   ### makes the turtle march around
>>> running = False

turtle.mainloop()

turtle.done()

Запускает цикл обработки событий — вызывает функцию mainloop из Tkinter. Это должно быть последней инструкцией в программе для черепашьей графики. Не следует использовать её, если сценарий запускается из IDLE в режиме -n (без подпроцесса) — для интерактивной работы с черепашьей графикой.

>>> screen.mainloop()

Методы ввода

turtle.textinput(title, prompt)

Параметры:

• title — строка
• prompt — строка

Открывает диалоговое окно для ввода строки. Параметр title задаёт заголовок диалогового окна, prompt — текст, обычно поясняющий, какую информацию нужно ввести. Возвращает введённую строку. Если диалоговое окно отменено, возвращает None.

>>> screen.textinput("NIM", "Name of first player:")

turtle.numinput(title, prompt, default=None, minval=None, maxval=None)

Параметры:

• title — строка
• prompt — строка
• default — число (необязательно)
• minval — число (необязательно)
• maxval — число (необязательно)

Открывает диалоговое окно для ввода числа. title задаёт заголовок диалогового окна, prompt — текст, обычно поясняющий, какое числовое значение нужно ввести. default: значение по умолчанию, minval: минимальное значение для ввода, maxval: максимальное значение для ввода. Если заданы minval и maxval, введённое число должно находиться в диапазоне minval .. maxval. В противном случае выводится подсказка, а диалоговое окно остаётся открытым для исправления. Возвращает введённое число. Если диалоговое окно отменено, возвращает None.

>>> screen.numinput("Poker", "Your stakes:", 1000, minval=10, maxval=10000)

Настройки и специальные методы

turtle.mode(mode=None)

Параметры:

mode — одна из строк «standard», «logo» или «world»

Задаёт режим черепахи («standard», «logo» или «world») и выполняет сброс. Если режим не задан, возвращается текущий режим.

Режим «standard» совместим со старой версией turtle. Режим «logo» совместим с большинством вариантов черепашьей графики Logo. В режиме «world» используются пользовательские «мировые координаты». Внимание: в этом режиме углы выглядят искажёнными, если x/y соотношение единиц не равно 1.

Режим	Начальное направление черепахи	Положительные углы
«standard»	вправо (на восток)	против часовой стрелки
«logo»	вверх (на север)	по часовой стрелке

>>> mode("logo")   # resets turtle heading to north
>>> mode()
'logo'

turtle.colormode(cmode=None)

Параметры:

cmode — одно из значений 1.0 или 255

Возвращает режим цвета или задаёт его равным 1.0 или 255. В дальнейшем значения r, g, b в кортежах цветов должны находиться в диапазоне 0..*cmode*.

>>> screen.colormode(1)
>>> turtle.pencolor(240, 160, 80)
Traceback (most recent call last):
     ...
TurtleGraphicsError: bad color sequence: (240, 160, 80)
>>> screen.colormode()
1.0
>>> screen.colormode(255)
>>> screen.colormode()
255
>>> turtle.pencolor(240,160,80)

turtle.getcanvas()

Возвращает Canvas этого TurtleScreen. Полезно для опытных пользователей, которые знают, что делать с Canvas Tkinter.

>>> cv = screen.getcanvas()
>>> cv
<turtle.ScrolledCanvas object ...>

turtle.getshapes()

Возвращает список имён всех доступных в данный момент форм черепахи.

>>> screen.getshapes()
['arrow', 'blank', 'circle', ..., 'turtle']

turtle.register_shape(name, shape=None)

turtle.addshape(name, shape=None)

Эту функцию можно вызвать четырьмя разными способами:

1. name — имя файла изображения (PNG, GIF, PGM и PPM), а shape равен None: устанавливает соответствующую форму изображения.

   >>> screen.register_shape("turtle.gif")
   

   Примечание

   Формы изображений не поворачиваются при повороте черепахи, поэтому направление черепахи на них не отображается!

2. name — произвольная строка, а shape — имя файла изображения (PNG, GIF, PGM и PPM): устанавливает соответствующую форму изображения.

   >>> screen.register_shape("turtle", "turtle.gif")
   

   Примечание

   Формы изображений не поворачиваются при повороте черепахи, поэтому направление черепахи на них не отображается!

3. name — произвольная строка, а shape — кортеж пар координат: устанавливает соответствующую форму многоугольника.

   >>> screen.register_shape("triangle", ((5,-3), (0,5), (-5,-3)))
   

4. name — произвольная строка, а shape — объект Shape (составной формы): устанавливает соответствующую составную форму.

Добавляет форму черепахи в список форм TurtleScreen. Только зарегистрированные таким образом формы можно использовать с помощью команды shape(shapename).

Изменено в версии 3.14: Добавлена поддержка форматов изображений PNG, PGM и PPM. Можно указать как имя формы, так и имя файла изображения.

turtle.turtles()

Возвращает список черепах на экране.

>>> for turtle in screen.turtles():
...     turtle.color("red")

turtle.window_height()

Возвращает высоту окна черепахи.

>>> screen.window_height()
480

turtle.window_width()

Возвращает ширину окна черепахи.

>>> screen.window_width()
640

Методы, специфичные для Screen и не унаследованные от TurtleScreen

turtle.bye()

Закрывает окно черепашьей графики.

turtle.exitonclick()

Привязывает метод bye() к щелчкам мышью по экрану.

Если значение «using_IDLE» в словаре конфигурации равно False (значение по умолчанию), также запускается главный цикл обработки событий. Примечание: если используется IDLE с переключателем -n (без подпроцесса), это значение следует установить в True в turtle.cfg. В этом случае собственный главный цикл IDLE активен и для клиентского сценария.

turtle.save(filename, overwrite=False)

Сохраняет текущий рисунок черепахи (и черепах) в файл PostScript.

Параметры:

• filename — путь к сохраняемому файлу PostScript
• overwrite — если False и файл с указанным именем уже существует, функция вызовет исключение FileExistsError. Если значение равно True, файл будет перезаписан.

>>> screen.save("my_drawing.ps")
>>> screen.save("my_drawing.ps", overwrite=True)

Добавлено в версии 3.14.

turtle.setup(width=_CFG['width'], height=_CFG['height'], startx=_CFG['leftright'], starty=_CFG['topbottom'])

Задаёт размер и положение главного окна. Значения аргументов по умолчанию хранятся в словаре конфигурации и могут быть изменены с помощью файла turtle.cfg.

Параметры:

• width — целое число задаёт размер в пикселях, дробное число — долю экрана; по умолчанию 50% экрана
• height — целое число задаёт высоту в пикселях, дробное число — долю экрана; по умолчанию 75% экрана
• startx — если положительное, начальное положение в пикселях от левого края экрана; если отрицательное — от правого края; если None, окно располагается по центру горизонтально
• starty — если положительное, начальное положение в пикселях от верхнего края экрана; если отрицательное — от нижнего края; если None, окно располагается по центру вертикально

>>> screen.setup (width=200, height=200, startx=0, starty=0)
>>>              # sets window to 200x200 pixels, in upper left of screen
>>> screen.setup(width=.75, height=0.5, startx=None, starty=None)
>>>              # sets window to 75% of screen by 50% of screen and centers

turtle.title(titlestring)

Параметры:

titlestring — строка, отображаемая в заголовке окна черепашьей графики

Задаёт заголовок окна черепахи равным titlestring.

>>> screen.title("Welcome to the turtle zoo!")

Как пользоваться справкой

Общедоступные методы классов Screen и Turtle подробно документированы с помощью docstring. Поэтому их можно использовать в качестве онлайн-справки с помощью средств справки Python:

• При использовании IDLE во всплывающих подсказках отображаются сигнатуры и первые строки docstring вводимых вызовов функций и методов.

• Вызов help() для методов или функций отображает docstring:

  >>> help(Screen.bgcolor)
  Help on method bgcolor in module turtle:
  
  bgcolor(self, *args) unbound turtle.Screen method
      Set or return backgroundcolor of the TurtleScreen.
  
      Arguments (if given): a color string or three numbers
      in the range 0..colormode or a 3-tuple of such numbers.
  
  
      >>> screen.bgcolor("orange")
      >>> screen.bgcolor()
      "orange"
      >>> screen.bgcolor(0.5,0,0.5)
      >>> screen.bgcolor()
      "#800080"
  
  >>> help(Turtle.penup)
  Help on method penup in module turtle:
  
  penup(self) unbound turtle.Turtle method
      Pull the pen up -- no drawing when moving.
  
      Aliases: penup | pu | up
  
      No argument
  
      >>> turtle.penup()
  

• Docstring функций, производных от методов, имеют изменённую форму:

  >>> help(bgcolor)
  Help on function bgcolor in module turtle:
  
  bgcolor(*args)
      Set or return backgroundcolor of the TurtleScreen.
  
      Arguments (if given): a color string or three numbers
      in the range 0..colormode or a 3-tuple of such numbers.
  
      Example::
  
        >>> bgcolor("orange")
        >>> bgcolor()
        "orange"
        >>> bgcolor(0.5,0,0.5)
        >>> bgcolor()
        "#800080"
  
  >>> help(penup)
  Help on function penup in module turtle:
  
  penup()
      Pull the pen up -- no drawing when moving.
  
      Aliases: penup | pu | up
  
      No argument
  
      Example:
      >>> penup()
  

Эти изменённые docstring автоматически создаются во время импорта вместе с определениями функций, производных от методов.

Перевод docstring на разные языки

Существует утилита для создания словаря, в котором ключами служат имена методов, а значениями — docstring общедоступных методов классов Screen и Turtle.

turtle.write_docstringdict(filename='turtle_docstringdict')

Параметры:

filename – строка, используемая в качестве имени файла

Создаёт словарь docstring и записывает его в скрипт Python с указанным именем файла. Эту функцию необходимо вызывать явно (классы графики черепашки её не используют). Словарь docstring будет записан в скрипт Python filename.py. Он предназначен служить шаблоном для перевода docstring на разные языки.

Если вы (или ваши ученики) хотите использовать turtle с онлайн-справкой на родном языке, необходимо перевести docstring и сохранить полученный файл, например, как turtle_docstringdict_german.py.

Если в вашем файле turtle.cfg есть соответствующая запись, этот словарь будет прочитан во время импорта и заменит исходные английские docstring.

На момент написания этого текста существуют словари docstring на немецком и итальянском языках. (Пожелания и запросы отправляйте по адресу glingl@aon.at.)

Настройка Screen и черепашек

Встроенная конфигурация по умолчанию имитирует внешний вид и поведение старого модуля turtle, чтобы обеспечить максимально возможную совместимость с ним.

Если вы хотите использовать другую конфигурацию, которая лучше отражает возможности этого модуля или больше подходит для ваших нужд, например для занятий в классе, можно подготовить файл конфигурации turtle.cfg. Он будет прочитан во время импорта и изменит конфигурацию в соответствии с заданными параметрами.

Встроенная конфигурация соответствует следующему turtle.cfg:

width = 0.5
height = 0.75
leftright = None
topbottom = None
canvwidth = 400
canvheight = 300
mode = standard
colormode = 1.0
delay = 10
undobuffersize = 1000
shape = classic
pencolor = black
fillcolor = black
resizemode = noresize
visible = True
language = english
exampleturtle = turtle
examplescreen = screen
title = Python Turtle Graphics
using_IDLE = False

Краткие пояснения к некоторым параметрам:

• Первые четыре строки соответствуют аргументам метода Screen.setup.
• Строки 5 и 6 соответствуют аргументам метода Screen.screensize.
• shape может принимать любое из встроенных значений формы, например arrow, turtle и т. д. Дополнительную информацию можно получить с помощью help(shape).
• Чтобы не использовать цвет заливки (то есть сделать черепашку прозрачной), укажите fillcolor = "" (при этом все непустые строки в файле cfg должны быть без кавычек).
• Чтобы отображать состояние черепашки, необходимо использовать resizemode = auto.
• Если задать, например, language = italian, словарь docstring turtle_docstringdict_italian.py будет загружен во время импорта (если он есть в пути поиска модулей, например в том же каталоге, что и turtle).
• Параметры exampleturtle и examplescreen задают имена этих объектов, используемые в docstring. При преобразовании docstring методов в docstring функций эти имена удаляются.
• using_IDLE: задайте True, если вы регулярно работаете в IDLE с переключателем -n («no subprocess»). Это не позволит методу exitonclick() запускать главный цикл обработки событий.

Файл turtle.cfg может находиться в каталоге, где хранится turtle, а ещё один такой файл — в текущем рабочем каталоге. Настройки последнего переопределяют настройки первого.

Каталог Lib/turtledemo содержит файл turtle.cfg. Вы можете изучить его в качестве примера и посмотреть, как он влияет на работу демонстраций (желательно запускать их не из средства просмотра демонстраций).