Download runmenu.zip and unzip the contents into a folder that is in your path.
The Tutorial.htm file contains:
runmenu
|
What's New runmenu 2.1 Minor bug fix. Now the /verb option should work for context menu extensions that install owner-drawn submenus. See the command line reference below for more. runmenu 2.0 Runmenu 2.0 now supports the Eluent Tools syntax for referring to Windows Shell folders, such as <Desktop>, which gives you a convenient, portable way to refer to common Windows folders such as the current user's desktop folder. In addition, you can refer to the shell's virtual folders, such as <NetworkConnections>, which allows you to do things such as connect and disconnect VPN connections. More on this below. There is also a new option /showfiles, which prints the names of files that would have been operated on had the command actually been run. You can use this to determine what your command line wildcards actually resolve to. Other new options affecting wildcard expansion include /all, /justfiles, and /justfolders. See the command line reference below for more. Now back to the regular runmenu documentation... |
When you right-click a file or folder in Windows Explorer, a menu appears called a context menu. These context menus (also known as shortcut menus) allow you to perform various actions on the objects which are selected in Explorer, such as:
- Get file and folder properties.
- Rename files and folders.
- Delete files and folders.
- Cut, copy, and paste files and folders using the clipboard.
- Eject removable media such as CDs and format disks.
- Access third party functionality, such as the Eluent Tools context menu, on-demand antivirus scanning, file compression and archiving, and so forth.
Context menus provide quick access to a wide range of features, and people use them day in and day out. While most people manage their files inside Windows Explorer, there are many who continue to use the command line for certain tasks. Software developers, DOS diehards, Unix users, and pretty much anyone who ever had to write a batch file or script has a use for the command line, also known as the console or DOS prompt. (The latter term is really a misnomer for NT-based Windows like Windows XP, because the XP console isn't DOS at all.) Most Explorer context menu functionality is available at the command line through console programs provided by Microsoft and others who support context menus, but not everything. For example, if you've ever wanted to get a file's Properties from the console, or delete a file to the Recycle Bin from the console, or run your antivirus program's on-demand scanner from the console, only to find it doesn't provide console access to it, but it does provide context menu access, you were out of luck. The good news is, runmenu can probably help you.
In a nutshell, runmenu is a console program that allows you to run Windows Explorer context menu commands on files and folders from the command line. It probably goes without saying that context menus are, well, context-sensitive, so the available commands depend on the files or folders under consideration. To determine what your choices are, you can use runmenu's /list option, and that's what we'll look at first.
Listing Context Menu Commands: The /list option
|
E>runmenu /list a.exe Open (Verb: open) Run as... (Verb: runas) View Dependencies (Verb: View Dependencies) Eluent Tools\Find Eluent Tools\Replace Eluent Tools\Dir Eluent Tools\Attrib Eluent Tools\Touch Eluent Tools\EOL Eluent Tools\Tab Scan with Panda Antivirus Platinum WinRAR\Add to archive... (Verb: AddTo) WinRAR\Add to "a.rar" (Verb: Add) Pin to Start menu (Verb: pin) Send To\! NotePad Send To\! WordPad Send To\Any Folder... Send To\Clipboard as Name Send To\Desktop (create shortcut) Send To\Disc P Send To\Drag-to-Disc Drive (P) Send To\Mail Recipient Send To\My Documents Send To\3½ Floppy (A:) Cut (Verb: cut) Copy (Verb: copy) Create Shortcut (Verb: link) Delete (Verb: delete) Properties (Verb: properties) |
There are several things to note in this listing, which was the output of the command:
| runmenu /list a.exe |
Consider the first line of the output:
| Open (Verb: open) |
The text on the left side, Open, is what you would see on the context menu, were you to right-click on a.exe in Windows Explorer. The part in parentheses is the verb associated with this context menu item, and it provides a way for programs to access context menu commands for which they know the verbs. Runmenu allows you to invoke the item either by menu text or by verb, which is a good thing, because as you can see, not all context menu items define verbs. In addition, except for a handful of verbs predefined by Microsoft, there's no standardization of verb names, and simple verb names like "Add" may not be unique. In such cases, you may prefer to use the menu text to select the command.
Now, look carefully at the Eluent Tools, WinRAR, and Send To lines. See the backslashes? These lines represent submenus off the main context menu. That is, in Windows Explorer, the Eluent Tools, WinRAR, and Send To context menu items open submenus, whose contents are the text on the right sides of the backslashes; above, the backslash is sort of like that little arrow you see on the sides of menu items which open submenus. Runmenu allows you to run these commands by specifying their full names, which consist of their menu item text, read from primary menu to deepest submenu, in the same order in which the submenus open, each part separated from the next by a backslash. Thus, you can use "WinRAR\Add to archive..." with runmenu. Now, let's consider how to run a context menu command.
Running a Command: The /exec option
When you delete a file using the del console command, it's gone forever. That's a big difference from Windows Explorer, which normally moves the file to the Recycle Bin, where you can recover it later. Wouldn't it be great to have this option at the command line? Here's how to do it with runmenu.
| runmenu /exec:delete a.cpp |
A quick look into the Recycle Bin confirms a.cpp is there. I've configured my system not to prompt me when I delete files to the Recycle Bin. What about Windows straight out of the box? The default behavior is to display a dialog box that asks you if you really want to delete the file, even though it's going into the Recycle Bin, from which it can be recovered. This works just as you would expect when you use runmenu. However, things aren't always so simple in the world of context menus, as we shall soon see.
Running a Command: The /verb option
To display the Properties window for a file or folder, you can use either /exec or /verb. Here, we'll use /verb.
| runmenu /verb:properties a.exe |
If you're running Windows 2000 or Windows XP, you should have been rewarded by the Properties window for a.exe, in all its splendor. However, if you're running Windows 95, 98, or ME, you may not have seen anything, or perhaps the Properties window briefly appeared, only to take an immediate hike. If you're a software developer who's tried to use the ShellExecute or ShellExecuteEx APIs, you may have experienced the same thing. What's going on?
Without getting gruesomely technical, Windows provides a way for programs to create Explorer context menus and execute their commands. This is great, as far as it goes, but implicit in running many of these commands is the necessity of the program which ran them to stick around until the command has completed. Some commands execute in their entirety before returning control to the calling program, while others don't play quite so nice. The delete command is an example of the former, while properties is an example of the latter. Commands such as properties require the calling program to outlive everything they do, and in some versions of Windows, there is no predefined way for the calling program to determine when they've finished. This is not a problem for the primary creator of context menus, namely, Windows Explorer, because it's always running at least the desktop, but it poses a serious problem for a program like runmenu, which should carry out your command and return control to you as soon as your command has completed. That is, runmenu should terminate as soon as possible, but not too soon, and terminating too soon is what caused the Windows 98 Properties window to disappear right away. Thus was born the /wait option.
Waiting for Window
To fix the Windows 95/98/ME Properties window disappearance problem, use the /wait option along with its window argument:
| runmenu /verb:properties /wait:window a.exe |
This causes runmenu to watch for windows created by the context menu command and remain active until all have closed, at which point, it stops waiting and exits, returning control to whomever started it, typically you there at the console.
This is not entirely foolproof, but in practice, it seems to work well, and fortunately, it is not needed for modern versions of Windows such as Windows 2000 and Windows XP, which provide a proper way for context menu commands to keep their callers alive. (Shell extension developers should now go straight to MSDN and look up SHGetInstanceExplorer and SHCreateThread.) The major potential (and I stress the word potential) weakness in /wait:window is that as mentioned earlier, runmenu has to exit as soon as possible, which implies it can't wait forever for a window to appear. What if one doesn't, perhaps due to an error condition? Runmenu would wait forever. Not so obviously, once a window has been closed, a context menu handler can open a new window, and runmenu should allow for that. However, runmenu cannot wait forever for the thread which created the window to exit. It's easy to demonstrate that some context menu command implementations create threads that never exit, and a runmenu that waits indefinitely on them is a runmenu that waits forever.
Thus, runmenu strikes a compromise. The /wait:window option allows each thread created by the context menu command some time to create windows, and it expires threads that don't create windows within this interval. That is, it stops monitoring those threads. What about the threads which create windows? Runmenu monitors them as long as they have a window open, and only when all their windows have closed, and they haven't created any new windows within a short interval thereafter, does runmenu consider it safe to exit. This approach seems to work fine with the Windows 95/98/ME Properties command, but be aware of the issues just discussed if you ever consider using /wait:window with other commands. Strange window lifetime patterns can defeat it.
Waiting for Processes and Threads
Besides waiting on windows created by context menu commands, /wait can wait on processes and threads they create. For example, to run the antivirus program installed on this computer, I could use:
| runmenu "/exec:Scan with Panda Antivirus Platinum" a.exe |
This works just fine, and the Panda scanner window appears, just like it should. However, it's interesting to note that runmenu returns control to me immediately, before Panda has finished the scan. Particularly in batch files, you would want runmenu to return only after the command it started has finished, and it would be even nicer for runmenu to return that command's exit code, or errorlevel. You can accomplish both these goals by adding /wait:process to your command:
| runmenu "/exec:Scan with Panda Antivirus Platinum" /wait:process a.exe |
The /wait:process option causes runmenu to monitor processes, or less jargonly, plain old programs, started by context menu commands. When you use /wait:process, runmenu waits for these processes to exit, and it returns the exit code of the last one to exit, which you can find in the %errorlevel% environment level, just like a batch file programmer would expect.
For completeness, runmenu provides the /wait:thread option, but it should be used only as a last resort. It's vulnerable to context menus which create threads that never exit, and if used with such a menu, it will cause runmenu to wait forever. Fortunately, the /wait:window and /wait:process options satisfy most waiting scenarios.
Waiting Summarized
There are two major reasons to use the /wait option.
- The context menu command opens windows but doesn't use the method defined by Microsoft to control the lifetime of the calling program. Symptoms of this include windows that should appear but don't, windows which close immediately after they open, and commands that execute successfully but seem to accomplish nothing. To fix it, use /wait:window.
- The context menu command launches a program, and you would like runmenu to wait for it to terminate and return its exit code. Here, you would use /wait:process.
There's really no way to tell in advance if you need to use /wait. In general, you have to experiment. Runmenu makes this a little easier with its /verbose option.
Runmenu Talks Back: The /verbose option
When you use the /verbose option, runmenu prints out a list of interesting events that occur during its execution. These events include processes started by a context menu command, threads it creates, and calls to SHGetInstanceExplorer, the special function Windows provides to help context menu handlers control the lifetimes of their callers. Let's look at a couple of examples.
|
E>runmenu "/exec:Scan with Panda Antivirus
Platinum" /verbose a.exe runmenu: Executing command "Scan with Panda Antivirus Platinum". runmenu: CreateProcessA succeeded: runmenu: AppName: C:\Program Files\Panda Software\Panda Antivirus Platinum\PAVJOBS.EXE runmenu: CmdLine: E:\Temp\pavC.tmp/CONTEXTUAL PAV_FOG.opc "" |
The runmenu command above runs my antivirus program's on-demand scanner on a.exe. The runmenu output starts with the "Executing command" line. The following lines indicate that the antivirus context menu command used the Windows API CreateProcessA to start a new process, whose program file name, PAVJOBS.EXE, can be found in the next line. The remaining lines document the application name and command line the context menu command passed to CreateProcessA. Of course, because /wait was not used, runmenu did not wait for the PAVJOBS.EXE program to complete. To make runmenu wait for PAVJOBS.EXE and return its exit code, use /wait:process.
Let's take a look at the Windows 98 Properties command under /verbose.
| C>runmenu /verbose /verb:properties d.txt runmenu: CreateThread succeeded (id = 0xFFFDD6A3) for threadproc in module: SHELL32.DLL runmenu: Executing verb "properties". runmenu: CreateThread succeeded (id = 0xFFFC2537) for threadproc in module: SHLWAPI.DLL |
As you can see, the Windows 98 Properties command creates a couple of threads, which really isn't all that interesting. More relevant is the fact the window you were expecting to see either didn't show up at all or disappeared immediately. Knowing that /wait:thread can easily hang runmenu, as previously discussed, your first thought should be to try /wait:window. That's the proper solution. Here, /verbose mainly tells you that the Windows 98 Properties command didn't launch a new program, so that rules out /wait:process.
To complete our discussion of /verbose, let's look at the Properties command under Windows XP.
|
E>runmenu /verb:properties /verbose a.exe runmenu: Executing verb "properties". runmenu: SHGetInstanceExplorer was called. runmenu: CreateThread succeeded (id = 0xD70) for threadproc in module: SHLWAPI.dll runmenu: CreateThread succeeded (id = 0xD84) for threadproc in module: aclui.dll |
Notice that the Windows XP Properties command calls SHGetInstanceExplorer like a good citizen of the Windows Shell, and it should not be necessary to use /wait. Indeed, it works just fine without using /wait.
Windows defines a number of shell folders, many of which you're no doubt familiar with. For example, the Desktop folder, My Documents, Temporary Internet Files, and so forth are standard folders that exist somewhere on your hard drive and are thus known as physical folders. There are also a number of virtual folders, which do not map directly to physical folders on your hard drive; they include Control Panel, My Computer, Network Connections, and so on. Runmenu allows you to refer to both physical and virtual folders in the same convenient way. The syntax is as follows:
|
<ShellFolderName> <PhysicalShellFolderName>\additional path in file system <VirtualShellFolderName>\object in that virtual folder |
You can use the above on the runmenu command line just like normal filenames, though you will typically have to quote the argument so that the angle brackets won't be interpreted as redirection characters. Here are some examples.
1. To open your My Documents folder:
| runmenu /exec:open "<MyDocuments>" |
2. To list the contents of the Recycle Bin:
| runmenu /showfiles "<RecycleBin>\*" |
3. To restore an item from the Recycle Bin to its original location:
| runmenu /wait:thread /verb:undelete "<RecycleBin>\file.txt" |
Note that this is a rare operation for which the /wait:thread option seems to work, at least on Windows XP SP2. Unfortunately, it seems to be necessary, as the undelete verb is yet another verb Windows fails to protect with SHGetInstanceExplorer. (Sigh.)
4. To empty the Recycle Bin unconditionally (no prompt for confirmation):
| runmenu /verb:empty /nogui "<RecycleBin>" |
5. To connect and disconnect a VPN connection named "TheServer":
|
runmenu /wait:window /exec:Connect "<NetworkConnections>\TheServer" runmenu /wait:thread /exec:Disconnect "<NetworkConnections>\TheServer" |
Interestingly, the Windows Connect command does use SHGetInstanceExplorer, but it calls it too late to do any good, hence we need to use /wait:window. The Disconnect command requires /wait:thread, which works fine on Windows 2000, at least. (Hmmm, these /wait:thread commands seem to be multiplying in the virtual folder arena.)
Note that runmenu does not support multilevel paths for virtual shell folders. That is, you can refer to a virtual folder itself, or objects contained within that virtual folder, but that's as deep as runmenu currently goes. This restriction does not apply to physical shell folders, of course. Here's a list of the shell folders runmenu recognizes:
| Shell Folder Name | Minimum OS | Type |
| <AdminTools> | Win2K | Physical |
| <AltStartup> | WinNT | Physical |
| <AppData> | All | Physical |
| <CDBurning> | WinXP | Physical |
| <Common_AdminTools> | Win2K | Physical |
| <Common_AltStartup> | WinNT | Physical |
| <Common_AppData> | Win2K | Physical |
| <Common_Desktop> | WinNT | Physical |
| <Common_Documents> | WinNT | Physical |
| <Common_Favorites> | WinNT | Physical |
| <Common_Music> | WinXP | Physical |
| <Common_Pictures> | WinXP | Physical |
| <Common_ProgramFiles> | Win2K | Physical |
| <Common_Programs> | WinNT | Physical |
| <Common_StartMenu> | WinNT | Physical |
| <Common_Startup> | WinNT | Physical |
| <Common_Templates> | WinNT | Physical |
| <Common_Video> | WinXP | Physical |
| <ComputersNearMe> | All | Virtual |
| <ControlPanel> | All | Virtual |
| <Cookies> | All | Physical |
| <Desktop> | All | Physical |
| <Favorites> | All | Physical |
| <Fonts> | All | Virtual |
| <History> (Internet History items) | All | Physical |
| <Internet> | All | Virtual |
| <InternetCache> (Synonym for <TemporaryInternetFiles>) | All | Physical |
| <Local_AppData> | Win2K | Physical |
| <MyComputer> | All | Virtual |
| <MyDocuments> | All | Physical |
| <MyMusic> | WinXP | Physical |
| <MyPictures> | Win2K | Physical |
| <MyVideo> | WinXP | Physical |
| <NetHood> (Contains links within Network Neighborhood virtual folder) | All | Physical |
| <NetworkConnections> | All | Virtual |
| <NetworkNeighborhood> | All | Virtual |
| <Printers> | All | Virtual |
| <PrintHood> (Contains links within Printers virtual folder) | All | Physical |
| <Profile> | Win2K | Physical |
| <ProgramFiles> | Win2K | Physical |
| <Programs> (Start menu "programs" folder) | All | Physical |
| <Recent> (Recent documents) | All | Physical |
| <RecycleBin> | All | Virtual |
| <SendTo> | All | Physical |
| <StartMenu> | All | Physical |
| <Startup> | All | Physical |
| <System> | Win2K | Physical |
| <Templates> (Document templates) | All | Physical |
| <TemporaryInternetFiles> | All | Physical |
| <Windows> | Win2K | Physical |
Refresher Course: The /? option
When you can't remember the name of a program option, or you want to review the available options, use the runmenu /? option. Below, options in bold text comprise the set of action options, and every runmenu command line requires exactly one action.
|
E>runmenu /? runmenu: Runs Windows Explorer context menu commands on files and folders. runmenu \[/list | /exec:cmd | /verb:name | /show | /showfiles\] \[/wait: \[process | thread | window\]\] \[/keys: \[ctrl | shift\]\] \[/ext\] \[/nogui\] \[/all\] \[/justfiles\] \[/justfolders\] \[/verbose\] file and/or folder names runmenu \[/? | /version\] |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
You must use exactly one of /list, /exec, /verb, /show, /showfiles, /?, and /version. |
Wrapping Up
This completes our runmenu tutorial. Please send any questions or comments you have to [email protected] and visit our web site at http://www.eluent.com. Thanks for trying runmenu.
Copyright © 2003, 2004 Eluent Software, L.L.C. All rights reserved.
