Utiliser des contrôles ActiveX et COM dans Qt

Le module QAxContainer fait partie du cadre ActiveQt. Il fournit une bibliothèque mettant en œuvre une sous-classe de QWidget, QAxWidget, qui agit comme un conteneur pour les contrôles ActiveX, et une sous-classe de QObject, QAxObject, qui peut être utilisée pour accéder facilement à des objets COM non visuels. Les classes QAxScript, QAxScriptManager et QAxScriptEngine permettent de créer des scripts pour les objets COM intégrés à l'aide de ces classes, et un ensemble d'outils facilite l'accès programmatique aux objets COM.

Le module se compose de six classes

1. QAxBase est une classe abstraite qui fournit une API pour initialiser et accéder à un objet COM ou à un contrôle ActiveX.
2. QAxObject QObject est une classe abstraite qui fournit une API permettant d'initialiser et d'accéder à un objet COM ou à un contrôle ActiveX.
3. QAxWidget est une classe QWidget qui englobe un contrôle ActiveX.
4. QAxScriptManagerLes classes de contrôle ActiveX, QAxScript et QAxScriptEngine fournissent une interface à l'hôte Windows Script.

Quelques exemples d'applications utilisant des contrôles ActiveX standard pour fournir des fonctionnalités d'interface utilisateur de haut niveau sont fournis.

Utilisation de la bibliothèque

Pour créer des applications Qt XML pouvant héberger des objets COM et des contrôles ActiveX, liez l'application au module QAxContainer en ajoutant

QT += axcontainer

au fichier .pro de votre application.

Distribuer les applications QAxContainer

La bibliothèque QAxContainer est statique, il n'est donc pas nécessaire de redistribuer des fichiers supplémentaires lors de l'utilisation de ce module. Notez cependant que les binaires du serveur ActiveX que vous utilisez peuvent ne pas être installés sur le système cible, vous devez donc les livrer avec votre paquetage et les enregistrer pendant le processus d'installation de votre application.

Instanciation des objets COM

Pour instancier un objet COM, utilisez l'API QAxBase::setControl(), ou passez le nom de l'objet directement dans le constructeur de la sous-classe QAxBase que vous utilisez.

Le contrôle peut être spécifié sous différents formats, mais le format le plus rapide et le plus puissant consiste à utiliser directement l'identifiant de classe (CLSID) de l'objet. L'ID de classe peut être précédé d'informations sur la machine distante sur laquelle l'objet doit être exécuté et peut inclure une clé de licence pour les contrôles sous licence.

Messages d'erreur typiques

ActiveQt imprime des messages d'erreur sur la sortie de débogage lorsqu'il rencontre des situations d'erreur lors de l'exécution. En général, vous devez exécuter votre programme dans le débogueur pour voir ces messages (par exemple, dans la sortie de débogage de Visual Studio).

Le contrôle demandé n'a pas pu être instancié

Le contrôle demandé dans QAxBase::setControl() n'est pas installé sur ce système ou n'est pas accessible à l'utilisateur actuel.

Le contrôle peut nécessiter des droits d'administrateur ou une clé de licence. Si le contrôle est sous licence, transmettez la clé de licence à QAxBase::setControl comme documenté.

Accès à l'API objet

ActiveQt fournit une API Qt à l'objet COM et remplace les types de données COM par des équivalents Qt.

Il existe quatre façons d'appeler des API sur l'objet COM :

• Générer un espace de noms C
• Appel par nom
• Par l'intermédiaire d'un moteur de script
• En utilisant les interfaces COM natives

Création d'un espace de noms C

Pour générer un espace de noms C++ pour la bibliothèque de types à laquelle vous souhaitez accéder, utilisez l'outil dumpcpp. Exécutez cet outil manuellement sur la bibliothèque de types que vous souhaitez utiliser ou intégrez-le dans le système de construction en ajoutant les bibliothèques de types à la variable TYPELIBS dans le fichier .pro de votre application :

TYPELIBS = file.tlb

Notez que dumpcpp peut ne pas être en mesure d'exposer toutes les API de la bibliothèque de types.

Incluez le fichier d'en-tête résultant dans votre code pour accéder aux API d'objets par le biais des classes C++ générées. Voir l'exemple Qutlook pour plus d'informations.

Appel par nom

Utilisez QAxBase::dynamicCall() et QAxBase::querySubObject() ainsi que les API QObject::setProperty() et QObject::property() pour appeler les méthodes et les propriétés de l'objet COM par leur nom. Utilisez l'outil dumpdoc pour obtenir la documentation de l'API Qt pour tout objet COM et ses sous-objets ; notez que toutes les API de l'objet COM peuvent ne pas être disponibles.

Appel d'une fonction par l'intermédiaire d'un moteur de script

Une application Qt peut héberger n'importe quel moteur ActiveScript installé sur le système. Le moteur de script peut alors exécuter un code de script qui accède aux objets COM.

Pour instancier un moteur de script, utilisez QAxScriptManager::addObject() pour enregistrer les objets COM auxquels vous souhaitez accéder à partir du script, et QAxScriptManager::load() pour charger le code de script dans le moteur. Appelez ensuite les fonctions de script à l'aide de QAxScriptManager::call() ou QAxScript::call().

Les API de l'objet COM disponibles par l'intermédiaire de scripts dépendent du langage de script utilisé.

Le conteneur de test ActiveX montre le chargement des fichiers de script.

Appel d'une fonction à l'aide des interfaces COM natives

Pour appeler des fonctions de l'objet COM qui ne sont pas accessibles par l'une des méthodes ci-dessus, il est possible de demander directement l'interface COM à l'aide de QAxBase::queryInterface(). Pour obtenir une définition C++ des classes d'interface respectives, utilisez la directive #import avec la bibliothèque de types fournie avec la commande ; consultez le manuel de votre compilateur pour plus de détails.

Messages d'erreur typiques

ActiveQt imprime des messages d'erreur sur la sortie de débogage lorsqu'il rencontre des situations d'erreur lors de l'exécution. En général, vous devez exécuter votre programme dans le débogueur pour voir ces messages (par exemple, dans la sortie Debug de Visual Studio).

QAxBase::internalInvoke : No such method

Un QAxBase::dynamicCall() a échoué - le prototype de la fonction ne correspondait à aucune fonction disponible dans l'API de l'objet.

Erreur lors de l'appel d'un membre IDispatch : Paramètre non optionnel manquant

A QAxBase::dynamicCall() a échoué - le prototype de la fonction était correct, mais trop peu de paramètres ont été fournis.

Erreur lors de l'appel d'un membre d'IDispatch : Type mismatch in parameter n

Un QAxBase::dynamicCall() a échoué - le prototype de la fonction était correct, mais le paramètre à l'index n n'était pas du bon type et n'a pas pu être converti au bon type.

QAxScriptManager::call() : Aucun script ne fournit cette fonction

Vous essayez d'appeler une fonction qui est fournie par un moteur qui ne fournit pas d'introspection (par exemple ActivePython ou ActivePerl). Vous devez appeler la fonction directement sur l'objet QAxScript correspondant.