4D Progress Barras de progresso Lista alfabética dos comandos

(1)

4D Progress

4D inclui um novo recipiente integrado chamado 4D Progress. Este componente lhes permite abrir uma ou mais barras de progresso 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 por todos 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

(2)

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

(3)

Progress Get Button Enabled

Progress Get Button Enabled ( id ) -> Resultado

Parâmetro Tipo Descrição

id Inteiro longo ID da barra de progresso

Resultado 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 mostra um botão Stop. Se não mostra um (funcionamento por padrão), o método devolve False.

(4)

Progress Get Button Title

Progress Get Button Title ( id ) -> Resultado

Resultado 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 pelo parâ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.

(5)

Progress Get Icon

Progress Get Icon ( id ) -> Resultado

Resultado 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.

(6)

Progress Get Message

Progress Get Message ( id ) -> Resultado

id Inteiro longo ID da barra de progresso Resultado 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.

(7)

Progress Get On Error Method

Progress Get On Error Method -> Resultado Parâmetro Tipo Descrição

Resultado 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 erro durante o uso de uma barra de progresso.

Se não se define um método de erro, este método devolve uma cadeia vazia.

(8)

Progress Get On Stop Method

Progress Get On Stop Method ( id ) -> Resultado

Resultado 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ário faz 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.

(9)

Progress Get Progress

Progress Get Progress ( id ) -> Resultado

Resultado 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.

(10)

Progress Get Title

Progress Get Title ( id ) -> Resultado

Resultado 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.

(11)

Progress New

Progress New -> Resultado

Resultado 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 a duraçã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 janela principal. Por padrão, esta janela:

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

(12)

Progress QUIT

Progress QUIT ( id )

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 uma nova barra de progresso debaixo da anterior no mesmo processo:

(13)

Progress SET BUTTON ENABLED

Progress SET BUTTON ENABLED ( id ; botao )

botao 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 pelo parâ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 do método Progress Stopped.

(14)

Progress SET BUTTON TITLE

Progress SET BUTTON TITLE ( id ; titulo )

titulo 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 pelo parâ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")

(15)

Progress SET FONT SIZES

Progress SET FONT SIZES ( tamTitulos {; tamMensagens {; tamBotoes}} )

tamTitulos Inteiro longo Tamanho da fonte para os títulos tamMensagens Inteiro longo Tamanho da fonte para as mensagens

tamBotoes 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 em todas as janelas de progresso.

Nos parâmetros tamTitulos, tamMensagens e tamBotoes, passe os tamanhos das fontes a utilizar. Se não quer modificar um 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)

(16)

Progress SET FONTS

Progress SET FONTS ( fonteTitulos {; fonteMensagens {; fonteBotoes}} )

fonteTitulos Texto Fonte a utilizar para os títulos fonteMensagens Texto Fonte a utilizar para as mensagens

fonteBotoes 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 as janelas de progresso.

Nos parámetros fonteTitulos, fonteMensagens e fonteBotoes, passe os nomes das fontes a utilizar. Se não deseja modificar uma fonte, passe uma cadeia vazia ("") no parâmetro correspondente.

Exemplo

Queremos mudar a fonte das mensagens: Progress SET FONTS("";"Arial")

(17)

Progress SET ICON

Progress SET ICON ( id ; icone {; primeiroPlano} )

id Inteiro longo ID da barra de progresso icone Imagem Imagem a mostrar como icone

primeiroPlano 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 os seguintes í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áximo deste ícone deve ser:

Em Mac OS, 40 x 40 píxels Em 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 seu tamanho 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:

(18)

Progress SET MESSAGE

Progress SET MESSAGE ( id ; mensagem {; primeiroPlano} )

id Inteiro longo ID da barra de progresso mensagem Texto Mensagem da barra de progresso

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.

(19)

Progress SET ON ERROR METHOD

Progress SET ON ERROR METHOD ( nomMetodo )

nomMetodo 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ção das 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 é compartilhado por 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 a propriedade "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)

(20)

Progress SET ON STOP METHOD

Progress SET ON STOP METHOD ( id ; nomMetodo )

nomMetodo 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 Stop

da 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 o mé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. Este método recebe o identificador único da barra de progresso como seu primeiro parâmetro. A continuação, se executa em um novo 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.

(21)

Progress SET PROGRESS

Progress SET PROGRESS ( id ; progresso {; mensagem {; primeiroPlano}} )

id Inteiro longo ID da barra de progresso progresso Real Valor de progresso([0...1] ou -1) mensagem Texto Mensagem da barra de progresso

Descrição

O método Progress SET PROGRESS modifica o valor da barra de progresso junto com a informação mostrada na janela de 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 especificar uma 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)

(22)

Progress SET TITLE

Progress SET TITLE ( id ; titulo {; progresso {; mensagem {; primeiroPlano}}} )

id Inteiro longo ID da barra de progresso titulo Texto Título da barra de progresso progresso Real Valor de progresso ([0...1] ou -1)

mensagem Texto Mensagem da barra

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 de progresso.

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 para definir 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). Este parâ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")

(23)

Progress SET WINDOW VISIBLE

Progress SET WINDOW VISIBLE ( visivel {; posHor ; posVert {; primeiroPlano}} )

visivel Booleano True = Mostrar, False = Ocultar posHor Inteiro longo Coordenada esquerda da janela

-1 = Não mudar

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

primeiroPlano 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âmetro para 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 valores que representem o movimento em píxels a direita (posHor) ou para abaixo (posVert) com respeito as coordenadas da janela principal 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 da janela), 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)

(24)

Progress Stopped

Progress Stopped ( id ) -> Resultado

Resultado 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 pelo parâ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)