offapi/com/sun/star/resource/XStringResourceResolver.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef __com_sun_star_resource_XStringResourceResolver_idl__
  20 #define __com_sun_star_resource_XStringResourceResolver_idl__
  21
  22 #include <com/sun/star/resource/MissingResourceException.idl>
  23 #include <com/sun/star/util/XModifyBroadcaster.idl>
  24 #include <com/sun/star/lang/Locale.idl>
  25
  26
  27
  28 module com { module sun { module star { module resource {
  29
  30 /**
  31     Interface to access strings in a resource.
  32
  33     The interface is derived from
  34     com::sun::star::util::XModifyBroadcaster
  35
  36     All registered com::sun::star::util::XModifyListener
  37     interfaces will be notified if either the current locale changes or if
  38     a string is added, changed or removed. This usually will only happen if
  39     the implementing object also supports the interface
  40     com::sun::star::resource::XStringResourceManager
  41     and is used in the design mode of a Dialog or String table editor.
  42     But also changing the locale at runtime can be supported in this way.
  43
  44 */
  45 interface XStringResourceResolver: com::sun::star::util::XModifyBroadcaster
  46 {
  47     /**
  48         Resolves the passed ResoureID for the current locale. This
  49         locale is set during initialization of the object implementing
  50         this interface or - in case that also the interface
  51         com::sun::star::resource::XStringResourceManager
  52         is supported - by using the <code>XStringResourceManager::setLocale</code>
  53         method.
  54
  55         @param ResourceID
  56             ID to specify the string inside the resource.
  57             The ID can - but not needs to - be a hierarchical
  58             name like "foo.nothing.invalid".
  59
  60         @return  the localized string for the specified ID
  61
  62         @throws ::com::sun::star::resource::MissingResourceException
  63             if no entry exists for the given ResourceID
  64     */
  65     string resolveString( [in] string ResourceID )
  66         raises( com::sun::star::resource::MissingResourceException );
  67
  68
  69     /** Resolves the passed ResoureID for a specific locale.
  70
  71         It's not recommended to use this method to get the best
  72         performance as the implementation may be optimized for
  73         the use of the current locale.
  74
  75         @param ResourceID
  76             ID to specify the string inside the resource.
  77             The ID can - but not needs to - be a hierarchical
  78             name like "foo.nothing.invalid".
  79
  80         @param locale
  81             The locale the string should be resolved for.
  82             The locale has to match exactly with one of the locales provided by
  83             getLocales(). A closest match search is not supported.
  84
  85         @return  the localized string for the specified ID and Locale
  86
  87         @throws com::sun::star::resource::MissingResourceException
  88             if no entry exists for the given ResourceID or locale
  89     */
  90     string resolveStringForLocale( [in] string ResourceID, [in] com::sun::star::lang::Locale locale )
  91         raises( com::sun::star::resource::MissingResourceException );
  92
  93
  94     /**
  95         Checks if the resource contains an entry for the given ResourceID
  96         and current locale.
  97
  98         @param ResourceID
  99             ID to specify the string inside the resource.
 100
 101         @return  `TRUE` if an entry exists, otherwise `FALSE`
 102
 103     */
 104     boolean hasEntryForId( [in] string ResourceID );
 105
 106
 107     /**
 108         Checks if the resource contains an entry for the given ResourceID and locale.
 109
 110         It's not recommended to use this method to get the best
 111         performance as the implementation may be optimized for
 112         the use of the current locale.
 113
 114         @param ResourceID
 115             ID to specify the string inside the resource.
 116
 117         @param locale
 118             The locale the entry should be checked for.
 119             The locale has to match exactly with one of the locales provided by
 120             getLocales(). A closest match search is not supported.
 121
 122         @return  `TRUE` if an entry exists, otherwise `FALSE`
 123     */
 124     boolean hasEntryForIdAndLocale( [in] string ResourceID, [in] com::sun::star::lang::Locale locale );
 125
 126
 127     /**
 128         Returns a sequence of all valid Resource IDs for the current locale
 129
 130         @return  a sequence of all valid Resource IDs
 131     */
 132     sequence<string> getResourceIDs();
 133
 134
 135     /**
 136         Returns a sequence of all valid Resource IDs for a specific locale
 137
 138         It's not recommended to use this method to get the best
 139         performance as the implementation may be optimized for
 140         the use of the current locale.
 141
 142         @param locale
 143             The locale the ResourceIDs should be returned for.
 144             The locale has to match exactly with one of the locales provided by
 145             getLocales(). A closest match search is not supported.
 146
 147         @return  a sequence of all valid Resource IDs
 148     */
 149     sequence<string> getResourceIDsForLocale( [in] com::sun::star::lang::Locale locale );
 150
 151
 152     /** Returns the current locale specified in the accessed resource.
 153
 154         If no locale is available, the returned Locale structure
 155         only contains empty strings.
 156
 157         @returns  the used locale
 158     */
 159     com::sun::star::lang::Locale getCurrentLocale();
 160
 161
 162     /** Returns the default locale of the accessed resource. In many
 163         cases this will be the locale of the Office initially used
 164         to create the resource.
 165
 166         @return  the used locale
 167     */
 168     com::sun::star::lang::Locale getDefaultLocale();
 169
 170
 171     /**
 172         Returns a sequence of all supported locales
 173
 174         @return  a sequence of all supported locales
 175     */
 176     sequence<com::sun::star::lang::Locale> getLocales();
 177 };
 178
 179
 180 }; }; }; };
 181
 182 #endif
 183
 184 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */