Songbird / Development / Songbird Add-Ons API Documentation

components/servicepane/public/sbIServicePaneService.idl

Go to the documentation of this file.
00001 /* vim: ts=2 sw=2 expandtab
00002 //
00003 // BEGIN SONGBIRD GPL
00004 //
00005 // This file is part of the Songbird web player.
00006 //
00007 // Copyright(c) 2005-2008 POTI, Inc.
00008 // http://songbirdnest.com
00009 //
00010 // This file may be licensed under the terms of of the
00011 // GNU General Public License Version 2 (the "GPL").
00012 //
00013 // Software distributed under the License is distributed
00014 // on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either
00015 // express or implied. See the GPL for the specific language
00016 // governing rights and limitations.
00017 //
00018 // You should have received a copy of the GPL along with this
00019 // program. If not, go to http://www.gnu.org/licenses/gpl.html
00020 // or write to the Free Software Foundation, Inc.,
00021 // 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
00022 //
00023 // END SONGBIRD GPL
00024 //
00025 */
00026 
00032 #include "nsISupports.idl"
00033 
00034 interface nsIArray;
00035 interface nsIRDFDataSource;
00036 interface nsIRDFResource;
00037 interface nsIDOMXULElement;
00038 interface nsIDOMNode;
00039 interface nsIDOMWindow;
00040 interface nsISimpleEnumerator;
00041 interface nsIDragSession;
00042 interface nsITransferable;
00043 interface nsIStringBundle;
00044 
00049 [scriptable, uuid(d730af19-1b0b-4679-9f22-b41caa4ec59a)]
00050 interface sbIServicePaneNode : nsISupports
00051 {
00052   /* \brief the uri of this node as an RDF resource */
00053   readonly attribute nsIRDFResource resource;
00054   
00055   /* \brief the uri of this node as a string */
00056   readonly attribute AString id;
00057   
00058   /* \brief can this node have children */
00059   readonly attribute boolean isContainer;
00060   
00061   /* \brief the URL to load when the node is clicked on in the tree */
00062   attribute AString url;
00063   /* \brief the URL of the image to display in the tree */
00064   attribute AString image;
00065   /* \brief the name to display in the tree */
00066   attribute AString name;
00067   /* \brief the tooltip to display when the user hovers over the node in the tree */
00068   attribute AString tooltip;
00069   /* \brief should the node be hidden in the tree ? */
00070   attribute boolean hidden;
00071   /* \brief should the node name be editable in the tree ? */
00072   attribute boolean editable;
00073   /* \brief is the this node open in the tree? */
00074   attribute boolean isOpen;
00075   /* \brief the contract id of the service that owns the node */
00076   attribute AString contractid;
00077   
00078   /* drag and drop reordering helper attributes */
00079   /* \brief a comma separated list of drag types to offer for reordering */
00080   attribute AString dndDragTypes;
00081   /* \brief a comma separated list of drag types to allow to be reordered before or after */
00082   attribute AString dndAcceptNear;
00083   /* \brief a comma separated list of drag types to allow dropping into */
00084   attribute AString dndAcceptIn;
00085   
00086   /* \brief the uri of a stringbundle to use to translate the properties of this node */
00087   attribute AString stringbundle;
00088 
00089   /* \brief space separated list of property IDs, used to style the tree cell */
00090   attribute AString properties;
00091 
00092   
00093   // here's a subset of the W3C DOM Level 1 Core
00094   
00095   AString getAttributeNS(in AString aNamespace,
00096                          in AString aName);
00097   AString setAttributeNS(in AString aNamespace,
00098                          in AString aName,
00099                          in AString aValue);
00100   boolean hasAttributeNS(in aString aNamespace,
00101                          in AString aName);
00102   
00103   readonly attribute nsISimpleEnumerator childNodes;
00104   readonly attribute sbIServicePaneNode firstChild;
00105   readonly attribute sbIServicePaneNode lastChild;
00106   readonly attribute sbIServicePaneNode nextSibling;
00107   readonly attribute sbIServicePaneNode parentNode;
00108   readonly attribute sbIServicePaneNode previousSibling;
00109   
00110   sbIServicePaneNode appendChild (in sbIServicePaneNode aChild);
00111   sbIServicePaneNode insertBefore (in sbIServicePaneNode aNewNode,
00112                                    in sbIServicePaneNode aAdjacentNode);
00113   void removeChild (in sbIServicePaneNode aChild);
00114   void replaceChild (in sbIServicePaneNode aNewNode,
00115                      in sbIServicePaneNode aOldNode);
00116   
00117   
00118   // potential additions:
00119   // readonly attribute ownerDataSource; // like ownerDocument
00120   // boolean hasChildNodes();
00121   // AString getAttribute(in AString aName);
00122   // AString setAttribute(in AString aName, in AString aValue);
00123   // AString removeAttribute(in AString aName);
00124   // AString removeAttributeNS(in AString aNamespace, in AString aName);
00125   // some way to enumerate attributes
00126   // readonly attribute AString namespaceURI; // default attribute namespace
00127 };
00128 
00133 [scriptable, uuid(9bbc6245-475e-464b-834c-9a45d7642f2b)]
00134 interface sbIServicePaneNodeInternal : sbIServicePaneNode {
00140   void unlinkChild (in sbIServicePaneNode aChild);
00141   
00145   void unlinkNode ();
00146   
00152   void clearNode ();
00153 };
00154 
00159 [scriptable, uuid(0c86331b-6767-4595-95e7-80f775ab1770)]
00160 interface sbIServicePaneListener : nsISupports {
00166   void nodePropertyChanged(in string aNodeId, in string aAttributeName);
00167 };
00168 
00169 
00170 
00180 [scriptable, uuid(01935bf0-70a4-4334-b166-0349ced535bf)]
00181 interface sbIServicePaneService : nsISupports
00182 {
00186   readonly attribute nsIRDFDataSource dataSource;
00187 
00191   readonly attribute sbIServicePaneNode root;
00192 
00196   void init();
00197 
00198   /* \brief Add a node to the tree
00199    * Create a new node and add it as a child of the specified parent. If a
00200    * child with the given id already exists then do not create it, and return
00201    * null. Otherwise return a node object.
00202    * \param aId an URN to use as the ID, or null if it should be anonymous
00203    * \param aParent the desired parent node
00204    * \param aContainer should the new node be a container
00205    * \return node object, or null if the node couldn't be created
00206    */
00207   sbIServicePaneNode addNode(in AString aId,
00208                              in sbIServicePaneNode aParent,
00209                              in boolean aContainer);
00210   
00211   /* \brief Remove a node and all its children
00212    * Remove a node from the tree and all its children and all their childen and
00213    * so on.
00214    * \param aNode the node to remove
00215    */
00216   void removeNode(in sbIServicePaneNode aNode);
00217   
00218   /* \brief Get the node object for the given id
00219    * \param aId the ID of the desired node
00220    * \return node object, or null if it couldn't be found
00221    */
00222   sbIServicePaneNode getNode(in AString aId);
00223 
00224   /* \brief Get the first node object for the given url
00225    * \param aURL the url of the desired node
00226    * \return node object, or null if it couldn't be found
00227    */
00228   sbIServicePaneNode getNodeForURL(in AString aURL);
00229 
00230   /* \brief Get all nodes with the given attribute value
00231    * \param aNamespace the attribute namespace
00232    * \param aName the attribute name
00233    * \param aValue the attribute value
00234    * \return nsIArray of sbIServicePaneNode nodes with attribute value
00235    */
00236   nsIArray getNodesByAttributeNS(in AString aNamespace,
00237                                  in AString aName,
00238                                  in AString aValue);
00239 
00240   /* \brief Sort a node based on its weight attribute
00241    * \param aNode the node to sort
00242    */
00243   void sortNode(in sbIServicePaneNode aNode);
00244 
00245   /* \brief Save the state of the tree to disk.
00246    * This should go away and be handled magically
00247    */
00248   void save();
00249 
00250   /* \brief Fill the context menu for the given node
00251    * \param aId the id of the node
00252    * \param aContextMenu the menu we're trying to fill
00253    * \param aParentWindow the toplevel window we're displaying in
00254    */
00255   void fillContextMenu(in AString aId,
00256                        in nsIDOMXULElement aContextMenu,
00257                        in nsIDOMWindow aParentWindow);
00258   
00259   /* \brief Fill a menu with menuitems to create new tree nodes
00260    * \param aId the id of the node or null for the click and hold menu
00261    * \param aContextMenu the menu we're trying to fill
00262    * \param aParentWindow the toplevel window we're displaying in
00263    */
00264   void fillNewItemMenu(in AString aId,
00265                        in nsIDOMXULElement aContextMenu,
00266                        in nsIDOMWindow aParentWindow);
00267   
00268   /* \brief Selection changes notification
00269    * \param aId the id of the node that is now selected
00270    * \param aContainer The container object that implements the selection
00271    * \param aParentWindow the toplevel window we're displaying in
00272    */
00273   void onSelectionChanged(in AString aId,
00274                           in nsIDOMNode aContainer,
00275                           in nsIDOMWindow aParentWindow);
00276   
00277   /* I think we'll need to have this interface too:
00278   nsITreeView wrapTreeView(in nsITreeView aTreeView);
00279   it will take an existing tree-builder tree view and add some
00280   functionality that we want to have
00281   */
00282   
00283   /* drag and drop support */
00284   PRBool canDrop(in AString aID,
00285                  in nsIDragSession aDragSession,
00286                  in PRInt32 aOrientation,
00287                  in nsIDOMWindow aWindow);
00288                  
00289   void onDrop(in AString aID,
00290               in nsIDragSession aDragSession,
00291               in PRInt32 aOrientation,
00292               in nsIDOMWindow aWindow);
00293               
00294   PRBool onDragGesture(in AString aID,
00295                        out nsITransferable aTransferable);
00296 
00297   /* \brief Called when a node is renamed by the user, allows
00298    *        the node owner to accept the action by setting the
00299    *        node name to the given value.
00300    * \param aId the ID of the node being renamed
00301    * \param aNewName new name entered by the user
00302    */
00303   void onRename(in AString aID,
00304                 in AString aNewName);
00305 
00306   /* \brief Add a service pane listener
00307    * \param aListener the listener to add
00308    */
00309   void addListener(in sbIServicePaneListener aListener);
00310 
00311   /* \brief Remove a service pane listener
00312    * \param aListener the listener to remove
00313    */
00314   void removeListener(in sbIServicePaneListener aListener);
00315 };
00316 
00317 
00322 [scriptable, uuid(db05f541-6e70-4fad-98fc-e50820d36648)]
00323 interface sbIServicePaneModule : nsISupports
00324 {
00325   /* \brief Initialize this service pane module
00326    * This is where the module should set itself up in the tree if it hasn't
00327    * before.
00328    * \param aServicePaneService the service pane service instance
00329    */
00330   void servicePaneInit(in sbIServicePaneService aServicePaneService);
00331   
00332   /* \brief Fill the context menu for the given node
00333    * \param aNode the node that was context-clicked on
00334    * \param aContextMenu the menu we're trying to fill
00335    * \param aParentWindow the toplevel window we're displaying in
00336    */
00337   void fillContextMenu(in sbIServicePaneNode aNode,
00338                        in nsIDOMXULElement aContextMenu,
00339                        in nsIDOMWindow aParentWindow);
00340   
00341   void fillNewItemMenu(in sbIServicePaneNode aNode,
00342                        in nsIDOMXULElement aContextMenu,
00343                        in nsIDOMWindow aParentWindow);
00344 
00345   /* \brief Selection changes notification
00346    * \param aNode the node that is now selected
00347    * \param aParentWindow the toplevel window we're displaying in
00348    */
00349   void onSelectionChanged(in sbIServicePaneNode aNode,
00350                           in nsIDOMNode aContainer,
00351                           in nsIDOMWindow aParentWindow);
00352 
00353   PRBool canDrop(in sbIServicePaneNode aNode,
00354                  in nsIDragSession aDragSession,
00355                  in PRInt32 aOrientation,
00356                  in nsIDOMWindow aWindow);
00357   void onDrop(in sbIServicePaneNode aNode,
00358               in nsIDragSession aDragSession,
00359               in PRInt32 aOrientation,
00360               in nsIDOMWindow aWindow);
00361   PRBool onDragGesture(in sbIServicePaneNode aNode,
00362                        in nsITransferable aTransferable);
00363 
00364   /* \brief Called when a node is renamed by the user, allows
00365    *        the module to accept the action by setting the
00366    *        node name to the given value.
00367    * \param aNode the node that was renamed
00368    * \param aNewName new name entered by the user
00369    */
00370   void onRename(in sbIServicePaneNode aNode,
00371                 in AString aNewName);
00372   
00373   /* \brief optional URI of stringbundle to use to localize names of nodes
00374     associated with this module */
00375   readonly attribute AString stringbundle;
00376 
00377   /* \brief Called when service pane service is shutting down
00378    */
00379   void shutdown();
00380 };
00381 
00382 

Generated on Tue Mar 10 14:28:55 2009 for Songbird by  doxygen 1.5.2