michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsIURI;
michael@0: interface nsILocalHandlerApp;
michael@0: interface nsIMutableArray;
michael@0: 
michael@0: /**
michael@0:  * Implements Win7 Taskbar jump list item interfaces.
michael@0:  *
michael@0:  * Note to consumers: it's reasonable to expect we'll need support for other types
michael@0:  * of jump list items (an audio file, an email message, etc.). To add types,
michael@0:  * create the specific interface here, add an implementation class to WinJumpListItem,
michael@0:  * and add support to addListBuild & removed items processing.
michael@0:  * 
michael@0:  */
michael@0: 
michael@0: [scriptable, uuid(ACB8FB3C-E1B0-4044-8A50-E52C3E7C1057)]
michael@0: interface nsIJumpListItem : nsISupports
michael@0: {
michael@0:   const short JUMPLIST_ITEM_EMPTY      = 0; // Empty list item
michael@0:   const short JUMPLIST_ITEM_SEPARATOR  = 1; // Separator
michael@0:   const short JUMPLIST_ITEM_LINK       = 2; // Web link item
michael@0:   const short JUMPLIST_ITEM_SHORTCUT   = 3; // Application shortcut
michael@0: 
michael@0:   /**
michael@0:    * Retrieves the jump list item type.
michael@0:    */
michael@0:   readonly attribute short type;
michael@0: 
michael@0:   /**
michael@0:    * Compare this item to another.
michael@0:    *
michael@0:    * Compares the type and other properties specific to this item's
michael@0:    * type.
michael@0:    *
michael@0:    * separator: type
michael@0:    * link: type, uri, title
michael@0:    * shortcut: type, handler app
michael@0:    */
michael@0:   boolean equals(in nsIJumpListItem item);
michael@0: };
michael@0: 
michael@0: /**
michael@0:  * A menu separator.
michael@0:  */
michael@0: 
michael@0: [scriptable, uuid(69A2D5C5-14DC-47da-925D-869E0BD64D27)]
michael@0: interface nsIJumpListSeparator : nsIJumpListItem
michael@0: {
michael@0:   /* nothing needed here */
michael@0: };
michael@0: 
michael@0: /**
michael@0:  * A URI link jump list item.
michael@0:  *
michael@0:  * Note the application must be the registered protocol
michael@0:  * handler for the protocol of the link.
michael@0:  */
michael@0: 
michael@0: [scriptable, uuid(76EA47B1-C797-49b3-9F18-5E740A688524)]
michael@0: interface nsIJumpListLink : nsIJumpListItem
michael@0: {
michael@0:   /**
michael@0:    * Set or get the uri for this link item.
michael@0:    */
michael@0:   attribute nsIURI uri;
michael@0: 
michael@0:   /**
michael@0:    * Set or get the title for a link item.  
michael@0:    */
michael@0:   attribute AString uriTitle;
michael@0: 
michael@0:   /**
michael@0:    * Get a 'privacy safe' unique string hash of the uri's
michael@0:    * spec. Useful in tracking removed items using visible
michael@0:    * data stores such as prefs. Generates an MD5 hash of
michael@0:    * the URI spec using nsICryptoHash.
michael@0:    */
michael@0:   readonly attribute ACString uriHash;
michael@0: 
michael@0:   /**
michael@0:    * Compare this item's hash to another uri.
michael@0:    *
michael@0:    * Generates a spec hash of the incoming uri and compares
michael@0:    * it to this item's uri spec hash.
michael@0:    */
michael@0:   boolean compareHash(in nsIURI uri);
michael@0: };
michael@0: 
michael@0: /**
michael@0:  * A generic application shortcut with command line support.
michael@0:  */
michael@0: 
michael@0: [scriptable, uuid(CBE3A37C-BCE1-4fec-80A5-5FFBC7F33EEA)]
michael@0: interface nsIJumpListShortcut : nsIJumpListItem
michael@0: {
michael@0:   /**
michael@0:    * Set or get the handler app for this shortcut item.
michael@0:    *
michael@0:    * The handler app may also be used along with iconIndex to generate an icon
michael@0:    * for the jump list item.
michael@0:    * 
michael@0:    * @throw NS_ERROR_FILE_NOT_FOUND if the handler app can
michael@0:    * not be found on  the system.
michael@0:    *
michael@0:    * @see faviconPageUri
michael@0:    */
michael@0:   attribute nsILocalHandlerApp app;
michael@0: 
michael@0:   /**
michael@0:    * Set or get the icon displayed with the jump list item.
michael@0:    *
michael@0:    * Indicates the resource index of the icon contained within the handler
michael@0:    * executable which may be used as the jump list icon.
michael@0:    *
michael@0:    * @see faviconPageUri
michael@0:    */
michael@0:   attribute long iconIndex;
michael@0: 
michael@0:   /**
michael@0:    * Set or get the URI of a page whose favicon may be used as the icon.
michael@0:    *
michael@0:    * When a jump list build occurs, the favicon to be used for the item is
michael@0:    * obtained using the following steps:
michael@0:    * - First, attempt to use the asynchronously retrieved and scaled favicon
michael@0:    * associated with the faviconPageUri.
michael@0:    * - If faviconPageUri is null, or if retrieving the favicon fails, fall
michael@0:    * back to using the handler executable and iconIndex.  
michael@0:    */
michael@0:   attribute nsIURI faviconPageUri;
michael@0: };
michael@0: