Index: /CKEditor/branches/versions/3.1.x/CHANGES.html
===================================================================
--- /CKEditor/branches/versions/3.1.x/CHANGES.html	(revision 4313)
+++ /CKEditor/branches/versions/3.1.x/CHANGES.html	(revision 4314)
@@ -69,4 +69,7 @@
 		<li><a href="http://dev.fckeditor.net/ticket/4387">#4387</a> : Right clicking in Kama skin can lead to a javascript error.</li>
 		<li><a href="http://dev.fckeditor.net/ticket/4397">#4397</a> : Wisiwig mode will cause the host page scroll.</li>
+		<li><a href="http://dev.fckeditor.net/ticket/4385">#4385</a> : Fixed editor's auto adjusting on DOM structure were confusing the dirty checking mechanism.</li>
+		<li><a href="http://dev.fckeditor.net/ticket/4397">#4397</a> : Fixed regression of [3816] where turn on design mode is causing Firefox3 to scroll the host page.</li>
+		<li><a href="http://dev.fckeditor.net/ticket/4254">#4254</a> : Added basic API sample.</li> 
 	</ul>
 	<h3>
Index: /CKEditor/branches/versions/3.1.x/_samples/api.html
===================================================================
--- /CKEditor/branches/versions/3.1.x/_samples/api.html	(revision 4314)
+++ /CKEditor/branches/versions/3.1.x/_samples/api.html	(revision 4314)
@@ -0,0 +1,126 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!--
+Copyright (c) 2003-2009, CKSource - Frederico Knabben. All rights reserved.
+For licensing, see LICENSE.html or http://ckeditor.com/license
+-->
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+	<title>API usage - CKEditor Sample</title>
+	<script type="text/javascript" src="sample.js"></script>
+	<script id="headscript" type="text/javascript">
+	//<![CDATA[
+
+// The instanceReady event is fired when an instance of CKEditor has finished 
+// its initialization.
+CKEDITOR.on( 'instanceReady', function( ev )
+	{
+		// Show the editor name and description in the browser status bar.
+		document.getElementById('eMessage').innerHTML = '<p>Instance "' + ev.editor.name + '" loaded.<\/p>' ;
+
+		// Show this sample buttons.
+		document.getElementById('eButtons').style.visibility = '' ;
+	});
+
+function InsertHTML()
+{
+	// Get the editor instance that we want to interact with.
+	var oEditor = CKEDITOR.instances.editor1 ;
+	var value = document.getElementById( 'plainArea' ).value ;
+
+	// Check the active editing mode.
+	if (oEditor.mode == 'wysiwyg' )
+	{
+		// Insert the desired HTML.
+		oEditor.insertHtml( value ) ;
+	}
+	else
+		alert( 'You must be on WYSIWYG mode!' ) ;
+}
+
+function SetContents()
+{
+	// Get the editor instance that we want to interact with.
+	var oEditor = CKEDITOR.instances.editor1 ;
+	var value = document.getElementById( 'plainArea' ).value ;
+
+	// Set the editor contents (replace the actual one).
+	oEditor.setData( value ) ;
+}
+
+function GetContents()
+{
+	// Get the editor instance that we want to interact with.
+	var oEditor = CKEDITOR.instances.editor1 ;
+
+	// Get the editor contents
+	alert( oEditor.getData() ) ;	
+}
+
+function ExecuteCommand( commandName )
+{
+	// Get the editor instance that we want to interact with.
+	var oEditor = CKEDITOR.instances.editor1 ;
+
+	// Check the active editing mode.
+	if (oEditor.mode == 'wysiwyg' )
+	{
+		// Execute the command.
+		oEditor.execCommand( commandName ) ;
+	}
+	else
+		alert( 'You must be on WYSIWYG mode!' ) ;
+}
+
+function CheckDirty()
+{
+	// Get the editor instance that we want to interact with.
+	var oEditor = CKEDITOR.instances.editor1 ;
+	alert( oEditor.checkDirty() ) ;
+}
+
+function ResetDirty()
+{
+	// Get the editor instance that we want to interact with.
+	var oEditor = CKEDITOR.instances.editor1 ;
+	oEditor.resetDirty() ;
+	alert( 'The "IsDirty" status has been reset' ) ;
+}
+
+	//]]>
+	</script>
+</head>
+<body>
+	<div id="html">
+		<form action="sample_posteddata.php" method="post">
+		<p>
+		This sample shows how to use the CKeditor JavaScript API to interact with the editor
+		at runtime.</p>
+		<textarea id="editor1" name="editor1" rows="10" cols="80">&lt;p&gt;This is some &lt;strong&gt;sample text&lt;/strong&gt;. You are using &lt;a href="http://www.fckeditor.net/"&gt;CKEditor&lt;/a&gt;.&lt;/p&gt;</textarea>
+		<script type="text/javascript">
+		//<![CDATA[
+			// Replace the <textarea id="editor1"> with an CKEditor instance.
+			var editor = CKEDITOR.replace( 'editor1');
+		//]]>
+		</script>
+		<div id="eMessage">
+			
+		</div>
+		<div id="eButtons" style="visibility: hidden">
+			<input type="button" value="Insert HTML" onclick="InsertHTML();" />
+			<input type="button" value="Set Editor Contents" onclick="SetContents();" />
+			<input type="button" value="Get Editor Contents (XHTML)" onclick="GetContents();" />
+			<br />
+			<textarea id="plainArea" cols="80" rows="3">&lt;h2&gt;Test&lt;/h2&gt;&lt;p&gt;This is some &lt;a href="/Test1.html"&gt;sample&lt;/a&gt; HTML&lt;/p&gt;</textarea>
+			<br />
+			<br />
+			<input type="button" value='Execute "bold" Command' onclick="ExecuteCommand('bold');" />
+			<input type="button" value='Execute "link" Command' onclick="ExecuteCommand('link');" />
+		<br />
+		<br />
+		<input type="button" value="checkDirty()" onclick="CheckDirty();" />
+		<input type="button" value="resetDirty()" onclick="ResetDirty();" />
+		</div>
+		</form>
+	</div>
+</body>
+</html>
Index: /CKEditor/branches/versions/3.1.x/_samples/index.html
===================================================================
--- /CKEditor/branches/versions/3.1.x/_samples/index.html	(revision 4313)
+++ /CKEditor/branches/versions/3.1.x/_samples/index.html	(revision 4314)
@@ -34,4 +34,5 @@
 		<li><a href="divreplace.html">Replace DIV elements on the fly</a>&nbsp; </li>
 		<li><a href="ajax.html">Create and destroy editor instances for Ajax applications</a></li>
+		<li><a href="api.html">Basic usage of the API</a></li>
 		<li><a href="api_dialog.html">Using the JavaScript API to customize dialogs</a></li>
 		<li><a href="enterkey.html">Using the "Enter" key in CKEditor</a></li>
Index: /CKEditor/branches/versions/3.1.x/_source/plugins/wysiwygarea/plugin.js
===================================================================
--- /CKEditor/branches/versions/3.1.x/_source/plugins/wysiwygarea/plugin.js	(revision 4313)
+++ /CKEditor/branches/versions/3.1.x/_source/plugins/wysiwygarea/plugin.js	(revision 4314)
@@ -121,4 +121,11 @@
 			}, 0, this );
 		}
+	}
+
+	// DOM modification here should not bother dirty flag.(#4385)
+	function restoreDirty( editor )
+	{
+		if( !editor.checkDirty() )
+			setTimeout( function(){ editor.resetDirty() } );
 	}
 
@@ -144,4 +151,5 @@
 			 && !path.block )
 		{
+			restoreDirty( editor );
 			var bms = selection.createBookmarks(),
 				fixedBlock = range.fixBlock( true,
@@ -194,4 +202,5 @@
 		if ( lastNode && lastNode.getName && ( lastNode.getName() in nonExitableElementNames ) )
 		{
+			restoreDirty( editor );
 			var paddingBlock = editor.document.createElement(
 					( CKEDITOR.env.ie && enterMode != CKEDITOR.ENTER_BR ) ?
@@ -354,9 +363,5 @@
 						}
 						else
-							// Avoid opening design mode in a frame window thread,
-							// which will cause host page scrolling.(#4397)
-							setTimeout( function(){
-								domDocument.$.designMode = 'on';
-							}, 0 );
+							domDocument.designMode = 'on';
 
 						// IE, Opera and Safari may not support it and throw
@@ -367,24 +372,4 @@
 						domWindow	= editor.window		= new CKEDITOR.dom.window( domWindow );
 						domDocument	= editor.document	= new CKEDITOR.dom.document( domDocument );
-
-						// Gecko need a key event to 'wake up' the editing
-						// ability when document is empty.(#3864)
-						var firstNode = domDocument.getBody().getFirst();
-						if ( CKEDITOR.env.gecko
-							&& firstNode && firstNode.is
-							&& firstNode.is( 'br' ) && firstNode.hasAttribute( '_moz_editor_bogus_node' ) )
-						{
-							var keyEventSimulate = domDocument.$.createEvent( "KeyEvents" );
-							keyEventSimulate.initKeyEvent( 'keypress', true, true, domWindow.$, false,
-								false, false, false, 0, 32 );
-							domDocument.$.dispatchEvent( keyEventSimulate );
-							var bogusText = domDocument.getBody().getFirst() ;
-							// Compensate the line maintaining <br> if enterMode is not block.
-							if ( editor.config.enterMode == CKEDITOR.ENTER_BR )
-								domDocument.createElement( 'br', { attributes: { '_moz_dirty' : "" } } )
-									.replace( bogusText );
-							else
-								bogusText.remove();
-						}
 
 						// Gecko/Webkit need some help when selecting control type elements. (#3448)
@@ -427,4 +412,30 @@
 						focusTarget.on( 'focus', function()
 							{
+								// Gecko need a key event to 'wake up' the editing
+								// ability when document is empty.(#3864)
+								if ( CKEDITOR.env.gecko )
+								{
+									var first = body;
+									while( first.firstChild )
+										first = first.firstChild;
+
+									if( !first.nextSibling
+										&& ( 'BR' == first.tagName )
+										&& first.hasAttribute( '_moz_editor_bogus_node' ) )
+									{
+										var keyEventSimulate = domDocument.$.createEvent( "KeyEvents" );
+										keyEventSimulate.initKeyEvent( 'keypress', true, true, domWindow.$, false,
+											false, false, false, 0, 32 );
+										domDocument.$.dispatchEvent( keyEventSimulate );
+										var bogusText = domDocument.getBody().getFirst() ;
+										// Compensate the line maintaining <br> if enterMode is not block.
+										if ( editor.config.enterMode == CKEDITOR.ENTER_BR )
+											domDocument.createElement( 'br', { attributes: { '_moz_dirty' : "" } } )
+												.replace( bogusText );
+										else
+											bogusText.remove();
+									}
+								}
+
 								editor.focusManager.focus();
 							});
