doc/colorPicker.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   2     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3
   4 <html xmlns="http://www.w3.org/1999/xhtml">
   5 <head>
   6    <meta http-equiv="content-type"
   7          content="text/html; charset=us-ascii" />
   8
   9    <title>Color Picker</title>
  10    <link rel="stylesheet"
  11          href="doc.css"
  12          type="text/css" />
  13 </head>
  14
  15 <body>
  16    <div class="header">
  17       Composer: developers
  18    </div>
  19
  20    <div id="navBar">
  21       <a href="index.html">Index</a> &gt; <a href=
  22       "colorPicker.html">ColorPickerHelper</a>
  23    </div>
  24
  25    <h1>Color Picker</h1>
  26
  27    <p><img style=
  28    "margin-left: 1em; width: 232px; height: 206px; float: right;"
  29         alt="Color picker"
  30         src="colorPicker.png" />Composer has a helper for simple
  31         and convenient usage of its new color picker inside a
  32         sidebar or extension. This helper allows to create
  33         persistent color objects that carry information for a given
  34         system color, for example the foreground color, the page's
  35         background color, table cells' background color and so
  36         on.</p>
  37
  38    <p style="clear: both;">The object is</p>
  39    <pre><span class="objectName">ColorPickerHelper</span>
  40
  41   <span class="methodName">newPersistentColorObject:</span> function(aColorObjectId)
  42   <span class="methodName">cleanPersistentColorObject</span>: function(aColorObjectId)
  43   <span class="methodName">getCurrentColor</span>: function(aColorObjectId)
  44   <span class="methodName">setLastPickedColor</span>: function(aColorObjectId, aColor)
  45   <span class="methodName">isCancelled</span>: function(aColorObjectId)
  46   <span class="methodName">openColorPicker</span>: function(aColorObjectId, aWindowTitle, aShowTransparency)</pre>
  47
  48    <ol class="readonly"
  49        id="mozToc">
  50       <!--mozToc h2 1-->
  51
  52       <li><a href="#mozTocId73209">Create a new persistent color
  53       object</a></li>
  54
  55       <li><a href="#mozTocId303492">Delete a persistent color
  56       object</a></li>
  57
  58       <li><a href="#mozTocId464951">Retrieve the selected color in
  59       a color object</a></li>
  60
  61       <li><a href="#mozTocId299067">Set the last picked color for a
  62       given color object</a></li>
  63
  64       <li><a href="#mozTocId400897">Show the color picker</a></li>
  65
  66       <li><a href="#mozTocId400897">Check if the color picker was
  67       cancelled</a></li>
  68
  69       <li><a href="#mozTocId303457">Example</a></li>
  70    </ol>
  71
  72    <h2><a class="mozTocH2"
  73       name="mozTocId73209"
  74       id="mozTocId73209"></a>Create a new persistent color
  75       object</h2>
  76
  77    <div class="section">
  78       <table style="text-align: left;"
  79              class="methodTable"
  80              border="1"
  81              cellpadding="2"
  82              cellspacing="2">
  83          <tbody>
  84             <tr>
  85                <th>Method name</th>
  86
  87                <td><code>newPersistentColorObject</code></td>
  88             </tr>
  89
  90             <tr>
  91                <th>Parameters</th>
  92
  93                <td>
  94                   <ol>
  95                      <li><code>aColorObjectId</code>, a unique
  96                      string identifying the color object</li>
  97                   </ol>
  98                </td>
  99             </tr>
 100
 101             <tr>
 102                <th>Return value</th>
 103
 104                <td><code>null</code> in case of error or failure,
 105                the color object otherwise</td>
 106             </tr>
 107          </tbody>
 108       </table>
 109
 110       <p>List of predefined color object identifiers:</p>
 111
 112       <ul>
 113          <li>"<code>TextColor</code>" : color of the text</li>
 114
 115          <li>"<code>PageBackgroundColor</code>" : background color
 116          of the document</li>
 117
 118          <li>"<code>TableBackgroundColor</code>" : background of a
 119          table</li>
 120
 121          <li>"<code>TableCellBackgroundColor</code>" : background
 122          of a table cell</li>
 123
 124          <li>"<code>BorderColor</code>" : color of a border or
 125          outline applied to an element</li>
 126       </ul>
 127    </div>
 128
 129    <h2><a class="mozTocH2"
 130       name="mozTocId303492"
 131       id="mozTocId303492"></a>Delete a persistent color object</h2>
 132
 133    <div class="section">
 134       <table class="methodTable"
 135              style="text-align: left;"
 136              border="1"
 137              cellpadding="2"
 138              cellspacing="2">
 139          <tbody>
 140             <tr>
 141                <th>Method name</th>
 142
 143                <td><code>cleanPersistentColorObject</code></td>
 144             </tr>
 145
 146             <tr>
 147                <th>Parameters</th>
 148
 149                <td>
 150                   <ol>
 151                      <li><code>aColorObjectId</code>, a unique
 152                      string identifying the color object</li>
 153                   </ol>
 154                </td>
 155             </tr>
 156
 157             <tr>
 158                <th>Return value</th>
 159
 160                <td><code><span style=
 161                "font-family: Arial,Helvetica,sans-serif;">no return
 162                value</span></code></td>
 163             </tr>
 164          </tbody>
 165       </table>
 166    </div>
 167
 168    <h2><a class="mozTocH2"
 169       name="mozTocId464951"
 170       id="mozTocId464951"></a>Retrieve the selected color in a
 171       color object</h2>
 172
 173    <div class="section">
 174       <table style="text-align: left;"
 175              class="methodTable"
 176              border="1"
 177              cellpadding="2"
 178              cellspacing="2">
 179          <tbody>
 180             <tr>
 181                <th>Method name</th>
 182
 183                <td><code>getCurrentColor</code></td>
 184             </tr>
 185
 186             <tr>
 187                <th>Parameters</th>
 188
 189                <td>
 190                   <ol>
 191                      <li><code>aColorObjectId</code>, a unique
 192                      string identifying the color object</li>
 193                   </ol>
 194                </td>
 195             </tr>
 196
 197             <tr>
 198                <th>Return value</th>
 199
 200                <td><code>null</code> in case of error or failure
 201                (for instance if the corresponding color object does
 202                not exist), the selected color in the corresponding
 203                color object otherwise</td>
 204             </tr>
 205          </tbody>
 206       </table>
 207    </div>
 208
 209    <h2><a class="mozTocH2"
 210       name="mozTocId299067"
 211       id="mozTocId299067"></a>Set the last picked color for a given
 212       color object</h2>
 213
 214    <div class="section">
 215       <table class="methodTable"
 216              style="text-align: left;"
 217              border="1"
 218              cellpadding="2"
 219              cellspacing="2">
 220          <tbody>
 221             <tr>
 222                <th>Method name</th>
 223
 224                <td><code>setLastPickedColor</code></td>
 225             </tr>
 226
 227             <tr>
 228                <th>Parameters</th>
 229
 230                <td>
 231                   <ol>
 232                      <li><code>aColorObjectId</code>, a unique
 233                      string identifying the color object</li>
 234
 235                      <li><code>aColor</code>, a color (see the
 236                      <a href=
 237                      "http://www.w3.org/TR/1998/REC-CSS2-19980512/syndata.html#color-units">
 238                      CSS definition of a color</a>)</li>
 239                   </ol>
 240                </td>
 241             </tr>
 242
 243             <tr>
 244                <th>Return value</th>
 245
 246                <td><code>null</code> in case of error or failure,
 247                the color <code>aColor</code> otherwise</td>
 248             </tr>
 249          </tbody>
 250       </table>
 251    </div>
 252
 253    <h2><a class="mozTocH2"
 254       name="mozTocId400897"
 255       id="mozTocId400897"></a>Show the color picker</h2>
 256
 257    <div class="section">
 258       <table class="methodTable"
 259              style="text-align: left;"
 260              border="1"
 261              cellpadding="2"
 262              cellspacing="2">
 263          <tbody>
 264             <tr>
 265                <th>Method name</th>
 266
 267                <td><code>openColorPicker</code></td>
 268             </tr>
 269
 270             <tr>
 271                <th>Parameters</th>
 272
 273                <td>
 274                   <ol>
 275                      <li><code>aColorObjectId</code>, a unique
 276                      string identifying the color object ; if the
 277                      color object for this identifier does not
 278                      already exist, a new color object is created
 279                      for that identifier</li>
 280
 281                      <li>
 282                      <code>aWindowTitle</code><code><span style="font-family: Arial,Helvetica,sans-serif;">,</span></code>
 283                      a title for the color picker dialog</li>
 284
 285                      <li><code>aShowTransparency</code>, a boolean
 286                      being true if the checkbox allowing to set the
 287                      color "transparent" has to be shown (for CSS
 288                      backgrounds for instance)</li>
 289                   </ol>
 290                </td>
 291             </tr>
 292
 293             <tr>
 294                <th>Return value</th>
 295
 296                <td><code>null</code> in case of error or failure,
 297                the color object otherwise</td>
 298             </tr>
 299          </tbody>
 300       </table>
 301
 302       <p>It is possible to check if the color picker was closed by
 303       the user on a Cancel action using the following method:</p>
 304    </div>
 305
 306    <h2><a class="mozTocH2"
 307       name="mozTocId400897"
 308       id="mozTocId400897"></a>Check if the color picker was
 309       cancelled</h2>
 310
 311    <div class="section">
 312       <table class="methodTable"
 313              style="text-align: left;"
 314              border="1"
 315              cellpadding="2"
 316              cellspacing="2">
 317          <tbody>
 318             <tr>
 319                <th>Method name</th>
 320
 321                <td><code>isCancelled</code></td>
 322             </tr>
 323
 324             <tr>
 325                <th>Parameters</th>
 326
 327                <td>
 328                   <ol>
 329                      <li><code>aColorObjectId</code>, a unique
 330                      string identifying the color object</li>
 331                   </ol>
 332                </td>
 333             </tr>
 334
 335             <tr>
 336                <th>Return value</th>
 337
 338                <td><code><span style=
 339                "font-family: Arial,Helvetica,sans-serif;">returns a
 340                boolean is the last color picked shown for the color
 341                object identifier was cancelled ; if there is no
 342                color object for this identifier, an exception
 343                NS_ERROR_NULL_POINTER is thrown</span></code></td>
 344             </tr>
 345          </tbody>
 346       </table>
 347    </div>
 348
 349    <h2><a class="mozTocH2"
 350       name="mozTocId303457"
 351       id="mozTocId303457"></a>Example</h2>
 352
 353    <div class="section">
 354       <pre>const kTEMPLATE_COLUMN_BG_COLOR = <code>"TemplateColumnBgColor";</code>
 355 var colorHelper = window.top.ColorPickerHelper;
 356 if (colorHelper.<code>newPersistentColorObject(</code>kTEMPLATE_COLUMN_BG_COLOR<code>))
 357 {
 358   colorHelper.openColorPicker( </code>kTEMPLATE_COLUMN_BG_COLOR<code>,
 359                                "Set the background color for the column",
 360                                true);
 361   if (colorHelper.isCancelled(</code>kTEMPLATE_COLUMN_BG_COLOR))
 362     return;
 363   SetTemplateBgColor(colorHelper.getCurrentColor(kTEMPLATE_COLUMN_BG_COLOR));
 364 }</pre>
 365    </div>
 366    <hr style="width: 100%; height: 2px;" />
 367
 368    <h4>History</h4>
 369
 370    <div class="section history">
 371       <dl>
 372          <dt>Last Update:</dt>
 373
 374          <dd>2007-oct-26, 12:53pm CEST</dd>
 375
 376          <dt>2007-oct-26, 12:53pm CEST</dt>
 377
 378          <dd>initial revision (dglazman)</dd>
 379       </dl>
 380    </div>
 381 </body>
 382 </html>