Internals, Inputs: Comments, alignment.
This commit is contained in:
ocornut
parent
4c3eac2c10
commit
6d1a6f1c74
@ -5605,7 +5605,7 @@ Other Changes:
|
||||
VERSION 1.08 (2014-08-25)
|
||||
-----------------------------------------------------------------------
|
||||
|
||||
Decorated log and release notes: https://github.com/ocornut/imgui/releases/tag/v1.09
|
||||
Decorated log and release notes: https://github.com/ocornut/imgui/releases/tag/v1.08
|
||||
|
||||
- Fixed ImGuiTextFilter trimming of leading/trailing blanks.
|
||||
- Fixed file descriptor leak on LoadSettings() failure.
|
||||
|
||||
@ -1445,34 +1445,35 @@ struct ImGuiKeyOwnerData
|
||||
// Don't mistake with ImGuiInputTextFlags! (which is for ImGui::InputText() function)
|
||||
enum ImGuiInputFlags_
|
||||
{
|
||||
// Flags for IsKeyPressed(), IsKeyChordPressed(), IsMouseClicked(), Shortcut()
|
||||
ImGuiInputFlags_None = 0,
|
||||
|
||||
// Repeat mode
|
||||
// Flags for IsKeyPressed(), IsKeyChordPressed(), IsMouseClicked(), Shortcut()
|
||||
// - Repeat mode
|
||||
ImGuiInputFlags_Repeat = 1 << 0, // Enable repeat. Return true on successive repeats. Default for legacy IsKeyPressed(). NOT Default for legacy IsMouseClicked(). MUST BE == 1.
|
||||
ImGuiInputFlags_RepeatRateDefault = 1 << 1, // Repeat rate: Regular (default)
|
||||
ImGuiInputFlags_RepeatRateNavMove = 1 << 2, // Repeat rate: Fast
|
||||
ImGuiInputFlags_RepeatRateNavTweak = 1 << 3, // Repeat rate: Faster
|
||||
|
||||
// Repeat mode: Specify when repeating key pressed can be interrupted.
|
||||
// In theory ImGuiInputFlags_RepeatUntilOtherKeyPress may be a desirable default, but it would break too many behavior so everything is opt-in.
|
||||
// - Repeat mode: Specify when repeating key pressed can be interrupted.
|
||||
// - In theory ImGuiInputFlags_RepeatUntilOtherKeyPress may be a desirable default, but it would break too many behavior so everything is opt-in.
|
||||
ImGuiInputFlags_RepeatUntilRelease = 1 << 4, // Stop repeating when released (default for all functions except Shortcut). This only exists to allow overriding Shortcut() default behavior.
|
||||
ImGuiInputFlags_RepeatUntilKeyModsChange = 1 << 5, // Stop repeating when released OR if keyboard mods are changed (default for Shortcut)
|
||||
ImGuiInputFlags_RepeatUntilKeyModsChangeFromNone = 1 << 6, // Stop repeating when released OR if keyboard mods are leaving the None state. Allows going from Mod+Key to Key by releasing Mod.
|
||||
ImGuiInputFlags_RepeatUntilOtherKeyPress = 1 << 7, // Stop repeating when released OR if any other keyboard key is pressed during the repeat
|
||||
|
||||
// Flags for SetItemKeyOwner()
|
||||
// - Condition
|
||||
ImGuiInputFlags_CondHovered = 1 << 8, // Only set if item is hovered (default to both)
|
||||
ImGuiInputFlags_CondActive = 1 << 9, // Only set if item is active (default to both)
|
||||
ImGuiInputFlags_CondDefault_ = ImGuiInputFlags_CondHovered | ImGuiInputFlags_CondActive,
|
||||
|
||||
// Flags for SetKeyOwner(), SetItemKeyOwner()
|
||||
// Locking is useful to make input-owner-aware code steal keys from non-input-owner-aware code. If all code is input-owner-aware locking would never be necessary.
|
||||
// - Locking key away from non-input aware code. Locking is useful to make input-owner-aware code steal keys from non-input-owner-aware code. If all code is input-owner-aware locking would never be necessary.
|
||||
ImGuiInputFlags_LockThisFrame = 1 << 10, // Further accesses to key data will require EXPLICIT owner ID (ImGuiKeyOwner_Any/0 will NOT accepted for polling). Cleared at end of frame.
|
||||
ImGuiInputFlags_LockUntilRelease = 1 << 11, // Further accesses to key data will require EXPLICIT owner ID (ImGuiKeyOwner_Any/0 will NOT accepted for polling). Cleared when the key is released or at end of each frame if key is released.
|
||||
|
||||
// Routing policies for Shortcut() + low-level SetShortcutRouting()
|
||||
// - The general idea is that several callers register interest in a shortcut, and only one owner gets it.
|
||||
// Flags for Shortcut() and low-level SetShortcutRouting()
|
||||
// - Routing Policies
|
||||
// The general idea is that several callers register interest in a shortcut, and only one owner gets it.
|
||||
// Parent -> call Shortcut(Ctrl+S) // When Parent is focused, Parent gets the shortcut.
|
||||
// Child1 -> call Shortcut(Ctrl+S) // When Child1 is focused, Child1 gets the shortcut (Child1 overrides Parent shortcuts)
|
||||
// Child2 -> no call // When Child2 is focused, Parent gets the shortcut.
|
||||
@ -3251,12 +3252,12 @@ namespace ImGui
|
||||
// - SetItemKeyOwner() is a shortcut for common simple case. A custom widget will probably want to call SetKeyOwner() multiple times directly based on its interaction state.
|
||||
// - This is marked experimental because not all widgets are fully honoring the Set/Test idioms. We will need to move forward step by step.
|
||||
// Please open a GitHub Issue to submit your usage scenario or if there's a use case you need solved.
|
||||
IMGUI_API ImGuiID GetKeyOwner(ImGuiKey key);
|
||||
IMGUI_API void SetKeyOwner(ImGuiKey key, ImGuiID owner_id, ImGuiInputFlags flags = 0);
|
||||
IMGUI_API void SetKeyOwnersForKeyChord(ImGuiKeyChord key, ImGuiID owner_id, ImGuiInputFlags flags = 0);
|
||||
IMGUI_API void SetItemKeyOwner(ImGuiKey key, ImGuiInputFlags flags = 0); // Set key owner to last item if it is hovered or active. Equivalent to 'if (IsItemHovered() || IsItemActive()) { SetKeyOwner(key, GetItemID());'.
|
||||
IMGUI_API bool TestKeyOwner(ImGuiKey key, ImGuiID owner_id); // Test that key is either not owned, either owned by 'owner_id'
|
||||
inline ImGuiKeyOwnerData* GetKeyOwnerData(ImGuiContext* ctx, ImGuiKey key) { if (key & ImGuiMod_Mask_) key = ConvertSingleModFlagToKey(key); IM_ASSERT(IsNamedKey(key)); return &ctx->KeysOwnerData[key - ImGuiKey_NamedKey_BEGIN]; }
|
||||
IMGUI_API ImGuiID GetKeyOwner(ImGuiKey key);
|
||||
IMGUI_API void SetKeyOwner(ImGuiKey key, ImGuiID owner_id, ImGuiInputFlags flags = 0);
|
||||
IMGUI_API void SetKeyOwnersForKeyChord(ImGuiKeyChord key, ImGuiID owner_id, ImGuiInputFlags flags = 0);
|
||||
IMGUI_API void SetItemKeyOwner(ImGuiKey key, ImGuiInputFlags flags = 0); // Set key owner to last item if it is hovered or active. Equivalent to 'if (IsItemHovered() || IsItemActive()) { SetKeyOwner(key, GetItemID());'.
|
||||
IMGUI_API bool TestKeyOwner(ImGuiKey key, ImGuiID owner_id); // Test that key is either not owned, either owned by 'owner_id'
|
||||
inline ImGuiKeyOwnerData* GetKeyOwnerData(ImGuiContext* ctx, ImGuiKey key) { if (key & ImGuiMod_Mask_) key = ConvertSingleModFlagToKey(key); IM_ASSERT(IsNamedKey(key)); return &ctx->KeysOwnerData[key - ImGuiKey_NamedKey_BEGIN]; }
|
||||
|
||||
// [EXPERIMENTAL] High-Level: Input Access functions w/ support for Key/Input Ownership
|
||||
// - Important: legacy IsKeyPressed(ImGuiKey, bool repeat=true) _DEFAULTS_ to repeat, new IsKeyPressed() requires _EXPLICIT_ ImGuiInputFlags_Repeat flag.
|
||||
@ -3264,32 +3265,34 @@ namespace ImGui
|
||||
// - Specifying a value for 'ImGuiID owner' will test that EITHER the key is NOT owned (UNLESS locked), EITHER the key is owned by 'owner'.
|
||||
// Legacy functions use ImGuiKeyOwner_Any meaning that they typically ignore ownership, unless a call to SetKeyOwner() explicitly used ImGuiInputFlags_LockThisFrame or ImGuiInputFlags_LockUntilRelease.
|
||||
// - Binding generators may want to ignore those for now, or suffix them with Ex() until we decide if this gets moved into public API.
|
||||
IMGUI_API bool IsKeyDown(ImGuiKey key, ImGuiID owner_id);
|
||||
IMGUI_API bool IsKeyPressed(ImGuiKey key, ImGuiID owner_id, ImGuiInputFlags flags = 0); // Important: when transitioning from old to new IsKeyPressed(): old API has "bool repeat = true", so would default to repeat. New API requiress explicit ImGuiInputFlags_Repeat.
|
||||
IMGUI_API bool IsKeyReleased(ImGuiKey key, ImGuiID owner_id);
|
||||
IMGUI_API bool IsMouseDown(ImGuiMouseButton button, ImGuiID owner_id);
|
||||
IMGUI_API bool IsMouseClicked(ImGuiMouseButton button, ImGuiID owner_id, ImGuiInputFlags flags = 0);
|
||||
IMGUI_API bool IsMouseReleased(ImGuiMouseButton button, ImGuiID owner_id);
|
||||
IMGUI_API bool IsMouseDoubleClicked(ImGuiMouseButton button, ImGuiID owner_id);
|
||||
IMGUI_API bool IsKeyDown(ImGuiKey key, ImGuiID owner_id);
|
||||
IMGUI_API bool IsKeyPressed(ImGuiKey key, ImGuiID owner_id, ImGuiInputFlags flags = 0); // Important: when transitioning from old to new IsKeyPressed(): old API has "bool repeat = true", so would default to repeat. New API requiress explicit ImGuiInputFlags_Repeat.
|
||||
IMGUI_API bool IsKeyReleased(ImGuiKey key, ImGuiID owner_id);
|
||||
IMGUI_API bool IsKeyChordPressed(ImGuiKeyChord key_chord, ImGuiID owner_id, ImGuiInputFlags flags = 0);
|
||||
IMGUI_API bool IsMouseDown(ImGuiMouseButton button, ImGuiID owner_id);
|
||||
IMGUI_API bool IsMouseClicked(ImGuiMouseButton button, ImGuiID owner_id, ImGuiInputFlags flags = 0);
|
||||
IMGUI_API bool IsMouseReleased(ImGuiMouseButton button, ImGuiID owner_id);
|
||||
IMGUI_API bool IsMouseDoubleClicked(ImGuiMouseButton button, ImGuiID owner_id);
|
||||
|
||||
// [EXPERIMENTAL] Shortcut Routing
|
||||
// - ImGuiKeyChord = a ImGuiKey optionally OR-red with ImGuiMod_Alt/ImGuiMod_Ctrl/ImGuiMod_Shift/ImGuiMod_Super.
|
||||
// ImGuiKey_C (accepted by functions taking ImGuiKey or ImGuiKeyChord)
|
||||
// ImGuiKey_C | ImGuiMod_Ctrl (accepted by functions taking ImGuiKeyChord)
|
||||
// ONLY ImGuiMod_XXX values are legal to 'OR' with an ImGuiKey. You CANNOT 'OR' two ImGuiKey values.
|
||||
// - When using one of the routing flags (e.g. ImGuiInputFlags_RouteFocused): routes requested ahead of time given a chord (key + modifiers) and a routing policy.
|
||||
// - Routes are resolved during NewFrame(): if keyboard modifiers are matching current ones: SetKeyOwner() is called + route is granted for the frame.
|
||||
// - Route is granted to a single owner. When multiple requests are made we have policies to select the winning route.
|
||||
// - Multiple read sites may use the same owner id and will all get the granted route.
|
||||
// - For routing: when owner_id is 0 we use the current Focus Scope ID as a default owner in order to identify our location.
|
||||
// - When using one of the routing option, e.g. ImGuiInputFlags_RouteFocused:
|
||||
// - Routes are requested given a chord (key + modifiers) and a routing policy.
|
||||
// - Routes are resolved during NewFrame(): if keyboard modifiers are matching current ones: SetKeyOwner() is called + route is granted for the frame.
|
||||
// - One route may be granted to a single owner. When multiple requests are made we have policies to select the winning route (e.g. deep most window).
|
||||
// - Multiple read sites may use the same owner id can all access the granted route.
|
||||
// - When owner_id is 0 we use the current Focus Scope ID as a owner ID in order to identify our location.
|
||||
// - TL;DR;
|
||||
// - IsKeyChordPressed() compares mods + call IsKeyPressed() -> function has no side-effect.
|
||||
// - Shortcut() submits a route then if currently can be routed calls IsKeyChordPressed() -> function has (desirable) side-effects.
|
||||
IMGUI_API bool IsKeyChordPressed(ImGuiKeyChord key_chord, ImGuiID owner_id, ImGuiInputFlags flags = 0);
|
||||
IMGUI_API void SetNextItemShortcut(ImGuiKeyChord key_chord);
|
||||
IMGUI_API bool Shortcut(ImGuiKeyChord key_chord, ImGuiID owner_id = 0, ImGuiInputFlags flags = 0);
|
||||
IMGUI_API bool SetShortcutRouting(ImGuiKeyChord key_chord, ImGuiID owner_id, ImGuiInputFlags flags = 0); // owner_id needs to be explicit and cannot be 0
|
||||
IMGUI_API bool TestShortcutRouting(ImGuiKeyChord key_chord, ImGuiID owner_id);
|
||||
// - Use Tools->Metrics/Debugger->Inputs to view input routes.
|
||||
IMGUI_API void SetNextItemShortcut(ImGuiKeyChord key_chord);
|
||||
IMGUI_API bool Shortcut(ImGuiKeyChord key_chord, ImGuiID owner_id = 0, ImGuiInputFlags flags = 0);
|
||||
IMGUI_API bool SetShortcutRouting(ImGuiKeyChord key_chord, ImGuiID owner_id, ImGuiInputFlags flags = 0); // owner_id needs to be explicit and cannot be 0
|
||||
IMGUI_API bool TestShortcutRouting(ImGuiKeyChord key_chord, ImGuiID owner_id);
|
||||
IMGUI_API ImGuiKeyRoutingData* GetShortcutRoutingData(ImGuiKeyChord key_chord);
|
||||
|
||||
// [EXPERIMENTAL] Focus Scope
|
||||
|
||||
Loading…
Reference in New Issue
Block a user