DVCS - Verso 0.2 Alfa - Manual de referncia

O que ?
O DVCS  um mdulo que possibilita ao Python
se comunicar com as rotinas do Dosvox. Com isso,  possvel criar aplicativos
em Python para o Dosvox como se fossem os nativos escritos em Delphi.

Modo de uso
1. Copie os arquivos dvcs.py e _dvcs.pyd para o diretrio do seu
projeto.

2. Para trazer as funes do DVCS para o seu programa, use
from dvcs import *

ou se preferir:
import dvcs

mas dessa forma  necessrio usar as funes com dvcs. como prefixo.

Lista de funes
Aqui est a lista de todas as funes implementadas no DVCS at o
momento.
As funes proporcionadas nesta parte do manual foram expostas diretamente das proporcionadas pelo tradutor, ento
em caso de dvida estas devem ser consultadas como referncia.

sintInic(veloc: int, dir: str)
Se o sintetizador no estiver inicializado, esta funo ir
inicializ-lo com a velocidade e o diretrio especificados. Se a
velocidade for 0, o sintetizador assumir a configurada pelo usurio.
Nada faz se o sintetizador estiver inicializado.

sintFim()
Termina o processo do sintetizador.

sintWrite(s: ?)
Escreve o valor de s na tela e o fala.

sintWriteln(s: ?)
Escreve o valor de s na tela e o fala, pulando linha.
A funo print, do Python, tambm pode ser usada para esse propsito.

sintReadln(): str
L uma linha de texto com suporte de sntese de fala e a retorna.

sintSenha(): str
L uma linha de senha do usurio (ocultando os caracteres digitados).

writeln, write e readln
Fazem a mesma coisa que as funes acima, s que sem suporte de fala.

sintBip() e sintClek()
Emitem um bip ou clek.

sintReadKey(): bytes e readKey(): bytes
L somente um caractere e retorna. a funo sintReadKey ir falar o
caractere digitado.
Observao
Para caracteres especiais, como o pressionamento de uma seta direcional,
o caractere de byte nulo (b'\0')  retornado antes da tecla.

sintSoletra(s: str)
Soletra a string s.

Sintetiza(s: str)
Apenas fala a string s.

existeArqSom(s: str)
Verifica se um arquivo de som existe no diretrio do aplicativo.

sintAmbiente(seo, item: str)
Pega um valor do arquivo de configurao (dosvox.ini).

sintGravaAmbiente(seo, item, valor: str)
Grava um atributo no arquivo de configurao (dosvox.ini).

sintRemoveAmbiente(seo, item: str)
Remove um atributo do arquivo de configurao (dosvox.ini).

sintPara()
Para o processo de sntese de fala.

sintSom(s: str)
Toca um arquivo Wav.

sintFalando(): bool
Retorna True se o sintetizador estiver falando, False caso contrrio.

SAPIPresente(): bool
Retorna True se o sintetizador estiver usando a fala SAPI, False caso contrrio.

keyPressed(): bool
Retorna True se uma tecla foi pressionada, False caso contrrio.

whereX(): int
Retorna a linha na qual a dvcrt est escrevendo.

whereY(): int
Retorna a coluna na qual a dvcrt est escrevendo.

gotoXY(x, y: int)
Posiciona o cursor na linha x e coluna y para escrita.

clrScr()
Limpa a tela.

clrEol()
Limpa at o fim da linha que o cursor est.

textColor(cor: int)
Muda a cor do texto (ver mais abaixo para as constantes).

textBackground(fundo: int)
Muda a cor de fundo do texto (ver mais abaixo para as constantes).

setWindowTitle(s: str)
Muda o ttulo da janela.
Observao: o ttulo com mais de 144 letras provavelmente ser truncado.

popupMenuCria(x, y, tam, nOpcoesTela, corfundo: int)
Cria um menu selecionvel com as setas.

popupMenuAdiciona(nomeArqSom, nome: string)
Adiciona um item no menu.

popupMenuSeleciona()
Exibe o menu e retorna a opo selecionada.
Observao: no Dosvox a lista de opes comea no 1.

obtemNomeArq(dy: int)
Rotina bsica para pegar um nome de arquivo no Dosvox.
Retorna o nome do arquivo selecionado pelo usurio como string.

falaDia()
Fala o dia da semana, semelhantemente  funo Control F8.

falaHora()
Fala a hora, semelhantemente  funo F8.

leitorDeTela()
Ativa o leitor de tela (usado na opo CONTROL + ALT + F9 na maioria dos
programas).

sintFalapont(comPontuacao: bool = False): bool?
Se usada sem argumentos, esta funo retorna True se o sintetizador fala
pontuao, ou False caso contrrio. Se usada com um argumento, ela
configura se o sintetizador deve falar pontuao.

sintEdita(campo: str, x, y, tamanho: int, altera: bool): str, bytes
Edita uma string previamente salva.
x e y  onde deve comear a editar.
Tamanho  o tamanho mximo do texto.
Altera  se pode alterar o texto.
A funo retorna o campo modificado e a tecla usada para terminar o
editor (tipo bytes).

waitMessage()
Espera algum evento no programa acontecer.

executaScript(nomeArq, rtulo: str, numUltLinha: int, linha: str,
rotinaExterna: funo): numUltLinha, tcontedo da linha, erro
Executa um script pelo Scripvox 6.3.
nomeArq  o nome do arquivo do script.
Rtulo  de onde iniciar executando.
numUltLinha  de qual linha comear executando.
Contedo da linha  o texto da linha.
rotinaExterna  uma funo que proporcionar comandos adicionais ao
Scripvox.
Ela recebe uma string e dever retornar uma string.

Aps a funo executaScript terminar, ela vai retornar os seguintes
valores:
* numUltLinha qual a ltima linha que executou;
* Contedo da linha, se houver;
* Erro: maior que 0 ocorreu um erro no script.
Observao: Uma cpia do Scripvox 6.3 est includa no executvel do
DVCS.

scriptCalculaExpressao(expresso: str): str
Permite colocar ou pegar variveis do script que ir ser executado.
Exemplo:
scriptCalculaExpressao("$x = 5")
Faz $x ser 5, e quando o script executar ter essa varivel.
x = scriptCalculaExpressao("$x")
Pega o resultado de $x.

formCria()
Cria um formulrio para preenchimento de dados.

formCampo(som, nome, valor padro: str, tamanho: int)
Adiciona um campo no formulrio.
Nota: ao contrrio do Pascal, a varivel que contm o valor padro do
campo no  modificada, ver mais abaixo.

formEdita(pode alterar: bool): dicionrio, tecla
Permite que o usurio altere o formulrio.
Quando a varivel pode alterar estiver como True, o usurio poder
escrever no campo.
A funo retorna um dicionrio, cujas chaves so os nomes dos campos e
os valores so os valores fornecidos pelo usurio e uma tecla, que  a
tecla usada pelo usurio para sair do formulrio.

Funes proporcionadas pelo DVCS
Estas funes foram criadas para facilitar o uso do tradutor para as
tarefas mais comuns. Esto implementadas no arquivo dvcs.py.

dvcsLeTecla(falar=True): bytes
L uma tecla, tratando o caso das teclas especiais.
Quando falar for False, a tecla no ser falada pelo Dosvox.
O uso recomendado para essa funo  o seguinte (usando as constantes):
tecla = dvcsLeTecla()
if tecla == F1:
    # cdigo para a funo F1

Nota: adicionado nesta verso o modificador falar, sugerido
pelo Fabiano Ferreira.

dvcsExecutaScript(nomeArq: str, rotina_externa: funo = None)
Executa um arquivo pelo Scriptvox do DVCS.
A funo retorna os mesmos valores que a funo nativa executaScript,
acima.

Constantes das teclas implementadas
ENTER, F1 a F12, CONTROL_F1 a CONTROL_F12, ALT_F1, INSERT, DELETE, HOME,
END, PAGEUP, PAGEDOWN, CIMA, BAIXO, ESQUERDA, DIREITA, BACKSPACE, ESC e
TAB.

Constantes das cores (para usar em textColor e textBackground)
BLACK
BLUE
GREEN
CYAN
RED
MAGENTA
BROWN
LIGHTGRAY

DARKGRAY
LIGHTBLUE
LIGHTGREEN
LIGHTCYAN
LIGHTRED
LIGHTMAGENTA
YELLOW
WHITE
