Barra de progresso no Delphi: os componentes TfrProgressBar e TfrxProgressBar do FastReport VCL

O indicador de progresso — um dos elementos mais ilustrativos da interface: ele mostra instantaneamente quanto trabalho já foi feito e quanto resta até a conclusão do processo. Neste artigo, veremos como adicionar esse indicador tanto à interface de um aplicativo Delphi quanto aos relatórios — com a ajuda dos novos componentes TfrProgressBar e TfrxProgressBar.

Usuários de FastReport VCL Ultimate têm disponíveis componentes adicionais de interface visual no âmbito dos conjuntos FastEditors VCL e FastGrid VCL. Agora esses conjuntos foram ampliados com um novo editor útil — o TfrProgressBar, e os relatórios — com o componente TfrxProgressBar. Além disso, o componente de relatórios está disponível não apenas para os proprietários do Ultimate, mas para todos que têm acesso ao componente principal de relatórios — o TfrxReport.

A seguir, examinaremos em detalhe as propriedades e os recursos dos novos componentes e, em seguida, os mostraremos em ação: no exemplo de um projeto de demonstração com dados realistas, que acompanha o FastReport VCL Ultimate.

Componente TfrProgressBar: propriedades e recursos

O componente ProgressBar está disponível na IDE, na paleta FastEditors VCL, e destina-se à exibição de valores numéricos no formato de indicador de progresso. O componente:

• suporta direção horizontal e vertical da escala;
• calcula e exibe automaticamente o valor percentual em relação ao intervalo limite especificado;
• contém uma coleção de linhas-marcadoras e valores de limite, que permitem visualizar os intervalos da escala de progresso em diversos estilos: preenchimento sólido, preenchimento em gradiente, textura.

Examinemos as principais propriedades que distinguem este componente de progresso dos outros editores do conjunto FastEditors VCL.

• Value — o valor numérico exibido. O componente o formata automaticamente conforme as configurações de estilo visual e o intervalo de valores. Se o ProgressBar for usado dentro de uma célula do componente FastGrid, o valor dessa célula será usado automaticamente como Value.
• Properties.CaptionColor — a cor do texto exibido. Se esta propriedade tiver o valor clDefault, a cor do texto se ajusta automaticamente à cor de fundo, de modo que a legenda fique visível em qualquer fundo.
• Properties.CaptionHorizontalAlignment — alinhamento do texto na horizontal.
• Properties.CaptionVerticalAlignment — alinhamento do texto na vertical.
• Properties.CaptionOrientation — direção horizontal ou vertical do texto.
• Properties.CaptionType — o tipo de formatação do texto. Pode assumir os valores frpbctPercent (cálculo automático do valor percentual em função do intervalo MinValue/MaxValue), frpbctPosition (exibição da representação textual da propriedade Value sem formatação) ou frpbctCustom (exibição do texto gravado na propriedade Properties.ProgressCaption).
• Properties.MarkerLinesVisible — controla a visibilidade das linhas-marcadoras na escala de progresso. Essas linhas são definidas na coleção Properties.Thresholds.
• Properties.MaxValue — o valor máximo da escala para o cálculo do percentual de progresso. Não pode ser menor que o valor de Properties.MinValue.
• Properties.MinValue — o valor mínimo da escala para o cálculo do percentual de progresso. Não pode ser maior que o valor de Properties.MaxValue.
• Properties.Orientation — a direção de mudança do nível da escala de progresso em função do Value: da esquerda para a direita ou de cima para baixo.
• Properties.ProgressBarStyle — o estilo de exibição da escala de progresso. Pode assumir os valores frpbsSolid (preenchimento sólido com a cor Properties.ProgressBeginColor), frpbsGradient (preenchimento em gradiente com transição suave de cor de Properties.ProgressBeginColor até Properties.ProgressEndColor) ou frpbsBitmap (preenchimento com textura da propriedade Properties.ProgressBitmap).
• Properties.ProgressBeginColor — a cor inicial da escala de progresso.
• Properties.ProgressEndColor — a cor final da escala de progresso.
• Properties.ProgressBitmap — a textura para o preenchimento da escala de progresso no caso Properties.ProgressBarStyle = frpbsBitmap.
• Properties.ProgressCaption — o texto da legenda para o caso Properties.CaptionType = frpbctCustom.
• ProgressChunkBorder — controle da visibilidade da linha de contorno para o estilo de preenchimento em gradiente da escala principal e dos valores de limite.
• Properties.ProgressMargin — a medida do recuo da escala de progresso em relação às bordas do componente.
• Properties.ShowAsLEDs — ativação e desativação da divisão visual da escala de progresso em retângulos.
• Properties.Thresholds — coleção de valores de limite (mais sobre ela — abaixo).
• Properties.OnGetDisplayText — um evento que permite alterar manualmente, no código, o texto exibido na escala (parâmetro AText) em função do valor do parâmetro AValue.

Valores de limite: a coleção Properties.Thresholds

Todas essas propriedades permitem ajustar com flexibilidade o estilo visual da exibição da escala de progresso e, se necessário, usar vários intervalos de valores e marcadores diferentes:

Cada valor de limite da coleção Properties.Thresholds tem as seguintes propriedades:

• Value — o valor da escala a partir do qual o estilo e as cores de preenchimento da escala mudam para os especificados neste valor de limite;
• BeginColor — a cor inicial do preenchimento deste valor de limite;
• EndColor — a cor final do preenchimento deste valor de limite;
• MarkerLineColor — a cor da linha-marcadora que assinala o Value na escala;
• MarkerLineSize — a espessura da linha-marcadora que assinala o Value na escala;
• MarkerLineVisible — controle da visibilidade da linha-marcadora;
• ProgressBarStyle — o estilo de preenchimento da escala de progresso deste limite;
• ProgressBorderVisible — controle da visibilidade da linha de contorno deste limite;
• ProgressVisible — controle da visibilidade da escala de progresso deste limite (se a escala de progresso do limite não estiver visível, usam-se para ela os parâmetros da escala principal — isso é conveniente quando se precisa representar apenas a linha-marcadora).

Componente de relatório TfrxProgressBar

Um conjunto semelhante de propriedades é oferecido pelo componente especial TfrxProgressBar, disponível nos relatórios. Para incorporá-lo ao seu relatório:

1.    coloque no formulário o componente não visual TfrxProgressBarObject — ele adicionará automaticamente os módulos necessários ao seu projeto;
2.    abra o designer de relatórios usando o componente TfrxReport;
3.    selecione o componente de progresso no painel de componentes e coloque-o na página do relatório.

Em comparação com o componente de interface, o componente de relatório tem uma série de particularidades:

• ShowGeneralBorder — permite mostrar ou ocultar uma moldura ao redor do objeto;
• DataField e DataSet — permitem vincular o componente a um dos campos do conjunto de dados e obter automaticamente os valores de progresso dele;
• ProgressCaptionExpression — permite definir uma expressão para formatar manualmente o valor de progresso obtido do campo de dados.

Exemplo de uso: controle de temperatura do forno de fusão

O componente de exibição de progresso é conveniente para usar em aplicativos em que é preciso visualizar valores ao longo do tempo em comparação com valores limite e de limite: em sistemas de controle de processos, para acompanhamento de KPIs ou para controle do grau de ocupação do armazém.
Para demonstrar os recursos do ProgressBar, escolhemos a metalurgia. É nela que os valores de limite de temperatura e a variabilidade do processo tecnológico de fusão são importantes, e as amostras de dados servem bem para impressão. Em outras palavras, aqui há tudo aquilo em que o ProgressBar é bom.

Simulação do processo de fusão

Primeiro, escreveremos um pequeno código auxiliar que imita as oscilações dos sensores de temperatura em várias zonas do forno de fusão: zona de carregamento, zona de fusão, zona de superaquecimento, zona de descarga e revestimento. Em cada zona, a temperatura oscila aleatoriamente em torno dos valores nominais ao longo das seguintes fases do processo: aquecimento, fusão, superaquecimento, correção. Naturalmente, este é um esquema muito simplificado, que não corresponde ao processo real, mas para demonstrar os recursos do componente essa simulação é perfeita.

O código-fonte da simulação pode ser encontrado no projeto de demonstração do FastGrid, nos módulos frFurnaceZones e frFurnaceSimulator, e o código principal de trabalho com o componente — no módulo ProgressBarDemo.

Configuração da coluna FastGrid e dos componentes de progresso

O trabalho principal neste projeto acontece nos manipuladores de eventos OnShow e UpdateUI.

Em OnShow, um conjunto de dados é criado com base no componente padrão TClientDataSet, e a vinculação desses dados ao FastGrid é implementada. Naturalmente, o FastGrid sabe trabalhar com dados diretamente, sem intermediário na forma de DataSet, mas neste projeto queríamos mostrar as possibilidades de impressão de dados formatados com o ProgressBar, tanto diretamente da fonte quanto por meio do FastGrid. E para isso, um armazenamento de dados universal na forma de TClientDataSet ou de outro componente semelhante é mais adequado.

Em seguida, no manipulador OnShow, são configuradas as propriedades da coluna FastGrid responsável pela exibição do progresso, bem como as propriedades dos componentes TfrProgressBar individuais localizados no diagrama do forno de fusão:

gFurnaceTableView1.Columns.RetrieveMissingColumns;
LColumn := gFurnaceTableView1.Columns[0];
LColumn.Caption := 'Furnace Zone';
LColumn.Options.Editing := False;
LColumn.PropertiesClass := TfrEditProperties;
LColumn := gFurnaceTableView1.Columns[1];
LColumn.Caption := 'Temperature, C';
LColumn.Width := 300;
LColumn.PropertiesClass := TfrProgressBarProperties;
LProperties := TfrProgressBarProperties(LColumn.Properties);
LProperties.CaptionType := frpbctPosition;
LProperties.CaptionColor := clBlack;
LProperties.ProgressBarStyle := frpbsGradient;
LProperties.MaxValue := FConfig.ScaleMax;
LProperties.MinValue := FConfig.ScaleMin;
LProperties.MarkerLinesVisible := True;
LProperties.CaptionType := frpbctPosition;
LProperties.ProgressBeginColor := clWhite;
LProperties.ProgressEndColor := FConfig.Thresholds[0].Color;
LProperties.ProgressChunkBorder := False;
LProperties.OnGetDisplayText := DoGetDisplayText;
for J := 1 to Length(FConfig.Thresholds) - 1 do
begin
  LThresholdItem := LProperties.Thresholds.Add;
  LThresholdItem.MarkerLineVisible := False;
  LThresholdItem.ProgressBarStyle := frpbsGradient;
  LThresholdItem.MarkerLineVisible := FConfig.Thresholds[J].Caption = 'Overheat';
  LThresholdItem.MarkerLineSize := 2;
  LThresholdItem.Value := FConfig.Thresholds[J - 1].UpperBound;
  LThresholdItem.BeginColor := FConfig.Thresholds[J - 1].Color;
  LThresholdItem.EndColor := FConfig.Thresholds[J].Color;
end;
pbLoading.Properties.Assign(LProperties);
pbLoading.Properties.Thresholds.Assign(LProperties.Thresholds);
pbLoading.Properties.CaptionType := frpbctPercent;
pbMelting.Properties.Assign(LProperties);
pbMelting.Properties.Thresholds.Assign(LProperties.Thresholds);
pbMelting.Properties.CaptionType := frpbctPercent;
pbDischarge.Properties.Assign(LProperties);
pbDischarge.Properties.Thresholds.Assign(LProperties.Thresholds);
pbDischarge.Properties.Orientation := frpboVertical;
pbDischarge.Properties.CaptionType := frpbctPercent;
pbOverheat.Properties.Assign(LProperties);
pbOverheat.Properties.Thresholds.Assign(LProperties.Thresholds);
pbOverheat.Properties.Orientation := frpboVertical;
pbOverheat.Properties.CaptionType := frpbctPercent;
pbLining.Properties.Assign(LProperties);
pbLining.Properties.Thresholds.Assign(LProperties.Thresholds);
pbLining.Properties.Orientation := frpboVertical;
pbLining.Properties.CaptionType := frpbctPercent;

Para saber mais sobre o trabalho com o componente FastGrid, você pode ler o artigo «Visão detalhada dos recursos da biblioteca FastGrid».

Atualização dos dados por temporizador

No manipulador do evento UpdateUI, os valores no conjunto de dados e nos componentes individuais são atualizados por temporizador:

procedure TfrmProgressBar.UpdateUI;
var
  I: Integer;
  LZoneRuntime: TFurnaceZoneRuntime;
  LControl: TfrProgressBar;
  LZoneName: string;
begin
  dmData.cdsZones.DisableControls;
  try
    dmData.cdsZones.First;
    for I := 0 to Length(FProcess.FRuntime) - 1 do
    begin
      LZoneRuntime := FProcess.FRuntime[I];
      dmData.cdsZones.Edit;
      dmData.cdsZones.FieldByName('Temperature').AsFloat := LZoneRuntime.CurrentTemp;
      dmData.cdsZones.Post;
      dmData.cdsZones.Next;
      LZoneName := LZoneRuntime.Zone.Name;
      if LZoneName = 'Loading zone' then
        LControl := pbLoading
      else if LZoneName = 'Melting zone' then
        LControl := pbMelting
      else if LZoneName = 'Overheat zone' then
        LControl := pbOverheat
      else if LZoneName = 'Discharge zone' then
        LControl := pbDischarge
      else
        LControl := pbLining;
      LControl.Value := LZoneRuntime.CurrentTemp;
    end;
  finally
    dmData.cdsZones.EnableControls;
  end;
  // General progress
  lOrders.Caption := ' Furnace Grid - Progress: ' +
    IntToStr(Round(FProcess.Progress01 * 100)) + ' % finished. ' +
    Format('Melting time: %s', [FormatDateTime('nn:ss', FProcess.TotalElapsed / SecsPerDay)]);
end;

Configuração do componente de relatório

A configuração do componente de relatório e sua vinculação aos dados são feitas no designer de relatórios da seguinte forma:

Como resultado, obtemos um pequeno aplicativo que demonstra claramente as fases de aquecimento e fusão no forno:

E, a qualquer momento, é possível obter uma amostra dos dados de temperatura na forma de relatório:

Conclusão

Os componentes TfrProgressBar e TfrxProgressBar — ferramentas práticas que permitem adicionar indicação visual de progresso não apenas à interface do usuário do seu aplicativo, mas também aos relatórios. A vinculação aos dados, a incorporação em células da grade, as configurações flexíveis de estilos de escala e texto — tudo isso ajuda a apresentar a informação de forma fácil, rápida e agradável de perceber.

Se entre as suas tarefas estão o monitoramento de processos tecnológicos, painéis de KPI ou relatórios sobre o andamento de tarefas — baixe a versão mais recente do FastReport VCL Ultimate, abra o projeto de demonstração do FastGrid e experimente o novo indicador de progresso nos seus próprios dados.