doc/notifiers.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">\r
   2 <html xmlns="http://www.w3.org/1999/xhtml">\r
   3 \r
   4 <head>\r
   5   <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type" />\r
   6 \r
   7   \r
   8   <title>notifiers</title>\r
   9 \r
  10 </head>\r
  11 \r
  12 <body>\r
  13 <h3>Notifiers</h3>\r
  14 <p>BlueGriffon provides extension developers with an object allowing to register listeners for any kind of events. This object is NotifierUtils:</p>\r
  15 <h4>Register a BlueGriffon event callback</h4>\r
  16 <table style="text-align: left;" class="methodTable" border="1" cellpadding="2" cellspacing="2">\r
  17 \r
  18          <tbody>\r
  19 \r
  20             <tr>\r
  21 \r
  22                <th>Method name</th>\r
  23 \r
  24 \r
  25                <td><code>addNotifierCallback</code></td>\r
  26 \r
  27             </tr>\r
  28 \r
  29 \r
  30             <tr>\r
  31 \r
  32                <th>Parameters</th>\r
  33 \r
  34 \r
  35                <td>\r
  36                   \r
  37       <ol>\r
  38         <li><code>aEventName,</code> a string representing the event</li>\r
  39         <li><code>aListener</code>, a function</li>\r
  40         <li><code>aContext</code>, an object to be user in the listener as local context</li>\r
  41       </ol>\r
  42 \r
  43                </td>\r
  44 \r
  45             </tr>\r
  46 \r
  47 \r
  48             <tr>\r
  49 \r
  50                <th>Return value</th>\r
  51 \r
  52 \r
  53                <td>no return value ; dumps an error on console if listener cannot be registered</td>\r
  54 \r
  55             </tr>\r
  56 \r
  57          \r
  58   </tbody>\r
  59       \r
  60 </table>\r
  61 <h4>Dispatch a BlueGriffon event</h4>\r
  62 <p>To dispatch an event use the following method:</p>\r
  63 <table style="text-align: left;" class="methodTable" border="1" cellpadding="2" cellspacing="2">\r
  64 \r
  65          <tbody>\r
  66 \r
  67             <tr>\r
  68 \r
  69                <th>Method name</th>\r
  70 \r
  71 \r
  72                <td><code>notify</code></td>\r
  73 \r
  74             </tr>\r
  75 \r
  76 \r
  77             <tr>\r
  78 \r
  79                <th>Parameters</th>\r
  80 \r
  81 \r
  82                <td>\r
  83                   \r
  84       <ol>\r
  85         <li><code>aEventName,</code> a string representing the event<span style="font-family: monospace;"></span></li>\r
  86         <li>all other arguments will be passed to the listeners for this event</li>\r
  87       </ol>\r
  88 \r
  89                </td>\r
  90 \r
  91             </tr>\r
  92 \r
  93 \r
  94             <tr>\r
  95 \r
  96                <th>Return value</th>\r
  97 \r
  98 \r
  99                <td>no return value ; dumps an error on console if no event of that name is registered or if a listener throws an exception</td>\r
 100 \r
 101             </tr>\r
 102 \r
 103          \r
 104   </tbody>\r
 105       \r
 106 </table>\r
 107 <h4>Remove&nbsp;a BlueGriffon event callback</h4>\r
 108 <table style="text-align: left;" class="methodTable" border="1" cellpadding="2" cellspacing="2">\r
 109 \r
 110          <tbody>\r
 111 \r
 112             <tr>\r
 113 \r
 114                <th>Method name</th>\r
 115 \r
 116 \r
 117                <td><code>removeNotifierCallback</code></td>\r
 118 \r
 119             </tr>\r
 120 \r
 121 \r
 122             <tr>\r
 123 \r
 124                <th>Parameters</th>\r
 125 \r
 126 \r
 127                <td>\r
 128                   \r
 129       <ol>\r
 130         <li><code>aEventName,</code> a string representing the event</li>\r
 131         <li><code>aListener</code>, a function</li>\r
 132       </ol>\r
 133 \r
 134                </td>\r
 135 \r
 136             </tr>\r
 137 \r
 138 \r
 139             <tr>\r
 140 \r
 141                <th>Return value</th>\r
 142 \r
 143 \r
 144                <td>no return value ; dumps an error on console if\r
 145 no event of that name is registered or if &nbsp;that listener is not\r
 146 registered as callback for that event name</td>\r
 147 \r
 148             </tr>\r
 149 \r
 150          \r
 151   </tbody>\r
 152       \r
 153 </table>\r
 154 <h4>Clean all BlueGriffon event callback for a given event name</h4>\r
 155 <table style="text-align: left;" class="methodTable" border="1" cellpadding="2" cellspacing="2">\r
 156 \r
 157          <tbody>\r
 158 \r
 159             <tr>\r
 160 \r
 161                <th>Method name</th>\r
 162 \r
 163 \r
 164                <td><code>cleanNotifier</code></td>\r
 165 \r
 166             </tr>\r
 167 \r
 168 \r
 169             <tr>\r
 170 \r
 171                <th>Parameters</th>\r
 172 \r
 173 \r
 174                <td>\r
 175                   \r
 176       <ol>\r
 177         <li><code>aEventName,</code> a string representing the event<span style="font-family: monospace;"></span></li>\r
 178       </ol>\r
 179 \r
 180                </td>\r
 181 \r
 182             </tr>\r
 183 \r
 184 \r
 185             <tr>\r
 186 \r
 187                <th>Return value</th>\r
 188 \r
 189 \r
 190                <td>no return value</td>\r
 191 \r
 192             </tr>\r
 193 \r
 194          \r
 195   </tbody>\r
 196       \r
 197 </table>\r
 198 <h4>Example</h4>\r
 199 <pre>var EditorScrolledNotifier =&nbsp; {<br />&nbsp; startup: function EditorScrolledNotifier_startup()<br />&nbsp; {<br />&nbsp;&nbsp;&nbsp; var tabeditor = document.getElementById("tabeditor");<br />&nbsp;&nbsp;&nbsp; tabeditor.addEventListener("scroll", this.onEditorScrolled, false);<br />&nbsp; },<br /><br />&nbsp; shutdown: function EditorScrolledNotifier_shutdown()<br />&nbsp; {<br />&nbsp;&nbsp;&nbsp; var tabeditor = document.getElementById("tabeditor");<br />&nbsp;&nbsp;&nbsp; tabeditor.removeEventListener("scroll", this.onEditorScrolled, false);<br />&nbsp; },<br /><br />&nbsp; onEditorScrolled: function EditorScrolledNotifier_onEditorScrolled(aEvent)<br />&nbsp; {<br />&nbsp;&nbsp;&nbsp; NotifierUtils.notify("editorScrolled", EditorUtils.getCurrentEditorElement());<br />&nbsp; }<br />};<br /><br />EditorScrolledNotifier .startup();<br /><br />.....<br /><br />&nbsp; &lt;constructor&gt;<br />&nbsp;&nbsp;&nbsp; &lt;![CDATA[<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; NotifierUtils.addNotifierCallback("editorScrolled", this.onEditorScrolled, this);<br />&nbsp;&nbsp;&nbsp; ]]&gt;<br />&nbsp; &lt;/constructor&gt;<br /><br />&nbsp; &lt;destructor&gt;<br />&nbsp;&nbsp;&nbsp; &lt;![CDATA[<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; NotifierUtils.removeNotifierCallback("editorScrolled", this.onEditorScrolled);<br />&nbsp;&nbsp;&nbsp; ]]&gt;<br />&nbsp; &lt;/destructor&gt;<br /><br />&nbsp; &lt;method name="onEditorScrolled"&gt;<br />&nbsp;&nbsp;&nbsp; &lt;param name="aEditor"/&gt;<br />&nbsp;&nbsp;&nbsp; &lt;body&gt;<br />&nbsp;&nbsp;&nbsp; &lt;![CDATA[<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; var elt = this.getSelectionForEditor(aEditor);<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; this.refreshRulerForElement(elt);<br />&nbsp;&nbsp;&nbsp; ]]&gt;<br />&nbsp;&nbsp;&nbsp; &lt;/body&gt;<br />&nbsp; &lt;/method&gt;</pre>\r
 200 </body>\r
 201 \r
 202 </html>\r