Difference between revisions of "Dialog Dump"
(→Tweaks) |
|||
Line 106: | Line 106: | ||
* a member resource id <code>ED_MESSAGE</code> | * a member resource id <code>ED_MESSAGE</code> | ||
− | ===== Miscellaneous ==== | + | ===== Miscellaneous ===== |
* care for your "Tab index" properties: They're evaluated and reflected in the member ordering | * care for your "Tab index" properties: They're evaluated and reflected in the member ordering | ||
Revision as of 11:53, 1 September 2006
Introduction
Every OpenOffice.org developer who ever needed to create a VCL dialog knows that this can be a ... laborious procedure: You need to
- define your dialog, with a text editor, in a resource file (.src), including manual maintainance of control sizes and positions
- define the IDs for your dialog's elements in a separate .hrc file
- create a class definition for your dialog in yet another .hxx file
- create an initial class implementation in a .cxx file
All of this is laborious, cumbersome, and not really fun to do.
dialogdump is a Java tool which relieves you from some of those tasks, by dumping UNO dialogs to source code. This way, you can create your dialogs in the OpenOffice.org Dialog Editor (Tools / Macros / Organize Dialogs ...
), and let dialogdump create all 4 files with initial content - ready to be compiled.
Get it
dialogdump is currently not available for direct download. You can check it out from CVS, it's in the module awttools
of the gsl project:
cvs checkout gsl/awttools
(If you're unfamilar with how to check out source code from CVS, refer to the documentation)
After you have the source, create a NetBeans project:
- choose
File / New Project ...
from the menu - choose
General / Java Project with Existing Sources
in the "New Project" dialog - on the second page of the dialog, give your project a name and location
- on the third page of the dialog, add the
awttools/java
directory, in the location where you just checked out the module, to the "Source Package Folders" list. - Finally, in the project properties, add the
ridl.jar
,unoil.jar
,jurt.jar
,juh.jar
,jut.jar
,java_uno.jar
files, to be found in your OpenOffice.org installation in the program/classes folder, to theCompile-time Libraries
list.
Use it
General
Start OpenOffice.org, by allowing it to accept incoming connections from localhost, on port 8100:
soffice --accept=socket,host=localhost,port=8100;urp
Then, simply run dialogdump from the command line, or from within the NetBeans IDE, if you have set up a project as described in the previous chapter.
Just pass the names of the dialogs you want to dump as arguments when calling dialogdump:
dialogdump [switches] <dialog_name_1> [<dialog_name_2> [<dialog_name_3> ... ]]
(in NetBeans, this is the "Run" section in the project properties)
Choosing the Dialogs
A dialog name is composed of the module, plus the actual name. So, for instance
dialogdump Standard.MyDialog
will dump the dialog named "MyDialog" in the application-wide module "Standard"
If you want to dump dialogs which are not application-wide, but part of a document, use the --document
switch:
dialogdump --document "c:\documents\dialog designs.odt" Demos.HelloWorld
will dump the dialog named "HelloWorld", located in the "Demos" module in the document "c:\documents\dialog designs.odt".
Currently, you must have opened the document in question in OpenOffice.org, before you can dump the contained dialogs. |
Output
By default, all output happens on the console. You can override this with the --file
switch:
dialogdump --file c:\source\hello Demos.HelloWorld Demos.SimpleInput
will create the following files:
- c:\source\hello.hrc - contains the resource identifier definitions
- c:\source\hello.src - contains the resource definitions
- c:\source\hello.hxx - contains the class declarations
- c:\source\hello.cxx - contains the class implementations
All those files will be ready to compile - place them in a directory of your choice, and add them to the respective makefile. Note, however, that you certainly want to tweak the files:
- The identifiers for the global dialogs are placed in the .hrc file, but this is not their proper place. You should move them to the central .hrc file for your complete source module, where you collect all global resouce identifiers for the module.
- The dialog classes are constructed as follows
[c++]
HelloWorldDialog::HelloWorldDialog( Window* _pParent )
:ModalDialog( _pParent, ResId( DLG_HELLO_WORLD ) )
...
Note that there is a
ResId
in the call to the ModalDialog
constructor. You will want to replace this with the resource-id-class for your module.
In general, look for // TODO:
in the generated files - this will tell you placed you need to tweak.
Tweaks
dialogdump features more settings than the ones currently available at the command line. In particular, those are
setting | meaning | allowed values | default |
---|---|---|---|
host | specifies the machine at which OpenOffice.org is running | n/a | localhost |
port | specifies the port at which OpenOffice.org is accepting connections | n/a | 8100 |
format | specifies the output format. Currently, only one format is supported, but one could imagine more formats, e.g. dumping the dialogs as Java code. | "VCL" | "VCL" |
dialog-type | specifies the VCL type of the dialog(s) to dump. Only used when format is "VCL" | "ModalDialog", "ModelessDialog", "TabPage" | "ModalDialog" |
namespace | specifies the namespace in which the dialog's declaration and implementation should reside. Only used when format is "VCL" | n/a | <none> |
global-resource-base | specifies the base id for global resource identifiers. Only used when format is "VCL" | n/a | 256 |
resource-id-class | specifies the class for global resource ids. Only used when format is "VCL" | n/a | ResId |
Things to Know
When designing the dialogs, it might be helpful to keep the following in mind:
Identifiers
Resource identifiers, as well as member names, as well as dialog class names, are derived from the Name
property, and the type of the control/dialog. For example, consider a dialog which you named "HelloWorld", with a fixed text control named "Message". Then, you would get
- a dialog class named
HelloWorldDialog
, orHelloWorldPage
if you set the dialog-type setting to "TabPage" - a member
Edit m_aMessage
- a dialog resource id
DLG_HELLO_WORLD
, orTP_HELLO_WORLD
if you set the dialog-type setting to "TabPage" - a member resource id
ED_MESSAGE
Miscellaneous
- care for your "Tab index" properties: They're evaluated and reflected in the member ordering
Known Limitations
- Currently, not all control types are supported, but only those I needed so far. New types should be fairly easy to add, just see the
WindowClassFactory.impl_createControlClass
method. - Not all properties which you can set at the dialog editor are currently exported. In general, properties are exported into the .src file where possible, and into the .cxx otherwise. However, the list is not complete currently. See the
RuntimePropertyValues
class for an extension. - Properties for the dialog as a whole are currently not dumped (except Title, Position, Size)
- If dialogs contained in documents are to be dumped, those documents must already be loaded in OOo. It would be possible to work around this in the dialogdump code, but isn't this a bug^Wmissing feature in the
XDialogProvider
implementation? - No localization support: The current AWT dialog API does not support localizations, and thus dialogdump doesn't. Texts are exported as
Text [ de ] = ...
andText [ en-US ] = ...
to the resource file, with both versions having the same text.
Possible Enhancements
Minor
- load additional settings from a .properties file
- allow changing all settings from the command line
- create makefiles so the project can be built inside an OpenOffice.org build environment
- order identifiers in the .hrc file by type, with an own numbering for each type, i.e., for every control type, ids should start with 1. Currently, all types are mixed.
- automatically load documents in which dialogs are located.
Major
- allow re-using files. That is, when you edit a dialog in the dialog editor, and call dialogdump again, then it could be able to recognize its previous dump, and only overwrite the changed aspects
- reverse-engineering :) - allow creating UNO dialogs from resource files
Known Issues
- MultiLine edit controls are not properly exported currently: They will appear as
Edit
(instead ofMultiLineEdit
), having aMultiLine = TRUE;
property in the resource file, which will not compile.