mirrors/imgui
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updated documentation, better FAQ on ids and usage of "##" and "###" (#107)

Browse Source
This commit is contained in:
ocornut 2015-03-07 21:54:46 +00:00
parent 81a742bf54
commit fbbde3a7c0
1 changed files with 55 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
imgui.cpp
View File

@ -9,9 +9,9 @@
Index Index
- MISSION STATEMENT - MISSION STATEMENT
- END-USER GUIDE - END-USER GUIDE
- PROGRAMMER GUIDE - PROGRAMMER GUIDE (read me!)
- API BREAKING CHANGES - API BREAKING CHANGES (read me when you update!)
- TROUBLESHOOTING & FREQUENTLY ASKED QUESTIONS - FREQUENTLY ASKED QUESTIONS & TROUBLESHOOTING (read me!)
- ISSUES & TODO-LIST - ISSUES & TODO-LIST
- CODE - CODE
- SAMPLE CODE - SAMPLE CODE
@ -27,14 +27,14 @@
- minimize screen real-estate usage - minimize screen real-estate usage
- minimize setup and maintenance - minimize setup and maintenance
- minimize state storage on user side - minimize state storage on user side
- portable, minimize dependencies, run on target (consoles, etc.) - portable, minimize dependencies, run on target (consoles, phones, etc.)
- efficient runtime (NB- we do allocate when "growing" content - creating a window / opening a tree node for the first time, etc. - but a typical frame won't allocate anything) - efficient runtime (NB- we do allocate when "growing" content - creating a window / opening a tree node for the first time, etc. - but a typical frame won't allocate anything)
- read about immediate-mode GUI principles @ http://mollyrocket.com/861, http://mollyrocket.com/forums/index.html - read about immediate-mode gui principles @ http://mollyrocket.com/861, http://mollyrocket.com/forums/index.html
Designed for developers and content-creators, not the typical end-user! Some of the weaknesses includes: Designed for developers and content-creators, not the typical end-user! Some of the weaknesses includes:
- doesn't look fancy, doesn't animate - doesn't look fancy, doesn't animate
- limited layout features, intricate layouts are typically crafted in code - limited layout features, intricate layouts are typically crafted in code
- occasionally use statically sized buffers for string manipulations - won't crash, but some long text may be clipped - occasionally uses statically sized buffers for string manipulations - won't crash, but some long text may be clipped. functions like ImGui::TextUnformatted() don't have such restriction.
END-USER GUIDE END-USER GUIDE
@ -63,12 +63,12 @@
PROGRAMMER GUIDE PROGRAMMER GUIDE
================ ================
- your code creates the UI, if your code doesn't run the UI is gone! == dynamic UI, no construction step, less data retention on your side, no state duplication, less sync, less errors. - read the FAQ below this section!
- call and read ImGui::ShowTestWindow() for user-side sample code - 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 sample code demonstrating most features.
- see examples/ folder for standalone sample applications. - see examples/ folder for standalone sample applications.
- customization: use the style editor or PushStyleColor/PushStyleVar to tweak the look of the interface (e.g. if you want a more compact UI or a different color scheme). - customization: use the style editor or PushStyleColor/PushStyleVar to tweak the look of the interface (e.g. if you want a more compact UI or a different color scheme).
- getting started: - getting started:
- initialisation: call ImGui::GetIO() and fill the 'Settings' data. - initialisation: call ImGui::GetIO() and fill the 'Settings' data.
- every frame: - every frame:
@ -167,29 +167,57 @@
- 2014/08/28 (1.09) - changed the behavior of IO.PixelCenterOffset following various rendering fixes - 2014/08/28 (1.09) - changed the behavior of IO.PixelCenterOffset following various rendering fixes
TROUBLESHOOTING & FREQUENTLY ASKED QUESTIONS FREQUENTLY ASKED QUESTIONS & TROUBLESHOOTING
============================================ ============================================
If text or lines are blurry when integrating ImGui in your engine: If text or lines are blurry when integrating ImGui in your engine:
- in your Render function, try translating your projection matrix by (0.5f,0.5f) or (0.375f,0.375f) - in your Render function, try translating your projection matrix by (0.5f,0.5f) or (0.375f,0.375f)
If you are confused about the meaning or use of ID in ImGui: A primer on the meaning and use of ID in ImGui:
- many widgets requires state to be carried over multiple frames (most typically ImGui often wants remember what is the "active" widget).
to do so they need an unique ID. unique ID are typically derived from a string label, an indice or a pointer. - widgets require state to be carried over multiple frames (most typically ImGui often needs to remember what is the "active" widget).
when you call Button("OK") the button shows "OK" and also use "OK" as an ID. to do so they need an unique ID. unique ID are typically derived from a string label, an integer index or a pointer.
Button("OK"); // Label = "OK", ID = hash of "OK"
Button("Cancel"); // Label = "Cancel", ID = hash of "Cancel"
- ID are uniquely scoped within Windows so no conflict can happen if you have two buttons called "OK" in two different Windows. - ID are uniquely scoped within Windows so no conflict can happen if you have two buttons called "OK" in two different Windows.
within a same Window, use PushID() / PopID() to easily create scopes and avoid ID conflicts.
so if you have a loop creating "multiple" items, you can use PushID() / PopID() with the index of each item, or their pointer, etc. - when passing a label you can optionally specify extra unique ID information within string itself. This helps solving the simpler collision cases.
some functions like TreeNode() implicitly creates a scope for you by calling PushID() use "##" to pass a complement to the ID that won't be visible to the end-user:
- when dealing with trees, ID are important because you want to preserve the opened/closed state of tree nodes.
depending on your use cases you may want to use strings, indices or pointers as ID. experiment and see what makes more sense! Button("Play##0"); // Label = "Play", ID = hash of "Play##0"
e.g. When displaying a single object that may change over time, using a static string as ID will preserve your node open/closed state when the targeted object change Button("Play##1"); // Label = "Play", ID = hash of "Play##1" (different from above)
e.g. When displaying a list of objects, using indices or pointers as ID will preserve the node open/closed state per object
- when passing a label you can optionally specify extra unique ID information within the same string using "##". This helps solving the simpler collision cases. use "###" to pass a label that isn't part of ID. You can use that to change labels while preserving a constant ID.
e.g. "Label" display "Label" and uses "Label" as ID
e.g. "Label##Foobar" display "Label" and uses "Label##Foobar" as ID Button("Hello###ID"; // Label = "Hello", ID = hash of "ID"
e.g. "##Foobar" display an empty label and uses "##Foobar" as ID Button("World###ID"; // Label = "World", ID = hash of "ID" (same as above)
- read articles about immediate-mode ui principles (see web links) to understand the requirement and use of ID.
- use PushID() / PopID() to create scopes and avoid ID conflicts within the same Window:
Button("Click"); // Label = "Click", ID = hash of "Click"
PushID("node");
Button("Click"); // Label = "Click", ID = hash of "node" and "Click"
for (int i = 0; i < 100; i++)
{
PushID(i);
Button("Click"); // Label = "Click", ID = hash of "node" and i and "label"
PopID();
}
PopID();
PushID(my_ptr);
Button("Click"); // Label = "Click", ID = hash of ptr and "Click"
PopID();
so if you have a loop creating multiple items, you can use PushID() / PopID() with the index of each item, or their pointer, etc.
some functions like TreeNode() implicitly creates a scope for you by calling PushID().
- when working with trees, ID are used to preserve the opened/closed state of tree nodes.
depending on your use cases you may want to use strings, indices or pointers as ID.
e.g. when displaying a single object that may change over time (1-1 relationship), using a static string as ID will preserve your node open/closed state when the targeted object change.
e.g. when displaying a list of objects, using indices or pointers as ID will preserve the node open/closed state differerently. experiment and see what makes more sense!
If you want to load a different font than the default (ProggyClean.ttf, size 13) If you want to load a different font than the default (ProggyClean.ttf, size 13)