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()

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

while True:
    forward(200)
    left(170)
    if abs(pos()) < 1:
        break

abs(pos()) < 1 — удобный способ узнать, что черепаха вернулась в начальную позицию.

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

end_fill()

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

Как можно быстрее приступить к работе

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

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

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

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

Использование пространства имён модуля 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(size=None, *color)

Параметры:

• 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.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 в список фигур Screen и используйте его:

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

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

turtle.bgcolor(*args)

Параметры:

args – строка с названием цвета, три числа в диапазоне 0..colormode или 3-кортеж из таких чисел

Установить или вернуть цвет фона TurtleScreen.

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

turtle.bgpic(picname=None)

Параметры:

picname – строка, имя GIF-файла или "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.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 с событием отпускания клавиши. Если 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 с событием нажатия указанной клавиши или, если клавиша не задана, с событием нажатия любой клавиши. Примечание: для регистрации событий клавиатуры 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()

Запускает цикл обработки событий — вызывает функцию Tkinter mainloop. Должен быть последней инструкцией в программе с графикой черепашки. Не должен использоваться, если скрипт запущен из 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, если эти значения заданы. Если условие не выполнено, выводится подсказка, а диалог остаётся открытым для исправления. Вернуть введённое число. Если диалог отменён, вернуть 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 Turtle. Режим “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()

Вернуть холст этого TurtleScreen. Полезно для опытных пользователей, которые знают, что делать с холстом 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 — имя GIF-файла, а shape — None: установить соответствующую форму-изображение.

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

   Примечание

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

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

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

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

Добавить форму черепашки в список форм TurtleScreen. Использовать можно только зарегистрированные таким образом формы, вызвав команду shape(shapename).

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 (значение по умолчанию), также запустить mainloop. Примечание: при использовании IDLE с переключателем -n (без подпроцесса) это значение следует установить в True в turtle.cfg. В этом случае собственный цикл mainloop IDLE также активен для клиентского скрипта.

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 всплывающие подсказки отображают сигнатуры и первые строки строк документации для вводимых вызовов функций и методов.

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

  >>> 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()
  

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

  >>> 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()
  

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

Перевод строк документации на разные языки

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

turtle.write_docstringdict(filename='turtle_docstringdict')

Параметры:

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

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

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

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

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

Как настроить Screen и Turtle

Встроенная конфигурация по умолчанию имитирует внешний вид и поведение старого модуля 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, при импорте будет загружен словарь строк документации turtle_docstringdict_italian.py (если он есть в пути импорта, например в том же каталоге, что и turtle).
• Записи exampleturtle и examplescreen задают имена этих объектов, используемые в строках документации. При преобразовании строк документации методов в строки документации функций эти имена удаляются.
• using_IDLE: задайте значение True, если вы регулярно работаете в IDLE с переключателем -n («без подпроцесса»). Это предотвратит вход в главный цикл при вызове exitonclick().

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

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