Qt for HarmonyOS/qtohosextras doc/QtOhosExtras Namespace

QtOhosExtras Namespace

The QtOhosExtras namespace provides miscellaneous functions to aid Ohos development. More...

Header:	#include <QtOhosExtras>
qmake:	QT += ohosextras
Since:	Qt 5.12.12

This namespace was introduced in Qt 5.12.12.

Namespaces

namespace	AppPermissions
namespace	FileShare
namespace	Multimedia
namespace	QOhosPasteboard
namespace	ShareKit

Classes

class	QOhosAbilityContext
class	QOhosAppContext
class	QOhosBundleInfo
class	QOhosDistributedDataObject
struct	QOhosElementName
class	QOhosOnContinueContext
class	QOhosOpenLinkOptions
class	QOhosOperationStatus
class	QOhosStartOptions
class	QOhosStartRequest
struct	QOhosWant
class	QOhosWantInfo
class	QOhosWindowCreateParams

Types

enum class	CloseEventRootCause { InternalClose, AbilityClose, WindowStageClose }
enum class	QOhosWantFlag { AuthReadUriPermission, AuthWriteUriPermission, InstallOnDemand }
flags	QOhosWantFlags
enum class	WindowGeometryPersistenceHint { Disabled, Enabled, FollowSystemSetting }

Functions

bool	authorizeFilePath(QWindow *parentWindow, const QString &filePath)
QSharedPointer<QOhosOpenLinkOptions>	createOpenLinkOptions()
QSharedPointer<QOhosStartOptions>	createStartOptions()
QSharedPointer<QOhosStartRequest>	createStartRequest(const QOhosStartOptions &options)
QSharedPointer<QOhosWindowCreateParams>	createWindowCreateParams()
CloseEventRootCause	getCloseEventRootCause(QCloseEvent *closeEvent)
bool	moveFileToTrash(const QString &filePath)
void	setAbilityInstanceDestroyEnabled(QWindow *instanceWindow, bool destroyEnabled)
void	setBundledAbilityAndQWindowBindingKeyForQWindow(QWindow *window, const QString &qAbilityQWindowBindingKey)
void	setMainWindowGeometryPersistenceHint(WindowGeometryPersistenceHint geometryPersistenceHint)
void	setShowWindowAsFloatWindowHint(QWindow *window, bool showAsFloatWindow)
void	setShowWindowAsFloatWindowHint(QWidget *widget, bool showAsFloatWindow)
void	setSurfaceBackgroundColor(QWindow *window, const QColor &color)
void	setSurfaceBackgroundColor(QWidget *widget, const QColor &color)
void	setWindowCornerRadius(QWindow *window, double radius)
void	setWindowCornerRadius(QWidget *widget, double radius)
void	setWindowDragResizable(QWindow *window, bool dragResizable)
void	setWindowDragResizable(QWidget *widget, bool dragResizable)
void	setWindowKeepScreenOn(QWindow *window, bool keepScreenOn)
void	setWindowKeepScreenOn(QWidget *widget, bool keepScreenOn)
void	setWindowPrivacyMode(QWindow *window, bool privacyModeEnabled)
QSharedPointer<QOhosOperationStatus>	startAbility(const QOhosWant &want)
QSharedPointer<QOhosOperationStatus>	startAbility(const QOhosWant &want, const QOhosStartOptions &options)
QSharedPointer<QOhosOperationStatus>	startAbility(const QOhosWant &want, const QOhosStartRequest &startRequest)
QSharedPointer<QOhosOperationStatus>	startAbilityByType(const QString &appType, const QJsonObject &wantParameters)
void	startAppProcess(const QString &processId, const QOhosWant &requestWant)
void	startAppProcess(const QString &processId, const QOhosWant &requestWant, const QOhosStartOptions &options)
void	startAppProcess(const QString &processId, const QOhosWant &requestWant, const QOhosStartRequest &startRequest)
void	startNewAbilityInstance(QWidget *instanceWidget)
QSharedPointer<double>	tryGetNativeWindowId(QWindow *window)
QSharedPointer<QByteArray>	tryGetOnContinueData(const QOhosWant &want)
QSharedPointer<double>	tryGetScreenDisplayId(QScreen *screen)
QList<QSharedPointer<QOhosDistributedDataObject>>	tryRestoreOnContinueDistributedDataObjects(const QOhosWant &want)

Namespaces

namespace QtOhosExtras::AppPermissions

 auto *appContext = QtOhosExtras::QOhosAppContext::instance();
 if (!appContext->isPermissionGranted(QtOhosExtras::AppPermissions::Permission::AccessBluetooth)) {
     QObject::connect(
         appContext, &QtOhosExtras::QOhosAppContext::permissionRequestResponseWithResultReceived,
         [](QtOhosExtras::AppPermissions::Permission permission,
            QtOhosExtras::AppPermissions::PermissionResult result) {
             if (result.permissionGranted) {
                 // start using the permission-protected feature ...
             }
         });
     appContext->requestPermissionFromUserIfNeeded(
         QtOhosExtras::AppPermissions::Permission::AccessBluetooth);
 }

This namespace was introduced in Qt 5.12.12.

See also QtOhosExtras::QOhosAppContext and QtOhosExtras::QOhosAbilityContext.

namespace QtOhosExtras::FileShare

This API uses file system paths, which differ from the URIs used internally by HarmonyOS. For example, the path /data/storage/el1/bundle/entry/resources/resfile/test.txt will be converted to the URI file://com.your.example/data/storage/el1/bundle/entry/resources/resfile/test.txt , where com.your.example is app bundle name.

To learn more about file paths and URIs in HarmonyOS, see sandbox documentation.

Warning: This API relies on the underlying OHOS implementation. The following functions: persistPermission(), revokePermission(), activatePermission(), deactivatePermission(), and checkPersistent() may be unavailable on some devices. Additionally, there may be limitations on the maximum number of policies, and certain permissions may need to be explicitly granted to the application.

For more details and limitations, refer to the API documentation.

This namespace was introduced in Qt 5.12.12.

namespace QtOhosExtras::Multimedia

The Multimedia namespace contains functions and types for controlling audio stream usage on HarmonyOS. It allows setting audio stream usage hints on QSoundEffect and QSound objects, which influences how the system routes and manages audio output.

This namespace was introduced in Qt 5.12.12.

See also QtOhosExtras::Multimedia::AudioStreamUsageHint.

namespace QtOhosExtras::QOhosPasteboard

This namespace was introduced in Qt 5.12.12.

namespace QtOhosExtras::ShareKit

This namespace was introduced in Qt 5.12.12.

Classes

class QOhosAbilityContext

The QOhosAbilityContext class is to manage native UI Ability context. See UIAbilityContext. More...

class QOhosAppContext

The QOhosAppContext class contains API to manage native application context. More...

class QOhosBundleInfo

The QOhosBundleInfo class contains API to provide native application bundle info. More...

class QOhosDistributedDataObject

The QOhosDistributedDataObject class shares a fixed set of named fields across devices that belong to the same trusted network. More...

class QOhosElementName

The QOhosElementName struct identifies an ability component. More...

class QOhosOnContinueContext

The QOhosOnContinueContext class manages onContinue context. It provides system data, like source application version code and set the onContinue result that is requested by the system. See UIAbility onContinue. More...

class QOhosOpenLinkOptions

The QOhosOpenLinkOptions class provides options for the QOhosAbilityContext::tryOpenLink() call. More...

class QOhosOperationStatus

The QOhosOperationStatus class provides an interface to check an operation status. More...

class QOhosStartOptions

The QOhosStartOptions class is to provide new options for new started ability or process. More...

class QOhosStartRequest

The QOhosStartRequest class emits signals for start ability. More...

class QOhosWant

QOhosWant wraps Ohos Want class. More...

class QOhosWantInfo

The QOhosWantInfo class is to represent Ohos want type. More...

class QOhosWindowCreateParams

The QOhosWindowCreateParams class provides window creation parameters for a started ability window. More...

Type Documentation

enum class QtOhosExtras::CloseEventRootCause

Enumerates the close event root cause.

Constant	Value	Description
QtOhosExtras::CloseEventRootCause::InternalClose	0	Close root cause not specified or unknown.
QtOhosExtras::CloseEventRootCause::AbilityClose	1	Close root cause of preparing to terminate.
QtOhosExtras::CloseEventRootCause::WindowStageClose	2	Close root cause of native Window Stage or Sub-Window close.

This enum was introduced or modified in Qt 5.12.12.

enum class QtOhosExtras::QOhosWantFlag
flags QtOhosExtras::QOhosWantFlags

QOhosWantFlag specifies how the Want will be handled. See Flags.

Constant	Value	Description
QtOhosExtras::QOhosWantFlag::AuthReadUriPermission	1 << 0	Grants the permission to read the URI.
QtOhosExtras::QOhosWantFlag::AuthWriteUriPermission	1 << 1	Grants the permission to write data to the URI.
QtOhosExtras::QOhosWantFlag::InstallOnDemand	1 << 2	Ability will be installed if it has not been installed.

This enum was introduced or modified in Qt 5.12.12.

The QOhosWantFlags type is a typedef for QFlags<QOhosWantFlag>. It stores an OR combination of QOhosWantFlag values.

enum class QtOhosExtras::WindowGeometryPersistenceHint

Enumerates the policy for window geometry persistence support. Specifies how a window’s geometry (the size and position) is determined when it is shown.

Constant	Value	Description
QtOhosExtras::WindowGeometryPersistenceHint::Disabled	0	Use default window's geometry.
QtOhosExtras::WindowGeometryPersistenceHint::Enabled	1	Restore previous window's geometry (position and size when before window was closed).
QtOhosExtras::WindowGeometryPersistenceHint::FollowSystemSetting	2	Let the system decide whether to use Disabled or Enabled value.

This enum was introduced or modified in Qt 5.12.12.

Function Documentation

bool QtOhosExtras::authorizeFilePath(QWindow *parentWindow, const QString &filePath)

Request authorization on the User selected parentWindow for a given filePath. The system File Dialog in authorization mode will be presented to the User. According to User choice returns true if file path is authorized, false otherwise. See authMode

This function was introduced in Qt 5.12.12.

QSharedPointer<QOhosOpenLinkOptions> QtOhosExtras::createOpenLinkOptions()

Creates an options object to be used with QOhosAbilityContext::tryOpenLink().

See also QOhosAbilityContext::tryOpenLink().

QSharedPointer<QOhosStartOptions> QtOhosExtras::createStartOptions()

Creates QOhosStartOptions instance.

QSharedPointer<QOhosStartRequest> QtOhosExtras::createStartRequest(const QOhosStartOptions &options)

Creates a start request for given options and adapts the completion handler into Qt signals.

Connect to QOhosStartRequest::requestSucceeded() and QOhosStartRequest::requestFailed() to receive completion handler results.

See Completion Handler.

See also QOhosStartRequest.

QSharedPointer<QOhosWindowCreateParams> QtOhosExtras::createWindowCreateParams()

Creates QOhosWindowCreateParams instance.

CloseEventRootCause QtOhosExtras::getCloseEventRootCause(QCloseEvent *closeEvent)

Converts a given closeEvent to QtOhosExtras::CloseEventRootCause and returns the related value.

bool QtOhosExtras::moveFileToTrash(const QString &filePath)

Moves the file specified by filePath to the trash. Returns true if successful, false otherwise.

This function provides functionality of QFile::moveToTrash() from Qt 5.15.

void QtOhosExtras::setAbilityInstanceDestroyEnabled(QWindow *instanceWindow, bool destroyEnabled)

Sets whether the Ability related with instanceWindow can be automatically destroyed by the system when the user clicks on the window's "close" button. If destroyEnabled is true, the system destroys the Ability automatically (and Qt needs to adapt to this). If destroyEnabled = false, the window is not automatically destroyed, but instead standard Qt path for window close is triggered, i.e. QWindow::close().

By default, the flag is set to false.

See also QOhosAbilityContext::setDestroyFromSystemEnabled().

void QtOhosExtras::setBundledAbilityAndQWindowBindingKeyForQWindow(QWindow *window, const QString &qAbilityQWindowBindingKey)

Function marks that the window is supposed to be used with QBundledEmbeddedUiExtensionAbility instance that has specific "Ability <=> QWindow binding key" assigned in form of 'io.qt.public.bundledAbilityAndQWindowBindingKey' want parameter matching the provided qAbilityQWindowBindingKey.

The window that is passed to this function needs to have no parent/transient parent any may not be visible. The window will become visible either after the function call, if the corresponding instance of the QBundledEmbeddedUiExtensionAbility is already present, or after the corresponding instance is started.

The concept of multiple EmbeddedUIExtensionAbilities is described in OpenHarmony docs: https://gitee.com/openharmony/docs/blob/master/en/application-dev/application-models/embeddeduiextensionability.md

void QtOhosExtras::setMainWindowGeometryPersistenceHint(WindowGeometryPersistenceHint geometryPersistenceHint)

Sets a given geometryPersistenceHint on first main window shown.

If this function is called with geometryPersistenceHint `Enabled`, the first main window's geometry will be saved when the window is closed and restored on the next application launch. By default this feature is disabled.

This method must be called before first main window is shown. Otherwise geometry persistence policy will not be updated.

Only supported on 2-in-1 devices.

Read about details in here.

void QtOhosExtras::setShowWindowAsFloatWindowHint(QWindow *window, bool showAsFloatWindow)

Sets or unsets a given window as floating window according to showAsFloatWindow flag. Read more about floating window type here.

 auto window = std::make_unique<MainWindow>();
 QtOhosExtras::setShowWindowAsFloatWindowHint(window.get(), true);
 window->show();

void QtOhosExtras::setShowWindowAsFloatWindowHint(QWidget *widget, bool showAsFloatWindow)

Sets or unsets a given widget as floating window according to showAsFloatWindow flag. Read more about floating window type here.

void QtOhosExtras::setSurfaceBackgroundColor(QWindow *window, const QColor &color)

Sets a given color as background color on the window inner native layer.

void QtOhosExtras::setSurfaceBackgroundColor(QWidget *widget, const QColor &color)

Sets a given color as background color on the widget inner native layer.

Warning: Currently, dynamic color change on a widget is not supported yet.

void QtOhosExtras::setWindowCornerRadius(QWindow *window, double radius)

Sets corner radius for a window. Given window has to be a sub or floating window type. It can be achieved for example: - by setting Qt::WindowFlags, like: Qt::Window, Qt::Popup, Qt::Dialog etc. - explicitly using QtOhosExtras::setShowWindowAsFloatWindowHint() function. More on windows in: Qt official docs. The radius must not be a negative number. There's no upper limit in value, although visually OHOS uses maximum achievable value. In order for this function to work properly, it has to be called before the window is shown.

Read more: here.

void QtOhosExtras::setWindowCornerRadius(QWidget *widget, double radius)

Sets corner radius for a widget. Given widget has to be formed as a new window, it means it cannot be embedded in a parent widget. It can be achieved for example: - by setting Qt::WindowFlags, like: Qt::Window, Qt::Popup, Qt::Dialog etc. - explicitly using QtOhosExtras::setShowWindowAsFloatWindowHint() function. More on widgets as windows in: Qt official docs. The radius must not be a negative number. There's no upper limit in value, although visually OHOS uses maximum achievable value. In order for this function to work properly, it has to be called before the widget is shown.

Read more: here.

void QtOhosExtras::setWindowDragResizable(QWindow *window, bool dragResizable)

Enables or disables window resize ability (dragging), as per the dragResizable parameter.

The function takes effect on sub windows and floating windows.

Note: This function can be called on a window after being shown.

Note: The functionality isn't supported on application main windows (i.e. first QWidget shown in application, or QWidget shown without parent, or QWidget explicitly tagged as main window before show).

Read more: here.

void QtOhosExtras::setWindowDragResizable(QWidget *widget, bool dragResizable)

Enables or disables widget resize ability (dragging).

Given widget has to be formed as a new window, it means it cannot be embedded in a parent widget. The function takes effect on sub windows (window flags: Qt::Window, Qt::Dialog, Qt::Popup, Qt::ToolTip etc) and floating windows (marked with QtOhosExtras::setShowWindowAsFloatWindowHint() function)

Note: This function can be called on a widget before as well as after being shown.

Note: The functionality isn't supported on application main windows (i.e. first QWidget shown in application, or QWidget shown without parent, or QWidget explicitly tagged as main window before show).

Read more: here.

void QtOhosExtras::setWindowKeepScreenOn(QWindow *window, bool keepScreenOn)

Sets or unsets a given window to keep the screen on according to keepScreenOn flag.

Read more: here.

void QtOhosExtras::setWindowKeepScreenOn(QWidget *widget, bool keepScreenOn)

Sets or unsets a given widget to keep the screen on according to keepScreenOn flag.

Read more: here.

void QtOhosExtras::setWindowPrivacyMode(QWindow *window, bool privacyModeEnabled)

Change window privacy mode according to a given window and privacyModeEnabled. Read more about window privacy mode here

QSharedPointer<QOhosOperationStatus> QtOhosExtras::startAbility(const QOhosWant &want)

Starts an Ability for a given want. See Start Ability.

Warning: Currently, operation status result is hardcoded as "successful" (even if ability were not started).

QSharedPointer<QOhosOperationStatus> QtOhosExtras::startAbility(const QOhosWant &want, const QOhosStartOptions &options)

Starts an Ability for a given want and options. See Start Ability.

Warning: Currently, operation status result is hardcoded as "successful" (even if ability were not started).

QSharedPointer<QOhosOperationStatus> QtOhosExtras::startAbility(const QOhosWant &want, const QOhosStartRequest &startRequest)

Starts an Ability for a given want and startRequest.

The startRequest carries the completion handler from start options. Connect to QOhosStartRequest::requestSucceeded() and QOhosStartRequest::requestFailed() to receive completion handler results. See Start Ability.

QSharedPointer<QOhosOperationStatus> QtOhosExtras::startAbilityByType(const QString &appType, const QJsonObject &wantParameters)

Starts an Ability for a given appType and wantParameters. See Start Ability.

Returns an operation status object; its QOhosOperationStatus::success() reports whether the request succeeded.

void QtOhosExtras::startAppProcess(const QString &processId, const QOhosWant &requestWant)

Starts application process for a given processId and requestWant.

void QtOhosExtras::startAppProcess(const QString &processId, const QOhosWant &requestWant, const QOhosStartOptions &options)

Starts application process for a given processId, requestWant and options.

void QtOhosExtras::startAppProcess(const QString &processId, const QOhosWant &requestWant, const QOhosStartRequest &startRequest)

Starts application process for a given processId, requestWant and startRequest. The startRequest carries the completion handler from start options. Connect to QOhosStartRequest::requestSucceeded() and QOhosStartRequest::requestFailed() to receive completion handler results.

See Start Ability.

See also QOhosStartRequest.

void QtOhosExtras::startNewAbilityInstance(QWidget *instanceWidget)

Starts another instance of the UIAbility used by the Qt app with specified widget inside

The caller should pass newly created QWidget instanceWidget, without any setting any parent, calling show() or winId() on it.

QSharedPointer<double> QtOhosExtras::tryGetNativeWindowId(QWindow *window)

Function tries to obtain native window ID (ID associated with system window object) of given window. The failure of the operation is indicated by returned value equal to nullptr.

Note: This function must be called only after the window has been shown.

Warning: Returned native window ID isn't guaranteed to be valid throughout the lifetime of application. Application stability and performance may be poor after using this function, use it at your own risk!

Read more on native window ID (WindowProperties.id): here

QSharedPointer<QByteArray> QtOhosExtras::tryGetOnContinueData(const QOhosWant &want)

Tries to get continuation / migration related data that was provided on the source device. Returns nullptr if no such data found. The data is expected to be stored in the want parameters. See Application Continuation.

QSharedPointer<double> QtOhosExtras::tryGetScreenDisplayId(QScreen *screen)

Function tries to obtain native display ID of given screen. The failure of the operation is indicated by returning nullptr .

Read more on display ID (Display.id): here

QList<QSharedPointer<QOhosDistributedDataObject>> QtOhosExtras::tryRestoreOnContinueDistributedDataObjects(const QOhosWant &want)

Recreates the distributed data objects that were migrated in want by QOhosOnContinueContext::setResponseOnDistributedDataObjectsSaveResults() on the source device, and returns them. Returns an empty list if want carries no distributed data objects.

Each returned object joins its session asynchronously, so connect to its dataChanged(), statusChanged() and progressChanged() signals right away to avoid missing the initial sync.

See also QOhosOnContinueContext::setResponseOnDistributedDataObjectsSaveResults().