$szTitle = "Qt 4.5: QAxContainer Module"; include "./_header.inc"; ?>
Home · All Namespaces · All Classes · Main Classes · Grouped Classes · Modules · Functions |
[Previous: QtTest Module] [Qt's Modules] [Next: QAxServer Module]
The QAxContainer module is a Windows-only extension for accessing ActiveX controls and COM objects. More...
QAxBase | Abstract class that provides an API to initialize and access a COM object |
---|---|
QAxObject | QObject that wraps a COM object |
QAxScript | Wrapper around script code |
QAxScriptEngine | Wrapper around a script engine |
QAxScriptManager | Bridge between application objects and script code |
QAxWidget | QWidget that wraps an ActiveX control |
The QAxContainer module is part of the ActiveQt framework. It provides a library implementing a QWidget subclass, QAxWidget, that acts as a container for ActiveX controls, and a QObject subclass, QAxObject, that can be used to easily access non-visual COM objects. Scripting COM objects embedded using these classes is possible through the QAxScript, QAxScriptManager and QAxScriptEngine classes, and a set of tools makes it easy to access COM objects programmatically.
The module consists of six classes
Some example applications that use standard ActiveX controls to provide high-level user interface functionality are provided.
Topics:
To build Qt applications that can host COM objects and ActiveX controls link the application against the QAxContainer module by adding
CONFIG += qaxcontainer
to your application's .pro file.
The QAxContainer 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.
To instantiate a COM object use the QAxBase::setControl() API, or pass the name of the object directly into the constructor of the QAxBase 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.
ActiveQt 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).
The control requested in QAxBase::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, pass the license key to QAxBase::setControl as documented.
ActiveQt provides a Qt API to the COM object, and replaces COM datatypes with Qt equivalents.
There are four ways to call APIs on the COM object:
To generate a C++ namespace for the type library you want to access, use the dumpcpp tool. Run this tool manually on the type library you want to use, or integrate it into the build system by adding the type libraries to the TYPELIBS variable in your application's .pro file:
TYPELIBS = file.tlb
Note that dumpcpp might not be able to expose all APIs in the type library.
Include the resulting header file in your code to access the object APIs through the generated C++ classes. See the Qutlook example for more information.
Use QAxBase::dynamicCall() and QAxBase::querySubObject() as well as the QObject::setProperty() and QObject::property() APIs to call the methods and properties of the COM object through their name. Use the dumpdoc tool to get the documentation of the Qt API for any COM object and its subobjects; note that not all of the COM object's APIs might be available.
See the Webbrowser example for more information.
A Qt application can host any ActiveScript engine installed on the system. The script engine can then run script code that accesses the COM objects.
To instantiate a script engine, use QAxScriptManager::addObject() to register the COM objects you want to access from script, and QAxScriptManager::load() to load the script code into the engine. Then call the script functions using QAxScriptManager::call() or QAxScript::call().
Which APIs of the COM object are available through scripting depends on the script language used.
The ActiveX Test Container demonstrates loading of script files.
To call functions of the COM object that can not be accessed via any of the above methods it is possible to request the COM interface directly using QAxBase::queryInterface(). To get a C++ definition of the respective interface classes use the #import directive with the type library provided with the control; see your compiler manual for details.
ActiveQt 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).
A QAxBase::dynamicCall() failed - the function prototype did not match any function available in the object's API.
A QAxBase::dynamicCall() failed - the function prototype was correct, but too few parameters were provided.
A QAxBase::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.
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 QAxScript object.
The QAxContainer module is not covered by the GNU General Public License (GPL), the GNU Lesser General Public License (LGPL), or the Qt Commercial License. Instead, it is distributed under the following license.
Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
All rights reserved.
Contact: Qt Software Information (qt-info@nokia.com)
You may use this file under the terms of the BSD license as follows:
"Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
* Neither the name of Nokia Corporation and its Subsidiary(-ies) nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
See also ActiveQt Framework.
[Previous: QtTest Module] [Qt's Modules] [Next: QAxServer Module]
Copyright © 2009 Nokia Corporation and/or its subsidiary(-ies) | Trademarks | Qt 4.5.2 |