scheduler — u_pbt_scheduler #

← Référence des composants · Sommaire du guide

Un calendrier à la manière d'Outlook : vues jour, semaine de travail, semaine, mois et agenda, bande « journée entière », glisser-déposer pour déplacer et redimensionner, ressources côte à côte, catégories de couleur, et des cartes et des info-bulles écrites par modèles. Il se remplit rendez-vous par rendez-vous, ou d'un seul appel depuis un DataStore — et chaque geste de l'utilisateur vous rend la ligne à mettre à jour.

▶ Le voir en vrai — Application de démonstration, tuile Scheduler : l'aperçu, le code qui le produit et cette page, côte à côte.

En bref #

Démarrage rapide #

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

Comprendre le calendrier #

Les vues #

is_view choisit la vue, is_date le jour autour duquel elle se construit : sa semaine, son mois. L'utilisateur change l'une et l'autre depuis la barre d'outils du composant (Aujourd'hui, précédent, suivant, menu des vues) — les deux propriétés se relisent en direct, et ue_view_changed / ue_date_changed le disent, que le changement vienne de l'utilisateur ou de votre code.

Les dates #

Une date voyage en texte, "yyyy-mm-dd hh:mm" — dans les méthodes, les propriétés et les événements. C'est une heure locale flottante : ni fuseau horaire, ni heure d'été ; "2026-09-22 09:00" s'affiche à 09:00, sur tous les postes.

• La fin est exclusive. Un rendez-vous de 09:00 à 10:00 finit à 10:00 : le suivant, qui commence à 10:00, ne le chevauche pas. Sans fin, un rendez-vous dure 30 minutes.
• Une date sans heure inclut ses deux jours. "2026-09-24" → "2026-09-25" avec ib_all_day = true, c'est le 24 et le 25. Pour une journée entière, l'heure est ignorée : une colonne datetime de DataWindow, qui porte 00:00:00, donne des jours, le dernier inclus.
• Ce que le calendrier accepte aussi : "2026-09-22T09:30", des secondes, et le texte d'une colonne datetime de DataWindow. of_add_appointment a une surcharge qui prend deux datetime.
• Ce que les événements rendent : les dates sous la forme où vous les avez écrites — "yyyy-mm-dd hh:mm", fin exclusive, pour un rendez-vous horaire ; des dates seules, les deux jours inclus, pour une journée entière. C'est aussi ce que is_start et is_end relisent sur le 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 bande « journée entière » #

Au-dessus de la grille horaire des vues jour et semaine, une bande reçoit les rendez-vous ib_all_day et ceux qui durent 24 heures ou plus : un séminaire de trois jours y tient en une barre au lieu d'écraser trois colonnes. ib_all_day_band = false la retire. Dans la vue mois, ces rendez-vous sont des barres qui traversent leurs jours ; les autres, une ligne écrite par is_month_template.

Les rendez-vous d'un DataStore #

of_from_datastore(ids) charge le calendrier d'un seul appel : une ligne = un rendez-vous, et sa clé est son numéro de ligne — c'est elle que chaque événement vous rend, prête pour SetItem. Une colonne joue un rôle quand elle en porte le nom, ou quand of_map le lui donne :

• Une colonne booléenne vaut vrai pour 1, true, Y ou yes. Une colonne status porte les valeurs de STATUS_* (busy, tentative, free, oof, elsewhere). Chaque nom se reconnaît aussi préfixé is_ : is_private, puisque private est un mot réservé de PowerScript.
• Toutes les colonnes, rôle ou non, sont des champs des modèles : une colonne customer s'écrit {customer} sur la carte, et se lit par of_get_field.
• Une colonne qui joue ROLE_KEY remplace le numéro de ligne comme clé : à réserver aux données que vous ne rechargez pas depuis ce DataStore. Ses valeurs doivent être uniques et non vides : une ligne qui ne le respecte pas (ou dont la valeur contient / ou |) garde son numéro de ligne comme clé, et ue_script_error le dit une fois.
• Le calendrier ne modifie jamais le DataStore : il vous dit ce que l'utilisateur a fait (ue_appointment_moved, ue_appointment_resized), vous faites SetItem, puis Update() quand votre application le décide.
• Après un InsertRow, un DeleteRow, un Sort ou un Filter, les numéros de ligne changent : rappelez of_from_datastore.

Ressources et regroupement #

Une ressource est ce sur quoi on réserve : une personne, une salle, une machine (of_add_resource). Un rendez-vous la nomme par is_resource. Avec is_group_by = GROUP_RESOURCE, chaque jour des vues jour et semaine se divise en une colonne par ressource, et glisser une carte dans une autre colonne change sa ressource — ue_appointment_moved la rend dans as_resource. ib_visible = false sur une ressource masque sa colonne et ses rendez-vous, comme décocher un calendrier dans Outlook.

Couleurs, catégories et statut #

La couleur d'une carte se décide dans cet ordre : l'il_accent posé sur ce rendez-vous, puis la couleur de sa catégorie (of_add_category, is_category), puis celle de sa ressource, puis l'accent du thème. Le liseré de gauche dit le statut (is_status, le « Afficher comme » d'Outlook : occupé, provisoire, libre, absent, ailleurs) ; un rendez-vous ib_cancelled est dessiné creux, et ib_recurring, ib_private, ib_reminder posent un petit signe sur la carte.

Propriétés #

Propriétés d'un rendez-vous #

Un rendez-vous se pilote par son handle, of_appointment("clé") — créé au premier accès, il reste valable ensuite. Une propriété lue demande au composant ce qu'elle vaut maintenant : après un glisser, is_start et is_end disent déjà où l'utilisateur l'a déposé.

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

Comme tout item, un rendez-vous porte aussi l'info-bulle commune (is_tooltip, is_super_tooltip_title, is_super_tooltip_text, is_super_tooltip_image) — elle remplace alors celle des modèles — et les couleurs d'item : il_accent recolore la carte et son liseré, il_back_color, il_text_color, il_back_color_hover et il_text_color_hover la peignent au repos et au survol.

Propriétés d'une ressource et d'une catégorie #

Constantes #

Les constantes se lisent sur l'objet qui les porte : u_pbt_scheduler.VIEW_MONTH pour une propriété du composant, n_pbt_scheduler_appointment.STATUS_OOF pour une propriété de rendez-vous.

Méthodes #

Rendez-vous #

DataStore #

Ressources et catégories #

Navigation et sélection #

Événements #

Les modèles #

Ce qu'une carte, une ligne du mois et une info-bulle disent n'est pas figé : c'est un modèle que vous écrivez, en texte riche ([b], [br], [color=…], [symbol=…]…) avec des champs entre accolades. Quatre propriétés les portent : is_card_template (cartes des vues jour et semaine, agenda, barres du mois), is_month_template (une ligne de la vue mois), is_tooltip_title_template et is_tooltip_template (l'info-bulle). Le modèle d'info-bulle par défaut est :

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

La syntaxe #

Les formats de date #

Les jetons sont ceux de PowerBuilder ; les noms de jours et de mois suivent la langue d'affichage. Un texte entre guillemets est écrit tel quel. Les mêmes jetons servent à is_time_format.

Les champs #

Un champ inconnu écrit une chaîne vide.

Les symboles #

La balise [symbol=nom] du texte riche pose un symbole intégré, monochrome, dessiné dans la couleur du texte qui l'entoure — il suit le thème, le survol et la couleur de la carte, sans fichier à livrer : clock, location, person, people, calendar, repeat, lock, bell, phone, mail, video, note, tag, link, check, star, info, warning. Un nom inconnu s'affiche tel quel.

Ce que l'utilisateur peut faire sans une ligne de code #

• naviguer : Aujourd'hui, précédent, suivant, et le menu des vues de la barre d'outils ;
• déplacer un rendez-vous vers une autre heure, un autre jour ou une autre ressource, en le glissant — le pas suit ii_slot_minutes ;
• redimensionner un rendez-vous en tirant son bord ;
• balayer des cases vides pour choisir une plage → ue_range_selected — dans la bande « journée entière » ou dans le mois, des jours entiers ;
• demander un rendez-vous par double-clic sur une case vide ou par le + d'un en-tête de jour (d'un en-tête de ressource quand le calendrier est regroupé) → ue_new_requested ;
• ouvrir un rendez-vous par double-clic → ue_appointment_opened, et cliquer droit sur un rendez-vous ou une case vide pour votre menu.

Le calendrier ne crée, ne modifie ni ne supprime rien de lui-même au-delà du glisser : il demande, votre application décide. ib_read_only coupe tous ces gestes d'un coup, ib_read_only sur un rendez-vous les coupe pour lui seul.

Au clavier, une fois le calendrier atteint :

Exemples #

Les rendez-vous d'un DataStore, et ce que l'utilisateur en fait #

Le DataStore ids_appts (variable d'instance) a les colonnes subject, start_date, end_date, location, room, category et customer. Les quatre premières jouent leur rôle par leur nom ; room le reçoit d'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()

Créer et supprimer #

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

Une colonne par salle #

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

Des cartes et des info-bulles à vous #

// 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}"

Refuser un déplacement #

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

Ne charger que ce qui se voit #

Sur des années d'historique, inutile de tout lire : ue_date_changed donne la plage à l'écran à chaque navigation, et au premier affichage. Ici d_appointments prend deux arguments datetime, début et fin de la plage.

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

Votre menu sur un rendez-vous #

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

Bonnes pratiques #

• Encadrez une série d'ajouts par of_set_redraw(/*on*/ false) / of_set_redraw(/*on*/ true) : les rendez-vous apparaissent d'un seul coup.
• Pour des données qui vivent en base, préférez of_from_datastore à une boucle d'of_add_appointment : un seul transfert, et chaque événement vous rend la ligne.
• Rechargez (of_from_datastore) après tout InsertRow, DeleteRow, Sort ou Filter du DataStore : la clé d'un rendez-vous est un numéro de ligne.
• Écrivez les dates en "yyyy-mm-dd hh:mm", jamais dans le format régional du poste : c'est le seul que le calendrier lit partout.
• Dans un modèle, entourez un champ facultatif de {?champ}…{/champ} : une carte sans lieu n'affiche pas un « ; » orphelin.
• Sur un historique long, chargez la plage visible dans ue_date_changed plutôt que tout le DataStore.
• Pour une règle métier (pas de rendez-vous le week-end, pas de chevauchement dans une salle), ib_veto_changes et ue_appointment_changing refusent avant que la carte bouge.

Limites de la 4.0 #

Ce que le calendrier ne fait pas — à savoir avant de le choisir :

• Récurrence : ni séries (règles RRULE), ni exceptions, ni édition « cette occurrence / toute la série ». ib_recurring pose seulement un signe sur la carte : chaque occurrence est un rendez-vous (une ligne du DataStore) que votre application déroule elle-même. Un moteur de récurrence est prévu pour une version suivante.
• Fuseaux horaires : l'heure est locale flottante (voir Les dates) ; aucune seconde échelle horaire, aucune conversion.
• Vue chronologie (ressources en lignes, temps en colonnes) et mini-calendrier de navigation : absents ; regroupez par ressource (GROUP_RESOURCE) dans les vues jour et semaine.
• iCalendar : ni import ni export de fichiers .ics.
• Impression : aucune ; le calendrier se dessine à l'écran seulement.
• Clavier : on sélectionne, ouvre, supprime et navigue au clavier, mais on ne crée ni ne déplace un rendez-vous sans la souris.
• Date et heure en deux colonnes : un début écrit dans deux colonnes du DataStore ne se mappe pas ; assemblez-le en une colonne datetime dans la requête.

Hérité du socle commun #

Ces membres existent sur tous les composants visuels — ils ne sont pas propres à celui-ci. Ils sont détaillés une seule fois, dans les chapitres transverses ; cette table dit seulement où les lire.

Deux aides ne sont pas héritées : of_icon et of_escape_markup vivent sur n_pbt_utils. Déclarez-en une — n_pbt_utils lnv_utils, rien à créer — et appelez-les dessus.

← Référence des composants · Sommaire du guide