Класс QAxBase

Класс QAxBase — абстрактный класс, предоставляющий API для инициализации и доступа к объекту COM. Подробнее...

• Список всех членов, включая унаследованные

Типы публичного доступа

Функции публичного доступа

Защищенные функции

Подробное описание

QAxBase — абстрактный класс, который нельзя использовать напрямую и который создаётся через подклассы QAxObject и QAxWidget. Этот класс предоставляет API для прямого доступа к объекту COM через его реализацию IUnknown. Если объект COM реализует интерфейс IDispatch, свойства и методы этого объекта становятся доступными как свойства и слоты Qt.

connect(buttonBack, SIGNAL(clicked()), webBrowser, SLOT(GoBack()));

Свойства, экспонируемые реализацией объекта IDispatch, могут читаться и записываться через систему свойств, предоставляемую Qt Object Model (оба подкласса являются объектами QObject, поэтому вы можете использовать QObject::setProperty() и QObject::property()). Свойства с несколькими параметрами не поддерживаются.

activeX->setProperty("text", "some text");
int value = activeX->property("value");

Функции записи для свойств и других методов, экспонируемых реализацией объекта IDispatch, могут вызываться непосредственно с помощью dynamicCall() или косвенно как слоты, подключенные к сигналу.

webBrowser->dynamicCall("GoHome()");

Выходящие события, поддерживаемые объектом COM, передаются как стандартные Qt-сигналы.

connect(webBrowser, SIGNAL(TitleChanged(QString)),
        this, SLOT(setCaption(QString)));

QAxBase прозрачно преобразует типы данных COM в эквивалентные типы данных Qt. Некоторые типы COM не имеют эквивалентной структуры данных Qt.

Поддерживаемые типы данных COM указаны в первой колонке следующей таблицы. Во второй колонке — тип Qt, который может быть использован с функциями свойства QObject. В третьей колонке — тип Qt, используемый в прототипе сгенерированных сигналов и слотов для входных параметров, а в последней колонке — тип Qt, используемый в прототипе сигналов и слотов для выходных параметров.

Поддерживаются также перечисления и типы-псевдонимы для поддерживаемых типов.

Для вызова методов COM-интерфейса, описанного следующим IDL

dispinterface IControl
{
properties:
    [id(1)] BSTR text;
    [id(2)] IFontDisp *font;

methods:
    [id(6)] void showColumn([in] int i);
    [id(3)] bool addColumn([in] BSTR t);
    [id(4)] int fillList([in, out] SAFEARRAY(VARIANT) *list);
    [id(5)] IDispatch *item([in] int i);
};

используйте API QAxBase следующим образом:

QAxObject object("<CLSID>");

QString text = object.property("text").toString();
object.setProperty("font", QFont("Times New Roman", 12));

connect(this, SIGNAL(clicked(int)), &object, SLOT(showColumn(int)));
bool ok = object.dynamicCall("addColumn(const QString&)", "Column 1").toBool();

QList<QVariant> varlist;
QList<QVariant> parameters;
parameters << QVariant(varlist);
int n = object.dynamicCall("fillList(QList<QVariant>&)", parameters).toInt();

QAxObject *item = object.querySubItem("item(int)", 5);

Обратите внимание, что QList объектов, которые необходимо заполнить, должен быть предоставлен в качестве элемента в списке параметров QVariant.

Если вам нужно получить доступ к свойствам или передать параметры неподдерживаемых типов данных, вы должны напрямую обратиться к COM-объекту через его IDispatch реализацию или другие интерфейсы. Эти интерфейсы можно получить через queryInterface().

IUnknown *iface = 0;
activeX->queryInterface(IID_IUnknown, (void**)&iface);
if (iface) {
    // use the interface
    iface->Release();
}

Чтобы получить определение COM-интерфейсов, вам необходимо использовать заголовочные файлы, предоставленные с компонентом, который вы хотите использовать. Некоторые компиляторы также могут импортировать библиотеки типов, используя директиву компилятора #import. Обратитесь к документации компонента, чтобы узнать, какие библиотеки типов вам необходимо импортировать и как их использовать.

Если вам необходимо реагировать на события, передающие параметры неподдерживаемых типов данных, вы можете использовать универсальный сигнал, который передает данные события, предоставляемые COM-событием.

См. также QAxObject, QAxWidget, QAxScript и ActiveQt Framework.

Документация по типам-членам

[alias] QAxBase::PropertyBag

A QMap<QString,QVariant> которое может хранить свойства в виде пар имя:значение.

Документация по функциям-членам

[protected] QAxBase::QAxBase()

Создаёт объект QAxBase.

[virtual] QAxBase::~QAxBase()

Закрывает COM-объект и уничтожает объект QAxBase.

См. также clear().

QVariant QAxBase::asVariant() const

Возвращает QVariant, которая оборачивает COM-объект. Затем эта переменная может быть использована в качестве параметра, например, в dynamicCall().

[since 5.13] ulong QAxBase::classContext() const

Возвращает контекст, в котором будет работать ActiveX-контроль (по умолчанию CLSCTX_SERVER).

Эта функция была введена в Qt 5.13.

См. также setClassContext().

void QAxBase::clear()

Отключает и уничтожает COM-объект.

Если вы переопределяете эту функцию, вы также должны переопределить деструктор, чтобы вызвать clear(), и вызвать это реализацию в конце вашей функции clear().

QString QAxBase::control() const

Возвращает ActiveX-контроль.

void QAxBase::disableClassInfo()

Отключает генерацию информации о классе для данного ActiveX-контейнера. Если вам не нужна информация о классе ActiveX-контроля, используйте эту функцию для ускорения генерации метаобъектов.

Обратите внимание, что эта функция должна быть вызвана сразу после создания объекта.

void QAxBase::disableEventSink()

Отключает реализацию обработчика событий для этого ActiveX-контейнера. Если вы не планируете прослушивать события ActiveX-контроля, используйте эту функцию для ускорения генерации метаобъектов.

Некоторые ActiveX-контроли могут быть нестабильными при подключении к обработчику событий. Для получения OLE-событий используйте стандартные COM-методы для регистрации собственного обработчика событий. Используйте queryInterface() для доступа к исходному COM-объекту.

Обратите внимание, что эта функция должна быть вызвана сразу после создания объекта.

void QAxBase::disableMetaObject()

Отключает генерацию метаобъектов для этого ActiveX-контейнера. Это также отключает обработчик событий и генерацию информации о классе. Если вы не планируете использовать Qt-реализацию метаобъектов, вызовите эту функцию для ускорения создания управления. Вы по-прежнему сможете вызывать объект через dynamicCall(), но сигналы, слоты и свойства не будут доступны с помощью API QObject.

Некоторые ActiveX-контроли могут быть нестабильны при использовании OLE Automation. Используйте стандартные COM-методы для использования этих элементов управления через COM-интерфейсы, предоставленные queryInterface().

Обратите внимание, что эта функция должна быть вызвана сразу после создания объекта.

QVariant QAxBase::dynamicCall(const char *function, const QVariant &var1 = QVariant(), const QVariant &var2 = QVariant(), const QVariant &var3 = QVariant(), const QVariant &var4 = QVariant(), const QVariant &var5 = QVariant(), const QVariant &var6 = QVariant(), const QVariant &var7 = QVariant(), const QVariant &var8 = QVariant())

Вызывает метод COM-объекта function, передавая параметры var1, var1, var2, var3, var4, var5, var6, var7 и var8 и возвращает значение, возвращаемое методом, или недействительный QVariant, если метод не возвращает значение или при сбое вызова функции.

Если function является методом объекта, строка должна быть предоставлена в полном прототипе, например, как она записывается в вызове QObject::connect().

activeX->dynamicCall("Navigate(const QString&)", "www.qt-project.org");

В качестве альтернативы функция может быть вызвана, передавая параметры, встроенные в строку, например, функция выше также может быть вызвана с помощью

activeX->dynamicCall("Navigate(\"www.qt-project.org\")");

Все параметры передаются в виде строк; зависит от управления, правильно ли они интерпретируются, и это медленнее, чем использование прототипа с правильно типизированными параметрами.

Если function является свойством, строка должна быть именем свойства. Сеттер свойства вызывается, когда var1 является допустимым QVariant, в противном случае вызывается геттер.

activeX->dynamicCall("Value", 5);
QString text = activeX->dynamicCall("Text").toString();

Обратите внимание, что свойства быстрее получать и устанавливать с помощью QObject::property() и QObject::setProperty().

dynamicCall() также может использоваться для вызова объектов с отключаемым метаобъектом-обёрткой, что может существенно улучшить производительность, особенно при вызове многих разных объектов разных типов во время процесса автоматизации. ActiveQt в этом случае не будет проверять параметры.

Вызывать функции можно только через dynamicCall(), имеющие параметры или возвращающие значения типов данных, поддерживаемых QVariant. Список поддерживаемых и неподдерживаемых типов данных см. в документации класса QAxBase. Если вам нужно вызвать функции с неподдерживаемыми типами данных в списке параметров, используйте queryInterface() для получения соответствующего COM-интерфейса и вызовите функцию напрямую.

IWebBrowser2 *webBrowser = 0;
activeX->queryInterface(IID_IWebBrowser2, (void **)&webBrowser);
if (webBrowser) {
    webBrowser->Navigate2(pvarURL);
    webBrowser->Release();
}

Это также более эффективно.

QVariant QAxBase::dynamicCall(const char *function, QList<QVariant> &vars)

Это перегруженная функция.

Вызывает метод COM-объекта function, передавая параметры в vars, и возвращает значение, возвращаемое методом. Если метод не возвращает значение или вызов функции завершился неудачей, эта функция возвращает объект QVariant с недопустимым значением.

Объекты QVariant в vars обновляются, когда метод имеет параметры вывода.

QString QAxBase::generateDocumentation()

Возвращает строку форматированного текста с документацией для обернутого COM-объекта. Выведите строку в HTML-файл или используйте её, например, в виджете QTextBrowser.

[virtual protected] bool QAxBase::initialize(IUnknown **ptr)

Этот виртуальный метод вызывается методом setControl() и создаёт запрашиваемый COM-объект. ptr устанавливается в реализацию IUnknown объекта. Метод возвращает true, если инициализация объекта прошла успешно; в противном случае возвращает false.

Реализация по умолчанию интерпретирует строку, возвращаемую методом control(), и вызывает initializeRemote(), initializeLicensed() или initializeActive(), если строка соответствует соответствующим шаблонам. Если control() является именем существующего файла, вызывается метод initializeFromFile(). Если шаблон не совпадает или инициализация удалённая или лицензионная завершается неудачей, используется CoCreateInstance для непосредственного создания объекта.

См. документацию свойства QAxBaseWidget::control для получения подробной информации о поддерживаемых шаблонах.

Интерфейс, возвращаемый в ptr, должен быть сосчитан ровно один раз после возврата этого метода. Интерфейс, предоставленный, например, CoCreateInstance, уже сосчитан, и нет необходимости повторно считывать его.

[protected] bool QAxBase::initializeActive(IUnknown **ptr)

Подключается к активному экземпляру, выполняемому на текущей машине, и возвращает интерфейс IUnknown к работающему объекту в ptr. Метод возвращает true при успехе, в противном случае возвращает false.

Этот метод вызывается методом initialize(), если строка управления содержит подстроку "}&".

См. также initialize().

[protected] bool QAxBase::initializeFromFile(IUnknown **ptr)

Создаёт COM-объект, обрабатывающий имя файла в свойстве control, и возвращает интерфейс IUnknown к объекту в ptr. Этот метод возвращает true при успехе, в противном случае возвращает false.

Этот метод вызывается методом initialize(), если строка управления является именем существующего файла.

См. также initialize().

[protected] bool QAxBase::initializeLicensed(IUnknown **ptr)

Создаёт экземпляр лицензированного элемента управления и возвращает интерфейс IUnknown к объекту в ptr. Этот метод возвращает true при успехе, в противном случае возвращает false.

Этот метод вызывается методом initialize(), если строка управления содержит подстроку "}:". Ключ лицензии должен следовать за этой подстрокой.

См. также initialize().

[protected] bool QAxBase::initializeRemote(IUnknown **ptr)

Создаёт экземпляр на удалённом сервере и возвращает интерфейс IUnknown к объекту в ptr. Этот метод возвращает true при успехе, в противном случае возвращает false.

Этот метод вызывается методом initialize(), если строка управления содержит подстроку "/{". Информация об удалённой машине должна быть предоставлена перед подстрокой.

См. также initialize().

bool QAxBase::isNull() const

Возвращает true, если COM-объект не загружен данным обёрткой; в противном случае возвращает false.

См. также control().

QAxBase::PropertyBag QAxBase::propertyBag() const

Возвращает карту имя:значение всех свойств, экспонируемых COM-объектом.

Это более эффективно, чем получение нескольких свойств индивидуально, если COM-объект поддерживает пакеты свойств.

См. также setPropertyBag().

[virtual] bool QAxBase::propertyWritable(const char *prop) const

Возвращает true, если свойство prop записываемое; в противном случае возвращает false. По умолчанию все свойства являются записываемыми.

См. также setPropertyWritable(), QAxBaseWidget::propertyChanged() и QAxBaseObject::propertyChanged().

long QAxBase::queryInterface(const QUuid &uuid, void **iface) const

Запрашивает интерфейс uuid у COM-объекта и устанавливает значение iface на предоставленный интерфейс или 0, если запрашиваемый интерфейс не может быть предоставлен.

Возвращает результат реализации QueryInterface COM-объекта.

См. также control().

QAxObject *QAxBase::querySubObject(const char *name, const QVariant &var1 = QVariant(), const QVariant &var2 = QVariant(), const QVariant &var3 = QVariant(), const QVariant &var4 = QVariant(), const QVariant &var5 = QVariant(), const QVariant &var6 = QVariant(), const QVariant &var7 = QVariant(), const QVariant &var8 = QVariant())

Возвращает указатель на QAxObject, оборачивающий COM-объект, предоставляемый методом или свойством name, передавая параметры var1, var1, var2, var3, var4, var5, var6, var7 и var8.

Если name предоставляется методом, строка должна включать полную сигнатуру функции.

Если name является свойством, строка должна быть именем свойства, а var1, ... var8 игнорируются.

Возвращаемый QAxObject является дочерним элементом этого объекта (который является либо QAxObject, либо QAxWidget), и удаляется при удалении этого объекта. Тем не менее, безопасно удалить возвращаемый объект самостоятельно, и вы должны сделать это при итерации по спискам дочерних объектов.

COM-совместимые приложения обычно имеют модель объекта, публикующую определённые элементы приложения как интерфейсы диспетчера. Используйте этот метод для навигации по иерархии модели объекта, например.

QAxWidget outlook("Outlook.Application");
QAxObject *session = outlook.querySubObject("Session");
if (session) {
    QAxObject *defFolder = session->querySubObject(
                            "GetDefaultFolder(OlDefaultFolders)",
                            "olFolderContacts");
    //...
}

QAxObject *QAxBase::querySubObject(const char *name, QList<QVariant> &vars)

Это перегруженная функция.

Объекты QVariant в vars обновляются, когда метод имеет параметры вывода.

[since 5.13] void QAxBase::setClassContext(ulong classContext)

Устанавливает контекст, в котором будет работать ActiveX-элемент управления, в classContext

Влияет на аргумент «dwClsContext» при вызове CoCreateInstance. Это можно использовать для управления запуском в процессе или вне процесса для элементов управления, поддерживающих оба варианта. Также его можно использовать для изменения/сокращения разрешений элемента управления при использовании CLSCTX_ENABLE_CLOAKING и маркера имперсонации.

Обратите внимание, что этот метод должен быть вызван до setControl(), чтобы иметь какой-либо эффект.

Этот метод был добавлен в Qt 5.13.

См. также classContext().

void QAxBase::setPropertyBag(const QAxBase::PropertyBag &bag)

Устанавливает свойства COM-объекта на соответствующие значения в bag.

См. также propertyBag().

[virtual] void QAxBase::setPropertyWritable(const char *prop, bool ok)

Устанавливает свойство prop в режим записи, если ok имеет значение true, в противном случае устанавливает prop в режим только для чтения. По умолчанию все свойства доступны для записи.

См. также propertyWritable(), QAxBaseWidget::propertyChanged(), и QAxBaseObject::propertyChanged().

QStringList QAxBase::verbs() const

Возвращает список команд, которые может выполнить COM-объект. Если объект не реализует IOleObject или не поддерживает никакие команды, эта функция возвращает пустой список строк.

Обратите внимание, что стандартные команды OLE (OLEIVERB_SHOW и т. д.) не включены в список.