diff --git a/interface/src/ui/overlays/ContextOverlayInterface.h b/interface/src/ui/overlays/ContextOverlayInterface.h index e688d1c115..5d11b254fc 100644 --- a/interface/src/ui/overlays/ContextOverlayInterface.h +++ b/interface/src/ui/overlays/ContextOverlayInterface.h @@ -29,6 +29,22 @@ #include "EntityTree.h" #include "ContextOverlayLogging.h" +/**jsdoc + * The ContextOverlay API manages the "i" proof-of-provenance context overlay that appears on Marketplace items + * when a user right-clicks them. + * + * @namespace ContextOverlay + * + * @hifi-interface + * @hifi-client-entity + * @hifi-avatar + * + * @property {boolean} enabled - true if the context overlay is enabled to be displayed, false if it + * is disabled and will never be displayed. + * @property {Uuid} entityWithContextOverlay - The ID of the entity that the context overlay is currently displayed for, + * null if the context overlay is not currently displayed. + * @property {boolean} isInMarketplaceInspectionMode - Currently not used. + */ class ContextOverlayInterface : public QObject, public Dependency { Q_OBJECT @@ -44,30 +60,140 @@ class ContextOverlayInterface : public QObject, public Dependency { QUuid _contextOverlayID { UNKNOWN_ENTITY_ID }; public: ContextOverlayInterface(); + + /**jsdoc + * Gets the ID of the entity that the context overlay is currently displayed for. + * @function ContextOverlay.getCurrentEntityWithContextOverlay + * @returns {Uuid} - The ID of the entity that the context overlay is currently displayed for, null if the + * context overlay is not currently displayed. + */ Q_INVOKABLE QUuid getCurrentEntityWithContextOverlay() { return _currentEntityWithContextOverlay; } + void setCurrentEntityWithContextOverlay(const QUuid& entityID) { _currentEntityWithContextOverlay = entityID; } void setLastInspectedEntity(const QUuid& entityID) { _challengeOwnershipTimeoutTimer.stop(); } void setEnabled(bool enabled); bool getEnabled() { return _enabled; } bool getIsInMarketplaceInspectionMode() { return _isInMarketplaceInspectionMode; } void setIsInMarketplaceInspectionMode(bool mode) { _isInMarketplaceInspectionMode = mode; } + + /**jsdoc + * Initiates a check on an avatar entity belongs to the user wearing it. The result is returned via + * {@link WalletScriptingInterface.ownershipVerificationSuccess} or + * {@link WalletScriptingInterface.ownershipVerificationFailed}. + *

Warning: Neither of these signals are triggered if the entity is not an avatar entity or is not + * certified.

+ * @function ContextOverlay.requestOwnershipVerification + * @param {Uuid} entityID - The ID of the entity to check. + */ Q_INVOKABLE void requestOwnershipVerification(const QUuid& entityID); + EntityPropertyFlags getEntityPropertyFlags() { return _entityPropertyFlags; } signals: + /**jsdoc + * Triggered when the user clicks on the context overlay. + * @function ContextOverlay.contextOverlayClicked + * @param {Uuid} id - The ID of the entity that the context overlay is for. + * @returns {Signal} + * @example Report when a context overlay is clicked. + * ContextOverlay.contextOverlayClicked.connect(function (id) { + * print("Context overlay clicked for:", id); + * }); + */ void contextOverlayClicked(const QUuid& currentEntityWithContextOverlay); public slots: + + /**jsdoc + * @function ContextOverlay.clickDownOnEntity + * @param {Uuid} id - Entity ID. + * @param {PointerEvent} event - Pointer event. + * @deprecated This method is deprecated and will be removed. + */ + // FIXME: Method shouldn't be in the API. void clickDownOnEntity(const EntityItemID& entityItemID, const PointerEvent& event); + + /**jsdoc + * @function ContextOverlay.mouseReleaseOnEntity + * @param {Uuid} id - Entity ID. + * @param {PointerEvent} event - Pointer event. + * @deprecated This method is deprecated and will be removed. + */ + // FIXME: Method shouldn't be in the API. void mouseReleaseOnEntity(const EntityItemID& entityItemID, const PointerEvent& event); + /**jsdoc + * Displays or deletes the context overlay as appropriate for the target entity and a pointer event: the context overlay + * must be enabled and the pointer event must be a right-click; if so, then any current context overlay is deleted, and if + * the target entity should have a context overlay then it is displayed. + * @function ContextOverlay.createOrDestroyContextOverlay + * @param {Uuid} entityID - The target entity. + * @param {PointerEvent} pointerEvent - The pointer event. + * @returns {boolean} - true if the context overlay was deleted or displayed on the specified entity, + * false if no action was taken. + */ bool createOrDestroyContextOverlay(const EntityItemID& entityItemID, const PointerEvent& event); + + /**jsdoc + * Deletes the context overlay and removes the entity highlight, if shown. + * @function ContextOverlay.destroyContextOverlay + * @param {Uuid} entityID - The ID of the entity. + * @param {PointerEvent} [event] - Not used. + * @returns {boolean} - true if the context overlay was deleted, false if it wasn't (e.g., it + * wasn't displayed). + */ bool destroyContextOverlay(const EntityItemID& entityItemID, const PointerEvent& event); bool destroyContextOverlay(const EntityItemID& entityItemID); + + /**jsdoc + * @function ContextOverlay.contextOverlays_hoverEnterOverlay + * @param {Uuid} id - Overlay ID. + * @param {PointerEvent} event - Pointer event. + * @deprecated This method is deprecated and will be removed. + */ + // FIXME: Method shouldn't be in the API. void contextOverlays_hoverEnterOverlay(const QUuid& id, const PointerEvent& event); + + /**jsdoc + * @function ContextOverlay.contextOverlays_hoverLeaveOverlay + * @param {Uuid} id - Overlay ID. + * @param {PointerEvent} event - Pointer event. + * @deprecated This method is deprecated and will be removed. + */ + // FIXME: Method shouldn't be in the API. void contextOverlays_hoverLeaveOverlay(const QUuid& id, const PointerEvent& event); + + /**jsdoc + * @function ContextOverlay.contextOverlays_hoverEnterEntity + * @param {Uuid} id - Entity ID. + * @param {PointerEvent} event - Pointer event. + * @deprecated This method is deprecated and will be removed. + */ + // FIXME: Method shouldn't be in the API. void contextOverlays_hoverEnterEntity(const EntityItemID& entityID, const PointerEvent& event); + + /**jsdoc + * @function ContextOverlay.contextOverlays_hoverLeaveEntity + * @param {Uuid} id - Entity ID. + * @param {PointerEvent} event - Pointer event. + * @deprecated This method is deprecated and will be removed. + */ + // FIXME: Method shouldn't be in the API. void contextOverlays_hoverLeaveEntity(const EntityItemID& entityID, const PointerEvent& event); + + /**jsdoc + * Checks with a context overlay should be displayed for an entity — in particular, whether the item has a non-empty + * certificate ID. + * @function ContextOverlay.contextOverlayFilterPassed + * @param {Uuid} entityID - The ID of the entity to check. + * @returns {boolean} - true if the context overlay should be shown for the entity, false if it + * shouldn't. + * @example Report whether the context overlay should be displayed for entities clicked. + * Entities.clickDownOnEntity.connect(function (id, event) { + * print("Item clicked:", id); + * print("Should display context overlay:", ContextOverlay.contextOverlayFilterPassed(id)); + * }); + */ bool contextOverlayFilterPassed(const EntityItemID& entityItemID); private slots: