mirror of
https://github.com/Drezil/imgui.git
synced 2025-07-04 12:08:47 +02:00
Inputs: Extra Keys / AddKeyEvent(): bidirectional mapping, basic CI, simplify backends, asserts on misuses, tested backward compat. (#2625, #4858, #2787)
(edit: simplified backends merged into previous commits to make history clearer)
This commit is contained in:
ocornut
105
imgui.h
105
imgui.h
@ -65,7 +65,7 @@ Index of this file:
|
||||
// Version
|
||||
// (Integer encoded as XYYZZ for use in #if preprocessor conditionals. Work in progress versions typically starts at XYY99 then bounce up to XYY00, XYY01 etc. when release tagging happens)
|
||||
#define IMGUI_VERSION "1.87 WIP"
|
||||
#define IMGUI_VERSION_NUM 18603
|
||||
#define IMGUI_VERSION_NUM 18604
|
||||
#define IMGUI_CHECKVERSION() ImGui::DebugCheckVersionAndDataLayout(IMGUI_VERSION, sizeof(ImGuiIO), sizeof(ImGuiStyle), sizeof(ImVec2), sizeof(ImVec4), sizeof(ImDrawVert), sizeof(ImDrawIdx))
|
||||
#define IMGUI_HAS_TABLE
|
||||
|
||||
@ -152,6 +152,7 @@ struct ImColor; // Helper functions to create a color that c
|
||||
struct ImGuiContext; // Dear ImGui context (opaque structure, unless including imgui_internal.h)
|
||||
struct ImGuiIO; // Main configuration and I/O between your application and ImGui
|
||||
struct ImGuiInputTextCallbackData; // Shared state of InputText() when using custom ImGuiInputTextCallback (rare/advanced use)
|
||||
struct ImGuiKeyData; // Storage for ImGuiIO and IsKeyDown(), IsKeyPressed() etc functions.
|
||||
struct ImGuiListClipper; // Helper to manually clip large list of items
|
||||
struct ImGuiOnceUponAFrame; // Helper for running a block of code not more than once a frame
|
||||
struct ImGuiPayload; // User data payload for drag and drop operations
|
||||
@ -173,7 +174,7 @@ typedef int ImGuiCol; // -> enum ImGuiCol_ // Enum: A
|
||||
typedef int ImGuiCond; // -> enum ImGuiCond_ // Enum: A condition for many Set*() functions
|
||||
typedef int ImGuiDataType; // -> enum ImGuiDataType_ // Enum: A primary data type
|
||||
typedef int ImGuiDir; // -> enum ImGuiDir_ // Enum: A cardinal direction
|
||||
typedef int ImGuiKey; // -> enum ImGuiKey_ // Enum: A key identifier (ImGui-side enum)
|
||||
typedef int ImGuiKey; // -> enum ImGuiKey_ // Enum: A key identifier
|
||||
typedef int ImGuiNavInput; // -> enum ImGuiNavInput_ // Enum: An input identifier for navigation
|
||||
typedef int ImGuiMouseButton; // -> enum ImGuiMouseButton_ // Enum: A mouse button identifier (0=left, 1=right, 2=middle)
|
||||
typedef int ImGuiMouseCursor; // -> enum ImGuiMouseCursor_ // Enum: A mouse cursor identifier
|
||||
@ -884,20 +885,16 @@ namespace ImGui
|
||||
IMGUI_API void ColorConvertHSVtoRGB(float h, float s, float v, float& out_r, float& out_g, float& out_b);
|
||||
|
||||
// Inputs Utilities: Keyboard
|
||||
// Without IMGUI_DISABLE_OBSOLETE_KEYIO:
|
||||
// - For 'ImGuiKey key' you can use your own indices/enums according to how your backend/engine stored them in io.KeysDown[].
|
||||
// - We don't know the meaning of those value. You can use GetKeyIndex() to map a ImGuiKey_ value into the user index.
|
||||
// With: IMGUI_DISABLE_OBSOLETE_KEYIO:
|
||||
// - `ImGuiKey key` will assert when key < 512 will be passed, previously reserved as user keys indices
|
||||
// Without IMGUI_DISABLE_OBSOLETE_KEYIO: (legacy support)
|
||||
// - For 'ImGuiKey key' you can still use your legacy native/user indices according to how your backend/engine stored them in io.KeysDown[].
|
||||
// With IMGUI_DISABLE_OBSOLETE_KEYIO: (this is the way forward)
|
||||
// - Any use of 'ImGuiKey' will assert when key < 512 will be passed, previously reserved as native/user keys indices
|
||||
// - GetKeyIndex() is pass-through and therefore deprecated (gone if IMGUI_DISABLE_OBSOLETE_KEYIO is defined)
|
||||
#ifndef IMGUI_DISABLE_OBSOLETE_KEYIO
|
||||
IMGUI_API int GetKeyIndex(ImGuiKey key); // map ImGuiKey_* values into user's key index. == io.KeyMap[key]
|
||||
#endif
|
||||
IMGUI_API const char* GetKeyName(ImGuiKey key); // returns English name of the key
|
||||
IMGUI_API bool IsKeyDown(ImGuiKey key); // is key being held. == io.KeysData[key - ImGuiKey_FirstKey].Down.
|
||||
IMGUI_API bool IsKeyDown(ImGuiKey key); // is key being held.
|
||||
IMGUI_API bool IsKeyPressed(ImGuiKey key, bool repeat = true); // was key pressed (went from !Down to Down)? if repeat=true, uses io.KeyRepeatDelay / KeyRepeatRate
|
||||
IMGUI_API bool IsKeyReleased(ImGuiKey key); // was key released (went from Down to !Down)?
|
||||
IMGUI_API int GetKeyPressedAmount(int key, float repeat_delay, float rate); // uses provided repeat rate/delay. return a count, most often 0 or 1 but might be >1 if RepeatRate is small enough that DeltaTime > RepeatRate
|
||||
IMGUI_API int GetKeyPressedAmount(ImGuiKey key, float repeat_delay, float rate); // uses provided repeat rate/delay. return a count, most often 0 or 1 but might be >1 if RepeatRate is small enough that DeltaTime > RepeatRate
|
||||
IMGUI_API const char* GetKeyName(ImGuiKey key); // [DEBUG] returns English name of the key. Those names a provided for debugging purpose and are not meant to be saved persistently not compared.
|
||||
IMGUI_API void CaptureKeyboardFromApp(bool want_capture_keyboard_value = true); // attention: misleading name! manually override io.WantCaptureKeyboard flag next frame (said flag is entirely left for your application to handle). e.g. force capture keyboard when your widget is being hovered. This is equivalent to setting "io.WantCaptureKeyboard = want_capture_keyboard_value"; after the next NewFrame() call.
|
||||
|
||||
// Inputs Utilities: Mouse
|
||||
@ -1358,15 +1355,8 @@ enum ImGuiSortDirection_
|
||||
|
||||
enum ImGuiKey_
|
||||
{
|
||||
ImGuiKey_None = 0,
|
||||
|
||||
// Reserve range used by legacy io.KeyMap[]. Prior to 1.86 we required user to fill io.KeysDown[512] using their own native index.
|
||||
// We are ditching this method but keeping a legacy path for user code doing e.g. IsKeyPressed(MY_NATIVE_KEY_CODE)
|
||||
ImGuiKey_LegacyNativeKey_BEGIN = 0,
|
||||
ImGuiKey_LegacyNativeKey_END = 512, // First index after valid range
|
||||
ImGuiKey_NamedKey_BEGIN = 512,
|
||||
|
||||
ImGuiKey_Tab = 512,
|
||||
ImGuiKey_None = 0,
|
||||
ImGuiKey_Tab = 512, // == ImGuiKey_NamedKey_BEGIN
|
||||
ImGuiKey_LeftArrow,
|
||||
ImGuiKey_RightArrow,
|
||||
ImGuiKey_UpArrow,
|
||||
@ -1473,17 +1463,20 @@ enum ImGuiKey_
|
||||
ImGuiKey_F12,
|
||||
ImGuiKey_COUNT, // No valid ImGuiKey is ever greater than this value
|
||||
|
||||
ImGuiKey_NamedKey_END = ImGuiKey_COUNT,
|
||||
ImGuiKey_NamedKey_COUNT = ImGuiKey_NamedKey_END - ImGuiKey_NamedKey_BEGIN,
|
||||
|
||||
#ifndef IMGUI_DISABLE_OBSOLETE_KEYIO
|
||||
ImGuiKey_KeyIndex_BEGIN = ImGuiKey_LegacyNativeKey_BEGIN,
|
||||
ImGuiKey_KeyIndex_END = ImGuiKey_LegacyNativeKey_END,
|
||||
// Legacy range used by legacy io.KeyMap[]. Prior to 1.87 we required user to fill io.KeysDown[512] using their own native index.
|
||||
// We are ditching this method but keeping a legacy path for user code doing e.g. IsKeyPressed(MY_NATIVE_KEY_CODE)
|
||||
ImGuiKey_LegacyNativeKey_BEGIN = 0,
|
||||
ImGuiKey_LegacyNativeKey_END = 512, // First index after valid range
|
||||
ImGuiKey_NamedKey_BEGIN = 512,
|
||||
ImGuiKey_NamedKey_END = ImGuiKey_COUNT,
|
||||
ImGuiKey_NamedKey_COUNT = ImGuiKey_NamedKey_END - ImGuiKey_NamedKey_BEGIN,
|
||||
#ifdef IMGUI_DISABLE_OBSOLETE_KEYIO
|
||||
ImGuiKey_KeysData_SIZE = ImGuiKey_NamedKey_COUNT, // Size of KeysData[]: only hold named keys
|
||||
ImGuiKey_KeysData_OFFSET = ImGuiKey_NamedKey_BEGIN // First key stored in KeysData[0]
|
||||
#else
|
||||
ImGuiKey_KeyIndex_BEGIN = ImGuiKey_NamedKey_BEGIN,
|
||||
ImGuiKey_KeyIndex_END = ImGuiKey_NamedKey_END,
|
||||
ImGuiKey_KeysData_SIZE = ImGuiKey_COUNT, // Size of KeysData[]: hold legacy 0..512 keycodes + named keys
|
||||
ImGuiKey_KeysData_OFFSET = ImGuiKey_LegacyNativeKey_BEGIN // First key stored in KeysData[0]
|
||||
#endif
|
||||
ImGuiKey_KeyIndex_COUNT = ImGuiKey_KeyIndex_END - ImGuiKey_KeyIndex_BEGIN
|
||||
|
||||
#ifndef IMGUI_DISABLE_OBSOLETE_FUNCTIONS
|
||||
, ImGuiKey_KeyPadEnter = ImGuiKey_KeypadEnter // Renamed in 1.87
|
||||
@ -1501,7 +1494,7 @@ enum ImGuiKeyModFlags_
|
||||
};
|
||||
|
||||
// Gamepad/Keyboard navigation
|
||||
// Keyboard: Set io.ConfigFlags |= ImGuiConfigFlags_NavEnableKeyboard to enable. NewFrame() will automatically fill io.NavInputs[] based on your io.KeysDown[] + io.KeyMap[] arrays.
|
||||
// Keyboard: Set io.ConfigFlags |= ImGuiConfigFlags_NavEnableKeyboard to enable. NewFrame() will automatically fill io.NavInputs[] based on your io.AddKeyEvent() calls.
|
||||
// Gamepad: Set io.ConfigFlags |= ImGuiConfigFlags_NavEnableGamepad to enable. Backend: set ImGuiBackendFlags_HasGamepad and fill the io.NavInputs[] fields before calling NewFrame(). Note that io.NavInputs[] is cleared by EndFrame().
|
||||
// Read instructions in imgui.cpp for more details. Download PNG/PSD at http://dearimgui.org/controls_sheets.
|
||||
enum ImGuiNavInput_
|
||||
@ -1525,7 +1518,7 @@ enum ImGuiNavInput_
|
||||
ImGuiNavInput_TweakFast, // Faster tweaks // e.g. R1 or R2 (PS4), RB or RT (Xbox), R or ZL (Switch)
|
||||
|
||||
// [Internal] Don't use directly! This is used internally to differentiate keyboard from gamepad inputs for behaviors that require to differentiate them.
|
||||
// Keyboard behavior that have no corresponding gamepad mapping (e.g. CTRL+TAB) will be directly reading from io.KeysDown[] instead of io.NavInputs[].
|
||||
// Keyboard behavior that have no corresponding gamepad mapping (e.g. CTRL+TAB) will be directly reading from keyboard keys instead of io.NavInputs[].
|
||||
ImGuiNavInput_KeyLeft_, // Move left // = Arrow keys
|
||||
ImGuiNavInput_KeyRight_, // Move right
|
||||
ImGuiNavInput_KeyUp_, // Move up
|
||||
@ -1538,7 +1531,7 @@ enum ImGuiNavInput_
|
||||
enum ImGuiConfigFlags_
|
||||
{
|
||||
ImGuiConfigFlags_None = 0,
|
||||
ImGuiConfigFlags_NavEnableKeyboard = 1 << 0, // Master keyboard navigation enable flag. NewFrame() will automatically fill io.NavInputs[] based on io.KeysDown[].
|
||||
ImGuiConfigFlags_NavEnableKeyboard = 1 << 0, // Master keyboard navigation enable flag. NewFrame() will automatically fill io.NavInputs[] based on io.AddKeyEvent() calls
|
||||
ImGuiConfigFlags_NavEnableGamepad = 1 << 1, // Master gamepad navigation enable flag. This is mostly to instruct your imgui backend to fill io.NavInputs[]. Backend also needs to set ImGuiBackendFlags_HasGamepad.
|
||||
ImGuiConfigFlags_NavEnableSetMousePos = 1 << 2, // Instruct navigation to move the mouse cursor. May be useful on TV/console systems where moving a virtual mouse is awkward. Will update io.MousePos and set io.WantSetMousePos=true. If enabled you MUST honor io.WantSetMousePos requests in your backend, otherwise ImGui will react as if the mouse is jumping around back and forth.
|
||||
ImGuiConfigFlags_NavNoCaptureKeyboard = 1 << 3, // Instruct navigation to not set the io.WantCaptureKeyboard flag when io.NavActive is set.
|
||||
@ -1927,11 +1920,13 @@ struct ImGuiStyle
|
||||
// Access via ImGui::GetIO(). Read 'Programmer guide' section in .cpp file for general usage.
|
||||
//-----------------------------------------------------------------------------
|
||||
|
||||
// [Internal] Storage used by IsKeyDown(), IsKeyPressed() etc functions.
|
||||
// If prior to 1.87 you used io.KeysDownDuration[] (which was marked as internal), you should use GetKeyData(key)->DownDuration and not io.KeysData[key]->DownDuration.
|
||||
struct ImGuiKeyData
|
||||
{
|
||||
bool Down; // True for if key is down
|
||||
float DownDuration; // Duration the keyboard key has been down (0.0f == just pressed)
|
||||
float DownDurationPrev; // Previous duration the key has been down
|
||||
bool Down; // True for if key is down
|
||||
float DownDuration; // Duration the key has been down (<0.0f: not pressed, 0.0f: just pressed, >0.0f: time held)
|
||||
float DownDurationPrev; // Last frame duration the key has been down
|
||||
};
|
||||
|
||||
struct ImGuiIO
|
||||
@ -2011,23 +2006,14 @@ struct ImGuiIO
|
||||
float NavInputs[ImGuiNavInput_COUNT]; // Gamepad inputs. Cleared back to zero by EndFrame(). Keyboard keys will be auto-mapped and be written here by NewFrame().
|
||||
|
||||
// Input Functions
|
||||
IMGUI_API void AddKeyEvent(ImGuiKey key, bool down, int native_keycode = -1, int native_scancode = -1); // Notify Dear ImGui of key down/up event
|
||||
IMGUI_API void AddKeyEvent(ImGuiKey key, bool down); // Queue a new key down/up event. Key should be "translated" (as in, generally ImGuiKey_A matches the key end-user would use to emit an 'A' character)
|
||||
IMGUI_API void AddFocusEvent(bool focused); // Queue an hosting application/platform windows gain or loss of focus
|
||||
IMGUI_API void AddInputCharacter(unsigned int c); // Queue new character input
|
||||
IMGUI_API void AddInputCharacterUTF16(ImWchar16 c); // Queue new character input from an UTF-16 character, it can be a surrogate
|
||||
IMGUI_API void AddInputCharactersUTF8(const char* str); // Queue new characters input from an UTF-8 string
|
||||
IMGUI_API void ClearInputCharacters(); // [Internal] Clear the text input buffer manually
|
||||
IMGUI_API void ClearInputKeys(); // [Internal] Release all keys
|
||||
|
||||
//------------------------------------------------------------------
|
||||
// Legacy: before 1.86, we required backend to fill io.KeyMap[] (imgui->native map) during Init and io.KeysDown[] (native indices) every frame.
|
||||
// This is still temporarily supported as a legacy feature. However the new preferred scheme is for backend to call io.AddKeyEvent().
|
||||
//------------------------------------------------------------------
|
||||
|
||||
#ifndef IMGUI_DISABLE_OBSOLETE_KEYIO
|
||||
int KeyMap[ImGuiKey_COUNT]; // [LEGACY] Input: map of indices into the KeysDown[512] entries array which represent your "native" keyboard state. The first 512 are now unused and should be kept zero. Legacy backend will write into KeyMap[] using ImGuiKey_ indices which are always >512.
|
||||
bool KeysDown[512]; // [LEGACY] Input: Keyboard keys that are pressed (ideally left in the "native" order your engine has access to keyboard keys, so you can use your own defines/enums for keys).
|
||||
#endif
|
||||
IMGUI_API void SetKeyEventNativeData(ImGuiKey key, int native_keycode, int native_scancode, int native_legacy_index = -1); // [Optional] Specify index for legacy <1.87 IsKeyXXX() functions with native indices + specify native keycode, scancode.
|
||||
|
||||
//------------------------------------------------------------------
|
||||
// Output - Updated by NewFrame() or EndFrame()/Render()
|
||||
@ -2050,13 +2036,20 @@ struct ImGuiIO
|
||||
int MetricsActiveAllocations; // Number of active allocations, updated by MemAlloc/MemFree based on current context. May be off if you have multiple imgui contexts.
|
||||
ImVec2 MouseDelta; // Mouse delta. Note that this is zero if either current or previous position are invalid (-FLT_MAX,-FLT_MAX), so a disappearing/reappearing mouse won't have a huge delta.
|
||||
|
||||
// Legacy: before 1.87, we required backend to fill io.KeyMap[] (imgui->native map) during initialization and io.KeysDown[] (native indices) every frame.
|
||||
// This is still temporarily supported as a legacy feature. However the new preferred scheme is for backend to call io.AddKeyEvent().
|
||||
#ifndef IMGUI_DISABLE_OBSOLETE_KEYIO
|
||||
int KeyMap[ImGuiKey_COUNT]; // [LEGACY] Input: map of indices into the KeysDown[512] entries array which represent your "native" keyboard state. The first 512 are now unused and should be kept zero. Legacy backend will write into KeyMap[] using ImGuiKey_ indices which are always >512.
|
||||
bool KeysDown[512]; // [LEGACY] Input: Keyboard keys that are pressed (ideally left in the "native" order your engine has access to keyboard keys, so you can use your own defines/enums for keys).
|
||||
#endif
|
||||
|
||||
//------------------------------------------------------------------
|
||||
// [Internal] Dear ImGui will maintain those fields. Forward compatibility not guaranteed!
|
||||
//------------------------------------------------------------------
|
||||
|
||||
ImGuiKeyModFlags KeyMods; // Key mods flags (same as io.KeyCtrl/KeyShift/KeyAlt/KeySuper but merged into flags), updated by NewFrame()
|
||||
ImGuiKeyModFlags KeyModsPrev; // Key mods flags (from previous frame)
|
||||
ImGuiKeyData KeysData[ImGuiKey_KeyIndex_COUNT]; // Key state for all known keys.
|
||||
ImGuiKeyData KeysData[ImGuiKey_KeysData_SIZE]; // Key state for all known keys. Use IsKeyXXX() functions to access this.
|
||||
|
||||
bool WantCaptureMouseUnlessPopupClose; // Alternative to WantCaptureMouse: (WantCaptureMouse == true && WantCaptureMouseUnlessPopupClose == false) when a click over void is expected to close a popup.
|
||||
ImVec2 MousePosPrev; // Previous mouse position (note that MouseDelta is not necessary == MousePos-MousePosPrev, in case either position is invalid)
|
||||
@ -2076,6 +2069,7 @@ struct ImGuiIO
|
||||
float NavInputsDownDurationPrev[ImGuiNavInput_COUNT];
|
||||
float PenPressure; // Touch/Pen pressure (0.0f to 1.0f, should be >0.0f only when MouseDown[0] == true). Helper storage currently unused by Dear ImGui.
|
||||
bool AppFocusLost;
|
||||
ImS8 BackendUsingLegacyKeyArrays; // -1: unknown, 0: using AddKeyEvent(), 1: using legacy io.KeysDown[]
|
||||
ImWchar16 InputQueueSurrogate; // For AddInputCharacterUTF16()
|
||||
ImVector<ImWchar> InputQueueCharacters; // Queue of _characters_ input (obtained by platform backend). Fill using AddInputCharacter() helper.
|
||||
|
||||
@ -2973,13 +2967,18 @@ struct ImGuiPlatformImeData
|
||||
// Please keep your copy of dear imgui up to date! Occasionally set '#define IMGUI_DISABLE_OBSOLETE_FUNCTIONS' in imconfig.h to stay ahead.
|
||||
//-----------------------------------------------------------------------------
|
||||
|
||||
namespace ImGui
|
||||
{
|
||||
#ifndef IMGUI_DISABLE_OBSOLETE_KEYIO
|
||||
IMGUI_API int GetKeyIndex(ImGuiKey key); // map ImGuiKey_* values into legacy native key index. == io.KeyMap[key]
|
||||
#else
|
||||
static inline int GetKeyIndex(ImGuiKey key) { IM_ASSERT(key >= ImGuiKey_NamedKey_BEGIN && key < ImGuiKey_NamedKey_END && "ImGuiKey and native_index was merged together and native_index is disabled by IMGUI_DISABLE_OBSOLETE_KEYIO. Please switch to ImGuiKey."); return key; }
|
||||
#endif
|
||||
}
|
||||
|
||||
#ifndef IMGUI_DISABLE_OBSOLETE_FUNCTIONS
|
||||
namespace ImGui
|
||||
{
|
||||
// OBSOLETED in 1.XX (from YYYY)
|
||||
#ifdef IMGUI_DISABLE_OBSOLETE_KEYIO
|
||||
static inline int GetKeyIndex(ImGuiKey key) { IM_ASSERT(key >= ImGuiKey_NamedKey_BEGIN && key < ImGuiKey_NamedKey_END && "ImGuiKey and user_key_index was merged together and user_key_index is disabled by IMGUI_DISABLE_OBSOLETE_KEYIO. Please switch to ImGuiKey."); return key; }
|
||||
#endif
|
||||
// OBSOLETED in 1.86 (from November 2021)
|
||||
IMGUI_API void CalcListClipping(int items_count, float items_height, int* out_items_display_start, int* out_items_display_end); // Calculate coarse clipping for large list of evenly sized items. Prefer using ImGuiListClipper.
|
||||
// OBSOLETED in 1.85 (from August 2021)
|
||||
|
||||
Reference in New Issue
Block a user