From: Alexander\ Kovalenko Date: Wed, 25 Oct 2017 15:05:50 +0000 (+0300) Subject: TizenRefApp-9676 [Gallery] Add doxygen documentation to Model public classes X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=1bc5b76c5526a22f84baeba6f78b64d3d6b6c5f3;p=profile%2Fwearable%2Fapps%2Fnative%2Fgallery.git TizenRefApp-9676 [Gallery] Add doxygen documentation to Model public classes Change-Id: If78d316799343d555d88e85dcb0116f8b80b5cfc --- diff --git a/gallery/model/CustomMediaAlbum.h b/gallery/model/CustomMediaAlbum.h index 08ff4b3..50c175e 100644 --- a/gallery/model/CustomMediaAlbum.h +++ b/gallery/model/CustomMediaAlbum.h @@ -23,24 +23,66 @@ namespace gallery { UCL_DECLARE_REF_ALIASES(CustomMediaAlbum); + /** + * @brief Implements IMediaAlbum + */ class CustomMediaAlbum final : public IMediaAlbum { public: + + /** + * @brief Contsructor + */ CustomMediaAlbum(); + + /** + * @brief Desructor + */ virtual ~CustomMediaAlbum(); + /** + * @brief Adds media item to album + * @param[in] item Shared reference to MediaItem object + */ void addItem(MediaItemSRef item); + /** + * @brief Gets album contents + * @return Vector of media items + */ const MediaItems &getItems() const; // IMediaAlbum // + /** + * @brief Adds change handler + * @param[in] handler Change handler + */ virtual void addChangeHandler(NotiHandler handler) final override; + + /** + * @brief Deletes change handler + * @param[in] handler Change handler + */ virtual void delChangeHandler( NotiHandler::CDRef handler) final override; + /** + * @brief Calls a provided callback function once for each MediaAlbum entry + * @param[in] cb Callback function + * @return RES_OK on success, otherwise an error code on failure + */ virtual ucl::Result forEachMedia(EachCb cb) const final override; + + /** + * @brief Gets number of items in album + * @param[out] count Media count + * @return RES_OK on success, otherwise an error code on failure + */ virtual ucl::Result getMediaCount(int &count) const final override; + /** + * @brief Defragments media album contents + */ virtual void defragment() final override; private: diff --git a/gallery/model/Gallery.h b/gallery/model/Gallery.h index e17b1f5..a82bff6 100644 --- a/gallery/model/Gallery.h +++ b/gallery/model/Gallery.h @@ -23,11 +23,27 @@ namespace gallery { UCL_DECLARE_REF_ALIASES(Gallery); + /** + * @brief Represents application main model class + */ class Gallery final : public ucl::NonCopyable { public: + + /** + * @brief Creates new instance of Gallery + * @return Shared reference to Gallery object + */ static GallerySRef newInstance(); + + /** + * @brief Destructor + */ ~Gallery(); + /** + * @brief Gets media album + * @return Shared reference to media album object + */ IMediaAlbumSRef getAlbum(); private: diff --git a/gallery/model/IJob.h b/gallery/model/IJob.h index 2894d52..58f9c59 100644 --- a/gallery/model/IJob.h +++ b/gallery/model/IJob.h @@ -23,10 +23,28 @@ namespace gallery { UCL_DECLARE_REF_ALIASES(IJob); + /** + * @brief Represents abstract job + */ class IJob : protected ucl::NonCopyable { public: + + /** + * @brief Gets result + * @return Result. @see ucl::Result + */ virtual ucl::Result getResult() const = 0; + + /** + * @brief Check if job can be canceled + * @return true if cancelable, false if not cancelable + */ virtual bool isCancelable() const = 0; + + /** + * @brief Cancels job + * @return RES_OK on success, otherwise an error code + */ virtual ucl::Result cancel() = 0; }; } diff --git a/gallery/model/IMediaAlbum.h b/gallery/model/IMediaAlbum.h index a0b2c4c..a8b6ee3 100644 --- a/gallery/model/IMediaAlbum.h +++ b/gallery/model/IMediaAlbum.h @@ -23,22 +23,56 @@ namespace gallery { UCL_DECLARE_REF_ALIASES(IMediaAlbum); + /** + * @brief Represents media album interface + */ class IMediaAlbum : protected ucl::NonCopyable { public: + /** + * @brief Callback for each item in album type + */ using EachCb = ucl::Delegate; public: + + /** + * @brief Adds change handler + * @param[in] handler Change handler + */ virtual void addChangeHandler(NotiHandler handler) = 0; + + /** + * @brief Removes change handler + * @param[in] handler Change handler + */ virtual void delChangeHandler(NotiHandler::CDRef handler) = 0; + /** + * @brief Calls a provided callback function once for each MediaAlbum entry + * @param[in] cb Callback function + * @return RES_OK on success, otherwise an error code on failure + */ virtual ucl::Result forEachMedia(EachCb cb) const = 0; + + /** + * @brief Gets number of items in album + * @param[out] count Media count + * @return RES_OK on success, otherwise an error code on failure + */ virtual ucl::Result getMediaCount(int &count) const = 0; + /** + * @brief Defragments media album contents + */ virtual void defragment() = 0; }; // Non-member functions // + /** + * @brief Checks if album is empty + * @return true if album is empty, false if album is filled + */ bool isEmpty(const IMediaAlbum &album); } diff --git a/gallery/model/MediaItem.h b/gallery/model/MediaItem.h index 25cf4a8..a0e5cb8 100644 --- a/gallery/model/MediaItem.h +++ b/gallery/model/MediaItem.h @@ -32,68 +32,203 @@ namespace gallery { using MediaItems = std::vector; + /** + * @brief Represents media item + */ class MediaItem : protected ucl::NonCopyable { public: + /** + * @brief Callback for thumbnail creation type + */ using ThumbnailPathGetCb = ucl::WeakDelegate; + /** + * @brief Provides removal option + */ class Remover; + + /** + * @brief Builder for the job that removes file + */ class RemoverBuilder final { public: + /** + * @brief Stages items for delition + * @param[in] items Vector of items + * @return RemoverBuilder object + */ RemoverBuilder &setItems(MediaItems items); + + /** + * @brief Creates job + * @param[in] onComplete Completion handler + * @return Shared reference to IJob + */ IJobSRef build(const NotiHandler &onComplete) const; private: ucl::SharedRef m_items; }; + /** + * @brief Provides saving option + */ class Saver; + + /** + * @brief Builder for the job that saves file on the device + */ class SaverBuilder final { public: + /** + * @brief Sets item to save + * @param[in] item Shared reference to MediaItem + * @return SaverBuilder object + */ SaverBuilder &setItem(const MediaItemSRef &item); + + /** + * @brief Creates job + * @param[in] onComplete Completion handler + * @return Shared reference to IJob + */ IJobSRef build(const NotiHandler &onComplete) const; private: MediaItemSRef m_item; }; + /** + * @brief Enumeration of possible flags + */ enum { - FLAG_THUMBNAIL = 1, - FLAG_REMOVE = 2, - FLAG_SAVE = 4, - FLAG_RESOLUTION = 8, + FLAG_THUMBNAIL = 1, /**< Thumbnail*/ + FLAG_REMOVE = 2, /**< Staged for deletion*/ + FLAG_SAVE = 4, /**< Save*/ + FLAG_RESOLUTION = 8, /**< Resolution*/ FLAGS_FROM_MEDIA_DB = (FLAG_THUMBNAIL | FLAG_REMOVE | - FLAG_RESOLUTION), - FLAGS_SIMPLE_FILE = (FLAG_SAVE) + FLAG_RESOLUTION), /**< File from media DB*/ + FLAGS_SIMPLE_FILE = (FLAG_SAVE) /**< Simple file*/ }; public: + + /** + * @brief Creates new instance of MediaItem + * @param[in] media Media info + * @return Shared reference to MediaItem object + */ static MediaItemSRef newInstance(media_info_h media); + + /** + * @brief Creates new instance of MediaItem + * @param[in] filePath Path to file + * @return Shared reference to MediaItem object + */ static MediaItemSRef newInstance(std::string filePath); public: + /** + * @brief Checks if MediaItem is valid + * @return true if valid, false if invalid + */ bool isValid() const; + + /** + * @brief Gets MediaItem flags + * @return Flags + */ int getFlags() const; + + /** + * @brief Gets type + * @return Media item type + */ MediaType getType() const; + /** + * @brief Gets ID + * @return Media item ID + */ const std::string &getId() const; + /** + * @brief Gets resolution + * @param[out] x X axis size + * @param[out] y Y axis size + * @return RES_OK on success, otherwise an error code on failure + */ ucl::Result getResolution(int &x, int &y) const; + /** + * @brief Gets file path + * @return File path + */ const std::string &getFilePath() const; + /** + * @brief Gets path to thumbnail + * @param[in] cb Thumbnail creation callback + * @return RES_OK on synchronous callback, RES_FALSE on asynchronous, + * otherwise an error code on failure + */ ucl::Result getThumbnailPath(const ThumbnailPathGetCb &cb) const; + + /** + * @brief Cancels getting path to thumbnail + * @details Cancels callback and thumbnail generation + * @param[in] cb Callback + * @return RES_OK on synchronous callback, RES_FALSE on asynchronous, + * otherwise an error code on failure + */ void cancelThumbnailPathGet(const ThumbnailPathGetCb &cb) const; + /** + * @brief Removes media items file + * @return RES_OK on success, otherwise an error code on failure + */ ucl::Result removeFile(); + + /** + * @brief Saves media items file locally + * @return RES_OK on success, otherwise an error code on failure + */ ucl::Result saveToDevice(); protected: friend class ucl::ReffedObj; + + /** + * @brief Constructor + * @param[in] flags Flags + * @param[in] type Media type + */ MediaItem(int flags, MediaType type); + + /** + * @brief Destructor + */ virtual ~MediaItem(); + /** + * @brief Prepares media image data + * @param[in] media Media info + * @return RES_OK on success, otherwise an error code on failure + */ ucl::Result prepare(media_info_h media); + + /** + * @brief Prepares media image data + * @param[in] media Media info + * @return RES_OK on success, otherwise an error code on failure + */ ucl::Result prepareImage(media_info_h media); + + /** + * @brief Prepares media image data + * @param[in] filePath Path to media file + * @return RES_OK on success, otherwise an error code on failure + */ ucl::Result prepare(std::string filePath); private: diff --git a/gallery/model/SoundManager.h b/gallery/model/SoundManager.h index 9e7814a..45a5dfb 100644 --- a/gallery/model/SoundManager.h +++ b/gallery/model/SoundManager.h @@ -27,20 +27,60 @@ namespace gallery { UCL_DECLARE_REF_ALIASES(SoundManager); + /** + * @brief Provides set of instruments to operate with sound parameters + */ class SoundManager final : public ucl::NonCopyable { public: + + /** + * @brief Creates new instance of SoundManager + * @return Shared reference to SoundManager object + */ static SoundManagerSRef newInstance(); public: + + /** + * @brief Checks if media device is ready + * @return true if ready, false if not ready + */ bool isMediaDeviceReady() const; + /** + * @brief Gets current volume level + * @return Current volume level + */ int getCurrentMediaVolume() const; + + /** + * @brief Gets max volume level + * @return Max volume level + */ int getMaxMediaVolume() const; + /** + * @brief Adds media device state change handler + * @param[in] handler Handler + */ void addMediaDeviceStateChangeHandler(NotiHandler handler); + + /** + * @brief Removes media device state change handler + * @param[in] handler Handler + */ void delMediaDeviceStateChangeHandler(NotiHandler::CDRef handler); + /** + * @brief Adds media volume state change handler + * @param[in] handler Handler + */ void addMediaVolumeChangeHandler(NotiHandler handler); + + /** + * @brief Adds media volume change handler + * @param[in] handler Handler + */ void delMediaVolumeChangeHandler(NotiHandler::CDRef handler); private: diff --git a/gallery/model/helpers.h b/gallery/model/helpers.h index 9ad2e4a..f6998d3 100644 --- a/gallery/model/helpers.h +++ b/gallery/model/helpers.h @@ -23,6 +23,11 @@ namespace gallery { namespace util { + /** + * @brief Creates CustomMediaAlbum + * @param[in] filePathArray Vector of file paths + * @return Shared reference to CustomMediaAlbum + */ CustomMediaAlbumSRef makeMediaAlbum( const std::vector &filePathArray); }} diff --git a/gallery/model/types.h b/gallery/model/types.h index 38feee5..a6f7d5e 100644 --- a/gallery/model/types.h +++ b/gallery/model/types.h @@ -21,12 +21,15 @@ namespace gallery { + /** + * @brief Enumeration of media types + */ enum class MediaType { - IMAGE, - VIDEO, - SOUND, - MUSIC, - OTHERS + IMAGE, /**< Image*/ + VIDEO, /**< Video*/ + SOUND, /**< Sound*/ + MUSIC, /**< Music*/ + OTHERS /**< Others*/ }; }