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