Parsing

Parsing

To actually parse the LML templates, you need to create an instance of LmlParser with your customized settings. The easiest way to do that is to use Lml or VisLml (when using gdx-lml-vis) static utilities, both of which feature a parser() method returning a parser builder. For example, this code snippet creates a LmlParser with VisUI syntax, a custom I18NBundle for localization and a global ActionContainer:

VisLml.parser()
  // Registering i18n:
  .i18nBundle(I18NBundle.createBundle(Gdx.files.internal("bundle")))
  // Registering global actions:
  .actions("global", MyGlobalActionContainer.class)
  .build();

There are 2 basic ways of creating actors from LML templates:

• parseTemplate methods: they consume a FileHandle or template as simple String and return Array<Actor>. The array will contain all root actors from the parsed template. For example, given this template:

<!-- example.lml -->
<button/>
<label>Text.</label>
<window title="My window">
  <imageButton/>
</window>

lmlParser.parseTemplate(Gdx.files.internal("example.lml")) would return an Array instance containing Button, Label and Window instances. ImageButton is a child of Window - it would be displayed on the window, but not returned in the result array, as it is not a root tag.

• fillStage methods: they consume a Stage instance and a FileHandle or template as plain String. Similarly to parseTemplate, they will parse and array of actors and add them directly to the passed stage. This is preferred over parseTemplate, as some actors might need "special treatment" when added to the stage, and this method handles it for you automatically. For example, Dialog instances should be generally added using show(Stage) method rather than like other widgets - when using fillStage, it's not you who has to worry about stuff like that.

If you want to access an instance of a specific actor, use id="myId" attribute in its tag. Then, after parsing, you can use LmlParser#getActorsMappedByIds() method to access a map of all actors with specified IDs. This way you can access actors that are not roots without tedious searching the whole actor tree.

Note that parseTemplate, fillStage and getActorsMappedByIds are all considered rather "low level" API. You can do much more (and much faster) thanks to LML annotations. Actor injection is something you should consider using.