Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions |

# The TQAxContainer Module

- Introduction
- Building the library
- Using the library
  - Distributing TQAxContainer applications
- Instantiating COM objects
- Accessing the object API
  - Typical error messages
    - Requested control could not be instantiated
    - TQAxBase::internalInvoke: No such method
    - Error calling IDispatch member: Non-optional parameter missing
    - Error calling IDispatch member: Type mismatch in parameter n
    - TQAxScriptManager::call(): No script provides this function

## Introduction

The TQAxContainer module provides a library implementing a TQWidget subclass, TQAxWidget, that acts as a container for ActiveX controls, and a TQObject subclass, TQAxObject, that can be used to easily access non-visual COM objects. Scripting COM objects embedded using these classes is possible through the TQAxScript, TQAxScriptManager and TQAxScriptEngine classes.

This module is part of the ActiveTQt framework. (To make an application into an ActiveX server see the TQAxServer module.)

The module consists of six classes

1. TQAxBase is an abstract class that provides an API to initialize and access a COM/ActiveX object.
2. TQAxObject provides a TQObject that wraps a COM object.
3. TQAxWidget is a TQWidget that wraps an ActiveX control.
4. TQAxScriptManager, TQAxScript and TQAxScriptEngine provide an interface to the Windows Script Host.

Some example applications that use standard ActiveX controls to provide high level user interface functionality are provided.

## Building the library

In the `activeqt` directory (usually `TQTDIR/extensions/activeqt`) enter the `container` subdirectory and run `qmake` to generate the makefile, and use the make tool (`nmake` for VC++, `make` for Borland) to build the library. The library `qaxcontainer.lib` will be linked into `TQTDIR/lib`.

If you have a shared configuration of TQt enter the `plugin` subdirectory and run `qmake` and your make tool to build a plugin that integrates the TQAxWidget class into TQt Designer.

## Using the library

To build TQt applications that can host COM objects and ActiveX controls link the application against the TQAxContainer module by adding

        LIBS += qaxcontainer.lib

to the application's `.pro` file.

### Distributing TQAxContainer applications

The TQAxContainer library is static, so there is no need to redistribute any additional files when using this module. Note however that the ActiveX server binaries you are using might not be installed on the target system, so you have to ship them with your package and register them during the installation process of your application.

## Instantiating COM objects

To instantiate a COM object use the TQAxBase::setControl() API, or pass the name of the object directly into the constructor of the TQAxBase subclass you are using.

The control can be specified in a variety of formats, but the fastest and most powerful format is to use the class ID (CLSID) of the object directly. The class ID can be prepended with information about a remote machine that the object should run on, and can include a license key for licensed controls.

## Accessing the object API

ActiveTQt provides a TQt API to the COM object, and replaces COM datatypes with TQt equivalents. Use the `dumpdoc` tool to get the documentation of the TQt API for any COM object and it's subobjects.

See the TQAxWidget and TQAxObject API documentation about how to use this class to use ActiveX controls and COM objects in TQt applications. To access the COM object with scripting languages use the TQAxScript class.

To call functions of the COM object that can not be accessed via ActiveTQt it is possible to request the COM interface directly using TQAxBase::queryInterface(). To get a C++ definition of the respective interface classes use the `#import` directive with the type library provided with the control.

### Typical error messages

ActiveTQt prints error messages to the debug output when it encounters error situations at runtime. Usually you must run your program in the debugger to see these messages (e.g. in Visual Studio's Debug output).

#### Requested control could not be instantiated

The control requested in TQAxBase::setControl() is not installed on this system, or is not accessible for the current user.

The control might require administrator rights, or a license key. If the control is licensed, reimplement initialize() and use the COM APIs to call the IClassFactory2 interface functions.

#### TQAxBase::internalInvoke: No such method

A `dynamicCall()` failed - the function prototype did not match any function available in the object's API.

#### Error calling IDispatch member: Non-optional parameter missing

A `dynamicCall()` failed - the function prototype was correct, but too few parameters were provided.

#### Error calling IDispatch member: Type mismatch in parameter n

A `dynamicCall()` failed - the function prototype was correct, but the paramter at index `n` was of the wrong type and could not be coerced to the correct type.

#### TQAxScriptManager::call(): No script provides this function

You try to call a function that is provided through an engine that doesn't provide introspection (ie. ActivePython or ActivePerl). You need to call the function directly on the respective TQAxScript object.