--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/API.txt	Fri Dec 31 13:41:08 2010 +0100
@@ -0,0 +1,37 @@
+As well as attaching popup behavior to links, 
+Popups API provides javascript function for creating in-window popup messages.
+
+Popups.message(title, message)
+  Produces a simple modal box with the title, message and "OK", "Cancel" buttons.
+  
+Popups.open(title, body, buttons, width)
+  More powerful, allows you to specify what the buttons are and what they do.
+  buttons is a hash of hash, with button title and function.
+  * Example:
+  Drupal.popups.open( 
+    Drupal.t('Warning: Please Confirm'), 
+    Drupal.t("There are unsaved changes on this page, which you will lose if you continue."),
+    { 
+      'popup_save': {
+        title: Drupal.t('Save Changes'), 
+        func: function(){Drupal.popups.savePage(element, options);}
+      },
+      'popup_submit': {
+        title: Drupal.t('Continue'), 
+        func: function(){Drupal.popups.removePopup(); Drupal.popups.openPath(element, options);}
+      },
+      'popup_cancel': {
+        title: Drupal.t('Cancel'), func: Drupal.popups.close;
+      } 
+    }
+  );
+
+// TODO - make a more useful api function for opening a path.
+Popups.openPath = function(element, options, parent)
+ * @param element
+ *   Element that was clicked to open the popups.
+ * @param options
+ *   Hash of options controlling how the popups interacts with the underlying page.
+ * @param parent
+ *   If path is being opened from inside another popup, that popup is the parent.
+