Several Manipulator updates

* Add documentation to README, cleanup some docs for other plugins
* Preserve existing unit list order and cursor/scroll position
* Adjust mouse input handling, don't move cursor on left-click

README.rst

@@ -199,7 +199,8 @@ Examples:
 changevein
 ==========
 Changes material of the vein under cursor to the specified inorganic RAW
-material.
+material. Only affects tiles within the current 16x16 block - for veins and
+large clusters, you will need to use this command multiple times.
 
 Example:
 --------
@@ -512,12 +513,6 @@ Removes invalid references to mineral inclusions and restores missing ones.
 Use this if you broke your embark with tools like tiletypes, or if you
 accidentally placed a construction on top of a valuable mineral floor.
 
-fixwagons
-=========
-Due to a bug in all releases of version 0.31, merchants no longer bring wagons
-with their caravans. This command re-enables them for all appropriate
-civilizations.
-
 flows
 =====
 A tool for checking how many tiles contain flowing liquids. If you suspect that
@@ -1477,10 +1472,41 @@ are mostly implemented by lua scripts.
 Dwarf Manipulator
 =================
 
-Implemented by the manipulator plugin. To activate, open the unit screen and press 'l'.
+Implemented by the manipulator plugin. To activate, open the unit screen and
-
+press 'l'.
-This tool implements a Dwarf Therapist-like interface within the game ui.
+
-
+This tool implements a Dwarf Therapist-like interface within the game UI. The
+far left column displays the unit's Happiness (color-coded based on its
+value), and the right half of the screen displays each dwarf's labor settings
+and skill levels (0-9 for Dabbling thru Professional, A-E for Great thru Grand
+Master, and U-Z for Legendary thru Legendary+5). Cells with red backgrounds
+denote skills not controlled by labors.
+
+Use the arrow keys or number pad to move the cursor around, holding Shift to
+move 10 tiles at a time.
+
+Press the Z-Up (<) and Z-Down (>) keys to move quickly between labor/skill
+categories.
+
+Press Enter to toggle the selected labor for the selected unit, or Shift+Enter
+to toggle all labors within the selected category.
+
+Press the +- keys to sort the unit list according to the currently selected
+skill/labor, and press the */ keys to sort the unit list by Name, Profession,
+or Happiness (using Tab to select which sort method to use here).
+
+With a unit selected, you can press the "v" key to view its properties (and
+possibly set a custom nickname or profession) or the "c" key to exit
+Manipulator and zoom to its position within your fortress.
+
+The following mouse shortcuts are also available:
+* Click on a column header to sort the unit list. Left-click to sort it in one
+  direction (descending for happiness or labors/skills, ascending for name or
+  profession) and right-click to sort it in the opposite direction.
+* Left-click on a labor cell to toggle that labor. Right-click to move the
+  cursor onto that cell instead of toggling it.
+* Left-click on a unit's name or profession to view its properties.
+* Right-click on a unit's name or profession to zoom to it.
 
 Liquids
 =======

plugins/manipulator.cpp

@@ -338,7 +338,7 @@ public:
 
     std::string getFocusString() { return "unitlabors"; }
 
-    viewscreen_unitlaborsst(vector<df::unit*> &src);
+    viewscreen_unitlaborsst(vector<df::unit*> &src, int cursor_pos);
     ~viewscreen_unitlaborsst() { };
 
 protected:
@@ -354,7 +354,7 @@ protected:
     void calcSize ();
 };
 
-viewscreen_unitlaborsst::viewscreen_unitlaborsst(vector<df::unit*> &src)
+viewscreen_unitlaborsst::viewscreen_unitlaborsst(vector<df::unit*> &src, int cursor_pos)
 {
     for (size_t i = 0; i < src.size(); i++)
     {
@@ -382,12 +382,23 @@ viewscreen_unitlaborsst::viewscreen_unitlaborsst(vector<df::unit*> &src)
 
         units.push_back(cur);
     }
-    std::sort(units.begin(), units.end(), sortByName);
-
     altsort = ALTSORT_NAME;
-    first_row = sel_row = 0;
     first_column = sel_column = 0;
+
+    first_row = 0;
+    sel_row = cursor_pos;
     calcSize();
+
+    // recalculate first_row to roughly match the original layout
+    first_row = 0;
+    while (first_row < sel_row - num_rows + 1)
+        first_row += num_rows + 2;
+    // make sure the selection stays visible
+    if (first_row > sel_row)
+        first_row = sel_row - num_rows + 1;
+    // don't scroll beyond the end
+    if (first_row > units.size() - num_rows)
+        first_row = units.size() - num_rows;
 }
 
 void viewscreen_unitlaborsst::calcSize()
@@ -528,7 +539,11 @@ void viewscreen_unitlaborsst::feed(set<df::interface_key> *events)
     if (first_column < sel_column - col_widths[DISP_COLUMN_LABORS] + 1)
         first_column = sel_column - col_widths[DISP_COLUMN_LABORS] + 1;
 
-    // handle mouse input
+    int input_row = sel_row;
+    int input_column = sel_column;
+    int input_sort = altsort;
+
+    // Translate mouse input to appropriate keyboard input
     if (enabler->tracking_on && gps->mouse_x != -1 && gps->mouse_y != -1)
     {
         int click_header = DISP_COLUMN_MAX; // group ID of the column header clicked
@@ -560,34 +575,44 @@ void viewscreen_unitlaborsst::feed(set<df::interface_key> *events)
         case DISP_COLUMN_HAPPINESS:
             if (enabler->mouse_lbut || enabler->mouse_rbut)
             {
-                descending = enabler->mouse_lbut;
+                input_sort = ALTSORT_HAPPINESS;
-                std::sort(units.begin(), units.end(), sortByHappiness);
+                if (enabler->mouse_lbut)
+                    events->insert(interface_key::SECONDSCROLL_PAGEUP);
+                if (enabler->mouse_rbut)
+                    events->insert(interface_key::SECONDSCROLL_PAGEDOWN);
             }
             break;
 
         case DISP_COLUMN_NAME:
             if (enabler->mouse_lbut || enabler->mouse_rbut)
             {
-                descending = enabler->mouse_rbut;
+                input_sort = ALTSORT_NAME;
-                std::sort(units.begin(), units.end(), sortByName);
+                if (enabler->mouse_lbut)
+                    events->insert(interface_key::SECONDSCROLL_PAGEDOWN);
+                if (enabler->mouse_rbut)
+                    events->insert(interface_key::SECONDSCROLL_PAGEUP);
             }
             break;
 
         case DISP_COLUMN_PROFESSION:
             if (enabler->mouse_lbut || enabler->mouse_rbut)
             {
-                descending = enabler->mouse_rbut;
+                input_sort = ALTSORT_PROFESSION;
-                std::sort(units.begin(), units.end(), sortByProfession);
+                if (enabler->mouse_lbut)
+                    events->insert(interface_key::SECONDSCROLL_PAGEDOWN);
+                if (enabler->mouse_rbut)
+                    events->insert(interface_key::SECONDSCROLL_PAGEUP);
             }
             break;
 
         case DISP_COLUMN_LABORS:
             if (enabler->mouse_lbut || enabler->mouse_rbut)
             {
-                descending = enabler->mouse_lbut;
+                input_column = click_labor;
-                sort_skill = columns[click_labor].skill;
+                if (enabler->mouse_lbut)
-                sort_labor = columns[click_labor].labor;
+                    events->insert(interface_key::SECONDSCROLL_UP);
-                std::sort(units.begin(), units.end(), sortBySkill);
+                if (enabler->mouse_rbut)
+                    events->insert(interface_key::SECONDSCROLL_DOWN);
             }
             break;
         }
@@ -603,12 +628,12 @@ void viewscreen_unitlaborsst::feed(set<df::interface_key> *events)
             // left-click to view, right-click to zoom
             if (enabler->mouse_lbut)
             {
-                sel_row = click_unit;
+                input_row = click_unit;
                 events->insert(interface_key::UNITJOB_VIEW);
             }
             if (enabler->mouse_rbut)
             {
-                sel_row = click_unit;
+                input_row = click_unit;
                 events->insert(interface_key::UNITJOB_ZOOM_CRE);
             }
             break;
@@ -617,21 +642,28 @@ void viewscreen_unitlaborsst::feed(set<df::interface_key> *events)
             // left-click to toggle, right-click to just highlight
             if (enabler->mouse_lbut || enabler->mouse_rbut)
             {
-                sel_row = click_unit;
-                sel_column = click_labor;
                 if (enabler->mouse_lbut)
+                {
+                    input_row = click_unit;
+                    input_column = click_labor;
                     events->insert(interface_key::SELECT);
+                }
+                if (enabler->mouse_rbut)
+                {
+                    sel_row = click_unit;
+                    sel_column = click_labor;
+                }
             }
             break;
         }
         enabler->mouse_lbut = enabler->mouse_rbut = 0;
     }
 
-    UnitInfo *cur = units[sel_row];
+    UnitInfo *cur = units[input_row];
-    if (events->count(interface_key::SELECT) && (cur->allowEdit) && (columns[sel_column].labor != unit_labor::NONE))
+    if (events->count(interface_key::SELECT) && (cur->allowEdit) && (columns[input_column].labor != unit_labor::NONE))
     {
         df::unit *unit = cur->unit;
-        const SkillColumn &col = columns[sel_column];
+        const SkillColumn &col = columns[input_column];
         bool newstatus = !unit->status.labors[col.labor];
         if (col.special)
         {
@@ -650,7 +682,7 @@ void viewscreen_unitlaborsst::feed(set<df::interface_key> *events)
     if (events->count(interface_key::SELECT_ALL) && (cur->allowEdit))
     {
         df::unit *unit = cur->unit;
-        const SkillColumn &col = columns[sel_column];
+        const SkillColumn &col = columns[input_column];
         bool newstatus = !unit->status.labors[col.labor];
         for (int i = 0; i < NUM_COLUMNS; i++)
         {
@@ -675,15 +707,15 @@ void viewscreen_unitlaborsst::feed(set<df::interface_key> *events)
     if (events->count(interface_key::SECONDSCROLL_UP) || events->count(interface_key::SECONDSCROLL_DOWN))
     {
         descending = events->count(interface_key::SECONDSCROLL_UP);
-        sort_skill = columns[sel_column].skill;
+        sort_skill = columns[input_column].skill;
-        sort_labor = columns[sel_column].labor;
+        sort_labor = columns[input_column].labor;
         std::sort(units.begin(), units.end(), sortBySkill);
     }
 
     if (events->count(interface_key::SECONDSCROLL_PAGEUP) || events->count(interface_key::SECONDSCROLL_PAGEDOWN))
     {
         descending = events->count(interface_key::SECONDSCROLL_PAGEUP);
-        switch (altsort)
+        switch (input_sort)
         {
         case ALTSORT_NAME:
             std::sort(units.begin(), units.end(), sortByName);
@@ -718,7 +750,7 @@ void viewscreen_unitlaborsst::feed(set<df::interface_key> *events)
         {
             for (int i = 0; i < unitlist->units[unitlist->page].size(); i++)
             {
-                if (unitlist->units[unitlist->page][i] == units[sel_row]->unit)
+                if (unitlist->units[unitlist->page][i] == units[input_row]->unit)
                 {
                     unitlist->cursor_pos[unitlist->page] = i;
                     unitlist->feed(events);
@@ -964,7 +996,7 @@ struct unitlist_hook : df::viewscreen_unitlistst
         {
             if (units[page].size())
             {
-                Screen::show(new viewscreen_unitlaborsst(units[page]));
+                Screen::show(new viewscreen_unitlaborsst(units[page], cursor_pos[page]));
                 return;
             }
         }