13.1.13.4.2. عناصر التحكم القيمية#

هذه هي عناصر التحكم التي تحمل إعدادًا. يحمل كل منها value، ويكتب الحفظ القيمة value المحرَّرة مرة أخرى في عنصر التحكم. والجدول أدناه هو الخريطة السريعة من عنصر التحكم إلى نوع JSON الذي يخزّنه؛ وتوثّق الأقسام التالية كل مفتاح.

عنصر التحكم

يحفظ

checkbox

قيمة منطقية، أو عدد صحيح 0/1/2

combobox

القيمة المختارة، أو فهرسها

radio

القيمة المختارة، أو فهرسها

spinbox

عدد صحيح

doublespinbox

رقم (فاصلة عائمة)

slider

عدد صحيح

lineedit

سلسلة نصية

تقبل جميع عناصر التحكم بالقيم أيضاً المفاتيح المشتركة ( name ، label ، tooltip ، enabled )؛ انظر نظرة عامة . يظهر label بجوار عنصر التحكم (على المربع نفسه في حالة checkbox ).

13.1.13.4.2.1. checkbox#

مفتاح تشغيل/إيقاف. ويمكن اختياريًا جعله ثلاثي الحالات، للإعدادات التي لها حالة وسطى "غير محددة".

{ "type": "checkbox", "name": "draw_overlays", "label": "Draw Overlays", "value": true }

الوسائط:

  • label (سلسلة نصية) -- النص المعروض بجوار الصندوق. نص عادي فقط (على عكس عناصر التحكم الأخرى التي تأخذ تسمياتها نصًا منسّقًا).

  • tristate (قيمة منطقية، الافتراضي false) -- السماح بحالة ثالثة محددة جزئيًا.

  • value -- الحالة الأولية. ثنائي الحالة: قيمة منطقية. ثلاثي الحالات: 0 (إيقاف)، أو 1 (جزئي)، أو 2 (تشغيل).

يحفظ: قيمة منطقية للصندوق ثنائي الحالة؛ وعددًا صحيحًا 0 أو 1 أو 2 للصندوق ثلاثي الحالات.

13.1.13.4.2.2. combobox#

قائمة منسدلة من الخيارات.

{
  "type": "combobox",
  "name": "resolution",
  "label": "Resolution",
  "options": ["QQVGA", "QVGA", "VGA"],
  "values": ["qqvga", "qvga", "vga"],
  "value": "qvga"
}

الوسائط:

  • options (مصفوفة من السلاسل النصية) -- العناصر المعروضة في القائمة.

  • values (مصفوفة) -- مصفوفة موازية اختيارية للقيم المراد حفظها، واحدة لكل option. مع values، تعرض القائمة options[i] لكنها تحفظ values[i] -- فيرى المستخدم "QVGA" بينما يخزّن الملف "qvga". ويمكن أن تكون العناصر من أي نوع JSON. وبدون values، يحفظ عنصر التحكم فهرس العنصر المحدد بدلًا من ذلك.

  • value -- التحديد الأولي. مع values، العنصر المساوي لأحد قيم values. وبدون values، فهرس العنصر المراد تحديده (الافتراضي 0).

يحفظ: عنصر values المطابق (أي نوع) عند إعطاء values؛ وإلا فـ**الفهرس** المحدد (عدد صحيح).

13.1.13.4.2.3. radio#

مجموعة من أزرار الاختيار -- يظهر خيار واحد في كل مرة، مثل combobox لكن معروضة بالكامل.

{
  "type": "radio",
  "name": "mode",
  "label": "Mode",
  "options": ["Idle", "Track", "Record"],
  "values": ["idle", "track", "record"],
  "value": "idle",
  "orientation": "horizontal"
}

الوسائط:

  • options (مصفوفة من السلاسل النصية) -- زر واحد لكل عنصر.

  • values (مصفوفة) -- القيم الاختيارية المراد حفظها، واحدة لكل option، تمامًا كما في combobox. وبدونها، يحفظ عنصر التحكم الفهرس المحدد.

  • value -- التحديد الأولي، يُطابق مع values أو يُستخدم كفهرس، كما في combobox.

  • orientation (سلسلة نصية، الافتراضي "vertical") -- "horizontal" لترتيب الأزرار في صف، وإلا ففي عمود.

يحفظ: عنصر values المطابق (أي نوع)، أو الفهرس المحدد.

13.1.13.4.2.4. spinbox#

صندوق أرقام للأعداد الصحيحة، مع سهمي أعلى/أسفل.

{
  "type": "spinbox",
  "name": "server_port",
  "label": "Port",
  "value": 8080,
  "min": 0,
  "max": 65535,
  "group_separator": true
}

الوسائط:

  • value (عدد صحيح، الافتراضي 0) -- الرقم الأولي.

  • min (عدد صحيح، الافتراضي 0 أو value، أيهما أصغر) -- أدنى قيمة مسموح بها.

  • max (عدد صحيح، الافتراضي 100 أو value، أيهما أكبر) -- أعلى قيمة مسموح بها.

  • step (عدد صحيح، الافتراضي 1) -- مقدار الزيادة/النقصان لأعلى/لأسفل.

  • prefix (سلسلة نصية) -- نص معروض قبل الرقم، مثل "0x".

  • suffix (سلسلة نصية) -- نص يظهر بعد الرقم، مثل وحدة مثل " px" .

  • base (عدد صحيح، الافتراضي 10) -- أساس العرض؛ اضبطه على 16 لعرض الرقم وتحريره بالنظام الست عشري.

  • group_separator (قيمة منطقية، الافتراضي false) -- تجميع الأرقام بفواصل الآلاف.

  • special_value_text (سلسلة نصية) -- نص يُعرض بدلًا من الرقم عندما يكون عند min، مثل عرض "Off" عند 0.

يحفظ: عددًا صحيحًا.

13.1.13.4.2.5. doublespinbox#

صندوق أرقام للأعداد العشرية.

{
  "type": "doublespinbox",
  "name": "sensitivity",
  "label": "Sensitivity",
  "value": 50.0,
  "min": 0,
  "max": 100,
  "step": 0.5,
  "decimals": 1,
  "suffix": " %"
}

الوسائط:

  • value (رقم، الافتراضي 0) -- الرقم الأولي.

  • min (رقم، الافتراضي 0 أو value، أيهما أصغر) -- أدنى قيمة مسموح بها.

  • max (رقم، الافتراضي 100 أو value، أيهما أكبر) -- أعلى قيمة مسموح بها.

  • decimals (عدد صحيح، الافتراضي 2) -- عدد الأرقام المعروضة بعد الفاصلة العشرية.

  • step (رقم، الافتراضي 1.0) -- مقدار الزيادة/النقصان لأعلى/لأسفل.

  • prefix (سلسلة نصية) -- نص معروض قبل الرقم، مثل "max ".

  • suffix (سلسلة نصية) -- نص يظهر بعد الرقم، مثل وحدة مثل " %" .

  • group_separator (قيمة منطقية، الافتراضي false) -- فواصل الآلاف.

  • special_value_text (سلسلة نصية) -- نص يُعرض عندما يكون الرقم عند min.

يحفظ: رقمًا (فاصلة عائمة).

13.1.13.4.2.6. slider#

شريط تمرير أفقي مع قراءة رقمية حية بجانبه.

{
  "type": "slider",
  "name": "brightness",
  "label": "Brightness",
  "value": 50,
  "min": 0,
  "max": 100,
  "step": 1,
  "suffix": " %",
  "ticks": 25
}

الوسائط:

  • value (عدد صحيح، الافتراضي 0) -- الموضع الأولي.

  • min (عدد صحيح، الافتراضي 0 أو value، أيهما أصغر) -- الطرف الأدنى من المسار.

  • max (عدد صحيح، الافتراضي 100 أو value، أيهما أكبر) -- الطرف الأعلى من المسار.

  • step (عدد صحيح، الافتراضي 1) -- مقدار الزيادة بلوحة المفاتيح والسحب؛ ويلتقط السحب إلى أقرب مضاعف.

  • prefix (سلسلة نصية) -- نص معروض قبل القراءة الرقمية بجانب الشريط، مثل "x".

  • suffix (سلسلة نصية) -- نص معروض بعد القراءة، مثل " %".

  • ticks (عدد صحيح) -- تباعد علامات التدريج المرسومة أسفل المسار.

يحفظ: عددًا صحيحًا.

13.1.13.4.2.7. lineedit#

حقل نصي من سطر واحد، للأسماء وكلمات المرور والعناوين وما شابه.

{
  "type": "lineedit",
  "name": "hostname",
  "label": "Hostname",
  "value": "openmv-cam",
  "placeholder": "letters, digits, dashes",
  "regex": "[A-Za-z0-9-]+",
  "clear_button": true
}

الوسائط:

  • value (سلسلة نصية، الافتراضي "") -- النص الأولي.

  • placeholder (سلسلة نصية) -- نص تلميح رمادي يُعرض ما دام الحقل فارغًا.

  • max_length (عدد صحيح) -- أقصى عدد من الأحرف يقبله الحقل.

  • mask (سلسلة نصية) -- قناع إدخال يثبّت تخطيط ما يمكن كتابته، مثل "000.000.000.000;_" لعنوان IPv4. راجع Input masks أدناه.

  • regex (سلسلة نصية) -- تعبير نمطي يجب أن يطابقه الإدخال بأكمله. راجع Regular expressions أدناه.

  • clear_button (قيمة منطقية، الافتراضي false) -- عرض زر مسح صغير داخل الحقل.

  • password (قيمة منطقية، الافتراضي false) -- إخفاء النص على شكل نقاط وإضافة زر عين لكشفه.

يحفظ: سلسلة نصية.

يقيّد كل من mask و*regex* ما يقبله الحقل، لكن من زاويتين متعاكستين -- فالقناع يثبّت تخطيط النص، والتعبير النمطي يقيّد محتواه. والحقل المزوّد بأحدهما هو عنصر التحكم الوحيد الذي يمكنه منع الحفظ: فإن كان نصه غير مكتمل أو غير مطابق، يدرج المحرر الحقل بحسب label الخاص به ويرفض الحفظ حتى يُصلَح أو يُمسَح. استخدم واحدًا فقط من الاثنين في الحقل الواحد كحد أقصى.

13.1.13.4.2.7.1. أقنعة الإدخال#

يثبّت mask الحقل حرفًا بحرف: تُرسم الفواصل للمستخدم الذي يملأ الفراغات فقط. ويمثّل كل حرف من القناع موضع إدخال واحدًا:

  • 9 -- رقم مطلوب؛ 0 -- رقم اختياري.

  • A / a -- حرف مطلوب / اختياري.

  • N / n -- حرف أو رقم مطلوب / اختياري.

  • X / x -- حرف من أي نوع مطلوب / اختياري.

  • H / h -- رقم ست عشري مطلوب / اختياري.

  • > / < -- تحويل الأحرف التالية إلى كبيرة / صغيرة؛ و``!`` يوقف التحويل.

أي حرف آخر -- كالنقطة . في 000.000.000.000، أو الشرطة - في رقم تسلسلي -- هو فاصل حرفي: يُوضع تلقائيًا ويُتخطّى أثناء كتابة المستخدم. ولاستخدام حرف قناع كحرف حرفي، ضع شرطة مائلة عكسية أمامه.

الفاصلة المنقوطة ; قرب النهاية تحدد العنصر النائب المعروض للمواضع غير المملوءة: فـ``"000.000.000.000;_"`` يعرض الحقل الفارغ على شكل ___.___.___.___. واتركها فيصبح الفراغ مسافات. وما دام أي موضع مطلوب لا يزال فارغًا يكون الإدخال غير مكتمل، مما يمنع الحفظ.

13.1.13.4.2.7.2. التعبيرات النمطية#

يفحص regex المحتوى لا التخطيط، وهو الأنسب عندما تكون القاعدة "هذه الأحرف، هذا النمط" بدلًا من حقل ثابت. ويجب أن يطابق الإدخال بأكمله -- إذ يكون التعبير مثبّتًا عند الطرفين، لذا فإن "[A-Za-z0-9-]+" يعني فقط الأحرف والأرقام والشرطات من البداية إلى النهاية، وليس مجرد "يحتوي على واحد".

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

لبناء نمط واختباره، يشرح regex101.com كل جزء أثناء كتابتك -- اضبط نكهته على PCRE2، وهي الصيغة التي يستخدمها المحرر.