Класс 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.

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

typedef QAxBase::PropertyBag

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 automation IDispatch. code, source, desc и help предоставляют информацию об исключении, предоставленную COM-сервером, и могут использоваться для предоставления полезной обратной связи пользователю. help включает файл справки и идентификатор контекста справки в скобках, например, «имя_файла [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(), если строка свойства 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() и 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. Это может использоваться для управления запуском в процессе или вне процесса для элементов управления, поддерживающих оба варианта. Также может использоваться для изменения/сокращения разрешений элемента управления при использовании 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

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

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

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