یک برنامه‌ی Hello World¶

با بررسی گام‌به‌گام یک برنامه‌ی «Hello World» در Tkinter شروع می‌کنیم. این کوچک‌ترین برنامه‌ای نیست که می‌توانستیم بنویسیم، اما به اندازه کافی برای نشان دادن برخی مفاهیم کلیدی که لازم است بدانید، دارد.

from tkinter import *
from tkinter import ttk
root = Tk()
frm = ttk.Frame(root, padding=10)
frm.grid()
ttk.Label(frm, text="Hello World!").grid(column=0, row=0)
ttk.Button(frm, text="Quit", command=root.destroy).grid(column=1, row=0)
root.mainloop()

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

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

خط بعدی یک ابزارک برچسب (label widget) ایجاد می‌کند که حاوی یک رشته‌ی متن ثابت است. از متد grid() برای مشخص کردن چیدمان نسبی (موقعیت) برچسب درون ابزارک قاب (frame widget) حاوی آن استفاده می‌شود، مشابه نحوه‌ی کار جدول‌ها در HTML.

سپس یک ابزارک دکمه ایجاد می‌شود و در سمت راست برچسب قرار می‌گیرد. هنگام فشرده‌شدن، متد destroy() پنجره ریشه را فراخوانی می‌کند.

در نهایت، متد mainloop() همه‌چیز را روی صفحه‌نمایش قرار می‌دهد و تا زمانی که برنامه خاتمه یابد، به ورودی کاربر پاسخ می‌دهد.

مفاهیم مهم Tk¶

حتی این برنامه‌ی ساده، مفاهیم کلیدی زیر از Tk را نشان می‌دهد:

ابزارک‌ها

رابط کاربری Tkinter از ابزارک‌های مجزا تشکیل شده است. هر ابزارک به‌صورت یک شیء پایتون نمایش داده می‌شود که از کلاس‌هایی مانند ttk.Frame، ttk.Label و ttk.Button نمونه‌سازی شده است.

سلسله‌مراتب ابزارک‌ها

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

گزینه‌های پیکربندی

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

مدیریت هندسه (geometry management)

ابزارک‌ها به‌طور خودکار هنگامی که ایجاد می‌شوند به رابط کاربری اضافه نمی‌شوند. یک مدیر چیدمان مانند grid کنترل می‌کند که آن‌ها در کجای رابط کاربری قرار بگیرند.

حلقه رویداد

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

درک این‌که Tkinter چگونه Tcl/Tk را می‌پوشاند¶

هنگامی که برنامه شما از کلاس‌ها و متدهای Tkinter استفاده می‌کند، Tkinter به‌صورت داخلی رشته‌هایی را که نشان‌دهنده دستورات Tcl/Tk هستند، می‌سازد و آن دستورات را در مفسر Tcl متصل به نمونه Tk برنامه شما اجرا می‌کند.

چه بخواهید در مستندات مرجع پیمایش کنید، چه بخواهید متد یا گزینه مناسب را پیدا کنید، چه بخواهید برخی کدهای موجود را تطبیق دهید، یا چه بخواهید برنامه Tkinter خود را اشکال‌زدایی کنید، گاهی اوقات درک اینکه آن دستورات زیربنایی Tcl/Tk چه شکلی هستند، مفید خواهد بود.

برای روشن‌سازی، در اینجا معادل Tcl/Tk بخش اصلی اسکریپت Tkinter بالا آمده است.

ttk::frame .frm -padding 10
grid .frm
grid [ttk::label .frm.lbl -text "Hello World!"] -column 0 -row 0
grid [ttk::button .frm.btn -text "Quit" -command "destroy ."] -column 1 -row 0

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

• دستوراتی که برای ایجاد ابزارک‌ها به کار می‌روند (مانند ttk::frame) معادل کلاس‌های ابزارک در Tkinter هستند.

• گزینه‌های ابزارک Tcl (مانند -text) با آرگومان‌های کلیدواژه‌ای در Tkinter متناظر هستند.

• در Tcl، ابزارک‌ها با یک pathname (مانند .frm.btn) ارجاع داده می‌شوند، در حالی که Tkinter از نام‌ها استفاده نمی‌کند، بلکه از ارجاع‌های شیء استفاده می‌کند.

• جایگاه یک ابزارک در سلسله‌مراتب ابزارک‌ها، در مسیر سلسله‌مراتبی آن کدگذاری شده است؛ در این مسیر از . (نقطه) به‌عنوان جداکننده‌ی مسیر استفاده می‌شود. مسیر پنجره‌ی ریشه فقط . (نقطه) است. در Tkinter، سلسله‌مراتب نه با مسیر، بلکه با مشخص کردن ابزارک والد هنگام ایجاد هر ابزارک فرزند تعریف می‌شود.

• عملیاتی که به‌صورت دستورهای جداگانه در Tcl پیاده‌سازی شده‌اند (مانند grid یا destroy)، به‌صورت متدهایی روی اشیای ابزارک Tkinter ارائه می‌شوند. همان‌طور که به‌زودی خواهید دید، در موارد دیگر Tcl از مواردی استفاده می‌کند که به نظر می‌رسد فراخوانی متد روی اشیای ابزارک باشند و شباهت بیشتری به آنچه در Tkinter استفاده می‌شود دارند.

چگونه ...؟ چه گزینه‌ای ...؟¶

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

نخست، به یاد داشته باشید که جزئیات چگونگی کارکرد هر ابزارک ممکن است در نسخه‌های مختلف Tkinter و Tcl/Tk متفاوت باشد. اگر در حال جست‌وجوی مستندات هستید، اطمینان حاصل کنید که با نسخه‌های پایتون و Tcl/Tk نصب‌شده بر روی سیستم شما مطابقت دارد.

هنگام جست‌وجو درباره نحوه استفاده از یک API، دانستن نام دقیق کلاس، گزینه یا متدی که استفاده می‌کنید مفید است. درون‌نگری، چه در پوسته تعاملی پایتون و چه با print()، می‌تواند به شما کمک کند تا آنچه را که نیاز دارید شناسایی کنید.

برای اطلاع از گزینه‌های پیکربندی در دسترس برای هر ابزارک، متد configure() آن را فراخوانی کنید، که یک دیکشنری حاوی اطلاعات گوناگونی درباره هر شیء، از جمله مقادیر پیش‌فرض و فعلی آن برمی‌گرداند. برای دریافت فقط نام‌های هر گزینه از keys() استفاده کنید.

btn = ttk.Button(frm, ...)
print(btn.configure().keys())

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

print(set(btn.configure().keys()) - set(frm.configure().keys()))

به همین ترتیب، می‌توانید متدهای در دسترس برای یک شیء ابزارک را با استفاده از تابع استاندارد dir() پیدا کنید. اگر آن را امتحان کنید، خواهید دید که بیش از ۲۰۰ متد مشترک ابزارک وجود دارد، بنابراین باز هم شناسایی آن‌هایی که مختص یک کلاس ابزارک هستند، مفید است.

print(dir(btn))
print(set(dir(btn)) - set(dir(frm)))

پیمایش راهنمای مرجع Tcl/Tk¶

همان‌طور که اشاره شد، مرجع رسمی Tk commands (صفحات man) اغلب دقیق‌ترین توصیف را از عملکرد عملیات خاص روی ابزارک‌ها ارائه می‌دهد. حتی وقتی نام گزینه یا متدی را که نیاز دارید می‌دانید، ممکن است همچنان لازم باشد به چند جا مراجعه کنید.

در حالی که تمام عملیات‌ها در Tkinter به‌صورت فراخوانی متد روی اشیاء ابزارک پیاده‌سازی شده‌اند، دیده‌اید که بسیاری از عملیات‌های Tcl/Tk به‌صورت دستورهایی ظاهر می‌شوند که مسیر نام ابزارک را به‌عنوان نخستین پارامتر خود می‌گیرند و پس از آن پارامترهای اختیاری قرار دارند، برای مثال

destroy .
grid .frm.btn -column 0 -row 0

با این حال، برخی دیگر بیشتر شبیه متدهایی هستند که روی یک شیء ابزارک فراخوانی می‌شوند (در واقع، هنگامی که یک ابزارک در Tcl/Tk ایجاد می‌کنید، یک فرمان Tcl با نام مسیر ابزارک ایجاد می‌شود که اولین پارامتر آن فرمان، نام متدی است که باید فراخوانی شود).

.frm.btn invoke
.frm.lbl configure -text "Goodbye"

در مستندات مرجع رسمی Tcl/Tk، بیشتر عملیاتی را که شبیه فراخوانی متد هستند، در صفحه‌ی man مربوط به یک ابزارک مشخص خواهید یافت (برای مثال، متد invoke() را در صفحه‌ی man ttk::button خواهید یافت)، در حالی که توابعی که یک ابزارک را به‌عنوان پارامتر می‌گیرند، اغلب صفحه‌ی man مخصوص به خود را دارند (برای مثال، grid).

بسیاری از گزینه‌ها و متدهای رایج را در صفحه‌های man مربوط به options یا ttk::widget خواهید یافت، در حالی که سایر موارد در صفحه man مربوط به یک کلاس ابزارک خاص یافت می‌شوند.

همچنین خواهید دید که بسیاری از متدهای Tkinter نام‌های ترکیبی دارند، برای مثال، winfo_x()، winfo_height()، winfo_viewable(). مستندات همه‌ی این‌ها را در صفحه‌ی راهنمای winfo خواهید یافت.

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

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

در زمان ایجاد شیء، با استفاده از آرگومان‌های کلیدواژه‌ای

fred = Button(self, fg="red", bg="blue")

پس از ایجاد شیء، رفتار با نام گزینه مانند یک اندیس دیکشنری

fred["fg"] = "red"
fred["bg"] = "blue"

برای به‌روزرسانی چندین ویژگی پس از ایجاد شیء، از متد config() استفاده کنید

fred.config(fg="red", bg="blue")

برای توضیح کامل یک گزینه مشخص و رفتار آن، به صفحات man مربوط به Tk برای ابزارک موردنظر مراجعه کنید.

توجه داشته باشید که صفحه‌های man برای هر ابزارک، «STANDARD OPTIONS» و «WIDGET SPECIFIC OPTIONS» را فهرست می‌کنند. مورد اول فهرستی از گزینه‌هایی است که بین بسیاری از ابزارک‌ها مشترک هستند؛ مورد دوم گزینه‌هایی هستند که مخصوص همان ابزارک خاص‌اند. گزینه‌های استاندارد در صفحه‌ی man options(3) مستند شده‌اند.

در این سند هیچ تمایزی بین گزینه‌های استاندارد و گزینه‌های مختص ابزارک قائل نشده است. برخی گزینه‌ها برای برخی انواع ابزارک‌ها کاربرد ندارند. این‌که یک ابزارک مشخص به یک گزینه‌ی خاص پاسخ دهد یا نه، به کلاس آن ابزارک بستگی دارد؛ دکمه‌ها گزینه‌ی command دارند، اما برچسب‌ها ندارند.

گزینه‌های پشتیبانی‌شده توسط یک ابزارک مشخص، در صفحه‌ی man همان ابزارک فهرست شده‌اند، یا می‌توان آن‌ها را در ران‌تایم با فراخوانی متد config() بدون آرگومان، یا با فراخوانی متد keys() روی آن ابزارک پرس‌وجو کرد. مقدار بازگشتی این فراخوانی‌ها یک دیکشنری است که کلید آن نام گزینه به‌صورت یک رشته (برای مثال، 'relief') است و مقادیر آن تاپل‌های ۵تایی هستند.

برخی گزینه‌ها، مانند bg، مترادف گزینه‌های رایج با نام‌های طولانی هستند (bg شکل کوتاهی از "background" است).

مثال:

>>> print(fred.config())
{'relief': ('relief', 'relief', 'Relief', 'raised', 'groove')}

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

مدیریت هندسه¶

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

Tk سه مدیر چیدمان ارائه می‌دهد. هر یک از این مدیران توسط همه ابزارک‌ها به ارث برده می‌شود، بنابراین هر ابزارکی می‌تواند توسط هر کدام از آن‌ها مدیریت شود (اما هشدار زیر را درباره ناسازگاری grid و pack ببینید). انتخاب به نوع چیدمانی بستگی دارد که شما می‌خواهید.

grid

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

ttk.Label(frm, text="Name:").grid(column=0, row=0, sticky="w")
ttk.Entry(frm).grid(column=1, row=0)
ttk.Button(frm, text="OK").grid(column=1, row=1, sticky="e")

pack

ابزارک‌ها را در یکی از سمت‌های ظرفشان روی هم می‌چیند -- "top" (پیش‌فرض)، "bottom"، "left" یا "right" -- و می‌تواند باعث شود که آن‌ها فضای باقی‌مانده را پر کنند یا در آن گسترش یابند. این برای چیدمان‌های ساده مناسب است، مانند یک ردیف یا ستون واحد از ابزارک‌ها یا یک ناحیه‌ی محتوا که میان یک نوار ابزار و یک نوار وضعیت محصور شده است.

toolbar.pack(side="top", fill="x")
status.pack(side="bottom", fill="x")
body.pack(side="left", expand=True, fill="both")

place

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

background.place(x=0, y=0, relwidth=1.0, relheight=1.0)
badge.place(relx=1.0, rely=0.0, anchor="ne")

چیدمان‌ها با تودرتو کردن ساخته می‌شوند: ابزارک‌ها، از جمله قاب‌ها، را با grid یا pack درون یک قاب یا پنجره‌ی سطح بالا قرار دهید. پنجره‌های سطح بالا توسط مدیر پنجره‌ی سیستم‌عامل مدیریت می‌شوند. ابزارک‌های کلاسیک و ابزارک‌های تم‌دار tkinter.ttk را می‌توان به‌جای یکدیگر مدیریت کرد.

مجموعه کامل گزینه‌های پذیرفته‌شده توسط هر مدیر، به همراه مقادیر و پیش‌فرض‌های آن‌ها، در Grid.grid_configure()، Pack.pack_configure() و Place.place_configure() مستند شده است؛ همچنین صفحه‌های راهنمای grid(3tk)، pack(3tk) و place(3tk) را ببینید.

جفت‌سازی متغیرهای ابزارک¶

برخی ابزارک‌ها می‌توانند مقدار جاری خود را مستقیماً به یک متغیر برنامه متصل کنند، تا این دو با هم همگام بمانند. گزینه‌هایی مانند variable، textvariable، value، onvalue و offvalue این اتصال را برقرار می‌کنند: هنگامی که کاربر ابزارک را تغییر می‌دهد، متغیر به‌روزرسانی می‌شود، و هنگامی که متغیر تنظیم می‌شود، ابزارک بازترسیم می‌شود تا با آن هماهنگ شود.

یک ابزارک تنها می‌تواند به یک شیء Variable پیوند داده شود، نه به یک متغیر معمولی پایتون. این محدودیتی برای tkinter نیست، بلکه پیامد چگونگی تفاوت این دو زبان است: این پیوند به این موضوع متکی است که هر بار که مقدار تغییر می‌کند، به Tcl اطلاع داده شود، و پایتون هیچ راهی برای واکنش نشان دادن هنگامی که یک متغیر ساده دوباره مقداردهی می‌شود فراهم نمی‌کند. یک Variable با نگه داشتن مقدار خود درون مفسر Tcl و در دسترس قرار دادن آن از طریق متدهای صریح get() و set() از این مسئله اجتناب می‌کند.

زیرکلاس‌های آماده انواع رایج را پوشش می‌دهند: StringVar، IntVar، DoubleVar و BooleanVar. یکی را به‌عنوان گزینه‌ی textvariable (یا variable) یک ابزارک ارسال کنید، سپس آن را با get() و set() بخوانید و به‌روزرسانی کنید؛ ابزارک آن را بدون هیچ کار بیشتری از سوی شما پیگیری می‌کند.

ارجاعی به متغیر را تا زمانی که ابزارک از آن استفاده می‌کند، نگه دارید — برای مثال با ذخیره‌کردن آن به‌عنوان یک ویژگی. یک Variable که زباله‌روبی می‌شود، متغیر Tcl زیربنایی خود را حذف می‌کند و اتصال به ابزارک را قطع می‌کند (به Variable مراجعه کنید).

برای مثال:

import tkinter as tk
from tkinter import ttk

root = tk.Tk()

# Create the application variable and give it an initial value.
contents = tk.StringVar(value="this is a variable")

# Tell the entry widget to track the variable.
entry = ttk.Entry(root, textvariable=contents)
entry.pack()

# Print the current value whenever the user presses Return.
def print_contents(event):
    print("The current entry content is:", contents.get())

entry.bind("<Return>", print_contents)

# Setting the variable from the program updates the entry through the
# same link.
def clear():
    contents.set("")

ttk.Button(root, text="Clear", command=clear).pack()

root.mainloop()

مدیر پنجره¶

مدیر پنجره بخشی از میزکار است که مسئول نوار عنوان، قاب و کنترل‌هایی که اطراف هر پنجره‌ی سطح بالا ترسیم می‌شوند، و همچنین مواردی مانند عنوان، موقعیت، اندازه و نماد آن است. Tk دسترسی به این موارد را از طریق میکس‌این Wm فراهم می‌کند، که پنجره‌ی ریشه‌ی Tk و هر Toplevel از آن ارث می‌برند. بنابراین شما متدهای مدیر پنجره را مستقیماً روی یک پنجره‌ی سطح بالا فراخوانی می‌کنید. هر متد یک نام کوتاه و یک نام معادل با پیشوند wm_ دارد، برای مثال title() و wm_title().

این متدها بر پنجره‌ی سطح بالا عمل می‌کنند، چه محتوای آن از ابزارک‌های کلاسیک ساخته شده باشد و چه از ابزارک‌های طرح‌دارِ tkinter.ttk. برای دسترسی به پنجره‌ی سطح بالایی که حاوی یک ابزارک دلخواه است، متد winfo_toplevel() آن را فراخوانی کنید.

برای مثال:

import tkinter as tk
from tkinter import ttk

root = tk.Tk()
root.title("My Application")
root.geometry("640x480")
root.minsize(320, 240)

ttk.Label(root, text="Hello").pack(padx=20, pady=20)

root.mainloop()

برای مجموعه کامل متدهای مدیر پنجره، Wm را ببینید.

انواع داده‌ی گزینه‌های Tk¶

بسیاری از گزینه‌های ابزارک مستندشده در بخش ارجاع، مقادیری از تعداد کمی از انواع متداول را می‌پذیرند که در اینجا توصیف شده‌اند. گزینه‌های استاندارد و انواع آن‌ها در صفحه‌ی راهنمای options(3tk) شرح داده شده‌اند.

لنگر

مقادیر مجاز جهات قطب‌نما هستند: "n"، "ne"، "e"، "se"، "s"، "sw"، "w"، "nw" و همچنین "center". گزینه‌ی labelanchor در کلاس‌های LabelFrame و ttk.LabelFrame مقادیر "en"، "es"، "wn" و "ws" را نیز می‌پذیرد. گزینه‌ی sticky در مدیر هندسه‌ی شبکه ترکیبی از جهت‌های قطب‌نما مانند "nsew" یا یک رشته‌ی خالی را می‌پذیرد.

بیت‌مپ

ده بیت‌مپ توکار و نام‌گذاری‌شده وجود دارد: 'error'، 'gray12'، 'gray25'، 'gray50'، 'gray75'، 'hourglass'، 'info'، 'questhead'، 'question'، 'warning'. در سیستم‌عامل macOS نیز بیت‌مپ‌های زیر در دسترس هستند: 'application'، 'accessory'، 'folder'، 'pfolder'، 'trash'، 'floppy'، 'ramdisk'، 'cdrom'، 'preferences'، 'querydoc'، 'stop'، 'note' و 'caution'. برای مشخص کردن یک پرونده‌ی بیت‌مپ X، مسیر کامل پرونده را بدهید که پیش از آن یک @ قرار گرفته باشد، مانند "@/usr/contrib/bitmap/gumby.bit".

بولی

می‌توانید اعداد صحیح ۰ یا ۱، True یا False، یا رشته‌های "0"، "1"، "yes"، "no"، "true"، "false"، "on" یا "off" را ارسال کنید. تطبیق رشته‌ها با صرف‌نظر از بزرگ و کوچک بودن حروف انجام می‌شود و یک پیشوند غیرمبهم، مانند "t"، کافی است. هر عدد صحیح غیرصفری به معنای درست است.

کال‌بک

این هر شیء فراخوانی‌پذیری است. بیشتر کال‌بک‌ها هیچ آرگومانی نمی‌پذیرند. برای نمونه:

def print_it():
    print("hi there")
fred["command"] = print_it

برخی گزینه‌ها آن را با آرگومان‌هایی فراخوانی می‌کنند، مانند گزینه‌ی command در کلاس Scale که با مقدار جدید فراخوانی می‌شود.

رنگ

رنگ‌ها را می‌توان به صورت نام‌های نمادین، مانند "red" یا "light blue"، یا به صورت رشته‌هایی که مقادیر RGB را در محدوده‌های ۴ بیتی: "#RGB"، ۸ بیتی: "#RRGGBB"، ۱۲ بیتی: "#RRRGGGBBB" یا ۱۶ بیتی: "#RRRRGGGGBBBB" نشان می‌دهند، ارائه کرد که در اینجا R ،G و B نمایانگر هر رقم هگز مجاز هستند. کتابخانه‌ی Tk مجموعه‌ی قابل‌حملی از نام‌های نمادین را فراهم می‌کند که در تمام پلتفرم‌ها در دسترس هستند؛ تطبیق آن‌ها با صرف‌نظر از بزرگی و کوچکی حروف و فاصله‌ها انجام می‌شود، بنابراین "light blue"، "Light Blue" و "lightblue" یک رنگ هستند. فهرست کامل نام‌ها، از جمله نام‌های مختص پلتفرمِ رنگ‌های سیستم فعلی (برای نمونه "systemButtonFace" در ویندوز یا "systemWindowBody" در macOS)، در صفحه‌ی راهنمای colors(3tk) آمده است. متد winfo_rgb() اجزای قرمز، سبز و آبی یک رنگ را برمی‌گرداند.

compound

تعیین می‌کند که چگونه یک تصویر و یک متن نمایش‌داده‌شده در یک ابزارک با یکدیگر ترکیب شوند. مقادیر مجاز عبارتند از "none" (نمایش تصویر در صورت وجود، در غیر این صورت متن)، "text"، "image"، "center" (نمایش متن در مرکز تصویر) و "top"، "bottom"، "left"، "right" (نمایش تصویر در بالا، پایین، سمت چپ یا سمت راست متن). ابزارک‌های پوسته‌ای تمام این مقادیر را می‌پذیرند، ابزارک‌های کلاسیک همه به جز "text" و "image" را می‌پذیرند.

مکان‌نما

نام مکان‌نما ماوسی که هنگام قرار داشتن اشاره‌گر روی ابزارک نمایش داده می‌شود. Tk مجموعه‌ای قابل‌حمل از نام‌های مکان‌نما را فراهم می‌کند که در همه‌ی سکوها در دسترس است (برای مثال "arrow"، "watch"، "cross" یا "hand2")؛ همچنین می‌توان از نام‌های استاندارد مکان‌نما X در cursorfont.h بدون پیشوند XC_ استفاده کرد (بنابراین XC_hand2 به "hand2" تبدیل می‌شود). فهرست کامل نام‌ها، از جمله نام‌های مختص سکو، در صفحه‌ی راهنمای cursors(3tk) آمده است. شما همچنین می‌توانید یک پرونده بیت‌مپ و نقاب دلخواه خودتان را مشخص کنید. در ویندوز می‌توان مستقیماً از یک پرونده مکان‌نما (.cur یا .ani) استفاده کرد، به این صورت که مسیر آن با پیشوند @ داده شود، مانند "@C:/cursors/bart.ani".

فاصله

فاصله‌های صفحه را می‌توان به‌صورت پیکسل یا فاصله‌های مطلق مشخص کرد. پیکسل‌ها به‌صورت عدد و فاصله‌های مطلق به‌صورت رشته داده می‌شوند، به‌گونه‌ای که نویسه پایانی نشان‌دهنده یکا است: c برای سانتی‌متر، i برای اینچ، m برای میلی‌متر، p برای نقطه‌های چاپگر. برای مثال، ۳٫۵ اینچ به‌صورت "3.5i" بیان می‌شود.

قلم

کتابخانه‌ی Tk از توصیف قلمی مانند {courier 10 bold} استفاده می‌کند؛ در ماژول tkinter این کار به‌طور طبیعی‌تر به صورت یک تاپل از (family, size, *styles) (یا به صورت رشته‌ی معادل "Courier 10 bold") ارسال می‌شود. اندازه‌های قلم با اعداد مثبت بر اساس نقطه (point) اندازه‌گیری می‌شوند؛ اندازه‌ها با اعداد منفی بر اساس پیکسل اندازه‌گیری می‌شوند. نام یک قلم نام‌گذاری‌شده، مانند "TkDefaultFont"، یک نمونه از tkinter.font.Font، یا در X11، نام یک قلم XLFD نیز می‌تواند استفاده شود.

تراز کردن

مقادیر مجاز، رشته‌های زیر هستند: "left"، "center" و "right".

جهت

مقادیر مجاز عبارتند از "horizontal" و "vertical".

پُرکننده

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

ناحیه

برای گزینه‌ی scrollregion در Canvas استفاده می‌شود. این یک رشته با چهار عنصر جداشده با فاصله است که هر کدام یک فاصله‌ی مجاز (مشاهده در بالا) یا دنباله‌ای از چهار عنصر این‌چینی است. برای مثال: "2 3 4 5"، (2, 3, 4, 5)، "3i 2i 4.5i 2i" و "3c 2c 4c 10.43c" همگی ناحیه‌های مجازی هستند.

برجستگی

مشخص می‌کند که سبک حاشیه یک ابزارک چه خواهد بود. مقادیر مجاز عبارت‌اند از: "raised"، "sunken"، "flat"، "groove"، "ridge" و "solid".

scrollcommand

این تقریباً همیشه متد set()یک ابزارک نوار پیمایش است، اما می‌تواند هر متدی از یک ابزارک باشد که یک آرگومان می‌پذیرد.

وضعیت

مقادیر مجاز عبارتند از "normal"، "disabled" و بسته به ابزارک، همچنین "active"، "hidden" (برای آیتم‌های Canvas) یا "readonly" (برای Entry، Spinbox و ابزارک‌های پوسته‌بندی‌شده). ابزارک‌های پوسته‌بندی‌شده علاوه بر این دارای مجموعه‌ی عمومی‌تری از وضعیت‌ها هستند که با ttk.Widget.state دستکاری می‌شوند.

دربرگرفتن

برای ابزارک Text و برچسب‌های آن باید یکی از مقادیر "none"، "char" یا "word" باشد؛ برای یک برچسب، رشته‌ی خالی به معنای استفاده از مقدار ابزارک است.

اتصال‌ها و رویدادها¶

متد bind از دستور ابزارک (widget command) به شما امکان می‌دهد رویدادهای خاصی را زیر نظر بگیرید و کاری کنید که یک تابع کال‌بک هنگام وقوع آن نوع رویداد فعال شود. قالب متد bind به این صورت است:

def bind(self, sequence, func, add=''):

که در آن:

دنباله

رشته‌ای است که نوع رویداد هدف را نشان می‌دهد. رویدادهای فیزیکی از قالب <modifier-modifier-type-detail> استفاده می‌کنند (برای مثال "<Enter>" یا "<Control-Button-1>")؛ رویدادهای مجازی تعریف‌شده توسط برنامه از علامت‌های زاویه‌ای دوتایی استفاده می‌کنند، مانند "<<Paste>>". (برای جزئیات، صفحه راهنمای bind(3tk) را ببینید.)

تابع

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

افزودن

اختیاری است و می‌تواند '' یا '+' باشد. ارسال یک رشته خالی نشان می‌دهد که این اتصال جایگزین تمام اتصال‌های دیگری می‌شود که این رویداد با آن‌ها مرتبط است. ارسال '+' به این معناست که این تابع به فهرست توابعی اضافه می‌شود که به این نوع رویداد متصل هستند.

برای مثال:

def turn_red(self, event):
    event.widget["activeforeground"] = "red"

self.button.bind("<Enter>", self.turn_red)

توجه کنید که چگونه در کال‌بک turn_red() به فیلد ابزارک رویداد دسترسی پیدا می‌شود. این فیلد حاوی ابزارکی است که رویداد X را گرفته است. جدول زیر سایر فیلدهای رویداد را که می‌توانید به آن‌ها دسترسی داشته باشید، و نحوه‌ی نمایش آن‌ها در Tk فهرست می‌کند، که می‌تواند هنگام مراجعه به صفحات راهنمای Tk مفید باشد.

پارامتر add در بالا فقط بر مقیدسازی‌هایی که خودتان ایجاد می‌کنید تأثیر می‌گذارد. هر ابزارک همچنین مقیدسازی‌های کلاس را به ارث می‌برد که رفتار استاندارد آن را پیاده‌سازی می‌کنند — برای مثال، یک ابزارک Text، Control-t را به جابه‌جایی دو نویسه متصل می‌کند. این اتصال‌ها در بخش مقیدسازی‌های صفحه راهنمای Tk مربوط به ابزارک (مانند text(3tk) یا entry(3tk)) توضیح داده شده‌اند.

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

پارامتر اندیس¶

تعدادی از ابزارک‌ها نیازمند ارسال پارامترهای «اندیس» هستند. این پارامترها برای اشاره به مکانی مشخص در یک ابزارک Text، یا نویسه‌هایی خاص در یک ابزارک Entry، یا آیتم‌های منوی خاصی در یک ابزارک Menu استفاده می‌شوند.

اندیس‌های ابزارک Entry (index، view index و غیره)

ابزارک‌های Entry دارای متدها و گزینه‌هایی هستند که به موقعیت‌های نویسه در متن نمایش‌داده‌شده اشاره می‌کنند. هر زمان که به یک اندیس نیاز باشد، می‌توانید موارد زیر را وارد کنید:

• عدد صحیحی که به موقعیت عددی یک نویسه اشاره دارد و از ابتدای متن، با شروع از ۰ شمرده می‌شود؛

• رشته‌ی "anchor"، که به نقطه‌ی لنگر انتخاب اشاره دارد؛ این نقطه با متدهای انتخاب ابزارک تنظیم می‌شود؛

• رشته "end"، که به موقعیت درست پس از آخرین نویسه اشاره دارد؛

• رشته‌ی "insert"، که به نویسه‌ی درست پس از مکان‌نمای درج اشاره دارد؛

• رشته‌های "sel.first" و "sel.last"، که به اولین نویسه‌ی انتخاب و موقعیت درست پس از آخرین نویسه اشاره دارند (اگر انتخابی وجود نداشته باشد، استفاده از این‌ها خطا است)؛

• رشته‌ای متشکل از @ که پس از آن یک عدد صحیح آمده است، مانند "@6"، که در آن عدد صحیح به‌عنوان مختصات پیکسلی x در دستگاه مختصات ورودی تفسیر می‌شود و نویسه‌ای را انتخاب می‌کند که آن نقطه را در بر می‌گیرد.

اندیس‌های ابزارک Text

نمادگذاری اندیس برای ابزارک‌های Text بسیار غنی است و بهترین توصیف آن در صفحات راهنمای Tk آمده است.

اندیس‌های منو (menu.invoke()، menu.entryconfig() و غیره)

برخی گزینه‌ها و متدهای مربوط به منوها، آیتم‌های خاصی از منو را دستکاری می‌کنند. هر زمان که برای یک گزینه یا پارامتر به اندیس منو نیاز باشد، می‌توانید موارد زیر را وارد کنید:

• عدد صحیحی که به موقعیت عددی ورودی در ابزارک اشاره دارد، از بالا شمرده می‌شود و از ۰ آغاز می‌شود؛

• رشته "active"، که به موقعیتی از منو اشاره می‌کند که در حال حاضر زیر مکان‌نما قرار دارد؛

• رشته‌ی "last" که به آخرین آیتم منو اشاره می‌کند؛

• رشته‌ای متشکل از @ و به‌دنبال آن یک عدد صحیح، مانند "@6"، که در آن عدد صحیح به‌عنوان مختصات پیکسلی y در دستگاه مختصات منو تفسیر می‌شود؛

• رشته "none"، که نشان‌دهنده‌ی نبود هیچ ورودی منو است، بیشتر همراه با menu.activate() برای غیرفعال کردن همه‌ی ورودی‌ها استفاده می‌شود، و در نهایت،

• یک رشته‌ی لفظی که با پیمایش منو از بالا به پایین، به‌عنوان الگو با برچسب آیتم منو تطبیق داده می‌شود. توجه داشته باشید که این نوع اندیس پس از همه‌ی انواع دیگر در نظر گرفته می‌شود، به این معنا که تطابق‌ها برای آیتم‌های منو با برچسب‌های last، active یا none ممکن است در عوض به‌عنوان مقادیر لفظی بالا تفسیر شوند.

تصاویر¶

تصاویری در قالب‌های مختلف را می‌توان از طریق زیرکلاس متناظرِ tkinter.Image ایجاد کرد:

• BitmapImage برای تصاویر در قالب XBM.

• PhotoImage برای تصاویر در قالب‌های PGM، PPM، GIF و PNG. قالب آخر از Tk 8.6 پشتیبانی می‌شود.

هر نوع تصویری از طریق گزینه file یا data ایجاد می‌شود (گزینه‌های دیگری نیز در دسترس است).

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

کلاس‌های پایه و میکس‌این¶

class tkinter.Misc¶

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

cget(key)¶

مقدار فعلی گزینه‌ی پیکربندی با نام key برای این ابزارک را به‌صورت یک رشته برمی‌گرداند. عبارت widget[key] معادل است و می‌توانید به‌جای آن از این عبارت استفاده کنید.

configure(cnf=None, **kw)¶

گزینه‌های پیکربندی ابزارک را پرس‌وجو یا اصلاح می‌کند. بدون آرگومان، یک دیکشنری برمی‌گرداند که هر نام گزینه‌ی موجود را به یک تاپل توصیف‌کننده‌ی آن (نام آن، نام منبع X، کلاس منبع X، مقدار پیش‌فرض و مقدار فعلی) نگاشت می‌کند. اگر یک نام گزینه به‌صورت یک رشته داده شود، فقط تاپل همان گزینه را برمی‌گرداند. اگر یک یا چند آرگومان کلیدواژه‌ای داده شود، یا یک دیکشنری به‌عنوان cnf ارسال شود، هر گزینه‌ی نام‌برده را به مقدار متناظر تنظیم می‌کند؛ عبارت widget[key] = value یک گزینه را به همین روش تنظیم می‌کند.

config() نام مستعار configure() است.

keys()¶

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

getboolean(s)¶

رشته‌ی s را به عنوان یک مقدار بولی Tcl تفسیر کرده و bool متناظر را برمی‌گرداند. Tcl مقادیری مانند '1'، '0'، 'yes'، 'no'، 'true'، 'false'، 'on' و 'off' را می‌پذیرد. اگر s یک مقدار بولی معتبر نباشد، استثنای ValueError را بالا بیاورید.

getdouble(s)¶

رشته‌ی s را به‌عنوان یک عدد ممیز شناور Tcl تفسیر می‌کند و آن را به‌صورت یک float برمی‌گرداند. اگر s یک عدد معتبر نباشد، ValueError پرتاب می‌شود.

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

getint(s)¶

رشته s را به‌عنوان یک عدد صحیح Tcl تفسیر می‌کند و آن را به‌صورت یک int برمی‌گرداند. اگر s یک عدد صحیح معتبر نباشد، ValueError پرتاب می‌شود.

getvar(name)¶

مقدار متغیر سراسری Tcl به نام name را برمی‌گرداند.

setvar(name, value)¶

متغیر سراسری Tcl به نام name را برابر با value قرار دهید.

متدهای getvar() و setvar() دسترسی مستقیم به متغیرهای Tcl را فراهم می‌کنند. در بیشتر کدها، به‌جای آن از زیرکلاسی از Variable مانند StringVar یا IntVar استفاده خواهید کرد، که یک متغیر Tcl را دربر می‌گیرد و مقدار آن را به یک نوع پایتون و بالعکس تبدیل می‌کند.

register(func, subst=None, needcleanup=1)¶

شیء فراخوانی‌پذیر پایتون func را به‌عنوان یک فرمان Tcl ثبت می‌کند و نام فرمان جدید را به‌صورت یک رشته برمی‌گرداند. هر زمان که Tcl آن فرمان را فراخوانی کند، func فراخوانی می‌شود؛ اگر subst داده شده باشد، ابتدا روی آرگومان‌های فرمان اعمال می‌شود. این سازوکاری است که به‌صورت داخلی برای تبدیل کال‌بک‌های پایتون به نام‌های فرمانی که به گزینه‌های Tk مانند command داده می‌شوند، استفاده می‌شود. مگر اینکه needcleanup برابر false باشد، فرمان به‌طور خودکار هنگام نابود شدن ابزارک حذف می‌شود.

تغییر یافته در نسخه‌ی 3.13: آرگومان‌های ارسال‌شده به func دیگر به رشته تبدیل نمی‌شوند.

deletecommand(name)¶

فرمان Tcl با نام name را حذف می‌کند، مانند فرمانی که پیش‌تر توسط register() برگردانده شده است.

nametowidget(name)¶

نمونه‌ی ابزارک متناظر با نام مسیر Tk به‌نام name را برمی‌گرداند.

send(interp, cmd, *args)¶

فرمان Tcl cmd را، به همراه args داده‌شده، به مفسر Tcl ثبت‌شده با نام interp ارسال کنید و نتیجه‌ی آن را برگردانید. این قابلیت در همه‌ی سکوها در دسترس نیست.

destroy()¶

این ابزارک و همه‌ی ابزارک‌های زیرمجموعه‌ی آن را نابود کنید و دستورات Tcl مرتبط با آن‌ها را حذف کنید.

tkraise(aboveThis=None)¶

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

lift() نام مستعاری از tkraise() است.

lower(belowThis=None)¶

این ابزارک را در ترتیب پشته‌ای (stacking order) پایین ببرید تا زیر هم‌سطح‌های خود ترسیم شود. اگر belowThis داده شده باشد، در عوض ابزارک دقیقاً زیر آن در ترتیب پشته‌ای جابه‌جا می‌شود.

tkraise()/lift() و lower() توسط ابزارک Canvas بازنویسی شده‌اند؛ در این ابزارک، آن‌ها به‌جای آن، آیتم‌های Canvas را دوباره پشته‌بندی می‌کنند.

image_names()¶

نام همه‌ی تصاویری را که در حال حاضر در مفسر Tcl وجود دارند، برمی‌گرداند.

این مورد توسط ابزارک Text بازنویسی می‌شود، که در آن image_names() در عوض نام تصاویر تعبیه‌شده‌ی آن را برمی‌گرداند.

image_types()¶

انواع تصویر در دسترس را برمی‌گرداند، مانند 'photo' و 'bitmap'.

grid_anchor(anchor=None)¶

لنگر را تنظیم کنید؛ این لنگر تعیین می‌کند که وقتی ظرف بزرگ‌تر از شبکه است و هیچ ردیف یا ستونی وزن غیرصفر ندارد، شبکه در کجای این ظرف قرار گیرد. anchor یکی از رشته‌های لنگر معمول است، مانند 'nw' (پیش‌فرض) یا 'center'. اگر این متد بدون آرگومان فراخوانی شود، هیچ تأثیری ندارد.

anchor() نام مستعار grid_anchor() است.

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

grid_bbox(column=None, row=None, col2=None, row2=None)¶

جعبه‌ی محدودکننده یک ناحیه از شبکه‌ی چیده‌شده در این ظرف را بر حسب پیکسل، به‌صورت یک ۴تایی (xoffset, yoffset, width, height) برمی‌گرداند. بدون آرگومان، جعبه‌ی محدودکننده کل شبکه برگردانده می‌شود. اگر column و row داده شده باشند، جعبه از سلول در ردیف ۰ و ستون ۰ تا آن سلول امتداد دارد؛ اگر col2 و row2 نیز داده شده باشند، از سلول (column، row) تا سلول (col2، row2) امتداد دارد.

bbox() نام مستعار grid_bbox() است، به‌جز در Canvas، Listbox، Spinbox، Text، ttk.Entry و ttk.Treeview، که متد bbox() خود را فراهم می‌کنند.

grid_columnconfigure(index, cnf={}, **kw)¶

ویژگی‌های ستون (یا ستون‌های) index از شبکه‌ی مدیریت‌شده توسط این ظرف را بپرسید یا تنظیم کنید. index می‌تواند یک شماره ستون باشد؛ هنگام تنظیم گزینه‌ها، همچنین می‌تواند فهرستی از شماره‌های ستون، رشته‌ی 'all' برای تأثیر بر همه‌ی ستون‌ها، یا یک ابزارک فرزند باشد که ستون‌های اشغال‌شده‌ی آن تحت تأثیر قرار می‌گیرند. گزینه‌های پشتیبانی‌شده عبارتند از:

minsize

حداقل اندازه‌ی ستون، بر حسب پیکسل.

weight

یک عدد صحیح که تعیین می‌کند چه مقدار از فضای اضافی به ستون اختصاص داده شود. وزن 0 ستون را در اندازه درخواستی خود نگه می‌دارد، و ستونی با وزن ۲ دو برابر سریع‌تر از ستونی با وزن ۱ رشد می‌کند.

uniform

نام یک گروه یکنواخت (uniform group). ستون‌هایی که یک نام گروه غیرخالی مشترک دارند، در اندازه‌هایی نگه داشته می‌شوند که دقیقاً متناسب با وزن‌هایشان است.

pad

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

با یک نام گزینه، مقدار آن گزینه را برمی‌گرداند؛ بدون هیچ گزینه‌ای، یک دیکشنری از همه‌ی آن‌ها را برمی‌گرداند.

columnconfigure() نام مستعاری از grid_columnconfigure() است.

grid_rowconfigure(index, cnf={}, **kw)¶

ویژگی‌های ردیف (یا ردیف‌های) index از شبکه مدیریت‌شده توسط این ظرف را پرس‌وجو یا تنظیم کنید. تفسیر index همانند grid_columnconfigure() است و گزینه‌های پشتیبانی‌شده (minsize، weight، uniform و pad) یکسان هستند، با این تفاوت که به‌جای ستون، بر ردیف اعمال می‌شوند.

rowconfigure() نام مستعاری از grid_rowconfigure() است.

grid_location(x, y)¶

(column, row) مربوط به سلول شبکه‌ای که پیکسلی در موقعیت (x, y) را در بر دارد، برمی‌گرداند؛ این موقعیت بر حسب پیکسل نسبت به این ظرف داده شده است. برای موقعیت‌های بالاتر از شبکه یا سمت چپ آن، برای مختصات متناظر -1 برگردانده می‌شود.

grid_propagate()¶

grid_propagate(flag)

انتشار هندسه (geometry propagation) را برای این ظرف، وقتی فرزندان خود را با مدیر هندسه‌ی grid مدیریت می‌کند، فعال یا غیرفعال کنید. وقتی flag درست باشد، ظرف اندازه‌ی خود را تغییر می‌دهد تا با اندازه‌های درخواست‌شده‌ی فرزندان خود متناسب شود؛ وقتی نادرست باشد، اندازه‌ی آن تحت کنترل شما باقی می‌ماند. اگر بدون آرگومان فراخوانی شود، تنظیم فعلی را به‌صورت یک مقدار بولی برمی‌گرداند.

grid_size()¶

اندازه‌ی شبکه‌ی مدیریت‌شده توسط این ظرف را به‌صورت یک تاپل (columns, rows) برمی‌گرداند.

size() نام مستعاری از grid_size() است، به‌جز در ابزارک Listbox، که متد size() خود را ارائه می‌دهد.

grid_slaves(row=None, column=None)¶

فهرستی از ابزارک‌های فرزند مدیریت‌شده در شبکه‌ی این ظرف را برمی‌گرداند، به‌طوری که آخرین ابزارک مدیریت‌شده در ابتدا قرار دارد. اگر row یا column داده شود، فقط ابزارک‌های فرزند موجود در آن ردیف یا ستون برگردانده می‌شوند.

grid_content(row=None, column=None)¶

مشابه grid_slaves(): ابزارک‌های فرزندی را که در شبکه (grid) این ظرف مدیریت می‌شوند برمی‌گرداند، که به صورت اختیاری به یک row یا column مشخص محدود می‌شود.

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

pack_propagate()¶

pack_propagate(flag)

فعال یا غیرفعال کردن انتشار هندسه برای این ظرف (container) هنگامی که فرزندان خود را با مدیر هندسه‌ی pack مدیریت می‌کند. وقتی flag درست باشد، ظرف اندازه‌ی خود را متناسب با اندازه‌های درخواستی فرزندان تغییر می‌دهد؛ وقتی نادرست باشد، اندازه‌ی آن تحت کنترل شما باقی می‌ماند. در صورت فراخوانی بدون آرگومان، تنظیم فعلی را به‌صورت یک مقدار بولی برمی‌گرداند.

propagate() نام مستعاری از pack_propagate() است.

pack_slaves()¶

فهرستی از ابزارک‌های فرزند مدیریت‌شده توسط این ظرف با مدیر چیدمان pack را به ترتیب چیدمان pack برمی‌گرداند.

slaves() نام مستعار pack_slaves() است.

pack_content()¶

مشابه pack_slaves(): ابزارک‌های فرزندی را که توسط این ظرف با مدیر هندسه‌ی بسته‌بندی (pack) مدیریت می‌شوند، به ترتیب بسته‌بندی، برمی‌گرداند.

content() نام مستعاری برای pack_content() است.

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

place_slaves()¶

فهرستی از ابزارک‌های فرزند این ظرف را که با مدیر چیدمان place مدیریت می‌شوند، برمی‌گرداند.

place_content()¶

مشابه place_slaves(): ابزارک‌های فرزندی را که توسط این ظرف با مدیر هندسه‌ی مکان (place) مدیریت می‌شوند برمی‌گرداند.

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

متد‌هایی که دارای پیشوندهای bind و unbind هستند، الگوهای رویداد را به فراخوانی‌های بازگشتی (callback) متصل کرده و آن اتصالات را حذف می‌کنند.

bind(sequence=None, func=None, add=None)¶

الگوی رویداد sequence را در این ابزارک به شیء فراخوانی‌پذیر func متصل کنید.

sequence یک الگوی رویداد است، مانند '<Button-1>' (یک کلیک ماوس) یا '<KeyPress-a>'، و به‌صورت اختیاری می‌تواند الحاقی از چندین الگوی مشابه باشد که باید با فاصله‌ای کوتاه پس از یکدیگر رخ دهند. هنگامی که رویداد رخ می‌دهد، func با یک نمونه از Event که رویداد را توصیف می‌کند، به‌عنوان تنها آرگومان فراخوانی می‌شود؛ اگر func رشته‌ی 'break' را برگرداند، هیچ پیوند دیگری برای رویداد فراخوانی نمی‌شود.

اگر add درست باشد، func به توابعی که از قبل به sequence متصل شده‌اند اضافه می‌شود؛ در غیر این صورت، جایگزین آن‌ها می‌شود. این اتصال تنها برای این ابزارک اعمال می‌شود.

bind() یک شناسه‌ی رشته‌ای (یک funcid) برمی‌گرداند که بعداً می‌توان آن را به unbind() فرستاد تا اتصال را بدون نشت دستور Tcl مرتبط حذف کرد.

اگر func حذف شود، مقیدسازی‌های کنونی مرتبط با sequence را برمی‌گرداند؛ اگر sequence نیز حذف شود، فهرستی از همه دنباله‌هایی را که برای آن‌ها مقیدسازی‌هایی روی این ابزارک وجود دارد برمی‌گرداند.

bind_class(className, sequence=None, func=None, add=None)¶

مانند bind()، اما func را به برچسب مقیدسازی className متصل می‌کند، نه به یک ابزارک واحد، تا مقیدسازی به هر ابزارکی که آن برچسب را دارد اعمال شود. className معمولاً نام یک کلاس ابزارک است، مانند 'Button'، که در این صورت مقیدسازی بر همه ابزارک‌های آن کلاس اثر می‌گذارد. مجموعه برچسب‌های مقیدسازی برای یک ابزارک را می‌توان با bindtags() بررسی و تغییر داد.

آرگومان‌های باقی‌مانده و مقدار بازگشتی همانند bind() هستند.

bind_all(sequence=None, func=None, add=None)¶

مانند bind()، اما func را به برچسب مقیدسازی ویژه‌ی 'all' متصل می‌کند، تا این مقیدسازی به تمام ابزارک‌های برنامه اعمال شود.

آرگومان‌های باقی‌مانده و مقدار بازگشتی همانند bind() هستند.

unbind(sequence, funcid=None)¶

مقیدسازی‌های مربوط به الگوی رویداد sequence را روی این ابزارک حذف می‌کند.

اگر funcid داده شود، فقط تابع شناسایی‌شده توسط آن (مقداری که از فراخوانی قبلی bind() بازگشته است) حذف می‌شود و دستور Tcl مرتبط با آن حذف می‌گردد. در غیر این صورت، تمام پیوندهای sequence از بین می‌روند و آن را بی‌پیوند باقی می‌گذارند.

تغییر یافته در نسخه‌ی 3.13: اگر funcid داده شود، فقط همان کال‌بک از حالت مقید خارج می‌شود؛ سایر کال‌بک‌های مقید به sequence حفظ می‌شوند.

unbind_class(className, sequence)¶

تمام اتصال‌های الگوی رویداد sequence را از برچسب اتصال className حذف می‌کند. bind_class() را ببینید.

unbind_all(sequence)¶

تمام اتصال‌های الگوی رویداد sequence را از برچسب اتصال ویژه 'all' حذف کنید. bind_all() را ببینید.

bindtags(tagList=None)¶

اگر tagList حذف شود، یک تاپل از برچسب‌های اتصال مرتبط با این ابزارک برمی‌گرداند. هنگامی که یک رویداد در یک ابزارک رخ می‌دهد، آن رویداد به‌ترتیب به هر یک از برچسب‌های اتصال ابزارک اعمال می‌شود، و برای هر برچسب، خاص‌ترین اتصال منطبق اجرا می‌شود. به‌طور پیش‌فرض، یک ابزارک دارای چهار برچسب اتصال است: نام مسیر خود، کلاس ابزارک آن، نام مسیر نزدیک‌ترین نیاک سطح بالای آن، و 'all'، به همین ترتیب.

اگر tagList داده شود، باید دنباله‌ای از رشته‌ها باشد؛ برچسب‌های اتصال ابزارک به عناصر آن تنظیم می‌شوند که ترتیب ارزیابی اتصال‌ها را تعیین می‌کند.

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

event_add(virtual, *sequences)¶

رویداد مجازی virtual را، که نام آن به شکل '<<Paste>>' است، با هر یک از الگوهای رویداد فیزیکی داده‌شده توسط sequences مرتبط کنید، تا هر زمان که هر یک از آن‌ها رخ دهد، رویداد مجازی فعال شود. اگر virtual از قبل تعریف شده باشد، دنباله‌های جدید به دنباله‌های موجود آن افزوده می‌شوند.

event_delete(virtual, *sequences)¶

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

event_generate(sequence, **kw)¶

دنباله‌ی رویداد sequence را روی این ابزارک تولید کنید و ترتیبی دهید که درست همان‌طور پردازش شود که گویی از سامانه‌ی پنجره‌ای آمده است. sequence باید یک الگوی رویداد واحد باشد، مانند '<Button-1>' یا '<<Paste>>'، نه الحاق چندین الگو. آرگومان‌های کلیدواژه‌ای فیلدهای اضافی رویداد را مشخص می‌کنند، برای مثال x و y برای موقعیت اشاره‌گر، یا when برای کنترل زمان پردازش رویداد؛ برای فهرست کامل به صفحه‌ی راهنمای event در Tk مراجعه کنید.

event_info(virtual=None)¶

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

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

after(ms, func=None, *args, **kw)¶

شیء فراخوانی‌پذیر func را زمان‌بندی می‌کند تا پس از ms میلی‌ثانیه فراخوانی شود، به‌طوری که args و kw به‌عنوان آرگومان‌های جایگاهی و کلیدواژه‌ای به آن ارسال شوند. شناسه‌ای برمی‌گرداند که می‌توان آن را به after_cancel() ارسال کرد تا فراخوانی لغو شود.

اگر func حذف شود، در عوض به مدت ms میلی‌ثانیه متوقف میشود در آن مدت هیچ رویدادی را پردازش نمی‌کند و None را برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.10: func اکنون می‌تواند هر شیء فراخوانی‌پذیر باشد، نه فقط یک تابع.

تغییر یافته در نسخه‌ی 3.14: آرگومان‌های کلیدواژه‌ای اکنون به func ارسال می‌شوند.

after_cancel(id)¶

کال‌بکی را که قبلاً با after() یا after_idle() زمان‌بندی شده است، لغو می‌کند. id باید شناسه‌ای باشد که توسط یکی از آن متدها برگردانده شده است؛ ارسال مقداری که چنین شناسه‌ای نباشد، باعث پرتاب ValueError می‌شود. اگر کال‌بک قبلاً اجرا یا لغو شده باشد، این کار اثری ندارد.

تغییر یافته در نسخه‌ی 3.7: ارسال None (یا هر مقدار کاذب) به‌عنوان id اکنون باعث پرتاب ValueError می‌شود.

after_idle(func, *args, **kw)¶

زمان‌بندی می‌کند که شیء فراخوانی‌پذیر func، همراه با args و kw که به آن ارسال می‌شوند، در دفعه‌ی بعدی که حلقه‌ی اصلی Tk بی‌کار شود فراخوانی شود، یعنی زمانی که رویداد دیگری برای پردازش نداشته باشد. یک شناسه برمی‌گرداند که می‌توان آن را به after_cancel() ارسال کرد تا فراخوانی لغو شود.

تغییر یافته در نسخه‌ی 3.14: آرگومان‌های کلیدواژه‌ای اکنون به func ارسال می‌شوند.

after_info(id=None)¶

اگر id ذکر نشود، یک تاپل از شناسه‌های تمام کال‌بک‌هایی را که در حال حاضر با after() و after_idle() برای این مفسر زمان‌بندی شده‌اند، برمی‌گرداند.

اگر id داده شده باشد، باید کال‌بکی را شناسایی کند که هنوز اجرا یا لغو نشده باشد، و مقدار بازگشتی یک تاپل (script, type) است، که در آن script به تابعی اشاره می‌کند که قرار است فراخوانی شود و type یا 'idle' است یا 'timer'. اگر id وجود نداشته باشد، TclError پرتاب می‌شود.

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

mainloop(n=0)¶

وارد حلقه‌ی رویداد Tk شوید، که رویدادها را پردازش می‌کند تا همه‌ی پنجره‌ها از بین بروند. این معمولاً یک بار، روی پنجره‌ی ریشه، برای اجرای برنامه فراخوانی می‌شود.

quit()¶

از مفسر Tcl خارج شوید، که باعث می‌شود mainloop() بازگشت کند.

update()¶

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

update_idletasks()¶

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

wait_variable(name)¶

منتظر بمانید تا متغیر Tcl با نام name تغییر کند؛ در این میان به پردازش رویدادها ادامه دهید تا برنامه پاسخگو بماند. name معمولاً نمونه‌ای از Variable است، مانند IntVar یا StringVar.

waitvar() نام مستعاری از wait_variable() است.

wait_window(window=None)¶

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

wait_visibility(window=None)¶

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

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

focus()¶

تمرکز ورودی صفحه‌کلید برای نمایشگر این ابزارک را به این ابزارک هدایت می‌کند. اگر برنامه در حال حاضر تمرکز ورودی را در نمایشگر این ابزارک نداشته باشد، این ابزارک به‌عنوان پنجره دارای تمرکز برای سطح بالای خود به خاطر سپرده می‌شود، و دفعه بعدی که مدیر پنجره تمرکز را به سطح بالا بدهد، تمرکز به آن هدایت مجدد می‌شود. focus() نام مستعاری از focus_set() است، به‌جز برای ابزارک‌های Canvas و ttk.Treeview، که متد focus() خودشان را ارائه می‌دهند.

focus_force()¶

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

focus_get()¶

ابزارکی را برمی‌گرداند که در حال حاضر تمرکز صفحه‌کلید را در برنامه دارد، یا اگر هیچ ابزارکی در برنامه تمرکز ندارد، None برمی‌گرداند. برای کارکرد صحیح با چندین نمایشگر، از focus_displayof() استفاده کنید.

focus_displayof()¶

ابزارکی را که در حال حاضر فوکوس صفحه‌کلید را روی نمایشگری که این ابزارک در آن قرار دارد دارد، برمی‌گرداند، یا اگر هیچ ابزارکی در برنامه فوکوس را روی آن نمایشگر نداشته باشد، None برمی‌گرداند.

focus_lastfor()¶

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

tk_focusFollowsMouse()¶

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

tk_focusNext()¶

ابزارک بعدی پس از این ابزارک را در ترتیب پیمایش با صفحه‌کلید برمی‌گرداند، یا اگر وجود نداشته باشد، None را برمی‌گرداند. ترتیب پیمایش ابتدا به فرزند بعدی می‌رود، سپس به‌صورت بازگشتی به فرزندان آن فرزند، و سپس به هم‌نیای بعدی که در ترتیب پشته‌بندی بالاتر است می‌رود. اگر گزینه‌ی takefocus یک ابزارک روی 0 تنظیم شده باشد، از آن ابزارک صرف‌نظر می‌شود. این متد در اتصال‌های پیش‌فرض برای کلید Tab استفاده می‌شود.

tk_focusPrev()¶

ابزارک قبلی را که پیش از این ابزارک در ترتیب پیمایش صفحه‌کلید قرار دارد، برمی‌گرداند، یا اگر موردی وجود نداشته باشد None را برمی‌گرداند. برای چگونگی تعریف این ترتیب، tk_focusNext() را ببینید. این متد در اتصال‌های پیش‌فرض برای کلید Shift-Tab استفاده می‌شود.

متدهای دارای پیشوند grab_، گرفتن ورودی (input grab) را که تمام رویدادهای ورودی را به یک ابزارک هدایت می‌کند، تنظیم و پرس‌وجو می‌کنند.

grab_set()¶

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

grab_set_global()¶

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

grab_release()¶

اگر گرفتن (grab) روی این ابزارک وجود دارد، آن را آزاد کنید؛ در غیر این صورت هیچ کاری انجام ندهید.

grab_current()¶

ابزارکی را که هم‌اکنون گرفتن (grab) را در این برنامه برای نمایشگر این ابزارک در اختیار دارد، برگردانید، یا اگر چنین ابزارکی وجود ندارد، None را برگردانید.

grab_status()¶

اگر در حال حاضر هیچ تصرفی (grab) روی این ابزارک تنظیم نشده باشد، None را برمی‌گرداند؛ در صورت تنظیم تصرف محلی، "local" یا در صورت تنظیم تصرف سراسری، "global" را برمی‌گرداند.

متدهایی با پیشوند selection_، انتخاب X را بازیابی و مدیریت می‌کنند.

selection_clear(**kw)¶

گزینش X را پاک می‌کند، به‌طوری که دیگر هیچ پنجره‌ای مالک آن نباشد. گزینشی که باید پاک شود با آرگومان کلیدواژه‌ای selection مشخص می‌شود؛ این آرگومان یک نام اتم مانند 'PRIMARY' یا 'CLIPBOARD' است و پیش‌فرض آن PRIMARY است. آرگومان کلیدواژه‌ای displayof نام ابزارکی را مشخص می‌کند که نمایشگر مورد عمل را تعیین می‌کند، و پیش‌فرض آن همین ابزارک است.

این رفتار در ابزارک‌های Entry، Listbox و Spinbox لغو می‌شود؛ در این ابزارک‌ها، selection_clear() به‌جای آن، انتخاب خود ابزارک را پاک می‌کند.

selection_get(**kw)¶

محتوای گزینش جاری X را برمی‌گرداند. آرگومان کلیدواژه‌ای selection نام گزینش را مشخص می‌کند و مقدار پیش‌فرض آن PRIMARY است. آرگومان کلیدواژه‌ای type قالبی را که داده باید در آن برگردانده شود (هدف تبدیل دلخواه) مشخص می‌کند: یک نام اتم (atom) مانند 'STRING' یا 'FILE_NAME'؛ مقدار پیش‌فرض آن STRING است، مگر در X11، که ابتدا UTF8_STRING امتحان می‌شود و STRING به‌عنوان جایگزین استفاده می‌شود. آرگومان کلیدواژه‌ای displayof نام ابزارکی را مشخص می‌کند که نمایشگر را برای واکشی گزینش تعیین می‌کند، و پیش‌فرض آن همین ابزارک است.

selection_handle(command, **kw)¶

command را به‌عنوان یک هندلر ثبت کنید تا گزینش X را که این ابزارک مالک آن است، هنگامی که برنامه‌ی دیگری آن را درخواست می‌کند، تأمین کند. هنگامی که گزینش بازیابی می‌شود، command با دو آرگومان فراخوانی می‌شود: آفست نویسه‌ی آغازین و حداکثر تعداد نویسه‌های قابل بازگرداندن، و باید حداکثر همان تعداد نویسه از گزینش را که از آن آفست شروع می‌شود، بازگرداند؛ برای گزینش‌های بسیار طولانی، این فرمان به‌طور مکرر با آفست‌های فزاینده فراخوانی می‌شود. آرگومان کلیدواژه‌ای selection نام گزینش را مشخص می‌کند (پیش‌فرض PRIMARY) و آرگومان کلیدواژه‌ای type قالب گزینشی را که مدیر تأمین می‌کند، مشخص می‌کند (مانند 'STRING' یا 'FILE_NAME'، پیش‌فرض STRING).

selection_own(**kw)¶

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

selection_own_get(**kw)¶

ابزارکی در این برنامه را برمی‌گرداند که مالک گزینش X در نمایشگر حاوی این ابزارک است، یا اگر هیچ ابزارکی در این برنامه مالک گزینش نباشد، None برمی‌گرداند. آرگومان کلیدواژه‌ای selection نام گزینش را تعیین می‌کند و مقدار پیش‌فرض آن PRIMARY است. آرگومان کلیدواژه‌ای displayof ابزارکی را تعیین می‌کند که نمایشگر مورد پرس‌وجو را مشخص می‌کند، و مقدار پیش‌فرض آن این ابزارک است.

متدهایی که پیشوند clipboard_ دارند، کلیپ‌بورد را مدیریت می‌کنند.

clipboard_append(string, **kw)¶

string را به کلیپ‌بورد Tk اضافه کنید و مالکیت کلیپ‌بورد را در نمایش این ابزارک کسب کنید. پیش از افزودن، کلیپ‌بورد باید با clipboard_clear() خالی شود؛ همه افزودن‌ها باید پیش از بازگشت به حلقه رویداد کامل شوند تا کلیپ‌بورد به‌صورت اتمی به‌روزرسانی شود. آرگومان کلیدواژه‌ای type قالب داده را مشخص می‌کند، یعنی یک نام اتم (atom) مانند 'STRING' یا 'FILE_NAME' (پیش‌فرض STRING)، و آرگومان کلیدواژه‌ای format بازنمایی را مشخص می‌کند که برای انتقال آن استفاده می‌شود (پیش‌فرض STRING). آرگومان کلیدواژه‌ای displayof ابزارکی را مشخص می‌کند که نمایش هدف را تعیین می‌کند، و پیش‌فرض آن این ابزارک است. محتویات را می‌توان با clipboard_get() یا selection_get() بازیابی کرد.

clipboard_clear(**kw)¶

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

clipboard_get(**kw)¶

داده‌ها را از کلیپ‌بورد در نمایش این ابزارک بازیابی می‌کند. آرگومان کلیدواژه‌ای type قالبی را مشخص می‌کند که داده در آن بازگردانده می‌شود؛ این قالب یک نام اتم مانند 'STRING' یا 'FILE_NAME' است. مقدار پیش‌فرض آن STRING است، به‌جز در X11، که ابتدا UTF8_STRING امتحان می‌شود و از STRING به‌عنوان جایگزین استفاده می‌شود. آرگومان کلیدواژه‌ای displayof نام ابزارکی است که نمایش را تعیین می‌کند، و پیش‌فرض آن پنجره ریشه برنامه است. این معادل selection_get(selection='CLIPBOARD') است.

متدهایی که پیشوند option_ دارند، پایگاه داده‌ی گزینه‌های Tk را پرس‌وجو و تغییر می‌دهند.

option_add(pattern, value, priority=None)¶

یک گزینه به پایگاه داده‌ی گزینه‌های Tk اضافه کنید که value را با pattern مرتبط می‌سازد. pattern در قالب معمول X از نام‌ها و/یا کلاس‌هایی تشکیل شده است که با ستاره یا نقطه از هم جدا شده‌اند. priority یک عدد صحیح بین ۰ تا ۱۰۰ است، یا یکی از نام‌های نمادین 'widgetDefault' (۲۰)، 'startupFile' (۴۰)، 'userDefault' (۶۰) یا 'interactive' (۸۰)؛ پیش‌فرض آن interactive است.

option_clear()¶

پایگاه داده‌ی گزینه‌های Tk را پاک می‌کند. گزینه‌های پیش‌فرض از ویژگی RESOURCE_MANAGER یا پرونده .Xdefaults، بار بعدی که گزینه‌ای به پایگاه داده افزوده شود یا از آن حذف شود، به‌طور خودکار دوباره بارگذاری می‌شوند.

option_get(name, className)¶

مقدار گزینه‌ای را که در پایگاه داده‌ی گزینه‌های Tk، با این ابزارک تحت name و className مطابقت دارد، برمی‌گرداند؛ اگر هیچ ورودی مطابقی وجود نداشته باشد، یک رشته خالی برمی‌گرداند. هنگامی که چند ورودی مطابقت داشته باشند، ورودی با بالاترین اولویت برگردانده می‌شود و در میان ورودی‌های با اولویت برابر، آخرین ورودی اضافه‌شده برگردانده می‌شود.

option_readfile(fileName, priority=None)¶

پرونده‌ای به نام fileName را بخوانید، که باید قالب استاندارد یک پایگاه داده منابع X مانند .Xdefaults را داشته باشد، و همه گزینه‌های مشخص‌شده در آن را به پایگاه داده گزینه‌های Tk اضافه کنید. priority مانند option_add() تفسیر می‌شود و به‌طور پیش‌فرض interactive است.

bell(displayof=0)¶

زنگ را روی نمایشگر این ابزارک، با استفاده از تنظیمات فعلی مربوط به زنگِ نمایشگر، به صدا درآورید و نگهبان صفحه را برای صفحه بازنشانی کنید. اگر displayof به‌عنوان یک ابزارک داده شود، در عوض زنگ در نمایشگر آن ابزارک به صدا درمی‌آید.

tk_setPalette(background, /)¶

tk_setPalette(*args, **kw)

طرح‌واره رنگ جدیدی را برای تمام عناصر ابزارک Tk تنظیم می‌کند. ابزارک‌های موجود به‌روزرسانی می‌شوند و پایگاه داده‌ی گزینه‌ها تغییر می‌کند تا ابزارک‌های بعدی از رنگ‌های جدید استفاده کنند. یک آرگومان رنگ واحد به‌عنوان رنگ پس‌زمینه معمول تلقی می‌شود و پالت کاملی از آن محاسبه می‌شود. به‌عنوان جایگزین، می‌توان آرگومان‌ها را به‌صورت جفت‌های کلیدواژه‌ای name/value نیز وارد کرد که نام گزینه‌های منفرد در پایگاه داده‌ی گزینه‌ها را تعیین می‌کنند. نام گزینه‌های شناخته‌شده عبارت‌اند از activeBackground، activeForeground، background، disabledForeground، foreground، highlightBackground، highlightColor، insertBackground، selectColor، selectBackground، selectForeground و troughColor؛ برای هر گزینه‌ای که مشخص نشده باشد، پیش‌فرض‌های معقولی محاسبه می‌شوند.

tk_bisque()¶

رنگ‌های برنامه را به طرح‌واره رنگی قهوه‌ای روشن (bisque) که در Tk 3.6 و نسخه‌های پیشین استفاده می‌شد، بازمی‌گرداند. برای سازگاری با نسخه‌های قدیمی‌تر ارائه شده است.

tk_strictMotif(boolean=None)¶

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

متدهایی که پیشوند busy_ دارند، وضعیت مشغول بودن یک پنجره را مدیریت می‌کنند؛ این وضعیت یک مکان‌نما مشغول نمایش می‌دهد و ورودی کاربر را نادیده می‌گیرد.

tk_busy_hold(**kw)¶

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

تنها گزینه‌ی پیکربندی پشتیبانی‌شده cursor است، یعنی مکان‌نمای که هنگام مشغول بودن ابزارک نمایش داده می‌شود؛ این گزینه می‌تواند هر یک از مقادیر پذیرفته‌شده توسط configure() را داشته باشد.

busy_hold()، busy() و tk_busy() نام‌های مستعار tk_busy_hold() هستند.

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

tk_busy_configure(cnf=None, **kw)¶

گزینه‌های پیکربندی پنجره مشغول را بازیابی یا تغییر می‌دهد. ابزارک باید پیش‌تر با tk_busy_hold() مشغول شده باشد. بدون آرگومان، یک دیکشنری برمی‌گرداند که همه گزینه‌های موجود را توصیف می‌کند؛ اگر cnf نام یک گزینه باشد، یک تاپل برمی‌گرداند که همان گزینه را توصیف می‌کند. در غیر این صورت، گزینه‌های داده‌شده را به مقادیر داده‌شده تنظیم می‌کند. گزینه‌ها می‌توانند هر یک از مقادیر پذیرفته‌شده توسط tk_busy_hold() را داشته باشند.

به پایگاه داده‌ی گزینه‌ها از طریق نام یا کلاس ابزارک ارجاع داده می‌شود. برای مثال، اگر قرار باشد یک ابزارک Frame با نام frame مشغول شود، می‌توان مکان‌نما مشغول را با هر یک از فراخوانی‌های زیر برای آن مشخص کرد:

w.option_add('*frame.busyCursor', 'gumby')
w.option_add('*Frame.BusyCursor', 'gumby')

busy_configure()، busy_config() و tk_busy_config() نام‌های مستعار tk_busy_configure() هستند.

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

tk_busy_cget(option)¶

مقدار فعلی option پیکربندی busy را برمی‌گرداند. ابزارک باید پیش‌تر توسط tk_busy_hold() مشغول شده باشد، و option می‌تواند هر یک از مقادیر پذیرفته‌شده توسط آن متد را داشته باشد.

busy_cget() نام مستعار tk_busy_cget() است.

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

tk_busy_forget()¶

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

busy_forget() یک نام مستعار از tk_busy_forget() است.

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

tk_busy_status()¶

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

busy_status() نام مستعاری از tk_busy_status() است.

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

tk_busy_current(pattern=None)¶

فهرستی از ابزارک‌هایی را که در حال حاضر مشغول هستند برمی‌گرداند. اگر pattern داده شود، تنها ابزارک‌های مشغولی که نام مسیرشان با الگو مطابقت دارد برگردانده می‌شوند.

busy_current() نام مستعاری برای tk_busy_current() است.

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

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

winfo_atom(name, displayof=0)¶

شناسه عدد صحیح برای اتمی که نام آن name است را برمی‌گرداند و در صورتی که اتمی وجود نداشته باشد، یک اتم جدید ایجاد می‌کند. اگر displayof داده شده باشد، اتم در نمایش آن پنجره جستجو می‌شود؛ در غیر این صورت در نمایش پنجره اصلی برنامه جستجو می‌شود.

winfo_atomname(id, displayof=0)¶

نام متنی اتمی که شناسه‌ی عدد صحیح آن id است را برمی‌گرداند. این، معکوس winfo_atom() است. اگر displayof داده شود، شناسه در نمایش آن پنجره جست‌وجو می‌شود؛ در غیر این صورت، در نمایش پنجره‌ی اصلی برنامه جست‌وجو می‌شود.

winfo_cells()¶

تعداد سلول‌های نقشه رنگ (colormap) برای ابزارک را برمی‌گرداند.

winfo_children()¶

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

winfo_class()¶

نام کلاس ابزارک را برمی‌گرداند.

winfo_colormapfull()¶

اگر مشخص باشد که نقشه رنگ (colormap) برای ابزارک پر است، True را برمی‌گرداند، در غیر این صورت False را برمی‌گرداند.

winfo_containing(rootX, rootY, displayof=0)¶

ابزارک شامل نقطه‌ی مشخص‌شده با rootX و rootY را برمی‌گرداند، یا اگر هیچ پنجره‌ای در این برنامه شامل آن نقطه نباشد، None را برمی‌گرداند. مختصات در دستگاه مختصات پنجره‌ی ریشه و بر حسب واحدهای صفحه هستند. اگر displayof داده شود، مختصات به صفحه‌ی شامل آن پنجره اشاره می‌کنند؛ در غیر این صورت به صفحه‌ی پنجره‌ی اصلی برنامه اشاره می‌کنند.

winfo_depth()¶

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

winfo_exists()¶

اگر ابزارک وجود داشته باشد، مقدار true و در غیر این صورت مقدار false را برمی‌گرداند.

winfo_fpixels(number)¶

یک مقدار ممیز شناور برمی‌گرداند که تعداد پیکسل‌های ابزارک معادل فاصله‌ی صفحه‌نمایش number را نشان می‌دهد (برای مثال، "2.0c" یا "1i"). نتیجه ممکن است کسری باشد؛ برای یک مقدار عدد صحیح گرد شده از winfo_pixels() استفاده کنید.

winfo_geometry()¶

هندسه‌ی ابزارک را در قالب widthxheight+x+y برمی‌گرداند. تمام ابعاد بر حسب پیکسل هستند. موقعیت نسبت به ابزارک والد است؛ برای موقعیت روی صفحه از winfo_rootx() و winfo_rooty() استفاده کنید. یک آفست می‌تواند منفی باشد؛ geometry() را ببینید.

winfo_height()¶

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

winfo_id()¶

یک شناسه‌ی سطح پایین ویژه‌ی سکو برای ابزارک برمی‌گرداند. در یونیکس، این شناسه‌ی پنجره‌ی X است و در ویندوز، دسته پنجره (window handle) است.

winfo_interps(displayof=0)¶

یک تاپل از نام‌های تمام مفسرهای Tcl که در حال حاضر برای یک نمایش خاص ثبت شده‌اند، برمی‌گرداند. اگر displayof داده شده باشد، مقدار بازگشتی به نمایش آن پنجره اشاره می‌کند؛ در غیر این صورت، به نمایش پنجره‌ی اصلی برنامه اشاره می‌کند.

winfo_ismapped()¶

اگر ابزارک در حال حاضر نگاشت‌شده باشد، مقدار true بازمی‌گرداند، در غیر این صورت مقدار false بازمی‌گرداند.

winfo_manager()¶

نام مدیر چیدمان (geometry manager) مسئول فعلی ابزارک را برمی‌گرداند، یا اگر تحت مدیریت هیچ مدیر چیدمانی نباشد، یک رشته خالی برمی‌گرداند.

winfo_name()¶

نام ابزارک را در والد خود برمی‌گرداند، برخلاف نام مسیر کامل آن.

winfo_parent()¶

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

winfo_pathname(id, displayof=0)¶

نام مسیر پنجره‌ای که شناسه‌ی آن id است را برمی‌گرداند. اگر displayof داده شده باشد، شناسه در نمایشگر آن پنجره جستجو می‌شود؛ در غیر این صورت، در نمایشگر پنجره‌ی اصلی برنامه جستجو می‌شود.

winfo_pixels(number)¶

تعداد پیکسل‌های موجود در ابزارک را که با فاصله صفحه‌ای number متناظر است برمی‌گرداند (برای مثال، "2.0c" یا "1i"). نتیجه به نزدیک‌ترین عدد صحیح گرد می‌شود؛ برای نتیجه کسری از winfo_fpixels() استفاده کنید.

winfo_pointerx()¶

مختصات x مکان‌نما را بر حسب پیکسل، نسبت به پنجره‌ی ریشه‌ی صفحه نمایش (یا ریشه‌ی مجازی، در صورت استفاده) برمی‌گرداند. اگر مکان‌نما در همان صفحه نمایش ابزارک نباشد، -1 را برمی‌گرداند.

winfo_pointerxy()¶

مختصات اشاره‌گر را به‌صورت یک تاپل (x, y)، بر حسب پیکسل و نسبت به پنجره‌ی ریشه‌ی صفحه‌نمایش (یا ریشه‌ی مجازی، در صورت استفاده) برمی‌گرداند. اگر اشاره‌گر روی همان صفحه‌نمایش ابزارک نباشد، هر دو مختصات -1 خواهند بود.

winfo_pointery()¶

مختصات y اشاره‌گر را بر حسب پیکسل، نسبت به پنجره‌ی ریشه‌ی صفحه‌نمایش (یا ریشه‌ی مجازی، در صورت استفاده) برمی‌گرداند. اگر اشاره‌گر در همان صفحه‌نمایشی که ابزارک قرار دارد نباشد، -1 برمی‌گرداند.

winfo_reqheight()¶

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

winfo_reqwidth()¶

عرض درخواستی ابزارک را بر حسب پیکسل برمی‌گرداند. این مقداری است که مدیر هندسی ابزارک برای محاسبه هندسه آن استفاده می‌کند.

winfo_rgb(color)¶

یک تاپل (r, g, b) از شدت‌های قرمز، سبز و آبی، در بازه‌ی ۰ تا ۶۵۵۳۵، برمی‌گرداند که در ابزارک با color مطابقت دارند. color را می‌توان در هر یک از قالب‌های قابل‌قبول برای یک گزینه‌ی رنگ مشخص کرد.

winfo_rootx()¶

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

winfo_rooty()¶

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

winfo_screen()¶

نام صفحه‌ی مرتبط با ابزارک را در قالب displayName.screenIndex برمی‌گرداند.

winfo_screencells()¶

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

winfo_screendepth()¶

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

winfo_screenheight()¶

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

winfo_screenmmheight()¶

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

winfo_screenmmwidth()¶

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

winfo_screenvisual()¶

کلاس بصری پیش‌فرض صفحه‌ی ابزارک را برمی‌گرداند؛ یکی از "directcolor"، "grayscale"، "pseudocolor"، "staticcolor"، "staticgray" یا "truecolor" است.

winfo_screenwidth()¶

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

winfo_server()¶

رشته‌ای حاوی اطلاعات درباره‌ی سرورِ نمایش ابزارک برمی‌گرداند. قالب دقیق این رشته ممکن است از یک سکو به سکوی دیگر متفاوت باشد.

winfo_toplevel()¶

پنجره‌ی بالای سلسله‌مراتبِ حاوی ابزارک را برمی‌گرداند. در Tk استاندارد، این همیشه یک ابزارک Toplevel است.

winfo_viewable()¶

اگر ابزارک و تمام نیاکان آن تا نزدیک‌ترین پنجره‌ی سطح بالا نگاشت‌شده باشند، true و در غیر این صورت false را برمی‌گرداند.

winfo_visual()¶

کلاس بصری ابزارک را برمی‌گرداند؛ یکی از "directcolor"، "grayscale"، "pseudocolor"، "staticcolor"، "staticgray" یا "truecolor".

winfo_visualid()¶

شناسه‌ی X برای بصری (visual) مربوط به ابزارک را برمی‌گرداند.

winfo_visualsavailable(includeids=False)¶

فهرستی برمی‌گرداند که visualهای در دسترس برای صفحه‌ی ابزارک را توصیف می‌کند. هر آیتم شامل یک کلاس visual (به winfo_visual() مراجعه کنید) و به دنبال آن، عمقی از نوع عدد صحیح است. اگر includeids درست باشد، شناسه‌ی X مربوط به visual نیز گنجانده می‌شود.

winfo_vrootheight()¶

اگر پنجره ریشه مجازی مرتبط با ابزارک وجود داشته باشد، ارتفاع آن را برمی‌گرداند؛ در غیر این صورت ارتفاع صفحه ابزارک را برمی‌گرداند.

winfo_vrootwidth()¶

عرض پنجره‌ی ریشه‌ی مجازی مرتبط با ابزارک را در صورت وجود برمی‌گرداند؛ در غیر این صورت، عرض صفحه‌ی نمایش ابزارک را برمی‌گرداند.

winfo_vrootx()¶

آفست x پنجره ریشه مجازی مرتبط با ابزارک را نسبت به پنجره ریشه صفحه آن برمی‌گرداند. این مقدار معمولاً صفر یا منفی است، و اگر پنجره ریشه مجازی وجود نداشته باشد، 0 است.

winfo_vrooty()¶

آفست y پنجره ریشه مجازی مرتبط با ابزارک را نسبت به پنجره ریشه صفحه‌نمایش آن برمی‌گرداند. این مقدار معمولاً صفر یا منفی است، و اگر پنجره ریشه مجازی وجود نداشته باشد، 0 است.

winfo_width()¶

عرض ابزارک را بر حسب پیکسل برمی‌گرداند. هنگامی که یک پنجره برای نخستین بار ایجاد می‌شود، عرض آن ۱ پیکسل است؛ این عرض در نهایت توسط مدیر چیدمان تغییر می‌کند. همچنین ببینید winfo_reqwidth().

winfo_x()¶

مختصات x گوشه‌ی بالا-چپ حاشیه‌ی ابزارک (یا خود ابزارک، اگر حاشیه‌ای نداشته باشد) را در والد ابزارک برمی‌گرداند.

winfo_y()¶

مختصات y گوشه‌ی بالا سمت چپ حاشیه‌ی ابزارک را در والد ابزارک برمی‌گرداند (یا خود ابزارک اگر حاشیه ندارد).

info_patchlevel()¶

سطح وصله‌ی Tcl/Tk را به‌صورت یک تاپل نام‌دار (named tuple) با همان پنج فیلدِ sys.version_info برمی‌گرداند: major، minor، micro، releaselevel و serial. releaselevel یکی از 'alpha'، 'beta' یا 'final' است. تبدیل آن به یک رشته، نسخه را در نمادگذاری معمول Tcl/Tk می‌دهد؛ برای مثال '9.0.3' برای یک انتشار نهایی یا '9.1b2' برای یک پیش‌انتشار.

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

class tkinter.Wm¶

میکس‌این Wm دسترسی به مدیر پنجره را فراهم می‌کند و به برنامه اجازه می‌دهد مواردی مانند عنوان، هندسه و نماد یک پنجره‌ی سطح بالا، نحوه‌ی تغییر اندازه‌ی آن و چگونگی پاسخ آن به پروتکل‌های مدیر پنجره را کنترل کند. این میکس‌این در Tk و Toplevel ادغام شده است، بنابراین متدهای آن در هر پنجره‌ی سطح بالا در دسترس هستند. هر متد دو نوشتار معادل دارد: یک نام کوتاه و یک نام با پیشوند wm_ (برای مثال، title() و wm_title()). همچنین ببینید مدیر پنجره.

aspect(minNumer=None, minDenom=None, maxNumer=None, maxDenom=None)¶

نسبت ابعاد (نسبت عرض به ارتفاع) پنجره را محدود می‌کند. اگر هر چهار آرگومان داده شوند، مدیر پنجره این نسبت را بین minNumer/minDenom و maxNumer/maxDenom حفظ می‌کند؛ دادن رشته‌های خالی هرگونه محدودیت موجود را حذف می‌کند. بدون آرگومان، یک تاپل از چهار مقدار فعلی، یا اگر هیچ محدودیت نسبت ابعادی فعال نباشد، None برمی‌گرداند. wm_aspect() نام مستعاری از aspect() است.

attributes(*args, return_python_dict=False, **kwargs)¶

ویژگی‌های مختص پلتفرم پنجره را پرس‌وجو یا تنظیم کنید. بدون آرگومان، پرچم‌های مختص پلتفرم و مقادیر آن‌ها برمی‌گردانده می‌شوند؛ برای دریافت آن‌ها به‌صورت یک دیکشنری، return_python_dict را با مقدار true ارسال کنید. یک نام گزینه تکی مانند 'alpha' مقدار آن گزینه را برمی‌گرداند و گزینه‌ها با استفاده از آرگومان‌های کلیدواژه‌ای تنظیم می‌شوند (alpha=0.5).

ویژگی‌های در دسترس بسته به پلتفرم متفاوت است. تمام پلتفرم‌ها از موارد زیر پشتیبانی می‌کنند:

alpha

کدری پنجره، از 0.0 (کاملاً شفاف) تا 1.0 (کدر). هر جا شفافیت پشتیبانی نشود، مقدار روی 1.0 باقی می‌ماند.

appearance

اینکه پنجره در ویندوز و مک‌اواس در حالت تاریک رندر می‌شود: 'auto'، 'light' یا 'dark' (این مورد در X11 تأثیری ندارد).

fullscreen

اینکه پنجره تمام صفحه را اشغال می‌کند و حاشیه ندارد.

topmost

اینکه پنجره بالای همه‌ی پنجره‌های دیگر نمایش داده می‌شود.

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

disabled

اینکه پنجره در وضعیت غیرفعال قرار دارد.

toolwindow

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

transparentcolor

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

macOS همچنین پشتیبانی می‌کند:

class

اینکه پنجره‌ی زیربنایی Aqua یک nswindow است یا یک nspanel؛ این مورد فقط پیش از ایجاد پنجره قابل تنظیم است.

modified

وضعیت تغییری که توسط دکمه‌ی بستن پنجره و نماد پراکسی (proxy icon) نمایش داده می‌شود.

notify

اینکه آیا آیکون داک برنامه برای جلب توجه جهش می‌کند.

stylemask

نقاب سبک (style mask) پنجره‌ی زیربنایی Aqua، که به‌صورت فهرستی از نام‌های بیت مانند titled یا resizable ارائه می‌شود.

tabbingid

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

tabbingmode

اینکه آیا پنجره می‌تواند به‌عنوان زبانه باز شود: 'auto'، 'preferred' یا 'disallowed'.

titlepath

مسیر پرونده‌ای که نماد پراکسی (proxy icon) پنجره آن را نشان می‌دهد.

transparent

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

X11 علاوه بر این پشتیبانی می‌کند:

type

نوع پنجره، یا فهرستی از انواع به‌ترتیب اولویت، که مدیر پنجره باید برای تفسیر پنجره از آن‌ها استفاده کند، مانند 'dialog' یا 'splash'.

zoomed

اینکه آیا پنجره بیشینه‌شده است.

نکته

Tk 8.6 ویژگی type را افزود و Tk 9.0 ویژگی‌های appearance، class، stylemask، tabbingid و tabbingmode را افزود.

در X11، تغییرات به‌صورت ناهمگام اعمال می‌شوند، بنابراین مقدار پرس‌وجوشده ممکن است هنوز بازتاب‌دهنده آخرین درخواست نباشد. wm_attributes() نام مستعار attributes() است.

تغییر یافته در نسخه‌ی 3.13: اکنون می‌توان یک ویژگی را با نام، بدون - آغازین، پرس‌وجو کرد و ویژگی‌ها را می‌توان با آرگومان‌های کلیدواژه‌ای تنظیم کرد. پارامتر return_python_dict افزوده شد.

منسوخ شده از نسخه‌ی 3.13: تنظیم یک ویژگی با ارسال نام گزینه (با یک - در ابتدا) و مقدار آن به‌عنوان دو آرگومان جایگاهی، مانند w.attributes('-alpha', 0.5)، منسوخ شده است؛ در عوض از آرگومان‌های کلیدواژه‌ای استفاده کنید.

client(name=None)¶

name را که باید نام میزبانی باشد که برنامه روی آن اجرا می‌شود، در ویژگی WM_CLIENT_MACHINE پنجره ذخیره می‌کند تا مدیر پنجره یا نشست از آن استفاده کند. یک رشته خالی ویژگی را حذف می‌کند. بدون آرگومان، آخرین نام تنظیم‌شده را برمی‌گرداند، یا یک رشته خالی. wm_client() نام مستعار client() است.

colormapwindows(*wlist)¶

ویژگی WM_COLORMAP_WINDOWS را دستکاری می‌کند، که به مدیر پنجره درباره پنجره‌هایی که نقشه‌رنگ‌های خصوصی دارند اطلاع می‌دهد. اگر wlist داده شود، ویژگی را با آن پنجره‌ها بازنویسی می‌کند (ترتیب آن‌ها یک ترتیب اولویت برای نصب نقشه‌رنگ‌ها است). بدون آرگومان، فهرست پنجره‌هایی که در حال حاضر در این ویژگی آمده‌اند را برمی‌گرداند. wm_colormapwindows() نام مستعار colormapwindows() است.

command(value=None)¶

مقدار value را در ویژگی WM_COMMAND پنجره ذخیره می‌کند تا توسط مدیر پنجره یا مدیر نشست استفاده شود؛ این مقدار باید فهرستی باشد که کلمات فرمان استفاده‌شده برای فراخوانی برنامه را ارائه می‌دهد. یک رشته خالی ویژگی را حذف می‌کند. بدون آرگومان، آخرین مقدار تنظیم‌شده یا یک رشته خالی را برمی‌گرداند. wm_command() نام مستعار command() است.

deiconify()¶

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

focusmodel(model=None)¶

مدل فوکوس پنجره را تنظیم یا پرس‌وجو می‌کند. model یا 'active' است (پنجره فوکوس ورودی را برای خود یا زیرمجموعه‌هایش مطالبه می‌کند، حتی زمانی که فوکوس در برنامه‌ای دیگر است) یا 'passive' است (پنجره به مدیر پنجره اتکا می‌کند تا فوکوس را به آن بدهد). بدون آرگومان، مدل جاری را برمی‌گرداند. مقدار پیش‌فرض 'passive' است، که دستور focus() آن را فرض می‌کند. wm_focusmodel() نام مستعار focusmodel() است.

forget(window)¶

window را از صفحه‌ی نمایش خارج کنید (unmap) تا دیگر توسط مدیر پنجره مدیریت نشود. در این صورت با یک Toplevel مانند یک Frame رفتار می‌شود، اگرچه پیکربندی -menu آن به خاطر سپرده می‌شود و اگر ابزارک دوباره مدیریت شود، منو دوباره ظاهر می‌شود. wm_forget() یک نام مستعار از forget() است.

با Pack.forget() اشتباه گرفته نشود.

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

frame()¶

اگر مدیر پنجره آن را در چنین قابی تغییر والد داده باشد، شناسه‌ی پنجره‌ی خاصِ سکو برای بیرونی‌ترین قاب تزئینی حاوی پنجره را برمی‌گرداند؛ در غیر این صورت شناسه‌ی خود پنجره را برمی‌گرداند. wm_frame() نام مستعار frame() است.

geometry(newGeometry=None)¶

هندسه پنجره را تنظیم یا پرس‌وجو می‌کند. newGeometry به شکل =widthxheight+x+y است، که در آن می‌توان هر یک از =، widthxheight و موقعیت +x+y را حذف کرد. width و height بر حسب پیکسل هستند (یا واحدهای شبکه برای یک پنجره شبکه‌بندی‌شده)؛ موقعیت با پیشوند + از لبه چپ یا بالای صفحه‌نمایش اندازه‌گیری می‌شود و موقعیت با پیشوند - از لبه راست یا پایین صفحه‌نمایش اندازه‌گیری می‌شود. آفست می‌تواند منفی باشد، مانند '200x100+-9+-8'، هنگامی که لبه پنجره فراتر از لبه متناظر صفحه‌نمایش قرار گرفته باشد. یک رشته خالی هر هندسه تعیین‌شده توسط کاربر را لغو می‌کند و به پنجره اجازه می‌دهد تا به اندازه طبیعی خود بازگردد. بدون آرگومان، هندسه کنونی را به صورت رشته‌ای به شکل '200x200+10+10' برمی‌گرداند. wm_geometry() نام مستعاری از geometry() است.

grid(baseWidth=None, baseHeight=None, widthInc=None, heightInc=None)¶

پنجره را به‌عنوان یک پنجره شبکه‌بندی‌شده مدیریت می‌کند و رابطه بین واحدهای شبکه و پیکسل‌ها را تعریف می‌کند. baseWidth و baseHeight تعداد واحدهای شبکه برای اندازه درخواستی داخلی پنجره هستند، و widthInc و heightInc اندازه‌های پیکسلی یک واحد شبکه افقی و یک واحد شبکه عمودی هستند. رشته‌های خالی مدیریت شبکه‌بندی‌شده را غیرفعال می‌کنند. بدون آرگومان، یک تاپل از چهار مقدار فعلی را برمی‌گرداند، یا اگر پنجره شبکه‌بندی‌نشده باشد None را برمی‌گرداند. wm_grid() نام مستعاری از grid() است.

با مدیر هندسی grid Grid.grid() اشتباه گرفته نشود.

group(pathName=None)¶

رهبر یک گروه از پنجره‌های مرتبط را تنظیم یا پرس‌وجو کنید. pathName نام مسیر رهبر گروه را مشخص می‌کند؛ برای مثال، مدیر پنجره ممکن است هنگامی که رهبر گروه به آیکون تبدیل می‌شود (iconified)، تمام پنجره‌های گروه را از نگاشت خارج کند (unmap). یک رشته خالی پنجره را از هر گروه حذف می‌کند. بدون آرگومان، نام مسیر رهبر گروه فعلی یا یک رشته خالی را برمی‌گرداند. wm_group() نام مستعاری از group() است.

iconbitmap(bitmap=None, default=None)¶

بیت‌مپ استفاده‌شده توسط مدیر پنجره برای آیکون پنجره را تنظیم یا پرس‌وجو می‌کند. bitmap یک بیت‌مپ را در یکی از قالب‌های استاندارد پذیرفته‌شده توسط Tk مشخص می‌کند؛ یک رشته خالی بیت‌مپ آیکون فعلی را لغو می‌کند. بدون آرگومان، نام بیت‌مپ آیکون فعلی یا یک رشته خالی را برمی‌گرداند. در ویندوز، آرگومان default یک آیکون را مشخص می‌کند (برای مثال یک پرونده .ico) که به تمام پنجره‌های سطح بالایی که آیکون خودشان را ندارند اعمال می‌شود. wm_iconbitmap() نام مستعار iconbitmap() است.

iconify()¶

پنجره را به حالت آیکون‌شده درآورید. اگر پنجره هنوز برای نخستین بار نگاشت (map) نشده است، ترتیبی دهید که هنگامی که در نهایت نگاشت می‌شود، در حالت آیکون‌شده ظاهر شود. wm_iconify() نام مستعار iconify() است.

iconmask(bitmap=None)¶

بیت‌مپی را که به‌عنوان نقاب برای آیکون استفاده می‌شود، تنظیم یا پرس‌وجو کنید (به iconbitmap() مراجعه کنید). هر جا که نقاب ۰ باشد، هیچ آیکونی نمایش داده نمی‌شود؛ هر جا که مقدار آن ۱ باشد، بیت‌های متناظر بیت‌مپ آیکون نمایش داده می‌شوند. یک رشته خالی نقاب فعلی را لغو می‌کند. بدون آرگومان، نام نقاب فعلی آیکون یا یک رشته خالی را برمی‌گرداند. wm_iconmask() نام مستعاری از iconmask() است.

iconname(newName=None)¶

نامی را که مدیر پنجره در داخل آیکون پنجره نمایش می‌دهد، تنظیم یا پرس‌وجو می‌کند. بدون آرگومان، نام فعلی آیکون را برمی‌گرداند، یا اگر هیچ نامی تنظیم نشده باشد، یک رشته‌ی خالی برمی‌گرداند (در این حالت، مدیر پنجره معمولاً عنوان پنجره را نمایش می‌دهد). wm_iconname() یک نام مستعار برای iconname() است.

iconphoto(default=False, *images)¶

آیکون نوار عنوان پنجره را از یک یا چند شیء PhotoImage ارائه‌شده در images تنظیم می‌کند. می‌توان چندین تصویر با اندازه‌های مختلف (برای مثال ۱۶x۱۶ و ۳۲x۳۲) ارائه کرد تا مدیر پنجره بتواند تصویر مناسبی را انتخاب کند. داده‌های تصویر در زمان فراخوانی به‌عنوان یک تصویر لحظه‌ای گرفته می‌شوند؛ تغییرات بعدی در تصاویر منعکس نمی‌شوند. اگر default درست باشد، آیکون همچنین برای همه پنجره‌های سطح بالا که در آینده ایجاد می‌شوند اعمال می‌شود. در macOS فقط از اولین تصویر استفاده می‌شود. wm_iconphoto() نام مستعاری از iconphoto() است.

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

iconposition(x=None, y=None)¶

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

iconwindow(pathName=None)¶

پنجره‌ای را که به‌عنوان آیکون برای پنجره استفاده می‌شود، تنظیم یا پرس‌وجو کنید. هنگامی که پنجره به حالت آیکون درمی‌آید، pathName نگاشت می‌شود تا به‌عنوان آیکون آن عمل کند و هنگامی که از حالت آیکون خارج می‌شود، دوباره از نگاشت خارج می‌شود. یک رشته‌ی خالی این ارتباط را لغو می‌کند. بدون آرگومان، نام مسیر پنجره‌ی آیکون کنونی یا یک رشته‌ی خالی برگردانده می‌شود. همه‌ی مدیران پنجره از پنجره‌های آیکون پشتیبانی نمی‌کنند، و این مفهوم در سکوهای غیر X11 بی‌معنا است. wm_iconwindow() نام مستعار iconwindow() است.

manage(widget)¶

widget را به یک پنجره‌ی سطح بالای مستقل تبدیل می‌کند که توسط مدیر پنجره با نوار عنوان و غیره آراسته می‌شود. تنها می‌توان از ابزارک‌های Frame، LabelFrame و Toplevel استفاده کرد (نسخه‌های tkinter.ttk پذیرفته نمی‌شوند)؛ ارسال هر نوع ابزارک دیگری خطایی پرتاب می‌کند. wm_manage() نام مستعاری برای manage() است.

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

maxsize(width=None, height=None)¶

حداکثر ابعاد مجاز پنجره را بر حسب پیکسل (یا واحدهای شبکه برای پنجره شبکه‌بندی‌شده) تنظیم یا پرس‌وجو می‌کند. مدیر پنجره، پنجره را محدود می‌کند تا بزرگ‌تر از width و height نباشد. بدون آرگومان، یک تاپل از حداکثر عرض و ارتفاع فعلی برمی‌گرداند. حداکثر اندازه به‌طور پیش‌فرض برابر با اندازه صفحه است. wm_maxsize() نام مستعاری از maxsize() است.

minsize(width=None, height=None)¶

حداقل ابعاد مجاز پنجره را، بر حسب پیکسل (یا واحدهای شبکه برای پنجره شبکه‌بندی‌شده)، تنظیم یا دریافت کنید. مدیر پنجره، پنجره را محدود می‌کند که از width و height کوچک‌تر نباشد. بدون آرگومان، یک تاپل از حداقل عرض و ارتفاع کنونی برمی‌گرداند. حداقل اندازه به‌طور پیش‌فرض در هر بُعد یک پیکسل است. wm_minsize() نام مستعاری از minsize() است.

overrideredirect(boolean=None)¶

پرچم override-redirect را برای پنجره تنظیم یا پرس‌وجو می‌کند. هنگامی که این پرچم تنظیم شده باشد، مدیر پنجره پنجره را نادیده می‌گیرد: در یک قاب تزئینی قرار نمی‌گیرد (reparented) و کاربر نمی‌تواند از طریق کنترل‌های معمول مدیر پنجره با آن تعامل کند. بدون آرگومان، یک مقدار بولی برمی‌گرداند که نشان می‌دهد پرچم تنظیم شده است یا خیر، یا اگر تنظیم‌نشده باشد، None برمی‌گرداند. این پرچم تنها زمانی به‌طور قابل‌اتکا رعایت می‌شود که پنجره برای نخستین بار به نگاشت درآید یا از حالت withdrawn دوباره به نگاشت درآید (remapped). wm_overrideredirect() یک نام مستعار برای overrideredirect() است.

positionfrom(who=None)¶

منشأ موقعیت فعلی پنجره را تنظیم یا پرس‌وجو می‌کند. who یا 'program' است یا 'user' و نشان می‌دهد که موقعیت را برنامه درخواست کرده است یا کاربر؛ یک رشته‌ی خالی منشأ فعلی را لغو می‌کند. بدون آرگومان، منشأ فعلی را برمی‌گرداند، یا اگر هیچ منشأی تنظیم نشده باشد، یک رشته‌ی خالی برمی‌گرداند. Tk به‌طور خودکار، هنگامی که geometry() فراخوانی می‌شود، منشأ را روی 'user' تنظیم می‌کند، مگر اینکه به‌طور صریح روی 'program' تنظیم شده باشد. wm_positionfrom() نام مستعاری از positionfrom() است.

protocol(name=None, func=None)¶

func به‌عنوان هندلر پروتکل name مدیر پنجره ثبت می‌شود؛ name یک اتم (atom) مانند 'WM_DELETE_WINDOW'، 'WM_SAVE_YOURSELF' یا 'WM_TAKE_FOCUS' است. سپس هرگاه مدیر پنجره پیامی از آن پروتکل ارسال کند، func فراخوانی می‌شود. Tk یک هندلر پیش‌فرض WM_DELETE_WINDOW نصب می‌کند که پنجره را نابود می‌کند؛ این متد می‌تواند آن را جایگزین کند. اگر func یک رشته‌ی خالی باشد، هندلر حذف می‌شود. در صورت ارائه‌ی فقط name، نام فرمان هندلر ثبت‌شده‌ی آن برگردانده می‌شود، یا اگر هیچ هندلری تنظیم نشده باشد، یک رشته‌ی خالی برگردانده می‌شود (هندلر پیش‌فرض WM_DELETE_WINDOW گزارش نمی‌شود)؛ بدون آرگومان، یک تاپل از پروتکل‌هایی که در حال حاضر هندلر دارند برگردانده می‌شود. wm_protocol() نام مستعار protocol() است.

resizable(width=None, height=None)¶

کنترل می‌کند که آیا کاربر مجاز است به‌صورت تعاملی اندازه‌ی پنجره را تغییر دهد یا خیر. width و height مقادیر بولی هستند که تعیین می‌کنند آیا عرض و ارتفاع پنجره قابل تغییر هستند یا خیر. بدون آرگومان، یک تاپل از دو مقدار 0/1 برمی‌گرداند که نشان می‌دهد هر بُعد در حال حاضر قابل تغییر اندازه است یا خیر. به‌طور پیش‌فرض، یک پنجره در هر دو بُعد قابل تغییر اندازه است. wm_resizable() نام مستعاری برای resizable() است.

sizefrom(who=None)¶

منبع اندازه‌ی فعلی پنجره را تنظیم یا پرس‌وجو می‌کند. who می‌تواند 'program' یا 'user' باشد و نشان می‌دهد که اندازه توسط برنامه درخواست شده است یا توسط کاربر؛ یک رشته خالی منبع فعلی را لغو می‌کند. بدون آرگومان، منبع فعلی را برمی‌گرداند، یا اگر هیچ منبعی تنظیم نشده باشد، یک رشته خالی را برمی‌گرداند. wm_sizefrom() یک نام مستعار برای sizefrom() است.

state(newstate=None)¶

وضعیت پنجره را تنظیم یا پرس‌وجو می‌کند. بدون آرگومان، وضعیت فعلی را برمی‌گرداند: یکی از 'normal'، 'iconic'، 'withdrawn'، 'icon' یا 'zoomed' (فقط در Windows و macOS). 'iconic' به پنجره‌ای اشاره دارد که به آیکون تبدیل شده است، در حالی که 'icon' به پنجره‌ای اشاره دارد که به‌عنوان آیکون برای پنجره‌ای دیگر عمل می‌کند (به iconwindow() مراجعه کنید)؛ نمی‌توان وضعیت 'icon' را تنظیم کرد. wm_state() نام مستعاری از state() است.

با ttk.Widget.state اشتباه گرفته نشود.

title(string=None)¶

عنوان پنجره را تنظیم یا دریافت کنید، که مدیر پنجره باید آن را در نوار عنوان پنجره نمایش دهد. بدون آرگومان، عنوان فعلی را برمی‌گرداند. عنوان به‌طور پیش‌فرض نام پنجره است. wm_title() یک نام مستعار از title() است.

transient(master=None)¶

پنجره را به‌عنوان یک پنجره گذرا (مانند یک منوی بازشو یا جعبه محاوره‌ای) علامت‌گذاری می‌کند که از طرف master، نام مسیر یک پنجره سطح بالای دیگر، عمل می‌کند. یک رشته خالی وضعیت گذرا را پاک می‌کند. بدون آرگومان، نام مسیر master جاری یا یک رشته خالی را برمی‌گرداند. یک پنجره گذرا تغییرات وضعیت master خود را منعکس می‌کند و ممکن است توسط مدیر پنجره به‌شکل متفاوتی آراسته شود؛ تبدیل یک پنجره به پنجره گذرای خودش خطا است. wm_transient() نام مستعاری از transient() است.

withdraw()¶

پنجره را از صفحه‌نمایش خارج می‌کند، آن را از نگاشت خارج کرده و باعث می‌شود مدیر پنجره آن را فراموش کند. اگر پنجره هرگز نگاشت نشده باشد، در عوض در حالت خارج‌شده (withdrawn) نگاشت می‌شود. گاهی لازم است پنجره‌ای را خارج کنید و سپس دوباره آن را نگاشت کنید (برای مثال با deiconify()) تا برخی مدیرهای پنجره متوجه تغییرات ویژگی‌های پنجره شوند. wm_withdraw() یک نام مستعار برای withdraw() است.

class tkinter.Pack¶

مدیر چیدمانی که ابزارک‌ها را با چسباندن آن‌ها به کناره‌های ظرفشان مرتب می‌کند. کلاس میکس‌این Pack توسط همه ابزارک‌ها (از طریق Widget) به ارث برده می‌شود و متدهایی را برای مدیریت یک ابزارک با مدیر چیدمان pack فراهم می‌کند. همچنین مدیریت هندسه را ببینید.

نکته

Pack، Place و Grid همگی نام‌های کوتاه متد forget()، info()، slaves()، content() و propagate() را تعریف می‌کنند. در یک ابزارک، این نام‌های بدون پیشوند به نسخه‌های مربوط به مدیر pack حل می‌شوند، زیرا Pack و Misc در ترتیب حل متد، پیش از Place و Grid قرار دارند، صرف‌نظر از این‌که کدام مدیر واقعاً ابزارک را مدیریت می‌کند؛ و configure()/config() گزینه‌های ابزارک را پیکربندی می‌کنند، نه هندسه‌ی آن. برای عمل بر یک مدیر هندسه‌ی خاص، از متدهای صریح pack_*، grid_* و place_* استفاده کنید (و برای پیکربندی هندسه از pack، grid و place).

pack_configure(cnf={}, **kw)¶

pack(cnf={}, **kw)¶

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

side

اینکه در برابر کدام سمت از ظرف، ابزارک چیده شود: 'top' (پیش‌فرض)، 'bottom'، 'left' یا 'right'.

fill

اینکه ابزارک برای پر کردن ناحیه‌ی خود کشیده شود یا خیر: 'none' (پیش‌فرض)، 'x'، 'y' یا 'both'.

expand

اینکه ابزارک باید گسترش یابد تا هر فضای اضافی در ظرف خود را اشغال کند (یک بولی، پیش‌فرض false).

anchor

محل قرارگیری ابزارک در قطعه‌ی خود (parcel)، هنگامی که قطعه از ابزارک بزرگ‌تر باشد: لنگری مانند 'n' یا 'sw' (پیش‌فرض 'center').

ipadx, ipady

فاصله‌ی داخلی افزوده‌شده در سمت چپ و راست (ipadx) یا بالا و پایین (ipady) ابزارک، به‌عنوان یک فاصله‌ی صفحه‌ای (پیش‌فرض 0).

padx, pady

فاصله‌گذاری بیرونی در سمت چپ و راست (padx) یا بالا و پایین (pady) ابزارک، به‌صورت یک فاصله‌ی صفحه‌ای یا جفتی از دو فاصله برای دو طرف (پیش‌فرض 0).

after

ابزارک را پس از ابزارک داده‌شده در ترتیب چیدمان، با استفاده از همان ظرف بچینید.

before

ابزارک را پیش از ابزارک داده‌شده در ترتیب چیدمان، با استفاده از همان ظرف بچینید.

in_

ظرفی که ابزارک در آن بسته‌بندی می‌شود؛ مقدار پیش‌فرض آن ابزارک والد است.

pack()، configure() و config() نام‌های مستعار pack_configure() هستند.

pack_forget()¶

ابزارک را از نمایش برمی‌دارد و آن را از ترتیب pack حذف می‌کند و گزینه‌های pack آن را فراموش می‌کند. بعداً می‌توان آن را دوباره با pack_configure() pack کرد. forget() نام مستعار pack_forget() است، به جز در PanedWindow، ttk.Notebook و ttk.PanedWindow که متد forget() خود را ارائه می‌دهند.

با Wm.forget() اشتباه گرفته نشود.

pack_info()¶

یک دیکشنری از گزینه‌های فعلی بسته‌بندی (packing) ابزارک برمی‌گرداند. info() یک نام مستعار برای pack_info() است.

pack_propagate()¶

pack_propagate(flag)

مانند Misc.pack_propagate()، با در نظر گرفتن این ابزارک به‌عنوان یک ظرف: فعال یا غیرفعال کردن انتشار هندسه. propagate() نام مستعاری از pack_propagate() است.

pack_slaves()¶

مشابه Misc.pack_slaves(): فهرست ابزارک‌های تعبیه‌شده در این ابزارک را برمی‌گرداند. slaves() نام مستعاری از pack_slaves() است.

pack_content()¶

مشابه Misc.pack_content(). متد content() نام مستعاری برای pack_content() است.

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

class tkinter.Place¶

مدیر چیدمانی که ابزارک‌ها را در موقعیت‌ها و اندازه‌های مشخص درون ظرفشان قرار می‌دهد. همه ابزارک‌ها (از طریق Widget) از کلاس میکس‌این Place ارث می‌برند. همچنین ببینید مدیریت هندسه.

place_configure(cnf={}, **kw)¶

place(cnf={}, **kw)¶

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

x, y

موقعیت مطلق افقی و عمودی نقطه‌ی لنگر ابزارک، به‌صورت فاصله‌ی صفحه (پیش‌فرض 0).

relx, rely

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

anchor

اینکه کدام نقطه از ابزارک در موقعیت داده‌شده قرار می‌گیرد: یک لنگر مانند 'n' یا 'se' (پیش‌فرض 'nw').

عرض، ارتفاع

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

relwidth, relheight

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

bordermode

چگونگی تأثیر حاشیه‌ی ظرف بر جای‌گذاری: 'inside' (پیش‌فرض) ناحیه‌ی درون حاشیه را اندازه‌گیری می‌کند، 'outside' ناحیه‌ی شامل حاشیه را اندازه‌گیری می‌کند، و 'ignore' از ناحیه‌ی رسمی X استفاده می‌کند.

in_

ظرف که ابزارک نسبت به آن جای‌گذاری می‌شود؛ باید والد ابزارک یا یکی از نوادگان والد باشد و مقدار پیش‌فرض آن والد است.

place()، configure() و config() نام‌های مستعار place_configure() هستند.

place_forget()¶

ابزارک را از نگاشت خارج می‌کند و آن را از جای‌گذاری حذف می‌کند، به‌طوری‌که گزینه‌های جای‌گذاری آن فراموش می‌شوند.

place_info()¶

یک دیکشنری از گزینه‌های جاری place ابزارک برمی‌گرداند.

place_slaves()¶

مشابه Misc.place_slaves(): فهرست ابزارک‌های قرار گرفته در این ابزارک را برمی‌گرداند.

place_content()¶

مشابه Misc.place_content().

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

class tkinter.Grid¶

مدیر چیدمانی که ابزارک‌ها را در یک شبکه‌ی دوبعدی از ردیف‌ها و ستون‌ها درون ظرف آن‌ها می‌چیند. همه‌ی ابزارک‌ها میکس‌این Grid را (از طریق Widget) به ارث می‌برند. همچنین مدیریت هندسه را ببینید.

grid_configure(cnf={}, **kw)¶

grid(cnf={}, **kw)¶

ابزارک را در یک خانه از شبکه‌ی ظرف خود قرار می‌دهد.

با Wm.grid() اشتباه گرفته نشود.

گزینه‌های پشتیبانی‌شده عبارتند از:

ردیف، ستون

ردیف و ستون سلولی که ابزارک در آن قرار می‌گیرد، از 0 شمرده می‌شود. column به‌طور پیش‌فرض برابر با ستون پس از ابزارک قبلی قرار داده‌شده در همان فراخوانی grid_configure() (یا 0) است، و row به‌طور پیش‌فرض برابر با ردیف خالی بعدی است.

rowspan, columnspan

تعداد ردیف‌ها و ستون‌هایی که ابزارک باید در بر بگیرد (پیش‌فرض 1).

sticky

نحوه‌ی قرار دادن یا کشیدن ابزارک هنگامی که سلول آن بزرگ‌تر از ابزارک است: رشته‌ای شامل صفر یا چند تا از نویسه‌های 'n'، 's'، 'e' و 'w' که اضلاع سلول را که ابزارک به آن‌ها می‌چسبد مشخص می‌کند. مشخص کردن هر دو 'n' و 's' (یا 'e' و 'w') باعث می‌شود ابزارک کشیده شود تا ارتفاع (یا عرض) سلول را پر کند. مقدار پیش‌فرض '' است که ابزارک را در اندازه‌ی درخواستی آن در مرکز قرار می‌دهد.

ipadx, ipady

فاصله‌ی داخلی افزوده‌شده در سمت چپ و راست (ipadx) یا بالا و پایین (ipady) ابزارک، به‌عنوان یک فاصله‌ی صفحه‌ای (پیش‌فرض 0).

padx, pady

فاصله‌گذاری بیرونی در سمت چپ و راست (padx) یا بالا و پایین (pady) ابزارک، به‌صورت یک فاصله‌ی صفحه‌ای یا جفتی از دو فاصله برای دو طرف (پیش‌فرض 0).

in_

ظرف که ابزارک در شبکه‌ی آن قرار می‌گیرد؛ به‌طور پیش‌فرض، ابزارک والد است.

grid()، configure() و config() نام‌های مستعار grid_configure() هستند.

grid_forget()¶

ابزارک را از نگاشت خارج کرده و آن را از شبکه حذف می‌کند، گزینه‌های شبکه آن را نیز فراموش می‌کند.

grid_remove()¶

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

grid_info()¶

یک دیکشنری از گزینه‌های فعلی شبکه‌بندی (grid) ابزارک برمی‌گرداند.

grid_bbox(column=None, row=None, col2=None, row2=None)¶

مشابه Misc.grid_bbox(). bbox() نام مستعاری از grid_bbox() است، به‌جز در Canvas، Listbox، Spinbox، Text، ttk.Entry و ttk.Treeview، که متد bbox() خود را ارائه می‌دهند.

grid_columnconfigure(index, cnf={}, **kw)¶

همانند Misc.grid_columnconfigure(): گزینه‌های یک ستون شبکه (مانند weight، minsize، pad و uniform) را پرس‌وجو یا تنظیم می‌کند. columnconfigure() نام مستعاری از grid_columnconfigure() است.

grid_rowconfigure(index, cnf={}, **kw)¶

مشابه Misc.grid_rowconfigure(): گزینه‌های یک ردیف شبکه را پرس‌وجو یا تنظیم می‌کند. rowconfigure() نام مستعاری از grid_rowconfigure() است.

grid_location(x, y)¶

مشابه Misc.grid_location(): (column, row) سلولی را که پیکسل در x، y را می‌پوشاند برمی‌گرداند. location() نام مستعاری از grid_location() است.

grid_size()¶

مانند Misc.grid_size(): یک تاپل (columns, rows) برمی‌گرداند که اندازه‌ی شبکه را نشان می‌دهد. size() یک نام مستعار برای grid_size() است، به‌جز در ابزارک Listbox، که متد size() خود را ارائه می‌دهد.

grid_propagate()¶

grid_propagate(flag)

همان Misc.grid_propagate() است.

grid_slaves(row=None, column=None)¶

همانند Misc.grid_slaves(): ابزارک‌های مدیریت‌شده در شبکه را بازمی‌گرداند، که به‌صورت اختیاری به یک ردیف و/یا ستون محدود شده‌اند.

grid_content(row=None, column=None)¶

مشابه Misc.grid_content().

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

class tkinter.XView¶

میکس‌اینکه رابط پیمایش افقی مشترک میان ابزارک‌هایی مانند Entry، Canvas، Listbox، Text و Spinbox را فراهم می‌کند. متد xview() یک ابزارک به‌عنوان command یک Scrollbar افقی ثبت می‌شود.

xview(*args)¶

موقعیت افقی نما را دریافت یا تغییر می‌دهد. بدون آرگومان، یک تاپل (first, last) از دو کسر بین ۰ و ۱ برمی‌گرداند که بخشی از سند را که در حال حاضر قابل مشاهده است، نشان می‌دهند. در غیر این صورت، آرگومان‌ها به فرمان ابزارک xview در Tk ارسال می‌شوند و معمولاً توسط یک نوار پیمایش تولید می‌شوند؛ xview_moveto() و xview_scroll() رابط آسان‌تری فراهم می‌کنند.

xview_moveto(fraction)¶

نما را به‌گونه‌ای تنظیم کنید که fraction از عرض کل سند در سمت چپ، خارج از صفحه قرار گیرد. fraction عددی بین ۰ و ۱ است.

xview_scroll(number, what)¶

نما را به اندازه‌ی number واحد به چپ یا راست جابه‌جا کنید. what یا 'units' است یا 'pages'؛ مقدار منفی number به چپ اسکرول می‌کند و مقدار مثبت به راست اسکرول می‌کند. ابزارک Text همچنین 'pixels' را می‌پذیرد و در این صورت number می‌تواند یک فاصله‌ی روی صفحه مانند '1i' باشد.

class tkinter.YView¶

میکس‌اینرابط پیمایش عمودی مشترک میان ابزارک‌هایی مانند Canvas، Listbox و Text را فراهم می‌کند. متد yview() یک ابزارک به‌عنوان فرمان یک Scrollbar عمودی ثبت می‌شود.

yview(*args)¶

موقعیت عمودی نما را پرس‌وجو می‌کند یا تغییر می‌دهد. بدون آرگومان، یک تاپل (first, last) از دو کسر بین ۰ و ۱ برمی‌گرداند که نشان‌دهنده‌ی بخشی از سند است که در حال حاضر قابل مشاهده است. در غیر این صورت، آرگومان‌ها، که معمولاً توسط نوار لغزش تولید می‌شوند، به فرمان yview ابزارک Tk ارسال می‌شوند؛ yview_moveto() و yview_scroll() رابط آسان‌تری فراهم می‌کنند.

yview_moveto(fraction)¶

نما را طوری تنظیم کنید که fraction از ارتفاع کل سند در بالای صفحه خارج از دید باشد. fraction عددی بین ۰ و ۱ است.

yview_scroll(number, what)¶

نما را به اندازه‌ی number واحد به بالا یا پایین جابه‌جا کنید. what یا 'units' است یا 'pages'؛ مقدار منفی number به بالا اسکرول می‌کند و مقدار مثبت به پایین اسکرول می‌کند. ابزارک Text همچنین 'pixels' را می‌پذیرد و در این صورت number می‌تواند یک فاصله‌ی روی صفحه مانند '1i' باشد.

class tkinter.BaseWidget(master, widgetName, cnf={}, kw={}, extra=())¶

کلاس پایه‌ی داخلی برای همه‌ی ابزارک‌ها. این کلاس از Misc ارث‌بری می‌کند و سازوکار ایجاد ابزارک Tk زیربنایی را می‌افزاید؛ کد برنامه معمولاً به‌جای نمونه‌سازی مستقیم BaseWidget از Widget یا یک کلاس ابزارک مشخص استفاده می‌کند.

destroy()¶

این ابزارک و تمام فرزندان آن را نابود می‌کند، ابزارک‌های Tk مربوطه را حذف می‌کند و دستورات Tcl مرتبط را حذف می‌کند.

class tkinter.Widget(master, widgetName, cnf={}, kw={}, extra=())¶

کلاس پایه داخلی برای ابزارک‌های استاندارد. این کلاس، BaseWidget را با کلاس‌های میکس‌این مدیر چیدمانیعنی Pack، Place و Grid ترکیب می‌کند تا هر ابزارک بتواند توسط هر یک از سه مدیر چیدمان مدیریت شود. کلاس‌های ابزارک عینی (Button، Label و غیره) از Widget مشتق می‌شوند.

ابزارک‌های Toplevel¶

class tkinter.Tk(screenName=None, baseName=None, className='Tk', useTk=True, sync=False, use=None)¶

یک ابزارک Tk سطح بالا می‌سازد، که معمولاً پنجره‌ی اصلی یک برنامه است، و یک مفسر Tcl برای این ابزارک راه‌اندازی می‌کند. هر نمونه، مفسر Tcl مرتبط با خود را دارد. از Misc و Wm ارث می‌برد.

برای ایجاد یک مفسر Tcl بدون مقداردهی اولیه‌ی زیرسیستم Tk، به‌جای آن از تابع کارخانه‌ی Tcl() استفاده کنید.

کلاس Tk معمولاً با استفاده از تمام مقادیر پیش‌فرض نمونه‌سازی می‌شود. با این حال، آرگومان‌های کلیدواژه‌ای زیر در حال حاضر شناسایی می‌شوند:

screenName

هنگامی که (به‌صورت یک رشته) داده شود، متغیر محیطی DISPLAY را تنظیم می‌کند. (فقط X11)

baseName

نام پرونده پروفایل. به‌طور پیش‌فرض، baseName از نام برنامه (sys.argv[0]) گرفته می‌شود.

className

نام کلاس ابزارک. به‌عنوان پرونده پروفایل و همچنین به‌عنوان نامی که Tcl با آن فراخوانی می‌شود (argv0 در interp) استفاده می‌شود.

useTk

اگر True باشد، زیرسیستم Tk را راه‌اندازی می‌کند. تابع tkinter.Tcl() این را روی False قرار می‌دهد.

sync

اگر True باشد، تمام دستورات سرور X به‌صورت همگام اجرا می‌شوند، به‌طوری که خطاها بلافاصله گزارش می‌شوند. می‌توان از آن برای اشکال‌زدایی استفاده کرد. (فقط X11)

use

id پنجره‌ای را مشخص می‌کند که برنامه باید به جای ایجاد شدن به‌عنوان یک پنجره سطح بالای مستقل، در آن تعبیه شود. id باید به همان شیوه‌ای مشخص شود که مقدار گزینه -use برای ابزارک‌های سطح بالا مشخص می‌شود (یعنی شکلی مانند شکلی دارد که توسط winfo_id() برگردانده می‌شود).

توجه داشته باشید که در برخی سکوها، این مورد تنها در صورتی به‌درستی کار می‌کند که id به یک frame یا toplevel از Tk اشاره کند که گزینه‌ی -container آن فعال باشد.

Tk پرونده‌های پروفایل با نام‌های .className.tcl و .baseName.tcl را می‌خواند و آن‌ها را در مفسر Tcl تفسیر می‌کند و exec() را روی محتوای .className.py و .baseName.py فراخوانی می‌کند. مسیر پرونده‌های پروفایل، متغیر محیطی HOME است یا اگر تعریف‌نشده باشد، os.curdir است.

نکته

در ویندوز، ایجاد یک مفسر Tcl (با ایجاد نمونه‌ای از Tk یا فراخوانی Tcl()) متغیر محیطی HOME را برای فرایند، اگر از قبل تنظیم نشده باشد، به %HOMEDRIVE%%HOMEPATH% (یا USERPROFILE، یا c:\) تنظیم می‌کند. این کار توسط Tcl انجام می‌شود و می‌تواند بر سایر کدهایی که HOME را می‌خوانند تأثیر بگذارد.

tk¶

شیء برنامه‌ی Tk که با نمونه‌سازی از Tk ایجاد شده است. این شیء دسترسی به مفسر Tcl را فراهم می‌کند. هر ابزارکی که به همان نمونه از Tk متصل باشد، مقدار یکسانی برای ویژگی tk خود دارد.

master¶

شیء ابزارکی که این ابزارک را در بر می‌گیرد. برای Tk، master برابر None است، زیرا پنجره‌ی اصلی است. اصطلاحات master و parent مشابه‌اند و گاهی به‌جای یکدیگر به‌عنوان نام آرگومان استفاده می‌شوند؛ با این حال، فراخوانی winfo_parent() رشته‌ای از نام ابزارک را برمی‌گرداند، در حالی که master شیء را برمی‌گرداند. parent/child رابطه‌ی درخت‌مانند را بازتاب می‌دهد، در حالی که master (یا container)/content ساختار ظرف را بازتاب می‌دهد.

children¶

فرزندان مستقیم این ابزارک به‌صورت یک dict با نام ابزارک‌های فرزند به‌عنوان کلیدها و اشیای نمونه‌ی فرزند به‌عنوان مقدارها.

destroy()¶

این ابزارک و همه ابزارک‌های زیرمجموعه آن را نابود می‌کند و برای پنجره اصلی، اتصال به مفسر Tcl زیرین را پایان می‌دهد.

loadtk()¶

بارگذاری و مقداردهی اولیه‌ی زیرسیستم Tk را به پایان می‌رساند. این متد تنها زمانی لازم است که مفسر بدون Tk ایجاد شده باشد (برای مثال از طریق Tcl())؛ وقتی useTk برابر true باشد، به‌صورت خودکار فراخوانی می‌شود.

readprofile(baseName, className)¶

پرونده‌های پروفایل کاربر .className.tcl و .baseName.tcl را می‌خواند و در مفسر Tcl بارگذاری (source) می‌کند و پرونده‌های متناظر .className.py و .baseName.py را اجرا می‌کند. این کار در هنگام مقداردهی اولیه فراخوانی می‌شود؛ توضیح سازنده را در بالا ببینید.

report_callback_exception(exc, val, tb)¶

یک استثنای کال‌بک را گزارش می‌دهد. این هنگامی فراخوانی می‌شود که یک استثنا از یک کال‌بک Tkinter به بیرون منتشر شود؛ exc، val و tb نوع استثنا، مقدار و ردگیری پشته هستند، همان‌گونه که sys.exc_info() برمی‌گرداند. پیاده‌سازی پیش‌فرض یک ردگیری پشته را در sys.stderr چاپ می‌کند. می‌توان آن را برای سفارشی‌سازی مدیریت خطا بازنویسی کرد، برای مثال برای نمایش ردگیری پشته در یک پنجره‌ی محاوره‌ای.

class tkinter.Toplevel(master=None, cnf={}, **kw)¶

یک ابزارک Toplevel یک پنجره سطح‌بالا است، مشابه یک Frame با این تفاوت که والد X آن پنجره ریشه یک صفحه‌نمایش است، نه والد منطقی آن. هدف اصلی آن این است که به‌عنوان ظرفی برای جعبه‌های محاوره و سایر مجموعه‌های ابزارک‌ها عمل کند؛ تنها ویژگی‌های قابل مشاهده آن پس‌زمینه و یک حاشیه سه‌بعدی اختیاری است. از گزینه‌های قابل‌توجه می‌توان به menu اشاره کرد که یک Menu را به‌عنوان نوار منوی پنجره نصب می‌کند. این ابزارک از BaseWidget و Wm ارث می‌برد، بنابراین یک پنجره سطح‌بالا توسط مدیر پنجره مدیریت می‌شود. برای فهرست کامل گزینه‌ها، به صفحه راهنمای toplevel در Tk مراجعه کنید.

کلاس‌های ابزارک¶

class tkinter.Button(master=None, cnf={}, **kw)¶

یک ابزارک Button یک رشته متنی، بیت‌مپ یا تصویر را نمایش می‌دهد و هنگامی که کاربر آن را فشار دهد (با کلیک دکمه ۱ ماوس روی دکمه یا، هنگامی که دکمه تمرکز دارد، با فشار دادن کلید فاصله)، یک فرمان را فراخوانی می‌کند. این ابزارک از Widget ارث می‌برد. علاوه بر گزینه‌های استاندارد ابزارک، یک دکمه گزینه‌هایی را می‌پذیرد که در صفحه راهنمای button در Tk مستند شده‌اند، مانند command (کال‌بکی که هنگام فشار دادن دکمه فراخوانی می‌شود)، textvariable، state و default.

invoke()¶

فرمان مرتبط با دکمه را، در صورت وجود، فراخوانی کنید و نتیجه آن را برگردانید، یا اگر فرمانی با دکمه مرتبط نباشد، یک رشته خالی برگردانید. اگر وضعیت دکمه disabled باشد، این عمل نادیده گرفته می‌شود.

flash()¶

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

class tkinter.Canvas(master=None, cnf={}, **kw)¶

ابزارک Canvas گرافیک ساختاریافته را پیاده‌سازی می‌کند. این ابزارک هر تعداد آیتم را نمایش می‌دهد، مانند کمان‌ها، سطرهای، بیضی‌ها، چندضلعی‌ها، مستطیل‌ها، متن، بیت‌مپ‌ها، تصاویر و پنجره‌های تعبیه‌شده، که می‌توان آن‌ها را ترسیم کرد، جابه‌جا کرد، تغییر رنگ داد و به رویدادها متصل کرد. این ابزارک از Widget، XView و YView ارث می‌برد، بنابراین می‌توان نما را به‌صورت افقی و عمودی با xview() و yview() پیمایش کرد. برای فهرست کامل گزینه‌های ابزارک و آیتم، به صفحه راهنمای canvas در Tk مراجعه کنید.

هر آیتم دارای یک شناسه عدد صحیح یکتا، که هنگام ایجاد اختصاص داده می‌شود، و صفر یا چند برچسب رشته‌ای است. برچسب یک رشته دلخواه است که به شکل عدد صحیح نیست؛ ممکن است یک برچسب یکسان بین بسیاری از آیتم‌ها مشترک باشد، که این امر برچسب‌ها را برای گروه‌بندی آیتم‌ها مناسب می‌سازد. برچسب ویژه 'all' با همه آیتم‌های بوم مطابقت دارد، و 'current' با بالاترین آیتم زیر مکان‌نما ماوس مطابقت دارد. بیشتر متدها یک آرگومان tagOrId می‌گیرند که ممکن است یک شناسه عدد صحیح باشد که یک آیتم واحد را مشخص می‌کند، یا برچسبی باشد که صفر یا چند آیتم را مشخص می‌کند؛ همان‌طور که در صفحه راهنمای canvas Tk توضیح داده شده است، یک برچسب همچنین می‌تواند یک عبارت منطقی از برچسب‌ها باشد که با عملگرهای &&، ||، ^، ! و پرانتز ترکیب شده است. هنگامی که به متدی که روی یک آیتم واحد عمل می‌کند، یک tagOrId داده شود که با چند آیتم مطابقت دارد، معمولاً از پایین‌ترین آیتم منطبق در فهرست نمایش استفاده می‌کند.

آیتم‌ها در یک فهرست نمایش نگهداری می‌شوند که ترتیب ترسیم را تعیین می‌کند: آیتم‌هایی که در فهرست دیرتر می‌آیند، روی آیتم‌های پیشین ترسیم می‌شوند. یک آیتم تازه ایجادشده در بالای فهرست قرار می‌گیرد؛ ترتیب را می‌توان با tag_raise() و tag_lower() تغییر داد.

create_arc(*args, **kw)¶

create_bitmap(*args, **kw)¶

create_image(*args, **kw)¶

create_line(*args, **kw)¶

create_oval(*args, **kw)¶

create_polygon(*args, **kw)¶

create_rectangle(*args, **kw)¶

create_text(*args, **kw)¶

create_window(*args, **kw)¶

یک آیتم جدید از نوع متناظر ایجاد می‌شود و شناسه‌ی عدد صحیح آن را برمی‌گرداند. هر متد به‌صورت create_TYPE(coord..., **options) فراخوانی می‌شود: آرگومان‌های جایگاهی ابتدایی مختصاتی را ارائه می‌دهند که آیتم را تعریف می‌کنند (به‌صورت اعداد جداگانه، به‌صورت یک دنباله از اعداد، یا به‌صورت جفت‌های مختصات)، و آرگومان‌های کلیدواژه‌ای گزینه‌های مختص آیتم را تنظیم می‌کنند. مختصات و فاصله‌های صفحه می‌توانند به‌صورت اعداد (که به‌عنوان پیکسل تفسیر می‌شوند) یا به‌صورت رشته‌هایی با پسوند واحد ('m'، 'c'، 'i' یا 'p' برای میلی‌متر، سانتی‌متر، اینچ یا نقاط چاپگر) داده شوند، اما همیشه بر حسب پیکسل ذخیره و برگردانده می‌شوند.

انواع آیتم‌ها عبارتند از: arc (ناحیه‌ای کمان‌شکل که بخشی از یک بیضی است و با دو گوشه مقابل به‌صورت مورب x1, y1, x2, y2 از مستطیل دربرگیرنده تعریف می‌شود)؛ bitmap (یک بیت‌مپ دو رنگ که در نقطه x, y قرار دارد)؛ image (یک تصویر Tk که در نقطه x, y قرار دارد)؛ line (یک خط یا منحنی که از نقاط x1, y1, ..., xn, yn می‌گذرد)؛ oval (یک دایره یا بیضی محاط‌شده در مستطیل x1, y1, x2, y2)؛ polygon (یک چندضلعی بسته که از نقاط x1, y1, ..., xn, yn می‌گذرد)؛ rectangle (یک مستطیل با گوشه‌های x1, y1, x2, y2)؛ text (یک رشته متن که در نقطه x, y قرار دارد)؛ و window (یک ابزارک فرزند تعبیه‌شده در بوم در نقطه x, y که با گزینه window مشخص می‌شود).

بیشتر انواع آیتم، مجموعه‌ی مشترکی از گزینه‌های استاندارد آیتم و چند گزینه‌ی مختص هر نوع را می‌پذیرند. نام گزینه‌ها به‌عنوان آرگومان‌های کلیدواژه‌ای، بدون خط تیره‌ی آغازین ارسال می‌شوند.

گزینه‌های استاندارد آیتم عبارتند از:

fill

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

outline

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

width

پهنای خط دور، با مقدار پیش‌فرض 1.0. اگر outline خالی باشد، هیچ تأثیری ندارد.

dash

الگوی خط‌چین برای خط دور، که یا به‌صورت دنباله‌ای از طول قطعه‌ها بر حسب پیکسل داده می‌شود یا به‌صورت رشته‌ای از نویسه‌های '.'، ','، '-'، '_' و فاصله. الگوی خالی (پیش‌فرض) یک خط دور توپر رسم می‌کند.

dashoffset

آفست شروع بر حسب پیکسل در الگوی dash. اگر الگوی dash وجود نداشته باشد، نادیده گرفته می‌شود.

stipple

یک بیت‌مپ که به‌عنوان الگوی نقطه‌نگاری (stipple pattern) هنگام پر کردن آیتم استفاده می‌شود. تنها در X11 به‌خوبی پشتیبانی می‌شود.

outlinestipple

یک بیت‌مپ که به‌عنوان الگوی stipple هنگام رسم خط دور استفاده می‌شود. اگر outline خالی باشد، هیچ تأثیری ندارد.

offset, outlineoffset

آفست الگوهای نقطه‌نگاری (stipple) برای پر کردن و خط دور، که به‌صورت 'x,y' یا به‌عنوان یک سمت مانند 'n'، 'se' یا 'center' داده می‌شود. آفست‌های نقطه‌نگاری فقط در X11 پشتیبانی می‌شوند.

state

وضعیت بوم را برای این آیتم بازنویسی می‌کند؛ یکی از 'normal'، 'disabled' یا 'hidden'.

tags

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

بسیاری از این گزینه‌ها دارای گونه‌های active... و disabled... هستند (مانند activefill، disabledfill، activewidth، disableddash، activeoutline، disabledstipple) که هنگام فعال بودن آیتم (قرار داشتن زیر مکان‌نما ماوس) یا در وضعیت غیرفعال بودن آن، جایگزین گزینه‌ی پایه می‌شوند.

انواع آیتم زیر از گزینه‌های اضافی پشتیبانی می‌کنند.

برای آیتم‌های arc:

start

آغاز محدوده‌ی زاویه‌ای کمان، بر حسب درجه که خلاف جهت عقربه‌های ساعت از موقعیت ساعت ۳ اندازه‌گیری می‌شود.

extent

اندازه‌ی بازه‌ی زاویه‌ای، بر حسب درجه، در خلاف جهت عقربه‌های ساعت از start.

style

نحوه ترسیم کمان: 'pieslice' (پیش‌فرض)، 'chord' یا 'arc'.

برای آیتم‌های line:

arrow

محل رسم سرپیکان‌ها: 'none' (پیش‌فرض)، 'first'، 'last' یا 'both'.

arrowshape

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

capstyle

نحوه رسم انتهای سطرهای: 'butt' (پیش‌فرض)، 'projecting' یا 'round'.

joinstyle

نحوه‌ی رسم رئوس خط: 'round' (پیش‌فرض)، 'bevel' یا 'miter'.

smooth

روش هموارسازی: یک مقدار نادرست (پیش‌فرض) برای حالت بدون هموارسازی، یا 'true'/'bezier' یا 'raw' برای رسم خط به‌صورت منحنی.

splinesteps

تعداد پاره‌سطرهایی که هر اسپلاین (spline) را هنگام فعال بودن smooth تقریب می‌زنند.

برای آیتم‌های polygon:

joinstyle, smooth, splinesteps

در مورد آیتم‌های line، بر خط پیرامونی چندضلعی اعمال می‌شود.

برای آیتم‌های text:

text

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

font

قلم استفاده‌شده برای متن.

justify

چگونگی تراز سطرهای: 'left' (پیش‌فرض)، 'right' یا 'center'.

anchor

چگونگی قرارگیری متن نسبت به نقطه‌ی آن، که مقدار پیش‌فرض آن 'center' است.

width

حداکثر طول خط؛ اگر غیرصفر باشد، سطرهای در فاصله‌ها شکسته می‌شوند.

angle

میزان چرخش متن در خلاف جهت عقربه‌های ساعت حول نقطه موقعیت‌دهی آن، از 0.0 تا 360.0 (پیش‌فرض 0.0).

underline

اندیس نویسه‌ای که باید زیر آن خط کشیده شود، یا -1 برای هیچ‌کدام.

برای آیتم‌های bitmap:

bitmap

بیت‌مپ برای نمایش.

anchor

نحوه‌ی قرارگیری بیت‌مپ نسبت به نقطه‌ی آن.

پس‌زمینه، پیش‌زمینه

رنگ‌های استفاده‌شده برای پیکسل‌های 0 و 1 بیت‌مپ؛ یک background خالی، پیکسل‌های 0 را شفاف می‌کند. هر دو دارای گونه‌های active... و disabled... هستند و bitmap دارای گونه‌های activebitmap و disabledbitmap است.

برای آیتم‌های image:

image

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

anchor

چگونگی قرارگیری تصویر نسبت به نقطه‌ی آن.

هر دو گزینه دارای گونه‌های active... و disabled... (activeimage، disabledimage) هستند که در وضعیت‌های فعال و غیرفعال استفاده می‌شوند.

برای آیتم‌های window:

window

ابزارکی که باید تعبیه شود؛ این ابزارک باید فرزند بوم یا فرزند یکی از نیاکان آن باشد و نباید یک پنجره سطح بالا باشد.

anchor

چگونگی قرارگیری پنجره نسبت به نقطه‌ی آن.

عرض، ارتفاع

اندازه‌ای که باید به پنجره اختصاص داده شود؛ اگر صفر باشد (پیش‌فرض)، اندازه‌ی درخواستی به پنجره داده می‌شود.

آیتم‌های oval و rectangle گزینه‌های مختص نوع ندارند؛ آن‌ها فقط از گزینه‌های استاندارد آیتم استفاده می‌کنند.

نکته

نسخه‌ی Tk 8.6 گزینه‌ی angle را برای آیتم‌های text اضافه کرد.

coords(tagOrId)¶

coords(tagOrId, coordList, /)

coords(tagOrId, /, *coordList)

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

تغییر یافته در نسخه‌ی 3.12: آرگومان‌ها اکنون مسطح شده‌اند: مختصات می‌توانند به‌صورت آرگومان‌های جداگانه، به‌صورت یک دنباله واحد، یا به‌صورت جفت‌ها گروه‌بندی‌شده داده شوند، مانند متدهای create_*.

move(tagOrId, xAmount, yAmount, /)¶

هر یک از آیتم‌های مشخص‌شده با tagOrId را در فضای مختصات بوم (canvas) با افزودن xAmount به هر یک از مختصات‌های x و yAmount به هر یک از مختصات‌های y آن آیتم جابه‌جا می‌کند.

moveto(tagOrId, x='', y='')¶

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

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

scale(tagOrId, xOrigin, yOrigin, xScale, yScale, /)¶

مقیاس‌دهی مجدد مختصات تمام آیتم‌های داده‌شده توسط tagOrId در فضای مختصات بوم. هر مختصات x به‌گونه‌ای تنظیم می‌شود که فاصله‌ی آن از xOrigin با ضریب xScale تغییر کند، و هر مختصات y به‌گونه‌ای که فاصله‌ی آن از yOrigin با ضریب yScale تغییر کند (ضریب 1.0 مختصات را بدون تغییر باقی می‌گذارد).

delete(*tagOrIds)¶

هر یک از آیتم‌های داده‌شده توسط آرگومان‌های tagOrIds را حذف می‌کند.

dchars(tagOrId, first, /)¶

dchars(tagOrId, first, last, /)

از هر یک از آیتم‌های داده‌شده توسط tagOrId، نویسه‌ها (برای آیتم‌های متنی) یا مختصات (برای آیتم‌های خط و چندضلعی) را در بازه‌ی first تا last (شامل هر دو) حذف می‌کند؛ مقدار پیش‌فرض last برابر first است. آیتم‌هایی که از اندیس‌دهی پشتیبانی نمی‌کنند، این عملیات را نادیده می‌گیرند.

insert(tagOrId, beforeThis, string, /)¶

string را در هر یک از آیتم‌های مشخص‌شده با tagOrId، درست پیش از نویسه یا مختصاتی که اندیس آن beforeThis است، درج کنید. برای آیتم‌های خط و چندضلعی، string باید دنباله‌ای معتبر از مختصات باشد.

itemcget(tagOrId, option)¶

مقدار فعلی گزینه پیکربندی option را برای آیتم مشخص‌شده با tagOrId برمی‌گرداند (اگر با چندین آیتم مطابقت داشته باشد، پایین‌ترین آیتم منطبق). این مانند cget() است، اما برای یک آیتم منفرد اعمال می‌شود.

itemconfigure(tagOrId, cnf=None, **kw)¶

گزینه‌های پیکربندی آیتم‌های مشخص‌شده با tagOrId را بپرسید یا تغییر دهید. این متد همانند configure() است، با این تفاوت که به‌جای کل بوم، به آیتم‌های جداگانه اعمال می‌شود. بدون هیچ گزینه‌ای، یک دیکشنری برمی‌گرداند که گزینه‌های جاری اولین آیتم منطبق را توصیف می‌کند؛ در غیر این صورت، گزینه‌های داده‌شده را روی همه آیتم‌های منطبق تنظیم می‌کند. گزینه‌های مجاز، گزینه‌هایی هستند که متد create_* متناظر آن‌ها را می‌پذیرد. itemconfig() نام مستعاری برای itemconfigure() است.

type(tagOrId)¶

نوع آیتم داده‌شده توسط tagOrId را برمی‌گرداند (اولین آیتم منطبق در صورتی که با چندین آیتم مطابقت داشته باشد)، مانند 'rectangle' یا 'text'، یا اگر tagOrId با هیچ آیتمی مطابقت نداشته باشد None را برمی‌گرداند.

gettags(tagOrId, /)¶

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

dtag(tagOrId, /)¶

dtag(tagOrId, tagToDelete, /)

برچسب tagToDelete (که به‌طور پیش‌فرض tagOrId است) را از هر یک از آیتم‌های داده‌شده توسط tagOrId حذف می‌کند. آیتم‌هایی که آن برچسب را ندارند، بدون تغییر می‌مانند.

addtag(newtag, searchSpec, /, *args)¶

برچسب newtag را به هر آیتمی که توسط مشخصه جستجوی searchSpec (و هر args بیشتر) انتخاب‌شده است، اضافه می‌کند. searchSpec یکی از 'above'، 'all'، 'below'، 'closest'، 'enclosed'، 'overlapping' یا 'withtag' است؛ متدهای addtag_* زیر، متدهای پوششی مناسبی هستند که هر یک از این قالب‌ها را فراهم می‌کنند.

addtag_above(newtag, tagOrId)¶

برچسب newtag را به آیتم بلافاصله بالای (پس از) tagOrId در فهرست نمایش اضافه کنید.

addtag_all(newtag)¶

برچسب newtag را به تمام آیتم‌های بوم اضافه کنید.

addtag_below(newtag, tagOrId)¶

برچسب newtag را به آیتم درست پایین (قبل از) tagOrId در فهرست نمایش اضافه کنید.

addtag_closest(newtag, x, y, halo=None, start=None)¶

برچسب newtag را به نزدیک‌ترین آیتم به نقطه‌ی (x، y) اضافه می‌کند. اگر halo داده شده باشد، هر آیتمی که در آن فاصله از نقطه قرار داشته باشد، هم‌پوشان با آن در نظر گرفته می‌شود. اگر start داده شده باشد (یک برچسب یا شناسه)، بالاترین آیتم نزدیک که پایین‌تر از start در فهرست نمایش قرار دارد انتخاب می‌شود؛ این قابلیت می‌تواند برای پیمایش همه‌ی نزدیک‌ترین آیتم‌ها استفاده شود.

addtag_enclosed(newtag, x1, y1, x2, y2)¶

برچسب newtag را به هر آیتمی که به‌طور کامل درون مستطیل (x1، y1، x2، y2) محصور شده است، اضافه کنید، که در آن x1 <= x2 و y1 <= y2 است.

addtag_overlapping(newtag, x1, y1, x2, y2)¶

برچسب newtag را به هر آیتمی که با مستطیل (x1, y1, x2, y2) هم‌پوشانی دارد یا درون آن محصور شده است، اضافه کنید، که در آن x1 <= x2 و y1 <= y2 است.

addtag_withtag(newtag, tagOrId)¶

برچسب newtag را به هر آیتم داده‌شده توسط tagOrId اضافه کنید.

find(searchSpec, /, *args)¶

تاپلی از شناسه‌های همه آیتم‌های انتخاب‌شده توسط مشخصه جستجوی searchSpec (و هر آرگومان بعدی در args) را برمی‌گرداند، به ترتیب پشته‌بندی و با پایین‌ترین آیتم در ابتدا. مشخصه جستجو می‌تواند هر یک از قالب‌های پذیرفته‌شده توسط addtag() را داشته باشد. متدهای find_* زیر، متدهای پوششی آسان‌تری حول آن هستند.

find_above(tagOrId)¶

یک تاپل شامل شناسه‌ی آیتم درست بالای tagOrId در فهرست نمایش را برمی‌گرداند.

find_all()¶

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

find_below(tagOrId)¶

یک تاپل شامل شناسه‌ی آیتمی که درست زیر tagOrId در فهرست نمایش قرار دارد برمی‌گرداند.

find_closest(x, y, halo=None, start=None)¶

یک تاپل شامل شناسه‌ی نزدیک‌ترین آیتم به نقطه‌ی (x، y) برمی‌گرداند. halo و start مانند addtag_closest() تفسیر می‌شوند.

find_enclosed(x1, y1, x2, y2)¶

یک تاپل از شناسه‌های تمام آیتم‌هایی که کاملاً درون مستطیل (x1, y1, x2, y2) محصور شده‌اند، برمی‌گرداند.

find_overlapping(x1, y1, x2, y2)¶

یک تاپل از شناسه‌های تمام آیتم‌هایی که با مستطیل (x1, y1, x2, y2) هم‌پوشانی دارند یا درون آن محصور شده‌اند را برمی‌گرداند.

find_withtag(tagOrId)¶

یک تاپل از شناسه‌های تمام آیتم‌های مشخص‌شده با tagOrId را برمی‌گرداند.

tag_raise(tagOrId, aboveThis=None, /)¶

تمام آیتم‌های مشخص‌شده توسط tagOrId را به موقعیت جدیدی در فهرست نمایش، دقیقاً بالاتر از آیتم مشخص‌شده توسط aboveThis، یا به بالای فهرست نمایش اگر aboveThis ذکر نشود، منتقل می‌کند. هنگامی که چند آیتم منتقل می‌شوند، ترتیب نسبی آن‌ها حفظ می‌شود. این کار تأثیری بر آیتم‌های پنجره‌ی تعبیه‌شده ندارد؛ در عوض، ترتیب پشته‌ای آن‌ها توسط Misc.tkraise() و Misc.lower() کنترل می‌شود. lift() و tkraise() نام‌های مستعار tag_raise() هستند.

tag_lower(tagOrId, belowThis=None, /)¶

تمام آیتم‌های مشخص‌شده با tagOrId را به موقعیت جدیدی در فهرست نمایش، درست زیر آیتم مشخص‌شده با belowThis، یا در صورت حذف belowThis به انتهای فهرست نمایش منتقل می‌کند. هنگامی که چندین آیتم جابه‌جا می‌شوند، ترتیب نسبی آن‌ها حفظ می‌شود. این کار تأثیری بر آیتم‌های پنجره‌ی تعبیه‌شده ندارد. lower() نام مستعاری برای tag_lower() است.

نکته

در یک Canvas، tkraise()/lift() و lower() آیتم‌های بوم را دوباره در پشته می‌چینند و متدهای به‌ارث‌برده‌شده‌ی Misc.tkraise()/Misc.lift() و Misc.lower() را می‌پوشانند؛ متدهایی که خود ابزارک را دوباره در پشته می‌چینند و بنابراین در دسترس نیستند.

tag_bind(tagOrId, sequence=None, func=None, add=None)¶

کال‌بک func را برای تمام آیتم‌های مشخص‌شده با tagOrId به دنباله رویداد sequence متصل می‌کند، به‌گونه‌ای که هرگاه آن رویداد برای یکی از آیتم‌ها رخ دهد، func فراخوانی شود. این مانند Widget.bind است، اما روی آیتم‌های بوم به‌جای ابزارک‌های کامل عمل می‌کند؛ فقط رویدادهای ماوس، صفحه‌کلید و مجازی را می‌توان متصل کرد. رویدادهای ماوس به آیتم جاری و رویدادهای صفحه‌کلید به آیتم دارای فوکوس هدایت می‌شوند (به focus() مراجعه کنید). اگر add درست باشد، اتصال جدید به هرگونه اتصال موجود برای همان دنباله افزوده می‌شود، نه اینکه آن‌ها را جایگزین کند. شناسه تابع متصل‌شده را برمی‌گرداند؛ می‌توان این شناسه را به tag_unbind() داد.

tag_unbind(tagOrId, sequence, funcid=None)¶

اتصال رویداد sequence را برای همه آیتم‌های مشخص‌شده با tagOrId حذف می‌کند. اگر funcid داده شود، فقط همان کال‌بک (که توسط tag_bind() برگردانده‌شده است) لغو اتصال می‌شود و از ثبت خارج می‌گردد.

تغییر یافته در نسخه‌ی 3.13: اگر funcid داده شده باشد، فقط همان کال‌بک از اتصال خارج می‌شود.

bbox(tagOrId, /, *tagOrIds)¶

یک ۴-تایی (x1, y1, x2, y2) برگردانید که یک جعبه‌ی محدودکننده (bounding box) تقریبی را بر حسب پیکسل ارائه می‌دهد، جعبه‌ای که همه آیتم‌های مشخص‌شده با tagOrId و هر tagOrIds دیگری را در بر می‌گیرد. ممکن است نتیجه، جعبه‌ی محدودکننده واقعی را به اندازه چند پیکسل بیش‌برآورد کند. اگر هیچ آیتمی مطابقت نداشته باشد یا آیتم‌های منطبق چیزی برای نمایش نداشته باشند، None را برگردانید.

این، Misc.bbox() موروثی را می‌پوشاند؛ برای جعبه‌ی محدودکننده شبکه از grid_bbox() استفاده کنید.

canvasx(screenx, gridspacing=None)¶

با داشتن مختصات x پنجره screenx، مختصات x بوم نمایش‌داده‌شده در آن موقعیت را برمی‌گرداند. اگر gridspacing داده شده باشد، نتیجه به نزدیک‌ترین مضرب از واحدهای gridspacing گرد می‌شود.

canvasy(screeny, gridspacing=None)¶

با فرض مختصات y پنجره screeny، مختصات y بوم نمایش‌داده‌شده در آن موقعیت را برمی‌گرداند. اگر gridspacing داده شود، نتیجه به نزدیک‌ترین مضرب از واحدهای gridspacing گرد می‌شود.

focus()¶

focus(tagOrId, /)

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

این، Misc.focus() موروثی را می‌پوشاند؛ برای فوکوس کردن خود ابزارک از focus_set() استفاده کنید.

icursor(tagOrId, index, /)¶

مکان‌نمای درج آیتم‌های مشخص‌شده با tagOrId را دقیقاً پیش از نویسه‌ی مشخص‌شده با index قرار دهید. آیتم‌هایی که از مکان‌نمای درج پشتیبانی نمی‌کنند، تحت تأثیر قرار نمی‌گیرند. مکان‌نما تنها زمانی نمایش داده می‌شود که آیتم فوکوس داشته باشد، اما می‌توان موقعیت آن را در هر زمانی تنظیم کرد.

index(tagOrId, index, /)¶

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

select_adjust(tagOrId, index)¶

انتهای انتخاب در tagOrId را که به index نزدیک‌تر است، طوری تنظیم می‌کند که در index قرار گیرد، و انتهای دیگر را نقطه‌ی لنگر برای فراخوانی‌های بعدی select_to() قرار می‌دهد. اگر انتخاب در حال حاضر در tagOrId نباشد، مانند select_to() رفتار می‌کند.

select_clear()¶

اگر انتخاب در این بوم است، آن را پاک کنید؛ در غیر این صورت، هیچ کاری انجام ندهید.

select_from(tagOrId, index)¶

نقطه‌ی لنگر انتخاب را درست پیش از نویسه‌ی مشخص‌شده با index در آیتم مشخص‌شده با tagOrId تنظیم کنید. این کار خود انتخاب را تغییر نمی‌دهد؛ بلکه پایان ثابتی را برای فراخوانی‌های بعدی select_to() تعیین می‌کند.

select_item()¶

شناسه آیتمی که انتخاب را در بر دارد برگردانید، یا اگر انتخاب در این بوم نباشد None برگردانید. برخلاف find() و متدهای find_*، این متد شناسه را به‌جای عدد صحیح به‌صورت رشته برمی‌گرداند.

select_to(tagOrId, index)¶

انتخاب را روی نویسه‌های tagOrId بین نقطه‌ی لنگر انتخاب و index، شامل خود index، تنظیم می‌کند. نقطه‌ی لنگر همان نقطه‌ای است که توسط آخرین فراخوانی select_adjust() یا select_from() تنظیم شده است.

scan_mark(x, y)¶

x، y و نمای فعلی را برای استفاده در فراخوانی‌های بعدی scan_dragto() ثبت کنید. این کار معمولاً به فشار دکمه ماوس در ابزارک متصل می‌شود.

scan_dragto(x, y, gain=10)¶

بوم را به اندازه‌ی gain برابرِ اختلاف میان x، y و مختصات ارسال‌شده به آخرین فراخوانی scan_mark() پیمایش کنید. این معمولاً به رویدادهای حرکت ماوس در ابزارک متصل می‌شود و جلوه‌ی کشیدن بوم با سرعت بالا در پنجره‌ی خود را ایجاد می‌کند.

postscript(cnf={}, **kw)¶

یک بازنمایی PostScript (Encapsulated PostScript، نسخه‌ی 3.0) از بخشی یا کل بوم تولید می‌کند. اگر گزینه‌ی file یا channel داده شود، PostScript در آن‌جا نوشته می‌شود و یک رشته‌ی خالی برگردانده می‌شود؛ در غیر این صورت به‌صورت یک رشته برگردانده می‌شود. به‌طور پیش‌فرض، فقط ناحیه‌ای که در حال حاضر در پنجره قابل‌مشاهده است، تولید می‌شود؛ بنابراین معمولاً لازم است یا ابتدا update() فراخوانی شود یا از گزینه‌های width و height استفاده شود. گزینه‌های پشتیبانی‌شده شامل colormap، colormode، file، fontmap، height، pageanchor، pageheight، pagewidth، pagex، pagey، rotate، width، x و y می‌شوند.