Класс QDesktopServices

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

Этот класс был представлен в Qt 4.2.

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

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

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

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

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

Функция 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() могут быть также доступны другим приложениям, открывая возможности для глубоких ссылок приложения или очень простого механизма IPC на основе URL.

Примечание: Начиная с Qt 5, storageLocation() и displayName() заменены функциональностью, предоставляемой классом QStandardPaths.

См. также 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 для 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);
};

QDesktopServices::setUrlHandler("help", helpInstance, "showHelp");

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

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

Для получения дополнительной информации см. документацию разработчика Apple для 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 для 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().