diff --git a/interface/src/scripting/DesktopScriptingInterface.cpp b/interface/src/scripting/DesktopScriptingInterface.cpp index ae4af48cd6..f78f7853ca 100644 --- a/interface/src/scripting/DesktopScriptingInterface.cpp +++ b/interface/src/scripting/DesktopScriptingInterface.cpp @@ -30,21 +30,6 @@ * @property {InteractiveWindow.DockArea} LEFT - Dock to the left edge of the Interface window. * @property {InteractiveWindow.DockArea} RIGHT - Dock to the right edge of the Interface window. */ -/**jsdoc - *

A docking location of an InteractiveWindow.

- * - * - * - * - * - * - * - * - * - * - *
ValueNameDescription
0TOPDock to the top edge of the Interface window.
1BOTTOMDock to the bottom edge of the Interface window.
2LEFTDock to the left edge of the Interface window.
3RIGHTDock to the right edge of the Interface window.
- * @typedef {number} InteractiveWindow.DockArea - */ static const QVariantMap DOCK_AREA { { "TOP", DockArea::TOP }, { "BOTTOM", DockArea::BOTTOM }, @@ -53,13 +38,17 @@ static const QVariantMap DOCK_AREA { }; /**jsdoc - * The possible "relative position anchors" of an InteractiveWindow. Used when defining the `relativePosition` property of an `InteractiveWindow`. + * The possible relative position anchors of an InteractiveWindow relative to the Interface window. * @typedef {object} InteractiveWindow.RelativePositionAnchors - * @property {InteractiveWindow.RelativePositionAnchor} NO_ANCHOR - Specifies that the position of the `InteractiveWindow` will not be relative to any part of the Interface window. - * @property {InteractiveWindow.RelativePositionAnchor} TOP_LEFT - Specifies that the `relativePosition` of the `InteractiveWindow` will be offset from the top left of the Interface window. - * @property {InteractiveWindow.RelativePositionAnchor} TOP_RIGHT - Specifies that the `relativePosition` of the `InteractiveWindow` will be offset from the top right of the Interface window. - * @property {InteractiveWindow.RelativePositionAnchor} BOTTOM_RIGHT - Specifies that the `relativePosition` of the `InteractiveWindow` will be offset from the bottom right of the Interface window. - * @property {InteractiveWindow.RelativePositionAnchor} BOTTOM_LEFT - Specifies that the `relativePosition` of the `InteractiveWindow` will be offset from the bottom left of the Interface window. + * @property {InteractiveWindow.RelativePositionAnchor} NO_ANCHOR - Position is not relative to any part of the Interface + * window. + * @property {InteractiveWindow.RelativePositionAnchor} TOP_LEFT - Position is offset from the top left of the Interface window. + * @property {InteractiveWindow.RelativePositionAnchor} TOP_RIGHT - Position is offset from the top right of the Interface + * window. + * @property {InteractiveWindow.RelativePositionAnchor} BOTTOM_RIGHT - Position offset from the bottom right of the Interface + * window. + * @property {InteractiveWindow.RelativePositionAnchor} BOTTOM_LEFT - Position is offset from the bottom left of the Interface + * window. */ static const QVariantMap RELATIVE_POSITION_ANCHOR { { "NO_ANCHOR", RelativePositionAnchor::NO_ANCHOR }, @@ -89,21 +78,6 @@ int DesktopScriptingInterface::getHeight() { * @property {InteractiveWindow.PresentationMode} NATIVE - The window is displayed separately from the Interface window, as its * own separate window. */ -/**jsdoc - *

A display mode for an InteractiveWindow.

- * - * - * - * - * - * - * - * - *
ValueNameDescription
0VIRTUALThe window is displayed inside Interface: in the desktop window in - * desktop mode or on the HUD surface in HMD mode.
1NATIVEThe window is displayed separately from the Interface window, as its - * own separate window.
- * @typedef {number} InteractiveWindow.PresentationMode - */ QVariantMap DesktopScriptingInterface::getPresentationMode() { static QVariantMap presentationModes { { "VIRTUAL", Virtual }, diff --git a/interface/src/scripting/DesktopScriptingInterface.h b/interface/src/scripting/DesktopScriptingInterface.h index e75bd571e8..e57d7a6805 100644 --- a/interface/src/scripting/DesktopScriptingInterface.h +++ b/interface/src/scripting/DesktopScriptingInterface.h @@ -42,8 +42,8 @@ * @property {InteractiveWindow.DockAreas} DockArea - The possible docking locations of an {@link InteractiveWindow}: top, * bottom, left, or right of the Interface window. * Read-only. - * @property {InteractiveWindow.RelativePositionAnchors} RelativePositionAnchor - The possible "relative position anchors" for an {@link InteractiveWindow}: top left, - * top right, bottom right, or bottom left of the Interface window. + * @property {InteractiveWindow.RelativePositionAnchors} RelativePositionAnchor - The possible relative position anchors for an + * {@link InteractiveWindow}: none, top left, top right, bottom right, or bottom left of the Interface window. * Read-only. */ class DesktopScriptingInterface : public QObject, public Dependency { @@ -84,7 +84,7 @@ public: * @param {string} url - The QML file that specifies the window content. The QML file can use a WebView * control (defined by "WebView.qml" included in the Interface install) to embed an HTML web page (complete with * EventBridge object). - * @param {InteractiveWindow.Properties} [properties] - Initial window properties. + * @param {InteractiveWindow.WindowProperties} [properties] - Initial window properties. * @returns {InteractiveWindow} A new window object. * @example Open a dialog in its own window separate from Interface. * var nativeWindow = Desktop.createWindow(Script.resourcesPath() + 'qml/OverlayWindowTest.qml', { diff --git a/interface/src/ui/InteractiveWindow.cpp b/interface/src/ui/InteractiveWindow.cpp index 6cc26e2409..2acac2c529 100644 --- a/interface/src/ui/InteractiveWindow.cpp +++ b/interface/src/ui/InteractiveWindow.cpp @@ -129,8 +129,8 @@ void InteractiveWindow::emitMainWindowResizeEvent() { } /**jsdoc - * A set of properties used when creating an InteractiveWindow. - * @typedef {object} InteractiveWindow.Properties + * Property values used when creating an InteractiveWindow. + * @typedef {object} InteractiveWindow.WindowProperties * @property {string} [title="InteractiveWindow] - The title of the window. * @property {Vec2} [position] - The initial position of the window, in pixels. * @property {Vec2} [size] - The initial size of the window, in pixels @@ -142,13 +142,36 @@ void InteractiveWindow::emitMainWindowResizeEvent() { * @property {InteractiveWindow.PresentationWindowInfo} [presentationWindowInfo] - Controls how a NATIVE window is * displayed. If used, the window is docked to the specified edge of the Interface window, otherwise the window is * displayed as its own separate window. - * @property {InteractiveWindow.AdditionalFlags} [additionalFlags=0] - Window behavior flags in addition to "native window flags" (minimize/maximize/close), - * set at window creation. Possible flag values are provided as {@link Desktop|Desktop.ALWAYS_ON_TOP} and {@link Desktop|Desktop.CLOSE_BUTTON_HIDES}. - * Additional flag values can be found on Qt's website at https://doc.qt.io/qt-5/qt.html#WindowType-enum. - * @property {InteractiveWindow.OverrideFlags} [overrideFlags=0] - Window behavior flags instead of the default window flags. - * Set at window creation. Possible flag values are provided as {@link Desktop|Desktop.ALWAYS_ON_TOP} and {@link Desktop|Desktop.CLOSE_BUTTON_HIDES}. - * Additional flag values can be found on Qt's website at https://doc.qt.io/qt-5/qt.html#WindowType-enum. + * @property {InteractiveWindow.Flags} [additionalFlags=0] - Customizes window behavior. + * @property {InteractiveWindow.OverrideFlags} [overrideFlags=0] - Customizes window controls. + + * @property {InteractiveWindow.RelativePositionAnchor} [relativePositionAnchor] - he anchor for the + * relativePosition, if used. + * @property {Vec2} [relativePosition] - The position of the window, relative to the relativePositionAnchor, in + * pixels. Excludes the window frame. + * @property {boolean} [isFullScreenWindow] - true to make the window full screen. */ +/**jsdoc + *

A set of flags customizing InteractiveWindow controls. The value is constructed by using the | + * (bitwise OR) operator on the individual flag values..

+ * + * + * + * + * + * + * + *
ValueNameDescription
0x00000001WindowDisplays the window as a window rather than a dialog.
0x00001000WindowTitleHintAdds a title bar. + *
0x00002000WindowSystemMenuHintAdds a window system menu. + *
0x00004000WindowMinimizeButtonHintAdds a minimize button. + *
0x00008000WindowMaximizeButtonHintAdds a maximize button. + *
0x00040000WindowStaysOnTopHintThe window stays on top of other windows. + * Not used on Windows. + *
0x08000000WindowCloseButtonHintAdds a close button. + *
+ * @typedef {number} InteractiveWindow.OverrideFlags + */ +// OverrideFlags is per InteractiveWindow.qml. InteractiveWindow::InteractiveWindow(const QString& sourceUrl, const QVariantMap& properties, bool restricted) { InteractiveWindowPresentationMode presentationMode = InteractiveWindowPresentationMode::Native; diff --git a/interface/src/ui/InteractiveWindow.h b/interface/src/ui/InteractiveWindow.h index 56060f5c27..3d134e119f 100644 --- a/interface/src/ui/InteractiveWindow.h +++ b/interface/src/ui/InteractiveWindow.h @@ -76,12 +76,42 @@ namespace InteractiveWindowEnums { }; Q_ENUM_NS(InteractiveWindowFlags); + /**jsdoc + *

A display mode for an InteractiveWindow.

+ * + * + * + * + * + * + * + * + *
ValueNameDescription
0VIRTUALThe window is displayed inside Interface: in the desktop window in + * desktop mode or on the HUD surface in HMD mode.
1NATIVEThe window is displayed separately from the Interface window, as its + * own separate window.
+ * @typedef {number} InteractiveWindow.PresentationMode + */ enum InteractiveWindowPresentationMode { Virtual, Native }; Q_ENUM_NS(InteractiveWindowPresentationMode); + /**jsdoc + *

A docking location of an InteractiveWindow.

+ * + * + * + * + * + * + * + * + * + * + *
ValueNameDescription
0TOPDock to the top edge of the Interface window.
1BOTTOMDock to the bottom edge of the Interface window.
2LEFTDock to the left edge of the Interface window.
3RIGHTDock to the right edge of the Interface window.
+ * @typedef {number} InteractiveWindow.DockArea + */ enum DockArea { TOP, BOTTOM, @@ -90,6 +120,24 @@ namespace InteractiveWindowEnums { }; Q_ENUM_NS(DockArea); + /**jsdoc + *

The anchor for a relative position of an InteractiveWindow.

+ * + * + * + * + * + * + * + * + * + * + * + *
ValueNameDescription
0NO_ANCHORPosition is not relative to any part of the Interface window.
1TOP_LEFTPosition is offset from the top left of the Interface window.
2TOP_RIGHTPosition is offset from the top right of the Interface window.
3BOTTOM_RIGHTPosition offset from the bottom right of the Interface + * window.
4BOTTOM_LEFFTPosition is offset from the bottom left of the Interface + * window.
+ * @typedef {number} InteractiveWindow.RelativePositionAnchor + */ enum RelativePositionAnchor { NO_ANCHOR, TOP_LEFT, @@ -116,7 +164,11 @@ using namespace InteractiveWindowEnums; * @hifi-avatar * * @property {string} title - The title of the window. - * @property {Vec2} position - The position of the window, in pixels. + * @property {Vec2} position - The absolute position of the window, in pixels. + * @property {InteractiveWindow.RelativePositionAnchor} relativePositionAnchor - The anchor for the + * relativePosition, if used. + * @property {Vec2} relativePosition - The position of the window, relative to the relativePositionAnchor, in + * pixels. Excludes the window frame. * @property {Vec2} size - The size of the window, in pixels. * @property {boolean} visible - true if the window is visible, false if it isn't. * @property {InteractiveWindow.PresentationMode} presentationMode - The presentation mode of the window: