/ 
Win32-CtrlGUI-0.21
River stage zero No dependents
/ Win32::CtrlGUI::State

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{1}{ENTER}",
                   timeout => 5,
                   cnfm_criteria => [pos => 'Save As', qr/already exists/i],
                   cnfm_action => "!y"],
      ],

      dialog => [criteria => [pos => 'Open', 'Cancel'],
                 action => "!n{1}".Win32::GetCwd()."\\test.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. Also, it lets you use a Tk debugger to observe your scripts as they execute.

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.

multi

This is an abstract parent class intended to support such classes as seq, seq_opt, fork, and loop. The preferred syntax for passing states to multi subclasses is:

multi => [
  parameter => value,
  state1_class => [ state1 parameters ],
  state2_class => [ state2 parameters ],
],

Alternate legal syntaxes include:

multi => [
  [state1_class => state1 parameters],
  Win32::CtrlGUI::State:state2_class->new(state2 parameters),
]

That is to say, multi class objects expect their parameter array to consist of a sequence of these four "entities" (which can be alternated as desired):

  • parameter => value pairs

  • state_class => array ref to state parameters pairs

  • array ref to state1_class, state parameters

  • Win32::Ctrl::GUI::State class object

seq

The passed 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. That is to say, execution will "jump" to whichever state shows up first. Once a state has been jumped to, the previous states will not be executed. The last state in the list is sometimes referred to as the exit criteria.

fork

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.

loop

Lets you do loops:) Loops take two optional parameters - timeout and body_req and either one or two states. The first state is the "body" state and the second the "exit" state. I strongly encourage the use of the dialog state when building loops (this is especially critical for loops where the body only has one state - otherwise, simple atoms may trigger multiple times off of the same window).

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. Note that waiting for the window to disappear is based on the window handle, not on the criteria, which makes this safe to use in loops.

Of note, if you pass a multi state to another multi state, remember that the "child" state has to finish executing before the parent can continue. For instance, in the following code, if the window "Foo" is seen, seeing the window "Done" will not cause the loop to exit until the window "Bar" has been seen.

Win32::CtrlGUI::State->newdo(
  loop => [
    seq => [
        dialog => [criteria => [pos => 'Foo'], action => '{ENTER}'],
        dialog => [criteria => [pos => 'Bar'], action => '{ENTER}'],
    ],
    seq => [
        atom => [criteria => [pos => 'Done'], action => '{ENTER}'],
    ],
  ]
);

STATES

It is important to note that Win32::CtrlGUI::State objects can be in one of six different states. They are:

init

This is the state before the object has had any methods invoked on it.

srch

This is the state the object enters after is_recognized is first called on it, but before the desired state has been recognized. Distinguishing between <init> and <srch> allows time outs to be implemented.

rcog

This is the state the object enters after its criteria are first recognized.

actn

This is the state the object enters when do_action_step is first called.

done

This is the state the object enters after the action is fully completed.

fail

This is the state the object enters when a time out has occurred (this doesn't apply to loop states, but does apply to atom states).

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.

newdo

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

is_recognized

This is a generic method and has to be overriden by the subclass. When is_recognized is called, it should return true if this state is currently or has ever been recognized (once a path is followed, the path needs to be followed until the end.)

wait_recognized

This will wait until a given state has been recognized.

do_action_step

Because the whole system is capable of being driven in an asynchronous manner from the very top (which makes it possible to run the Win32::CtrlGUI::State system from within Tk, for instance), actions need to be executable in a non-blocking fashion. The method call do_action_step is crucial to that. Remember that there is an action "delay", so do_action_step will keep returning, but not setting the state to done, until that delay is used up and the action can actually be executed. The system does not yet allow for multi-part actions in and of themselves (for instance, it will still block if a sendkeys action involves internal delays).

wait_action

This will wait until the action for a given state has been completed. It should only be called after is_recognized returns true.

do_state

This will wait until the state is recognized (by calling wait_recognized) and then execute the action (by calling wait_action).

reset

The reset method automagically resets the state as if nothing had ever happened.