changelog.md
[nikiroo-utils.git] / src / be / nikiroo / utils / resources / Meta.java
1 package be.nikiroo.utils.resources;
2
3 import java.lang.annotation.ElementType;
4 import java.lang.annotation.Retention;
5 import java.lang.annotation.RetentionPolicy;
6 import java.lang.annotation.Target;
7
8 /**
9 * Annotation used to give some information about the translation keys, so the
10 * translation .properties file can be created programmatically.
11 *
12 * @author niki
13 */
14 @Retention(RetentionPolicy.RUNTIME)
15 @Target(ElementType.FIELD)
16 public @interface Meta {
17 /**
18 * The format of an item (the values it is expected to be of).
19 * <p>
20 * Note that the INI file can contain arbitrary data, but it is expected to
21 * be valid.
22 *
23 * @author niki
24 */
25 public enum Format {
26 /** An integer value, can be negative. */
27 INT,
28 /** true or false. */
29 BOOLEAN,
30 /** Any text String. */
31 STRING,
32 /** A password field. */
33 PASSWORD,
34 /** A colour (either by name or #rrggbb or #aarrggbb). */
35 COLOR,
36 /** A locale code (e.g., fr-BE, en-GB, es...). */
37 LOCALE,
38 /** A path to a file. */
39 FILE,
40 /** A path to a directory. */
41 DIRECTORY,
42 /** A fixed list of values (see {@link Meta#list()} for the values). */
43 FIXED_LIST,
44 /**
45 * A fixed list of values (see {@link Meta#list()} for the values) OR a
46 * custom String value (basically, a {@link Format#FIXED_LIST} with an
47 * option to enter a not accounted for value).
48 */
49 COMBO_LIST
50 }
51
52 /**
53 * A description of this item.
54 *
55 * @return what it is
56 */
57 String description() default "";
58
59 /**
60 * This item is only used as a group, not as an option.
61 * <p>
62 * For instance, you could have LANGUAGE_CODE as a group for which you won't
63 * use the value in the program, and LANGUAGE_CODE_FR, LANGUAGE_CODE_EN
64 * inside for which the value must be set.
65 *
66 * @return TRUE if it is a group
67 */
68 boolean group() default false;
69
70 /**
71 * What format should/must this key be in.
72 *
73 * @return the format it is in
74 */
75 Format format() default Format.STRING;
76
77 /**
78 * The list of fixed values this item can be (either for
79 * {@link Format#FIXED_LIST} or {@link Format#COMBO_LIST}).
80 *
81 * @return the list of values
82 */
83 String[] list() default {};
84
85 /**
86 * This item can be left unspecified.
87 *
88 * @return TRUE if it can
89 */
90 boolean nullable() default true;
91
92 /**
93 * The default value of this item.
94 *
95 * @return the value
96 */
97 String def() default "";
98
99 /**
100 * This item is a comma-separated list of values instead of a single value.
101 *
102 * @return TRUE if it is
103 */
104 boolean array() default false;
105
106 /**
107 * An addition to the format.
108 * <p>
109 * Free info text to help translate, for instance the parameters order and
110 * type for String translations (i.e., %s = input file name, %d = file size
111 * in MB).
112 *
113 * @return some info
114 */
115 String info() default "";
116 }