ncurses(3X)

الاسم
ncurses - واجهة طرفية ذات خلايا محارف مع إخراج مُحسَّن

موجز
#include <curses.h>

الوصف
مكتبة “new curses” تُوفِّر للمُبرمِج وسيلةً مستقلةً عن الطرفية لقراءة دخل لوحة المفاتيح والفأرة والكتابة إلى شاشات خلايا محارف مع إخراج مُحسَّن لتقليل تحديثات الشاشة. ncurses يستبدل مكتبات curses من نظام Unix الإصدار 5 (الإصدار 4) (“SVr4”) و 4.4BSD Unix، التي توقف تطويرها في التسعينيات. يصف هذا المستند ncurses الإصدار 6.6 (التصحيح 20251230).

ncurses يسمح بالتحكم في محتويات شاشة الطرفية؛ تجريدها وتقسيمها باستخدام windows و pads؛ الحصول على أحداث لوحة المفاتيح والفأرة؛ اختيار اللون وسمات العرض (مثل العريض أو التسطير)؛ تعريف واستخدام مفاتيح soft label؛ الوصول إلى قاعدة بيانات قدرات الطرفية terminfo؛ واجهة توافق termcap؛ وتجريد واجهة برمجة التطبيقات للنظام لمعالجة الطرفية (مثل termios(3)).

ncurses يُطبِّق الواجهة الموصوفة بواسطة X/Open Curses Issue 7. في العديد من تفاصيل السلوك غير المُوحَّدة بواسطة X/Open، يُحاكي ncurses مكتبة curses الخاصة بـ SVr4 ويُوفِّر امتدادات مفيدة عديدة.

صفحات دليل ncurses تستخدم عدة أقسام لتوضيح مسائل الاستخدام والتوافق مع تطبيقات curses الأخرى. “NOTES” يصف المشكلات والتحذيرات التي يجب أن يكون أي مستخدم لواجهة برمجة التطبيقات ncurses على علم بها، مثل القيود على حجم نوع صحيح أساسي أو توفر ماكرو معالج مسبق حصري لتعريف دالة (مما يمنع أخذ عنوانها). يصف هذا القسم أيضًا تفاصيل تنفيذية مهمة للمبرمج ولكنها غير مُوحَّدة. “EXTENSIONS” يُقدِّم ابتكارات ncurses التي تتجاوز معيار X/Open Curses و/أو تطبيق SVr4 curses. تُسمى extensions للإشارة إلى أنه لا يمكن تنفيذها فقط باستخدام واجهة برمجة التطبيقات للمكتبة، بل تتطلب الوصول إلى الحالة الداخلية للمكتبة. “PORTABILITY” يناقش المسائل (بما يتجاوز استخدام الامتدادات) التي يجب مراعاتها عند الكتابة وفقًا لمعيار curses، أو لتطبيقات متعددة. “HISTORY” يفحص نقاط التفاصيل في ncurses وتطبيقات curses الأخرى عبر عقود تطويرها، خاصةً حيث أعاقت السابقة أو الجمود تصميمًا أفضل (وفي حالات قليلة، حيث تم التغلب على هذا الجمود).

يجب ربط تطبيق curses بالمكتبة؛ استخدم الخيار -lncurses مع المترجم أو الرابط. قد تتوفر نسخة تصحيح من المكتبة؛ إذا كان الأمر كذلك، فاربط بها باستخدام -lncurses_g. (قد يكون مُكامل نظامك قد ثبَّت هذه المكتبات بحيث يمكنك استخدام الخيارين -lcurses و -lcurses_g، على التوالي.) مكتبة ncurses_g تُسجِّل الأحداث التي تصف إجراءات ncurses في ملف يُسمى trace في دليل عمل التطبيق عند بدء التشغيل. انظر القسم “ALTERNATE CONFIGURATIONS” أدناه.

  هيكل التطبيق
تطبيق curses يستخدم معلومات من الإعدادات المحلية للنظام؛ setlocale(3) يُهيِّئها لاستدعاءات مكتبة curses.

        setlocale(LC_ALL, "");

إذا لم تُهيَّأ الإعدادات المحلية بهذه الطريقة، تفترض المكتبة أن المحارف قابلة للطباعة كما في ISO 8859-1، للعمل مع بعض البرامج القديمة. يجب عليك تهيئة الإعدادات المحلية؛ لا تتوقع سلوكًا ثابتًا من المكتبة عندما لا تكون الإعدادات المحلية قد أُعدت.

يجب استدعاء initscr(3X) أو newterm(3X) لتهيئة curses قبل استخدام أي دوال تصل إلى النوافذ أو الشاشات أو تعالجها.

للحصول على دخل محرف تلو الآخر بدون صدى — معظم البرامج التفاعلية الموجهة للشاشة تريد هذا — استخدم التسلسل التالي.

        initscr(); cbreak(); noecho();

معظم التطبيقات ستُجري إعدادًا إضافيًا على النحو التالي.

        noqiflush();
        keypad(stdscr, TRUE);

غالبًا ما يدخل برنامج curses بعد ذلك في حلقة معالجة أحداث. استدعِ endwin(3X) قبل الخروج.

  نظرة عامة
تُجرّد مكتبة curses الطرفية بهيكل بيانات SCREEN، وتمثل كل أو جزء من شاشتها بهياكل WINDOW. تنطبق خصائص مميزة على كل منها؛ على سبيل المثال، يكون نظام الخط لمشغل طرفية Unix النموذجي في أحد ثلاثة أوضاع: خام، cbreak، أو قانوني (“مطبوخ”). في curses، نظام الخط هو خاصية للشاشة، تنطبق بشكل متطابق على جميع النوافذ المرتبطة بها.

النافذة هي شبكة مستطيلة من خلايا المحارف، تُعنون بإحداثيات السطر والعمود (y, x)، مع الزاوية العليا اليسرى كـ (0, 0). نافذة تُدعى stdscr، مبدئيًا بنفس حجم شاشة الطرفية، متاحة دائمًا. أنشئ أخرى باستخدام newwin(3X).

لا تدير مكتبة curses النوافذ المتداخلة (لكن انظر أدناه). يمكنك إما استخدام stdscr لإدارة نافذة واحدة تملأ الشاشة، أو تجانب الشاشة إلى نوافذ غير متداخلة وعدم استخدام stdscr على الإطلاق. سيؤدي خلط النهجين إلى تأثيرات غير متوقعة وغير مرغوب فيها.

تسمح الدوال بمعالجة نافذة والمؤشر الذي يُحدد الخلية داخلها حيث ستحدث العملية التالية. من بينها، الأكثر أساسية هي move(3X) و addch(3X): تضع هذه المؤشر داخل stdscr وتكتب محرفًا إليه، على التوالي.

يمكن أن تسبب التغييرات المتكررة لشاشة الطرفية وميضًا مزعجًا أو استخدامًا غير فعال لقناة الاتصال بالجهاز، لذلك كقاعدة لا تُحدّثها المكتبة آليًا. لذلك، بعد استخدام دوال curses لتجميع مجموعة من التحديثات المرغوبة التي من المنطقي تقديمها معًا، استدعِ refresh(3X) لإخبار المكتبة بجعل شاشة المستخدم تبدو مثل stdscr. تُحسّن المكتبة مخرجاتها بحساب حجم أدنى من العمليات لتحويل الشاشة من حالتها في التحديث السابق إلى الحالة الجديدة. يتطلب التحسين الفعال معلومات دقيقة عن جهاز الطرفية: إدارة هذه المعلومات هي مجال واجهة برمجة التطبيقات terminfo(3X)، وهي ميزة في كل تطبيق curses قياسي.

يمكن أيضًا معالجة نوافذ خاصة تُدعى الوسادات. هذه ليست مقيدة بحجم شاشة الطرفية ولا يلزم عرض محتوياتها بالكامل. انظر curs_pad(3X).

تدعم العديد من الطرفيات تكوين ألوان المقدمة والخلفية لخلايا المحارف بالإضافة إلى السمات، التي تجعل المحارف تُعرض في أوضاع مثل العريض، المسطر، أو الفيديو المعكوس. انظر curs_color(3X) و curs_attr(3X).

يُعرّف curses ثوابت لتبسيط الوصول إلى مجموعة صغيرة من رسومات رسم النماذج المقابلة لمجموعة المحارف البديلة DEC (ACS)، وهي ميزة في VT100 وطرفيات أخرى. انظر addch(3X).

يُطبّق curses باستخدام مشغل طرفية نظام التشغيل؛ تُستقبل أحداث المفاتيح ليس كرموز مسح ضوئي بل كتسلسلات بايت. يُبلغ المشغل عن أغطية المفاتيح الرسومية (مفاتيح الأبجدية الرقمية وعلامات الترقيم والمسافة) كما هي. كل شيء آخر، بما في ذلك علامة التبويب، الإدخال/العودة، لوحة المفاتيح الرقمية، الأسهم، ومفاتيح الوظائف، يظهر لـ curses كمحرف تحكم أو تسلسل هروب متعدد البايت. يمكن لـ curses ترجمة الأخير إلى رموز مفاتيح فريدة. انظر keypad(3X) و getch(3X).

يوفر ncurses إعادة تطبيقات لمكتبات SVr4 panel(3X) و form(3X) و menu(3X)؛ تسمح هذه بالنوافذ المتداخلة وتُسهّل بناء واجهات المستخدم باستخدام curses.

  التهيئة
اختيار قيمة مناسبة لـ TERM في بيئة العملية ضروري لتشغيل مكتبة curses و terminfo بشكل صحيح. يختار نظام مُهيأ جيدًا قيمة TERM صحيحة آليًا؛ قد يساعد tset(1) في استكشاف المواقف الغريبة.

إذا غيّرت نوع الطرفية من شل، صدّر TERM، ثم شغّل tset(1) أو الأمر “tput init”. انظر القسم الفرعي “علامات التبويب والتهيئة” من terminfo(5).

إذا كانت متغيرات البيئة LINES و COLUMNS مضبوطة، أو إذا كان برنامج curses يُنفّذ في بيئة نوافذ رسومية، فإن المعلومات المُحصلة من هناك تتجاوز تلك المُحصلة بواسطة terminfo. امتداد ncurses يدعم شاشات طرفية قابلة لتغيير الحجم؛ انظر wresize(3X).

إذا كان متغير البيئة TERMINFO مُعرّفًا، يتحقق برنامج curses أولاً من وصف نوع طرفية في الموقع الذي يُحدده. TERMINFO مفيد لتطوير أوصاف الأنواع أو عندما لا تكون صلاحية الكتابة إلى /usr/share/terminfo متاحة.

انظر القسم “البيئة” أدناه.

  اتفاقيات التسمية
يقدم curses العديد من الدوال في أشكال متغيرة باستخدام مجموعة منتظمة من البدائل لاسم الدالة الأساسية. تلك المسبوقة بـ “w” تتطلب معامل مؤشر WINDOW؛ تلك التي بادئة “mv” تؤدي أولاً حركة مؤشر باستخدام wmove(3X)؛ بادئة “mvw” تشير إلى كليهما. دالة “w” هي عادةً الأساسية؛ إزالة هذه البادئة تشير عادةً إلى العمل على stdscr.

أربع دوال مسبوقة بـ “p” تتطلب معامل وسادة؛ انظر أدناه.

في ملخصات الدوال، تطبق صفحات دليل ncurses الأسماء التالية على المعاملات. نقدم أنواع المحارف في القسم الفرعي التالي.

bf | قيمة منطقية (صواب أو خطأ)
c | قيمة محرف أو عدد صحيح
ch | قيمة chtype
wc | قيمة wchar_t أو wint_t
wch | قيمة cchar_t
win | مؤشر إلى نافذة
pad | مؤشر إلى نافذة تمثل لوحة
زوج | معرّف زوج ألوان أمامية/خلفية

  تهيئات المحارف العريضة وغير العريضة
تستعرض صفحة الدليل هذه بشكل رئيسي الدوال التي تظهر في أي تهيئة من تهيئات المكتبة. هناك تهيئتان شائعتان؛ للاطلاع على الأخرى، راجع القسم “التهيئات البديلة” أدناه.

ncurses
    هي المكتبة في تهيئتها “غير العريضة”، التي تعالج محارف ثمانية البتات فقط. تخزن محرفًا مدمجًا مع سمات ومعرّف زوج ألوان في عنصر بيانات chtype، والذي غالبًا ما يكون اسمًا مستعارًا لـ int. سلسلة محارف curses مشابهة لسلسلة محارف C char؛ تنتهي سلسلة chtype بقيمة صحيحة 0، وهي محرف curses الفارغ.

    يمكن تخزين السمات ومعرّف زوج الألوان (بدون محرف مقابل) في متغيرات من نوع chtype أو attr_t. في كلتا الحالتين، يُوصل إليها عبر قناع بتات صحيح.

    يخزن ncurses كل خلية من نافذة كقيمة chtype. لا تحدد X/Open Curses أحجام رمز المحرف أو معرّف زوج الألوان، ولا عدد بتات السمات، في chtype؛ هذه الأمور تعتمد على التنفيذ. يستخدم ncurses ثمانية بتات لرمز المحرف. يجب على التطبيق الذي يتطلب نوع محرف أوسع، مثل تمثيل Unicode، استخدام واجهة برمجة التطبيقات للمحارف العريضة.

ncursesw
    هي المكتبة في تهيئتها “العريضة”، التي تعالج ترميزات المحارف التي تتطلب نوع بيانات أكبر مما يمكن أن يمثله char (نوع بحجم بايت). توفر دوال إضافية تكمل تلك الموجودة في المكتبة غير العريضة حيث يكون حجم نوع المحرف الأساسي مهمًا. تربط اصطلاحية تسمية منتظمة إلى حد ما العديد من المتغيرات العريضة بنظيراتها غير العريضة؛ حيث يحتوي اسم الدالة غير العريضة على “ch” أو “str”، أسبقها بـ “_w” للحصول على النظير العريض. على سبيل المثال، تصبح waddch هي wadd_wch. الاستثناء هو ins_nwstr (ومتغيراته)، مكتوبة هكذا بدلاً من “insn_wstr”. (الاستثناءات التي تضيف فقط “w” تشمل addwstr و inwstr ومتغيراتهما.)

    هذه الاصطلاحية غير قابلة للتطبيق على بعض أسماء الدوال غير العريضة، لذا تُستخدم تحويلات أخرى للتهيئة العريضة: دالة إدارة خلفية النافذة “bkgd” تصبح “bkgrnd”؛ دوال رسم ومسح حدود النافذة تُلحق باللاحقة “_set”؛ ودوال معالجة سمات المحرف مثل “attron” تصبح “attr_on”.

    cchar_t
        هو “محرف معقد” في curses ويقابل chtype في تهيئة المحرف غير العريض. هو نوع بنية لأنه يتطلب تخزينًا أكبر مما يوفره نوع قياسي عددي. قد لا يكون رمز المحرف قابلاً للتمثيل كـ char، وعلاوة على ذلك قد يشغل أكثر من محرف خلية واحدة (كما هو الحال مع علامات التشكيل وغيرها من العلامات الإعرابية). كل محرف من نوع wchar_t؛ يحتوي المحرف المعقد على محرف تباعد واحد وصفر أو أكثر من محارف عدم التباعد (انظر أدناه). تنتهي سلسلة المحارف المعقدة بـ cchar_t الذي يكون عضوه wchar_t هو المحرف العريض الفارغ. تُخزَّن السمات ومعرّف زوج الألوان في حقول منفصلة من البنية، وليست مدمجة في عدد صحيح كما في chtype.

    يخزن ncurses كل خلية من WINDOW كـ cchar_t. تخزن وتسترجع setcchar(3X) و getcchar(3X) بيانات cchar_t.

    تعتمد واجهة برمجة التطبيقات للمكتبة العريضة لـ ncurses على نوعي بيانات موحدين بواسطة ISO C95.

    wchar_t
        يخزن محرفًا عريضًا. مثل chtype، قد يكون اسمًا مستعارًا لـ int. اعتمادًا على ترميز المحرف، قد يكون المحرف العريض تباعديًا، مما يعني أنه يشغل خلية محرف بمفرده ويصاحب عادةً تقدم المؤشر، أو غير تباعدي، مما يعني أنه يشغل نفس خلية المحرف التباعدي، ويُعتبر غالبًا “معدِّلاً” للشكل الأساسي الذي يتحد معه، ولا يقدم المؤشر عادةً.

    wint_t
        يمكنه تخزين wchar_t أو الثابت WEOF، بشكل مماثل لدوال معالجة المحارف بحجم int في ISO C وثابتها EOF.

  فهرس أسماء الدوال
يسرد الجدول التالي دوال curses المقدمة في واجهات برمجة التطبيقات غير العريضة والعريضة وصفحات الدليل المقابلة التي تصفها. تلك المعلَّمة بـ “*” خاصة بـ ncurses، غير موصوفة بواسطة X/Open Curses ولا موجودة في SVr4.

اسم دالة curses | صفحة الدليل
COLOR_PAIR | curs_color(3X)
PAIR_NUMBER | curs_color(3X)
add_wch | curs_add_wch(3X)
add_wchnstr | curs_add_wchstr(3X)
add_wchstr | curs_add_wchstr(3X)
addch | curs_addch(3X)
addchnstr | curs_addchstr(3X)
addchstr | curs_addchstr(3X)
addnstr | curs_addstr(3X)
addnwstr | curs_addwstr(3X)
addstr | curs_addstr(3X)
addwstr | curs_addwstr(3X)
alloc_pair | new_pair(3X)*
assume_default_colors | default_colors(3X)*
attr_get | curs_attr(3X)
attr_off | curs_attr(3X)
attr_on | curs_attr(3X)
attr_set | curs_attr(3X)
attroff | curs_attr(3X)
attron | curs_attr(3X)
attrset | curs_attr(3X)
baudrate | curs_termattrs(3X)
beep | curs_beep(3X)
bkgd | curs_bkgd(3X)
bkgdset | curs_bkgd(3X)
bkgrnd | curs_bkgrnd(3X)
bkgrndset | curs_bkgrnd(3X)
border | curs_border(3X)
border_set | curs_border_set(3X)
box | curs_border(3X)
box_set | curs_border_set(3X)
can_change_color | curs_color(3X)
cbreak | curs_inopts(3X)
chgat | curs_attr(3X)
clear | curs_clear(3X)
clearok | curs_outopts(3X)
clrtobot | curs_clear(3X)
clrtoeol | curs_clear(3X)
color_content | curs_color(3X)
color_set | curs_attr(3X)
copywin | curs_overlay(3X)
curs_set | curs_kernel(3X)
curses_trace | curs_trace(3X)*
curses_version | curs_extend(3X)*
def_prog_mode | curs_kernel(3X)
def_shell_mode | curs_kernel(3X)
define_key | define_key(3X)*
del_curterm | curs_terminfo(3X)
delay_output | curs_util(3X)
delch | curs_delch(3X)
deleteln | curs_deleteln(3X)
delscreen | curs_initscr(3X)
delwin | curs_window(3X)
derwin | curs_window(3X)
doupdate | curs_refresh(3X)
dupwin | curs_window(3X)
echo | curs_inopts(3X)
echo_wchar | curs_add_wch(3X)
صدى_حرف | curs_addch(3X)
إنهاء_النافذة | curs_initscr(3X)
مسح | curs_clear(3X)
حرف_المسح | curs_termattrs(3X)
حرف_المسح_العريض | curs_termattrs(3X)
خروج_من_الكيرسز | curs_memleaks(3X)*
خروج_من_معلومات_الطرفية | curs_memleaks(3X)*
محتوى_اللون_الممتد | curs_color(3X)*
محتوى_الزوج_الممتد | curs_color(3X)*
لون_مفاتيح_التسمية_اللينة_الممتد | curs_slk(3X)*
filter | curs_util(3X)
إيجاد_زوج | new_pair(3X)*
وميض | curs_beep(3X)
مسح_المدخلات | curs_util(3X)
تحرير_زوج | new_pair(3X)*
الحصول_على_تأخير_الهروب | curs_threads(3X)*
الحصول_على_حرف_عريض | curs_get_wch(3X)
get_wstr | curs_get_wstr(3X)
getattrs | curs_attr(3X)
getbegx | curs_legacy(3X)*
getbegy | curs_legacy(3X)*
getbegyx | curs_getyx(3X)
getbkgd | curs_bkgd(3X)
getbkgrnd | curs_bkgrnd(3X)
getcchar | curs_getcchar(3X)
getch | curs_getch(3X)
getcurx | curs_legacy(3X)*
getcury | curs_legacy(3X)*
getmaxx | curs_legacy(3X)*
getmaxy | curs_legacy(3X)*
getmaxyx | curs_getyx(3X)
getmouse | curs_mouse(3X)*
getn_wstr | curs_get_wstr(3X)
getnstr | curs_getstr(3X)
getparx | curs_legacy(3X)*
getpary | curs_legacy(3X)*
getparyx | curs_getyx(3X)
getstr | curs_getstr(3X)
getsyx | curs_kernel(3X)
getwin | curs_util(3X)
getyx | curs_getyx(3X)
halfdelay | curs_inopts(3X)
has_colors | curs_color(3X)
has_ic | curs_termattrs(3X)
has_il | curs_termattrs(3X)
has_key | curs_getch(3X)*
has_mouse | curs_mouse(3X)*
hline | curs_border(3X)
hline_set | curs_border_set(3X)
idcok | curs_outopts(3X)
idlok | curs_outopts(3X)
immedok | curs_outopts(3X)
in_wch | curs_in_wch(3X)
in_wchnstr | curs_in_wchstr(3X)
in_wchstr | curs_in_wchstr(3X)
inch | curs_inch(3X)
inchnstr | curs_inchstr(3X)
inchstr | curs_inchstr(3X)
init_color | curs_color(3X)
init_extended_color | curs_color(3X)*
init_extended_pair | curs_color(3X)*
init_pair | curs_color(3X)
initscr | curs_initscr(3X)
innstr | curs_instr(3X)
innwstr | curs_inwstr(3X)
ins_nwstr | curs_ins_wstr(3X)
ins_wch | curs_ins_wch(3X)
ins_wstr | curs_ins_wstr(3X)
insch | curs_insch(3X)
insdelln | curs_deleteln(3X)
insertln | curs_deleteln(3X)
insnstr | curs_insstr(3X)
insstr | curs_insstr(3X)
instr | curs_instr(3X)
intrflush | curs_inopts(3X)
inwstr | curs_inwstr(3X)
is_cbreak | curs_inopts(3X)*
is_cleared | curs_opaque(3X)*
is_echo | curs_inopts(3X)*
is_idcok | curs_opaque(3X)*
is_idlok | curs_opaque(3X)*
is_immedok | curs_opaque(3X)*
is_keypad | curs_opaque(3X)*
is_leaveok | curs_opaque(3X)*
is_linetouched | curs_touch(3X)
is_nl | curs_inopts(3X)*
is_nodelay | curs_opaque(3X)*
is_notimeout | curs_opaque(3X)*
is_pad | curs_opaque(3X)*
is_raw | curs_inopts(3X)*
is_scrollok | curs_opaque(3X)*
is_subwin | curs_opaque(3X)*
is_syncok | curs_opaque(3X)*
is_term_resized | resizeterm(3X)*
is_wintouched | curs_touch(3X)
isendwin | curs_initscr(3X)
key_defined | key_defined(3X)*
key_name | curs_util(3X)
keybound | keybound(3X)*
keyname | curs_util(3X)
keyok | keyok(3X)*
keypad | curs_inopts(3X)
killchar | curs_termattrs(3X)
killwchar | curs_termattrs(3X)
leaveok | curs_outopts(3X)
longname | curs_termattrs(3X)
mcprint | curs_print(3X)*
meta | curs_inopts(3X)
mouse_trafo | curs_mouse(3X)*
mouseinterval | curs_mouse(3X)*
mousemask | curs_mouse(3X)*
move | curs_move(3X)
mvadd_wch | curs_add_wch(3X)
mvadd_wchnstr | curs_add_wchstr(3X)
mvadd_wchstr | curs_add_wchstr(3X)
mvaddch | curs_addch(3X)
mvaddchnstr | curs_addchstr(3X)
mvaddchstr | curs_addchstr(3X)
mvaddnstr | curs_addstr(3X)
mvaddnwstr | curs_addwstr(3X)
mvaddstr | curs_addstr(3X)
mvaddwstr | curs_addwstr(3X)
mvchgat | curs_attr(3X)
mvcur | curs_kernel(3X)
mvdelch | curs_delch(3X)
mvderwin | curs_window(3X)
mvget_wch | curs_get_wch(3X)
mvget_wstr | curs_get_wstr(3X)
mvgetch | curs_getch(3X)
mvgetn_wstr | curs_get_wstr(3X)
mvgetnstr | curs_getstr(3X)
mvgetstr | curs_getstr(3X)
mvhline | curs_border(3X)
mvhline_set | curs_border_set(3X)
mvin_wch | curs_in_wch(3X)
mvin_wchnstr | curs_in_wchstr(3X)
mvin_wchstr | curs_in_wchstr(3X)
mvinch | curs_inch(3X)
mvinchnstr | curs_inchstr(3X)
mvinchstr | curs_inchstr(3X)
mvinnstr | curs_instr(3X)
mvinnwstr | curs_inwstr(3X)
mvins_nwstr | curs_ins_wstr(3X)
mvins_wch | curs_ins_wch(3X)
mvins_wstr | curs_ins_wstr(3X)
mvinsch | curs_insch(3X)
mvinsnstr | curs_insstr(3X)
mvinsstr | curs_insstr(3X)
mvinstr | curs_instr(3X)
mvinwstr | curs_inwstr(3X)
mvprintw | curs_printw(3X)
mvscanw | curs_scanw(3X)
mvvline | curs_border(3X)
mvvline_set | curs_border_set(3X)
mvwadd_wch | curs_add_wch(3X)
mvwadd_wchnstr | curs_add_wchstr(3X)
mvwadd_wchstr | curs_add_wchstr(3X)
mvwaddch | curs_addch(3X)
mvwaddchnstr | curs_addchstr(3X)
mvwaddchstr | curs_addchstr(3X)
mvwaddnstr | curs_addstr(3X)
mvwaddnwstr | curs_addwstr(3X)
mvwaddstr | curs_addstr(3X)
mvwaddwstr | curs_addwstr(3X)
mvwchgat | curs_attr(3X)
mvwdelch | curs_delch(3X)
mvwget_wch | curs_get_wch(3X)
mvwget_wstr | curs_get_wstr(3X)
mvwgetch | curs_getch(3X)
mvwgetn_wstr | curs_get_wstr(3X)
mvwgetnstr | curs_getstr(3X)
mvwgetstr | curs_getstr(3X)
mvwhline | curs_border(3X)
mvwhline_set | curs_border_set(3X)
mvwin | curs_window(3X)
mvwin_wch | curs_in_wch(3X)
mvwin_wchnstr | curs_in_wchstr(3X)
mvwin_wchstr | curs_in_wchstr(3X)
mvwinch | curs_inch(3X)
mvwinchnstr | curs_inchstr(3X)
mvwinchstr | curs_inchstr(3X)
mvwinnstr | curs_instr(3X)
mvwinnwstr | curs_inwstr(3X)
mvwins_nwstr | curs_ins_wstr(3X)
mvwins_wch | curs_ins_wch(3X)
mvwins_wstr | curs_ins_wstr(3X)
mvwinsch | curs_insch(3X)
mvwinsnstr | curs_insstr(3X)
mvwinsstr | curs_insstr(3X)
mvwinstr | curs_instr(3X)
mvwinwstr | curs_inwstr(3X)
mvwprintw | curs_printw(3X)
mvwscanw | curs_scanw(3X)
mvwvline | curs_border(3X)
mvwvline_set | curs_border_set(3X)
napms | curs_kernel(3X)
newpad | curs_pad(3X)
newterm | curs_initscr(3X)
newwin | curs_window(3X)
nl | curs_inopts(3X)
nocbreak | curs_inopts(3X)
nodelay | curs_inopts(3X)
noecho | curs_inopts(3X)
nofilter | curs_util(3X)*
nonl | curs_inopts(3X)
noqiflush | curs_inopts(3X)
noraw | curs_inopts(3X)
notimeout | curs_inopts(3X)
overlay | curs_overlay(3X)
overwrite | curs_overlay(3X)
pair_content | curs_color(3X)
pecho_wchar | curs_pad(3X)
pechochar | curs_pad(3X)
pnoutrefresh | curs_pad(3X)
prefresh | curs_pad(3X)
printw | curs_printw(3X)
putp | curs_terminfo(3X)
putwin | curs_util(3X)
qiflush | curs_inopts(3X)
raw | curs_inopts(3X)
redrawwin | curs_refresh(3X)
refresh | curs_refresh(3X)
reset_color_pairs | curs_color(3X)*
reset_prog_mode | curs_kernel(3X)
reset_shell_mode | curs_kernel(3X)
resetty | curs_kernel(3X)
resize_term | resizeterm(3X)*
resizeterm | resizeterm(3X)*
restartterm | curs_terminfo(3X)
ripoffline | curs_kernel(3X)
savetty | curs_kernel(3X)
scanw | curs_scanw(3X)
scr_dump | curs_scr_dump(3X)
scr_init | curs_scr_dump(3X)
scr_restore | curs_scr_dump(3X)
scr_set | curs_scr_dump(3X)
scrl | curs_scroll(3X)
scroll | curs_scroll(3X)
scrollok | curs_outopts(3X)
set_curterm | curs_terminfo(3X)
set_escdelay | curs_threads(3X)*
set_tabsize | curs_threads(3X)*
set_term | curs_initscr(3X)
setcchar | curs_getcchar(3X)
setscrreg | curs_outopts(3X)
setsyx | curs_kernel(3X)
setupterm | curs_terminfo(3X)
slk_attr | curs_slk(3X)*
slk_attr_off | curs_slk(3X)
slk_attr_on | curs_slk(3X)
slk_attr_set | curs_slk(3X)
slk_attroff | curs_slk(3X)
slk_attron | curs_slk(3X)
slk_attrset | curs_slk(3X)
slk_clear | curs_slk(3X)
slk_color | curs_slk(3X)
slk_init | curs_slk(3X)
slk_label | curs_slk(3X)
slk_noutrefresh | curs_slk(3X)
slk_refresh | curs_slk(3X)
slk_restore | curs_slk(3X)
slk_set | curs_slk(3X)
slk_touch | curs_slk(3X)
slk_wset | curs_slk(3X)
standend | curs_attr(3X)
standout | curs_attr(3X)
start_color | curs_color(3X)
subpad | curs_pad(3X)
نافذة فرعية | curs_window(3X)
مزامنة_موافق | curs_window(3X)
سمات_المحطة | curs_termattrs(3X)
سمات_المحطة | curs_termattrs(3X)
اسم_المحطة | curs_termattrs(3X)
tgetent | curs_termcap(3X)
tgetflag | curs_termcap(3X)
tgetnum | curs_termcap(3X)
tgetstr | curs_termcap(3X)
tgoto | curs_termcap(3X)
tigetflag | curs_terminfo(3X)
tigetnum | curs_terminfo(3X)
tigetstr | curs_terminfo(3X)
timeout | curs_inopts(3X)
tiparm | curs_terminfo(3X)
tiparm_s | curs_terminfo(3X)*
tiscan_s | curs_terminfo(3X)*
لمس_سطر | curs_touch(3X)
لمس_نافذة | curs_touch(3X)
tparm | curs_terminfo(3X)
tputs | curs_termcap(3X)
tputs | curs_terminfo(3X)
trace | curs_trace(3X)*
typeahead | curs_inopts(3X)
unctrl | curs_util(3X)
unget_wch | curs_get_wch(3X)
ungetch | curs_getch(3X)
ungetmouse | curs_mouse(3X)*
untouchwin | curs_touch(3X)
use_default_colors | default_colors(3X)*
use_env | curs_util(3X)
use_extended_names | curs_extend(3X)*
use_legacy_coding | legacy_coding(3X)*
use_screen | curs_threads(3X)*
use_tioctl | curs_util(3X)*
use_window | curs_threads(3X)*
vid_attr | curs_terminfo(3X)
vid_puts | curs_terminfo(3X)
vidattr | curs_terminfo(3X)
vidputs | curs_terminfo(3X)
vline | curs_border(3X)
vline_set | curs_border_set(3X)
vw_printw | curs_printw(3X)
vw_scanw | curs_scanw(3X)
vwprintw | curs_printw(3X)
vwscanw | curs_scanw(3X)
wadd_wch | curs_add_wch(3X)
wadd_wchnstr | curs_add_wchstr(3X)
wadd_wchstr | curs_add_wchstr(3X)
waddch | curs_addch(3X)
waddchnstr | curs_addchstr(3X)
waddchstr | curs_addchstr(3X)
waddnstr | curs_addstr(3X)
waddnwstr | curs_addwstr(3X)
waddstr | curs_addstr(3X)
waddwstr | curs_addwstr(3X)
wattr_get | curs_attr(3X)
wattr_off | curs_attr(3X)
wattr_on | curs_attr(3X)
wattr_set | curs_attr(3X)
wattroff | curs_attr(3X)
wattron | curs_attr(3X)
wattrset | curs_attr(3X)
wbkgd | curs_bkgd(3X)
wbkgdset | curs_bkgd(3X)
wbkgrnd | curs_bkgrnd(3X)
wbkgrndset | curs_bkgrnd(3X)
wborder | curs_border(3X)
wborder_set | curs_border_set(3X)
wchgat | curs_attr(3X)
wclear | curs_clear(3X)
wclrtobot | curs_clear(3X)
wclrtoeol | curs_clear(3X)
wcolor_set | curs_attr(3X)
wcursyncup | curs_window(3X)
wdelch | curs_delch(3X)
wdeleteln | curs_deleteln(3X)
wecho_wchar | curs_add_wch(3X)
wechochar | curs_addch(3X)
wenclose | curs_mouse(3X)*
werase | curs_clear(3X)
wget_wch | curs_get_wch(3X)
wget_wstr | curs_get_wstr(3X)
wgetbkgrnd | curs_bkgrnd(3X)
wgetch | curs_getch(3X)
wgetdelay | curs_opaque(3X)*
wgetn_wstr | curs_get_wstr(3X)
wgetnstr | curs_getstr(3X)
wgetparent | curs_opaque(3X)*
wgetscrreg | curs_opaque(3X)*
wgetstr | curs_getstr(3X)
whline | curs_border(3X)
whline_set | curs_border_set(3X)
win_wch | curs_in_wch(3X)
win_wchnstr | curs_in_wchstr(3X)
win_wchstr | curs_in_wchstr(3X)
winch | curs_inch(3X)
winchnstr | curs_inchstr(3X)
winchstr | curs_inchstr(3X)
وِنستر | curs_instr(3X)
وِنوِستر | curs_inwstr(3X)
وِنز_إنوِستر | curs_ins_wstr(3X)
وِنز_وِتش | curs_ins_wch(3X)
وِنز_وِستر | curs_ins_wstr(3X)
وِنزش | curs_insch(3X)
وِنزدلن | curs_deleteln(3X)
وِنزرتلن | curs_deleteln(3X)
وِنزنستر | curs_insstr(3X)
وِنزستر | curs_insstr(3X)
وِنستر | curs_instr(3X)
وِنوِستر | curs_inwstr(3X)
دبليوماوس_ترافو | curs_mouse(3X)*
دبليوموف | curs_move(3X)
دبليونوترفش | curs_refresh(3X)
دبليوبرينتو | curs_printw(3X)
دبليوريدرولن | curs_refresh(3X)
دبليورفش | curs_refresh(3X)
دبليوريسايز | دبليوريسايز(3X)*
wscanw | curs_scanw(3X)
wscrl | curs_scroll(3X)
wsetscrreg | curs_outopts(3X)
wstandend | curs_attr(3X)
wstandout | curs_attr(3X)
wsyncdown | curs_window(3X)
wsyncup | curs_window(3X)
wtimeout | curs_inopts(3X)
wtouchln | curs_touch(3X)
wunctrl | curs_util(3X)
wvline | curs_border(3X)
wvline_set | curs_border_set(3X)

إضافة ncurses لمؤشر الشاشة تُضيف دوال إضافية تُقابل العديد مما سبق، كل منها بلاحقة “_sp”؛ انظر curs_sp_funcs(3X).

توفر بعض الإضافات قابل للتكوين عند تجميع ncurses؛ انظر القسمين “ALTERNATE CONFIGURATIONS” و “EXTENSIONS” أدناه.

قيمة الإرجاع
ما لم يُذكر خلاف ذلك، الدوال التي تُرجع أعدادًا صحيحة تُرجع الثوابت OK عند النجاح و ERR عند الفشل؛ انظر curs_variables(3X). الدوال التي تُرجع مؤشرات تُرجع مؤشرًا فارغًا عند الفشل. عادةً، تعالج ncurses المؤشر الفارغ المُمرر كمعامل دالة كفشل. الدوال المسبوقة بـ “mv” تؤدي أولاً حركة المؤشر وتفشل إذا كان الموضع (y, x) خارج حدود النافذة.

البيئة
الرموز التالية من بيئة العملية تُخصص سلوك وقت التشغيل لتطبيقات ncurses. قد تُكوّن المكتبة لتتجاهل المتغيرات TERMINFO و TERMINFO_DIRS و TERMPATH و HOME، إذا كان المستخدم هو المستخدم الفائق (الجذر)، أو استخدم التطبيق setuid(2) أو setgid(2).

  BAUDRATE
مكتبة التصحيح تفحص هذا المتغير عندما يُعيد التطبيق توجيه المخرجات إلى ملف. ncurses تُفسر قيمته الصحيحة كسرعة خط الطرفية بالبت في الثانية. إذا كانت تلك القيمة غائبة أو غير صالحة، تستخدم ncurses 9600. هذه الميزة تسمح للمطورين ببناء حالات اختبار قابلة للتكرار تراعي قرارات التحسين التي تعتمد على سرعة خط الطرفية.

  CC (حرف الأمر)
عند تعيينه، تتغير قيمة إمكانية command_character (cmdch) لمدخلات terminfo المُحمّلة إلى قيمة هذا المتغير. عدد قليل جدًا من مدخلات terminfo توفر هذه الميزة.

لأن هذا الاسم يُستخدم أيضًا في بيئات التطوير لتخزين اسم مترجم C، فإن ncurses يتجاهل قيمته إذا لم يكن طوله حرفًا واحدًا.

  COLUMNS
يحدد هذا المتغير عرض الشاشة بوحدات الخلايا المحرفية. التطبيقات التي تعمل في بيئة النوافذ عادةً ما تستطيع الحصول على عرض النافذة التي تنفذ فيها. يفرض ncurses حدًا أقصى قدره 512 عند قراءة القيمة. إذا لم يُعرف COLUMNS ولم يكن حجم شاشة الطرفية متاحًا من برنامج تشغيل الطرفية، يستخدم ncurses الحجم المحدد بواسطة قدرة columns (cols) لإدخال نوع الطرفية في قاعدة بيانات terminfo، إن وُجد.

من المهم أن يستخدم تطبيقك حجم الشاشة الصحيح. الكشف الآلي عنه ليس ممكنًا دائمًا لأن التطبيق قد يعمل على مضيف لا يحترم NAWS (مفاوضات حول حجم النافذة) أو بهوية مستخدم مختلفة عن مالك ملف جهاز الطرفية. تعيين COLUMNS و/أو LINES يتجاوز استخدام المكتبة لحجم الشاشة المُحصل عليه من نظام التشغيل.

يمكن تحديد المتغيرين COLUMNS و LINES بشكل مستقل. هذه الخاصية مفيدة لتجاوز العيوب في أوصاف أنواع الطرفيات القديمة؛ أوصاف xterm(1) التي تحدد 65 سطرًا كانت سيئة السمعة يومًا. للحصول على أفضل النتائج، تجنب تحديد رموز القدرة cols و lines في أوصاف terminfo لمحاكيات الطرفيات.

يمكن لـ use_env(3X) تعطيل استخدام بيئة العملية في تحديد حجم الشاشة. يمكن لـ use_tioctl(3X) تحديث COLUMNS و LINES لمطابقة حجم الشاشة المُحصل عليه من استدعاءات النظام أو قاعدة بيانات الطرفيات.

  ESCDELAY
لكي يميز curses حرف ESC الناتج عن ضغط المستخدم لمفتاح “Escape” على جهاز الإدخال عن ذلك الذي يبدأ تسلسل هروب (كما يُنتج عادةً بواسطة مفاتيح الوظائف)، ينتظر بعد استقبال حرف الهروب ليرى ما إذا كانت محارف إضافية متاحة في دفق الإدخال خلال فترة قصيرة. يخزن متغير عام ESCDELAY هذه الفترة بالمللي ثانية. القيمة المبدئية 1000 (ثانية واحدة) كافية لمعظم الاستخدامات. يتجاوز متغير البيئة هذا هذه القيمة؛ يفرض ncurses حدًا أقصى قدره 30,000 (30 ثانية) عند قراءة القيمة.

الحالة الأكثر شيوعًا التي قد ترغب فيها بتغيير هذه القيمة هي العمل مع مضيف بعيد عبر قناة اتصال بطيئة. إذا لم يستقبل المضيف الذي يشغل تطبيق curses محارف تسلسل الهروب في الوقت المناسب، يمكن للمكتبة تفسيرها كأحداث ضغطات مفاتيح متعددة. على العكس، كاتب سريع على اتصال منخفض الكمون الذي يُدخل بالصدفة ESC متبوعًا بمحارف تطابق تسلسل هروب قد يواجه سلوك تطبيق مربك.

أحداث الفأرة في xterm(1) هي شكل من تسلسل الهروب؛ لذلك، إذا كان تطبيقك يستخدم النقر المتعدد بكثافة، قد ترغب في إطالة القيمة المبدئية لأن التأخير ينطبق على حدث النقر المتعدد المركب وكذلك النقرات الفردية.

لا ينبغي للتطبيقات المحمولة الاعتماد على وجود ESCDELAY بأي شكل، لكن تعيين متغير البيئة بدلاً من المتغير العام لا يخلق مشاكل عند ترجمة تطبيق.

إذا كان keypad(3X) معطلًا لنافذة curses التي تستقبل الإدخال، فإن ESCDELAY غير ذي صلة ويجب على البرنامج إزالة الغموض عن تسلسلات الهروب بنفسه.

  HOME
قد يقرأ ncurses ويكتب أوصاف طرفيات مساعدة في ملفات .termcap و .terminfo في دليل المستخدم الرئيسي.

  LINES
هذا النظير لـ COLUMNS يحدد ارتفاع الشاشة بالمحارف. القدرة والرمز المقابلان في terminfo هما lines. انظر وصف المتغير COLUMNS أعلاه.

  MOUSE_BUTTONS_123
(منفذ OS/2 EMX فقط) يُرقم OS/2 فأرة ثلاثية الأزرار بشكل غير متسق مع المنصات الأخرى، بحيث يكون 1 هو الزر الأيسر، 2 الأيمن، و3 الأوسط. يخصص هذا المتغير ترقيم أزرار الفأرة. يجب أن تكون قيمته ثلاثة أرقام 1-3 بأي ترتيب. افتراضيًا، يفترض ncurses ترقيمًا “132”.

  NCURSES_ASSUMED_COLORS
إذا عُيّن، يتجاوز هذا المتغير افتراض المكتبة ncurses المُضمّن في الترجمة بأن ألوان الطرفية المبدئية هي أبيض على أسود؛ انظر default_colors(3X). عيّن قيم لون المقدمة والخلفية باستخدام متغير البيئة هذا بتعيين قيمتين صحيحتين مفصولتين بفاصلة، تشيران إلى رقمي لون المقدمة والخلفية، على التوالي.

على سبيل المثال، لإخبار ncurses بعدم افتراض أي شيء عن الألوان، استخدم قيمة “-1,-1”. لجعل مخطط الألوان المبدئي أخضر على أسود على طرفية تستخدم تعيينات ألوان ANSI X3.64/ECMA-48/ISO 6429، استخدم “2,0”. يقبل ncurses قيمًا صحيحة من -1 حتى قيمة قدرة terminfo max_colors (colors) لنوع الطرفية المحدد.

  NCURSES_CONSOLE2
(منفذ MinGW فقط) يعالج برنامج Console2 بشكل معيب استدعاء واجهة برمجة تطبيقات وحدة التحكم من Microsoft CreateConsoleScreenBuffer. التطبيقات التي تستخدمه ستتوقف. ومع ذلك، من الممكن محاكاة إجراء هذا الاستدعاء عن طريق تعيين الإحداثيات، وحفظ واستعادة محتويات الشاشة الأصلية بشكل صريح. تعيين متغير البيئة NCGDB له نفس التأثير.

  NCURSES_GPM_TERMS
(لينكس فقط) عندما يُهيأ ncurses لاستخدام واجهة GPM، قد يُدرج هذا المتغير اسم نوع طرفية واحد أو أكثر، مفصولة بخطوط عمودية (|) أو نقطتين رأسيتين (:)، يُطابق بها متغير TERM (انظر أدناه). القيمة الفارغة تُعطل واجهة GPM، مستخدمةً دعم ncurses المدمج لبروتوكولات فأر xterm(1) بدلاً من ذلك. إذا غاب المتغير، يحاول ncurses فتح GPM إذا احتوى TERM على “linux”.

  NCURSES_NO_HARD_TABS
قد يستخدم ncurses محارف الجدولة في تحسين حركة المؤشر. في بعض الحالات، قد لا يعالج برنامج تشغيل طرفيتك هذه المحارف بشكل صحيح. عيّن هذا المتغير البيئي إلى أي قيمة لتعطيل الميزة. يمكنك أيضاً ضبط إعدادات stty(1) لتجنب المشكلة.

  NCURSES_NO_MAGIC_COOKIE
تخزن العديد من الأطراف خصائص الفيديو كخصائص لخلية محرف، كما يفعل curses. تاريخياً، سجلت بعض التغييرات في خصائص الفيديو كبيانات احتلت منطقياً (لكن بشكل غير مرئي) خلايا محرف على الشاشة، مُشغّلة أو مُعطّلة الخصائص، مشابهاً للوسوم في لغة ترميز، والتي كان يجب طباعتها فوقياً لتصوير المحتويات المرغوبة للخلايا؛ تُسمى هذه “الكعكات السحرية”. إذا كان إدخال terminfo لنوع طرفيتك لا يصف معالجتها للكعكات السحرية بشكل كافٍ، عيّن هذا المتغير إلى أي قيمة لتوجيه ncurses لتعطيل الخصائص بالكامل.

  NCURSES_NO_PADDING
تصف معظم أوصاف أنواع الأطراف في قاعدة بيانات terminfo الأجهزة المادية. يستخدم العديد من الأشخاص تطبيقات قائمة على curses في برامج محاكاة طرفية تعمل في بيئة نوافذ. يمكن لهذه البرامج مضاعفة جميع الميزات الهامة للطرفية المادية، لكنها غالباً تفتقر إلى قيودها. من أبرز هذه العيوب الغائبة مشكلة إدارة تدفق البيانات؛ أي تحديد سرعة الاتصال بما يمكن للجهاز المادي معالجته. ما لم تُوصل طرفية مادية بمركز طرفية (الذي يقوم بالتحكم بالتدفق)، يجب على التطبيق إدارة التدفق بنفسه لمنع التجاوز وفقدان البيانات.

الحل الذي لا يكلف أجهزة هو أن يوقف التطبيق الإرسال بعد توجيه طرفية لتنفيذ عملية تؤديها ببطء، مثل مسح الشاشة. تضمن العديد من أوصاف أنواع الأطراف، بما في ذلك وصف VT100، مواصفات تأخير في الإمكانيات. قد ترغب في استخدام هذه الأوصاف الطرفية دون دفع ثمن الأداء. عيّن NCURSES_NO_PADDING إلى أي قيمة لتعطيل كل الحشو باستثناء الإلزامي. يُستخدم الحشو الإلزامي بواسطة إمكانيات طرفية مثل flash_screen (flash).

  NCURSES_NO_SETBUF
(مهمل) قبل التغييرات الداخلية المطورة في ncurses 5.9 (التصحيحات من 20120825 إلى 20130126)، استخدمت المكتبة setbuf(3) لتمكين الإخراج المخزن بالكامل عند تهيئة الطرفية. فُعل هذا، كما في SVr4 curses، لزيادة الأداء. لأغراض الاختبار، لكل من ncurses وبعض التطبيقات، جُعلت هذه الميزة اختيارية. تعطيل هذا المتغير عطل تخزين الإخراج مؤقتاً، تاركاً دفق الإخراج في الوضع الأصلي (عادةً تخزين سطري مؤقت).

في الوقت الحالي، يقوم ncurses بتخزينه المؤقت الخاص ولا يحتاج هذا الحل البديل؛ لا يعدل تخزين دفق الإخراج القياسي. هذا النهج يجعل معالجة المكتبة للإشارات المبدوءة بلوحة المفاتيح أكثر متانة. العيب هو أن بعض البرامج غير التقليدية خلطت استدعاءات stdio(3) مع استدعاءات ncurses وحصلت (عادةً) على السلوك الذي توقعته. لم يعد هذا هو الحال؛ لا يكتب ncurses إلى واصف ملف الإخراج القياسي عبر دفق مخزن مؤقتاً بواسطة stdio.

كحالة خاصة، لا تزال استدعاءات واجهة برمجة التطبيقات منخفضة المستوى مثل putp(3X) تستخدم دفق الإخراج القياسي. استدعاءات curses عالية المستوى مثل printw(3X) لا تفعل ذلك.

  NCURSES_NO_UTF8_ACS
عند التهيئة، يفحص ncurses المتغير البيئي TERM للحالات الخاصة حيث محارف رسم الأشكال VT100 (وإمكانيات مجموعة المحارف البديلة المقابلة terminfo) معروفة بأنها غير مدعومة بأنواع أطراف تدعي خلاف ذلك توافق VT100. تحديداً، عند التشغيل في بيئة محلية UTF-8، يتجاهلها جهاز وحدة التحكم الافتراضية لينكس وبرنامج GNU screen(1). عيّن هذا المتغير إلى قيمة غير صفرية لتوجيه ncurses بأن دعم ACS للطرفية معطل؛ ثم تُخرج المكتبة نقاط رمز Unicode التي تتوافق مع محارف رسم الأشكال. عيّنه إلى صفر (أو غير عدد صحيح) لتعطيل الفحص الخاص لأسماء أنواع الأطراف المطابقة لـ “linux” أو “screen”، موجهاً ncurses لافتراض أن ميزة ACS تعمل إذا أعلن وصف نوع الطرفية عنها.

كبديل لاستخدام هذا المتغير، يفحص ncurses إمكانية رقمية موسعة terminfo U8 يمكن تجميعها باستخدام “tic -x”. الأمثلة تتبع.

        # linux console, if patched to provide working
        # VT100 shift-in/shift-out, with corresponding font.
        linux-vt100|linux console with VT100 line-graphics,
                U8#0, use=linux,

        # uxterm with vt100Graphics resource set to false
        xterm-utf8|xterm relying on UTF-8 line-graphics,
                U8#1, use=xterm,

اختير الاسم المكون من محرفين “U8” للسماح باستخدامه عبر واجهة termcap الخاصة بـ ncurses.

  NCURSES_TRACE
عند التهيئة، يفحص ncurses (في تكوين التصحيح الخاص به) وجود هذا المتغير. إذا عُرف بقيمة صحيحة، تستدعي المكتبة curses_trace(3X) بتلك القيمة كمعامل.

  TERM
المتغير TERM يُشير إلى نوع الطرفية. كل نوع متميز، رغم تشابه العديد منها. يُضبط عادةً بواسطة محاكيات الطرفية لمساعدة التطبيقات في إيجاد وصف طرفية قابل للعمل. بعضها يختار تقريبًا شائعًا مثل “ansi” أو “vt100” أو “xterm” بدلاً من تطابق دقيق مع قدراتها. ليس نادرًا أن يواجه تطبيق مشاكل مع هذا النهج؛ على سبيل المثال، قد لا تعمل ضغطة مفتاح بشكل صحيح، أو لا تُنتج أي تأثير سوى أحرف تبدو غير مفهومة على الشاشة.

ضبط TERM ليس له تأثير على تشغيل العتاد؛ بل يؤثر على طريقة تواصل التطبيقات مع الطرفية. وبالمثل، كقاعدة عامة (xterm(1) استثناء نادر)، محاكيات الطرفية التي تسمح لك بتحديد TERM كمعامل أو قيمة تهيئة لا تُغير سلوكها ليتطابق مع ذلك الضبط.

  TERMCAP
إذا كان ncurses مُهيأ بدعم termcap، فإنه يتحقق من وجود وصف نوع طرفية بصيغة termcap إذا لم يتوفر وصف بصيغة terminfo. ضبط هذا المتغير يُوجّه ncurses لتجاهل موقع قاعدة بيانات termcap المعتاد، /etc/termcap؛ انظر TERMPATH أدناه. يجب أن يحتوي TERMCAP إما على وصف طرفية (مع إزالة الأسطر الجديدة)، أو اسم ملف يُشير إلى مكان تخزين المعلومات المطلوبة بواسطة متغير البيئة TERM.

  TERMINFO
يمكن تهيئة ncurses لقراءة قواعد بيانات أوصاف أنواع الطرفيات في مواقع مختلفة باستخدام صيغ متنوعة. هذا المتغير يُلغي الموقع المبدئي. الأوصاف بصيغة terminfo تُخزّن عادةً في شجرة أدلة باستخدام أدلة فرعية مُسمّاة بأول حرف شائع لأنواع الطرفيات المذكورة فيها. استخدم System V هذا المخطط. إذا كان ncurses مُهيأ لاستخدام قواعد بيانات مُجزّأة، فقد يُسمي TERMINFO موقعها، مثل /usr/share/terminfo.db، بدلاً من /usr/share/terminfo/.

قاعدة البيانات المُجزّأة تستخدم مساحة قرص أقل وتكون أسرع قليلاً من شجرة الأدلة. ومع ذلك، تفترض بعض التطبيقات وجود شجرة الأدلة وتقرأها مباشرةً، متجاهلة واجهة برمجة التطبيقات terminfo. إذا كان ncurses مُهيأ بدعم termcap، فقد يحتوي هذا المتغير على موقع ملف termcap. إذا بدأت قيمة TERMINFO بـ “hex:” أو “b64:”، يستخدم ncurses باقي القيمة كوصف terminfo مُجمّع. يمكنك إنتاج صيغة base64 باستخدام infocmp(1M).

            TERMINFO=$(infocmp -0 -Q2 -q)
            export TERMINFO

    يستخدم ncurses الوصف المُجمّع فقط إذا تطابق مع نوع الطرفية المُعرّف بواسطة TERM.

ضبط TERMINFO هو أبسط طريقة، ولكن ليست الوحيدة، لتوجيه ncurses إلى قاعدة بيانات طرفية. مسار البحث كما يلي. آخر قاعدة بيانات طرفية كتب إليها تطبيق ncurses الجاري، إن وُجدت الموقع المُحدد بواسطة متغير البيئة TERMINFO $HOME/.terminfo المواقع المُدرجة في متغير البيئة TERMINFO_DIRS location(s) configured and compiled into ncurses
    /usr/share/terminfo

  TERMINFO_DIRS
هذا المتغير يُحدد قائمة من المواقع، شبيهة بـ PATH، حيث يبحث ncurses عن أوصاف أنواع الطرفيات الموصوفة بواسطة TERMINFO أعلاه. عناصر القائمة مفصولة بنقطتين رأسيتين في Unix وفواصل منقوطة في OS/2 EMX. يفتقر System V terminfo إلى ميزة مقابلة؛ TERMINFO_DIRS هو امتداد لـ ncurses.

  TERMPATH
إذا لم يحتوِ TERMCAP على وصف لنوع طرفية أو اسم ملف، فإن ncurses يتحقق من محتويات TERMPATH، وهي قائمة مواقع، تشبه PATH، يبحث فيها عن أوصاف أنواع الطرفيات termcap. تُفصل عناصر القائمة بنقطتين رأسيتين في يونكس وفواصل منقوطة في OS/2 EMX.

إذا كان كل من TERMCAP و TERMPATH غير مُعيَّنين أو غير صالحين، فإن ncurses يبحث عن الملفات /etc/termcap و /usr/share/misc/termcap و $HOME/.termcap، بهذا الترتيب.

تهيئات بديلة
العديد من تهيئات ncurses المختلفة ممكنة، تُحددها الخيارات المُعطاة لسكريبت configure عند بناء المكتبة. شغّل السكريبت بالخيار --help لتصفحها جميعًا. القليل منها ذو أهمية خاصة لمطور التطبيقات الذي يستخدم ncurses.

--disable-overwrite
    تجنب تعارضات أسماء الملفات بين ncurses وتثبيت curses موجود على النظام. إدراج المعالج المسبق C القياسي لمكتبة curses يكون كالتالي.

            #include <curses.h>

    إذا تم تثبيت ncurses مع تعطيل الاستبدال، فإنه يضع ملفات الرأس الخاصة به في دليل فرعي. إليك مثال.

            #include <ncurses/curses.h>

    مع --disable-overwrite، يحذف التثبيت أيضًا رابطًا رمزيًا كان سيجعل خيار المترجم -lcurses يربط ملفات الكائن مع ncurses بدلاً من مكتبة النظام curses.

    الدليل المستخدم بواسطة هذه التهيئة لـ ncurses مُوضَّح في القسم “SYNOPSIS” أعلاه.

--enable-widec
    (مبدئي لـ ABI 6+ منذ 2023-10-21) فعّل دعم المحارف العريضة. سكريبت configure يعيد تسمية مكتبة ncurses (ومكتبة tinfo، إذا تم تحديد --with-termlib أيضًا)، بإلحاق “w”. تطبيق يرغب في دعم المحارف العريضة يستخدم بعد ذلك -lncursesw (أو -ltinfow) بدلاً من -lncurses (أو -ltinfo) كخيار رابط له. مكتبات ncurses++ و panel و form و menu يُعاد تسميتها بالمثل.

    يجب على التطبيق أيضًا تعريف رموز معينة للمعالج المسبق C لتفعيل ميزات المحارف العريضة في ملفات رأس curses لاستخدام الدوال الموسعة (ذات المحارف العريضة). الرمز الذي يُفعِّل هذه الميزات قد تغير منذ X/Open Curses Issue 4.
    في الأصل، كانت ميزة المحارف العريضة تتطلب الرمز _XOPEN_SOURCE_EXTENDED، لكن ذلك كان صالحًا فقط لـ XPG4 (1996). لاحقًا، اعتُبر ذلك متعارضًا مع قيمة _XOPEN_SOURCE البالغة 500. اعتبارًا من منتصف 2018، لا تتطلب أي ميزة من ncurses قيمة _XOPEN_SOURCE أكبر من 600. ومع ذلك، يوصي X/Open Curses Issue 7 (2009) بتعريفها على 700. بدلاً من ذلك، يمكنك تفعيل الميزة بتعريف NCURSES_WIDECHAR مع التحذير بأن بعض ملفات الرأس غير curses.h قد تتطلب قيمة محددة لـ _XOPEN_SOURCE (أو رمز خاص بالنظام).

    ملف الرأس curses.h المُثبَّت لمكتبة المحارف العريضة مصمم ليكون متوافقًا مع رأس المكتبة غير العريضة. يختلف فقط حجم بنية WINDOW؛ قليل من التطبيقات تتطلب أكثر من مؤشرات إلى WINDOW.

    إذا تم تثبيت ملفات رأس ncurses مع السماح بالاستبدال (المبدئي، لكن انظر --disable-overwrite أعلاه)، فيجب تثبيت رؤوس مكتبة المحارف العريضة أخيرًا بواسطة أنظمة التعبئة وما شابه، للسماح ببناء التطبيقات باستخدام أي من المكتبتين من نفس مجموعة الرؤوس.

--with-pthread
    يتيح دعم التطبيقات متعددة الخيوط. يُعيد سكريبت configure تسمية مكتبة ncurses (ومكتبة tinfo، إذا حُدد --with-termlib أيضًا)، مُلحقًا “t” (قبل أي “w” يُضاف بواسطة --enable-widec). يستخدم التطبيق الراغب في دعم خيوط تنفيذ متعددة، على سبيل المثال، -lncursest (أو -ltinfot) بدلاً من -lncurses (أو -ltinfo) كخيار رابط. تُعاد تسمية مكتبات ncurses++ وpanel وform وmenu بالمثل.

    تستبدل ncursest وncursestw المتغيرات العامة مثل LINES بوحدات ماكرو تسمح بالوصول للقراءة فقط. وفي الوقت نفسه، توفر دوالًا لتعيين هذه القيم. تتطلب تطبيقات قليلة جدًا تغييرات للعمل مع هذه الاتفاقية.

--with-shared
    --with-normal --with-debug --with-profile يُلزم بترجمة مكتبة ncurses (ومكتبة tinfo، إذا حُدد --with-termlib أيضًا) بالأشكال المحددة. تختلف أسماء المكتبات المشتركة والعادية (الثابتة) بلواحقها، كما هو الحال مع libncurses.so وlibncurses.a. تضيف مكتبات التصحيح والتنميط “_g” و“_p” إلى جذور هذه الأسماء على التوالي، مُشكلة libncurses_g.so وlibncurses_p.a، على سبيل المثال. تُتاح مكتبات ncurses++ وpanel وform وmenu بالمثل.

--with-termlib
    توفر دوال واجهة الطرفية منخفضة المستوى لـ ncurses (تلك التي لا تعتمد على تجريدات SCREEN وWINDOW) في مكتبة باسم tinfo. يُقلل هذا الترتيب من أوقات الربط و/أو التحميل للتطبيق عندما لا يحتاج إلى ميزات curses عالية المستوى.

    توثق الصفحات التالية دوال curses المقدمة من tinfo:
    curs_extend(3X) - إضافات ncurses متنوعة curs_inopts(3X) - خيارات إدخال curses curs_kernel(3X) - إجراءات curses منخفضة المستوى curs_termattrs(3X) - إجراءات استعلام بيئة curses curs_termcap(3X) - محاكاة curses لـ termcap curs_terminfo(3X) - واجهة curses لقاعدة بيانات terminfo curs_util(3X) - إجراءات أدوات curses متنوعة

--with-trace
    يكشف دالة curses_trace(3X) في المكتبات المشتركة والثابتة لـ ncurses(w). عادةً، تكون متاحة فقط في مكتبة التصحيح. (إذا حُدد --with-termlib أيضًا، توفر tinfo(w) بدلاً من ncurses(w) دالة trace(3X) المهملة.) يجب أن يتحقق سكريبت تهيئة التطبيق من وجود الدالة بدلاً من افتراض حصرها في مكتبة التصحيح.

الملفات

/usr/share/tabset
    قاعدة بيانات تهيئة علامات الجدولة

/usr/share/terminfo
    قاعدة بيانات قدرات طرفية مُجمَّعة

ملاحظات
يسمح X/Open Curses بتوفير معظم الدوال التي يحددها كوحدات ماكرو أيضًا. يفعل ncurses ذلك للدوال التي تُرجع قيمًا عبر معاملاتها، لدعم الميزات القديمة، لإعادة استخدام الدوال (مثلًا، تلك التي تُحرك المؤشر قبل عملية أخرى)، و في حالات خاصة قليلة.

إذا تم توجيه واصف ملف الإخراج القياسي لبرنامج ncurses إلى شيء ليس جهاز طرفية، تكتب المكتبة تحديثات الشاشة إلى واصف ملف الخطأ القياسي. كانت هذه ميزة غير موثقة لـ SVr3 curses.

انظر القسم الفرعي “ملفات الرأس” أدناه بخصوص الرموز المكشوفة بتضمين curses.h.

الامتدادات
يُمكّن ncurses التطبيق من التقاط أحداث الفأرة من أطراف معينة، بما في ذلك xterm(1)؛ انظر curs_mouse(3X).

يوفر ncurses وسيلة للاستجابة لأحداث تغيير حجم النافذة، كما هو الحال عند التشغيل في تطبيق محاكي طرفية واجهة مستخدم رسومية مثل xterm؛ انظر resizeterm(3X) و wresize(3X).

يسمح ncurses للتطبيق باستعلام الطرفية عن وجود مجموعة واسعة من المفاتيح الخاصة؛ انظر has_key(3X).

يوسع ncurses المجموعة الثابتة من قدرات مفاتيح الدوال المحددة بواسطة X/Open Curses بالسماح لمبرمج التطبيق بتعريف أحداث مفاتيح إضافية في وقت التشغيل؛ انظر define_key(3X)، key_defined(3X)، keybound(3X)، و keyok(3X).

يمكن لـ ncurses استغلال قدرات الأطراف التي تنفذ تسلسلات ISO 6429/ECMA-48 SGR 39 و SGR 49، والتي تسمح للتطبيق بإعادة تعيين الطرفية إلى ألوان المقدمة والخلفية الأصلية. من منظور المستخدم، يستطيع التطبيق رسم نص ملون على خلفية يُضبط لونها بشكل مستقل، مما يوفر تحكمًا أفضل في تباينات الألوان. انظر default_colors(3X).

يمكن لتطبيق ncurses تجنب معرفة تفاصيل بنية SCREEN و WINDOW الداخلية، واستخدام دوال الوصول مثل is_cbreak(3X) و is_scrollok(3X) بدلًا من ذلك.

يُمكّن ncurses التطبيق من توجيه مخرجاته إلى طابعة موصولة بجهاز الطرفية؛ انظر curs_print(3X).

يقدم ncurses slk_attr(3X) كمقابل لـ attr_get(3X) لخطوط مفاتيح التسمية الناعمة، و extended_slk_color(3X) كشكل من slk_color(3X) يمكنه جمع معلومات الألوان منها عند دعم العديد من الألوان.

يسمح ncurses بتعديل سلوك unctrl(3X)؛ انظر use_legacy_coding(3X).

قد يتوفر دعم أولي للتطبيقات متعددة الخيوط؛ انظر curs_threads(3X).

يمكن كشف دوال تُسهل إدارة الشاشات المتعددة؛ انظر curs_sp_funcs(3X).

لمساعدة التطبيقات في تصحيح استخدامها للذاكرة، يقدم ncurses اختياريًا دوالًا لتحرير الذاكرة التي يخصصها ديناميكيًا بشكل أكثر عدوانية؛ انظر curs_memleaks(3X).

تُسهل المكتبة تدقيق واستكشاف أخطاء سلوكها؛ انظر curs_trace(3X).

يؤدي تجميع ncurses مع الخيار -DUSE_GETCAP إلى الرجوع إلى قراءة /etc/termcap إذا لم يتمكن كود إعداد الطرفية من العثور على إدخال terminfo مطابق لـ TERM. لا يُوصى باستخدام هذه الميزة، لأنها تتضمن بشكل أساسي مُجمّع termcap كامل في كود بدء تشغيل ncurses، على حساب استهلاك الذاكرة وتأخير إطلاق التطبيق.

تدمج PDCurses و NetBSD curses بعض امتدادات ncurses. تشير صفحات الدليل الفردية إلى مكان حدوث ذلك.

القابلية للنقل
يُعرّف X/Open Curses مستويين من المطابقة، “أساسي” و “مُحسّن”. يتضمن الأخير عدة ميزات إضافية، مثل دعم الأحرف العريضة والألوان. يهدف ncurses إلى المطابقة على المستوى الأساسي مع X/Open Curses، ويدعم جميع ميزات مستواه المُحسّن باستثناء أداة untic.

تُوثّق الاختلافات بين X/Open Curses و ncurses في أقسام “قابلية النقل” من صفحات الدليل المنطبقة.

  التحقق من الأخطاء
في حالات عديدة، يكون X/Open Curses غامضًا بشأن حالات الخطأ، متجاهلاً بعض توثيق SVr4.

على عكس التطبيقات الأخرى، يتحقق ncurses من معاملات المؤشر، مثل تلك الخاصة بهياكل WINDOW، لضمان أنها ليست فارغة. يُفعل ذلك بشكل أساسي للحماية من أخطاء المبرمج. لا توفر الواجهة القياسية طريقة للمكتبة لإخبار التطبيق بأي من الأخطاء المحتملة حدث. يحد التطبيق الذي يعتمد على ncurses للتحقق من صحة معاملات دواله من قابلية نقله ومتانته.

  اختلافات الحشو
في تطبيقات curses التاريخية، فعّلت التأخيرات المضمنة في قدرات terminfo carriage_return (cr) و scroll_forward (ind) و cursor_left (cub1) و form_feed (ff) و tab (ht) بتات التأخير المقابلة في مشغل طرفية يونكس. يُنفذ ncurses كل الحشو بإرسال بايتات NUL إلى الجهاز. هذه الطريقة أغلى قليلاً، لكنها تضيّق الواجهة مع نواة يونكس بشكل كبير وتزيد من قابلية نقل الحزمة بالمقابل.

  ملفات الرأس
يتضمن ملف الرأس curses.h نفسه ملفي الرأس stdio.h و unctrl.h.

لدى X/Open Curses المزيد ليقوله،

    قد يُظهر تضمين curses.h جميع الرموز من الرؤوس stdio.h و term.h و termios.h و wchar.h.

لكنه لا يُكمل القصة. يلي ذلك شرح أكثر اكتمالاً. وفر أول curses، في 4BSD، ملف curses.h.

    ضمّن كود BSD curses ملفي curses.h و unctrl.h من ملف رأس داخلي curses.ext، حيث اختصر “ext” “externs”.

    استخدمت تطبيقات printw و scanw دوال داخلية غير موثقة لمكتبة الإدخال/الإخراج القياسية (_doprnt و _doscan)، لكن لم يعتمد أي شيء في curses.h نفسه على stdio.h. أضاف SVr2 curses الدالة newterm، التي تعتمد على stdio.h لأن نموذج دالتها يستخدم النوع FILE.

    أضاف SVr4 curses الدالتين putwin و getwin، اللتين تستخدمان أيضًا stdio.h.

    يحدد X/Open Curses هذه الدوال الثلاث جميعها.

    SVr4 curses و X/Open Curses لا تطلبان من المطور تضمين stdio.h قبل curses.h. كلاهما يوثق استخدام curses على أنه يتطلب فقط curses.h.

    ونتيجة لذلك، يتضمن curses.h القياسي دائمًا stdio.h. X/Open Curses و SVr4 curses غير متسقين فيما يتعلق بـ unctrl.h.

    كما ذُكر في curs_util(3X)، يتضمن ncurses unctrl.h من curses.h (كما تفعل SVr4). قد تشير تعليقات X/Open Curses حول term.h و termios.h إلى HP-UX و AIX.

    يتضمن HP-UX curses term.h من curses.h للإعلان عن setupterm في curses.h، لكن ncurses و Solaris curses لا يفعلان ذلك.

    يتضمن AIX curses term.h و termios.h. مرة أخرى، ncurses و Solaris curses لا يفعلان ذلك. يقول X/Open Curses أن curses.h قد يتضمن term.h، لكنه لا يطلب ذلك.

    تستخدم بعض البرامج دوال معلنة في كل من curses.h و term.h، ويجب تضمين كلا ملفي الرأس في نفس وحدة الترجمة.

    تتضمن ملفات الرأس المقدمة من ncurses رؤوس المكتبة القياسية المطلوبة لإعلاناتها، لذا يمكن تضمين ملفات رأس ncurses الخاصة بأي ترتيب. من أجل قابلية النقل حتى لأنظمة AIX القديمة، ضمّن curses.h قبل term.h. يقول X/Open Curses “قد يجعل مرئيًا” لأن تضمين ملف رأس لا يجعل بالضرورة جميع الرموز فيه مرئية (ضع في اعتبارك #ifdef وما شابه).

    على سبيل المثال، قد يتضمن curses.h الخاص بـ ncurses wchar.h إذا تم تعريف الرمز المناسب، وإذا تم تكوين ncurses لدعم الأحرف العريضة. إذا تم تضمين wchar.h، قد تُجعل رموزه مرئية اعتمادًا على قيمة ماكرو اختبار الميزة _XOPEN_SOURCE. يفرض X/Open Curses تضمين التطبيق لملف رأس واحد من مكتبة C القياسية في حالة خاصة: stdarg.h قبل curses.h لإنشاء نموذج أولي للدوال vw_printw و vw_scanw (بالإضافة إلى vwprintw و vwscanw القديمتين). تأخذ كل من هذه قائمة وسائط متغيرة، معامل va_list، مثل معامل printf(3).

    قدم SVr3 curses الدالتين القديمتين، وقدم X/Open Curses الباقي. في ما بين ذلك، وفر SVr4 curses إمكانية أن يتضمن التطبيق إما varargs.h أو stdarg.h. مثلت هذه نهجين متباينين لمعالجة قوائم الوسائط المتغيرة. استخدمت الواجهة الأقدم، varargs.h، مؤشرًا إلى char لمعامل va_list للدوال المتغيرة. لاحقًا، اكتسبت القائمة نوع بياناتها القياسي الخاص، va_list، المُعرّف في stdarg.h، مما مكّن المترجم من التحقق من أنواع المعاملات الفعلية لاستدعاء دالة مقابل تلك الرسمية المعلنة في نموذجها الأولي.

    لا تتطلب أي تطبيقات متوافقة مع X/Open Curses من التطبيق تضمين stdarg.h قبل curses.h لأنها إما سمحت بنوع خاص، أو، مثل ncurses، تضمن stdarg.h بنفسها لتوفير واجهة محمولة.

المؤلفون
زيد م. بن حليم، إريك س. ريموند، توماس إ. ديكي. استنادًا إلى pcurses بواسطة بافل كورتيس.

انظر أيضًا
curs_variables(3X)، terminfo(5)، user_caps(5)

ترجمة
تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي <zayed.alsaidi@gmail.com>

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: kde-l10n-ar@kde.org.