form — u_pbt_form #

← Referência dos componentes · Índice do guia

form é um ecrã de introdução de dados inteiro em um só controlo: campos tipados — texto, número, lista, botões de opção, data, hora, cor, caixa de verificação, palavra-passe, e-mail, texto longo, imagem, etiquetas, estrelas — dispostos em colunas e em secções que se recolhem, cada um com o seu rótulo que sobe para a margem. As regras de cada campo (obrigatório, limites, padrão, máscara…) e os seus erros de negócio verificam-se em conjunto; of_is_dirty diz o que mudou desde o carregamento, of_load_row / of_save_row leem e escrevem uma linha de DataWindow. O seu próprio botão OK chama of_validate.

▶ Ver ao vivo — Aplicação de demonstração, mosaico Form: a pré-visualização, o código que o produz e esta página, lado a lado.

Em resumo #

Início rápido #

// Two columns ; a name at the top, then a section
uo_form.ii_columns = 2
uo_form.of_add_field(/*keys*/ "name", /*label*/ "Name", /*type*/ u_pbt_form.TYPE_STRING, /*value*/ "")
uo_form.of_field(/*keys*/ "name").ib_required = true
uo_form.of_add_section(/*key*/ "order", /*title*/ "Order")
uo_form.of_add_field(/*keys*/ "order/qty", /*label*/ "Quantity", /*type*/ u_pbt_form.TYPE_NUMBER, /*value*/ "1")
uo_form.of_add_field(/*keys*/ "order/due", /*label*/ "Due on", /*type*/ u_pbt_form.TYPE_DATE, /*value*/ "")

// event clicked of cb_ok
// Local variables
n_pbt_json lnv_json

// Every error shown at once, the keyboard on the first
if uo_form.of_validate() > 0 then return

// Valid : read the values, typed, along the same addresses
lnv_json.of_load(/*json*/ uo_form.of_values())
of_save_order(lnv_json.of_get_string(/*path*/ "name"), lnv_json.of_get_number(/*path*/ "order/qty"))

Um endereço por campo #

Um campo designa-se pelo seu endereço: a sua chave sozinha no primeiro nível ("name"), a secção e depois o campo unidos por / dentro de uma secção ("order/qty") — um nível, nunca mais. Uma secção designa-se pela sua chave sozinha. No primeiro nível, uma chave nomeia uma única coisa: uma secção e um campo de cima não a podem partilhar. Os eventos levam o mesmo endereço, o que escreveu; a chave de um campo (o seu último nível) é também o nome da coluna que of_load_row e of_save_row leem.

// A section by its key, a field by its address
uo_form.of_section(/*key*/ "order").ib_collapsed = true
uo_form.of_field(/*keys*/ "order/qty").is_value = "3"

Os tipos de campo #

O tipo escolhe-se uma vez, em of_add_field, e dá o controlo. O valor, esse, é sempre texto — dado, lido, entregue pelos eventos — escrito da mesma forma qualquer que seja a língua do posto. Uma lista, uma data e uma cor abrem-se nas janelas nativas partilhadas por toda a biblioteca, com as cores do tema.

A validação #

Cada campo leva as suas regras: ib_required (uma caixa obrigatória tem de estar assinalada), is_min / is_max (um número, uma data, uma hora), ii_max_length, is_pattern (uma expressão regular que o valor inteiro deve seguir), is_mask (uma máscara preenchida), is_match (igual a outro campo), e a forma de um e-mail, de um número ou de uma hora. A sua aplicação acrescenta os seus erros de negócio (is_error: já existe), que ficam até o utilizador alterar o campo. Nada aparece a vermelho enquanto o utilizador não tiver saído de um campo: um formulário novo não está a vermelho. of_is_valid e of_invalid_keys respondem sem mostrar nada; of_validate mostra tudo de uma vez e põe o teclado no primeiro campo com erro. Um campo oculto, desativado ou só de leitura não é julgado pelas suas regras: o utilizador não o poderia corrigir.

// A customer code : two capital letters, then four digits
uo_form.of_field(/*keys*/ "code").is_pattern = "[A-Z]{2}[0-9]{4}"
uo_form.of_field(/*keys*/ "code").is_pattern_message = "Two capital letters, then four digits"

// A rule only your database knows
if of_email_taken(uo_form.of_field(/*keys*/ "email").is_value) then
    uo_form.of_field(/*keys*/ "email").is_error = "Already used by another customer"
end if

Propriedades #

Propriedades de uma secção — n_pbt_form_section #

Propriedades de um campo — n_pbt_form_field #

Métodos #

No componente #

Numa secção e num campo #

Uma secção contém campos; uma lista ou botões de opção contêm as suas opções, designadas pelo seu valor. Os três métodos percorrem-nos.

Eventos #

Teclado e rato #

Exemplos #

Uma ficha de cliente #

// The whole form in one paint, two columns
uo_form.of_set_redraw(/*on*/ false)
uo_form.ii_columns = 2

// Identity : two required names, an e-mail, a phone with its mask
uo_form.of_add_section(/*key*/ "identity", /*title*/ "Identity")
uo_form.of_add_field(/*keys*/ "identity/first_name", /*label*/ "First name", /*type*/ u_pbt_form.TYPE_STRING, /*value*/ "")
uo_form.of_field(/*keys*/ "identity/first_name").ib_required = true
uo_form.of_add_field(/*keys*/ "identity/last_name", /*label*/ "Last name", /*type*/ u_pbt_form.TYPE_STRING, /*value*/ "")
uo_form.of_field(/*keys*/ "identity/last_name").ib_required = true
uo_form.of_add_field(/*keys*/ "identity/email", /*label*/ "E-mail", /*type*/ u_pbt_form.TYPE_EMAIL, /*value*/ "")
uo_form.of_add_field(/*keys*/ "identity/phone", /*label*/ "Phone", /*type*/ u_pbt_form.TYPE_STRING, /*value*/ "")
uo_form.of_field(/*keys*/ "identity/phone").is_mask = "(###) ###-####"

// Account : a credit limit with a bound, shown as a price and typed without the
// dollar sign ; a list ; a switch
uo_form.of_add_section(/*key*/ "account", /*title*/ "Account")
uo_form.of_add_field(/*keys*/ "account/credit_limit", /*label*/ "Credit limit", /*type*/ u_pbt_form.TYPE_NUMBER, /*value*/ "2500")
uo_form.of_field(/*keys*/ "account/credit_limit").is_format = "$#,##0.00"
uo_form.of_field(/*keys*/ "account/credit_limit").is_max = "50000"
uo_form.of_add_field(/*keys*/ "account/country", /*label*/ "Country", /*type*/ u_pbt_form.TYPE_ENUM, /*value*/ "gb")
uo_form.of_add_option(/*keys*/ "account/country", /*value*/ "gb", /*text*/ "United Kingdom")
uo_form.of_add_option(/*keys*/ "account/country", /*value*/ "fr", /*text*/ "France")
uo_form.of_add_field(/*keys*/ "account/vip", /*label*/ "VIP customer", /*type*/ u_pbt_form.TYPE_BOOLEAN, /*value*/ "false")

// Shown at once, the keyboard on the first field
uo_form.of_set_redraw(/*on*/ true)
uo_form.of_focus_field(/*keys*/ "identity/first_name")

Editar uma linha de DataWindow #

A chave de cada campo é o nome da sua coluna: o formulário lê a linha, o utilizador altera-a, o formulário escreve-a.

// The current row of dw_customers fills the form ; nothing is dirty yet
uo_form.of_load_row(/*data*/ dw_customers, /*row*/ dw_customers.GetRow())

// event clicked of cb_save
if uo_form.of_validate() > 0 then return

// Write the values back into the row, then save it
if uo_form.of_save_row(/*data*/ dw_customers, /*row*/ dw_customers.GetRow()) < 0 then
    MessageBox("Save", uo_form.of_get_last_error())
    return
end if

// Saved : what is on screen is the new reference
if dw_customers.Update() = 1 then
    COMMIT USING SQLCA;
    uo_form.of_reset_update()
end if

Etiquetas e estrelas #

Uma avaliação de um produto: uma nota em cinco com meias estrelas, e etiquetas livres com sugestões. Os dois valores continuam a ser texto, que of_save_row escreve numa coluna numérica e numa coluna de texto.

// Local variables
string ls_score, ls_tags

// The score : five stars, half stars set BEFORE a half value
uo_form.of_add_field(/*keys*/ "score", /*label*/ "Overall", /*type*/ u_pbt_form.TYPE_RATING, /*value*/ "")
uo_form.of_field(/*keys*/ "score").ib_half_stars = true
uo_form.of_field(/*keys*/ "score").is_value = "3.5"

// Tags : free text, the options are suggestions, five at most
uo_form.of_add_field(/*keys*/ "tags", /*label*/ "Tags", /*type*/ u_pbt_form.TYPE_TAGS, /*value*/ "office, led")
uo_form.of_add_option(/*keys*/ "tags", /*value*/ "eco", /*text*/ "Eco-friendly")
uo_form.of_add_option(/*keys*/ "tags", /*value*/ "usb", /*text*/ "USB powered")
uo_form.of_field(/*keys*/ "tags").ii_max_tags = 5

// Read back : "3.5" and "office, led"
ls_score = uo_form.of_field(/*keys*/ "score").is_value
ls_tags = uo_form.of_field(/*keys*/ "tags").is_value

Avisar antes de perder alterações #

// event closequery of the window
if not uo_form.of_is_dirty() then return 0

// Changes since the load : ask, and put them back if the user gives up
if MessageBox("Customer", "Discard your changes ?", Question!, YesNo!) = 2 then return 1
uo_form.of_revert()
return 0

Boas práticas #

• Um valor é um texto: um número escreve-se com ponto ("12.5"), um booleano "true"/"false", uma cor String(RGB(…)), uma data "yyyy-mm-dd", uma hora "hh:mm" — qualquer que seja a língua do posto. Para valores tipados, of_values e n_pbt_json.
• O seu botão OK decide: of_validate mostra os erros e devolve o seu número; o formulário não grava nada sozinho.
• Dê aos campos o nome das colunas: of_load_row e of_save_row fazem então todo o trabalho; senão, is_column nomeia a coluna de um campo.
• ib_readonly em vez de ib_enabled = false para um valor que o utilizador deve ler: um texto só de leitura seleciona-se e copia-se.
• Modo de demonstração: sem chave, o formulário desenha 6 campos, os primeiros mostrados pela ordem do ecrã — um campo de uma secção recolhida também conta, expandi-la não redesenha nada; os outros ficam em memória e em of_values, mas não são desenhados nem julgados (ver Licença).

Herdado da base comum #

Estes membros existem em todos os componentes visuais — não são próprios deste. São detalhados uma só vez, nos capítulos transversais; esta tabela apenas diz onde os ler.

Duas ajudas não são herdadas: of_icon e of_escape_markup vivem em n_pbt_utils. Declare um — n_pbt_utils lnv_utils, nada a criar — e chame-as nele.

← Referência dos componentes · Índice do guia