offapi/com/sun/star/resource/XStringResourceResolver.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: XStringResourceResolver.idl,v $
  10  * $Revision: 1.3 $
  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 #ifndef __com_sun_star_resource_XStringResourceResolver_idl__
  31 #define __com_sun_star_resource_XStringResourceResolver_idl__
  32
  33 #ifndef __com_sun_star_resource_MissingResourceException_idl__
  34 #include <com/sun/star/resource/MissingResourceException.idl>
  35 #endif
  36
  37 #ifndef __com_sun_star_util_XModifyBroadcaster_idl__
  38 #include <com/sun/star/util/XModifyBroadcaster.idl>
  39 #endif
  40
  41 #ifndef __com_sun_star_lang_Locale_idl__
  42 #include <com/sun/star/lang/Locale.idl>
  43 #endif
  44
  45
  46 //=============================================================================
  47
  48 module com { module sun { module star { module resource {
  49
  50 //=============================================================================
  51 /**
  52     Interface to access strings in a resource.
  53
  54     The interface is derived from
  55     <type scope="com::sun::star::util">XModifyBroadcaster</type>
  56
  57     All registered <type scope="com::sun::star::util">XModifyListener</type>
  58     interfaces will be notified if either the current locale changes or if
  59     a string is added, changed or removed. This usually will only happen if
  60     the implementing object also supports the interface
  61     <type scope="com::sun::star::resource">XStringResourceManager</type>
  62     and is used in the design mode of a Dialog or String table editor.
  63     But also changing the locale at runtime can be supported in this way.
  64
  65 */
  66 interface XStringResourceResolver: com::sun::star::util::XModifyBroadcaster
  67 {
  68     /**
  69         Resolves the passed ResoureID for the current locale. This
  70         locale is set during initalisation of the object implementing
  71         this interface or - in case that also the interface
  72         <type scope="com::sun::star::resource">XStringResourceManager</type>
  73         is supported - by using the <code>XStringResourceManager::setLocale</code>
  74         method.
  75
  76         @param ResourceID
  77             ID to specify the string inside the resource.
  78             The ID can - but not needs to - be a hierarchical
  79             name like "foo.nothing.invalid".
  80
  81         @return  the localized string for the specified ID
  82
  83         @throws ::com::sun::star::resource::MissingResourceException
  84             if no entry exists for the given ResourceID
  85     */
  86     string resolveString( [in] string ResourceID )
  87         raises( com::sun::star::resource::MissingResourceException );
  88
  89
  90     /** Resolves the passed ResoureID for a specific locale.
  91
  92         It's not recommended to use this method to get the best
  93         performance as the implementation may be optimized for
  94         the use of the current locale.
  95
  96         @param ResourceID
  97             ID to specify the string inside the resource.
  98             The ID can - but not needs to - be a hierarchical
  99             name like "foo.nothing.invalid".
 100
 101         @param locale
 102             The locale the string should be resolved for.
 103             The locale has to match exactly with one of the locales provided by
 104             <member>getLocales</member>. A closest match search is not supported.
 105
 106         @return  the localized string for the specified ID and Locale
 107
 108         @throws <type scope="com::sun::star::resource">MissingResourceException</type>
 109             if no entry exists for the given ResourceID or locale
 110     */
 111     string resolveStringForLocale( [in] string ResourceID, [in] com::sun::star::lang::Locale locale )
 112         raises( com::sun::star::resource::MissingResourceException );
 113
 114
 115     /**
 116         Checks if the resource contains an entry for the given ResourceID
 117         and current locale.
 118
 119         @param ResourceID
 120             ID to specify the string inside the resource.
 121
 122         @return  <TRUE/> if an entry exists, otherwise <FALSE/>
 123
 124     */
 125     boolean hasEntryForId( [in] string ResourceID );
 126
 127
 128     /**
 129         Checks if the resource contains an entry for the given ResourceID and locale.
 130
 131         It's not recommended to use this method to get the best
 132         performance as the implementation may be optimized for
 133         the use of the current locale.
 134
 135         @param ResourceID
 136             ID to specify the string inside the resource.
 137
 138         @param locale
 139             The locale the entry should be checked for.
 140             The locale has to match exactly with one of the locales provided by
 141             <member>getLocales</member>. A closest match search is not supported.
 142
 143         @return  <TRUE/> if an entry exists, otherwise <FALSE/>
 144     */
 145     boolean hasEntryForIdAndLocale( [in] string ResourceID, [in] com::sun::star::lang::Locale locale );
 146
 147
 148     /**
 149         Returns a sequence of all valid Resource IDs for the current locale
 150
 151         @return  a sequence of all valid Resource IDs
 152     */
 153     sequence<string> getResourceIDs();
 154
 155
 156     /**
 157         Returns a sequence of all valid Resource IDs for a specific locale
 158
 159         It's not recommended to use this method to get the best
 160         performance as the implementation may be optimized for
 161         the use of the current locale.
 162
 163         @param locale
 164             The locale the ResourceIDs should be returned for.
 165             The locale has to match exactly with one of the locales provided by
 166             <member>getLocales</member>. A closest match search is not supported.
 167
 168         @return  a sequence of all valid Resource IDs
 169     */
 170     sequence<string> getResourceIDsForLocale( [in] com::sun::star::lang::Locale locale );
 171
 172
 173     /** Returns the current locale specified in the accessed resource.
 174
 175         If no locale is available, the returned Locale structure
 176         only contains empty strings.
 177
 178         @returns  the used locale
 179     */
 180     com::sun::star::lang::Locale getCurrentLocale();
 181
 182
 183     /** Returns the default locale of the accessed resource. In many
 184         cases this will be the locale of the Office initially used
 185         to create the resource.
 186
 187         @return  the used locale
 188     */
 189     com::sun::star::lang::Locale getDefaultLocale();
 190
 191
 192     /**
 193         Returns a sequence of all supported locales
 194
 195         @return  a sequence of all supported locales
 196     */
 197     sequence<com::sun::star::lang::Locale> getLocales();
 198 };
 199
 200 //=============================================================================
 201
 202 }; }; }; };
 203
 204 #endif