imgui

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 27, 2018 License: BSD-3-Clause Imports: 4 Imported by: 0

README

Dear ImGui for Go

Go Report Card

This library is a Go wrapper for Dear ImGui.

At the moment, this wrapper is a special-purpose wrapper for use within InkyBlackness. However, it is self-contained and can be used for other purposes as well.

This wrapper is

  • hand-crafted, for Go
  • documented
  • versioned
  • with a ported example using GLFW3 and OpenGL3.

Screenshot from example

API naming

Names of types and functions follow closely those of Dear ImGui.

For functions that have optional parameters, the following schema is applied:

  • There is the "verbose" variant, followed by the letter V, such as ButtonV(id string, size Vec2) bool
  • Next to it there is the "idiomatic" variant, without any optional parameter, such as Button(id string) bool.
  • The idiomatic variant calls the verbose variant with the default values for the optional parameters. Functions that don't have optional parameters don't come in a verbose variant.

The Dear ImGui functions IO() and Style() have been renamed to be CurrentIO() and CurrentStyle(). This was done because their returned types have the same name, causing a name clash. With the Current prefix, they also better describe what they return.

API philosophy

This library does not intend to export all the functions of the wrapped ImGui. The following filter applies as a rule of thumb:

  • Functions marked as "obsolete" are not available. (The corresponding C code isn't even compiled - disabled by define)
  • "Shortcut" Functions, which combine language features and/or other ImGui functions, are not available. Prime example are the Text*() functions for instance: Text formatting should be done with fmt.Sprintf(), and style formatting with the corresponding Push/Pop functions.
  • Functions that are not needed by InkyBlackness are ignored. This doesn't mean that they can't be in the wrapper, they are simply not a priority. Feel free to propose an implementation or make a pull request, respecting the previous points :)

Version philosophy

This library does not mirror the versions of the wrapped ImGui. The semantic versioning of this wrapper is defined as:

  • Major changes: (Breaking) changes in API or behaviour. Typically done through changes in ImGui.
  • Minor changes: Extensions in API. Typically done through small version increments of ImGui and/or exposing further features in a compatible way.
  • Patch changes: Bug fixes - either in the wrapper or the wrapped ImGui, given that the API & behaviour remains the same.

At the moment, this library uses version 1.61 of ImGui.

Alternatives

Before this project was created, the following alternatives were considered - and ignored:

  • kdrag0n/go-imgui. Reasons for dismissal:
    • Auto-generated bloat, which doesn't help
    • Old API (1.5x)
    • Does not compile (Issues 1 and 3)
    • Project appears to be abandoned
  • Extrawurst/cimgui. Reasons for dismissal:
    • Old API (1.5x), 1.6x attempted, in-progress, could not be used
    • Appears to still semi-expose the C++ API, especially through the structures
    • Adding this adds another dependency

License

The project is available under the terms of the New BSD License (see LICENSE file). The licenses of included sources are stored in the _licenses folder.

Documentation

Overview

Package imgui contains all the functions to create an immediate mode graphical user interface based on Dear ImGui.

Setup

Refer to the _examples directory, which contains ported examples of the C++ version, available to Go.

Conventions

The exported functions and constants are named closely to that of the wrapped library. If a function has optional parameters, it will be available in two versions: A verbose one, which has all optional parameters listed, and a terse one, with only the mandatory parameters in its signature. The verbose variant will have the suffix V in its name. For example, there are 

func Button(id string) bool

and 

func ButtonV(id string, size Vec2) bool

The terse variant will list the default parameters it uses to call the verbose variant.

There are several types which are based on uintptr. These are references to the wrapped instances in C++. You will always get to such a reference via some function - you never "instantiate" such an instance on your own.

Index

Constants

View Source 
const (
	// ComboFlagPopupAlignLeft aligns the popup toward the left by default.
	ComboFlagPopupAlignLeft = 1 << iota
	// ComboFlagHeightSmall has max ~4 items visible.
	// Tip: If you want your combo popup to be a specific size you can use SetNextWindowSizeConstraints() prior to calling BeginCombo().
	ComboFlagHeightSmall
	// ComboFlagHeightRegular has max ~8 items visible (default).
	ComboFlagHeightRegular
	// ComboFlagHeightLarge has max ~20 items visible.
	ComboFlagHeightLarge
	// ComboFlagHeightLargest has as many fitting items as possible.
	ComboFlagHeightLargest
	// ComboFlagNoArrowButton displays on the preview box without the square arrow button.
	ComboFlagNoArrowButton
	// ComboFlagNoPreview displays only a square arrow button.
	ComboFlagNoPreview
)
View Source 
const (
	// HoveredFlagsDefault Return true if directly over the item/window, not obstructed by another window,
	// not obstructed by an active popup or modal blocking inputs under them.
	HoveredFlagsDefault = 0
	// HoveredFlagsChildWindows IsWindowHovered() only: Return true if any children of the window is hovered.
	HoveredFlagsChildWindows = 1 << 0
	// HoveredFlagsRootWindow IsWindowHovered() only: Test from root window (top most parent of the current hierarchy).
	HoveredFlagsRootWindow = 1 << 1
	// HoveredFlagsAnyWindow IsWindowHovered() only: Return true if any window is hovered.
	HoveredFlagsAnyWindow = 1 << 2
	// HoveredFlagsAllowWhenBlockedByPopup Return true even if a popup window is normally blocking access to this item/window.
	HoveredFlagsAllowWhenBlockedByPopup = 1 << 3

	// HoveredFlagsAllowWhenBlockedByActiveItem Return true even if an active item is blocking access to this item/window.
	// Useful for Drag and Drop patterns.
	HoveredFlagsAllowWhenBlockedByActiveItem = 1 << 5
	// HoveredFlagsAllowWhenOverlapped Return true even if the position is overlapped by another window
	HoveredFlagsAllowWhenOverlapped = 1 << 6
)
View Source 
const (
	HoveredFlagsRectOnly            = HoveredFlagsAllowWhenBlockedByPopup | HoveredFlagsAllowWhenBlockedByActiveItem | HoveredFlagsAllowWhenOverlapped
	HoveredFlagsRootAndChildWindows = HoveredFlagsRootWindow | HoveredFlagsChildWindows
)

HoveredFlags combinations

View Source 
const (
	// TreeNodeFlagsSelected draws as selected.
	TreeNodeFlagsSelected = 1 << iota
	// TreeNodeFlagsFramed draws full colored frame (e.g. for CollapsingHeader).
	TreeNodeFlagsFramed
	// TreeNodeFlagsAllowItemOverlap hit testing to allow subsequent widgets to overlap this one.
	TreeNodeFlagsAllowItemOverlap
	// TreeNodeFlagsNoTreePushOnOpen doesn't do a TreePush() when open
	// (e.g. for CollapsingHeader) = no extra indent nor pushing on ID stack.
	TreeNodeFlagsNoTreePushOnOpen
	// TreeNodeFlagsNoAutoOpenOnLog doesn't automatically and temporarily open node when Logging is active
	// (by default logging will automatically open tree nodes).
	TreeNodeFlagsNoAutoOpenOnLog
	// TreeNodeFlagsDefaultOpen defaults node to be open.
	TreeNodeFlagsDefaultOpen
	// TreeNodeFlagsOpenOnDoubleClick needs double-click to open node.
	TreeNodeFlagsOpenOnDoubleClick
	// TreeNodeFlagsOpenOnArrow opens only when clicking on the arrow part.
	// If TreeNodeFlagsOpenOnDoubleClick is also set, single-click arrow or double-click all box to open.
	TreeNodeFlagsOpenOnArrow
	// TreeNodeFlagsLeaf allows no collapsing, no arrow (use as a convenience for leaf nodes).
	TreeNodeFlagsLeaf
	// TreeNodeFlagsBullet displays a bullet instead of arrow.
	TreeNodeFlagsBullet
	// TreeNodeFlagsFramePadding use FramePadding (even for an unframed text node) to
	// vertically align text baseline to regular widget height. Equivalent to calling AlignTextToFramePadding().
	TreeNodeFlagsFramePadding

	// TreeNodeFlagsNavLeftJumpsBackHere (WIP) Nav: left direction may move to this TreeNode()
	// from any of its child (items submitted between TreeNode and TreePop).
	TreeNodeFlagsNavLeftJumpsBackHere
	// TreeNodeFlagsCollapsingHeader combines TreeNodeFlagsFramed and TreeNodeFlagsNoAutoOpenOnLog.
	TreeNodeFlagsCollapsingHeader = TreeNodeFlagsFramed | TreeNodeFlagsNoAutoOpenOnLog
)
View Source 
const (
	// WindowFlagsNoTitleBar disables the title-bar.
	WindowFlagsNoTitleBar = 1 << 0
	// WindowFlagsNoResize disables user resizing with the lower-right grip.
	WindowFlagsNoResize = 1 << 1
	// WindowFlagsNoMove disables user moving the window.
	WindowFlagsNoMove = 1 << 2
	// WindowFlagsNoScrollbar disables scrollbars (window can still scroll with mouse or programatically).
	WindowFlagsNoScrollbar = 1 << 3
	// WindowFlagsNoScrollWithMouse disables user vertically scrolling with mouse wheel.
	// On child window, mouse wheel will be forwarded to the parent unless NoScrollbar is also set.
	WindowFlagsNoScrollWithMouse = 1 << 4
	// WindowFlagsNoCollapse disables user collapsing window by double-clicking on it.
	WindowFlagsNoCollapse = 1 << 5
	// WindowFlagsAlwaysAutoResize resizes every window to its content every frame.
	WindowFlagsAlwaysAutoResize = 1 << 6
	// WindowFlagsNoSavedSettings prohibits load/save settings in .ini file.
	WindowFlagsNoSavedSettings = 1 << 8
	// WindowFlagsNoInputs disables catching mouse or keyboard inputs, hovering test with pass through.
	WindowFlagsNoInputs = 1 << 9
	// WindowFlagsMenuBar has a menu-bar.
	WindowFlagsMenuBar = 1 << 10
	// WindowFlagsHorizontalScrollbar allows horizontal scrollbar to appear (off by default).
	// You may use SetNextWindowContentSize(Vec2(width,0.0f)); prior to calling Begin() to specify width.
	// Read code in imgui_demo in the "Horizontal Scrolling" section.
	WindowFlagsHorizontalScrollbar = 1 << 11
	// WindowFlagsNoFocusOnAppearing disables taking focus when transitioning from hidden to visible state.
	WindowFlagsNoFocusOnAppearing = 1 << 12
	// WindowFlagsNoBringToFrontOnFocus disables bringing window to front when taking focus.
	// (e.g. clicking on it or programatically giving it focus)
	WindowFlagsNoBringToFrontOnFocus = 1 << 13
	// WindowFlagsAlwaysVerticalScrollbar shows always a vertical scrollbar (even if ContentSize.y < Size.y)
	WindowFlagsAlwaysVerticalScrollbar = 1 << 14
	// WindowFlagsAlwaysHorizontalScrollbar shows always a horizontal scrollbar (even if ContentSize.x < Size.x).
	WindowFlagsAlwaysHorizontalScrollbar = 1 << 15
	// WindowFlagsAlwaysUseWindowPadding ensures child windows without border uses style.WindowPadding.
	// (ignored by default for non-bordered child windows, because more convenient)
	WindowFlagsAlwaysUseWindowPadding = 1 << 16
	// WindowFlagsResizeFromAnySide [BETA] enables resize from any corners and borders.
	// Your back-end needs to honor the different values of io.MouseCursor set by imgui.
	WindowFlagsResizeFromAnySide = 1 << 17
	// WindowFlagsNoNavInputs disables gamepad/keyboard navigation within the window.
	WindowFlagsNoNavInputs = 1 << 18
	// WindowFlagsNoNavFocus disables focusing toward this window with gamepad/keyboard navigation (e.g. skipped by CTRL+TAB)
	WindowFlagsNoNavFocus = 1 << 19
	// WindowFlagsNoNav combines WindowFlagsNoNavInputs and WindowFlagsNoNavFocus.
	WindowFlagsNoNav = WindowFlagsNoNavInputs | WindowFlagsNoNavFocus
)
View Source 
const (
	KeyTab        = 0
	KeyLeftArrow  = 1
	KeyRightArrow = 2
	KeyUpArrow    = 3
	KeyDownArrow  = 4
	KeyPageUp     = 5
	KeyPageDown   = 6
	KeyHome       = 7
	KeyEnd        = 8
	KeyInsert     = 9
	KeyDelete     = 10
	KeyBackspace  = 11
	KeySpace      = 12
	KeyEnter      = 13
	KeyEscape     = 14
	KeyA          = 15 // for text edit CTRL+A: select all
	KeyC          = 16 // for text edit CTRL+C: copy
	KeyV          = 17 // for text edit CTRL+V: paste
	KeyX          = 18 // for text edit CTRL+X: cut
	KeyY          = 19 // for text edit CTRL+Y: redo
	KeyZ          = 20 // for text edit CTRL+Z: undo
	KeyCOUNT      = 21
)

User fill ImGuiIO.KeyMap[] array with indices into the ImGuiIO.KeysDown[512] array

Variables

View Source 
var ErrContextDestroyed = errors.New("context is destroyed")

ErrContextDestroyed is returned when trying to use an already destroyed context.

View Source 
var ErrNoContext = errors.New("no current context")

ErrNoContext is used when no context is current.

Functions

func Begin added in v0.2.0 

func Begin(id string) bool

Begin calls BeginV(id, nil, 0).

func BeginChild added in v0.2.0 

func BeginChild(id string) bool

BeginChild calls BeginChildV(id, Vec2{0,0}, false, 0).

func BeginChildV added in v0.2.0 

func BeginChildV(id string, size Vec2, border bool, flags int) bool

BeginChildV pushes a new child to the stack and starts appending to it.

func BeginCombo added in v0.2.0 

func BeginCombo(label, previewValue string) bool

BeginCombo calls BeginComboV(label, previewValue, 0).

func BeginComboV added in v0.2.0 

func BeginComboV(label, previewValue string, flags int) bool

BeginComboV creates a combo box with complete control over the content to the user. Call EndCombo() if this function returns true.

func BeginGroup added in v0.2.0 

func BeginGroup()

BeginGroup locks horizontal starting position + capture group bounding box into one "item" (so you can use IsItemHovered() or layout primitives such as SameLine() on whole group, etc.)

func BeginMainMenuBar added in v0.2.0 

func BeginMainMenuBar() bool

BeginMainMenuBar creates and appends to a full screen menu-bar. If the return value is true, then EndMainMenuBar() must be called!

func BeginMenu added in v0.2.0 

func BeginMenu(label string) bool

BeginMenu calls BeginMenuV(label, true).

func BeginMenuBar added in v0.2.0 

func BeginMenuBar() bool

BeginMenuBar appends to menu-bar of current window. This requires WindowFlagsMenuBar flag set on parent window. If the return value is true, then EndMenuBar() must be called!

func BeginMenuV added in v0.2.0 

func BeginMenuV(label string, enabled bool) bool

BeginMenuV creates a sub-menu entry. If the return value is true, then EndMenu() must be called!

func BeginPopupContextItem added in v0.5.0 

func BeginPopupContextItem() bool

BeginPopupContextItem calls BeginPopupContextItemV("", 1)

func BeginPopupContextItemV added in v0.5.0 

func BeginPopupContextItemV(label string, mouseButton int) bool

BeginPopupContextItemV returns true if the identified mouse button was pressed while hovering over the last item.

func BeginPopupModal added in v0.2.0 

func BeginPopupModal(name string) bool

BeginPopupModal calls BeginPopupModalV(name, nil, 0)

func BeginPopupModalV added in v0.2.0 

func BeginPopupModalV(name string, open *bool, flags int) bool

BeginPopupModalV creates modal dialog (regular window with title bar, block interactions behind the modal window, can't close the modal window by clicking outside).

func BeginTooltip added in v0.4.0 

func BeginTooltip()

BeginTooltip begins/appends to a tooltip window. Used to create full-featured tooltip (with any kind of contents). Requires a call to EndTooltip().

func BeginV added in v0.2.0 

func BeginV(id string, open *bool, flags int) bool

BeginV pushes a new window to the stack and start appending to it. You may append multiple times to the same window during the same frame. If the open argument is provided, the window can be closed, in which case the value will be false after the call.

Returns false if the window is currently not visible. Regardless of the return value, End() must be called for each call to Begin().

func Button added in v0.2.0 

func Button(id string) bool

Button calls ButtonV(id, Vec2{0,0}).

func ButtonV added in v0.2.0 

func ButtonV(id string, size Vec2) bool

ButtonV returning true if it is pressed.

func Checkbox added in v0.2.0 

func Checkbox(id string, selected *bool) bool

Checkbox creates a checkbox in the selected state. The return value indicates if the selected state has changed.

func CloseCurrentPopup added in v0.2.0 

func CloseCurrentPopup()

CloseCurrentPopup closes the popup we have begin-ed into. Clicking on a MenuItem or Selectable automatically close the current popup.

func Dummy added in v0.4.0 

func Dummy(size Vec2)

Dummy adds a dummy item of given size.

func End added in v0.2.0 

func End()

End closes the scope for the previously opened window. Every call to Begin() must be matched with a call to End().

func EndChild added in v0.2.0 

func EndChild()

EndChild closes the scope for the previously opened child. Every call to BeginChild() must be matched with a call to EndChild().

func EndCombo added in v0.2.0 

func EndCombo()

EndCombo must be called if BeginComboV() returned true.

func EndFrame 

func EndFrame()

EndFrame ends the ImGui frame. Automatically called by Render(), so most likely don't need to ever call that yourself directly. If you don't need to render you may call EndFrame() but you'll have wasted CPU already. If you don't need to render, better to not create any imgui windows instead!

func EndGroup added in v0.2.0 

func EndGroup()

EndGroup must be called for each call to BeginGroup().

func EndMainMenuBar added in v0.2.0 

func EndMainMenuBar()

EndMainMenuBar finishes a main menu bar. Only call EndMainMenuBar() if BeginMainMenuBar() returns true!

func EndMenu added in v0.2.0 

func EndMenu()

EndMenu finishes a sub-menu entry. Only call EndMenu() if BeginMenu() returns true!

func EndMenuBar added in v0.2.0 

func EndMenuBar()

EndMenuBar finishes a menu bar. Only call EndMenuBar() if BeginMenuBar() returns true!

func EndPopup added in v0.2.0 

func EndPopup()

EndPopup finshes a popup. Only call EndPopup() if BeginPopupXXX() returns true!

func EndTooltip added in v0.4.0 

func EndTooltip()

EndTooltip closes the previously started tooltip window.

func Image added in v0.3.0 

func Image(id TextureID, size Vec2)

Image calls ImageV(id, size, Vec2{0,0}, Vec2{1,1}, Vec4{1,1,1,1}, Vec4{0,0,0,0}).

func ImageButton added in v0.3.0 

func ImageButton(id TextureID, size Vec2) bool

ImageButton calls ImageButtonV(id, size, Vec2{0,0}, Vec2{1,1}, -1, Vec4{0,0,0,0}, Vec4{1,1,1,1}).

func ImageButtonV added in v0.3.0 

func ImageButtonV(id TextureID, size Vec2, uv0, uv1 Vec2, framePadding int, bgCol Vec4, tintCol Vec4) bool

ImageButtonV adds a button with an image, based on given texture ID. Refer to TextureID what this represents and how it is drawn. <0 framePadding uses default frame padding settings. 0 for no padding.

func ImageV added in v0.3.0 

func ImageV(id TextureID, size Vec2, uv0, uv1 Vec2, tintCol, borderCol Vec4)

ImageV adds an image based on given texture ID. Refer to TextureID what this represents and how it is drawn.

func IndexBufferLayout 

func IndexBufferLayout() (entrySize int)

IndexBufferLayout returns the byte size necessary to select fields in an index buffer of DrawList.

func IsItemHovered added in v0.4.0 

func IsItemHovered() bool

IsItemHovered calls IsItemHoveredV(HoveredFlagsDefault)

func IsItemHoveredV added in v0.4.0 

func IsItemHoveredV(flags int) bool

IsItemHoveredV returns true if the last item is hovered. (and usable, aka not blocked by a popup, etc.). See HoveredFlags for more options.

func LabelText added in v0.3.0 

func LabelText(label, text string)

LabelText adds text+label aligned the same way as value+label widgets. 

func MenuItem(label string) bool

MenuItem calls MenuItemV(label, "", false, true). 

func MenuItemV(label string, shortcut string, selected bool, enabled bool) bool

MenuItemV adds a menu item with given label. Returns true if the item is selected. If selected is not nil, it will be toggled when true is returned. Shortcuts are displayed for convenience but not processed by ImGui at the moment.

func NewFrame 

func NewFrame()

NewFrame starts a new ImGui frame, you can submit any command from this point until Render()/EndFrame().

func OpenPopup added in v0.2.0 

func OpenPopup(id string)

OpenPopup marks popup as open (don't call every frame!). Popups are closed when user click outside, or if CloseCurrentPopup() is called within a BeginPopup()/EndPopup() block. By default, Selectable()/MenuItem() are calling CloseCurrentPopup(). Popup identifiers are relative to the current ID-stack (so OpenPopup and BeginPopup needs to be at the same level).

func PopFont added in v0.3.0 

func PopFont()

PopFont removes the previously pushed font from the stack.

func PopID added in v0.3.0 

func PopID()

PopID removes the last pushed identifier from the ID stack.

func PopItemWidth added in v0.2.0 

func PopItemWidth()

PopItemWidth must be called for each call to PushItemWidth().

func PopStyleColor added in v0.2.0 

func PopStyleColor()

PopStyleColor calls PopStyleColorV(1).

func PopStyleColorV added in v0.2.0 

func PopStyleColorV(count int)

PopStyleColorV reverts the given amount of style color changes.

func PopStyleVar added in v0.2.0 

func PopStyleVar()

PopStyleVar calls PopStyleVarV(1).

func PopStyleVarV added in v0.2.0 

func PopStyleVarV(count int)

PopStyleVarV reverts the given amount of style variable changes.

func PopTextWrapPos added in v0.2.0 

func PopTextWrapPos()

PopTextWrapPos resets the last pushed position.

func PushFont added in v0.3.0 

func PushFont(font Font)

PushFont adds the given font on the stack. Use DefaultFont to refer to the default font.

func PushID added in v0.3.0 

func PushID(id string)

PushID pushes the given identifier into the ID stack. IDs are hash of the entire stack!

func PushItemWidth added in v0.2.0 

func PushItemWidth(width float32)

PushItemWidth sets width of items for the common item+label case, in pixels. 0.0f = default to ~2/3 of windows width, >0.0f: width in pixels, <0.0f align xx pixels to the right of window (so -1.0f always align width to the right side).

func PushStyleColor added in v0.2.0 

func PushStyleColor(id StyleColorID, color Vec4)

PushStyleColor pushes the current style color for given ID on a stack and sets the given one. To revert to the previous color, call PopStyleColor().

func PushStyleVarFloat added in v0.2.0 

func PushStyleVarFloat(id StyleVarID, value float32)

PushStyleVarFloat pushes a float value on the stack to temporarily modify a style variable.

func PushStyleVarVec2 added in v0.2.0 

func PushStyleVarVec2(id StyleVarID, value Vec2)

PushStyleVarVec2 pushes a Vec2 value on the stack to temporarily modify a style variable.

func PushTextWrapPos added in v0.2.0 

func PushTextWrapPos()

PushTextWrapPos calls PushTextWrapPosV(0.0).

func PushTextWrapPosV added in v0.2.0 

func PushTextWrapPosV(wrapPosX float32)

PushTextWrapPosV defines word-wrapping for Text() commands. < 0.0f: no wrapping; 0.0f: wrap to end of window (or column); > 0.0f: wrap at 'wrapPosX' position in window local space. Requires a matching call to PopTextWrapPos().

func Render 

func Render()

Render ends the ImGui frame, finalize the draw data. After this method, call RenderedDrawData to retrieve the draw commands and execute them.

func SameLine added in v0.2.0 

func SameLine()

SameLine calls SameLineV(0, -1).

func SameLineV added in v0.2.0 

func SameLineV(posX float32, spacingW float32)

SameLineV is between widgets or groups to layout them horizontally.

func Selectable added in v0.2.0 

func Selectable(label string) bool

Selectable calls SelectableV(label, false, 0, Vec2{0, 0})

func SelectableV added in v0.2.0 

func SelectableV(label string, selected bool, flags int, size Vec2) bool

SelectableV returns true if the user clicked it, so you can modify your selection state. size.x==0.0: use remaining width, size.x>0.0: specify width. size.y==0.0: use label height, size.y>0.0: specify height

func Separator added in v0.2.0 

func Separator()

Separator is generally horizontal. Inside a menu bar or in horizontal layout mode, this becomes a vertical separator.

func SetAssertHandler added in v0.3.0 

func SetAssertHandler(handler AssertHandler)

SetAssertHandler registers a handler function for all future assertions. Setting nil will disable special handling. The default handler panics.

func SetCursorPos added in v0.5.0 

func SetCursorPos(localPos Vec2)

SetCursorPos sets the cursor relative to the current window.

func SetNextTreeNodeOpen added in v0.4.0 

func SetNextTreeNodeOpen(open bool, cond Condition)

SetNextTreeNodeOpen sets the open/collapsed state of the following tree node.

func SetNextWindowBgAlpha added in v0.3.0 

func SetNextWindowBgAlpha(value float32)

SetNextWindowBgAlpha sets next window background color alpha. Helper to easily modify ImGuiCol_WindowBg/ChildBg/PopupBg.

func SetNextWindowFocus added in v0.2.0 

func SetNextWindowFocus()

SetNextWindowFocus sets next window to be focused / front-most. Call before Begin().

func SetNextWindowPos added in v0.2.0 

func SetNextWindowPos(pos Vec2)

SetNextWindowPos calls SetNextWindowPosV(pos, 0, Vec{0,0})

func SetNextWindowPosV added in v0.2.0 

func SetNextWindowPosV(pos Vec2, cond Condition, pivot Vec2)

SetNextWindowPosV sets next window position. Call before Begin(). Use pivot=(0.5,0.5) to center on given point, etc.

func SetNextWindowSize added in v0.2.0 

func SetNextWindowSize(size Vec2)

SetNextWindowSize calls SetNextWindowSizeV(size, 0)

func SetNextWindowSizeV added in v0.2.0 

func SetNextWindowSizeV(size Vec2, cond Condition)

SetNextWindowSizeV sets next window size. Set axis to 0.0 to force an auto-fit on this axis. Call before Begin().

func SetTooltip added in v0.4.0 

func SetTooltip(text string)

SetTooltip sets a text tooltip under the mouse-cursor, typically use with IsItemHovered(). Overrides any previous call to SetTooltip().

func ShowDemoWindow 

func ShowDemoWindow(open *bool)

ShowDemoWindow creates a demo/test window. Demonstrates most ImGui features. Call this to learn about the library! Try to make it always available in your application!

func ShowUserGuide added in v0.2.0 

func ShowUserGuide()

ShowUserGuide adds basic help/info block (not a window): how to manipulate ImGui as a end-user (mouse/keyboard controls).

func SliderInt added in v0.2.0 

func SliderInt(label string, value *int32, min, max int32) bool

SliderInt calls SliderIntV(label, value, min, max, "%d").

func SliderIntV added in v0.2.0 

func SliderIntV(label string, value *int32, min, max int32, format string) bool

SliderIntV creates a slider for integers.

func Spacing added in v0.5.0 

func Spacing()

Spacing adds vertical spacing.

func Text added in v0.2.0 

func Text(text string)

Text adds formatted text. See PushTextWrapPosV() or PushStyleColorV() for modifying the output. Without any modified style stack, the text is unformatted.

func TextLineHeight added in v0.2.0 

func TextLineHeight() float32

TextLineHeight returns ~ FontSize.

func TextLineHeightWithSpacing added in v0.2.0 

func TextLineHeightWithSpacing() float32

TextLineHeightWithSpacing returns ~ FontSize + style.ItemSpacing.y (distance in pixels between 2 consecutive lines of text).

func TreeNode added in v0.4.0 

func TreeNode(label string) bool

TreeNode calls TreeNodeV(label, 0).

func TreeNodeV added in v0.4.0 

func TreeNodeV(label string, flags int) bool

TreeNodeV returns true if the tree branch is to be rendered. Call TreePop() in this case.

func TreePop added in v0.4.0 

func TreePop()

TreePop finishes a tree branch. This has to be called for a matching TreeNodeV call returning true.

func Version 

func Version() string

Version returns a version string e.g. "1.23".

func VertexBufferLayout 

func VertexBufferLayout() (entrySize int, posOffset int, uvOffset int, colOffset int)

VertexBufferLayout returns the byte sizes necessary to select fields in a vertex buffer of a DrawList.

Types

type Alpha8Image 

type Alpha8Image struct {
	Width, Height int
	Pixels        unsafe.Pointer
}

Alpha8Image represents a imgui backed 8-bit alpha value image.

type AssertHandler added in v0.3.0 

type AssertHandler func(expression string, file string, line int)

AssertHandler is a handler for an assertion that happened in the native part of ImGui.

type Condition added in v0.2.0 

type Condition int

Condition for SetWindow***(), SetNextWindow***(), SetNextTreeNode***() functions. Important: Treat as a regular enum! Do NOT combine multiple values using binary operators! All the functions above treat 0 as a shortcut to ConditionAlways. 

const (
	// ConditionAlways sets the variable.
	ConditionAlways Condition = 1 << iota
	// ConditionOnce sets the variable once per runtime session (only the first call with succeed).
	ConditionOnce
	// ConditionFirstUseEver sets the variable if the object/window has no persistently saved data (no entry in .ini file).
	ConditionFirstUseEver
	// ConditionAppearing sets the variable if the object/window is appearing after being hidden/inactive (or the first time).
	ConditionAppearing
)

type Context 

type Context struct {
	// contains filtered or unexported fields
}

Context specifies a scope of ImGui.

All contexts share a same FontAtlas by default. If you want different font atlas, you can create them and overwrite the CurrentIO.Fonts of an ImGui context.

func CreateContext 

func CreateContext(fontAtlas *FontAtlas) *Context

CreateContext produces a new internal state scope. Passing nil for the fontAtlas creates a default font.

func CurrentContext 

func CurrentContext() (*Context, error)

CurrentContext returns the currently active state scope. Returns ErrNoContext if no context is available.

func (*Context) Destroy 

func (context *Context) Destroy()

Destroy removes the internal state scope. Trying to destroy an already destroyed context does nothing.

func (Context) SetCurrent 

func (context Context) SetCurrent() error

SetCurrent activates this context as the currently active state scope.

type DrawCommand 

type DrawCommand uintptr

DrawCommand describes one GPU call (or a callback).

func (DrawCommand) CallUserCallback 

func (cmd DrawCommand) CallUserCallback(list DrawList)

CallUserCallback calls the user callback instead of rendering the vertices. ClipRect and TextureID will be set normally.

func (DrawCommand) ClipRect 

func (cmd DrawCommand) ClipRect() (rect Vec4)

ClipRect defines the clipping rectangle (x1, y1, x2, y2).

func (DrawCommand) ElementCount 

func (cmd DrawCommand) ElementCount() int

ElementCount is the number of indices (multiple of 3) to be rendered as triangles. Vertices are stored in the callee DrawList's VertexBuffer, indices in IndexBuffer.

func (DrawCommand) HasUserCallback 

func (cmd DrawCommand) HasUserCallback() bool

HasUserCallback returns true if this handle command should be deferred.

func (DrawCommand) TextureID 

func (cmd DrawCommand) TextureID() TextureID

TextureID is the user-provided texture ID. Set by user in FontAtlas.SetTextureID() for fonts or passed to Image*() functions. Ignore if never using images or multiple fonts atlas.

type DrawData 

type DrawData uintptr

DrawData contains all draw data to render an ImGui frame.

func RenderedDrawData 

func RenderedDrawData() DrawData

RenderedDrawData returns the created draw commands, which are valid after Render() and until the next call to NewFrame(). This is what you have to render.

func (DrawData) CommandLists 

func (data DrawData) CommandLists() []DrawList

CommandLists is an array of DrawList to render. The DrawList are owned by the context and only pointed to from here.

func (DrawData) ScaleClipRects 

func (data DrawData) ScaleClipRects(scale Vec2)

ScaleClipRects is a helper to scale the ClipRect field of each DrawCmd. Use if your final output buffer is at a different scale than ImGui expects, or if there is a difference between your window resolution and framebuffer resolution.

func (DrawData) Valid 

func (data DrawData) Valid() bool

Valid indicates whether the structure is usable. It is valid only after Render() is called and before the next NewFrame() is called.

type DrawList 

type DrawList uintptr

DrawList is a draw-command list. This is the low-level list of polygons that ImGui functions are filling. At the end of the frame, all command lists are passed to your render function for rendering.

Each ImGui window contains its own DrawList. You can use GetWindowDrawList() to access the current window draw list and draw custom primitives.

You can interleave normal ImGui calls and adding primitives to the current draw list.

All positions are generally in pixel coordinates (top-left at (0,0), bottom-right at io.DisplaySize), however you are totally free to apply whatever transformation matrix to want to the data (if you apply such transformation you'll want to apply it to ClipRect as well)

Important: Primitives are always added to the list and not culled (culling is done at higher-level by ImGui functions), if you use this API a lot consider coarse culling your drawn objects.

func (DrawList) Commands 

func (list DrawList) Commands() []DrawCommand

Commands returns the list of draw commands. Typically 1 command = 1 GPU draw call, unless the command is a callback.

func (DrawList) IndexBuffer 

func (list DrawList) IndexBuffer() (unsafe.Pointer, int)

IndexBuffer returns the handle information of the whole index buffer. Returned are the handle pointer and the total byte size. The buffer is a packed array of index entries, each consisting of an integer offset. To determine the byte size, call IndexBufferLayout.

func (DrawList) VertexBuffer 

func (list DrawList) VertexBuffer() (unsafe.Pointer, int)

VertexBuffer returns the handle information of the whole vertex buffer. Returned are the handle pointer and the total byte size. The buffer is a packed array of vertex entries, each consisting of a 2D position vector, a 2D UV vector, and a 4-byte color value. To determine the byte size and offset values, call VertexBufferLayout.

type Font added in v0.3.0 

type Font uintptr

Font describes one loaded font in an atlas. 

const DefaultFont Font = 0

DefaultFont can be used to refer to the default font of the current font atlas without having the actual font reference.

type FontAtlas 

type FontAtlas uintptr

FontAtlas contains runtime data for multiple fonts, bake multiple fonts into a single texture, TTF/OTF font loader

func (FontAtlas) AddFontDefault added in v0.3.0 

func (atlas FontAtlas) AddFontDefault() Font

AddFontDefault adds the default font to the atlas. This is done by default if you do not call any of the AddFont* methods before retrieving the texture data.

func (FontAtlas) AddFontFromFileTTF added in v0.3.0 

func (atlas FontAtlas) AddFontFromFileTTF(filename string, sizePixels float32) Font

AddFontFromFileTTF attempts to load a font from given TTF file.

func (FontAtlas) SetTextureID 

func (atlas FontAtlas) SetTextureID(id TextureID)

SetTextureID sets user data to refer to the texture once it has been uploaded to user's graphic systems. It is passed back to you during rendering via the DrawCommand.

func (FontAtlas) TextureDataAlpha8 

func (atlas FontAtlas) TextureDataAlpha8() *Alpha8Image

TextureDataAlpha8 returns the image in 8-bit alpha values for the font atlas. The returned image is valid as long as the font atlas is.

type IO 

type IO struct {
	// contains filtered or unexported fields
}

IO is where your app communicate with ImGui. Access via CurrentIO(). Read 'Programmer guide' section in imgui.cpp file for general usage.

func CurrentIO 

func CurrentIO() IO

CurrentIO returns access to the ImGui communication struct for the currently active context.

func (IO) AddInputCharacters added in v0.4.0 

func (io IO) AddInputCharacters(chars string)

AddInputCharacters adds a new character into InputCharacters[].

func (IO) AddMouseWheelDelta 

func (io IO) AddMouseWheelDelta(horizontal, vertical float32)

AddMouseWheelDelta adds the given offsets to the current mouse wheel values. 1 vertical unit scrolls about 5 lines text. Most users don't have a mouse with an horizontal wheel, may not be provided by all back-ends.

func (IO) Fonts 

func (io IO) Fonts() FontAtlas

Fonts returns the font atlas to load and assemble one or more fonts into a single tightly packed texture.

func (IO) KeyAlt added in v0.4.0 

func (io IO) KeyAlt(leftAlt int, rigthAlt int)

KeyAlt sets the keyboard modifier alt pressed

func (IO) KeyCtrl added in v0.4.0 

func (io IO) KeyCtrl(leftCtrl int, rigthCtrl int)

KeyCtrl sets the keyboard modifier control pressed

func (IO) KeyMap added in v0.4.0 

func (io IO) KeyMap(imguiKey int, nativeKey int)

KeyMap maps a key into the KeysDown array which represents your "native" keyboard state

func (IO) KeyPress added in v0.4.0 

func (io IO) KeyPress(key int)

KeyPress sets the KeysDown flag

func (IO) KeyRelease added in v0.4.0 

func (io IO) KeyRelease(key int)

KeyRelease clear the KeysDown flag

func (IO) KeyShift added in v0.4.0 

func (io IO) KeyShift(leftShift int, rigthShift int)

KeyShift sets the keyboard modifier shift pressed

func (IO) KeySuper added in v0.4.0 

func (io IO) KeySuper(leftSuper int, rigthSuper int)

KeySuper sets the keyboard modifier super pressed

func (IO) SetDeltaTime 

func (io IO) SetDeltaTime(value float32)

SetDeltaTime sets the time elapsed since last frame, in seconds.

func (IO) SetDisplaySize 

func (io IO) SetDisplaySize(value Vec2)

SetDisplaySize sets the size in pixels.

func (IO) SetFontGlobalScale 

func (io IO) SetFontGlobalScale(value float32)

SetFontGlobalScale sets the global scaling factor for all fonts.

func (IO) SetMouseButtonDown 

func (io IO) SetMouseButtonDown(index int, down bool)

SetMouseButtonDown sets whether a specific mouse button is currently pressed. Mouse buttons: left, right, middle + extras. ImGui itself mostly only uses left button (BeginPopupContext** are using right button). Other buttons allows us to track if the mouse is being used by your application + available to user as a convenience via IsMouse** API.

func (IO) SetMousePosition 

func (io IO) SetMousePosition(value Vec2)

SetMousePosition sets the mouse position, in pixels. Set to Vec2(-math.MaxFloat32,-mathMaxFloat32) if mouse is unavailable (on another screen, etc.)

func (IO) WantCaptureKeyboard added in v0.4.0 

func (io IO) WantCaptureKeyboard() bool

WantCaptureKeyboard returns true if imgui will use the keyboard inputs. Do not dispatch them to your main game/application (in both cases, always pass keyboard inputs to imgui). (e.g. InputText active, or an imgui window is focused and navigation is enabled, etc.).

func (IO) WantCaptureMouse added in v0.3.0 

func (io IO) WantCaptureMouse() bool

WantCaptureMouse returns true if imgui will use the mouse inputs. Do not dispatch them to your main game/application in this case. In either case, always pass on mouse inputs to imgui. (e.g. unclicked mouse is hovering over an imgui window, widget is active, mouse was clicked over an imgui window, etc.)

func (IO) WantTextInput added in v0.4.0 

func (io IO) WantTextInput() bool

WantTextInput is true, you may display an on-screen keyboard. This is set by ImGui when it wants textual keyboard input to happen (e.g. when a InputText widget is active).

type Style 

type Style uintptr

Style describes the overall graphical representation of the user interface.

func CurrentStyle 

func CurrentStyle() Style

CurrentStyle returns the UI Style for the currently active context.

func (Style) ScaleAllSizes 

func (style Style) ScaleAllSizes(scale float32)

ScaleAllSizes applies a scaling factor to all sizes. To scale your entire UI (e.g. if you want your app to use High DPI or generally be DPI aware) you may use this helper function. Scaling the fonts is done separately and is up to you.

Important: This operation is lossy because all sizes are rounded to integer. If you need to change your scale multiples, call this over a freshly initialized style rather than scaling multiple times.

func (Style) SetColor added in v0.2.0 

func (style Style) SetColor(id StyleColorID, value Vec4)

SetColor sets a color value of the UI style.

type StyleColorID added in v0.2.0 

type StyleColorID int

StyleColorID identifies a color in the UI style. 

const (
	StyleColorText StyleColorID = iota
	StyleColorTextDisabled
	StyleColorWindowBg
	StyleColorChildBg
	StyleColorPopupBg
	StyleColorBorder
	StyleColorBorderShadow
	StyleColorFrameBg
	StyleColorFrameBgHovered
	StyleColorFrameBgActive
	StyleColorTitleBg
	StyleColorTitleBgActive
	StyleColorTitleBgCollapsed
	StyleColorMenuBarBg
	StyleColorScrollbarBg
	StyleColorScrollbarGrab
	StyleColorScrollbarGrabHovered
	StyleColorScrollbarGrabActive
	StyleColorCheckMark
	StyleColorSliderGrab
	StyleColorSliderGrabActive
	StyleColorButton
	StyleColorButtonHovered
	StyleColorButtonActive
	StyleColorHeader
	StyleColorHeaderHovered
	StyleColorHeaderActive
	StyleColorSeparator
	StyleColorSeparatorHovered
	StyleColorSeparatorActive
	StyleColorResizeGrip
	StyleColorResizeGripHovered
	StyleColorResizeGripActive
	StyleColorPlotLines
	StyleColorPlotLinesHovered
	StyleColorPlotHistogram
	StyleColorPlotHistogramHovered
	StyleColorTextSelectedBg
	StyleColorModalWindowDarkening
	StyleColorDragDropTarget
	StyleColorNavHighlight
	StyleColorNavWindowingHighlight
)

StyleColor identifier

type StyleVarID added in v0.2.0 

type StyleVarID int

StyleVarID identifies a style variable in the UI style. 

const (
	// StyleVarAlpha is a float
	StyleVarAlpha StyleVarID = iota
	// StyleVarWindowPadding is a Vec2
	StyleVarWindowPadding
	// StyleVarWindowRounding is a float
	StyleVarWindowRounding
	// StyleVarWindowBorderSize is a float
	StyleVarWindowBorderSize
	// StyleVarWindowMinSize is a Vec2
	StyleVarWindowMinSize
	// StyleVarWindowTitleAlign is a Vec2
	StyleVarWindowTitleAlign
	// StyleVarChildRounding is a float
	StyleVarChildRounding
	// StyleVarChildBorderSize is a float
	StyleVarChildBorderSize
	// StyleVarPopupRounding is a float
	StyleVarPopupRounding
	// StyleVarPopupBorderSize is a float
	StyleVarPopupBorderSize
	// StyleVarFramePadding is a Vec2
	StyleVarFramePadding
	// StyleVarFrameRounding is a float
	StyleVarFrameRounding
	// StyleVarFrameBorderSize is a float
	StyleVarFrameBorderSize
	// StyleVarItemSpacing is a Vec2
	StyleVarItemSpacing
	// StyleVarItemInnerSpacing is a Vec2
	StyleVarItemInnerSpacing
	// StyleVarIndentSpacing is a float
	StyleVarIndentSpacing
	// StyleVarScrollbarSize is a float
	StyleVarScrollbarSize
	// StyleVarScrollbarRounding is a float
	StyleVarScrollbarRounding
	// StyleVarGrabMinSize is a float
	StyleVarGrabMinSize
	// StyleVarGrabRounding is a float
	StyleVarGrabRounding
	// StyleVarButtonTextAlign is a Vec2
	StyleVarButtonTextAlign
)

type TextureID 

type TextureID uintptr

TextureID is a user data to identify a texture.

TextureID is a uintptr used to pass renderer-agnostic texture references around until it hits your render function. imgui knows nothing about what those bits represent, it just passes them around. It is up to you to decide what you want the value to carry!

It could be an identifier to your OpenGL texture (cast as uint32), a key to your custom engine material, etc. At the end of the chain, your renderer takes this value to cast it back into whatever it needs to select a current texture to render.

To display a custom image/texture within an imgui window, you may use functions such as imgui.Image(). imgui will generate the geometry and draw calls using the TextureID that you passed and which your renderer can use. It is your responsibility to get textures uploaded to your GPU.

Note: Internally, the value is based on a pointer type, so its size is dependent on your architecture. For the most part, this will be 64bits on current systems (in 2018). Beware: This value must never be a Go pointer, because the value escapes the runtime!

type Vec2 

type Vec2 struct {
	X float32
	Y float32
}

Vec2 represents a two-dimensional vector.

type Vec4 

type Vec4 struct {
	X float32
	Y float32
	Z float32
	W float32
}

Vec4 represents a four-dimensional vector.

Source Files

View all Source files

Directories

Path Synopsis
_examples
opengl3_example

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.