Confirmed users, Bureaucrats and Sysops emeriti
792
edits
m (correct grammar) |
No edit summary |
||
Line 8: | Line 8: | ||
''There is a [[Bookmarks Use Cases]] page if you would like to describe and discuss user-level Bookmark behaviours and use cases.'' | ''There is a [[Bookmarks Use Cases]] page if you would like to describe and discuss user-level Bookmark behaviours and use cases.'' | ||
[[User:VladVukicevic|VladVukicevic]] 20:26, 6 Jul 2005 (PDT): Updated API incorporating comments, and expanding in-IDL documentation. All bmI* became mozI*. Removed the forwarded nsIMutableArray methods from mozIBookmarkContainer, and just required all mozIBookmarkContainer implementations to also implement nsIMutableArray. All mozIBookmarkNode implementations also must implement nsIWritablePropertyBag. Removed serialization/deserialization -- the property bag for each node should contain the entire state of that node, and will be serialized/deserialized automatically if the node is serialized. | |||
<pre> | <pre> | ||
/* | /* | ||
* The Provider is responsible for creating new bookmark nodes. | * The Provider is responsible for creating new bookmark nodes. | ||
Line 18: | Line 19: | ||
[scriptable, uuid(230e3f93-ce0b-48e1-ad40-e51cb6b8b814)] | [scriptable, uuid(230e3f93-ce0b-48e1-ad40-e51cb6b8b814)] | ||
interface | interface mozIBookmarkProvider : nsISupports { | ||
/** | /** | ||
* The name of this provider's bookmark types, as displayed in the | * The name of this provider's bookmark types, as displayed in the UI. | ||
* Should be localized! | * Should be localized! | ||
*/ | */ | ||
Line 32: | Line 33: | ||
/** | /** | ||
* Create a new bookmark | * Whether this provider can create items. | ||
*/ | |||
readonly attribute boolean canCreateItems; | |||
/** | |||
* Whether this provider can create containers. | |||
*/ | |||
readonly attribute boolean canCreateContainers; | |||
/** | |||
* Create a new bookmark item from this provider. This item should | |||
* be initialized to some sane defaults; however, it is possile that | |||
* immediately after createItem() the node's property bag will | |||
* be filled in with properties read from storage to recreate a | |||
* bookmark item that was written to disk. | |||
* | * | ||
* @returns a new | * @returns a new mozIBookmarkItem instance for this provider. | ||
*/ | */ | ||
mozIBookmarkItem createItem(); | |||
/** | /** | ||
* | * Create a new bookmark container from this provider. This item | ||
* should be initialized to some sane defaults; however, it is | |||
* | * possile that immediately after createItem() the node's property | ||
* bag will be filled in with properties read from storage to | |||
* | * recreate a bookmark item that was written to disk. | ||
* | |||
* | |||
* | * | ||
* @ | * @returns a new mozIBookmarkItem instance for this provider. | ||
*/ | */ | ||
mozIBookmarkContainer createContainer(); | |||
}; | }; | ||
Line 63: | Line 73: | ||
[scriptable, uuid(5ee39c0f-74f1-48ed-990f-fd68f28028e0)] | [scriptable, uuid(5ee39c0f-74f1-48ed-990f-fd68f28028e0)] | ||
interface | interface mozIBookmarkService : nsISupports { | ||
/ | /* convenience to avoid having to call getKnownBookmark(BookmarksRoot) */ | ||
attribute | attribute mozIBookmarkContainer bookmarksRoot; | ||
/* well-known bookmark node identifiers | |||
* XXX - how do we actually set the BookmarksToolbarFolder? | |||
*/ | |||
const unsigned long BookmarksRoot = 0; | const unsigned long BookmarksRoot = 0; | ||
const unsigned long BookmarksToolbarFolder = 1; | const unsigned long BookmarksToolbarFolder = 1; | ||
Line 76: | Line 89: | ||
* @param bmtype well-known bookmark id | * @param bmtype well-known bookmark id | ||
* | * | ||
* @returns | * @returns mozIBookmarkNode for the given bookmark id, or null | ||
* if that well-known bookmark type isn't present in the current | * if that well-known bookmark type isn't present in the current | ||
* bookmarks hierarchy. | * bookmarks hierarchy. | ||
Line 82: | Line 95: | ||
* @throws NS_ERROR_INVALID_ARG if bmtype is invalid. | * @throws NS_ERROR_INVALID_ARG if bmtype is invalid. | ||
*/ | */ | ||
mozIBookmarkNode getKnownBookmark(in string bmtype); | |||
/** | /** | ||
* Get a bookmark by string id, which is | * Get a bookmark by string id, which is mozIBookmarkNode.id. | ||
* | * | ||
* @param bmid the bookmark node's id which to return. | * @param bmid the bookmark node's id which to return. | ||
* | * | ||
* @returns | * @returns mozIBookmarkNode for the given id, or null | ||
* if bmid can't be found. | * if bmid can't be found. | ||
*/ | */ | ||
mozIBookmarkNode getBookmarkById(in string bmid); | |||
/** | |||
* Get an array of bookmarks by property name and value. | |||
* | |||
* @param propName The property name to search for. | |||
* @param propValue The property value to search for. | |||
* | |||
* @returns An array of mozIBookmarkNodes. | |||
*/ | |||
void getBookmarksByProperty(in string propName, in nsIVariant propValue, | |||
out PRUint32 retCount, | |||
[retval,array,size_is(retCount)] out mozIBookmarkNode retNodes); | |||
/** | /** | ||
* Create a bookmark with the given type. This is a convenience | * Create a bookmark with the given type. This is a convenience | ||
* function, which will call getService to obtain a | * function, which will call getService to obtain a mozIBookmarkProvider | ||
* for that type, and call its createBookmark function. | * for that type, and call its createBookmark function. | ||
* | * | ||
Line 103: | Line 128: | ||
* @returns a new bookmark of the given type. | * @returns a new bookmark of the given type. | ||
* | * | ||
* @see | * @see mozIBookmarkProvider::createBookmark | ||
*/ | */ | ||
mozIBookmarkNode createBookmark(in string type); | |||
/** | /** | ||
Line 112: | Line 137: | ||
* @param obs the observer to add. | * @param obs the observer to add. | ||
*/ | */ | ||
void addObserver(in | void addObserver(in mozIBookmarkObserver obs); | ||
/** | /** | ||
Line 121: | Line 146: | ||
* @throws NS_ERROR_INVALID_ARG if the observer isn't found. | * @throws NS_ERROR_INVALID_ARG if the observer isn't found. | ||
*/ | */ | ||
void removeObserver(in | void removeObserver(in mozIBookmarkObserver obs); | ||
}; | }; | ||
Line 128: | Line 153: | ||
*/ | */ | ||
[scriptable, uuid(75c53908-7aa0-45ee-a68a-f2db90374742)] | [scriptable, uuid(75c53908-7aa0-45ee-a68a-f2db90374742)] | ||
interface | interface mozIBookmarkObserver : nsISupports { | ||
/ | /** | ||
void onBookmarkAdded ( | * Notify this observer that the bookmark was added. | ||
* Called after the actual add took place. | |||
* | |||
* @param bmrk The bookmark node that was added. | |||
*/ | |||
void onBookmarkAdded (in mozIBookmarkNode bmrk); | |||
/ | /** | ||
void onBookmarkRemoved ( | * Notify this observer that the bookmark was removed. | ||
* Called before the actual remove takes place. | |||
* | |||
* @param bmrk The bookmark that will be removed. | |||
*/ | |||
void onBookmarkRemoved (in mozIBookmarkNode bmrk); | |||
/** | |||
* Notify this observer that the bookmark's position in the given | |||
* container has changed. The old index of the bookmark within the | |||
* container is passed in, as well as the new index. Note that the | |||
* new index is relative to the container without the old bookmark, | |||
* and indicates that the bookmark was inserted at that position and | |||
* any elements present there are pushed forward. | |||
* | |||
* @param container The bookmark container in which the bookmark moved. | |||
* @param bmrk The bookmark which moved. | |||
* @param oldIndex The bookmark's old index in the container. | |||
* @param newIndex The bookmark's new index in the container. | |||
*/ | |||
void onBookmarkMoved (in mozIBookmarkContainer container, | |||
in mozIBookmarkNode bmrk, | |||
in unsigned long oldIndex, | |||
in unsigned long newIndex); | |||
unsigned long oldIndex); | |||
/ | /** | ||
void onBookmarkChanged ( | * Notify this observer that a bookmark's information has changed. This | ||
* will be called whenever any attributes like "name" are changed, | |||
* or whenever any properties on the property bag are modified. | |||
* | |||
* @param bmrk The bookmark which changed. | |||
*/ | |||
void onBookmarkChanged (in mozIBookmarkNode bmrk); | |||
}; | }; | ||
/** | /** | ||
* A Node in the bookmarks tree. Providers may derive | * A Node in the bookmarks tree. Providers may derive their own Node | ||
* | * implementations from this interface, if they wish to expose | ||
* additional functionality. | |||
* | * | ||
* A | * A mozIBookmarkNode must also implement a nsIWritablePropertyBag for | ||
* | * storing arbitrary data along with the bookmark. | ||
*/ | */ | ||
[scriptable, uuid(be2823f2-79b4-4835-8a27-68efe378659f)] | [scriptable, uuid(be2823f2-79b4-4835-8a27-68efe378659f)] | ||
interface | interface mozIBookmarkNode : nsISupports { | ||
/** | |||
* UUID for this node | |||
*/ | |||
readonly attribute string id; | readonly attribute string id; | ||
readonly attribute string | |||
/** | |||
* The provider type; part of the provider's contractid | |||
*/ | |||
readonly attribute string providerType; | |||
/** | |||
* Whether this node is read-only; in other whether, the | |||
* name or any other properties can be changed. | |||
*/ | |||
readonly attribute boolean readOnly; | readonly attribute boolean readOnly; | ||
Line 179: | Line 244: | ||
*/ | */ | ||
attribute PRTime creationTime; | attribute PRTime creationTime; | ||
/** | /** | ||
Line 194: | Line 252: | ||
/** | /** | ||
* | * Tests whether this node can be contained by the given container. | ||
* Both the container and the node have a chance to reject a parent-child | |||
* relationship (via canBeContainedBy and canContain). | |||
* | |||
* @param bmcontainer The container to test. | |||
* | |||
* @returns a boolean indicating whether this node can be contained | |||
* by the given container. | |||
*/ | */ | ||
boolean canBeContainedBy(in | boolean canBeContainedBy(in mozIBookmarkContainer bmcontainer); | ||
/** | /** | ||
* Return a clone of this node, using some node type that has no | * Return a clone of this node, using some node type that has no | ||
* restrictions (e.g. that it can be contained by a simple | * restrictions (e.g. that it can be contained by a simple container | ||
* | * -- in most cases, this would just use the simple item/container | ||
* types). This would be used to copy an otherwise read-only | * types). This would be used to copy an otherwise read-only child, | ||
* | * e.g. to save a RSS feed item into another folder. | ||
*/ | */ | ||
mozIBookmarkNode cloneSimple(); | |||
}; | }; | ||
Line 213: | Line 277: | ||
*/ | */ | ||
[scriptable, uuid(47e221fd-b4c3-4dc0-99da-8109c2730981)] | [scriptable, uuid(47e221fd-b4c3-4dc0-99da-8109c2730981)] | ||
interface | interface mozIBookmarkItem : mozIBookmarkNode { | ||
/** | /** | ||
* The URI for this item. | * The URI for this item. | ||
Line 227: | Line 291: | ||
/** | /** | ||
* A generic bookmark container, holding one or more child nodes. | * A generic bookmark container, holding one or more child nodes. | ||
* | |||
* Implementors of mozIBookmarkContainer MUST also implement | |||
* nsIMutableArray, which will be used to actually modify | |||
* the bookmark contents. | |||
*/ | */ | ||
[scriptable, uuid(3c82858d-9a17-45b7-87ef-173c70b1067e)] | [scriptable, uuid(3c82858d-9a17-45b7-87ef-173c70b1067e)] | ||
interface | interface mozIBookmarkContainer : mozIBookmarkNode { | ||
/** | /** | ||
* If the container contents are read only. If | * If the container contents are read only. If | ||
Line 236: | Line 304: | ||
* its children cannot be modified (e.g. can't add | * its children cannot be modified (e.g. can't add | ||
* or remove a child). | * or remove a child). | ||
* | |||
* Note that a readOnly node implies a read-only | |||
* container. | |||
*/ | */ | ||
readonly attribute boolean containerReadOnly; | readonly attribute boolean containerReadOnly; | ||
Line 246: | Line 317: | ||
/** | /** | ||
* Returns whether this container can contain a given node. | * Returns whether this container can contain a given node. | ||
* | |||
* @param bmrk The bookmark node to be tested. | |||
* | |||
* @returns a boolean indicating whether this container can | |||
* contain the given node or not. | |||
*/ | */ | ||
boolean canContain(in | boolean canContain(in mozIBookmarkNode bmrk); | ||
/** | |||
* Convenience function to avoid having to deal with an | |||
* enumerator in JavaScript. | |||
* | |||
* @returns an array of mozIBookmarkNodes in the current container. | |||
*/ | |||
void getBookmarks(out unsigned long count, | void getBookmarks(out unsigned long count, | ||
[retval,array,size_is(count)] out | [retval,array,size_is(count)] out mozIBookmarkNode bookmarks); | ||
}; | }; | ||
</pre> | </pre> |