scheduler — u_pbt_scheduler #

← Referência dos componentes · Índice do guia

Um calendário à maneira do Outlook: vistas dia, semana de trabalho, semana, mês e agenda, faixa « dia inteiro », arrastar e largar para mover e redimensionar, recursos lado a lado, categorias de cor, e cartões e tooltips escritos por modelos. Preenche-se compromisso a compromisso, ou numa só chamada a partir de um DataStore — e cada gesto do utilizador devolve a linha a atualizar.

▶ Ver ao vivo — Aplicação de demonstração, mosaico Scheduler: a pré-visualização, o código que o produz e esta página, lado a lado.

Em resumo #

Início 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)

Compreender o calendário #

As vistas #

is_view escolhe a vista, is_date o dia à volta do qual ela se constrói: a sua semana, o seu mês. O utilizador muda uma e outro a partir da barra de ferramentas do componente (Hoje, anterior, seguinte, menu das vistas) — as duas propriedades releem-se em direto, e ue_view_changed / ue_date_changed indicam-no, venha a mudança do utilizador ou do seu código.

As datas #

Uma data viaja como texto, "yyyy-mm-dd hh:mm" — nos métodos, nas propriedades e nos eventos. É uma hora local flutuante: sem fuso horário nem hora de verão; "2026-09-22 09:00" aparece às 09:00, em todos os postos.

• O fim é exclusivo. Um compromisso das 09:00 às 10:00 termina às 10:00: o seguinte, que começa às 10:00, não se sobrepõe. Sem fim, um compromisso dura 30 minutos.
• Uma data sem hora inclui os seus dois dias. "2026-09-24" → "2026-09-25" com ib_all_day = true é o dia 24 e o dia 25. Para um dia inteiro a hora é ignorada: uma coluna datetime de DataWindow, que traz 00:00:00, dá dias, o último incluído.
• O que o calendário também aceita: "2026-09-22T09:30", segundos, e o texto de uma coluna datetime de DataWindow. of_add_appointment tem uma sobrecarga que recebe dois datetime.
• O que os eventos devolvem: as datas na forma em que as escreveu — "yyyy-mm-dd hh:mm", fim exclusivo, para um compromisso com hora; apenas datas, ambos os dias incluídos, para um dia inteiro. É também o que is_start e is_end releem no 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)))

A faixa « dia inteiro » #

Por cima da grelha horária das vistas dia e semana, uma faixa recebe os compromissos ib_all_day e os que duram 24 horas ou mais: um seminário de três dias cabe lá numa barra em vez de esmagar três colunas. ib_all_day_band = false retira-a. Na vista mês, esses compromissos são barras que atravessam os seus dias; os outros, uma linha escrita por is_month_template.

Os compromissos de um DataStore #

of_from_datastore(ids) carrega o calendário numa só chamada: uma linha = um compromisso, e a sua chave é o seu número de linha — é ela que cada evento devolve, pronta para SetItem. Uma coluna desempenha um papel quando tem o seu nome, ou quando of_map lho atribui:

• Uma coluna booleana é verdadeira para 1, true, Y ou yes. Uma coluna status tem os valores de STATUS_* (busy, tentative, free, oof, elsewhere). Cada nome é reconhecido também com o prefixo is_: is_private, já que private é uma palavra reservada do PowerScript.
• Todas as colunas, com papel ou não, são campos dos modelos: uma coluna customer escreve-se {customer} no cartão, e lê-se com of_get_field.
• Uma coluna que desempenha ROLE_KEY substitui o número de linha como chave: reserve-a para dados que não recarrega a partir desse DataStore. Os seus valores devem ser únicos e não vazios: uma linha que não o respeita (ou cujo valor contém / ou |) mantém o seu número de linha como chave, e ue_script_error indica-o uma vez.
• O calendário nunca modifica o DataStore: diz-lhe o que o utilizador fez (ue_appointment_moved, ue_appointment_resized), faz SetItem e depois Update() quando a sua aplicação o decidir.
• Depois de um InsertRow, DeleteRow, Sort ou Filter, os números de linha mudam: volte a chamar of_from_datastore.

Recursos e agrupamento #

Um recurso é aquilo que se reserva: uma pessoa, uma sala, uma máquina (of_add_resource). Um compromisso nomeia-o através de is_resource. Com is_group_by = GROUP_RESOURCE, cada dia das vistas dia e semana divide-se em uma coluna por recurso, e arrastar um cartão para outra coluna muda o seu recurso — ue_appointment_moved devolve-o em as_resource. ib_visible = false num recurso oculta a sua coluna e os seus compromissos, como desmarcar um calendário no Outlook.

Cores, categorias e estado #

A cor de um cartão decide-se por esta ordem: o il_accent definido neste compromisso, depois a cor da sua categoria (of_add_category, is_category), depois a do seu recurso, depois o destaque do tema. O filete à esquerda indica o estado (is_status, o « Mostrar como » do Outlook: ocupado, provisório, livre, ausente, noutro local); um compromisso ib_cancelled é desenhado vazio, e ib_recurring, ib_private, ib_reminder colocam um pequeno sinal no cartão.

Propriedades #

Propriedades de um compromisso #

Um compromisso controla-se pelo seu handle, of_appointment("chave") — criado no primeiro acesso, continua válido depois. Uma propriedade lida pergunta ao componente quanto vale agora: depois de um arrastar, is_start e is_end já dizem onde o utilizador o largou.

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

Como qualquer item, um compromisso tem também o tooltip comum (is_tooltip, is_super_tooltip_title, is_super_tooltip_text, is_super_tooltip_image) — que então substitui o dos modelos — e as cores de item: il_accent recolore o cartão e o seu filete, il_back_color, il_text_color, il_back_color_hover e il_text_color_hover pintam-no em repouso e ao passar o rato.

Propriedades de um recurso e de uma categoria #

Constantes #

As constantes leem-se no objeto que as define: u_pbt_scheduler.VIEW_MONTH para uma propriedade do componente, n_pbt_scheduler_appointment.STATUS_OOF para uma propriedade de compromisso.

Métodos #

Compromissos #

DataStore #

Recursos e categorias #

Navegação e seleção #

Eventos #

Os modelos #

O que um cartão, uma linha do mês e um tooltip dizem não é fixo: é um modelo que escreve, em texto formatado ([b], [br], [color=…], [symbol=…]…) com campos entre chavetas. Quatro propriedades os definem: is_card_template (cartões das vistas dia e semana, agenda, barras do mês), is_month_template (uma linha da vista mês), is_tooltip_title_template e is_tooltip_template (o tooltip). O modelo de tooltip predefinido é:

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

A sintaxe #

Os formatos de data #

Os símbolos são os do PowerBuilder; os nomes dos dias e dos meses seguem a língua de apresentação. Um texto entre aspas é escrito tal como está. Os mesmos símbolos servem para is_time_format.

Os campos #

Um campo desconhecido escreve uma cadeia vazia.

Os símbolos #

A etiqueta de texto formatado [symbol=nome] coloca um símbolo integrado, monocromático, desenhado na cor do texto que o rodeia — segue o tema, a passagem do rato e a cor do cartão, sem ficheiro a distribuir: clock, location, person, people, calendar, repeat, lock, bell, phone, mail, video, note, tag, link, check, star, info, warning. Um nome desconhecido aparece tal como está.

O que o utilizador pode fazer sem uma linha de código #

• navegar: Hoje, anterior, seguinte, e o menu das vistas da barra de ferramentas;
• mover um compromisso para outra hora, outro dia ou outro recurso, arrastando-o — o passo segue ii_slot_minutes;
• redimensionar um compromisso arrastando a sua extremidade;
• percorrer casas vazias para escolher um intervalo → ue_range_selected — na faixa « dia inteiro » ou na vista mês, dias inteiros;
• pedir um compromisso com um duplo clique numa casa vazia ou com o + de um cabeçalho de dia (de um cabeçalho de recurso quando o calendário está agrupado) → ue_new_requested;
• abrir um compromisso com um duplo clique → ue_appointment_opened, e clicar com o botão direito num compromisso ou numa casa vazia para o seu menu.

O calendário não cria, não modifica nem elimina nada por si além do arrastar: pergunta, a sua aplicação decide. ib_read_only desliga todos estes gestos de uma vez, ib_read_only num compromisso desliga-os só para ele.

Com o teclado, depois de o calendário ter o foco:

Exemplos #

Os compromissos de um DataStore, e o que o utilizador faz com eles #

O DataStore ids_appts (variável de instância) tem as colunas subject, start_date, end_date, location, room, category e customer. As quatro primeiras desempenham o seu papel pelo nome; room recebe-o 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()

Criar e 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)

Uma coluna 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

Cartões e tooltips seus #

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

Recusar uma deslocação #

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

Carregar só o que se vê #

Com anos de histórico, não vale a pena ler tudo: ue_date_changed dá o intervalo no ecrã a cada navegação, e na primeira apresentação. Aqui d_appointments recebe dois argumentos datetime, início e fim do 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)

O seu menu num compromisso #

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

Boas práticas #

• Enquadre uma série de adições com of_set_redraw(/*on*/ false) / of_set_redraw(/*on*/ true): os compromissos aparecem de uma só vez.
• Para dados que vivem numa base, prefira of_from_datastore a um ciclo de of_add_appointment: uma só transferência, e cada evento devolve a linha.
• Recarregue (of_from_datastore) depois de qualquer InsertRow, DeleteRow, Sort ou Filter do DataStore: a chave de um compromisso é um número de linha.
• Escreva as datas como "yyyy-mm-dd hh:mm", nunca no formato regional do posto: é o único que o calendário lê em todo o lado.
• Num modelo, envolva um campo facultativo em {?campo}…{/campo}: um cartão sem local não mostra um « ; » órfão.
• Com um histórico longo, carregue o intervalo visível em ue_date_changed em vez de todo o DataStore.
• Para uma regra de negócio (nenhum compromisso ao fim de semana, nenhuma sobreposição numa sala), ib_veto_changes e ue_appointment_changing recusam antes de o cartão se mover.

Limites da 4.0 #

O que o calendário não faz — convém sabê-lo antes de o escolher:

• Periodicidade: nem séries (regras RRULE), nem exceções, nem edição « esta ocorrência / toda a série ». ib_recurring só põe um sinal no cartão: cada ocorrência é um compromisso (uma linha do DataStore) que a sua aplicação gera ela própria. Um motor de periodicidade está previsto para uma versão seguinte.
• Fusos horários: a hora é local flutuante (ver As datas); nenhuma segunda escala horária, nenhuma conversão.
• Vista cronológica (recursos em linhas, tempo em colunas) e minicalendário de navegação: ausentes; agrupe por recurso (GROUP_RESOURCE) nas vistas dia e semana.
• iCalendar: nem importação nem exportação de ficheiros .ics.
• Impressão: nenhuma; o calendário desenha-se só no ecrã.
• Teclado: seleciona-se, abre-se, elimina-se e navega-se pelo teclado, mas não se cria nem se move um compromisso sem o rato.
• Data e hora em duas colunas: um início escrito em duas colunas do DataStore não se mapeia; junte-o numa coluna datetime na consulta.

Herdado da base comum #

Estes membros existem em todos os componentes visuais — não são próprios deste. São detalhados uma só vez, nos capítulos transversais; esta tabela apenas diz onde os ler.

Duas ajudas não são herdadas: of_icon e of_escape_markup vivem em n_pbt_utils. Declare um — n_pbt_utils lnv_utils, nada a criar — e chame-as nele.

← Referência dos componentes · Índice do guia