scheduler — u_pbt_scheduler #

← Komponentenreferenz · Inhalt des Handbuchs

Ein Kalender nach Art von Outlook: Ansichten Tag, Arbeitswoche, Woche, Monat und Agenda, ein Ganztagsband, Ziehen und Ablegen zum Verschieben und Größenändern, Ressourcen nebeneinander, Farb-Kategorien, und Karten und Tooltips, die von Vorlagen geschrieben werden. Er wird Termin für Termin gefüllt oder mit einem einzigen Aufruf aus einem DataStore — und jede Geste des Benutzers gibt Ihnen die zu aktualisierende Zeile zurück.

▶ Live ansehen — Demoanwendung, Kachel Scheduler: die Vorschau, der zugehörige Code und diese Seite, nebeneinander.

Auf einen Blick #

Schnellstart #

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

Den Kalender verstehen #

Die Ansichten #

is_view wählt die Ansicht, is_date den Tag, um den sie aufgebaut wird: seine Woche, sein Monat. Der Benutzer ändert beides über die Symbolleiste der Komponente (Heute, zurück, weiter, Ansichtsmenü) — beide Eigenschaften werden live zurückgelesen, und ue_view_changed / ue_date_changed melden es, ob die Änderung vom Benutzer oder von Ihrem Code kommt.

Datumsangaben #

Ein Datum reist als Text, "yyyy-mm-dd hh:mm" — in Methoden, Eigenschaften und Events. Es ist eine schwebende Ortszeit: keine Zeitzone, keine Sommerzeit; "2026-09-22 09:00" wird auf jedem Arbeitsplatz um 09:00 angezeigt.

• Das Ende ist exklusiv. Ein Termin von 09:00 bis 10:00 endet um 10:00: Der nächste, der um 10:00 beginnt, überschneidet sich nicht damit. Ohne Ende dauert ein Termin 30 Minuten.
• Ein Datum ohne Uhrzeit schließt seine beiden Tage ein. "2026-09-24" → "2026-09-25" mit ib_all_day = true ist der 24. und der 25. Bei einem Ganztagstermin wird die Uhrzeit ignoriert: Eine datetime-Spalte eines DataWindows, die 00:00:00 trägt, ergibt Tage, der letzte eingeschlossen.
• Was der Kalender ebenfalls annimmt: "2026-09-22T09:30", Sekunden und den Text einer datetime-Spalte eines DataWindows. of_add_appointment hat eine Überladung mit zwei datetime-Werten.
• Was die Events zurückgeben: die Daten in der Form, in der Sie sie geschrieben haben — "yyyy-mm-dd hh:mm", Ende exklusiv, für einen Termin mit Uhrzeit; nur Daten, beide Tage eingeschlossen, für einen Ganztagstermin. Genau das lesen auch is_start und is_end auf dem 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)))

Das Ganztagsband #

Über dem Stundenraster der Tages- und Wochenansichten nimmt ein Band die Termine mit ib_all_day und die von 24 Stunden oder mehr auf: Ein dreitägiges Seminar passt dort als ein Balken, statt drei Spalten zu erdrücken. ib_all_day_band = false entfernt es. In der Monatsansicht sind diese Termine Balken über ihre Tage; die anderen eine Zeile, geschrieben von is_month_template.

Termine aus einem DataStore #

of_from_datastore(ids) lädt den Kalender mit einem Aufruf: eine Zeile = ein Termin, und sein Schlüssel ist seine Zeilennummer — ihn gibt Ihnen jedes Event zurück, bereit für SetItem. Eine Spalte spielt eine Rolle, wenn sie deren Namen trägt oder wenn of_map sie ihr gibt:

• Eine boolesche Spalte ist wahr bei 1, true, Y oder yes. Eine Spalte status trägt die Werte von STATUS_* (busy, tentative, free, oof, elsewhere). Jeder Name wird auch mit dem Präfix is_ erkannt: is_private, da private ein reserviertes Wort von PowerScript ist.
• Jede Spalte, ob mit Rolle oder nicht, ist ein Feld der Vorlagen: Eine Spalte customer wird als {customer} auf die Karte geschrieben und mit of_get_field gelesen.
• Eine Spalte mit ROLE_KEY ersetzt die Zeilennummer als Schlüssel: Behalten Sie sie Daten vor, die Sie nicht aus diesem DataStore neu laden. Ihre Werte müssen eindeutig und nicht leer sein: Eine Zeile, die das nicht einhält (oder deren Wert / oder | enthält), behält ihre Zeilennummer als Schlüssel, und ue_script_error meldet es einmal.
• Der Kalender ändert den DataStore nie: Er sagt Ihnen, was der Benutzer getan hat (ue_appointment_moved, ue_appointment_resized), Sie rufen SetItem auf, dann Update(), wenn Ihre Anwendung es entscheidet.
• Nach einem InsertRow, DeleteRow, Sort oder Filter ändern sich die Zeilennummern: Rufen Sie of_from_datastore erneut auf.

Ressourcen und Gruppierung #

Eine Ressource ist das, was gebucht wird: eine Person, ein Raum, eine Maschine (of_add_resource). Ein Termin nennt sie über is_resource. Mit is_group_by = GROUP_RESOURCE teilt sich jeder Tag der Tages- und Wochenansichten in eine Spalte je Ressource, und das Ziehen einer Karte in eine andere Spalte ändert ihre Ressource — ue_appointment_moved gibt sie in as_resource zurück. ib_visible = false auf einer Ressource blendet ihre Spalte und ihre Termine aus, wie das Abwählen eines Kalenders in Outlook.

Farben, Kategorien und Status #

Die Farbe einer Karte wird in dieser Reihenfolge bestimmt: das auf diesem Termin gesetzte il_accent, dann die Farbe seiner Kategorie (of_add_category, is_category), dann die seiner Ressource, dann der Akzent des Designs. Der Streifen links zeigt den Status (is_status, Outlooks „Anzeigen als“: gebucht, mit Vorbehalt, frei, abwesend, woanders); ein Termin mit ib_cancelled wird hohl gezeichnet, und ib_recurring, ib_private, ib_reminder setzen ein kleines Zeichen auf die Karte.

Eigenschaften #

Eigenschaften eines Termins #

Ein Termin wird über sein Handle gesteuert, of_appointment("schlüssel") — beim ersten Zugriff erstellt, bleibt es danach gültig. Eine gelesene Eigenschaft fragt die Komponente, was sie jetzt wert ist: Nach einem Ziehen sagen is_start und is_end bereits, wo der Benutzer ihn abgelegt hat.

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

Wie jedes Item trägt ein Termin auch den gemeinsamen Tooltip (is_tooltip, is_super_tooltip_title, is_super_tooltip_text, is_super_tooltip_image) — der dann den der Vorlagen ersetzt — und die Item-Farben: il_accent färbt die Karte und ihren Streifen um, il_back_color, il_text_color, il_back_color_hover und il_text_color_hover malen sie in Ruhe und beim Überfahren.

Eigenschaften einer Ressource und einer Kategorie #

Konstanten #

Konstanten werden auf dem Objekt gelesen, das sie trägt: u_pbt_scheduler.VIEW_MONTH für eine Eigenschaft der Komponente, n_pbt_scheduler_appointment.STATUS_OOF für eine Eigenschaft eines Termins.

Methoden #

Termine #

DataStore #

Ressourcen und Kategorien #

Navigation und Auswahl #

Events #

Die Vorlagen #

Was eine Karte, eine Monatszeile und ein Tooltip sagen, ist nicht festgelegt: Es ist eine Vorlage, die Sie schreiben, in Rich Text ([b], [br], [color=…], [symbol=…]…) mit Feldern in geschweiften Klammern. Vier Eigenschaften tragen sie: is_card_template (Karten der Tages- und Wochenansichten, Agenda, Monatsbalken), is_month_template (eine Zeile der Monatsansicht), is_tooltip_title_template und is_tooltip_template (der Tooltip). Die Standardvorlage des Tooltips lautet:

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

Die Syntax #

Die Datumsformate #

Die Kürzel sind die von PowerBuilder; Tages- und Monatsnamen folgen der Anzeigesprache. Ein Text in Anführungszeichen wird unverändert geschrieben. Dieselben Kürzel dienen is_time_format.

Die Felder #

Ein unbekanntes Feld schreibt eine leere Zeichenkette.

Die Symbole #

Das Rich-Text-Tag [symbol=name] setzt ein eingebautes Symbol, einfarbig, in der Farbe des umgebenden Texts gezeichnet — es folgt dem Design, dem Überfahren und der Farbe der Karte, ohne mitzuliefernde Datei: clock, location, person, people, calendar, repeat, lock, bell, phone, mail, video, note, tag, link, check, star, info, warning. Ein unbekannter Name wird unverändert angezeigt.

Was der Benutzer ohne eine Zeile Code tun kann #

• navigieren: Heute, zurück, weiter und das Ansichtsmenü der Symbolleiste;
• einen Termin verschieben, auf eine andere Uhrzeit, einen anderen Tag oder eine andere Ressource, durch Ziehen — der Schritt folgt ii_slot_minutes;
• einen Termin durch Ziehen seines Rands in der Größe ändern;
• leere Felder überstreichen, um einen Bereich zu wählen → ue_range_selected — im Ganztagesband oder in der Monatsansicht ganze Tage;
• einen Termin anfordern durch Doppelklick auf ein leeres Feld oder über das + eines Tageskopfs (eines Ressourcenkopfs, wenn der Kalender gruppiert ist) → ue_new_requested;
• einen Termin durch Doppelklick öffnen → ue_appointment_opened, und auf einen Termin oder ein leeres Feld rechtsklicken für Ihr Menü.

Der Kalender erstellt, ändert und löscht nichts von selbst über das Ziehen hinaus: Er fragt, Ihre Anwendung entscheidet. ib_read_only schaltet alle diese Gesten auf einmal ab, ib_read_only auf einem Termin nur für diesen.

Mit der Tastatur, sobald der Kalender den Fokus hat:

Beispiele #

Termine aus einem DataStore und was der Benutzer damit macht #

Der DataStore ids_appts (Instanzvariable) hat die Spalten subject, start_date, end_date, location, room, category und customer. Die ersten vier spielen ihre Rolle über ihren Namen; room erhält sie von 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()

Anlegen und löschen #

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

Eine Spalte je Raum #

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

Eigene Karten und Tooltips #

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

Ein Verschieben ablehnen #

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

Nur laden, was sichtbar ist #

Bei jahrelanger Historie muss nicht alles gelesen werden: ue_date_changed liefert bei jeder Navigation und bei der ersten Anzeige den sichtbaren Bereich. Hier nimmt d_appointments zwei datetime-Argumente, Beginn und Ende des Bereichs.

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

Ihr Menü auf einem Termin #

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

Best Practices #

• Rahmen Sie eine Reihe von Hinzufügungen mit of_set_redraw(/*on*/ false) / of_set_redraw(/*on*/ true) ein: Die Termine erscheinen auf einen Schlag.
• Für Daten aus der Datenbank ziehen Sie of_from_datastore einer Schleife von of_add_appointment vor: eine einzige Übertragung, und jedes Event gibt Ihnen die Zeile zurück.
• Laden Sie nach jedem InsertRow, DeleteRow, Sort oder Filter des DataStores neu (of_from_datastore): Der Schlüssel eines Termins ist eine Zeilennummer.
• Schreiben Sie Daten als "yyyy-mm-dd hh:mm", nie im Regionalformat des Arbeitsplatzes: Nur dieses liest der Kalender überall.
• Umgeben Sie in einer Vorlage ein optionales Feld mit {?feld}…{/feld}: Eine Karte ohne Ort zeigt kein verwaistes „;“.
• Laden Sie bei langer Historie den sichtbaren Bereich in ue_date_changed statt des ganzen DataStores.
• Für eine Geschäftsregel (kein Termin am Wochenende, keine Überschneidung in einem Raum) lehnen ib_veto_changes und ue_appointment_changing ab, bevor sich die Karte bewegt.

Grenzen der 4.0 #

Was der Kalender nicht kann — gut zu wissen, bevor Sie ihn wählen:

• Serien: keine Terminserien (RRULE-Regeln), keine Ausnahmen, keine Bearbeitung „dieses Vorkommen / die ganze Serie“. ib_recurring setzt nur ein Zeichen auf die Karte: Jedes Vorkommen ist ein Termin (eine Zeile des DataStores), den Ihre Anwendung selbst erzeugt. Eine Serien-Engine ist für eine spätere Version geplant.
• Zeitzonen: Die Uhrzeit ist schwebende Ortszeit (siehe Datumsangaben); keine zweite Zeitskala, keine Umrechnung.
• Zeitachsenansicht (Ressourcen als Zeilen, Zeit als Spalten) und Mini-Kalender zur Navigation: nicht vorhanden; gruppieren Sie in der Tages- und Wochenansicht nach Ressource (GROUP_RESOURCE).
• iCalendar: weder Import noch Export von .ics-Dateien.
• Drucken: nicht vorhanden; der Kalender wird nur am Bildschirm gezeichnet.
• Tastatur: Auswählen, Öffnen, Löschen und Navigieren gehen per Tastatur, aber ein Termin lässt sich ohne Maus weder anlegen noch verschieben.
• Datum und Uhrzeit in zwei Spalten: Ein Beginn in zwei Spalten des DataStores lässt sich nicht zuordnen; fügen Sie ihn in der Abfrage zu einer datetime-Spalte zusammen.

Vom gemeinsamen Sockel geerbt #

Diese Mitglieder gibt es bei jeder visuellen Komponente — sie sind nicht dieser eigen. Sie werden einmal in den übergreifenden Kapiteln beschrieben; diese Tabelle sagt nur, wo man sie liest.

Zwei Helfer werden nicht geerbt: of_icon und of_escape_markup liegen auf n_pbt_utils. Deklarieren Sie eines — n_pbt_utils lnv_utils, nichts zu erzeugen — und rufen Sie sie darauf auf.

← Komponentenreferenz · Inhalt des Handbuchs