DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (d96ee8115c5a)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsIArray;
interface nsIMutableArray;

[scriptable, function, uuid(5131a62a-e99f-4631-9138-751f8aad1ae4)]
interface nsIJumpListCommittedCallback : nsISupports
{
  void done(in boolean result);
};

[scriptable, uuid(1FE6A9CD-2B18-4dd5-A176-C2B32FA4F683)]
interface nsIJumpListBuilder : nsISupports
{
  /**
   * JumpLists
   *
   * Jump lists are built and then applied. Modifying an applied jump list is not
   * permitted. Callers should begin the creation of a new jump list using
   * initListBuild, add sub lists using addListToBuild, then commit the jump list
   * using commitListBuild. Lists are built in real-time during the sequence of
   * build calls, make sure to check for errors on each individual step.
   *
   * The default number of allowed items in a jump list is ten. Users can change
   * the number through system preferences. User may also pin items to jump lists,
   * which take up additional slots. Applications do not have control over the
   * number of items allowed in jump lists; excess items added are dropped by the
   * system. Item insertion priority is defined as first to last added. 
   *
   * Users may remove items from jump lists after they are commited. The system
   * tracks removed items between commits. A list of these items is returned by
   * a call to initListBuild. nsIJumpListBuilder does not filter entries added that
   * have been removed since the last commit. To prevent repeatedly adding entries
   * users have removed, applications are encoraged to track removed items 
   * internally.
   *
   * Each list is made up of an array of nsIJumpListItem representing items
   * such as shortcuts, links, and separators. See nsIJumpListItem for information
   * on adding additional jump list types.
   */

  /**
   * List Types
   */

  /**
   * Task List
   * 
   * Tasks are common actions performed by users within the application. A task
   * can be represented by an application shortcut and associated command line
   * parameters or a URI. Task lists should generally be static lists that do not
   * change often, if at all - similar to an application menu.
   *
   * Tasks are given the highest priority of all lists when space is limited.
   */
  const short JUMPLIST_CATEGORY_TASKS = 0;

  /**
   * Recent or Frequent list
   * 
   * Recent and frequent lists are based on Window's recent document lists. The
   * lists are generated automatically by Windows. Applications that use recent
   * or frequent lists should keep document use tracking up to date by calling
   * the SHAddToRecentDocs shell api.
   */
  const short JUMPLIST_CATEGORY_RECENT       = 1;
  const short JUMPLIST_CATEGORY_FREQUENT     = 2;

  /**
   * Custom Lists
   *
   * Custom lists can be made up of tasks, links, and separators. The title of
   * of the list is passed through the optional string parameter of addBuildList.
   */
  const short JUMPLIST_CATEGORY_CUSTOMLIST   = 3;

  /**
   * Indicates whether jump list taskbar features are supported by the current
   * host.
   */
  readonly attribute short available;

  /**
   * JumpList management
   *
   * @throw NS_ERROR_NOT_AVAILABLE on all calls if taskbar functionality
   * is not supported by the operating system.
   */

  /**
   * Indicates if a commit has already occurred in this session.
   */
  readonly attribute boolean isListCommitted;

  /**
   * The maximum number of jump list items the current desktop can support.
   */
  readonly attribute short maxListItems;

  /**
   * Initializes a jump list build and returns a list of items the user removed
   * since the last time a jump list was committed. Removed items can become state
   * after initListBuild is called, lists should be built in single-shot fasion.
   *
   * @param removedItems
   *        A list of items that were removed by the user since the last commit.
   *
   * @returns true if the operation completed successfully.
   */
  boolean initListBuild(in nsIMutableArray removedItems);
  
  /**
   * Adds a list and if required, a set of items for the list.
   *
   * @param aCatType
   *        The type of list to add.
   * @param items
   *        An array of nsIJumpListItem items to add to the list.
   * @param catName
   *        For custom lists, the title of the list.
   *
   * @returns true if the operation completed successfully.
   *
   * @throw NS_ERROR_INVALID_ARG if incorrect parameters are passed for
   * a particular category or item type.
   * @throw NS_ERROR_ILLEGAL_VALUE if an item is added that was removed
   * since the last commit.
   * @throw NS_ERROR_UNEXPECTED on internal errors.
   */
  boolean addListToBuild(in short aCatType, [optional] in nsIArray items, [optional] in AString catName);

  /**
   * Aborts and clears the current jump list build.
   */
  void abortListBuild();

  /**
   * Commits the current jump list build to the Taskbar.
   *
   * @param callback
   *        Receives one argument, which is true if the operation completed
   *        successfully, otherwise it is false.
   */
  void commitListBuild([optional] in nsIJumpListCommittedCallback callback);

  /**
   * Deletes any currently applied taskbar jump list for this application.
   * Common uses would be the enabling of a privacy mode and uninstallation.
   *
   * @returns true if the operation completed successfully.
   *
   * @throw NS_ERROR_UNEXPECTED on internal errors.
   */
  boolean deleteActiveList();
};