widget/nsIJumpListItem.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7
   8 interface nsIURI;
   9 interface nsILocalHandlerApp;
  10 interface nsIMutableArray;
  11
  12 /**
  13  * Implements Win7 Taskbar jump list item interfaces.
  14  *
  15  * Note to consumers: it's reasonable to expect we'll need support for other types
  16  * of jump list items (an audio file, an email message, etc.). To add types,
  17  * create the specific interface here, add an implementation class to WinJumpListItem,
  18  * and add support to addListBuild & removed items processing.
  19  *
  20  */
  21
  22 [scriptable, uuid(ACB8FB3C-E1B0-4044-8A50-E52C3E7C1057)]
  23 interface nsIJumpListItem : nsISupports
  24 {
  25   const short JUMPLIST_ITEM_EMPTY      = 0; // Empty list item
  26   const short JUMPLIST_ITEM_SEPARATOR  = 1; // Separator
  27   const short JUMPLIST_ITEM_LINK       = 2; // Web link item
  28   const short JUMPLIST_ITEM_SHORTCUT   = 3; // Application shortcut
  29
  30   /**
  31    * Retrieves the jump list item type.
  32    */
  33   readonly attribute short type;
  34
  35   /**
  36    * Compare this item to another.
  37    *
  38    * Compares the type and other properties specific to this item's
  39    * type.
  40    *
  41    * separator: type
  42    * link: type, uri, title
  43    * shortcut: type, handler app
  44    */
  45   boolean equals(in nsIJumpListItem item);
  46 };
  47
  48 /**
  49  * A menu separator.
  50  */
  51
  52 [scriptable, uuid(69A2D5C5-14DC-47da-925D-869E0BD64D27)]
  53 interface nsIJumpListSeparator : nsIJumpListItem
  54 {
  55   /* nothing needed here */
  56 };
  57
  58 /**
  59  * A URI link jump list item.
  60  *
  61  * Note the application must be the registered protocol
  62  * handler for the protocol of the link.
  63  */
  64
  65 [scriptable, uuid(76EA47B1-C797-49b3-9F18-5E740A688524)]
  66 interface nsIJumpListLink : nsIJumpListItem
  67 {
  68   /**
  69    * Set or get the uri for this link item.
  70    */
  71   attribute nsIURI uri;
  72
  73   /**
  74    * Set or get the title for a link item.
  75    */
  76   attribute AString uriTitle;
  77
  78   /**
  79    * Get a 'privacy safe' unique string hash of the uri's
  80    * spec. Useful in tracking removed items using visible
  81    * data stores such as prefs. Generates an MD5 hash of
  82    * the URI spec using nsICryptoHash.
  83    */
  84   readonly attribute ACString uriHash;
  85
  86   /**
  87    * Compare this item's hash to another uri.
  88    *
  89    * Generates a spec hash of the incoming uri and compares
  90    * it to this item's uri spec hash.
  91    */
  92   boolean compareHash(in nsIURI uri);
  93 };
  94
  95 /**
  96  * A generic application shortcut with command line support.
  97  */
  98
  99 [scriptable, uuid(CBE3A37C-BCE1-4fec-80A5-5FFBC7F33EEA)]
 100 interface nsIJumpListShortcut : nsIJumpListItem
 101 {
 102   /**
 103    * Set or get the handler app for this shortcut item.
 104    *
 105    * The handler app may also be used along with iconIndex to generate an icon
 106    * for the jump list item.
 107    *
 108    * @throw NS_ERROR_FILE_NOT_FOUND if the handler app can
 109    * not be found on  the system.
 110    *
 111    * @see faviconPageUri
 112    */
 113   attribute nsILocalHandlerApp app;
 114
 115   /**
 116    * Set or get the icon displayed with the jump list item.
 117    *
 118    * Indicates the resource index of the icon contained within the handler
 119    * executable which may be used as the jump list icon.
 120    *
 121    * @see faviconPageUri
 122    */
 123   attribute long iconIndex;
 124
 125   /**
 126    * Set or get the URI of a page whose favicon may be used as the icon.
 127    *
 128    * When a jump list build occurs, the favicon to be used for the item is
 129    * obtained using the following steps:
 130    * - First, attempt to use the asynchronously retrieved and scaled favicon
 131    * associated with the faviconPageUri.
 132    * - If faviconPageUri is null, or if retrieving the favicon fails, fall
 133    * back to using the handler executable and iconIndex.
 134    */
 135   attribute nsIURI faviconPageUri;
 136 };