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 *. Такой подход описан в руководстве по черепашьей графике.

Стоит отметить, что у многих команд turtle есть еще более короткие эквиваленты, например 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 или кортеж из трёх таких чисел

Установить или вернуть цвет фона 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 с событием отпускания клавиши 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()

Запустить цикл обработки событий — вызвать функцию 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, введённое число должно находиться в диапазоне 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 — имя 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() со щелчками мыши на Screen.

Если значение «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 подробно документированы с помощью строк документации. Поэтому их можно использовать как интерактивную справку средствами 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 с указанным именем файла. Эту функцию нужно вызывать явно (она не используется классами графики черепахи). Словарь строк документации будет записан в скрипт 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. Вы можете изучить его как пример и посмотреть, как он влияет на работу демонстраций (желательно запускать их не из средства просмотра демонстраций).