From b11fce321f226ad71bb6a30c79c1d1a66f69ceee Mon Sep 17 00:00:00 2001 From: AndersonTorres Date: Sat, 21 Aug 2021 16:54:32 -0300 Subject: [PATCH] ptBR translations: docs/ptBR/keys.md --- docs/ptBR/keys.md | 168 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 docs/ptBR/keys.md diff --git a/docs/ptBR/keys.md b/docs/ptBR/keys.md new file mode 100644 index 0000000..2144f11 --- /dev/null +++ b/docs/ptBR/keys.md @@ -0,0 +1,168 @@ +# Teclas + +> NOTE: Isto não é uma tabela de busca de objetos fornecidos pelo KMK. Esta +> listagem pode ser encontrada em `keycodes.md`. Possivelmente vale a pena +> observar o código-fonte bruto se você estiver travado: `kmk/keys.py`. + +Este é um montante de documentação sobre como teclas físicas são mapeada para +eventos (e o ciclo-de-vida destes eventos) no KMK. É um tanto técnico, mas se +você cogita estender a funcionalidade so seu teclado com código extra, você +precisará de pelo menos uma fração deste conhecimento técnico. + +Os primeiros passos neste processo não são tão interessantes para a maior parte +dos fluxos de trabalho, razão pela qual eles estão tão soterrados no KMK: +varremos um monte de faixas de GPIO (o quão rápido o CircuitPython nos permitir) +para ver onde, numa matriz de teclas, uma delas foi pressionada. Os detalhes +técnicos deste processo estão melhor descritos na +[Wikipedia](https://en.wikipedia.org/wiki/Keyboard_matrix_circuit). Então, +varremos o mapa de teclas definido, encontrando a primeira tecla válida neste +índice baseado na pilha de camadas ativas (esta lógica, se você quer ler o +código, está em `kmk/internal_state.py`, método `_find_key_in_map`). + +Os próximos passos são a parte interessante, mas para compreendê-los precisamos +entender um pouco do objeto `Key` (encontrado em `kmk/keys.py`). Objetos `Key` +têm algumas peças fundamentais de informação: + +* O `code`, que pode ser qualquer inteiro. Inteiros menores que + `FIRST_KMK_INTERNAL_KEY` são enviados pela pilha de HID (e portanto para o + computador, que traduzirá aquele inteiro para algo útil - por exemplo, + `code=4` torna-se `a` em um teclado US QWERTY/Dvorak) + +* Os modificadores anexados (para implementar coisas como Shift ou `KC.HYPR` que + são pressionamentos de teclas singulares enviadas juntamente a mais de uma + tecla em um único reporte HID. Este é um conceito diferente de Sequências, que + são uma característica do KMK documentada em `sequences.md`). Para todos os + propósitos fora do núcleo do KMK, este campo deve ser ignorado - ele pode ser + seguramente populado mediante meios bem mais sãos que perder tempo fazendo + isso na mão. + +* Alguns dados sobre se a tecla deveria ter sido pressionada ou liberada - isto + é majoritariamente um detalhe de implementação sobre como Sequências + funcionam, onde, por exemplo, `KC.RALT` pode precisar ser segurada por toda a + duração da sequência, em vez de ser liberada imediatamente antes de mover para + o próximo catactere. Geralmente usuários finais não precisam se preocupar com + isso, mas os campos são denominados `no_press` e `no_release` e são + referenciados em alguns lugares da base de código se você precisar de + exemplos. + +* Manipuladores (*handler*) para o pressionamento (algumas vezes chamado de + "keydown" ou "press") e liberação (algumas vezes chamado de "keyup" ou + "release"). KMK fornece manipuladores para funções padrão do yteclado e + algumas teclas especiais de sobrescrita (como `KC.GESC`, que é uma forma + aprimorada de teclas ANSI já existentes) em `kmk/handlers/stock.py`, para + troca de camadas em `kmk/handlers.layers.py`, e para tudo relacionado a + sequências (veja de novo `sequences.md`) em + `kmk/handlers/sequences.py`. Discutiremos mais estes em breve. + +* Chamadas de retorno (*callback*) opcionais a serem executadas antes e/ou + depois dos handlers acima. Mais sobre isso em breve. + +* Um campo `meta` genérico, que é mais comumente utilizado para teclas "com + argumentos" - objetos no objeto `KC` que na realidade são funções que retornam + instâncias de `Key`, que geralmente precisam acessar os argumentos passados + para a "função mais externa". Muitos destes exemplos são relacionados com + trocas de camadas - por exemplo, `KC.MO` é implementada como uma tecla com + argumentos - quando o usuário acrescenta `KC.MO(1)` ao teclado, a chamada de + função retorna um objeto `Key` com `meta` contendo um objeto contendo as + propriedades `layer` e `kc`. Existem outros usos para o campo `meta`, e + exemplos podem ser encontrados em `kmk/types.py`. + +Objetos `Key` também podem ser encadeados chamando eles! Para criar uma tecla +que segura Ctrl e Shift simultaneamente, simplesmente fazemos: + +```python +CTRLSHFT = KC.LCTL(KC.LSFT) + +keyboard.keymap = [ ... CTRLSHFT ... ] +``` + +Quando uma tecla é pressionada e tiramos um objeto `Key` do keymap, acontecerá o +seguinte: + +- Callbacks pré-pressionamento serão executados na ordem em que foram + atribuídos, com seus valores de retorno descartados (a não ser que o usuário + os anexe, eles quase nunca existem). +- O handler de pressionamento correspondente será executado (mais comumente este + é fornecido pelo KMK). +- Calllbacks pós-pressionamento serão executados na ordem em que foram + atribuídos, com seus valores de retorno descartados (a não ser que o usuário + os anexe, eles quase nunca existem). + +Os mesmos passos são executados quando uma tecla é liberada. + +_OK, então... Mas o que é um handler, e o que são esses callbacks?!_ + +Grosso modo, todos eles servem a um mesmo propósiti: fazer algo com os dados da +tecla, ou executar efeitos colaterais. A maioria dos handlers são fornecidos +pelo KMK internamente e modificam o `InternalState` de alguma forma - +adicionando a tecla à fila HID, modificando camadas, etc. Os handlers +pré/pós-pressionamento são projetados para permitir que a funcionalidade seja +embutida nestes pontos no fluxo de eventos sem ter que reimplementar (ou +importar e chamar internamente) os handlers internos. + +Todos esses métodos recebem os mesmos argumentos, e por isso eu vou copiar a +docstring direto do código-fonte: + +> Recebe o seguinte: +> +> - self (Esta instância Key) +> - state (InternalState corrente) +> - KC (A tabela de busca KC, para conveniência) +> - `coord_int` (Um inteiro, representação interna da coordenada da matriz para +> a tecla pressionada - costumeiramente isto não é útil para usuários finais, +> mas é fornecida por consistência com os manipuladores internos) +> - `coord_raw` (Uma tupla X,Y de coordenadas da matrix - costumeiramente não é +> útil, também) +> +> O valor de retorno do callback fornecido é descartado. _Exceções não são +> capturadas_, e provavelmente quebrarão o KMK se não forem tratadas dentro da +> tua função. +> +> Estes handlers são executados na ordem de anexação: handlers fornecidos por +> chamadas anteriores deste método são executados antes daqueles fornecidos por +> chamadas posteriores. + +Isto significa que se você quer adicionar coisas como suporte a LED/brilho, ou +um botão que aciona seu modem GSM para falar com alguém, ou seja lá o que você +puder fazer em CircuitPython, que também retenha as capacidades de troca de +camadas ou seja lá qual for o handler de suporte, você está coberto. Isto também +significa que você pode adicionar funcionalidades completamente novas ao KMK +escrevendo seu próprio handler. + +Eis um exemplo de gancho de ciclo de vida (*lifecycle hook*) que imprime um +Shrek gigante em Arte ASCII. Ele não utiliza os argumentos que recebe, porque +não tem intenção de modificar o estado interno. Ele é puramente um efeito +colateral ([side +effect](https://en.wikipedia.org/wiki/Side_effect_(computer_science))) executado +sempre que se pressiona o Alt esquerdo: + +```python +def shrek(*args, **kwargs): + print('⢀⡴⠑⡄⠀⠀⠀⠀⠀⠀⠀⣀⣀⣤⣤⣤⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀') + print('⠸⡇⠀⠿⡀⠀⠀⠀⣀⡴⢿⣿⣿⣿⣿⣿⣿⣿⣷⣦⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀') + print('⠀⠀⠀⠀⠑⢄⣠⠾⠁⣀⣄⡈⠙⣿⣿⣿⣿⣿⣿⣿⣿⣆⠀⠀⠀⠀⠀⠀⠀⠀') + print('⠀⠀⠀⠀⢀⡀⠁⠀⠀⠈⠙⠛⠂⠈⣿⣿⣿⣿⣿⠿⡿⢿⣆⠀⠀⠀⠀⠀⠀⠀') + print('⠀⠀⠀⢀⡾⣁⣀⠀⠴⠂⠙⣗⡀⠀⢻⣿⣿⠭⢤⣴⣦⣤⣹⠀⠀⠀⢀⢴⣶⣆') + print('⠀⠀⢀⣾⣿⣿⣿⣷⣮⣽⣾⣿⣥⣴⣿⣿⡿⢂⠔⢚⡿⢿⣿⣦⣴⣾⠁⠸⣼⡿') + print('⠀⢀⡞⠁⠙⠻⠿⠟⠉⠀⠛⢹⣿⣿⣿⣿⣿⣌⢤⣼⣿⣾⣿⡟⠉⠀⠀⠀⠀⠀') + print('⠀⣾⣷⣶⠇⠀⠀⣤⣄⣀⡀⠈⠻⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡇⠀⠀⠀⠀⠀⠀') + print('⠀⠉⠈⠉⠀⠀⢦⡈⢻⣿⣿⣿⣶⣶⣶⣶⣤⣽⡹⣿⣿⣿⣿⡇⠀⠀⠀⠀⠀⠀') + print('⠀⠀⠀⠀⠀⠀⠀⠉⠲⣽⡻⢿⣿⣿⣿⣿⣿⣿⣷⣜⣿⣿⣿⡇⠀⠀⠀⠀⠀⠀') + print('⠀⠀⠀⠀⠀⠀⠀⠀⢸⣿⣿⣷⣶⣮⣭⣽⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀') + print('⠀⠀⠀⠀⠀⠀⣀⣀⣈⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠇⠀⠀⠀⠀⠀⠀⠀') + print('⠀⠀⠀⠀⠀⠀⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠃⠀⠀⠀⠀⠀⠀⠀⠀') + print('⠀⠀⠀⠀⠀⠀⠀⠹⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠟⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀') + print('⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠛⠻⠿⠿⠿⠿⠛⠉') + + +KC.LALT.before_press_handler(shrek) +``` + +Você também pode copiar uma tecla sem quaisquer handlers pré ou pós nela +mediante `.clone()`, tal que por exemplo, se eu já adicionei Shrek ao meu `LALT` +mas quero um `LALT` sem Shrek em algum lugar do keymap, eu posso simplesmente +clonar a tecla, e a nova tecla não terá meus handlers atrelados a ela: + +```python +SHREKLESS_ALT = KC.LALT.clone() +```