********************************************************************************************
*********** VISUAL PINMAME COM OBJECT PROPERTY/METHOD REFERENCE ****************************
********************************************************************************************

The following is a list of all properties and methods made accessible by VPinMAME's COM 
interface.

=======================
 Visual PinMAME Control
=======================

************
*Properties*
************

GameName                                                (Read/Write)
--------------------------------------------------------------------
  Initializes VPinMAME for game "gameName".

  gameName: PinMAME short name (e.g. "tz_94h")

  Errors : An emulation is already running
           "gameName" isn't a valid pinmame short gamename.

  Example:
    Controller.GameName = "tz_94h"
    if Controller.GameName = "tz_94h" Then

Running                                                  (Read-Only)
--------------------------------------------------------------------
  Returns True if the emulation is running, false otherwise.

  Example:
    If Controller.Running Then ...

Pause                                                   (Read/Write)
--------------------------------------------------------------------
  Setting this property to True will "Pause" the current emulation. 
  Setting it to false will "Resume" a paused emulation.

  Example:
    Controller.Pause = True
    If Controller.Pause Then ...

*********
*Methods*
*********

Run parentWindow, minVersion
--------------------------------------------------------------------
  Starts Visual PinMAME emulation of game specified with .GameName property

  parentWindow: handler of window to put output in.
                Default=0 -> open in a new window
  minVersion:   Minimum version of Visual PinMAME (e.g. 100 for 1.00) required to
                run this game
                Default=any version

  Err: An emulation is already running
       Game is not specified (via .GameName)
       Current VPinMAME version is less than required version
       Can't start game. (Most probable cause is that the
                          Game ROMs could not be found)
       User answerd "no" to being legally entitled to play game

  Example:
    Controller.Run 0,110  ' VPinMAME 1.1 or higher required

Stop
--------------------------------------------------------------------
  Stops Visual PinMAME emulation.

  Example:
    Controller.Stop


===============
 Game settings
===============

************
*Properties*
************

Dip(dipBank)                                            (Read/Write)
--------------------------------------------------------------------
  Sets the Dip switch settings for the current game.
  Do this before .Run since most games only checks the Dips at startup.

  dipBank:  dip 1-8 = bank 0, dip 9-16 = bank 1 ...
  value:    binary value to set the dips 1=On, 0=off

  Example:
    Controller.Dip(0) = &H55
    Controller.Dip(1) = &Haa

HandleMechanics                                         (Read/Write)
--------------------------------------------------------------------
  If the game has a PinMAME simulator it can be used to simulate hardware "toys".

  value: Mechnics VPinMAME should handle. Look at the PinMAME simulator source
         for alternatives.

  Example:
    ' For TZ: 1=Clock, 2=Gumball Machine
    Controller.HandleMechanics = 1+2  ' Handle both Clock and gumball machine

WPCNumbering                                             (Read-Only)
--------------------------------------------------------------------
  Determine if game uses WPCNumbering of Switches and Lamps
  WPCNumbering = Column*10 + Row (11,12,13,14,15,16,17,18,21,22...)
  non WPCnumbering = 1,2,3,4,...

  Example:
    If WPCNumbering Then firstSwitch = 1 Else firstSwitch = 11


*********
*Methods*
*********

None

===================
 Game input/output
===================

************
*Properties*
************

Lamp(number)                                             (Read-Only)
--------------------------------------------------------------------
  Get status of a single lamp

  number:     lamp #
  return: True = Lamp on, False = Lamp off

  Example: (In VBScript is True = -1)
    Lamp32.Status = Abs(Controller.Lamp(32))

Solenoid(number)                                         (Read-Only)
--------------------------------------------------------------------
  Get status of a single solenoid

  number:     solenoid #
  return: True = solenoid on, False = solenoid off

  Example: (In VBScript is True = -1)
    If Controller.Solenoi(5) Then ...

Switch(number)                                          (Read/Write)
--------------------------------------------------------------------
  Get or Set status of a single switch

  number: Switch #
  value: True = set switch on, False = set switch off

  Example:
    Controller.Switch(25) = True
    Controller.Switch(18) = Not Controller.Switch(18)  ' toggle switch


GIString(number)                                         (Read-Only)
--------------------------------------------------------------------
 ** = Works only for WPC Games!

  Get status of a single GI string 

  number: GI string # (0-4)
  return: True = GI string on, False = GI string off

  Example:
    If Controller.GIString(0) then
      BackboxLamp1.Status = On

*********
*Methods*
*********

None

===================================================================
 Aggregate polling functions

 These functions return a matrix with everything that has
 changed since last call. The array  contains the following info
 Matrix(0,0) Number of first changed item
 Matrix(0,1) New status of first item
 Matrix(1,0) Number of second changed item
 ...
====================================================================

************
*Properties*
************

ChangedLamps                                             (Read-Only)
--------------------------------------------------------------------
  Returns which lamps have changed since last call to this property!

  Example:
    chg = Controller.ChangedLamps
    count = UBound(chg)
    if count > 0 Then
      For ii = 0 to count
        Text = "Lamp " & chg(ii,0) & "=" & chg(ii,1)
      Next
    end if

ChangedSolenoids                                         (Read-Only)
--------------------------------------------------------------------
  Same as ChangedLamps but for solenoids

ChangedGI                                                (Read-Only)
--------------------------------------------------------------------
  Same as .ChangedLamps but for GI strings

*********
*Methods*
*********

None

=================
 Customization
=================

************
*Properties*
************

SplashInfoLine                                          (Read/Write)
--------------------------------------------------------------------
  Game credits to display in startup splash screen.

  Example:
    Controller.SplashInfoLine = "Game design by ..."

ShowOptsDialog parentWindow
--------------------------------------------------------------------
  Opens the options dialogue for current game

  Example:
    Controller.ShowOptDialog

ShowAboutDialog                  
--------------------------------------------------------------------
  About box for VPinMAME

  Example:
    Controller.ShowAboutDialog

*********
*Methods*
*********

None

==============
 Debugging
==============

************
*Properties*
************

ShowDMDOnly                                            (Read/Write)
--------------------------------------------------------------------
  Enable/disable VPinMAME status matrices.

  Example:
    Controller.ShowDMDOnly = False  ' display lamp,switch and solenoid matrix

HandleKeyboard                                         (Read/Write)
--------------------------------------------------------------------
  If set to True, VPinMAME will process the keyboard. 
  Standard MAME keys can be used in VPinMAME output window.
  If set to False, the scripting language will process the keyboard.

  Example:
    Controller.HandleKeyboard = True

ShowTitle                                              (Read/Write)
--------------------------------------------------------------------
  Show title bar on VPinMAME output window (to move it around)

  Example:
    Controller.ShowTitle = True

*********
*Methods*
*********

None

==============================================================
 Events - May not be supported in all scripting environments!
==============================================================

OnSolenoid(solenoidNo, isActive)
--------------------------------------------------------------------
Called whenever a solenoid changes state

OnStateChange(newState)
--------------------------------------------------------------------
Called whenever the emulation is started or stopped
(not called on Pause)

