13.1.13.4.2. פקדי ערך#

אלה הפקדים שמחזיקים הגדרה. כל אחד נושא value, ו-Save כותב את ה-value הערוך בחזרה אל הפקד. הטבלה שלהלן היא המפה המהירה מפקד אל סוג ה-JSON שהוא מאחסן; הסעיפים שלאחר מכן מתעדים כל מפתח.

פקד

נשמר

checkbox

בוליאני, או מספר שלם 0/1/2

combobox

הערך הנבחר, או האינדקס שלו

radio

הערך הנבחר, או האינדקס שלו

spinbox

מספר שלם

doublespinbox

מספר (נקודה צפה)

slider

מספר שלם

lineedit

מחרוזת

כל פקדי הערך מקבלים גם את המפתחות המשותפים ( name , label , tooltip , enabled ); ראו את overview . התווית 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 מגבילים את מה שהשדה יקבל, מזוויות מנוגדות – מסכה מקבעת את הפריסה של הטקסט, ביטוי רגולרי מגביל את התוכן שלו. שדה עם אחד מהם הוא הפקד היחיד שיכול לחסום Save: אם הטקסט שלו חלקי או אינו תואם, העורך מפרט את השדה לפי ה-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;_" מציג שדה ריק כ-___.___.___.___. השמיטו אותו והמקומות הריקים יהיו רווחים. כל עוד מיקום נדרש כלשהו עדיין ריק, הקלט חלקי, מה שחוסם Save.

13.1.13.4.2.7.2. ביטויים רגולריים#

regex בודק תוכן ולא פריסה, והוא ההתאמה הטובה יותר כאשר הכלל הוא ”התווים הללו, התבנית הזו“ ולא שדה קבוע. כל הקלט חייב להתאים – הביטוי מעוגן בשני הקצוות, כך ש-"[A-Za-z0-9-]+" פירושו רק אותיות, ספרות ומקפים מההתחלה ועד הסוף, לא סתם ”מכיל אחד“.

הבדיקה רצה בכל הקשה. תו מתקבל כל עוד הטקסט עדיין יכול לגדול להתאמה מלאה, ונדחה ברגע שאינו יכול, כך שהמשתמש לעולם אינו יכול להקליד את דרכו למשהו לא תקין. השדה נחשב תקין – ו-Save מותר – רק לאחר שכל הביטוי מתאים; קלט חלקי בדרך לשם נשאר במקומו אך חוסם Save עד שהוא שלם.

כדי לבנות ולבדוק תבנית, regex101.com מסביר כל חלק תוך כדי הקלדה – הגדירו את הגרסה שלו ל-PCRE2, התחביר שבו העורך משתמש.