scheduler — u_pbt_scheduler #

← Component reference · Guide contents

An Outlook-like calendar: day, work week, week, month and agenda views, an all-day band, drag and drop to move and resize, resources side by side, colour categories, and cards and tooltips written by templates. It is filled appointment by appointment, or in one call from a DataStore — and every gesture of the user hands you back the row to update.

▶ See it live — Demo application, Scheduler tile: the preview, the code behind it and this page, side by side.

At a glance #

Quick start #

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

Understanding the calendar #

The views #

is_view picks the view, is_date the day it is built around: its week, its month. The user changes both from the component's toolbar (Today, previous, next, the view menu) — both properties are read back live, and ue_view_changed / ue_date_changed say so, whether the change comes from the user or from your code.

Dates #

A date travels as text, "yyyy-mm-dd hh:mm" — in methods, properties and events. It is a floating local time: no time zone, no daylight saving; "2026-09-22 09:00" is shown at 09:00, on every workstation.

• The end is exclusive. An appointment from 09:00 to 10:00 ends at 10:00: the next one, starting at 10:00, does not overlap it. Without an end, an appointment lasts 30 minutes.
• A date without a time includes both its days. "2026-09-24" → "2026-09-25" with ib_all_day = true is the 24th and the 25th. For an all-day appointment the time is ignored: a DataWindow datetime column, which carries 00:00:00, gives days, the last one included.
• What the calendar also accepts: "2026-09-22T09:30", seconds, and the text of a DataWindow datetime column. of_add_appointment has an overload that takes two datetime values.
• What the events hand back: the dates in the form you wrote them — "yyyy-mm-dd hh:mm", end exclusive, for a timed appointment; dates only, both days included, for an all-day one. That is also what is_start and is_end read back on the 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)))

The all-day band #

Above the time grid of the day and week views, a band receives the ib_all_day appointments and those lasting 24 hours or more: a three-day seminar fits there as one bar instead of crushing three columns. ib_all_day_band = false removes it. In the month view, those appointments are bars running across their days; the others, one line written by is_month_template.

Appointments from a DataStore #

of_from_datastore(ids) loads the calendar in one call: one row = one appointment, and its key is its row number — that is what every event hands you back, ready for SetItem. A column plays a role when it bears its name, or when of_map gives it one:

• A boolean column is true for 1, true, Y or yes. A status column carries the values of STATUS_* (busy, tentative, free, oof, elsewhere). Every name is also recognised with an is_ prefix: is_private, since private is a PowerScript reserved word.
• Every column, role or not, is a template field: a customer column is written {customer} on the card, and read with of_get_field.
• A column playing ROLE_KEY replaces the row number as the key: keep it for data you do not reload from that DataStore. Its values must be unique and not empty: a row that breaks that (or whose value holds / or |) keeps its row number as key, and ue_script_error says so once.
• The calendar never modifies the DataStore: it tells you what the user did (ue_appointment_moved, ue_appointment_resized), you call SetItem, then Update() when your application decides.
• After an InsertRow, a DeleteRow, a Sort or a Filter, the row numbers change: call of_from_datastore again.

Resources and grouping #

A resource is what gets booked: a person, a room, a machine (of_add_resource). An appointment names it through is_resource. With is_group_by = GROUP_RESOURCE, each day of the day and week views splits into one column per resource, and dragging a card into another column changes its resource — ue_appointment_moved hands it back in as_resource. ib_visible = false on a resource hides its column and its appointments, like unticking a calendar in Outlook.

Colours, categories and status #

The colour of a card is decided in this order: the il_accent set on this appointment, then the colour of its category (of_add_category, is_category), then that of its resource, then the theme accent. The strip on the left tells the status (is_status, Outlook's "Show as": busy, tentative, free, out of office, elsewhere); an ib_cancelled appointment is drawn hollow, and ib_recurring, ib_private, ib_reminder put a small sign on the card.

Properties #

Appointment properties #

An appointment is driven through its handle, of_appointment("key") — created on first access, it stays valid afterwards. A property that is read asks the component what it is now: after a drag, is_start and is_end already say where the user dropped it.

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

Like any item, an appointment also carries the common tooltip (is_tooltip, is_super_tooltip_title, is_super_tooltip_text, is_super_tooltip_image) — which then replaces the one of the templates — and the item colours: il_accent recolours the card and its strip, il_back_color, il_text_color, il_back_color_hover and il_text_color_hover paint it at rest and on hover.

Resource and category properties #

Constants #

Constants are read on the object that carries them: u_pbt_scheduler.VIEW_MONTH for a component property, n_pbt_scheduler_appointment.STATUS_OOF for an appointment property.

Methods #

Appointments #

DataStore #

Resources and categories #

Navigation and selection #

Events #

Templates #

What a card, a month line and a tooltip say is not fixed: it is a template you write, in rich text ([b], [br], [color=…], [symbol=…]…) with fields between braces. Four properties carry them: is_card_template (cards of the day and week views, agenda, month bars), is_month_template (one line of the month view), is_tooltip_title_template and is_tooltip_template (the tooltip). The default tooltip template is:

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

Syntax #

Date formats #

The tokens are PowerBuilder's; day and month names follow the display language. A text between double quotes is written as is. The same tokens serve is_time_format.

Fields #

An unknown field writes an empty string.

Symbols #

The [symbol=name] rich-text tag puts a built-in symbol, monochrome, drawn in the colour of the text around it — it follows the theme, the hover and the colour of the card, with no file to ship: clock, location, person, people, calendar, repeat, lock, bell, phone, mail, video, note, tag, link, check, star, info, warning. An unknown name is shown as is.

What the user can do without a line of code #

• navigate: Today, previous, next, and the view menu of the toolbar;
• move an appointment to another time, day or resource, by dragging it — the step follows ii_slot_minutes;
• resize an appointment by dragging its edge;
• sweep empty slots to pick a range → ue_range_selected — in the all-day band or the month view, whole days;
• ask for an appointment with a double-click on an empty slot or with the + of a day header (of a resource header when the calendar is grouped) → ue_new_requested;
• open an appointment with a double-click → ue_appointment_opened, and right-click an appointment or an empty slot for your menu.

The calendar creates, modifies and deletes nothing by itself beyond the drag: it asks, your application decides. ib_read_only switches all these gestures off at once, ib_read_only on an appointment switches them off for that one alone.

With the keyboard, once the calendar has the focus:

Examples #

Appointments from a DataStore, and what the user does with them #

The ids_appts DataStore (an instance variable) has the columns subject, start_date, end_date, location, room, category and customer. The first four play their role by their name; room receives it from 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()

Creating and deleting #

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

One column per room #

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

Cards and tooltips of your own #

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

Refusing a move #

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

Loading only what is visible #

Over years of history, there is no point reading everything: ue_date_changed gives the range on screen at every navigation, and on the first display. Here d_appointments takes two datetime arguments, the start and end of the range.

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

Your menu on an appointment #

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

• Wrap a series of additions in of_set_redraw(/*on*/ false) / of_set_redraw(/*on*/ true): the appointments appear at once.
• For data that lives in a database, prefer of_from_datastore to a loop of of_add_appointment: one transfer, and every event hands you back the row.
• Reload (of_from_datastore) after any InsertRow, DeleteRow, Sort or Filter of the DataStore: the key of an appointment is a row number.
• Write dates as "yyyy-mm-dd hh:mm", never in the regional format of the workstation: it is the only one the calendar reads everywhere.
• In a template, wrap an optional field in {?field}…{/field}: a card without a place does not show an orphan ";".
• Over a long history, load the visible range in ue_date_changed rather than the whole DataStore.
• For a business rule (no appointment at the weekend, no overlap in a room), ib_veto_changes and ue_appointment_changing refuse before the card moves.

Limits of the 4.0 #

What the calendar does not do — worth knowing before you choose it:

• Recurrence: no series (RRULE rules), no exceptions, no "this occurrence / the whole series" editing. ib_recurring only puts a sign on the card: each occurrence is an appointment (a DataStore row) your application expands itself. A recurrence engine is planned for a later version.
• Time zones: the time is floating local time (see Dates); no second time scale, no conversion.
• Timeline view (resources as rows, time as columns) and navigation mini-calendar: absent; group by resource (GROUP_RESOURCE) in the day and week views.
• iCalendar: no import or export of .ics files.
• Printing: none; the calendar is drawn on screen only.
• Keyboard: you select, open, delete and navigate with the keyboard, but you cannot create or move an appointment without the mouse.
• Date and time in two columns: a start written in two DataStore columns cannot be mapped; join it into one datetime column in the query.

Inherited from the common base #

These members exist on every visual component — they are not specific to this one. They are detailed once, in the transverse chapters; this table only says where to read them.

Two helpers are not inherited: of_icon and of_escape_markup live on n_pbt_utils. Declare one — n_pbt_utils lnv_utils, nothing to create — and call them on it.

← Component reference · Guide contents