ReaImGui: ReaScript binding for Dear ImGui

[cfillion]

Originally Posted by jbradbury

I have just made a DEBUG build on my system (your instructions are really good by the way! A rarity).

I was able to get something to appear by following your advice, however, I cannot close this black window in the dock and if I run the script without the docking code in there, then modify the code to work with the docking API the old behaviour takes over again and nothing happens.

Thanks! I pushed a fix, can you check whether it improves things on your end?

[jbradbury]

Originally Posted by cfillion

Thanks! I pushed a fix, can you check whether it improves things on your end?

That seems to have fixed it checking out on 2585715 and building a debug build

Now I just need to get my windows all flush with the new API. Thanks for all your help with this. Hopefully I can contribute back at some point.

[cfillion]

Released version 0.5.2:

• Documentation: group all functions and constants by category
• Documentation: hide write-only arguments from the Lua and Python signatures
• Documentation: omit printing "double" type for arguments in EEL signatures
• macOS: fix REAPER's defer timer stopping on Big Sur [p=2458897]

[daniellumertz]

congrats on keeping it update! I am not coding at the moment, but everytime I see a update here it gives me desire to go and do something. Really inspiring!

Question, what is this documentation you showed in the last post? Is it from the help menu on reaper or there is a site or a UI somewhere now?

[cfillion]

Originally Posted by daniellumertz

Question, what is this documentation you showed in the last post? Is it from the help menu on reaper or there is a site or a UI somewhere now?

It's accessible from the demo -> Tools -> Documentation (or opening <resource path>/Data/reaper_imgui_doc.html).

EDIT: Added to the first post.

[daniellumertz]

Hey cfillion just seen the docs, it is incredible thanks for the hard hard work! I am updating my scripts to match the new update as some code lose backward copatible. But I liked the changes, nice design choices! Hope to get at it again I just love programming with it.

[daniellumertz]

Some doubts

Are some info being stored in Imgui extension?
I have a script that is crashing when I click on the hide window button(the arrow on the upper left). That is not what I think is strange. The strange part is next time I run I don't have the same behaiviour actually the script just crash. And only return when I change the second argument on ImGui_Begin.
Edit: In my research yes, it makes sense. And I was able to correct my error

Also in the docs of ImGui_Begin the third argument is just described as nil.

EDIT: About the collapse crashing I havent found out why it is not working, but what I seem to notice in the demo script is that it stop looping in the deefer when is collapsed is it right? That means I need to have a defer over a defer like in the demo. Is there a simpler way? I am writing the simplest blank gui possible, I really like the demo script but is too much, and because there is too much in there the code is good for big projects like making use of tables for a lot of things. For some of this things it is difficult to use in small projects, would be nice smaller exemples with different coding views. Trying to do some here and will post
Update: I'm dumb and didn't saw the small exemples in the first post. But the good news is I made a script to work in the same model of the big demo (with a function to keep or kill it)

[daniellumertz]

Exemple of a minimal GUI in 0.5.2. I am thinking in update the minial post on the first page as it might put some people off tracks

----------------------------------------
---------------------Gui CTX
---------------------------------------
local ctx = reaper.ImGui_CreateContext('S.Organizer')

---------------------------------------
----------------------Defining GUI FUNCTIONS (functions to be used in GUI LOOP)
---------------------------------------
--Exemple:
function HelpMarker(desc) -- Function to show a ?
    reaper.ImGui_TextDisabled(ctx, '(?)')
    if reaper.ImGui_IsItemHovered(ctx) then
    reaper.ImGui_BeginTooltip(ctx)
    reaper.ImGui_PushTextWrapPos(ctx, reaper.ImGui_GetFontSize(ctx) * 35.0)
    reaper.ImGui_Text(ctx, desc)
    reaper.ImGui_PopTextWrapPos(ctx)
    reaper.ImGui_EndTooltip(ctx)
    end
end

---------------------------------------
----------------------GUI LOOP (Where you write your Gui)
---------------------------------------
function loop()
    ------------ Windows Flags & Configs (Here you set some window configs) (Some will be flags that will feed the ImGui_Begin and other are action for NextWindows) 
    --Exemple:
    local flags = reaper.ImGui_WindowFlags_MenuBar()   -- Add Menu bar and remove the rezise feature. 
    -- flags = reaper.ImGui_WindowFlags_MenuBar() | reaper.ImGui_WindowFlags_NoCollapse() -- To add more flags put other actions with | between like this line  

    reaper.ImGui_SetNextWindowPos(ctx, 0, 0, reaper.ImGui_Cond_FirstUseEver())-- Set the position of the windows.  Use in the 4th argument reaper.ImGui_Cond_FirstUseEver() to just apply at the first user run, so ImGUI remembers user position s2
    reaper.ImGui_SetNextWindowSize(ctx, 200, 400, reaper.ImGui_Cond_Once())-- Set the size of the windows.  Use in the 4th argument reaper.ImGui_Cond_FirstUseEver() to just apply at the first user run, so ImGUI remembers user resize s2
    
   
    ------------Begin
    local visible, open = reaper.ImGui_Begin(ctx, 'Minimal GUI', true, flags) -- the 3rd argument show/hide the close button
    if not visible then return open end -- Stop Here if minimized

    
    
    --------------GUI
    --Exemple:
    HelpMarker("A slim GUI")
    
    ------------- Ending
    reaper.ImGui_End(ctx)
    return open
end
---------------------------------------
----------------------GUI KEEPER (It decides to keep gui running or closes it)
---------------------------------------
function gui_keeper()
    local run = loop()
    if run then
        reaper.defer(gui_keeper)
    else
        reaper.ImGui_DestroyContext(ctx)
    end
end

--SCRIPT

reaper.defer(gui_keeper)

In the "model" of the small scripts (with what keeps or close the script inside the GUI loop)

 
----------------------------------------
---------------------Gui CTX
---------------------------------------
local ctx = reaper.ImGui_CreateContext('S.Organizer')

---------------------------------------
----------------------Defining GUI FUNCTIONS (functions to be used in GUI LOOP)
---------------------------------------
--Exemple:
function HelpMarker(desc) -- Function to show a ?
    reaper.ImGui_TextDisabled(ctx, '(?)')
    if reaper.ImGui_IsItemHovered(ctx) then
    reaper.ImGui_BeginTooltip(ctx)
    reaper.ImGui_PushTextWrapPos(ctx, reaper.ImGui_GetFontSize(ctx) * 35.0)
    reaper.ImGui_Text(ctx, desc)
    reaper.ImGui_PopTextWrapPos(ctx)
    reaper.ImGui_EndTooltip(ctx)
    end
end

---------------------------------------
----------------------GUI LOOP (Where you write your Gui)
---------------------------------------
function loop()
    ------------ Windows Flags & Configs (Here you set some window configs) (Some will be flags that will feed the ImGui_Begin and other are action for NextWindows) 
    --Exemple:
    local flags = reaper.ImGui_WindowFlags_MenuBar()   -- Add Menu bar and remove the rezise feature. 
    -- flags = reaper.ImGui_WindowFlags_MenuBar() | reaper.ImGui_WindowFlags_NoCollapse() -- To add more flags put other actions with | between like this line  

    reaper.ImGui_SetNextWindowPos(ctx, 0, 0, reaper.ImGui_Cond_FirstUseEver())-- Set the position of the windows.  Use in the 4th argument reaper.ImGui_Cond_FirstUseEver() to just apply at the first user run, so ImGUI remembers user position s2
    reaper.ImGui_SetNextWindowSize(ctx, 200, 400, reaper.ImGui_Cond_Once())-- Set the size of the windows.  Use in the 4th argument reaper.ImGui_Cond_FirstUseEver() to just apply at the first user run, so ImGUI remembers user resize s2
    
   
    ------------Begin
    local visible, open = reaper.ImGui_Begin(ctx, 'Minimal GUI', true, flags) -- the 3rd argument show/hide the close button
    if  visible then
        --------------GUI
        --Exemple:
        HelpMarker("A slim GUI")
        
        ------------- Ending
        reaper.ImGui_End(ctx)
    end

    ------------- Keep or Close
    if open then
        reaper.defer(loop)
    else
        reaper.ImGui_DestroyContext(ctx)
    end
end


--SCRIPT
reaper.defer(loop)

I still exploring to see the new but thanks a lot it is really working fine!

[cfillion]

Originally Posted by daniellumertz

Are some info being stored in Imgui extension?

Window position, size, docking state and table settings are persisted. This data is linked to the name argument given to CreateContext. (This can be disabled either completely, per-window or per-table using the corresponding NoSavedSettings flag.)

Originally Posted by daniellumertz

Also in the docs of ImGui_Begin the third argument is just described as nil.

Ah yes, every p_open/p_visible arguments are marked as write-only instead of read-write. Fixing!

(Write-only arguments, aka return values, are documented as nil on purpose, as their input values are unused.)

Originally Posted by daniellumertz

EDIT: About the collapse crashing [...]

End() must be called only if Begin() returned true. See the v0.4 -> v0.5 upgrade tips at https://forum.cockos.com/showthread.php?p=2455336. But looks like you've figured it out.

[daniellumertz]

Yeah man! the last hours passed so fast, I was just digging the updates really nice! Also testing the Python version of imgui, this thing is huuuge... Thanks a lot for your work, I really think this is one of the nicest improvement Reaper had this year!

[Rodilab]

Hello,

I noticed that if the window is unfocus, then the right click does not give the focus.
So you can't right click directly, it first left click somewhere then right click. This must be very annoying for some scripts.

I don't remember if this was already the case on older versions of ReaImGui.

Is there a way to avoid this?

[ccdsache]

hi guys~~~sos~is there any way dock the window on the one side（up/donw/left/right）,like the gfx.dock(number) do, maybe this could be one kind of feature request，hahaha~ thx

[Rodilab]

Yes, with ImGui_SetNextWindowDockID.
See the "Window options" in Dear ImGui Demo script.

[daniellumertz]

Just want to share a function I did to get the center of the plot bars. usefull to draw some text over it
like this:

 
    function GetBarsCenterX(width, num_bars) -- list x_values = GetBarsCenterX(width, num_bars).  x_values = each bar center x position FROM the START of the PLOT. width = width of the plot. num_bars = number of bars in the plot
        local plot_pad = 4
        local bar_area_w = width - ((num_bars-1) + (2 * plot_pad))
        local bar_w = bar_area_w / num_bars
        local list = {} -- List of X based on start of plot
        for i = 1, num_bars do
            if i == 1 then 
                list[1] = 4 + (bar_w/2)
            else
                list[i] =  list[i-1] + bar_w + 1 
            end
        end
        return list
    end

Edit: Released the script if anyone interested https://forum.cockos.com/showthread....41#post2461641

[cfillion]

Originally Posted by Rodilab

I noticed that if the window is unfocus, then the right click does not give the focus.
So you can't right click directly, it first left click somewhere then right click. This must be very annoying for some scripts.

Not changing focus when right-clicking is a Dear ImGui feature.

However, there are two bugs responsible for popups failing to open on right click when none of the windows in the context have focus. The first bug is in ReaImGui and happens only on macOS, and the second bug is in upstream Dear ImGui. Fixing the former and reported the later: https://github.com/ocornut/imgui/issues/4308.

[Rodilab]

Ok, thanks cfillion.
I hope Dear ImGui will correct this point.

One more thing :
If I quit Reaper before quit the script, then ReaImGui don't save the last position, size and dockID.
Is this normal ?

Thanks again

[cfillion]

Originally Posted by Rodilab

If I quit Reaper before quit the script, then ReaImGui don't save the last position, size and dockID.

Adding support for saving when REAPER exits. (Settings are saved 5 seconds after they stop changing, so only very recent changes are currently lost when quitting.)

[kotll]

Hello, I'm having some trouble understanding what ImGui_WindowFlags_NoBringToFrontOnFocus does

I'm trying to create a window that always stays in the background and never gets bought in front of any other Reaper window, but passing ImGui_WindowFlags_NoBringToFrontOnFocus() to ImGui_Begin() doesn't seem to do anything, the window still gets sent to the front when I click on it. Is this normal behaviour?

[cfillion]

Originally Posted by kotll

Hello, I'm having some trouble understanding what ImGui_WindowFlags_NoBringToFrontOnFocus does

I'm trying to create a window that always stays in the background and never gets bought in front of any other Reaper window, but passing ImGui_WindowFlags_NoBringToFrontOnFocus() to ImGui_Begin() doesn't seem to do anything, the window still gets sent to the front when I click on it. Is this normal behaviour?

NoBringToFrontOnFocus has no effect since v0.5 switched from virtual windows to system-managed windows. I'll un-expose that flag from the API.

[ccdsache]

Originally Posted by Rodilab

Yes, with ImGui_SetNextWindowDockID.
See the "Window options" in Dear ImGui Demo script.

yeah~ found the reaper.ImGui_SetDock~~~too careless ... thx man~

[cfillion]

Released v0.5.3:

• Demo: improve ImGui docker handling in the docking example
• Docking: don't recreate the platform window when switching active ImGui window in the same dock
• Docking: keep docker open if there are other windows sharing it when undocking a window by dragging
• Documentation: mark p_* arguments as both read and write [p=2459747]
• Documentation: use Consolas font to improve readability on Windows
• Font: enable loading color data from fonts
• Font: report font loading errors in the first function call of the frame
• macOS: give focus to the platform window under mouse on right/middle click [p=2460594]
• Save settings of active contexts when unloading the extension [p=2461792]

API changes:
• Remove WindowFlags_NoBringToFrontOnFocus (no-op since v0.5) [p=2462354]

[Rodilab]

Thanks for this update
But "macOS: give focus to the platform window under mouse on right/middle click" doesn't work here. Idon't know why.
Mac 10.15.7

[cfillion]

Originally Posted by Rodilab

"macOS: give focus to the platform window under mouse on right/middle click" doesn't work here. Idon't know why.

That only gives focus to the OS-level window, not to the ImGui window hosted within. (Or did you mean that the windows are not brought to the foreground on your system?)

It should however partially resolve the problem with popups not opening on right click. The remaining bug on Dear ImGui's side can be worked around by calling OpenPopup before BeginPopup (or using the shortcut function BeginPopupContextItem).

[Rodilab]

can be worked around by calling OpenPopup before BeginPopup

Ok, thanks. That was my problem

[kartalex]

Images in ReaImGUI... we need them very, very badly

[cfillion]

Originally Posted by kartalex

Images in ReaImGUI... we need them very, very badly

Adding bitmap image support is on the list of things I want to do. No ETA since it's going to be a lot of work...

Currently, flat vector icons/images can be drawn using OpenType TT fonts (with color layers in COLR/CPAL format, v0.5.3+).



(At this time, ReaImGui rasterizes glyphs only from the Basic Latin and Latin Supplement Unicode blocks.)

[poulhoi]

I'm having some problems with undo states when creating them within a ReaImGui script. My script is a search bar gui for finding tracks to create sends to from the selected track. When I have created a send with a track, I can undo creating the send but not redo it after. I expect this is because I somehow don't understand reaper.Undo_BeginBlock() but I hope it's all right that I post in here regardless.

This is the code in its current state:

-- CONFIG
local searchRate = 0.05 
local autoCloseDefault = true

local tracks  = {}
local trackNames = {}
local trackNamesLower = {}
local hits = {}
local first, refresh = true, true
local clock = os.clock()
local autoClose = autoCloseDefault

function init()
	for i = 1, reaper.CountTracks(0) do
		local track = reaper.GetTrack(0, i-1)
		tracks[i] = track
		local _, name = reaper.GetSetMediaTrackInfo_String(track, "P_NAME", '', false)
		trackNames[i] = name
		trackNamesLower[i] = name:lower() --make all lowercase
	end
end

function ShowWindow()
	if not ctx then
		ctx = reaper.ImGui_CreateContext('phoi_Send to track', reaper.ImGui_ConfigFlags_None())
	end
	local rv, open = nil, true
--  reaper.ImGui_SetNextWindowPos(ctx, 500, 500)
--  reaper.ImGui_SetNextWindowSize(ctx, 500, 440)
	rv, open = reaper.ImGui_Begin(ctx, 'phoi_Send to track', open, reaper.ImGui_WindowFlags_None())
	if not rv then return open end

	local openSendPrefs = reaper.ImGui_Button(ctx, 'Send preferences...') -- button to open send preferences
	if openSendPrefs then
		reaper.ViewPrefs(0x0b2, '')
	end	
	reaper.ImGui_SameLine(ctx)
	local autoCloseSwitch = reaper.ImGui_Checkbox(ctx, 'Auto-close?', autoClose)
	if autoCloseSwitch then
		autoClose = not autoClose
		msg(autoClose)
	end

	if not oldText then oldText = '' end
	if first then reaper.ImGui_SetKeyboardFocusHere(ctx, 0) end
	reaper.ImGui_Dummy(ctx, 100, 10)
	local rv, text = reaper.ImGui_InputText(ctx, '<- Search!', oldText, reaper.ImGui_InputTextFlags_None())
	if refresh then
		local search = text:lower()
		local searchWords = {}
		for word in search:gmatch('[^%s]*') do
			searchWords[#searchWords+1] = word
		end
		
		hits = {}
		for i = 1, #tracks do
			local name = trackNamesLower[i]
			for j = 1, #searchWords do
				if name:find(searchWords[j]) then
					hits[#hits+1] = i -- store only the index
					break
				end
			end
		end
		refresh = false
	else
		local delta = os.clock() - clock
		if delta >= searchRate then
			refresh = true
			clock = os.clock()
		end
	end

	oldText = text
	reaper.ImGui_Dummy(ctx, 100, 10)
	local oops = false
	local function CreateSend(destTrack)
		reaper.Undo_BeginBlock()
		local trackCount = reaper.CountSelectedTracks(0)
		if trackCount < 1 then 
			oops = true
			return 
		end
		local targetTrackName

		if trackCount > 1 then
			targetTrackName = 'multiple tracks'
		else
			_, targetTrackName = reaper.GetSetMediaTrackInfo_String(reaper.GetSelectedTrack(0, 0), 'P_NAME', '', false)
		end

		local _, destTrackName = reaper.GetSetMediaTrackInfo_String(destTrack, 'P_NAME', '', false)

		for j = 0, trackCount - 1 do
			local targetTrack = reaper.GetSelectedTrack(0, j)
			reaper.CreateTrackSend(targetTrack, destTrack)
		end
		reaper.Undo_EndBlock("Create track send from " .. targetTrackName .. ' to ' .. destTrackName, 0)
	end

	for i = 1, #hits do
		local trackChosen = reaper.ImGui_Button(ctx, trackNames[hits[i]])
		if trackChosen then
			local destTrack = tracks[hits[i]]
			CreateSend(destTrack)
			if autoClose and not oops then
				reaper.ImGui_End(ctx)	
				return false
			end
		end
	end

	if reaper.ImGui_IsKeyDown(ctx, 13) then -- if enter is pressed, send to top track
		local destTrack = tracks[hits[1]]
		CreateSend(destTrack)	
		if autoClose and not oops then
			reaper.ImGui_End(ctx)	
			return false
		end
	end

	if reaper.ImGui_IsKeyDown(ctx, 27) then -- if escape is pressed, close window
		reaper.ImGui_End(ctx)
		return false
	end


	reaper.ImGui_End(ctx)
	first = false
	return open
end


function loop()
	open = ShowWindow()
	if open then
		reaper.defer(loop)
	else
		reaper.ImGui_DestroyContext(ctx)
	end
end

init()
loop()

Notice how I'm simply calling reaper.Undo_BeginBlock and reaper.Undo_EndBlock at the beginning and end of my CreateSend function and nowhere else in the script; that's probably the most relevant part of the code. I'm just including all of it here since I'm not sure what's wrong.

[cfillion]

Originally Posted by poulhoi

I'm having some problems with undo states

That's unrelated to ReaImGui so it doesn't belong in this thread.

Anyway, to solve the problem:

• Set EndBlock's extraflags parameter to 1 to include sends in the undo point https://forum.cockos.com/showthread.php?p=2090533
• Bonus: move Undo_BeginBlock below the track count check, so that it doesn't get called without a matching EndBlock

[poulhoi]

Originally Posted by cfillion

That's unrelated to ReaImGui so it doesn't belong in this thread.

Anyway, to solve the problem:

• Set EndBlock's extraflags parameter to 1 to include sends in the undo point https://forum.cockos.com/showthread.php?p=2090533
• Bonus: move Undo_BeginBlock below the track count check, so that it doesn't get called without a matching EndBlock

Thanks for your help cfillion. I'm sorry for derailing the thread; I guess I just never needed the extraflags before, so I assumed I did something wrong related to ReaImGui.

[cfillion]

Released version 0.5.4:

• Docking: wait until after the left mouse button is released before closing the REAPER docker
• Documentation: fix parsing of links at the very end of the help text
• Python binding: fix a syntax error in imgui_python.py [#4]
• Windows: fix a possible crash during (un)docking of a window

API changes:
• Add ShowAboutWindow

[kotll]

Is there a way to let keyboard inputs pass through to the Reaper window while the ImGui window is focused?

I'm coding some sort of floating window with ImGui but I notice my keyboard inputs do nothing to Reaper when the ImGui window is focused. It's a bit troublesome to keep clicking back and forth between the ImGui window and the Reaper window to use shortcuts.

[cfillion]

Originally Posted by kotll

Is there a way to let keyboard inputs pass through to the Reaper window while the ImGui window is focused?

Only for shortcuts in the Action List's Global and "Global + Text fields" scopes.

(Global+Text shortcuts are always pass-through. Global shortcuts are pass-through unless a text input item has focus or ImGui_CaptureKeyboardFromApp was enabled during the previous frame.)

(On Windows, capturing global scope shortcuts requires REAPER v6.29 or newer.)

[kotll]

Originally Posted by cfillion

Only for shortcuts in the Action List's Global and "Global + Text fields" scopes.

Thanks for the info, I might have to use some HWND trickery to force focus to the main window in that case.

[dangguidan]

Imgui doesn't seem to display Chinese correctly. Is there a way?

[cfillion]

Originally Posted by dangguidan

Imgui doesn't seem to display Chinese correctly. Is there a way?

ReaImGui's font loader only reads from the Basic Latin and Latin Supplement Unicode blocks at this time.

Adding an argument to CreateFont for explicitly specifying which glyph ranges to rasterize is possible but non-ideal. I prefer waiting until upstream Dear ImGui adds the ability for backends like ReaImGui to auto-load glyphs based on usage.

(It's being actively worked on: https://github.com/ocornut/imgui/pull/3761 then https://github.com/ocornut/imgui/pull/3471)

[dangguidan]

Is there a way to keep the window always at the front?

[cfillion]

Originally Posted by dangguidan

Is there a way to keep the window always at the front?

Only tooltip windows (BeginTooltip) are always on top.

v0.1-v0.4 used to insert REAPER's thumbstack button in the titlebars for allowing users to toggle always on top (only on Windows and macOS). This might come back in the future as a ConfigFlag to enable the system's titlebars.

Were you looking to make a window always topmost or have this be user configurable via a button?

Just for fun (don't do this): setting 1<<25 as a window flag adds tooltip behavior to any window, including always on top. As a side effect the window will run away from the mouse!

[dangguidan]

This prompt often appears on win7 computers. Is there a good way to solve it?

ReaImGui error: failed to initialize OpenGL 3.2 or newer

[cfillion]

What is the minimum version of OpenGL supported by that computer's graphic card (assuming the GPU driver is up to date)?

[dangguidan]

Originally Posted by cfillion

What is the minimum version of OpenGL supported by that computer's graphic card (assuming the GPU driver is up to date)?

How should I check this?