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

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 = Q_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, в противном случае вызывается getter.

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

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

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.

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 PropertyBag &bag)

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

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

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

[virtual] void QAxBase::setPropertyWritable(const char *prop, bool ok)

Устанавливает свойство prop в режим записи, если ok истинно, в противном случае устанавливает 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.