mirror of
https://github.com/ocornut/imgui.git
synced 2024-11-28 17:40:56 +01:00
Merge various documentation tweaks, comments, todos from the Navigation Branch to reduce drift a little
This commit is contained in:
omar
parent
a1bcc8392e
commit
b5ad88627d
72
imgui.cpp
72
imgui.cpp
@ -16,6 +16,8 @@
|
||||
- MISSION STATEMENT
|
||||
- END-USER GUIDE
|
||||
- PROGRAMMER GUIDE (read me!)
|
||||
- Read first
|
||||
- Getting started with integrating imgui in your code/engine
|
||||
- API BREAKING CHANGES (read me when you update!)
|
||||
- FREQUENTLY ASKED QUESTIONS (FAQ), TIPS
|
||||
- How can I help?
|
||||
@ -50,22 +52,21 @@
|
||||
Designed for developers and content-creators, not the typical end-user! Some of the weaknesses includes:
|
||||
- doesn't look fancy, doesn't animate
|
||||
- limited layout features, intricate layouts are typically crafted in code
|
||||
- occasionally uses statically sized buffers for string manipulations - won't crash, but some very long pieces of text may be clipped. functions like ImGui::TextUnformatted() don't have such restriction.
|
||||
|
||||
|
||||
END-USER GUIDE
|
||||
==============
|
||||
|
||||
- double-click title bar to collapse window
|
||||
- click upper right corner to close a window, available when 'bool* p_open' is passed to ImGui::Begin()
|
||||
- click and drag on lower right corner to resize window
|
||||
- click and drag on any empty space to move window
|
||||
- double-click/double-tap on lower right corner grip to auto-fit to content
|
||||
- Double-click title bar to collapse window
|
||||
- Click upper right corner to close a window, available when 'bool* p_open' is passed to ImGui::Begin()
|
||||
- Click and drag on lower right corner to resize window
|
||||
- Click and drag on any empty space to move window
|
||||
- Double-click/double-tap on lower right corner grip to auto-fit to content
|
||||
- TAB/SHIFT+TAB to cycle through keyboard editable fields
|
||||
- use mouse wheel to scroll
|
||||
- use CTRL+mouse wheel to zoom window contents (if IO.FontAllowScaling is true)
|
||||
- Use mouse wheel to scroll
|
||||
- Use CTRL+mouse wheel to zoom window contents (if io.FontAllowScaling is true)
|
||||
- CTRL+Click on a slider or drag box to input value as text
|
||||
- text editor:
|
||||
- Text editor:
|
||||
- Hold SHIFT or use mouse to select text.
|
||||
- CTRL+Left/Right to word jump
|
||||
- CTRL+Shift+Left/Right to select words
|
||||
@ -74,32 +75,36 @@
|
||||
- CTRL+Z,CTRL+Y to undo/redo
|
||||
- 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.
|
||||
|
||||
|
||||
PROGRAMMER GUIDE
|
||||
================
|
||||
|
||||
- read the FAQ below this section!
|
||||
- your code creates the UI, if your code doesn't run the UI is gone! == very dynamic UI, no construction/destructions steps, less data retention on your side, no state duplication, less sync, less bugs.
|
||||
- call and read ImGui::ShowTestWindow() for demo code demonstrating most features.
|
||||
- see examples/ folder for standalone sample applications. Prefer reading examples/opengl2_example/ first as it is the simplest.
|
||||
you may be able to grab and copy a ready made imgui_impl_*** file from the examples/.
|
||||
- customization: PushStyleColor()/PushStyleVar() or the style editor to tweak the look of the interface (e.g. if you want a more compact UI or a different color scheme).
|
||||
READ FIRST
|
||||
|
||||
- getting started:
|
||||
- init: call ImGui::GetIO() to retrieve the ImGuiIO structure and fill the fields marked 'Settings'.
|
||||
- init: call io.Fonts->GetTexDataAsRGBA32(...) and load the font texture pixels into graphics memory.
|
||||
- every frame:
|
||||
- Read the FAQ below this section!
|
||||
- Your code creates the UI, if your code doesn't run the UI is gone! == very dynamic UI, no construction/destructions steps, less data retention on your side, no state duplication, less sync, less bugs.
|
||||
- Call and read ImGui::ShowTestWindow() for demo code demonstrating most features.
|
||||
- Customization: PushStyleColor()/PushStyleVar() or the style editor to tweak the look of the interface (e.g. if you want a more compact UI or a different color scheme).
|
||||
|
||||
GETTING STARTED WITH INTEGRATING IMGUI IN YOUR CODE/ENGINE
|
||||
|
||||
- See examples/ folder for standalone sample applications. Prefer reading examples/opengl_example/ first as it is the simplest.
|
||||
You may be able to grab and copy a ready made imgui_impl_*** file from the examples/.
|
||||
- Init: call ImGui::GetIO() to retrieve the ImGuiIO structure and fill the fields marked 'Settings'.
|
||||
- Init: call io.Fonts->GetTexDataAsRGBA32(...) and load the font texture pixels into graphics memory.
|
||||
- Every frame:
|
||||
1/ in your mainloop or right after you got your keyboard/mouse info, call ImGui::GetIO() and fill the fields marked 'Input'
|
||||
2/ call ImGui::NewFrame() as early as you can!
|
||||
3/ use any ImGui function you want between NewFrame() and Render()
|
||||
4/ call ImGui::Render() as late as you can to end the frame and finalize render data. it will call your RenderDrawListFn handler that you set in the IO structure.
|
||||
(if you don't need to render, you still need to call Render() and ignore the callback, or call EndFrame() instead. if you call neither some aspects of windows focusing/moving will appear broken.)
|
||||
- all rendering information are stored into command-lists until ImGui::Render() is called.
|
||||
- ImGui never touches or know about your GPU state. the only function that knows about GPU is the RenderDrawListFn handler that you provide.
|
||||
- effectively it means you can create widgets at any time in your code, regardless of considerations of being in "update" vs "render" phases of your own application.
|
||||
- refer to the examples applications in the examples/ folder for instruction on how to setup your code.
|
||||
- a typical application skeleton may be:
|
||||
- All rendering information are stored into command-lists until ImGui::Render() is called.
|
||||
- ImGui never touches or knows about your GPU state. the only function that knows about GPU is the RenderDrawListFn handler that you provide.
|
||||
- Effectively it means you can create widgets at any time in your code, regardless of considerations of being in "update" vs "render" phases of your own application.
|
||||
- Refer to the examples applications in the examples/ folder for instruction on how to setup your code.
|
||||
- A typical application skeleton may be:
|
||||
|
||||
// Application init
|
||||
ImGuiIO& io = ImGui::GetIO();
|
||||
@ -109,8 +114,7 @@
|
||||
io.RenderDrawListsFn = my_render_function; // Setup a render function, or set to NULL and call GetDrawData() after Render() to access the render data.
|
||||
// TODO: Fill others settings of the io structure
|
||||
|
||||
// Load texture atlas
|
||||
// There is a default font so you don't need to care about choosing a font yet
|
||||
// Load texture atlas (there is a default font so you don't need to care about choosing a font yet)
|
||||
unsigned char* pixels;
|
||||
int width, height;
|
||||
io.Fonts->GetTexDataAsRGBA32(pixels, &width, &height);
|
||||
@ -146,6 +150,7 @@
|
||||
mouse inputs from the rest of your application. Read the FAQ below for more information about those flags.
|
||||
|
||||
|
||||
|
||||
API BREAKING CHANGES
|
||||
====================
|
||||
|
||||
@ -269,7 +274,7 @@
|
||||
|
||||
Q: How can I help?
|
||||
A: - If you are experienced enough with ImGui and with C/C++, look at the todo list and see how you want/can help!
|
||||
- Become a Patron/donate. Convince your company to become a Patron or provide serious funding for development time.
|
||||
- Become a Patron/donate! Convince your company to become a Patron or provide serious funding for development time! See http://www.patreon.com/imgui
|
||||
|
||||
Q: How do I update to a newer version of ImGui?
|
||||
A: Overwrite the following files:
|
||||
@ -490,9 +495,9 @@
|
||||
- window/tooltip: allow to set the width of a tooltip to allow TextWrapped() etc. while keeping the height automatic.
|
||||
- window: increase minimum size of a window with menus or fix the menu rendering so that it doesn't look odd.
|
||||
- draw-list: maintaining bounding box per command would allow to merge draw command when clipping isn't relied on (typical non-scrolling window or non-overflowing column would merge with previous command).
|
||||
!- scrolling: allow immediately effective change of scroll if we haven't appended items yet
|
||||
!- scrolling: allow immediately effective change of scroll after Begin() if we haven't appended items yet
|
||||
- splitter/separator: formalize the splitter idiom into an official api (we want to handle n-way split) (#319)
|
||||
- widgets: display mode: widget-label, label-widget (aligned on column or using fixed size), label-newline-tab-widget etc.
|
||||
- widgets: display mode: widget-label, label-widget (aligned on column or using fixed size), label-newline-tab-widget etc. (#395)
|
||||
- widgets: clean up widgets internal toward exposing everything.
|
||||
- widgets: add disabled and read-only modes (#211)
|
||||
- main: considering adding an Init() function? some constructs are awkward in the implementation because of the lack of them.
|
||||
@ -575,13 +580,14 @@
|
||||
- textwrapped: figure out better way to use TextWrapped() in an always auto-resize context (tooltip, etc.) (#249)
|
||||
- settings: write more decent code to allow saving/loading new fields
|
||||
- settings: api for per-tool simple persistent data (bool,int,float,columns sizes,etc.) in .ini file
|
||||
- stb: add defines to disable stb implementations
|
||||
- style: add window shadows.
|
||||
- style/optimization: store rounded corners in texture to use 1 quad per corner (filled and wireframe) to lower the cost of rounding.
|
||||
- style: color-box not always square?
|
||||
- style: a concept of "compact style" that the end-user can easily rely on (e.g. PushStyleCompact()?) that maps to other settings? avoid implementing duplicate helpers such as SmallCheckbox(), etc.
|
||||
- style: try to make PushStyleVar() more robust to incorrect parameters (to be more friendly to edit & continues situation).
|
||||
- style: global scale setting.
|
||||
- style: WindowPadding needs to be EVEN needs the 0.5 multiplier probably have a subtle effect on clip rectangle
|
||||
- style: WindowPadding needs to be EVEN as the 0.5 multiplier used on this value probably have a subtle effect on clip rectangle
|
||||
- text: simple markup language for color change?
|
||||
- font: dynamic font atlas to avoid baking huge ranges into bitmap and make scaling easier.
|
||||
- font: small opt: for monospace font (like the defalt one) we can trim IndexXAdvance as long as trailing value is == FallbackXAdvance
|
||||
@ -594,6 +600,7 @@
|
||||
- log: let user copy any window content to clipboard easily (CTRL+C on windows? while moving it? context menu?). code is commented because it fails with multiple Begin/End pairs.
|
||||
- filters: set a current filter that tree node can automatically query to hide themselves
|
||||
- filters: handle wildcards (with implicit leading/trailing *), regexps
|
||||
- filters: fuzzy matches (may use code at blog.forrestthewoods.com/4cffeed33fdb)
|
||||
- shortcuts: add a shortcut api, e.g. parse "&Save" and/or "Save (CTRL+S)", pass in to widgets or provide simple ways to use (button=activate, input=focus)
|
||||
!- keyboard: tooltip & combo boxes are messing up / not honoring keyboard tabbing
|
||||
- keyboard: full keyboard navigation and focus. (#323)
|
||||
@ -6414,6 +6421,7 @@ static bool DataTypeApplyOpFromText(const char* buf, const char* initial_value_b
|
||||
}
|
||||
|
||||
// Create text input in place of a slider (when CTRL+Clicking on slider)
|
||||
// FIXME: Logic is messy and confusing.
|
||||
bool ImGui::InputScalarAsWidgetReplacement(const ImRect& aabb, const char* label, ImGuiDataType data_type, void* data_ptr, ImGuiID id, int decimal_precision)
|
||||
{
|
||||
ImGuiContext& g = *GImGui;
|
||||
@ -6427,9 +6435,8 @@ bool ImGui::InputScalarAsWidgetReplacement(const ImRect& aabb, const char* label
|
||||
char buf[32];
|
||||
DataTypeFormatString(data_type, data_ptr, decimal_precision, buf, IM_ARRAYSIZE(buf));
|
||||
bool text_value_changed = InputTextEx(label, buf, IM_ARRAYSIZE(buf), aabb.GetSize(), ImGuiInputTextFlags_CharsDecimal | ImGuiInputTextFlags_AutoSelectAll);
|
||||
if (g.ScalarAsInputTextId == 0)
|
||||
if (g.ScalarAsInputTextId == 0) // First frame we started displaying the InputText widget
|
||||
{
|
||||
// First frame
|
||||
IM_ASSERT(g.ActiveId == id); // InputText ID expected to match the Slider ID (else we'd need to store them both, which is also possible)
|
||||
g.ScalarAsInputTextId = g.ActiveId;
|
||||
SetHoveredID(id);
|
||||
@ -9872,6 +9879,7 @@ void ImGui::ShowMetricsWindow(bool* p_open)
|
||||
ImGui::Text("HoveredRootWindow: '%s'", g.HoveredRootWindow ? g.HoveredRootWindow->Name : "NULL");
|
||||
ImGui::Text("HoveredID: 0x%08X/0x%08X", g.HoveredId, g.HoveredIdPreviousFrame); // Data is "in-flight" so depending on when the Metrics window is called we may see current frame information or not
|
||||
ImGui::Text("ActiveID: 0x%08X/0x%08X", g.ActiveId, g.ActiveIdPreviousFrame);
|
||||
ImGui::Text("ActiveIdWindow: '%s", g.ActiveIdWindow ? g.ActiveIdWindow->Name : "NULL");
|
||||
ImGui::TreePop();
|
||||
}
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user