4D Progress

4D inclui um novo recipiente integrado chamado 4D Progress. Este componente lhes permite abrir uma ou mais barras deprogresso em uma mesma janela (como a interface do Finder em Mac OS).Cada barra de progresso recebe um ID que é gerado automaticamente pelo método Progress New. Este ID é utilizado portodos os métodos projeto do recipiente para administrar as propriedades e valores nas caixas de diálogo de progresso.Os métodos projeto para este componente se listam na página Métodos recipiente do Explorador:

Barras de progresso Lista alfabética dos comandos

- 1 -

Barras de progresso

Progress Get Button Enabled Progress Get Button Title Progress Get Icon Progress Get Message Progress Get On Error Method Progress Get On Stop Method Progress Get Progress Progress Get Title Progress New Progress QUIT Progress SET BUTTON ENABLED Progress SET BUTTON TITLE Progress SET FONT SIZES Progress SET FONTS Progress SET ICON Progress SET MESSAGE Progress SET ON ERROR METHOD Progress SET ON STOP METHOD Progress SET PROGRESS Progress SET TITLE Progress SET WINDOW VISIBLE Progress Stopped

- 2 -

Progress Get Button Enabled

Progress Get Button Enabled ( id ) -> Resultado Parâmetro Tipo Descriçãoid Inteiro longo ID da barra de progressoResultado Booleano True = botão Stop mostrado; caso contrário, False

Descrição

O método Progress Get Button Enabled devolve True quando a barra de progresso designada pelo parâmetro id mostraum botão Stop. Se não mostra um (funcionamento por padrão), o método devolve False.

- 3 -

Progress Get Button Title

Progress Get Button Title ( id ) -> Resultado Parâmetro Tipo Descriçãoid Inteiro longo ID da barra de progressoResultado Texto Title of Stop button

Descrição

Nota: Este método só pode ser utilizado em Windows. Em Mac OS, os botões para parar não tem títulos.O método Progress Get Button Title devolve o título atual do botão stop para a barra de progresso designada peloparâmetro id.Por padrão, o título é "Stop". Note que o método devolve o título atual inclusive se o botão Stop não é mostrado.

- 4 -

Progress Get Icon

Progress Get Icon ( id ) -> Resultado Parâmetro Tipo Descriçãoid Inteiro longo ID da barra de progressoResultado Imagem Ícone da barra de progresso

Descrição

O método Progress Get Icon devolve o ícone da barra de progresso designada pelo parâmetro id.

- 5 -

Progress Get Message

Progress Get Message ( id ) -> Resultado Parâmetro Tipo Descriçãoid Inteiro longo ID da barra de progressoResultado Texto Mensagem da barra de progresso

Descrição

O método Progress Get Message devolve a mensagem da barra de progresso designada pelo parâmetro id.

- 6 -

Progress Get On Error Method

Progress Get On Error Method -> Resultado Parâmetro Tipo DescriçãoResultado Texto Nome do método chamado em caso de erro (se definido)

Descrição

O método Progress Get On Error Method devolve o nome do método projeto da base local chamada em caso de errodurante o uso de uma barra de progresso.Se não se define um método de erro, este método devolve uma cadeia vazia.

- 7 -

Progress Get On Stop Method

Progress Get On Stop Method ( id ) -> Resultado Parâmetro Tipo Descriçãoid Inteiro longo ID da barra de progressoResultado Texto Nome do método chamado em caso de clique no botão Stop (se definido)

Descrição

O método Progress Get On Stop Method devolve o nome do método de projeto da base local chamada quando o usuáriofaz clique no botão Stop da barra de progresso designada pelo parâmetro id.Se nenhum método está associado ao botão Stop, este método devolve uma cadeia vazia.

- 8 -

Progress Get Progress

Progress Get Progress ( id ) -> Resultado Parâmetro Tipo Descriçãoid Inteiro longo ID da barra de progressoResultado Real Valor da barra de progresso

Descrição

O método Progress Get Progress devolve o valor atual associado a barra de progresso designada pelo parâmetro id.

- 9 -

Progress Get Title

Progress Get Title ( id ) -> Resultado Parâmetro Tipo Descriçãoid Inteiro longo ID da barra de progressoResultado Texto Título da barra de progresso

Descrição

O método Progress Get Title devolve o título principal da barra de progresso designada pelo parâmetro id.

- 10 -

Progress New

Progress New -> Resultado Parâmetro Tipo DescriçãoResultado Inteiro longo ID da nova barra de progresso

Descrição

O método Progress New cria uma nova barra de progresso e devolve seu número de ID. Este número é único durante aduração da barra de progresso mas pode ser reutilizado posteriormente.A primeira vez que é chamado este método, é criado um processo local e uma nova janela centrada se abre sobre a janelaprincipal. Por padrão, esta janela:

contém uma barra de progresso indefinidanão tem uma mensagem.

- 11 -

Progress QUIT

Progress QUIT ( id ) Parâmetro Tipo Descriçãoid Inteiro longo ID da barra de progresso

Descrição

O método Progress QUIT fecha a barra de progresso referenciada pelo parâmetro id.Se id designa a única barra de progresso mostrada, a janela de progresso também fecha (e também o processo local).Caso contrário, a janela se redimensiona com o propósito de só conter as barras de progresso abertas.Pode passar 0 no parâmetro id com o objetivo de parar todas as barras de progresso e fechar a janela de progresso.

Exemplo

Se a barra chamada "Copying folder 3" tem o número de ID 3:

Progress QUIT(3)

Se uma janela de progresso já está aberta quando se chama este método, esta janela se redimensiona para mostrar umanova barra de progresso debaixo da anterior no mesmo processo:

- 12 -

Progress SET BUTTON ENABLED

Progress SET BUTTON ENABLED ( id ; botao ) Parâmetro Tipo Descriçãoid Inteiro longo ID da barra de progressobotao Booleano True = Mostrar, False = Ocultar

Descrição

O método Progress SET BUTTON ENABLED permite agregar um botão Stop a barra de progresso designada peloparâmetro id.Por padrão, as barras de progresso não tem botões Stop. Se passar True no parâmetro botao, é mostrado um botão:

Pode lidar o efeito do clique no botão Stop utilizando o método Progress SET ON STOP METHOD ou provando o valor dométodo Progress Stopped.

- 13 -

Progress SET BUTTON TITLE

Progress SET BUTTON TITLE ( id ; titulo ) Parâmetro Tipo Descriçãoid Inteiro longo ID da barra de progressotitulo Texto Título do botão Stop (Windows)

Descrição

Nota: Este método só pode ser utilizado em Windows. Em Mac OS, os botões stop não tem títulos.O método Progress SET BUTTON TITLE permite modificar o título do botão Stop da barra de progresso designada peloparâmetro id. Por padrão, o título deste botão é "Stop":

Por padrão, as barras de progresso não tem botões Stop. Para que uma barra de progressão contenha um botão Stop,deve utilizar o método Progress SET BUTTON ENABLED.

Exemplo

Você quer utilizar o título "Abort":

<>ID:=Progress New ... Progress SET BUTTON TITLE(<>ID;"Abort")

- 14 -

Progress SET FONT SIZES

Progress SET FONT SIZES ( tamTitulos {; tamMensagens {; tamBotoes}} ) Parâmetro Tipo DescriçãotamTitulos Inteiro longo Tamanho da fonte para os títulostamMensagens Inteiro longo Tamanho da fonte para as mensagenstamBotoes Inteiro longo (Windows) Tamanho da fonte para os botões Stop

Descrição

O método Progress SET FONT SIZES permite mudar o tamanho da fonte utilizada para os diferentes textos mostrados emtodas as janelas de progresso.Nos parâmetros tamTitulos, tamMensagens e tamBotoes, passe os tamanhos das fontes a utilizar. Se não quer modificarum tamanho, passe -1 no parâmetro correspondente.

Exemplo 1

Queremos mudar unicamente o tamanho das mensagens:

Progress SET FONT SIZES(-1;13)

Exemplo 2

Queremos mudar o tamanho dos títulos e das mensagens:

Progress SET FONTS("Arial Black";"Arial narrow") Progress SET FONT SIZES(13;12)

- 15 -

Progress SET FONTS

Progress SET FONTS ( fonteTitulos {; fonteMensagens {; fonteBotoes}} ) Parâmetro Tipo DescriçãofonteTitulos Texto Fonte a utilizar para os títulosfonteMensagens Texto Fonte a utilizar para as mensagensfonteBotoes Texto (Windows) Fonte a utilizar para os botões Stop

Descrição

O método Progress SET FONTS permite mudar as fontes utilizadas para os diferentes textos mostrados em todas asjanelas de progresso.Nos parámetros fonteTitulos, fonteMensagens e fonteBotoes, passe os nomes das fontes a utilizar. Se não desejamodificar uma fonte, passe uma cadeia vazia ("") no parâmetro correspondente.

Exemplo

Queremos mudar a fonte das mensagens:

Progress SET FONTS("";"Arial")

- 16 -

Progress SET ICON

Progress SET ICON ( id ; icone {; primeiroPlano} ) Parâmetro Tipo Descriçãoid Inteiro longo ID da barra de progressoicone Imagem Imagem a mostrar como iconeprimeiroPlano Booleano Mostrar a barra de progresso no primeiro plano

Descrição

O método Progress SET ICON permite modificar o ícone mostrado na barra de progresso. Por padrão, se mostram osseguintes ícones:

Em id, passe o número de id único da barra de progresso, devolvido pelo método Progress New.Em icone, passe a imagem (variável ou campo) a utilizar como ícone na janela da barra de progresso. O tamanho máximodeste ícone deve ser:

Em Mac OS, 40 x 40 píxelsEm Windows, 40 x 80 píxels

Se passar um ícone com um tamanho que é menor a estes limites, se centra e não se redimensiona. No entanto, quando seutamanho supera estes limites, se centra e redimensiona.Passe True em primeiroPlano se quer forçar o passo da janela de progresso ao primeiro plano da aplicação.Exemplos de ícones personalizados:

- 17 -

Progress SET MESSAGE

Progress SET MESSAGE ( id ; mensagem {; primeiroPlano} ) Parâmetro Tipo Descriçãoid Inteiro longo ID da barra de progressomensagem Texto Mensagem da barra de progressoprimeiroPlano Booleano Mostrar a barra de progresso no primeiro plano

Descrição

O método Progress SET MESSAGE permite modificar a mensagem mostrada na barra de progresso.Em id, passe o número de ID único da barra de progresso, devolvido pelo método Progress New.Em mensagem, passe o texto a modificar sob o título principal (Windows) ou sob a barra de progresso (Mac OS).Passe True em primeiroPlano se quer forçar o passo da janela de progresso ao primeiro plano da aplicação.

- 18 -

Progress SET ON ERROR METHOD

Progress SET ON ERROR METHOD ( nomMetodo ) Parâmetro Tipo DescriçãonomMetodo Texto Nome do método do erro

Descrição

O método Progress SET ON ERROR METHOD designa um método a executar em caso de um erro durante a utilizaçãodas barras de progresso (por exemplo id desconhecido, número de parâmetros incorreto, etc.).Em nomMetodo, passe o nome do método projeto da base local a chamar em caso de erro. Este método é compartilhadopor todas as janelas de progresso da aplicação.Nota: Dado que o método Progress SET ON ERROR METHOD pertence a um componente, deve lembrar designar apropriedade "Compartilhado entre componentes e base local" ao método nomMetodo; caso contrário se devolve um erro.O método nomMetodo se chama com três parâmetros::

$1 (Inteiro longo): número do erro$2 (Texto): texto do erro$3 (Inteiro longo): identificador único da barra de progresso

Exemplo

Este é um exemplo de um método chamado em caso de erro. Este método se declara "compartilhado" em modo Desenho:

C_LONGINT($1) C_TEXT($2) C_LONGINT($3) C_LONGINT($ErrorID) C_TEXT($ErrorText) C_LONGINT($ProgressID) $ErrorID:=$1 $ErrorText:=$2 $ProgressID:=$3 $Error:="" $Error:=$Error+"Error number: "+String($ErrorID)+Char(Carriage return) $Error:=$Error+$ErrorText+Char(Carriage return) $Error:=$Error+"Progress ID: "+String($ProgressID) ALERT($Error)

- 19 -

Progress SET ON STOP METHOD

Progress SET ON STOP METHOD ( id ; nomMetodo ) Parâmetro Tipo Descriçãoid Inteiro longo ID da barra de progressonomMetodo Texto Nome do método de stop

Descrição

O método Progress SET ON STOP METHOD designa um método a executar quando o usuário faz clique no botão Stopda barra de progresso.Por padrão, as barras de progresso não tem botões Stop. Se quer que uma barra de progresso tenha um, deve usar ométodo Progress SET BUTTON ENABLED.Em id, passe o identificador único da barra de progresso, devolvido pelo método Progress New.Em nomMetodo, passe o nome do método projeto da base local a chamar quando se faz clique no botão Stop. Estemétodo recebe o identificador único da barra de progresso como seu primeiro parâmetro. A continuação, se executa em umnovo processo lançado pelo recipiente. Nota: Como o método Progress SET ON STOP METHOD pertence a um recipiente, deve lembrar designar a propriedade"Compartilhado entre recipientes e base local" ao método nomMetodo; caso contrário devolve um erro.

- 20 -

Progress SET PROGRESS

Progress SET PROGRESS ( id ; progresso {; mensagem {; primeiroPlano}} ) Parâmetro Tipo Descriçãoid Inteiro longo ID da barra de progressoprogresso Real Valor de progresso([0...1] ou -1)mensagem Texto Mensagem da barra de progressoprimeiroPlano Booleano Mostrar a barra de progresso no primeiro plano

Descrição

O método Progress SET PROGRESS modifica o valor da barra de progresso junto com a informação mostrada na janelade progresso. Este método é útil para a atualização de uma barra de progresso dentro de um bucle.Em id, passe o número de ID único da barra de progresso, devolvido pelo método Progress New.Em progresso, passe o valor atual da barra de progresso. Pode passar um valor Real (entre 0 e 1) ou -1 para especificaruma barra de progresso indefinida (também conhecido como "Barber shop" em Mac OS).Em mensagem, passe um texto adicional para mostrar debaixo do título principal (Windows) ou sob a barra de progresso(Mac OS). Este parâmetro é opcional.Passe True em primeiroPlano quando queira forçar o passo da janela de progresso ao primeiro plano da aplicação.

Exemplo

Atualização da barra de progresso:

$P:=Progress New // criamos uma nova barra // Realizar um processo em um bucle For($i;1;100) // ... código do processo // Atualizar a barra de progresso $r:=$i/100 Progress SET PROGRESS($P;$r;"More info") End for // Eliminação da barra uma vez termina o processo PROGRESS QUIT($P)

- 21 -

Progress SET TITLE

Progress SET TITLE ( id ; titulo {; progresso {; mensagem {; primeiroPlano}}} ) Parâmetro Tipo Descriçãoid Inteiro longo ID da barra de progressotitulo Texto Título da barra de progressoprogresso Real Valor de progresso ([0...1] ou -1)mensagem Texto Mensagem da barraprimeiroPlano Booleano Mostrar a barra de progresso no primeiro plano

Descrição

O método Progress SET TITLE define o título da barra de progresso junto com a informação que é mostrada na janela deprogresso.Em id, passe o identificador único da barra de progresso, devolvido pelo método Progress New.Em titulo, passe o texto principal a mostrar na janela de progresso.Em progresso, passe o valor atual da barra de progresso (opcional). Pode passar um valor real (entre 0 e 1) ou -1 paradefinir uma barra de progresso indefinida (também conhecida como "Barber shop" em Mac OS).Em mensagem, passe um texto adicional a mostrar no título principal (Windows) ou na barra de progresso (Mac OS). Esteparâmetro é opcional.Passe True em primeiroPlano se deseja forçar o passo da janela de progresso ao primeiro plano da aplicação.

Exemplo

Criação de uma janela de progresso simples:

$P:=Progress New Progress SET TITLE($P;"Copying folder";-1;"Counting files

- 22 -

Progress SET WINDOW VISIBLE

Progress SET WINDOW VISIBLE ( visivel {; posHor ; posVert {; primeiroPlano}} ) Parâmetro Tipo Descriçãovisivel Booleano True = Mostrar, False = OcultarposHor Inteiro longo Coordenada esquerda da janela

-1 = Não mudarposVert Inteiro longo Coordenada superior da janela

-1 = Não mudarprimeiroPlano Booleano Mostrar barra de progresso no primeiro plano

Descrição

O método Progress SET WINDOW VISIBLE permite administrar a visualização da janela de progressão, se existe.O parâmetro visivel indica se a janela deve ser visível ou não (por padrão, a janela é visível). Passe False neste parâmetropara ocultar a janela e True para mostrar ela novamente, se existe.Os parâmetros posHor e posVert modificam a localização da janela de progresso na tela. Nestes parâmetros, passe valoresque representem o movimento em píxels a direita (posHor) ou para abaixo (posVert) com respeito as coordenadas da janelaprincipal da aplicação (em Windows) ou na tela (em Mac OS).Para não modificar as coordenadas (por exemplo, se quer utilizar o parâmetro primeiroPlano sem mudar a posição dajanela), passe -1 em cada um destes parâmetros.Passe True em primeiroPlano se quer forçar o passo da janela de progresso ao primeiro plano da aplicação.

Exemplo 1

Localizar a barra de progresso de 50 píxels desde a esquina esquerda e 100 píxels da esquina superior:

Progress SET WINDOW VISIBLE(True;50;100)

Exemplo 2

Ocultar a janela de progresso:

Progress SET WINDOW VISIBLE(False)

Exemplo 3

Mostrar a janela de progresso e passar ela ao primeiro plano sem modificar sua posição:

Progress SET WINDOW VISIBLE(True;-1;-1;True)

- 23 -

Progress Stopped

Progress Stopped ( id ) -> Resultado Parâmetro Tipo Descriçãoid Inteiro longo ID da barra de progressoResultado Booleano True = o usuário fez clique no botão Stop

Descrição

O método Progress Stopped devolve True se o usuário faz clique no botão Stop da barra de progresso designada peloparâmetro id.Deve chamar este método para provar se o usuário fez clique no botão Stop. O botão não dispara um evento.

Exemplo

Exemplo de barra de progresso em um laço:

$ProgressID:=Progress New // criação de uma nova barra // A barra de progresso deve ter um botão Stop Progress SET BUTTON ENABLED($ProgressID;True) For($i;1;100) // Enquanto o progresso não seja detido... If(Not(Progress Stopped($ProgressID))) Progress SET TITLE($ProgressID;"Test progress #"+String($ProgressID)) Progress SET PROGRESS($ProgressID;$i/100) Progress SET MESSAGE($ProgressID;String(100*$i/100)+" %") (...) Else // O usuário faz clique em Stop $i:=100 // Saímos do laço End if End for // Fecho final da barra (o botão Stop não faz nada) Progress QUIT($ProgressID)

- 24 -