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.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")
>>> turtle.stamp()
11
>>> 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):
...     turtle.stamp(); turtle.fd(30)
13
14
15
16
17
18
19
20
>>> 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()

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

>>> 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.

turtle.exitonclick()

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

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

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