Utilisation des contrôles ActiveX et de COM dans Qt

Le module QAxContainer fait partie du framework ActiveQt. Il fournit une bibliothèque implémentant une sous-classe de QWidget, QAxWidget, qui sert de conteneur pour les contrôles ActiveX, ainsi qu’une sous-classe de QObject, QAxObject, qui permet d’accéder facilement à des objets COM non visuels. Il est possible de créer des scripts pour les objets COM intégrés à l’aide de ces classes grâce aux classes QAxScript, QAxScriptManager et QAxScriptEngine, et un ensemble d’outils facilite l’accès aux objets COM par programmation.

Le module se compose de six classes

1. QAxBase est une classe abstraite qui fournit une API permettant d’initialiser et d’accéder à un objet COM ou à un contrôle ActiveX.
2. QAxObject fournit une interface QObject qui encapsule un objet COM.
3. QAxWidget est une QWidget qui encapsule un contrôle ActiveX.
4. QAxScriptManager, ` QAxScript ` et ` QAxScriptEngine ` fournissent une interface vers Windows Script Host.

Des exemples d’applications utilisant des contrôles ActiveX standard pour offrir des fonctionnalités d’interface utilisateur de haut niveau sont fournis.

Utilisation de la bibliothèque

Pour créer des applications Qt capables d’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.

Distribution des 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 toutefois que les binaires du serveur ActiveX que vous utilisez peuvent ne pas être installés sur le système cible ; vous devez donc les inclure dans votre package et les enregistrer lors du processus d’installation de votre application.

Instanciation d’objets COM

Pour instancier un objet COM, utilisez l’API QAxBase::setControl(), ou transmettez directement le nom de l’objet au constructeur de la sous-classe d’ QAxBase que vous utilisez.

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

Messages d’erreur courants

ActiveQt affiche des messages d’erreur dans 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).

Impossible d’instancier le contrôle demandé

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 indiqué dans la documentation.

Accès à l’API objet

ActiveQt fournit une API Qt pour l’objet COM et remplace les types de données COM par leurs équivalents Qt.

Il existe quatre façons d'appeler les API de l'objet COM :

• Génération d’un espace de noms C++
• Appel par nom
• Via un moteur de script
• Utilisation des interfaces COM natives

Génération 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 au système de compilation 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 obtenu dans votre code pour accéder aux API d'objet via les classes C++ générées. Reportez-vous à l'exemple Qutlook pour plus d'informations.

Appel par nom

Utilisez les méthodes ` 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 ne sont pas forcément disponibles.

Appel d’une fonction via 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 du code de script accédant aux objets COM.

Pour instancier un moteur de script, utilisez ` QAxScriptManager::addObject()` pour enregistrer les objets COM auxquels vous souhaitez accéder depuis le 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 via les scripts dépendent du langage de script utilisé.

Le conteneur de test ActiveX illustre le chargement de fichiers de script.

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

Pour appeler des fonctions de l’objet COM auxquelles aucune des méthodes ci-dessus ne permet d’accéder, il est possible de solliciter directement l’interface COM à l’aide de QAxBase::queryInterface(). Pour obtenir une définition C++ des classes d’interface correspondantes, utilisez la directive #import avec la bibliothèque de types fournie avec le contrôle ; consultez le manuel de votre compilateur pour plus de détails.

Messages d’erreur courants

ActiveQt affiche des messages d’erreur dans 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 : Méthode introuvable

Échec d’un appel à ` QAxBase::dynamicCall()` : le prototype de la fonction ne correspond à aucune fonction disponible dans l’API de l’objet.

Erreur lors de l'appel d'un membre IDispatch : paramètre obligatoire manquant

Échec d'un appel à QAxBase::dynamicCall() : le prototype de la fonction était correct, mais le nombre de paramètres fournis était insuffisant.

Erreur lors de l’appel d’un membre IDispatch : incompatibilité de types au niveau du paramètre n

Échec de l'QAxBase::dynamicCall() : le prototype de la fonction était correct, mais le paramètre à l'index n était d'un type incorrect et n'a pas pu être converti au type correct.

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

Vous essayez d’appeler une fonction fournie par un moteur qui ne prend pas en charge l’introspection (par exemple, ActivePython ou ActivePerl). Vous devez appeler la fonction directement sur l’objet QAxScript correspondant.