### So, what have we learned?

There's a few gotchas when integrating a config dialog. Notably the lack of examples
and spotty documentation made this somewhat tedious to figure out. Hence a few notes
to the existing xml data and code in this project.

Some references / archive links:

 *
     *
     *
         → the .xcs must be noted in the manifest.xml too
     *
     *
 *
 *
     *
 * - (Solved) OptionsDialog not showing up for Python
 * - (Solved) My addon's option dialog doesn't show
     → Pretty much the baseline version of what we're using here. Only the `__init__(,args)` parameter was invalid
 *


### OptionsDialog.xcu

The .xcu registers the dialog within one of the Configuration leaves.

 * Both the leaf `name=` and the `Id` property can be arbitrary.

        <node oor:name="pkg.vnd-name.OptionsPageTranslate.leaf" oor:op="fuse">

 * It doesn't even have to be identical, but perhaps should show some resemblence
   to the package name still:

        <prop

 * The .xdl reference in `<prop OptionsPage>` should use `%origin%` and perhaps be
   relative to the .xcu:

        <prop oor:name="OptionsPage"> </prop>

 * EventHandlerService registers a callback, which is meant to populate the dialog
   widgets or save data changes.

          <prop oor:name="EventHandlerService">
            <value>pkg.vnd-name.OptionsHandlerImplId</value>
          </prop>

 * The implementation identifier here can be arbitrary again, doesn't have to be
       `service:pyuno` URL, nor strictly match `Id` or the node leaf `name=` either.
       **Although it's perfectly fine to use the same ID for all three.**

 * It's used for the UNO handler registration:

        `g_ImplementationHelper.addImplementation( class, "pkg.vnd-name.OptionsHandlerImplId", () )`

   The service name `()` list is likely redundant, because of the absurd number of stubs like `getServiceNames()` etc.


 * **For testing**, you can define this property to be empty at first:

      `<prop oor:name="EventHandlerService"> <value /> </prop>`

    So the dialog will at least show up in the configuration section, without actually doing anything.


### OptionsDialog.xdl

The .xdl can be edited using LibreOffice > Tools > Manage Macros > Edit Dialogs..

  * The `<window` property for titlebars must be disabled however:

          <dlg:window  …  dlg:withtitlebar="false">

    (Not sure if that can be done in the Dialog editor.)

  * The `dlg:id="OptionsPageTranslate"` is arbitrary again.


### OptionsScheme.xcs

The component-scheme .xcs prepares entries and defaults for the Openoffice registry. It's
somewhat redundant in declaring both names and storage types for a single registry tree.
(The approach probably made sense for extensions that had multiple "leaves".)

Anyway, the `$nodepath` to access the registry later on would be a combination of
`oor:package=`, the schema `oor:name=`, `Leaves`, and the `<group oor:name=…`, e.g.

                                     oor:name=          group name
                                         ↓                  ↓

                ↑                                   ↑
            package id                           "Leaves"


### manifest.xml

Must list **both** the dialog .xcu and the registry schema .xcs:

    <manifest:file-entry manifest:media-type="application/vnd.sun.star.configuration-data"

    <manifest:file-entry manifest:media-type="application/vnd.sun.star.configuration-schema"
                          manifest:full-path="./OptionsSchema.xcs" />


<style>
code { background: #ddd; }
</style>