AdvPL - Comandos

Quando programamos em AdvPL, basicamente usamos instruções conhecidas como "Statements" ou "Diretivas" da linguagem, como as instruções de decisão e repetição ( If, Else, Endif, For, Next, While ), e também chamadas de funções e métodos de classes. 

O AdvPL também permite o acesso aos recursos de funções e classes da Linguagem AdvPL através de comandos, concebidos para tornar a escrita e a interpretação do código mais legível. Esta página está em criação justamente para documentar os recursos do AdvPL disponibilizados pela Tecnologia TOTVS através de comandos nativos da linguagem AdvPL.

Padronização e Informações adicionais

• A documentação base de um comando deve incluir sua sintaxe mínima e sintaxe completa.
• Sintaxe mínima: Utilização do comando com o mínimo de parâmetros, apenas os obrigatórios.
• Sintaxe completa: Descreve todas as cláusulas do comando, obrigatórias e opcionais.
• Em algumas ocasiões o comando pode não endereçar diretamente todos os parâmetros do método encapsulado pelo comando. Nestes casos, normalmente é possível setar as propriedades adicionais de forma direta no objeto após criado ou mesmo por método. 
• Cada comando da interface visual normalmente está vinculada ao uso de uma classe da interface visual, e encapsula o construtor NEW() da mesma. Cada comando documentado menciona e aponta por link a classe endereçada, e vice-versa. 

Convenções sintáticas

Vamos analisar o exemplo da sintaxe completa do comando @ ... SAY, e ver os elementos comuns a todas as representações de sintaxe de comandos:

@ <nRow>, <nCol> SAY [ <oSay> PROMPT | VAR ] <cText> 
   [ PICTURE <cPict> ] 
   [ OF | WINDOW | DIALOG <oWnd> ] 
   [ FONT <oFont> ] 
   [ PIXEL | PIXELS ] 
   [ COLOR | COLORS <nClrText> [,<nClrBack> ] ] 
   [ SIZE <nWidth>, <nHeight> ] 
   [ HTML ] 

• Todas as palavras e expressões e agrupamentos entre colchetes são opcionais.
• Quando encontramos mais de uma palavra ou expressão opcional entre colchetes, elas fazem parte da sintaxe e devem ser informadas. Por exemplo, PICTURE <cPict> está entre colchetes, portanto é opcional. Porém, ao usarmos a palavra PICTURE no comando, devemos obrigatoriamente especificar a variável <cPict> – o nome da variável ou expressão caractere que será usada como máscara de entrada de dados. 
• Quando palavras reservadas da sintaxe estão separadas por "|" (pipe), isto significa que elas são sinônimos, e qualquer uma – mas apenas uma – delas pode ser usada. Alguns comandos possuem sinônimos, outros não. Geralmente quando a utilização de apenas um sinônimo é recomendada por questões de padronização de código, a recomendação de uso está explicitamente descrita na documentação da cláusula. Como é o caso de PIXEL e PIXELS. A primeira forma é a recomendada, pois várias funções não usam o sinônimo PIXELS. De forma semelhante, para especificar o componente superior (pai) do componente atual, podemos usar OF, WINDOW ou DIALOG – porém a forma recomendável é usar sempre OF.
• Parâmetros e cláusulas opcionais também podem estar dentro de um bloco opcional. Por exemplo, ao usar COLOR ou COLORS, obrigatoriamente devemos especificar uma expressão numérica – constante ou variável – para identificar a cor de frente do texto do componente. Quando especificamos a cor de frente, opcionalmente podemos usar uma virgula imediatamente após a cor de frente do texto, e após a vírgula podemos especificar a cor de fundo do texto (background color). Uma vez que colocamos a vírgula após a cor de frente, devemos especificar a cor de fundo, ou o programa não será compilado e apresentará o erro Syntax Error. Quando queremos especificar apenas a cor de frente, não usamos a vírgula.
• Como os comandos possuem regras de tradução para chamadas que envolvem listas de parâmetros, texto sem aspas tratado como caractere – como por exemplo o comando USE – algumas chamadas podem usar de alguns artifícios para usar uma variável como parâmetro. O comando USE foi desenhado para traduzir o nome da tabela especificado imediatamente após o comando como uma string constante, sem usar aspas para identificar que a expressão informada é uma string. Nestes casos, para informar uma variável como o nome da tabela, colocamos a variável entre parênteses. Cada comando onde um parâmetro possuir esta particularidade, a documentação do parâmetro deve conter estas informações adicionais.