scheduler — u_pbt_scheduler #

← Referencia de componentes · Índice de la guía

Un calendario al estilo de Outlook: vistas día, semana laboral, semana, mes y agenda, banda « todo el día », arrastrar y soltar para mover y redimensionar, recursos uno al lado del otro, categorías de color, y tarjetas e información sobre herramientas escritas por plantillas. Se llena cita a cita, o con una sola llamada desde un DataStore — y cada gesto del usuario le devuelve la fila que hay que actualizar.

▶ Verlo en vivo — Aplicación de demostración, mosaico Scheduler: la vista previa, el código que lo genera y esta página, uno al lado del otro.

De un vistazo #

Inicio rápido #

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

Entender el calendario #

Las vistas #

is_view elige la vista, is_date el día alrededor del cual se construye: su semana, su mes. El usuario cambia una y otro desde la barra de herramientas del componente (Hoy, anterior, siguiente, menú de vistas) — las dos propiedades se releen en directo, y ue_view_changed / ue_date_changed lo indican, venga el cambio del usuario o de su código.

Las fechas #

Una fecha viaja como texto, "yyyy-mm-dd hh:mm" — en los métodos, las propiedades y los eventos. Es una hora local flotante: sin zona horaria ni horario de verano; "2026-09-22 09:00" se muestra a las 09:00, en todos los equipos.

• El fin es exclusivo. Una cita de 09:00 a 10:00 termina a las 10:00: la siguiente, que empieza a las 10:00, no se solapa con ella. Sin fin, una cita dura 30 minutos.
• Una fecha sin hora incluye sus dos días. "2026-09-24" → "2026-09-25" con ib_all_day = true es el 24 y el 25. Para una cita de todo el día se ignora la hora: una columna datetime de DataWindow, que lleva 00:00:00, da días, el último incluido.
• Lo que el calendario acepta también: "2026-09-22T09:30", segundos, y el texto de una columna datetime de DataWindow. of_add_appointment tiene una sobrecarga que recibe dos datetime.
• Lo que devuelven los eventos: las fechas en la forma en que las escribió — "yyyy-mm-dd hh:mm", fin exclusivo, para una cita con hora; solo fechas, ambos días incluidos, para una cita de todo el día. Es también lo que is_start e is_end releen en el 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 banda « todo el día » #

Encima de la cuadrícula horaria de las vistas día y semana, una banda recibe las citas ib_all_day y las que duran 24 horas o más: un seminario de tres días cabe allí en una barra en lugar de aplastar tres columnas. ib_all_day_band = false la retira. En la vista mes, esas citas son barras que atraviesan sus días; las demás, una línea escrita por is_month_template.

Las citas de un DataStore #

of_from_datastore(ids) carga el calendario con una sola llamada: una fila = una cita, y su clave es su número de fila — es la que cada evento le devuelve, lista para SetItem. Una columna desempeña un rol cuando lleva su nombre, o cuando of_map se lo asigna:

• Una columna booleana es verdadera para 1, true, Y o yes. Una columna status lleva los valores de STATUS_* (busy, tentative, free, oof, elsewhere). Cada nombre se reconoce también con el prefijo is_: is_private, ya que private es una palabra reservada de PowerScript.
• Todas las columnas, con rol o sin él, son campos de las plantillas: una columna customer se escribe {customer} en la tarjeta, y se lee con of_get_field.
• Una columna que desempeña ROLE_KEY sustituye al número de fila como clave: resérvela para datos que no vuelve a cargar desde ese DataStore. Sus valores deben ser únicos y no vacíos: una fila que no lo cumple (o cuyo valor contiene / o |) conserva su número de fila como clave, y ue_script_error lo indica una vez.
• El calendario nunca modifica el DataStore: le dice lo que hizo el usuario (ue_appointment_moved, ue_appointment_resized), usted hace SetItem, y luego Update() cuando su aplicación lo decide.
• Después de un InsertRow, un DeleteRow, un Sort o un Filter, los números de fila cambian: vuelva a llamar a of_from_datastore.

Recursos y agrupación #

Un recurso es lo que se reserva: una persona, una sala, una máquina (of_add_resource). Una cita lo nombra mediante is_resource. Con is_group_by = GROUP_RESOURCE, cada día de las vistas día y semana se divide en una columna por recurso, y arrastrar una tarjeta a otra columna cambia su recurso — ue_appointment_moved lo devuelve en as_resource. ib_visible = false en un recurso oculta su columna y sus citas, como desmarcar un calendario en Outlook.

Colores, categorías y estado #

El color de una tarjeta se decide en este orden: el il_accent establecido en esta cita, luego el color de su categoría (of_add_category, is_category), luego el de su recurso, luego el acento del tema. El filete de la izquierda indica el estado (is_status, el « Mostrar como » de Outlook: ocupado, provisional, libre, fuera de la oficina, en otro lugar); una cita ib_cancelled se dibuja hueca, y ib_recurring, ib_private, ib_reminder ponen un pequeño signo en la tarjeta.

Propiedades #

Propiedades de una cita #

Una cita se controla mediante su handle, of_appointment("clave") — creado en el primer acceso, sigue siendo válido después. Una propiedad leída pregunta al componente cuánto vale ahora: tras un arrastre, is_start e is_end ya dicen dónde la soltó el usuario.

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

Como todo item, una cita lleva también la información sobre herramientas común (is_tooltip, is_super_tooltip_title, is_super_tooltip_text, is_super_tooltip_image) — que entonces sustituye a la de las plantillas — y los colores de item: il_accent vuelve a colorear la tarjeta y su filete, il_back_color, il_text_color, il_back_color_hover e il_text_color_hover la pintan en reposo y al pasar el ratón.

Propiedades de un recurso y de una categoría #

Constantes #

Las constantes se leen en el objeto que las lleva: u_pbt_scheduler.VIEW_MONTH para una propiedad del componente, n_pbt_scheduler_appointment.STATUS_OOF para una propiedad de cita.

Métodos #

Citas #

DataStore #

Recursos y categorías #

Navegación y selección #

Eventos #

Las plantillas #

Lo que dicen una tarjeta, una línea del mes y una información sobre herramientas no es fijo: es una plantilla que usted escribe, en texto enriquecido ([b], [br], [color=…], [symbol=…]…) con campos entre llaves. Cuatro propiedades las llevan: is_card_template (tarjetas de las vistas día y semana, agenda, barras del mes), is_month_template (una línea de la vista mes), is_tooltip_title_template e is_tooltip_template (la información sobre herramientas). La plantilla de información predeterminada es:

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

La sintaxis #

Los formatos de fecha #

Los símbolos son los de PowerBuilder; los nombres de días y meses siguen el idioma de visualización. Un texto entre comillas se escribe tal cual. Los mismos símbolos sirven para is_time_format.

Los campos #

Un campo desconocido escribe una cadena vacía.

Los símbolos #

La etiqueta de texto enriquecido [symbol=nombre] coloca un símbolo integrado, monocromo, dibujado en el color del texto que lo rodea — sigue el tema, el paso del ratón y el color de la tarjeta, sin archivo que distribuir: clock, location, person, people, calendar, repeat, lock, bell, phone, mail, video, note, tag, link, check, star, info, warning. Un nombre desconocido se muestra tal cual.

Lo que el usuario puede hacer sin una línea de código #

• navegar: Hoy, anterior, siguiente, y el menú de vistas de la barra de herramientas;
• mover una cita a otra hora, otro día u otro recurso, arrastrándola — el paso sigue ii_slot_minutes;
• redimensionar una cita arrastrando su borde;
• barrer casillas vacías para elegir un intervalo → ue_range_selected — en la banda « todo el día » o en la vista mes, días enteros;
• pedir una cita con un doble clic en una casilla vacía o con el + de un encabezado de día (de un encabezado de recurso cuando el calendario está agrupado) → ue_new_requested;
• abrir una cita con un doble clic → ue_appointment_opened, y hacer clic derecho en una cita o una casilla vacía para su menú.

El calendario no crea, no modifica ni elimina nada por sí mismo más allá del arrastre: pregunta, su aplicación decide. ib_read_only desactiva todos estos gestos de una vez, ib_read_only en una cita los desactiva solo para ella.

Con el teclado, una vez que el calendario tiene el foco:

Ejemplos #

Las citas de un DataStore, y lo que el usuario hace con ellas #

El DataStore ids_appts (variable de instancia) tiene las columnas subject, start_date, end_date, location, room, category y customer. Las cuatro primeras desempeñan su rol por su nombre; room lo recibe de 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()

Crear y eliminar #

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

Tarjetas e información propias #

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

Rechazar un desplazamiento #

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

Cargar solo lo que se ve #

Con años de historial, no hace falta leerlo todo: ue_date_changed da el intervalo en pantalla en cada navegación, y en la primera visualización. Aquí d_appointments recibe dos argumentos datetime, inicio y fin del intervalo.

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

Su menú sobre una cita #

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

Buenas prácticas #

• Enmarque una serie de adiciones con of_set_redraw(/*on*/ false) / of_set_redraw(/*on*/ true): las citas aparecen de una sola vez.
• Para datos que viven en una base, prefiera of_from_datastore a un bucle de of_add_appointment: una sola transferencia, y cada evento le devuelve la fila.
• Recargue (of_from_datastore) después de cualquier InsertRow, DeleteRow, Sort o Filter del DataStore: la clave de una cita es un número de fila.
• Escriba las fechas como "yyyy-mm-dd hh:mm", nunca en el formato regional del equipo: es el único que el calendario lee en todas partes.
• En una plantilla, rodee un campo opcional con {?campo}…{/campo}: una tarjeta sin lugar no muestra un « ; » huérfano.
• Con un historial largo, cargue el intervalo visible en ue_date_changed en lugar de todo el DataStore.
• Para una regla de negocio (ninguna cita el fin de semana, ningún solapamiento en una sala), ib_veto_changes y ue_appointment_changing rechazan antes de que la tarjeta se mueva.

Límites de la 4.0 #

Lo que el calendario no hace — conviene saberlo antes de elegirlo:

• Periodicidad: ni series (reglas RRULE), ni excepciones, ni edición « esta repetición / toda la serie ». ib_recurring solo pone un signo en la tarjeta: cada repetición es una cita (una fila del DataStore) que su aplicación genera por sí misma. Un motor de periodicidad está previsto para una versión posterior.
• Zonas horarias: la hora es local flotante (véase Las fechas); ninguna segunda escala horaria, ninguna conversión.
• Vista cronológica (recursos en filas, tiempo en columnas) y minicalendario de navegación: ausentes; agrupe por recurso (GROUP_RESOURCE) en las vistas día y semana.
• iCalendar: ni importación ni exportación de archivos .ics.
• Impresión: ninguna; el calendario se dibuja solo en pantalla.
• Teclado: se selecciona, se abre, se elimina y se navega con el teclado, pero no se crea ni se mueve una cita sin el ratón.
• Fecha y hora en dos columnas: un inicio escrito en dos columnas del DataStore no se asigna; únalo en una columna datetime en la consulta.

Heredado de la base común #

Estos miembros existen en todos los componentes visuales — no son propios de este. Se detallan una sola vez, en los capítulos transversales; esta tabla solo dice dónde leerlos.

Dos ayudas no se heredan: of_icon y of_escape_markup viven en n_pbt_utils. Declare uno — n_pbt_utils lnv_utils, nada que crear — y llámelas sobre él.

← Referencia de componentes · Índice de la guía