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

<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, то вместо запуска внешнего приложения в объекте receiver вызывается заданный method.

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

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

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

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

iOS

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

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

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

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

Android

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

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="https" android:host="your.domain.com" android:port="1337" android:path="/help"/>
</intent-filter>

Для получения дополнительной информации см. документацию разработчика Android по Создание глубоких ссылок на содержимое приложения.

Чтобы немедленно открыть соответствующее содержимое в вашем приложении Android без необходимости выбора приложения пользователем, вам необходимо проверить вашу ссылку. Для включения проверки добавьте дополнительный параметр в фильтр намерения:

<intent-filter android:autoVerify="true">

Android будет искать https://your.domain.com/.well-known/assetlinks.json, когда приложение устанавливается. Если вы хотите прослушивать https://your.domain.com:1337/help, вам необходимо предоставить следующее содержимое там:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Для получения дополнительной информации см. документацию разработчика Android по Проверка ассоциаций веб-сайтов Android App Links.

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

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

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

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