offapi/com/sun/star/resource/XStringResourceManager.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_XStringResourceManager_idl__
  20 #define __com_sun_star_resource_XStringResourceManager_idl__
  21
  22 #include <com/sun/star/resource/MissingResourceException.idl>
  23 #include <com/sun/star/resource/XStringResourceResolver.idl>
  24 #include <com/sun/star/container/ElementExistException.idl>
  25 #include <com/sun/star/lang/Locale.idl>
  26 #include <com/sun/star/lang/IllegalArgumentException.idl>
  27 #include <com/sun/star/lang/NoSupportException.idl>
  28
  29
  30
  31 module com { module sun { module star { module resource {
  32
  33 /**
  34     Interface to manage a resource string table containing a set of
  35     strings for different locales.
  36
  37     The interface is derived from
  38     com::sun::star::resource::XStringResourceResolver
  39     that allows to access the string table but not to modify it. This
  40     interface also allows to modify the string table.
  41
  42     It's designed to be used in the context of creating a string table,
  43     e.g. from a string table editor or from a Dialog Editor designing
  44     localized dialogs.
  45
  46 */
  47 interface XStringResourceManager: com::sun::star::resource::XStringResourceResolver
  48 {
  49     /**
  50         Returns the resource's read only state
  51
  52         @return  `TRUE` if the resource is read only, otherwise `FALSE`
  53     */
  54     boolean isReadOnly();
  55
  56
  57     /** Sets the locale to be used
  58
  59         @param Locale
  60             Specifies the current locale to be used.
  61
  62         @param FindClosestMatch
  63             <p>If true: If the exact locale that should be set is not available
  64             the method tries to find the closest match. E.g. if en_US is re-
  65             quired but not available, en would be the next choice. Finally
  66             the default locale will be used `TRUE`.
  67
  68             <p>If false: If the exact locale that should be set is not available
  69             a com::sun::star::lang::IllegalArgumentException
  70             is thrown.
  71
  72             <p>If false: If the exact locale that should be set is not available
  73             a com::sun::star::lang::IllegalArgumentException
  74             is thrown.
  75     */
  76     void setCurrentLocale
  77     (
  78         [in] com::sun::star::lang::Locale Locale,
  79         [in] boolean FindClosestMatch
  80     )
  81     raises( com::sun::star::lang::IllegalArgumentException );
  82
  83
  84     /** Sets the default locale to be used
  85
  86         @param Locale
  87             Specifies the default locale to be used.
  88             If this locale is not available a
  89             com::sun::star::lang::IllegalArgumentException
  90             is thrown.
  91
  92         @throws com::sun::star::lang::NoSupportException
  93             if the resource is read only, see isReadOnly()
  94     */
  95     void setDefaultLocale( [in] com::sun::star::lang::Locale Locale )
  96         raises( com::sun::star::lang::IllegalArgumentException,
  97                 com::sun::star::lang::NoSupportException );
  98
  99
 100     /**
 101         Associates a String to a Resource ID for the current locale.
 102         If an entry for the Resource ID already exists, the string
 103         associated with it will be overwritten, otherwise a new
 104         entry will be created.
 105
 106         @param ResourceID
 107             ID to address the string inside the resource for the current locale.
 108
 109         @param Str
 110             String to be associated with the Resource ID.
 111
 112         @throws com::sun::star::lang::NoSupportException
 113             if the resource is read only, see isReadOnly()
 114     */
 115     void setString
 116     (
 117         [in] string ResourceID,
 118         [in] string Str
 119     )
 120     raises( com::sun::star::lang::NoSupportException );
 121
 122
 123     /**
 124         Associates a String to a Resource ID for a specific locale.
 125         If an entry for the Resource ID already exists, the string
 126         associated with it will be overwritten, otherwise a new
 127         entry will be created.
 128
 129         It's not recommended to use this method to get the best
 130         performance as the implementation may be optimized for
 131         the use of the current locale.
 132
 133         @param ResourceID
 134             ID to address the string inside the resource.
 135
 136         @param Str
 137             String to be associated with the Resource ID.
 138
 139         @param locale
 140             The locale the string should be set for.
 141             The locale has to match exactly with one of the locales provided by
 142             getLocales(). A closest match search is not supported.
 143
 144         @throws com::sun::star::lang::NoSupportException
 145             if the resource is read only, see isReadOnly()
 146     */
 147     void setStringForLocale
 148     (
 149         [in] string ResourceID,
 150         [in] string Str,
 151         [in] com::sun::star::lang::Locale locale
 152     )
 153     raises( com::sun::star::lang::NoSupportException );
 154
 155
 156     /**
 157         Removes a Resource ID including the corresponding string for
 158         the current locale.
 159
 160         @param ResourceID
 161             The Resource ID to be removed for the current locale.
 162
 163         @throws
 164         com::sun::star::resource::MissingResourceException
 165         if the Resource ID is not valid.
 166
 167         @throws
 168         com::sun::star::lang::NoSupportException
 169         if the resource is read only, see isReadOnly()
 170     */
 171     void removeId( [in] string ResourceID )
 172         raises( com::sun::star::resource::MissingResourceException,
 173                 com::sun::star::lang::NoSupportException );
 174
 175
 176     /**
 177         Removes a Resource ID including the corresponding string for
 178         s specific locale.
 179
 180         @param ResourceID
 181             The Resource ID to be removed.
 182
 183         @param locale
 184             The locale the Resource ID should be removed for.
 185             The locale has to match exactly with one of the locales provided by
 186             getLocales(). A closest match search is not supported.
 187
 188         @throws
 189         com::sun::star::resource::MissingResourceException
 190         if the Resource ID is not valid.
 191
 192         @throws
 193         com::sun::star::lang::NoSupportException
 194         if the resource is read only, see isReadOnly()
 195     */
 196     void removeIdForLocale( [in] string ResourceID, [in] com::sun::star::lang::Locale locale )
 197         raises( com::sun::star::resource::MissingResourceException,
 198                 com::sun::star::lang::NoSupportException );
 199
 200
 201     /**
 202         Creates a new locale.
 203
 204         <p>For each existing ResourceID an empty string
 205         will be created. The first locale created will
 206         automatically be the first default locale.
 207         Otherwise strings for all already created IDs
 208         will be copied from the default locale.</p>
 209
 210         @throws
 211         com::sun::star::container::ElementExistException
 212         if the Locale already has been created.
 213
 214         @throws
 215         com::sun::star::lang::IllegalArgumentException
 216         if the Locale is not valid.
 217
 218         @throws
 219         com::sun::star::lang::NoSupportException
 220         if the resource is read only, see isReadOnly()
 221     */
 222     void newLocale( [in] com::sun::star::lang::Locale locale )
 223         raises( com::sun::star::container::ElementExistException,
 224                 com::sun::star::lang::IllegalArgumentException,
 225                 com::sun::star::lang::NoSupportException );
 226
 227
 228     /**
 229         Removes a locale completely including the corresponding
 230         strings for each locale.
 231
 232         @throws
 233         com::sun::star::lang::IllegalArgumentException
 234         if the Locale to be removed is not supported.
 235
 236         @throws
 237         com::sun::star::lang::NoSupportException
 238         if the resource is read only, see isReadOnly()
 239     */
 240     void removeLocale( [in] com::sun::star::lang::Locale locale )
 241         raises( com::sun::star::lang::IllegalArgumentException,
 242                 com::sun::star::lang::NoSupportException );
 243
 244
 245     /**
 246         Provides a numeric id that is unique within all Resource IDs
 247         used in the string table.
 248
 249         This method takes into account all Resource IDs starting with
 250         a decimal number and only evaluates the ID until the first non
 251         digit character is reached. This allows to extend unique IDs
 252         with individual identifiers without breaking the mechanism of
 253         this method.
 254
 255         Examples:
 256         ID "42" -> numeric id 42
 257         ID "0foo" -> numeric id 0
 258         ID "111.MyId.Something.Else" -> numeric id 111
 259         ID "No Digits" -> not considered for numeric id
 260
 261         The id returned will be 0 for an empty string table and it will
 262         be reset to 0 if all locales are removed. In all other cases
 263         this method returns the maximum numeric id used so far at the
 264         beginning of a Resource ID incremented by 1. When calling this
 265         method more than once always the same number will be returned
 266         until this number is really used at the beginning of a new
 267         Resource ID passed to setString() or
 268         setStringForLocale().
 269
 270         As the numeric id is guaranteed to be unique for the complete
 271         string table all locales are taken into account. So using this
 272         methods will force the implementation to load all locale data
 273         that may not have been loaded so far.
 274
 275         @throws
 276         com::sun::star::lang::NoSupportException
 277         if the next available id exceeds the range of type long.
 278         So it's not recommended to use own Resource IDs starting
 279         with a decimal number near to the maximum long value if
 280         this methods should be used.
 281     */
 282     long getUniqueNumericId()
 283         raises( com::sun::star::lang::NoSupportException );
 284 };
 285
 286
 287 }; }; }; };
 288
 289 #endif
 290
 291 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */