کنترل قلم¶

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

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

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

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

home()

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

pos()

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

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

clearscreen()

حرکت و ترسیم¶

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() باشد

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

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

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)

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

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

کنترل پنجره¶

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

تصویر پس‌زمینه را تنظیم می‌کند یا نام تصویر پس‌زمینه‌ی فعلی را برمی‌گرداند. اگر 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 -- یک عدد صحیح (integer) مثبت یا None

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

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

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

تمرکز را روی TurtleScreen تنظیم کنید (برای جمع‌آوری رویدادهای کلید). آرگومان‌های ساختگی ارائه شده‌اند تا بتوانید listen() را به متد onclick بفرستید.

turtle.onkey(fun, key)¶

turtle.onkeyrelease(fun, key)¶

پارامترها:

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

• key -- یک رشته

fun را به رویداد رها شدن کلید متصل می‌کند. اگر fun برابر None باشد، اتصال‌های رویداد حذف می‌شوند. نکته: برای این‌که بتوانید رویدادهای کلید را ثبت کنید، TurtleScreen باید فوکوس را داشته باشد. (متد 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

fun را، اگر key داده‌شده باشد، به رویداد فشردن کلید مربوط به key، و اگر key داده‌نشده باشد، به هر رویداد فشردن کلید متصل می‌کند. نکته: برای آن که بتوانید رویدادهای کلید را ثبت کنید، TurtleScreen باید فوکوس داشته باشد. (متد listen() را ببینید.)

>>> def f():
...     fd(50)
...     lt(60)
...
>>> screen.onkey(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 -- عدد صحیح نامنفی

یک زمان‌سنج نصب کنید که 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!")