The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

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

VERSION

This document describes version 0.32 of Win32::CtrlGUI::Criteria, released January 10, 2015 as part of Win32-CtrlGUI version 0.32.

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.

stringify

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

is_recognized

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

CONFIGURATION AND ENVIRONMENT

Win32::CtrlGUI::Criteria requires no configuration files or environment variables.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

AUTHOR

Toby Ovod-Everett <toby AT ovod-everett.org>

Win32::CtrlGUI is now maintained by Christopher J. Madsen <perl AT cjmweb.net>

Please report any bugs or feature requests to <bug-Win32-CtrlGUI AT rt.cpan.org> or through the web interface at http://rt.cpan.org/Public/Bug/Report.html?Queue=Win32-CtrlGUI.

You can follow or contribute to Win32-CtrlGUI's development at http://github.com/madsen/win32-ctrlgui.

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Toby Ovod-Everett.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.