Running an External Program
For some types of customizations, you might want to launch an
external program in response to some event in PinballY. The
most obvious case would be to launch a program when the user
selects a custom menu command. This is
one of the simpler but more versatile approaches to customizing,
since it lets you take some existing function that's already
available via a separate program, and integrate it more or
less seamlessly into the PinballY user interface.
Setting up the custom menu
We'll start by setting up a custom menu command, which we'll
add to the main menu. We can do this by setting up a listener
for the menuopen event.
When the listener recognizes that the main menu is being
opened, it inserts our new custom command into the menu, and
then lets the system show the modified menu as normal. This
technique is explained in full in
Overriding a system menu.
Whenever we want to add a new custom command, we have to do one
little bit of preparatory work, which is to allocate an ID for
our command. This just requires one line of code in the "global"
part of the Javascript file (outside of any functions).
let runCustomProgCommand = command.allocate("RunCustomProgram");
Once we have the command ID, we can create the menuopen
listener that modifies the main menu, placing our new command
after the exiting "Rate Table" command.
mainWindow.on("menuopen", ev => {
if (ev.id == "main") {
ev.addMenuItem({after: command.RateGame},
{ title: "Run Custom Program", cmd: runCustomProgCommand });
}
});
You can use this same technique to add
commands to any of the other standard menus, such as the Operator
menu or Exit menu. The only things you have to change to use
a different menu are the menu ID string that you check
(see System Menus for
a list of these) and the command ID you search for to determine the
insertion location (see System Command IDs
for those).
Launching the command
Now that we have the menu item in place, we can write the code that
responds to our new command by actually carrying out the custom program
launch. Processing a custom menu command requires writing a listener
for the command event, and responding
when the command ID in the event matches the custom command ID we
created earlier.
mainWindow.on("command", ev => {
if (ev.id == runCustomProgCommand) {
// TO DO - carry out the command
}
});
Javascript doesn't have any built-in way of launching an external
program, so we'll use the native DLL interface
to call a Windows system function that runs a command. There are several
Windows APIs for launching a program; the main ones are ShellExecute(),
ShellExecuteEx(), and CreateProcess(). ShellExecute() is the easiest to
use, so it's the one I'd recommend for simple cases where you just want
to launch a command and don't need to interact with the new process
after it's started. ShellExecuteEx() and CreateProcess() give you more
options, including the ability to monitor the process for completion, but
they're more complex to use.
You can read all about the DLL import system in the chapter on
calling native DLLs, so we won't repeat
all of that here. We'll just show the code needed for this specific
situation.
The first step is to "bind" the native Windows DLL function we need.
Binding sets up a bridge from Javascript to the DLL so that we can
call the function.
We'll use the simple ShellExecute() API for this example. Note that
we have to call the function by its "full" name, ShellExecuteW().
The added "W", as explained in the DLL import chapter, stands for
"Wide characters", meaning the Unicode version. We always have to
use the "W" version in Javascript calls.
let Shell32 = dllImport.bind("Shell32.dll", `
HINSTANCE ShellExecuteW(
HWND hwnd,
LPCWSTR lpOperation,
LPCWSTR lpFile,
LPCWSTR lpParameters,
LPCWSTR lpDirectory,
INT nShowCmd
);
`);
Now that we have our DLL import defined, we can flesh out the
"TO DO" code in the event handler prototype we wrote earlier.
mainWindow.on("command", ev => {
if (ev.id == runCustomProgCommand) {
// run the command
let result = Shell32.ShellExecuteW(null, "open",
"c:\\Path\\MyProgram.exe", " /option1 /option2",
"c:\\Path", SW_SHOW);
// The result of ShellExecute() is a fake handle value that we
// have to interpret as an integer to make sense of. A value
// higher than 32 indicates success; a value 32 or lower is an
// error code. See the Windows SDK documentation for details.
if (result.toNumber() > 32)
{
// success! do any follow-up here
}
else
{
// launch failed
mainWindow.message("Program launch failed (code " + result.toNumber() + ")", "error");
}
}
});
Using CreateProcess()
For the sake of completeness, let's look at how you'd do
the same thing using CreateProcess() instead of ShellExecute().
You can skip all of this if ShellExecute() meets your
needs, but I wanted to provide the details on how to use
CreateProcess() just in case you need its extra power.
As before, the first step is to bind the DLL function:
let Kernel32 = dllImport.bind("Kernel32.dll", `
typedef struct _STARTUPINFO {
DWORD cb;
LPWSTR lpReserved;
LPWSTR lpDesktop;
LPWSTR lpTitle;
DWORD dwX;
DWORD dwY;
DWORD dwXSize;
DWORD dwYSize;
DWORD dwXCountChars;
DWORD dwYCountChars;
DWORD dwFillAttribute;
DWORD dwFlags;
WORD wShowWindow;
WORD cbReserved2;
BYTE *lpReserved2;
HANDLE hStdInput;
HANDLE hStdOutput;
HANDLE hStdError;
} STARTUPINFO, *LPSTARTUPINFO;
typedef struct _PROCESS_INFORMATION {
HANDLE hProcess;
HANDLE hThread;
DWORD dwProcessId;
DWORD dwThreadId;
} PROCESS_INFORMATION, *PPROCESS_INFORMATION, *LPPROCESS_INFORMATION;
typedef struct _SECURITY_ATTRIBUTES {
DWORD nLength;
LPVOID lpSecurityDescriptor;
BOOL bInheritHandle;
} SECURITY_ATTRIBUTES, *PSECURITY_ATTRIBUTES, *LPSECURITY_ATTRIBUTES;
BOOL WINAPI CreateProcessW(
LPCWSTR lpApplicationName,
LPWSTR lpCommandLine,
LPSECURITY_ATTRIBUTES lpProcessAttributes,
LPSECURITY_ATTRIBUTES lpThreadAttributes,
BOOL bInheritHandles,
DWORD dwCreationFlags,
LPVOID lpEnvironment,
LPCWSTR lpCurrentDirectory,
LPSTARTUPINFO lpStartupInfo,
LPPROCESS_INFORMATION lpProcessInformation
);
BOOL WINAPI CloseHandle(HANDLE hObject);
`);
As you can see, CreateProcess() has a bunch of additional arguments you
have to provide (including several structure definitions). That's
where its extra power comes from, as well as the extra headaches
using it.
Now let's change the command handler to use CreateProcess() to
do the launch.
mainWindow.on("command", ev => {
if (ev.id == runCustomProgCommand) {
// create our STARTUPINFOW and PROCESS_INFORMATION structs
let processInfo = dllImport.create("PROCESS_INFORMATION");
let startupInfo = dllImport.create("STARTUPINFO");
// We have to fill in the STARTUPINFO struct with some minimal
// information. You can also populate the other fields if you
// want to set specific options. By default, Javascript will
// set everything to zeros and nulls, so you'll get the default
// options without filling in anything else here.
startupInfo.cb = dllImport.sizeof("STARTUPINFO");
// Launch the process. Fortunately, we can provide "null"
// parameters to get the defaults for some of the more
// obscure items, such as the "security attributes". If
// you need to set any of the options we've defaulted, you'd
// just change the corresponding nulls or zeroes to supply
// the specific options you want to set.
if (Kernel32.CreateProcessW(
null, "\"c:\\Path\\MyProgram.exe\" /option1 /option2",
null, null, false, 0, null, "c:\\Path", startupInfo, processInfo);
{
// Success!
//
// CreateProcess() will have filled in our PROCESS_INFORMATION
// struct with handles for the new process and thread. It's
// VERY important to close these handles (or ANY handles that
// Windows creates for us) when we're done with them, because
// otherwise we'd "leak" these system resources, which could
// eventually make the program crash if we did if often
// enough. Javascript can't close native Windows handles
// for us automatically, because it doesn't have enough
// information to know where else they might be used. So
// we MUST do this explicitly.
//
// If we wanted to interact with the new process later (for
// example, to monitor it for completion), we could hang onto
// the process and/or thread handle in a global variable
// instead of closing them immediately here. That would let
// us access the handles later. But that makes things a bit
// trickier, because it's still important that we *eventually*
// close the handles. In cases where you don't need them
// later, it's best to close them immediately, so that you
// don't have to worry about losing track of them.
Kernel32.CloseHandle(processInfo.hProcess);
Kernel32.CloseHandle(processInfo.hThread);
}
else
{
// something went wrong
mainWin.message("Something went wrong launching the program!", "error");
}
}
});