@...GET
 Cria um novo objeto GET e o coloca em exibiçao na tela
------------------------------------------------------------------------------

 Sintaxe

     @ <nLin>, <nCol>
        [SAY <exp>
           [PICTURE <cSayPicture>]]
         GET <idVar>
           [PICTURE <cGetPicture>]
           [WHEN <lPreCondiçao>]
           [RANGE <dnMínimo>, <dnMáximo>] | [VALID <lPosCondiçao>]

 Argumentos

     <nLin> e <nCol> sao as coordenadas de linha e coluna para a
     operaçao.  Se a claúsula SAY está presente, especificam as coordenadas
     para o SAY, e o GET é exibido a direita deste.  Caso a saída esteja
     além da extensao visível ela nao aparecerá.

     SAY exibe o valor de <exp> nas coordenadas especificadas.  Caso a
     PICTURE <cSayPicture> seja especificada, <exp> é formatada de acordo
     com as regras das máscaras do SAY.

     GET <idVar> define o nome da variável de qualquer tipo de dados a
     ser editada.  Ela pode ser caractere, data, numérica ou lógica (Se o
     tipo for ambíguo, FIELD é assumido).  Vetores, NIL, e blocos de código
     nao podem ser editados.

     PICTURE <cGetPicture> especifica uma máscara para exibiçao e as
     regras para ediçao do GET.

     WHEN <lPreCondiçao> especifica uma expressao que deve ser
     satisfeita antes do cursor entrar na regiao de ediçao de GET.  Se
     <lCondiçao> é avaliada como verdadeira (.T.), é permitido ao cursor
     entrar; de outra forma, o GET corrente é saltado e o cursor move-se
     para o próximo GET no vetor GetList.

     RANGE <dnMínimo>, <dnMáximo> limita a ediçao de datas ou variáveis
     numéricas especificando os limites mínimos e máximos aceitáveis (o
     mínimo deve preceder o máximo).  Se o valor entrado nao está dentro do
     RANGE especificado, uma mensagem indicativa aparece no SCOREBOARD e o
     controle retorna ao objeto GET.  A verificaçao de RANGE (faixa) é
     executada a menos que o usuário aperte Esc para terminar a ediçao do
     GET corrente.  Quando isto ocorre, a verificaçao de RANGE nao é
     executada e é reatribuído seu valor original.

     VALID <lPosCondiçao> especifica uma expressao que deve ser
     satisfeita antes que o cursor possa deixar a regiao de ediçao do GET
     corrente.  De forma semelhante às expressoes RANGE, o
     VALID<lPosCondiçao> é avaliado sempre que o usuário tenta deixar a
     regiao de ediçao do GET, a menos que a tecla Esc seja pressionada e
     ESCAPE esteja ON.  Se <lPosCondiçao> retorna falso (.F.), o controle
     retorna ao GET e o usuário nao pode deixá-lo até que <lPosCondiçao>
     retorne verdadeiro (.T.) ou o usuário aperte Esc.  Um VALID
     <lPosCondiçao> pode conter ou ser uma funçao definida pelo usuário,
     permitindo-lhe executar buscas e outros tipos de operaçoes de
     validaçao.

 Descriçao

     O comando @...GET cria um novo objeto GET, adiciona-o ao vetor GetList,
     e exibe-o na tela.  Um comando READ subsequente permite a ediçao dos
     conteúdos de todos os objetos GET contidos no vetor GetList corrente.

     Quando um comando READ é especificado, um GET executa uma ediçao do
     conteúdo de <idVar> de qualquer tipo de dado, incluindo campo de
     arquivo, elemento de vetor, variável de memória local ou estática.
     Quando um objeto GET é criado, o nome e valor corrente de <idVar> sao
     guardados no objeto GET.  O valor de <idVar> fica armazenado no que é
     chamado de buffer do GET.  O buffer de GET é o que é realmente mostrado
     na tela e editado.

     Formataçao automática e validaçao: Quando o usuário estiver
     editando o buffer do objeto GET, existe uma formataçao implícita e
     validaçao da ediçao para cada tipo de dado.  Isto significa que
     enquanto o usuário digita, um teste automático de tipo é executado para
     cada tecla pressionada de forma a evitar que o usuário digite um
     caractere impróprio para aquele tipo de dado contido em <idVar>.  Este
     comportamento assumido aplica-se a datas, numéricos, e lógicos.  Tipo
     caractere nao é automáticamente verificado.

     PICTURE: Cada objeto GET pode opcionalmente conter uma PICTURE e
     string template para explicitamente impor formataçao e validaçao da
     entrada.  Um funçao PICTURE impoe uma regra de como o GET pode ser
     editado pelo usuário.  Por exemplo, se a funçao de PICTURE @! é
     especificada para um GET, todos os caracteres alfabéticos serao
     convertidos para maiúsculas antes de tomarem lugar no buffer.  Um
     template PICTURE define o tamanho do buffer de GET, e a regra de
     validaçao para cada posiçao dentro do buffer.  Por exemplo, o template
     "999" define o tamanho do buffer de GET em três dígitos, com cada
     dígito devendo ser um número entre 0 e 9.

       Funçoes: Uma funçao PICTURE é um símbolo precedido do
        símbolo @.  Um símbolo de template segue a funçao, e deve ser
        precedido de um espaço.  Note que mais de uma funçao pode ser
        aplicada dentro da mesma PICTURE.  A tabela na página seguinte
        mostra as opçoes disponíveis para as funçoes PICTURE:

        Tabela 4-1: Formatos de PICTURE para um GET
        ---------------------------------------------------------------------
        Funç     Tipo        Açao
        ---------------------------------------------------------------------
        A        C           Permite somente caracteres alfabéticos
        B        N           Exibe números alinhados à esquerda
        C        N           Exibe CR após números positivos
        D        D,N         Exibe datas segundo o formato SET DATE
        E        D,N         Exibe datas com o mês e dia invertidos
                             independente do SET DATE corrente, númericos com
                             pontos e vírgulas period reverse invertidos
        K        TODOS       Elimina texto assumido caso a primeira tecla nao
                             seja cursor
        R        C           Caracteres nao-template sao inseridos na tela
                             mas nao sao guardados na variável
        S<n>     C           Permite rolagem horizontal dentro de um GET.
                             <n> é um inteiro que especifica a largura da
                             regiao
        X        N           Exibe DB após números negativos
        Z        N           Exibe zeros como brancos
        (        N           Exibe números negativos entre parênteses com
                             espaços à esquerda
        )        N           Exibe números negativos entre parênteses sem
                             espaços à esquerda
        !        C           Converte caracteres alfabéticos para maiúsculas
        ---------------------------------------------------------------------

       Templates: Símbolos de template seguem as funçoes no
        string de PICTURE se forem especificados.  Cada posiçao no fluxo de
        entrada ou saída é mapeada para o símbolo na mesma posiçao no string
        template.  O Clipper fornece vários símbolos os quais estao
        discriminados na tabela da página seguinte:

        Tabela 4-2: Símbolos Template para PICTURES de GETs
        ---------------------------------------------------------------------
        Template    Açao
        ---------------------------------------------------------------------
        A           Permite somente caracteres alfabéticos
        N           Permite somente caracteres alfabéticos e alfanuméricos
        X           Permite qualquer caractere
        9           Permite dígitos para qualquer tipo de dados incluindo
                    sinal para numéricos
        #           Permite dígitos, sinais, e espaços para qualquer tipo de
                    dados
        L           Permite somente T, F, Y ou N
        Y           Permite somente Y ou N
        !           Converte um caractere alfabético para maiúsculo
        $           Exibe o sinal de dolar em lugar de um espaço à esquerda
                    de um numérico
        *           Exibe um asterisco em lugar de um espaço à esquerda de um
                    numérico
        .           Exibe um ponto decimal
        ,           Exibe uma vírgula
        ---------------------------------------------------------------------

        Outros caracteres especificados no template sobreescrevem o
        caractere localizado na mesma posiçao no fluxo fonte e saída.  Se,
        entretanto, você usar a funçao R, símbolos nao-template
        especificados sao inseridos na tela mas nao sao gravados no buffer
        de GET.

     WHEN e VALID: Um objeto GET também possui expressoes de pré
     condiçao e pós condiçao usando WHEN e VALID respectivamente.  A
     expressao WHEN é executada sempre que o usuário tenta entrar com o
     cursor na regiao de GET.  A expressao VALID é executada sempre que o
     usuário tentar sair do GET exceto se o usuário apertar uma tecla com
     SET KEY ou Esc.

     SET KEY: Quando existe uma rotina definida para SET KEY, o usuário
     pode apertar a tecla designada de forma a desviar o controle para a
     rotina definida.  Após tal rotina ter sido executada, o controle
     retorna ao GET com o cursor restaurado à sua posiçao prévia.

     Vida útil de um objeto GET: Objetos GET existem enquanto existirem
     referências ativas a eles em algum local do programa corrente.  Caso
     você nao tenha atribuído um objeto GET a outra variável ou GetList, ele
     terá uma duraçao enquanto o vetor GetList corrente existir, ou até que
     o vetor GetList seja reatribuído.  O vetor GetList corrente é atribuído
     a um vetor vazio sempre que for emitido CLEAR GETS, CLEAR, ou um
     comando READ sem a cláusula SAVE.

     Variável associada: Cada objeto GET é criado associado a uma
     variável que você especifica como <idVar>.  Quando o objeto GET é
     ativado durante um READ, <idVar> é atribuído, em vários pontos, com o
     valor corrente do buffer do objeto GET.  Isto ocorre nas seguintes
     situaçoes:

       O usuário aperta uma tecla de saída e antes a expressao de
        validaçao é executada.

       O usuário aperta um SET KEY

     Da mesma forma, o buffer do GET corrente sofre refresh e é reexibido
     após vários intervalos, incluindo:

       Quando do término de uma rotina SET KEY

       Após uma expressao WHEN

       Após uma expressao VALID

     Isto permite a você explicitamente atribuir <idVar> dentro destas
     operaçoes.  Em Clipper 5.0, entretanto, nao é mais necessário utilizar
     KEYBOARD para atualizar o buffer do GET corrente.  Veja a nota abaixo
     para maiores informaçoes.

     Exibiçao do objeto GET: Quando o comando @...GET é executado, o
     novo objeto GET é exibido em <nLin> e <nCol>, a menos que a cláusula
     SAY seja especificada.  Se isto acontece, o objeto GET é exibido em
     ROW() e COL() + 1.

     Caso SET DELIMITERS esteja ON quando o comando @...GET for executado, o
     objeto GET é inicialmente exibido delimitado pelo caractere escolhido
     correntemente como delimitador e seu atributo de coluna é <nCol> +
     1.  Note que os delimitadores nao sao atributos do objeto GET, mas
     simplesmente sao exibidos como na cláusula SAY.

     Se INTENSITY está ON, um objeto GET é exibido na cor destaque ou vídeo
     reverso dependendo do adaptador utilizado pelo seu monitor.  Se a cor
     nao selecionado é definida, o objeto GET é exibido na cor destaque,
     enquanto os GET remanescentes serao exibidos na cor nao selecionado.
     Com INTENSITY OFF, um objeto GET é exibido na cor corrente para a cor
     padrao.

     Quando um objeto GET é exibido, o tamanho da área é determinado pelo
     tamanho de <idVar>, ou pelo número de dígitos especificado por
     <cGetPicture> se a cláusula PICTURE foi especificada.  Caso a funçao @S
     for especificada como parte de <cGetPicture>, o tamanho da área a ser
     exibida é o argumento da funçao @S.

 Notas

       Atribuindo <idVar>: Devido às propriedades de refresh
        automático e exibiçao de um objeto GET quando sofre um READ, você
        pode fazer uma atribuiçao explícita de <idVar> ao objeto GET dentro
        de um WHEN ou VALID.  Existem duas formas de fazê-lo.  Para
        aplicaçoes onde as expressoes de validaçao estao acopladas ao objeto
        GET, você pode atribuir a variável por nome na expressao de
        validaçao ou numa funçao definida pelo usuário.  Para aplicaçoes
        onde a rotina de validaçao é genérica e <idVar> nao é uma variável
        campo ou elemento de vetor, você pode passar <idVar> por referência
        e atribuir seu parâmetro formal.

       Help em GET: Você exibe texto de help (auxílio) usando
        uma rotina de SET KEY.  Dentro da rotina de SET KEY, use a funçao
        READVAR() para determinar a variável <idVar> associada ao objeto GET
        corrente.  Entao use esta informaçao para exibir o texto
        apropriado.  Lembre-se de que num programa compilado em Clipper, a
        tecla F1 é automaticamente configurada para uma rotina de nome Help.

       SET DEVICE TO PRINTER: A exibiçao de um objeto GET com o
        comando @...GET nao é direcionada para a impressora ou arquivo caso
        SET DEVICE seja TO PRINTER.

 Exemplos

       O exemplo seguinte demonstra o uso da cláusula VALID para
        validar entradas num GET:

        nNumber = 0
        @ 10, 10 SAY "Digite um número maior que zero:";
           GET nNumber;
           VALID nNumber > 0

       Este exemplo mostra como a cláusula WHEN pode ser usada para
        proibir a entrada em GETs baseada no valor de outro GET.  Neste
        exemplo, entrando com Y no campo Insured indica que o cliente tem
        seguro e ao usuário é permitido entrar com a informaçao.  Se o
        cliente nao tem seguro, o cursor move-se para o campo Accident:

        @ 10, 10 GET Insured PICTURE "Y"
        @ 11, 10 GET InsNumber WHEN Insured
        @ 12, 10 GET InsCompany WHEN Insured
        @ 13, 10 GET Accident PICTURE "Y"
        READ

       Um exemplo de GET em uma área secundária:

        USE Invoice NEW
        APPEND BLANK
        USE Inventory NEW
        @ 1, 1 GET Invoice->CustNo
        READ

       Este exemplo demonstra o uso da funçao @K para sugerir um
        valor padrao de entrada, mas elimina-o caso a primeira tecla
        pressionada nao seja uma tecla de movimentaçao de cursor ou  Return:

        file = "Accounts"
        @ 1, 1 SAY "Arquivo" GET file PICTURE "@K"
        READ

 Arquivos:  Biblioteca CLIPPER.LIB.
 To download this example - click here.

See Also: @...SAY READ COL() ROW() SETCOLOR() Códigos PICTURE