Class ImGuiHelpers

Class containing various helper methods for use with ImGui inside Dalamud.

Assembly: Dalamud.dll

Declaration

public static class ImGuiHelpers

Properties

MainViewport

Gets the main viewport.

Declaration

public static ImGuiViewportPtr MainViewport { get; }

GlobalScale

Gets the global Dalamud scale.

Declaration

public static float GlobalScale { get; }

IsImGuiInitialized

Gets a value indicating whether ImGui is initialized and ready for use.

This does not necessarily mean you can call drawing functions.

Declaration

public static bool IsImGuiInitialized { get; }

GlobalScaleSafe

Gets the global Dalamud scale; even available before drawing is ready.

If you are sure that drawing is ready, at the point of using this, use Dalamud.Interface.Utility.ImGuiHelpers.GlobalScale instead.

Declaration

public static float GlobalScaleSafe { get; }

Methods

CheckIsWindowOnMainViewport()

Check if the current ImGui window is on the main viewport. Only valid within a window.

Declaration

public static bool CheckIsWindowOnMainViewport()

Returns

System.Boolean: Whether the window is on the main viewport.

ScaledVector2(float)

Gets a System.Numerics.Vector2 that is pre-scaled with the Dalamud.Interface.Utility.ImGuiHelpers.GlobalScale multiplier.

Declaration

public static Vector2 ScaledVector2(float x)

Returns

System.Numerics.Vector2: A scaled Vector2.

Parameters

Type	Name	Description
System.Single	x	Vector2 X/Y parameter.

ScaledVector2(float, float)

Gets a System.Numerics.Vector2 that is pre-scaled with the Dalamud.Interface.Utility.ImGuiHelpers.GlobalScale multiplier.

Declaration

public static Vector2 ScaledVector2(float x, float y)

Returns

System.Numerics.Vector2: A scaled Vector2.

Parameters

Type	Name	Description
System.Single	x	Vector2 X parameter.
System.Single	y	Vector2 Y parameter.

ScaledVector4(float, float, float, float)

Gets a System.Numerics.Vector4 that is pre-scaled with the Dalamud.Interface.Utility.ImGuiHelpers.GlobalScale multiplier.

Declaration

public static Vector4 ScaledVector4(float x, float y, float z, float w)

Returns

System.Numerics.Vector4: A scaled Vector2.

Parameters

Type	Name	Description
System.Single	x	Vector4 X parameter.
System.Single	y	Vector4 Y parameter.
System.Single	z	Vector4 Z parameter.
System.Single	w	Vector4 W parameter.

ForceNextWindowMainViewport()

Force the next ImGui window to stay inside the main game window.

Declaration

public static void ForceNextWindowMainViewport()

AddBlurBehind(ImDrawListPtr, Vector2, Vector2, float, float, Vector4, Vector4, float)

Adds a blur-behind region to an ImGui draw list. Optionally applies a luminosity blend, color tint and grain noise.

Declaration

public static void AddBlurBehind(ImDrawListPtr drawList, Vector2 min, Vector2 max, float blurStrength = 1.5, float rounding = 4, Vector4 tintColor = default, Vector4 luminosityColor = default, float noiseOpacity = 0.17)

Parameters

Type	Name	Description
Dalamud.Bindings.ImGui.ImDrawListPtr	drawList	Target draw list. For windows, you may want to use Dalamud.Interface.Utility.ImGuiHelpers.PrependBlurBehind(Dalamud.Bindings.ImGui.ImDrawListPtr,System.Numerics.Vector2,System.Numerics.Vector2,System.Single,System.Single,System.Numerics.Vector4,System.Numerics.Vector4,System.Single), since calling this after ImGui.Begin()
will affect the title bar and the window background.
System.Numerics.Vector2	min	Top-left corner of the blur region in display (screen) coordinates.
System.Numerics.Vector2	max	Bottom-right corner of the blur region in display (screen) coordinates.
System.Single	blurStrength	Controls the strength of the blur. Higher values produce stronger blur.
System.Single	rounding	Corner radius of the rounded-rectangle mask in pixels.
Use 0 for sharp corners, or match the value from ImGui.GetStyle().WindowRounding
to align with the window border.
System.Numerics.Vector4	tintColor	Tint color (RGB) and tint blend strength (A in [0, 1]).
A = 0 (default) means no tint is applied.
System.Numerics.Vector4	luminosityColor	Luminosity target color (RGB) and blend strength (A in [0, 1]).
The luminosity step reduces contrast in the blurred image by replacing its lightness with the
target's lightness.
A = 0 (default) skips the step. A typical value is around 0.64–0.85.
System.Single	noiseOpacity	Opacity of the tiled noise grain layer composited on top, in [0, 1].
Defaults to an aesthetically pleasing value that was scientifically determined by the implementor
Pass 0 to disable grain.

PrependBlurBehind(ImDrawListPtr, Vector2, Vector2, float, float, Vector4, Vector4, float)

Like Dalamud.Interface.Utility.ImGuiHelpers.AddBlurBehind(Dalamud.Bindings.ImGui.ImDrawListPtr,System.Numerics.Vector2,System.Numerics.Vector2,System.Single,System.Single,System.Numerics.Vector4,System.Numerics.Vector4,System.Single), but inserts the blur callback at index 0 of the draw list's command buffer so that it fires before all other draw commands. This is the correct variant to use from within a window, because it preserves z-order. Each window's blur fires after all lower-z windows have been rendered to the RT, so an overlapping blurred window correctly captures the window behind it rather than only the game.

Declaration

public static void PrependBlurBehind(ImDrawListPtr drawList, Vector2 min, Vector2 max, float blurStrength = 1.5, float rounding = 4, Vector4 tintColor = default, Vector4 luminosityColor = default, float noiseOpacity = 0.17)

Parameters

Type	Name	Description
Dalamud.Bindings.ImGui.ImDrawListPtr	drawList	The drawlist to prepend the blur command to. Usually the window drawlist.
System.Numerics.Vector2	min	Top-left corner of the blur region in display (screen) coordinates.
System.Numerics.Vector2	max	Bottom-right corner of the blur region in display (screen) coordinates.
System.Single	blurStrength	Controls the strength of the blur. Higher values produce stronger blur.
System.Single	rounding	Corner radius of the rounded-rectangle mask in pixels.
System.Numerics.Vector4	tintColor	Tint colour RGB and blend strength A. A=0 disables the tint.
System.Numerics.Vector4	luminosityColor	Luminosity target RGB and blend strength A. A=0 skips the step.
System.Single	noiseOpacity	Noise grain opacity [0, 1]. Defaults to an aesthetically pleasing value that was scientifically determined by the implementor.

ScaledDummy(float)

Create a dummy scaled by the global Dalamud scale.

Declaration

public static void ScaledDummy(float size)

Parameters

Type	Name	Description
System.Single	size	The size of the dummy.

ScaledDummy(float, float)

Create a dummy scaled by the global Dalamud scale.

Declaration

public static void ScaledDummy(float x, float y)

Parameters

Type	Name	Description
System.Single	x	Vector2 X parameter.
System.Single	y	Vector2 Y parameter.

ScaledDummy(Vector2)

Create a dummy scaled by the global Dalamud scale.

Declaration

public static void ScaledDummy(Vector2 size)

Parameters

Type	Name	Description
System.Numerics.Vector2	size	The size of the dummy.

ScaledIndent(float)

Create an indent scaled by the global Dalamud scale.

Declaration

public static void ScaledIndent(float size)

Parameters

Type	Name	Description
System.Single	size	The size of the indent.

ScaledRelativeSameLine(float, float)

Use a relative ImGui.SameLine() from your current cursor position, scaled by the Dalamud global scale.

Declaration

public static void ScaledRelativeSameLine(float offset, float spacing = -1)

Parameters

Type	Name	Description
System.Single	offset	The offset from your current cursor position.
System.Single	spacing	The spacing to use.

SetNextWindowPosRelativeMainViewport(Vector2, ImGuiCond, Vector2)

Set the position of the next window relative to the main viewport.

Declaration

public static void SetNextWindowPosRelativeMainViewport(Vector2 position, ImGuiCond condition = ImGuiCond.None, Vector2 pivot = default)

Parameters

Type	Name	Description
System.Numerics.Vector2	position	The position of the next window.
Dalamud.Bindings.ImGui.ImGuiCond	condition	When to set the position.
System.Numerics.Vector2	pivot	The pivot to set the position around.

SetWindowPosRelativeMainViewport(ImU8String, Vector2, ImGuiCond)

Set the position of a window relative to the main viewport.

Declaration

public static void SetWindowPosRelativeMainViewport(ImU8String name, Vector2 position, ImGuiCond condition = ImGuiCond.None)

Parameters

Type	Name	Description
Dalamud.Bindings.ImGui.ImU8String	name	The name/ID of the window.
System.Numerics.Vector2	position	The position of the window.
Dalamud.Bindings.ImGui.ImGuiCond	condition	When to set the position.

DefaultColorPalette(int)

Creates default color palette for use with color pickers.

Declaration

public static List<Vector4> DefaultColorPalette(int swatchCount = 32)

Returns

System.Collections.Generic.List<System.Numerics.Vector4>: Default color palette.

Parameters

Type	Name	Description
System.Int32	swatchCount	The total number of swatches to use.

GetButtonSize(ImU8String)

Get the size of a button considering the default frame padding.

Declaration

public static Vector2 GetButtonSize(ImU8String text)

Returns

System.Numerics.Vector2: System.Numerics.Vector2 with the size of the button.

Parameters

Type	Name	Description
Dalamud.Bindings.ImGui.ImU8String	text	Text in the button.

ClickToCopyText(ImU8String, ImU8String, Vector4?)

Print out text that can be copied when clicked.

Declaration

public static void ClickToCopyText(ImU8String text, ImU8String textCopy = default, Vector4? color = null)

Parameters

Type	Name	Description
Dalamud.Bindings.ImGui.ImU8String	text	The text to show.
Dalamud.Bindings.ImGui.ImU8String	textCopy	The text to copy when clicked.
System.Nullable<System.Numerics.Vector4>	color	The color of the text.

SeStringWrapped(ReadOnlySpan<byte>, scoped in SeStringDrawParams, ImGuiId, ImGuiButtonFlags)

Draws a SeString.

Declaration

public static SeStringDrawResult SeStringWrapped(ReadOnlySpan<byte> sss, scoped in SeStringDrawParams style = default, ImGuiId imGuiId = default, ImGuiButtonFlags buttonFlags = ImGuiButtonFlags.MouseButtonDefault)

Returns

Dalamud.Interface.ImGuiSeStringRenderer.SeStringDrawResult: Interaction result of the rendered text.

Parameters

Type	Name	Description
System.ReadOnlySpan<System.Byte>	sss	SeString to draw.
Dalamud.Interface.ImGuiSeStringRenderer.SeStringDrawParams	style	Initial rendering style.
Dalamud.Interface.Utility.ImGuiId	imGuiId	ImGui ID, if link functionality is desired.
Dalamud.Bindings.ImGui.ImGuiButtonFlags	buttonFlags	Button flags to use on link interaction.

CompileSeStringWrapped(string, scoped in SeStringDrawParams, ImGuiId, ImGuiButtonFlags)

Creates and caches a SeString from a text macro representation, and then draws it.

Declaration

public static SeStringDrawResult CompileSeStringWrapped(string text, scoped in SeStringDrawParams style = default, ImGuiId imGuiId = default, ImGuiButtonFlags buttonFlags = ImGuiButtonFlags.MouseButtonDefault)

Returns

Dalamud.Interface.ImGuiSeStringRenderer.SeStringDrawResult: Interaction result of the rendered text.

Parameters

Type	Name	Description
System.String	text	SeString text macro representation.

        Newline characters will be normalized to [Dalamud.Game.Text.SeStringHandling.Payloads.NewLinePayload](../../Dalamud.Game.Text.SeStringHandling.Payloads/Classes/NewLinePayload.md). |

| Dalamud.Interface.ImGuiSeStringRenderer.SeStringDrawParams | style | Initial rendering style. | | Dalamud.Interface.Utility.ImGuiId | imGuiId | ImGui ID, if link functionality is desired. | | Dalamud.Bindings.ImGui.ImGuiButtonFlags | buttonFlags | Button flags to use on link interaction. |

SafeTextWrapped(ImU8String)

Write unformatted text wrapped.

Declaration

[Obsolete("Use ImGui.TextWrapped. It's safe now.", true)]
public static void SafeTextWrapped(ImU8String text)

Parameters

Type	Name	Description
Dalamud.Bindings.ImGui.ImU8String	text	The text to write.

SafeTextColoredWrapped(Vector4, ImU8String)

Write colored, unformatted text wrapped.

Declaration

[Obsolete("Use ImGui.TextColoredWrapped. It's safe.", true)]
public static void SafeTextColoredWrapped(Vector4 color, ImU8String text)

Parameters

Type	Name	Description
System.Numerics.Vector4	color	The color of the text.
Dalamud.Bindings.ImGui.ImU8String	text	The text to write.

AdjustGlyphMetrics(ImFontPtr, float, float)

Unscales fonts after they have been rendered onto atlas.

Declaration

public static void AdjustGlyphMetrics(this ImFontPtr fontPtr, float scale, float round = 0)

Parameters

Type	Name	Description
Dalamud.Bindings.ImGui.ImFontPtr	fontPtr	Font to scale.
System.Single	scale	Scale.
System.Single	round	If a positive number is given, numbers will be rounded to this.

CopyGlyphsAcrossFonts(ImFontPtr?, ImFontPtr?, bool, bool, int, int)

Fills missing glyphs in target font from source font, if both are not null.

Declaration

[Obsolete("Use the non-nullable variant.", true)]
public static void CopyGlyphsAcrossFonts(ImFontPtr? source, ImFontPtr? target, bool missingOnly, bool rebuildLookupTable = true, int rangeLow = 32, int rangeHigh = 65534)

Parameters

Type	Name	Description
System.Nullable<Dalamud.Bindings.ImGui.ImFontPtr>	source	Source font.
System.Nullable<Dalamud.Bindings.ImGui.ImFontPtr>	target	Target font.
System.Boolean	missingOnly	Whether to copy missing glyphs only.
System.Boolean	rebuildLookupTable	Whether to call target.BuildLookupTable().
System.Int32	rangeLow	Low codepoint range to copy.
System.Int32	rangeHigh	High codepoing range to copy.

CopyGlyphsAcrossFonts(ImFontPtr, ImFontPtr, bool, bool, int, int)

Fills missing glyphs in target font from source font, if both are not null.

Declaration

public static void CopyGlyphsAcrossFonts(ImFontPtr source, ImFontPtr target, bool missingOnly, bool rebuildLookupTable = true, int rangeLow = 32, int rangeHigh = 65534)

Parameters

Type	Name	Description
Dalamud.Bindings.ImGui.ImFontPtr	source	Source font.
Dalamud.Bindings.ImGui.ImFontPtr	target	Target font.
System.Boolean	missingOnly	Whether to copy missing glyphs only.
System.Boolean	rebuildLookupTable	Whether to call target.BuildLookupTable().
System.Int32	rangeLow	Low codepoint range to copy.
System.Int32	rangeHigh	High codepoing range to copy.

VirtualKeyToImGuiKey(VirtualKey)

Map a VirtualKey keycode to an ImGuiKey enum value.

Declaration

public static ImGuiKey VirtualKeyToImGuiKey(VirtualKey key)

Returns

Dalamud.Bindings.ImGui.ImGuiKey: The ImGuiKey that corresponds to this VirtualKey, or ImGuiKey.None otherwise.

Parameters

Type	Name	Description
Dalamud.Game.ClientState.Keys.VirtualKey	key	The VirtualKey value to retrieve the ImGuiKey counterpart for.

ImGuiKeyToVirtualKey(ImGuiKey)

Map an ImGuiKey enum value to a VirtualKey code.

Declaration

public static VirtualKey ImGuiKeyToVirtualKey(ImGuiKey key)

Returns

Dalamud.Game.ClientState.Keys.VirtualKey: The VirtualKey that corresponds to this ImGuiKey, or VirtualKey.NO_KEY otherwise.

Parameters

Type	Name	Description
Dalamud.Bindings.ImGui.ImGuiKey	key	The ImGuiKey value to retrieve the VirtualKey counterpart for.

CenteredText(ImU8String)

Show centered text.

Declaration

public static void CenteredText(ImU8String text)

Parameters

Type	Name	Description
Dalamud.Bindings.ImGui.ImU8String	text	Text to show.

CenterCursorForText(ImU8String)

Center the ImGui cursor for a certain text.

Declaration

public static void CenterCursorForText(ImU8String text)

Parameters

Type	Name	Description
Dalamud.Bindings.ImGui.ImU8String	text	The text to center for.

CenterCursorFor(float)

Center the ImGui cursor for an item with a certain width.

Declaration

public static void CenterCursorFor(float itemWidth)

Parameters

Type	Name	Description
System.Single	itemWidth	The width to center for.

BeginHorizontalButtonGroup()

Starts a new horizontal button group.

Declaration

public static ImGuiHelpers.HorizontalButtonGroup BeginHorizontalButtonGroup()

Returns

Dalamud.Interface.Utility.ImGuiHelpers.HorizontalButtonGroup: The group.

AllocateMemory(nuint)

Allocates memory on the heap using Dalamud.Bindings.ImGui.ImGui.MemAlloc(System.UIntPtr)

Memory must be freed using Dalamud.Bindings.ImGui.ImGui.MemFree(System.Void*).

Note that null is a valid return value when <code class="paramref">length</code> is 0.

Declaration

public static void* AllocateMemory(nuint length)

Returns

System.Void*: The allocated memory.

Parameters

Type	Name	Description
System.UIntPtr	length	The length of allocated memory.

Exceptions

System.OutOfMemoryException
If Dalamud.Bindings.ImGui.ImGui.MemAlloc(System.UIntPtr) returns null.

NewFontGlyphRangeBuilderPtrScoped(out ImFontGlyphRangesBuilderPtr)

Creates a new instance of Dalamud.Bindings.ImGui.ImFontGlyphRangesBuilderPtr with a natively backed memory.

Declaration

public static IDisposable NewFontGlyphRangeBuilderPtrScoped(out ImFontGlyphRangesBuilderPtr builder)

Returns

System.IDisposable: Disposable you can call.

Parameters

Type	Name	Description
Dalamud.Bindings.ImGui.ImFontGlyphRangesBuilderPtr	builder	The created instance.

BuildRangesToArray(ImFontGlyphRangesBuilderPtr, bool, bool)

Builds ImGui Glyph Ranges for use with Dalamud.Interface.ManagedFontAtlas.SafeFontConfig.GlyphRanges.

Declaration

public static ushort[] BuildRangesToArray(this ImFontGlyphRangesBuilderPtr builder, bool addFallbackCodepoints = true, bool addEllipsisCodepoints = true)

Returns

System.UInt16[]: When disposed, the resource allocated for the range will be freed.

Parameters

Type	Name	Description
Dalamud.Bindings.ImGui.ImFontGlyphRangesBuilderPtr	builder	The builder.
System.Boolean	addFallbackCodepoints	Add fallback codepoints to the range.
System.Boolean	addEllipsisCodepoints	Add ellipsis codepoints to the range.

CreateImGuiRangesFrom(params UnicodeRange[])

Creates glyph ranges from System.Text.Unicode.UnicodeRange.

Use values from System.Text.Unicode.UnicodeRanges.

Declaration

public static ushort[] CreateImGuiRangesFrom(params UnicodeRange[] ranges)

Returns

System.UInt16[]: The range array that can be used for Dalamud.Interface.ManagedFontAtlas.SafeFontConfig.GlyphRanges.

Parameters

Type	Name	Description
System.Text.Unicode.UnicodeRange[]	ranges	The unicode ranges.

CreateImGuiRangesFrom(IEnumerable<UnicodeRange>)

Creates glyph ranges from System.Text.Unicode.UnicodeRange.

Use values from System.Text.Unicode.UnicodeRanges.

Declaration

public static ushort[] CreateImGuiRangesFrom(IEnumerable<UnicodeRange> ranges)

Returns

System.UInt16[]: The range array that can be used for Dalamud.Interface.ManagedFontAtlas.SafeFontConfig.GlyphRanges.

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<System.Text.Unicode.UnicodeRange>	ranges	The unicode ranges.

IsNotNullAndLoaded(ImFontPtr)

Determines whether <code class="paramref">ptr</code> is not empty and loaded.

Declaration

public static bool IsNotNullAndLoaded(this ImFontPtr ptr)

Returns

System.Boolean: Whether it is not null and loaded.

Parameters

Type	Name	Description
Dalamud.Bindings.ImGui.ImFontPtr	ptr	The pointer.

OrElse(ImFontPtr, ImFontPtr)

If <code class="paramref">self</code> is default, then returns <code class="paramref">other</code>.

Declaration

public static ImFontPtr OrElse(this ImFontPtr self, ImFontPtr other)

Returns

Dalamud.Bindings.ImGui.ImFontPtr: <code class="paramref">self</code> if it is not default; otherwise, <code class="paramref">other</code>.

Parameters

Type	Name	Description
Dalamud.Bindings.ImGui.ImFontPtr	self	The self.
Dalamud.Bindings.ImGui.ImFontPtr	other	The other.