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

Transcrição

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

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

3 Progress Get Button Enabled Progress Get Button Enabled ( id ) -> Resultado Resultado Booleano True = botão Stop mostrado; caso contrário, False 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 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 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 Resultado Texto Mensagem da barra de progresso 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 Resultado Texto Nome do método chamado em caso de erro (se definido) 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) 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 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 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 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 ) 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 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) 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 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 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} ) icone Imagem Imagem a mostrar como icone primeiroplano Booleano Mostrar a barra de progresso no primeiro plano 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} ) mensagem Texto Mensagem da barra de progresso primeiroplano Booleano Mostrar a barra de progresso no primeiro plano 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 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 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}} ) progresso Real Valor de progresso([0...1] ou -1) mensagem Texto Mensagem da barra de progresso primeiroplano Booleano Mostrar a barra de progresso no primeiro plano 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}}} ) titulo Texto Título da barra de progresso progresso Real Valor de progresso ([0...1] ou -1) mensagem Texto Mensagem da barra primeiroplano Booleano Mostrar a barra de progresso no primeiro plano 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 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 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)