15.3.768  src/lib/x-kit/xclient/src/window/keycode-to-keysym.api

## keycode-to-keysym.api
#
# For the big picture see the imp dataflow diagrams in
#
#     src/lib/x-kit/xclient/src/window/xclient-ximps.pkg

# Compiled by:
#     src/lib/x-kit/xclient/xclient-internals.sublib


stipulate
    include package   threadkit;                                                                # threadkit                                     is from   src/lib/src/lib/thread-kit/src/core-thread-kit/threadkit.pkg
    #
    package xet =  xevent_types;                                                                # xevent_types                                  is from   src/lib/x-kit/xclient/src/wire/xevent-types.pkg
    package v1u =  vector_of_one_byte_unts;                                                     # vector_of_one_byte_unts                       is from   src/lib/std/src/vector-of-one-byte-unts.pkg
    package g2d =  geometry2d;                                                                  # geometry2d                                    is from   src/lib/std/2d/geometry2d.pkg
    package xt  = xtypes;                                                                       # xtypes                                        is from   src/lib/x-kit/xclient/src/wire/xtypes.pkg

    package x2s =  xclient_to_sequencer;                                                        # xclient_to_sequencer                          is from   src/lib/x-kit/xclient/src/wire/xclient-to-sequencer.pkg
    package dy  =  display;                                                                     # display                                       is from   src/lib/x-kit/xclient/src/wire/display.pkg

#    package r2k =  xevent_router_to_keymap;                                                    # xevent_router_to_keymap                       is from   src/lib/x-kit/xclient/src/window/xevent-router-to-keymap.pkg

#   oldworld -- do not use:
#   package dy  =  display_old;                                                                 # display_old                                   is from   src/lib/x-kit/xclient/src/wire/display-old.pkg

herein


    # This api is implemented in:
    #
    #     src/lib/x-kit/xclient/src/window/keycode-to-keysym.pkg
    #
    api Keycode_To_Keysym
    {
        Keycode_To_Keysym_Map                                                                   # Was "Keycode_Map/KEYCODE_MAP".
            =
            KEYCODE_TO_KEYSYM_MAP
              {
                min_keycode:    Int,
                max_keycode:    Int,
                vector:         Rw_Vector( List(xt::Keysym) )
              };

        Lock_Meaning =   NO_LOCK | LOCK_SHIFT | LOCK_CAPS;                                      # The meaning of the Lock modifier key.


        Shift_Mode   =   UNSHIFTED | SHIFTED | CAPS_LOCKED  Bool;                               # The shifting mode of a key-button state.


        Key_Mapping  =   KEY_MAPPING
                          {
                            lookup:                     xt::Keycode -> List(xt::Keysym),
                            keycode_to_keysym_map:      Keycode_To_Keysym_Map,
                            #
                            is_mode_switched:           xt::Modifier_Keys_State -> Bool,
                            shift_mode:                 xt::Modifier_Keys_State -> Shift_Mode
                          };


        # Translate a keycode plus modifier-state to a keysym:
        #       
        translate_keycode_to_keysym
            :
            Key_Mapping
            ->
            (xt::Keycode, xt::Modifier_Keys_State)
            ->
            xt::Keysym
            ;

        translate_keysym_to_keycode
            :
            Key_Mapping
            ->
            xt::Keysym
            ->
            Null_Or( xt::Keycode )
            ;


#       keycode_to_keysym:      xet::Key_Xevtinfo -> (xt::Keysym, xt::Modifier_Keys_State);     # Our workhouse call.


#       keysym_to_keycode:      xt::Keysym -> Null_Or(xt::Keycode);                             # Useful for selfcheck code generating keystrokes.
            #
            # Translate a keysym to a keycode.  This is intended
            # only for occasional selfcheck use, so we just do
            # a brute-force search down every list in every slot
            # of the KEYCODE_MAP.
            #
            # Currently we ignore modifier key issues, so this
            # logic won't work very well for SHIFT-ed chars or
            # control chars.   XXX BUGGO FIXME

        create_key_mapping
            :
            (x2s::Xclient_To_Sequencer, dy::Xdisplay)
            ->
            Key_Mapping;
    };                                                                                          # api Keymap_Ximp
end;