js_ReaScriptAPI extension

[juliansader]

I have uploaded a new extension that may be of interest to other scripters: "js_ReaScriptAPI".

It can be installed via ReaPack (if ReaTeam/Extensions is not listed among your default repositories, you can add the repository manually with this URL), or via direct download (copy the file to REAPER's /UserPlugins directory).

The idea behind this extension is to make all the useful and powerful functions that are available to C++ extensions available to ReaScripts too. (The resulting ReaScript API is therefore not the result of my own amazing programming skills, but is mostly just an interface to existing C++ functions.)

The online documentation for the corresponding C++ functions is probably the best place to learn how to use these functions. For example, Window messages and Drawing with GDI.

I have tried to make most functions cross-platform applicable, but I am not able to test the extension on MacOS, so let me know if anything doesn't work as expected.

Many thanks to cfillion, Xenakios and nofish, who helped me a *lot* to figure out the esoteric and undocumented mysteries of REAPER extensions.


Here are a few examples:


Attach "pin on top" button to script GUIs

FR: add 'always on top' pin for EEL script GUI's

w = reaper.JS_Window_Find("MIDI Inspector", true)
if w then reaper.JS_Window_AttachTopmostPin(w) end

Drawing inside REAPER windows

FR: Lasso Select for midi notes





Load custom cursors

FR: ReaScript: Allow scripts to change mouse cursor

-- Load REAPER's native "arpeggiate" cursor
reaper.JS_Mouse_SetCursor(reaper.JS_Mouse_LoadCursor(502)) 
-- Prevent REAPER from changing cursor back, by intercepting "SETCURSOR" messages
reaper.JS_WindowMessage_Intercept(window, "WM_SETCURSOR", false)

Take control of mouse clicks and mousewheel

By intercepting mouse and mousewheel messages, scripts can be controlled with the mouse, without activating REAPER's own mouse modifier actions.

For example, in my own "Mouse editing" CC scripts, I use code like the following to block the mouse from interacting with the piano roll while the script is running:

tIntercepts = { WM_LBUTTONDOWN   = false,
	        WM_LBUTTONUP     = false,
	        WM_LBUTTONDBLCLK = false,
	        WM_MBUTTONDOWN   = false,
	        WM_MBUTTONUP     = false,
	        WM_MBUTTONDBLCLK = false,
	        WM_RBUTTONDOWN   = false,
	        WM_RBUTTONUP     = false,
	        WM_RBUTTONDBLCLK = false,
	        WM_MOUSEWHEEL    = false,
	        WM_MOUSEHWHEEL   = false,
	        WM_MOUSEMOVE     = false,
	        WM_SETCURSOR     = false
	      }
midiview = reaper.JS_Window_FromPoint(reaper.GetMousePosition())
for key, value in pairs(tIntercepts) do
    OK = reaper.JS_WindowMessage_Intercept(midiview, key, value)
end

The scripts can then use JS_WindowMessage_Peek to track mouse events while running:

peekOK, _, time, keys, rotate, x, y = reaper.JS_WindowMessage_Peek(midiview, "WM_MOUSEWHEEL")
if peekOK and time ~= prevTime then
    -- mousewheel has moved since last defer cycle
end
peekOK, _, time, keys, _, x, y = reaper.JS_WindowMessage_Peek(midiview, "WM_LBUTTONDOWN")
if peekOK and time ~= prevTime then
    -- Left button has been pressed
end

Trigger REAPER actions for any window

Send commands to any window, similar to Main_OnCommand and MIDIEditor_OnCommand:

-- Action 1011 = Autoplay: Toggle on/off
me = reaper.JS_Window_Find("Media Explorer", true)
reaper.JS_Window_OnCommand(me, commandID)

Keep the Mixer window out of the way

FR: Plugin windows always on top, Mixer window always behind

The API offers several functions for getting and setting the Z order and focus of windows, so one possible solution for the FR is discussed here:
Move Mixer out of the way: example of Win32/SWELL in ReaScript.



Track mouse events outside script GUI

FR: Exposure of mouse state-functions for non gfx.ini-created windows

In addition to the WindowMessage functions, which are specific to a single target window, the mouse can be tracked using JS_Mouse_GetState:

-- Flag 0b00000001+0b00010000 = left mouse button + alt key
if reaper.JS_Mouse_GetState(0x0011) = 0x0011 then
   --...
end

Frameless script GUIs

FR: Stylish ReaScript GUIs: Transparent backgrounds and no titlebars:

Using JS_Window_SetStyle, or when creating new windows:

[mpl]

Interesting, looks cool!

[_Stevie_]

Holy cow, didn't see THAT coming! Mouse lasso, always on top... Geez Julian, you never cease to amaze me!

[X-Raym]

Many thx ! This may bring a lot of useful things !



C++ function were recently exposed in SWS but because pull request are very long to be merged, having your extension will definitly be useful
Though I dont see the function for getting bitdepth, which is accessible for C++ and was wating for mege in SWS, is it missing ?



Ill try to add your functions in my reascript doc.

[_Stevie_]

Originally Posted by X-Raym

Ill try to add your functions in my reascript doc.

Merci X-Raym!!!

[amagalma]

AMAZING!!! :O


Well done! A lot of useful stuff in there opening great possibilities!

[nofish]

Originally Posted by X-Raym

Though I dont see the function for getting bitdepth, which is accessible for C++ and was wating for mege in SWS, is it missing ?

This came from cfillion and is still waiting for merge in SWS.
https://github.com/reaper-oss/sws/pull/1011

[InfiniteDimensionality]

Cool,

I wonder if you could extend it a little bit?

Writing in some languages sucks or does not offer as much performance.

Could you potentially extend your plugin to load other plugin compiled in other languages(such as c++/d/haskell/etc)?

The idea is this:

1. You have a context variable that allows any plugin to use to access the methods and variables(an interface basically).

2. You compile the source code when it changes by monitoring any changes and recompiling and loading(this might work only when restarting reaper without some special hot plugging capabilities). You just run a compile string on the code.

3. You load the code, run any setup routines(similar to dll loading). Run some main function(possibly in another thread) and pass it the context.

This then makes it much easier to write programs and even debug them(e.g., with windows one could use VS to debug the program while it is in reaper).

It would allow for much more freedom than using reapers built in scripting, which isn't bad but isn't great(mainly the dev part such as using IDE's and such).

It would also make writing plugins easier in some ways.

Most of the work shouldn't be too difficult(it can be done easily but might be hard to do well).

[NextLevel]

@juliansader,

Noticed a little typo in the "MediaExplorer_OnCommand" example.

The line "m = reaper.JS_Window_Find("Media Explorer", true)"
should be "me = reaper.JS_Window_Find("Media Explorer", true)"

This extension is going to open up some nice possibilities, so thank you so much!

Just added your "pin to top" example to Lokasenna's Radial Menu.., yea!!!

[X-Raym]

Could you potentially extend your plugin to load other plugin compiled in other languages(such as c++/d/haskell/etc)?

ReaScript already supports Lua and Python, I don't think there is a lot of demand for other languages.

Most of the work shouldn't be too difficult

You seems to have a lot of knowledge about programming, so why no you take a try to do this ?
Juliansader extension is open source, you can work from there.

[nofish]

Amazing. Kudos for the work you've put into this!

Originally Posted by juliansader

Attach "pin on top" button to script GUIs

FR: add 'always on top' pin for EEL script GUI's

I'd tend to suggest all ReaScripters having scripts with GUI's to update their scripts to add the 'always on top' pin.

[TonE]

Originally Posted by juliansader

I have uploaded a new extension that may be of interest to other scripters: "js_ReaScriptAPI".

Does this allow docking of trackey hackey and patterns in wine? Now lua scripts can not be docked in wine.

[nappies]

Very useful and promising thing! Thank you for your hard work juliansader!
I didn’t really dive into the new API, but what I saw was very impressive!
Is it possible to intercept the left mouse click on TCP solo button and make an exclusive solo( by deafult while code running ) for example?

[amagalma]

Julian, I followed your example in post #46 trying to mimick mouseclicks but it works the first time and fails all the other times. Any idea why?
This is the test code:

reaper.ShowConsoleMsg("This message should always be cleared\n")
local RSwindow = reaper.JS_Window_Find("ReaScript console output", true)
local _, leftX, topY, rightX, bottomY = reaper.JS_Window_GetRect(RSwindow)
-- "clear" button
local buttonX = rightX - 114
local buttonY = bottomY -27
-- Get button window
local buttonWindow = reaper.JS_Window_FromPoint(buttonX, buttonY)
_, leftX, topY, rightX, bottomY = reaper.JS_Window_GetRect(buttonWindow)
-- Post click message
reaper.JS_WindowMessage_Post(buttonWindow, "WM_LBUTTONDOWN", 0x0001, 0, buttonX-leftX, buttonY-topY)
reaper.JS_WindowMessage_Post(buttonWindow, "WM_LBUTTONUP", 0x0000, 0, buttonX-leftX, buttonY-topY)

P.S. If I close the Console window and run the script again, it works. But if I keep running the script with the console window being open, then it fails.
P.S.2. Ok, I found it.. For it to work, I must first focus the button window using

reaper.ShowConsoleMsg("This message should always be cleared\n")
local RSwindow = reaper.JS_Window_Find("ReaScript console output", true)
local _, leftX, topY, rightX, bottomY = reaper.JS_Window_GetRect(RSwindow)
-- Get "clear" button window
local buttonWindow = reaper.JS_Window_FromPoint(rightX - 114, bottomY -27)
-- Post click message
reaper.JS_Window_SetFocus( buttonWindow )
reaper.JS_WindowMessage_Send(buttonWindow, "WM_LBUTTONDOWN", 0x0001, 0, 10, 10)
reaper.JS_WindowMessage_Send(buttonWindow, "WM_LBUTTONUP", 0x0000, 0, 10,10)

before the WindowMessage Posts

[Sexan]

Is this possible without flickering?

W,H = 5000,5000
local bmp = reaper.JS_LICE_CreateBitmap( true, W, H )
local bmpDC = reaper.JS_LICE_GetDC(bmp )
reaper.JS_LICE_FillRect( bmp, 0, 0, W, H, 0x99009999, 1, "ADD" )

local track_window = reaper.Window_Find("trackview", true) -- GET TRACK VIEW
local track_window_dc =  reaper.JS_GDI_GetWindowDC( track_window )

function main()
reaper.JS_GDI_Blit(track_window_dc, X_start, Y_start, bmpDC, 0, 0, W, H )
reaper.defer(main)
end
main()

This is the short versions of whats going on,but rectangle is constantly updated when window is moved,scrolled etc

[juliansader]

I also posted about this some time ago:
SWELL/GDI and LICE: Is it possible to draw inside REAPER's window without flickering?, but I didn't get any answers, so I asked Justin on askjf.com:

Question: Is it possible for a REAPER script or extension to use swell/GDI to draw basic shapes such as lines inside other REAPER/swell windows, without flickering? Flickering is not unexpected, since the script and window paint their stuff alternately and separately. I have tried blocking WM_PAINT messages, and then sending my own WM_PAINT once per defer cycle, but t
Asked by Julian (54.39.119.x) on September 20 2018, 9:41am
Reply on September 20 2018, 2:20pm:

It's probably possible via subclassing, but it would get messy/tricky.

[Aleksandr_Oleynik]

Originally Posted by juliansader

I have uploaded a new extension that may be of interest to other scripters: "js_ReaScriptAPI".

Hello juliansader!

Could you, please, add to your "js_ReaScriptAPI" a function to receive and send OSC-messages (OSC Client and Server)?
I use Reaper and LUA for creating live setups and I really need a function to hear outgoing OSC-commands with LUA-script (with specific port and IP and send OSC-messages to a specific port and IP).

The Reaper itself supports OSC, but today there’s no way to send OSC from script and to receive OSC to a script.

I would be very thankful for this help. And ready to pay for your time in any reasonable amount.

Best regards,
Aleksandr

[juliansader]

I have uploaded v0.96 of the extension to its repository. [EDIT: Now v0.961.]

The reason why this update was somewhat delayed, is that I was trying to figure out how to return long strings (for example, if dozens of files are selected in an Open File dialog) and strings that contain \0 characters (for example, packed Lua strings). Fortunately, Justin noticed my threads, and the upcoming version of REAPER will allow API functions to return such strings. The extension will therefore require an up-to-date version of REAPER.

The update is not yet available via ReaPack, but in the meantime if anyone is interested in testing the new functions, it can be downloaded and installed manually. It requires one of the recent dev versions of REAPER.

New functions:

* FindChildByID: (Thanks to amagalma for reminding me about this.) IDs seem to be a more reliable cross-platform way of getting child windows (such as the arrange view within the main window, or the piano roll within an MIDI editor), than searching by title ("trackview" or "midiview") or by Z order.

* Localize: If searching for standard windows such as "Actions" or "Navigator" by window title, localized (translated) titles should be used.

* Several ListView functions: Useful for finding selected items in any list window, such as the FX chain.

* Open files, save file and select folder dialogs.

Changed functions:

* All the "List" functions that previously stored long strings in ExtStates. These functions now return the long strings directly.

[X-Raym]

* Open files, save file and select folder dialogs.

Finally !!!


Thx !

[lb0]

Great stuff! Thanks for all your hard work!

Would the listview functions be any good for getting the command id of the selected item in the action list?

[juliansader]

Originally Posted by lb0

Would the listview functions be any good for getting the command id of the selected item in the action list?

I have uploaded a quick update v0.961, and now you can: if the commandID is visible in the Actions list, you can get it as subitem 3:

commandID = reaper.JS_ListView_GetItemText(window, index, 3)

[amagalma]

How could I paste the text in the clipboard to a focused window?
For example, with Spy++ I get this code when pasting into a window:

<000001> 00250490 P WM_CHAR chCharCode:'22' (22) cRepeat:1 ScanCode:2F fExtended:0 fAltDown:0 fRepeat:0 fUp:0 [wParam:00000016 lParam:002F0001]

I have tried this but it does not work:

reaper.JS_WindowMessage_Send( windowHWND, "WM_CHAR", 0x0016, 0x0000, 0x0001, 0x002F)

Any ideas?

[Edgemeal]

EDIT
You got me wondering about sending text and clicking buttons now.
Since there is no support for "BM_CLICK" or "WM_SETTEXT"

EDIT 2
This seems OK for "BM_CLICK" on Windows..

-- Send button click message, a.k.a. "BM_CLICK".
reaper.JS_WindowMessage_Send(button_hWnd, "0x00F5", 0, 0, 0, 0)

CODE REMOVED! TRY AGAIN!

[amagalma]

Originally Posted by Edgemeal

This seems to work OK, tho not sure its actually correct.

local hWnd_action = reaper.JS_Window_Find("Actions", true)
if hWnd_action ~= nil then
  -- Get handle to Filter editbox in Actions window,
  local hWnd_filter = reaper.JS_Window_FindChildByID(hWnd_action, 1324)
  -- send it an "A" Char
  ret = reaper.JS_WindowMessage_Post(hWnd_filter, "WM_CHAR", string.byte("A"), 0,0,0) 
end

Yes, simple characters work, but Ctrl+V etc do not.

function JS_Send_Text(hWnd, str)
  for char in string.gmatch(str, "%U") do 
    ret = reaper.JS_WindowMessage_Post(hWnd, "WM_CHAR", string.byte(char), 0, 0, 0) 
    if ret ~= true then break end -- something went wrong?, abort loop!
  end
end

For some reason, this works up to 64 characters. If they are more than 64, it truncates the start.

[X-Raym]

Do you think we can get selected media files from Media Explorer and start doing some Media Explorer script ? :P

[tparker24]

I wanted to try ReaScriptAPI, but am having problems just getting started:

1) I couldn't find it on ReaPack.

2) I saw the files on GitHub, but don't know how/where to install them.

3) I want to use this from python, but couldn't find the normal .py interface file.


Can you help me out?

[nofish]

Originally Posted by tparker24

1) I couldn't find it on ReaPack.

It should be listed in ReaPack as 'js_ReaScriptAPI: API functions for ReaScripts' and the repository where it's hosted (ReaTeam/Extensions) should be enabled by default in ReaPack afaik.
If you don't see it, maybe try 'Synchronize packages' ?

[tparker24]

Originally Posted by nofish

It should be listed in ReaPack as 'js_ReaScriptAPI: API functions for ReaScripts' and the repository where it's hosted (ReaTeam/Extensions) should be enabled by default in ReaPack afaik.
If you don't see it, maybe try 'Synchronize packages' ?

Still no luck.

I searched for "js_reascript" and then for "js_rea", but got no results. ("js_re" did show a bunch, but nothing with reascript).

My settings are "Display: All" and "All Packages". I didn't see "Synchronize packages", but I did try "Refresh repositories", without any success.

[Edgemeal]

Originally Posted by tparker24

I searched for "js_reascript" and then for "js_rea", but got no results. ("js_re" did show a bunch, but nothing with reascript).

Manage Repositories > "ReaTeam Extensions" is enabled? > Sync again.

[tparker24]

Originally Posted by Edgemeal

Manage Repositories > "ReaTeam Extensions" is enabled? > Sync again.

Yes, they're all enabled. Did yet another "Refresh repositories", but still no luck.

I vaguely remember something about it being removed from Reapack ... could you perhaps give it a try?

[nofish]

Originally Posted by tparker24

I didn't see "Synchronize packages"

It's a dedicated menu entry in Reaper under ReaPack menu (here at least).



(I have ReaMenu installed, so it might look a bit different on your side.)

[tparker24]

Originally Posted by nofish

It's a dedicated menu entry in Reaper (here at least).



(I have ReaMenu installed, so it might look a bit different on your side.)

Thanks. I also found that in Actions.

I imagine that Synchronize does the same thing as "Refresh repositories" (which is under the packages dropdown in the browser).

[X-Raym]

@juliansader
Excellent, here is my final string:

'csv files (.csv)\0*.csv\0All Files (*.*)\0*.*\0

Per default, just entering a File name will create a file without extension, the save doesn't force the extension based on the actual filter list, it would be nice if it could :P


Else, I suppose it could be handle by the script itself, but as this will be a common case, I worth having it default if possible, don't you think ?




BTW? \0 as seperator character is a very nice thing..... I really which GetUserInput to be like that, cause if you enter CSV in a multi line input window of this type, it just mess everything.

[Meo-Ada Mespotine]

I think I've found an issue JS_Mouse_GetState(), while using it on Mac(though I don't know, whether its a Mac-problem or a general problem).

I tried to write a script with it to get mouse-click-events in the ruler, which worked fine on Windows. However, when I tried the same script on Mac, it couldn't detect mouseclicks, when they were too short.
I think its because my Mac is much faster than my Windows-computer, so I think the mouseclicks are inbetween two defer-cycles and can't be detected because of that. Could be on Windows too, but I haven't noticed such a problem yet.

Anyway, as deferred ReaScripts can only run about 30 times per second and when they are run quick, the amount of time could be too short to notice mouseclicks.

So I think, the function should work something like that:
a background-thread constantly listens to the mouse-events/keyboard modifier-states.
When I run the JS_Mouse_GetState-function, it will return the current mouse-state(as usual) and in addition a csv-string, that contains all mousestates that happened since last time calling JS_Mouse_GetState or at least since the last defer-cycle.
That way, I couldn't miss any of them, no matter how short they are.

I have no idea how easy or hard this would be to implement, but it would improve heavily on Mouse-State-Management.


With that, I could add to my API a Mouse-Event-defer-script, that returns the mouseclicks(including dragging and doubleclick) in specific HWNDs, which would improve using mouse-states heavily(my dream is to program a clickable UI in the VideoProcessor-window).

Originally Posted by X-Raym

BTW? \0 as seperator character is a very nice thing..... I really which GetUserInput to be like that, cause if you enter CSV in a multi line input window of this type, it just mess everything.

Yep, that's really clever to do

[dsyrock]

I have a question about JS_Dialog_BrowseForOpenFiles. I set the argue "allowMultiple " to true. But when I selected a bunch of files, it only returned a path, but without any filenames. Did I do anything wrong?

retval,  filenames = reaper.JS_Dialog_BrowseForOpenFiles("a", "E:/test/", "*.txt", "*.txt", true)

[X-Raym]

@dyrock


You have to parse the results with null characte (the code snippet is on this thread),
If I remeber correctly, IDE console and message cobsole doesnt display characters after a null.
But maybe it is another problem.

[juliansader]

Originally Posted by dsyrock

I have a question about JS_Dialog_BrowseForOpenFiles. I set the argue "allowMultiple " to true. But when I selected a bunch of files, it only returned a path, but without any filenames. Did I do anything wrong?

As X-Raym mentioned, please check out the discussion here, and some other posts earlier in the thread.

Zero-separated strings have confused other new users too, so I should probably mention something in the API help.

[dsyrock]

Originally Posted by juliansader

As X-Raym mentioned, please check out the discussion here, and some other posts earlier in the thread.

Zero-separated strings have confused other new users too, so I should probably mention something in the API help.

Thanks, juliansader and X-raym!

[dsyrock]

@juliansader

One more thing about JS_Dialog_BrowseForOpenFiles:

I run this script

local check,  names = reaper.JS_Dialog_BrowseForOpenFiles("", "E:/test/", "*.txt", "*.txt", true)

for v in names:gmatch("[^\0]*") do

  reaper.ShowConsoleMsg(v .. "\n")

end

As you mentioned before, when I seleted multy files, the first result in this script is the file path "E:\test\". I tried it on win8.1 and win10, it showed the path correctly. But When I tried it on Win8.0, the result was "E:\test", a "\"at the end was missing.

[Sexan]

@Julian
https://forum.cockos.com/showpost.ph...&postcount=133

Other user is also on Win 7