F050ROT o ponto de entrada que acrescenta botões ao Contas a Pagar

Este é o ponto de entrada do menu, não da operação. Ele não sabe se o usuário vai incluir, alterar ou excluir um título: roda antes de qualquer clique, uma vez a cada montagem do aRotina. Para validar ou reagir à gravação do título, o lugar é outro ponto de entrada.

Para o mecanismo geral de como o padrão chama um PE, veja Ponto de entrada no Protheus.

Nos dois menus o padrão entrega o aRotina como o argumento do ponto de entrada e, se o retorno for um array, passa a usá-lo como menu no lugar do original. Qualquer outro tipo de retorno é descartado.

Duas consequências práticas:

• O retorno substitui o menu inteiro. Quem devolve o array recebido com um item a mais, acrescenta. Quem devolve um array novo e menor, remove os itens do padrão.
• Retornar Nil (ou esquecer o Return) é seguro: o padrão descarta e mantém o menu original. Mas o seu item também não entra.

Armadilha: o array não é o mesmo nas duas telas

O PE é chamado em dois lugares, e o PARAMIXB de cada um tem outro escopo:

Em outras palavras: o mesmo PE, chamado pela mesma User Function, monta o menu em duas telas diferentes. O item que você acrescenta aparece nas duas. Se ele só faz sentido numa delas, é preciso testar o conteúdo do array recebido para decidir. Na FINA050 as opções apontam para funções como FA050Inclu; na FINA750, para Fin750050(...).

Outro ponto: o MenuDef() do FINA050 é chamado antes de o padrão decidir se a execução é automática. Ou seja, o PE também roda quando a rotina é chamada por MsExecAuto, sem nenhuma tela. Qualquer coisa além de mexer no array (mensagem, consulta, ConOut pesado) não pertence a este PE.

O formato de cada opção é o do aRotina do padrão:

Nos itens nativos do FINA050, a posição 4 vai de 1 a 9. Os cinco primeiros seguem o padrão do aRotina: 1 pesquisa, 2 visualização, 3 inclusão, 4 alteração, 5 exclusão. Os valores 6, 7, 8 e 9 também aparecem, em itens como Substituir, Agendamento, Documentos, Legenda, Tracker Contábil, histórico do título e consulta de retenções. A lista não é exaustiva e o significado de cada valor acima de 5 não está documentado aqui; para um item novo, prefira 2, 3, 4 ou 5 conforme o comportamento da sua função.

Esse layout é o descrito nos comentários do próprio MenuDef() do padrão, e é o que os itens nativos usam, por exemplo { "Visualizar", "Fa050Visua", 0, 2 }.

Na execução direta por opção (chamada da rotina informando a operação), o FINA050 localiza o item com Ascan pelo 4º elemento igual à operação pedida e pega o primeiro que encontrar. Por isso, acrescente o seu item no fim com aAdd. Inseri-lo antes dos nativos com o mesmo tipo de operação mudaria qual função é chamada nesse caminho.

Um botão que abre uma rotina própria de consulta sobre o título posicionado. O nome da função do botão é fictício.

#Include "Protheus.ch"

/*/{Protheus.doc} F050ROT
Executado na montagem do menu do Contas a Pagar.
Acrescenta o botão de uma consulta própria ao final do aRotina.
@type user function
@param PARAMIXB, array, o próprio aRotina montado pelo padrão
@return array, aRotina final; qualquer outro tipo é ignorado pelo padrão
/*/
User Function F050ROT()

    Local aRotina := {}

    // PARAMIXB já é o aRotina; se não vier como array, não mexe no menu.
    If Type("PARAMIXB") <> "A"
        Return Nil
    EndIf

    aRotina := PARAMIXB

    // No fim, para não mudar a posição dos itens nativos.
    // Título, função (texto), reservado, operação (2 = visualização).
    aAdd(aRotina, {"Consulta interna", "U_ConsTitPg", 0, 2})

Return aRotina

O Return Nil do primeiro desvio é intencional: como o padrão só aceita retorno do tipo array, ele mantém o menu original. E como o retorno é o menu, o caminho normal devolve o aRotina recebido, com o item a mais.

Armadilhas

Devolver só o seu item. Se você retornar { {"Consulta interna", ...} }, o menu do Contas a Pagar passa a ter apenas esse botão. Comece sempre do array recebido.

Assumir que a tela é a FINA050. No FINA750 o array é só o submenu. Remover ou reordenar itens por posição fixa (PARAMIXB[3]) funciona numa tela e quebra na outra.

Lógica pesada no PE. Ele roda a cada montagem do menu. Deixe a regra de negócio na função do botão, que só executa no clique.

Esperar que o PE reaja a uma operação. Ele é de menu. Para atuar na gravação do título, use outro ponto de entrada do FINA050.

Para saber como o Catálogo de Personalizações registra e desliga um ponto de entrada sem recompilar, veja Catálogo de personalizações. Sobre como conferir o PARAMIXB antes de ler, veja PARAMIXB: o array que às vezes não é seu.