Does anyone know what the Dock functions do?

[amagalma]

These:

reaper.Dock_UpdateDockID( ident_str, whichDock )
reaper.DockIsChildOfDock( hwnd )
reaper.DockWindowActivate( hwnd )
reaper.DockWindowAdd( hwnd, name, pos, allowShow )
reaper.DockWindowAddEx( hwnd, name, identstr, allowShow )
reaper.DockWindowRefresh()
reaper.DockWindowRefreshForHWND( hwnd )
reaper.DockWindowRemove( hwnd )
reaper.GetConfigWantsDock( ident_str )

What each one does? Anybody knows?

[Meo-Ada Mespotine]

You can influence docking, as well as get, in which docker a certain window is located.

For window names, you can use the one, that is displayed in the titles (like "Mixer").

Unfortunately the docker-values themselves are undocumented and the usage of the functions is also poorly documented....

[amagalma]

Any use examples for each function?

[Meo-Ada Mespotine]

Not yet.

I'm in the process of documenting all functions of the API, especially the undocumented ones, so this is docker-functions-management is still on my To-Do-list.

[Meo-Ada Mespotine]

I would probably use reaper.GetConfigWantsDock("Mixer") (where "Mixer" is the ident_str of the mixer-window) in a persistant script, that displays into the ReaConsole the return-value of GetConfigWantsDock.

Then just drag the Mixer into the various dockers and see, what GetConfigWantsDock returns as values(the dockID).
(There are two dockers at least at the bottom of Reaper's window, keep that in mind.)

Keep in mind: even if a window isn't docked, it's docker-value, as returned by GetConfigWantsDock is still kept. So when you dock it again into the Reaper-window, it will fall again into the "old"-docker position.

Those who need a HWND as parameter are probably mostly useless in ReaScript, as there are too few functions returning the HWNDs for the windows opened in Reaper. They are probably only useful for C++-extensions, who have more easy access to HWNDs(a HWND is a window object, that has all attributes in it).


That's all I know for now...

[spk77]

Originally Posted by mespotine

I would probably use reaper.GetConfigWantsDock("Mixer") (where "Mixer" is the ident_str of the mixer-window) in a persistant script, that displays into the ReaConsole the return-value of GetConfigWantsDock.

Then just drag the Mixer into the various dockers and see, what GetConfigWantsDock returns as values(the dockID).
(There are two dockers at least at the bottom of Reaper's window, keep that in mind.)

Keep in mind: even if a window isn't docked, it's docker-value, as returned by GetConfigWantsDock is still kept. So when you dock it again into the Reaper-window, it will fall again into the "old"-docker position.

Those who need a HWND as parameter are probably mostly useless in ReaScript, as there are too few functions returning the HWNDs for the windows opened in Reaper. They are probably only useful for C++-extensions, who have more easy access to HWNDs(a HWND is a window object, that has all attributes in it).


That's all I know for now...

I noticed that passing the full file name of a script as "ident_str" -parameter will return the dock ID for script windows:

dock_ID = reaper.GetConfigWantsDock("spk77_Track Tags (dev101119).lua")

reaper.GetConfigWantsDock function

integer reaper.GetConfigWantsDock(string ident_str)

gets the dock ID desired by ident_str, if any

gfx.dock(-1) returns different values - this is how they seem to relate:

reaper.GetConfigWantsDock(string ident_str) == (gfx.dock(-1)-1)/256

[Meo-Ada Mespotine]

Nice work! That is a good start for working through them.

[spk77]

This seems to be added recently, thanks!

integer reaper.DockGetPosition(integer whichDock)

-1=not found, 0=bottom, 1=left, 2=top, 3=right, 4=floating

...but how to use it?

I thought that it would work like this (I tried to dock the script window to the left)

dock_pos = reaper.DockGetPosition(1)
gfx.dock(dock_pos*256+1)

...didn't dock to the left



Running this...

  for i=1, 5 do
    reaper.ShowConsoleMsg(tostring(reaper.DockGetPosition(i-1)) .. "\n")
  end

...returns these values...I thought it would return each position once? It returns multiple "top" positions.

1
3
2
2
2

[schwa]

Each dock has a whichDock number associated with it. To find the whichDock number for a given window, you can use the DockIsChildOfDock function. Once you have the whichDock number, the DockGetPosition function will tell you where that dock is located relative to the main REAPER window.

[spk77]

Thanks, I'll test it immediately!

[amagalma]

Nice! It all starts to get a bit less mystic now (to me) regarding the docks and the functions for them.


Spk77, impressive work you have done with the docking with your track tags and great script btw!

[spk77]

Originally Posted by amagalma

Nice! It all starts to get a bit less mystic now (to me) regarding the docks and the functions for them.


Spk77, impressive work you have done with the docking with your track tags and great script btw!

Thanks! I like how easy it is to throw the script window around the screen

[cohler]

How do you find which windows are docked in which Docks?

[cohler]

How do you find the current height of the dock in the main window?

[Meo-Ada Mespotine]

You can look into the reaper.ini
I don't remember which entry stores it, but look for entries with "docker" in their name and check, how they change, when you drag the borders of the dock around.

It's always updated immediately, when the user drags around docker-borders.

[amagalma]

Originally Posted by schwa

Each dock has a whichDock number associated with it. To find the whichDock number for a given window, you can use the DockIsChildOfDock function. Once you have the whichDock number, the DockGetPosition function will tell you where that dock is located relative to the main REAPER window.

From what I have found there are 16 dockers (whichDock), numbered from 0 to 15.

I could not find anywhere any list of the ident_str, so I made one with 95 strings found inside the screensets.ini (like "projbay_0", "toolbar:1", "bigclock" etc).

@schwa:
Care do demystify a bit what the other functions do and how to use them properly? The ones that I haven't understood well are the following:
- DockWindowActivate. Is this to select a certain tab of a docker?
- DockWindowAdd and DockWindowAddEx. How to use correctly each one of them?
- When to call the two dock refresh APIs?

For example, let's say that I want to open the project bay window and place it at the bottom of the screen:

reaper.Main_OnCommand(41157, 0) -- Show project bay window
hwnd = reaper.JS_Window_Find("Project Bay", true)
retval, isFloatingDocker = reaper.DockIsChildOfDock( hwnd )
if hwnd and retval == -1 and isFloatingDocker == false then
  reaper.Dock_UpdateDockID( "projbay_0", 5 )
  reaper.DockWindowAddEx( hwnd, "Project Bay 1", "projbay_0", true )
end

This works, but:
- I already know that docker 5 is at the bottom of my screen. How can I know which dockers are visible, where they are placed and their sizes? And is there any way to get and set that info with ReaScript?
- If I right-click the docked Project Bay after running the code I posted, "Dock Project Bay in Docker" is not ticked. Which means although it appears docked the window is not aware that it is. If I check this then the Project Bay window disappears.

P.S. Here is a code snippet that shows which dock is where:

local place = {[-1]="not found", [0]="bottom", [1]="left", [2]="top", [3]="right", [4]="floating"}
for i = 0, 15 do
  reaper.ShowConsoleMsg("whichDock "..i.." : "..place[reaper.DockGetPosition( i )].."\n")
end

[Edgemeal]

Originally Posted by amagalma

How can I know which dockers are visible, where they are placed and their sizes?

Maybe something like?..

function DockInfo()
  t={}
  place = {[-1]="not found", [0]="bottom", [1]="left", [2]="top", [3]="right", [4]="floating"}
  arr = reaper.new_array({}, 16)
  reaper.JS_Window_ArrayFind("REAPER_dock", true, arr)
  dockers = arr.table()
  for i = 1, #dockers do
    hwnd = reaper.JS_Window_HandleFromAddress(dockers[i]) 
    whichDock, isFloatingDocker = reaper.DockIsChildOfDock(hwnd) 
    dock_pos = reaper.DockGetPosition(whichDock)  
    retval, left, top, right, bottom = reaper.JS_Window_GetRect(hwnd) 
    visible = reaper.JS_Window_IsVisible(hwnd) 
    t[i] = { id=whichDock, pos=place[dock_pos], x=left, y=top, visible=visible }
  end
     
  table.sort(t, function(a,b) return a.id < b.id end)
  for i = 1, #t do 
    if t[i].visible then
      reaper.ShowConsoleMsg(t[i].id .. " = " .. t[i].pos .. ", x = " .. t[i].x .. ", y = " .. t[i].y ..'\n' )
    end
  end

end

[amagalma]

Originally Posted by Edgemeal

Maybe something like?..

function DockInfo()
  t={}
  place = {[-1]="not found", [0]="bottom", [1]="left", [2]="top", [3]="right", [4]="floating"}
  arr = reaper.new_array({}, 16)
  reaper.JS_Window_ArrayFind("REAPER_dock", true, arr)
  dockers = arr.table()
  for i = 1, #dockers do
    hwnd = reaper.JS_Window_HandleFromAddress(dockers[i]) 
    whichDock, isFloatingDocker = reaper.DockIsChildOfDock(hwnd) 
    dock_pos = reaper.DockGetPosition(whichDock)  
    retval, left, top, right, bottom = reaper.JS_Window_GetRect(hwnd) 
    visible = reaper.JS_Window_IsVisible(hwnd) 
    t[i] = { id=whichDock, pos=place[dock_pos], x=left, y=top, visible=visible }
  end
     
  table.sort(t, function(a,b) return a.id < b.id end)
  for i = 1, #t do 
    if t[i].visible then
      reaper.ShowConsoleMsg(t[i].id .. " = " .. t[i].pos .. ", x = " .. t[i].x .. ", y = " .. t[i].y ..'\n' )
    end
  end

end

You are a star! Wizard of the JS_ReaScriptAPI

This post has nice info.

@schwa: Link to my post regarding the dock API functions, in order to not be forgotten.

[Buy One]

This places a toolbar in the floating toolbar docker window named Toolbar 1 (docked)

PHP Code:

hwnd = reaper.BR_Win32_FindWindowEx('0', '0', '0', 'Toolbar 1', false, true)
reaper.DockWindowAdd(hwnd, 'Toolbar 1', 1, true)  // Toolbar 1 is only the tab name

// not sure about these, sometimes the seem to prevent artifacts, but other times they don't
reaper.DockWindowActivate(hwnd)
reaper.DockWindowRefresh(hwnd) 


Not clear however if it's supposed to be placed in the floating docker always or it depends on other variables.

Sometimes produces graphical artifacts as if the main window didn't update

If a toolbar added in this way, manually by dragging it can only be removed from the docker on 2nd try

If this sequence is applied to another toolbar, it will join the 1st one in the window named Docker in another tab but both will float within this window

Couldn't figure out how to properly attach them to a single floating docker window.


This removes the toolbar from this window

PHP Code:

hwnd = reaper.BR_Win32_FindWindowEx('0', '0', '0', 'Toolbar 1 (docked)', false, true)
toolbar_hwnd = reaper.JS_Window_FindChild(hwnd, 'Toolbar 1', true)
reaper.DockWindowRemove(toolbar_hwnd) 


after removal toolbar toggle state is updated but manually from the menu or with the action it can only be reopened on 2nd try

[Buy One]

A function to move a window to another dock position. Covers native and SWS/S&M extension windows.

function Move_Window_To_Another_Dock(wnd_id, new_pos, cur_pos)
-- only updates visible windows
-- wnd_id is window identifier string found in reaper.ini, see table keys below,
-- if routing, add digit without space: routing1 - routing matrix;
-- routing2 - group matrix; routing3 - track wiring; 
-- routing4 - region render matrix -- non-toggle
-- cur_pos and new_pos args are integer: 0 - bottom, 1 - left, 2 - top, 3 - right, 4 - floating
-- cur_pos is optional, if passed, docker position will only be changed of the window's current pos matches cur_pos value, otherwise position will be changed regardless of the current one

local r = reaper

	if not new_pos or not tonumber(new_pos)
	or tonumber(new_pos) < 0 or tonumber(new_pos) > 4 then
	return end
	
	if cur_pos and (not tonumber(new_pos)
	or tonumber(new_pos) < 0 or tonumber(new_pos) > 4) then
	return end

local dockermode = r.GetConfigWantsDock(wnd_id) -- ger dockermode the window is currently assigned to
	
	if cur_pos and r.DockGetPosition(dockermode) ~= cur_pos then return end -- compare the position the dockermode belongs to with the cur_pos value if any

-- in actual Routing menu order
local routing = {40251, -- View: Show routing matrix window ('Routing Matrix')
42031, -- View: Show track wiring diagram ('Track Wiring Diagram')
40768, -- View: Show track grouping matrix window ('Grouping Matrix')
41888 -- View: Show region render matrix window ('Region Render Matrix') -- non-toggle
}

local function is_region_render_vis(routing)
	for _, commID in ipairs(routing) do
		if r.GetToggleCommandStateEx(0,commID) == 1 
		then -- one of the other 3 windows which have toggle state is visible
		return end -- so region render matrix visibility is false
	end
-- if the function didn't exit early, all windows with toggle action are closed
-- 'View: Show region render matrix window' is not a toggle, so evaluate that via reaper,ini 
	for line in io.lines(r.get_ini_file()) do
		if line:match('routingwnd_vis') and line:sub(-1) == '1' then 
		-- the key has value 1 when region render matrix is open as well	
		return true
		end
	end
end

local t = {transport = 40259, mixer = 40078, actions = 40605, 
projbay_0 = 41157, projbay_1 = 41628, projbay_2 = 41629, 
projbay_3 = 41630, projbay_4 = 41631, projbay_5 = 41632, 
projbay_6 = 41633, projbay_7 = 41634, --routing = rout,
regmgr = 40326, explorer = 50124, trackmgr = 40906, grpmgr = 40327, 
bigclock = 40378, video = 50125, perf = 40240, navigator = 40268, 
vkb = 40377, fadeedit = 41827, undo = 40072, fxbrowser = 40271, 
itemprops = 41589, midiedit = '', ['toolbar:1'] = 41679, 
['toolbar:2'] = 41680, ['toolbar:3'] = 41681, ['toolbar:4'] = 41682, 
['toolbar:5'] = 41683, ['toolbar:6'] = 41684, ['toolbar:7'] = 41685, 
['toolbar:8'] = 41686, ['toolbar:9'] = 41936, ['toolbar:10'] = 41937, 
['toolbar:11'] = 41938, ['toolbar:12'] = 41939, ['toolbar:13'] = 41940,
['toolbar:14'] = 41941, ['toolbar:15'] = 41942, ['toolbar:16'] = 41943, 
['toolbar:17'] = 42404, -- MX toolbar
SWSAutoColor = '_SWSAUTOCOLOR_OPEN', -- SWS: Open auto color/icon/layout window ('Auto Color/Icon/Layout')
['BR - ContextualToolbars WndPos'] = '_BR_CONTEXTUAL_TOOLBARS_PREF', -- SWS/BR: Contextual toolbars... ('Contextual toolbars')
SnMCyclaction = '_S&M_CYCLEDITOR', -- SWS/S&M: Open/close Cycle Action editor ('Cycle Actions') // doesn't remember section selection BUT all 3 actions toggle
SnMFind = '_S&M_SHOWFIND', -- SWS/S&M: Find ('Find')
FNGGroove = '_FNG_GROOVE_TOOL', -- SWS/FNG: Show groove tool ('Groove')
SnMLiveConfigs = '_S&M_SHOWMIDILIVE', -- SWS/S&M: Open/close Live Configs window ('Live Config')
SnMLiveConfigMonitor1 = '_S&M_OPEN_LIVECFG_MONITOR1', -- SWS/S&M: Live Config #1 - Open/close monitoring window
SnMLiveConfigMonitor2 = '_S&M_OPEN_LIVECFG_MONITOR2', -- SWS/S&M: Live Config #2 - Open/close monitoring window
SnMLiveConfigMonitor3 = '_S&M_OPEN_LIVECFG_MONITOR3', -- SWS/S&M: Live Config #3 - Open/close monitoring window
SnMLiveConfigMonitor4 = '_S&M_OPEN_LIVECFG_MONITOR4', -- SWS/S&M: Live Config #4 - Open/close monitoring window
SnMLiveConfigMonitor5 = '_S&M_OPEN_LIVECFG_MONITOR5', -- SWS/S&M: Live Config #5 - Open/close monitoring window
SnMLiveConfigMonitor6 = '_S&M_OPEN_LIVECFG_MONITOR6', -- SWS/S&M: Live Config #6 - Open/close monitoring window
SnMLiveConfigMonitor7 = '_S&M_OPEN_LIVECFG_MONITOR7', -- SWS/S&M: Live Config #7 - Open/close monitoring window
SnMLiveConfigMonitor8 = '_S&M_OPEN_LIVECFG_MONITOR8', -- SWS/S&M: Live Config #8 - Open/close monitoring window
['BR - AnalyzeLoudness WndPos'] = '_BR_ANALAYZE_LOUDNESS_DLG', -- SWS/BR: Analyze loudness... ('Loudness')
SWSMarkerList = '_SWSMARKERLIST1', -- SWS: Open marker list ('Marker List')
SnMNotesHelp = '_S&M_SHOW_NOTES_VIEW', -- SWS/S&M: Open/close Notes window ('Notes') // does remember notes type selection so other 11 actions will likely be redundant
SWSProjectList = '_SWS_PROJLIST_OPEN', -- SWS: Open project list ('Project List')
ReaConsole = '_SWSCONSOLE', -- SWS: Open console ('ReaConsole')
SnMRgnPlaylist = '_S&M_SHOW_RGN_PLAYLIST', -- SWS/S&M: Open/close Region Playlist window ('Region Playlist')
SnMResources = '_S&M_SHOW_RESOURCES_VIEW', -- SWS/S&M: Open/close Resources window ('Resources') // does remember resource type selection so other 7 actions will likely be redundant
SWSSnapshots = '_SWSSNAPSHOT_OPEN' -- SWS: Open snapshots window ('Snapshots') // (caused redraw problem)
}

local function wrapper(func,...)
-- https://forums.cockos.com/showthread.php?t=218805 Lokasenna
local t = {...}
return function() func(table.unpack(t)) end
end


local function wait_and_reopen(commandID)
	if commandID ~= 41888 and r.GetToggleCommandStateEx(0,commandID) == 0 then
	r.Main_OnCommand(commandID, 0) -- re-open // must be inside defer loop, for some reason when the defer loop stops commandID  is not accessible to Main_OnCommand() function outside
	return 
	elseif commandID == 41888 then
		for line in io.lines(r.get_ini_file()) do
			if line:match('routingwnd_vis') and 
			-- the key has value 0 when region render matrix is closed as well
			line:sub(-1) == '0' then	
			r.Main_OnCommand(commandID, 0) return end
		end
	end
r.defer(wrapper(wait_and_reopen, commandID))
end


-- extract index if routing and select command ID
local commandID = wnd_id:match('routing') and routing[wnd_id:sub(-1)+0] or r.NamedCommandLookup(t[wnd_id]) -- accounting for SWS ext command IDs
local vis = commandID ~= 41888 and r.GetToggleCommandStateEx(0,commandID) == 1 
or commandID == 41888 and is_region_render_vis(routing)

	if not vis then return end -- only update visible windows
	
local wnd_id = wnd_id:match('routing') and 'routing' or wnd_id	
	
	for i = 0, 15 do -- there're 16 dockermode indices in total
		if r.DockGetPosition(i) == new_pos then -- find dockermode associated with the desired position
		-- in reaper.ini it's e.g. dockermode5=0;
		-- update dockermode to which the window is assigned in reaper.ini;
		-- in [REAPERdockpref] section
		r.Dock_UpdateDockID(wnd_id, i)
		-- must be refreshed for the change to become visible, that is its visibility toggled
			if commandID ~= 41888 and r.GetToggleCommandStateEx(0,commandID) == 1 
			or commandID == 41888 and is_region_render_vis(routing)
			then -- visible
			r.Main_OnCommand(commandID, 0) -- close
			wait_and_reopen(commandID) -- toggle state is updated slower than the function runs hence the need to wait and only then re-open, the same is true for routingwnd_vis value update in reaper.ini
		-- 	OR
		--	r.defer(wrapper(wait_and_reopen, commandID)) -- re-open
			end
		break end
	end
end