Changeset 1144 for trunk/modules


Ignore:
Timestamp:
12/24/08 15:34:25 (11 years ago)
Author:
ray
Message:

Updated inline documentation for XinhaCore?.js and XinhaDialog?.js

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/modules/Dialogs/XinhaDialog.js

    r1141 r1144  
    2626 
    2727/** Xinha Dialog 
    28  * 
    29  * 
    30  * @param editor Xinha object     
    31  * @param html string  
    32  * @param localizer string the "context" parameter for Xinha._lc(), typically the name of the plugin 
    33  * @param size object with two possible properties of the size: width & height as int, where height is optional 
    34  * @param options dictionary with optional boolean attributes 'modal', 'closable', 'resizable', and 'centered', as well as integer attribute 'layer' 
     28 *   
     29 * @constructor 
     30 * @version $LastChangedRevision$ $LastChangedDate$ 
     31 * @param {Xinha} editor Xinha object     
     32 * @param {String} html string The HTML for the dialog's UI 
     33 * @param {String} localizer string the "context" parameter for Xinha._lc(), typically the name of the plugin 
     34 * @param {Object} size object with two possible properties of the size: width & height as int, where height is optional 
     35 * @param {Object} options dictionary with optional boolean attributes 'modal', 'closable', 'resizable', and 'centered', as well as integer attribute 'layer' 
     36 
    3537 */ 
    3638Xinha.Dialog = function(editor, html, localizer, size, options) 
    3739{ 
    3840  var dialog = this; 
     41   
     42  /** Used for dialog.getElementById() 
     43   * @type Object 
     44   * @private 
     45   */ 
    3946  this.id    = { }; 
     47  /** Used for dialog.getElementById() 
     48   * @type Object 
     49   * @private 
     50   */ 
    4051  this.r_id  = { }; // reverse lookup id 
     52  /** The calling Xinha instance 
     53   * @type Xinha 
     54   * @private 
     55   */ 
    4156  this.editor   = editor; 
     57  /**  
     58   * @private 
     59   * @type Document 
     60   */ 
    4261  this.document = document; 
     62  /** Object with width, height as numbers 
     63   * @type Object 
     64   */ 
     65   
    4366  this.size = size; 
     67  /**  
     68   * @type Boolean 
     69   * @private 
     70   */ 
    4471  this.modal = (options && options.modal === false) ? false : true; 
     72  /**  
     73   * @type Boolean 
     74   * @private 
     75   */ 
    4576  this.closable = (options && options.closable === false) ? false : true; 
     77  /**  
     78   * @type Boolean 
     79   * @private 
     80   */ 
    4681  this.resizable = (options && options.resizable === false) ? false : true; 
     82  /**  
     83   * @type Number 
     84   * @private 
     85   */ 
    4786  this.layer = (options && options.layer) ? options.layer : 0; 
     87  /**  
     88   * @type Boolean 
     89   * @private 
     90   */ 
    4891  this.centered = (options && options.centered === true) ? true : false; 
     92  /**  
     93   * @type Boolean 
     94   * @private 
     95   */ 
    4996  this.closeOnEscape = (options && options.closeOnEscape === true) ? true : false; 
    50  
     97   
     98  /** The div that is the actual dialog 
     99   *  @type DomNode 
     100   */ 
     101  this.rootElem = null; 
     102   
     103  /** The caption at the top of the dialog that is used to dragged the dialog. It is automatically created from the first h1 in the dialog's HTML 
     104   *  @type DomNode 
     105   */ 
     106  this.captionBar = null; 
     107  /** This div contains the content 
     108   *  @type DomNode 
     109   */ 
     110  this.main = null; 
     111   
     112  /** Each dialog has a background 
     113   *  @type DomNode 
     114   *  @private 
     115   */ 
     116  this.background = null; 
     117  /**  
     118   * @type Boolean 
     119   * @private 
     120   */ 
     121  this.centered = null; 
     122  /**  
     123   * @type Boolean 
     124   * @private 
     125   */ 
     126  this.greyout = null; 
     127   
     128  /**  
     129   * @type DomNode 
     130   * @private 
     131   */ 
     132  this.buttons = null; 
     133  /**  
     134   * @type DomNode 
     135   * @private 
     136   */ 
     137  this.closer = null; 
     138  /**  
     139   * @type DomNode 
     140   * @private 
     141   */ 
     142  this.icon = null; 
     143  /**  
     144   * @type DomNode 
     145   * @private 
     146   */ 
     147  this.resizer = null; 
     148  /**  
     149   * @type Number 
     150   * @private 
     151   */ 
     152  this.initialZ = null; 
     153   
    51154  /* Check global config to see if we should override any of the above options 
    52155    If a global option is set, it will apply to all dialogs, regardless of their 
     
    152255 
    153256  document.body.appendChild(backG); 
     257 
    154258  this.background = backG; 
    155259 
     
    326430 
    327431}; 
    328  
     432/** This function is called when the dialog is resized.  
     433 *  By default it does nothing, but you can override it in your Xinha.Dialog object e.g. to resize elements within you Dialog. 
     434 *  Example:<br /> 
     435 *  <code> 
     436 *  var dialog = this.dialog; //The plugin's dialog instance; 
     437 *  dialog.onresize = function()  
     438 *  { 
     439 *    var el = dialog.getElementById('foo'); 
     440 *    el.style.width = dialog.width; 
     441 *  } 
     442 *  </code> 
     443 */ 
    329444Xinha.Dialog.prototype.onresize = function() 
    330445{ 
    331446  return true; 
    332447}; 
    333  
     448/** This function shows the dialog and populates form elements with values. 
     449 * Example:<br /> 
     450 * Given your dialog contains an input element like <code>&lt;input name="[myInput]" type="text" /&gt;</code> 
     451 * <code> 
     452 *  var dialog = this.dialog; //The plugin's dialog instance; 
     453 *  var values = {myInput : 'My input value'} 
     454 *  dialog.show(values); 
     455 *  </code> 
     456 *  @see #setValues 
     457 *  @param {Object} values Object indexed by names of input elements 
     458 */ 
    334459Xinha.Dialog.prototype.show = function(values) 
    335460{ 
     
    489614  this.dialogShown = true; 
    490615}; 
    491  
     616/** Hides the dialog and returns an object with the valuse of form elements 
     617 * @see #getValues 
     618 * @type Object 
     619 */ 
    492620Xinha.Dialog.prototype.hide = function() 
    493621{ 
     
    538666  return this.getValues(); 
    539667}; 
    540  
     668/** Shows/hides the dialog 
     669 *  
     670 */ 
    541671Xinha.Dialog.prototype.toggle = function() 
    542672{ 
     
    550680  } 
    551681}; 
     682/** Reduces the dialog to the size of the caption bar 
     683 *  
     684 */ 
    552685Xinha.Dialog.prototype.collapse = function() 
    553686{ 
     
    564697}; 
    565698/** Equivalent to document.getElementById. You can't use document.getElementById because id's are dynamic to avoid id clashes between plugins 
    566  * @type {Element} 
     699 * @type DomNode 
    567700 * @param {String} id 
    568701 */ 
     
    572705}; 
    573706/** Equivalent to document.getElementByName. You can't use document.getElementByName because names are dynamic to avoid name clashes between plugins 
    574  * @type {Array} 
     707 * @type Array 
    575708 * @param {String} name 
    576709 */ 
     
    581714}; 
    582715/** Return all elements in the dialog that have the given class 
    583  * @type {Array}  
     716 * @type Array  
    584717 * @param {String} className 
    585718 */ 
     
    589722}; 
    590723 
     724/** Initiates dragging 
     725 * @private 
     726 * @param {Object} ev Mousedown event 
     727 */ 
    591728Xinha.Dialog.prototype.dragStart = function (ev)  
    592729{ 
     
    628765  } 
    629766}; 
    630  
     767/** Sets the position while dragging 
     768 * @private 
     769 * @param {Object} ev Mousemove event 
     770 */ 
    631771Xinha.Dialog.prototype.dragIt = function(ev) 
    632772{ 
     
    655795  dialog.posDialog(newPos); 
    656796}; 
    657  
     797/** Ends dragging 
     798 * @private 
     799 * @param {Object} ev Mouseup event 
     800 */ 
    658801Xinha.Dialog.prototype.dragEnd = function(ev) 
    659802{ 
     
    693836 
    694837}; 
    695  
     838/** Initiates resizing 
     839 * @private 
     840 * @param {Object} ev Mousedown event 
     841 */ 
    696842Xinha.Dialog.prototype.resizeStart = function (ev) { 
    697843  var dialog = this; 
     
    728874  } 
    729875}; 
    730  
     876/** Sets the size while resiziong 
     877 * @private 
     878 * @param {Object} ev Mousemove event 
     879 */ 
    731880Xinha.Dialog.prototype.resizeIt = function(ev) 
    732881{ 
     
    763912  dialog.onresize(); 
    764913}; 
    765  
     914/** Ends resizing 
     915 * @private 
     916 * @param {Object} ev Mouseup event 
     917 */ 
    766918Xinha.Dialog.prototype.resizeEnd = function(ev) 
    767919{ 
     
    793945  }   
    794946}; 
    795  
     947/** Attaches a modeless dialog to a panel on the given side 
     948 *  Triggers a notifyOf panel_change event 
     949 *  @param {String} side one of 'left', 'right', 'top', 'bottom' 
     950 */ 
    796951Xinha.Dialog.prototype.attachToPanel = function(side) 
    797952{ 
     
    831986  editor.notifyOf('panel_change', {'action':'add','panel':rootElem}); 
    832987}; 
    833  
    834 Xinha.Dialog.prototype.detachFromPanel = function(ev) 
     988/** Removes a panel dialog from its panel and makes it float 
     989 *  
     990 */ 
     991Xinha.Dialog.prototype.detachFromPanel = function() 
    835992{ 
    836993  var dialog = this; 
     
    8691026   
    8701027}; 
    871  
     1028/**  
     1029 * @private 
     1030 * @type Object Object with width, height strings incl. "px" for CSS 
     1031 */ 
    8721032Xinha.Dialog.calcFullBgSize = function() 
    8731033{ 
     
    8761036  return {width:(page.x > viewport.x  ? page.x : viewport.x )  + "px",height:(page.x > viewport.y ? page.y : viewport.y ) + "px"}; 
    8771037}; 
    878  
     1038/** Sizes the background to the size of the dialog 
     1039 *  @private 
     1040 */ 
    8791041Xinha.Dialog.prototype.sizeBgToDialog = function() 
    8801042{ 
     
    8861048  bgStyle.height = rootElemStyle.height; 
    8871049}; 
     1050/** Hides the background 
     1051 *  @private 
     1052 */ 
    8881053Xinha.Dialog.prototype.hideBackground = function() 
    8891054{ 
     
    8911056  Xinha.Dialog.fadeOut(this.background); 
    8921057}; 
     1058/** Shows the background 
     1059 *  @private 
     1060 */ 
    8931061Xinha.Dialog.prototype.showBackground = function() 
    8941062{ 
     
    8961064  Xinha.Dialog.fadeIn(this.background,70); 
    8971065}; 
     1066/** Positions the background 
     1067 *  @private 
     1068 *  @param {Object} pos Object with top, left strings incl. "px" for CSS 
     1069 */ 
    8981070Xinha.Dialog.prototype.posBackground = function(pos) 
    8991071{ 
     
    9041076  } 
    9051077}; 
     1078/** Resizes the background 
     1079 *  @private 
     1080 *  @param {Object} size Object with width, height strings incl. "px" for CSS 
     1081 */ 
    9061082Xinha.Dialog.prototype.resizeBackground = function(size) 
    9071083{ 
     
    9121088  } 
    9131089}; 
     1090/** Positions the dialog 
     1091 *  @param {Object} pos Object with top, left strings incl. "px" for CSS 
     1092 */ 
    9141093Xinha.Dialog.prototype.posDialog = function(pos) 
    9151094{ 
     
    9181097  st.top  = pos.top; 
    9191098}; 
     1099/** Resizes the dialog 
     1100 *  
     1101 * @param {Object} size Object with width, height strings incl. "px" for CSS 
     1102 */ 
    9201103Xinha.Dialog.prototype.sizeDialog = function(size) 
    9211104{ 
     
    9281111  this.main.style.width = (width > 10) ? width : 10 + 'px'; 
    9291112}; 
     1113/** Sets the values like Xinha.Dialog.prototype.show(values) 
     1114 * @see #show 
     1115 * @param {Object} values  
     1116 */ 
    9301117Xinha.Dialog.prototype.setValues = function(values) 
    9311118{ 
     
    10021189}; 
    10031190 
     1191/** Retrieves the values like Xinha.Dialog.prototype.hide() 
     1192 * @see #hide 
     1193 * @type Object values  
     1194 */ 
    10041195Xinha.Dialog.prototype.getValues = function() 
    10051196{ 
     
    10971288  return values; 
    10981289}; 
    1099  
    1100 Xinha.Dialog.prototype.translateHtml = function(html,localizer) 
     1290/** Localizes strings in the dialog. 
     1291 * @private 
     1292 * @param {String} html The HTML to translate 
     1293 * @param {String} localizer Context for translation, usually plugin's name 
     1294 */ 
     1295Xinha.Dialog.prototype.translateHtml = function(html, localizer) 
    11011296{ 
    11021297  var dialog = this; 
     
    11421337/** 
    11431338 * Fixup links in the elements to allow linking to Xinha resources 
     1339 * @private 
    11441340 */ 
    11451341Xinha.Dialog.prototype.fixupDOM = function(root,plugin) 
Note: See TracChangeset for help on using the changeset viewer.