diff --git a/rtgui/toollocationpref.cc b/rtgui/toollocationpref.cc index 0dda56806..32cd73e97 100644 --- a/rtgui/toollocationpref.cc +++ b/rtgui/toollocationpref.cc @@ -30,6 +30,12 @@ using Favorites = std::unordered_set; namespace { +/** + * Gets the tool name for the tool's ToolPanel as a string. + * + * @param tool The name as a raw string, or an empty string if the tool is + * unknown. + */ std::string getToolName(Tool tool) { switch (tool) { @@ -149,6 +155,9 @@ std::string getToolName(Tool tool) return ""; }; +/** + * Returns the language key for the panel's title. + */ Glib::ustring getToolPanelTitleKey(ToolPanelCoordinator::Panel panel) { switch (panel) { @@ -172,6 +181,9 @@ Glib::ustring getToolPanelTitleKey(ToolPanelCoordinator::Panel panel) return ""; } +/** + * Returns the language key for the tool's title. + */ Glib::ustring getToolTitleKey(Tool tool) { using Tool = Tool; @@ -292,6 +304,13 @@ Glib::ustring getToolTitleKey(Tool tool) return ""; } +/** + * A widget with buttons (packed vertically) for modifying a list store with a + * tree view. + * + * Includes buttons for moving single rows up or down and a button for removing + * selected rows. + */ class ListEditButtons : public Gtk::Box { private: @@ -310,15 +329,34 @@ private: void updateButtonSensitivity(); public: + /** + * Constructs an edit buttons widget for modifying the provided list store. + * + * @param list The tree view for which selections are made in. The tree + * view's model MUST be the list store. + * @param listStore The list store that the widget will modify. + */ explicit ListEditButtons(Gtk::TreeView &list, Glib::RefPtr listStore); + /** + * Returns the signal that gets emitted right before this widget removes + * rows from its list store. + * + * The signal contains a vector of tree model paths of the rows that will be + * erased. + */ sigc::signal> getSignalRowsPreErase(); }; +/** + * Model columns for the favorites list. + */ class FavoritesColumns : public Gtk::TreeModelColumnRecord { public: + /** The tool's display name. */ Gtk::TreeModelColumn toolName; + /** The tool. */ Gtk::TreeModelColumn tool; FavoritesColumns() @@ -328,12 +366,19 @@ public: } }; +/** + * Model columns for the available tools list. + */ class ToolListColumns : public Gtk::TreeModelColumnRecord { public: + /** The tool's display name. */ Gtk::TreeModelColumn toolName; + /** The tool. */ Gtk::TreeModelColumn tool; + /** Is the tool added to favorites. */ Gtk::TreeModelColumn isFavorite; + /** Can the tool be added to favorites. */ Gtk::TreeModelColumn isEditable; ToolListColumns() @@ -394,6 +439,7 @@ void ListEditButtons::onButtonDownPressed() return; } + // Get the selected row and next row. auto selected_row_iter = listStore->get_iter(selected[0]); auto next_row_iter = selected_row_iter; next_row_iter++; @@ -402,6 +448,7 @@ void ListEditButtons::onButtonDownPressed() return; } + // Move the selected row down and update the buttons. listStore->iter_swap(selected_row_iter, next_row_iter); updateButtonSensitivity(); } @@ -419,6 +466,7 @@ void ListEditButtons::onButtonRemovePressed() signalRowsPreErase.emit(selected_paths); + // Remove the selected rows. for (const auto & row_ref : selected) { const auto row_path = row_ref.get_path(); if (row_path) { @@ -445,6 +493,7 @@ void ListEditButtons::onButtonUpPressed() return; } + // Swap selected row with the previous row. auto prev_row_iter = selected_row_iter; prev_row_iter--; listStore->iter_swap(selected_row_iter, prev_row_iter); @@ -469,6 +518,8 @@ void ListEditButtons::updateButtonSensitivity() buttonDown.set_sensitive(false); buttonUp.set_sensitive(false); } else { + // Up button cannot be used on the first row. Down button cannot be used + // on the last row. auto selected_row_iter = list.get_model()->get_iter(selected[0]); const auto list_children = listStore->children(); buttonUp.set_sensitive(!selected_row_iter->equal(list_children.begin())); @@ -511,19 +562,68 @@ struct ToolLocationPreference::Impl { Gtk::TreeView *favoritesViewPtr; ListEditButtons favoritesListEditButtons; + /** + * Constructs an implementation that gets values from and updates the + * provided options object. + */ explicit Impl(Options &options); + /** + * Adds the tools in the tool tree as a child in the provided row. + * + * @param tools The tool tree. + * @param parentRowIter An iterator to the row under which to add the tools. + * @param favorites The tools which are currently marked as favorites. + */ void addToolListRowGroup( const std::vector &tools, const Gtk::TreeIter &parentRowIter, const Favorites &favorites); + /** + * Toggles the tool list favorite column and updates the favorites list. + * + * @param row_path Path to the tool list model row. + */ void favoriteToggled(const Glib::ustring &row_path); + /** + * Gets the tool with the provided tool name. + * + * @param name The tool name as a raw string. + * @return The tool. + */ Tool getToolFromName(const std::string &name) const; + /** + * Initializes the favorites list. + * + * @param favorites Tools that are currently marked as favorites. + */ void initFavoritesRows(const std::vector &favorites); + /** + * Initializes the available tools list. + * + * @param favorites Tools that are currently marked as favorites. + */ void initToolListRows(const std::vector &favorites); + /** + * Updates the favorites column of the available tools list when tools are + * about to be removed from the favorites list. + * + * @param paths Paths in the favorites list pointing to the rows that are + * about to be removed. + */ void onFavoritesRowsPreRemove(const std::vector paths); + /** + * Converts tool names to their corresponding tools. + * + * @param tool_names The tool names that need to be converted. + * @return The tools. + */ std::vector toolNamesToTools( const std::vector &tool_names) const; + /** + * Updates the options object associated with this object with the current + * favorites preferences. + */ void updateOptions(); }; @@ -533,6 +633,7 @@ std::unordered_map ToolLocationPreference::Impl::Impl(Options &options) : options(options), + // Tool list. toolListModelPtr(Gtk::TreeStore::create(toolListColumns)), toolListViewColumnFavorite( Gtk::TreeViewColumn(M("PREFERENCES_TOOLPANEL_FAVORITE"))), @@ -540,6 +641,7 @@ ToolLocationPreference::Impl::Impl(Options &options) : Gtk::TreeViewColumn(M("PREFERENCES_TOOLPANEL_TOOL"))), toolListViewPtr(Gtk::manage(new Gtk::TreeView(toolListModelPtr))), + // Favorites list. favoritesModelPtr(Gtk::ListStore::create(favoritesColumns)), favoritesViewColumnToolName( Gtk::TreeViewColumn(M("PREFERENCES_TOOLPANEL_TOOL"))), @@ -644,6 +746,7 @@ Tool ToolLocationPreference::Impl::getToolFromName(const std::string &name) cons void ToolLocationPreference::Impl::initFavoritesRows( const std::vector &favorites) { + // Add the favorites to the favorites list store. for (const auto tool : favorites) { auto favorite_row_iter = favoritesModelPtr->append(); favorite_row_iter->set_value( @@ -658,6 +761,7 @@ void ToolLocationPreference::Impl::addToolListRowGroup( const Gtk::TreeIter &parentRowIter, const Favorites &favorites) { + // Recursively add the tool and its children to the tool list tree store. for (const ToolPanelCoordinator::ToolTree &tool : tools) { auto tool_row_iter = toolListModelPtr->append(parentRowIter->children()); tool_row_iter->set_value( @@ -680,10 +784,12 @@ void ToolLocationPreference::Impl::initToolListRows(const std::vector &fav const auto panel_tools = ToolPanelCoordinator::getDefaultToolLayout(); Favorites favorites_set; + // Convert the favorites vector into a set for fast lookup. for (const auto &tool : favorites) { favorites_set.insert(tool); } + // Add each panel and their children to the tool list. for (const auto panel : { ToolPanelCoordinator::Panel::EXPOSURE, ToolPanelCoordinator::Panel::DETAILS, diff --git a/rtgui/toollocationpref.h b/rtgui/toollocationpref.h index 815df6839..c7bee8695 100644 --- a/rtgui/toollocationpref.h +++ b/rtgui/toollocationpref.h @@ -22,6 +22,9 @@ class Options; +/** + * Widget for configuring the location of tools in the tool panel tabs. + */ class ToolLocationPreference : public Gtk::Box { private: @@ -29,6 +32,14 @@ private: std::unique_ptr impl; public: + /** + * Constructs a tool location preference widget that gets values from and + * updates the provided options object. + */ explicit ToolLocationPreference(Options &options); + /** + * Updates the options object associated with this object with the current + * favorites preferences. + */ void updateOptions(); };