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

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

---

Turtle star

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

یک لاک‌پشت رباتی را تصور کنید که در مختصات (۰، ۰) در صفحه 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 a copy of the turtle shape onto the canvas and return its id. The stamp is placed at the current turtle position. The returned id can be used to delete the stamp with clearstamp().

>>> turtle.color("blue")
>>> stamp_id = turtle.stamp()
>>> turtle.fd(50)

turtle.clearstamp(stampid)

پارامترها:

stampid -- یک عدد صحیح

Delete the stamp with the given stampid. stampid must be the return value of a previous stamp() call.

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

Delete all or the first or last n of the turtle's stamps. If n is not given, delete all stamps. If n is positive, delete the first n stamps. If n is negative, delete the last n stamps, so -2 deletes the last two.

>>> 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 -- a dictionary or None

• pendict -- keyword arguments with the keys below

Return or set the pen's attributes. The attributes are returned as a dictionary with the following keys and values:

• "shown": True or False

• "pendown": True or False

• "pencolor": a color string or a color tuple

• "fillcolor": a color string or a color tuple

• "pensize": a positive number

• "speed": a number from 0 to 10

• "resizemode": "auto", "user" or "noresize"

• "stretchfactor": a pair of positive numbers

• "shearfactor": a number

• "outline": a positive number

• "tilt": a number

Such a dictionary can be passed as pen to restore a former pen state. The attributes can also be given as keyword arguments, which can be used to set several of them in one statement.

>>> turtle.pen(fillcolor="black", pencolor="red", pensize=10)
>>> turtle.pen()
{'shown': True, 'pendown': True, 'pencolor': 'red', 'fillcolor': 'black',
 'pensize': 10, 'speed': 9, 'resizemode': 'noresize',
 'stretchfactor': (1.0, 1.0), 'shearfactor': 0.0, 'outline': 1,
 'tilt': 0.0}
>>> penstate = turtle.pen()
>>> turtle.color("yellow", "")
>>> turtle.penup()
>>> turtle.pen()["pencolor"]
'yellow'
>>> # restore the saved pen state, but with a green fill
>>> turtle.pen(penstate, fillcolor="green")
>>> turtle.pen()["pencolor"]
'red'
>>> turtle.pen()["fillcolor"]
'green'

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

Fill the shape drawn in the with block.

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

fill() is a context manager, so using it is the same as calling begin_fill() before the block and end_fill() after it:

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

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

turtle.begin_fill()

Call just before drawing a shape to be filled. The shape is filled by the next call to end_fill().

turtle.end_fill()

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

If the shape crosses itself or several shapes overlap, whether the overlapping parts are filled depends on the operating system, the type of overlap and how many there are. For example, the turtle star above may be either all yellow or have some white regions.

>>> 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 -- an object

• move -- یک بولی

• align -- یک رشته

• font -- a tuple of a string, an integer and a string

Write text at the current turtle position. The text is the string representation of arg. align is one of the strings "left", "center" or "right" and says how the text is placed relative to the turtle position. font is a triple of font name, font size and font type. If move is True, the pen is moved to the bottom-right corner of the text.

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

Return or set the current shear factor. Shearing slants the turtle shape, like the slant of italic letters. The shear factor says how much it is slanted: 0 is not slanted at all, and the larger the number, the stronger the slant. Negative numbers slant the other way. If shear is not given, return the current shear factor. Otherwise slant the turtle shape accordingly and set resizemode to "user". The turtle's heading does not change. Precisely, the shear factor is the tangent of the shear angle.

>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.shearfactor(0.5)
>>> turtle.shearfactor()
0.5

turtle.tilt(angle)

پارامترها:

angle -- یک عدد

Turn the turtle shape by angle from its current tilt angle. The turtle's heading does not change, so the turtle keeps moving in the same direction. See tiltangle().

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

Return or set the current tilt angle. The tilt angle is the angle between the direction the turtle shape points in and the direction the turtle moves in. Normally the shape points in the direction of movement, so the tilt angle is 0. If angle is given, turn the turtle shape to that tilt angle, no matter what it was before, and set resizemode to "user". The turtle's heading does not change. If angle is not given, return the current tilt 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 -- یک عدد یا None

• t12 -- یک عدد یا None

• t21 -- یک عدد یا None

• t22 -- یک عدد یا None

Return or set the transformation matrix of the turtle shape. The matrix combines the stretch factors, the shear factor and the tilt angle of the turtle shape into four numbers: t11 and t12 form its first row, t21 and t22 its second. If none of them are given, return the current matrix as a tuple of four numbers. Otherwise set the given elements and update the stretch factors, shear factor and tilt angle accordingly. t11 * t22 - t12 * t21 must not be zero, otherwise an error is raised.

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

Return the points that form the outline of the current turtle shape as a tuple of (x, y) coordinate pairs. These points can be used to define a new shape or parts of a compound shape

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

Record the vertices of a polygon drawn in the with block. The first and last vertices will be connected.

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

poly() is a context manager, so using it is the same as calling begin_poly() before the block and end_poly() after it:

>>> turtle.begin_poly()
>>> turtle.forward(100)
>>> turtle.right(60)
>>> turtle.forward(100)
>>> turtle.end_poly()

اضافه شده در نسخه‌ی 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 -- یک رشته یا None

Set the background image or return the name of the current one. If picname is the name of an image file (PNG, GIF, PGM, and PPM), set that image as the background. If picname is "nopic", delete the background image, if present. If picname is None, return the filename of the current background image.

>>> 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 -- یک عدد صحیح (integer) مثبت یا None

• canvheight -- یک عدد صحیح (integer) مثبت یا None

• bg -- a colorstring or a color tuple or None

Resize the canvas the turtles are drawing on. canvwidth and canvheight are the new width and height of the canvas in pixels, and bg is the new background color. If no arguments are given, return the current canvas width and height.

The drawing window is not altered. To see hidden parts of the canvas, use the scrollbars. This can make visible those parts of a drawing which were outside the canvas before, for example to find a turtle that has wandered off the canvas.

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

پارامترها:

• xdummy -- ignored

• ydummy -- ignored

Set focus on the TurtleScreen so that it receives key events. The two dummy arguments are only there so that listen() can be passed to onclick().

turtle.onkey(fun, key)

turtle.onkeyrelease(fun, key)

پارامترها:

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

• key -- یک رشته

Bind fun to the key-release event of key. key is a key, such as "a", or a key symbol, such as "space". If fun is None, the event binding is removed. To be able to receive key events, the TurtleScreen must have focus, see listen().

>>> def f():
...     fd(50)
...     lt(60)
...
>>> screen.onkey(f, "Up")
>>> screen.listen()

The turtle can then be moved by repeatedly pressing the up-arrow key, drawing a hexagon.

turtle.onkeypress(fun, key=None)

پارامترها:

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

• key -- یک رشته یا None

Bind fun to the key-press event of key. key is a key, such as "a", or a key symbol, such as "space". If key is not given, fun is bound to the key-press event of any key. If fun is None, the event binding is removed. To be able to receive key events, the TurtleScreen must have focus, see listen().

>>> def f():
...     fd(50)
...     lt(60)
...
>>> screen.onkeypress(f, "Up")
>>> screen.listen()

The turtle can then be moved by pressing or holding down the up-arrow key, drawing a hexagon.

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 -- a nonnegative number

یک زمان‌سنج نصب کنید که 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 اضافه کنید. این تابع می‌تواند به چهار روش مختلف فراخوانی شود:

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 (مرکب) است: شکل مرکب متناظر نصب می‌شود.

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

پارامترها:

• filename -- یک رشته

• overwrite -- یک بولی

Save the current drawing and the turtles as a PostScript file. filename is the path of the file to create. It must end with ".ps" or ".eps". If a file with that name already exists, a FileExistsError is raised, unless overwrite is True. overwrite must be given by name, as in overwrite=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 استفاده کنید، همان‌طور که در زیر توضیح داده شده است:

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

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

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

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

ابزاری برای ایجاد یک دیکشنری وجود دارد که کلیدهای آن نام متدها و مقادیر آن رشته‌مستندهای متدهای عمومی کلاس‌های 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 است. می‌توانید آن را به‌عنوان نمونه بررسی کنید و اثرات آن را هنگام اجرای دموها مشاهده کنید (ترجیحاً نه از درون نمایشگر دمو).

توضیح

یک شیء 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()

لذت ببرید!