/*
  Copyright (c) 2022 Alex Diener
  
  This software is provided 'as-is', without any express or implied
  warranty. In no event will the authors be held liable for any damages
  arising from the use of this software.
  
  Permission is granted to anyone to use this software for any purpose,
  including commercial applications, and to alter it and redistribute it
  freely, subject to the following restrictions:
  
  1. The origin of this software must not be misrepresented; you must not
     claim that you wrote the original software. If you use this software
     in a product, an acknowledgment in the product documentation would be
     appreciated but is not required.
  2. Altered source versions must be plainly marked as such, and must not be
     misrepresented as being the original software.
  3. This notice may not be removed or altered from any source distribution.
  
  Alex Diener alex@ludobloom.com
*/

#ifndef __UIKeyShortcut_H__
#define __UIKeyShortcut_H__

#include "utilities/AutoFreePool.h"
#include "utilities/HashTable.h"
#include <stdbool.h>
#include <stddef.h>

typedef struct UIKeyShortcut {
	unsigned int keyCode;
	unsigned int modifiers;
	unsigned int alternateCount;
	struct {
		unsigned int keyCode;
		unsigned int modifiers;
	} * alternates;
} UIKeyShortcut;

#define KEY_SHORTCUT(key_code, additional_modifiers) AutoFreePool_add(UIKeyShortcut_single(key_code, additional_modifiers))
#define KEY_SHORTCUT_MULTIPLE(key_code, additional_modifiers, ...) AutoFreePool_add(UIKeyShortcut_multiple(key_code, additional_modifiers, ##__VA_ARGS__))

#define UIKeyShortcut_none NULL
UIKeyShortcut * UIKeyShortcut_single(unsigned int keyCode, unsigned int modifiers);
// Additional arguments: unsigned int keyCode, unsigned int modifiers, terminated by NULL
UIKeyShortcut * UIKeyShortcut_multiple(unsigned int keyCode, unsigned int modifiers, ...) __attribute__((sentinel));
UIKeyShortcut * UIKeyShortcut_copy(UIKeyShortcut * shortcut);

static inline void UIKeyShortcut_free(UIKeyShortcut * shortcut) {
	free(shortcut);
}

// If keyCodeEquivalents is non-NULL, each key code in the shortcut will be looked up as a uint32 key, and if found, the
// uint32 entry will be accepted as a valid match for the keyCode parameter. See also getDefaultKeyCodeEquivalents().
bool UIKeyShortcut_isMatch(UIKeyShortcut * shortcut, unsigned int keyCode, unsigned int modifiers, HashTable * keyEquivalents);
void UIKeyShortcut_getHumanReadableString(UIKeyShortcut * shortcut, bool useShellKeyLabel, bool includeAlternates, char * outString, size_t lengthMax);

// Returns true for key codes that are appropriate to use with Shell_getKeyLabel(), and false for key codes that
// are symbolic and invariant across international keyboard layouts
bool isLocalizableKeyCode(unsigned int keyCode);

// Returns a human-readable string for the specified key code, appropriate for displaying as a shortcut without
// the context of the key's position on the keyboard. Uses non-localized descriptions for all letter keys.
const char * getShortcutKeyCodeString(unsigned int keyCode);

// Returns a static HashTable with common key code translations for use with UIKeyShortcut_isMatch() in permissive
// matching situations. Number enter and number keys will be accepted in place of non-extended enter and number row
// keys, and forward delete will be accepted in place of backspace.
HashTable * getDefaultKeyEquivalents(void);

#endif