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.
• Il calendario non modifica mai 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.
• Dopo un InsertRow, un DeleteRow, un Sort o un Filter, i numeri di riga cambiano: richiami of_from_datastore.

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 #

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, location, room, category e customer. Le prime quattro svolgono il loro ruolo per nome; room lo riceve da of_map.

// 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()

// "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)
// Local variables
long ll_row

// The key of a row loaded by of_from_datastore is its row number
ll_row = Long(as_key)
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)

// 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)
// Local variables
long ll_row

// Only the times change : same row, same two columns
ll_row = Long(as_key)
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.Update()

Creare ed eliminare #

// 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)

// 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_start, string as_end, string as_resource) returns boolean
// 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.

Limiti della 4.0 #

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: nessuna; il calendario si disegna solo a schermo.
• 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