Qt for HarmonyOS/qtohosextras doc/QOhosAppContext Class

QOhosAppContext Class

class QtOhosExtras::QOhosAppContext

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

Header:	#include <QOhosAppContext>
qmake:	QT += ohosextras
Since:	Qt 5.12.12
Inherits:	QObject

This class was introduced in Qt 5.12.12.

• List of all members, including inherited members

Public Types

enum class

ColorThemeMode { LightTheme, DarkTheme, FollowSystemSetting }

Public Functions

virtual bool	darkThemeActive() const = 0
virtual void	enableContextMenuEventOnLongPress() = 0
virtual double	fontSizeScale() const = 0
virtual QSharedPointer<QOhosBundleInfo>	getBundleInfo() const = 0
virtual bool	hasSerialPortAccessRight(const QString &portName) const = 0
virtual bool	isPermissionGranted(AppPermissions::Permission permission) const = 0
virtual bool	isPermissionGranted(const QString &permissionName) const = 0
virtual void	requestPermissionFromUserIfNeeded(AppPermissions::Permission permission) = 0
virtual void	requestPermissionOnSettingIfNeeded(AppPermissions::Permission permission) = 0
virtual void	requestSerialPortAccessRightIfNeeded(const QString &portName) = 0
virtual void	restartApp() = 0
virtual void	restartApp(const QOhosWant &requestWant) = 0
virtual void	setColorThemeMode(ColorThemeMode mode) = 0

Signals

void	darkThemeActiveChanged(bool darkThemeActive)
void	fontSizeScaleChanged(double fontSizeScale)
void	permissionRequestOnSettingResponseReceived(AppPermissions::Permission permission, bool permissionGranted)
void	permissionRequestResponseReceived(AppPermissions::Permission permission, bool permissionGranted)
void	permissionRequestResponseWithResultReceived(AppPermissions::Permission permission, AppPermissions::PermissionResult result)
void	serialPortAccessRightResponseReceived(const QString &portName, QSharedPointer<QObject> serialPortAccessRightContext)

Static Public Members

QOhosWant	getAppLaunchWant()
QSharedPointer<QOhosWantInfo>	getAppLaunchWantInfo()
QOhosAppContext *	instance()
bool	isNoUiChildMode()
void	startNoUiChildProcess(QString libraryName, QStringList args)

Member Type Documentation

enum class QOhosAppContext::ColorThemeMode

Defines the color theme mode for the application.

Constant	Value	Description
QtOhosExtras::QOhosAppContext::ColorThemeMode::LightTheme	0	Uses the light theme colors (default).
QtOhosExtras::QOhosAppContext::ColorThemeMode::DarkTheme	1	Uses the dark theme colors.
QtOhosExtras::QOhosAppContext::ColorThemeMode::FollowSystemSetting	2	Automatically updates the theme based on the system setting. See Configuration Updated.

This enum was introduced or modified in Qt 5.12.12.

Member Function Documentation

[signal] void QOhosAppContext::darkThemeActiveChanged(bool darkThemeActive)

Signal emitted when the application's color theme changes between dark and light modes. The darkThemeActive parameter is true when the dark theme became active.

See also darkThemeActive() and setColorThemeMode().

[signal] void QOhosAppContext::fontSizeScaleChanged(double fontSizeScale)

Signal emitted on system configuration update. fontSizeScale is the system current font size scale. See Configuration Updated.

See also fontSizeScale().

[signal] void QOhosAppContext::permissionRequestOnSettingResponseReceived(AppPermissions::Permission permission, bool permissionGranted)

Signal emitted on requestPermissionOnSettingIfNeeded() request result. Provides permissionGranted state for a checked permission.

See also requestPermissionOnSettingIfNeeded().

[signal] void QOhosAppContext::permissionRequestResponseReceived(AppPermissions::Permission permission, bool permissionGranted)

Signal emitted on requestPermissionFromUserIfNeeded() request result. Provides permissionGranted state for a checked permission.

See also requestPermissionFromUserIfNeeded().

[signal] void QOhosAppContext::permissionRequestResponseWithResultReceived(AppPermissions::Permission permission, AppPermissions::PermissionResult result)

Signal emitted on requestPermissionFromUserIfNeeded() request result. Provides result for a checked permission.

See also requestPermissionFromUserIfNeeded().

[signal] void QOhosAppContext::serialPortAccessRightResponseReceived(const QString &portName, QSharedPointer<QObject> serialPortAccessRightContext)

Emitted when the result of requestSerialPortAccessRightIfNeeded(const QString &portName) becomes available.

The signal provides the portName corresponding to the response. Additionally, it includes a serialPortAccessRightContext that defines the access rights granted for the requested serial port. The caller must keep this context alive for as long as access to the serial port is required.

Destroying or releasing the context automatically cancels the access rights for the associated serial port.

If access was not granted, the context will be nullptr.

Note: The lifetime of the access permission is strictly tied to the lifetime of the provided context. Once the last reference to the context is destroyed, the permission request is revoked internally.

See also requestSerialPortAccessRightIfNeeded(const QString &portName).

[pure virtual] bool QOhosAppContext::darkThemeActive() const

Returns whether the dark color theme is active. By default, this function returns `false`, meaning the light theme is used.

See also darkThemeActiveChanged() and setColorThemeMode().

[pure virtual] void QOhosAppContext::enableContextMenuEventOnLongPress()

Enable context menu triggering on long press touch for the entire application lifetime. Mimic Windows long touch behavior by generating a contextMenuEvent with the QContextMenuEvent::Other reason.

The function should be called at the application start, before app.exec();.

[pure virtual] double QOhosAppContext::fontSizeScale() const

Returns font size scale ratio. The value ranges from 0 to 3.2. The default value is 1. See Font Size Scale.

See also fontSizeScaleChanged(double fontSizeScale).

[static] QOhosWant QOhosAppContext::getAppLaunchWant()

Returns the Want object that was used to launch initial instance of the application's QAbility. It is recommended to use newer getAppLaunchWantInfo() method.

See also getAppLaunchWantInfo().

[static] QSharedPointer<QOhosWantInfo> QOhosAppContext::getAppLaunchWantInfo()

Returns the Want object that was used to launch initial instance of the application's QAbility.

[pure virtual] QSharedPointer<QOhosBundleInfo> QOhosAppContext::getBundleInfo() const

Returns QOhosBundleInfo object for the current application. The obtained information does not contain information about the signature, HAP module, ability, ExtensionAbility, or permission.

[pure virtual] bool QOhosAppContext::hasSerialPortAccessRight(const QString &portName) const

Checks whether the application currently has permission to access the serial port identified by portName.

Returns true if access rights for the specified serial port are currently granted, otherwise returns false.

This function performs a synchronous check of the current permission state and does not trigger any permission request. To request access rights when they are not yet granted, use requestSerialPortAccessRightIfNeeded().

For details about the underlying platform API, see Serial Port Manager.

See also requestSerialPortAccessRightIfNeeded().

[static] QOhosAppContext *QOhosAppContext::instance()

Gets QOhosAppContext global instance.

[static] bool QOhosAppContext::isNoUiChildMode()

Returns true if the current process was started as a "No UI" child.

[pure virtual] bool QOhosAppContext::isPermissionGranted(AppPermissions::Permission permission) const

Returns true is a given permission is granted, false otherwise. See Check Access Token.

[pure virtual] bool QOhosAppContext::isPermissionGranted(const QString &permissionName) const

Returns true if a permission with a given permissionName is granted, false otherwise. The permissionName is a full OHOS permission name, for example "ohos.permission.READ_PASTEBOARD". See Check Access Token.

[pure virtual] void QOhosAppContext::requestPermissionFromUserIfNeeded(AppPermissions::Permission permission)

Request a given application permission from the User. This is asynchronous call which result will be emitted by permissionRequestResponseReceived() signal.

See also permissionRequestResponseReceived().

[pure virtual] void QOhosAppContext::requestPermissionOnSettingIfNeeded(AppPermissions::Permission permission)

Request a given application permission in a Settings dialog box. This is asynchronous call which result will be emitted by permissionRequestOnSettingResponseReceived() signal.

See also permissionRequestOnSettingResponseReceived().

[pure virtual] void QOhosAppContext::requestSerialPortAccessRightIfNeeded(const QString &portName)

Requests permission for the application to access the serial port identified by portName.

This function performs an asynchronous permission request. The result of the request is delivered via the serialPortAccessRightResponseReceived() signal.

The outcome of the request (granted or denied) is reported asynchronously through serialPortAccessRightResponseReceived(). If access is granted, the signal provides a context object that must be kept alive for as long as the application requires access to the serial port.

If access is not granted, serialPortAccessRightResponseReceived() signal delivers nullptr. This may happen if:

• a provided portName cannot be mapped to a valid system serial port,
• an error occurred while requesting the access right,
• user denied the access right.

For details about the underlying platform API, see Serial Port Manager.

See also serialPortAccessRightResponseReceived().

[pure virtual] void QOhosAppContext::restartApp()

Restarts the Application using the app launch want.

The current application will be killed using SIGKILL and a new instance of the application will be launched with the application start want.

All abilities and sub-widnows created within this process will be closed.

The application will be killed ungracefully. This function won't return to the caller.

The caller must ensure, that the application has system focus when this function is called, otherwise the application will be killed but the new application won't be started. OHOS system treats some system dialogs (for example File Dialog) as separate from the application. If such dialog is open, the application loses the system focus.

If restartApp is called too frequently, the system call will be throttled to avoid errors.

Use this function, if you want to restart app with app launch want, instead of calling restartApp(const QOhosWant &requestWant) with QOhosAppContext::getAppLaunchWant() as a parameter.

[pure virtual] void QOhosAppContext::restartApp(const QOhosWant &requestWant)

Restarts the Application using the requestWant.

The current application will be killed using SIGKILL and a new instance of the application will be launched with the requestWant.

All abilities and sub-widnows created within this process will be closed.

The application will be killed ungracefully. This function won't return to the caller.

The caller must ensure, that the application has system focus when this function is called, otherwise the application will be killed but the new application won't be started. OHOS system treats some system dialogs (for example File Dialog) as separate from the application. If such dialog is open, the application loses the system focus.

If restartApp is called too frequently, the system call will be throttled to avoid errors.

To call this function with the app launch want (see QOhosAppContext::getAppLaunchWant()), use restartApp().

 QtOhosExtras::QOhosWant requestWant = QtOhosExtras::QOhosAppContext::getAppLaunchWant();
 requestWant.parameters["first_parameter"] = "first_parameter_value";
 requestWant.parameters["second_parameter"] = "second_parameter_value";
 QtOhosExtras::QOhosAppContext::restartApp(requestWant);

[pure virtual] void QOhosAppContext::setColorThemeMode(ColorThemeMode mode)

Sets the application's color theme to fixed value or enables automatic theme updates.

Calling this function with mode `FollowSystemSetting` allows the application to adjust its theme dynamically based on the system's theme configuration. The theme will be updated to match the system theme when `FollowSystemSetting` is set. See Configuration Updated. If the color theme actually changes as a result of this call, the darkThemeActiveChanged() signal will be emitted.

See also darkThemeActive() and darkThemeActiveChanged().

[static] void QOhosAppContext::startNoUiChildProcess(QString libraryName, QStringList args)

Starts "No UI" child process for a given libraryName and args. Arguments passed to the startNoUiChildProcess() function are forwarded to the child's main() function. See Child Process Manager.

 QtOhosExtras::QOhosAppContext::startNoUiChildProcess(
     "libapp.so",
     QStringList{
         "first arg",
         "second arg",
     });