D 2020-05-29T15:20:10.835
L OptionsDialog
N text/x-markdown
P 747cff09315fbb4e087ed30d8ce43b6869176db2
U mario
W 6204
### 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:
* [https://wiki.openoffice.org/wiki/Documentation/DevGuide/Extensions/Checklist_for_Writing_Extensions](https://wiki.openoffice.org/wiki/Documentation/DevGuide/Extensions/Checklist_for_Writing_Extensions)
* [https://wiki.openoffice.org/wiki/Documentation/DevGuide/Extensions/Options_Dialog](https://wiki.openoffice.org/wiki/Documentation/DevGuide/Extensions/Options_Dialog])
* [https://web.archive.org/web/20160101020749/https://wiki.openoffice.org/wiki/Documentation/DevGuide/Extensions/Saving_and_Reading_Data_for_the_Options_Page](https://web.archive.org/web/20160101020749/https://wiki.openoffice.org/wiki/Documentation/DevGuide/Extensions/Saving_and_Reading_Data_for_the_Options_Page)
→ the .xcs must be noted in the manifest.xml too
* [https://github.com/vmiklos/lo-sdk-examples/tree/master/java/OptionsPageDemo](https://github.com/vmiklos/lo-sdk-examples/tree/master/java/OptionsPageDemo)
* [https://wiki.openoffice.org/wiki/Documentation/DevGuide/Extensions/Adding_a_Leaf_to_an_Existing_Node](https://wiki.openoffice.org/wiki/Documentation/DevGuide/Extensions/Adding\_a\_Leaf\_to\_an\_Existing\_Node)
* [https://github.com/kelsa-pi/unodit](https://github.com/kelsa-pi/unodit)
* [https://github.com/p--q/OptionsDialog/tree/master/OptionsDialog/src](https://github.com/p--q/OptionsDialog/tree/master/OptionsDialog/src)
* […/src/pythonpath/optionsdialog/component.py](https://github.com/p--q/OptionsDialog/blob/master/OptionsDialog/src/pythonpath/optionsdialog/component.py)
* [https://forum.openoffice.org/en/forum/viewtopic.php?t=96509 - (Solved) OptionsDialog not showing up for Python Extension](https://forum.openoffice.org/en/forum/viewtopic.php?t=96509)
* [https://forum.openoffice.org/en/forum/viewtopic.php?p=92278 - (Solved) My addon's option dialog doesn't show up](https://forum.openoffice.org/en/forum/viewtopic.php?p=92278)
→ Pretty much the baseline version of what we're using here. Only the `__init__(,args)` parameter was invalid
* [https://web.archive.org/web/20130801024954/http://wiki.openoffice.org/wiki/Documentation/DevGuide/Text/Editing_Text](https://web.archive.org/web/20130801024954/http://wiki.openoffice.org/wiki/Documentation/DevGuide/Text/Editing_Text)
### OptionsDialog.xcu
The [.xcu](artifact/72cc52be538dc6b3447f2bc9394498c7d160423a) 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 oor:name="Id"><value>pkg.vnd-name.OptionsPageTranslate</value></prop>
* The .xdl reference in `<prop OptionsPage>` should use `%origin%` and perhaps be
relative to the .xcu:
<prop oor:name="OptionsPage"> <value>%origin%/OptionsDialog.xdl</value> </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` <s>or the node leaf `name=` either</s>.
Although it's for the best to use the same ID for all three. For Apache OpenOffice compatibility, **the leaf name must match the handler ID** however.
* The EventServiceHandler string is 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. (It probably doesn't need to match any of the .xcu identifiers: leaf/id/handler.)
* Note that AOO might hiccup if the dialog is too large (>= 200x180px).
### 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
↓ ↓
/pkg.vnd-name.packageidentifier/OptionsSchema/Leaves/Settings
↑ ↑
package id "Leaves"
### META-INF/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:full-path="./OptionsDialog.xcu"/>
<manifest:file-entry manifest:media-type="application/vnd.sun.star.configuration-schema"
manifest:full-path="./OptionsSchema.xcs" />
<style>
pre, pre.prettyprint, code { background: #e7e7e7; }
</style>
Z e3551e5e4915ee49e1ac98e3f66ca87f