[ANN] MWCG - MAMEWah Window Caption Grabber

[roger]

Hi all.

I created an application that takes advantage of the hidden window caption in MAMEWah. It can execute external applications when certain changes to the caption (e.g. change of emulator or change of game selection) occur.

MWCG is freeware and can be downloaded here:

http://freeware.the-meiers.org/arcade.html



To provide a better idea of what MWCG is, here is an excerpt of the readme.txt document that is included with the download:



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_enter
  This event occurs when MAMEWah is started or comes to the foreground.

mamewah_leave
  This event occurs when MAMEWah is quit or is pushed to the background by
  another application.

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_enter_commandlines    - applications to be automatically launched
                                  when a MAMEWah caption is first detected.
  mamewah_leave_commandlines    - applications to be automatically launched
                                  whenever the MAMEWah caption disappears,
                                  e.g. when MAMEWah quits or when an emulator
                                  is running.
  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_enter_commandlines      [emurootpath]\write_lcd.bat [emurootpath]\mamewah\lcds\start_text.lcd
mamewah_leave_commandlines      [emurootpath]\write_lcd.bat [emurootpath]\mamewah\lcds\quit_text.lcd
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".

[Ginsu Victim]

I'm definitely going to have to try this out. Thanks!