`curses` --- مدیریت پایانه برای نمایشگرهای سلول‌نویسه‌ای (character-cell displays)¶

کد منبع: Lib/curses

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

اگرچه curses بیشترین کاربرد را در محیط یونیکس دارد، نسخه‌هایی برای ویندوز، DOS و احتمالاً سیستم‌های دیگر نیز در دسترس هستند. این ماژول توسعه به‌گونه‌ای طراحی شده است که با API کتابخانه ncurses مطابقت داشته باشد؛ ncurses یک کتابخانه curses متن‌باز است که روی لینوکس و نسخه‌های BSD یونیکس میزبانی می‌شود.

دسترس‌پذیری: not Android, not iOS, not WASI.

این ماژول در سکوهای موبایل یا سکوهای WebAssembly پشتیبانی نمی‌شود.

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

دسترس‌پذیری: Unix.

توجه

Whenever the documentation mentions a character it can be specified as an integer, a one-character Unicode string or a one-byte byte string. An integer is the code of a single encoded byte, optionally combined with attributes and a color pair, as returned by window.inch(). Methods that write to a window accept also a character cell: a Unicode string of a spacing character followed by combining characters, or a complexchar.

Whenever the documentation mentions a character string it can be specified as a Unicode string or a byte string. Methods that write to a window accept also a complexstr.

توجه

Whether curses may be used from several threads depends on the underlying library and how it was built. In many implementations, including the default build of ncurses, the screen state is shared and not thread-safe; since the blocking and refresh methods (such as getch() and refresh()) release the GIL, unsynchronized use from several threads can then crash the interpreter. Serialize the calls, or wrap them in window.use() and screen.use().

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

ماژول curses.ascii: ابزارهایی برای کار با نویسه‌های ASCII، صرف‌نظر از تنظیمات locale (locale) شما.
ماژول curses.panel: یک افزونه‌ی پشته‌ی پنل که به پنجره‌های curses عمق می‌بخشد.
ماژول curses.textpad: ابزارک متنی قابل‌ویرایش برای curses با پشتیبانی از کلیدبندی‌های مشابه Emacs.
برنامه‌نویسی Curses با پایتون: مطلب آموزشی درباره‌ی استفاده از curses در پایتون، نوشته‌ی Andrew Kuchling و Eric Raymond.

توابع¶

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

exception curses.error¶: استثنایی که هنگام برگرداندن خطا توسط تابعی از کتابخانه curses پرتاب می‌شود.

توجه

هرگاه آرگومان‌های x یا y برای یک تابع یا متد اختیاری باشند، مقدار پیش‌فرض آن‌ها موقعیت فعلی مکان‌نما خواهد بود. هرگاه attr اختیاری باشد، مقدار پیش‌فرض آن A_NORMAL خواهد بود.

ماژول curses توابع زیر را تعریف می‌کند:

Initialization and termination¶

curses.initscr()¶

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

برای آگاهی از هشداری درباره‌ی فراخوانی آن پیش از این تابع، setupterm() را ببینید.

توجه

اگر در باز کردن پایانه خطایی رخ دهد، ممکن است کتابخانه curses زیربنایی باعث خروج مفسر شود.

curses.endwin()¶: کتابخانه را از مقداردهی اولیه خارج می‌کند و پایانه را به وضعیت عادی بازمی‌گرداند.

curses.isendwin()¶: اگر endwin() فراخوانی شده باشد (یعنی کتابخانه curses از مقداردهی اولیه خارج شده باشد)، True را برمی‌گرداند.

curses.newterm(type=None, fd=None, infd=None, /)¶

Initialize a new terminal in addition to the one initialized by initscr(), and return a screen for it. This allows a program to drive more than one terminal.

type is the terminal name, as in setupterm(); if None, the value of the TERM environment variable is used. fd and infd are the output and input files for the terminal: either a file object or a file descriptor. They default to sys.stdout and sys.stdin.

The new screen becomes the current one. Use set_term() to switch between screens.

برای آگاهی از هشداری درباره‌ی فراخوانی آن پیش از این تابع، setupterm() را ببینید.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.new_prescr()¶

Return a new screen that can be used to call functions that affect global state before initscr() or newterm() is called.

Availability: if the underlying curses library provides new_prescr().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.set_term(screen, /)¶: Make screen, a screen returned by newterm(), the current terminal, and return the previously current screen. Returns None if the previous screen was the one created by initscr(). Raises error if screen has no terminal, as is the case for a screen returned by new_prescr().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.wrapper(func, /, *args, **kwargs)¶: curses را مقداردهی اولیه می‌کند و شیء فراخوانی‌پذیر دیگری به نام func را فراخوانی می‌کند که باید بخش باقی‌مانده‌ی برنامه‌ی استفاده‌کننده از curses شما باشد. اگر برنامه استثنایی را پرتاب کند، این تابع پیش از پرتاب دوباره‌ی استثنا و ایجاد ردگیری پشته، پایانه را به وضعیت سالم بازمی‌گرداند. سپس شیء فراخوانی‌پذیر func، پنجره‌ی اصلی 'stdscr' را به‌عنوان نخستین آرگومان خود و پس از آن، هر آرگومان دیگری را که به wrapper() داده شده باشد دریافت می‌کند. پیش از فراخوانی func، wrapper() حالت cbreak را روشن می‌کند، بازتاب را خاموش می‌کند، صفحه‌کلید پایانه را فعال می‌کند و اگر پایانه پشتیبانی از رنگ داشته باشد، رنگ‌ها را مقداردهی اولیه می‌کند. هنگام خروج (چه به‌صورت عادی و چه در اثر استثنا) حالت cooked را بازمی‌گرداند، بازتاب را روشن می‌کند و صفحه‌کلید پایانه را غیرفعال می‌کند.

Terminal mode control¶

curses.def_prog_mode()¶: حالت فعلی پایانه را به‌عنوان حالت «برنامه» ذخیره می‌کند، حالتی که برنامه‌ی در حال اجرا از curses استفاده می‌کند. (همتای آن حالت «پوسته» است، برای زمانی که برنامه در curses نیست.) فراخوانی‌های بعدی reset_prog_mode() این حالت را بازمی‌گردانند.

curses.def_shell_mode()¶: حالت جاری پایانه را به‌عنوان حالت «پوسته» ذخیره می‌کند، حالتی که برنامه‌ی در حال اجرا از curses استفاده نمی‌کند. (حالت متناظر آن، حالت «برنامه» است، زمانی که برنامه از قابلیت‌های curses استفاده می‌کند.) فراخوانی‌های بعدی reset_shell_mode() این حالت را بازگردانی می‌کند.

curses.reset_prog_mode()¶: پایانه را به حالت «program» بازمی‌گرداند، همان‌طور که پیش‌تر توسط def_prog_mode() ذخیره‌شده است.

curses.reset_shell_mode()¶: پایانه را به حالت «پوسته» بازمی‌گرداند، همان‌طور که پیش‌تر با def_shell_mode() ذخیره‌شده است.

curses.savetty()¶: وضعیت فعلی حالت‌های پایانه را در یک بافر ذخیره می‌کند که توسط resetty() قابل استفاده است.

curses.resetty()¶: وضعیت حالت‌های پایانه را به وضعیتی که در آخرین فراخوانی savetty() داشت، بازگردانید.

curses.curs_set(visibility)¶: وضعیت مکان‌نما را تنظیم می‌کند. می‌توان visibility را روی 0، 1، یا 2 برای حالت‌های نامرئی، عادی، یا بسیار نمایان تنظیم کرد. اگر پایانه از حالت نمایش درخواستی پشتیبانی کند، وضعیت قبلی مکان‌نما را برمی‌گرداند؛ در غیر این صورت استثنایی پرتاب می‌کند. در بسیاری از پایانه‌ها، حالت «نمایان» یک مکان‌نمای خط زیر و حالت «بسیار نمایان» یک مکان‌نمای بلوکی است.

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

curses.setsyx(y, x)¶: مکان‌نمای صفحه‌ی مجازی را روی y، x تنظیم می‌کند. اگر y و x هر دو -1 باشند، leaveok روی True تنظیم می‌شود.

curses.doupdate()¶

صفحه فیزیکی را به‌روزرسانی می‌کند. کتابخانه‌ی curses دو ساختار داده را نگه می‌دارد: یکی نشان‌دهنده‌ی محتویات فعلی صفحه فیزیکی و دیگری یک صفحه مجازی است که وضعیت بعدی مورد نظر را نشان می‌دهد. تابع doupdate() صفحه فیزیکی را به‌روزرسانی می‌کند تا با صفحه مجازی مطابقت داشته باشد.

صفحه‌ی مجازی می‌تواند پس از انجام عملیات نوشتن مانند addstr() روی یک پنجره، با یک فراخوانی noutrefresh() به‌روزرسانی شود. فراخوانی معمول refresh() صرفاً noutrefresh() و به‌دنبال آن doupdate() است؛ اگر لازم است چندین پنجره را به‌روزرسانی کنید، می‌توانید با انجام فراخوانی‌های noutrefresh() روی تمام پنجره‌ها و به‌دنبال آن‌ها یک doupdate()، سرعت عملکرد را افزایش دهید و شاید سوسوی صفحه را کاهش دهید.

Input options¶

curses.cbreak()¶: وارد حالت cbreak می‌شود. در حالت cbreak (که گاهی به آن حالت «rare» می‌گویند) بافرینگ خطی معمول tty غیرفعال می‌شود و نویسه‌ها برای خوانده‌شدن به‌صورت یکی‌یکی در دسترس قرار می‌گیرند. با این حال، برخلاف حالت raw، نویسه‌های ویژه (وقفه، خروج، تعلیق و کنترل جریان) اثرات خود را بر راه‌انداز tty و برنامه فراخوان حفظ می‌کنند. اگر ابتدا raw() و سپس cbreak() فراخوانی شود، پایانه در حالت cbreak باقی می‌ماند.

curses.nocbreak()¶: از حالت cbreak خارج شوید. به حالت عادی «cooked» همراه با بافرینگ خطی (line buffering) بازگردید.

curses.echo()¶: وارد حالت بازتاب (echo mode) شوید. در حالت بازتاب، هر نویسه‌ی ورودی به محض وارد شدن، روی صفحه بازتاب داده می‌شود.

curses.noecho()¶: از حالت echo خارج شوید. بازتاب نویسه‌های ورودی خاموش می‌شود.

curses.raw()¶: وارد حالت خام می‌شود. در حالت خام، بافر کردن خطی عادی و پردازش کلیدهای وقفه، خروج، تعلیق و کنترل جریان غیرفعال می‌شوند؛ نویسه‌ها یک‌به‌یک به توابع ورودی curses ارائه می‌شوند.

curses.noraw()¶: از حالت raw خارج شوید. به حالت عادی «cooked» با بافرینگ خطی (line buffering) بازگردید.

curses.halfdelay(tenths)¶: برای حالت نیمه‌تأخیر (half-delay) استفاده می‌شود؛ این حالت شبیه حالت cbreak است، بدین معنا که نویسه‌های تایپ‌شده توسط کاربر بلافاصله در دسترس برنامه قرار می‌گیرند. با این حال، پس از مسدود شدن به مدت tenths دهم ثانیه، اگر چیزی تایپ نشده باشد، یک استثنا پرتاب می‌شود. مقدار tenths باید عددی بین 1 و 255 باشد. برای خروج از حالت نیمه‌تأخیر از nocbreak() استفاده کنید.

curses.meta(flag)¶: اگر flag برابر True باشد، اجازه داده می‌شود که نویسه‌های ۸ بیتی ورودی داده شوند. اگر flag برابر False باشد، فقط اجازه داده می‌شود که نویسه‌های ۷ بیتی ورودی داده شوند.

curses.nl(flag=True)¶

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

اگر flag برابر False باشد، اثر آن همان فراخوانی nonl() است.

curses.nonl()¶: حالت خط جدید را ترک می‌کند. تبدیل بازگشت به خط جدید در ورودی را غیرفعال می‌کند، و تبدیل سطح پایین خط جدید به خط جدید/بازگشت در خروجی را غیرفعال می‌کند (اما این موضوع رفتار addch('\n') را تغییر نمی‌دهد، که همواره معادل بازگشت و پیشروی خط را روی صفحه‌ی مجازی انجام می‌دهد). با غیرفعال بودن تبدیل، curses گاهی می‌تواند کمی سرعت حرکت عمودی را افزایش دهد؛ همچنین، قادر خواهد بود کلید بازگشت را در ورودی تشخیص دهد.

curses.intrflush(flag)¶: اگر flag برابر True باشد، فشردن یک کلید وقفه (وقفه، قطع یا خروج) تمام خروجی موجود در صف راه‌انداز پایانه را تخلیه می‌کند. اگر flag برابر False باشد، هیچ تخلیه‌ای انجام نمی‌شود.

curses.qiflush([flag])¶: اگر flag برابر False باشد، نتیجه همانند فراخوانی noqiflush() است. اگر flag برابر True باشد، یا آرگومانی ارائه نشود، صف‌ها هنگام خوانده شدن این نویسه‌های کنترلی تخلیه می‌شوند.

curses.noqiflush()¶: وقتی از روال noqiflush() استفاده می‌شود، تخلیه‌ی عادی صف‌های ورودی و خروجی مرتبط با نویسه‌های INTR، QUIT و SUSP انجام نخواهد شد. ممکن است بخواهید noqiflush() را در یک هندلر سیگنال فراخوانی کنید، اگر می‌خواهید پس از خروج هندلر، خروجی همان‌طور ادامه یابد که گویی وقفه‌ای رخ نداده است.

curses.typeahead(fd)¶

مشخص می‌کند که توصیف‌گر پرونده fd برای بررسی پیش‌تایپ (typeahead) به کار رود. اگر fd -1 باشد، هیچ‌گونه بررسی پیش‌تایپ (typeahead) انجام نمی‌شود.

The curses library does "line-breakout optimization" by looking for typeahead periodically while updating the screen. If input is found, and it is coming from a tty, the current update is postponed until refresh() or doupdate() is called again, allowing faster response to commands typed in advance. This function allows specifying a different file descriptor for typeahead checking.

curses.is_cbreak()¶: Return True if cbreak mode (see cbreak()) is enabled, False otherwise. Availability: ncurses 6.5 or later.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.is_echo()¶: Return True if echo mode (see echo()) is enabled, False otherwise. Availability: ncurses 6.5 or later.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.is_nl()¶: Return True if nl mode (see nl()) is enabled, False otherwise. Availability: ncurses 6.5 or later.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.is_raw()¶: Return True if raw mode (see raw()) is enabled, False otherwise. Availability: ncurses 6.5 or later.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

Keyboard input¶

curses.ungetch(ch)¶

Push ch so the next getch() or get_wch() will return it.

ch may be an integer (a key code or the code of an encoded byte), a byte, or a string of length 1. A one-character string is pushed like unget_wch(); on a narrow build it must encode to a single byte.

توجه

تنها یک ch را می‌توان پیش از فراخوانی getch() پوش کرد (push).

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): A one-character string argument is no longer required to encode to a single byte, except on a narrow build.

curses.unget_wch(ch)¶

ch را فشار دهید تا get_wch() بعدی آن را برگرداند.

ch می‌تواند یک عدد صحیح (یک کد نویسه، نه کد کلید) یا یک رشته با طول 1 باشد.

توجه

تنها یک ch را می‌توان پیش از فراخوانی get_wch() فشار داد.

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

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Also available on a narrow build, where ch must encode to a single byte (an 8-bit locale).

curses.flushinp()¶: تمام بافرهای ورودی را تخلیه می‌کند. این کار هرگونه پیش‌تایپ (typeahead) را که کاربر تایپ کرده است و برنامه هنوز آن را پردازش نکرده است، دور می‌ریزد.

curses.has_key(ch)¶: مقدار کلید ch را می‌گیرد و اگر نوع پایانه‌ی جاری کلیدی با آن مقدار را بشناسد، True را برمی‌گرداند.

curses.keyname(k)¶

نام کلید با شماره‌ی k را به‌عنوان یک شیء bytes برمی‌گرداند. نام کلیدی که یک نویسه‌ی ASCII قابل‌چاپ تولید می‌کند، همان نویسه‌ی کلید است. نام یک ترکیب کلید کنترل، یک شیء bytes دو بایتی است که از یک نویسه‌ی caret (b'^') و به‌دنبال آن نویسه‌ی ASCII قابل‌چاپ متناظر تشکیل شده است. نام یک ترکیب کلید Alt (۱۲۸--۲۵۵) یک شیء bytes است که از پیشوند b'M-' و به‌دنبال آن نام نویسه‌ی ASCII متناظر تشکیل شده است.

اگر k منفی باشد، یک ValueError پرتاب می‌کند.

curses.define_key(definition, keycode)¶

Define an escape sequence definition, a string, as a key that generates the key code keycode, so that curses interprets it like one of the keys predefined in the terminal database.

If definition is None, any existing binding for keycode is removed. If keycode is zero or negative, any existing binding for definition is removed.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.key_defined(definition)¶: Return the key code bound to the escape sequence definition, a string, 0 if no key code is bound to it, or -1 if definition is a prefix of a longer bound sequence (and so is ambiguous).

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.keyok(keycode, enable)¶: Enable (if enable is true) or disable (otherwise) interpretation of the key code keycode. Unlike window.keypad(), this affects a single key code rather than all of them.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

Mouse¶

curses.getmouse()¶: پس از اینکه getch() KEY_MOUSE را برای اعلام یک رویداد ماوس برگرداند، باید این متد فراخوانی شود تا رویداد ماوس در صف بازیابی شود؛ این رویداد به‌صورت یک ۵-تایی (id, x, y, z, bstate) نمایش داده می‌شود. id یک مقدار شناسه برای تمایز دستگاه‌های متعدد است، و x، y، z مختصات رویداد هستند. (z در حال حاضر استفاده نشده است.) bstate یک مقدار عدد صحیح است که بیت‌های آن برای نشان دادن نوع رویداد تنظیم خواهند شد و برابر با OR بیتی یک یا چند مورد از ثابت‌های زیر خواهد بود، که در آن n شماره‌ی دکمه از ۱ تا ۵ است: BUTTONn_PRESSED، BUTTONn_RELEASED، BUTTONn_CLICKED، BUTTONn_DOUBLE_CLICKED، BUTTONn_TRIPLE_CLICKED، BUTTON_SHIFT، BUTTON_CTRL، BUTTON_ALT.

تغییر یافته در نسخه‌ی 3.10: ثابت‌های BUTTON5_* اکنون در صورتی که توسط کتابخانه curses زیرین ارائه شده باشند، در دسترس قرار می‌گیرند.

curses.ungetmouse(id, x, y, z, bstate)¶: یک رویداد KEY_MOUSE را به صف ورودی اضافه کنید و داده‌های وضعیت داده‌شده را با آن مرتبط کنید.

curses.mousemask(mousemask)¶: رویدادهای ماوس را برای گزارش‌شدن تنظیم می‌کند و یک تاپل (availmask, oldmask) را برمی‌گرداند. availmask نشان می‌دهد کدام‌یک از رویدادهای تعیین‌شده ماوس می‌توانند گزارش شوند؛ در صورت شکست کامل، 0 برگردانده می‌شود. oldmask مقدار قبلی نقاب رویدادهای ماوس است. اگر این تابع هرگز فراخوانی نشود، هیچ رویداد ماوسی گزارش نخواهد شد.

curses.mouseinterval(interval)¶: حداکثر زمان بر حسب میلی‌ثانیه که می‌تواند بین رویدادهای فشردن و رها کردن سپری شود تا آن‌ها به‌عنوان یک کلیک شناخته شوند را تنظیم می‌کند و مقدار فاصله پیشین را برمی‌گرداند. مقدار پیش‌فرض ۱۶۶ میلی‌ثانیه، یا یک‌ششم ثانیه است. برای دریافت مقدار فاصله بدون تغییر آن، از یک interval منفی استفاده کنید.

curses.has_mouse()¶

Return True if the mouse driver has been successfully initialized.

Availability: if the underlying curses library provides has_mouse().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

رنگ¶

curses.start_color()¶

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

start_color() هشت رنگ پایه (سیاه، قرمز، سبز، زرد، آبی، سرخابی، فیروزه‌ای و سفید) و دو متغیر سراسری در ماژول curses یعنی COLORS و COLOR_PAIRS را مقداردهی اولیه می‌کند که حاوی بیشینه تعداد رنگ‌ها و جفت‌رنگ‌هایی هستند که پایانه می‌تواند پشتیبانی کند. همچنین رنگ‌های پایانه را به مقادیری بازمی‌گرداند که پایانه هنگام روشن شدن داشت.

curses.has_colors()¶: اگر پایانه بتواند رنگ‌ها را نمایش دهد، True را برمی‌گرداند؛ در غیر این صورت، False را برمی‌گرداند.

curses.has_extended_color_support()¶

اگر ماژول از رنگ‌های گسترش‌یافته پشتیبانی کند، True را برمی‌گرداند؛ در غیر این صورت، False را برمی‌گرداند. پشتیبانی از رنگ‌های گسترش‌یافته، بیش از ۲۵۶ جفت‌رنگ را برای پایانه‌هایی که از بیش از ۱۶ رنگ پشتیبانی می‌کنند (برای مثال، xterm-256color) امکان‌پذیر می‌سازد.

پشتیبانی رنگی گسترده به ncurses نسخه 6.1 یا جدیدتر نیاز دارد.

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

curses.can_change_color()¶: برگرداندن True یا False، بسته به اینکه برنامه‌نویس بتواند رنگ‌هایی را که پایانه نمایش می‌دهد تغییر دهد.

curses.init_color(color_number, r, g, b)¶: تعریف یک رنگ را تغییر می‌دهد؛ شماره رنگی که باید تغییر کند و سپس سه مقدار RGB (برای میزان کامپوننت‌های قرمز، سبز و آبی) را دریافت می‌کند. مقدار color_number باید بین 0 و COLORS - 1 باشد. هر یک از r، g و b باید مقداری بین 0 و 1000 باشد. هنگامی که از init_color() استفاده شود، تمام موارد آن رنگ روی صفحه بلافاصله به تعریف جدید تغییر می‌کنند. این تابع در بیشتر پایانه‌ها هیچ عملیاتی انجام نمی‌دهد؛ تنها زمانی فعال است که can_change_color() مقدار True را برگرداند.

curses.color_content(color_number)¶: شدت کامپوننت‌های قرمز، سبز و آبی (RGB) در رنگ color_number را برمی‌گرداند. color_number باید بین 0 و COLORS - 1 باشد. یک تاپل سه‌تایی شامل مقادیر R، G، B برای رنگ داده‌شده برمی‌گرداند؛ این مقادیر بین 0 (بدون کامپوننت) و 1000 (حداکثر مقدار کامپوننت) خواهند بود. اگر رنگ پشتیبانی نشود، یک استثنا پرتاب می‌کند.

curses.init_pair(pair_number, fg, bg)¶: تعریف یک جفت‌رنگ را تغییر می‌دهد. این تابع سه آرگومان دریافت می‌کند: شماره‌ی جفت‌رنگی که باید تغییر کند، شماره‌ی رنگ پیش‌زمینه و شماره‌ی رنگ پس‌زمینه. مقدار pair_number باید بین 1 و COLOR_PAIRS - 1 باشد (جفت‌رنگ 0 فقط با use_default_colors() و assume_default_colors() قابل تغییر است). مقدار آرگومان‌های fg و bg باید بین 0 و COLORS - 1 باشد، یا پس از فراخوانی use_default_colors() یا assume_default_colors()، -1 باشد. اگر جفت‌رنگ پیش‌تر مقداردهی اولیه شده باشد، صفحه تازه‌سازی می‌شود و تمام موارد استفاده از آن جفت‌رنگ به تعریف جدید تغییر می‌کنند.

curses.pair_content(pair_number)¶: یک تاپل (fg, bg) را برمی‌گرداند که شامل رنگ‌های جفت‌رنگ درخواستی است. مقدار pair_number باید بین 0 و COLOR_PAIRS - 1 باشد.

curses.color_pair(pair_number)¶: Return the attribute value for displaying text in the specified color pair. Only color pairs that fit in the color-pair field of the returned value can be represented (usually the first 256); a larger pair_number raises OverflowError rather than being silently masked to a different pair. Use color_set() or attr_set() to display higher pairs. This attribute value can be combined with A_STANDOUT, A_REVERSE, and the other A_* attributes. pair_number() is the counterpart to this function.

curses.pair_number(attr)¶: شماره‌ی جفت‌رنگ تنظیم‌شده با مقدار ویژگی attr را برمی‌گرداند. color_pair() همتای این تابع است.

curses.use_default_colors()¶: معادل assume_default_colors(-1, -1).

curses.assume_default_colors(fg, bg, /)¶

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

رنگ‌های پیش‌فرض پیش‌زمینه/پس‌زمینه پایانه را به شماره‌ی رنگ -1 اختصاص می‌دهد. بنابراین init_pair(x, COLOR_RED, -1) جفت x را به‌صورت قرمز روی پس‌زمینه پیش‌فرض مقداردهی اولیه می‌کند و init_pair(x, -1, COLOR_BLUE) جفت x را به‌صورت پیش‌زمینه پیش‌فرض روی پس‌زمینه آبی مقداردهی اولیه می‌کند.
تعریف جفت‌رنگ 0 را به (fg, bg) تغییر دهید.

این یک افزونه برای ncurses است.

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

curses.alloc_pair(fg, bg)¶

Allocate a color pair for foreground color fg and background color bg, and return its number. If a color pair for the same combination of colors already exists, return its number. Otherwise allocate a new color pair and return its number.

This function is only available if Python was built against a wide-character version of the underlying curses library with extended-color support (see has_extended_color_support()).

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.free_pair(pair_number)¶

Free the color pair pair_number, which must have been allocated by alloc_pair(). The pair must not be in use.

This function is only available if Python was built against a wide-character version of the underlying curses library with extended-color support (see has_extended_color_support()).

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.find_pair(fg, bg)¶

Return the number of a color pair for foreground color fg and background color bg, or -1 if no color pair for this combination of colors has been allocated.

This function is only available if Python was built against a wide-character version of the underlying curses library with extended-color support (see has_extended_color_support()).

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.reset_color_pairs()¶

Discard all color-pair definitions, releasing the color pairs allocated by init_pair() and alloc_pair().

This function is only available if Python was built against a wide-character version of the underlying curses library with extended-color support (see has_extended_color_support()).

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

Windows and pads¶

curses.newwin(nlines, ncols)¶

curses.newwin(nlines, ncols, begin_y, begin_x)

یک پنجره جدید برمی‌گرداند که گوشه‌ی بالا-چپ آن در (begin_y, begin_x) قرار دارد و ارتفاع/عرض آن nlines/ncols است.

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

curses.newpad(nlines, ncols)¶

یک اشاره‌گر به ساختار داده‌ای جدید پد با تعداد سطرهای و ستون‌های داده‌شده ایجاد کرده و برمی‌گرداند. یک پد را به‌عنوان یک شیء پنجره برمی‌گرداند.

یک پد مانند یک پنجره است، با این تفاوت که به اندازه‌ی صفحه‌نمایش محدود نمی‌شود و لزوماً با بخش خاصی از صفحه‌نمایش مرتبط نیست. هنگامی که به یک پنجره‌ی بزرگ نیاز است و تنها بخشی از پنجره در یک زمان روی صفحه‌نمایش قرار می‌گیرد، می‌توان از پدها استفاده کرد. بازسازی خودکار پدها (مانند ناشی از پیمایش یا بازتاب ورودی) رخ نمی‌دهد. متدهای refresh() و noutrefresh() یک پد برای مشخص کردن بخشی از پد که باید نمایش داده شود و مکان روی صفحه‌نمایش که برای نمایش استفاده می‌شود، به ۶ آرگومان نیاز دارند. آرگومان‌ها pminrow، pmincol، sminrow، smincol، smaxrow، smaxcol هستند؛ آرگومان‌های p به گوشه‌ی بالا-چپ ناحیه‌ی پد که باید نمایش داده شود اشاره دارند و آرگومان‌های s یک جعبه‌ی اسلایس (clipping box) روی صفحه‌نمایش تعریف می‌کنند که ناحیه‌ی پد باید درون آن نمایش داده شود.

Soft labels¶

The following functions manage soft-label keys, a row of labels displayed along the bottom line of the screen, typically used to label a row of function keys. slk_init() must be called before initscr() or newterm(); it takes one screen line away from the standard window for the labels.

curses.slk_init(fmt=0)¶

Reserve a screen line for the soft labels and choose their layout. fmt selects the arrangement: 0 for 3-2-3 (eight labels), 1 for 4-4 (eight labels). Where the underlying curses library supports them, 2 gives 4-4-4 (twelve labels) and 3 gives 4-4-4 with an index line.

Must be called before initscr() or newterm(), and affects only the screen created next.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.slk_set(labnum, label, justify)¶: Set the text of soft label number labnum, in the range 1 through 8 (or 12 in a twelve-label layout). justify controls how label is placed within the label: 0 for left, 1 for centered, 2 for right.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.slk_label(labnum)¶: Return the current text of soft label number labnum, justified as it was set, or an empty string if it has no label.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.slk_refresh()¶: Update the soft labels on the physical screen, like refresh() for a window.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.slk_noutrefresh()¶: Update the soft labels on the virtual screen, like window.noutrefresh(). Use it together with doupdate() to batch screen updates.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.slk_clear()¶: Remove the soft labels from the screen.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.slk_restore()¶: Restore the soft labels to the screen after a slk_clear().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.slk_touch()¶: Force all the soft labels to be redrawn by the next slk_refresh() or slk_noutrefresh().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.slk_attron(attr)¶
curses.slk_attroff(attr)¶
curses.slk_attrset(attr)¶: Add, remove, or set the attributes used to display the soft labels, given as packed A_* attributes.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.slk_attr()¶: Return the current attributes of the soft labels as packed A_* attributes. Availability depends on the underlying curses library.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.slk_attr_on(attr)¶
curses.slk_attr_off(attr)¶: Turn the given attributes on or off without affecting any others. Like the attr_* window methods, these work with the WA_* attributes rather than packed A_* attributes.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.slk_attr_set(attr, pair=0)¶: Set the attributes and color pair of the soft labels. attr is given as WA_* attributes and pair as a color pair number.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.slk_color(pair)¶: Set the color pair of the soft labels to color pair number pair.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

Saving and restoring¶

curses.getwin(file)¶: داده‌های مرتبط با پنجره را که در پرونده توسط یک فراخوانی قبلی window.putwin() ذخیره شده‌اند، می‌خواند. سپس این روال با استفاده از آن داده‌ها، پنجره‌ی جدیدی را ایجاد و مقداردهی اولیه می‌کند و شیء پنجره‌ی جدید را برمی‌گرداند. آرگومان file باید یک شیء پرونده باشد که برای خواندن در حالت دودویی باز شده است.

curses.scr_dump(filename)¶: Write the current contents of the virtual screen to filename, which may be a string or a path-like object. The file can later be read by scr_restore(), scr_init() or scr_set(). This is the whole-screen counterpart of window.putwin().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.scr_restore(filename)¶: Set the virtual screen to the contents of filename, which must have been written by scr_dump(). The next call to doupdate() or window.refresh() restores the screen to those contents.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.scr_init(filename)¶: Initialize the assumed contents of the terminal from filename, which must have been written by scr_dump(). Use it when the terminal already displays those contents, for example after another program has drawn the screen, so that curses does not redraw what is already there.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.scr_set(filename)¶: Use filename, which must have been written by scr_dump(), as both the virtual screen and the assumed terminal contents. This combines the effects of scr_restore() and scr_init().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

Querying the terminal¶

curses.baudrate()¶: سرعت خروجی پایانه را بر حسب بیت بر ثانیه برمی‌گرداند. در شبیه‌سازهای نرم‌افزاری پایانه، این سرعت مقدار ثابت بالایی خواهد داشت. به دلایل تاریخی گنجانده شده است؛ در گذشته، برای نوشتن حلقه‌های خروجی جهت تأخیرهای زمانی و گاهی برای تغییر رابط‌ها بسته به سرعت خط استفاده می‌شد.

curses.erasechar()¶: Return the user's current erase character as a raw byte, a bytes object of length 1. See also erasewchar().

curses.erasewchar()¶: Return the user's current erase character as a one-character str. Under Unix operating systems this is a property of the controlling tty of the curses program, and is not set by the curses library itself.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.killchar()¶: Return the user's current line kill character as a raw byte, a bytes object of length 1. See also killwchar().

curses.killwchar()¶: Return the user's current line kill character as a one-character str. Under Unix operating systems this is a property of the controlling tty of the curses program, and is not set by the curses library itself.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.termname()¶: مقدار متغیر محیطی TERM را به‌عنوان یک شیء بایتی برمی‌گرداند، که به ۱۴ نویسه کوتاه شده است.

curses.longname()¶: یک شیء بایتی حاوی فیلد نام بلند terminfo را برمی‌گرداند که پایانه فعلی را توصیف می‌کند. حداکثر طول یک توصیف پرجزئیات ۱۲۸ نویسه است. این فیلد فقط پس از فراخوانی initscr() تعریف می‌شود.

curses.termattrs()¶: یک OR منطقی از تمام ویژگی‌های ویدیویی مورد پشتیبانی پایانه را برمی‌گرداند. این اطلاعات زمانی مفید است که یک برنامه curses به کنترل کامل بر ظاهر صفحه نیاز داشته باشد.

curses.term_attrs()¶: Like termattrs(), but return the attributes as WA_* values rather than A_* values.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.has_ic()¶: اگر پایانه قابلیت‌های درج و حذف نویسه را داشته باشد، True را برمی‌گرداند. این تابع فقط به دلایل تاریخی گنجانده شده است، زیرا همه نرم‌افزارهای شبیه‌ساز پایانه امروزی چنین قابلیت‌هایی دارند.

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

Bell and screen flash¶

curses.beep()¶: یک صدای کوتاه برای جلب توجه پخش می‌کند.

curses.flash()¶: صفحه را چشمک بزنید. یعنی آن را به حالت ویدیوی معکوس (reverse-video) تغییر دهید و سپس در بازه‌ی کوتاهی آن را به حالت پیشین برگردانید. برخی افراد چنین چیزی را به‌عنوان «زنگ قابل مشاهده (visible bell)» به سیگنال جلب توجه شنیداری تولیدشده توسط beep() ترجیح می‌دهند.

Terminal resizing¶

curses.resizeterm(nlines, ncols)¶: اندازه‌ی پنجره‌های استاندارد و جاری را به ابعاد مشخص‌شده تغییر می‌دهد و سایر داده‌های مدیریتی مورد استفاده‌ی کتابخانه‌ی curses را که ابعاد پنجره را ثبت می‌کنند، تنظیم می‌کند (به‌ویژه هندلری SIGWINCH).

curses.resize_term(nlines, ncols)¶: تابع بک‌اند استفاده‌شده توسط resizeterm() که بیشتر کار را انجام می‌دهد؛ هنگام تغییر اندازه پنجره‌ها، resize_term() ناحیه‌هایی را که گسترش می‌یابند با نویسه‌های خالی پر می‌کند. برنامه فراخوان باید این ناحیه‌ها را با داده‌های مناسب پر کند. تابع resize_term() تلاش می‌کند اندازه همه پنجره‌ها را تغییر دهد. با این حال، به دلیل قرارداد فراخوانی پدها (pads)، تغییر اندازه آن‌ها بدون تعامل اضافی با برنامه ممکن نیست.

curses.is_term_resized(nlines, ncols)¶: اگر resize_term() ساختار پنجره را تغییر دهد، True و در غیر این صورت False را برمی‌گرداند.

curses.update_lines_cols()¶: متغیرهای ماژول LINES و COLS را به‌روزرسانی کنید. برای تشخیص تغییر دستی اندازه‌ی صفحه مفید است.

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

Terminfo database¶

curses.setupterm(term=None, fd=-1)¶

پایانه را راه‌اندازی می‌کند. term رشته‌ای است که نام پایانه را مشخص می‌کند، یا None؛ اگر حذف شود یا None باشد، از مقدار متغیر محیطی TERM استفاده خواهد شد. fd توصیف‌گر پرونده‌ای است که هر دنباله‌ی راه‌اندازی به آن فرستاده می‌شود؛ اگر ارائه نشود یا -1 باشد، از توصیف‌گر پرونده برای sys.stdout استفاده خواهد شد.

اگر پایانه پیدا نشود یا ورودی پایگاه داده‌ی terminfo آن خوانده نشود، یک curses.error پرتاب می‌شود. اگر پایانه از قبل راه‌اندازی شده باشد، این تابع هیچ تأثیری ندارد.

توجه

Calling initscr() or newterm() after setupterm() leaks the terminal that setupterm() allocated: the curses library keeps only a single current terminal and does not free the previously allocated one.

curses.tigetflag(capname)¶

مقدار قابلیت بولی متناظر با نام قابلیت capname در terminfo را به‌صورت یک عدد صحیح برمی‌گرداند. اگر capname یک قابلیت بولی نباشد، مقدار -1 و اگر لغو شده یا در توضیح پایانه وجود نداشته باشد، مقدار 0 را برمی‌گرداند.

ابتدا باید setupterm() (یا initscr()) فراخوانی شود.

curses.tigetnum(capname)¶

مقدار قابلیت عددی متناظر با نام قابلیت terminfo به نام capname را به‌صورت عدد صحیح برمی‌گرداند. اگر capname یک قابلیت عددی نباشد، مقدار -2 و اگر لغوشده یا در توصیف پایانه موجود نباشد، مقدار -1 را برمی‌گرداند.

ابتدا باید setupterm() (یا initscr()) فراخوانی شود.

curses.tigetstr(capname)¶

مقدار قابلیت رشته‌ای متناظر با نام قابلیت capname در terminfo را به‌عنوان یک شیء bytes برمی‌گرداند. اگر capname یک «قابلیت رشته‌ای» terminfo نباشد، یا لغو شده باشد یا در توصیف پایانه وجود نداشته باشد، None را برمی‌گرداند.

ابتدا باید setupterm() (یا initscr()) فراخوانی شود.

curses.tparm(str[, ...])¶

شیء بایتی str را با پارامترهای داده شده نمونه‌سازی کنید، جایی که str باید یک رشته‌ی بایتی پارامتره‌یافته شده از پایگاه داده‌ی terminfo باشد. برای مثال، tparm(tigetstr("cup"), 5, 3) می‌تواند منجر به b'\033[6;4H' شود، نتیجه‌ی دقیق بستگی به نوع ترمینال دارد. حداکثر نه پارامتر عدد صحیح می‌تواند داده شود.

ابتدا باید setupterm() (یا initscr()) فراخوانی شود.

curses.putp(str)¶

معادل با tputs(str, 1, putchar) است؛ مقدار یک قابلیت terminfo مشخص، که یک شیء بایتی است، را برای ترمینال جاری صادر می‌کند. توجه داشته باشید که خروجی putp() همیشه به خروجی استاندارد می‌رود.

ابتدا باید setupterm() (یا initscr()) فراخوانی شود.

Utilities¶

curses.unctrl(ch)¶

Return a bytes object which is a printable representation of the character ch; any attributes and color pair are ignored. Control characters are represented as a caret followed by a character, for example as b'^C'. Printing characters are left as they are. The representation of other characters is defined by the underlying curses library.

ch must fit in a single byte; use wunctrl() for other characters.

curses.wunctrl(ch)¶: Return a string which is a printable representation of the character ch; any attributes and color pair are ignored. ASCII control characters are represented as a caret followed by a character, for example as '^C'. Printing characters, including non-ASCII characters printable in the locale, are left as they are. The representation of other characters is defined by the underlying curses library.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.filter()¶: The filter() routine, if used, must be called before initscr() or newterm() is called, and affects every screen created afterwards. The effect is that, during the initialization, LINES is set to 1; the capabilities clear, cup, cud, cud1, cuu1, cuu, vpa are disabled; and the home string is set to the value of cr. The effect is that the cursor is confined to the current line, and so are screen updates. This may be used for enabling character-at-a-time line editing without touching the rest of the screen.

curses.nofilter()¶

Undo the effect of a previous filter() call. Like filter(), it must be called before initscr() (or newterm()) so that the next initialization uses the full screen again.

Availability: if the underlying curses library provides nofilter().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

curses.use_env(flag)¶: If used, this function should be called before initscr() or newterm() are called, and affects every screen created afterwards. When flag is False, the values of lines and columns specified in the terminfo database will be used, even if environment variables LINES and COLUMNS (used by default) are set, or if curses is running in a window (in which case default behavior would be to use the window size if LINES and COLUMNS are not set).

curses.get_escdelay()¶: مقدار تنظیم‌شده توسط set_escdelay() را بازیابی می‌کند.

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

curses.set_escdelay(ms)¶

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

Depending on the curses library, the setting may apply to all screens, not only to the current one.

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

curses.get_tabsize()¶: مقدار تنظیم‌شده توسط set_tabsize() را بازیابی می‌کند.

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

curses.set_tabsize(size)¶

تعداد ستون‌هایی را که کتابخانه curses هنگام تبدیل یک نویسه tab به فاصله‌ها، در زمان افزودن tab به یک پنجره استفاده می‌کند، تنظیم می‌کند.

Depending on the curses library, the setting may apply to all screens, not only to the current one, and creating a screen may reset it.

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

curses.napms(ms)¶: به مدت ms میلی‌ثانیه متوقف میشود.

curses.delay_output(ms)¶: یک مکث ms میلی‌ثانیه‌ای در خروجی درج کنید.

اشیای پنجره¶

class curses.window¶: اشیای پنجره، که توسط initscr() و newwin() در بالا بازگردانده می‌شوند، دارای متدها و ویژگی‌های زیر هستند:

Adding and inserting text¶

window.addch(ch[, attr])¶

window.addch(y, x, ch[, attr])

نویسه‌ی ch را در (y, x) با ویژگی‌های attr ترسیم می‌کند و هر نویسه‌ای را که پیش‌تر در آن مکان ترسیم شده باشد، بازنویسی می‌کند. به‌طور پیش‌فرض، موقعیت نویسه و ویژگی‌ها، تنظیمات جاری شیء پنجره هستند.

ch may be a single character, optionally followed by combining characters, that together occupy one character cell.

توجه

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

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): A character may now be given as a string of a base character followed by combining characters, instead of only a single character, or as a complexchar cell.

window.addstr(str[, attr])¶

window.addstr(y, x, str[, attr])

رشته‌ی نویسه‌ای str را در (y, x) با ویژگی‌های attr ترسیم می‌کند و هر چیزی را که پیش‌تر روی نمایشگر بوده، بازنویسی می‌کند.

str may also be a complexstr, in which case each cell carries its own attributes and color pair, so attr must not be given. A complexstr obtained from in_wchstr() is written back unchanged.

توجه

نوشتن بیرون از پنجره، زیرپنجره یا پد موجب پرتاب curses.error می‌شود. تلاش برای نوشتن در گوشه‌ی پایین سمت راست یک پنجره، زیرپنجره یا پد منجر به پرتاب یک استثنا پس از چاپ رشته می‌شود.
یک اشکال در ncurses، بک‌اند این ماژول پایتون، می‌توانست هنگام تغییر اندازه‌ی پنجره‌ها باعث ایجاد خطاهای قطعه‌بندی حافظه (segfaults) شود. این اشکال در ncurses-6.1-20190511 برطرف شد. اگر مجبور به استفاده از نسخه‌ی قدیمی‌تر ncurses هستید، می‌توانید با خودداری از فراخوانی addstr() با یک str که حاوی نویسه‌های خط جدید داخلی است، از بروز آن جلوگیری کنید؛ در عوض، addstr() را برای هر خط به‌صورت جداگانه فراخوانی کنید.

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): str may now also be a complexstr, as described above.

window.addnstr(str, n[, attr])¶
window.addnstr(y, x, str, n[, attr]): حداکثر n نویسه از رشته‌ی نویسه‌ای str را در (y, x) با ویژگی‌های attr رسم کنید و هر آنچه را که پیش‌تر روی نمایشگر بوده است بازنویسی کنید.

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): str may now also be a complexstr; see addstr().

window.echochar(ch[, attr])¶: نویسه‌ی ch را با ویژگی attr اضافه کنید و بلافاصله refresh() را روی پنجره فراخوانی کنید.

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Wide and combining characters, and complexchar cells, are now accepted.

window.insch(ch[, attr])¶
window.insch(y, x, ch[, attr]): نویسه ch را با ویژگی‌های attr پیش از نویسه زیر مکان‌نما، یا در (y, x) در صورت مشخص بودن، درج می‌کند. تمام نویسه‌های سمت راست مکان‌نما یک موقعیت به راست جابه‌جا می‌شوند و راست‌ترین نویسه خط از بین می‌رود. موقعیت مکان‌نما تغییر نمی‌کند.

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Wide and combining characters, and complexchar cells, are now accepted.

window.insstr(str[, attr])¶

window.insstr(y, x, str[, attr])

یک رشته‌ی نویسه‌ای (به تعداد نویسه‌هایی که در خط جا می‌شوند) پیش از نویسه‌ی زیر مکان‌نما درج می‌شود. همه‌ی نویسه‌های سمت راست مکان‌نما به سمت راست جابه‌جا می‌شوند و راست‌ترین نویسه‌های خط از دست می‌روند. موقعیت مکان‌نما تغییر نمی‌کند (پس از حرکت به y، x، در صورت مشخص بودن).

str may also be a complexstr, in which case each cell carries its own attributes and color pair, so attr must not be given.

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): str may now also be a complexstr, as described above.

window.insnstr(str, n[, attr])¶
window.insnstr(y, x, str, n[, attr]): یک رشته از نویسه‌ها (هر تعداد نویسه که در خط جا شود) را پیش از نویسه‌ی زیر مکان‌نما، تا سقف n نویسه درج کنید. اگر n صفر یا منفی باشد، تمام رشته درج می‌شود. همه‌ی نویسه‌های سمت راست مکان‌نما به سمت راست جابه‌جا می‌شوند و راست‌ترین نویسه‌های خط از دست می‌روند. موقعیت مکان‌نما تغییر نمی‌کند (پس از حرکت به y، x، در صورت مشخص بودن).

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): str may now also be a complexstr; see insstr().

Deleting and inserting lines¶

window.delch([y, x])¶: نویسه‌ی زیر مکان‌نما، یا در (y, x) در صورت مشخص شدن، حذف می‌کند. همه‌ی نویسه‌های سمت راست در همان خط یک موقعیت به چپ جابه‌جا می‌شوند.

window.deleteln()¶: خط زیر مکان‌نما حذف می‌شود. همه‌ی سطرهای بعدی یک خط به بالا جابه‌جا می‌شوند.

window.insertln()¶: یک خط خالی زیر مکان‌نما درج می‌کند. همه‌ی سطرهای بعدی یک خط به پایین جابه‌جا می‌شوند.

window.insdelln(nlines)¶: nlines خط را در پنجره‌ی مشخص‌شده، بالای خط فعلی درج می‌کند. nlines خط پایینی از دست می‌روند. برای nlines منفی، nlines خط را شروع از خط زیر مکان‌نما حذف می‌کند و سطرهای باقی‌مانده را به بالا حرکت می‌دهد. nlines خط پایینی پاک می‌شوند. موقعیت فعلی مکان‌نما بدون تغییر باقی می‌ماند.

Reading input¶

window.getch([y, x])¶

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

یک کلید معمولی به عنوان کد یک بایتِ تکی از کدگذاریِ آن در locale جاری برگردانده می‌شود، بنابراین یک نویسه که با چند بایت کدگذاری شده است، چند فراخوانی می‌طلبد. برای مثال، در یک locale از نوع UTF-8، 'é' به عنوان 195 خوانده می‌شود، سپس 169. برای خواندن آن به عنوان یک نویسه تکی از get_wch() استفاده کنید.

در حالت کی‌پد (به keypad() مراجعه کنید) کلیدهای تابع و سایر کلیدهای ویژه به عنوان یکی از ثابت‌های KEY_* برگردانده می‌شوند، که نمی‌توان آن‌ها را با یک کلید معمولی اشتباه گرفت. در غیر این صورت، یا اگر دنباله‌ی گریز آن‌ها به موقع نرسد (به notimeout() و set_escdelay() مراجعه کنید)، بایت‌های آن‌ها یکی‌یکی برگردانده می‌شوند.

در حالت اکو (به echo() مراجعه کنید) کلید همانند addch() به پنجره اضافه می‌شود؛ کلیدهای ویژه اکو نمی‌شوند.

window.get_wch([y, x])¶

یک فشردنِ کلید را بخوانید، پس از انتقال نشانگر به y، x در صورت تعیین، و آن را به عنوان یک str تک‌نویسه برگردانید. پنجره ابتدا تازه‌سازی می‌شود اگر پد نباشد و از آخرین تازه‌سازی تغییر کرده باشد. تا فشردن یک کلید صبر کنید، یا error را پرتاب کنید اگر خواندن غیرمسدودکننده باشد یا زمان‌به‌حد برسد (به nodelay() و timeout() مراجعه کنید).

در حالت کی‌پد (به keypad() مراجعه کنید) کلیدهای تابع و سایر کلیدهای ویژه به عنوان یکی از ثابت‌های KEY_* برگردانده می‌شوند، یک عدد صحیح. در غیر این صورت، یا اگر دنباله‌ی گریز آن‌ها به موقع نرسد (به notimeout() و set_escdelay() مراجعه کنید)، نویسه‌های آن‌ها یکی‌یکی برگردانده می‌شوند.

در حالت اکو (به echo() مراجعه کنید) کلید همانند addch() به پنجره اضافه می‌شود؛ کلیدهای ویژه اکو نمی‌شوند.

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

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Also available on a narrow build, where only a character representable as a single byte (an 8-bit locale) can be returned.

window.getkey([y, x])¶: یک فشردنِ کلید را همانند getch() بخوانید، اما آن را به عنوان یک str برگردانید: یک کلید معمولی به عنوان یک رشته‌ی تک‌نویسه، بایت رمزگشایی‌شده به عنوان Latin-1، و یک کلید ویژه به عنوان نام آن، مانند 'KEY_UP' (به keyname() مراجعه کنید). اگر ورودی وجود نداشته باشد، به جای برگرداندن -1، error را پرتاب کنید.

window.getstr()¶

window.getstr(n)

window.getstr(y, x)

window.getstr(y, x, n)

یک سطر ورودی را از کاربر بخوانید، با قابلیتِ ابتداییِ ویرایش سطر، پس از انتقال نشانگر به y، x در صورت تعیین. آن را به عنوان یک شیء بایت‌ها برگردانید، در کدگذاریِ locale جاری و بدون کاراکترِ خط‌جداکننده‌ی پایانی. حداکثر n بایت خوانده می‌شود؛ n به پیش‌فرض ۲۰۴۷ است و نمی‌تواند از آن بیشتر باشد.

Use get_wstr() to read the input as a str.

تغییر یافته در نسخه‌ی 3.14: حداکثر مقدار برای n از ۱۰۲۳ به ۲۰۴۷ افزایش یافت.

window.get_wstr()¶

window.get_wstr(n)

window.get_wstr(y, x)

window.get_wstr(y, x, n)

Read a line of input from the user, with primitive line editing capacity, after moving the cursor to y, x if specified. Return it as a str, without the terminating newline. At most n characters are read; n defaults to and cannot exceed 2047.

This is the wide-character variant of getstr().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

window.getdelay()¶: Return the window's read timeout in milliseconds, as set by nodelay() or timeout(): -1 for blocking, 0 for non-blocking, or a positive number of milliseconds.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

Reading window contents¶

window.inch([y, x])¶: Return the character at the given position in the window. The bottom 8 bits are the character proper and the upper bits are the attributes; extract them with the A_CHARTEXT and A_ATTRIBUTES bit-masks, and the color pair with pair_number(). The character byte is the locale-encoded byte of the cell's character, consistent with instr(). It cannot represent a cell holding combining characters, a character that does not fit in a single byte, or a color pair outside the color_pair() range; use in_wch() for those, which returns it as a complexchar.

window.in_wch([y, x])¶: Return the complex character at the given position in the window as a complexchar. Unlike inch(), the returned object carries the cell's text (a spacing character optionally followed by combining characters) together with its attributes and color pair.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

window.instr([n])¶
window.instr(y, x[, n]): Read the text of the window from the current cursor position, or from y, x if specified, to the end of the line or at most n bytes if n is specified, and return it as a bytes object, in the encoding of the current locale. Attributes and color pairs are stripped; use in_wchstr() to read them too. A character not representable in the encoding cannot be returned; use in_wstr() for those.

تغییر یافته در نسخه‌ی 3.14: حداکثر مقدار برای n از ۱۰۲۳ به ۲۰۴۷ افزایش یافت.

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): n is no longer limited to 2047.

window.in_wstr([n])¶

window.in_wstr(y, x[, n])

Read the text of the window from the current cursor position, or from y, x if specified, to the end of the line or at most n characters if n is specified, and return it as a str. Attributes and color pairs are stripped; use in_wchstr() to read them too.

This is the wide-character variant of instr().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

window.in_wchstr([n])¶
window.in_wchstr(y, x[, n]): Read the styled cells of the window from the current cursor position, or from y, x if specified, to the end of the line or at most n cells if n is specified, and return them as a complexstr. Unlike instr() and in_wstr(), each cell keeps its attributes and color pair, so the result can be written back unchanged with addstr().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

Attributes¶

window.attroff(attr)¶: ویژگی attr را از مجموعه «background» اعمال‌شده بر همه نوشتن‌ها در پنجره جاری حذف کنید.

window.attron(attr)¶: ویژگی attr را به مجموعه‌ی «background» اضافه کنید که بر تمام نوشتن‌ها در پنجره‌ی جاری اعمال می‌شود.

window.attrset(attr)¶: مجموعه‌ی ویژگی‌های «پس‌زمینه» را روی attr تنظیم کنید. این مجموعه در ابتدا 0 است (بدون ویژگی).

window.attr_get()¶

Return the window's current rendition as a (attrs, pair) tuple, where attrs is the set of attributes and pair is the color pair number.

Unlike attron() and friends, which take packed A_* attributes, this method and the other attr_* methods work with the WA_* attributes and keep the color pair as a separate number, which lets them use color pairs that do not fit alongside the attributes in a single value.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

window.attr_set(attr, pair=0)¶: Set the window's rendition to the attributes attr and the color pair pair.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

window.attr_on(attr)¶: Turn on the attributes attr without affecting any others.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

window.attr_off(attr)¶: Turn off the attributes attr without affecting any others.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

window.color_set(pair)¶: Set the window's color pair to pair, leaving the other attributes unchanged.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

window.getattrs()¶: Return the window's current attributes.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

window.standout()¶: ویژگی A_STANDOUT را روشن کنید.

window.standend()¶: ویژگی standout را خاموش کنید. در برخی پایانه‌ها، این کار به‌عنوان اثر جانبی، تمام ویژگی‌ها را خاموش می‌کند.

window.chgat(attr)¶
window.chgat(num, attr)
window.chgat(y, x, attr)
window.chgat(y, x, num, attr): ویژگی‌های num نویسه را در موقعیت فعلی مکان‌نما، یا در موقعیت (y, x) در صورت ارائه شدن، تنظیم می‌کند. اگر num داده نشده باشد یا -1 باشد، ویژگی برای تمام نویسه‌ها تا پایان خط تنظیم خواهد شد. این تابع مکان‌نما را در صورت ارائه شدن به موقعیت (y, x) منتقل می‌کند. خط تغییرکرده با استفاده از متد touchline() علامت‌گذاری می‌شود تا محتویات در بازخوانی بعدی پنجره دوباره نمایش داده شوند.

Background¶

window.bkgd(ch[, attr])¶

ویژگی پس‌زمینه‌ی پنجره را روی نویسه‌ی ch، با صفت‌های attr تنظیم کنید. سپس این تغییر روی همه‌ی موقعیت‌های نویسه در آن پنجره اعمال می‌شود:

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

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Wide and combining characters, and complexchar cells, are now accepted.

window.bkgdset(ch[, attr])¶: پس‌زمینه پنجره را تنظیم کنید. پس‌زمینه یک پنجره از یک نویسه و هر ترکیبی از ویژگی‌ها تشکیل شده است. بخش ویژگی پس‌زمینه با تمام نویسه‌های غیرخالی که در پنجره نوشته می‌شوند، ترکیب (OR) می‌شود. هر دو بخش نویسه و ویژگی پس‌زمینه با نویسه‌های خالی ترکیب می‌شوند. پس‌زمینه به یک خصوصیت نویسه تبدیل می‌شود و همراه با نویسه در هر عملیات پیمایش و درج/حذف خط/نویسه جابه‌جا می‌شود.

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Wide and combining characters, and complexchar cells, are now accepted.

window.getbkgd()¶: Return the given window's current background character/attribute pair. Its components can be extracted like those of inch(). It cannot represent a background set with a wide character or with a color pair outside the color_pair() range; use getbkgrnd() for those.

window.getbkgrnd()¶: Return the given window's current background as a complexchar. Unlike getbkgd(), the returned object carries the background character together with its attributes and color pair, and the color pair is not limited to the value that fits in a color_pair().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

Clearing and erasing¶

window.erase()¶: پنجره را پاک کنید.

window.clear()¶: مانند erase()، اما باعث می‌شود در فراخوانی بعدی refresh()، کل پنجره دوباره ترسیم شود.

window.clrtobot()¶: پاک کردن از مکان‌نما تا انتهای پنجره: همه سطرهای زیر مکان‌نما حذف می‌شوند، سپس معادل clrtoeol() اجرا می‌شود.

window.clrtoeol()¶: از مکان‌نما تا انتهای خط را پاک می‌کند.

Borders and lines¶

window.border([ls[, rs[, ts[, bs[, tl[, tr[, bl[, br]]]]]]]])¶

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

توجه

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

پارامتر	توضیحات	مقدار پیش‌فرض	Wide default value
ls	سمت چپ	`ACS_VLINE`	`WACS_VLINE`
rs	سمت راست	`ACS_VLINE`	`WACS_VLINE`
ts	بالا	`ACS_HLINE`	`WACS_HLINE`
bs	پایین	`ACS_HLINE`	`WACS_HLINE`
tl	گوشه‌ی بالا-چپ	`ACS_ULCORNER`	`WACS_ULCORNER`
tr	گوشه‌ی بالا-راست	`ACS_URCORNER`	`WACS_URCORNER`
bl	گوشه پایین چپ	`ACS_LLCORNER`	`WACS_LLCORNER`
br	گوشه پایین-راست	`ACS_LRCORNER`	`WACS_LRCORNER`

The wide default value is used when the border is drawn from string characters or complexchar cells.

If any parameter is a byte character or an integer other than 0, the border is drawn from byte characters, and every string character must be encodable as a single byte.

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Wide and combining characters, and complexchar cells, are now accepted. A single call cannot mix complexchar cells with integer or byte characters.

window.box([vertch, horch])¶: مشابه border()، اما هر دو ls و rs برابر با vertch و هر دو ts و bs برابر با horch هستند. این تابع همیشه از نویسه‌های گوشه پیش‌فرض استفاده می‌کند.

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Wide and combining characters, and complexchar cells, are now accepted. A single call cannot mix complexchar cells with integer or byte characters.

window.hline(ch, n[, attr])¶
window.hline(y, x, ch, n[, attr]): یک خط افقی را نمایش می‌دهد که از (y, x) آغاز می‌شود، به طول n است و از نویسه ch با ویژگی‌های attr تشکیل شده است. اگر کمتر از n خانه در دسترس باشد، خط در لبه‌ی راست پنجره متوقف می‌شود.

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Wide and combining characters, and complexchar cells, are now accepted.

window.vline(ch, n[, attr])¶
window.vline(y, x, ch, n[, attr]): یک خط عمودی را از (y, x) با طول n نمایش می‌دهد که از نویسه‌ی ch با ویژگی‌های attr تشکیل شده است.

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Wide and combining characters, and complexchar cells, are now accepted.

Cursor position and window geometry¶

window.move(new_y, new_x)¶: مکان‌نما را به (new_y, new_x) حرکت دهید.

window.getyx()¶: یک تاپل (y, x) از موقعیت فعلی مکان‌نما نسبت به گوشه‌ی بالا-چپ پنجره برمی‌گرداند.

window.getbegyx()¶: یک تاپل (y, x) از مختصات گوشه‌ی بالا سمت چپ برمی‌گرداند.

window.getmaxyx()¶: یک تاپل (y, x) شامل ارتفاع و عرض پنجره برمی‌گرداند.

window.getparyx()¶: مختصات آغازین این پنجره را نسبت به پنجره والد آن به‌صورت یک تاپل (y, x) برمی‌گرداند. اگر این پنجره والدی نداشته باشد، (-1, -1) را برمی‌گرداند.

window.getparent()¶: Return the parent window of this subwindow, or None if this window is not a subwindow.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

Creating and resizing windows¶

window.subwin(begin_y, begin_x)¶

window.subwin(nlines, ncols, begin_y, begin_x)

یک زیرپنجره را برمی‌گرداند که گوشه‌ی بالا-چپ آن در مختصات نسبت به صفحه‌ی نمایش (begin_y, begin_x) قرار دارد و عرض/ارتفاع آن ncols/nlines است.

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

window.derwin(begin_y, begin_x)¶
window.derwin(nlines, ncols, begin_y, begin_x): derwin() که مخفف «derive window» است، همانند فراخوانی subwin() است، با این تفاوت که begin_y و begin_x نسبت به مبدأ پنجره هستند، نه نسبت به کل صفحه‌نمایش. یک شیء پنجره برای پنجره مشتق‌شده برمی‌گرداند.

window.subpad(begin_y, begin_x)¶
window.subpad(nlines, ncols, begin_y, begin_x): یک زیرپد (sub-pad) برمی‌گرداند که گوشه‌ی بالا-چپ آن در (begin_y, begin_x) قرار دارد و عرض/ارتفاع آن ncols/nlines است. مختصات نسبت به پد والد است (برخلاف subwin()، که از مختصات صفحه استفاده می‌کند). این متد فقط برای پدهای ایجادشده با newpad() در دسترس است.

window.dupwin()¶: Return a new window that is an exact duplicate of the window: it has the same size, position, contents and attributes. Unlike a window created by subwin() or derwin(), the duplicate is independent of the original -- it has its own cell buffer, so later changes to one do not affect the other.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

window.mvwin(new_y, new_x)¶

پنجره را جابه‌جا کنید تا گوشه‌ی بالا-چپ آن در (new_y, new_x) قرار گیرد.

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

window.mvderwin(y, x)¶: پنجره را درون پنجره‌ی والد آن جابه‌جا کنید. پارامترهای پنجره نسبت به صفحه‌ی نمایش تغییر داده نمی‌شوند. این رویه برای نمایش بخش‌های مختلف پنجره‌ی والد در یک موقعیت فیزیکی یکسان روی صفحه‌ی نمایش استفاده می‌شود.

window.resize(nlines, ncols)¶: فضای ذخیره‌سازی برای یک پنجره curses را دوباره تخصیص می‌دهد تا ابعاد آن با مقادیر مشخص‌شده تنظیم شود. اگر هر یک از ابعاد بزرگ‌تر از مقادیر فعلی باشد، داده‌های پنجره با نویسه‌های خالی پر می‌شوند که جلوه پس‌زمینه فعلی (که با bkgdset() تنظیم شده است) در آن‌ها ادغام شده است.

Refreshing and redrawing¶

window.refresh([pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol])¶

نمایش را بلافاصله به‌روزرسانی کنید (صفحه واقعی را با متدهای قبلی ترسیم/حذف همگام‌سازی کنید).

این ۶ آرگومان فقط زمانی می‌توانند مشخص شوند، و در آن صورت الزامی هستند، که پنجره یک پد باشد که با newpad() ایجاد شده است. پارامترهای اضافی برای مشخص‌کردن اینکه چه بخشی از پد و صفحه درگیر است، لازم هستند. pminrow و pmincol گوشه‌ی بالا سمت چپ مستطیلی را که باید در پد نمایش داده شود مشخص می‌کنند. sminrow، smincol، smaxrow و smaxcol لبه‌های مستطیلی را که باید روی صفحه نمایش داده شود مشخص می‌کنند. گوشه‌ی پایین سمت راست مستطیلی که باید در پد نمایش داده شود، از مختصات صفحه محاسبه می‌شود، زیرا اندازه‌ی مستطیل‌ها باید یکسان باشد. هر دو مستطیل باید به‌طور کامل درون ساختارهای مربوط به خود قرار داشته باشند. مقادیر منفی pminrow، pmincol، sminrow یا smincol به‌عنوان صفر در نظر گرفته می‌شوند.

window.noutrefresh()¶

window.noutrefresh(pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol)

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

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

window.redrawln(beg, num)¶: نشان می‌دهد که num خط از سطرهای صفحه، که از خط beg شروع می‌شوند، آسیب‌دیده‌اند و باید در فراخوانی بعدی refresh() به‌طور کامل بازترسیم شوند.

window.redrawwin()¶: کل پنجره را لمس (touch) کنید؛ این کار باعث می‌شود در فراخوانی بعدی refresh() به‌طور کامل بازترسیم شود.

Output options¶

window.clearok(flag)¶: اگر flag برابر True باشد، فراخوانی بعدی refresh() پنجره را به‌طور کامل پاک می‌کند.

window.idlok(flag)¶: اگر flag برابر True باشد، curses تلاش می‌کند از امکانات سخت‌افزاری ویرایش خط استفاده کند. در غیر این صورت، curses از آن‌ها استفاده نخواهد کرد.

window.idcok(flag)¶: اگر flag برابر False باشد، curses دیگر استفاده از قابلیت سخت‌افزاری درج/حذف نویسه پایانه را در نظر نمی‌گیرد؛ اگر flag برابر True باشد، استفاده از درج و حذف نویسه فعال می‌شود. هنگامی که curses برای نخستین بار مقداردهی اولیه می‌شود، استفاده از درج/حذف نویسه به‌طور پیش‌فرض فعال است.

window.immedok(flag)¶: اگر flag برابر True باشد، هر تغییری در تصویر پنجره به‌طور خودکار باعث تازه‌سازی پنجره می‌شود؛ دیگر نیازی نیست خودتان refresh() را فراخوانی کنید. با این حال، ممکن است به دلیل فراخوانی‌های مکرر wrefresh، کارایی را به‌طور قابل‌توجهی کاهش دهد. این گزینه به‌طور پیش‌فرض غیرفعال است.

window.leaveok(flag)¶

اگر flag برابر True باشد، مکان‌نما هنگام به‌روزرسانی در همان جای خود باقی می‌ماند، به جای آنکه در «موقعیت مکان‌نما» قرار گیرد. این کار حرکت مکان‌نما را تا حد ممکن کاهش می‌دهد.

اگر flag برابر False باشد، مکان‌نما پس از یک به‌روزرسانی همیشه در «موقعیت مکان‌نما» خواهد بود.

window.scrollok(flag)¶: کنترل کنید که وقتی مکان‌نمای یک پنجره از لبه‌ی پنجره یا ناحیه‌ی پیمایش خارج می‌شود، چه اتفاقی رخ می‌دهد؛ خواه در نتیجه‌ی یک عمل خط جدید روی خط پایین، خواه با تایپ آخرین نویسه‌ی خط آخر. اگر flag برابر False باشد، مکان‌نما روی خط پایین باقی می‌ماند. اگر flag برابر True باشد، پنجره یک خط به بالا پیمایش می‌شود. توجه داشته باشید که برای دریافت اثر پیمایش فیزیکی روی پایانه، لازم است idlok() نیز فراخوانی شود.

window.scroll([lines=1])¶: صفحه یا ناحیه‌ی پیمایش را پیمایش می‌کند. اگر lines مثبت باشد، به اندازه‌ی lines خط به بالا پیمایش می‌شود و اگر منفی باشد، به پایین پیمایش می‌شود. پیمایش هیچ اثری ندارد مگر اینکه با scrollok() برای پنجره فعال شده باشد.

window.setscrreg(top, bottom)¶: ناحیه‌ی پیمایش را از خط top تا خط bottom تنظیم کنید. تمام عملیات‌های پیمایش در این ناحیه انجام خواهند شد.

window.getscrreg()¶: Return a tuple (top, bottom) of the window's current scrolling region, as set by setscrreg().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

window.syncok(flag)¶: اگر flag برابر True باشد، syncup() به‌طور خودکار هر زمان که تغییری در پنجره وجود داشته باشد فراخوانی می‌شود.

Input options¶

window.keypad(flag)¶: اگر flag برابر True باشد، دنباله‌های گریز تولیدشده توسط برخی کلیدها (کی‌پد، کلیدهای تابع) توسط curses تفسیر می‌شوند. اگر flag برابر False باشد، دنباله‌های گریز در جریان ورودی بدون تغییر باقی می‌مانند. حالت کی‌پد به پیش‌فرض غیرفعال است، اما wrapper() آن را برای پنجره‌ی اصلی فعال می‌کند.

window.nodelay(flag)¶: اگر flag برابر True باشد، getch() غیرمسدود خواهد بود.

window.notimeout(flag)¶

اگر flag برابر True باشد، زمان انقضا برای دنباله‌های خنثی‌سازی اعمال نخواهد شد.

اگر flag برابر False باشد، پس از چند میلی‌ثانیه، یک دنباله‌ی گریز (escape sequence) تفسیر نخواهد شد و همان‌گونه که هست در جریان ورودی باقی خواهد ماند.

window.timeout(delay)¶: تنظیم رفتار خواندن مسدودکننده یا غیرمسدودکننده برای پنجره. اگر delay منفی باشد، از خواندن مسدودکننده استفاده می‌شود (که به‌طور نامحدود برای ورودی منتظر می‌ماند). اگر delay صفر باشد، از خواندن غیرمسدودکننده استفاده می‌شود و getch() در صورتی که هیچ ورودی در انتظار نباشد، -1 را برمی‌گرداند. اگر delay مثبت باشد، getch() به مدت delay میلی‌ثانیه مسدود می‌شود و اگر در پایان آن زمان هنوز ورودی وجود نداشته باشد، -1 را برمی‌گرداند.

Overlapping and touch¶

window.overlay(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])¶

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

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

window.overwrite(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])¶

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

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

window.touchline(start, count[, changed])¶: فرض کنید count خط با شروع از خط start تغییر کرده‌اند. اگر changed ارائه شود، مشخص می‌کند که سطرهای متأثر به‌عنوان تغییر یافته علامت‌گذاری شده‌اند (changed=True) یا بدون تغییر علامت‌گذاری شده‌اند (changed=False).

window.touchwin()¶: برای بهینه‌سازی ترسیم، فرض کنید کل پنجره تغییر کرده است.

window.untouchwin()¶: تمام سطرهای پنجره را از آخرین فراخوانی refresh() به‌عنوان بدون تغییر علامت‌گذاری می‌کند.

window.syncup()¶: تمام مکان‌های موجود در نیاکان پنجره را که در پنجره تغییر کرده‌اند، لمس کنید.

window.syncdown()¶: هر موقعیت در پنجره را که در هر یک از پنجره‌های نیاکان آن لمس شده باشد، لمس کنید. این روال توسط refresh() فراخوانی می‌شود، بنابراین تقریباً هرگز نباید لازم باشد آن را به‌صورت دستی فراخوانی کنید.

window.cursyncup()¶: موقعیت فعلی مکان‌نمای همه‌ی نیاکان پنجره را به‌روزرسانی کنید تا موقعیت فعلی مکان‌نمای پنجره منعکس شود.

Coordinate conversion¶

window.enclose(y, x)¶: آزمایش می‌کند که آیا جفت داده‌شده از مختصات سلول‌نویسه‌ای نسبت به صفحه، درون پنجره‌ی داده‌شده قرار دارد یا خیر، و True یا False برمی‌گرداند. این برای تعیین اینکه چه زیرمجموعه‌ای از پنجره‌های صفحه محل یک رویداد ماوس را دربر می‌گیرد، مفید است.

تغییر یافته در نسخه‌ی 3.10: پیش‌تر، به‌جای True یا False، 1 یا 0 را برمی‌گرداند.

window.mouse_trafo(y, x, to_screen)¶

Convert between window-relative and screen-relative (stdscr-relative) character-cell coordinates. If to_screen is true, convert the window-relative coordinates y, x to screen-relative coordinates; otherwise convert in the opposite direction. The two coordinate systems differ when lines are reserved on the screen, for example for soft labels.

Return the converted coordinates as a (y, x) tuple, or None if they lie outside the window.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

Other¶

window.encoding¶: کدگذاری مورد استفاده برای کدگذاری آرگومان‌های رشته‌ای متدها و کدگشایی نتایج آن‌ها در ساخت بدون پشتیبانی از نویسه‌های پهن. ویژگی کدگذاری از پنجره والد هنگام ایجاد یک زیرپنجره ارث می‌شود، برای مثال با window.subwin(). به طور پیش‌فرض، کدگذاری locale جاری استفاده می‌شود (به locale.getencoding() مراجعه کنید).

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

window.putwin(file)¶: تمام داده‌های مرتبط با پنجره را در شیء پرونده ارائه‌شده می‌نویسد. این اطلاعات را می‌توان بعداً با استفاده از تابع getwin() بازیابی کرد.

window.use(func, /, *args, **kwargs)¶

Call func(window, *args, **kwargs) with the lock of the window held, and return its result. This provides automatic protection for the window against concurrent access from another thread.

Availability: if the underlying curses library provides use_window().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

State queries¶

window.is_cleared()¶: Return the current value set by clearok().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

window.is_idcok()¶: Return the current value set by idcok().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

window.is_idlok()¶: Return the current value set by idlok().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

window.is_immedok()¶: Return the current value set by immedok().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

window.is_keypad()¶: Return the current value set by keypad().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

window.is_leaveok()¶: Return the current value set by leaveok().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

window.is_linetouched(line)¶: اگر سطر مشخص‌شده از آخرین فراخوانی refresh() تغییر کرده باشد، True را برمی‌گرداند؛ در غیر این صورت False را برمی‌گرداند. اگر line برای پنجره داده‌شده معتبر نباشد، استثنای curses.error پرتاب می‌شود.

window.is_nodelay()¶: Return the current value set by nodelay().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

window.is_notimeout()¶: Return the current value set by notimeout().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

window.is_pad()¶: Return True if the window is a pad created by newpad().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

window.is_scrollok()¶: Return the current value set by scrollok().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

window.is_subwin()¶: Return True if the window is a subwindow created by subwin() or derwin().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

window.is_syncok()¶: Return the current value set by syncok().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

window.is_wintouched()¶: اگر پنجره‌ی مشخص‌شده از آخرین فراخوانی refresh() تغییر کرده باشد، True را برمی‌گرداند؛ در غیر این صورت False را برمی‌گرداند.

Screen objects¶

class curses.screen¶

A screen object represents a terminal initialized by newterm() (or new_prescr()), in addition to the default screen created by initscr(). Screen objects are returned by those functions; they cannot be instantiated directly.

A screen is freed automatically once it is no longer referenced, either directly or through one of its windows. Each window keeps its screen alive, so a screen remains valid as long as any of its windows does.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

screen.close()¶: Detach the screen's standard window, breaking the reference cycle between them so the screen can be reclaimed promptly instead of waiting for a garbage collection. Afterwards stdscr is None and the window it returned earlier can no longer be used. The screen's resources are released once it and all its windows are no longer referenced.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

screen.stdscr¶: The standard window of the screen, covering the whole terminal, or None for a screen created by new_prescr().

screen.use(func, /, *args, **kwargs)¶

Call func(screen, *args, **kwargs) with the lock of the screen held, and return its result. This provides automatic protection for the screen against concurrent access from another thread.

Availability: if the underlying curses library provides use_screen().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

Complex character objects¶

class curses.complexchar(text, /, attr=0, pair=0)¶

A complex character (or complexchar) is an immutable styled character cell: a spacing character optionally followed by combining characters, together with a set of attributes and a color pair.

text is the cell's text, attr a combination of the WA_* attributes (equivalent to the matching A_* constants), and pair a color pair number. Unlike the packed chtype used by inch() and the A_* methods, the color pair is stored separately and is not limited to the value that fits in a color_pair().

Complex characters are returned by window.in_wch() and window.getbkgrnd(), and are accepted (along with an integer, a byte or a string) by the character-cell methods such as window.addch(), window.insch(), window.bkgd(), window.border(), window.hline() and window.vline(). A complex character already carries its own rendition, so it cannot be combined with an explicit attr argument.

str() returns the cell's text; two complex characters are equal when their text, attributes and color pair all match.

The same code works on both wide- and narrow-character builds. On a narrow build a cell holds a single character (no combining marks) that must encode to one byte in the window's encoding (8-bit locales only), and pair is limited to the value that fits in a color_pair().

attr¶: The attributes of the character cell (read-only).

pair¶: The color pair number of the character cell (read-only).

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

class curses.complexstr(cells[, attr[, pair]])¶

A complex character string (or complexstr) is an immutable sequence of styled character cells -- the string counterpart of complexchar (as str is to a single character).

If cells is a string, it is split into character cells (each a spacing character optionally followed by combining characters), and attr (a combination of the WA_* attributes) and pair (a color pair number), if given, are applied to every cell.

Otherwise cells is an iterable whose items are themselves cells, each a complexchar or a string; each item then carries its own rendition, and attr and pair must be omitted.

It is returned by window.in_wchstr(), and accepted by window.addstr(), addnstr(), insstr() and insnstr(), so a run read from a window can be written back unchanged.

It behaves like an immutable sequence: len(s) is the number of cells, s[i] is the i-th cell as a complexchar, slicing and concatenation produce new complexstr instances, and iterating yields the cells. str() returns the cells' text joined together, and two complex character strings are equal when their cells all match. It is hashable.

To build or edit a run of cells, use an ordinary list of complexchar (or strings); a complexstr is the immutable form returned by a read.

Like complexchar, this type works on both wide- and narrow-character builds, with the same per-cell limitations on a narrow build.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

ثابت‌ها¶

General¶

ماژول curses اعضای داده‌ای زیر را تعریف می‌کند:

curses.ERR¶: برخی از روال‌های curses که عدد صحیحی برمی‌گردانند، مانند getch()، در صورت شکست ERR را برمی‌گردانند.

curses.OK¶: برخی روتین‌های curses که یک عدد صحیح برمی‌گردانند، مانند napms()، در صورت موفقیت OK را برمی‌گردانند.

curses.version¶: یک شیء bytes که نسخه‌ی فعلی ماژول را نشان می‌دهد.

curses.ncurses_version¶

یک تاپل نام‌دار (named tuple) شامل سه کامپوننت از نسخه‌ی کتابخانه‌ی ncurses: major، minor و patch. همه‌ی مقدارها عدد صحیح هستند. همچنین می‌توان به این کامپوننت‌ها با نام دسترسی داشت، بنابراین curses.ncurses_version[0] معادل curses.ncurses_version.major است و به همین ترتیب.

دسترس‌پذیری: اگر از کتابخانه ncurses استفاده شود.

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

curses.COLORS¶: حداکثر تعداد رنگ‌هایی که پایانه می‌تواند از آن‌ها پشتیبانی کند. این مقدار فقط پس از فراخوانی start_color() تعریف می‌شود.

curses.COLOR_PAIRS¶: حداکثر تعداد جفت‌های رنگی که پایانه می‌تواند از آن‌ها پشتیبانی کند. این مقدار فقط پس از فراخوانی start_color() تعریف می‌شود.

curses.COLS¶: عرض صفحه، یعنی تعداد ستون‌ها. این مقدار فقط پس از فراخوانی initscr() تعریف می‌شود. توسط update_lines_cols()، resizeterm() و resize_term() به‌روزرسانی می‌شود.

curses.LINES¶: ارتفاع صفحه، یعنی تعداد سطرهای. این مقدار تنها پس از فراخوانی initscr() تعریف می‌شود. توسط update_lines_cols()، resizeterm() و resize_term() به‌روزرسانی می‌شود.

Attributes¶

برخی ثابت‌ها برای تعیین ویژگی‌های سلول نویسه در دسترس هستند. ثابت‌های دقیقی که در دسترس هستند، به سیستم وابسته‌اند.

ویژگی	Wide attribute	معنی
curses.A_ALTCHARSET¶	curses.WA_ALTCHARSET¶	حالت مجموعه‌نویسه‌ی جایگزین
curses.A_BLINK¶	curses.WA_BLINK¶	حالت چشمک‌زن
curses.A_BOLD¶	curses.WA_BOLD¶	حالت پررنگ
curses.A_DIM¶	curses.WA_DIM¶	حالت کم‌نور
curses.A_INVIS¶	curses.WA_INVIS¶	حالت نامرئی یا خالی
curses.A_ITALIC¶	curses.WA_ITALIC¶	حالت کج
curses.A_NORMAL¶	curses.WA_NORMAL¶	ویژگی عادی
curses.A_PROTECT¶	curses.WA_PROTECT¶	حالت محافظت‌شده
curses.A_REVERSE¶	curses.WA_REVERSE¶	معکوس کردن رنگ‌های پس‌زمینه و پیش‌زمینه
curses.A_STANDOUT¶	curses.WA_STANDOUT¶	حالت برجسته (Standout mode)
curses.A_UNDERLINE¶	curses.WA_UNDERLINE¶	حالت زیرخط
curses.A_HORIZONTAL¶	curses.WA_HORIZONTAL¶	برجسته‌سازی افقی
curses.A_LEFT¶	curses.WA_LEFT¶	برجسته‌سازی سمت چپ
curses.A_LOW¶	curses.WA_LOW¶	برجسته‌سازی کم
curses.A_RIGHT¶	curses.WA_RIGHT¶	برجسته‌سازی راست
curses.A_TOP¶	curses.WA_TOP¶	برجسته‌سازی بالا
curses.A_VERTICAL¶	curses.WA_VERTICAL¶	برجسته‌سازی عمودی

اضافه شده در نسخه‌ی 3.7: A_ITALIC افزوده شد.

The attr_get(), attr_set(), attr_on() and attr_off() methods use the parallel set of WA_* constants listed above. Each has the same meaning as the corresponding A_* attribute (WA_BOLD like A_BOLD, and so on), but belongs to the attr_t type rather than being packed into a character. In ncurses the two sets share the same values, but other curses implementations may give them different ones, so use the WA_* constants with the attr_* methods.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased): The WA_* constants were added.

چندین ثابت برای استخراج ویژگی‌های متناظری که توسط برخی متدها برگردانده می‌شوند، در دسترس هستند.

نقاب بیتی	Wide bit-mask	معنی
curses.A_ATTRIBUTES¶	curses.WA_ATTRIBUTES¶	نقاب بیتی (bit-mask) برای استخراج ویژگی‌ها
curses.A_CHARTEXT¶		نقاب بیتی برای استخراج یک نویسه
curses.A_COLOR¶		نقاب بیتی (bit-mask) برای استخراج اطلاعات فیلد جفت‌رنگ

Keys¶

کلیدها با ثابت‌های عدد صحیح با نام‌هایی که با KEY_ آغاز می‌شوند، ارجاع داده می‌شوند. کلیدهای دقیق موجود، به سیستم وابسته‌اند.

ثابت کلید	کلید
curses.KEY_MIN¶	کمینه مقدار کلید
curses.KEY_BREAK¶	کلید Break (غیرقابل‌اعتماد)
curses.KEY_DOWN¶	فلش پایین
curses.KEY_UP¶	فلش بالا
curses.KEY_LEFT¶	پیکان چپ
curses.KEY_RIGHT¶	فلش راست
curses.KEY_HOME¶	کلید Home (فلش بالا+چپ)
curses.KEY_BACKSPACE¶	پس‌بر (غیرقابل‌اطمینان)
curses.KEY_F0¶	کلیدهای تابعی. تا ۶۴ کلید تابعی پشتیبانی می‌شود.
curses.KEY_Fn¶	مقدار کلید تابعی n
curses.KEY_DL¶	حذف خط
curses.KEY_IL¶	درج خط
curses.KEY_DC¶	نویسه‌ی حذف
curses.KEY_IC¶	درج نویسه یا ورود به حالت درج
curses.KEY_EIC¶	خروج از حالت درج نویسه
curses.KEY_CLEAR¶	پاک‌کردن صفحه
curses.KEY_EOS¶	پاک کردن تا انتهای صفحه
curses.KEY_EOL¶	پاک‌سازی تا انتهای خط
curses.KEY_SF¶	پیمایش ۱ خط به جلو
curses.KEY_SR¶	پیمایش ۱ خط به عقب (معکوس)
curses.KEY_NPAGE¶	صفحه بعدی
curses.KEY_PPAGE¶	صفحه قبلی
curses.KEY_STAB¶	تنظیم زبانه
curses.KEY_CTAB¶	پاک‌کردن زبانه
curses.KEY_CATAB¶	پاک کردن همه زبانه‌ها
curses.KEY_ENTER¶	Enter یا ارسال (غیرقابل‌اعتماد)
curses.KEY_SRESET¶	بازنشانی نرم (جزئی) (غیرقابل‌اطمینان)
curses.KEY_RESET¶	بازنشانی یا بازنشانی سخت (غیرقابل‌اطمینان)
curses.KEY_PRINT¶	چاپ
curses.KEY_LL¶	Home down یا bottom (پایین سمت چپ)
curses.KEY_A1¶	بالا سمت چپ صفحه‌کلید
curses.KEY_A3¶	بالا سمت راست صفحه‌کلید
curses.KEY_B2¶	مرکز صفحه‌کلید عددی
curses.KEY_C1¶	پایین سمت چپ صفحه‌کلید عددی
curses.KEY_C3¶	پایین سمت راست صفحه‌کلید عددی
curses.KEY_BTAB¶	تب معکوس (Back tab)
curses.KEY_BEG¶	Beg (آغاز)
curses.KEY_CANCEL¶	لغو
curses.KEY_CLOSE¶	بستن
curses.KEY_COMMAND¶	Cmd (فرمان)
curses.KEY_COPY¶	کپی
curses.KEY_CREATE¶	ایجاد
curses.KEY_END¶	پایان
curses.KEY_EXIT¶	خروج
curses.KEY_FIND¶	یافتن
curses.KEY_HELP¶	راهنما
curses.KEY_MARK¶	نشانه
curses.KEY_MESSAGE¶	پیام
curses.KEY_MOVE¶	انتقال
curses.KEY_NEXT¶	بعدی
curses.KEY_OPEN¶	باز کردن
curses.KEY_OPTIONS¶	گزینه‌ها
curses.KEY_PREVIOUS¶	قبلی (پیشین)
curses.KEY_REDO¶	بازانجام
curses.KEY_REFERENCE¶	مرجع (reference)
curses.KEY_REFRESH¶	تازه‌سازی
curses.KEY_REPLACE¶	جایگزینی
curses.KEY_RESTART¶	راه‌اندازی مجدد
curses.KEY_RESUME¶	از سرگیری
curses.KEY_SAVE¶	ذخیره
curses.KEY_SBEG¶	آغاز شیفت‌شده (Beg)
curses.KEY_SCANCEL¶	لغو با Shift
curses.KEY_SCOMMAND¶	Command همراه با Shift
curses.KEY_SCOPY¶	کپی شیفت‌شده
curses.KEY_SCREATE¶	ایجاد با شیفت
curses.KEY_SDC¶	حذف نویسه با Shift
curses.KEY_SDL¶	حذف خط با Shift
curses.KEY_SELECT¶	انتخاب
curses.KEY_SEND¶	End شیفت‌شده
curses.KEY_SEOL¶	پاک‌کردن خط با Shift
curses.KEY_SEXIT¶	خروج شیفت‌شده
curses.KEY_SFIND¶	جستجوی Shiftدار
curses.KEY_SHELP¶	راهنمای شیفت‌شده
curses.KEY_SHOME¶	Home با Shift
curses.KEY_SIC¶	ورودی شیفت‌شده
curses.KEY_SLEFT¶	پیکان چپ همراه با Shift
curses.KEY_SMESSAGE¶	پیام شیفت‌شده
curses.KEY_SMOVE¶	جابه‌جایی شیفت‌شده
curses.KEY_SNEXT¶	بعدی شیفت‌شده
curses.KEY_SOPTIONS¶	گزینه‌های شیفت‌شده
curses.KEY_SPREVIOUS¶	شیفت‌شده‌ی قبلی
curses.KEY_SPRINT¶	چاپ شیفت‌شده
curses.KEY_SREDO¶	انجام دوباره با Shift
curses.KEY_SREPLACE¶	جایگزینی با Shift
curses.KEY_SRIGHT¶	پیکان راست شیفت‌شده
curses.KEY_SRSUME¶	ازسرگیری شیفت‌شده
curses.KEY_SSAVE¶	ذخیره با Shift
curses.KEY_SSUSPEND¶	تعلیق شیفت‌شده
curses.KEY_SUNDO¶	واگرد شیفت‌شده (Shifted Undo)
curses.KEY_SUSPEND¶	تعلیق
curses.KEY_UNDO¶	واگرد
curses.KEY_MOUSE¶	رویداد ماوس رخ داده است
curses.KEY_RESIZE¶	رویداد تغییر اندازه‌ی پایانه
curses.KEY_MAX¶	حداکثر مقدار کلید

در پایانه‌های VT100 و شبیه‌سازی‌های نرم‌افزاری آن‌ها، مانند شبیه‌سازهای پایانه X، معمولاً حداقل چهار کلید تابع (KEY_F1، KEY_F2، KEY_F3، KEY_F4) در دسترس هستند و کلیدهای جهت به‌شکل بدیهی به KEY_UP، KEY_DOWN، KEY_LEFT و KEY_RIGHT نگاشته شده‌اند. اگر رایانه شما صفحه‌کلید PC دارد، می‌توانید با اطمینان انتظار داشته باشید که کلیدهای جهت و دوازده کلید تابع وجود داشته باشند (صفحه‌کلیدهای قدیمی PC ممکن است تنها ده کلید تابع داشته باشند)؛ همچنین، نگاشت‌های صفحه‌کلید عددی زیر استاندارد هستند:

کلید	ثابت
`Insert`	KEY_IC
`Delete`	KEY_DC
`Home`	KEY_HOME
`End`	KEY_END
`Page Up`	KEY_PPAGE
`Page Down`	KEY_NPAGE

Alternate character set¶

جدول زیر نویسه‌های مجموعه نویسه جایگزین را فهرست می‌کند. این نویسه‌ها از پایانه VT100 به ارث رسیده‌اند و معمولاً در شبیه‌سازی‌های نرم‌افزاری مانند پایانه‌های X در دسترس خواهند بود. هنگامی که هیچ گرافیکی در دسترس نباشد، curses به یک تقریب خام ASCII قابل‌چاپ برمی‌گردد.

Every character has two names. The ACS_* code is an integer character, restricted to the 8-bit alternate character set of the terminal. The WACS_* code is the same character as a complexchar cell, which is not restricted to the alternate character set.

توجه

These are available only after initscr() has been called. The WACS_* codes are only available if Python is built with wide character support.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased): The WACS_* codes.

کد ACS	WACS code	معنی
curses.ACS_BBSS¶	curses.WACS_BBSS¶	نام جایگزین برای گوشه‌ی بالا سمت راست
curses.ACS_BLOCK¶	curses.WACS_BLOCK¶	بلوک مربعی توپر
curses.ACS_BOARD¶	curses.WACS_BOARD¶	صفحه‌ای از مربع‌ها
curses.ACS_BSBS¶	curses.WACS_BSBS¶	نام جایگزین برای خط افقی
curses.ACS_BSSB¶	curses.WACS_BSSB¶	نام جایگزین برای گوشه‌ی بالا سمت چپ
curses.ACS_BSSS¶	curses.WACS_BSSS¶	نام جایگزین برای T بالایی (top tee)
curses.ACS_BTEE¶	curses.WACS_BTEE¶	tee پایین (bottom tee)
curses.ACS_BULLET¶	curses.WACS_BULLET¶	بولت (bullet)
curses.ACS_CKBOARD¶	curses.WACS_CKBOARD¶	صفحه شطرنجی (stipple)
curses.ACS_DARROW¶	curses.WACS_DARROW¶	فلش رو به پایین
curses.ACS_DEGREE¶	curses.WACS_DEGREE¶	نماد درجه
curses.ACS_DIAMOND¶	curses.WACS_DIAMOND¶	لوزی
curses.ACS_GEQUAL¶	curses.WACS_GEQUAL¶	بزرگ‌تر یا مساوی
curses.ACS_HLINE¶	curses.WACS_HLINE¶	خط افقی
curses.ACS_LANTERN¶	curses.WACS_LANTERN¶	نماد فانوس
curses.ACS_LARROW¶	curses.WACS_LARROW¶	پیکان چپ
curses.ACS_LEQUAL¶	curses.WACS_LEQUAL¶	کمتر یا مساوی
curses.ACS_LLCORNER¶	curses.WACS_LLCORNER¶	گوشه‌ی پایین سمت چپ
curses.ACS_LRCORNER¶	curses.WACS_LRCORNER¶	گوشه‌ی پایین-راست
curses.ACS_LTEE¶	curses.WACS_LTEE¶	تی چپ (left tee)
curses.ACS_NEQUAL¶	curses.WACS_NEQUAL¶	علامت نابرابر
curses.ACS_PI¶	curses.WACS_PI¶	حرف پی
curses.ACS_PLMINUS¶	curses.WACS_PLMINUS¶	علامت مثبت-منفی
curses.ACS_PLUS¶	curses.WACS_PLUS¶	علامت جمع بزرگ
curses.ACS_RARROW¶	curses.WACS_RARROW¶	فلش راست
curses.ACS_RTEE¶	curses.WACS_RTEE¶	تی راست (right tee)
curses.ACS_S1¶	curses.WACS_S1¶	خط پویش ۱
curses.ACS_S3¶	curses.WACS_S3¶	خط پویش ۳
curses.ACS_S7¶	curses.WACS_S7¶	خط پویش ۷
curses.ACS_S9¶	curses.WACS_S9¶	خط پویش ۹
curses.ACS_SBBS¶	curses.WACS_SBBS¶	نام جایگزین برای گوشه پایین راست
curses.ACS_SBSB¶	curses.WACS_SBSB¶	نام جایگزین برای خط عمودی
curses.ACS_SBSS¶	curses.WACS_SBSS¶	نام جایگزین برای right tee
curses.ACS_SSBB¶	curses.WACS_SSBB¶	نام جایگزین برای گوشه‌ی پایین چپ
curses.ACS_SSBS¶	curses.WACS_SSBS¶	نام جایگزین برای tee پایین (bottom tee)
curses.ACS_SSSB¶	curses.WACS_SSSB¶	نام جایگزین برای تی چپ (left tee)
curses.ACS_SSSS¶	curses.WACS_SSSS¶	نام جایگزین برای تقاطع (crossover) یا به‌علاوه‌ی بزرگ (big plus)
curses.ACS_STERLING¶	curses.WACS_STERLING¶	پوند استرلینگ
curses.ACS_TTEE¶	curses.WACS_TTEE¶	top tee
curses.ACS_UARROW¶	curses.WACS_UARROW¶	پیکان بالا
curses.ACS_ULCORNER¶	curses.WACS_ULCORNER¶	گوشه‌ی بالا-چپ
curses.ACS_URCORNER¶	curses.WACS_URCORNER¶	گوشه‌ی بالا-راست
curses.ACS_VLINE¶	curses.WACS_VLINE¶	خط عمودی

The following table lists the double-line and thick-line characters. They have no ACS_* counterpart, and are not provided by every implementation. As in the table above, the alternate name spells out the four sides of the character, clockwise from the top: B for a blank side, S for a single line, D for a double line and T for a thick line.

WACS code	Alternate name	معنی
curses.WACS_D_BTEE¶	curses.WACS_DDBD¶	double-line bottom tee
curses.WACS_D_HLINE¶	curses.WACS_BDBD¶	double-line horizontal line
curses.WACS_D_LLCORNER¶	curses.WACS_DDBB¶	double-line lower-left corner
curses.WACS_D_LRCORNER¶	curses.WACS_DBBD¶	double-line lower-right corner
curses.WACS_D_LTEE¶	curses.WACS_DDDB¶	double-line left tee
curses.WACS_D_PLUS¶	curses.WACS_DDDD¶	double-line big plus sign
curses.WACS_D_RTEE¶	curses.WACS_DBDD¶	double-line right tee
curses.WACS_D_TTEE¶	curses.WACS_BDDD¶	double-line top tee
curses.WACS_D_ULCORNER¶	curses.WACS_BDDB¶	double-line upper-left corner
curses.WACS_D_URCORNER¶	curses.WACS_BBDD¶	double-line upper-right corner
curses.WACS_D_VLINE¶	curses.WACS_DBDB¶	double-line vertical line
curses.WACS_T_BTEE¶	curses.WACS_TTBT¶	thick-line bottom tee
curses.WACS_T_HLINE¶	curses.WACS_BTBT¶	thick-line horizontal line
curses.WACS_T_LLCORNER¶	curses.WACS_TTBB¶	thick-line lower-left corner
curses.WACS_T_LRCORNER¶	curses.WACS_TBBT¶	thick-line lower-right corner
curses.WACS_T_LTEE¶	curses.WACS_TTTB¶	thick-line left tee
curses.WACS_T_PLUS¶	curses.WACS_TTTT¶	thick-line big plus sign
curses.WACS_T_RTEE¶	curses.WACS_TBTT¶	thick-line right tee
curses.WACS_T_TTEE¶	curses.WACS_BTTT¶	thick-line top tee
curses.WACS_T_ULCORNER¶	curses.WACS_BTTB¶	thick-line upper-left corner
curses.WACS_T_URCORNER¶	curses.WACS_BBTT¶	thick-line upper-right corner
curses.WACS_T_VLINE¶	curses.WACS_TBTB¶	thick-line vertical line

Mouse buttons¶

جدول زیر ثابت‌های دکمه‌ی ماوس را که توسط getmouse() استفاده می‌شوند، فهرست می‌کند:

ثابت دکمه‌ی ماوس	معنی
curses.BUTTONn_PRESSED¶	دکمه‌ی n ماوس فشرده شد
curses.BUTTONn_RELEASED¶	دکمه‌ی ماوس n رها شد
curses.BUTTONn_CLICKED¶	دکمه‌ی ماوس n کلیک شد
curses.BUTTONn_DOUBLE_CLICKED¶	دکمه ماوس n دوبار کلیک شد
curses.BUTTONn_TRIPLE_CLICKED¶	دکمه‌ی ماوس n سه‌بار کلیک شد
curses.BUTTON_SHIFT¶	کلید Shift در حین تغییر وضعیت دکمه فشرده بود
curses.BUTTON_CTRL¶	کلید Control در حین تغییر وضعیت دکمه فشرده بود
curses.BUTTON_ALT¶	کلید Alt در حین تغییر وضعیت دکمه فشرده شده بود

تغییر یافته در نسخه‌ی 3.10: ثابت‌های BUTTON5_* اکنون در صورتی که توسط کتابخانه curses زیرین ارائه شده باشند، در دسترس قرار می‌گیرند.

Colors¶

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

ثابت	رنگ
curses.COLOR_BLACK¶	سیاه
curses.COLOR_BLUE¶	آبی
curses.COLOR_CYAN¶	فیروزه‌ای (آبی مایل به سبز روشن)
curses.COLOR_GREEN¶	سبز
curses.COLOR_MAGENTA¶	سرخابی (قرمز مایل به بنفش)
curses.COLOR_RED¶	قرمز
curses.COLOR_WHITE¶	سفید
curses.COLOR_YELLOW¶	زرد

`curses.textpad` --- ابزارک ورودی متن برای برنامه‌های curses¶

ماژول curses.textpad کلاس Textbox را فراهم می‌کند که ویرایش مقدماتی متن را در یک پنجره curses مدیریت می‌کند و از مجموعه‌ای از اتصال‌های کلید (keybindings) شبیه به Emacs پشتیبانی می‌کند (بنابراین، همچنین مانند Netscape Navigator، BBedit 6.x، FrameMaker و بسیاری از برنامه‌های دیگر). این ماژول همچنین تابعی برای رسم مستطیل ارائه می‌دهد که برای قاب‌گذاری جعبه‌های متنی یا سایر مقاصد مفید است.

ماژول curses.textpad تابع زیر را تعریف می‌کند:

curses.textpad.rectangle(win, uly, ulx, lry, lrx)¶: یک مستطیل رسم می‌کند. اولین آرگومان باید یک شیء پنجره باشد؛ آرگومان‌های باقی‌مانده مختصات نسبت به آن پنجره هستند. آرگومان‌های دوم و سوم مختصات y و x گوشه‌ی بالا سمت چپ مستطیلی هستند که رسم می‌شود؛ آرگومان‌های چهارم و پنجم مختصات y و x گوشه‌ی پایین سمت راست هستند. این مستطیل با استفاده از نویسه‌های فرم VT100/IBM PC روی پایانه‌هایی که این امکان را فراهم می‌کنند (از جمله xterm و بیشتر شبیه‌سازهای نرم‌افزاری پایانه دیگر) رسم خواهد شد. در غیر این صورت، با خط‌تیره‌ها، سطرهای عمودی و علامت‌های جمع ASCII رسم خواهد شد.

اشیاء Textbox¶

می‌توانید یک شیء Textbox را به‌صورت زیر نمونه‌سازی کنید:

class curses.textpad.Textbox(win, insert_mode=False)¶

یک شیء ابزارک جعبه‌متن را برمی‌گرداند. آرگومان win باید یک شیء پنجره از curses باشد که جعبه‌متن در آن قرار گیرد. اگر insert_mode درست باشد، جعبه‌متن به جای بازنویسی متن موجود، نویسه‌های تایپ‌شده را درج می‌کند و متن موجود را به سمت راست جابه‌جا می‌کند. مکان‌نمای ویرایش جعبه‌متن در ابتدا در گوشه‌ی بالا سمت چپ پنجره‌ی حاوی آن قرار دارد، با مختصات (0, 0). پرچم stripspaces این نمونه در ابتدا روشن است.

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Entering and reading back the full Unicode range, including combining characters, is now supported when curses is built with wide-character support.

شیءهای Textbox متدهای زیر را دارند:

edit(validate=None)¶: این نقطه ورودی است که معمولاً از آن استفاده خواهید کرد. این نقطه ورود، کلیدهای ویرایشی را تا زمانی می‌پذیرد که یکی از کلیدهای خاتمه فشرده شود. اگر validate ارائه شده باشد، باید یک تابع باشد. این تابع برای هر کلید فشرده‌شده با همان کلید به‌عنوان پارامتر فراخوانی می‌شود؛ توزیع فرمان بر اساس نتیجه انجام می‌شود. اگر مقدار نادرستی برگرداند، کلید نادیده گرفته می‌شود. این متد محتوای پنجره را به‌صورت یک رشته برمی‌گرداند؛ اینکه نویسه‌های خالی درون پنجره گنجانده شوند یا نه، تحت تأثیر ویژگی stripspaces است.

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): validate is now called with a non-ASCII character as a string; other keystrokes are still passed as an integer.

do_command(ch)¶

یک کلیدفشاری فرمانی را پردازش می‌کند. مقدار 1 را برای ادامه‌ی ویرایش بازمی‌گرداند، یا اگر یک کلیدفشاری پایانی پردازش شده باشد، مقدار 0 را بازمی‌گرداند. کلیدفشارهای ویژه‌ی پشتیبانی‌شده عبارت‌اند از:

فشار کلید	عملیات
`Control`-`A`	به لبه‌ی چپ پنجره بروید.
`Control`-`B`	حرکت مکان‌نما به چپ، با انتقال به خط قبلی در صورت لزوم.
`Control`-`D`	حذف نویسه‌ی زیر مکان‌نما.
`Control`-`E`	به لبه‌ی راست (در صورت خاموش بودن stripspaces) یا پایان خط (در صورت روشن بودن stripspaces) بروید.
`Control`-`F`	مکان‌نما به راست، در صورت لزوم به خط بعدی می‌رود.
`Control`-`G`	خاتمه دادن و برگرداندن محتوای پنجره.
`Control`-`H`	حذف نویسه‌ی قبلی.
`Control`-`J`	اگر پنجره ۱ خطی باشد، خاتمه می‌یابد؛ در غیر این صورت به ابتدای خط بعدی می‌رود.
`Control`-`K`	اگر خط خالی باشد، آن را حذف کنید؛ در غیر این صورت، تا انتهای خط را پاک کنید.
`Control`-`L`	تازه‌سازی صفحه.
`Control`-`N`	مکان‌نما پایین؛ یک خط به پایین حرکت کنید.
`Control`-`O`	یک خط خالی در محل مکان‌نما درج کنید.
`Control`-`P`	مکان‌نما به بالا؛ یک خط به بالا حرکت کنید.

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

ثابت	فشار کلید
`KEY_LEFT`	`Control`-`B`
`KEY_RIGHT`	`Control`-`F`
`KEY_UP`	`Control`-`P`
`KEY_DOWN`	`Control`-`N`
`KEY_BACKSPACE`	`Control`-`h`

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

gather()¶: محتوای پنجره را به‌عنوان یک رشته برمی‌گرداند؛ اینکه آیا فاصله‌های خالی درون پنجره گنجانده می‌شوند، تحت تأثیر عضو stripspaces قرار می‌گیرد.

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

curses --- مدیریت پایانه برای نمایشگرهای سلول‌نویسه‌ای (character-cell displays)¶

توابع¶

Initialization and termination¶

Terminal mode control¶

Input options¶

Keyboard input¶

Mouse¶

رنگ¶

Windows and pads¶

Soft labels¶

Saving and restoring¶

Querying the terminal¶

Bell and screen flash¶

Terminal resizing¶

Terminfo database¶

Utilities¶

اشیای پنجره¶

Adding and inserting text¶

Deleting and inserting lines¶

Reading input¶

Reading window contents¶

Attributes¶

Background¶

Clearing and erasing¶

Borders and lines¶

Cursor position and window geometry¶

Creating and resizing windows¶

Refreshing and redrawing¶

Output options¶

Input options¶

Overlapping and touch¶

Coordinate conversion¶

Other¶

State queries¶

Screen objects¶

Complex character objects¶

ثابت‌ها¶

General¶

Attributes¶

Keys¶

Alternate character set¶

Mouse buttons¶

Colors¶

curses.textpad --- ابزارک ورودی متن برای برنامه‌های curses¶

اشیاء Textbox¶

`curses` --- مدیریت پایانه برای نمایشگرهای سلول‌نویسه‌ای (character-cell displays)¶

`curses.textpad` --- ابزارک ورودی متن برای برنامه‌های curses¶