Este documento une a inteligência técnica da estrutura do código (por Rui Fontes/Edilberto Fonseca) com o manual de operação de repositórios e publicação (por Wendrill/Ângelo Abrantes).
1. Arquitetura e Estrutura do Código-Fonte
Ao desenvolver um complemento (como o exemplo "Tirar Apontamentos"), a lógica de programação deve ser seguida rigorosamente para garantir a organização e facilidade de manutenção:
1.1. Variáveis Globais e Configuração
configFilePath: Define o caminho para o arquivo Config.json. Este arquivo é vital para armazenar de forma persistente o caminho do arquivo de notas que o usuário escolher.
self.filePath: Variável de instância que armazena o caminho do arquivo de texto (.txt) atualmente selecionado pelo usuário.
1.2. Métodos da Classe GlobalPlugin
__init__: Além de inicializar o complemento, deve carregar as configurações via loadConfig. É o que mantém o complemento ativo durante a sessão do NVDA.
loadConfig: Carrega o caminho do arquivo de notas padrão. Verifica se o Config.json existe; se sim, lê o caminho; caso contrário, retorna None.
saveConfig: Salva o caminho do arquivo em formato JSON para garantir que, ao reiniciar o NVDA, o usuário não precise configurar tudo novamente.
1.3. Scripts e Comandos de Teclado (Atalhos)
A implementação técnica deve seguir este mapeamento de funções e atalhos:
1. Ativação (NVDA+Control+Shift+A): Invoca o script script_activatePlugin, que solicita a escolha ou criação de um arquivo de notas padrão.
2. Capturar Texto Selecionado (Windows+Control+1): Obtém o texto selecionado de qualquer aplicativo ou página da web e o adiciona ao final do arquivo de notas.
3. Adicionar da Área de Transferência (Windows+Control+2): Lê o conteúdo do Clipboard do Windows e o anexa ao arquivo.
4. Adicionar Nota Manual (Windows+Control+3): Exibe um diálogo para o usuário digitar uma nota, que é salva com a data formatada (dd/mm/aaaa).
5. Editar Arquivo (Windows+Control+4): Abre uma interface wx (classe showNotes). Esta janela possui:
Campo de texto para edição direta.
Botões para Salvar, Copiar para área de transferência e Cancelar.
Suporte à tecla Escape para fechar sem salvar.
6. Reportar Arquivo Atual (Windows+Control+5): Informa, via voz/braille, o caminho completo do arquivo de notas em uso.
2. Gestão do Repositório no GitHub
2.1. Criação a partir do Template
Existem duas alternativas principais para iniciar o projeto:
Opção 1 (Via Interface): No repositório AddonTemplate, clique no botão "Use this template" (Utilizar este modelo) localizado acima do título de nível 1. Escolha "Create a new repository". Isso mantém a estrutura oficial e as automações (GitHub Actions).
Opção 2 (Manual): Clonar o repositório do template para sua conta e, quando quiser criar um novo extra, copiar toda a estrutura para uma nova pasta com o nome do complemento.
2.2. Uso do GitHub Desktop
1. Inicie sessão no GitHub pelo navegador.
2. No seu novo repositório, clique em "Code" e depois em "Open with GitHub Desktop".
3. O Chrome (ou seu navegador) pedirá permissão para abrir o app; aceite e escolha a pasta local no seu computador.
4. Clique em "Clone" ou "Create Repository" para baixar os arquivos.
3. Compilação e Tradução (O sistema SCons)
Este é o passo onde o código se transforma no arquivo instalável .nvda-addon:
1. Abrir o CMD na pasta: Na pasta local do extra, pressione Alt+D, digite cmd e aperte Enter.
2. Gerar Modelo de Tradução: Se o extra for traduzível, digite scons pot. O arquivo gerado deve ser renomeado para nvda.po, copiado para a pasta de idiomas (ex: locale/pt_BR/) e traduzido.
3. Gerar o Instalador: De volta à linha de comando, digite apenas scons.
O sistema verificará erros no código.
Se estiver tudo certo, será criado o arquivo .nvda-addon na pasta.
4. Publicação de Versões (Releases)
4.1. Sincronização (Commit e Push)
1. No GitHub Desktop, clique em "Fetch origin".
2. Vá até as caixas de edição (Summary e Description). Preencha com o número da versão (ex: 0.2) e as notas de lançamento.
3. Clique em "Commit to Master" (ou Main) e depois em "Push origin" para enviar ao GitHub online.
4.2. Criar a Release Online (Navegador)
1. Na página do seu repositório no GitHub, clique em "Releases" (ou em "Tags" e depois "Releases").
2. Clique em "Create a new release".
3. Clique em "Choose a tag", digite o número (ex: 0.2) e pressione Enter para criar a tag.
4. Preencha o título (ex: Versão 0.2) e a descrição das novidades.
5. Anexar o Binário: Clique em "Attach binaries..." e selecione o arquivo .nvda-addon que você gerou com o comando scons. Este passo é obrigatório para que as pessoas possam baixar o complemento pronto.
6. Clique em "Publish release".
5. Submissão à Loja Oficial e Referências
Após publicar a release, você pode registrar seu complemento na loja oficial do NVDA através do Formulário de Submissão do Addon Datastore.
Links de Apoio:
GitHub Desktop para Windows: Download
https://central.github.com/deployments/desktop/desktop/latest/win32
Modelo de Repositório Padrão: AddonTemplate
https://github.com/nvdaaddons/AddonTemplate
Link para o formulário de submissão à loja de extras do NVDA:
https://github.com/nvaccess/addon-datastore/issues/new?assignees=nvaccess&labels=autoSubmissionFromIssue&template=registerAddon.yml&title=%5BSubmit+add-on%5D%3A+
Código-Fonte Original do NVDA: Referência no GitHub
https://github.com/nvaccess/nvda
Dica Técnica: Se o seu complemento crescer e tiver muitas janelas, é aconselhável criar um módulo separado chamado dialogs.py para concentrar todos os diálogos, tornando a manutenção do código muito mais simples e intuitiva.
Tutorial escrito por Rui Fontes, Ângelo Abrantes, Edilberto Fonseca e Wendrill
Todos Direitos Reservados - Acessibilidade em Foco ®