13.1.13.4.2. Điều khiển giá trị#

Đây là các điều khiển lưu một thiết lập. Mỗi cái mang một value, và Save ghi value đã chỉnh sửa trở lại điều khiển. Bảng bên dưới là bản đồ nhanh từ điều khiển tới kiểu JSON mà nó lưu; các phần tiếp theo tài liệu hóa từng khóa.

Điều khiển

Lưu

checkbox

boolean, hoặc số nguyên 0/1/2

combobox

giá trị được chọn, hoặc chỉ số của nó

radio

giá trị được chọn, hoặc chỉ số của nó

spinbox

số nguyên

doublespinbox

số (dấu phẩy động)

slider

số nguyên

lineedit

chuỗi

Tất cả các điều khiển giá trị cũng chấp nhận các khóa chung (name, label, tooltip, enabled); xem tổng quan. label được hiển thị bên cạnh điều khiển (trên chính hộp đối với checkbox).

13.1.13.4.2.1. checkbox#

Một công tắc bật/tắt. Tùy chọn ba trạng thái, dành cho các thiết lập có trạng thái "chưa đặt" ở giữa.

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

Đối số:

  • label (string) -- văn bản hiển thị bên cạnh ô. Chỉ văn bản thuần túy (khác với các điều khiển khác, có nhãn nhận văn bản định dạng).

  • tristate (boolean, mặc định false) -- cho phép một trạng thái thứ ba, đánh dấu một phần.

  • value -- trạng thái ban đầu. Hai trạng thái: một boolean. Ba trạng thái: 0 (tắt), 1 (một phần), hoặc 2 (bật).

Lưu: một boolean cho ô hai trạng thái; một số nguyên 0, 1, hoặc 2 cho ô ba trạng thái.

13.1.13.4.2.2. combobox#

Một menu thả xuống các lựa chọn.

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

Đối số:

  • options (mảng các chuỗi) -- các mục hiển thị trong menu.

  • values (array) -- một mảng song song tùy chọn của các giá trị để lưu, mỗi giá trị ứng với một option. Với values, menu hiển thị options[i] nhưng lưu values[i] -- nên người dùng thấy "QVGA" trong khi tệp lưu "qvga". Các mục có thể là bất kỳ kiểu JSON nào. Không có values, điều khiển lưu chỉ số của mục được chọn thay vào đó.

  • value -- lựa chọn ban đầu. Với values, mục bằng một trong các values. Không có values, chỉ số của mục cần chọn (mặc định 0).

Lưu: mục values khớp (bất kỳ kiểu nào) khi values được cung cấp; nếu không thì chỉ số được chọn (số nguyên).

13.1.13.4.2.3. radio#

Một tập hợp các nút radio -- một lựa chọn hiển thị tại một thời điểm, giống như một combobox nhưng được bố trí đầy đủ.

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

Đối số:

  • options (mảng các chuỗi) -- một nút cho mỗi mục.

  • values (array) -- các giá trị tùy chọn để lưu, mỗi giá trị ứng với một option, chính xác như với combobox. Không có nó, điều khiển lưu chỉ số được chọn.

  • value -- lựa chọn ban đầu, được khớp với values hoặc dùng làm chỉ số, như với combobox.

  • orientation (string, mặc định "vertical") -- "horizontal" để bố trí các nút thành một hàng, nếu không thì thành một cột.

Lưu: mục values khớp (bất kỳ kiểu nào), hoặc chỉ số được chọn.

13.1.13.4.2.4. spinbox#

Một ô số cho các số nguyên, với các mũi tên lên/xuống.

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

Đối số:

  • value (số nguyên, mặc định 0) -- con số ban đầu.

  • min (số nguyên, mặc định 0 hoặc value, cái nào nhỏ hơn) -- giá trị thấp nhất được phép.

  • max (số nguyên, mặc định 100 hoặc value, cái nào lớn hơn) -- giá trị cao nhất được phép.

  • step (số nguyên, mặc định 1) -- bước tăng/giảm lên/xuống.

  • prefix (string) -- văn bản hiển thị trước con số, ví dụ "0x".

  • suffix (string) -- văn bản hiển thị sau con số, ví dụ một đơn vị như " px".

  • base (số nguyên, mặc định 10) -- cơ số hiển thị; đặt thành 16 để hiển thị và chỉnh sửa con số theo hệ thập lục phân.

  • group_separator (boolean, mặc định false) -- nhóm các chữ số bằng dấu phân cách hàng nghìn.

  • special_value_text (string) -- văn bản để hiển thị thay cho con số khi nó ở mức min, ví dụ hiển thị "Off" tại 0.

Lưu: một số nguyên.

13.1.13.4.2.5. doublespinbox#

Một ô số cho các số thập phân.

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

Đối số:

  • value (số, mặc định 0) -- con số ban đầu.

  • min (số, mặc định 0 hoặc value, cái nào nhỏ hơn) -- giá trị thấp nhất được phép.

  • max (số, mặc định 100 hoặc value, cái nào lớn hơn) -- giá trị cao nhất được phép.

  • decimals (số nguyên, mặc định 2) -- số chữ số hiển thị sau dấu thập phân.

  • step (số, mặc định 1.0) -- bước tăng/giảm lên/xuống.

  • prefix (string) -- văn bản hiển thị trước con số, ví dụ "max ".

  • suffix (string) -- văn bản hiển thị sau con số, ví dụ một đơn vị như " %".

  • group_separator (boolean, mặc định false) -- dấu phân cách hàng nghìn.

  • special_value_text (string) -- văn bản để hiển thị khi con số ở mức min.

Lưu: một số (dấu phẩy động).

13.1.13.4.2.6. slider#

Một slider ngang với một giá trị số hiển thị trực tiếp bên cạnh nó.

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

Đối số:

  • value (số nguyên, mặc định 0) -- vị trí ban đầu.

  • min (số nguyên, mặc định 0 hoặc value, cái nào nhỏ hơn) -- đầu thấp của thanh trượt.

  • max (số nguyên, mặc định 100 hoặc value, cái nào lớn hơn) -- đầu cao của thanh trượt.

  • step (số nguyên, mặc định 1) -- bước tăng khi dùng bàn phím và kéo; kéo sẽ bắt vào bội số gần nhất.

  • prefix (string) -- văn bản hiển thị trước giá trị số bên cạnh slider, ví dụ "x".

  • suffix (string) -- văn bản hiển thị sau giá trị số, ví dụ " %".

  • ticks (số nguyên) -- khoảng cách giữa các vạch chia được vẽ dưới thanh trượt.

Lưu: một số nguyên.

13.1.13.4.2.7. lineedit#

Một trường văn bản một dòng, dành cho tên, mật khẩu, địa chỉ, và những thứ tương tự.

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

Đối số:

  • value (string, mặc định "") -- văn bản ban đầu.

  • placeholder (string) -- văn bản gợi ý màu xám hiển thị khi trường trống.

  • max_length (số nguyên) -- số ký tự tối đa mà trường sẽ chấp nhận.

  • mask (string) -- một mặt nạ nhập liệu cố định bố cục của những gì có thể được gõ, ví dụ "000.000.000.000;_" cho một địa chỉ IPv4. Xem Input masks bên dưới.

  • regex (string) -- một biểu thức chính quy mà toàn bộ nội dung nhập vào phải khớp. Xem Regular expressions bên dưới.

  • clear_button (boolean, mặc định false) -- hiển thị một nút xóa nhỏ bên trong trường.

  • password (boolean, mặc định false) -- ẩn văn bản dưới dạng các dấu chấm và thêm một nút hình con mắt để hiện nó ra.

Lưu: một chuỗi.

Một mask và một regex đều hạn chế những gì trường sẽ chấp nhận, từ hai góc độ đối lập -- mask cố định bố cục của văn bản, regex ràng buộc nội dung của nó. Một trường có một trong hai là điều khiển duy nhất có thể chặn một lần Save: nếu văn bản của nó chưa hoàn chỉnh hoặc không khớp, trình chỉnh sửa liệt kê trường theo label của nó và từ chối lưu cho đến khi nó được sửa hoặc xóa. Chỉ dùng nhiều nhất một trong hai trên một trường.

13.1.13.4.2.7.1. Mặt nạ nhập liệu#

Một mask cố định trường theo từng ký tự: các dấu phân cách được vẽ sẵn cho người dùng, người chỉ điền vào các chỗ trống. Mỗi ký tự mặt nạ đại diện cho một vị trí nhập liệu:

  • 9 -- một chữ số bắt buộc; 0 -- một chữ số tùy chọn.

  • A / a -- một chữ cái bắt buộc / tùy chọn.

  • N / n -- một chữ cái hoặc chữ số bắt buộc / tùy chọn.

  • X / x -- một ký tự bất kỳ loại nào, bắt buộc / tùy chọn.

  • H / h -- một chữ số thập lục phân bắt buộc / tùy chọn.

  • > / < -- viết hoa / viết thường các chữ cái tiếp theo; ! dừng việc chuyển đổi.

Bất kỳ ký tự nào khác -- dấu . trong 000.000.000.000, một dấu - trong một số sê-ri -- là một dấu phân cách theo nghĩa đen: nó được đặt tự động và được bỏ qua khi người dùng gõ. Để dùng một ký tự mặt nạ theo nghĩa đen, hãy đặt một dấu gạch chéo ngược phía trước nó.

Một dấu ; gần cuối đặt ký tự giữ chỗ hiển thị cho các vị trí chưa được điền: "000.000.000.000;_" hiển thị một trường trống dưới dạng ___.___.___.___. Bỏ nó đi thì các chỗ trống là các khoảng trắng. Trong khi bất kỳ vị trí bắt buộc nào vẫn còn trống thì nội dung nhập vào là chưa hoàn chỉnh, điều này chặn Save.

13.1.13.4.2.7.2. Biểu thức chính quy#

Một regex kiểm tra nội dung thay vì bố cục, và phù hợp hơn khi quy tắc là "những ký tự này, mẫu này" thay vì một trường cố định. Toàn bộ nội dung nhập vào phải khớp -- biểu thức được neo ở cả hai đầu, nên "[A-Za-z0-9-]+" có nghĩa là chỉ các chữ cái, chữ số, và dấu gạch ngang từ đầu tới cuối, không đơn thuần là "có chứa một cái".

Việc kiểm tra chạy trên mỗi lần gõ phím. Một ký tự được chấp nhận miễn là văn bản vẫn có thể phát triển thành một khớp hoàn chỉnh, và bị từ chối ngay khi nó không thể, nên người dùng không bao giờ có thể gõ đến một thứ không hợp lệ. Trường được coi là hợp lệ -- và Save được phép -- chỉ khi toàn bộ biểu thức khớp; một nội dung nhập một phần trên đường tới đó vẫn được giữ nguyên nhưng chặn Save cho đến khi nó hoàn chỉnh.

Để xây dựng và kiểm tra một mẫu, regex101.com giải thích từng phần khi bạn gõ -- đặt phiên bản cú pháp của nó thành PCRE2, cú pháp mà trình chỉnh sửa sử dụng.