<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- activeqt-container.qdoc -->
<title>Qt 4.8: Using ActiveX controls and COM in Qt</title>
<link rel="stylesheet" type="text/css" href="style/style.css" />
<script src="scripts/jquery.js" type="text/javascript"></script>
<script src="scripts/functions.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="style/superfish.css" />
<link rel="stylesheet" type="text/css" href="style/narrow.css" />
<!--[if IE]>
<meta name="MSSmartTagsPreventParsing" content="true">
<meta http-equiv="imagetoolbar" content="no">
<![endif]-->
<!--[if lt IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie6.css">
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie7.css">
<![endif]-->
<!--[if IE 8]>
<link rel="stylesheet" type="text/css" href="style/style_ie8.css">
<![endif]-->
<script src="scripts/superfish.js" type="text/javascript"></script>
<script src="scripts/narrow.js" type="text/javascript"></script>
</head>
<body class="" onload="CheckEmptyAndLoadList();">
<div class="header" id="qtdocheader">
<div class="content">
<div id="nav-logo">
<a href="index.html">Home</a></div>
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
<div id="narrowsearch"></div>
<div id="nav-topright">
<ul>
<li class="nav-topright-home"><a href="http://qt.digia.com/">Qt HOME</a></li>
<li class="nav-topright-dev"><a href="http://qt-project.org/">DEV</a></li>
<li class="nav-topright-doc nav-topright-doc-active"><a href="http://qt-project.org/doc/">
DOC</a></li>
<li class="nav-topright-blog"><a href="http://blog.qt.digia.com/">BLOG</a></li>
</ul>
</div>
<div id="shortCut">
<ul>
<li class="shortCut-topleft-inactive"><span><a href="index.html">Qt 4.8</a></span></li>
<li class="shortCut-topleft-active"><a href="http://qt-project.org/doc/">ALL VERSIONS </a></li>
</ul>
</div>
<ul class="sf-menu" id="narrowmenu">
<li><a href="#">API Lookup</a>
<ul>
<li><a href="classes.html">Class index</a></li>
<li><a href="functions.html">Function index</a></li>
<li><a href="modules.html">Modules</a></li>
<li><a href="namespaces.html">Namespaces</a></li>
<li><a href="qtglobal.html">Global Declarations</a></li>
<li><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</li>
<li><a href="#">Qt Topics</a>
<ul>
<li><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li><a href="supported-platforms.html">Supported Platforms</a></li>
<li><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</li>
<li><a href="#">Examples</a>
<ul>
<li><a href="all-examples.html">Examples</a></li>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="demos.html">Demos</a></li>
<li><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="wrapper">
<div class="hd">
<span></span>
</div>
<div class="bd group">
<div class="sidebar">
<div class="searchlabel">
Search index:</div>
<div class="search" id="sidebarsearch">
<form id="qtdocsearch" action="" onsubmit="return false;">
<fieldset>
<input type="text" name="searchstring" id="pageType" value="" />
<div id="resultdialog">
<a href="#" id="resultclose">Close</a>
<p id="resultlinks" class="all"><a href="#" id="showallresults">All</a> | <a href="#" id="showapiresults">API</a> | <a href="#" id="showarticleresults">Articles</a> | <a href="#" id="showexampleresults">Examples</a></p>
<p id="searchcount" class="all"><span id="resultcount"></span><span id="apicount"></span><span id="articlecount"></span><span id="examplecount"></span> results:</p>
<ul id="resultlist" class="all">
</ul>
</div>
</fieldset>
</form>
</div>
<div class="box first bottombar" id="lookup">
<h2 title="API Lookup"><span></span>
API Lookup</h2>
<div id="list001" class="list">
<ul id="ul001" >
<li class="defaultLink"><a href="classes.html">Class index</a></li>
<li class="defaultLink"><a href="functions.html">Function index</a></li>
<li class="defaultLink"><a href="modules.html">Modules</a></li>
<li class="defaultLink"><a href="namespaces.html">Namespaces</a></li>
<li class="defaultLink"><a href="qtglobal.html">Global Declarations</a></li>
<li class="defaultLink"><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</div>
</div>
<div class="box bottombar" id="topics">
<h2 title="Qt Topics"><span></span>
Qt Topics</h2>
<div id="list002" class="list">
<ul id="ul002" >
<li class="defaultLink"><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li class="defaultLink"><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li class="defaultLink"><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li class="defaultLink"><a href="supported-platforms.html">Supported Platforms</a></li>
<li class="defaultLink"><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li class="defaultLink"><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</div>
</div>
<div class="box" id="examples">
<h2 title="Examples"><span></span>
Examples</h2>
<div id="list003" class="list">
<ul id="ul003">
<li class="defaultLink"><a href="all-examples.html">Examples</a></li>
<li class="defaultLink"><a href="tutorials.html">Tutorials</a></li>
<li class="defaultLink"><a href="demos.html">Demos</a></li>
<li class="defaultLink"><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</div>
</div>
</div>
<div class="wrap">
<div class="toolbar">
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li>Using ActiveX controls and COM in Qt</li>
</ul>
</div>
<div class="toolbuttons toolblock">
<ul>
<li id="smallA" class="t_button">A</li>
<li id="medA" class="t_button active">A</li>
<li id="bigA" class="t_button">A</li>
<li id="print" class="t_button"><a href="javascript:this.print();">
<span>Print</span></a></li>
</ul>
</div>
</div>
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#using-the-library">Using the Library</a></li>
<li class="level2"><a href="#distributing-qaxcontainer-applications">Distributing QAxContainer Applications</a></li>
<li class="level1"><a href="#instantiating-com-objects">Instantiating COM Objects</a></li>
<li class="level2"><a href="#typical-error-messages">Typical Error Messages</a></li>
<li class="level3"><a href="#requested-control-could-not-be-instantiated">Requested control could not be instantiated</a></li>
<li class="level1"><a href="#accessing-the-object-api">Accessing the Object API</a></li>
<li class="level2"><a href="#generating-a-c-namespace">Generating a C++ Namespace</a></li>
<li class="level2"><a href="#call-by-name">Call-by-Name</a></li>
<li class="level2"><a href="#calling-function-through-a-script-engine">Calling Function Through a Script Engine</a></li>
<li class="level2"><a href="#calling-a-function-using-the-native-com-interfaces">Calling a Function Using the Native COM Interfaces</a></li>
<li class="level2"><a href="#typical-error-messages">Typical Error Messages</a></li>
<li class="level3"><a href="#qaxbase-internalinvoke-no-such-method">QAxBase::internalInvoke: No such method</a></li>
<li class="level3"><a href="#error-calling-idispatch-member-non-optional-parameter-missing">Error calling IDispatch member: Non-optional parameter missing</a></li>
<li class="level3"><a href="#error-calling-idispatch-member-type-mismatch-in-parameter-n">Error calling IDispatch member: Type mismatch in parameter n</a></li>
<li class="level3"><a href="#qaxscriptmanager-call-no-script-provides-this-function">QAxScriptManager::call(): No script provides this function</a></li>
</ul>
</div>
<h1 class="title">Using ActiveX controls and COM in Qt</h1>
<span class="subtitle"></span>
<!-- $$$activeqt-container.html-description -->
<div class="descr"> <a name="details"></a>
<p>The <a href="qaxcontainer.html">QAxContainer</a> module is part of the <a href="activeqt.html#activeqt">ActiveQt</a> framework. It provides a library implementing a <a href="qwidget.html">QWidget</a> subclass, <a href="qaxwidget.html">QAxWidget</a>, that acts as a container for ActiveX controls, and a <a href="qobject.html">QObject</a> subclass, <a href="qaxobject.html">QAxObject</a>, that can be used to easily access non-visual COM objects. Scripting COM objects embedded using these classes is possible through the <a href="qaxscript.html">QAxScript</a>, <a href="qaxscriptmanager.html">QAxScriptManager</a> and <a href="qaxscriptengine.html">QAxScriptEngine</a> classes, and a set of <a href="activeqt-tools.html">tools</a> makes it easy to access COM objects programmatically.</p>
<p>The module consists of six classes</p>
<ol class="1">
<li><a href="qaxbase.html">QAxBase</a> is an abstract class that provides an API to initialize and access a COM object or ActiveX control.</li>
<li><a href="qaxobject.html">QAxObject</a> provides a <a href="qobject.html">QObject</a> that wraps a COM object.</li>
<li><a href="qaxwidget.html">QAxWidget</a> is a <a href="qwidget.html">QWidget</a> that wraps an ActiveX control.</li>
<li><a href="qaxscriptmanager.html">QAxScriptManager</a>, <a href="qaxscript.html">QAxScript</a> and <a href="qaxscriptengine.html">QAxScriptEngine</a> provide an interface to the Windows Script Host.</li>
</ol>
<p>Some <a href="examples-activeqt.html">example applications</a> that use standard ActiveX controls to provide high-level user interface functionality are provided.</p>
<p>Topics:</p>
<a name="using-the-library"></a>
<h2>Using the Library</h2>
<p>To build Qt applications that can host COM objects and ActiveX controls link the application against the <a href="qaxcontainer.html">QAxContainer</a> module by adding</p>
<pre class="cpp"> CONFIG += qaxcontainer</pre>
<p>to your application's <tt>.pro</tt> file.</p>
<a name="distributing-qaxcontainer-applications"></a>
<h3>Distributing QAxContainer Applications</h3>
<p>The <a href="qaxcontainer.html">QAxContainer</a> 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.</p>
<a name="instantiating-com-objects"></a>
<h2>Instantiating COM Objects</h2>
<p>To instantiate a COM object use the <a href="qaxbase.html#control-prop">QAxBase::setControl</a>() API, or pass the name of the object directly into the constructor of the <a href="qaxbase.html">QAxBase</a> subclass you are using.</p>
<p>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.</p>
<a name="typical-error-messages"></a>
<h3>Typical Error Messages</h3>
<p><a href="activeqt.html#activeqt">ActiveQt</a> 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).</p>
<a name="requested-control-could-not-be-instantiated"></a>
<h4>Requested control could not be instantiated</h4>
<p>The control requested in <a href="qaxbase.html#control-prop">QAxBase::setControl</a>() is not installed on this system, or is not accessible for the current user.</p>
<p>The control might require administrator rights, or a license key. If the control is licensed, pass the license key to QAxBase::setControl as documented.</p>
<a name="accessing-the-object-api"></a>
<h2>Accessing the Object API</h2>
<p><a href="activeqt.html#activeqt">ActiveQt</a> provides a Qt API to the COM object, and replaces COM datatypes with Qt equivalents.</p>
<p>There are four ways to call APIs on the COM object:</p>
<ul>
<li>Generating a C++ namespace</li>
<li>Call-by-name</li>
<li>Through a script engine</li>
<li>Using the native COM interfaces</li>
</ul>
<a name="generating-a-c-namespace"></a>
<h3>Generating a C++ Namespace</h3>
<p>To generate a C++ namespace for the type library you want to access, use the <a href="activeqt-dumpcpp.html#dumpcpp">dumpcpp</a> 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 <tt>TYPELIBS</tt> variable in your application's <tt>.pro</tt> file:</p>
<pre class="cpp"> TYPELIBS = file.tlb</pre>
<p>Note that <a href="activeqt-dumpcpp.html#dumpcpp">dumpcpp</a> might not be able to expose all APIs in the type library.</p>
<p>Include the resulting header file in your code to access the object APIs through the generated C++ classes. See the <a href="activeqt-qutlook.html">Qutlook</a> example for more information.</p>
<a name="call-by-name"></a>
<h3>Call-by-Name</h3>
<p>Use <a href="qaxbase.html#dynamicCall">QAxBase::dynamicCall</a>() and <a href="qaxbase.html#querySubObject">QAxBase::querySubObject</a>() as well as the <a href="qobject.html#setProperty">QObject::setProperty</a>() and <a href="qobject.html#property">QObject::property</a>() APIs to call the methods and properties of the COM object through their name. Use the <a href="activeqt-dumpdoc.html#dumpdoc">dumpdoc</a> 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.</p>
<p>See the <a href="activeqt-webbrowser.html">Webbrowser</a> example for more information.</p>
<a name="calling-function-through-a-script-engine"></a>
<h3>Calling Function Through a Script Engine</h3>
<p>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.</p>
<p>To instantiate a script engine, use <a href="qaxscriptmanager.html#addObject">QAxScriptManager::addObject</a>() to register the COM objects you want to access from script, and <a href="qaxscriptmanager.html#load">QAxScriptManager::load</a>() to load the script code into the engine. Then call the script functions using <a href="qaxscriptmanager.html#call">QAxScriptManager::call</a>() or <a href="qaxscript.html#call">QAxScript::call</a>().</p>
<p>Which APIs of the COM object are available through scripting depends on the script language used.</p>
<p>The <a href="activeqt-testcon.html">ActiveX Test Container</a> demonstrates loading of script files.</p>
<a name="calling-a-function-using-the-native-com-interfaces"></a>
<h3>Calling a Function Using the Native COM Interfaces</h3>
<p>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 <a href="qaxbase.html#queryInterface">QAxBase::queryInterface</a>(). To get a C++ definition of the respective interface classes use the <tt>#import</tt> directive with the type library provided with the control; see your compiler manual for details.</p>
<a name="typical-error-messages"></a>
<h3>Typical Error Messages</h3>
<p><a href="activeqt.html#activeqt">ActiveQt</a> 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).</p>
<a name="qaxbase-internalinvoke-no-such-method"></a>
<h4>QAxBase::internalInvoke: No such method</h4>
<p>A <a href="qaxbase.html#dynamicCall">QAxBase::dynamicCall</a>() failed - the function prototype did not match any function available in the object's API.</p>
<a name="error-calling-idispatch-member-non-optional-parameter-missing"></a>
<h4>Error calling IDispatch member: Non-optional parameter missing</h4>
<p>A <a href="qaxbase.html#dynamicCall">QAxBase::dynamicCall</a>() failed - the function prototype was correct, but too few parameters were provided.</p>
<a name="error-calling-idispatch-member-type-mismatch-in-parameter-n"></a>
<h4>Error calling IDispatch member: Type mismatch in parameter n</h4>
<p>A <a href="qaxbase.html#dynamicCall">QAxBase::dynamicCall</a>() failed - the function prototype was correct, but the paramter at index <tt>n</tt> was of the wrong type and could not be coerced to the correct type.</p>
<a name="qaxscriptmanager-call-no-script-provides-this-function"></a>
<h4>QAxScriptManager::call(): No script provides this function</h4>
<p>You try to call a function that is provided through an engine that doesn't provide introspection (ie. ActivePython or <a href="http://www.activestate.com/Products/activeperl/index.mhtml">ActivePerl</a>). You need to call the function directly on the respective <a href="qaxscript.html">QAxScript</a> object.</p>
</div>
<p><b>See also </b><a href="activeqt.html#activeqt-framework">ActiveQt Framework</a>.</p>
<!-- @@@activeqt-container.html -->
</div>
</div>
</div>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2013 Digia Plc and/or its
subsidiaries. Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
The documentation provided herein is licensed under the terms of the
<a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
License version 1.3</a> as published by the Free Software Foundation.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Digia, Qt and their respective logos are trademarks of Digia Plc
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
<script src="scripts/functions.js" type="text/javascript"></script>
</body>
</html>
