From a04da70f16fc9f75df236e5d7cced8c14fd74b39 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Fri, 19 Jul 2019 08:36:45 +1200 Subject: [PATCH] AvatarBookmarks JSDoc --- interface/src/AvatarBookmarks.cpp | 12 +++++ interface/src/AvatarBookmarks.h | 84 +++++++++++++++++++++++++++---- 2 files changed, 87 insertions(+), 9 deletions(-) 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..a8f10b1756 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 lets your create and use 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: