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

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

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

گرافیک لاک‌پشت پیاده‌سازی ابزارهای ترسیم معرفی‌شده در Logo در سال ۱۹۶۷ است. این ابزار به‌عنوان یک ابزار آموزشی ایجاد‌شده، و بازخورد آنی و قابل‌مشاهده‌ی آن، آن را به روشی مؤثر برای یادگیرندگان جهت آشنایی با مفاهیم برنامه‌نویسی تبدیل می‌کند. این همچنین روشی راحت برای تولید خروجی گرافیکی ساده بدون وارد کردن کتابخانه‌های خارجی است.

این سند شامل چهار بخش اصلی است:

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

نکته

گرافیک لاک‌پشت به tkinter ماژول اختیاری نیاز دارد. نصب‌کننده‌های python.org برای ویندوز و macOS آن را شامل می‌شوند، اما برخی توزیع‌های لینوکس و سایر پلتفرم‌ها ممکن است آن را به‌صورت جداگانه بسته‌بندی کنند. اگر import turtle با خطایی که به _tkinter اشاره می‌دارد شکست‌خورد، به دنبال مستندات از توزیع‌کننده‌ی خود بگردید (یعنی کسی که پایتون را به شما ارائه‌کرده است). اگر قصد دارید از گرافیک لاک‌پشت با یک یادگیرنده استفاده کنید، این را از‌پیش بررسی کنید.

آموزش¶

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

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

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

from turtle import *

اگر با خطای Standard library module '_tkinter' was not found مواجه شدید، باید بسته رابط کاربری Tk را روی سیستم خود نصب کنید.

هنوز هیچ چیزی ظاهر نشده است. برای باز کردن پنجره‌ی turtle، لاک‌پشت را نمایان کنید:

showturtle()

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

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

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

forward(100)

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

left(120)

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

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

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

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

کنترل قلم¶

تغییر رنگ - برای مثال، 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 روش خوبی برای دانستن زمانی است که لاک‌پشت به موقعیت آغازین خود بازگشته است.

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

end_fill()

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

ارجاع¶

متدها و توابع 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.goto(60,30)
>>> turtle.pos()
(60.00,30.00)
>>> turtle.goto((20,80))
>>> turtle.pos()
(20.00,80.00)
>>> turtle.goto(tp)
>>> turtle.pos()
(0.00,0.00)

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

پارامترها:

x -- یک عدد یا None
y -- یک عدد یا None
fill_gap -- یک بولی

لاک‌پشت (turtle) را به یک موقعیت مطلق منتقل کنید، یا فوراً حرکت دهید. برخلاف goto()، هیچ خطی رسم نمی‌شود. اگر x یا y داده نشود، آن مختصات به همان صورت حفظ می‌شود. سردرِ لاک‌پشت (turtle) تغییر نمی‌کند.

اگر لاک‌پشت (turtle) در حال پر کردن یک شکل باشد، شکل رسم‌شده تا این لحظه، قبل از انتقال کامل شده و پر می‌شود و پر کردن دوباره در موقعیت جدید آغاز می‌شود. برای ادامه‌ی پر کردن یک شکل، fill_gap=True را ارسال کنید. سپس انتقال مانند goto() به عنوان یک ضلع از شکل محاسبه می‌شود.

>>> 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 لاک‌پشت را روی x تنظیم کنید؛ مختصات y بدون تغییر می‌ماند.

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

turtle.sety(y)¶

پارامترها:: y -- یک عدد

مختصات y لاک‌پشت را روی y تنظیم کنید؛ مختصات x بدون تغییر می‌ماند.

>>> 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 -- یک عدد صحیح (integer) مثبت یا None
color -- یک رشته‌ی رنگ یا یک تاپل عددی رنگ

با استفاده از color، یک نقطه‌ی دایره‌ای با قطر size رسم کنید. اگر size داده نشود، بزرگ‌ترین مقدار بین pensize + 4 و 2 * pensize استفاده می‌شود. اگر color داده نشود، رنگ قلم فعلی به کار می‌رود.

>>> 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 -- یک عدد صحیح (integer)، یک رشته (string) یا None

سرعت لاک‌پشت (turtle) را برگردانید یا تنظیم کنید. اگر speed داده نشود، سرعت فعلی برگردانده می‌شود. در غیر این صورت، سرعت لاک‌پشت (turtle) را روی یک عدد صحیح (integer) از 0 تا 10 تنظیم کنید. اگر speed عددی بزرگ‌تر از 10 یا کوچک‌تر از 0.5 باشد، سرعت روی 0 تنظیم می‌شود. همچنین می‌توانید به‌جای اعداد از این نام‌ها استفاده کنید:

"fastest": 0
"fast": 10
"normal": 6
"slow": 3
"slowest": 1

سرعت‌های بین 1 تا 10 پویانمایی سریع‌تری برای رسم خط و چرخش لاک‌پشت (turtle) فراهم می‌کنند. سرعت 0 به این معناست که هیچ پویانمایی‌ای انجام نمی‌شود: forward() و back() باعث پرش لاک‌پشت (turtle) می‌شوند و به همین ترتیب left() و right() باعث چرخش آنی لاک‌پشت (turtle) می‌شوند.

>>> 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) میرود را برمیگرداند. اگر y برابر None باشد، x باید یک جفت مختصات، یک Vec2D (برای مثال مقداری که توسط pos() بازگردانده میشود) یا یک لاکپشت دیگر باشد. زاویه نسبت به جهتگیری اولیهی لاکپشت اندازهگیری میشود؛ این جهتگیری به حالت لاکپشت بستگی دارد، mode() را ببینید.

>>> 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) را بر حسب واحدهای گام لاک‌پشت برمی‌گرداند. اگر y برابر None باشد، x باید یک جفت مختصات یا یک Vec2D باشد (مثلاً مانند مقداری که توسط pos() بازگردانده می‌شود) یا یک لاک‌پشت دیگر.

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

واحد اندازه‌گیری زاویه را روی درجه تنظیم کنید. تعداد درجه‌های یک دایره‌ی کامل با 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) هنگام حرکت، یک خط رسم می‌کند.

turtle.penup()¶
turtle.pu()¶
turtle.up()¶: قلم را بالا ببرید. لاک‌پشت (turtle) هنگام حرکت چیزی رسم نمی‌کند.

turtle.pensize(width=None)¶

turtle.width(width=None)¶

پارامترها:: width -- یک عدد مثبت یا None

ضخامت خط را برگردانید یا تنظیم کنید. اگر width داده نشود، اندازه‌ی قلم فعلی برگردانده می‌شود. اگر resizemode روی «auto» تنظیم شده باشد و شکل لاک‌پشت (turtle) یک چندضلعی باشد، آن چندضلعی با همان ضخامت خط رسم می‌شود.

>>> 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): رنگ قلم را روی colorstring تنظیم کنید؛ که یک رشته‌ی (string) مشخصات رنگ Tk است، مانند "red"، "yellow"، یا "#33cc8c".
pencolor((r, g, b)): رنگ قلم را روی رنگ RGB نشان‌داده‌شده توسط تاپلِ r، g و b تنظیم کنید. هر یک از r، g و b باید بین 0 و colormode باشند، که در آن colormode برابر با 1.0 یا 255 است (به colormode() مراجعه کنید).
pencolor(r, g, b): رنگ قلم را روی رنگ RGB مشخص‌شده توسط r، g و b تنظیم کنید. هر کدام از r، g و b باید بین ۰ و colormode باشند.

اگر شکل لاک‌پشت (turtle) یک چندضلعی باشد، حاشیه‌ی آن چندضلعی با رنگ قلم تازه‌تنظیم‌شده رسم می‌شود.

>>> 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)): رنگ پر کردن را روی رنگ RGB مشخص‌شده توسط تاپل r، g و b تنظیم کنید. هر کدام از r، g و b باید بین ۰ و colormode باشند، که در آن colormode برابر با ۱.۰ یا ۲۵۵ است (نگاه کنید به colormode()).
fillcolor(r, g, b): رنگ پر کردن را روی رنگ RGB مشخص‌شده توسط r، g و b تنظیم کنید. هر کدام از r، g و b باید بین ۰ و colormode باشند.

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

>>> 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, /)

رنگ قلم و رنگ پر کردن را برگردانید یا تنظیم کنید.

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

color(): رنگ قلم فعلی و رنگ پر کردن فعلی را به‌صورت یک جفت از رشته‌ها یا تاپل‌های مشخصه‌ی رنگ، همان‌گونه که pencolor() و fillcolor() بازمی‌گردانند، برمی‌گرداند.
color(colorstring), color((r,g,b)), color(r,g,b): ورودی‌ها مانند pencolor() هستند. هم رنگ قلم و هم رنگ پر کردن را روی مقدار داده‌شده تنظیم کنید.
color(colorstring1, colorstring2), color((r1,g1,b1), (r2,g2,b2)): معادل pencolor(colorstring1) و fillcolor(colorstring2) است و اگر از قالب ورودی دیگر استفاده شود، به‌طور مشابه عمل می‌کند.

اگر شکل لاک‌پشت (turtle) یک چندضلعی باشد، حاشیه و درون آن چندضلعی با رنگ‌های تازه‌تنظیم‌شده رسم می‌شوند.

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

اگر لاک‌پشت (turtle) در حال پر کردن باشد، 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.showturtle()¶
turtle.st()¶: لاک‌پشت را نمایان کنید.

turtle.isvisible()¶

اگر لاک‌پشت (turtle) مرئی باشد True و اگر پنهان باشد False را برگردانید.

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

ظاهر¶

turtle.shape(name=None)¶

پارامترها:: name -- یک رشته یا None

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

>>> turtle.shape()
'classic'
>>> turtle.shape("turtle")
>>> turtle.shape()
'turtle'

turtle.resizemode(rmode=None)¶

پارامترها:: rmode -- یک رشته یا None

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

"auto": اندازه‌ی لاک‌پشت (turtle) بر اساس مقدار pensize() تغییر می‌کند.
"user": اندازه‌ی لاک‌پشت (turtle) بر اساس عوامل کشش و عرض حاشیه که توسط shapesize() تنظیم شده‌اند، تغییر می‌کند.
"noresize": اندازه‌ی لاک‌پشت (turtle) تغییر نمی‌کند.

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 -- یک عدد مثبت یا None
stretch_len -- یک عدد مثبت یا None
outline -- یک عدد مثبت یا None

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

stretch_wid: عامل کشش عمود بر جهت حرکت لاک‌پشت (turtle)
stretch_len: عامل کشش در راستای جهت حرکت لاک‌پشت (turtle)
outline: عرض حاشیه‌ی شکل

برای نمونه، shapesize(2, 1) لاک‌پشت را بدون تغییر طول، دو برابر پهن‌تر می‌کند. اگر تنها پارامتر stretch_wid داده شود، stretch_len روی همان مقدار تنظیم می‌شود.

>>> 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 -- تابعی با دو آرگومان یا None
btn -- یک عدد صحیح
add -- یک بولین یا None

fun را به رویدادهای کلیک ماوس روی این لاک‌پشت متصل کنید. fun با مختصات نقطه‌ی کلیک‌شده روی بوم فراخوانی می‌شود. اگر fun None باشد، اتصال‌های موجود حذف می‌شوند. btn شماره‌ی دکمه‌ی ماوس است و به‌طور پیش‌فرض ۱ است، یعنی دکمه‌ی چپ ماوس. اگر add True باشد، یک اتصال جدید اضافه می‌شود، در غیر این صورت یک اتصال پیشین را جایگزین می‌کند. مثالی برای لاک‌پشت ناشناس، یعنی روش رویه‌ای:

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

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

>>> leonel = Turtle()
>>> marco = leonel.clone()

turtle.getturtle()¶

turtle.getpen()¶

خود شیء Turtle را برمی‌گرداند.

برای دریافت لاک‌پشتِ مورد استفاده‌ی توابع مانند forward() و left()، تابع getturtle() را فراخوانی کنید:

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

متدها و توابع 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 باید بین ۰ و 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 -- یک عدد
lly -- یک عدد
urx -- یک عدد
ury -- یک عدد

یک سیستم مختصات تعریف‌شده توسط کاربر تنظیم کنید. llx و lly مختصات x و y گوشه‌ی پایین چپ بوم هستند. urx و ury مختصات x و y گوشه‌ی بالا راست هستند. در صورت لزوم به حالت "world" بروید که بازنشانی را انجام می‌دهد. اگر حالت "world" از قبل فعال باشد، تمام ترسیمات بر اساس مختصات جدید دوباره ترسیم می‌شوند. در سیستم‌های مختصات تعریف‌شده توسط کاربر، زوایا ممکن است تحریف‌شده به نظر برسند، mode() را ببینید.

>>> 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 را به‌طور موقت غیرفعال می‌کند. کد نوشته‌شده درون بلوک with پویانمایی نخواهد شد؛ پس از خروج از بلوک کد، ترسیم ظاهر می‌شود. این برای رسم شکل‌های پیچیده‌ای مفید است که حتی سریع‌ترین تنظیم سرعت نیز برای آن‌ها بسیار کند است.

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

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

turtle.delay(delay=None)¶

پارامترها:: delay -- یک عدد صحیح نامنفی یا None

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

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

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

پارامترها:

n -- یک عدد صحیح نامنفی یا None
delay -- یک عدد صحیح نامنفی یا None

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

>>> 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 -- تابعی با دو آرگومان یا None
btn -- یک عدد صحیح
add -- یک بولین یا None

fun را به رویدادهای کلیک ماوس روی این صفحه متصل کنید. fun با مختصات نقطه‌ی کلیک‌شده روی بوم فراخوانی می‌شود. اگر fun None باشد، اتصال‌های موجود حذف می‌شوند. btn شماره‌ی دکمه‌ی ماوس است و به‌طور پیش‌فرض ۱ است، یعنی دکمه‌ی چپ ماوس. اگر add True باشد، یک اتصال جدید اضافه می‌شود، در غیر این صورت یک اتصال پیشین را جایگزین می‌کند.

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

متدهای ورودی¶

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 -- یک عدد یا None
minval -- یک عدد یا None
maxval -- یک عدد یا None

یک پنجره‌ی محاوره برای دریافت یک عدد باز می‌کند. title عنوان پنجره‌ی محاوره است و prompt متنی است که توصیف می‌کند چه اطلاعات عددی باید وارد شود. default مقدار پیش‌فرض است، minval و maxval حداقل و حداکثر مقدار برای ورودی هستند. اگر این مقادیر داده شده باشند، عدد ورودی باید بین minval و maxval باشد. در غیر این صورت، یک راهنمایی نمایش داده می‌شود و پنجره‌ی محاوره برای اصلاح باز می‌ماند. عدد ورودی را برمی‌گرداند. اگر پنجره‌ی محاوره لغو شود، None برگردانده می‌شود.

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

تنظیمات و متدهای ویژه¶

turtle.mode(mode=None)¶

پارامترها:: mode -- یک رشته یا None

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

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

حالت	جهت اولیه لاک‌پشت	زوایای مثبت
"standard"	به سمت راست (شرق)	پادساعتگرد
"logo"	رو به بالا (شمال)	در جهت عقربه‌های ساعت

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

turtle.colormode(cmode=None)¶

پارامترها:: cmode -- یک عدد یا None

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

پارامترها:

name -- یک رشته
shape -- یک رشته، یک تاپل از جفت‌های عددی، یک شیء Shape یا None

یک شکل لاک‌پشت به فهرست شکل‌های TurtleScreen اضافه کنید. این تابع می‌تواند به چهار روش مختلف فراخوانی شود:

name نام یک پرونده تصویری (PNG، GIF، PGM و PPM) است و shape برابر None است: شکل تصویری متناظر نصب می‌شود.
```
>>> screen.register_shape("turtle.gif")
```
name یک رشته دلخواه است و shape نام یک پرونده تصویری (PNG، GIF، PGM و PPM) است: شکل تصویری متناظر را نصب کنید.
```
>>> screen.register_shape("turtle", "turtle.gif")
```
name یک رشته دلخواه است و shape تاپلی از جفت‌های مختصات است: شکل چندضلعی متناظر نصب می‌شود.
```
>>> screen.register_shape("triangle", ((5,-3), (0,5), (-5,-3)))
```
name یک رشته دلخواه است و shape یک شیء Shape (مرکب) است: شکل مرکب متناظر نصب می‌شود.

شکل‌های تصویری هنگام چرخاندن لاک‌پشت نمی‌چرخند، بنابراین جهت لاک‌پشت را نمایش نمی‌دهند. برای استفاده از یک شکل ثبت‌شده، shape() را با نام آن فراخوانی کنید.

تغییر یافته در نسخه‌ی 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¶

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، با چهار متد اضافه‌شده. فراخوانی Screen() تنها شیء صفحه را برمی‌گرداند. اگر هنوز وجود نداشته باشد، ایجاد می‌شود. در غیر این صورت شیء موجود برگردانده می‌شود.

class turtle.ScrolledCanvas(master)¶

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

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

class turtle.Shape(type_, data)¶

پارامترها:

type_ -- یک رشته
data -- به type_ بستگی دارد

ساختار داده‌ای که اشکال را مدل‌سازی می‌کند. type_ یکی از رشته‌های "polygon"، "image" یا "compound" است. اینکه data باید چه باشد به type_ بستگی دارد: برای "polygon" یک تاپل از جفت‌های مختصات، برای "image" یک تصویر (فقط به‌صورت داخلی استفاده می‌شود)، و برای "compound" None، زیرا یک شکل مرکب با استفاده از متد addcomponent() ساخته می‌شود.

addcomponent(poly, fill, outline=None)¶

پارامترها:

poly -- یک تاپل از جفت‌های عددی
fill -- یک رنگ
outline -- یک رنگ یا None

یک جزء به یک شکل از نوع "compound" اضافه کنید. poly یک چندضلعی است، یک تاپل از جفت‌های اعداد. fill رنگی است که چندضلعی با آن پر می‌شود و outline رنگ خط دور آن است. اگر outline داده نشده باشد، از fill برای آن نیز استفاده می‌شود.

مثال:

>>> 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) چرخش

استثناها¶

ماژول turtle استثنای زیر را تعریف می‌کند:

exception turtle.TurtleGraphicsError¶

برای آرگومان‌ها یا عملیات‌های نامعتبر رخ می‌دهد. برای مثال، یک رشته‌ی رنگِ نامناسب:

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

راهنماهای عملی¶

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

نحوه‌ی شروع و پایان خودکار پر کردن¶

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

یک شیء Shape خالی از نوع «compound» ایجاد کنید.

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

اکنون Shape را به shapelistِ Screen اضافه کنید و از آن استفاده کنید:
```
>>> register_shape("myshape", s)
>>> shape("myshape")
```

نحوه‌ی استفاده از فضای نام ماژول `turtle`¶

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

راه‌حل استفاده از 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)

البته یک مرحله دیگر نیز لازم است — به محض اینکه اسکریپت تمام شود، پایتون پنجره 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")

نحوه‌ی استفاده از `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()

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

ترجمه‌ی رشته‌مستندها به زبان‌های مختلف¶

The docstrings of the public methods of the Screen and Turtle classes, and of the corresponding functions, can be replaced with translations, so that help() and IDE tooltips are shown in another language. However, only the help text is translated, the names of the functions and methods stay the same.

Translations are distributed on PyPI in the turtle-translations package. To use them, install the package with pip and select the language with the PYTHON_TURTLE_LANG environment variable. For example, to show the help text in Spanish:

$ python -m pip install turtle-translations
$ PYTHON_TURTLE_LANG=es python
>>> import turtle
>>> help(turtle.forward)

The language can also be set permanently with the language entry of the turtle.cfg file (see چگونه Screen و Turtles را پیکربندی کنیم). If no translation is found for the selected language, the English docstrings are kept.

To add a new language or improve an existing translation, see the contribution instructions in the turtle-translations project.

A translation is a docstring dictionary. It is a top-level module named turtle_docstringdict_language.py on sys.path defining a dictionary named docsdict, the keys of which are method names such as Turtle.forward and the values of which are the translated docstrings. It is read in at import time. Entries naming a method which does not exist in the running version are ignored.

تغییر یافته در نسخه‌ی 3.16: Entries naming an unknown method are ignored instead of reported.

PYTHON_TURTLE_LANG¶: The name of the language to read the translation for. It takes precedence over the language entry of the turtle.cfg file.

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

turtle.write_docstringdict(filename='turtle_docstringdict')¶

پارامترها:: filename -- یک رشته، که به‌عنوان نام پرونده استفاده می‌شود

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

چگونه 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 استفاده کنید.
The language entry selects the language of the docstrings, unless the PYTHON_TURTLE_LANG environment variable is set. See ترجمه‌ی رشته‌مستندها به زبان‌های مختلف for more information.
مدخل‌های exampleturtle و examplescreen نام‌های این شیء‌ها را، همان‌گونه که در رشته‌مستندها آمده‌اند، تعریف می‌کنند. تبدیل رشته‌مستندهای متد به رشته‌مستندهای تابع، این نام‌ها را از رشته‌مستندها حذف خواهد کرد.
using_IDLE: اگر به‌طور منظم با IDLE و گزینه‌ی -n آن («بدون زیرفرایند») کار می‌کنید، این را روی True تنظیم کنید. این کار مانع از ورود exitonclick() به حلقه اصلی می‌شود.

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

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

توضیح¶

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

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

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

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

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

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

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

لذت ببرید!

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

آموزش¶

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

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

کنترل قلم¶

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

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

ارجاع¶

متدها و توابع Turtle¶

حرکت و ترسیم¶

گزارش وضعیت Turtle¶

تنظیمات اندازه‌گیری¶

کنترل قلم¶

وضعیت ترسیم¶

کنترل رنگ¶

پر کردن¶

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

وضعیت Turtle¶

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

ظاهر¶

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

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

متدها و توابع Screen¶

کنترل پنجره¶

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

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

متدهای ورودی¶

تنظیمات و متدهای ویژه¶

متدهای مختص Screen¶

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

استثناها¶

راهنماهای عملی¶

نحوه‌ی شروع و پایان خودکار پر کردن¶

نحوه‌ی استفاده از اشکال ترکیبی¶

نحوه‌ی استفاده از فضای نام ماژول turtle¶

نحوه‌ی استفاده از گرافیک لاک‌پشت در یک اسکریپت¶

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

نحوه‌ی استفاده از help()¶

ترجمه‌ی رشته‌مستندها به زبان‌های مختلف¶

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

توضیح¶

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

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

نحوه‌ی استفاده از فضای نام ماژول `turtle`¶

نحوه‌ی استفاده از `help()`¶

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