MEng.System.CQC.Runtime.AppCtrlClient is used by drivers which are
designed to control applications. This is done via an application control
'proxy' server running on the machine where the application is to be
controlled. This class allows the driver to register its application with
the server program, and to send it commands to make the target application
do what is desired.
For more information about application control drivers, see the Driver
Development Guide in the Technical documents section under the Learn Tab.
AddWindow([In] MEng.String WndPath) Returns MEng.Card4;
This method allows you to register a window with the application
control server. All of the methods that allow you to interact with the
windows of the target application will take a 'window id', which is
what is returned from this method. You provide a 'window path' that
describes the particular window of interest, and you get back a window
id that you should save away and use later to interact with that
window. The rules for window paths are discussed in tutorial, linked
to above.
ClickButton([In] MEng.Card4 WndId, [In] MEng.Card4 ChildId);
This method will simulate the clicking of a button. The window
should be some kind of button (check box, push button, radio button),
and this will cause it to act as though the user clicked on it. For a
check box or radio button, this will cause that button to be checked
or selected. For a push button, this will invoke whatever action that
button controls.
Connect() Returns MEng.Boolean;
This method allows the driver to connect to the application control
server. You would call this in your Connect() method. If the
connection is successful, this method will return True and your driver
can transition to connected state.
Disconnect();
This method should be called in your FreeCommRes() method to free
up the ORB connection that underlies this class.
IsRegistered() Returns MEng.Boolean;
This method will tell you if your application is registered with
the application control server program. In general, you will not have
a need for this. But, if you ever needed to defer connection for some
reasons and need to know if you've registered yet, you can use this to
check.
IsRunning() Returns MEng.Boolean;
This method will tell you if your application is currently running
on the target host. This doesn't say anything about it's state of
mind, just that it is currently running. Note that it is also only
advisory since it could always terminate between the time you call
this method and then react to the results.
You will generally use this in your Poll() method to keep the
current state of some sort of 'Power' field up to date.
IsVisible
(
[In] MEng.Card4 WndId
, [In] MEng.Card4 ChildId
) Returns MEng.Boolean;
This method will tell you if the indicated window is visible or
not. This means visible in the Windows sense, not whether it visible
to the user. It could be completely covered by other windows, but that
doesn't mean it is invisible in the Windows sense.
QueryButtonState
(
[In] MEng.Card4 WndId
, [In] MEng.Card4 ChildId
) Returns ButtonStates;
This method will return the current state of a button window. It
really only makes sense to call this on a check box or radio button,
since these have checked/unchecked type states that can be queried.
Calling it on other types of windows will produce undefined results.
QueryListSel
(
[In] MEng.Card4 WndId
, [In] MEng.Card4 ChildId
) Returns MEng.Card4;
This method will return the current selection index in a single
selection list box window. If you use it on any other type of window
or a multiple selection list box, the results are undefined.
QueryText
(
[In] MEng.Card4 WndId
, [In] MEng.Card4 ChildId
, [Out] MEng.String ToFill
) Returns MEng.Card4;
This method will return the text of a window. This really is only
useful on windows that have human consumable window text, such as text
entry windows. All windows technically have window text, but it might
not be of much use in most types of windows.
QueryTrackBar
(
[In] MEng.Card4 WndId
, [In] MEng.Card4 ChildId
) Returns MEng.Int4;
This method will return the value of a track bar (slider) type
window. The meaning of that value is up to you to interpret, and may
depend on the full range of the track bar. Calling this method on any
other type of window will product undefined results.
QueryWndStyles
(
[In] MEng.Card4 WndId
, [In] MEng.Card4 ChildId
) Returns MEng.Card4;
This method will return the styles of the indicated window. You can
use the window styles literals defined above to test for specific
bits.
SendExtKey
(
[In] MEng.Card4 WndId
, [In] MEng.Card4 ChildId
, [In] AppCtrlExtKeys ToSend
, [In] MEng.Boolean AltShifted
, [In] MEng.Boolean CtrlShifted
, [In] MEng.Boolean Shifted
);
This method will send an extended key to the target window. You can
indicate whether you want any of the shift keys to look as though they
are pressed when the application sees the key event.
SendKey
(
[In] MEng.Card4 WndId
, [In] MEng.Char ToSend
, [In] MEng.Boolean AltShifted
, [In] MEng.Boolean CtrlShifted
, [In] MEng.Boolean Shifted
);
This method will send a regular key (a character) to the target
window. You can indicate whether you want any of the shift keys to
look as though they are pressed when the application sees the key
event.
As a general rule, you would more likely want to use SetText() or
SetChildText() to put text into a window, rather than send a sequence
of characters. But, if the application supports key shortcuts (e.g.
Ctrl-T or Alt-S and so forth), you will need this method to send it
these types of 'hot key' keys to invoke those operations.
SendMenuItem
(
[In] MEng.Card4 WndId
, [In] MEng.Card4 ChildId
, [In] MEng.Card2 CmdId
);
This method will send a menu item selection message to the target
window. Basically it sends a WM_COMMAND message to the target window
with the passed command as the menu item that was 'selected' by the
user.
SendMsg
(
[In] MEng.Card4 WndId
, [In] MEng.Card4 ChildId
, [In] MEng.Card4 MsgToSend
, [In] MEng.Card4 Param1
, [In] MEng.Int4 Param2
, [In] MEng.Boolean Async
) Returns MEng.Int4;
These methods will send an arbitrary Windows message to the target
window. Use this with care, since you can completely confuse an
application by sending inappropriate messages. Obviously you cannot
send any message that requires a C type structure pointer as one of
the parameters, only those that take basic data values, because you
have no way in CML to create such a structure.
Messages can be sent synchronously, and asynchronously, which is
controlled by the last, Async, parameter. You should send messages in
the manner appropriate for the particular type of message you are
sending. Most messages of the 'do something' type that your driver
will likely send will be of the asynchronous type. Be very careful of
synchronous messages because you will be blocked until it completes
and if it caused some message to pop up that needs to be acknowledged
by the user, you are basically dead in the water.
SetButtonState
(
[In] MEng.Card4 WndId
, [In] MEng.Card4 ChildId
, [In] MEng.Boolean NewState
);
This method set the checked/selected state of a target check box or
radio button. Sending it to any other type of window will have
undefined results, most likely it just won't do anything at all. The
NewState Boolean parameter indicates what the new state should be.
SetFocus([In] MEng.Card4 WndId, [In] MEng.Card4 ChildId);
This method will put the keyboard input focus on the indicated
window. This will not normally be needed, since the other methods that
require the focus to be somewhere particular will insure that that
happens on your behalf, but could have some uses in special cases.
SetInfo
(
[In] MEng.String Moniker
, [In] MEng.String Binding
, [In] MEng.String AppTitle
, [In] MEng.String AppName
, [In] MEng.String AppPath
, [In] MEng.String Params
, [In] MEng.String WorkingDir
);
This method should be called during your driver initialization, to
set up the app control client object with the information it needs in
order to register your target application. This information is also
used to provide a good bit of information to the server behind your
back, so that you don't have to pass it each time.
Some of this information will come to you in standard 'user
prompts' in your manifest file, which cause the driver installation
wizard to get information from the user that is passed to your driver
initialization entry point.
The information you
must provide is:
-
Moniker. Your
driver moniker, which will uniquely identify your particular
application over on the the app control server, since driver
monikers are unique in the network.
-
Binding. Each host
that is running the application control server will have a 'binding'
name. Under the hood, this is the name used to register the server's
server side ORB object in the name server, but all you need to
really know is that this is how this object finds the right control
server to talk to. The binding names are set during installation
when you install the application server. This will come to you as a
prompt, since the user will indicate in the driver installation
wizard which binding he or she wants you to use.
-
AppTitle. Just a
human readable short string that is used to identify the application
in the app control server's list of registered apps.
-
AppName. Just the
name part of the application, e.g. "MyProgram.exe". Don't add any
path component to this string, just the name and extension. This
string will effectively be a hard coded string in your driver since
your driver knows the name of the program it is designed to control.
-
AppPath. This is
the path to the target program on the target host, i.e. not
necessarily where the driver is running but where the target app
control server is running. This shouldn't have any name component,
but should just be the directory where the program is at. If the
program is in the system path on the target machine, then this can
be empty. You will get this as a prompt since the user has to
indicate in the driver install wizard where the application is
installed on the target machine.
-
Params. Any
parameters that should be passed to the program. You will get this
from the user via a prompt as well, since they must enter any
optional parameters that they want to pass to the target program.
You can of course then modify this by adding more parameters or
whatever else needs to be done before it is passed into this method.
-
WorkingDir. If the
target application must run in a specific default directory, then
this can indicate that. If empty, it will just run in whatever
current directory the app control server chooses. You will get this
from the user via a prompt, but generally it will probably be empty.
You can always override this if you know (based on the path info
provided above) that the program must run in some specific
directory.
Note that, if you as the driver write know that the AppPath, Params,
or WorkingDir values must have specific values, you can just not put
those prompts into your manifest file, so that the user won't be asked
for them during the driver installation. You can then provide the
known required values. Or, you can modify or add to whatever the user
provides, if that is desirable.
SetListSel
(
[In] MEng.Card4 WndId
, [In] MEng.Card4 ChildId
, [In] MEng.Card4 Index
);
This method will set the currently selected item in a single
selection list box window. If the target window is not a list box, or
it is not a single selection list box, the results are undefined.
SetTrackBar
(
[In] MEng.Card4 WndId
, [In] MEng.Card4 ChildId
, [In] MEng.Int4 Value
);
This method will set the current value of a track bar (slider)
window. If the target window is not a track bar, the results are
undefined. If the value is not within the valid range of that slider,
then it will be rejected by the target window.
SetWindowPos
(
[In] MEng.Card4 WndId
, [In] MEng.Card4 ChildId
, [In] MEng.Int4 XPos
, [In] MEng.Int4 YPos
);
SetWindowSize
(
[In] MEng.Card4 WndId
, [In] MEng.Card4 ChildId
, [In] MEng.Card4 Width
, [In] MEng.Card4 Height
);
These methods set the origin and size of the target window to the
indicated position or size. In general, you should only use this on
top level windows, since the positioning of child windows within
applications is something best left to the application.
SetWindowText
(
[In] MEng.Card4 WndId
, [In] MEng.Card4 ChildId
, [In] MEng.String ToSet
);
This method will set the text of the target window. The target
window should be one which does something useful with window text,
such as an entry field.
ShowWindow
(
[In] MEng.Card4 WndId
, [In] MEng.Card4 ChildId
, [In] MEng.Boolean State
);
This method will set the visibility state of the target window. The
State parameter should be True to show the window or False to hid it.
StandardOp
(
[In] MEng.Card4 WndId
, [In] MEng.Card4 ChildId
, [In] AppCtrlOps OpToDo
);
This method will perform one of the standard frame window
operations on the target window. Obviously the target window should be
a top level frame window, else the results are undefined.
StartApp() Returns MEng.Boolean;
This method starts up the target application. You will generally
invoke this method in response to a write to a 'Power' type field in
your driver, to 'power up' the target application. If the application
is already running, then nothing will happen.
Note that the return only indicates whether the process got
started, it does not wait for the application to continue loading,
since that can take a considerable amount of time. The process is
completed asynchronously by the application control server. So if
necessary, you must wait for the application to continue loading.
This method will use the parameters set in the SetInfo() call
above, i.e. whatever default parameters you've set up. If you need
to pass different parameters each time, use the StartAppWithParams()
method.
StartAppWithParams([In] MEng.String Params) Returns MEng.Boolean;
This method is like StartApp() above, except that it lets you pass
per-invocation specific parameters to the program instead of using
the default ones set via SetInfo.().
StopApp() Returns MEng.Boolean;
This method will attempt to stop the application, if it is running.
Note that this will try some normal things to try to make a Windows
application stop; but, if that application has some known specific
means of exit, you should use that instead, since it is more likely to
do the right thing.