messagebox — `n_pbt_messagebox` #

← Riferimento dei componenti · Sommario della guida

Finestra di dialogo modale a tema, con esito sincrono: il sostituto diretto del MessageBox() di PowerBuilder, con testo formattato, pulsanti liberi, icone e casella di controllo.

▶ Vederlo dal vivo — Applicazione dimostrativa, riquadro Message box: l'anteprima, il codice che lo produce e questa pagina, affiancati.

In breve #

Oggetto	`n_pbt_messagebox` — non visuale: nulla da collocare nella finestra
Serve per	Porre una domanda o annunciare un risultato, al posto del `MessageBox()` nativo, rigido e privo di tema
Esito	Sincrono: `of_show()` blocca e restituisce l'indice del pulsante cliccato

A differenza dei componenti visuali, questo oggetto non si inserisce in una finestra: lo si crea, configura, mostra, distrugge.

// Variabili locali
n_pbt_messagebox lnv_mb

// Creare l'oggetto di dialogo
lnv_mb = create n_pbt_messagebox

// ... configurazione ...

// Liberare l'oggetto di dialogo
destroy lnv_mb

Avvio rapido #

// Variabili locali
n_pbt_messagebox lnv_mb

// Creare l'oggetto di dialogo
lnv_mb = create n_pbt_messagebox

// Configurare la finestra
lnv_mb.is_title   = "Eliminazione"
lnv_mb.is_icon    = lnv_mb.ICON_WARNING
lnv_mb.is_message = "Eliminare definitivamente [b]12 cartelle[/b] ?[br][br]Questa azione è irreversibile."

// Aggiungere i pulsanti
lnv_mb.of_add_button(/*text*/ "Elimina", /*default*/ true,  /*cancel*/ false)   // -> 1
lnv_mb.of_add_button(/*text*/ "Annulla",   /*default*/ false, /*cancel*/ true)    // -> 2

// Mostrare in modale, poi agire sul primo pulsante
if lnv_mb.of_show(/*hwnd*/ Handle(this)) = 1 then
    of_delete()
end if

// Liberare l'oggetto di dialogo
destroy lnv_mb

of_show attende la risposta dell'utente: la riga successiva viene eseguita solo dopo il clic, esattamente come con MessageBox().

Proprietà #

Da impostare prima di of_show.

Proprietà	Tipo	Predefinito	Ruolo
`is_title`	string	`""`	Titolo visualizzato nell'intestazione della finestra
`is_message`	string	`""`	Corpo del messaggio. Accetta il testo formattato con tag (`[b]`, `[i]`, `[br]`, `[accent]`, `[picture=…]`…). Il testo del messaggio e dell'istruzione si può selezionare e copiare. Un valore che viene dai vostri dati passa prima per `of_escape_markup`: altrimenti una parentesi quadra verrebbe letta come un tag — un `[action=x]` nel nome di un cliente chiuderebbe la finestra
`is_instruction`	string	`""`	Istruzione principale: la domanda stessa, mostrata più grande sopra il messaggio. Titolo / istruzione / messaggio è l'anatomia che rende un dialogo leggibile a colpo d'occhio — «Eliminare 42 righe?» poi «L'operazione è definitiva» — invece di un blocco uniforme. Accetta la marcatura
`is_icon`	string	`""`	Icona: una costante `ICON_`, oppure la vostra immagine* (percorso di file, o risorsa di DLL `mia.dll:NOME`)
`is_checkbox`	string	`""`	Testo di una casella di controllo facoltativa, in stile «non chiedermelo più» (`""` = nessuna casella)
`ib_checked`	boolean	`false`	Stato iniziale della casella (lo stato finale si legge con `of_checked()`)
`ib_input`	boolean	`false`	Aggiunge un campo di immissione a tema (rinominare, motivo, commento), così un'applicazione non deve più costruirsi una finestra che non segue né il tema né il senso di lettura. Si rilegge con `of_input_value()` dopo `of_show`. Tutto in una chiamata: `of_prompt`
`is_input_label`	string	`""`	Etichetta sopra il campo (`""` = nessuna). Richiede `ib_input`
`is_input_value`	string	`""`	Contenuto iniziale del campo. All'apertura è selezionato: digitare lo sostituisce, come in ogni dialogo di rinomina
`is_input_placeholder`	string	`""`	Suggerimento mostrato finché il campo è vuoto. Non è un valore: se l'utente non digita nulla, nulla viene restituito
`ib_input_password`	boolean	`false`	Maschera i caratteri digitati
`ib_input_required`	boolean	`false`	Il pulsante predefinito resta disattivato finché il campo è vuoto. Lasciar inviare per poi rimproverare non serve a nessuno; il pulsante di annullamento resta raggiungibile. Un conto alla rovescia su questo pulsante (`of_add_button_timed`) non lo clicca finché il campo è vuoto: si esaurisce e il pulsante aspetta una mano. Un pulsante insieme predefinito e di annullamento è anch'esso fuori portata: Esc e Alt+F4 chiudono allora la finestra senza scelta (`0`)
`ib_buttons_reverse`	boolean	`false`	Ordine dei pulsanti: `false` = da sinistra a destra nell'ordine di aggiunta; `true` = invertito
`ib_movable`	boolean	`true`	La finestra si sposta? Non ha barra del titolo — disegna la propria scheda — quindi Windows non ha presa su di essa: gliene diamo una, la scheda trascina la finestra tranne ciò che risponde già a un clic e il testo del messaggio, che si seleziona. Vera per difetto, perché una modale che copre proprio ciò che serve leggere per rispondere è una trappola. Metterla a falso per una finestra che deve restare dov'è
`is_position`	string	`POSITION_OWNER`	Centratura: `POSITION_OWNER` (sulla finestra chiamante) o `POSITION_SCREEN` (sullo schermo)
`il_min_width`	long	`0`	Larghezza minima in pixel (`0` = automatica, 320); mai sotto 200
`il_max_width`	long	`0`	Larghezza massima in pixel (`0` = automatica): il testo va a capo entro questo limite; mai sotto 200
`il_max_height`	long	`0`	Altezza massima in pixel (`0` = automatica): oltre, il corpo del messaggio scorre invece di ingrandire la finestra
`il_accent`	long	`-1`	Colore d'accento di questa finestra: il pulsante predefinito e la casella di controllo lo prendono, e il colore del testo leggibile ne deriva. `-1` (il predefinito) segue l'applicazione. Un errore in rosso, un successo in verde, senza toccare il tema

Costanti #

Costante	Valore	Uso
`ICON_INFORMATION`	`"information"`	Informazione neutra
`ICON_WARNING`	`"warning"`	Avviso, azione rischiosa
`ICON_ERROR`	`"error"`	Insuccesso, errore
`ICON_QUESTION`	`"question"`	Domanda chiusa
`ICON_SUCCESS`	`"success"`	Conferma di un esito positivo
`ICON_NONE`	`"none"`	Nessuna icona
`POSITION_OWNER`	`"owner"`	Centrata sulla finestra chiamante
`POSITION_SCREEN`	`"screen"`	Centrata sullo schermo

Metodi #

Metodo	Ruolo
`of_add_button (string as_text)` → long	Aggiunge un pulsante semplice. Restituisce il suo indice a partire da 1
`of_add_button (string as_text, boolean ab_default, boolean ab_cancel)` → long	Idem, contrassegnando il pulsante come predefinito (Invio) e/o di annullamento (Esc). Restituisce il suo indice, a partire da `1`
`of_add_button (string as_text, string as_icon, boolean ab_default, boolean ab_cancel)` → long	Idem, con un'icona sul pulsante. Restituisce il suo indice, a partire da `1`
`of_add_button_timed (string as_text, boolean ab_default, boolean ab_cancel, long al_enable_secs, long al_click_secs)` → long	Pulsante con conto alla rovescia: resta disattivato per `al_enable_secs` secondi (contatore visibile), poi si clicca da solo dopo `al_click_secs` secondi (`0` = timer inattivo). Finché un pulsante di annullamento conta ancora alla rovescia, né Esc né Alt+F4 chiudono la finestra: l'attesa serve a far leggere. Restituisce il suo indice, a partire da `1`
`of_count ( )` → `long`	Restituisce il numero di pulsanti che porta la finestra. Si designano con il loro rango — quello che rende `of_add_button` e quello che rende `of_show` — quindi non hanno chiave: qui non c'è né `of_keys_at` né `of_has`
`of_show (long al_hwnd)` → long	Mostra la finestra modale e restituisce l'indice del pulsante cliccato (`0` = chiusura con Esc o Alt+F4 senza pulsante di annullamento). Un valore negativo indica che nessuna finestra ha potuto aprirsi: `-4`, o `-6` se manca il runtime WebView2 — `of_get_last_error()` dice perché. Se la finestra proprietaria si chiude mentre la finestra è aperta (un timer, un evento), la finestra se ne va con lei e `of_show` restituisce `0`
`of_get_last_error ( )` → string	Perché l'ultima finestra non ha potuto aprirsi — stringa vuota se si è aperta. Da leggere dopo un `of_show` (o una scorciatoia come `of_info`) che ha restituito un valore negativo, o dopo un `of_choose` o un `of_prompt` che ha restituito una stringa vuota
`of_checked ( )` → boolean	Stato della casella di controllo al momento dell'ultimo `of_show`
`of_input_value ( )` → string	Testo digitato nell'ultimo `of_show` (vuoto se `ib_input` era disattivo)
`of_action ( )` → string	Id della zona `[action=id]` cliccata nel messaggio, stringa vuota altrimenti. Una zona simile è una scelta offerta nella frase stessa: chiude il dialogo e `of_show` restituisce `0`. Una zona `[hyperlink=url]`, invece, si apre nel browser e lascia il dialogo aperto — il chiamante è bloccato in `of_show`, quindi un collegamento non può essere una risposta
`of_info (long al_hwnd, string as_title, string as_message)` → long	Dialogo in una riga, come lo è `MessageBox()`: icona d'informazione e un solo pulsante OK, restituisce `1`. Le etichette vengono dalle traduzioni della libreria (6 lingue) invece di essere scritte in ogni applicazione — è tutta la ragion d'essere di queste scorciatoie (negativo: nessuna finestra mostrata, vedere `of_get_last_error`)
`of_warning (long al_hwnd, string as_title, string as_message)` → long	Icona di avviso, un pulsante OK. Restituisce `1` (negativo: nessuna finestra mostrata, vedere `of_get_last_error`)
`of_error (long al_hwnd, string as_title, string as_message)` → long	Icona di errore, un pulsante OK. Restituisce `1` (negativo: nessuna finestra mostrata, vedere `of_get_last_error`)
`of_success (long al_hwnd, string as_title, string as_message)` → long	Icona di riuscita, un pulsante OK. Restituisce `1` (negativo: nessuna finestra mostrata, vedere `of_get_last_error`)
`of_confirm (long al_hwnd, string as_title, string as_message)` → long	Domanda + OK / Annulla. Restituisce `1` = OK, `2` = Annulla, `0` = chiuso (negativo: nessuna finestra mostrata, vedere `of_get_last_error`)
`of_yes_no (long al_hwnd, string as_title, string as_message)` → long	Domanda + Sì / No. Restituisce `1` = Sì, `2` = No, `0` = chiuso (negativo: nessuna finestra mostrata, vedere `of_get_last_error`)
`of_yes_no_cancel (long al_hwnd, string as_title, string as_message)` → long	Domanda + Sì / No / Annulla. Restituisce `1`, `2`, `3`, o `0` se chiuso (negativo: nessuna finestra mostrata, vedere `of_get_last_error`)
`of_add_choice (string as_key, string as_title, string as_description)` → long	Aggiunge una scelta sotto il messaggio — un titolo e una descrizione, come i collegamenti di comando di una finestra attività di Windows. Il clic chiude la finestra e `of_action()` ne dà la chiave (`of_show` restituisce 0). Restituisce il rango della scelta (1 per la prima), `-5` con una chiave vuota, già presa o che contiene `/` o `	` — nulla viene allora aggiunto
`of_choose (long al_hwnd)` → string	Mostra le scelte con un solo pulsante Annulla (tradotto) e restituisce la chiave della scelta cliccata, o una stringa vuota se l'utente ha annullato. L'elenco scorre quando supera lo schermo. Stringa vuota anche quando nessuna finestra ha potuto aprirsi: `of_get_last_error` dice allora perché. Senza alcuna scelta non si mostra nulla: stringa vuota, e `of_get_last_error` dice «no choice to show»
`of_prompt (long al_hwnd, string as_title, string as_message, string as_default)` → string	Chiede un valore e restituisce quanto digitato, o una stringa vuota se l'utente ha annullato. Per distinguere una risposta vuota da un annullamento, usi `of_show` + `of_input_value`. Stringa vuota anche quando nessuna finestra ha potuto aprirsi: `of_get_last_error` dice allora perché
`of_reset ( )`	Cancella tutte le proprietà e i pulsanti aggiunti: la stessa istanza riparte da zero

L'etichetta di un pulsante accetta il testo formattato con tag e il mnemonico & ("&Salva" sottolinea la S e la attiva con Alt+S); && mostra una e commerciale letterale.

La tastiera #

Tasto	Effetto
Invio	Attiva il pulsante contrassegnato come predefinito
Esc	Attiva il pulsante contrassegnato come annullamento; senza pulsante di annullamento chiude la finestra e restituisce `0`. Alt+F4 fa lo stesso. Finché il pulsante di annullamento conta ancora alla rovescia (`of_add_button_timed`), nessuno dei due chiude
Alt + lettera	Attiva il pulsante la cui etichetta porta quel mnemonico
Tab	Sposta il focus da un pulsante all'altro
Ctrl + C	Copia il dialogo (titolo, istruzione, messaggio, scelte con la loro descrizione, casella di controllo con il suo stato `[x]` o `[ ]`, etichette dei pulsanti) negli appunti, come ogni finestra di dialogo di Windows — comodo quando un errore va inoltrato all'assistenza. Con del testo selezionato nel messaggio, copia solo la selezione

All'apertura nessun pulsante ha un contorno di focus: è voluto, ed è il comportamento delle finestre di dialogo Windows moderne. Il bordo appare solo dopo una prima pressione di Tab, cioè quando l'utente passa esplicitamente alla tastiera. Invio ed Esc restano attivi fin dal primo secondo, anche senza focus visibile.

Esempi #

Domanda chiusa con pulsante predefinito #

// Variabili locali
n_pbt_messagebox lnv_mb
long ll_answer

// Creare l'oggetto di dialogo
lnv_mb = create n_pbt_messagebox

// Configurare la finestra
lnv_mb.is_title   = "Salvare le modifiche"
lnv_mb.is_icon    = lnv_mb.ICON_QUESTION
lnv_mb.is_message = "La cartella è stata modificata. Vuole salvare prima di chiudere ?"

// Aggiungere i pulsanti
lnv_mb.of_add_button(/*text*/ "&Salva",     /*default*/ true,  /*cancel*/ false)  // 1
lnv_mb.of_add_button(/*text*/ "&Non salvare", /*default*/ false, /*cancel*/ false) // 2
lnv_mb.of_add_button(/*text*/ "Annulla",          /*default*/ false, /*cancel*/ true)   // 3

// Mostrare in modale, poi liberare l'oggetto di dialogo
ll_answer = lnv_mb.of_show(/*hwnd*/ Handle(this))
destroy lnv_mb

// Agire secondo il pulsante cliccato (rango da 1)
choose case ll_answer
    case 1 ; of_save() ; Close(parent)
    case 2 ; Close(parent)
    case else ; // 3 o 0 : non si chiude
end choose

Messaggio formattato e icona #

// Configurare la finestra
lnv_mb.is_title   = "Importazione completata"
lnv_mb.is_icon    = lnv_mb.ICON_SUCCESS
lnv_mb.is_message = "[b]1 240 righe[/b] integrate.[br][br]" &
                  + "[accent]18 duplicati[/accent] sono stati ignorati."

// Aggiungere il pulsante, poi mostrare la finestra
lnv_mb.of_add_button(/*text*/ "OK", /*default*/ true, /*cancel*/ false)
lnv_mb.of_show(/*hwnd*/ Handle(this))

Un valore dei vostri dati nel messaggio #

Il messaggio è testo formattato: una parentesi quadra è un tag. Il nome di un cliente, un'etichetta digitata da un utente passano per of_escape_markup (di n_pbt_utils) prima di entrarci — altrimenti «Rossi [action=x]» chiuderebbe la finestra come una scelta.

// Local variables
n_pbt_utils lnv_utils

// The name comes from the database : escape it, it is shown as it is
lnv_mb.is_title   = "Delete customer"
lnv_mb.is_message = "Delete the customer [b]" + lnv_utils.of_escape_markup(/*text*/ ls_name) + "[/b] ?"

// Add the buttons, then show the box
lnv_mb.of_add_button(/*text*/ "Delete", /*default*/ false, /*cancel*/ false)
lnv_mb.of_add_button(/*text*/ "Cancel", /*default*/ true, /*cancel*/ true)
lnv_mb.of_show(/*hwnd*/ Handle(this))

Casella «non chiedermelo più» #

// Variabili locali
n_pbt_messagebox lnv_mb

// Creare l'oggetto di dialogo
lnv_mb = create n_pbt_messagebox

// Configurare la finestra
lnv_mb.is_title    = "Eliminazione"
lnv_mb.is_icon     = lnv_mb.ICON_WARNING
lnv_mb.is_message  = "Eliminare le righe selezionate ? Questa azione è irreversibile."
lnv_mb.is_checkbox = "Non chiedermelo più"
lnv_mb.ib_checked  = false

// Aggiungere i pulsanti
lnv_mb.of_add_button(/*text*/ "Elimina", /*default*/ true,  /*cancel*/ false)
lnv_mb.of_add_button(/*text*/ "Annulla",   /*default*/ false, /*cancel*/ true)

// Mostrare in modale, poi agire sul primo pulsante
if lnv_mb.of_show(/*hwnd*/ Handle(this)) = 1 then
    of_delete()

    // Memorizzare la scelta dell'utente
    ib_confirm_delete = not lnv_mb.of_checked()
end if

// Liberare l'oggetto di dialogo
destroy lnv_mb

Pulsante con conto alla rovescia #

// Configurare la finestra
lnv_mb.is_title   = "Riavvio"
lnv_mb.is_icon    = lnv_mb.ICON_INFORMATION
lnv_mb.is_message = "L'applicazione verrà riavviata per applicare l'aggiornamento."

// "Continua" resta disattivato 3 secondi (viene mostrato un contatore)
lnv_mb.of_add_button_timed(/*text*/ "Continua", /*default*/ true, /*cancel*/ false, /*enable_secs*/ 3, /*click_secs*/ 0)

// "Piu tardi" si clicca da solo dopo 10 secondi
lnv_mb.of_add_button_timed(/*text*/ "Più tardi", /*default*/ false, /*cancel*/ true, /*enable_secs*/ 0, /*click_secs*/ 10)

// Mostrare in modale
lnv_mb.of_show(/*hwnd*/ Handle(this))

Messaggio lungo: limitare le dimensioni #

// Un testo voluminoso : la finestra e limitata e il corpo scorre
lnv_mb.is_title      = "Note di rilascio"
lnv_mb.is_message    = ls_notes
lnv_mb.il_max_width  = 480
lnv_mb.il_max_height = 320

// Aggiungere il pulsante, poi mostrare la finestra
lnv_mb.of_add_button(/*text*/ "Chiudi", /*default*/ true, /*cancel*/ true)
lnv_mb.of_show(/*hwnd*/ Handle(this))

Riutilizzare un'istanza #

// Un'istanza di finestra, piu dialoghi : of_reset tra una chiamata e l'altra
inv_mb.of_reset()      // cancella le proprieta E i pulsanti precedenti

// Configurare la nuova finestra, poi mostrarla
inv_mb.is_title   = "Secondo dialogo"
inv_mb.is_message = "Ogni of_reset riparte da una finestra vergine."
inv_mb.of_add_button(/*text*/ "OK", /*default*/ true, /*cancel*/ false)
inv_mb.of_show(/*hwnd*/ Handle(this))

Buone pratiche #

Chiami sempre of_reset() prima di riconfigurare un'istanza riutilizzata: senza di esso i pulsanti del dialogo precedente si aggiungono ai nuovi.
Contrassegni sistematicamente un pulsante predefinito e un pulsante di annullamento: chi usa la tastiera si aspetta Invio ed Esc.
Verifichi il valore restituito 0: significa che la finestra è stata chiusa senza scelta (croce o Esc). Lo tratti come un annullamento.
Passi Handle(this) (o Handle(parent)) come finestra chiamante: la finestra si centra su di essa e la modalità riguarda la finestra giusta.
Riservi il rosso e ICON_ERROR agli errori veri; una conferma banale merita ICON_QUESTION.
Per un'informazione che non richiede alcuna risposta, preferisca una notifica non bloccante: vedere toaster.