src/be/nikiroo/utils/resources/MetaInfo.java

   1 package be.nikiroo.utils.resources;
   2
   3 import java.util.ArrayList;
   4 import java.util.Iterator;
   5 import java.util.List;
   6
   7 import be.nikiroo.utils.resources.Meta.Format;
   8
   9 /**
  10  * A graphical item that reflect a configuration option from the given
  11  * {@link Bundle}.
  12  *
  13  * @author niki
  14  *
  15  * @param <E>
  16  *            the type of {@link Bundle} to edit
  17  */
  18 public class MetaInfo<E extends Enum<E>> implements Iterable<MetaInfo<E>> {
  19         private final Bundle<E> bundle;
  20         private final E id;
  21
  22         private Meta meta;
  23         private List<MetaInfo<E>> children = new ArrayList<MetaInfo<E>>();
  24
  25         private String value;
  26         private List<Runnable> reloadedListeners = new ArrayList<Runnable>();
  27         private List<Runnable> saveListeners = new ArrayList<Runnable>();
  28
  29         private String name;
  30         private String description;
  31
  32         private boolean dirty;
  33
  34         /**
  35          * Create a new {@link MetaInfo} from a value (without children).
  36          * <p>
  37          * For instance, you can call
  38          * <tt>new MetaInfo(Config.class, configBundle, Config.MY_VALUE)</tt>.
  39          *
  40          * @param type
  41          *            the type of enum the value is
  42          * @param bundle
  43          *            the bundle this value belongs to
  44          * @param id
  45          *            the value itself
  46          */
  47         public MetaInfo(Class<E> type, Bundle<E> bundle, E id) {
  48                 this.bundle = bundle;
  49                 this.id = id;
  50
  51                 try {
  52                         this.meta = type.getDeclaredField(id.name()).getAnnotation(
  53                                         Meta.class);
  54                 } catch (NoSuchFieldException e) {
  55                 } catch (SecurityException e) {
  56                 }
  57
  58                 // We consider that if a description bundle is used, everything is in it
  59
  60                 String description = null;
  61                 if (bundle.getDescriptionBundle() != null) {
  62                         description = bundle.getDescriptionBundle().getString(id);
  63                         if (description != null && description.trim().isEmpty()) {
  64                                 description = null;
  65                         }
  66                 }
  67                 if (description == null) {
  68                         description = meta.description();
  69                         if (description == null) {
  70                                 description = "";
  71                         }
  72                 }
  73
  74                 String name = idToName(id, null);
  75
  76                 // Special rules for groups:
  77                 if (meta.group()) {
  78                         String groupName = description.split("\n")[0];
  79                         description = description.substring(groupName.length()).trim();
  80                         if (!groupName.isEmpty()) {
  81                                 name = groupName;
  82                         }
  83                 }
  84
  85                 if (meta.def() != null && !meta.def().isEmpty()) {
  86                         if (!description.isEmpty()) {
  87                                 description += "\n\n";
  88                         }
  89                         description += "(Default value: " + meta.def() + ")";
  90                 }
  91
  92                 this.name = name;
  93                 this.description = description;
  94
  95                 reload();
  96         }
  97
  98         /**
  99          * For normal items, this is the name of this item, deduced from its ID (or
 100          * in other words, it is the ID but presented in a displayable form).
 101          * <p>
 102          * For group items, this is the first line of the description if it is not
 103          * empty (else, it is the ID in the same way as normal items).
 104          * <p>
 105          * Never NULL.
 106          *
 107          *
 108          * @return the name, never NULL
 109          */
 110         public String getName() {
 111                 return name;
 112         }
 113
 114         /**
 115          * A description for this item: what it is or does, how to explain that item
 116          * to the user including what can be used here (i.e., %s = file name, %d =
 117          * file size...).
 118          * <p>
 119          * For group, the first line ('\\n'-separated) will be used as a title while
 120          * the rest will be the description.
 121          * <p>
 122          * If a default value is known, it will be specified here, too.
 123          * <p>
 124          * Never NULL.
 125          *
 126          * @return the description, not NULL
 127          */
 128         public String getDescription() {
 129                 return description;
 130         }
 131
 132         /**
 133          * The format this item is supposed to follow
 134          *
 135          * @return the format
 136          */
 137         public Format getFormat() {
 138                 return meta.format();
 139         }
 140
 141         /**
 142          * The allowed list of values that a {@link Format#FIXED_LIST} item is
 143          * allowed to be, or a list of suggestions for {@link Format#COMBO_LIST}
 144          * items. Also works for {@link Format#LOCALE}.
 145          * <p>
 146          * Will always allow an empty string in addition to the rest.
 147          *
 148          * @return the list of values
 149          */
 150         public String[] getAllowedValues() {
 151                 String[] list = meta.list();
 152
 153                 String[] withEmpty = new String[list.length + 1];
 154                 withEmpty[0] = "";
 155                 for (int i = 0; i < list.length; i++) {
 156                         withEmpty[i + 1] = list[i];
 157                 }
 158
 159                 return withEmpty;
 160         }
 161
 162         /**
 163          * Return all the languages known by the program for this bundle.
 164          * <p>
 165          * This only works for {@link TransBundle}, and will return an empty list if
 166          * this is not a {@link TransBundle}.
 167          *
 168          * @return the known language codes
 169          */
 170         public List<String> getKnownLanguages() {
 171                 if (bundle instanceof TransBundle) {
 172                         return ((TransBundle<E>) bundle).getKnownLanguages();
 173                 }
 174
 175                 return new ArrayList<String>();
 176         }
 177
 178         /**
 179          * This item is a comma-separated list of values instead of a single value.
 180          * <p>
 181          * The list items are separated by a comma, each surrounded by
 182          * double-quotes, with backslashes and double-quotes escaped by a backslash.
 183          * <p>
 184          * Example: <tt>"un", "deux"</tt>
 185          *
 186          * @return TRUE if it is
 187          */
 188         public boolean isArray() {
 189                 return meta.array();
 190         }
 191
 192         /**
 193          * A manual flag to specify if the data has been changed or not, which can
 194          * be used by {@link MetaInfo#save(boolean)}.
 195          *
 196          * @return TRUE if it is dirty (if it has changed)
 197          */
 198         public boolean isDirty() {
 199                 return dirty;
 200         }
 201
 202         /**
 203          * A manual flag to specify that the data has been changed, which can be
 204          * used by {@link MetaInfo#save(boolean)}.
 205          */
 206         public void setDirty() {
 207                 this.dirty = true;
 208         }
 209
 210         /**
 211          * The number of items in this item if it {@link MetaInfo#isArray()}, or -1
 212          * if not.
 213          *
 214          * @param useDefaultIfEmpty
 215          *            check the size of the default list instead if the list is
 216          *            empty
 217          *
 218          * @return -1 or the number of items
 219          */
 220         public int getListSize(boolean useDefaultIfEmpty) {
 221                 if (!isArray()) {
 222                         return -1;
 223                 }
 224
 225                 return BundleHelper.getListSize(getString(-1, useDefaultIfEmpty));
 226         }
 227
 228         /**
 229          * This item is only used as a group, not as an option.
 230          * <p>
 231          * For instance, you could have LANGUAGE_CODE as a group for which you won't
 232          * use the value in the program, and LANGUAGE_CODE_FR, LANGUAGE_CODE_EN
 233          * inside for which the value must be set.
 234          *
 235          * @return TRUE if it is a group
 236          */
 237         public boolean isGroup() {
 238                 return meta.group();
 239         }
 240
 241         /**
 242          * The value stored by this item, as a {@link String}.
 243          *
 244          * @param item
 245          *            the item number to get for an array of values, or -1 to get
 246          *            the whole value (has no effect if {@link MetaInfo#isArray()}
 247          *            is FALSE)
 248          * @param useDefaultIfEmpty
 249          *            use the default value instead of NULL if the setting is not
 250          *            set
 251          *
 252          * @return the value
 253          */
 254         public String getString(int item, boolean useDefaultIfEmpty) {
 255                 if (isArray() && item >= 0) {
 256                         List<String> values = BundleHelper.parseList(value, -1);
 257                         if (values != null && item < values.size()) {
 258                                 return values.get(item);
 259                         }
 260
 261                         if (useDefaultIfEmpty) {
 262                                 return getDefaultString(item);
 263                         }
 264
 265                         return null;
 266                 }
 267
 268                 if (value == null && useDefaultIfEmpty) {
 269                         return getDefaultString(item);
 270                 }
 271
 272                 return value;
 273         }
 274
 275         /**
 276          * The default value of this item, as a {@link String}.
 277          *
 278          * @param item
 279          *            the item number to get for an array of values, or -1 to get
 280          *            the whole value (has no effect if {@link MetaInfo#isArray()}
 281          *            is FALSE)
 282          *
 283          * @return the default value
 284          */
 285         public String getDefaultString(int item) {
 286                 if (isArray() && item >= 0) {
 287                         List<String> values = BundleHelper.parseList(meta.def(), item);
 288                         if (values != null && item < values.size()) {
 289                                 return values.get(item);
 290                         }
 291
 292                         return null;
 293                 }
 294
 295                 return meta.def();
 296         }
 297
 298         /**
 299          * The value stored by this item, as a {@link Boolean}.
 300          *
 301          * @param item
 302          *            the item number to get for an array of values, or -1 to get
 303          *            the whole value (has no effect if {@link MetaInfo#isArray()}
 304          *            is FALSE)
 305          * @param useDefaultIfEmpty
 306          *            use the default value instead of NULL if the setting is not
 307          *            set
 308          *
 309          * @return the value
 310          */
 311         public Boolean getBoolean(int item, boolean useDefaultIfEmpty) {
 312                 return BundleHelper
 313                                 .parseBoolean(getString(item, useDefaultIfEmpty), -1);
 314         }
 315
 316         /**
 317          * The default value of this item, as a {@link Boolean}.
 318          *
 319          * @param item
 320          *            the item number to get for an array of values, or -1 to get
 321          *            the whole value (has no effect if {@link MetaInfo#isArray()}
 322          *            is FALSE)
 323          *
 324          * @return the default value
 325          */
 326         public Boolean getDefaultBoolean(int item) {
 327                 return BundleHelper.parseBoolean(getDefaultString(item), -1);
 328         }
 329
 330         /**
 331          * The value stored by this item, as a {@link Character}.
 332          *
 333          * @param item
 334          *            the item number to get for an array of values, or -1 to get
 335          *            the whole value (has no effect if {@link MetaInfo#isArray()}
 336          *            is FALSE)
 337          * @param useDefaultIfEmpty
 338          *            use the default value instead of NULL if the setting is not
 339          *            set
 340          *
 341          * @return the value
 342          */
 343         public Character getCharacter(int item, boolean useDefaultIfEmpty) {
 344                 return BundleHelper.parseCharacter(getString(item, useDefaultIfEmpty),
 345                                 -1);
 346         }
 347
 348         /**
 349          * The default value of this item, as a {@link Character}.
 350          *
 351          * @param item
 352          *            the item number to get for an array of values, or -1 to get
 353          *            the whole value (has no effect if {@link MetaInfo#isArray()}
 354          *            is FALSE)
 355          *
 356          * @return the default value
 357          */
 358         public Character getDefaultCharacter(int item) {
 359                 return BundleHelper.parseCharacter(getDefaultString(item), -1);
 360         }
 361
 362         /**
 363          * The value stored by this item, as an {@link Integer}.
 364          *
 365          * @param item
 366          *            the item number to get for an array of values, or -1 to get
 367          *            the whole value (has no effect if {@link MetaInfo#isArray()}
 368          *            is FALSE)
 369          * @param useDefaultIfEmpty
 370          *            use the default value instead of NULL if the setting is not
 371          *            set
 372          *
 373          * @return the value
 374          */
 375         public Integer getInteger(int item, boolean useDefaultIfEmpty) {
 376                 return BundleHelper
 377                                 .parseInteger(getString(item, useDefaultIfEmpty), -1);
 378         }
 379
 380         /**
 381          * The default value of this item, as an {@link Integer}.
 382          *
 383          * @param item
 384          *            the item number to get for an array of values, or -1 to get
 385          *            the whole value (has no effect if {@link MetaInfo#isArray()}
 386          *            is FALSE)
 387          *
 388          * @return the default value
 389          */
 390         public Integer getDefaultInteger(int item) {
 391                 return BundleHelper.parseInteger(getDefaultString(item), -1);
 392         }
 393
 394         /**
 395          * The value stored by this item, as a colour (represented here as an
 396          * {@link Integer}) if it represents a colour, or NULL if it doesn't.
 397          * <p>
 398          * The returned colour value is an ARGB value.
 399          *
 400          * @param item
 401          *            the item number to get for an array of values, or -1 to get
 402          *            the whole value (has no effect if {@link MetaInfo#isArray()}
 403          *            is FALSE)
 404          * @param useDefaultIfEmpty
 405          *            use the default value instead of NULL if the setting is not
 406          *            set
 407          *
 408          * @return the value
 409          */
 410         public Integer getColor(int item, boolean useDefaultIfEmpty) {
 411                 return BundleHelper.parseColor(getString(item, useDefaultIfEmpty), -1);
 412         }
 413
 414         /**
 415          * The default value stored by this item, as a colour (represented here as
 416          * an {@link Integer}) if it represents a colour, or NULL if it doesn't.
 417          * <p>
 418          * The returned colour value is an ARGB value.
 419          *
 420          * @param item
 421          *            the item number to get for an array of values, or -1 to get
 422          *            the whole value (has no effect if {@link MetaInfo#isArray()}
 423          *            is FALSE)
 424          *
 425          * @return the value
 426          */
 427         public Integer getDefaultColor(int item) {
 428                 return BundleHelper.parseColor(getDefaultString(item), -1);
 429         }
 430
 431         /**
 432          * A {@link String} representation of the list of values.
 433          * <p>
 434          * The list of values is comma-separated and each value is surrounded by
 435          * double-quotes; backslashes and double-quotes are escaped by a backslash.
 436          *
 437          * @param item
 438          *            the item number to get for an array of values, or -1 to get
 439          *            the whole value (has no effect if {@link MetaInfo#isArray()}
 440          *            is FALSE)
 441          * @param useDefaultIfEmpty
 442          *            use the default value instead of NULL if the setting is not
 443          *            set
 444          *
 445          * @return the value
 446          */
 447         public List<String> getList(int item, boolean useDefaultIfEmpty) {
 448                 return BundleHelper.parseList(getString(item, useDefaultIfEmpty), -1);
 449         }
 450
 451         /**
 452          * A {@link String} representation of the default list of values.
 453          * <p>
 454          * The list of values is comma-separated and each value is surrounded by
 455          * double-quotes; backslashes and double-quotes are escaped by a backslash.
 456          *
 457          * @param item
 458          *            the item number to get for an array of values, or -1 to get
 459          *            the whole value (has no effect if {@link MetaInfo#isArray()}
 460          *            is FALSE)
 461          *
 462          * @return the value
 463          */
 464         public List<String> getDefaultList(int item) {
 465                 return BundleHelper.parseList(getDefaultString(item), -1);
 466         }
 467
 468         /**
 469          * The value stored by this item, as a {@link String}.
 470          *
 471          * @param value
 472          *            the new value
 473          * @param item
 474          *            the item number to set for an array of values, or -1 to set
 475          *            the whole value (has no effect if {@link MetaInfo#isArray()}
 476          *            is FALSE)
 477          */
 478         public void setString(String value, int item) {
 479                 if (isArray() && item >= 0) {
 480                         List<String> values = BundleHelper.parseList(this.value, -1);
 481                         for (int i = values.size(); i <= item; i++) {
 482                                 values.add(null);
 483                         }
 484                         values.set(item, value);
 485                         this.value = BundleHelper.fromList(values);
 486                 } else {
 487                         this.value = value;
 488                 }
 489         }
 490
 491         /**
 492          * The value stored by this item, as a {@link Boolean}.
 493          *
 494          * @param value
 495          *            the new value
 496          * @param item
 497          *            the item number to set for an array of values, or -1 to set
 498          *            the whole value (has no effect if {@link MetaInfo#isArray()}
 499          *            is FALSE)
 500          */
 501         public void setBoolean(boolean value, int item) {
 502                 setString(BundleHelper.fromBoolean(value), item);
 503         }
 504
 505         /**
 506          * The value stored by this item, as a {@link Character}.
 507          *
 508          * @param value
 509          *            the new value
 510          * @param item
 511          *            the item number to set for an array of values, or -1 to set
 512          *            the whole value (has no effect if {@link MetaInfo#isArray()}
 513          *            is FALSE)
 514          */
 515         public void setCharacter(char value, int item) {
 516                 setString(BundleHelper.fromCharacter(value), item);
 517         }
 518
 519         /**
 520          * The value stored by this item, as an {@link Integer}.
 521          *
 522          * @param value
 523          *            the new value
 524          * @param item
 525          *            the item number to set for an array of values, or -1 to set
 526          *            the whole value (has no effect if {@link MetaInfo#isArray()}
 527          *            is FALSE)
 528          */
 529         public void setInteger(int value, int item) {
 530                 setString(BundleHelper.fromInteger(value), item);
 531         }
 532
 533         /**
 534          * The value stored by this item, as a colour (represented here as an
 535          * {@link Integer}) if it represents a colour, or NULL if it doesn't.
 536          * <p>
 537          * The colour value is an ARGB value.
 538          *
 539          * @param value
 540          *            the value
 541          * @param item
 542          *            the item number to set for an array of values, or -1 to set
 543          *            the whole value (has no effect if {@link MetaInfo#isArray()}
 544          *            is FALSE)
 545          */
 546         public void setColor(int value, int item) {
 547                 setString(BundleHelper.fromColor(value), item);
 548         }
 549
 550         /**
 551          * A {@link String} representation of the default list of values.
 552          * <p>
 553          * The list of values is comma-separated and each value is surrounded by
 554          * double-quotes; backslashes and double-quotes are escaped by a backslash.
 555          *
 556          * @param value
 557          *            the {@link String} representation
 558          * @param item
 559          *            the item number to set for an array of values, or -1 to set
 560          *            the whole value (has no effect if {@link MetaInfo#isArray()}
 561          *            is FALSE)
 562          */
 563         public void setList(List<String> value, int item) {
 564                 setString(BundleHelper.fromList(value), item);
 565         }
 566
 567         /**
 568          * Reload the value from the {@link Bundle}, so the last value that was
 569          * saved will be used.
 570          */
 571         public void reload() {
 572                 if (bundle.isSet(id, false)) {
 573                         value = bundle.getString(id);
 574                 } else {
 575                         value = null;
 576                 }
 577
 578                 for (Runnable listener : reloadedListeners) {
 579                         try {
 580                                 listener.run();
 581                         } catch (Exception e) {
 582                                 e.printStackTrace();
 583                         }
 584                 }
 585         }
 586
 587         /**
 588          * Add a listener that will be called <b>after</b> a reload operation.
 589          * <p>
 590          * You could use it to refresh the UI for instance.
 591          *
 592          * @param listener
 593          *            the listener
 594          */
 595         public void addReloadedListener(Runnable listener) {
 596                 reloadedListeners.add(listener);
 597         }
 598
 599         /**
 600          * Save the current value to the {@link Bundle}.
 601          * <p>
 602          * Note that listeners will be called <b>before</b> the dirty check and
 603          * <b>before</b> saving the value.
 604          *
 605          * @param onlyIfDirty
 606          *            only save the data if the dirty flag is set (will reset the
 607          *            dirty flag)
 608          */
 609         public void save(boolean onlyIfDirty) {
 610                 for (Runnable listener : saveListeners) {
 611                         try {
 612                                 listener.run();
 613                         } catch (Exception e) {
 614                                 e.printStackTrace();
 615                         }
 616                 }
 617
 618                 if (!onlyIfDirty || isDirty()) {
 619                         bundle.setString(id, value);
 620                 }
 621         }
 622
 623         /**
 624          * Add a listener that will be called <b>before</b> a save operation.
 625          * <p>
 626          * You could use it to make some modification to the stored value before it
 627          * is saved.
 628          *
 629          * @param listener
 630          *            the listener
 631          */
 632         public void addSaveListener(Runnable listener) {
 633                 saveListeners.add(listener);
 634         }
 635
 636         /**
 637          * The sub-items if any (if no sub-items, will return an empty list).
 638          * <p>
 639          * Sub-items are declared when a {@link Meta} has an ID that starts with the
 640          * ID of a {@link Meta#group()} {@link MetaInfo}.
 641          * <p>
 642          * For instance:
 643          * <ul>
 644          * <li>{@link Meta} <tt>MY_PREFIX</tt> is a {@link Meta#group()}</li>
 645          * <li>{@link Meta} <tt>MY_PREFIX_DESCRIPTION</tt> is another {@link Meta}</li>
 646          * <li><tt>MY_PREFIX_DESCRIPTION</tt> will be a child of <tt>MY_PREFIX</tt></li>
 647          * </ul>
 648          *
 649          * @return the sub-items if any
 650          */
 651         public List<MetaInfo<E>> getChildren() {
 652                 return children;
 653         }
 654
 655         @Override
 656         public Iterator<MetaInfo<E>> iterator() {
 657                 return children.iterator();
 658         }
 659
 660         /**
 661          * Create a list of {@link MetaInfo}, one for each of the item in the given
 662          * {@link Bundle}.
 663          *
 664          * @param <E>
 665          *            the type of {@link Bundle} to edit
 666          * @param type
 667          *            a class instance of the item type to work on
 668          * @param bundle
 669          *            the {@link Bundle} to sort through
 670          *
 671          * @return the list
 672          */
 673         static public <E extends Enum<E>> List<MetaInfo<E>> getItems(Class<E> type,
 674                         Bundle<E> bundle) {
 675                 List<MetaInfo<E>> list = new ArrayList<MetaInfo<E>>();
 676                 List<MetaInfo<E>> shadow = new ArrayList<MetaInfo<E>>();
 677                 for (E id : type.getEnumConstants()) {
 678                         MetaInfo<E> info = new MetaInfo<E>(type, bundle, id);
 679                         list.add(info);
 680                         shadow.add(info);
 681                 }
 682
 683                 for (int i = 0; i < list.size(); i++) {
 684                         MetaInfo<E> info = list.get(i);
 685
 686                         MetaInfo<E> parent = findParent(info, shadow);
 687                         if (parent != null) {
 688                                 list.remove(i--);
 689                                 parent.children.add(info);
 690                                 info.name = idToName(info.id, parent.id);
 691                         }
 692                 }
 693
 694                 return list;
 695         }
 696
 697         /**
 698          * Find the longest parent of the given {@link MetaInfo}, which means:
 699          * <ul>
 700          * <li>the parent is a {@link Meta#group()}</li>
 701          * <li>the parent Id is a substring of the Id of the given {@link MetaInfo}</li>
 702          * <li>there is no other parent sharing a substring for this
 703          * {@link MetaInfo} with a longer Id</li>
 704          * </ul>
 705          *
 706          * @param <E>
 707          *            the kind of enum
 708          * @param info
 709          *            the info to look for a parent for
 710          * @param candidates
 711          *            the list of potential parents
 712          *
 713          * @return the longest parent or NULL if no parent is found
 714          */
 715         static private <E extends Enum<E>> MetaInfo<E> findParent(MetaInfo<E> info,
 716                         List<MetaInfo<E>> candidates) {
 717                 String id = info.id.toString();
 718                 MetaInfo<E> group = null;
 719                 for (MetaInfo<E> pcandidate : candidates) {
 720                         if (pcandidate.isGroup()) {
 721                                 String candidateId = pcandidate.id.toString();
 722                                 if (!id.equals(candidateId) && id.startsWith(candidateId)) {
 723                                         if (group == null
 724                                                         || group.id.toString().length() < candidateId
 725                                                                         .length()) {
 726                                                 group = pcandidate;
 727                                         }
 728                                 }
 729                         }
 730                 }
 731
 732                 return group;
 733         }
 734
 735         static private <E extends Enum<E>> String idToName(E id, E prefix) {
 736                 String name = id.toString();
 737                 if (prefix != null && name.startsWith(prefix.toString())) {
 738                         name = name.substring(prefix.toString().length());
 739                 }
 740
 741                 if (name.length() > 0) {
 742                         name = name.substring(0, 1).toUpperCase()
 743                                         + name.substring(1).toLowerCase();
 744                 }
 745
 746                 name = name.replace("_", " ");
 747
 748                 return name.trim();
 749         }
 750 }