Updating documentation to reflect changes in 2.6.0, and addition of release notes (announce-2.6.0.txt).

git-svn-id: https://circuit.svn.sourceforge.net/svnroot/circuit/trunk@67 70edf91d-0b9e-4248-82e7-2488d7716404

doc/en/contents.xml

@@ -23,6 +23,7 @@
 		<tocitem target="subcirc" text="Subcircuits">
 			<tocitem target="subcirc_creating" text="Creating circuits" />
 			<tocitem target="subcirc_using" text="Using subcircuits" />
+			<tocitem target="subcirc_appear" text="Editing subcircuit appearance" />
 			<tocitem target="subcirc_debug" text="Debugging subcircuits" />
 			<tocitem target="subcirc_library" text="Logisim libraries" />
 		</tocitem>
@@ -129,6 +130,7 @@
 		<tocitem target="arith_negator" text="Negator" />
 		<tocitem target="arith_comparator" text="Comparator" />
 		<tocitem target="arith_shifter" text="Shifter" />
+		<tocitem target="arith_bitadder" text="Bit Adder" />
 	  </tocitem>
 	  <tocitem target="mem" text="Memory library">
 		<tocitem target="mem_flipflops" text="D/T/J-K/S-R Flip-Flop" />

doc/en/guide/menu/edit.html

@@ -60,6 +60,41 @@ the clipboard.</p></dd>
 <dt><strong>Select All</strong></dt>
 <dd><p>Selects all components in the current circuit.</p></dd>
 
+<dt><strong>Raise Selection</strong></dt>
+<dd><p>Available only when editing how a circuit's appearance, this menu item
+raises the currently selected object(s) to be drawn
+on top of an object that currently overlaps the selection. If the selected
+object is overlapped by several objects, it is raised only to be above the lowest
+one; select the menu item repeatedly until it is in the order it
+should be.</p>
+
+<p>(Determining whether two arbitrary objects overlap is difficult. Logisim uses
+an algorithm of selecting several random points in each of the two objects
+and seeing if any point is also in the other object. Sometimes it will fail to
+detect an overlap if the overlap is small &mdash; say, less than 5% of
+either of the objects.)</p></dd>
+
+<dt><strong>Lower Selection</strong></dt>
+<dd><p>Available only when editing a circuit's appearance, this menu item
+lowers the currently selected object(s) to be drawn below an object that the
+object currently overlaps. If it overlaps several objects, it is lowered only
+to be below the highest one; select the menu item repeatedly until it is in the
+order it should be.</p></dd>
+
+<dt><strong>Add Vertex</strong></dt>
+<dd><p>Available only when editing a circuit's appearance and a point has been
+selected on a line, polyline, or polygon, this menu item inserts a new vertex
+onto the shape. Previous to insertion, the selected point is drawn as a
+diamond.</p></dd>
+
+<dt><strong>Remove Vertex</strong></dt>
+<dd><p>Available only when editing a circuit's appearance and an existing
+vertex has been selected on a polyline or polygon, this menu item removes
+the selected vertex. Previous to deletion, the selected vertex is drawn as a
+diamond within the square representing the vertex. Logisim will not permit
+removing a vertex on a polygon with only three vertices or on a polyline with
+only two vertices.</p></dd>
+
 </dl>
 
 <p><strong>Next:</strong> <a href="project.html">The Project menu</a>.</p>

doc/en/guide/menu/project.html

@@ -36,11 +36,29 @@ circuits within the project, as displayed in the explorer pane.</p></dd></dd>
 
 <dt><strong>Set As Main Circuit</strong></dt>
 <dd><p>Sets the currently displayed circuit to be the project's
-``main circuit.'' (This menu item will be grayed out if the
+<q>main circuit.</q> (This menu item will be grayed out if the
 current circuit is already the project's main circuit.)
 The only significance of the main circuit is that it is the
 circuit that first appears when a project file is opened.</p></dd>
 
+<dt><strong>Edit Circuit Layout</strong></dt>
+<dd><p>Switches to allow you to edit how the layout of components that
+determines how the circuit works. This is what the program does when it starts,
+and you will edit circuit layouts most often using Logisim, so this menu item
+is normally disabled.</p></dd>
+
+<dt><strong>Edit Circuit Appearance</strong></dt>
+<dd><p>Switches to allow you to edit how the circuit will be represented
+when it is used as a subcircuit within another circuit. By default, the circuit
+is represented as a rectangle with a gray <q>notch</q> on its north end, but
+this menu option allows you to draw a different appearance for the
+subcircuit.</p></dd>
+
+<dt><strong>Revert To Default Appearance</strong></dt>
+<dd><p>If you've edited the circuit's appearance, this menu item reverts
+the appearance back to the default rectangle-with-notch appearance.
+The menu item is enabled only when editing the circuit's appearance.</p></dd>
+
 <dt><strong>Remove Circuit</strong></dt>
 <dd><p>Removes the currently displayed circuit from the project. 
 Logisim will prevent you from removing circuits that are used as
@@ -85,7 +103,8 @@ not included in the unique and recursive counts.</p></dd>
 <dd><p>When checked, this menu item indicates that a small toolbar
 should be displayed above the explorer pane, allowing the user
 easy access to adding, renaming, reordering, and removing circuits
-from a project.</p></dd>
+from a project. The toolbar also supports switching between editing a circuit's
+layout and its appearance.</p></dd>
 
 <dt><strong>Options...</strong></dt>
 <dd><p>Opens the <a href="../opts/index.html">Project Options

doc/en/guide/subcirc/appear.html

@@ -0,0 +1,132 @@
+<html>
+<head>
+<title>Editing subcircuit appearance</title>
+</head>
+
+<body bgcolor="FFFFFF">
+
+<h1>Editing subcircuit appearance</h1>
+
+<h2>Default appearance</h2>
+
+<p>By default, when a subcircuit is placed within a larger circuit, it is drawn
+as a rectangle with a notch indicating the north end of the subcircuit's
+layout. Pins will be placed on the rectangle's border based on their facing:
+Pins that face east in the layout (and typically appear on the west side
+of the layout) will be placed on the rectangle's west side,
+according to their top-down ordering in the layout.
+Pins that face south in the layout (typically toward the north side of the layout)
+will be placed on the rectangle's north side, according to the left-to-right
+ordering in the layout.</p>
+
+<p>The default rectangle can optionally include some letters that will appear
+in the middle of the rectangle. To specify this, select the selection tool
+(<img src="../../icons/select.gif">) and click the background of the circuit's
+layout. This will show the circuit attributes in the attribute table, including
+the Label, Label Facing, and Label Font attributes.
+The value of the Label attribute will be drawn in the rectangle's center;
+the Label Facing attribute customizes which direction the text is drawn,
+and of course the Label Font attribute customizes the font used.</p>
+
+<h2>Customized appearance</h2>
+
+<p>The default appearance is very usable, and indeed Logisim existed for many
+years with no other option. If, however, you prefer that the subcircuit be
+drawn differently, you can select <q>Edit Circuit Appearance</q> from the
+Project menu, and Logisim's interface will switch from its regular
+layout-editing interface to an interface for drawing the circuit's
+appearance. Below, we are editing the 2:1 multiplexer's appearance so that
+it is drawn with the usual trapezoid rather than a rectangle.
+(You can see the project toolbar just below the regular toolbar.
+This can be enabled through the Project menu, and it allows quick switching
+between editing the layout and appearance.)</p>
+
+<blockquote><img src="custom-appear.png" width="386" height="307"></blockquote>
+
+<p>With the appearance for the 2:1 multiplexer drawn as above,
+the layout for the 4:1 multiplexer would then appear as the following.</p> 
+
+<blockquote><img src="custom-layout.png" width="386" height="307"></blockquote>
+
+<p>The appearance editor is like a traditional drawing program, but there
+are a few special symbols for indicating how the drawing works when placed
+into a circuit's layout. These special symbols cannot be removed.</p>
+
+<ul>
+
+<li><p>The green circle with a line coming out of it, which we'll call the <q>ankh.</q>
+There is exactly one ankh in each subcircuit appearance.
+Each component in a circuit has a single point identifying its location;
+a user sees this when creating a new component:
+The mouse click identifies just a single location, and the component is placed
+relative to that (usually with the primary output at the mouse's location)
+The ankh identifies the mouse's location relative to the overall drawing
+when the subcircuit is created.</p>
+
+<p>The ankh also identifies the appearance's facing, as indicated by the
+direction the ankh's line points from its circle. When placing the subcircuit
+into a layout, the user can change the subcircuit's facing; the ankh's facing
+indicates in which direction the appearance is oriented. In our example, the
+ankh is facing east, and each instance of the subcircuit in the 4:1 multiplexer
+is also facing east, so they are all drawn in the same orientation as the 2:1
+multiplexer's appearance.</p></li>
+
+<li><p>The blue circles and squares with dots in them are the subcircuit's
+<q>ports.</q> There are exactly as many ports as there are input and output
+pins in the circuit.
+Ports corresponding to inputs are drawn as squares, while ports corresponding
+to outputs are drawn as circles.
+Each port indicates how a wire connecting into the
+circuit will correspond to an input or output pin within the layout.</p>
+
+<p>When you select a port, Logisim will indicate the corresponding pin
+by popping up a miniature diagram of the layout in the window's bottom right
+corner, with the corresponding pin(s) drawn in blue. This does not happen when
+all ports are selected.</p></li>
+
+</ul>
+
+<p>The toolbar contains tools for adding additional shapes.</p>
+
+<table><tbody>
+<tr><td valign="top"><img src="../../icons/select.gif" width="16" height="16"></td>
+  <td>Select, move, copy, and paste shapes.</td></tr>
+<tr><td valign="top"><img src="../../icons/text.gif" width="16" height="16"></td>
+  <td>Add or edit text.</td></tr>
+<tr><td valign="top"><img src="../../icons/drawline.gif" width="16" height="16"></td>
+  <td>Create a line segment. Shift-drag keeps the line at 45&deg; angles.</td></tr>
+<tr><td valign="top"><img src="../../icons/drawcurv.gif" width="16" height="16"></td>
+  <td>Create a quadratic Bezier curve.
+  For the first drag, where you specify the curve's endpoints,
+  shift-drag keeps the endpoints at a 45&deg; angle from each other.
+  Then you click to indicate the control point's location;
+  shift-click ensures the curve is symmetric,
+  while alt-click draws the curve through the control point.</td></tr>
+<tr><td valign="top"><img src="../../icons/drawplin.gif" width="16" height="16"></td>
+  <td>Create a sequence of connected lines, whose vertices are indicated by
+  a succession of clicks. Shift-clicking ensures that the vertex is at a 45&deg;
+  angle from the previous one. Double-click or press the Enter key to complete the
+  shape.</td></tr>
+<tr><td valign="top"><img src="../../icons/drawrect.gif" width="16" height="16"></td>
+  <td>Create a rectangle through dragging from one corner to the opposite corner.
+  Shift-drag to create a square, and alt-drag to create the rectangle starting
+  from the center.</td></tr>
+<tr><td valign="top"><img src="../../icons/drawrrct.gif" width="16" height="16"></td>
+  <td>Create a rectangle with rounded corners through dragging from one corner to the opposite corner.
+  Shift-drag to create a square, and alt-drag to create the rectangle starting
+  from the center.</td></tr>
+<tr><td valign="top"><img src="../../icons/drawoval.gif" width="16" height="16"></td>
+  <td>Create an oval through dragging from one corner of its bounding box to the opposite corner.
+  Shift-drag to create a circle, and alt-drag to create the circle starting
+  from the center.</td></tr>
+<tr><td valign="top"><img src="../../icons/drawpoly.gif" width="16" height="16"></td>
+  <td>Create an arbitrary polygon, whose vertices are indicated by
+  a succession of clicks. Shift-clicking ensures that the vertex is at a 45&deg;
+  angle from the previous one. Double-click, press the Enter key, or click the
+  starting vertex to complete the shape.</td></tr>
+</tbody></table>
+
+<p><strong>Next:</strong> <a href="using.html">Using subcircuits</a>.</p>
+
+</body>
+</html>

doc/en/guide/subcirc/index.html

@@ -24,6 +24,7 @@ facilitate debugging.</p>
 
 <blockquote><a href="creating.html">Creating circuits</a>
 	<br><a href="using.html">Using subcircuits</a>
+	<br><a href="appear.html">Editing subcircuit appearance</a>
 	<br><a href="debug.html">Debugging subcircuits</a>
 	<br><a href="library.html">Logisim libraries</a>
 </blockquote>

doc/en/guide/subcirc/using.html

@@ -67,7 +67,7 @@ deleting, or moving them) will rearrange them also in the containing
 circuit. Thus, if you change any pins in a circuit, you will also
 need to edit any circuits using it as a subcircuit.</p>
 
-<p><strong>Next:</strong> <a href="debug.html">Debugging subcircuits</a>.</p>
+<p><strong>Next:</strong> <a href="appear.html">Editing subcircuit appearance</a>.</p>
 
 </body>
 </html>

doc/en/libs/arith/bitadder.html

@@ -0,0 +1,79 @@
+<html>
+<head>
+<title>Bit Adder</title>
+</head>
+
+<body bgcolor="FFFFFF">
+
+<h1><img align="center" height="32" width="32" src="../../icons/bitadder.gif">
+<em>Bit Adder</em></h1>
+
+<p><table>
+<tr><td><strong>Library:</strong></td>
+	<td><a href="index.html">Arithmetic</a></td></tr>
+<tr><td><strong>Introduced:</strong></td>
+	<td>2.6.0</td></tr>
+<tr><td valign="top"><strong>Appearance:</strong></td>
+	<td valign="top"><img src="../images/bitadder.png"></td></tr>
+</table></p>
+
+<h2>Behavior</h2>
+
+<p>The component determines how many 1 bits are in its input(s) and emits the
+total number of 1 bits on its output. For example, given the 8-bit input 10011101,
+the output would be 5, since there are five 1-bits in the input
+(the first, the last, and a string of three bits in the middle).</p>
+
+<p>If any of the input bits are floating or error values, then the output will
+contain error bits in the output corresponding to the range of possible outputs
+depending on whether those floating/error values are counted as zeroes or ones.
+For instance, if the 14-bit input is 111x10110x1101, then the output must be
+at least 9 (if the x's are interpreted as zeroes
+and at most 11 (if they are interpreted as ones).
+Thus, the output will be 10EE: The upper two bits will be 1 and 0 since all integers
+between 9 and 11 have 1 and 0 as their top two bits, but the lower two bits are EE
+since integers between 9 and 11 vary within these bits.</p> 
+
+<h2>Pins</h2>
+
+<dl>
+
+<dt>West edge (inputs, bit width matches Data Bits attribute)</dt>
+<dd>The inputs whose 1 bits are to be counted. The number of inputs is based
+on the Number of Inputs attribute.</dd>
+
+<dt>East edge (output, bit width computed as described below)</dt>
+<dd>The number of input bits which are 1. The bit width of the output is the
+minimum number of bits to store the maximum possible value (which would be
+the product of the Data Bits attribute and the Number of Inputs attribute).</dd>
+
+</dl>
+
+<h2>Attributes</h2>
+
+<p>When the component is selected or being added,
+the digits '0' through '9' alter its <q>Number of Inputs</q> attribute and
+Alt-0 through Alt-9 alter its <q>Data Bits</q> attribute.</p>
+
+<dl>
+
+<dt>Data Bits</dt>
+<dd>The bit width of the input(s).</dd>
+
+<dt>Number of Inputs</dt>
+<dd>The number of input values.</dd>
+
+</dl>
+
+<h2>Poke Tool Behavior</h2>
+
+<p>None.</p>
+
+<h2>Text Tool Behavior</h2>
+
+<p>None.</p>
+
+<p><a href="../index.html">Back to <em>Library Reference</em></a></p>
+
+</body>
+</html>

doc/en/libs/arith/index.html

@@ -26,6 +26,8 @@ two's-complement values.</p>
 	<td><a href="comparator.html">Comparator</a></td></tr>
 <tr><td align="right"><a href="shifter.html"><img border="0" src="../../icons/shifter.gif"></a></td>
 	<td><a href="shifter.html">Shifter</a></td></tr>
+<tr><td align="right"><a href="bitadder.html"><img border="0" src="../../icons/bitadder.gif"></a></td>
+	<td><a href="bitadder.html">Bit Adder</a></td></tr>
 </table>
 
 <p><a href="../index.html">Back to <em>Library Reference</em></a></p>

doc/en/libs/index.html

@@ -111,6 +111,8 @@ documented in this reference material.</p>
 	<td><a href="arith/comparator.html">Comparator</a></td></tr>
 <tr><td align="right"><a href="arith/shifter.html"><img border="0" src="../icons/shifter.gif"></a></td>
 	<td><a href="arith/shifter.html">Shifter</a></td></tr>
+<tr><td align="right"><a href="arith/bitadder.html"><img border="0" src="../icons/bitadder.gif"></a></td>
+	<td><a href="arith/bitadder.html">Bit Adder</a></td></tr>
 
 <tr><td colspan="2"><br><font size="+1"><b><a href="mem/index.html">Memory library</a></b></font></td></tr>
 <tr><td align="right"><a href="mem/flipflops.html" style="text-decoration: none">

doc/en/map.jhm

@@ -23,6 +23,7 @@
 	<mapID target="subcirc" url="guide/subcirc/index.html" />
 	<mapID target="subcirc_creating" url="guide/subcirc/creating.html" />
 	<mapID target="subcirc_using" url="guide/subcirc/using.html" />
+	<mapID target="subcirc_appear" url="guide/subcirc/appear.html" />
 	<mapID target="subcirc_debug" url="guide/subcirc/debug.html" />
 	<mapID target="subcirc_library" url="guide/subcirc/library.html" />
 	<mapID target="bundles" url="guide/bundles/index.html" />
@@ -113,6 +114,7 @@
 	<mapID target="arith_negator" url="libs/arith/negator.html" />
 	<mapID target="arith_comparator" url="libs/arith/comparator.html" />
 	<mapID target="arith_shifter" url="libs/arith/shifter.html" />
+	<mapID target="arith_bitadder" url="libs/arith/bitadder.html" />
 	<mapID target="mem" url="libs/mem/index.html" />
 	<mapID target="mem_flipflops" url="libs/mem/flipflops.html" />
 	<mapID target="mem_register" url="libs/mem/register.html" />

notes/2.6.0/announce-2.6.0.txt

@@ -0,0 +1,45 @@
+Feature: You can customize how a subcircuit component will be drawn, in place of the default rectangle-with-notch appearance earlier.
+
+Feature: Multiplexers, demultiplexers, decoders, and priority encoders all support 5 "Select Bits."
+
+Feature: The Arithmetic library now includes a "Bit Adder" which computes the number of 1 bits in its input(s).
+
+Feature: The I/O library's LED has an "Off Color" attribute.
+
+Bug fix: After removing a circuit from the project, an Undo would place the removed circuit at the end of the project's list rather than back in its previous location.
+
+Bug fix: When loading more than 4,096 memory entries into RAM or ROM, if the 4,096th entry (or a multiple of 4096 entries) was at the end of a line in the text file, all subsequent entries were ignored.
+
+Bug fix: When the circuit is scaled using the zoom controls, tool tips would show up in the wrong location.
+
+Bug fix: A "ConcurrentModificationException" was observed from the EventSourceWeakSupport class. It was changed to guarantee that it does not occur there.
+
+Bug fix: Sometimes a diagonal line would appear across the layout when you selected a different component to be added.
+
+Interface change: The menu shortcut for moving up in the state hierarchy is now MenuKey+Shift+Up, since MenuKey+Up is used for raising the selection.
+
+Interface change: When the grid is being shown and the zoom factor is 200% or more, each grid dot is actually a square of several pixels.
+
+Interface change: The project toolbar is drawn slightly differently, with a darker "add" icon, and of course the added elements for selecting to edit the layout or the appearance. Behind the scenes, the icons are drawn differently - this will likely be most apparent under MacOS X, where it was fairly ugly before.
+
+Interface change: Subcircuits are drawn (by default) with a slightly different notch to adapt to the quadratic Bezier curve supported by the customized appearance module.
+
+Architectural change: Subcircuits are implemented using the newer logisim.instance API rather than the deprecated logisim.comp API.
+
+
+TODO:
+
+alt when creating curve creates curve going through the control point
+refine point containment in text
+respect shift/alt when moving handle - depends on shape
+cut/copy sometimes does not work immediately after selecting view
+don't create Appearance view until it is actually needed
+ensure that ports and origin are always at top of appearance
+When a component is selected, sometimes an attempt to change to an attribute in the attribute table changes the attribute, but the table is not updated to reflect it.
+save appearance zoom/show grid as part of file
+check: start but don't finish editing attribute, then change attribute list
+
+Deferred:
+
+refine when the Raise/Lower menu option is enabled
+probe tool - adds display of probe value inside circuit layout