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

Если указан mailto URL-адрес, клиент электронной почты пользователя будет использован для открытия окна составления сообщения, содержащего параметры, указанные в 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 для Communicating with Other Apps Using Custom URLs.

Предупреждение: Невозможно заявить о поддержке некоторых известных схем 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().