Reworking of graphical interface conventions

Makefile.am

@@ -509,19 +509,24 @@ gambit_SOURCES = \
 	src/gui/dlnfglogit.h \
 	src/gui/efgdisplay.cc \
 	src/gui/efgdisplay.h \
+	src/gui/efgdragdrop.cc \
 	src/gui/efglayout.cc \
 	src/gui/efglayout.h \
+	src/gui/efgnodemenu.cc \
 	src/gui/efgpanel.cc \
 	src/gui/efgpanel.h \
+	src/gui/efgtooltip.cc \
 	src/gui/efgprofile.cc \
 	src/gui/efgprofile.h \
 	src/gui/gamedoc.cc \
 	src/gui/gamedoc.h \
 	src/gui/gameframe.cc \
 	src/gui/gameframe.h \
 	src/gui/menuconst.h \
+	src/gui/nfgheadergrid.cc \
 	src/gui/nfgpanel.cc \
 	src/gui/nfgpanel.h \
+	src/gui/nfgpayoffgrid.cc \
 	src/gui/nfgprofile.cc \
 	src/gui/nfgprofile.h \
 	src/gui/nfgtable.cc \

doc/gui.efg.rst

@@ -27,30 +27,32 @@ strategic players in the game.
 Adding moves
 ------------
 
-There are two options for adding moves to a tree: drag-and-drop
-and the :guilabel:`Insert move` dialog.
-
-#. Moves can be added to the
-   tree using a drag-and-drop idiom. From the player list window, drag
-   the player icon located to the left of the player who will have the
-   move to any terminal node in the game tree. The tree will be extended
-   with a new move for that player, with two actions at the new move.
-   Adding a move for the chance player is done the same way, except the
-   dice icon appearing to the left of the chance player in the player
-   list window is used instead of the player icon. For the chance player,
-   the two actions created will each be given a probability weight of
-   one-half. If the desired move has more than two actions, additional
-   actions can be added by dragging the same player's icon to the move
-   node; this will add one action to the move each time this is done.
+There are two options for adding moves to a tree, both reached by
+right-clicking the node where the move should go: a quick per-player
+submenu, and the more flexible :guilabel:`Insert move` dialog.
+
+#. Right-clicking any terminal node in the tree and choosing
+   :guilabel:`Insert move for` opens a submenu listing every player
+   (each shown with its assigned colour), plus the chance player. Choosing
+   a player extends the tree with a new move for that player at the node,
+   with two actions. Choosing the chance player adds a chance move instead,
+   with its two actions each given a probability weight of one-half.
+
+   The player who moves at an *existing* move can be changed the same
+   way: right-clicking a nonterminal node offers the same submenu,
+   labeled :guilabel:`Assign this move to`, listing the other players
+   to which the move can be reassigned. A move cannot currently be
+   changed between the chance player and a personal player this way --
+   nor can it be, at present, using any other method in the interface.
 
 .. image:: screens/insertmove.*
            :width: 33%
            :alt: insert move dialog
            :align: right
            :target: _images/insertmove.png
 
-2. Click on any terminal node in
-   the tree, and select :menuselection:`Edit --> Insert move`
+2. Right-click any terminal node in
+   the tree, and choose :guilabel:`Insert move`
    to display the :guilabel:`insert move` dialog.
    The dialog is intended to read like a sentence:
 
@@ -66,17 +68,16 @@ and the :guilabel:`Insert move` dialog.
      Otherwise, it is set automatically to the number of actions at
      the selected information set.
 
-The two methods can be useful in different contexts.
-The drag-and-drop approach
-is a bit quicker to use, especially when creating trees that have few
-actions at each move. The dialog approach is a bit more flexible, in
-that a move can be added for a new, as-yet-undefined player, a move
-can be added directly into an existing information set, and a move can
-be immediately given more than two actions.
+Both are reached with a right-click, and can be useful in different
+contexts. The per-player submenu is a bit quicker to use, especially
+when creating trees that have few actions at each move. The dialog
+approach is a bit more flexible, in that a move can be added for a new,
+as-yet-undefined player, a move can be added directly into an existing
+information set, and a move can be immediately given more than two
+actions.
 
 A single action can also be added to, or removed from, an existing
-move without drag-and-drop, using the :guilabel:`Edit move` dialog
-described next.
+move using the :guilabel:`Edit move` dialog described next.
 
 
 .. _editing-moves:
@@ -86,8 +87,8 @@ Editing moves
 
 The properties of an existing move -- the label of its information
 set, the player to which it belongs, and the actions available at it
--- can be changed by clicking on any node belonging to the move and
-selecting :menuselection:`Edit --> Move`. This displays the
+-- can be changed by right-clicking on any node belonging to the move
+and choosing :guilabel:`Edit move`. This displays the
 :guilabel:`Edit move` dialog, which lists a text field for the
 information set's label, a dropdown for the player to which the move
 belongs, and a row for each action, showing its label and, for moves
@@ -165,25 +166,30 @@ the tree. It is often efficient to create the structure once, and then
 copy it as needed elsewhere.
 
 Gambit provides a convenient idiom for this. Clicking on any
-nonterminal node and dragging to another node results in a context-aware
-popup menu.  Depending on the destination node, this menu offers
-the option of copying the subtree rooted at the original node, moving
-it entirely, or placing the destination node in the same information set
-as the source node.
+nonterminal node and dragging it to another node results in a
+context-aware popup menu. While dragging, the node under the pointer is
+outlined in green if dropping there is possible, or in red if not.
+Depending on the destination node, this menu offers the option of
+copying the subtree rooted at the original node, moving it entirely, or
+placing the destination node in the same information set as the source
+node. Moving a subtree onto one of its own descendants is never
+offered (though shown, disabled), since the destination would cease to
+exist partway through the move; copying onto a descendant remains
+available, since the copy is made before anything is removed.
 
 
 Removing parts of a game tree
 -----------------------------
 
 Two deletion operations are supported on extensive games. To delete
-the entire subtree rooted at a node, click on that node and select
-:menuselection:`Edit --> Delete subtree`.
+the entire subtree rooted at a node, right-click that node and choose
+:guilabel:`Delete subtree`.
 
-To delete an individual move from the game, click on one of the direct
-children of that node, and select
-:menuselection:`Edit --> Delete parent`. This operation
+To delete an individual move from the game, right-click one of the
+direct children of that node, and choose
+:guilabel:`Delete parent`. This operation
 deletes the parent node, as well as all the children of the parent
-other than the selected node. The selected child node now takes the
+other than the clicked node. The clicked child node now takes the
 place of the parent node in the tree.
 
 
@@ -196,13 +202,12 @@ Gambit provides several methods to help manage the information
 structure in an extensive game.
 
 When building a tree, new moves can be placed in a given information
-set using the :ref:`Insert move dialog <adding-moves>`.
-Additionally, new moves can be
-created using the drag-and-drop idiom by holding down the :kbd:`Shift`
-key and dragging a node in the tree. During the drag operation, the
-cursor changes to the move icon . Dropping the move icon on another
-node places the target node in the same information set as the node
-where the drag operation began.
+set using the :ref:`Insert move dialog <adding-moves>`. Additionally, a
+node can be placed in the same information set as another using the
+drag-and-drop idiom described in :ref:`copying-trees`: dragging one
+node onto another and choosing :guilabel:`Put node in same information
+set` (or, when dropping on a terminal node, :guilabel:`Insert move
+using same information set`) from the popup menu.
 
 .. image::  screens/editnode.*
             :width: 33%
@@ -211,7 +216,8 @@ where the drag operation began.
             :target:  _images/editnode.png
 
 The information set to which a node belongs can also be set by
-selecting :menuselection:`Edit --> Node`.  This displays the
+right-clicking the node and choosing :guilabel:`Node properties`
+(or by double-clicking the node). This displays the
 :guilabel:`node properties` dialog.
 The :guilabel:`Information set` dropdown defaults
 to the current information set to which the node belongs, and contains
@@ -231,12 +237,12 @@ corresponding nodes in the original subtree. In many cases, though,
 these trees differ in the information available to some or all of the
 players. To help speed the process of adjusting information sets in
 bulk, Gambit offers a "reveal" operation, which breaks information
-sets based on the action taken at a particular node. Click on a node
-at which the action taken is to be made known subsequently to other
-players, and select :menuselection:`Edit --> Reveal`.  This displays a
+sets based on the action taken at a particular node. Right-click the
+node at which the action taken is to be made known subsequently to
+other players, and choose :guilabel:`Reveal`.  This displays a
 dialog listing the players in the game. Check the boxes next to the
 players who observe the outcome of the move at the node, and click
-:guilabel:`OK`.  The information sets at nodes below the selected one
+:guilabel:`OK`.  The information sets at nodes below the clicked one
 are adjusted based on the action selected at this node.
 
 .. note::
@@ -263,14 +269,15 @@ zero for all players, and pops up an editing panel for that outcome.
 For nodes with existing outcomes, clicking on any of the displayed
 payoffs pops up an editing panel for that outcome.
 
-Outcomes may also be moved or copied using drag-and-drop.
-Left-clicking and dragging an outcome to another node pops up a
-context-aware menu which allows the outcome to be moved or copied, or
-to create a new outcome with the same payoffs as the original one at
-the new node.
+Outcomes may also be moved, or shared between nodes, using drag-and-drop.
+Left-clicking and dragging an outcome to another node (highlighted, as with
+moving and copying subtrees, in green or red as a valid or invalid drop
+target) pops up a context-aware menu which allows the outcome to be moved to
+the new node, or for the new node to use the same outcome as the original --
+so that editing the payoffs at either node updates both.
 
-To remove an outcome from a node, click on the node, and
-select :menuselection:`Edit --> Remove outcome`.
+To remove an outcome from a node, right-click the node, and
+choose :guilabel:`Remove outcome`.
 
 
 
@@ -471,5 +478,7 @@ system different from the system on which it was saved, Gambit tries
 to match the font style as closely as possible when the original font
 is not available.
 
-The color-coding for each player can be changed by clicking on the
-color icon to the left of the corresponding player.
+The color-coding for each player (and for chance) can be changed on the
+:guilabel:`Players` page of the :guilabel:`Game properties` dialog
+(:menuselection:`Edit --> Game`), by clicking the color swatch next to the
+player's name.

doc/gui.general.rst

@@ -10,17 +10,25 @@ General layout of the main window
             :align: right
             :target: _images/overview.png
 
-The frame presenting a game consists of two principal panels. The main
-panel, to the right, displays the game graphically; in this case,
-showing the game tree of a simple one-card poker game. To the left is
-the player panel, which lists the players in the game; here, Fred and
-Alice are the players. Note that where applicable, information is
-color-coded to match the colors assigned to the players: Fred's moves
-and payoffs are all presented in red, and Alice's in blue. The color
-assigned to a player can be changed by clicking on the color icon
-located to the left of the player's name on the player panel. Player
-names are edited by clicking on the player's name, and editing the
-name in the text control that appears.
+The frame presenting a game consists of a single main panel, which displays
+the game graphically; in this case, showing the game tree of a simple
+one-card poker game. Note that where applicable, information is color-coded
+to match the colors assigned to the players: Fred's moves and payoffs are
+presented in red, and Alice's in blue. Player names and colors are set on
+the :guilabel:`Players` page of the :guilabel:`Game properties` dialog
+(:menuselection:`Edit --> Game`): each player is listed with a text field
+for its name and a color swatch beside it, which opens a color picker when
+clicked. A new player is added to the game using
+:menuselection:`Edit --> Add player`; the Players page itself does not yet
+support adding, removing, or reordering players.
+
+Hovering the mouse pointer over a node in the tree briefly displays a small
+window showing, for each player, that player's expected payoff from that
+point in the game onward, under the currently-selected profile. For a node
+that is not a terminal node, this window also shows the probability of
+reaching that node and its information set, the information set's value to
+the player who moves there, and that player's belief about being at this
+particular node within the information set.
 
 Two additional panels are available. Selecting
 :menuselection:`Tools --> Dominance` toggles

doc/gui.nash.rst

@@ -164,17 +164,20 @@ is proportional to the probability with which the action is played.
             :align: right
             :target: _images/beliefs.png
 
-Clicking on any node in the tree displays additional information about
-the profile at that node.
-The player panel displays
-information relevant to the selected node, including the payoff to all players
-conditional on reaching the node, as well as information about Alice's
-beliefs at the node.
+Hovering the mouse pointer over any node in the tree briefly displays
+additional information about the profile at that node, in a small window
+next to the node, including each player's expected payoff from that point
+in the game onward, as well as information about Alice's beliefs at the
+node.
 
 The computed profiles can also be viewed in the reduced strategic
 game. Clicking on the strategic game icon changes the view to the
 reduced strategic form of the game, and shows the equilibrium profiles
-converted to mixed strategies in the strategic game.
+converted to mixed strategies in the strategic game. Hovering the mouse
+pointer over a strategy's row or column label there shows the analogous
+information for that strategy: its probability under the current
+profile, its payoff if played against the others' current play, and its
+player's overall payoff under the current profile.
 
 
 

doc/gui.nfg.rst

@@ -20,8 +20,9 @@ game after any changes to the extensive game.
 Strategies in a reduced strategic game are assigned numeric labels for
 identification.  These labels are assigned via a deterministic algorithm for
 constructing the reduced strategic game from an extensive game.
-Click a strategy label to open a popup listing the action selected at each
-information set where the reduced strategy specifies an action.
+Hovering the mouse pointer over a strategy's row or column label briefly
+displays a small window listing the action selected at each information set
+where the reduced strategy specifies an action.
 
 Strategic games may also be input directly. To create a new strategic
 game, select :menuselection:`File --> New --> Strategic game`,
@@ -55,6 +56,15 @@ The payoffs in each cell are colour-coded by player. In the standard
 two-player arrangement, Gambit displays the row player's payoff first
 and the column player's payoff second.
 
+Whenever a profile has been computed and selected, hovering the mouse
+pointer over any strategy's row or column label also shows that
+strategy's probability under the current profile, the payoff its player
+would get by playing that strategy alone against the others' current
+play, and that player's overall payoff under the current profile.
+Comparing this payoff-if-played figure across a player's strategies is
+how to check whether the current profile is actually a best response for
+that player.
+
 
 Row and column hierarchies
 --------------------------
@@ -98,17 +108,19 @@ each strategy of the third player.
 Rearranging the table
 ---------------------
 
-To change the table arrangement, drag a player from the player list to
-the row-label or column-label area.
-
-When the drop menu appears, choose where to place the player in the row
-or column hierarchy. Gambit updates the display without changing the
-game itself.
-
-The available positions depend on the current arrangement. Placing a
-player before another player makes the moved player a higher level in
-the hierarchy; placing the player after another player makes the moved
-player a lower level.
+To change the table arrangement, right-click any row or column label and
+choose a player from the menu that appears. If that side of the table
+already has one or more players assigned to it, the menu offers
+:guilabel:`Place player before` and :guilabel:`Place player after`
+submenus, each listing every player; if not, it offers a single
+:guilabel:`Use as row player` (or :guilabel:`Use as column player`)
+submenu instead. Gambit updates the display without changing the game
+itself.
+
+The available positions depend on the current arrangement. Choosing a
+player from :guilabel:`Place player before` makes that player a higher
+level in the hierarchy than the row or column that was right-clicked;
+choosing one from :guilabel:`Place player after` makes it a lower level.
 
 .. image:: screens/pd3.*
    :width: 50%