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