Класс QDesktopServices

Класс QDesktopServices предоставляет методы для доступа к общим службам рабочего стола. Подробнее...

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

Статические публичные члены

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

Многие среды рабочего стола предоставляют службы, которые могут использоваться приложениями для выполнения общих задач, таких как открытие веб-страницы, способом, который является согласованным и учитывает предпочтения пользователя.

Этот класс содержит функции, которые предоставляют простые интерфейсы к этим службам, указывающие, удалось ли выполнение или нет.

Функция openUrl() используется для открытия файлов, расположенных по произвольным URL-адресам, во внешних приложениях. Для URL-адресов, соответствующих ресурсам на локальной файловой системе (где схема URL-адреса — «file»), будет использовано подходящее приложение для открытия файла; в противном случае для получения и отображения файла будет использован веб-браузер.

Настройки рабочего стола пользователя управляют тем, открываются ли определенные типы файлов с исполняемыми файлами для просмотра или выполняются вместо этого. Некоторые среды рабочего стола настроены так, чтобы предотвращать выполнение файлов, полученных из нелокальных URL-адресов, или запрашивать разрешение пользователя перед их выполнением.

Обработчики URL

Поведение функции openUrl() можно настроить для отдельных схем URL, чтобы приложения могли переопределять стандартное поведение обработки определённых типов URL.

Механизм обработки позволяет использовать только один пользовательский обработчик для каждой схемы URL-адреса; он устанавливается с помощью функции setUrlHandler(). Каждый обработчик реализуется как слот, который принимает только один аргумент QUrl.

Существующие обработчики для каждой схемы можно удалить с помощью функции unsetUrlHandler(). Это возвращает поведение обработки для заданной схемы к стандартному поведению.

Эта система облегчает реализацию системы справки, например. Справка может предоставляться в метках и текстовых браузерах с помощью URL-адресов help://myapplication/mytopic, и регистрация обработчика делает возможным отображение текста справки внутри приложения:

class MyHelpHandler : public QObject
{
    Q_OBJECT
public:
    // ...
public slots:
    void showHelp(const QUrl &url);
};
QDesktopServices::setUrlHandler("help", helpInstance, "showHelp");

Если внутри обработчика вы решите, что не можете открыть запрашиваемый URL-адрес, вы можете просто снова вызвать QDesktopServices::openUrl() с тем же аргументом, и он попытается открыть URL-адрес с помощью соответствующего механизма для среды рабочего стола пользователя.

В сочетании с платформенно-специфическими настройками схемы, зарегистрированные функцией openUrl(), также могут быть доступны другим приложениям, что открывает возможности для глубокой привязки приложений или очень простого механизма межпроцессного взаимодействия на основе URL-адресов.

См. также QSystemTrayIcon, QProcess и QStandardPaths.

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

[static] bool QDesktopServices::openUrl(const QUrl &url)

Открывает заданный url в соответствующем веб-браузере для среды рабочего стола пользователя и возвращает true в случае успеха; в противном случае возвращает false.

Если URL-адрес ссылается на локальный файл (т. е. схема URL-адреса — «file»), то он будет открыт с помощью соответствующего приложения вместо веб-браузера.

Следующий пример открывает файл в файловой системе Windows, расположенный по пути, содержащему пробелы:

QDesktopServices::openUrl(QUrl("file:///C:/Documents and Settings/All Users/Desktop", QUrl::TolerantMode));

Если указан URL-адрес mailto, для открытия окна создания письма, содержащего указанные в URL-адресе параметры, будет использован почтовый клиент пользователя, аналогично тому, как обрабатываются ссылки mailto в веб-браузере.

Например, следующий URL-адрес содержит получателя (user@foo.com), тему (Test) и тело сообщения (Just a test):

mailto:user@foo.com?subject=Test&body=Just a test

Предупреждение: Хотя многие почтовые клиенты могут отправлять вложения и работают с кодировкой Unicode, пользователь может настроить свой клиент без этих функций. Кроме того, у некоторых почтовых клиентов (например, Lotus Notes) есть проблемы с длинными URL-адресами.

Предупреждение: Значение возврата true указывает, что приложение успешно запросило операционную систему открыть URL-адрес во внешнем приложении. Внешнее приложение все равно может не запуститься или не открыть запрашиваемый URL-адрес. Этот результат не будет сообщен обратно приложению.

Предупреждение: URL-адреса, передаваемые в эту функцию на iOS, не будут загружаться, если их схемы не перечислены в ключе LSApplicationQueriesSchemes файла Info.plist приложения. Для получения дополнительной информации см. документацию Apple Developer для canOpenURL(_:). Например, следующие строки включают URL-адреса со схемой HTTPS:

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>https</string>
</array>

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

[static] void QDesktopServices::setUrlHandler(const QString &scheme, QObject *receiver, const char *method)

Устанавливает обработчик для заданной scheme, которым является обработчик method, предоставляемый объектом receiver.

Эта функция предоставляет способ настройки поведения openUrl(). Если openUrl() вызывается с URL-адресом с указанной scheme, то вместо запуска внешнего приложения приложением QDesktopServices вызывается указанный method для объекта receiver.

Предоставленный метод должен быть реализован как слот, принимающий только один аргумент QUrl.

class MyHelpHandler : public QObject
{
    Q_OBJECT
public:
    // ...
public slots:
    void showHelp(const QUrl &url);
};

Чтобы использовать эту функцию для получения данных от других приложений на iOS, вы также должны добавить пользовательскую схему в список CFBundleURLSchemes в файле Info.plist:

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>myapp</string>
        </array>
    </dict>
</array>

Для получения дополнительной информации см. документацию Apple Developer для Общение с другими приложениями с помощью настраиваемых URL-адресов.

Предупреждение: Невозможно заявить о поддержке некоторых известных схем URL-адресов, включая http и https. Это разрешено только для универсальных ссылок.

Для заявления о поддержке http и https указанная выше запись в файле Info.plist не допускается. Это возможно только при добавлении вашего домена в файл Entitlements:

<key>com.apple.developer.associated-domains</key>
<array>
    <string>applinks:your.domain.com</string>
</array>

При установке приложения iOS будет искать /.well-known/apple-app-site-association по вашему домену. Если вы хотите прослушивать https://your.domain.com/help?topic=ABCDEF, вам нужно предоставить следующее содержимое там:

{
    "applinks": {
        "apps": [],
        "details": [{
            "appIDs" : [ "ABCDE12345.com.example.app" ],
            "components": [{
                "/": "/help",
                "?": { "topic": "?*"}
            }]
        }]
    }
}

Для получения дополнительной информации см. документацию Apple Developer для https://developer.apple.com/documentation/safariservices/supporting_associated_domains_in_your_app[Поддержка связанных доменов}.

Если setUrlHandler() используется для установки нового обработчика для схемы, для которой уже есть обработчик, существующий обработчик просто заменяется новым. Поскольку QDesktopServices не берет на себя ответственность за обработчики, никакие объекты не удаляются при замене обработчика.

Обратите внимание, что обработчик всегда будет вызываться из того же потока, что и вызов QDesktopServices::openUrl().

См. также openUrl() и unsetUrlHandler().

[static] void QDesktopServices::unsetUrlHandler(const QString &scheme)

Удаляет ранее установленный обработчик URL для указанной scheme.

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