diff --git a/interface/src/AvatarBookmarks.cpp b/interface/src/AvatarBookmarks.cpp index 54c67daab8..d9ac522dc8 100644 --- a/interface/src/AvatarBookmarks.cpp +++ b/interface/src/AvatarBookmarks.cpp @@ -179,6 +179,18 @@ void AvatarBookmarks::updateAvatarEntities(const QVariantList &avatarEntities) { } } +/**jsdoc + * Details of an avatar bookmark. + * @typedef {object} AvatarBookmarks.BookmarkData + * @property {number} version - The version of the bookmark data format. + * @property {string} avatarUrl - The URL of the avatar model. + * @property {number} avatarScale - The target scale of the avatar. + * @property {Array>} [avatarEntites] - The avatar entities included with the + * bookmark. + * @property {MyAvatar.AttachmentData[]} [attachments] - The attachments included with the bookmark. + *

Deprecated: Use avatar entities instead. + */ + void AvatarBookmarks::loadBookmark(const QString& bookmarkName) { if (QThread::currentThread() != thread()) { BLOCKING_INVOKE_METHOD(this, "loadBookmark", Q_ARG(QString, bookmarkName)); diff --git a/interface/src/AvatarBookmarks.h b/interface/src/AvatarBookmarks.h index df75fec865..646d06456a 100644 --- a/interface/src/AvatarBookmarks.h +++ b/interface/src/AvatarBookmarks.h @@ -16,7 +16,9 @@ #include "Bookmarks.h" /**jsdoc - * This API helps manage adding and deleting avatar bookmarks. + * The AvatarBookmarks API provides facilities for working with avatar bookmarks ("favorites" in the Avatar app). + * An avatar bookmark associates a name with an avatar model, scale, and avatar entities (wearables). + * * @namespace AvatarBookmarks * * @hifi-interface @@ -32,41 +34,100 @@ class AvatarBookmarks: public Bookmarks, public Dependency { public: AvatarBookmarks(); void setupMenus(Menu* menubar, MenuWrapper* menu) override {}; + + /**jsdoc + * Gets the details of an avatar bookmark. + * @function AvatarBookmarks.getBookmark + * @param {string} bookmarkName - The name of the avatar bookmark (case sensitive). + * @returns {AvatarBookmarks.BookmarkData|{}} The bookmark data if the bookmark exists, {} if it doesn't. + */ Q_INVOKABLE QVariantMap getBookmark(const QString& bookmarkName); public slots: /**jsdoc - * Add the current Avatar to your avatar bookmarks. - * @function AvatarBookmarks.addBookMark + * Adds a new (or updates an existing) avatar bookmark with your current avatar model, scale, and avatar entities. + * @function AvatarBookmarks.addBookmark + * @param {string} bookmarkName - The name of the avatar bookmark (case sensitive). + * @example Add a new avatar bookmark and report the bookmark data. + * var bookmarkName = "New Bookmark"; + * AvatarBookmarks.addBookmark(bookmarkName); + * var bookmarkData = AvatarBookmarks.getBookmark(bookmarkName); + * print("Bookmark data: " + JSON.stringify(bookmarkData)); */ void addBookmark(const QString& bookmarkName); + + /**jsdoc + * Updates an existing bookmark with your current avatar model, scale, and wearables. No action is taken if the bookmark + * doesn't exist. + * @function AvatarBookmarks.saveBookmark + * @param {string} bookmarkName - The name of the avatar bookmark (case sensitive). + */ void saveBookmark(const QString& bookmarkName); + + /**jsdoc + * Loads an avatar bookmark, setting your avatar model, scale, and avatar entities (or attachments if an old bookmark) to + * those in the bookmark. + * @function AvatarBookmarks.loadBookmark + * @param {string} bookmarkName - The name of the avatar bookmark to load (case sensitive). + */ void loadBookmark(const QString& bookmarkName); + + /**jsdoc + * Deletes an avatar bookmark. + * @function AvatarBookmarks.removeBookmark + * @param {string} bookmarkName - The name of the avatar bookmark to delete (case sensitive). + */ void removeBookmark(const QString& bookmarkName); + + /**jsdoc + * Updates the avatar entities and their properties. Current avatar entities not included in the list provided are deleted. + * @function AvatarBookmarks.updateAvatarEntities + * @param {MyAvatar.AvatarEntityData[]} avatarEntities - The avatar entity IDs and properties. + * @deprecated This function is deprecated and will be removed. Use the {@link MyAvatar} API instead. + */ void updateAvatarEntities(const QVariantList& avatarEntities); + + /**jsdoc + * Gets the details of all avatar bookmarks. + * @function AvatarBookmarks.getBookmarks + * @returns {Object} The current avatar bookmarks in an object where the keys are the + * bookmark names and the values are the bookmark details. + * @example List the names and URLs of all the avatar bookmarks. + * var bookmarks = AvatarBookmarks.getBookmarks(); + * print("Avatar bookmarks:"); + * for (var key in bookmarks) { + * print("- " + key + " " + bookmarks[key].avatarUrl); + * }; + */ QVariantMap getBookmarks() { return _bookmarks; } signals: /**jsdoc - * This function gets triggered after avatar loaded from bookmark + * Triggered when an avatar bookmark is loaded, setting your avatar model, scale, and avatar entities (or attachments if an + * old bookmark) to those in the bookmark. * @function AvatarBookmarks.bookmarkLoaded - * @param {string} bookmarkName + * @param {string} bookmarkName - The name of the avatar bookmark loaded. * @returns {Signal} */ void bookmarkLoaded(const QString& bookmarkName); /**jsdoc - * This function gets triggered after avatar bookmark deleted + * Triggered when an avatar bookmark is deleted. * @function AvatarBookmarks.bookmarkDeleted - * @param {string} bookmarkName + * @param {string} bookmarkName - The name of the avatar bookmark deleted. * @returns {Signal} + * @example Report when a bookmark is deleted. + * AvatarBookmarks.bookmarkDeleted.connect(function (bookmarkName) { + * print("Bookmark deleted: " + bookmarkName); + * }); */ void bookmarkDeleted(const QString& bookmarkName); /**jsdoc - * This function gets triggered after avatar bookmark added + * Triggered when a new avatar bookmark is added or an existing avatar bookmark is updated, using + * {@link AvatarBookmarks.addBookmark|addBookmark}. * @function AvatarBookmarks.bookmarkAdded - * @param {string} bookmarkName + * @param {string} bookmarkName - The name of the avatar bookmark added or updated. * @returns {Signal} */ void bookmarkAdded(const QString& bookmarkName); @@ -77,6 +138,11 @@ protected: QVariantMap getAvatarDataToBookmark(); protected slots: + /**jsdoc + * Performs no action. + * @function AvatarBookmarks.deleteBookmark + * @deprecated This function is deprecated and will be removed. + */ void deleteBookmark() override; private: diff --git a/interface/src/avatar/AvatarManager.h b/interface/src/avatar/AvatarManager.h index ce23a80309..30f68297b4 100644 --- a/interface/src/avatar/AvatarManager.h +++ b/interface/src/avatar/AvatarManager.h @@ -238,7 +238,7 @@ public: * @function AvatarManager.getPalData * @param {string[]} [avatarIDs=[]] - The IDs of the avatars to get the PAL data for. If empty, then PAL data is obtained * for all avatars. - * @returns {object<"data", AvatarManager.PalData[]>} An array of objects, each object being the PAL data for an avatar. + * @returns {Object<"data", AvatarManager.PalData[]>} An array of objects, each object being the PAL data for an avatar. * @example Report the PAL data for an avatar nearby. * var palData = AvatarManager.getPalData(); * print("PAL data for one avatar: " + JSON.stringify(palData.data[0])); diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index d092122863..62605a5bee 100644 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -1369,9 +1369,9 @@ public: bool hasDriveInput() const; /**jsdoc - * Gets the list of avatar entities and their properties. + * Gets the current avatar entity IDs and their properties. * @function MyAvatar.getAvatarEntitiesVariant - * @returns {MyAvatar.AvatarEntityData[]} The list of avatar entities and their properties. + * @returns {MyAvatar.AvatarEntityData[]} The current avatar entity IDs and their properties. */ Q_INVOKABLE QVariantList getAvatarEntitiesVariant(); diff --git a/libraries/avatars/src/AvatarData.cpp b/libraries/avatars/src/AvatarData.cpp index a2dde3d651..22b070464d 100755 --- a/libraries/avatars/src/AvatarData.cpp +++ b/libraries/avatars/src/AvatarData.cpp @@ -2861,7 +2861,7 @@ glm::vec3 AvatarData::getAbsoluteJointTranslationInObjectFrame(int index) const * Information on an attachment worn by the avatar. * @typedef {object} AttachmentData * @property {string} modelUrl - The URL of the model file. Models can be FBX or OBJ format. - * @property {string} jointName - The offset to apply to the model relative to the joint position. + * @property {string} jointName - The name of the joint that the attachment is parented to. * @property {Vec3} translation - The offset from the joint that the attachment is positioned at. * @property {Vec3} rotation - The rotation applied to the model relative to the joint orientation. * @property {number} scale - The scale applied to the attachment model. diff --git a/libraries/avatars/src/AvatarData.h b/libraries/avatars/src/AvatarData.h index 498f39cdf9..3c8e2d6fcc 100755 --- a/libraries/avatars/src/AvatarData.h +++ b/libraries/avatars/src/AvatarData.h @@ -1292,7 +1292,7 @@ public: * jointName: "Head", * translation: {"x": 0, "y": 0.25, "z": 0}, * rotation: {"x": 0, "y": 0, "z": 0, "w": 1}, - * scale: 1, + * scale: 0.01, * isSoft: false * }; *