READ
 Ativa ediçao em tela usando objetos GET
------------------------------------------------------------------------------

 Sintaxe

     READ [SAVE]

 Argumentos

     SAVE retém o conteúdo do vetor GetList corrente após o fim da
     operaçao do comando READ.  Depois, você pode editar os mesmos objetos
     GET através de outro comando READ.  Caso nao esteja especificada, à
     GetList corrente é atribuído um vetor vazio eliminando todos os objetos
     GET anteriores quando o comando READ tiver terminado.

 Descriçao

     O comando READ executa um módulo de ediçao em tela usando todos os
     objetos GET criados e adicionados à GetList corrente a partir dos
     comandos CLEAR, CLEAR GETS, CLEAR ALL ou READ mais recentes.  Se há uma
     rotina de formataçao ativa, o comando READ executa essa rotina antes de
     entrar no módulo de ediçao em tela.

     Dentro de um READ, o usuário pode editar o buffer de cada objeto GET
     bem como mover-se de um objeto GET para outro.  Antes que o usuário
     possa entrar com um objeto GET, o controle passa para o respectivo WHEN
     <lPreCondiçao> caso alguma tenha sido atribuída àquele objeto GET.  Se
     <lPreCondiçao> retornar valor verdadeiro (.T.), é permitido ao usuário
     editar o buffer do objeto GET.  Caso contrário, o controle passa para o
     próximo objeto GET na GetList.  Dentro de um buffer GET, o usuário pode
     editar, utilizando-se do conjunto completo de teclas de navegaçao e
     ediçao.  Veja as tabelas abaixo.

     Quando o usuário pressiona uma tecla de saída de GET, o controle passa
     à pós-condiçao RANGE ou VALID respectiva, caso tenha sido
     especificada.  Se alguma das condiçoes retornar valor verdadeiro
     (.T.),  a ediçao do objeto GET é encerrada e o controle passa para o
     próximo objeto GET.  Caso contrário, o controle permanece dentro do
     objeto GET corrente até que um valor válido for entrado ou até que o
     usuário tecle Esc.

     Quando o usuário consegue entrar com um valor num objeto GET, é
     atribuído à respectiva variável o valor do buffer do objeto GET.

     As seguintes tabelas listam teclas ativas num comando READ:

     Tabela 4-9: Teclas de Navegaçao em um READ
     ------------------------------------------------------------------------
     Tecla                                     Açao
     ------------------------------------------------------------------------
     Cursor para esquerda, Ctrl-S              Caractere à esquerda. Nao move
                                               cursor para o GET anterior
     Cursor para direita, Ctrl-D               Caractere à direita. Nao move
                                               cursor para o próximo GET
     Ctrl-Cursor para esquerda, Ctrl-A         Palavra à esquerda
     Ctrl-Cursor para direita, Ctrl-F          Palavra à direita
     Cursor para cima, Ctrl-E                  GET anterior
     Cursor para baixo, Ctrl-X, Return, Ctrl-M Próximo GET
     Home                                      Primeiro caractere do GET
     End                                       ¯ltimo caractere do GET
     Ctrl-Home                                 Início do primeiro GET
     Ctrl-End                                  Início do último GET
     ------------------------------------------------------------------------

     Tabela 4-10: Teclas de Ediçao de READs
     ------------------------------------------------------------------------
     Tecla                   Açao
     ------------------------------------------------------------------------
     Del, Ctrl-G             Elimina caractere onde está o cursor
     Backspace, Ctrl-H       Backspace
     Ctrl-T                  Elimina palavra à direita
     Ctrl-Y                  Elimina do cursor até o final do GET
     Ctrl-U                  Retorna o GET ao seu valor original
     ------------------------------------------------------------------------

     Tabela 4-11: Teclas Comutativas em um READ
     ------------------------------------------------------------------------
     Tecla          Açao
     ------------------------------------------------------------------------
     Ins, Ctrl-V    Comuta modo de inserçao
     ------------------------------------------------------------------------

     Tabela 4-12: Teclas de Saída de um READ
     ------------------------------------------------------------------------
     Tecla                         Açao
     ------------------------------------------------------------------------
     Ctrl-W, Ctrl-C, PgUp, PgDn    Encerra um READ gravando GET corrente
     Return, Ctrl-M                Encerra um READ a partir do último GET
     Esc                           Encerra um READ sem gravar o GET corrente
     Cursor para cima              Encerra um READ a partir do primeiro GET
                                   se READEXIT()=.T.
     Cursor para baixo             Encerra um READ do último GET se
                                   READEXIT()=.T.
     ------------------------------------------------------------------------

 Notas

       BREAK dentro de um READ: Observe que um BREAK dentro de
        um comando READ finaliza o READ e limpa os GETs mesmo se a cláusula
        SAVE for usada.

       READs aninhados: Para executar um comando READ aninhado
        dentro de um procedimento SET KEY, VALID, ou WHEN ou de uma funçao
        definida por usuário, declare ou crie uma nova GetList, execute uma
        série de declaraçoes @...GET, e depois o comando READ.  Quando o
        procedimento terminar, a nova GetList é liberada e a anterior
        torna-se visível novamente.  Veja o exemplo abaixo.

       Home e End: Teclando Home ou End vai para o primeiro ou
        último caractere que nao estiver em branco num buffer de objeto GET.


       Finalizando um READ: Você pode finalizar um comando READ
        executando um CLEAR, CLEAR GETS, ou CLEAR ALL de dentro de uma
        rotina SET KEY ou uma funçao definida pelo usuário iniciada por
        VALID.

       UPDATED(): Caso qualquer buffer de objeto GET tenha sido
        mudado durante o comando READ corrente, a funçao UPDATED() é
        configurada em verdadeiro (.T.).

 Exemplos

       O exemplo abaixo define vários GETs e a seguir usa o comando
        READ:

        CLS
        cVar1 := cVar2 := cVar3 := SPACE(10)
        @ 10, 10 SAY "Variavel Um  :" GET cVar1 VALID !EMPTY(cVar1)
        @ 11, 10 SAY "Variavel Dois:" GET cVar2 WHEN RTRIM(cVar1) != "Um"
        @ 12, 10 SAY "Variavel Tres:" GET cVar3 VALID !EMPTY(cVar3)
        READ

       Este exemplo ilustra como executar um READ aninhado dentro de
        um procedimento SET KEY, WHEN, ou VALID ou funçao definida pelo
        usuário:

        LOCAL cName := SPACE(10)
        @ 10, 10 GET cName VALID SubForm( cName )
        READ
        RETURN

        FUNCTION SubForm( cLookup )
           PRIVATE GetList := {}           // Cria novo GetList
           USE Sales INDEX Salesman NEW
           SEEK cLookup
           IF FOUND()
              @ 15, 10 GET Salesman        // Adiciona novos GETS a GetList
              @ 16, 10 GET Amount
              READ                         // READ GetList
           ENDIF
           CLOSE Sales
           RETURN .T.                      // LIbera GetList

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

See Also: @...GET CLEAR GETS LASTKEY() READEXIT() READMODAL()