Jump to content

Qt for HarmonyOS/qtohosextras doc/QtOhosExtras Namespace

From Qt Wiki
< Qt for HarmonyOS | qtohosextras doc
Revision as of 06:51, 28 January 2026 by Shawn Luo (talk | contribs) (Created page with "<!-- Source: qtohosextras.html --> <span id="qtohosextras-namespace"></span> = QtOhosExtras Namespace = The QtOhosExtras namespace provides miscellaneous functions to aid Ohos development. More... <div class="table"> {| class="wikitable alignedsummary" |- | class="memItemLeft rightAlign topAlign"| Header: | class="memItemRight bottomAlign"| <span class="preprocessor">#include </span> |- | cl...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

QtOhosExtras Namespace

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

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



Namespaces

namespace FileShare
namespace QOhosPasteboard
namespace ShareKit


Classes

class QOhosAbilityContext
class QOhosAppContext
class QOhosBundleInfo
class QOhosOnContinueContext
class QOhosOpenLinkOptions
class QOhosOperationStatus
class QOhosStartOptions
class QOhosWant
class QOhosWantInfo


Types

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


Functions

bool authorizeFilePath(QWindow *parentWindow, const QString &filePath)
QSharedPointer convertToOhosExtrasWantInfo(int wantInfo)
int convertToQpaWantInfo(QSharedPointer)
QtOhosExtras::QOhosWant convertWantFromJsonObject(const QJsonObject &jsonWant)
QJsonObject convertWantToJsonObject(const QtOhosExtras::QOhosWant &want)
QSharedPointer createOpenLinkOptions()
QSharedPointer createStartOptions()
QtOhosExtras::CloseEventRootCause getCloseEventRootCause(QCloseEvent *closeEvent)
bool moveFileToTrash(const QString &filePath)
const QMetaObject * qt_getEnumMetaObject(QtOhosExtras::QOhosAppContext::ColorThemeMode)
const QMetaObject * qt_getEnumMetaObject(QtOhosExtras::QOhosStartOptions::ProcessMode)
const QMetaObject * qt_getEnumMetaObject(QtOhosExtras::QOhosStartOptions::StartupVisibility)
const QMetaObject * qt_getEnumMetaObject(QtOhosExtras::QOhosStartOptions::WindowMode)
const QMetaObject * qt_getEnumMetaObject(QtOhosExtras::QOhosStartOptions::SupportWindowMode)
const QMetaObject * qt_getEnumMetaObject(QtOhosExtras::CloseEventRootCause)
const QMetaObject * qt_getEnumMetaObject(QtOhosExtras::WindowGeometryPersistenceHint)
const char * qt_getEnumName(QtOhosExtras::QOhosAppContext::ColorThemeMode)
const char * qt_getEnumName(QtOhosExtras::QOhosStartOptions::ProcessMode)
const char * qt_getEnumName(QtOhosExtras::QOhosStartOptions::StartupVisibility)
const char * qt_getEnumName(QtOhosExtras::QOhosStartOptions::WindowMode)
const char * qt_getEnumName(QtOhosExtras::QOhosStartOptions::SupportWindowMode)
const char * qt_getEnumName(QtOhosExtras::CloseEventRootCause)
const char * qt_getEnumName(QtOhosExtras::WindowGeometryPersistenceHint)
void requestQOhosPermissionFromUserIfNeeded(QObject *resultConsumerQtContext, QWindow *optInstanceMainWindow, const QString &permissionName, int resultConsumer)
void requestQOhosPermissionOnSettingIfNeeded(QObject *resultConsumerQtContext, QWindow *optInstanceMainWindow, int permission, int resultConsumer)
void setAbilityInstanceDestroyEnabled(QWindow *instanceWindow, bool destroyEnabled)
void setBundledAbilityAndQWindowBindingKeyForQWindow(QWindow *window, const QString &qAbilityQWindowBindingKey)
void setMainWindowGeometryPersistenceHint(QtOhosExtras::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 setWindowKeepScreenOn(QWindow *window, bool keepScreenOn)
void setWindowKeepScreenOn(QWidget *widget, bool keepScreenOn)
void setWindowPrivacyMode(QWindow *window, bool privacyModeEnabled)
QSharedPointer startAbility(const QtOhosExtras::QOhosWant &want)
QSharedPointer startAbility(const QtOhosExtras::QOhosWant &want, const QtOhosExtras::QOhosStartOptions &options)
QSharedPointer startAbilityByType(const QString &appType, const QJsonObject &wantParameters)
void startAppProcess(const QString &processId, const QtOhosExtras::QOhosWant &requestWant)
void startAppProcess(const QString &processId, const QtOhosExtras::QOhosWant &requestWant, const QtOhosExtras::QOhosStartOptions &options)
void startNewAbilityInstance(QWidget *instanceWidget)
QSharedPointer tryGetNativeWindowId(QWindow *window)
QSharedPointer tryGetOnContinueData(const QtOhosExtras::QOhosWant &want)
QSharedPointer tryGetScreenDisplayId(QScreen *screen)
int tryMapQOhosPermissionFromName(const QString &)
int tryMapQOhosPermissionToName(int)
QFlags operator|(QOhosWantFlags::enum_type f1, QOhosWantFlags::enum_type f2)
QFlags operator|(QOhosWantFlags::enum_type f1, QFlags f2)
QIncompatibleFlag operator|(QOhosWantFlags::enum_type f1, int f2)


Detailed Description

The QtOhosExtras namespace provides miscellaneous functions to aid Ohos development.


Namespaces

namespace QtOhosExtras::FileShare

The FileShare to expose file permission API.

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::QOhosPasteboard

The QOhosPasteboard class is to manage native pasteboard.

This namespace was introduced in Qt 5.12.12.

namespace QtOhosExtras::ShareKit

The ShareKit to expose Share Kit API.

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 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

class QOhosOperationStatus

The QOhosOperationStatus class provides interface to get an opertaion status. More...

class QOhosStartOptions

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

class QOhosWant

QOhosWant wraps Ohos Want class. More...

class QOhosWantInfo

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


Type Documentation

enum QtOhosExtras::CloseEventRootCause

Enumerates the close event root cause.

Constant Value Description 
QtOhosExtras::InternalClose
 
0
 Close root cause not specified or unknown. 
QtOhosExtras::AbilityClose
 
1
 Close root cause of preparing to terminate. 
QtOhosExtras::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 QtOhosExtras::QOhosWantFlag
flags QtOhosExtras::QOhosWantFlags ===

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

Constant Value Description 
QtOhosExtras::AuthReadUriPermission
 
1 &lt;&lt; 0
 Grants the permission to read the URI. 
QtOhosExtras::AuthWriteUriPermission
 
1 &lt;&lt; 1
 Grants the permission to write data to the URI. 
QtOhosExtras::InstallOnDemand
 
1 &lt;&lt; 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. It stores an OR combination of QOhosWantFlag values.

enum 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::Disabled
 
0
 Use default window's geometry. 
QtOhosExtras::Enabled
 
1
 Restore previous window's geometry (position and size when before window was closed). 
QtOhosExtras::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.

convertToOhosExtrasWantInfo

QSharedPointer<QtOhosExtras::QOhosWantInfo> QtOhosExtras::convertToOhosExtrasWantInfo(int ''wantInfo'')

int QtOhosExtras::convertToQpaWantInfo(QSharedPointer)

QtOhosExtras::QOhosWant QtOhosExtras::convertWantFromJsonObject(const QJsonObject &jsonWant)

QJsonObject QtOhosExtras::convertWantToJsonObject(const QtOhosExtras::QOhosWant &want)

createOpenLinkOptions

QSharedPointer<QtOhosExtras::QOhosOpenLinkOptions> QtOhosExtras::createOpenLinkOptions()

createStartOptions

QSharedPointer<QtOhosExtras::QOhosStartOptions> QtOhosExtras::createStartOptions()

Creates QOhosStartOptions instance.

QtOhosExtras::CloseEventRootCause QtOhosExtras::getCloseEventRootCause(QCloseEvent *closeEvent)

Converts a given closeEvent to QtOhosExtras::CloseEventRootCause.

Returns related QtOhosExtras::CloseEventRootCause 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.

const QMetaObject *QtOhosExtras::qt_getEnumMetaObject(QtOhosExtras::QOhosAppContext::ColorThemeMode)

const QMetaObject *QtOhosExtras::qt_getEnumMetaObject(QtOhosExtras::QOhosStartOptions::ProcessMode)

const QMetaObject *QtOhosExtras::qt_getEnumMetaObject(QtOhosExtras::QOhosStartOptions::StartupVisibility)

const QMetaObject *QtOhosExtras::qt_getEnumMetaObject(QtOhosExtras::QOhosStartOptions::WindowMode)

const QMetaObject *QtOhosExtras::qt_getEnumMetaObject(QtOhosExtras::QOhosStartOptions::SupportWindowMode)

const QMetaObject *QtOhosExtras::qt_getEnumMetaObject(QtOhosExtras::CloseEventRootCause)

const QMetaObject *QtOhosExtras::qt_getEnumMetaObject(QtOhosExtras::WindowGeometryPersistenceHint)

const char *QtOhosExtras::qt_getEnumName(QtOhosExtras::QOhosAppContext::ColorThemeMode)

const char *QtOhosExtras::qt_getEnumName(QtOhosExtras::QOhosStartOptions::ProcessMode)

const char *QtOhosExtras::qt_getEnumName(QtOhosExtras::QOhosStartOptions::StartupVisibility)

const char *QtOhosExtras::qt_getEnumName(QtOhosExtras::QOhosStartOptions::WindowMode)

const char *QtOhosExtras::qt_getEnumName(QtOhosExtras::QOhosStartOptions::SupportWindowMode)

const char *QtOhosExtras::qt_getEnumName(QtOhosExtras::CloseEventRootCause)

const char *QtOhosExtras::qt_getEnumName(QtOhosExtras::WindowGeometryPersistenceHint)

void QtOhosExtras::requestQOhosPermissionFromUserIfNeeded(QObject *resultConsumerQtContext, QWindow *optInstanceMainWindow, const QString &permissionName, int resultConsumer)

void QtOhosExtras::requestQOhosPermissionOnSettingIfNeeded(QObject *resultConsumerQtContext, QWindow *optInstanceMainWindow, int permission, int resultConsumer)

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 QtOhosExtras::QOhosAbilityContext::setDestroyFromSystemEnabled().

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

void QtOhosExtras::setMainWindowGeometryPersistenceHint(QtOhosExtras::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::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

startAbility

QSharedPointer<QtOhosExtras::QOhosOperationStatus> QtOhosExtras::startAbility(const QtOhosExtras::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).

startAbility

QSharedPointer<QtOhosExtras::QOhosOperationStatus> QtOhosExtras::startAbility(const QtOhosExtras::QOhosWant &''want'', const QtOhosExtras::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).

startAbilityByType

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

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

Returns true on success

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

Starts application process for a given processId and requestWant.

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

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

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.

tryGetNativeWindowId

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

tryGetOnContinueData

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

tryGetScreenDisplayId

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

int QtOhosExtras::tryMapQOhosPermissionFromName(const QString &)

int QtOhosExtras::tryMapQOhosPermissionToName(int)

Function

QFlags<QOhosWantFlags::enum_type> QtOhosExtras::operator|(QOhosWantFlags::enum_type ''f1'', QOhosWantFlags::enum_type ''f2'')

Function

QFlags<QOhosWantFlags::enum_type> QtOhosExtras::operator|(QOhosWantFlags::enum_type ''f1'', QFlags<QOhosWantFlags::enum_type> ''f2'')

QIncompatibleFlag QtOhosExtras::operator|(QOhosWantFlags::enum_type f1, int f2)

Retrieved from "https://wiki.qt.io/index.php?title=Qt_for_HarmonyOS/qtohosextras_doc/QtOhosExtras_Namespace&oldid=45370"