NAME

Win32::CtrlGUI::Criteria - an OO interface for expressing state criteria

SYNOPSIS

use Win32::CtrlGUI::Criteria

my $criteria = Win32::CtrlGUI::Criteria->new(pos => qr/Notepad/);


use Win32::CtrlGUI::State

my $state = Win32::CtrlGUI::State->new(atom => criteria => [pos => qr/Notepad/], action => "!fo");

DESCRIPTION

Win32::CtrlGUI::Criteria objects represent state criteria, and are used by the Win32::CtrlGUI::State system to determine when a state has been entered. There are three main subclasses - Win32::CtrlGUI::Criteria::pos, Win32::CtrlGUI::Criteria::neg, and Win32::CtrlGUI::Criteria::arbitrary. These will be discussed in the documentation for Win32::CtrlGUI::Criteria, rather than in the implementation classes.

METHODS

new

The first parameter to the new method is the subclass to create - pos, neg, or arbitrary. The remaining parameters are passed to the new method for that class. Thus, Win32::CtrlGUI::Criteria->new(pos = qr/Notepad/)> is the same as Win32::CtrlGUI::Criteria::pos->new(qr/Notepad/).

The passed parameters for the pos and neg subclasses are the window criteria and childcriteria, with the same options available as for Win32::CtrlGUI::wait_for_window. The pos subclass will return true (i.e. the criteria are met) when a window matching those criteria exists. The neg subclass will return true when no windows matching the passed criteria exist. The pos subclass will return a Win32::CtrlGUI::Window object for the matching window when it returns true.

The arbitrary subclass takes a code reference and a list of hash parameters. The hash parameters will be added to the Win32::CtrlGUI::Criteria::arbitrary object, and the code reference will be passed a reference to the Win32::CtrlGUI::Criteria::arbitrary object at run-time. This enables the code reference to use the Win32::CtrlGUI::Criteria::arbitrary to store state. The code reference should return true when evaluated if the state criteria have been met.

The stringify method is called by the overloaded stringification operator and should return a printable string suitable for debug work.

The is_recognized method is called to determine if the criteria are currently being met.