Класс QAxBase

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

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

Типы public

Свойства

• control : QString

Функции public

Сигналы

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

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

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

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

Свойства, экспонируемые реализацией объекта IDispatch, могут быть читаемы и записываемы через систему свойств, предоставляемую моделью Qt Object (оба подкласса являются QObjects, поэтому вы можете использовать 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

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