NAME
    X11::GUITest - Provides GUI testing/interaction facilities.

    Developed by Dennis K. Paulsen

VERSION
    0.16

    Please consult 'docs/Changes' for the list of changes between module
    revisions.

SYNOPSIS
    For additional examples, please look under the 'eg/' sub-directory.

      use X11::GUITest qw/
        StartApp
        WaitWindowViewable
        SendKeys
      /;

      # Start gedit application
      StartApp('gedit');

      # Wait for application window to come up and become viewable. 
      my ($GEditWinId) = WaitWindowViewable('gedit');
      if (!$GEditWinId) {
        die("Couldn't find gedit window in time!");
      }

      # Send text to it
      SendKeys("Hello, how are you?\n");

      # Close Application (Alt-f, q).
      SendKeys("%(f)q");

      # Handle gedit's Question window if it comes up when closing.  Wait
      # at most 5 seconds for it.
      if (WaitWindowViewable('Question', undef, 5)) {
        # DoN't Save (Alt-n)
        SendKeys("%(n)");
      }

INSTALLATION
      perl Makefile.PL
      make
      make test
      make install

DEPENDENCIES
    An X server with the XTest extensions enabled. This seems to be the
    norm. If it is not enabled, it usually can be by modifying the X server
    configuration (i.e., XF86Config).

    Also, the standard DISPLAY environment variable is utilized to determine
    the host, display, and screen to work with. By default it is usually set
    to ":0.0" for the localhost. However, by altering this variable one can
    interact with applications under a remote host's X server. To change
    this from a terminal window, one can utilize the following basic syntax:
    export DISPLAY=<hostname-or-ipaddress>:<display>.<screen> Please note
    that under most circumstances, xhost will need to be executed properly
    on the remote host as well.

DESCRIPTION
    This Perl package is intended to facilitate the testing of GUI
    applications by means of user emulation. It can be used to test/interact
    with GUI applications; which have been built upon the X library or
    toolkits (i.e., GTK+, Xt, Qt, Motif, etc.) that "wrap" the X library's
    functionality.

FUNCTIONS
    Parameters enclosed within [] are optional.

    If there are multiple optional parameters available for a function and
    you would like to specify the last one, for example, you can utilize
    undef for those parameters you don't specify.

    REGEX in the documentation below denotes an item that is treated as a
    regular expression. For example, the regex "^OK$" would look for an
    exact match for the word OK.

    FindWindowLike TITLEREGEX [, WINDOWIDSTARTUNDER]
            Finds the window Ids of the windows matching the specified title
            regex. Optionally one can specify the window to start under;
            which would allow one to constrain the search to child windows
            of that window.

            An array of window Ids is returned for the matches found. An
            empty array is returned if no matches were found.

              my @WindowIds = FindWindowLike('gedit');
              # Only worry about first window found
              my ($WindowId) = FindWindowLike('gedit');

    WaitWindowLike TITLEREGEX [, WINDOWIDSTARTUNDER] [, MAXWAITINSECONDS]
            Waits for a window to come up that matches the specified title
            regex. Optionally one can specify the window to start under;
            which would allow one to constrain the search to child windows
            of that window.

            One can optionally specify an alternative wait amount in
            seconds. A window will keep being looked for that matches the
            specified title regex until this amount of time has been
            reached. The default amount is defined in the DEF_WAIT constant
            available through the :CONST export tag.

            If a window is going to be manipulated by input,
            WaitWindowViewable is the more robust solution to utilize.

            An array of window Ids is returned for the matches found. An
            empty array is returned if no matches were found.

              my @WindowIds = WaitWindowLike('gedit');
              # Only worry about first window found
              my ($WindowId) = WaitWindowLike('gedit');

              WaitWindowLike('gedit') or die("gedit window not found!");

    WaitWindowViewable TITLEREGEX [, WINDOWIDSTARTUNDER] [,
    MAXWAITINSECONDS]
            Similar to WaitWindow, but only recognizes windows that are
            viewable. When GUI applications are started, their window isn't
            necessarily viewable yet, let alone available for input, so this
            function is very useful.

            Likewise, this function will only return an array of the
            matching window Ids for those windows that are viewable. An
            empty array is returned if no matches were found.

    WaitWindowClose WINDOWID [, MAXWAITINSECONDS]
            Waits for the specified window to close.

            One can optionally specify an alternative wait amount in
            seconds. The window will keep being checked to see if it has
            closed until this amount of time has been reached. The default
            amount is defined in the DEF_WAIT constant available through the
            :CONST export tag.

            zero is returned if window is not gone, non-zero if it is gone.

    ClickWindow WINDOWID [, X Offset] [, Y Offset] [, Button]
            Clicks on the specified window with the mouse.

            Optionally one can specify the X offset and Y offset. By
            default, the top left corner of the window is clicked on, with
            these two parameters one can specify a different position to be
            clicked on.

            One can also specify an alternative button. The default button
            is M_LEFT, but M_MIDDLE and M_RIGHT may be specified too. Also,
            you could use the logical Id for the button: M_BTN1, M_BTN2,
            M_BTN3, M_BTN4, M_BTN5. These are all available through the
            :CONST export tag.

            zero is returned on failure, non-zero for success

    IsChild PARENTWINDOWID WINDOWID
            Determines if the specified window is a child of the specified
            parent.

            zero is returned for false, non-zero for true.

    QuoteStringForSendKeys STRING
            Quotes {} characters in the specified string that would be
            interpreted as having special meaning if sent to SendKeys
            directly. This function would be useful if you had a text file
            in which you wanted to use each line of the file as input to the
            SendKeys function, but didn't want any special interpretation of
            the characters in the file.

            Returns the quoted string, undef is returned on error.

              # Quote  ~, %, etc.  as  {~}, {%}, etc for literal use in SendKeys. 
              SendKeys( QuoteStringForSendKeys('Hello: ~%^(){}+') );

    StartApp COMMANDLINE
            Uses the shell to execute a program. A primative method is used
            to detach from the shell, so this function returns as soon as
            the program is called. Useful for starting GUI applications and
            then going on to work with them.

            zero is returned on failure, non-zero for success

              StartApp('gedit');

    RunApp COMMANDLINE
            Uses the shell to execute a program until its completion.

            Return value will be application specific, however -1 is
            returned to indicate a failure in starting the program.

              RunApp('/work/myapp');

    ClickMouseButton BUTTON
            Clicks the specified mouse button. Available mouse buttons are:
            M_LEFT, M_MIDDLE, M_RIGHT. Also, you could use the logical Id
            for the button: M_BTN1, M_BTN2, M_BTN3, M_BTN4, M_BTN5. These
            are all available through the :CONST export tag.

            zero is returned on failure, non-zero for success.

    <Documentation Continued...>

    SetEventSendDelay DELAYINMILLISECONDS
            Sets the milliseconds of delay between events being sent to the
            X display. It is usually not a good idea to set this to 0.

            Please note that this delay will also affect SendKeys.

            Returns the old delay amount in milliseconds.

    GetEventSendDelay
            Returns the current event sending delay amount in milliseconds.

    SetKeySendDelay DELAYINMILLISECONDS
            Sets the milliseconds of delay between keystrokes.

            Returns the old delay amount in milliseconds.

    GetKeySendDelay
            Returns the current keystroke sending delay amount in
            milliseconds.

    GetWindowName WINDOWID
            Returns the window name for the specified window Id. undef is
            returned if name could not be obtained.

              # Return the name of the window that has the input focus.
              my $WinName = GetWindowName(GetInputFocus());

    SetWindowName WINDOWID, NAME
            Sets the window name for the specified window Id.

            zero is returned on failure, non-zero for success.

    GetRootWindow
            Returns the root window Id. This is the top/root level window
            that all other windows are under.

    GetChildWindows WINDOWID
            Returns an array of the child windows for the specified window
            Id.

    MoveMouseAbs X, Y
            Moves the mouse cursor to the specified absolute position.

            zero is returned on failure, non-zero for success.

    GetMousePos
            Returns an array containing the position of the mouse cursor.

              my ($x, $y) = GetMousePos(); 

    PressMouseButton BUTTON
            Presses the specified mouse button. Available mouse buttons are:
            M_LEFT, M_MIDDLE, M_RIGHT. Also, you could use the logical Id
            for the button: M_BTN1, M_BTN2, M_BTN3, M_BTN4, M_BTN5. These
            are all available through the :CONST export tag.

            zero is returned on failure, non-zero for success.

    ReleaseMouseButton BUTTON
            Releases the specified mouse button. Available mouse buttons
            are: M_LEFT, M_MIDDLE, M_RIGHT. Also, you could use the logical
            Id for the button: M_BTN1, M_BTN2, M_BTN3, M_BTN4, M_BTN5. These
            are all available through the :CONST export tag.

            zero is returned on failure, non-zero for success.

    SendKeys KEYS
            Sends keystrokes to the window that has the input focus.

            The keystrokes to send are those specified in KEYS. Some
            characters have special meaning, they are:

                    Modifier Keys:
                    ^       CTRL
                    %       ALT
                    +       SHIFT

                    Other Keys:
                    ~       ENTER
                    \n      ENTER
                    \t      TAB
                    ( and ) MODIFIER USAGE
                    { and } QUOTE CHARACTERS

            Simply, one can send a text string like so:

                    SendKeys('Hello, how are you today?');

            Parenthesis allow a modifier to work on one or more characters.
            For example:

                    SendKeys('%(f)q'); # Alt-f, then press q
                    SendKeys('%(fa)^(m)'); # Alt-f, Alt-a, Ctrl-m
                    SendKeys('+(abc)'); # Uppercase ABC using shift modifier
                    SendKeys('^(+(l))'); # Ctrl-Shift-l
                    SendKeys('+'); # Press shift

            Braces are used to quote special characters, for utilizing
            aliased key names, or for special functionality. Multiple
            characters can be specified in a brace by space delimiting the
            entries. Characters can be repeated using a number that is space
            delimited after the preceeding key.

            Quote Special Characters

                    SendKeys('{{}'); # {
                    SendKeys('{+}'); # +

                    You can also use QuoteStringForSendKeys to perform quoting.

            Aliased Key Names

                    SendKeys('{BAC}'); # Backspace
                    SendKeys('{F1 F2 F3}'); # F1, F2, F3
                    SendKeys('{TAB 3}'); # Press TAB 3 times
                    SendKeys('{SPC 3 a b c}'); # Space 3 times, a, b, c

            Special Functionality

                    # Pause execution for 500 milliseconds
                    SendKeys('{PAUSE 500}');

            Combinations

                    SendKeys('abc+(abc){TAB PAUSE 500}'); # a, b, c, A, B, C, Tab, Pause 500
                    SendKeys('+({a b c})'); # A, B, C

            The following abbreviated key names are currently recognized
            within a brace set. If you don't see the desired key, you can
            still use the unabbreviated name for the key. If you are unsure
            of this name, utilize the xev (X event view) tool, press the
            button you need and look at the tools output for the name of the
            key. Names that are in the list below can be utilized regardless
            of case. Ones that aren't in this list are going to be case
            sensitive and also not abbreviated. For example, using 'xev' you
            will find that the name of the backspace key is BackSpace, so
            you could use {BackSpace} in place of {bac} if you really wanted
            to.

                    Name    Action
                    -------------------
                    BAC     BackSpace
                    BS      BackSpace
                    BKS     BackSpace
                    BRE     Break
                    CAN     Cancel
                    CAP     Caps_Lock
                    DEL     Delete
                    DOW     Down
                    END     End
                    ENT     Return
                    ESC     Escape
                    F1      F1
                    ...     ...
                    F12     F12
                    HEL     Help
                    HOM     Home
                    INS     Insert
                    LAL     Alt_L
                    LCT     Control_L
                    LEF     Left
                    LSH     Shift_L
                    LSK     Super_L
                    MNU     Menu
                    NUM     Num_Lock
                    PGD     Page_Down
                    PGU     Page_Up
                    PRT     Print
                    RAL     Alt_R
                    RCT     Control_R
                    RIG     Right
                    RSH     Shift_R
                    RSK     Super_R
                    SCR     Scroll_Lock
                    SPA     Space
                    SPC     Space
                    TAB     Tab
                    UP      Up

            zero is returned on failure, non-zero for success.

    PressKey KEY
            Presses the specified key.

            One can utilize the abbreviated key names from the table listed
            above as outlined in the following example:

              # Alt-n
              PressKey('LAL'); # Left Alt
              PressKey('n');
              ReleaseKey('n');
              ReleaseKey('LAL');

              # Uppercase a
              PressKey('LSH'); # Left Shift
              PressKey('a'); 
              ReleaseKey('a');
              ReleaseKey('LSH');

            The ReleaseKey calls in the above example are there to set both
            key states back.

            zero is returned on failure, non-zero for success.

    ReleaseKey KEY
            Releases the specified key. Normally follows a PressKey call.

            One can utilize the abbreviated key names from the table listed
            above.

              ReleaseKey('n');

            zero is returned on failure, non-zero for success.

    PressReleaseKey KEY
            Presses and releases the specified key.

            One can utilize the abbreviated key names from the table listed
            above.

              PressReleaseKey('n');

            This function is effected by the key send delay.

            zero is returned on failure, non-zero for success.

    IsKeyPressed KEY
            Determines if the specified key is currently being pressed.

            You can specify such things as 'bac' or the unabbreviated form
            'BackSpace' as covered in the SendKeys information. Brace forms
            such as '{bac}' are unsupported. A '{' is taken literally and
            letters are case sensitive.

              if (IsKeyPressed('esc')) {  # Is Escape pressed?
              if (IsKeyPressed('a')) { # Is a pressed?
              if (IsKeyPressed('A')) { # Is A pressed?

            Returns non-zero for true, zero for false.

    IsMouseButtonPressed BUTTON
            Determines if the specified mouse button is currently being
            pressed.

            Available mouse buttons are: M_LEFT, M_MIDDLE, M_RIGHT. Also,
            you could use the logical Id for the button: M_BTN1, M_BTN2,
            M_BTN3, M_BTN4, M_BTN5. These are all available through the
            :CONST export tag.

              if (IsMouseButtonPressed(M_LEFT)) { # Is left button pressed?

            Returns non-zero for true, zero for false.

    IsWindow WINDOWID
            zero is returned if the specified window Id is not for something
            that can be recognized as a window. non-zero is returned if it
            looks like a window.

    IsWindowViewable WINDOWID
            zero is returned if the specified window Id is for a window that
            isn't viewable. non-zero is returned if the window is viewable.

    MoveWindow WINDOWID, X, Y
            Moves the window to the specified location.

            zero is returned on failure, non-zero for success.

    ResizeWindow WINDOWID, WIDTH, HEIGHT
            Resizes the window to the specified size.

            zero is returned on failure, non-zero for success.

    IconifyWindow WINDOWID
            Minimizes (Iconifies) the specified window.

            zero is returned on failure, non-zero for success.

    UnIconifyWindow WINDOWID
            Unminimizes (UnIconifies) the specified window.

            zero is returned on failure, non-zero for success.

    RaiseWindow WINDOWID
            Raises the specified window to the top of the stack, so that no
            other windows cover it.

            zero is returned on failure, non-zero for success.

    LowerWindow WINDOWID
            Lowers the specified window to the bottom of the stack, so other
            existing windows will cover it.

            zero is returned on failure, non-zero for success.

    GetInputFocus
            Returns the window that currently has the input focus.

    SetInputFocus WINDOWID
            Sets the specified window to be the one that has the input
            focus.

            zero is returned on failure, non-zero for success.

    GetWindowPos WINDOWID
            Returns an array containing the position information for the
            specified window.

              my ($x, $y, $width, $height) = GetWindowPos(GetRootWindow());

    GetScreenRes
            Returns the screen resolution.

              my ($x, $y) = GetScreenRes();

    GetScreenDepth
            Returns the color depth for the screen.

            Value is represented as bits, i.e. 16.

              my $depth = GetScreenDepth();

OTHER DOCUMENTATION
Available under the docs sub-directory.

      Changes (Module Changes)
      CodingStyle (Coding-Style Guidelines)
      ToDo (ToDo List)
      Copying (Copy of the GPL License)

COPYRIGHT
    Copyright(c) 2003 Dennis K. Paulsen, All Rights Reserved. This program
    is free software; you can redistribute it and/or modify it under the
    terms of the GNU General Public License.

AUTHOR
    Dennis K. Paulsen <ctrondlp@users.sourceforge.net>

CREDITS
    Thanks to the following people for patches, suggestions, etc.:

    Richard Clamp

