turtle --- گرافیک لاک‌پشتی

کد منبع: Lib/turtle.py

مقدمه

گرافیک لاک‌پشتی، پیاده‌سازی ابزارهای محبوب ترسیم هندسی معرفی‌شده در Logo است که توسط Wally Feurzeig، Seymour Papert و Cynthia Solomon در ۱۹۶۷ توسعه‌یافته است.

این یک optional module است. اگر این ماژول در نسخه CPython شما موجود نیست، به مستندات توزیع‌کننده خود مراجعه کنید (یعنی هر کسی که پایتون را در اختیار شما قرار داده است). اگر شما توزیع‌کننده هستید، نیازمندی‌های ماژول‌های اختیاری را ببینید.

شروع کنید

تصور کنید یک لاک‌پشت رباتیک در نقطه‌ی (۰، ۰) در صفحه‌ی x-y قرار دارد. پس از import turtle، فرمان turtle.forward(15) را به آن بدهید، و ۱۵ پیکسل در جهتی که رو به آن دارد حرکت می‌کند (روی صفحه‌نمایش!) و در حین حرکت، سطری رسم می‌کند. فرمان turtle.right(25) را به آن بدهید، و ۲۵ درجه در جهت عقربه‌های ساعت درجا می‌چرخد.

در پایتون، گرافیک لاک‌پشتی یک بازنمایی از یک «لاک‌پشت» فیزیکی (یک ربات کوچک با قلم) ارائه می‌دهد که روی یک برگه کاغذ روی زمین ترسیم می‌کند.

این روشی مؤثر و کاملاً آزموده‌شده برای یادگیرندگان است تا با مفاهیم برنامه‌نویسی و تعامل با نرم‌افزار آشنا شوند، زیرا بازخوردی فوری و قابل‌مشاهده فراهم می‌کند. همچنین به‌طور کلی دسترسی آسانی به خروجی گرافیکی فراهم می‌کند.

رسم با Turtle در ابتدا به‌عنوان یک ابزار آموزشی ساخته شد تا معلمان در کلاس درس از آن استفاده کنند. برای برنامه‌نویسی که نیاز به تولید خروجی گرافیکی دارد، این می‌تواند راهی برای انجام این کار بدون سربار ناشی از وارد کردن کتابخانه‌های پیچیده‌تر یا خارجی به کارش باشد.

آموزش

کاربران تازه‌کار باید از اینجا شروع کنند. در این آموزش، برخی از مبانی ترسیم با turtle را بررسی می‌کنیم.

راه‌اندازی محیط turtle

در یک پوسته‌ی پایتون، همه‌ی اشیای ماژول turtle را ایمپورت کنید:

from turtle import *

اگر با خطای No module named '_tkinter' مواجه شدید، باید بسته‌ی رابط Tk را روی سیستم خود نصب کنید.

ترسیم مقدماتی

لاک‌پشت را ۱۰۰ گام به جلو بفرستید:

forward(100)

باید (به‌احتمال زیاد، در یک پنجره‌ی جدید روی نمایشگر شما) سطری را ببینید که لاک‌پشت آن را رو به شرق رسم کرده است. جهت لاک‌پشت را تغییر دهید تا ۱۲۰ درجه به چپ (خلاف جهت عقربه‌های ساعت) بچرخد:

left(120)

بیایید با رسم یک مثلث ادامه دهیم:

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

توجه کنید که چگونه لاک‌پشت، که با یک پیکان نمایش داده می‌شود، همان‌طور که آن را هدایت می‌کنید به جهت‌های مختلف اشاره می‌کند.

آن دستورات را آزمایش کنید، و همچنین backward() و right() را نیز آزمایش کنید.

کنترل قلم

تغییر رنگ - برای مثال، color('blue') - و پهنای خط - برای مثال، width(3) - و سپس رسم دوباره را امتحان کنید.

همچنین می‌توانید با بلند کردن قلم، لاک‌پشت را بدون رسم جابه‌جا کنید: پیش از جابه‌جایی up() را فراخوانی کنید. برای شروع دوباره‌ی رسم، از down() استفاده کنید.

موقعیت لاک‌پشت

لاک‌پشت خود را به نقطه آغازش بازگردانید (اگر از صفحه ناپدید شده باشد، مفید است):

home()

موقعیت خانه در مرکز صفحه‌ی لاک‌پشت قرار دارد. اگر زمانی نیاز داشتید آن‌ها را بدانید، مختصات x-y لاک‌پشت را با:

pos()

خانه در (0, 0) است.

و پس از مدتی، احتمالاً پاک کردن پنجره مفید خواهد بود تا بتوانیم از نو شروع کنیم:

clearscreen()

ایجاد الگوهای الگوریتمی

با استفاده از حلقه‌ها، می‌توانید الگوهای هندسی بسازید:

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

- که البته، تنها به تخیل محدود می‌شوند!

بیایید شکل ستاره‌ای بالای این صفحه را رسم کنیم. سطرهای قرمز می‌خواهیم که با زرد پر شده باشند:

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

همان‌گونه که up() و down() تعیین می‌کنند که آیا سطرهای رسم می‌شوند، می‌توان پر کردن را روشن و خاموش کرد:

begin_fill()

در ادامه یک حلقه ایجاد می‌کنیم:

start = pos()

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

distance(start) < 1 is a good way to know when the turtle is back at its start position.

در نهایت، پر کردن را کامل کنید:

end_fill()

(توجه داشته باشید که پر کردن در واقع تنها زمانی انجام می‌شود که دستور end_fill() را صادر کنید.)

چگونه...

این بخش برخی از موارد استفاده و رویکردهای رایج turtle را پوشش می‌دهد.

هرچه سریع‌تر شروع کنید

یکی از لذت‌های گرافیک لاک‌پشتی (turtle graphics)، بازخورد فوری و بصری است که از طریق دستورات ساده در دسترس است — این روشی عالی برای آشنا کردن کودکان با ایده‌های برنامه‌نویسی، با حداقل سربار است (البته نه فقط کودکان).

ماژول turtle این امکان را با در دسترس قرار دادن تمام قابلیت‌های پایه‌ی خود به‌صورت توابع فراهم می‌کند؛ این توابع با from turtle import * در دسترس هستند. آموزش گرافیک turtle این روش را پوشش می‌دهد.

شایان ذکر است که بسیاری از فرمان‌های turtle معادل‌های حتی مختصرتری نیز دارند، مانند fd() برای forward(). این معادل‌ها به‌ویژه هنگام کار با یادگیرندگانی که تایپ کردن جزو مهارت‌های آن‌ها نیست، مفید هستند.

برای کار کردن گرافیک لاک‌پشتی، باید بسته‌ی رابط Tk بر روی سیستم شما نصب شده باشد. توجه داشته باشید که این کار همیشه ساده نیست، بنابراین اگر قصد دارید از گرافیک لاک‌پشتی با یک یادگیرنده استفاده کنید، این مورد را از قبل بررسی کنید.

آغاز و پایان پر کردن به‌صورت خودکار

از پایتون 3.14 به بعد، می‌توانید به‌جای begin_fill() و end_fill() از fill() به‌عنوان context manager استفاده کنید تا شروع و پایان پر کردن به‌طور خودکار انجام شود. در اینجا مثالی آورده شده است:

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

forward(200)

کد بالا معادل است با:

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

forward(200)

از فضای نام ماژول turtle استفاده کنید

استفاده از from turtle import * مناسب است، اما توجه داشته باشید که این دستور مجموعه‌ای نسبتاً بزرگ از شیء‌ها را ایمپورت می‌کند و اگر کاری به‌جز گرافیک turtle انجام می‌دهید، با خطر تعارض نام مواجه می‌شوید (این موضوع به‌ویژه زمانی مشکل‌سازتر می‌شود که از گرافیک turtle در اسکریپتی استفاده می‌کنید که ممکن است ماژول‌های دیگر نیز ایمپورت شوند).

راه‌حل استفاده از import turtle است - fd() به turtle.fd() تبدیل می‌شود، width() به turtle.width() تبدیل می‌شود و به همین ترتیب. (اگر تایپ کردن مکرر "turtle" خسته‌کننده شد، برای مثال به‌جای آن از import turtle as t استفاده کنید.)

استفاده از گرافیک لاک‌پشتی (turtle graphics) در یک اسکریپت

توصیه می‌شود همان‌طور که بلافاصله در بالا توضیح داده شد، از فضای نام ماژول 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)

البته یک مرحله دیگر نیز لازم است — به محض اینکه اسکریپت تمام شود، پایتون پنجره turtle را نیز خواهد بست. اضافه کنید:

t.mainloop()

به انتهای اسکریپت. اسکریپت اکنون منتظر می‌ماند تا بسته شود و تا زمانی که پایان داده نشود، خارج نخواهد شد، برای مثال با بستن پنجره‌ی گرافیک turtle.

استفاده از گرافیک لاک‌پشتی شیءگرا

همچنین ملاحظه نمائید

توضیح رابط شیءگرا

به‌جز برای اهداف مقدماتی بسیار ساده، یا برای امتحان کردن موارد مختلف در سریع‌ترین حالت ممکن، استفاده از رویکرد شیء‌گرا برای گرافیک لاک‌پشتی معمول‌تر و بسیار قدرتمندتر است. برای مثال، این رویکرد امکان داشتن چندین لاک‌پشت به‌طور همزمان روی صفحه را می‌دهد.

در این رویکرد، دستورات مختلف turtle متدهایی از اشیاء هستند (بیشتر از اشیاء Turtle). شما می‌توانید از رویکرد شیءگرا در پوسته استفاده کنید، اما این کار در یک اسکریپت پایتون معمول‌تر است.

مثال بالا سپس به‌صورت زیر درمی‌آید:

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 بر روی آن قرار دارد؛ این صفحه به‌صورت خودکار به‌همراه لاک‌پشت ایجاد می‌شود.

می‌توان صفحه‌ی turtle را سفارشی کرد، برای مثال:

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

مرجع گرافیک لاک‌پشتی

توجه

در مستندات زیر، فهرست آرگومان‌های توابع داده شده است. متدها، البته، آرگومان اول اضافه‌ای به نام self دارند که در اینجا حذف شده است.

متدهای Turtle

حرکت لاک‌پشت
حرکت و ترسیم
forward() | fd()
backward() | bk() | back()
right() | rt()
left() | lt()
goto() | setpos() | setposition()
teleport()
setx()
sety()
setheading() | seth()
home()
circle()
dot()
stamp()
clearstamp()
clearstamps()
undo()
speed()
گزارش وضعیت Turtle
position() | pos()
towards()
xcor()
ycor()
heading()
distance()
تنظیم و اندازه‌گیری
degrees()
radians()
کنترل قلم
وضعیت ترسیم
pendown() | pd() | down()
penup() | pu() | up()
pensize() | width()
pen()
isdown()
کنترل رنگ
color()
pencolor()
fillcolor()
پر کردن
filling()
fill()
begin_fill()
end_fill()
کنترل بیشتر ترسیم
reset()
clear()
write()
وضعیت Turtle
قابلیت مشاهده
showturtle() | st()
hideturtle() | ht()
isvisible()
ظاهر
shape()
resizemode()
shapesize() | turtlesize()
shearfactor()
tiltangle()
tilt()
shapetransform()
get_shapepoly()
استفاده از رویدادها
onclick()
onrelease()
ondrag()
متدهای ویژه‌ی Turtle
poly()
begin_poly()
end_poly()
get_poly()
clone()
getturtle() | getpen()
getscreen()
setundobuffer()
undobufferentries()

متدهای TurtleScreen/Screen

کنترل پنجره
bgcolor()
bgpic()
clearscreen()
resetscreen()
screensize()
setworldcoordinates()
کنترل پویانمایی
no_animation()
delay()
tracer()
update()
استفاده از رویدادهای صفحه
listen()
onkey() | onkeyrelease()
onkeypress()
onclick() | onscreenclick()
ontimer()
mainloop() | done()
تنظیمات و متدهای ویژه
mode()
colormode()
getcanvas()
getshapes()
register_shape() | addshape()
turtles()
window_height()
window_width()
متدهای ورودی
textinput()
numinput()
متدهای خاص Screen
bye()
exitonclick()
save()
setup()
title()

متدهای RawTurtle/Turtle و توابع متناظر

بیشتر مثال‌های این بخش به یک نمونه از Turtle به نام turtle اشاره دارند.

حرکت لاک‌پشت

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 تنظیم کنید. در اینجا چند جهت رایج بر حسب درجه آمده است:

حالت استاندارد

حالت لوگو

۰ - شرق

۰ - شمال

۹۰ - شمال

۹۰ - شرق

۱۸۰ - غرب

۱۸۰ - جنوب

۲۷۰ - جنوب

۲۷۰ - غرب

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

لاک‌پشت را به مبدأ -- مختصات (۰،۰) -- منتقل کنید و جهت آن را برابر با جهت‌گیری اولیه‌اش تنظیم کنید (که به حالت بستگی دارد، mode() را ببینید).

>>> turtle.heading()
90.0
>>> turtle.position()
(0.00,-10.00)
>>> turtle.home()
>>> turtle.position()
(0.00,0.00)
>>> turtle.heading()
0.0
turtle.circle(radius, extent=None, steps=None)
پارامترها:

  • radius -- یک عدد

  • extent -- یک عدد (یا None)

  • steps -- یک عدد صحیح (یا None)

دایره‌ای با radius داده‌شده رسم می‌کند. مرکز آن radius واحد در سمت چپ لاک‌پشت قرار دارد؛ extent — یک زاویه — تعیین می‌کند کدام بخش از دایره رسم شود. اگر extent داده نشود، کل دایره رسم می‌شود. اگر extent دایره‌ی کامل نباشد، یکی از نقاط پایانی کمان، موقعیت فعلی قلم است. اگر radius مثبت باشد، کمان در جهت پادساعت‌گرد رسم می‌شود، در غیر این صورت در جهت ساعت‌گرد. در نهایت، جهت لاک‌پشت به اندازه‌ی extent تغییر می‌کند.

از آن‌جا که دایره با یک چندضلعی منتظم محاطی تقریب زده می‌شود، steps تعداد گام‌های مورد استفاده را تعیین می‌کند. اگر داده نشود، به‌صورت خودکار محاسبه خواهد شد. می‌تواند برای رسم چندضلعی‌های منتظم به کار رود.

>>> turtle.home()
>>> turtle.position()
(0.00,0.00)
>>> turtle.heading()
0.0
>>> turtle.circle(50)
>>> turtle.position()
(-0.00,0.00)
>>> turtle.heading()
0.0
>>> turtle.circle(120, 180)  # draw a semicircle
>>> turtle.position()
(0.00,240.00)
>>> turtle.heading()
180.0
turtle.dot()
turtle.dot(size)
turtle.dot(color, /)
turtle.dot(size, color, /)
turtle.dot(size, r, g, b, /)
پارامترها:

  • size -- یک عدد صحیح بزرگ‌تر یا مساوی ۱ (در صورت داده شدن)

  • color -- یک رشته‌ی رنگ یا یک تاپل عددی رنگ

با استفاده از color، یک نقطه‌ی دایره‌ای به قطر size رسم کنید. اگر 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 تا از مهرهای turtle را حذف می‌کند. اگر n None باشد، همه مهرها را حذف می‌کند؛ اگر n > ۰ باشد، اولین n مهر را حذف می‌کند، در غیر این صورت اگر n < ۰ باشد، آخرین n مهر را حذف می‌کند.

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

آخرین عمل(های) لاک‌پشت را (به‌طور مکرر) واگرد کنید. تعداد عمل‌های در دسترس برای واگرد، با اندازه‌ی بافر لغو (undobuffer) تعیین می‌شود.

>>> for i in range(4):
...     turtle.fd(50); turtle.lt(80)
...
>>> for i in range(8):
...     turtle.undo()
turtle.speed(speed=None)
پارامترها:

speed -- یک عدد صحیح در بازه‌ی ۰..۱۰ یا یک رشته‌ی سرعت (speedstring) (در زیر ببینید)

سرعت لاک‌پشت را روی یک مقدار عدد صحیح در بازه‌ی ۰ تا ۱۰ تنظیم می‌کند. اگر آرگومانی داده نشود، سرعت فعلی را برمی‌گرداند.

اگر ورودی عددی بزرگ‌تر از ۱۰ یا کوچک‌تر از ۰٫۵ باشد، سرعت روی ۰ تنظیم می‌شود. رشته‌های سرعت به مقدارهای سرعت به‌صورت زیر نگاشت می‌شوند:

  • "fastest": 0

  • "fast": 10

  • "normal": 6

  • "slow": 3

  • "slowest": 1

سرعت‌های ۱ تا ۱۰، پویانمایی رسم خط و چرخش لاک‌پشت را به‌طور فزاینده‌ای سریع‌تر می‌کنند.

توجه: speed = ۰ به این معناست که هیچ پویانمایی‌ای رخ نمی‌دهد. forward/back باعث پرش لاک‌پشت می‌شود و به همین ترتیب left/right باعث چرخش آنی لاک‌پشت می‌شود.

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

گزارش وضعیت Turtle

turtle.position()
turtle.pos()

موقعیت فعلی لاک‌پشت (x,y) را برمی‌گرداند (به‌عنوان یک بردار Vec2D).

>>> turtle.pos()
(440.00,-0.00)
turtle.towards(x, y=None)
پارامترها:

  • x -- یک عدد یا یک جفت/بردار از اعداد یا یک نمونه از turtle

  • 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 -- یک عدد یا یک جفت/بردار از اعداد یا یک نمونه از turtle

  • 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 -- یک عدد

واحدهای اندازه‌گیری زاویه را تنظیم کنید، یعنی تعداد «درجه‌ها» برای یک دایره کامل را مشخص کنید. مقدار پیش‌فرض ۳۶۰ درجه است.

>>> 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.pendown()
turtle.pd()
turtle.down()

قلم را پایین بکشید -- هنگام حرکت ترسیم می‌کند.

turtle.penup()
turtle.pu()
turtle.up()

قلم را بالا بکشید — هنگام حرکت، ترسیمی انجام نمی‌شود.

turtle.pensize(width=None)
turtle.width(width=None)
پارامترها:

width -- یک عدد مثبت

ضخامت خط را روی width تنظیم می‌کند یا آن را بازمی‌گرداند. اگر resizemode روی "auto" تنظیم شده باشد و turtleshape یک چندضلعی باشد، آن چندضلعی با همان ضخامت خط رسم می‌شود. اگر آرگومانی داده نشود، pensize فعلی بازگردانده می‌شود.

>>> turtle.pensize()
1
>>> turtle.pensize(10)   # from here on lines of width 10 are drawn
turtle.pen(pen=None, **pendict)
پارامترها:

  • pen -- یک دیکشنری با برخی یا همه‌ی کلیدهای فهرست‌شده در زیر

  • pendict -- یک یا چند آرگومان کلیدواژه‌ای با کلیدهای فهرست‌شده در زیر به‌عنوان کلیدواژه

ویژگی‌های قلم را در یک «دیکشنری قلم» با جفت‌های کلید/مقدار زیر برمی‌گرداند یا تنظیم می‌کند:

  • "shown": True/False

  • "pendown": True/False

  • "pencolor": رشته‌ی رنگ یا تاپل رنگ

  • "fillcolor": رشته‌ی رنگ یا تاپل رنگ

  • "pensize": عدد مثبت

  • "speed": عددی در بازه‌ی ۰..۱۰

  • "resizemode": "auto" یا "user" یا "noresize"

  • "stretchfactor": (عدد مثبت، عدد مثبت)

  • "outline": عدد مثبت

  • "tilt": عدد

این دیکشنری می‌تواند به‌عنوان آرگومان برای فراخوانی بعدی pen() جهت بازیابی وضعیت پیشین قلم استفاده شود. علاوه بر این، می‌توان یک یا چند مورد از این ویژگی‌ها را به‌صورت آرگومان‌های کلیدواژه‌ای ارائه کرد. می‌توان از این مورد برای تنظیم چند ویژگی قلم در یک دستور استفاده کرد.

>>> turtle.pen(fillcolor="black", pencolor="red", pensize=10)
>>> sorted(turtle.pen().items())
[('fillcolor', 'black'), ('outline', 1), ('pencolor', 'red'),
 ('pendown', True), ('pensize', 10), ('resizemode', 'noresize'),
 ('shearfactor', 0.0), ('shown', True), ('speed', 9),
 ('stretchfactor', (1.0, 1.0)), ('tilt', 0.0)]
>>> penstate=turtle.pen()
>>> turtle.color("yellow", "")
>>> turtle.penup()
>>> sorted(turtle.pen().items())[:3]
[('fillcolor', ''), ('outline', 1), ('pencolor', 'yellow')]
>>> turtle.pen(penstate, fillcolor="green")
>>> sorted(turtle.pen().items())[:3]
[('fillcolor', 'green'), ('outline', 1), ('pencolor', 'red')]
turtle.isdown()

اگر قلم پایین باشد، True و اگر بالا باشد، False برمی‌گرداند.

>>> turtle.penup()
>>> turtle.isdown()
False
>>> turtle.pendown()
>>> turtle.isdown()
True

کنترل رنگ

turtle.pencolor()
turtle.pencolor(color, /)
turtle.pencolor(r, g, b, /)

pencolor را برمی‌گرداند یا تنظیم می‌کند.

۴ قالب ورودی مجاز است:

pencolor()

رنگ قلم فعلی را به‌صورت رشته مشخصه رنگ یا تاپل برمی‌گرداند (مثال را ببینید). می‌تواند به‌عنوان ورودی برای فراخوانی دیگری از color/pencolor/fillcolor/bgcolor استفاده شود.

pencolor(colorstring)

pencolor را به colorstring تنظیم می‌کند، که یک رشته‌ی مشخصه‌ی رنگ Tk است، مانند "red"، "yellow"، یا "#33cc8c".

pencolor((r, g, b))

رنگ قلم (pencolor) را به رنگ RGB نشان‌داده‌شده با تاپل r، g و b تنظیم می‌کند. هر یک از r، g و b باید در بازه‌ی 0..colormode باشند، که در آن colormode برابر با 1.0 یا 255 است (به colormode() مراجعه کنید).

pencolor(r, g, b)

pencolor را روی رنگ RGB متناظر با r، g و b تنظیم کنید. هر یک از r، g و b باید در بازه‌ی 0..colormode باشند.

اگر turtleshape یک چندضلعی باشد، خط دور آن چندضلعی با pencolor تازه تنظیم‌شده رسم می‌شود.

>>> colormode()
1.0
>>> turtle.pencolor()
'red'
>>> turtle.pencolor("brown")
>>> turtle.pencolor()
'brown'
>>> tup = (0.2, 0.8, 0.55)
>>> turtle.pencolor(tup)
>>> turtle.pencolor()
(0.2, 0.8, 0.5490196078431373)
>>> colormode(255)
>>> turtle.pencolor()
(51.0, 204.0, 140.0)
>>> turtle.pencolor('#32c18f')
>>> turtle.pencolor()
(50.0, 193.0, 143.0)
turtle.fillcolor()
turtle.fillcolor(color, /)
turtle.fillcolor(r, g, b, /)

fillcolor را برمی‌گرداند یا تنظیم می‌کند.

۴ قالب ورودی مجاز است:

fillcolor()

fillcolor فعلی را به‌عنوان رشته مشخصات رنگ برمی‌گرداند، احتمالاً در قالب تاپل (به مثال مراجعه کنید). ممکن است به‌عنوان ورودی برای فراخوانی دیگری از color/pencolor/fillcolor/bgcolor استفاده شود.

fillcolor(colorstring)

fillcolor را روی colorstring تنظیم کنید، که یک رشته مشخص‌کننده رنگ Tk است، مانند "red"، "yellow" یا "#33cc8c".

fillcolor((r, g, b))

fillcolor را روی رنگ RGB نشان‌داده‌شده با تاپلِ r، g و b تنظیم کنید. هر یک از r، g و b باید در بازه‌ی 0..colormode باشد، که colormode برابر 1.0 یا 255 است (به colormode() مراجعه کنید).

fillcolor(r, g, b)

fillcolor را روی رنگ RGB متناظر با r، g و b تنظیم کنید. هر یک از r، g و b باید در بازه‌ی 0..colormode باشد.

اگر شکل لاک‌پشت یک چندضلعی باشد، فضای داخلی آن چندضلعی با fillcolor به‌تازگی تنظیم‌شده رسم می‌شود.

>>> turtle.fillcolor("violet")
>>> turtle.fillcolor()
'violet'
>>> turtle.pencolor()
(50.0, 193.0, 143.0)
>>> turtle.fillcolor((50, 193, 143))  # Integers, not floats
>>> turtle.fillcolor()
(50.0, 193.0, 143.0)
>>> turtle.fillcolor('#ffffff')
>>> turtle.fillcolor()
(255.0, 255.0, 255.0)
turtle.color()
turtle.color(color, /)
turtle.color(r, g, b, /)
turtle.color(pencolor, fillcolor, /)

pencolor و fillcolor را برمی‌گرداند یا تنظیم می‌کند.

چندین قالب ورودی مجاز است. آن‌ها از ۰ تا ۳ آرگومان به‌صورت زیر استفاده می‌کنند:

color()

رنگ قلم فعلی و رنگ پر کردن فعلی را به‌صورت یک جفت از رشته‌ها یا تاپل‌های مشخصه‌ی رنگ، همان‌گونه که pencolor() و fillcolor() بازمی‌گردانند، برمی‌گرداند.

color(colorstring), color((r,g,b)), color(r,g,b)

ورودی‌ها مانند pencolor()، هر دو، fillcolor و pencolor، به مقدار داده‌شده تنظیم می‌شوند.

color(colorstring1, colorstring2), color((r1,g1,b1), (r2,g2,b2))

معادل pencolor(colorstring1) و fillcolor(colorstring2) است و اگر از قالب ورودی دیگر استفاده شود، به‌طور مشابه عمل می‌کند.

اگر turtleshape یک چندضلعی باشد، خط دور و داخل آن چندضلعی با رنگ‌های تازه‌تنظیم‌شده رسم می‌شود.

>>> turtle.color("red", "green")
>>> turtle.color()
('red', 'green')
>>> color("#285078", "#a0c8f0")
>>> color()
((40.0, 80.0, 120.0), (160.0, 200.0, 240.0))

همچنین ببینید: متد Screen به نام colormode().

پر کردن

turtle.filling()

وضعیت پر کردن را برمی‌گرداند (اگر در حال پر کردن باشد True، در غیر این صورت False).

>>> turtle.begin_fill()
>>> if turtle.filling():
...    turtle.pensize(5)
... else:
...    turtle.pensize(3)
turtle.fill()

شکل کشیده‌شده در بلوک with turtle.fill(): را پر کنید.

>>> turtle.color("black", "red")
>>> with turtle.fill():
...     turtle.circle(80)

استفاده از fill() معادل افزودن begin_fill() پیش از بلوک پرکردن و end_fill() پس از بلوک پرکردن است:

>>> turtle.color("black", "red")
>>> turtle.begin_fill()
>>> turtle.circle(80)
>>> turtle.end_fill()

اضافه شده در نسخه‌ی 3.14.

turtle.begin_fill()

باید درست پیش از ترسیم شکلی که قرار است پر شود، فراخوانی شود.

turtle.end_fill()

شکل رسم‌شده پس از آخرین فراخوانی begin_fill() را پر کنید.

پر شدن یا پر نشدن ناحیه‌های هم‌پوشانی برای چندضلعی‌های خودمتقاطع یا شکل‌های متعدد، به گرافیک سیستم‌عامل، نوع هم‌پوشانی و تعداد هم‌پوشانی‌ها بستگی دارد. برای مثال، ستاره‌ی Turtle در بالا ممکن است کاملاً زرد باشد یا ناحیه‌های سفیدی داشته باشد.

>>> turtle.color("black", "red")
>>> turtle.begin_fill()
>>> turtle.circle(80)
>>> turtle.end_fill()

کنترل بیشتر ترسیم

turtle.reset()

نقاشی‌های لاک‌پشت را از صفحه پاک می‌کند، لاک‌پشت را دوباره در مرکز قرار می‌دهد و متغیرها را روی مقادیر پیش‌فرض تنظیم می‌کند.

>>> turtle.goto(0,-22)
>>> turtle.left(100)
>>> turtle.position()
(0.00,-22.00)
>>> turtle.heading()
100.0
>>> turtle.reset()
>>> turtle.position()
(0.00,0.00)
>>> turtle.heading()
0.0
turtle.clear()

ترسیمات لاک‌پشت را از صفحه حذف می‌کند. لاک‌پشت را حرکت نمی‌دهد. وضعیت و موقعیت لاک‌پشت و همچنین ترسیمات سایر لاک‌پشت‌ها تحت تأثیر قرار نمی‌گیرند.

turtle.write(arg, move=False, align='left', font=('Arial', 8, 'normal'))
پارامترها:

  • arg -- شیءای که باید در TurtleScreen نوشته شود

  • move -- True/False

  • align -- یکی از رشته‌های "left"، "center" یا "right"

  • font -- یک سه‌تایی (fontname, fontsize, fonttype)

متن - نمایش رشته‌ای arg - را در موقعیت فعلی لاک‌پشت بر اساس align ("left"، "center" یا "right") و با قلم داده‌شده می‌نویسد. اگر move درست باشد، قلم به گوشه‌ی پایین سمت راست متن منتقل می‌شود. به‌طور پیش‌فرض، move برابر False است.

>>> turtle.write("Home = ", True, align="center")
>>> turtle.write((0,0), True)

وضعیت Turtle

قابلیت مشاهده

turtle.hideturtle()
turtle.ht()

لاک‌پشت را نامرئی کنید. بهتر است این کار را هنگامی که در میانه‌ی انجام یک ترسیم پیچیده هستید انجام دهید، زیرا پنهان کردن لاک‌پشت سرعت ترسیم را به‌طور محسوسی افزایش می‌دهد.

>>> turtle.hideturtle()
turtle.showturtle()
turtle.st()

لاک‌پشت را نمایان کنید.

>>> turtle.showturtle()
turtle.isvisible()

اگر Turtle نمایش داده شده باشد، True و اگر پنهان باشد، False را برمی‌گرداند.

>>> turtle.hideturtle()
>>> turtle.isvisible()
False
>>> turtle.showturtle()
>>> turtle.isvisible()
True

ظاهر

turtle.shape(name=None)
پارامترها:

name -- رشته‌ای که یک نام شکل (shapename) معتبر باشد

شکل لاک‌پشت را به شکل با name داده‌شده تنظیم می‌کند یا اگر name داده نشده باشد، نام شکل جاری را برمی‌گرداند. شکل با name باید در دیکشنری شکل‌های TurtleScreen وجود داشته باشد. در ابتدا، شکل‌های چندضلعی زیر وجود دارند: "arrow"، "turtle"، "circle"، "square"، "triangle"، "classic". برای آشنایی با نحوه‌ی کار با شکل‌ها، متد register_shape() از Screen را ببینید.

>>> turtle.shape()
'classic'
>>> turtle.shape("turtle")
>>> turtle.shape()
'turtle'
turtle.resizemode(rmode=None)
پارامترها:

rmode -- یکی از رشته‌های "auto"، "user"، "noresize"

resizemode را روی یکی از مقادیر زیر تنظیم کنید: "auto"، "user"، "noresize". اگر rmode داده نشود، resizemode فعلی برگردانده می‌شود. حالت‌های مختلف resizemode پیامدهای زیر را دارند:

  • "auto": ظاهر لاک‌پشت را متناسب با مقدار pensize تطبیق می‌دهد.

  • "user": ظاهر لاک‌پشت را مطابق با مقادیر stretchfactor و outlinewidth (outline)، که توسط shapesize() تنظیم می‌شوند، تطبیق می‌دهد.

  • "noresize": هیچ سازگاری‌ای برای ظاهر لاک‌پشت انجام نمی‌شود.

resizemode("user") توسط shapesize() در صورتی که با آرگومان‌ها استفاده شود، فراخوانی می‌شود.

>>> turtle.resizemode()
'noresize'
>>> turtle.resizemode("auto")
>>> turtle.resizemode()
'auto'
turtle.shapesize(stretch_wid=None, stretch_len=None, outline=None)
turtle.turtlesize(stretch_wid=None, stretch_len=None, outline=None)
پارامترها:

  • stretch_wid -- عدد مثبت

  • stretch_len -- عدد مثبت

  • outline -- عدد مثبت

ویژگی‌های قلم، یعنی ضریب‌های کشیدگی x/y (x/y-stretchfactors) و/یا خط دور (outline)، را برمی‌گرداند یا تنظیم می‌کند. resizemode را روی "user" تنظیم می‌کند. اگر و فقط اگر resizemode روی "user" تنظیم شده باشد، لاک‌پشت بر اساس ضریب‌های کشیدگی خود به‌صورت کشیده‌شده نمایش داده می‌شود: stretch_wid ضریب کشیدگی عمود بر جهت آن است، stretch_len ضریب کشیدگی در راستای جهت آن است، و outline عرض خط دور شکل را تعیین می‌کند.

>>> turtle.shapesize()
(1.0, 1.0, 1)
>>> turtle.resizemode("user")
>>> turtle.shapesize(5, 5, 12)
>>> turtle.shapesize()
(5, 5, 12)
>>> turtle.shapesize(outline=8)
>>> turtle.shapesize()
(5, 5, 8)
turtle.shearfactor(shear=None)
پارامترها:

shear -- عدد (اختیاری)

ضریب اسلایس (shearfactor) جاری را تنظیم می‌کند یا برمی‌گرداند. شکل لاک‌پشت را بر اساس shearfactor داده‌شده (shear) اسلایس می‌دهد، که تانژانت زاویه اسلایس است. جهت لاک‌پشت (جهت حرکت) را تغییر نمی‌دهد. اگر shear داده نشده باشد: ضریب اسلایس جاری را برمی‌گرداند، یعنی تانژانت زاویه اسلایس، که سطرهای موازی با جهت لاک‌پشت با آن اسلایس داده می‌شوند.

>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.shearfactor(0.5)
>>> turtle.shearfactor()
0.5
turtle.tilt(angle)
پارامترها:

angle -- یک عدد

شکل لاک‌پشت را به اندازه‌ی angle نسبت به زاویه‌ی کجی فعلی‌اش بچرخانید، اما جهت لاک‌پشت (جهت حرکت) را تغییر نکنید.

>>> turtle.reset()
>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.tilt(30)
>>> turtle.fd(50)
>>> turtle.tilt(30)
>>> turtle.fd(50)
turtle.tiltangle(angle=None)
پارامترها:

angle -- یک عدد (اختیاری)

زاویه‌ی کجی فعلی را تنظیم یا برمی‌گرداند. اگر زاویه داده شود، شکل لاک‌پشت را می‌چرخاند تا در جهت مشخص‌شده توسط زاویه قرار گیرد، صرف‌نظر از زاویه‌ی کجی فعلی آن. جهت لاک‌پشت (جهت حرکت) را تغییر نمی‌دهد. اگر زاویه داده نشود: زاویه‌ی کجی فعلی را برمی‌گرداند، یعنی زاویه‌ی بین جهت‌گیری شکل لاک‌پشت و جهت لاک‌پشت (جهت حرکت آن).

>>> turtle.reset()
>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.tilt(45)
>>> turtle.tiltangle()
45.0
turtle.shapetransform(t11=None, t12=None, t21=None, t22=None)
پارامترها:

  • t11 -- یک عدد (اختیاری)

  • t12 -- یک عدد (اختیاری)

  • t21 -- یک عدد (اختیاری)

  • t12 -- یک عدد (اختیاری)

تنظیم یا برگرداندن ماتریس تبدیل فعلی شکل لاک‌پشت.

اگر هیچ‌کدام از عناصر ماتریس داده نشده باشد، ماتریس تبدیل را به‌صورت یک تاپل ۴ عنصری برمی‌گرداند. در غیر این صورت، عناصر داده‌شده را تنظیم می‌کند و شکل لاک‌پشت را مطابق ماتریس متشکل از ردیف اول t11، t12 و ردیف دوم t21، t22 تبدیل می‌کند. دترمینان t11 * t22 - t12 * t21 نباید صفر باشد، در غیر این صورت خطایی پرتاب می‌شود. stretchfactor، shearfactor و tiltangle را مطابق ماتریس داده‌شده تغییر می‌دهد.

>>> turtle = Turtle()
>>> turtle.shape("square")
>>> turtle.shapesize(4,2)
>>> turtle.shearfactor(-0.5)
>>> turtle.shapetransform()
(4.0, -1.0, -0.0, 2.0)
turtle.get_shapepoly()

چندضلعی شکل فعلی را به‌صورت تاپلی از جفت‌های مختصات برمی‌گرداند. این مقدار می‌تواند برای تعریف یک شکل جدید یا اجزای یک شکل مرکب استفاده شود.

>>> turtle.shape("square")
>>> turtle.shapetransform(4, -1, 0, 2)
>>> turtle.get_shapepoly()
((50, -20), (30, 20), (-50, 20), (-30, -20))

استفاده از رویدادها

turtle.onclick(fun, btn=1, add=None)
پارامترها:

  • fun -- تابعی با دو آرگومان که با مختصات نقطه‌ی کلیک‌شده روی بوم فراخوانی خواهد شد

  • btn -- شماره‌ی دکمه‌ی ماوس، پیش‌فرض ۱ (دکمه‌ی چپ ماوس)

  • 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 -- شماره‌ی دکمه‌ی ماوس، پیش‌فرض ۱ (دکمه‌ی چپ ماوس)

  • 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 -- شماره‌ی دکمه‌ی ماوس، پیش‌فرض ۱ (دکمه‌ی چپ ماوس)

  • add -- True یا False — اگر True باشد، یک اتصال جدید افزوده خواهد شد، در غیر این صورت جایگزین یک اتصال پیشین خواهد شد

fun را به رویدادهای حرکت ماوس روی این لاک‌پشت متصل کنید. اگر fun برابر None باشد، اتصالات موجود حذف می‌شوند.

نکته: پیش از هر دنباله‌ای از رویدادهای حرکت ماوس روی یک لاک‌پشت، یک رویداد کلیک ماوس روی همان لاک‌پشت رخ می‌دهد.

>>> turtle.ondrag(turtle.goto)

سپس، کلیک کردن و کشیدن Turtle آن را در سراسر صفحه حرکت می‌دهد و بدین ترتیب ترسیم‌های دستی ایجاد می‌کند (اگر قلم پایین باشد).

متدهای ویژه‌ی Turtle

turtle.poly()

رئوس یک چندضلعی ترسیم‌شده در بلوک with turtle.poly(): را ثبت کنید. اولین و آخرین رأس به یکدیگر متصل می‌شوند.

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

اضافه شده در نسخه‌ی 3.14.

turtle.begin_poly()

ثبت رأس‌های یک چندضلعی را آغاز کنید. موقعیت فعلی لاک‌پشت، اولین رأس چندضلعی است.

turtle.end_poly()

ثبت رأس‌های یک چندضلعی را متوقف می‌کند. موقعیت فعلی لاک‌پشت آخرین رأس چندضلعی است. این به اولین رأس متصل خواهد شد.

turtle.get_poly()

آخرین چندضلعی ثبت‌شده را برمی‌گرداند.

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

یک رونوشت (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

بافر لغو (undobuffer) را تنظیم یا غیرفعال کنید. اگر size یک عدد صحیح باشد، یک بافر لغو (undobuffer) خالی با اندازه‌ی داده‌شده نصب می‌شود. size حداکثر تعداد کنش‌های لاک‌پشت را که می‌توان با متد/تابع undo() آن‌ها را واگرد کرد، مشخص می‌کند. اگر size برابر None باشد، بافر لغو (undobuffer) غیرفعال می‌شود.

>>> turtle.setundobuffer(42)
turtle.undobufferentries()

تعداد ورودی‌های موجود در بافر لغو (undobuffer) را برمی‌گرداند.

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

شکل‌های ترکیبی

برای استفاده از شکل‌های ترکیبی turtle، که از چندین چندضلعی با رنگ‌های متفاوت تشکیل شده‌اند، باید به‌صراحت از کلاس کمکی 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 را به shapelistِ Screen اضافه کنید و از آن استفاده کنید:

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

توجه

کلاس Shape به‌صورت داخلی توسط متد register_shape() به روش‌های مختلفی استفاده می‌شود. برنامه‌نویس برنامه فقط هنگام استفاده از شکل‌های ترکیبی مانند آنچه در بالا نشان داده شد، باید با کلاس Shape سروکار داشته باشد!

متدهای TurtleScreen/Screen و توابع مربوطه

بیشتر مثال‌های این بخش به یک نمونه از TurtleScreen به نام screen اشاره می‌کنند.

کنترل پنجره

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

رنگ پس‌زمینه‌ی TurtleScreen را برمی‌گرداند یا تنظیم می‌کند.

۴ قالب ورودی مجاز است:

bgcolor()

رنگ پس‌زمینه‌ی جاری را به‌صورت یک رشته‌ی مشخصه‌ی رنگ یا یک تاپل برمی‌گرداند (مثال را ببینید). می‌تواند به‌عنوان ورودی در فراخوانی دیگری از color/pencolor/fillcolor/bgcolor استفاده شود.

bgcolor(colorstring)

رنگ پس‌زمینه را روی colorstring تنظیم کنید، که یک رشته مشخصات رنگ Tk است، مانند "red"، "yellow" یا "#33cc8c".

bgcolor((r, g, b))

رنگ پس‌زمینه را روی رنگ RGB بیان‌شده با تاپل r، g و b تنظیم کنید. هر یک از r، g و b باید در بازه‌ی ۰..colormode باشند، که colormode می‌تواند ۱.۰ یا ۲۵۵ باشد (به colormode() مراجعه کنید).

bgcolor(r, g, b)

رنگ پس‌زمینه را روی رنگ RGB نشان‌داده‌شده با r، g و b تنظیم کنید. هر یک از r، g و b باید در بازه‌ی 0..colormode باشد.

>>> screen.bgcolor("orange")
>>> screen.bgcolor()
'orange'
>>> screen.bgcolor("#800080")
>>> screen.bgcolor()
(128.0, 0.0, 128.0)
turtle.bgpic(picname=None)
پارامترها:

picname -- یک رشته، نام یک پرونده تصویر (PNG، GIF، PGM و PPM) یا "nopic" یا None

تصویر پس‌زمینه را تنظیم می‌کند یا نام تصویر پس‌زمینه‌ی فعلی را برمی‌گرداند. اگر picname یک نام پرونده باشد، تصویر مربوطه را به‌عنوان پس‌زمینه تنظیم می‌کند. اگر picname "nopic" باشد، در صورت وجود، تصویر پس‌زمینه را حذف می‌کند. اگر picname None باشد، نام پرونده تصویر پس‌زمینه‌ی فعلی را برمی‌گرداند.

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

توجه

این متد TurtleScreen تنها با نام clearscreen به‌عنوان یک تابع سراسری در دسترس است. تابع سراسری clear تابع متفاوتی است که از متد clear در Turtle گرفته شده است.

turtle.clearscreen()

تمام ترسیم‌ها و تمام لاک‌پشت‌ها را از TurtleScreen حذف می‌کند. TurtleScreen که اکنون خالی است را به وضعیت اولیه‌اش بازنشانی می‌کند: پس‌زمینه سفید، بدون تصویر پس‌زمینه، بدون اتصال‌های رویداد و با ردگیری روشن.

turtle.reset()

توجه

این متد TurtleScreen فقط با نام resetscreen به‌عنوان یک تابع سراسری در دسترس است. تابع سراسری reset تابع دیگری است که از متد reset در Turtle مشتق شده است.

turtle.resetscreen()

بازنشانی همه‌ی لاک‌پشت‌های روی صفحه به وضعیت اولیه‌شان.

turtle.screensize(canvwidth=None, canvheight=None, bg=None)
پارامترها:

  • canvwidth -- عدد صحیح مثبت، عرض جدید بوم به پیکسل

  • canvheight -- عدد صحیح مثبت، ارتفاع جدید بوم به پیکسل

  • bg -- رشته‌رنگ (colorstring) یا تاپل رنگ (color-tuple)، رنگ پس‌زمینه جدید

اگر هیچ آرگومانی داده نشود، مقادیر فعلی (canvaswidth, canvasheight) را برمی‌گرداند. در غیر این صورت، بومی را که لاک‌پشت‌ها روی آن ترسیم می‌کنند، تغییر اندازه می‌دهد. پنجره‌ی ترسیم را تغییر نمی‌دهد. برای مشاهده بخش‌های پنهان بوم، از نوارهای پیمایش استفاده کنید. با این متد، می‌توانید بخش‌هایی از یک ترسیم را که پیش‌تر خارج از بوم بودند، نمایان کنید.

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

مثلاً برای جستجوی لاک‌پشتی که به‌اشتباه فرار کرده است ;-)

turtle.setworldcoordinates(llx, lly, urx, ury)
پارامترها:

  • llx -- یک عدد، مختصات x گوشه‌ی پایین سمت چپ بوم

  • lly -- یک عدد، مختصات y گوشه‌ی پایین سمت چپ بوم

  • urx -- یک عدد، مختصات x گوشه‌ی بالا سمت راست بوم

  • ury -- یک عدد، مختصات y گوشه‌ی بالا سمت راست بوم

دستگاه مختصات تعریف‌شده توسط کاربر را تنظیم می‌کند و در صورت لزوم به حالت "world" تغییر می‌کند. این کار screen.reset() را انجام می‌دهد. اگر حالت "world" از قبل فعال باشد، همه ترسیم‌ها بر اساس مختصات جدید دوباره ترسیم می‌شوند.

توجه: در دستگاه‌های مختصات تعریف‌شده توسط کاربر، ممکن است زاویه‌ها تحریف‌شده به نظر برسند.

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

کنترل پویانمایی

turtle.no_animation()

پویانمایی turtle را به‌طور موقت غیرفعال می‌کند. کد نوشته‌شده درون بلوک no_animation پویانمایی نخواهد شد؛ پس از خروج از بلوک کد، ترسیم ظاهر می‌شود.

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

اضافه شده در نسخه‌ی 3.14.

turtle.delay(delay=None)
پارامترها:

delay -- عدد صحیح مثبت

تأخیر ترسیم را بر حسب میلی‌ثانیه تنظیم می‌کند یا برمی‌گرداند. (این مقدار تقریباً بازه‌ی زمانی بین دو به‌روزرسانی متوالی بوم است.) هرچه تأخیر ترسیم طولانی‌تر باشد، پویانمایی کندتر خواهد بود.

آرگومان اختیاری:

>>> screen.delay()
10
>>> screen.delay(5)
>>> screen.delay()
5
turtle.tracer(n=None, delay=None)
پارامترها:

  • n -- عدد صحیح نامنفی

  • delay -- عدد صحیح نامنفی

روشن/خاموش کردن پویانمایی turtle و تنظیم تأخیر برای به‌روزرسانی ترسیم‌ها. اگر n داده شود، تنها هر n-امین به‌روزرسانی منظم صفحه واقعاً انجام می‌شود. (می‌تواند برای تسریع ترسیم گرافیک‌های پیچیده استفاده شود.) هنگامی که بدون آرگومان فراخوانی شود، مقدار ذخیره‌شده‌ی کنونی n را برمی‌گرداند. آرگومان دوم مقدار تأخیر را تنظیم می‌کند (به delay() مراجعه کنید).

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

به‌روزرسانی TurtleScreen را انجام می‌دهد. زمانی استفاده می‌شود که tracer خاموش باشد.

همچنین متد speed() در RawTurtle/Turtle را ببینید.

استفاده از رویدادهای صفحه

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 را، اگر key داده‌شده باشد، به رویداد فشردن کلید مربوط به key، و اگر 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 -- شماره‌ی دکمه‌ی ماوس، پیش‌فرض ۱ (دکمه‌ی چپ ماوس)

  • 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 تابع دیگری است که از متد onclick Turtle مشتق شده است.

turtle.ontimer(fun, t=0)
پارامترها:

  • fun -- تابعی بدون آرگومان

  • t -- عددی بزرگ‌تر یا مساوی ۰

یک زمان‌سنج نصب کنید که 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 باشد. برای استفاده‌ی تعاملی از گرافیک turtle، اگر یک اسکریپت از داخل IDLE در حالت -n (بدون subprocess) اجرا شود، نباید از آن استفاده شود.

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

حالت turtle را ("standard"، "logo" یا "world") تنظیم کنید و بازنشانی را انجام دهید. اگر حالتی داده نشود، حالت کنونی برگردانده می‌شود.

حالت «standard» با ماژول قدیمی turtle سازگار است. حالت «logo» با بیشتر گرافیک‌های لاک‌پشتی Logo سازگار است. حالت «world» از «مختصات جهان» تعریف‌شده توسط کاربر استفاده می‌کند. توجه: در این حالت، اگر نسبت واحد x/y برابر با ۱ نباشد، زاویه‌ها اعوجاج‌یافته به نظر می‌رسند.

حالت

جهت اولیه لاک‌پشت

زوایای مثبت

"standard"

به سمت راست (شرق)

پادساعتگرد

"logo"

رو به بالا (شمال)

در جهت عقربه‌های ساعت

 
>>> mode("logo")   # resets turtle heading to north
>>> mode()
'logo'
turtle.colormode(cmode=None)
پارامترها:

cmode -- یکی از مقدارهای ۱.۰ یا ۲۵۵

colormode را برمی‌گرداند یا آن را روی 1.0 یا 255 تنظیم می‌کند. پس از آن، مقادیر r، g و b در سه‌تایی‌های رنگ باید در بازه‌ی 0..*cmode* باشند.

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

Canvas این TurtleScreen را برمی‌گرداند. برای افراد مطلعی که می‌دانند با یک Canvas در Tkinter چه کنند، مفید است.

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

فهرستی از نام‌های تمام شکل‌های لاک‌پشتی که در حال حاضر در دسترس هستند را برمی‌گرداند.

>>> screen.getshapes()
['arrow', 'blank', 'circle', ..., 'turtle']
turtle.register_shape(name, shape=None)
turtle.addshape(name, shape=None)

چهار روش مختلف برای فراخوانی این تابع وجود دارد:

  1. name نام یک پرونده تصویری (PNG، GIF، PGM و PPM) است و shape برابر None است: شکل تصویری متناظر نصب می‌شود.

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

    توجه

    شکل‌های تصویری هنگام چرخاندن لاک‌پشت نمی‌چرخند، بنابراین جهت لاک‌پشت را نمایش نمی‌دهند!

  2. name یک رشته دلخواه است و shape نام یک پرونده تصویری (PNG، GIF، PGM و PPM) است: شکل تصویری متناظر را نصب کنید.

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

    توجه

    شکل‌های تصویری هنگام چرخاندن لاک‌پشت نمی‌چرخند، بنابراین جهت لاک‌پشت را نمایش نمی‌دهند!

  3. name یک رشته دلخواه است و shape تاپلی از جفت‌های مختصات است: شکل چندضلعی متناظر نصب می‌شود.

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

  4. name یک رشته دلخواه است و shape یک شیء Shape (مرکب) است: شکل مرکب متناظر نصب می‌شود.

یک شکل لاک‌پشت را به فهرست شکل‌های TurtleScreen اضافه می‌کند. تنها می‌توان از شکل‌های ثبت‌شده بدین‌ترتیب با صدور دستور shape(shapename) استفاده کرد.

تغییر یافته در نسخه‌ی 3.14: پشتیبانی از قالب‌های تصویری PNG، PGM و PPM افزوده شد. می‌توان هم نام شکل و هم نام پرونده تصویر را مشخص کرد.

turtle.turtles()

فهرست لاک‌پشت‌های روی صفحه را برمی‌گرداند.

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

ارتفاع پنجره‌ی turtle را برمی‌گرداند.

>>> screen.window_height()
480
turtle.window_width()

عرض پنجره‌ی turtle را برمی‌گرداند.

>>> screen.window_width()
640

متدهای مختص Screen، که از TurtleScreen به ارث نمی‌رسند

turtle.bye()

پنجره‌ی گرافیک لاک‌پشتی را ببندید.

turtle.exitonclick()

متد bye() را به کلیک‌های ماوس روی Screen متصل کنید.

اگر مقدار "using_IDLE" در دیکشنری پیکربندی False باشد (مقدار پیش‌فرض)، همچنین وارد mainloop شوید. نکته: اگر از IDLE با سوییچ -n (بدون subprocess) استفاده شود، این مقدار باید در turtle.cfg روی True تنظیم شود. در این حالت، mainloop خود IDLE برای اسکریپت کلاینت نیز فعال است.

turtle.save(filename, overwrite=False)

نقاشی فعلی لاک‌پشت (و لاک‌پشت‌ها) را به‌عنوان یک پرونده PostScript ذخیره کنید.

پارامترها:

  • filename -- مسیر پرونده PostScript ذخیره‌شده

  • overwrite -- اگر False باشد و از قبل پرونده‌ای با نام پرونده داده‌شده وجود داشته باشد، تابع یک FileExistsError پرتاب خواهد کرد. اگر True باشد، پرونده بازنویسی خواهد شد.

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

اضافه شده در نسخه‌ی 3.14.

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

اندازه و موقعیت پنجره اصلی را تنظیم می‌کند. مقادیر پیش‌فرض آرگومان‌ها در دیکشنری پیکربندی ذخیره شده‌اند و می‌توان آن‌ها را از طریق یک پرونده turtle.cfg تغییر داد.

پارامترها:

  • width -- اگر عدد صحیح باشد، اندازه‌ای بر حسب پیکسل است؛ اگر عدد اعشاری باشد، کسری از صفحه‌نمایش است؛ پیش‌فرض ۵۰٪ از صفحه‌نمایش است

  • height -- اگر عدد صحیح باشد، ارتفاع بر حسب پیکسل است؛ اگر عدد اعشاری باشد، کسری از صفحه است؛ پیش‌فرض ۷۵٪ صفحه است

  • 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!")

کلاس‌های عمومی

class turtle.RawTurtle(canvas)
class turtle.RawPen(canvas)
پارامترها:

canvas -- یک tkinter.Canvas، یک ScrolledCanvas یا یک TurtleScreen

یک لاک‌پشت ایجاد کنید. این لاک‌پشت تمام متدهایی را دارد که در بالا به‌عنوان «متدهای Turtle/RawTurtle» شرح داده شده‌اند.

class turtle.Turtle

زیرکلاسی از RawTurtle، همان رابط را دارد اما روی یک شیء پیش‌فرض Screen ترسیم می‌کند که به‌طور خودکار هنگامی که برای اولین بار به آن نیاز باشد ایجاد می‌شود.

class turtle.TurtleScreen(cv)
پارامترها:

cv -- یک tkinter.Canvas

متدهای صفحه‌محوری مانند bgcolor() و غیره را فراهم می‌کند که در بالا توضیح داده شده‌اند.

class turtle.Screen

زیرکلاسی از TurtleScreen، با چهار متد افزوده‌شده.

class turtle.ScrolledCanvas(master)
پارامترها:

master -- یک ابزارک Tkinter برای دربرگرفتن ScrolledCanvas، یعنی یک بوم Tkinter با نوارهای پیمایش افزوده‌شده

توسط کلاس Screen استفاده می‌شود، که بنابراین به‌طور خودکار یک ScrolledCanvas را به‌عنوان زمین بازی برای لاک‌پشت‌ها فراهم می‌کند.

class turtle.Shape(type_, data)
پارامترها:

type_ -- یکی از رشته‌های "polygon"، "image"، "compound"

ساختار داده‌ای برای مدل‌سازی شکل‌ها. جفت (type_, data) باید این مشخصات را رعایت کند:

type_

data

"چندضلعی"

یک تاپل چندضلعی، یعنی یک تاپل از جفت‌های مختصات

"image"

یک تصویر (در این قالب فقط به‌صورت داخلی استفاده می‌شود!)

"compound"

None (یک شکل ترکیبی باید با استفاده از متد addcomponent() ساخته شود)
addcomponent(poly, fill, outline=None)
پارامترها:

  • poly -- یک چندضلعی، یعنی یک تاپل از جفت‌های عددی

  • fill -- رنگی که poly با آن پر خواهد شد

  • outline -- رنگی برای خط دور poly (در صورت داده‌شدن)

مثال:

>>> poly = ((0,0),(10,-5),(0,10),(-10,-5))
>>> s = Shape("compound")
>>> s.addcomponent(poly, "red", "blue")
>>> # ... add more components and then use register_shape()

شکل‌های ترکیبی را ببینید.

class turtle.Vec2D(x, y)

یک کلاس بردار دوبعدی، که به‌عنوان یک کلاس کمکی برای پیاده‌سازی گرافیک لاک‌پشتی (turtle graphics) استفاده می‌شود. ممکن است برای برنامه‌های گرافیک لاک‌پشتی نیز مفید باشد. از تاپلمشتق شده است، بنابراین بردار یک تاپل است!

فراهم می‌کند (برای بردارهای a و b، عدد k):

  • a + b جمع برداری

  • a - b تفریق برداری

  • a * b ضرب داخلی

  • ضرب k * a و a * k در اسکالر

  • abs(a) مقدار مطلق a

  • a.rotate(angle) چرخش

Exceptions

The turtle module defines the following exception:

exception turtle.TurtleGraphicsError

Raised for invalid arguments or operations. For example, a malformed color string:

>>> turtle.color("blau")
Traceback (most recent call last):
    ...
turtle.TurtleGraphicsError: bad color string: blau

توضیح

یک شیء turtle روی یک شیء screen ترسیم می‌کند، و تعدادی کلاس کلیدی در رابط شیءگرای turtle وجود دارد که می‌توان از آن‌ها برای ایجاد آن‌ها و برقراری ارتباط میان آن‌ها با یکدیگر استفاده کرد.

اگر نمونه‌ای از قبل موجود نباشد، یک نمونه Turtle به‌طور خودکار یک نمونه Screen ایجاد می‌کند.

Turtle زیرکلاسی از RawTurtle است که به‌طور خودکار یک سطح ترسیم ایجاد نمی‌کند — باید یک بوم برای آن فراهم یا ایجاد شود. این بوم می‌تواند یک tkinter.Canvas، ScrolledCanvas یا TurtleScreen باشد.

TurtleScreen سطح ترسیم پایه برای یک لاک‌پشت است. Screen زیرکلاسی از TurtleScreen است و شامل برخی متدهای اضافی برای مدیریت ظاهر آن (از جمله اندازه و عنوان) و رفتار آن است. سازنده‌ی TurtleScreen به یک tkinter.Canvas یا یک ScrolledCanvas به‌عنوان آرگومان نیاز دارد.

رابط تابعی برای گرافیک لاک‌پشتی از متدهای مختلف Turtle و TurtleScreen/Screen استفاده می‌کند. در پشت صحنه، هر زمان که تابعی مشتق‌شده از یک متد Screen فراخوانی شود، یک شیء صفحه به‌طور خودکار ایجاد می‌شود. به‌طور مشابه، هر زمان که هر یک از توابع مشتق‌شده از یک متد Turtle فراخوانی شود، یک شیء لاک‌پشت به‌طور خودکار ایجاد می‌شود.

برای استفاده از چندین لاک‌پشت در یک صفحه، باید از رابط شیءگرا استفاده شود.

راهنما و پیکربندی

نحوه استفاده از help

متدهای عمومی کلاس‌های Screen و Turtle به‌طور گسترده‌ای از طریق رشته‌مستندها مستند شده‌اند. بنابراین می‌توان از آن‌ها به‌عنوان راهنمای برخط از طریق امکانات راهنمای پایتون استفاده کرد:

  • هنگام استفاده از IDLE، راهنماهای شناور (tooltips) امضاها و ردیفهای نخست رشته‌مستندهای فراخوانی‌های تابع/متد تایپ‌شده را نمایش می‌دهند.

  • فراخوانی 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 -- یک رشته، که به‌عنوان نام پرونده استفاده می‌شود

دیکشنری رشته‌مستندها (docstring dictionary) را ایجاد کرده و آن را در یک اسکریپت پایتون با نام پرونده داده‌شده بنویسید. این تابع باید به‌صراحت فراخوانی شود (کلاس‌های گرافیک لاک‌پشتی از آن استفاده نمی‌کنند). دیکشنری رشته‌مستندها در اسکریپت پایتون filename.py نوشته خواهد شد. این دیکشنری به‌عنوان الگویی برای ترجمه‌ی رشته‌مستندها به زبان‌های مختلف در نظر گرفته شده است.

اگر شما (یا دانش‌آموزان شما) می‌خواهید از turtle با راهنمای برخط به زبان مادری خود استفاده کنید، باید رشته‌مستندها را ترجمه کنید و پرونده حاصل را مثلاً با نام turtle_docstringdict_german.py ذخیره کنید.

اگر ورودی مناسبی در پرونده turtle.cfg خود داشته باشید، این دیکشنری در زمان ایمپورت خوانده می‌شود و جایگزین رشته‌مستندهای اصلی انگلیسی می‌شود.

در زمان نگارش این متن، دیکشنری‌های رشته مستند به زبان‌های آلمانی و ایتالیایی وجود دارند. (لطفاً درخواست‌ها را به glingl@aon.at ارسال کنید.)

چگونه Screen و Turtles را پیکربندی کنیم

پیکربندی پیش‌فرض توکار، ظاهر و رفتار ماژول قدیمی 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 هستند.

  • خط ۵ و ۶ با آرگومان‌های متد Screen.screensize متناظر هستند.

  • shape می‌تواند هر یک از شکل‌های توکار باشد، مثلاً arrow، turtle و غیره. برای اطلاعات بیشتر help(shape) را امتحان کنید.

  • اگر می‌خواهید از هیچ رنگ پرکننده‌ای استفاده نکنید (یعنی لاک‌پشت را شفاف کنید)، باید fillcolor = "" را بنویسید (اما تمام رشته‌های غیرخالی نباید در پرونده cfg علامت نقل‌قول داشته باشند).

  • اگر می‌خواهید لاک‌پشت وضعیت خود را منعکس کند، باید از resizemode = auto استفاده کنید.

  • اگر برای مثال language = italian را تنظیم کنید، دیکشنری docstring turtle_docstringdict_italian.py در زمان ایمپورت بارگذاری خواهد شد (اگر در مسیر ایمپورت وجود داشته باشد، برای مثال در همان پوشه‌ای که turtle در آن قرار دارد).

  • مدخل‌های exampleturtle و examplescreen نام‌های این شیء‌ها را، همان‌گونه که در رشته‌مستندها آمده‌اند، تعریف می‌کنند. تبدیل رشته‌مستندهای متد به رشته‌مستندهای تابع، این نام‌ها را از رشته‌مستندها حذف خواهد کرد.

  • using_IDLE: اگر به‌طور منظم با IDLE و گزینه‌ی -n آن («بدون زیرفرایند») کار می‌کنید، این را روی True تنظیم کنید. این کار مانع از ورود exitonclick() به حلقه اصلی می‌شود.

ممکن است یک پرونده turtle.cfg در پوشه‌ای که turtle در آن ذخیره شده است وجود داشته باشد و یک پرونده دیگر نیز در پوشه کاری فعلی وجود داشته باشد. دومی تنظیمات اولی را بی‌اثر می‌کند.

پوشه‌ی Lib/turtledemo شامل یک پرونده‌ی turtle.cfg است. می‌توانید آن را به‌عنوان نمونه بررسی کنید و اثرات آن را هنگام اجرای دموها مشاهده کنید (ترجیحاً نه از درون نمایشگر دمو).

turtledemo --- اسکریپت‌های نمایشی

بسته‌ی turtledemo شامل مجموعه‌ای از اسکریپت‌های نمایشی است. این اسکریپت‌ها را می‌توان با استفاده از نمایشگر نمایشی ارائه‌شده به صورت زیر اجرا و مشاهده کرد:

python -m turtledemo

به‌عنوان جایگزین، می‌توانید اسکریپت‌های نمایشی را به‌صورت جداگانه اجرا کنید. برای مثال،

python -m turtledemo.bytedesign

پوشه‌ی بسته‌ی turtledemo شامل:

  • یک نمایشگر نمونه __main__.py که می‌توان از آن برای مشاهده‌ی کد منبع اسکریپت‌ها و اجرای همزمان آن‌ها استفاده کرد.

  • چندین اسکریپت که ویژگی‌های مختلف ماژول turtle را نشان می‌دهند. می‌توانید به نمونه‌ها از طریق منوی Examples دسترسی داشته باشید. همچنین می‌توان آن‌ها را به‌صورت مستقل اجرا کرد.

  • یک پرونده turtle.cfg که به‌عنوان نمونه‌ای از چگونگی نوشتن و استفاده از چنین پرونده‌هایی به کار می‌رود.

اسکریپت‌های نمایشی عبارتند از:

نام

توضیحات

امکانات

bytedesign

الگوی کلاسیک پیچیده‌ی گرافیک لاک‌پشتی

tracer(), delay(), update()

chaos

نمودار پویایی‌های Verhulst را رسم می‌کند و نشان می‌دهد که محاسبات رایانه گاهی می‌تواند نتایجی برخلاف انتظارات عقل سلیم تولید کند

مختصات جهانی

clock

ساعت عقربه‌ای که زمان رایانه‌ی شما را نشان می‌دهد

لاک‌پشت‌ها به‌عنوان عقربه‌های ساعت، ontimer()

colormixer

با r، g و b آزمایش کنید

ondrag()

forest

۳ درخت سطح‌اول

تصادفی‌سازی

fractalcurves

منحنی‌های هیلبرت و کخ

بازگشت

lindenmayer

ریاضیات قومی (کولام‌های هندی)

ال‌سیستم (L-System)

minimal_hanoi

برج‌های هانوی

لاک‌پشت‌های مستطیلی به‌عنوان دیسک‌های هانوی (shape(), shapesize())

nim

بازی کلاسیک نیم (Nim) را با سه هیپ چوب در برابر رایانه انجام دهید.

لاک‌پشت‌ها به‌عنوان nimsticks، رویدادمحور (ماوس، صفحه‌کلید)

paint

برنامه‌ی ترسیم بسیار ساده‌گرا

onclick()

peace

مقدماتی

turtle: ظاهر و پویانمایی

penrose

کاشی‌کاری غیرتناوبی با بادبادک‌ها و تیرها

stamp()

planet_and_moon

شبیه‌سازی سامانه گرانشی

شکل‌های ترکیبی، Vec2D

rosette

الگویی از مقاله‌ی ویکی‌پدیا درباره‌ی گرافیک لاک‌پشتی

clone(), undo()

round_dance

لاک‌پشت‌های رقصانی که به‌صورت جفتی در جهت مخالف می‌چرخند

شکل‌های مرکب، clone() shapesize()، tilt()، get_shapepoly()، update()

sorting_animate

نمایش بصری روش‌های مختلف مرتب‌سازی

چینش ساده، تصادفی‌سازی

tree

یک درخت پیمایش سطح اول (گرافیکی) (با استفاده از تولیدگرها)

clone()

two_canvases

طراحی ساده

لاک‌پشت‌ها روی دو بوم

yinyang

مثالی ساده‌ی دیگر

circle()

لذت ببرید!

تغییرات از پایتون 2.6

  • متدهای Turtle.tracer، Turtle.window_width و Turtle.window_height حذف شده‌اند. متدهایی با این نام‌ها و کارکرد، اکنون فقط به‌عنوان متدهایی از Screen در دسترس هستند. توابع مشتق‌شده از این متدها همچنان در دسترس هستند. (در واقع، این متدها از همان Python 2.6 صرفاً تکراری از متدهای متناظر TurtleScreen/Screen بودند.)

  • متد Turtle.fill() حذف شده است. رفتار begin_fill() و end_fill() اندکی تغییر کرده است: اکنون هر فرآیند پر کردن باید با یک فراخوانی end_fill() تکمیل شود.

  • متد Turtle.filling افزوده شده است. این متد یک مقدار بولی برمی‌گرداند: اگر فرایند پر کردن در حال انجام باشد، True و در غیر این صورت False. این رفتار معادل یک فراخوانی fill() بدون آرگومان در Python 2.6 است.

تغییرات از پایتون 3.0

  • متدهای shearfactor()، shapetransform() و get_shapepoly() برای Turtle افزوده شده‌اند. بنابراین طیف کاملی از تبدیلات خطی منظم اکنون برای تبدیل شکل‌های لاک‌پشت در دسترس است. tiltangle() از نظر عملکرد بهبود یافته است: اکنون می‌توان از آن برای دریافت یا تنظیم زاویه کجی استفاده کرد.

  • متد onkeypress() از Screen به‌عنوان مکملی برای onkey() اضافه شده است. از آنجا که دومی اکشن را به رویداد رها شدن کلید مقید می‌کند، نام مستعاری نیز برای آن اضافه شد: onkeyrelease().

  • متد Screen.mainloop افزوده شده است، بنابراین دیگر نیازی به استفاده از تابع مستقل mainloop() هنگام کار با اشیاء Screen و Turtle نیست.

  • دو متد ورودی افزوده شده‌اند: Screen.textinput و Screen.numinput. این متدها پنجره‌های محاوره‌ای ورودی را به‌صورت بازشو نمایش می‌دهند و به‌ترتیب رشته‌ها و اعداد را برمی‌گردانند.