[xboard.git] / whats_new / UserGuide.html

<h2>XBoard user guide</h2>
<p>
Xboard consists of a main window, displaying a chess board and clocks,
as well as a number of auxiliary windows dedicated to holding additional,
not strictly necessary information.
Depending on what you are using it for 
(game viewer, playing on internet server, playing with engine(s)),
that information could be useful or irrelevant,
and you can open or close these windows accordingly.
The auxiliary windows are:
</p>
<ul>
<li><a href="#tag-A1">Game list</a>, giving the table of contents of the loaded PGN file</li>
<li><a href="#tag-A2">Comment window</a>, where you can view or edit comments (and variations) to the move</li>
<li><a href="#tag-A3">Tags window</a>, where you can see and edit the tags of the currently loaded game</li>
<li><a href="#tag-A4">Move list</a>, where the moves of the current game are shown as text</li>
<li><a href="#tag-A5">Engine output</a>, where you can see the variations an engine is dreaming up</li>
<li><a href="#tag-A6">Evaluation graph</a>, which shows you how the engine score evolves over the current game</li>
<li><a href="#tag-A7">ICS interaction console</a>, a terminal window where you communicate with an internet server</li>
</ul>
<p>
These auxiliary windows can be kept open all the time, and tiled so they are always in view,
without disturbing the operation of the main (chess-boadrd) window.
In addition, there are a large number of dialog windows that grab the full attention of the user interface,
so that the block operation of anything else.
These are used for altering the settings of XBoard during the session.
</p>
<p>
Below we will first describe the operation of the main and auxiliary windows in detail.
After that the function of the various menu dialogs will be discussed.
</p>

<table cellpadding="20"><tr><td valign="top">
<h3>The main XBoard window</h3>
<p>
The main window contains several elements:
</p>
<ul>
<li>A title bar, actively used to display information</li>
<li>A menu bar, through which you can control XBoard</li>
<li>Two chess clocks, for white and black</li>
<li>An optional button bar, with which you an navigate through the current game</li>
<li>A single-line message field, where moves, variation, and sometimes texts are displayed</li>
<li>An area where the chess board (and sometimes other stuff) is drawn</li>
</ul>
<p>
The elements are mostly operated using the mouse, sometimes in combination with the keyboard.
Many keystrokes have been assigned a shortcut function, however, as an alternative to operating the menu bar with the mouse.
It is mainly non-printable keystrokes involving Alt and Ctrl key that act as shortcuts;
typing printable characters make an input box pop up where you can finish the typing while you see it,
to type stuff to XBoard (e.g. chess moves).
The menu bar is otherwise a quite normal menu bar, that you can operate both with left and right mouse button.
</p>
<p>
The message field above the board has no input function, 
and is only used to display simple error messages (such as "It is not your turn"),
or alerts ("draw pawn backwards to under-promote"),
the last move played,
or the latest 'principal variation' computed by an engine.
</p>
<p>
The button bar to the right of the message field
is used to step through the currently loaded game, move by move, or directly to beginning or end.
This can also be done through the menu (very clumsy!) or with the arrow keys on the keyboard (probably preferable).
</p>
</td><td valign ="top">
<img src="4.5.0/Spartan.png">
</td></tr></table>
<p>
The principal element of the main window is the chess board.
Its main function is of course to enter chess moves, but it has several other functions as well.
To move pieces, you use the left mouse button (button 1).
You can do this either by first clicking the piece you want to move,
and then the square you want to move it to ('click-click move'),
or by 'grabbing' the piece by pressing the mouse button,
drag it to its destination square, and release the mouse button there ('drag-drop moving').
Normally XBoard would show you the piece being dragged around 
(although this 'animate dragging' can be switched off).
The move you just made can be highlighted by drawing colored borders around the from- and to-square,
or by drawing an arrow between them.
</p>
<p>
With click-click moving the first click selects the piece, and such a selected piece will already be highlighted.
You also would get this effect after dragging around a piece, but releasing it on its original square;
this simply counts as a static click on the piece.
You still have the possibility to select another piece, by clicking it:
only a clicked empty square or opponent piece will be interpreted as a to-square.
You can also deselect the selected piece by clicking it, in which case the highlight on it will go off.
</p>
<p>
Keeping the Shift key down while entering a move gives it a special meaning:
the move is in that case not added to the mainline of the game (possibly truncating it first),
but as a variation, so that you can Revert to the original game later.
</p>
<p>
<b>Variation board -</b> A right-click (anywhere) on the chess board will normally be taken as a request to 'walk' the latest principal variation indicated by an engine.
This would normally be the one displayed in the message field.
By keeping the right mouse button (button 3) down, and moving the mouse vertically,
XBoard will start to step through the moves indicated by the engine,
so you see them played out on the chess board.
(This is sometimes called a 'variation board'.)
You can continue to step forward and backward through the engine line as long as you keep the button down.
</p>
<p>
When setting up a position ('Edit Position mode'), things work a bit differently, 
because you are not bound by any chess rules in that case.
In a click-click move any second click would be a to-square,
even if it captures a piece of your own.
You will also be able to move empty squares and even 'capture' pieces with them,
or drag pieces off the board to get rid of them.
But the most important difference is the function of the right-click,
which now is used to put a new piece on the square you clicked.
Depending on the settings, this can either go through popping up a menu from which you select,
or by making a vertical sweep with the mouse, keeping button 3 down,
which will make the identity of the newly introduced piece cycle through all possible choices,
so that you can release the button when you see the one you want ('sweep selection').
This will always start by dropping a Pawn in the clicked square (as you typically need those most);
this will be a black Pawn unless you kept the Shift key pressed, (or use button 2),
in which case it starts with a white Pawn.
</p>
<table cellpadding="20"><tr><td valign="top">
<img src="4.5.0/seekgraph.png">
</td><td valign ="top">
<p>
The clocks are mainly meant as output fields, but in some situations they also accept mouse clicks.
What the clicks do varies.
They can be taken as a signal you want to claim the game because the opponent has flagged
(when his clock displays a negative number).
When you keep the Shift key pressed during the click, you can adjust the clocks by adding (right-click) or subtracting (left-click) a minute.
In situations where this could be meaningful, clicking the clock of the side that does not have the move will transfer the turn to him.
(Such turn passing is obviously illegal in chess, so you cannot do that while playing a game,
but in analysis or for setting up a position, it ican be useful and is allowed.)
When setting up a position, clicking the clock of the side that already has the move
will clear the board.
</p>
<p>
<b>Seek graph -</b> When logged in to an Internet Chess Server, the area where the board is normally drawn doubles as 'seek graph',
where you can see who is looking for what type of game.
This only applies when the board is not in use, i.e. when you are not playing, examining or observing a game.
In this 'idle' mode, left-clicking the board anywhere will request information from the ICS and draw the seek graph accordingly.
Left-clicking on a dot in the seek graph makes you challenge the corresponding player,
while left-clicking off-dots would erase the seek graph, and replace it by the normal board display.
Right-clicking the seek graph off-dots would refresh it (only needed on ICS that cannot do that automatically).
On a busy server dots can sometimes cluster so densely you no longer can reach those that hide behind others;
in this case right-clicking on a dot would 'push it to the back', so that dots behind it now get to the foreground.
When you hover over a dot the message window will show you the details of the corresponding seek ad,
and an exclamation point there will warn you there were dots hiding behind it.
</p>
</td></tr></table>
<ul>
<li>Detour Under-promotion (General Options) determines if a promotion menu will pop up on promotion moves</li>
<li>-pieceMenu (command-line option) determines if a right-click invokes a menu in Edit Position mode</li>
<li>Drop Menu (General Options) determines if a right-click in bughouse invokes a drop menu</li>
<li>Animate Dragging (General Options) determines if you will see the piece being dragged</li>
<li>Seek Graph (ICS Options) determines if left-clicks can call up the seek graph</li>
<li>Highlight Last Move (General Options) controls if clicking squares highlights them</li>
<li>Highlight with Arrow (General Options) controls if an arrow is drawn between from- and to-square</li>
<li>One-click moving (General Options) can make a piece move by clicking only from- or to-square</li>
<li>Show Target Squares (General Options) marks square where the selected / dragged piece can move to</li>
<li>Hide Thinking from Human (General Options) determines if engine thinking is displayed in the message field</li>
<li>-variations (command-line option) determines whether you can enter variations</li>
<li>-showButtonBar (command-line option) determines whether the navigation buttons are present</li>
</ul>

<h3><a name="tag-A2">Comment window</h3>
<table cellpadding="20"><tr><td valign="top">
<p>
The Comment window displays comments and variations from the PGN file belonging to the current move,
and will automatically update when you step through the game.
Left clicks in the Comment window are reserved for the normal editing functions (selecting, drag-drop edition).
The right button can be used to click on a PGN variation
(a sequence of alternative moves enclosed in parentheses) on the current move.
In this case XBoard will 'upgrade' this variation to become the main line of the curent game
(the original main line being shelved in its memory, so you can 'Revert' to it later).
You can then step through the variation to make it visible on the board.
</p>
<ul>
<li>Auto-dispay comment (Load Options) causes automatic pop up whenever you encounter a commented move.</li>
</ul>
</td><td valign ="top">
<img src="Comment.png">
</td></tr></table>

<h3><a name="tag-A5">Engine output</h3>
<p>
As its name suggests, the engine-output window is only useful when an engine is involved.
(This an be can engine you connect to through an Internet Chess Server, however.)
Engines print how they think the game would continue if poth sides play the moves the engine considers best,
the so called 'Principal Variation',
at ever increasing search depth.
These PV lines are diplayed in the engine-output window, preceded by the search depth at which they were found,
and the score assigned to them, (plus the less interesting time and number of positions searched).
</p>
<table cellpadding="20"><tr><td valign="top">
<img src="4.4.0/EngOutXB.png">
</td><td valign ="top">
<p>
Left clicks in the Engine Output window are reserved for the normal editing functions,
although in this case only selecting for the purpose of copying would be a useful action.
The right button can be used to click on a PV indicated by the engine.
In this case that PV will be played out on the chess board when you move the mouse vertically with the button still down
(i.e. use the main board as 'variation board').
The behavior in analysis mode is a bit different from that in other modes:
when you release the button, the position on the variation board becomes the new position to analyse,
and all moves leading up to it will be added to the game.
Because the variation walk will start in the position after the first PV move there,
a static click on a PV would just make you play the suggested engine move.
In other modes, walking a PV will start at the end of the PV, and never change the game.
When you release the button, you will simply jump back to the original game.
When an engine produces a move, XBoard would force you back to the real game anyway, even without releasing the button.
</p>
<p>
Some engines support a multi-PV mode, where they don't only give continuations for the best move,
but also for second-best, or more.
In this case XBoard will print a header line above the PV's containing the words 'fewer' and 'more',
and when you right-click on those, the number of moves the engine calculates will be decreased or increased.
</p>
</td></tr></table>

<h3><a name="tag-A4">Move list</h3>
<table cellpadding="20"><tr><td valign="top">
<p>
The Move List contains the game in SAN notation, with or without score/depth information included as comments to the moves.
Left clicks in the Move List are reserved for the normal editing functions,
although in this case only selecting for the purpose of copying would be a useful action.
Right-clicking on a move (in WinBoard: left-double-clicking) will navigate you to the position after that move
(i.e. display that position on the board, and allow you to step through the game from there).
</p>
<ul>
<li>Scores in Move List (General Options) enables inclusion of engine score/depth</li>
</ul>
</td><td valign ="top">
<img src="4.6.0/History.png">
</td></tr></table>

<h3><a name="tag-A6">Evaluation graph</h3>
<table cellpadding="20"><tr><td valign="top">
<img src="4.6.0/Zoom.png">
</td><td valign ="top">
<p>
The evaluation graph displays how the engine score evolved over the game,
either as a histogram, or (when space gets too tight), as a drawn line.
If two engines are playing, each side has its own histogram / line,
distinguishable by their color.
Clicking in the graph navigates you to the position corrsponding to the point where you clicked.
</p>
<ul>
<li>Zoom factor (General Options) set magnifiation of the {-1, 1} score range</li>
<li>-evalThreshold (command-line option) minimum score to be considered different from 0</li>
</ul>
</td></tr></table>

<h3><a name="tag-A1">Game List</h3>
<p>
The Game List displays a table of contents of the urrently loaded PGN file as a listbox.
The lines in the listbox are composed of the PGN tags of the game,
in a user-configurable way.
Clicking on such a line would load the corresponding game, so you can navigate through it.
The currently loaded game will be highlighted in the list.
Using Up or Down arrow keys while the Game List window has focus will move the highlight to the previous / next game,
while typing &lt;Enter> will load the game.
</p>
<table cellpadding="20"><tr><td valign="top">
<p>
The Game List window includes a number of controls at the bottom,
to select a subset of the games for display in the window.
A 'Filter' field allows you to enter a text, where then only header lines containing that text will b displayed.
You can furthermore select on positions occurring in the game,
through the 'Find Position' button.
When you do that, only those games containing the position currently on the board
(or enough like it, according to the matching criterea you specified in the Load Game Options dialog,
reachable through the 'Thresholds' button)
will remain in the list, in that case.
</p>
<ul>
<li>(Game List Options) selects the PGN tags included in the header</li>
<li>(Load Options) can set all kind of filter and position-search criteria</li>
</ul>
</td><td valign ="top">
<img src="NewGameList.png">
</td></tr></table>

<h3><a name="tag-A3">Tags window</h3>
<p>
The Tags window is a text window that supports normal editing functions,
but otherise has no special functions.
It can be used to view or edit the PGN tags of the stored game.
To save any changes brought about by editing, you have to press a button at the bottom of the window.
</p>
<ul>
<li>Auto-display Tags (Load Options) cause automatic popup on loading a game</li>
</ul>

<h3><a name="tag-A1">Edit book</h3>
<p>
The Tags window is a text window that supports normal editing functions,
but otherise has no special functions.
It displays moves available for the current position (displayed on the board) in the currently installed opening book.
To save any changes brought about by editing, you have to press a button at the bottom of the window.
</p>
<ul>
<li>Polyglot Book (Common Engine Options) determines which book file we edit</li>
</ul>

<h3></h3>
<p>
</p>