ACHOICE()
 Executa um menu pop-up
------------------------------------------------------------------------------

 Sintaxe

     ACHOICE(<nTopo>, <nEsquerda>, <nBase>, <nDireita>,
        <acItensMenu>,
        [<alItensSelecionaveis> | <lItemsSelecionáveis>],
        [<cFunçaoUsuário>],
        [<nItemInicial>],
        [<nLinhaJanela>]) --> nPosiçao

 Argumentos

     <nTopo>, <nEsquerda> e <nBase>, <nDireita> sao as
     coordenadas do canto superior esquerdo e canto inferior direito da
     janela.  Valores de linha podem variar entre zero e MAXROW(), e valores
     de coluna podem variar entre zero e MAXCOL().

     <acItensMenu> é um vetor que contém as cadeias de caracteres que
     serao exibidas como sendo os itens de menu.  Cada item de menu será
     mais tarde identificado através de sua posiçao numérica neste vetor.

     <alItensSelecionaveis> é um vetor paralelo de valores
     lógicos--diretamente relacionado a <acItensMenu>--que especifica os
     itens de menu que poderao ser selecionados.  Os  elementos podem ser
     valores lógicos ou cadeias de caracteres.  Caso o elemento seja uma
     cadeia de caracteres, ele é avaliado como uma expressao macro que
     deverá retornar um tipo de dados lógico.  Em ambos os casos, um valor
     de falso (.F.) significa que o item de menu correspondente nao está
     disponível, e um valor de verdadeiro (.T.) significa que está
     disponível.  Se for especificado <lItensSelecionaveis> ao invés de um
     vetor, falso (.F.) torna todos os itens de menu nao disponíveis e
     verdadeiro (.T.) torna todos os itens de menu disponíveis.  O padrao
     adotado é que todos os itens de menu estejam disponíveis para seleçao.

     <cFunçaoUsuário> é o nome de uma funçao definida pelo usuário que é
     executada quando uma tecla nao reconhecível for pressionada.  O nome da
     funçao é especificado como uma expressao caractere sem parênteses ou
     argumentos.  Note que o comportamento de ACHOICE() é afetado pela
     presença deste argumento.  Consulte o texto abaixo para maiores
     informaçoes.

     <nItemInicial> é a posiçao ocupada no vetor de <acItensMenu> pelo
     item que aparecerá em destaque quando o menu for exibido pela primeira
     vez.  Caso você especifique um item de menu que nao esteja disponível,
     ou caso você nao use argumento algum, o item que aparecerá em destaque
     será o primeiro item selecionável do vetor.

     <nLinhaJanela> é o número da linha da janela na qual o item de menu
     inicial aparecerá. A numeraçao de linhas começa com zero.  O padrao é
     que o item de menu inicial apareça o mais próximo do topo da janela
     possível, sem deixar nenhuma linha vazia na parte de baixo.
     Consequentemente, caso haja um número suficiente de itens de menu após
     o primeiro para completar a janela, ele aparecerá na primeira linha
     (linha zero) do menu.  Este argumento é utilizado para controlar a
     disposiçao inicial do menu nos casos em que haja mais itens de menu do
     que a janela comporta.

     Como toda funçao, os argumentos opcionais sao omitidos usando-se uma
     vírgula ao invés do argumento propriamente dito.

 Retorno

     ACHOICE() retorna a posiçao numérica ocupada pelo item de menu
     selecionado no vetor de <acItensMenu>.  Se o processo de seleçao for
     interrompido, ACHOICE() retorna zero.

 Descriçao

     ACHOICE() é uma funçao de interface com o usuário que pode ser
     utilizada para criar vários tipos de menus pop-up.  Cada menu usa um
     vetor de cadeia de caracteres, que serao os itens de menu, e um vetor
     paralelo de valores lógicos que determina se os itens sao
     selecionáveis.  Quando ACHOICE() é invocada, a lista de itens de menu é
     exibida dentro das coordenadas de janela especificadas.  Quando o
     usuário tecla Return, o item corrente é selecionado, e ACHOICE()
     retorna a posiçao ocupada por este item de menu em <acItensMenu>.
     Quando o usuário pressiona Esc, ACHOICE() aborta e retorna zero.

     Caso a quantidade de itens em <acItensMenu> exceda a quantidade de
     linhas na janela de menu, os itens de menu aparecem na medida em que o
     usuário tenta mover a barra luminosa para cima ou para baixo, além dos
     limites da janela de menu.  Observe que a barra luminosa nao pula do
     último para o primeiro item de menu quando se chega ao fim da lista de
     itens, ou vice-versa.  Porém, se o usuário pressionar a primeira letra
     do item, a barra luminosa irá automaticamente para o primeiro item de
     menu cuja primeira letra for a mesma pressionada.

       Navegando pelo menu: ACHOICE() tem dois modos, dependendo
        se o argumento <cFunçaoUsuário> for especificado.  Caso nao seja
        especificado, as seguintes teclas de navegaçao sao
        ativas:

        Tabela 5-1: Teclas em ACHOICE() (Sem funçao de Controle)
        ---------------------------------------------------------------------
        Tecla                   Açao
        ---------------------------------------------------------------------
        Cursor para cima        Vai para o item anterior
        Cursor para baixo       Vai para o próximo item
        Home                    Vai para o primeiro item do menu
        End                     Vai para o último item do menu
        Ctrl-Home               Vai para o primeiro item da janela
        Ctrl-End                Vai para o último item da janela
        PgUp                    Vai para a página anterior
        PgDn                    Vai para a próxima página
        Ctrl-PgUp               Vai para o primeiro item do menu
        Ctrl-PgDn               Vai para o último item do menu
        Return                  Seleciona item corrente
        Esc                     Aborta seleçao
        Cursor para esquerda    Aborta seleçao
        Cursor para direita     Aborta seleçao
        Primeira letra          Vai para o próximo item iniciando com a letra
        ---------------------------------------------------------------------

       Cor: Os itens de menu sao exibidos na cor padrao, o item
        onde está a barra luminosa na cor destaque, e os itens nao
        disponíveis na cor nao seleciionada.  Por exemplo, a seguinte
        declaraçao de cores:

        SETCOLOR("W+/N, BG+/B, , , W/N")

        exibe um menu que é de cor branca intensificada sobre preto, a barra
        luminosa é de cor ciano intensificado sobre azul, e os itens de menu
        nao disponíveis sao brancos sobre preto.

       Funçao de usuário: Da mesma forma que as demais funçoes
        de interface com o usuário, ACHOICE() aceita uma funçao de usuário.
        A funçao de usuário é especificada quando você deseja aninhar
        invocaçoes da funçao ACHOICE() para criar menus hierárquicos ou
        redefinir teclas.

        Quando é especificada uma funçao de usuário, ACHOICE() processa
        somente um conjunto limitado de teclas automaticamente. Estas estao
        relacionadas na tabela abaixo.  Todas as outras teclas geram uma
        exceçao de tecla que passa o controle para a funçao de usuário.  O
        controle também será passado à funçao de usuário quando ACHOICE()
        fica inativo (ou seja, quando nao há mais teclas a
        processar).

        Tabela 5-2: Teclas em ACHOICE() (Com funçao de controle)
        ---------------------------------------------------------------------
        Tecla                Açao
        ---------------------------------------------------------------------
        Cursor para cima     Vai para o item anterior
        Cursor para baixo    Vai para o próximo item
        Ctrl-Home            Vai para o primeiro item da janela
        Ctrl-End             Vai para o último item da janela
        PgUp                 Vai para a página anterior
        PgDn                 Vai para a próxima página
        Ctrl-PgUp            Vai para o primeiro item do menu
        Ctrl-PgDn            Vai para o último item do menu
        ---------------------------------------------------------------------

        .  Quando ACHOICE() executa a funçao de usuário, ela passa
           automaticamente os três parâmetros a seguir:

        .  O modo ACHOICE() corrente

        .  O elemento corrente no vetor de itens

        .  A posiçao de linha relativa dentro da janela de menu

        O modo indica o estado atual de ACHOICE(), que depende da tecla
        pressionada e da açao tomada por ACHOICE() antes da execuçao da
        funçao de usuário.  O parâmetro modo pode ter os seguintes
        valores:

        Tabela 5-3: Modos de ACHOICE()
        ---------------------------------------------------------------------
        Modo        Achoice.ch        Descriçao
        ---------------------------------------------------------------------
        0           AC_IDLE           Inativo
        1           AC_HITTOP         Tentativa de passar início da lista
        2           AC_HITBOTTOM      Tentativa de passasr final da lista
        3           AC_EXCEPT         Teclagemn exceçao
        4           AC_NOITEM         Itens nao selecionados
        ---------------------------------------------------------------------

        Após a funçao de usuário ter executado as operaçoes apropriadas ao
        modo ACHOICE() ou LASTKEY(), ela deve retornar um valor que solicite
        a ACHOICE() executar uma operaçao entre o seguinte conjunto de
        açoes:

        Tabela 5-4: Valores de Retorno da Funçao de Controle de ACHOICE()
        ---------------------------------------------------------------------
        Valor                Achoice.ch        Açao
        ---------------------------------------------------------------------
        0                    AC_ABORT          Aborta seleçao
        1                    AC_SELECT         Executa seleçao
        2                    AC_CONT           Continua ACHOICE()
        3                    AC_GOTO           Vai para o próximo item cuja
                                               primeira letra for a tecla
                                               pressionada
        ---------------------------------------------------------------------

 Exemplos

       O exemplo a seguir utiliza dois vetores literais para
        especificar os itens de menu e critérios de seleçao.  Depois que o
        menu foi exibido e o usuário fez sua escolha, o nome do item de menu
        selecionado é exibido:

        acMenuItens := {Um, Dois, "", Três}
        alSelectableItens := {.T., .T., .F., .T.}
        nPosition := ACHOICE(10, 10, 12, 15, acMenuItens, alSelectableItens)
        ? acMenuItens[nPosition]

       No próximo exemplo, os vetores sao declarados, é especificada
        uma condiçao de seleçao para um dos itens de menu, e há uma funçao
        de usuário:

        FUNCTION MyMenu
           LOCAL acMenuItens[4], alSelectableItens[4], cUserFunction := "DoIt"
           //
           acMenuItens[1] := "Adiciona Registro"
           acMenuItens[2] := "Edita Registro"
           acMenuItens[3] := "Elimina Registro"
           acMenuItens[4] := "Atualiza Registro"
           //
           alSelectableItens[1] := .T.
           alSelectableItens[2] := .T.
           alSelectableItens[3] := .T.
           alSelectableItens[4] := "!UPDATED()"   // Condicao de selecao
           RETURN ACHOICE(10, 10, 12, 30, acMenuItens,;
                     alSelectableItens, cUserFunction)

 Arquivos:  Biblioteca EXTEND.LIB, arquivos header sao Achoice.ch e Inkey.ch.
 To download this example - click here.

See Also: MENU TO SET COLOR* Códigos INKEY()