mozilla
Your Search Results

    nsIJumpListBuilder

    Please add a summary to this article.
    1.0
    28
    Introduced
    Gecko 2.0
    Inherits from: nsISupports Last changed in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

    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 committed. 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 entires users have removed, applications are encouraged to track removed items internally.

    Each list is made up of an array of nsIWinJumpListItems representing items such as shortcuts, links, and separators. See nsIJumpListItem for information on adding additional jump list types.

    Method overview

    void abortListBuild();
    boolean addListToBuild(in short aCatType, in nsIArray items Optional, in AString catName Optional);
    boolean commitListBuild();
    boolean deleteActiveList();
    boolean initListBuild(in nsIMutableArray removedItems);

    Attributes

    Attribute Type Description
    available short Indicates whether jump list taskbar features are supported by the current host. Read only.
    isListCommitted boolean

    JumpList management.

    Indicates if a commit has already occurred in this session. Read only.
    Exceptions thrown
    NS_ERROR_NOT_AVAILABLE
    On all calls if taskbar functionality is not supported by the operating system.
    maxListItems short The maximum number of jump list items the current desktop can support. Read only.

    Constants

    Constant Value Description
    JUMPLIST_CATEGORY_TASKS 0

    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.
    JUMPLIST_CATEGORY_RECENT 1 Recent 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.
    JUMPLIST_CATEGORY_FREQUENT 2 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.
    JUMPLIST_CATEGORY_CUSTOMLIST 3 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.

    Methods

    abortListBuild()

    Aborts and clears the current jump list build.

    void abortListBuild();
    
    Parameters

    None.

    addListToBuild()

    Adds a list and if required, a set of items for the list.

    boolean addListToBuild(
      in short aCatType,
      in nsIArray items, Optional
      in AString catName Optional
    );
    
    Parameters
    aCatType
    The type of list to add.
    items Optional
    An array of nsIJumpListItem items to add to the list.
    catName Optional
    For custom lists, the title of the list.
    Return value

    true if the operation completed successfully.

    Exceptions thrown
    NS_ERROR_UNEXPECTED
    On internal errors.
    NS_ERROR_ILLEGAL_VALUE
    If an item is added that was removed since the last commit.
    NS_ERROR_INVALID_ARG
    If incorrect parameters are passed for a particular category or item type.

    commitListBuild()

    Commits the current jump list build to the Taskbar.

    boolean commitListBuild();
    
    Parameters

    None.

    Return value

    true if the operation completed successfully.

    deleteActiveList()

    Deletes any currently applied taskbar jump list for this application. Common uses would be the enabling of a privacy mode and uninstallation.

    boolean deleteActiveList();
    
    Parameters

    None.

    Return value

    true if the operation completed successfully.

    Exceptions thrown
    NS_ERROR_UNEXPECTED
    On internal errors.

    initListBuild()

    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 fashion.

    boolean initListBuild(
      in nsIMutableArray removedItems
    );
    
    Parameters
    removedItems
    A list of items that were removed by the user since the last commit.
    Return value

    true if the operation completed successfully.

    Document Tags and Contributors

    Contributors to this page: Sheppy, trevorh
    Last updated by: Sheppy,