////////////////////////////////////////////////////////////
//
// SFML - Simple and Fast Multimedia Library
// Copyright (C) 2007-2023 Marco Antognini (antognini.marco@gmail.com),
//                         Laurent Gomila (laurent@sfml-dev.org)
//
// 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.
//
////////////////////////////////////////////////////////////

#ifndef SFML_HIDINPUTMANAGER_HPP
#define SFML_HIDINPUTMANAGER_HPP

////////////////////////////////////////////////////////////
// Headers
////////////////////////////////////////////////////////////
#include <SFML/Window/JoystickImpl.hpp>
#include <SFML/Window/Keyboard.hpp>
#include <SFML/System/NonCopyable.hpp>
#include <Carbon/Carbon.h>
#include <IOKit/hid/IOHIDDevice.h>
#include <IOKit/hid/IOHIDManager.h>
#include <vector>

namespace sf
{
namespace priv
{

typedef std::vector<IOHIDElementRef> IOHIDElements;

////////////////////////////////////////////////////////////
/// \brief sf::priv::InputImpl helper
///
/// This class manage as a singleton instance the keyboard state.
/// Its purpose is to help sf::priv::InputImpl class.
///
////////////////////////////////////////////////////////////
class HIDInputManager : NonCopyable
{
public:

    ////////////////////////////////////////////////////////////
    /// \brief Get the unique instance of the class
    ///
    /// \note Private use only
    ///
    /// \return Reference to the HIDInputManager instance
    ///
    ////////////////////////////////////////////////////////////
    static HIDInputManager& getInstance();

public:

    ////////////////////////////////////////////////////////////
    /// \brief Get the usb location ID of a given device
    ///
    /// This location ID is unique and can be used a usb port identifier
    ///
    /// \param device HID device to query
    /// \return the device's location ID or 0 if something went wrong
    ///
    ////////////////////////////////////////////////////////////
    static long getLocationID(IOHIDDeviceRef device);

    ////////////////////////////////////////////////////////////
    /// \brief Create a mask (dictionary) for an IOHIDManager
    ///
    /// \param page  HID page
    /// \param usage HID usage page
    /// \return a retained CFDictionaryRef
    ///
    ////////////////////////////////////////////////////////////
    static CFDictionaryRef copyDevicesMask(UInt32 page, UInt32 usage);

    ////////////////////////////////////////////////////////////
    /// \brief Try to convert a character into a SFML key code
    ///
    /// Return sf::Keyboard::Unknown if it doesn't match any 'localized' keys.
    ///
    /// By 'localized' we mean keys that depend on the keyboard layout
    /// and might not be the same as the US keycode for some countries
    /// (e.g. the keys 'Y' and 'Z' are swapped on QWERTZ keyboard and
    /// US keyboard layouts.)
    ///
    ////////////////////////////////////////////////////////////
    static Keyboard::Key localizedKey(UniChar ch);

    ////////////////////////////////////////////////////////////
    /// \brief Opposite transformation as localizedKeys
    ///
    /// Return 0x00 (NULL) for non-convertible keys/numpad numbers.
    /// For letters, uppercase codes are returned.
    /// Some returned value are specific to macOS.
    ///
    ////////////////////////////////////////////////////////////
    static UniChar toUnicode(Keyboard::Key key);

    ////////////////////////////////////////////////////////////
    /// \brief Try to convert a virtual keycode (HID level) into a
    /// SFML scancode.
    ///
    /// Return sf::Keyboard::Scan::Unknown if the keycode is unknown.
    ///
    ////////////////////////////////////////////////////////////
    static Keyboard::Scancode nonLocalizedKey(UniChar virtualKeycode);

public:

    ////////////////////////////////////////////////////////////
    /// \copydoc sf::Keyboard::isKeyPressed(Key)
    ///
    ////////////////////////////////////////////////////////////
    bool isKeyPressed(Keyboard::Key key);

    ////////////////////////////////////////////////////////////
    /// \copydoc sf::Keyboard::isKeyPressed(Scancode)
    ///
    ////////////////////////////////////////////////////////////
    bool isKeyPressed(Keyboard::Scancode code);

    ////////////////////////////////////////////////////////////
    /// \copydoc sf::Keyboard::localize
    ///
    ////////////////////////////////////////////////////////////
    Keyboard::Key localize(Keyboard::Scancode code);

    ////////////////////////////////////////////////////////////
    /// \copydoc sf::Keyboard::delocalize
    ///
    ////////////////////////////////////////////////////////////
    Keyboard::Scancode delocalize(Keyboard::Key key);

    ////////////////////////////////////////////////////////////
    /// \copydoc sf::Keyboard::getDescription
    ///
    ////////////////////////////////////////////////////////////
    String getDescription(Keyboard::Scancode code);

private:

    ////////////////////////////////////////////////////////////
    /// \brief Default constructor
    ///
    ////////////////////////////////////////////////////////////
    HIDInputManager();

    ////////////////////////////////////////////////////////////
    /// \brief Destructor
    ///
    ////////////////////////////////////////////////////////////
    ~HIDInputManager();

    ////////////////////////////////////////////////////////////
    /// \brief Initialize the keyboard part of this class
    ///
    /// If something went wrong freeUp is called.
    ///
    /// In a nutshell, this function does this:
    ///
    ///     for each connected keyboard kb:
    ///       for each key k of kb:
    ///         memorize k -> scancode mapping
    ///
    ////////////////////////////////////////////////////////////
    void initializeKeyboard();

    ////////////////////////////////////////////////////////////
    /// \brief Load the given keyboard into m_keys
    ///
    /// If the given keyboard has no key this function simply
    /// returns without calling freeUp because this is not fatal.
    ///
    /// \param keyboard Keyboard to load
    ///
    /// \see initializeKeyboard
    ///
    ////////////////////////////////////////////////////////////
    void loadKeyboard(IOHIDDeviceRef keyboard);

    ////////////////////////////////////////////////////////////
    /// \brief Load the given key into m_keys
    ///
    /// On error, freeUp is _not_ called by this function.
    ///
    /// \param key Key to load
    ///
    /// \see initializeKeyboard
    ///
    ////////////////////////////////////////////////////////////
    void loadKey(IOHIDElementRef key);

    ////////////////////////////////////////////////////////////
    /// \brief Regenerate the mappings from/to Key and Scancode
    ///
    ////////////////////////////////////////////////////////////
    void buildMappings();

    ////////////////////////////////////////////////////////////
    /// \brief Callback to regenerate mappings from/to Key and
    /// Scancode when there's a keyboard layout change
    ///
    ////////////////////////////////////////////////////////////
    static void keyboardChanged(CFNotificationCenterRef /* center */, void* observer, CFStringRef /* name */, const void* /* object */, CFDictionaryRef /* userInfo */);

    ////////////////////////////////////////////////////////////
    /// \brief Release all resources
    ///
    /// Close all connections to any devices.
    ///
    /// \see initializeKeyboard
    ///
    ////////////////////////////////////////////////////////////
    void freeUp();

    ////////////////////////////////////////////////////////////
    /// \brief Filter the devices and return them
    ///
    /// On error, freeUp is _not_ called by this function.
    ///
    /// \param page  HID page like kHIDPage_GenericDesktop
    /// \param usage HID usage page like kHIDUsage_GD_Keyboard or kHIDUsage_GD_Mouse
    /// \return a retained, non-empty CFSetRef of IOHIDDeviceRef or NULL
    ///
    ////////////////////////////////////////////////////////////
    CFSetRef copyDevices(UInt32 page, UInt32 usage);

    ////////////////////////////////////////////////////////////
    /// \brief Check if a key is pressed
    ///
    /// \param elements HID elements mapping to this key
    ///
    /// \return True if the key is pressed, false otherwise
    ///
    /// \see isKeyPressed, isMouseButtonPressed
    ///
    ////////////////////////////////////////////////////////////
    bool isPressed(IOHIDElements& elements);

    ////////////////////////////////////////////////////////////
    /// \brief Convert a HID key usage to its corresponding scancode
    ///
    /// \param usage Any kHIDUsage_Keyboard* usage
    /// \return the scancode associated with the given HID key usage
    ///         or Scan::Unknown if it is associated with no scancode.
    ///
    ////////////////////////////////////////////////////////////
    static Keyboard::Scancode usageToScancode(UInt32 usage);

    ////////////////////////////////////////////////////////////
    /// Convert the scancode to the expected virtual code.
    ///
    ////////////////////////////////////////////////////////////
    static UInt8 scanToVirtualCode(Keyboard::Scancode code);

    ////////////////////////////////////////////////////////////
    /// Fallback convertion for keys which aren't expected to be impacted
    /// by the layout. Can return Unknown.
    ///
    ////////////////////////////////////////////////////////////
    static Keyboard::Key localizedKeyFallback(Keyboard::Scancode code);

private:

    ////////////////////////////////////////////////////////////
    // Member data
    ////////////////////////////////////////////////////////////
    IOHIDManagerRef    m_manager;                                             ///< Underlying HID Manager
    bool               m_keysInitialized;                                     ///< Has initializeKeyboard been called at least once?
    IOHIDElements      m_keys[Keyboard::Scan::ScancodeCount];                 ///< All the keys on any connected keyboard
    Keyboard::Scancode m_keyToScancodeMapping[Keyboard::KeyCount];            ///< Mapping from Key to Scancode
    Keyboard::Key      m_scancodeToKeyMapping[Keyboard::Scan::ScancodeCount]; ///< Mapping from Scancode to Key

    ////////////////////////////////////////////////////////////
    /// m_keys' index corresponds to sf::Keyboard::Scancode enum.
    /// If no key is assigned with key XYZ then m_keys[XYZ].size() == 0.
    /// If there are several keyboards connected and several HID keys associated
    /// with the same sf::Keyboard::Key then m_keys[XYZ] contains all these
    /// HID keys.
    ///
    /// The mappings (both directions) get invalidated when the
    /// keyboard layout changes. They both default to (Scan::)Unknown.
    ///
    ////////////////////////////////////////////////////////////
};

} // namespace priv

} // namespace sf

#endif
