Класс QAxBase

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

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

Типы

Свойства

• control : QString

Открытые функции

Сигналы

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

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

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

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

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.

[virtual] QAxBase::~QAxBase()

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

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

QVariant QAxBase::asVariant() const

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

[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 ( 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 обновляются, если метод имеет параметры-выходы.

[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]".

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().

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

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

[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::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().

[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.

QStringList QAxBase::verbs() const

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

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

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