Класс QAxBase

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

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

Публичные типы

Свойства

• control : QString

Публичные функции

Сигналы

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

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

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

Это псевдоним типа QMap<QString, QVariant>.

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

ctrl->setControl("{8E27C92B-1264-101C-8A2F-040224009C02}");

ctrl->setControl("MSCal.Calendar");

ctrl->setControl("Calendar Control 9.0");

ctrl->setControl("c:/files/file.doc");

ctrl->setControl("DOMAIN/user:password@server/{8E27C92B-1264-101C-8A2F-040224009C02}:LicenseKey");

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

QAxBase::QAxBase(IUnknown *iface = nullptr)

Создаёт объект QAxBase, который оборачивает COM-объект iface. Если iface равен 0 (значение по умолчанию), используйте setControl() для создания COM-объекта.

[signal] void QAxBase::exception(int code, const QString &source, const QString &desc, const QString &help)

Это сигнал, который испускается, когда COM-объект выбрасывает исключение при вызове через OLE-автоматизацию интерфейс IDispatch. code, source, desc и help предоставляют информацию об исключении, как предоставлено COM-сервером, и могут быть использованы для предоставления полезной обратной связи конечному пользователю. help включает файл справки и идентификатор контекста справки в квадратных скобках, например «filename [id]».

[signal] void QAxBase::propertyChanged(const QString &name)

Если COM-объект поддерживает уведомления о свойствах, этот сигнал испускается, когда свойство с именем name изменяется.

[signal] void QAxBase::signal(const QString &name, int argc, void *argv)

Этот универсальный сигнал испускается, когда COM-объект вызывает событие name. argc — количество параметров, предоставляемых событием (DISPPARAMS.cArgs), а argv — указатель на значения параметров (DISPPARAMS.rgvarg). Обратите внимание, что порядок значений параметров обратный, т.е. последний элемент массива является первым параметром функции.

void Receiver::slot(const QString &name, int argc, void *argv)
{
    VARIANTARG *params = (VARIANTARG*)argv;
    if (name.startsWith("BeforeNavigate2(")) {
        IDispatch *pDisp = params[argc-1].pdispVal;
        VARIANTARG URL = *params[argc-2].pvarVal;
        VARIANTARG Flags = *params[argc-3].pvarVal;
        VARIANTARG TargetFrameName = *params[argc-4].pvarVal;
        VARIANTARG PostData = *params[argc-5].pvarVal;
        VARIANTARG Headers = *params[argc-6].pvarVal;
        bool *Cancel = params[argc-7].pboolVal;
    }
}

Используйте этот сигнал, если событие содержит параметры неподдерживаемых типов данных. В противном случае подключайтесь непосредственно к сигналу name.

[virtual] QAxBase::~QAxBase()

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

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

QVariant QAxBase::asVariant() const

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

unsigned long QAxBase::classContext() const

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

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

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

[virtual] void QAxBase::clear()

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

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

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-автоматизации. Используйте стандартные методы 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 используется напрямую для создания объекта.

Подробности о поддерживаемых шаблонах см. в документации свойства 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-объект поддерживает пакеты свойств.

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

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

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

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

Предупреждение: В зависимости от реализации управляющего элемента это значение может игнорироваться для некоторых свойств.

См. также setPropertyWritable() и 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 обновляются, когда метод имеет параметры вывода.

void QAxBase::setClassContext(unsigned long 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() и propertyChanged().

QStringList QAxBase::verbs() const

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

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

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