"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "docs/FAQ.md" between
imgui-1.86.tar.gz and imgui-1.87.tar.gz

About: Dear ImGui is a bloat-free Graphical User Interface for C++ with minimal dependencies.

FAQ.md  (imgui-1.86):FAQ.md  (imgui-1.87)
skipping to change at line 115 skipping to change at line 115
- When `io.WantCaptureKeyboard` is set, you need to discard/hide the keyboard in puts from your underlying application. - When `io.WantCaptureKeyboard` is set, you need to discard/hide the keyboard in puts from your underlying application.
- When `io.WantTextInput` is set, you can notify your OS/engine to popup an on-s creen keyboard, if available (e.g. on a mobile phone, or console OS). - When `io.WantTextInput` is set, you can notify your OS/engine to popup an on-s creen keyboard, if available (e.g. on a mobile phone, or console OS).
Important: you should always pass your mouse/keyboard inputs to Dear ImGui, rega rdless of the value `io.WantCaptureMouse`/`io.WantCaptureKeyboard`. This is beca use e.g. we need to detect that you clicked in the void to unfocus its own windo ws, and other reasons. Important: you should always pass your mouse/keyboard inputs to Dear ImGui, rega rdless of the value `io.WantCaptureMouse`/`io.WantCaptureKeyboard`. This is beca use e.g. we need to detect that you clicked in the void to unfocus its own windo ws, and other reasons.
```cpp ```cpp
void MyLowLevelMouseButtonHandler(int button, bool down) void MyLowLevelMouseButtonHandler(int button, bool down)
{ {
// (1) ALWAYS forward mouse data to ImGui! This is automatic with default ba ckends. With your own backend: // (1) ALWAYS forward mouse data to ImGui! This is automatic with default ba ckends. With your own backend:
ImGuiIO& io = ImGui::GetIO(); ImGuiIO& io = ImGui::GetIO();
io.MouseDown[button] = down; io.AddMouseButtonEvent(button, down);
// (2) ONLY forward mouse data to your underlying app/game. // (2) ONLY forward mouse data to your underlying app/game.
if (!io.WantCaptureMouse) if (!io.WantCaptureMouse)
my_game->HandleMouseData(...); my_game->HandleMouseData(...);
} }
``` ```
**Note:** The `io.WantCaptureMouse` is more correct that any manual attempt to " check if the mouse is hovering a window" (don't do that!). It handle mouse dragg ing correctly (both dragging that started over your application or over a Dear I mGui window) and handle e.g. popup and modal windows blocking inputs. **Note:** The `io.WantCaptureMouse` is more correct that any manual attempt to " check if the mouse is hovering a window" (don't do that!). It handle mouse dragg ing correctly (both dragging that started over your application or over a Dear I mGui window) and handle e.g. popup and modal windows blocking inputs.
**Note:** Those flags are updated by `ImGui::NewFrame()`. However it is generall y more correct and easier that you poll flags from the previous frame, then subm it your inputs, then call `NewFrame()`. If you attempt to do the opposite (which is generally harder) you are likely going to submit your inputs after `NewFrame ()`, and therefore too late. **Note:** Those flags are updated by `ImGui::NewFrame()`. However it is generall y more correct and easier that you poll flags from the previous frame, then subm it your inputs, then call `NewFrame()`. If you attempt to do the opposite (which is generally harder) you are likely going to submit your inputs after `NewFrame ()`, and therefore too late.
skipping to change at line 139 skipping to change at line 139
**Note:** Text input widget releases focus on the "KeyDown" event of the Return key, so the subsequent "KeyUp" event that your application receive will typicall y have `io.WantCaptureKeyboard == false`. Depending on your application logic it may or not be inconvenient to receive that KeyUp event. You might want to track which key-downs were targeted for Dear ImGui, e.g. with an array of bool, and f ilter out the corresponding key-ups.) **Note:** Text input widget releases focus on the "KeyDown" event of the Return key, so the subsequent "KeyUp" event that your application receive will typicall y have `io.WantCaptureKeyboard == false`. Depending on your application logic it may or not be inconvenient to receive that KeyUp event. You might want to track which key-downs were targeted for Dear ImGui, e.g. with an array of bool, and f ilter out the corresponding key-ups.)
##### [Return to Index](#index) ##### [Return to Index](#index)
--- ---
### Q: How can I enable keyboard or gamepad controls? ### Q: How can I enable keyboard or gamepad controls?
- The gamepad/keyboard navigation is fairly functional and keeps being improved. The initial focus was to support game controllers, but keyboard is becoming inc reasingly and decently usable. Gamepad support is particularly useful to use Dea r ImGui on a game console (e.g. PS4, Switch, XB1) without a mouse connected! - The gamepad/keyboard navigation is fairly functional and keeps being improved. The initial focus was to support game controllers, but keyboard is becoming inc reasingly and decently usable. Gamepad support is particularly useful to use Dea r ImGui on a game console (e.g. PS4, Switch, XB1) without a mouse connected!
- Keyboard: set `io.ConfigFlags |= ImGuiConfigFlags_NavEnableKeyboard` to enable . - Keyboard: set `io.ConfigFlags |= ImGuiConfigFlags_NavEnableKeyboard` to enable .
- Gamepad: set `io.ConfigFlags |= ImGuiConfigFlags_NavEnableGamepad` to enable ( with a supporting backend). - Gamepad: set `io.ConfigFlags |= ImGuiConfigFlags_NavEnableGamepad` to enable ( with a supporting backend).
- See [Control Sheets for Gamepads](http://www.dearimgui.org/controls_sheets) (r eference PNG/PSD for for PS4, XB1, Switch gamepads). - See [Control Sheets for Gamepads](http://www.dearimgui.org/controls_sheets) (r eference PNG/PSD for PS4, XB1, Switch gamepads).
- See `USING GAMEPAD/KEYBOARD NAVIGATION CONTROLS` section of [imgui.cpp](https: //github.com/ocornut/imgui/blob/master/imgui.cpp) for more details. - See `USING GAMEPAD/KEYBOARD NAVIGATION CONTROLS` section of [imgui.cpp](https: //github.com/ocornut/imgui/blob/master/imgui.cpp) for more details.
##### [Return to Index](#index) ##### [Return to Index](#index)
--- ---
### Q: How can I use this on a machine without mouse, keyboard or screen? (input share, remote display) ### Q: How can I use this on a machine without mouse, keyboard or screen? (input share, remote display)
- You can share your computer mouse seamlessly with your console/tablet/phone us ing solutions such as [Synergy](https://symless.com/synergy) - You can share your computer mouse seamlessly with your console/tablet/phone us ing solutions such as [Synergy](https://symless.com/synergy)
This is the preferred solution for developer productivity. This is the preferred solution for developer productivity.
In particular, the [micro-synergy-client repository](https://github.com/symless/ micro-synergy-client) has simple In particular, the [micro-synergy-client repository](https://github.com/symless/ micro-synergy-client) has simple
skipping to change at line 463 skipping to change at line 463
// Get the current ImGui cursor position // Get the current ImGui cursor position
ImVec2 p = ImGui::GetCursorScreenPos(); ImVec2 p = ImGui::GetCursorScreenPos();
// Draw a red circle // Draw a red circle
draw_list->AddCircleFilled(ImVec2(p.x + 50, p.y + 50), 30.0f, IM_COL32(255, 0, 0 , 255), 16); draw_list->AddCircleFilled(ImVec2(p.x + 50, p.y + 50), 30.0f, IM_COL32(255, 0, 0 , 255), 16);
// Draw a 3 pixel thick yellow line // Draw a 3 pixel thick yellow line
draw_list->AddLine(ImVec2(p.x, p.y), ImVec2(p.x + 100.0f, p.y + 100.0f), IM_COL3 2(255, 255, 0, 255), 3.0f); draw_list->AddLine(ImVec2(p.x, p.y), ImVec2(p.x + 100.0f, p.y + 100.0f), IM_COL3 2(255, 255, 0, 255), 3.0f);
// Advance the ImGui cursor to claim space in the window (otherwise the window w ill appears small and needs to be resized) // Advance the ImGui cursor to claim space in the window (otherwise the window w ill appear small and needs to be resized)
ImGui::Dummy(ImVec2(200, 200)); ImGui::Dummy(ImVec2(200, 200));
ImGui::End(); ImGui::End();
``` ```
![ImDrawList usage](https://raw.githubusercontent.com/wiki/ocornut/imgui/tutoria ls/CustomRendering01.png) ![ImDrawList usage](https://raw.githubusercontent.com/wiki/ocornut/imgui/tutoria ls/CustomRendering01.png)
- Refer to "Demo > Examples > Custom Rendering" in the demo window and read the code of `ShowExampleAppCustomRendering()` in `imgui_demo.cpp` from more examples . - Refer to "Demo > Examples > Custom Rendering" in the demo window and read the code of `ShowExampleAppCustomRendering()` in `imgui_demo.cpp` from more examples .
- To generate colors: you can use the macro `IM_COL32(255,255,255,255)` to gener ate them at compile time, or use `ImGui::GetColorU32(IM_COL32(255,255,255,255))` or `ImGui::GetColorU32(ImVec4(1.0f,1.0f,1.0f,1.0f))` to generate a color that i s multiplied by the current value of `style.Alpha`. - To generate colors: you can use the macro `IM_COL32(255,255,255,255)` to gener ate them at compile time, or use `ImGui::GetColorU32(IM_COL32(255,255,255,255))` or `ImGui::GetColorU32(ImVec4(1.0f,1.0f,1.0f,1.0f))` to generate a color that i s multiplied by the current value of `style.Alpha`.
- Math operators: if you have setup `IM_VEC2_CLASS_EXTRA` in `imconfig.h` to bin d your own math types, you can use your own math types and their natural operato rs instead of ImVec2. ImVec2 by default doesn't export any math operators in the public API. You may use `#define IMGUI_DEFINE_MATH_OPERATORS` `#include "imgui_ internal.h"` to use the internally defined math operators, but instead prefer us ing your own math library and set it up in `imconfig.h`. - Math operators: if you have setup `IM_VEC2_CLASS_EXTRA` in `imconfig.h` to bin d your own math types, you can use your own math types and their natural operato rs instead of ImVec2. ImVec2 by default doesn't export any math operators in the public API. You may use `#define IMGUI_DEFINE_MATH_OPERATORS` `#include "imgui_ internal.h"` to use the internally defined math operators, but instead prefer us ing your own math library and set it up in `imconfig.h`.
- You can use `ImGui::GetBackgroundDrawList()` or `ImGui::GetForegroundDrawList( )` to access draw lists which will be displayed behind and over every other dear imgui windows (one bg/fg drawlist per viewport). This is very convenient if you need to quickly display something on the screen that is not associated to a dea r imgui window. - You can use `ImGui::GetBackgroundDrawList()` or `ImGui::GetForegroundDrawList( )` to access draw lists which will be displayed behind and over every other dear imgui windows (one bg/fg drawlist per viewport). This is very convenient if you need to quickly display something on the screen that is not associated to a dea r imgui window.
skipping to change at line 607 skipping to change at line 607
All your strings needs to use UTF-8 encoding. In C++11 you can encode a string l iteral in UTF-8 All your strings needs to use UTF-8 encoding. In C++11 you can encode a string l iteral in UTF-8
by using the u8"hello" syntax. Specifying literal in your source code using a lo cal code page by using the u8"hello" syntax. Specifying literal in your source code using a lo cal code page
(such as CP-923 for Japanese or CP-1251 for Cyrillic) will NOT work! (such as CP-923 for Japanese or CP-1251 for Cyrillic) will NOT work!
Otherwise you can convert yourself to UTF-8 or load text data from file already saved as UTF-8. Otherwise you can convert yourself to UTF-8 or load text data from file already saved as UTF-8.
Text input: it is up to your application to pass the right character code by cal ling `io.AddInputCharacter()`. Text input: it is up to your application to pass the right character code by cal ling `io.AddInputCharacter()`.
The applications in examples/ are doing that. The applications in examples/ are doing that.
Windows: you can use the WM_CHAR or WM_UNICHAR or WM_IME_CHAR message (depending if your app is built using Unicode or MultiByte mode). Windows: you can use the WM_CHAR or WM_UNICHAR or WM_IME_CHAR message (depending if your app is built using Unicode or MultiByte mode).
You may also use MultiByteToWideChar() or ToUnicode() to retrieve Unicode codepo ints from MultiByte characters or keyboard state. You may also use MultiByteToWideChar() or ToUnicode() to retrieve Unicode codepo ints from MultiByte characters or keyboard state.
Windows: if your language is relying on an Input Method Editor (IME), you copy t Windows: if your language is relying on an Input Method Editor (IME), you can wr
he HWND of your window to io.ImeWindowHandle in order for ite your HWND to ImGui::GetMainViewport()->PlatformHandleRaw
the default implementation of io.ImeSetInputScreenPosFn() to set your Microsoft in order for the default the default implementation of io.SetPlatformImeDataFn()
IME position correctly. to set your Microsoft IME position correctly.
##### [Return to Index](#index) ##### [Return to Index](#index)
--- ---
# Q&A: Concerns # Q&A: Concerns
### Q: Who uses Dear ImGui? ### Q: Who uses Dear ImGui?
You may take a look at: You may take a look at:
skipping to change at line 654 skipping to change at line 654
A reasonably skinned application may look like (screenshot from [#2529](https:// github.com/ocornut/imgui/issues/2529#issuecomment-524281119)) A reasonably skinned application may look like (screenshot from [#2529](https:// github.com/ocornut/imgui/issues/2529#issuecomment-524281119))
![minipars](https://user-images.githubusercontent.com/314805/63589441-d9794f00-c 5b1-11e9-8d96-cfc1b93702f7.png) ![minipars](https://user-images.githubusercontent.com/314805/63589441-d9794f00-c 5b1-11e9-8d96-cfc1b93702f7.png)
##### [Return to Index](#index) ##### [Return to Index](#index)
--- ---
### Q: Why using C++ (as opposed to C)? ### Q: Why using C++ (as opposed to C)?
Dear ImGui takes advantage of a few C++ languages features for convenience but n othing anywhere Boost insanity/quagmire. Dear ImGui does NOT require C++11 so it can be used with most old C++ compilers. Dear ImGui doesn't use any C++ header file. Language-wise, function overloading and default parameters are used to mak e the API easier to use and code more terse. Doing so I believe the API is sitti ng on a sweet spot and giving up on those features would make the API more cumbe rsome. Other features such as namespace, constructors and templates (in the case of the ImVector<> class) are also relied on as a convenience. Dear ImGui takes advantage of a few C++ languages features for convenience but n othing anywhere Boost insanity/quagmire. Dear ImGui doesn't use any C++ header f ile. Dear ImGui uses a very small subset of C++11 features. In particular, funct ion overloading and default parameters are used to make the API easier to use an d code more terse. Doing so I believe the API is sitting on a sweet spot and giv ing up on those features would make the API more cumbersome. Other features such as namespace, constructors and templates (in the case of the ImVector<> class) are also relied on as a convenience.
There is an auto-generated [c-api for Dear ImGui (cimgui)](https://github.com/ci mgui/cimgui) by Sonoro1234 and Stephan Dilly. It is designed for creating bindin gs to other languages. If possible, I would suggest using your target language f unctionalities to try replicating the function overloading and default parameter s used in C++ else the API may be harder to use. Also see [Bindings](https://git hub.com/ocornut/imgui/wiki/Bindings) for various third-party bindings. There is an auto-generated [c-api for Dear ImGui (cimgui)](https://github.com/ci mgui/cimgui) by Sonoro1234 and Stephan Dilly. It is designed for creating bindin gs to other languages. If possible, I would suggest using your target language f unctionalities to try replicating the function overloading and default parameter s used in C++ else the API may be harder to use. Also see [Bindings](https://git hub.com/ocornut/imgui/wiki/Bindings) for various third-party bindings.
##### [Return to Index](#index) ##### [Return to Index](#index)
--- ---
# Q&A: Community # Q&A: Community
### Q: How can I help? ### Q: How can I help?
 End of changes. 5 change blocks. 
8 lines changed or deleted 8 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)