keymap.h

Go to the documentation of this file.

/*
 * This file is part of the Ultibo project, https://ultibo.org/
 *
 * The MIT License (MIT)
 *
 * Copyright (c) 2026 Garry Wood <garry@softoz.com.au>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
#ifndef _ULTIBO_KEYMAP_H
#define _ULTIBO_KEYMAP_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include "ultibo/globaltypes.h"
#include "ultibo/globalconst.h"

#define KEYMAP_KEY_COUNT    256 
#define KEYMAP_ROW_COUNT    4 
#define KEYMAP_ROW_SIZE sizeof(uint16_t)
 
#define KEYMAP_MAX_CAPSKEYS 50 
#define KEYMAP_MAX_DEADKEYS 5 
#define KEYMAP_MAX_RESOLVES 20 

#define KEYMAP_SIGNATURE    0x863FDBA1

#define KEYMAP_NAME_LENGTH  SIZE_64 
#define KEYMAP_DESC_LENGTH  SIZE_128 

#define KEYMAP_MODE_NONE    0

#define KEYMAP_FLAG_NONE    0x00000000
#define KEYMAP_FLAG_ALTGR   0x00000001 
#define KEYMAP_FLAG_CAPS_ALL    0x00000002 
#define KEYMAP_FLAG_CAPS_ASCII  0x00000004 

#define KEYMAP_INDEX_NORMAL 0 
#define KEYMAP_INDEX_SHIFT  1 
#define KEYMAP_INDEX_ALTGR  2 
#define KEYMAP_INDEX_SHIFT_ALTGR    3 
 
#define KEYMAP_INDEX_COUNT  4


typedef struct _KEYMAP_HEADER
{
    uint32_t mode; 
    uint32_t flags; 
    uint32_t keycount; 
    uint32_t rowcount; 
    char name[256]; 
    char description[256]; 
} KEYMAP_HEADER;

typedef struct _KEYMAP_DATA
{
    uint16_t data[256][KEYMAP_INDEX_COUNT]; 
} KEYMAP_DATA;

typedef uint16_t KEYMAP_CHARS[];

typedef struct _KEYMAP_CAPSKEY
{
    uint16_t first; 
    uint16_t last; 
} KEYMAP_CAPSKEY;

typedef struct _KEYMAP_CAPSKEYS
{
    uint32_t count;
    KEYMAP_CAPSKEY keys[KEYMAP_MAX_CAPSKEYS];
} KEYMAP_CAPSKEYS;

typedef struct _KEYMAP_RESOLVE
{
    uint16_t key; 
    uint8_t index; 
    uint16_t code; 
} KEYMAP_RESOLVE;

typedef struct _KEYMAP_DEADKEY
{
    uint16_t key; 
    uint8_t index; 
    KEYMAP_RESOLVE resolves[KEYMAP_MAX_RESOLVES];
} KEYMAP_DEADKEY;

typedef struct _KEYMAP_DEADKEYS
{
    uint32_t count;
    KEYMAP_DEADKEY keys[KEYMAP_MAX_DEADKEYS];
} KEYMAP_DEADKEYS;

typedef struct _KEYMAP_PROPERTIES KEYMAP_PROPERTIES;
struct _KEYMAP_PROPERTIES
{
    uint32_t keymapmode; 
    uint32_t keymapflags; 
    uint32_t keycount; 
    uint32_t rowcount; 
    char keymapname[KEYMAP_NAME_LENGTH]; 
    char keymapdescription[KEYMAP_DESC_LENGTH]; 
};
 
typedef struct _KEYMAP_ENTRY KEYMAP_ENTRY;

typedef uint32_t STDCALL (*keymap_enumerate_cb)(KEYMAP_HANDLE handle, void *data);

struct _KEYMAP_ENTRY
{
    // Keymap Properties
    uint32_t signature; 
    uint32_t keymapmode; 
    uint32_t keymapflags; 
    char keymapname[KEYMAP_NAME_LENGTH]; 
    char keymapdescription[KEYMAP_DESC_LENGTH]; 
    // Driver Properties
    void *keydata; 
    uint32_t keycount; 
    uint32_t rowcount; 
    KEYMAP_CAPSKEYS *capskeysdata; 
    KEYMAP_DEADKEYS *deadkeysdata; 
    // Internal Properties
    KEYMAP_ENTRY *prev; 
    KEYMAP_ENTRY *next; 
};


KEYMAP_HANDLE STDCALL keymap_load(KEYMAP_HEADER *header, KEYMAP_DATA *data, uint32_t size);

KEYMAP_HANDLE STDCALL keymap_load_ex(KEYMAP_HEADER *header, KEYMAP_DATA *data, KEYMAP_CAPSKEYS *capskeys, KEYMAP_DEADKEYS *deadkeys, uint32_t size, KEYMAP_PROPERTIES *properties);

uint32_t STDCALL keymap_unload(KEYMAP_HANDLE handle);

uint32_t STDCALL keymap_get_name(KEYMAP_HANDLE handle, char *name, uint32_t len);

uint32_t STDCALL keymap_get_description(KEYMAP_HANDLE handle, char *description, uint32_t len);

BOOL STDCALL keymap_check_flag(KEYMAP_HANDLE handle, uint32_t flag);

uint16_t STDCALL keymap_get_key_code(KEYMAP_HANDLE handle, uint16_t scancode, uint8_t index);

char STDCALL keymap_get_char_code(KEYMAP_HANDLE handle, uint16_t keycode);

WCHAR STDCALL keymap_get_char_unicode(KEYMAP_HANDLE handle, uint16_t keycode);

BOOL STDCALL keymap_check_capskey(KEYMAP_HANDLE handle, uint16_t scancode);

BOOL STDCALL keymap_check_deadkey(KEYMAP_HANDLE handle, uint16_t scancode, uint8_t index);

BOOL STDCALL keymap_resolve_deadkey(KEYMAP_HANDLE handle, uint16_t deadcode, uint16_t scancode, uint8_t deadindex, uint8_t scanindex, uint16_t *keycode);

uint32_t STDCALL keymap_get_properties(KEYMAP_HANDLE handle, KEYMAP_PROPERTIES *properties);

KEYMAP_HANDLE STDCALL keymap_find_by_name(const char *name);

KEYMAP_HANDLE STDCALL keymap_find_by_description(const char *description);

uint32_t STDCALL keymap_enumerate(keymap_enumerate_cb callback, void *data);


uint32_t STDCALL keymap_get_count(void);

KEYMAP_HANDLE STDCALL keymap_get_default(void);

uint32_t STDCALL keymap_set_default(KEYMAP_HANDLE handle);

KEYMAP_ENTRY * STDCALL keymap_check(KEYMAP_ENTRY *keymap);
 
#ifdef __cplusplus
}
#endif
 
#endif // _ULTIBO_KEYMAP_H