offapi/com/sun/star/drawing/framework/XResourceId.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XResourceId.idl,v $
  10  * $Revision: 1.4 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef __com_sun_star_drawing_framework_XResourceId_idl__
  32 #define __com_sun_star_drawing_framework_XResourceId_idl__
  33
  34 #ifndef __com_sun_star_uno_XInterface_idl__
  35 #include <com/sun/star/uno/XInterface.idl>
  36 #endif
  37 #ifndef __com_sun_star_drawing_framework_AnchorBindingMode_idl__
  38 #include <com/sun/star/drawing/framework/AnchorBindingMode.idl>
  39 #endif
  40 #ifndef __com_sun_star_util_URL_idl__
  41 #include <com/sun/star/util/URL.idl>
  42 #endif
  43
  44 module com { module sun { module star { module drawing { module framework {
  45
  46 /** A resource id uses a set of URLs to unambiguously specify a resource of
  47     the drawing framework.
  48     <p>Resources of the drawing framework are panes, views, tool bars, and
  49     command groups.  One URL describes the type of the actual resource.  A
  50     sequence of URLs (typically one, sometimes two) specifies its anchor,
  51     the resource it is bound to.  The anchor typically is a pane (for
  52     views), or it is empty (for panes).</p>
  53     <p>The resource URL may be empty.  In this case the anchor is empty,
  54     too.  Such an empty resource id does not describe a resource but rather
  55     the absence of one.  Instead of an empty <type>XResourceId</type> object
  56     an empty reference can be used in many places.</p>
  57     <p>The resource URL may have arguments that are passed to the factory
  58     method on its creation.  Arguments are only available through the
  59     getFullResourceURL().  The getResourceURL() method strips them away.</p>
  60 */
  61 interface XResourceId
  62 {
  63     /** Return the URL of the resource.  Arguments supplied on creation are
  64         stripped away.  Use getFullResourceURL() to access them.
  65     */
  66     string getResourceURL ();
  67
  68     /** Return an URL object of the resource URL that may contain arguments.
  69     */
  70     com::sun::star::util::URL getFullResourceURL ();
  71
  72     /** Return whether there is a non-empty anchor URL.  When this method
  73         returns <FALSE/> then getAnchorURLs() will return an empty list.
  74     */
  75     boolean hasAnchor ();
  76
  77     /** Return a new XResourceId that represents the anchor resource.
  78     */
  79     XResourceId getAnchor ();
  80
  81     /** Return the, possibly empty, list of anchor URLs.  The URLs are
  82         ordered so that the one in position 0 is the direct anchor of the
  83         resource, while the one in position i+1 is the direct anchor of the
  84         one in position i.
  85     */
  86     sequence<string> getAnchorURLs ();
  87
  88     /** Return the type prefix of the resource URL.  This includes all up to
  89         and including the second slash.
  90     */
  91     string getResourceTypePrefix ();
  92
  93     /** Compare the called <type>XResourceId</type> object with the given
  94         one.
  95         <p>The two resource ids A and B are compared so that if A<B (return
  96         value is -1) then either A and B are unrelated or A is a direct or
  97         indirect anchor of B.</p>
  98         <p>The algorithm for this comparison is quite simple. It uses a
  99         double lexicographic ordering.  On the lower level individual URLs
 100         are compared via the lexicographic order defined on strings.  On the
 101         higher level two resource ids are compared via a lexicographic order
 102         defined on the URLS.  So when there are two resource ids A1.A2
 103         (A1 being the anchor of A2) and B1.B2 then A1.A2<B1.B2 when A1<B1 or
 104         A1==B1 and A2<B2.  Resource ids may have different lengths: A1 <
 105         B1.B2 when A1<B1 or A1==B1 (anchors first then resources linked to them.</p>
 106         @param xId
 107             The resource id to which the called resource id is compared.
 108         @return
 109             Returns <const>0</const> when the called resource id is
 110             equivalent to the given resource id. Returns <code>-1</code> or
 111             <code>+1</code> when the two compared resource ids differ.
 112     */
 113     short compareTo (
 114         [in] XResourceId xId);
 115
 116     /** Return whether the anchor of the called resource id object
 117         represents the same resource as the given object.
 118         <p>Note that not only the anchor of the given object is taken into
 119         account. The whole object, including the resource URL, is
 120         interpreted as anchor resource.</p>
 121         @param xAnchor
 122             The resource id of the anchor.
 123         @param eMode
 124             This mode specifies how the called resource has to be bound to
 125             the given anchor in order to have this function return <TRUE/>.
 126             <p>If eMode is <const>DIRECT</const> then the anchor of the called resource id
 127             has to be identical to the given anchor. If eMode is
 128             <const>INDIRECT</const> then the given anchor has to be a part
 129             of the anchor of the called resource.
 130     */
 131     boolean isBoundTo (
 132         [in] XResourceId xId,
 133         [in] AnchorBindingMode eMode);
 134
 135     /** Return whether the anchor of the called resource id object
 136         represents the same resource as the given anchor URL. This is a
 137         convenience variant of the <member>isBoundTo()</member> function
 138         that can also be seen as an optimization for the case that the
 139         anchor consists of exactly one URL.
 140         @param xAnchor
 141             The resource URL of the anchor.
 142         @param eMode
 143             This mode specifies how the called resource has to be bound to
 144             the given anchor in order to have this function return. See the
 145             description of <member>isBoundTo()</member> for more
 146             information.
 147     */
 148     boolean isBoundToURL (
 149         [in] string sAnchorURL,
 150         [in] AnchorBindingMode eMode);
 151
 152     /** Return a copy of the called resource id.  The caller becomes the
 153         owner of the new object.
 154     */
 155     XResourceId clone ();
 156 };
 157
 158 }; }; }; }; }; // ::com::sun::star::drawing::framework
 159
 160 #endif