|
MWCG - MAMEWah Window Caption Grabber (c) Copyright 2009 Roger Meier All rights reserved http://freeware.the-meiers.org VERSION HISTORY =============== 1.1.1 - 5/6/2009 ---------------- - Bug fixes. 1.1.0 - 3/3/2009 ---------------- - Added 2 new events: mamewah_startup, mamewah_exit 1.0.0 - 2/15/2009 ----------------- - Initial Release LICENSE ======= THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. WHAT IS IT? =========== In short, MWCG is a windowless application that captures the window title (caption) of the frontmost window at a predefined polling interval. If the frontmost window is the hidden MAMEWah window, MWCG can be enabled to execute external applications based on the contents of the window caption. WHAT IS THE HIDDEN MAMEWAH WINDOW CAPTION? ========================================== Starting with v1.5, MAMEWah has included a feature that makes information about the the currently selected emulator and game available via the caption (title) of a hidden window (frame) in real time. I.e. there is an invisible window with an invisible title bar (aka caption), and whenever the game selection in MAMEWAh changes, this caption is updated. From v1.5 through v1.63, the format of the caption was as follows: MAMEWAH - Emulator Title: Game Description (Romname) For example, when using MAME with the game Gridlee selected, the caption would be as follows: MAMEWAH - M.A.M.E.: Gridlee (gridlee) Since v1.64, MAMEWah employs an extended caption format that also includes the name of the emulator, such as this: MAMEWAH - Emulator Title (emuname): Game Description (Romname) For the previous example, the caption would read as follows: MAMEWAH - M.A.M.E. (mame): Gridlee (gridlee) When running, MWCG polls MAMEWah's hidden caption periodically and triggers command lines defined in an INI file (mwcg.ini) when a change in the caption (i.e. an "event") is detected. This can be useful for a variety of applications such as displaying game information on an external LCD display when a game is selected, changing colors of LEDs in the control panel or playing audio files when the current emulator changes, etc. WHAT TYPES OF EVENTS ARE DETECTED? ================================== The following event types are detected by MWCG: startup_app This event occurs when MWCG starts exit_app This event occurs when MWCG quits mamewah_startup This event occurs when a MAMEWah caption is detected for the first time after MWCG started, e.g. when MAMEWah is started. mamewah_exit This event occurs when a MAMEWah caption is no longer detected, i.e. after MAMEWah quits. mamewah_enter This event occurs when the hidden MAMEWah window becomes the frontmost window, e.g. when MAMEWah is started or comes to the foreground after an emulator quits. mamewah_leave This event occurs when MAMEWah is no longer the frontmost window, e.g. when MAMEWah is quit or is pushed to the background by another application (e.g. an emulator). emu_changed This event occurs when MWCG detects that the emulator name or title changed in the MAMEWah caption, e.g. when an other platform is selected. This event also occurs when mamewah_enter occurs. game_changed This event occurs when MWCG detects that the game name or description changed in the MAMEWah caption, e.g. when the game selection changed. This event also occurs when mamewah_enter or emu_change occurs. When several events occurs simultaneously, they are prioritized in the following order: 1. mamewah_enter 2. emu_change 3. game_change Command lines that are set to execute at the occurance of these events will be executed in the order of priority. HOW TO USE IT ============= INSTALLATION ------------ MWCG comes without an installer and can be placed anywhere on the harddrive as long as the correct folder structure is maintained. I.e. the "mwcg.ini" file as well as the "mwcg Libs" folder must reside in the same location as the "wmcg.exe" and "mwcg_quit.exe" executables. SYSTEM REQUIREMENTS ------------------- MWCG should work fine on Windows 2000 and newer. EXECUTION --------- MWCG.exe can be executed via the command line or by double-clicking the application icon in Explorer. Once launched, MWCG runs as icon in the system tray. MWCG logs its status in mwcg.log. Ideally, mwcg.exe is launched via the "startup_app_commandlines" setting in mamewah.ini, e.g. like this: startup_app_commandlines [emurootpath]\mwcg\mwcg.exe{nowait} The {nowait} flag must be used since mwcg.exe needs to run concurrently with MAMEWah. As an option, mwcg can be executed with the "-logevents" argument to enable the logging of events in addition to just status information, e.g.: startup_app_commandlines [emurootpath]\mwcg\mwcg.exe -logevents{nowait} TERMINATION ----------- MWCG can be quit either via the 'Exit' option in the system tray menu as well as by executing "mwcg_quit.exe", which tells a currently running instance of MWCG to quit. The latter option is intended as a means to quit MWCG from MAMEWah, e.g. via the "exit_app_commandlines" setting, like this: exit_app_commandlines [emurootpath]\mwcg\mwcg_quit.exe{nowait} Using {nowait} is optional, but it might speed up the quitting of MAMEWah on slower systems. CONFIGURATION ------------- The configuration of MWCG is achieved via the "mwcg.ini" configuration file. "mwcg.ini" includes the following settings: Misc Settings: emulator_root_path - path, e.g. c:\emu polling_interval - Interval in which the window caption is sampled, in milliseconds. Default = 1000 MAMEWAh Event Settings: mamewah_startup_commandlines - applications to be automatically launched when a MAMEWah caption is first detected. mamewah_exit_commandlines - applications to be automatically launched whenever the MAMEWah caption is no longer detected, i.e. when MAMEWah quits. mamewah_enter_commandlines - applications to be automatically launched when the MAMEWah caption comes to the foreground. mamewah_leave_commandlines - applications to be automatically launched whenever the MAMEWah is no longer in the foreground. emu_changed_commandlines - applications to be automatically launched whenever an emulator change is detected. game_changed_commandlines - applications to be automatically launched whenever a game change is detected. MWCG Event Settings: startup_app_commandlines - applications to be automatically launched when MWCG starts. exit_app_commandlines - applications to be automatically launched when MWCG quits. Similar to MAMEWah, any settings involving "_commandlines" should be specified the same way they would be called from a commandline. Multiple commandlines can be specfied for each setting by separating them by semilocons. In order for MWCG to use the commandlines dynamically, key parts can be replaced by place-holders. The following list shows the place-holders that can be used in commandlines: [emurootpath] - path set in emulator_root_path (mwcg.ini) [emutitle] - current emulator title (from the MAMEWAh caption) [emuname] - current emulator name (from the MAMEWAh caption. Use emunames.ini for MAMEWah v1.63 or earlier *) [description] - full game name (from the MAMEWAh caption) [name] - romname (from the MAMEWAh caption) MWCG also supports the following flags for use in commandlines: {wait} - tells MWCG not to continue execution until the called app is quit (default) {nowait} - tells MWCG to continue execution while the called app is launched (ie app will run at the same time) EXAMPLE CONFIGURATION --------------------- The following example sets up MWCG to poll the window caption at a 500ms interval and to update an external LCD display upon certain events, using a script called "write_lcd.bat": ### mwcg.ini ### ### Misc Settings ### emulator_root_path c:\emu polling_interval 500 ### MAMEWAh Event Settings ### mamewah_startup_commandlines [emurootpath]\write_lcd.bat [emurootpath]\mamewah\lcds\start_text.lcd mamewah_exut_commandlines [emurootpath]\write_lcd.bat [emurootpath]\mamewah\lcds\quit_text.lcd mamewah_enter_commandlines [emurootpath]\write_lcd.bat [emurootpath]\mamewah\lcds\start_text.lcd mamewah_leave_commandlines emu_changed_commandlines [emurootpath]\write_lcd.bat [emurootpath]\[emuname]\lcds\lcd_fe_text.lcd game_changed_commandlines [emurootpath]\write_lcd.bat [emurootpath]\[emuname]\lcds\[name].lcd ### MWCG Event Settings ### startup_app_commandlines exit_app_commandlines [emurootpath]\write_lcd.bat [emurootpath]\shutdown.lcd MAMEWAh v1.63 OR EARLIER ------------------------ MAMEWah versions 1.63 or earlier did not include the emulator name [emuname] in the hidden window caption, it only included the emulator title. In order for MWCG to be able to use the [emuname] placeholder for MAMEWah v1.63 or earlier, an "emunames.ini" lookup table has to be placed in the same folder as mwcg.exe so that MWCG can look up the emulator name for a given emulator title. "emunames.ini" must be formatted as a TAB separated lookup table file with one entry per line, such as this: EMUTITLE1<TAB>EMUNAME1<CR+LF> EMUTITLE2<TAB>EMUNAME2<CR+LF> EMUTITLE3<TAB>EMUNAME3<CR+LF> EMUTITLE4<TAB>EMUNAME4<CR+LF> In order for MWCG to correctly translate emulator titles to emulator names, the titles have to be exactly as specified in the "emulator_title" setting in the respective emuname.ini configuration files used by MAMEWah. The emulator titles and emulator names have to be separated by a TAB character (ascii code 9). Each line has to be terminated with line break (CR+LF). E.g. for MWCG to translate "M.A.M.E." to "mame", the "emunames.ini" file requires the following entry: M.A.M.E mame If MWCG detects an "emunames.ini" file at startup, it will assume that the MAMEWah version used is 1.63 or earlier, and it will always use "emunames.ini" to translate emulator titles to emulator names. NOTE: For MAMEWAh v1.64 or newer, the "emunames.ini" file MUST NOT be present in order for MWCG to extract the emulator name from MAMEWah's hidden window caption instead of using "emunames.ini". |