ptBR translations: docs/ptBR/keys.md
This commit is contained in:
AndersonTorres
committed by
Kyle Brown
Kyle Brown
parent
d21aa772a7
commit
b11fce321f
168
docs/ptBR/keys.md
Normal file
168
docs/ptBR/keys.md
Normal file
@@ -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()
|
||||
```
|
||||
Reference in New Issue
Block a user