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	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
48protected:
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
56private:
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_ */
216