Flags and masks

The top three bits in the left most byte are reserved for user defined flags. Such flags can be used to indicate that a sequence was interrupted for some input, or to toggle between various modes. One common use is to allow the temporary disabling of a particularly drastic key redefinition scheme to allow other users who aren't used to this scheme to type anything. Internally the flags are treated as if they were status keys like the shift, control and alternate keys. The difference is that the user exerts software control over them. The flags are set either by providing an absolute bit pattern (with the mnemonics flagsxxx), by turning one flag on (with flagxon) or turning one flag off (with flagxoff). The flags are numbered 1 to 3 and the leftmost bit corresponds to flag three.

So let's try an example. The key sequence shift-escape followed by the number one will put the current range between mark and cursor inside a fold, properly commented for the language TEX. Of course a fold needs a name, so in the middle it has to wait for for the user to type a name. After the name is complete the user presses again shift-escape followed by the number 1 and the sequence will be finished. For storing the name we use the learn buffer 0 as we don't want to upset the paste buffers.

: Example 5 : Put a marked range in a fold
              Mark should be at end of range!;

0200101B (left-shift+escape)+00000031 (number 1)=
    flag3on                   (Switch flag 3 on)
    insert                    (make the new line)
    % blank blank # \[ blank  (start of line)
    command l 0 endcommand    (start learning);

8200101B (left-shift+escape)+80000031 (number 1)=
    learn0       (finish learning)
    flag3off     (switch back to normal)
    blank colon  (finish the opening fold line)
    exchange     (go to the end of the range)
    insert       (make new line)
    % blank blank # \] blank  (start other line)
    learn0       (replay the typing of the name)
    blank colon  (finish this line)
    close        (close the fold {optional});
As you can see, we have two entries for the sh-esc+1 code sequence. The second time however we demand that the top bit, corresponding to the third flag, has been set.

The attentive reader will have noticed the left-shift, and may wonder about the right shift key (and about the simultaneous activities of the other flags). It would be rather annoying to have to provided the same code up to 24 times (left, right, left+right and this times 4 positions for the two other flags, and times two for the CapsLock key). For this we have masking. Basically a mask tells that a certain redefinition is active regardless the settings of some flags or status keys. Masks are only relevant at the left hand side of a redefinition. They should not occur at the right side. The mask should be in the leftmost 7 bits of byte 2. These are called bit 1 to 7 and 7 is the leftmost bit. The meaning of the bits is:

bit 1
This means that either one or both shift keys should be pressed. It is irrelevant which shift key. Hex code = 02.
bit 2
It doesn't matter whether the control key is pressed. Hex code = 04.
bit 3
It doesn't matter whether the alternate key is pressed. Hex code = 08.
bit 4
It doesn't matter whether the CapsLock key is pressed. Hex code = 10.
bit 5
It doesn't matter whether flag 1 is on or off. Hex code = 20.
bit 6
It doesn't matter whether flag 2 is on or off. Hex code = 40.
bit 7
It doesn't matter whether flag 3 is on or off. Hex code = 80.
One may combine masks by adding the corresponding hex codes. To make the scheme of the fold lines complete we make now the complete left sides as they could look in a real redefinition scheme:
: Example 5a : The proper left hand sides;

0272101B (shift+escape) + 00700031 (number 1) =
    etc....

8272101B (shift+escape) + 80700031 (number 1) =
    etc....
We have added the mask 72 (=02+10+20+40) which tells that we don't care whether it is the left shift, the right shift, or both. Neither do we care whether the CapsLock has been pressed or what the status of the other flags is. The 70 is similar but now we don't need the shift keys (on most keyboards at least). One could of course make the scheme independent of one flag and dependent of the other. If non of the redefinitions have masked out flag 2 we could set up a toggle to temporarily disable all redefinitions:
: Example 6 : Toggle flag 2;

02B21018 (shift+backspace mask 1+3) = flag2on:
    If flag 2 is off, turn it on;

42B21018 (shift+backspace mask 1+3) = flag2off:
    If flag 2 is on, turn it off;
If all other redefinitions don't like flag 2 then none of them will work when flag 2 is turned on.