Nav: Comments, guides.

This commit is contained in:
omar 2018-02-06 18:26:42 +01:00
parent ad09396672
commit ed4bbc4fd4
3 changed files with 28 additions and 27 deletions

View File

@ -238,6 +238,7 @@ It's mostly a bunch of personal notes, probably incomplete. Feel free to query i
- nav: integrate/design keyboard controls.
- nav: simulate right-click or context activation? (SHIFT+F10)
- nav: tabs should go through most/all widgets (in submission order?).
- nav: when CTRL-Tab/windowing is active, the HoveredWindow detection doesn't take account of the window display re-ordering.
- nav: cannot access menubar of a flattened child window with Alt/menu key (not a very common use case..).
- nav: esc/enter default behavior for popups, e.g. be able to mark an "ok" or "cancel" button that would get triggered by those keys.
- nav: when activating a button that changes label (without a static ID) or disappear, can we somehow automatically recover into a nearest highlight item?

View File

@ -80,7 +80,8 @@
- ESCAPE to revert text to its original value.
- You can apply arithmetic operators +,*,/ on numerical values. Use +- to subtract (because - would set a negative value!)
- Controls are automatically adjusted for OSX to match standard OSX text editing operations.
- Gamepad/keyboard navigation are in beta-phase, see Programmer Guide below.
- Gamepad navigation: see suggested mappings in imgui.h ImGuiNavInput_
- Keyboard navigation: see suggested mappings in imgui.h ImGuiNavInput_
PROGRAMMER GUIDE
@ -211,8 +212,7 @@
USING GAMEPAD/KEYBOARD NAVIGATION [BETA]
- Gamepad/keyboard navigation support is now available. Your feedback and bug reports are greatly welcome!
- See https://github.com/ocornut/imgui/issues/787 discussion thread and ask questions there.
- Ask questions and report issues at https://github.com/ocornut/imgui/issues/787.
- The initial focus was to support game controllers, but keyboard is becoming increasingly and decently usable.
- Your inputs are passed to imgui by filling the io.NavInputs[] array. See 'enum ImGuiNavInput_' in imgui.h for a description of available inputs.
- Please refer to the examples/ application for suggested keyboard and gamepad mapping.
@ -221,12 +221,12 @@
- The ImGuiNavFlags_EnableGamepad and ImGuiNavFlags_EnableKeyboard flags of io.NavFlags are only here to instruct your binding whether to find inputs.
- For gamepad use, the easiest approach is to go all-or-nothing, with a buttons combo that toggle your inputs between imgui and your game/application.
Sharing inputs in a more advanced or granular way between imgui and your game/application may be tricky and requires further work on imgui.
When keyboard navigation is active (io.NavActive + NavFlags_EnableKeyboard), the io.WantCaptureKeyboard is set.
For more advanced uses, you may want to use:
- io.NavActive: true when a window is focused and it doesn't have the ImGuiWindowFlags_NoNavInputs flag set.
- io.NavVisible: true when the navigation cursor is visible (and usually goes false when mouse is used).
- query focus information with e.g. IsWindowFocused(), IsItemFocused() etc. functions.
The reality is more complex than what those flags can express. Please discuss your issues and usage scenario in the thread above!
As we head toward more keyboard-oriented development this aspect will need to be improved.
Please reach out if you think the game vs navigation input sharing could be improved.
- On a TV/console system where readability may be lower or mouse inputs may be awkward, you may want to set the ImGuiNavFlags_MoveMouse flag in io.NavFlags.
Enabling ImGuiNavFlags_MoveMouse instructs dear imgui to move your mouse cursor along with navigation movement.
When enabled, the NewFrame() functions may alter 'io.MousePos' and set 'io.WantMoveMouse' to notify you that it did so.
@ -2675,7 +2675,7 @@ static ImVec2 NavCalcPreferredMousePos()
const ImRect& rect_rel = window->NavRectRel[g.NavLayer];
ImVec2 pos = g.NavWindow->Pos + ImVec2(rect_rel.Min.x + ImMin(g.Style.FramePadding.x*4, rect_rel.GetWidth()), rect_rel.Max.y - ImMin(g.Style.FramePadding.y, rect_rel.GetHeight()));
ImRect visible_rect = GetViewportRect();
return ImFloor(ImClamp(pos, visible_rect.Min, visible_rect.Max)); // ImFloor() is important because non-integer mouse position application in backend might be lossy and result in undesirable non-zero delta.
return ImFloor(ImClamp(pos, visible_rect.Min, visible_rect.Max)); // ImFloor() is important because non-integer mouse position application in back-end might be lossy and result in undesirable non-zero delta.
}
static int FindWindowIndex(ImGuiWindow* window) // FIXME-OPT O(N)
@ -2823,7 +2823,7 @@ static void ImGui::NavUpdateWindowing()
}
// Keyboard: Press and Release ALT to toggle menu layer
// FIXME: We lack an explicit IO variable for "is the imgui window focused", so compare mouse validity to detect the common case of backend clearing releases all keys on ALT-TAB
// FIXME: We lack an explicit IO variable for "is the imgui window focused", so compare mouse validity to detect the common case of back-end clearing releases all keys on ALT-TAB
if ((g.ActiveId == 0 || g.ActiveIdAllowOverlap) && IsNavInputPressed(ImGuiNavInput_KeyMenu, ImGuiInputReadMode_Released))
if (IsMousePosValid(&g.IO.MousePos) == IsMousePosValid(&g.IO.MousePosPrev))
apply_toggle_layer = true;
@ -4415,7 +4415,7 @@ int ImGui::GetKeyIndex(ImGuiKey imgui_key)
return GImGui->IO.KeyMap[imgui_key];
}
// Note that imgui doesn't know the semantic of each entry of io.KeyDown[]. Use your own indices/enums according to how your backend/engine stored them into KeyDown[]!
// Note that imgui doesn't know the semantic of each entry of io.KeyDown[]. Use your own indices/enums according to how your back-end/engine stored them into KeyDown[]!
bool ImGui::IsKeyDown(int user_key_index)
{
if (user_key_index < 0) return false;
@ -4536,7 +4536,7 @@ bool ImGui::IsMousePosValid(const ImVec2* mouse_pos)
return mouse_pos->x >= MOUSE_INVALID && mouse_pos->y >= MOUSE_INVALID;
}
// NB: This is only valid if IsMousePosValid(). Backends in theory should always keep mouse position valid when dragging even outside the client window.
// NB: This is only valid if IsMousePosValid(). Back-ends in theory should always keep mouse position valid when dragging even outside the client window.
ImVec2 ImGui::GetMouseDragDelta(int button, float lock_threshold)
{
ImGuiContext& g = *GImGui;

36
imgui.h
View File

@ -710,27 +710,27 @@ enum ImGuiKey_
enum ImGuiNavInput_
{
// Gamepad Mapping
ImGuiNavInput_PadActivate, // press button, tweak value // e.g. Circle button
ImGuiNavInput_PadCancel, // close menu/popup/child, lose selection // e.g. Cross button
ImGuiNavInput_PadInput, // text input // e.g. Triangle button
ImGuiNavInput_PadMenu, // toggle menu, hold to: focus, move, resize // e.g. Square button
ImGuiNavInput_PadDpadLeft, // move left, resize window (with PadMenu) // e.g. D-pad directions
ImGuiNavInput_PadDpadRight, // move right
ImGuiNavInput_PadDpadUp, // move up
ImGuiNavInput_PadDpadDown, // move down
ImGuiNavInput_PadLStickLeft, // scroll up, move window (with PadMenu) // e.g. left stick directions (analog)
ImGuiNavInput_PadLStickRight, // scroll right
ImGuiNavInput_PadLStickUp, // scroll up
ImGuiNavInput_PadLStickDown, // scroll down
ImGuiNavInput_PadFocusPrev, // next window (with PadMenu) // e.g. L-trigger
ImGuiNavInput_PadFocusNext, // prev window (with PadMenu) // e.g. R-trigger
ImGuiNavInput_PadTweakSlow, // slower tweaks // e.g. L-trigger, analog
ImGuiNavInput_PadTweakFast, // faster tweaks // e.g. R-trigger, analog
ImGuiNavInput_PadActivate, // activate / open / toggle / tweak value // e.g. Circle (PS4), A (Xbox), B (Switch)
ImGuiNavInput_PadCancel, // cancel / close / exit // e.g. Cross (PS4), B (Xbox), A (Switch)
ImGuiNavInput_PadInput, // text input / on-screen keyboard // e.g. Triang.(PS4), Y (Xbox), X (Switch)
ImGuiNavInput_PadMenu, // tap: toggle menu / hold: focus, move, resize // e.g. Square (PS4), X (Xbox), Y (Switch)
ImGuiNavInput_PadDpadLeft, // move / tweak / resize window (w/ PadMenu) // e.g. D-pad Left/Right/Up/Down
ImGuiNavInput_PadDpadRight, //
ImGuiNavInput_PadDpadUp, //
ImGuiNavInput_PadDpadDown, //
ImGuiNavInput_PadLStickLeft, // scroll / move window (w/ PadMenu) // e.g. Left Analog Stick Left/Right/Up/Down
ImGuiNavInput_PadLStickRight, //
ImGuiNavInput_PadLStickUp, //
ImGuiNavInput_PadLStickDown, //
ImGuiNavInput_PadFocusPrev, // next window (w/ PadMenu) // e.g. L1 (PS4), LB (Xbox), L (Switch)
ImGuiNavInput_PadFocusNext, // prev window (w/ PadMenu) // e.g. R1 (PS4), RB (Xbox), R (Switch)
ImGuiNavInput_PadTweakSlow, // slower tweaks // e.g. L2 (PS4), LT (Xbox), ZL (Switch), Analog
ImGuiNavInput_PadTweakFast, // faster tweaks // e.g. R2 (PS4), RT (Xbox), ZR (Switch), Analog
// Keyboard Mapping
// [BETA] To use keyboard control you currently need to map keys to those gamepad inputs: PadActivate (Enter), PadCancel (Escape), PadInput (Enter).
// Will add specialized keyboard mappings as we add features and clarify the input interface.
ImGuiNavInput_KeyMenu, // toggle menu // e.g. ALT
ImGuiNavInput_KeyLeft, // move left // e.g. Arrow keys
ImGuiNavInput_KeyMenu, // toggle menu // e.g. Alt
ImGuiNavInput_KeyLeft, // move left // e.g. Arrow keys
ImGuiNavInput_KeyRight, // move right
ImGuiNavInput_KeyUp, // move up
ImGuiNavInput_KeyDown, // move down