gantt — u_pbt_gantt #

← Referência dos componentes · Índice do guia

gantt planeia um projeto: à esquerda uma grelha de tarefas (nome, início, fim, duração, progresso), à direita as suas barras numa escala de tempo — dia, semana, mês ou trimestre — com a linha de hoje (na cor de destaque) e os dias de folga sombreados. Uma tarefa que contém outras é uma tarefa de resumo, cujas datas e progresso são calculados; um marco é um losango de um dia; uma seta liga uma tarefa à que espera por ela, e o caminho crítico é desenhado a vermelho. O utilizador arrasta uma barra para a deslocar, o seu bordo final para mudar o seu fim, o pequeno triângulo por baixo para o seu progresso; ue_task_moved, ue_task_resized e ue_progress_changed dizem-lho. O plano preenche-se à mão ou a partir de um DataStore, que recebe as alterações.

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

Em resumo #

Início rápido #

// A phase : the task that holds others becomes a summary
uo_plan.of_add_task(/*keys*/ "build", /*label*/ "Build", /*start*/ "2026-11-02", /*end*/ "2026-11-20")
uo_plan.of_add_task(/*keys*/ "build/design", /*label*/ "Design", /*start*/ "2026-11-02", /*end*/ "2026-11-06")
uo_plan.of_add_task(/*keys*/ "build/code", /*label*/ "Code", /*start*/ "2026-11-09", /*end*/ "2026-11-20")

// A milestone : an instant at the end of its day, here the day the code ends
uo_plan.of_add_milestone(/*keys*/ "golive", /*label*/ "Go-live", /*date*/ "2026-11-20")

// The links : a task starts once the one before it is finished
uo_plan.of_add_dependency(/*from_keys*/ "build/design", /*to_keys*/ "build/code")
uo_plan.of_add_dependency(/*from_keys*/ "build/code", /*to_keys*/ "golive")

// What is done already
uo_plan.of_task(/*keys*/ "build/design").id_progress = 100

// event ue_task_moved of uo_plan : (string as_keys, string as_start, string as_end, string as_old_start, string as_old_end)
// Local variables
string ls_code

// The code of the task : the LAST level of its address ("build/design" -> "design")
ls_code = this.of_task(/*keys*/ as_keys).of_key()

// Save the new dates of the task
UPDATE tasks SET start_date = :as_start, end_date = :as_end WHERE code = :ls_code;

Tarefas, resumos e marcos #

Uma tarefa designa-se pelo seu endereço: a sua chave sob o seu pai, os níveis unidos por / — "build" em cima, "build/design" dentro da tarefa "build", acrescentada primeiro. Uma tarefa que contém outras torna-se uma tarefa de resumo: uma barra fina, as suas datas vão do primeiro início ao último dia do que contém, o seu progresso é a média deles ponderada pelas durações. Nem o utilizador nem o seu código escrevem as suas datas ou o seu progresso: são calculados. A sua seta, um duplo clique na sua linha ou ib_collapsed recolhem-na; segue-se ue_task_toggled.

As datas são dias inteiros, aaaa-mm-dd, o fim incluído: uma tarefa de 6 a 10 dura cinco dias, contados no calendário. of_add_task e of_add_milestone aceitam também dois date do PowerBuilder. Um marco não tem duração: um dia, um losango, nenhum progresso. Através do handle de uma tarefa (of_task(endereço)), escrever is_start desloca-a (a sua duração mantém-se), is_end muda o seu fim, id_progress o seu progresso; um valor escrito pelo seu código não levanta nada, como SetItem. O mesmo handle lê o que a tarefa é agora: as suas datas, a sua duração (of_duration), o seu lugar entre as irmãs a partir de 1 (of_position), o seu nível (of_level).

// The test starts three days later : it moves, its length stays
uo_plan.of_task(/*keys*/ "test").is_start = "2026-11-26"

// Read back what the summary computed
MessageBox("Build", uo_plan.of_task(/*keys*/ "build").is_end + " - " + String(uo_plan.of_task(/*keys*/ "build").id_progress) + " %")

Ligações e caminho crítico #

of_add_dependency liga duas tarefas com uma seta. O tipo por omissão é fim a início (DEP_FS: a seguinte começa depois de a anterior terminar); DEP_SS (início a início), DEP_FF (fim a fim) e DEP_SF (início a fim) dão-se como terceiro argumento. Uma ligação que as datas quebram — a seguinte começa cedo demais — é desenhada a tracejado na cor de perigo. Uma ligação a si mesma, entre uma tarefa e o que ela contém, uma ligação já existente ou uma que fecharia um ciclo é recusada (-5). of_dependency_type lê o tipo de uma ligação, of_predecessors e of_successors do handle as tarefas ligadas.

Com ib_critical_path = true, o caminho crítico é desenhado na cor de perigo: as tarefas e as ligações sem folga, as que empurram o fim do projeto se escorregarem um dia. of_is_critical do handle lê-o, quer o caminho esteja desenhado quer não. Com ib_link_by_mouse = true, aparecem dois pontos de cada lado da barra sob o ponteiro: o utilizador arrasta um sobre outra tarefa, e ue_link_requested dá a ligação pedida — o seu tipo segue o ponto de partida e a metade da barra de destino. O diagrama não acrescenta nada por si: of_add_dependency depois de a sua aplicação concordar. Um clique numa seta levanta ue_dependency_clicked. A folga conta-se em dias úteis (is_work_days): uma tarefa que acaba numa sexta-feira seguida de outra que começa na segunda-feira não tem nenhuma. Um marco é um instante no fim do seu dia: colocado no dia em que acaba a tarefa que segue, a ligação é cumprida, e a tarefa seguinte começa no dia seguinte. Uma ligação que toca uma tarefa de resumo vincula as tarefas que contém; uma tarefa de resumo nunca é marcada, e uma seta só é vermelha entre duas barras vermelhas. Uma tarefa terminada (100 %) nunca é marcada: já não conduz nada. is_project_end conta a folga até um prazo em vez do último fim.

Calendário: feriados, desfasamentos, marcadores e atrasos #

Um projeto segue um calendário. is_work_days indica os dias úteis da semana; of_add_holiday acrescenta um feriado, um a um — sombreado como um fim de semana, nomeado na tooltip do seu dia na escala dia, não conta nem na folga do caminho crítico nem num desfasamento. Uma ligação pode levar um desfasamento em dias úteis: of_add_dependency("design", "build", DEP_FS, 2) deixa dois dias úteis entre o fim de uma e o início da outra (uma secagem, uma entrega); negativo, é uma antecipação. A regra da seta e o caminho crítico contam-no, of_dependency_lag relê-o, um DataStore escreve-o depois do tipo ("12:fs+2"). of_add_marker traça um marcador vertical no fim de um dia — um prazo contratual, o fim de um sprint — com a sua etiqueta em cima. Por fim, com ib_show_late = true, uma tarefa atrasada — o seu último dia já passou (is_today) e não está terminada — é desenhada a âmbar tracejado; of_is_late() do seu handle e o campo {late} dos modelos dizem-no em qualquer caso.

// The public holidays of the year : days off, never float
uo_plan.of_add_holiday(/*date*/ "2026-11-11", /*label*/ "Armistice Day")
uo_plan.of_add_holiday(/*date*/ "2026-12-25", /*label*/ "Christmas")

// The paint dries two working days before the second coat
uo_plan.of_add_dependency(/*from_keys*/ "paint", /*to_keys*/ "second_coat", /*type*/ u_pbt_gantt.DEP_FS, /*lag*/ 2)

// The contractual deadline, in red
uo_plan.of_add_marker(/*key*/ "deadline", /*date*/ "2026-12-18", /*label*/ "Contract", /*color*/ RGB(/*red*/ 196, /*green*/ 43, /*blue*/ 28))

// The tasks behind schedule, in amber
uo_plan.ib_show_late = true

O que o utilizador muda #

O utilizador arrasta uma barra para deslocar a tarefa, por dias inteiros (ue_task_moved), o seu bordo final para mudar o seu fim (ue_task_resized), o pequeno triângulo por baixo da barra para o seu progresso (ue_progress_changed); uma bolha mostra as datas ou a percentagem durante o arrasto, Esc cancela. Com o teclado, Ctrl + Esquerda / Direita desloca a tarefa selecionada um dia e Ctrl + Shift + Esquerda / Direita muda o seu fim. Os eventos chegam com a tarefa já no seu lugar. Só um gesto os levanta: uma data escrita pelo seu código é muda, como SetItem. Uma tarefa de resumo não se arrasta, nem uma tarefa ou um diagrama ib_read_only.

Com ib_veto_changes = true, ue_task_changing é colocado antes de cada uma destas três alterações, com as datas e o progresso que a tarefa tomaria: devolver FALSE deixa-a como estava. Delete na tarefa selecionada levanta ue_delete_requested: o diagrama não retira nada, of_remove_task depois de a sua aplicação concordar.

Escala, grelha e disposição #

A escala (is_scale) escolhe-se na barra de ferramentas (ib_toolbar, com o botão Hoje), com Ctrl + roda — o dia sob o ponteiro fica sob o ponteiro — ou pelo seu código; segue-se ue_scale_changed. Nas escalas dia e semana, os dias de folga (is_work_days) são sombreados. A grelha mostra as colunas de is_columns, pela sua ordem, com as datas escritas segundo is_date_format; o utilizador arrasta a linha entre grelha e diagrama (ii_grid_width) e o bordo de um cabeçalho de coluna para a sua largura. O que organizou — a escala, as larguras, os resumos recolhidos — lê-se com of_get_layout, devolve-se com of_set_layout, e cada alteração levanta ue_layout_changed com a disposição inteira: guarde-a e devolva-a no próximo arranque.

O texto das barras e das tooltips #

O texto ao lado de cada barra é escrito por um modelo, is_bar_template ("{label}" por omissão, vazio para nenhum), e a tooltip de uma barra por is_tooltip_title_template e is_tooltip_template: texto formatado com etiquetas onde {owner} é um campo da tarefa — um dos seus (of_set_field), uma coluna do DataStore de onde vem, ou um campo integrado (label, key, keys, start, end, duration, days, progress, percent, milestone, summary, critical, late, level, parent). {end:d mmm} escreve uma data com os símbolos d dd ddd dddd m mm mmm mmmm yy yyyy, {?owner}…{/owner} mantém um pedaço quando o campo diz alguma coisa, {!owner}…{/owner} quando não diz nada, {x:raw} mantém um valor como etiquetas, {{ }} são chavetas. {label} e {parent} são etiquetas, como na grelha; qualquer outro valor é mostrado tal como é, nunca lido como etiquetas. Um nome de campo integrado nunca é seu: of_set_field recusa-o, e uma coluna do DataStore com esse nome fica oculta por ele. Uma tarefa com uma tooltip própria (is_tooltip do seu handle) mostra essa.

// Who does what : a field of our own on a task
uo_plan.of_set_field(/*keys*/ "build/design", /*field*/ "owner", /*value*/ "Ada")

// Beside each bar : the label, the owner when there is one, the end day
uo_plan.is_bar_template = "{label}{?owner} - [b]{owner}[/b]{/owner} [symbol=calendar] {end:d mmm}"

A partir de um DataStore #

of_from_datastore faz uma tarefa de cada linha. A sua chave é o valor da coluna ROLE_KEY — um identificador — ou, sem ela, o RowID da linha; a coluna ROLE_PARENT nomeia a chave da tarefa que a contém (vazia: em cima; um pai não encontrado ou um ciclo põe a linha em cima). Uma coluna desempenha um papel quando tem o seu nome (key, parent, label, start, end, progress, milestone, color, predecessors) ou quando of_map o diz. ROLE_MILESTONE faz um marco de qualquer valor que diga sim; ROLE_COLOR colore a barra (um RGB() do PowerBuilder ou #rrggbb); ROLE_PREDECESSORS lista as tarefas esperadas, as suas chaves separadas por vírgulas, o tipo depois de : quando não é fim a início: "12, 14:ss". As datas são lidas na ordem regional do posto. Todas as colunas são campos dos modelos. As tarefas de um carregamento anterior saem (os seus handles são libertados), as acrescentadas à mão ficam. Duas linhas com a mesma chave: a segunda passa a key~RowID; uma chave que contém / ou | toma o RowID, e os seus filhos encontram-na pelo seu valor; uma chave que uma tarefa acrescentada à mão já tem passa a key~RowID, sob o mesmo pai — nenhuma linha é alguma vez posta de lado. Uma linha com o início vazio é uma tarefa não planeada: a grelha di-lo, não tem barra e nenhum gesto a desloca. Datas e decimais são lidos quaisquer que sejam as definições regionais (12,5 vale 12.5). of_from_datastore aceita também um DataWindow ou um DataWindowChild: as linhas que o utilizador vê ao lado do gráfico, reescritas aí. Depois de um Reset ou de um Retrieve do DataStore, volte a dá-lo: os seus RowID recomeçam.

Com ib_write_back = true, um gesto escreve na linha antes do seu evento: as datas de início e de fim para uma deslocação ou um novo fim, o progresso para o triângulo — cada valor no tipo da sua coluna. O evento lê o DataStore atualizado, o Update continua a ser consigo. Um valor que o DataStore recusa repõe a tarefa como estava, e também o que já estava escrito, e levanta ue_write_back_failed em vez do evento do gesto. Depois de alterar você mesmo uma linha, of_reload_row volta a enviá-la para o diagrama; uma linha inserida entretanto também chega. Uma tarefa que retira (of_remove_task) fica de fora até ao próximo of_from_datastore: of_map e o recarregamento de outra linha não a trazem de volta, of_reload_row da sua própria linha traz. Depois de of_clear, of_reload_row recusa (-5) até um novo carregamento.

// Which column of the DataStore plays which role
uo_plan.of_map(/*role*/ u_pbt_gantt.ROLE_KEY, /*column*/ "id")
uo_plan.of_map(/*role*/ u_pbt_gantt.ROLE_PARENT, /*column*/ "parent_id")
uo_plan.of_map(/*role*/ u_pbt_gantt.ROLE_START, /*column*/ "start_date")
uo_plan.of_map(/*role*/ u_pbt_gantt.ROLE_END, /*column*/ "end_date")
uo_plan.of_map(/*role*/ u_pbt_gantt.ROLE_PREDECESSORS, /*column*/ "after")

// A change goes into the DataStore, then the rows become tasks
uo_plan.ib_write_back = true
uo_plan.of_from_datastore(/*ads*/ ids_tasks)

Propriedades #

Propriedades de uma tarefa — n_pbt_gantt_task #

O seu handle, através de of_task(endereço). Uma leitura pergunta ao diagrama o que a tarefa é agora; um valor escrito é mudo, como SetItem; ib_collapsed é uma ordem e lança ue_task_toggled. O seu of_count() conta as tarefas que contém e o seu of_keys_at(n) devolve o endereço da n-ésima.

Constantes #

Métodos #

Eventos #

Teclado e rato #

• Arrastar uma barra desloca-a por dias inteiros, o seu bordo final muda o seu fim, o pequeno triângulo por baixo o seu progresso; uma bolha mostra as datas ou a percentagem, Esc cancela.
• Cima / Baixo: a tarefa de cima, de baixo; Home / End: a primeira, a última; Page Up / Page Down: uma página mais acima, mais abaixo. A vista segue a tarefa selecionada.
• Direita abre uma tarefa de resumo recolhida e depois desce para a sua primeira tarefa; Esquerda recolhe uma tarefa de resumo aberta e depois sobe para o seu pai. Lido da direita para a esquerda, Esquerda e Direita trocam.
• Ctrl + Esquerda / Direita desloca a tarefa um dia, Ctrl + Shift + Esquerda / Direita muda o seu fim um dia.
• Enter ou duplo clique abre a tarefa, Delete pede a sua eliminação, clique direito ou tecla Menu (Shift + F10): ue_task_rclicked. Um duplo clique na linha de uma tarefa de resumo recolhe-a ou abre-a.
• Ctrl + roda muda de escala, ficando no lugar o dia sob o ponteiro; a roda sobre a grelha desloca o diagrama.
• Arrastar a linha entre grelha e diagrama muda a largura da grelha, arrastar o bordo de um cabeçalho a da sua coluna.
• O diagrama é uma paragem de Tab, a linha entre grelha e diagrama uma segunda: Esquerda / Direita deslocam-na 10 px (Shift: 50), Home oculta a grelha.
• Alt + Esquerda / Direita desloca o tempo, a seleção fica; um clique na parte vazia de uma linha do diagrama seleciona a sua tarefa.
• Perto de um bordo, durante um arrasto, o diagrama desloca-se sozinho: ao longo do tempo para uma barra, para cima ou para baixo para uma ligação.
• A barra de ferramentas é uma paragem de Tab: Esquerda / Direita passam de um botão a outro, Enter ou Espaço prime-o. No diagrama, Ctrl + Mais / Menos muda de escala, Ctrl + Home traz hoje para a vista, Ctrl + Cima / Baixo muda o progresso da tarefa em 10 pontos.
• Enquanto se traça uma ligação, a barra visada é contornada, com um bordo espesso do lado que teria; uma ligação já existente ou que fecharia um ciclo é contornada a cinzento e não é pedida.

Exemplos #

Regras de planeamento #

// Once, after the plan is built : ask before each change of the user
uo_plan.ib_veto_changes = true

// event ue_task_changing of uo_plan : nothing ends after the go-live
if as_keys <> "golive" and as_end > this.of_task(/*keys*/ "golive").is_start then return false

// and nothing moves into the past : a task already started keeps its start
if as_start < String(Today(), "yyyy-mm-dd") and as_start < this.of_task(/*keys*/ as_keys).is_start then return false
return true

Ligações traçadas com o rato #

// Once : two dots beside the bar under the pointer, the critical path in red
uo_plan.ib_link_by_mouse = true
uo_plan.ib_critical_path = true

// event ue_link_requested of uo_plan : the chart adds nothing by itself
if this.of_add_dependency(/*from_keys*/ as_from_keys, /*to_keys*/ as_to_keys, /*type*/ as_type) = -5 then
	MessageBox("Plan", "This link cannot be added.")
end if

// event ue_dependency_clicked of uo_plan : a click on an arrow removes it
this.of_remove_dependency(/*from_keys*/ as_from_keys, /*to_keys*/ as_to_keys)

Reencontrar a disposição no próximo arranque #

// The layout stored at the last start, if any
uo_plan.of_set_layout(/*layout_json*/ ProfileString(gs_ini, "plan", "layout", ""))

// event ue_layout_changed of uo_plan : store every change
SetProfileString(gs_ini, "plan", "layout", as_layout_json)

Abrir uma tarefa na sua janela #

// event ue_task_opened of uo_plan
// Local variables
long ll_row

// The row of the task in the DataStore, whatever key the task had to take
ll_row = this.of_task(/*keys*/ as_keys).of_row()

// A task added by hand has no row
if ll_row = 0 then return

// Edited in your window, then the task follows its row
OpenWithParm(w_task_edit, ll_row)
this.of_reload_row(/*row*/ ll_row)

Boas práticas #

• Fases como tarefas de resumo: dois ou três níveis bastam, o utilizador recolhe o que não acompanha.
• Ligações em vez de datas copiadas: uma ligação que as datas quebram vê-se, uma data copiada engana-se em silêncio.
• O caminho crítico ligado quando é preciso cumprir uma data: mostra onde um dia de atraso custa um dia ao projeto.
• Guarde em ue_task_moved (ou deixe ib_write_back escrever o DataStore): o diagrama mostra o novo planeamento antes de a base de dados o saber.
• Devolva a disposição (ue_layout_changed, of_set_layout): a escala e as larguras que o utilizador escolheu são dele.

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