Класс 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(), если строка свойства control содержит подстроку "}&".

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

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

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

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

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

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

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

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

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

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

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

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

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

bool QAxBase::isNull() const

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

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

QAxBase::PropertyBag QAxBase::propertyBag() const

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

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

Предупреждение: Не гарантируется, что реализация пакета свойств COM-объекта возвращает все свойства или что возвращаемые свойства совпадают со свойствами, доступными через интерфейс IDispatch.

См. также 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. Это позволяет управлять запуском в процессе (in-proc) или вне процесса (out-of-proc) для элементов управления, поддерживающих оба варианта. Также можно изменять/снижать разрешения элемента управления, если используется CLSCTX_ENABLE_CLOAKING и маркер имперсонации.

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

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

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

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

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

Предупреждение: Вы должны устанавливать только пакеты свойств, которые были возвращены функцией propertyBag, так как нет гарантии, что реализация пакета свойств COM-объекта поддерживает те же свойства, которые доступны через интерфейс IDispatch.

См. также 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 и т. д.) не включены в список.