scheduler — u_pbt_scheduler #

← Riferimento dei componenti · Sommario della guida

Un calendario alla maniera di Outlook: viste giorno, settimana lavorativa, settimana, mese e agenda, fascia « giornata intera », trascinamento per spostare e ridimensionare, risorse affiancate, categorie di colore, e schede e tooltip scritti da modelli. Si riempie appuntamento per appuntamento, o con una sola chiamata da un DataStore — e ogni gesto dell'utente Le restituisce la riga da aggiornare.

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

In breve #

Avvio rapido #

// open event of the window : a few appointments of the week, in one repaint
uo_sched.of_set_redraw(/*on*/ false)
uo_sched.is_date = "2026-09-21"

// A colour category, then the appointments : a key, a subject, a start and an end
uo_sched.of_add_category(/*key*/ "customer", /*label*/ "Customer", /*color*/ RGB(216, 90, 48))
uo_sched.of_add_appointment(/*key*/ "a1", /*subject*/ "Weekly meeting", /*start*/ "2026-09-21 09:00", /*end*/ "2026-09-21 10:00")
uo_sched.of_appointment(/*key*/ "a1").is_location = "Room 3"
uo_sched.of_add_appointment(/*key*/ "a2", /*subject*/ "ACME visit", /*start*/ "2026-09-23 14:00", /*end*/ "2026-09-23 16:30")
uo_sched.of_appointment(/*key*/ "a2").is_category = "customer"

// Dates only : an all-day appointment, both days included
uo_sched.of_add_appointment(/*key*/ "a3", /*subject*/ "Trade fair", /*start*/ "2026-09-24", /*end*/ "2026-09-25")
uo_sched.of_appointment(/*key*/ "a3").ib_all_day = true
uo_sched.of_set_redraw(/*on*/ true)

// ue_appointment_opened event of uo_sched : (string as_key)
// A double-click, or Enter on the selected appointment : open YOUR editor
wf_edit_appointment(as_key)

Capire il calendario #

Le viste #

is_view sceglie la vista, is_date il giorno attorno al quale si costruisce: la sua settimana, il suo mese. L'utente cambia l'una e l'altro dalla barra degli strumenti del componente (Oggi, precedente, successivo, menu delle viste) — le due proprietà si rileggono dal vivo, e ue_view_changed / ue_date_changed lo segnalano, che il cambiamento venga dall'utente o dal vostro codice.

Le date #

Una data viaggia come testo, "yyyy-mm-dd hh:mm" — nei metodi, nelle proprietà e negli event. È un'ora locale fluttuante: né fuso orario, né ora legale; "2026-09-22 09:00" si visualizza alle 09:00, su tutte le postazioni.

• La fine è esclusiva. Un appuntamento dalle 09:00 alle 10:00 finisce alle 10:00: il successivo, che inizia alle 10:00, non si sovrappone. Senza fine, un appuntamento dura 30 minuti.
• Una data senza ora include i suoi due giorni. "2026-09-24" → "2026-09-25" con ib_all_day = true è il 24 e il 25. Per una giornata intera l'ora è ignorata: una colonna datetime di DataWindow, che porta 00:00:00, dà dei giorni, l'ultimo incluso.
• Ciò che il calendario accetta anche: "2026-09-22T09:30", i secondi, e il testo di una colonna datetime di DataWindow. of_add_appointment ha un overload che prende due datetime.
• Ciò che gli event restituiscono: le date nella forma in cui le avete scritte — "yyyy-mm-dd hh:mm", fine esclusiva, per un appuntamento con orario; solo date, entrambi i giorni inclusi, per una giornata intera. È anche ciò che is_start e is_end rileggono sull'handle.

// Local variables
datetime ldt_start

// A "yyyy-mm-dd hh:mm" text back into a PowerBuilder datetime
ldt_start = DateTime(Date(Left(as_start, 10)), Time(Mid(as_start, 12)))

La fascia « giornata intera » #

Sopra la griglia oraria delle viste giorno e settimana, una fascia riceve gli appuntamenti ib_all_day e quelli che durano 24 ore o più: un seminario di tre giorni vi sta in una barra invece di schiacciare tre colonne. ib_all_day_band = false la rimuove. Nella vista mese, questi appuntamenti sono barre che attraversano i loro giorni; gli altri, una riga scritta da is_month_template.

Gli appuntamenti di un DataStore #

of_from_datastore(ids) carica il calendario con una sola chiamata: una riga = un appuntamento, e la sua chiave è il suo numero di riga — è lei che ogni event Le restituisce, pronta per SetItem. Una colonna svolge un ruolo quando ne porta il nome, o quando of_map glielo assegna:

• Una colonna booleana vale vero per 1, true, Y o yes. Una colonna status porta i valori di STATUS_* (busy, tentative, free, oof, elsewhere). Ogni nome è riconosciuto anche con il prefisso is_: is_private, poiché private è una parola riservata di PowerScript.
• Tutte le colonne, con ruolo o no, sono campi dei modelli: una colonna customer si scrive {customer} sulla scheda, e si legge con of_get_field.
• Una colonna che svolge ROLE_KEY sostituisce il numero di riga come chiave: da riservare ai dati che non ricarica da quel DataStore. I suoi valori devono essere unici e non vuoti: una riga che non lo rispetta (o il cui valore contiene / o |) tiene il suo numero di riga come chiave, e ue_script_error lo segnala una volta.
• Per impostazione predefinita il calendario non modifica il DataStore: Le dice cosa ha fatto l'utente (ue_appointment_moved, ue_appointment_resized), Lei esegue SetItem, poi Update() quando la Sua applicazione lo decide.
• Con ib_write_back = true scrive da sé il nuovo inizio, la nuova fine e la nuova risorsa nella riga — un SetItem tipizzato dalla colonna — prima dell'event; un valore che il DataStore rifiuta rimette l'appuntamento al suo posto e solleva ue_write_back_failed. L'Update() resta Suo.
• Dopo che il Suo codice ha modificato una riga (SetItem, la Sua finestra di modifica), of_reload_row la rilegge sul posto: ciò che ha impostato sull'appuntamento e la selezione restano. of_appointment("k").of_row() dà la riga di un appuntamento, qualunque sia la sua chiave.
• of_from_datastore accetta anche una DataWindow o una DataWindowChild: ib_write_back scrive allora in quella che l'utente vede. Date e decimali si leggono qualunque siano le impostazioni regionali, e un CHAR perde il suo riempimento.
• La colonna che svolge ROLE_KEY non si cambia con of_set_field (-5): una chiave cambia ricaricando.
• Dopo un InsertRow, un DeleteRow, un Sort o un Filter, i numeri di riga cambiano: richiami of_from_datastore. Un appuntamento selezionato che sparisce così solleva ue_selection_changed("").

Risorse e raggruppamento #

Una risorsa è ciò che si prenota: una persona, una sala, una macchina (of_add_resource). Un appuntamento la nomina con is_resource. Con is_group_by = GROUP_RESOURCE, ogni giorno delle viste giorno e settimana si divide in una colonna per risorsa, e trascinare una scheda in un'altra colonna ne cambia la risorsa — ue_appointment_moved la restituisce in as_resource. ib_visible = false su una risorsa nasconde la sua colonna e i suoi appuntamenti, come togliere la spunta a un calendario in Outlook.

Colori, categorie e stato #

Il colore di una scheda si decide in quest'ordine: l'il_accent impostato su questo appuntamento, poi il colore della sua categoria (of_add_category, is_category), poi quello della sua risorsa, poi l'accento del tema. La striscia a sinistra indica lo stato (is_status, il « Mostra come » di Outlook: occupato, provvisorio, libero, fuori sede, altrove); un appuntamento ib_cancelled è disegnato vuoto, e ib_recurring, ib_private, ib_reminder pongono un piccolo segno sulla scheda.

Proprietà #

Proprietà di un appuntamento #

Un appuntamento si pilota tramite il suo handle, of_appointment("chiave") — creato al primo accesso, resta valido in seguito. Una proprietà letta chiede al componente quanto vale adesso: dopo un trascinamento, is_start e is_end dicono già dove l'utente l'ha rilasciato.

// A handle used once fits on one line
uo_sched.of_appointment(/*key*/ "a1").is_status = n_pbt_scheduler_appointment.STATUS_TENTATIVE

Come ogni item, un appuntamento porta anche il tooltip comune (is_tooltip, is_super_tooltip_title, is_super_tooltip_text, is_super_tooltip_image) — che allora sostituisce quello dei modelli — e i colori dell'item: il_accent ricolora la scheda e la sua striscia, il_back_color, il_text_color, il_back_color_hover e il_text_color_hover la dipingono a riposo e al passaggio del mouse.

Proprietà di una risorsa e di una categoria #

Una risorsa porta anche, come ogni elemento, il tooltip comune (is_tooltip, is_super_tooltip_title…) e i colori di elemento (il_accent, il_back_color…): vestono l'intestazione della sua colonna quando il calendario raggruppa per risorsa.

Costanti #

Le costanti si leggono sull'oggetto che le porta: u_pbt_scheduler.VIEW_MONTH per una proprietà del componente, n_pbt_scheduler_appointment.STATUS_OOF per una proprietà di un appuntamento.

Metodi #

Appuntamenti #

DataStore #

Risorse e categorie #

Navigazione e selezione #

Event #

I modelli #

Ciò che una scheda, una riga del mese e un tooltip dicono non è fisso: è un modello che scrive Lei, in testo formattato ([b], [br], [color=…], [symbol=…]…) con dei campi tra graffe. Quattro proprietà li portano: is_card_template (schede delle viste giorno e settimana, agenda, barre del mese), is_month_template (una riga della vista mese), is_tooltip_title_template e is_tooltip_template (il tooltip). Il modello di tooltip predefinito è:

[symbol=clock] {when}{?location}[br][symbol=location] {location}{/location}{?organizer}[br][symbol=person] {organizer}{/organizer}

La sintassi #

I formati di data #

I token sono quelli di PowerBuilder; i nomi dei giorni e dei mesi seguono la lingua di visualizzazione. Un testo tra virgolette è scritto così com'è. Gli stessi token servono a is_time_format.

I campi #

Un campo sconosciuto scrive una stringa vuota.

I simboli #

Il tag di testo formattato [symbol=nome] pone un simbolo integrato, monocromatico, disegnato nel colore del testo che lo circonda — segue il tema, il passaggio del mouse e il colore della scheda, senza file da distribuire: clock, location, person, people, calendar, repeat, lock, bell, phone, mail, video, note, tag, link, check, star, info, warning. Un nome sconosciuto si visualizza così com'è.

Cosa può fare l'utente senza una riga di codice #

• navigare: Oggi, precedente, successivo, e il menu delle viste della barra degli strumenti;
• spostare un appuntamento verso un'altra ora, un altro giorno o un'altra risorsa, trascinandolo — il passo segue ii_slot_minutes;
• ridimensionare un appuntamento trascinandone il bordo;
• percorrere delle caselle vuote per scegliere un intervallo → ue_range_selected — nella fascia « giornata intera » o nella vista mese, giorni interi;
• chiedere un appuntamento con un doppio clic su una casella vuota o con il + di un'intestazione di giorno (di un'intestazione di risorsa quando il calendario è raggruppato) → ue_new_requested;
• aprire un appuntamento con un doppio clic → ue_appointment_opened, e fare clic destro su un appuntamento o una casella vuota per il Suo menu.

Il calendario non crea, non modifica e non elimina nulla da sé oltre al trascinamento: chiede, la Sua applicazione decide. ib_read_only disattiva tutti questi gesti in una volta, ib_read_only su un appuntamento li disattiva solo per lui.

Da tastiera, una volta raggiunto il calendario:

Esempi #

Gli appuntamenti di un DataStore, e cosa ne fa l'utente #

Il DataStore ids_appts (variabile d'istanza) ha le colonne subject, start_date, end_date, all_day, location, room, category e customer. Le prime cinque svolgono il loro ruolo per nome; room lo riceve da of_map. Con ib_write_back, il calendario scrive da sé i gesti dell'utente nelle righe.

// open event of the window : the appointments, retrieved the way your application already does
ids_appts = create datastore
ids_appts.dataobject = "d_appointments"
ids_appts.SetTransObject(SQLCA)
ids_appts.Retrieve()

// What the user drags is written into its row (SetItem) before the event
uo_sched.ib_write_back = true

// "room" is not a role name : say which role it plays, then load every row
uo_sched.of_map(/*role*/ u_pbt_scheduler.ROLE_RESOURCE, /*column*/ "room")
uo_sched.of_from_datastore(/*ads*/ ids_appts)

// ue_appointment_moved event of uo_sched : (string as_key, string as_start, string as_end, string as_resource, string as_old_start, string as_old_end, string as_old_resource)
// ib_write_back has written the new start, end and room into the row already :
// save when YOUR application decides, here at once
ids_appts.Update()

// ue_appointment_resized event of uo_sched : (string as_key, string as_start, string as_end, string as_old_start, string as_old_end)
// Only the times changed, and they are in the row already : save
ids_appts.Update()

// ue_write_back_failed event of uo_sched : (string as_key, string as_col, string as_value, string as_reason)
// The DataStore refused the value : the appointment went back where it was
MessageBox("Not saved", as_col + " : " + as_reason)

// ue_appointment_opened event of uo_sched : (string as_key)
// Local variables
long ll_row

// The row of the appointment, edited in YOUR window, then read again in place
ll_row = uo_sched.of_appointment(/*key*/ as_key).of_row()
OpenWithParm(w_appointment_edit, ll_row)
uo_sched.of_reload_row(/*row*/ ll_row)

Creare ed eliminare #

Una richiesta di giornata intera arriva come sole date, ab_all_day a true: la colonna all_day lo dice alla riga — senza di essa, la riga si rileggerebbe come 30 minuti a mezzanotte.

// ue_new_requested event of uo_sched : (string as_start, string as_end, boolean ab_all_day, string as_resource)
// Local variables
long ll_row

// A new row, prefilled with the slot the user chose
ll_row = ids_appts.InsertRow(0)
ids_appts.SetItem(ll_row, "subject", "New appointment")
ids_appts.SetItem(ll_row, "start_date", DateTime(Date(Left(as_start, 10)), Time(Mid(as_start, 12))))
ids_appts.SetItem(ll_row, "end_date", DateTime(Date(Left(as_end, 10)), Time(Mid(as_end, 12))))
ids_appts.SetItem(ll_row, "room", as_resource)

// A whole day comes as dates alone : the all_day column says so, or the row
// would read back as 30 minutes at midnight
if ab_all_day then ids_appts.SetItem(ll_row, "all_day", 1)

// Reload (the row numbers are the keys), then bring the new one into view
uo_sched.of_from_datastore(/*ads*/ ids_appts)
uo_sched.of_show_appointment(/*key*/ String(ll_row))

// ue_delete_requested event of uo_sched : (string as_key)
// Ask first : the calendar never deletes by itself
if MessageBox("Delete", "Delete this appointment?", Question!, YesNo!) = 2 then return
ids_appts.DeleteRow(Long(as_key))
ids_appts.Update()

// The rows after it changed number : reload
uo_sched.of_from_datastore(/*ads*/ ids_appts)

Una colonna per sala #

// The rooms, each with its own colour, side by side under each day
uo_sched.of_set_redraw(/*on*/ false)
uo_sched.of_add_resource(/*key*/ "r1", /*label*/ "Room A")
uo_sched.of_add_resource(/*key*/ "r2", /*label*/ "Room B")
uo_sched.of_resource(/*key*/ "r1").il_color = RGB(15, 108, 189)
uo_sched.of_resource(/*key*/ "r2").il_color = RGB(31, 158, 117)
uo_sched.is_group_by = u_pbt_scheduler.GROUP_RESOURCE
uo_sched.is_view = u_pbt_scheduler.VIEW_DAY

// Each appointment names its room
uo_sched.of_add_appointment(/*key*/ "k1", /*subject*/ "Kickoff", /*start*/ "2026-09-22 09:00", /*end*/ "2026-09-22 10:00")
uo_sched.of_appointment(/*key*/ "k1").is_resource = "r1"
uo_sched.of_add_appointment(/*key*/ "k2", /*subject*/ "Interview", /*start*/ "2026-09-22 10:30", /*end*/ "2026-09-22 11:30")
uo_sched.of_appointment(/*key*/ "k2").is_resource = "r2"
uo_sched.of_set_redraw(/*on*/ true)

// A checkbox of the window hides Room B and its appointments, like unticking a calendar in Outlook
uo_sched.of_resource(/*key*/ "r2").ib_visible = cbx_room_b.checked

Schede e tooltip Suoi #

// The card : the time, the subject in bold, the customer (a DataStore column) when there is one
uo_sched.is_card_template = "{start} [b]{subject}[/b]{?customer}[br][symbol=people] {customer}{/customer}"

// The month line : a small lock on the private ones
uo_sched.is_month_template = "{?private}[symbol=lock] {/private}{subject}"

// The tooltip : the date written out, the duration, the status
uo_sched.is_tooltip_title_template = "{subject}"
uo_sched.is_tooltip_template = "[symbol=calendar] {start:dddd d mmmm}, {time} ({duration})[br][symbol=info] {status_label}"

Rifiutare uno spostamento #

// Ask before any move or resize is applied
uo_sched.ib_veto_changes = true

// ue_appointment_changing event of uo_sched : (string as_key, string as_kind, string as_start, string as_end, string as_resource) returns boolean
// A resize keeps the day : only a move is checked
if as_kind = u_pbt_scheduler.CHANGE_RESIZE then return true

// Nothing on a Saturday or a Sunday : returning false puts the appointment back
if DayNumber(Date(Left(as_start, 10))) = 1 or DayNumber(Date(Left(as_start, 10))) = 7 then return false
return true

Caricare solo ciò che si vede #

Su anni di storico, inutile leggere tutto: ue_date_changed fornisce l'intervallo a schermo a ogni navigazione, e alla prima visualizzazione. Qui d_appointments prende due argomenti datetime, inizio e fine dell'intervallo.

// ue_date_changed event of uo_sched : (string as_first, string as_last)
// The last day is INCLUDED : read up to the start of the day after
ids_appts.Retrieve(DateTime(Date(as_first)), DateTime(RelativeDate(Date(as_last), 1)))
uo_sched.of_from_datastore(/*ads*/ ids_appts)

Il Suo menu su un appuntamento #

// ue_appointment_rclicked event of uo_sched : (string as_key, long al_x, long al_y)
// Local variables
m_appointment lm_menu

// Remember which appointment the menu is about, then open YOUR menu under the pointer
is_menu_key = as_key
lm_menu = create m_appointment
lm_menu.m_popup.PopMenu(parent.PointerX(), parent.PointerY())
destroy lm_menu

Buone pratiche #

• Racchiuda una serie di aggiunte tra of_set_redraw(/*on*/ false) / of_set_redraw(/*on*/ true): gli appuntamenti compaiono in una sola volta.
• Per dati che vivono in una base, preferisca of_from_datastore a un ciclo di of_add_appointment: un solo trasferimento, e ogni event Le restituisce la riga.
• Ricarichi (of_from_datastore) dopo ogni InsertRow, DeleteRow, Sort o Filter del DataStore: la chiave di un appuntamento è un numero di riga.
• Scriva le date come "yyyy-mm-dd hh:mm", mai nel formato regionale della postazione: è il solo che il calendario legge ovunque.
• In un modello, racchiuda un campo facoltativo tra {?campo}…{/campo}: una scheda senza luogo non mostra un « ; » orfano.
• Su uno storico lungo, carichi l'intervallo visibile in ue_date_changed piuttosto che tutto il DataStore.
• Per una regola di business (nessun appuntamento nel fine settimana, nessuna sovrapposizione in una sala), ib_veto_changes e ue_appointment_changing rifiutano prima che la scheda si muova.
• Per salvare i gesti senza codice, imposti ib_write_back = true; dopo che il Suo codice ha modificato una sola riga, basta of_reload_row.

Limiti #

Ciò che il calendario non fa — da sapere prima di sceglierlo:

• Ricorrenza: niente serie (regole RRULE), niente eccezioni, niente modifica « questa occorrenza / tutta la serie ». ib_recurring mette solo un segno sulla scheda: ogni occorrenza è un appuntamento (una riga del DataStore) che la Sua applicazione genera da sé. Un motore di ricorrenza è previsto per una versione successiva.
• Fusi orari: l'ora è locale fluttuante (vedere Le date); nessuna seconda scala oraria, nessuna conversione.
• Vista cronologica (risorse in righe, tempo in colonne) e mini-calendario di navigazione: assenti; raggruppi per risorsa (GROUP_RESOURCE) nelle viste giorno e settimana.
• iCalendar: né importazione né esportazione di file .ics.
• Stampa impaginata: of_print e of_print_to_pdf (ereditati) stampano ciò che è a schermo; la stampa di un intero periodo del calendario, impaginata, non esiste.
• Tastiera: si seleziona, si apre, si elimina e si naviga da tastiera, ma non si crea né si sposta un appuntamento senza il mouse.
• Data e ora in due colonne: un inizio scritto in due colonne del DataStore non si mappa; lo unisca in una colonna datetime nella query.

Ereditato dalla base comune #

Questi membri esistono su tutti i componenti visivi — non sono propri di questo. Sono descritti una sola volta, nei capitoli trasversali; questa tabella dice solo dove leggerli.

Due aiuti non sono ereditati: of_icon e of_escape_markup vivono su n_pbt_utils. Ne dichiari uno — n_pbt_utils lnv_utils, niente da creare — e li chiami su di esso.

← Riferimento dei componenti · Sommario della guida