[BRLTTY] Low-level BrlAPI questions

[Samuel Thibault]

Aura Kelloniemi, le lun. 29 mars 2021 09:56:11 +0300, a ecrit:
> On 2021-03-28 at 22:32 +0200, Samuel Thibault <samuel.thibault at ens-lyon.org> wrote:
>  > Aura Kelloniemi, le dim. 28 mars 2021 12:05:46 +0300, a ecrit:
>  > > - If the number of code points in text does not match regionSize,
>  > >   brlapi__write does not write anything to the display.
> 
>  > ? Aren't you getting an exception?
> 
> Ah, I was calling brlapi__closeConnection after brlapi__write, and did not get
> an exception. I added a call to brlapi__leaveTtyMode, and now I see it.
> 
> Would it require changing the BrlAPI protocol to be able to pass the exception
> message to the client?

Yes.
The thing is: we'd rather not require an acknowledgment for each and
every write, so that they can pile up and be processed efficiently,
otherwise we can get flickering effects.

> It is a nuisance to restart BRLTTY and search the logs.

You can start brltty with -n -lserver to get immediate logs.

>  > > - Why does brlapi__writeDots go through all the trouble of decoding the raw
>  > >   dot pattern given by the caller to an UTF-8 sequence? It could just fill the
>  > >   text field with spaces, memset andMask to zero, and use dots as orMask. I
>  > >   have tested this, and it works.
> 
>  > It works for the braille output, but not for the text output, whenever a
>  > braille device has one, that text will remain blank.
> 
> I have never heard of such a device. Wow. Are they just virtual devices, or
> are there real ones as well?

The first device I saw has one :)

> And I have one more about brlapi_expandKeyCode. I kind of understand what this
> function supplies to the caller in struct brlapi_expandedKeyCode_t, but there
> is one dark corner: the case of type == BRLAPI_KEY_TYPE_SYM.
> 
> As far as I understand, if the key event corresponds to a Unicode symbol, cmd
> is set to 0 and arg is set to a Unicode scalar value.
> 
> If the symbol corresponds to an X keyboard symbol, cmd is set to 0xFF00, and
> arg contains 8 bits of key symbol value.

brlapi_expandKeyCode is not meant to be used for the keysym case. It
seems that there was a misplaced paragraph in the manual.

See man brlapi_keycodes: 

“
bits 28-0 (BRLAPI_KEY_CODE_MASK), key code: [...] for standard X
keysyms, this is the keysym value.
”

so mask with BRLAPI_KEY_CODE_MASK, and you will get a keysym.
Then there is nothing more to it than the X11 protocol. It does indeed
include some values that are simply the unicode values, but basically
see keysymdef.h

> - Are there other possible cmd/arg combinations that I did not list?

cmd/arg is for brltty commands, not keysyms.

> - What would be the most accurate and porable way of extracting all
>   information from a brlapi_keyCode_t value?

First check the key type with BRLAPI_KEY_TYPE_MASK, if it's a cmd you
can use brlapi_expandKeyCode, if its a keysym you can simply mask the
keysym.

> - Why is brlapi_argumentWidth() not exported, even if it is needed to fully
>   decode a brlapi_keyCode_t?

Normally brlapi_expandedKeyCode_t should already be providing what you
need. The bits about BRLAPI_KEY_TYPE_SYM, notably, seem doubtful to me
actually, programmers should most probably rather just consider "it's a
X11 keysym, use X11 keysym decoding".

Samuel