headers/os/locale/Catalog.h

   1 /*
   2  * Copyright 2003-2012, Haiku, Inc.
   3  * Distributed under the terms of the MIT License.
   4  */
   5 #ifndef _CATALOG_H_
   6 #define _CATALOG_H_
   7
   8
   9 #include <LocaleRoster.h>
  10 #include <Locker.h>
  11 #include <SupportDefs.h>
  12 #include <String.h>
  13
  14
  15 class BCatalogData;
  16 class BLocale;
  17 class BMessage;
  18 struct entry_ref;
  19
  20
  21 class BCatalog {
  22 public:
  23                                                                 BCatalog();
  24                                                                 BCatalog(const entry_ref& catalogOwner,
  25                                                                         const char* language = NULL,
  26                                                                         uint32 fingerprint = 0);
  27         virtual                                         ~BCatalog();
  28
  29                         const char*                     GetString(const char* string,
  30                                                                         const char* context = NULL,
  31                                                                         const char* comment = NULL);
  32                         const char*                     GetString(uint32 id);
  33
  34                         status_t                        GetData(const char* name, BMessage* msg);
  35                         status_t                        GetData(uint32 id, BMessage* msg);
  36
  37                         status_t                        GetSignature(BString* signature);
  38                         status_t                        GetLanguage(BString* language);
  39                         status_t                        GetFingerprint(uint32* fingerprint);
  40
  41                         status_t                        SetTo(const entry_ref& catalogOwner,
  42                                                                         const char* language = NULL,
  43                                                                         uint32 fingerprint = 0);
  44
  45                         status_t                        InitCheck() const;
  46                         int32                           CountItems() const;
  47
  48 protected:
  49                                                                 BCatalog(const BCatalog&);
  50                         const BCatalog&         operator= (const BCatalog&);
  51                                                                         // hide assignment and copy-constructor
  52
  53                         BCatalogData*           fCatalogData;
  54         mutable BLocker                         fLock;
  55
  56 private:
  57         friend  class BLocale;
  58         friend  status_t                        get_add_on_catalog(BCatalog*, const char*);
  59 };
  60
  61
  62 #undef B_TRANSLATION_SYSTEM_NAME_CONTEXT
  63 #define B_TRANSLATION_SYSTEM_NAME_CONTEXT "System name"
  64
  65
  66 #ifndef B_AVOID_TRANSLATION_MACROS
  67 // macros for easy catalog-access, define B_AVOID_TRANSLATION_MACROS if
  68 // you don't want these (in which case you need to collect the catalog keys
  69 // manually, as collectcatkeys won't do it for you):
  70
  71 #undef B_TRANSLATION_CONTEXT
  72         // In a single application, several strings (e.g. 'Ok') will be used
  73         // more than once, in different contexts.
  74         // As the application programmer can not know if all translations of
  75         // this string will be the same for all languages, each occurrence of
  76         // the string must be translated on its own.
  77         // Specifying the context explicitly with each string allows the person
  78         // translating a catalog to separate these different occurrences of the
  79         // same string and tell which strings appears in what context of the
  80         // application.
  81         // In order to give the translator a useful hint, the application
  82         // programmer needs to define B_TRANSLATION_CONTEXT with the context he'd
  83         // like to be associated with the strings used in this specifc source file.
  84         // example:
  85         //              #define B_TRANSLATION_CONTEXT "Folder-Window"
  86         // Tip: Use a descriptive name of the class implemented in that
  87         //              source-file.
  88
  89 #ifdef B_COLLECTING_CATKEYS
  90
  91 // pull in all the macros used when collecting catalog keys.
  92 #include <tools/CollectingCatalog.h>
  93
  94 #else
  95
  96 // Translation macros which may be used to shorten translation requests:
  97 #undef B_TRANSLATE
  98 #define B_TRANSLATE(string) \
  99         BLocaleRoster::Default()->GetCatalog()->GetString((string), \
 100                 B_TRANSLATION_CONTEXT)
 101
 102 #undef B_TRANSLATE_CONTEXT
 103 #define B_TRANSLATE_CONTEXT(string, context) \
 104         BLocaleRoster::Default()->GetCatalog()->GetString((string), (context))
 105
 106 #undef B_TRANSLATE_COMMENT
 107 #define B_TRANSLATE_COMMENT(string, comment) \
 108         BLocaleRoster::Default()->GetCatalog()->GetString((string), \
 109                 B_TRANSLATION_CONTEXT, (comment))
 110
 111 #undef B_TRANSLATE_ALL
 112 #define B_TRANSLATE_ALL(string, context, comment) \
 113         BLocaleRoster::Default()->GetCatalog()->GetString((string), (context), \
 114                 (comment))
 115
 116 #undef B_TRANSLATE_ID
 117 #define B_TRANSLATE_ID(id) \
 118         BLocaleRoster::Default()->GetCatalog()->GetString((id))
 119
 120 #undef B_TRANSLATE_SYSTEM_NAME
 121 #define B_TRANSLATE_SYSTEM_NAME(string) \
 122         BLocaleRoster::Default()->IsFilesystemTranslationPreferred() \
 123                 ? BLocaleRoster::Default()->GetCatalog()->GetString((string), \
 124                         B_TRANSLATION_SYSTEM_NAME_CONTEXT) \
 125                 : (string)
 126
 127 // Translation markers which can be used to mark static strings/IDs which
 128 // are used as key for translation requests (at other places in the code).
 129 /* Example:
 130                 #define B_TRANSLATION_CONTEXT "MyDecentApp-Menu"
 131
 132                 static const char* choices[] = {
 133                         B_TRANSLATE_MARK("left"),
 134                         B_TRANSLATE_MARK("right"),
 135                         B_TRANSLATE_MARK("up"),
 136                         B_TRANSLATE_MARK("down")
 137                 };
 138
 139                 void MyClass::AddChoices(BMenu* menu)
 140                 {
 141                         for (char** ch = choices; *ch != '\0'; ++ch) {
 142                                 menu->AddItem(
 143                                         new BMenuItem(
 144                                                 B_TRANSLATE(*ch),
 145                                                 new BMessage(...)
 146                                         )
 147                                 );
 148                         }
 149                 }
 150 */
 151 #undef B_TRANSLATE_MARK
 152 #define B_TRANSLATE_MARK(string) (string)
 153
 154 #undef B_TRANSLATE_MARK_CONTEXT
 155 #define B_TRANSLATE_MARK_CONTEXT(string, context) (string)
 156
 157 #undef B_TRANSLATE_MARK_COMMENT
 158 #define B_TRANSLATE_MARK_COMMENT(string, comment) (string)
 159
 160 #undef B_TRANSLATE_MARK_ALL
 161 #define B_TRANSLATE_MARK_ALL(string, context, comment) (string)
 162
 163 #undef B_TRANSLATE_MARK_ID
 164 #define B_TRANSLATE_MARK_ID(id) (id)
 165
 166 #undef B_TRANSLATE_MARK_SYSTEM_NAME
 167 #define B_TRANSLATE_MARK_SYSTEM_NAME(string) (string)
 168
 169 // the same for void contexts:
 170 #undef B_TRANSLATE_MARK_VOID
 171 #define B_TRANSLATE_MARK_VOID(string)
 172
 173 #undef B_TRANSLATE_MARK_CONTEXT_VOID
 174 #define B_TRANSLATE_MARK_CONTEXT_VOID(string, context)
 175
 176 #undef B_TRANSLATE_MARK_COMMENT_VOID
 177 #define B_TRANSLATE_MARK_COMMENT_VOID(string, comment)
 178
 179 #undef B_TRANSLATE_MARK_ALL_VOID
 180 #define B_TRANSLATE_MARK_ALL_VOID(string, context, comment)
 181
 182 #undef B_TRANSLATE_MARK_ID_VOID
 183 #define B_TRANSLATE_MARK_ID_VOID(id)
 184
 185 #undef B_TRANSLATE_MARK_SYSTEM_NAME_VOID
 186 #define B_TRANSLATE_MARK_SYSTEM_NAME_VOID(string)
 187
 188 // Translation macros which cause collectcatkeys to ignore this key
 189 // (useful in combination with the marking macros above):
 190 #undef B_TRANSLATE_NOCOLLECT
 191 #define B_TRANSLATE_NOCOLLECT(string) \
 192         B_TRANSLATE(string)
 193
 194 #undef B_TRANSLATE_NOCOLLECT_COMMENT
 195 #define B_TRANSLATE_NOCOLLECT_COMMENT(string, comment) \
 196         B_TRANSLATE_COMMENT(string, comment)
 197
 198 #undef B_TRANSLATE_NOCOLLECT_ALL
 199 #define B_TRANSLATE_NOCOLLECT_ALL(string, context, comment) \
 200         B_TRANSLATE_ALL(string, context, comment)
 201
 202 #undef B_TRANSLATE_NOCOLLECT_ID
 203 #define B_TRANSLATE_NOCOLLECT_ID(id) \
 204         B_TRANSLATE_ID(id)
 205
 206 #undef B_TRANSLATE_NOCOLLECT_SYSTEM_NAME
 207 #define B_TRANSLATE_NOCOLLECT_SYSTEM_NAME(string) \
 208         B_TRANSLATE_SYSTEM_NAME(string)
 209
 210 #endif  /* B_COLLECTING_CATKEYS */
 211
 212 #endif  /* B_AVOID_TRANSLATION_MACROS */
 213
 214
 215 #endif /* _CATALOG_H_ */