NAME

Win32::CtrlGUI::State - an OO system for controlling Win32 GUI windows through a state machine

SYNOPSIS

use Win32::CtrlGUI::State

Win32::CtrlGUI::State->newdo(
  seq =>
  [atom => criteria => [pos => qr/Notepad/],
    action => "!fo"],

  [ seq_opt =>
    [ seq =>
      [atom => criteria => [pos => 'Notepad', qr/^The text in the .* file has changed/i],
        action => "!y"],

      [dialog =>
        criteria => [pos => 'Save As'], action => "!nC:\\TEMP\\Saved.txt{ENTER}",
        cnfm_criteria => [pos => 'Save As', qr/already exists/i], cnfm_action => "!y"],
    ],

    [dialog => criteria => [pos => 'Open', 'Cancel'],
      action => "!n{1}".Win32::GetCwd()."\\demo.pl{1}{HOME}{2}{ENTER}"],
  ],

  [dialog => criteria => [pos => qr/Notepad/],
    action => "!fx"],
);

DESCRIPTION

Win32::CtrlGUI::State is used to define a set of state, the desired response to those state, and how those states fit together so as to make it easier to control Win32 GUI windows. Think of it as intelligent flow-control for Win32 GUI control.

The system itself is object-oriented - there are a number of types of states, most of which accept a list of other states as parameters. If you think about it, code-blocks are objects. So are if-then statements. So, rather than write my own language and parser for doing flow-control of GUI windows, I made an OO system within Perl. Much easier than writing a parser.

The basic state subclasses are:

atom

These are used to specify single "events" in the system. Passed to the constructor are a set of criteria and the action to take when those criteria are met. If that atom is currently active and the criteria become met, the action will be executed. It also takes on optional timeout parameter.

seq

This state takes a list of other states as a parameter. Those states will be waited for one-by-one and the actions executed. No state is allowed to be skipped.

seq_opt

This state is similar to seq, except that any state may be skipped except for the last one. The last state in the list is sometimes referred to as the exit criteria.

fork

This state takes a list of other states as a parameter. The first state to be met will be executed and none of the others will. Think of it as a select-case statement. Of course, seq and seq_opt states can be passed to the fork state.

dialog

The dialog state was created to deal with a common problem, that is to say waiting for a window to pop up, sending it text, and then waiting for it to disappear. In addition, the dialog state takes an optional set of parameters for a "confirmation" window. If the confirmation window shows up before the original window disappears, the confirmation action will be executed. The dialog state is implemented using a seq state and, if there is a confirmation specification, a seq_opt state.

METHODS

new

The first parameter to the new method is the subclass to create - atom, seq, seq_opt, etc. The _new method for that class is then called and the remaining parameters passed.

_new

The default _new method takes a list of hash entries, places the object in the init state, and returns the object. Also, if it finds an array reference in $self-E<GT>{criteria}, it creates a new Win32::CtrlGUI::Criteria object based on it.

newdo

This calls new and then do_state. It returns the Win32::CtrlGUI::State object after it has finished executing.