Difference between revisions of "Framework/Article/Gap Analysis Tookit API"
(Add category for article) |
|||
Line 16: | Line 16: | ||
The fourth chapter summarizes the different aspects and gives a recommendation how to proceed to close the revealed gaps. | The fourth chapter summarizes the different aspects and gives a recommendation how to proceed to close the revealed gaps. | ||
− | = | + | = Gaps in the internal usage of awt toolkit = |
This chapter tries to determine which functions are not available at awt toolkit API, but were needed by OpenOffice.org developers using references to awt toolkit objects. A strong indicator for these problems is the usage of the VCLUnoHelper class. It provides access to the implementation object through the XUnoTunnel interface. The next tables summarize the different non-accessible functions of the interfaces XWindow, XTopWindow, XDevice and XBitmap. | This chapter tries to determine which functions are not available at awt toolkit API, but were needed by OpenOffice.org developers using references to awt toolkit objects. A strong indicator for these problems is the usage of the VCLUnoHelper class. It provides access to the implementation object through the XUnoTunnel interface. The next tables summarize the different non-accessible functions of the interfaces XWindow, XTopWindow, XDevice and XBitmap. | ||
Line 366: | Line 366: | ||
It's pretty obvious that the current awt toolkit API has a very weak support for drawing and images/bitmaps operations. Starting with OpenOffice.org 2.0 a feature rich canvas UNO API (<code>com.sun.star.rendering</code>) is provided, supporting these kind of operations. It's still under development and more enhancements will be made. Therefore the drawing and image/bitmap aspects are not further discussed in this document. | It's pretty obvious that the current awt toolkit API has a very weak support for drawing and images/bitmaps operations. Starting with OpenOffice.org 2.0 a feature rich canvas UNO API (<code>com.sun.star.rendering</code>) is provided, supporting these kind of operations. It's still under development and more enhancements will be made. Therefore the drawing and image/bitmap aspects are not further discussed in this document. | ||
− | == | + | == Interpretation of the internal usage of awt toolkit == |
The interesting part of this analysis is that some of the most used functions are already part of the awt toollkit. It looks like that people were not able to find these functions at the right interface or may be they didn't care to look, but used VCLUnoHelper as a quick solution. One of the main reasons for this could be the missing information in the Developer's Guide (only the <code>com.sun.star.awt</code> IDL reference is available), although many chapters and other interfaces reference <code>com.sun.star.awt</code> types and interfaces. | The interesting part of this analysis is that some of the most used functions are already part of the awt toollkit. It looks like that people were not able to find these functions at the right interface or may be they didn't care to look, but used VCLUnoHelper as a quick solution. One of the main reasons for this could be the missing information in the Developer's Guide (only the <code>com.sun.star.awt</code> IDL reference is available), although many chapters and other interfaces reference <code>com.sun.star.awt</code> types and interfaces. | ||
Line 416: | Line 416: | ||
XTopWindow | XTopWindow | ||
|} | |} | ||
− | |||
− | |||
It's interesting that <code>setVisible(true)</code> as the replacement for <code>Show</code> was not found by so many developers. It cannot depend on the interface <code>XWindow</code>, which is the most famous awt toolkit interface. Several developers even had a reference to a <code>XWindow </code>interface, so they only had to call <code>setVisible</code>. There is no real explanation why so many developers used the <code>VCLUnoHelper</code> workaround.<br />The next VCL function <code>Get/SetText</code> is a completely different story. First there is no direct connection between the function names <code>Get/SetText</code> and <code>get/setPropertyValue</code>. One has to know that the title is provided as a property (not documented). The second problem is the interface name <code>XVCLWindowPeer</code> which is not intuitive. <br /><code>ToTop</code> is the next function which can easily matched to <code>toFront</code>, although this function is not available at the famous ''XWindow'' interface, but <code>XTopWindow</code>. The same is true for the replacement of the VCL function <code>GrabFocus</code>. It's called setFocus and is available at <code>XWindow</code> interface. The last VCL function <code>SetMenuBar</code> is a special one. It needs an argument and here it's much clearer why developers chose it. Normally developers have a menu bar pointer and can provide it directly to the VCL function. The awt toolkit function <code>setMenuBar</code> at the <code>XTopWindow</code> interface needs a <code>XMenuBar</code> reference and creating it needs much more code. So using the VCLUnoHelper function is easier. | It's interesting that <code>setVisible(true)</code> as the replacement for <code>Show</code> was not found by so many developers. It cannot depend on the interface <code>XWindow</code>, which is the most famous awt toolkit interface. Several developers even had a reference to a <code>XWindow </code>interface, so they only had to call <code>setVisible</code>. There is no real explanation why so many developers used the <code>VCLUnoHelper</code> workaround.<br />The next VCL function <code>Get/SetText</code> is a completely different story. First there is no direct connection between the function names <code>Get/SetText</code> and <code>get/setPropertyValue</code>. One has to know that the title is provided as a property (not documented). The second problem is the interface name <code>XVCLWindowPeer</code> which is not intuitive. <br /><code>ToTop</code> is the next function which can easily matched to <code>toFront</code>, although this function is not available at the famous ''XWindow'' interface, but <code>XTopWindow</code>. The same is true for the replacement of the VCL function <code>GrabFocus</code>. It's called setFocus and is available at <code>XWindow</code> interface. The last VCL function <code>SetMenuBar</code> is a special one. It needs an argument and here it's much clearer why developers chose it. Normally developers have a menu bar pointer and can provide it directly to the VCL function. The awt toolkit function <code>setMenuBar</code> at the <code>XTopWindow</code> interface needs a <code>XMenuBar</code> reference and creating it needs much more code. So using the VCLUnoHelper function is easier. | ||
− | == | + | == Conclusion == |
It should be clear that the missing documentation is an important issue while using the awt toolkit API. Several places in the current source code uses the VCLUnoHelper although this is not necessary. | It should be clear that the missing documentation is an important issue while using the awt toolkit API. Several places in the current source code uses the VCLUnoHelper although this is not necessary. | ||
Line 427: | Line 425: | ||
There are four classes of functions which are called using the VCLUnoHelper class: | There are four classes of functions which are called using the VCLUnoHelper class: | ||
− | * Important and frequently used functions for many developers. | + | * Important and frequently used functions for many developers. <code>GetParent</code> and <code>SetParent</code>, <code>ScreenToOutputPixel</code> and <code>OutputToScreenPixel</code>. |
− | * Functions which are only useful in special cases.< | + | * Functions which are only useful in special cases. <code>SetFullScreenMode</code>, <code>SetUniqueId</code> |
− | * Special functions which are normally only internally used. | + | * Special functions which are normally only internally used.<code>Get/SetWindowState</code>. |
− | * Functions which shouldn't be mapped to an UNO API. | + | * Functions which shouldn't be mapped to an UNO API.<code>GetType</code> |
The first and second class should be completely supported by an awt toolkit as developers normally have no chance to find a workaround for them. The only way would be to use a GUI library provided by a language (e.g. Java) or which is accessible on the specific platform OpenOffice.org runs (e.g. Windows API). | The first and second class should be completely supported by an awt toolkit as developers normally have no chance to find a workaround for them. The only way would be to use a GUI library provided by a language (e.g. Java) or which is accessible on the specific platform OpenOffice.org runs (e.g. Windows API). | ||
Line 436: | Line 434: | ||
The analysis part of the internal usage of awt toolkit can only cover a small area of the Office. The awt toolkit is currently only partially used in some projects (especially in framework). Therefore the data base is very small. The following chapter tries to fill the gap analyzing the usage of VCL in the application modules, which will cover a lot more areas. The application modules are a much better information source as the code provides user functions. Low-level function normally provide their service only to high-level code and not directly to the user. | The analysis part of the internal usage of awt toolkit can only cover a small area of the Office. The awt toolkit is currently only partially used in some projects (especially in framework). Therefore the data base is very small. The following chapter tries to fill the gap analyzing the usage of VCL in the application modules, which will cover a lot more areas. The application modules are a much better information source as the code provides user functions. Low-level function normally provide their service only to high-level code and not directly to the user. | ||
− | = | + | = Most used VCL functions in OpenOffice.org application code base = |
This chapter wants to document which VCL functions are heavily or rarely used by our application developers. It can help use to find the most important functions and give us an impression how many functions are really used. | This chapter wants to document which VCL functions are heavily or rarely used by our application developers. It can help use to find the most important functions and give us an impression how many functions are really used. | ||
− | == | + | == Analysis in the normal application code == |
The following table shows all methods of the following classes implemented by VCL and their usage count. | The following table shows all methods of the following classes implemented by VCL and their usage count. | ||
− | |||
− | |||
* Window | * Window | ||
Line 452: | Line 448: | ||
* OutputDevice | * OutputDevice | ||
* Bitmap/BitmapEx | * Bitmap/BitmapEx | ||
− | |||
− | |||
The application modules (sc, sch, chart2, dbaccess, sd, sw, starmath, basctl ) and the high-level framework modules (svx, sfx2, framework) were analyzed for these numbers. The rows with a green background represents functions which are already supported by the toolkit. | The application modules (sc, sch, chart2, dbaccess, sd, sw, starmath, basctl ) and the high-level framework modules (svx, sfx2, framework) were analyzed for these numbers. The rows with a green background represents functions which are already supported by the toolkit. | ||
− | |||
− | |||
{| width="641" | {| width="641" | ||
Line 5,824: | Line 5,816: | ||
(?) = Number is to high for this function. There can be clashes with some other functions with the same name. | (?) = Number is to high for this function. There can be clashes with some other functions with the same name. | ||
− | |||
− | |||
The following table summarizes the current VCL function coverage of the awt toolkit API. | The following table summarizes the current VCL function coverage of the awt toolkit API. | ||
Line 5,845: | Line 5,835: | ||
|} | |} | ||
− | + | === Conclusion === | |
− | + | ||
− | === | + | |
The awt toolkit API covers a good amount of the most used functions of VCL. The overall coverage is about 66%, where the top 20 is covered by about 75%. Looking deeper into the current coverage one will reveal that this value has to be increased as some important functions are missing. It's obvious that many interfaces support to set values, but lacks to retrieve them. | The awt toolkit API covers a good amount of the most used functions of VCL. The overall coverage is about 66%, where the top 20 is covered by about 75%. Looking deeper into the current coverage one will reveal that this value has to be increased as some important functions are missing. It's obvious that many interfaces support to set values, but lacks to retrieve them. | ||
Line 5,877: | Line 5,865: | ||
* Docking windows<br />Currently not supported by the framework based layout manager API. Support will be added in the near future and is therefore not dependent from the awt toolkit API work. | * Docking windows<br />Currently not supported by the framework based layout manager API. Support will be added in the near future and is therefore not dependent from the awt toolkit API work. | ||
− | == | + | == Analysis in dialog dependent code/resources == |
This chapter analyses which controls generic dialogs typically use, how they use controls and which functions. It's safe to assume that extension developers will use dialogs to provide their functions to users. Therefore awt toolkit API has to provide a good coverage, so developers are able to create easy to use dialogs. | This chapter analyses which controls generic dialogs typically use, how they use controls and which functions. It's safe to assume that extension developers will use dialogs to provide their functions to users. Therefore awt toolkit API has to provide a good coverage, so developers are able to create easy to use dialogs. | ||
− | === | + | === Usage of controls in OpenOffice.org dialogs === |
The following tables shows the usage of controls in the OpenOffice.org application dialogs and tab pages which are defined by a resource file. A green background color marks the controls which can be created by the current awt toolkit implementation. | The following tables shows the usage of controls in the OpenOffice.org application dialogs and tab pages which are defined by a resource file. A green background color marks the controls which can be created by the current awt toolkit implementation. | ||
Line 6,358: | Line 6,346: | ||
|} | |} | ||
− | + | (*) The UnoControlEditModel service which documents the supported properties of an edit control describes a boolean property called MultiLine. That means although the awt toolkit API is not able to create a multilineedit control using the awt toolkit factory, it has multi line support via properties. | |
− | + | ||
− | (*) The UnoControlEditModel service which documents the supported properties of an edit control describes a boolean property called | + | |
− | Once again this is an evidence that the whole awt toolkit API design is not easy to understand for the typical developer with VCL knowledge. There is a central factory which can create windows and controls, but from VCL point of view some are missing. The | + | Once again this is an evidence that the whole awt toolkit API design is not easy to understand for the typical developer with VCL knowledge. There is a central factory which can create windows and controls, but from VCL point of view some are missing. The missing controls are part of a property set provided by another control. This is a good example where a documentation could really help developers to understand the design concepts. It should describe the design goals and the general structure of the API. |
− | The control type | + | The control type Control is a special placeholder in resource files for controls which cannot be completely initialized by resources. The real control type is created by the implementation of the dialog at runtime. The analysis of the source code revealed the following special controls: |
{| width="459" border="1" cellpadding="4" | {| width="459" border="1" cellpadding="4" | ||
Line 6,619: | Line 6,605: | ||
There is one complex control which is very often used (<code>SvTreeListBox)</code>, it has a usage count of about 44% (including derivatives like <code>SvCheckListBox,SvTabListBox,SvHeaderTabListBox,_HeaderTabListBox</code>). The next control on the list has less than a third the usage count of the <code>SvTreeListBox</code> control and is called <code>ValueSet</code>. It offers a image based radio button group and often used to show the effect of a function/mode, e.g. the different text alignments are provided as images with lines where users can see the future text layout. It's very interesting that there is a class of some controls which have a usage count of about 6-7% following on third place. | There is one complex control which is very often used (<code>SvTreeListBox)</code>, it has a usage count of about 44% (including derivatives like <code>SvCheckListBox,SvTabListBox,SvHeaderTabListBox,_HeaderTabListBox</code>). The next control on the list has less than a third the usage count of the <code>SvTreeListBox</code> control and is called <code>ValueSet</code>. It offers a image based radio button group and often used to show the effect of a function/mode, e.g. the different text alignments are provided as images with lines where users can see the future text layout. It's very interesting that there is a class of some controls which have a usage count of about 6-7% following on third place. | ||
− | ==== | + | ==== Conclusion ==== |
About 40% of all dialogs use the controls <code>SvTreeListBox</code> (including derivatives) and/or <code>ValueSet</code> which are currently not supported by the awt toolkit API. As these controls are very powerful, often used and it's not easy to design dialogs with complex data without them, awt toolkit should support them. | About 40% of all dialogs use the controls <code>SvTreeListBox</code> (including derivatives) and/or <code>ValueSet</code> which are currently not supported by the awt toolkit API. As these controls are very powerful, often used and it's not easy to design dialogs with complex data without them, awt toolkit should support them. | ||
Line 6,625: | Line 6,611: | ||
The form controls collection enfolds a GridControl (called Table Control) which can also be valuable for the awt toolkit API. May be it's very easy to integrate it into the toolkit implementation. This should be further investigated. It has to be discussed if other complex controls should be supported by the awt toolkit API (e.g. <code>SvTabListBox, EditBrowseBox, SvxCheckListBox, SvxRectCtl, SvxXRectPreview</code>). They can be valuable in some situations, but it's not clear if they are important enough to invest so much time integrate them. There is also a technical problem as the toolkit only depends on VCL. Therefore it cannot easily use classes from higher level projects, like svtools and svx. | The form controls collection enfolds a GridControl (called Table Control) which can also be valuable for the awt toolkit API. May be it's very easy to integrate it into the toolkit implementation. This should be further investigated. It has to be discussed if other complex controls should be supported by the awt toolkit API (e.g. <code>SvTabListBox, EditBrowseBox, SvxCheckListBox, SvxRectCtl, SvxXRectPreview</code>). They can be valuable in some situations, but it's not clear if they are important enough to invest so much time integrate them. There is also a technical problem as the toolkit only depends on VCL. Therefore it cannot easily use classes from higher level projects, like svtools and svx. | ||
− | === | + | === Functions used in dialog implementations regarding controls === |
The implementation of a dialog focuses on different aspects than normal Office code. The most important parts of a dialog implementation is: | The implementation of a dialog focuses on different aspects than normal Office code. The most important parts of a dialog implementation is: | ||
Line 8,517: | Line 8,503: | ||
The overall coverage of about 81% of the most used function calls looks very promising. The top nine methods are all supported which cover about 54% of all function calls. There are also some controls which misses a better API support, like the <code>MetricField</code> (the most used field control that has no own control model) or the missing method <code>SelectEntryPos</code>. | The overall coverage of about 81% of the most used function calls looks very promising. The top nine methods are all supported which cover about 54% of all function calls. There are also some controls which misses a better API support, like the <code>MetricField</code> (the most used field control that has no own control model) or the missing method <code>SelectEntryPos</code>. | ||
− | === | + | === UNO API support to create dialogs (awt toolkit API, Basic dialogs) === |
The awt toolkit API supports more than one way to create dialogs, although only one way looks convincing as the other need much more implementation work. The Basic IDE supports to create dialogs which are stored as XML files (the file format is based on XUL). The dialog resources must be part of a Basic library and can then be used to create awt toolkit API based dialogs via a factory (without using any Basic macro). The service <code>com.sun.star.awt.DialogProvider</code> API offers the factory function <code>createDialog</code>( string dialogResourceURL ) via <code>com.sun.star.awt.XDialogProvider</code>. This solution is documented in the Developer's Guide (see chapter 11.5.2 ''OpenOffice.org Basic and Dialogs "Programming Dialogs and Dialog Controls"'' and ''18.3.4 Creating dialogs from macros''). | The awt toolkit API supports more than one way to create dialogs, although only one way looks convincing as the other need much more implementation work. The Basic IDE supports to create dialogs which are stored as XML files (the file format is based on XUL). The dialog resources must be part of a Basic library and can then be used to create awt toolkit API based dialogs via a factory (without using any Basic macro). The service <code>com.sun.star.awt.DialogProvider</code> API offers the factory function <code>createDialog</code>( string dialogResourceURL ) via <code>com.sun.star.awt.XDialogProvider</code>. This solution is documented in the Developer's Guide (see chapter 11.5.2 ''OpenOffice.org Basic and Dialogs "Programming Dialogs and Dialog Controls"'' and ''18.3.4 Creating dialogs from macros''). | ||
Line 8,527: | Line 8,513: | ||
One drawback, especially for Java developers, could be that there is not layout manager for dialogs. Controls must be absolute positioned and the size of dialogs cannot really be altered. If developers want to support this they have to implement their own layout management. Currently the size of most OpenOffice.org dialogs cannot be altered and VCL has also no generic layout management for dialogs. It must be further discussed how important is this missing feature. Could it hold off developers to implement extensions for OpenOffice.org? | One drawback, especially for Java developers, could be that there is not layout manager for dialogs. Controls must be absolute positioned and the size of dialogs cannot really be altered. If developers want to support this they have to implement their own layout management. Currently the size of most OpenOffice.org dialogs cannot be altered and VCL has also no generic layout management for dialogs. It must be further discussed how important is this missing feature. Could it hold off developers to implement extensions for OpenOffice.org? | ||
− | === | + | === Conclusion === |
The overall support for dialogs in awt toolkit API is on a level where most developers should be able to implement simple to medium complex dialogs. The awt toolkit dialog provider API makes it easy to create dialogs via resource files and even a generic handler mechanism is supported. To make all these features more accessible for developers there should be an integrated solution (creating dialogs, store the resulting XML file, create code for the controls, create and deploy the whole extension). There are gaps in the awt toolkit API when developers need special controls to present complex data to the user or want to better control over the behavior of the controls. | The overall support for dialogs in awt toolkit API is on a level where most developers should be able to implement simple to medium complex dialogs. The awt toolkit dialog provider API makes it easy to create dialogs via resource files and even a generic handler mechanism is supported. To make all these features more accessible for developers there should be an integrated solution (creating dialogs, store the resulting XML file, create code for the controls, create and deploy the whole extension). There are gaps in the awt toolkit API when developers need special controls to present complex data to the user or want to better control over the behavior of the controls. | ||
Line 8,545: | Line 8,531: | ||
** SetModeImage for Buttons | ** SetModeImage for Buttons | ||
− | = | + | = Missing functions, classes, controls and information in the awt toolkit API = |
This chapter tries to determine which functions, classes, controls and information are currently missing and could be valuable or vital for developers using the OpenOffice.org Software Development Kit. As this chapters is based on a small amount of data, e.g. community feedback, analyzing some extensions/add-ons sources, only hints can be drawn for the awt toolkit future. | This chapter tries to determine which functions, classes, controls and information are currently missing and could be valuable or vital for developers using the OpenOffice.org Software Development Kit. As this chapters is based on a small amount of data, e.g. community feedback, analyzing some extensions/add-ons sources, only hints can be drawn for the awt toolkit future. | ||
− | == | + | == Features demanded by the community == |
The community was asked to participate in the gap analysis and provide their point of view where things should improve and what's missing in the current awt toolkit API. Although the feedback of the community was not overwhelming some interesting information could be extracted. The most important issue from their point of view is a control which can represent complex or a huge amount data. A couple people clearly stated that something like a grid control is desperately missing. If a developer wants to represent hierarchical data (e.g. a directory of a file system) a tree-based control is also needed. That's not completely the same information which chapter 2.2.1.1 Conclusion revealed, analyzing the current application module dialogs. A grid control is not very often used by the application module dialogs, where a tree-list based control is clearly the number one of all complex controls. Analyzing the current code base cannot provide the whole picture of the OpenOffice.org development. Therefore the demand for a grid control should be taken serious as the current OpenOffice.org form control set already offers a grid-control called "Table Control". | The community was asked to participate in the gap analysis and provide their point of view where things should improve and what's missing in the current awt toolkit API. Although the feedback of the community was not overwhelming some interesting information could be extracted. The most important issue from their point of view is a control which can represent complex or a huge amount data. A couple people clearly stated that something like a grid control is desperately missing. If a developer wants to represent hierarchical data (e.g. a directory of a file system) a tree-based control is also needed. That's not completely the same information which chapter 2.2.1.1 Conclusion revealed, analyzing the current application module dialogs. A grid control is not very often used by the application module dialogs, where a tree-list based control is clearly the number one of all complex controls. Analyzing the current code base cannot provide the whole picture of the OpenOffice.org development. Therefore the demand for a grid control should be taken serious as the current OpenOffice.org form control set already offers a grid-control called "Table Control". | ||
− | == | + | == Requirements by extension developers == |
The review of current extension sources and discussions with extension developers disclosed that nearly the same problems were discovered what the previous chapters reveal. The missing documentation was a real problem as the IDL documentation is not comprehensive enough. Developers were often forced to use the "trail and error" method to fix their special problem. Sometimes work a rounds were implemented although a function to solve the issue is already available. | The review of current extension sources and discussions with extension developers disclosed that nearly the same problems were discovered what the previous chapters reveal. The missing documentation was a real problem as the IDL documentation is not comprehensive enough. Developers were often forced to use the "trail and error" method to fix their special problem. Sometimes work a rounds were implemented although a function to solve the issue is already available. | ||
Line 8,579: | Line 8,565: | ||
There was a complaint that the current image control doesn't offer image animation. Extending the image control would be the easiest way to support. It has to get all the necessary information to do the animation on its own. There were some complaints about non-working interfaces and services (e.g. the image observer/consumer infrastructure which includes support for animated images does not work) | There was a complaint that the current image control doesn't offer image animation. Extending the image control would be the easiest way to support. It has to get all the necessary information to do the animation on its own. There were some complaints about non-working interfaces and services (e.g. the image observer/consumer infrastructure which includes support for animated images does not work) | ||
− | == | + | == Conclusions == |
The following requirements for extension developers can be derived from the reviews and discussions: | The following requirements for extension developers can be derived from the reviews and discussions: | ||
Line 8,589: | Line 8,575: | ||
* Internationalization must be supported. It must be discussed what parts have to be covered by the awt toolkit API. The UNO dialog resource concept should support internationalization for user-defined dialogs. May be it can be extended to also provide resources for the default message boxes and dialogs. | * Internationalization must be supported. It must be discussed what parts have to be covered by the awt toolkit API. The UNO dialog resource concept should support internationalization for user-defined dialogs. May be it can be extended to also provide resources for the default message boxes and dialogs. | ||
− | = | + | = Final conclusion = |
The analysis revealed that the awt toolkit API doesn't deserve its a bad reputation. The function coverage is on an average level where the most prominent functions are supported. The control and dialog support is even better and give developers the opportunity to create normal dialogs. | The analysis revealed that the awt toolkit API doesn't deserve its a bad reputation. The function coverage is on an average level where the most prominent functions are supported. The control and dialog support is even better and give developers the opportunity to create normal dialogs. |
Revision as of 09:15, 19 December 2006
Gap analysis for awt toolkit API by Carsten Driesner Framework Project Co-Lead
The following document tries to give an overview about the current gaps in the awt toolkit functions. The document is split into three chapters which analyze different aspects of the awt toolkit API, VCL and OpenOffice.org.
- The awt toolkit API and VCLUnoHelper
- OpenOffice.org application code / dialogs and VCL
- Requirements and experience from the community and extension developers
The fourth chapter summarizes the different aspects and gives a recommendation how to proceed to close the revealed gaps.
Contents
Gaps in the internal usage of awt toolkit
This chapter tries to determine which functions are not available at awt toolkit API, but were needed by OpenOffice.org developers using references to awt toolkit objects. A strong indicator for these problems is the usage of the VCLUnoHelper class. It provides access to the implementation object through the XUnoTunnel interface. The next tables summarize the different non-accessible functions of the interfaces XWindow, XTopWindow, XDevice and XBitmap.
The analysis was done on the SRC680m172 code base and revealed that the following functions are missing or the responsible developer wasn't able to find it at awt toolkit API.
The background color of table row offers additional information.
The functions is part of the toolkit.
The function is newly offered by OOo 2.0
The function is not part of the current toolkit implementation.
XWindow/XTopWindow |
Function |
Usage (%) |
Description |
---|---|---|
GetType |
15.2 |
Provides the type of the window. This functions is normally used to cast the window pointer to the real window class. |
IsSystemWindow |
8.9 |
Determines if the window is a system window. |
Show |
8.0 |
Makes the window visible. |
Get/SetText |
6.3 |
Retrieves or sets the window text. |
Get/SetParent |
6.3 |
Retrieves or sets the parent of a child window. |
IsVisible |
5.4 |
Determines if the window is visible. |
GetOutputSizePixel |
5.4 |
Provides the current size of the window output area in pixel. |
ToTop |
3.6 |
Places the window on top of the window z-order. |
ScreenToOutputPixel |
3.6 |
Translates screen coordinates into window output coordinates. |
OutputToScreenPixel |
3.6 |
Translates window output coordinates into screen coordinates. |
GrabFoucs |
3.6 |
Forces the input focus. |
Get/SetWindowState |
3.6 |
Retrieves or sets the current window state as a string. |
SetMenuBar |
2.7 |
Sets a new menu bar on a system window. |
Minimize |
2.7 |
Minimizes the window. |
IsMinimized |
2.7 |
Determines if the window is currently minimized. |
HasChildPathFocus |
2.7 |
Has a window in the parent-child hierarchy the input focus |
GetClientWindowExtentRelative |
2.7 |
Window extents of the client window relative to another window. |
VCLEVENT_WINDOW_DATACHANGED |
0.9 |
Notification that settings have changed that can influence the user interface representation. E.g. Colors, sizes. |
ShowFullScreenMode |
0.9 |
Makes the windows full screen. |
SetUniqueId |
0.9 |
Sets a unique ID for the window. |
SetStyle |
0.9 |
Sets a new window style. |
SetMenuBarMode |
0.9 |
Sets a menu bar mode for a system window. |
SetIcon |
0.9 |
Sets a new icon on a system window. |
SetExtendedStyle |
0.9 |
Sets extended window styles. |
IsInModalMode |
0.9 |
Determines if the window is in modal mode (a modal dialog uses this window as its parent). |
IsFullScreenMode |
0.9 |
Determines if the window is in full screen mode. |
IsChild |
0.9 |
Determines if the provided window is a child window. |
HasFocus |
0.9 |
Determines if the window has the input focus. |
GetChildCount |
0.9 |
Provides the current number of child windows. |
GetChild |
0.9 |
Provides the child window with a provided index number. |
GetBackground |
0.9 |
Provides the current background wallpaper. |
Get/SetSizePixel |
0.9 |
Retrieves or sets the size of the window. The size is provided in pixel. |
Disable |
0.9 |
Disables the window for user input. The window is not able to receive the input focus. |
XDevice |
Function |
Usage (%) |
Description |
---|---|---|
BackgroundColor |
33.3 |
Retrieves the background wallpaper from the output device. |
DrawImage |
33.3 |
Draws an image |
SetRefDevice |
33.3 |
Sets a new reference device. |
XBitmap |
Function |
Usage (%) |
Description |
---|---|---|
GetPrefSize |
33.3 |
Retrieves the preferred size |
GetSizePixel |
33.3 |
Retrieves the size of the image in pixel |
GetPrefMapMode |
33.3 |
Retrieves the preferred map mode |
GetUniqueId |
33.3 |
Retrieves the unique ID of the image |
It's pretty obvious that the current awt toolkit API has a very weak support for drawing and images/bitmaps operations. Starting with OpenOffice.org 2.0 a feature rich canvas UNO API (com.sun.star.rendering
) is provided, supporting these kind of operations. It's still under development and more enhancements will be made. Therefore the drawing and image/bitmap aspects are not further discussed in this document.
Interpretation of the internal usage of awt toolkit
The interesting part of this analysis is that some of the most used functions are already part of the awt toollkit. It looks like that people were not able to find these functions at the right interface or may be they didn't care to look, but used VCLUnoHelper as a quick solution. One of the main reasons for this could be the missing information in the Developer's Guide (only the com.sun.star.awt
IDL reference is available), although many chapters and other interfaces reference com.sun.star.awt
types and interfaces.
The following table shows the five functions most used function with VCLUnoHelper although these functions are already available.
VCL |
Toolkit |
Interface |
---|---|---|
Show |
setVisible(true) |
XWindow |
Get/SetText |
get/setPropertyValue(Title,str) |
XVCLWindowPeer |
ToTop |
toFront() |
XTopWindow |
GrabFocus |
setFocus() |
XWindow |
SetMenuBar |
setMenuBar(XMenuBar) |
XTopWindow |
It's interesting that setVisible(true)
as the replacement for Show
was not found by so many developers. It cannot depend on the interface XWindow
, which is the most famous awt toolkit interface. Several developers even had a reference to a XWindow
interface, so they only had to call setVisible
. There is no real explanation why so many developers used the VCLUnoHelper
workaround.
The next VCL function Get/SetText
is a completely different story. First there is no direct connection between the function names Get/SetText
and get/setPropertyValue
. One has to know that the title is provided as a property (not documented). The second problem is the interface name XVCLWindowPeer
which is not intuitive. ToTop
is the next function which can easily matched to toFront
, although this function is not available at the famous XWindow interface, but XTopWindow
. The same is true for the replacement of the VCL function GrabFocus
. It's called setFocus and is available at XWindow
interface. The last VCL function SetMenuBar
is a special one. It needs an argument and here it's much clearer why developers chose it. Normally developers have a menu bar pointer and can provide it directly to the VCL function. The awt toolkit function setMenuBar
at the XTopWindow
interface needs a XMenuBar
reference and creating it needs much more code. So using the VCLUnoHelper function is easier.
Conclusion
It should be clear that the missing documentation is an important issue while using the awt toolkit API. Several places in the current source code uses the VCLUnoHelper although this is not necessary.
There are four classes of functions which are called using the VCLUnoHelper class:
- Important and frequently used functions for many developers.
GetParent
andSetParent
,ScreenToOutputPixel
andOutputToScreenPixel
. - Functions which are only useful in special cases.
SetFullScreenMode
,SetUniqueId
- Special functions which are normally only internally used.
Get/SetWindowState
. - Functions which shouldn't be mapped to an UNO API.
GetType
The first and second class should be completely supported by an awt toolkit as developers normally have no chance to find a workaround for them. The only way would be to use a GUI library provided by a language (e.g. Java) or which is accessible on the specific platform OpenOffice.org runs (e.g. Windows API).
The analysis part of the internal usage of awt toolkit can only cover a small area of the Office. The awt toolkit is currently only partially used in some projects (especially in framework). Therefore the data base is very small. The following chapter tries to fill the gap analyzing the usage of VCL in the application modules, which will cover a lot more areas. The application modules are a much better information source as the code provides user functions. Low-level function normally provide their service only to high-level code and not directly to the user.
Most used VCL functions in OpenOffice.org application code base
This chapter wants to document which VCL functions are heavily or rarely used by our application developers. It can help use to find the most important functions and give us an impression how many functions are really used.
Analysis in the normal application code
The following table shows all methods of the following classes implemented by VCL and their usage count.
- Window
- WorkWindow
- SystemWindow
- Dialog
- OutputDevice
- Bitmap/BitmapEx
The application modules (sc, sch, chart2, dbaccess, sd, sw, starmath, basctl ) and the high-level framework modules (svx, sfx2, framework) were analyzed for these numbers. The rows with a green background represents functions which are already supported by the toolkit.
Nr |
Function |
Count |
Percent |
Accumlated |
---|---|---|---|---|
1 |
Window::Enable |
3146 |
10.95% |
10.95% |
2 |
Window::SetText |
1991 |
6.93% |
17.88% |
3 |
Window::Show |
1522 |
5.30% |
22.56% |
4 |
Window::Invalidate |
1344 |
4.68% |
26.89% |
5 |
Window::Hide |
1245 |
4.33% |
31.22% |
6 |
Window::GetText |
1065 |
3.71% |
34.21% |
7 |
BitmapEx::Clear (?) |
860 |
2.99% |
37.21% |
8 |
OutputDevice::PixelToLogic |
754 |
2.62% |
39.83% |
9 |
Dialog::Execute |
719 |
2.50% |
42.33% |
10 |
Window::GrabFocus |
585 |
2.04% |
44.37% |
11 |
Window::GetWindow |
579 |
2.02% |
46.38% |
12 |
Window::GetPosPixel |
553 |
1.92% |
48.31% |
13 |
OutputDevice::LogicToPixel |
463 |
1.61% |
49.92% |
14 |
BitmapEx::GetSizePixel (?) |
459 |
1.60% |
51.52% |
15 |
Window::SetUpdateMode |
414 |
1.44% |
52.96% |
16 |
Window::SetPosPixel (1) |
403 |
1.40% |
54.36% |
17 |
Window::SetHelpId (3) |
386 |
1.34% |
55.70% |
18 |
OutputDevice::SetFont |
362 |
1.26% |
56.96% |
19 |
Window::SetPosSizePixel |
350 |
1.22% |
58.18% |
20 |
Window::KeyInput |
332 |
1.16% |
59.34% |
21 |
OutputDevice::SetMapMode |
311 |
1.08% |
59.26% |
22 |
OutputDevice::SetLineColor |
310 |
1.08% |
60.34% |
23 |
OutputDevice::Push |
305 |
1.06% |
61.40% |
24 |
OutputDevice::SetFillColor |
290 |
1.01% |
62.41% |
25 |
BitmapEx::SetSizePixel |
277 |
0.96% |
63.38% |
26 |
Window::DataChanged |
266 |
0.93% |
64.30% |
27 |
OutputDevice::DrawRect |
259 |
0.90% |
65.20% |
28 |
Window::Paint |
248 |
0.86% |
66.07% |
29 |
OutputDevice::LogicToLogic |
235 |
0.82% |
66.89% |
30 |
Window::MouseButtonDown |
229 |
0.80% |
67.68% |
31 |
OutputDevice::GetOutputSizePixel |
227 |
0.79% |
68.47% |
32 |
Bitmap::Erase (?) |
225 |
0.78% |
69.26% |
33 |
OutputDevice::GetFont |
207 |
0.72% |
69.98% |
34 |
OutputDevice::Pop |
198 |
0.69% |
70.67% |
35 |
OutputDevice::GetMapMode |
193 |
0.67% |
71.34% |
36 |
Window::GetType |
188 |
0.65% |
71.99% |
37 |
OutputDevice::DrawLine |
184 |
0.64% |
72.63% |
38 |
OutputDevice::GetTextWidth |
183 |
0.64% |
73.27% |
39 |
Window::Command (2) |
182 |
0.63% |
73.90% |
40 |
Window::SetParent |
180 |
0.63% |
74.53% |
41 |
Window::GetParent |
168 |
0.58% |
75.11% |
42 |
Window::MouseButtonUp |
164 |
0.57% |
75.68% |
43 |
Window::Update |
146 |
0.51% |
76.19% |
44 |
Bitmap::Replace |
143 |
0.50% |
76.69% |
45 |
Window::MouseMove |
137 |
0.48% |
77.17% |
46 |
OutputDevice::DrawText |
133 |
0.46% |
77.63% |
47 |
Window::SetStyle |
132 |
0.46% |
78.09% |
48 |
BitmapEx::GetBitmap |
132 |
0.46% |
78.55% |
49 |
Window::PreNotify |
129 |
0.45% |
79.00% |
50 |
Window::Notify |
128 |
0.45% |
79.44% |
51 |
OutputDevice::SetDrawMode |
124 |
0.43% |
79.87% |
52 |
OutputDevice::SetBackground |
122 |
0.42% |
80.30% |
53 |
Window::GetData |
122 |
0.42% |
80.72% |
54 |
OutputDevice::GetTextHeight |
115 |
0.40% |
81.12% |
55 |
Window::SetOutputSizePixel |
102 |
0.35% |
81.48% |
56 |
Window::SetType |
101 |
0.35% |
81.83% |
57 |
OutputDevice::SetClipRegion |
98 |
0.34% |
82.17% |
58 |
BitmapEx::Draw (1) |
98 |
0.34% |
82.51% |
59 |
Window::Resize |
96 |
0.33% |
82.85% |
60 |
Window::StateChanged |
85 |
0.30% |
83.14% |
61 |
Bitmap::Scale |
83 |
0.29% |
83.43% |
62 |
Window::IsVisible |
78 |
0.27% |
83.70% |
63 |
Window::Deactivate |
74 |
0.26% |
83.96% |
64 |
SystemWindow::Close |
73 |
0.25% |
84.21% |
65 |
Window::ReleaseMouse |
71 |
0.25% |
84.46% |
66 |
Window::Activate |
70 |
0.24% |
84.70% |
67 |
OutputDevice::EnableMapMode |
68 |
0.24% |
84.94% |
68 |
Window::Flush |
67 |
0.23% |
85.17% |
69 |
Bitmap::Adjust |
65 |
0.23% |
85.40% |
70 |
Window::GetFocus |
63 |
0.22% |
85.62% |
71 |
OutputDevice::GetLineColor |
62 |
0.22% |
85.84% |
72 |
Window::OutputToScreenPixel |
62 |
0.22% |
86.05% |
73 |
OutputDevice::GetOutputSize |
61 |
0.21% |
86.26% |
74 |
OutputDevice::GetDefaultFont |
60 |
0.21% |
86.47% |
75 |
Bitmap::GetPrefSize |
58 |
0.20% |
86.67% |
76 |
Window::RemoveUserEvent |
58 |
0.20% |
86.88% |
77 |
Window::SetZoom |
58 |
0.20% |
87.08% |
78 |
OutputDevice::DrawBitmap |
57 |
0.20% |
87.28% |
79 |
OutputDevice::GetDrawMode |
54 |
0.19% |
87.46% |
80 |
BitmapEx::SetPrefMapMode |
53 |
0.18% |
87.65% |
81 |
Bitmap::Convert |
53 |
0.18% |
87.83% |
82 |
OutputDevice::GetFillColor (3) |
52 |
0.18% |
88.01% |
83 |
Bitmap::SetPrefSize |
51 |
0.18% |
88.19% |
84 |
Window::LeaveWait |
49 |
0.17% |
88.36% |
85 |
OutputDevice::GetFontMetric |
45 |
0.16% |
88.52% |
86 |
BitmapEx::GetPrefMapMode |
45 |
0.16% |
88.68% |
87 |
Window::EnterWait |
44 |
0.15% |
88.83% |
88 |
Window::IsEnabled |
44 |
0.15% |
88.98% |
89 |
Window::GetWindowExtentsRelative |
43 |
0.15% |
89.13% |
90 |
Window::SetPointer |
43 |
0.15% |
89.28% |
91 |
OutputDevice::SetTextColor |
40 |
0.14% |
89.42% |
92 |
OutputDevice::SetRasterOp |
40 |
0.14% |
89.56% |
93 |
Bitmap::Filter |
40 |
0.14% |
89.70% |
94 |
Window::LoseFocus |
39 |
0.14% |
89.83% |
95 |
Window::Scroll |
38 |
0.13% |
89.97% |
96 |
Window::HasChildPathFocus |
35 |
0.12% |
90.09% |
97 |
OutputDevice::GetBackground |
35 |
0.12% |
90.21% |
98 |
Window::ScreenToOutputPixel |
35 |
0.12% |
90.33% |
99 |
Window::CaptureMouse |
35 |
0.12% |
90.45% |
100 |
Window::SetZOrder |
34 |
0.12% |
90.57% |
101 |
Window::GetZoom |
34 |
0.12% |
90.69% |
102 |
OutputDevice::IntersectClipRegion |
34 |
0.12% |
90.81% |
103 |
Window::SetUniqueId |
33 |
0.11% |
90.92% |
104 |
Window::RemoveEventListener |
31 |
0.11% |
91.03% |
105 |
BitmapEx::GetMask |
30 |
0.10% |
91.14% |
106 |
Window::EnableClipSiblings |
29 |
0.10% |
91.24% |
107 |
Bitmap::Expand |
29 |
0.10% |
91.34% |
108 |
Bitmap::Invert |
28 |
0.10% |
91.44% |
109 |
OutputDevice::DrawOutDev |
28 |
0.10% |
91.53% |
110 |
Window::SetBorderStyle |
28 |
0.10% |
91.63% |
111 |
Window::EnableInput |
28 |
0.10% |
91.73% |
112 |
OutputDevice::GetSettings |
27 |
0.09% |
91.82% |
113 |
Window::GetStyle |
27 |
0.09% |
91.92% |
114 |
Window::GetPointer |
27 |
0.09% |
92.01% |
115 |
Window::RequestHelp |
27 |
0.09% |
92.10% |
116 |
Window::ToTop |
27 |
0.09% |
92.20% |
117 |
OutputDevice::IsMapModeEnabled |
26 |
0.09% |
92.29% |
118 |
Window::AddEventListener |
25 |
0.09% |
92.37% |
119 |
Window::IsLocked |
25 |
0.09% |
92.46% |
120 |
BitmapEx::IsEqual |
24 |
0.08% |
92.55% |
121 |
OutputDevice::GetTextArray |
23 |
0.08% |
92.63% |
122 |
OutputDevice::SetTextLineColor |
23 |
0.08% |
92.71% |
123 |
Dialog::EndDialog |
23 |
0.08% |
92.79% |
124 |
Window::SetHelpText |
22 |
0.08% |
92.86% |
125 |
Window::GetChild |
22 |
0.08% |
92.94% |
126 |
Window::GetPointerPosPixel |
22 |
0.08% |
93.02% |
127 |
OutputDevice::SetLayoutMode |
22 |
0.08% |
93.09% |
128 |
Window::SetCursor |
21 |
0.07% |
93.16% |
129 |
SystemWindow::GetWindowState |
20 |
0.07% |
93.23% |
130 |
OutputDevice::SetDigitLanguage |
20 |
0.07% |
93.30% |
131 |
OutputDevice::EnableOutput |
19 |
0.07% |
93.37% |
132 |
Window::GetCursor |
19 |
0.07% |
93.44% |
133 |
OutputDevice::DrawPolygon |
19 |
0.07% |
93.50% |
134 |
SystemWindow::SetWindowState |
19 |
0.07% |
93.57% |
135 |
OutputDevice::EnableRTL |
18 |
0.06% |
93.63% |
136 |
Window::GetChildCount |
18 |
0.06% |
93.69% |
137 |
Window::SetData |
18 |
0.06% |
93.76% |
138 |
OutputDevice::DrawStretchText |
18 |
0.06% |
93.82% |
139 |
Window::HasFocus |
17 |
0.06% |
93.88% |
140 |
SystemWindow::SetMenuBar |
17 |
0.06% |
93.94% |
141 |
Window::SetControlBackground |
17 |
0.06% |
94.00% |
142 |
OutputDevice::DrawBitmapEx |
17 |
0.06% |
94.06% |
143 |
Window::GetHelpId |
16 |
0.06% |
94.11% |
144 |
Window::Disable |
15 |
0.05% |
94.16% |
145 |
OutputDevice::GetRasterOp |
15 |
0.05% |
94.22% |
146 |
OutputDevice::DrawPolyLine |
15 |
0.05% |
94.27% |
147 |
Bitmap::Rotate |
15 |
0.05% |
94.32% |
148 |
SystemWindow::SetMinOutputSizePixel |
15 |
0.05% |
94.37% |
149 |
OutputDevice::DrawImage |
14 |
0.05% |
94.42% |
150 |
Window::InvertTracking |
14 |
0.05% |
94.47% |
151 |
Window::SetControlForeground |
14 |
0.05% |
94.52% |
152 |
OutputDevice::GetClipRegion |
14 |
0.05% |
94.57% |
153 |
Window::SetQuickHelpText |
14 |
0.05% |
94.62% |
154 |
SystemWindow::Resizing |
14 |
0.05% |
94.66% |
155 |
OutputDevice::GetLayoutMode |
14 |
0.05% |
94.71% |
156 |
Window::GetControlFont |
14 |
0.05% |
94.76% |
157 |
Window::SetControlFont |
14 |
0.05% |
94.81% |
158 |
OutputDevice::DrawPixel |
14 |
0.05% |
94.86% |
159 |
Bitmap::IsSameInstance |
13 |
0.05% |
94.90% |
160 |
OutputDevice::DrawTextArray |
13 |
0.05% |
94.95% |
161 |
BitmapEx::IsEmpty |
12 |
0.04% |
94.99% |
162 |
SystemWindow::GetMenuBar |
12 |
|
|
163 |
OutputDevice::GetConnectMetaFile |
12 |
|
|
164 |
OutputDevice::GetExtOutDevData |
12 |
|
|
165 |
Window::Move |
12 |
|
|
166 |
BitmapEx::SetEmpty |
12 |
|
|
167 |
Window::OutputToAbsoluteScreenPixel |
12 |
|
|
168 |
OutputDevice::SetSettings |
11 |
|
|
169 |
Bitmap::Mirror |
11 |
|
|
170 |
OutputDevice::SetTextFillColor |
11 |
|
|
171 |
OutputDevice::GetOutDevType |
11 |
|
|
172 |
Window::IsActive |
11 |
|
|
173 |
OutputDevice::GetTextColor |
10 |
|
|
174 |
OutputDevice::GetDigitLanguage |
10 |
|
|
175 |
OutputDevice::DrawPolyPolygon |
10 |
|
|
176 |
OutputDevice::IsClipRegion |
10 |
|
|
177 |
OutputDevice::DrawGrid |
10 |
|
|
178 |
Window::GetInputLanguage |
10 |
|
|
179 |
Window::FindWindow |
9 |
|
|
180 |
Window::Validate |
9 |
|
|
181 |
OutputDevice::DrawTransparent |
9 |
|
|
182 |
Window::GetUniqueId |
8 |
|
|
183 |
OutputDevice::DrawEllipse |
8 |
|
|
184 |
OutputDevice::GetBitmapEx |
8 |
|
|
185 |
WorkWindow::Restore |
8 |
|
|
186 |
OutputDevice::GetCtrlTextWidth |
8 |
|
|
187 |
Window::SetPaintTransparent |
7 |
|
|
188 |
BitmapEx::IsTransparent |
7 |
|
|
189 |
Window::SetSmartHelpId |
7 |
|
|
190 |
OutputDevice::GetNonMnemonicString |
7 |
|
|
191 |
Window::GetQuickHelpText |
7 |
|
|
192 |
Window::HandleScrollCommand |
6 |
|
|
193 |
Window::Tracking |
6 |
|
|
194 |
Window::GetHelpText |
6 |
|
|
195 |
OutputDevice::SetRefPoint |
6 |
|
|
196 |
OutputDevice::GetTextOutlines |
6 |
|
|
197 |
Window::CalcZoom |
6 |
|
|
198 |
SystemWindow::GetMinOutputSizePixel |
6 |
|
|
199 |
Bitmap::GetSizeBytes |
6 |
|
|
200 |
Window::EnablePaint |
6 |
|
|
201 |
Window::HideFocus |
6 |
|
|
202 |
OutputDevice::IsFontAvailable |
5 |
|
|
203 |
Bitmap::ReduceColors |
5 |
|
|
204 |
Dialog::GrabFocusToFirstControl |
5 |
|
|
205 |
OutputDevice::GetPixel |
5 |
|
|
206 |
Window::SetInputContext |
5 |
|
|
207 |
OutputDevice::SetRelativeMapMode |
5 |
|
|
208 |
OutputDevice::GetRefPoint |
5 |
|
|
209 |
Window::IsUICaptured |
5 |
|
|
210 |
Bitmap::CombineSimple |
5 |
|
|
211 |
OutputDevice::GetActiveClipRegion |
5 |
|
|
212 |
OutputDevice::DrawHatch |
5 |
|
|
213 |
Window::OutputToNormalizedScreenPixel |
4 |
|
|
214 |
OutputDevice::CreateUnoGraphics |
4 |
|
|
215 |
Bitmap::Crop |
4 |
|
|
216 |
Window::KeyUp |
4 |
|
|
217 |
OutputDevice::GetTextBoundRect |
4 |
|
|
218 |
Window::IsInputEnabled |
4 |
|
|
219 |
OutputDevice::Get3DContext |
4 |
|
|
220 |
OutputDevice::GetTextBreak |
4 |
|
|
221 |
OutputDevice::IsFillColor |
4 |
|
|
222 |
Window::IsReallyVisible |
4 |
|
|
223 |
OutputDevice::IsLineColor |
4 |
|
|
224 |
OutputDevice::SetPixelOffset |
4 |
|
|
225 |
Window::IsWindowOrChild |
4 |
|
|
226 |
Window::ExpandPaintClipRegion |
4 |
|
|
227 |
Window::RemoveChildEventListener |
4 |
|
|
228 |
OutputDevice::DrawWallpaper |
3 |
|
|
229 |
Window::GetWindowClipRegionPixel |
3 |
|
|
230 |
Window::IsInModalMode |
3 |
|
|
231 |
OutputDevice::DrawGradient |
3 |
|
|
232 |
Bitmap::CreateMask |
3 |
|
|
233 |
Window::ShowFocus |
3 |
|
|
234 |
Window::NormalizedScreenToOutputPixel |
3 |
|
|
235 |
SystemWindow::RollUp |
3 |
|
|
236 |
Window::AddChildEventListener |
3 |
|
|
237 |
OutputDevice::DrawArc |
3 |
|
|
238 |
OutputDevice::DrawWaveLine |
3 |
|
|
239 |
OutputDevice::GetDevFont |
3 |
|
|
240 |
OutputDevice::GetEllipsisString |
3 |
|
|
241 |
Window::SetCursorRect |
3 |
|
|
242 |
OutputDevice::DrawCtrlText |
3 |
|
|
243 |
OutputDevice::DrawPie |
3 |
|
|
244 |
Window::Sync |
3 |
|
|
245 |
Window::SetMouseTransparent |
3 |
|
|
246 |
Window::GetDesktopRectPixel |
3 |
|
|
247 |
OutputDevice::GetFontCharMap |
3 |
|
|
248 |
Window::IsMouseCaptured |
3 |
|
|
249 |
Window::GetInputContext |
3 |
|
|
250 |
OutputDevice::CopyArea |
3 |
|
|
251 |
Window::IsChild |
2 |
|
|
252 |
WorkWindow::ShowFullScreenMode |
2 |
|
|
253 |
Bitmap::GetBitCount |
2 |
|
|
254 |
OutputDevice::GetTextRect |
2 |
|
|
255 |
Window::SetZoomedPointFont |
2 |
|
|
256 |
Window::UserEvent |
2 |
|
|
257 |
OutputDevice::SetTextAlign |
2 |
|
|
258 |
WorkWindow::IsFullScreenMode |
2 |
|
|
259 |
OutputDevice::GetTextAlign |
2 |
|
|
260 |
Window::GetDisplayBackground |
2 |
|
|
261 |
WorkWindow::Minimize |
2 |
|
|
262 |
SystemWindow::SetIcon |
2 |
|
|
263 |
Bitmap::Dither |
2 |
|
|
264 |
Bitmap::GetColorCount |
2 |
|
|
265 |
OutputDevice::GetDevFontCount |
2 |
|
|
266 |
SystemWindow::SetMenuBarMode |
2 |
|
|
267 |
Window::SnapShot |
2 |
|
|
268 |
OutputDevice::DrawTextLine |
2 |
|
|
269 |
OutputDevice::GetTextOutline |
2 |
|
|
270 |
OutputDevice::DrawChord |
2 |
|
|
271 |
Window::SetParentUpdateMode |
2 |
|
|
272 |
Window::IsSystemWindow |
2 |
|
|
273 |
Window::SetExtendedStyle |
1 |
|
|
274 |
OutputDevice::GetTextLineColor |
1 |
|
|
275 |
Window::GetSystemWindow |
1 |
|
|
276 |
Window::AbsoluteScreenToOutputPixel |
1 |
|
|
277 |
Window::UpdateSettings |
1 |
|
|
278 |
Window::EnableChildTransparentMode |
1 |
|
|
279 |
Window::SetPointFont |
1 |
|
|
280 |
WorkWindow::IsMinimized |
1 |
|
|
281 |
Bitmap::CreateDisplayBitmap |
1 |
|
|
282 |
Window::GetPointerState |
1 |
|
|
283 |
OutputDevice::IsRTLEnabled |
1 |
|
|
284 |
BitmapEx::GetTransparentColor |
1 |
|
|
285 |
SystemWindow::IsRollUp |
1 |
|
|
286 |
OutputDevice::GetPixelOffset |
1 |
|
|
287 |
Window::GrabFocusToDocument |
1 |
|
|
288 |
OutputDevice::DrawMask |
1 |
|
|
289 |
Window::CalcOutputSize |
1 |
|
|
290 |
Window::StartTracking |
1 |
|
|
291 |
Window::EndSaveFocus |
1 |
|
|
292 |
Bitmap::GetSystemData |
1 |
|
|
293 |
Window::AlwaysEnableInput |
1 |
|
|
294 |
SystemWindow::Roll |
1 |
|
|
295 |
Window::IsWait |
1 |
|
|
296 |
Window::GetPaintRegion |
1 |
|
|
297 |
OutputDevice::GetDevFontSizeCount |
1 |
|
|
298 |
Window::GetSystemDataAny |
1 |
|
|
299 |
OutputDevice::GetDevFontSize |
1 |
|
|
300 |
OutputDevice::GetCaretPositions |
1 |
|
|
301 |
Window::GetClientWindowExtentsRelative |
1 |
|
|
302 |
Window::GetPreferredKeyInputWindow |
1 |
|
|
303 |
Dialog::IsInExecute |
1 |
|
|
304 |
OutputDevice::IsTextLineColor |
1 |
|
|
305 |
BitmapEx::GetAlpha |
1 |
|
|
306 |
Window::GetPointFont |
1 |
|
|
307 |
Bitmap::Vectorize |
1 |
|
|
308 |
Window::EndTracking |
1 |
|
|
309 |
SystemWindow::GetTaskPaneList |
1 |
|
|
310 |
Window::SaveFocus |
1 |
|
|
311 |
Window::ShowPointer |
1 |
|
|
312 |
WorkWindow::StartPresentationMode |
1 |
|
|
313 |
OutputDevice::GetOutDevViewType |
1 |
|
|
314 |
Window::GetDockingManager |
1 |
|
|
315 |
OutputDevice::IsBackground |
1 |
|
|
316 |
Window::GetControlBackground |
1 |
|
|
317 |
Window::GetGetFocusFlags |
1 |
|
|
318 |
OutputDevice::GetTextIsRTL |
1 |
|
|
319 |
Window::IsDefaultPos |
1 |
|
|
320 |
Window::SetActivateMode |
1 |
|
|
321 |
Window::SetDialogControlFlags |
|
|
|
322 |
SystemWindow::Pin |
|
|
|
323 |
Dialog::SetModalInputMode |
|
|
|
324 |
Window::IsScrollable |
|
|
|
325 |
OutputDevice::GetAntialiasing |
|
|
|
326 |
OutputDevice::SetOutDevViewType |
|
|
|
327 |
Window::DrawSelectionBackground |
|
|
|
328 |
Bitmap::MakeMono |
|
|
|
329 |
OutputDevice::CreateUnoGraphicsList |
|
|
|
330 |
WorkWindow::EndPresentationMode |
|
|
|
331 |
Window::EnableChildNotify |
|
|
|
332 |
OutputDevice::EndFontSubstitution |
|
|
|
333 |
OutputDevice::AddHatchActions |
|
|
|
334 |
Window::GetDialogControlFlags |
|
|
|
335 |
OutputDevice::AddGradientActions |
|
|
|
336 |
SystemWindow::TitleButtonClick |
|
|
|
337 |
WorkWindow::IsPresentationMode |
|
|
|
338 |
Bitmap::Blend |
|
|
|
339 |
OutputDevice::IsDeviceOutput |
|
|
|
340 |
Window::EnableChildPointerOverwrite |
|
|
|
341 |
Window::GetSmartUniqueId |
|
|
|
342 |
OutputDevice::IsDeviceOutputNecessary |
|
|
|
343 |
SystemWindow::SetPin |
|
|
|
344 |
OutputDevice::SetAntialiasing |
|
|
|
345 |
SystemWindow::SetRollUpOutputSizePixel |
|
|
|
346 |
OutputDevice::HasAlpha |
|
|
|
347 |
Window::IsUserActive |
|
|
|
348 |
BitmapEx::SetTransparentColor |
|
|
|
349 |
Window::IsControlFont |
|
|
|
350 |
Window::SetDialogControlStart |
|
|
|
351 |
Window::ShowTracking |
|
|
|
352 |
Window::IsPaintTransparent |
|
|
|
353 |
OutputDevice::GetOutputWidthPixel |
|
|
|
354 |
Window::IsExtTextInput |
|
|
|
355 |
Window::IsPointerVisible |
|
|
|
356 |
Window::IsToolbarFloatingWindow |
|
|
|
357 |
OutputDevice::AddFontSubstitute |
|
|
|
358 |
OutputDevice::Set3DContext |
|
|
|
359 |
Window::IsChildNotify |
|
|
|
360 |
Window::HasPaintEvent |
|
|
|
361 |
Window::GetDrawPixel |
|
|
|
362 |
Window::GetWindowRegionPixel |
|
|
|
363 |
Window::HideTracking |
|
|
|
364 |
Dialog::EndAllDialogs |
|
|
|
365 |
Window::GetLastInputInterval |
|
|
|
366 |
Window::NotifyAllChilds |
|
|
|
367 |
Window::IsDialogControlStart |
|
|
|
368 |
Window::EnableAlwaysOnTop |
|
|
|
369 |
Window::IsUpdateMode |
|
|
|
370 |
Window::GetPrevStyle |
|
|
|
371 |
OutputDevice::GetOutputHeightPixel |
|
|
|
372 |
Window::IsWindowRegionPixel |
|
|
|
373 |
Window::EnableDocking |
|
|
|
374 |
WorkWindow::EndFullScreenMode |
|
|
|
375 |
Window::IsAlwaysOnTopEnabled |
|
|
|
376 |
OutputDevice::IsTextUnderlineAbove |
|
|
|
377 |
Window::CalcWindowSize |
|
|
|
378 |
BitmapEx::GetTransparentType |
|
|
|
379 |
Window::PostStateChanged |
|
|
|
380 |
WorkWindow::SetPluginParent |
|
|
|
381 |
Bitmap::GetChecksum |
|
|
|
382 |
SystemWindow::SetMaxOutputSizePixel |
|
|
|
383 |
Window::IsDefaultSize |
|
|
|
384 |
OutputDevice::IsOutputNecessary |
|
|
|
385 |
Window::IsMenuFloatingWindow |
|
|
|
386 |
Window::EndAutoScroll |
|
|
|
387 |
OutputDevice::GetOpenGL |
|
|
|
388 |
Bitmap::GetGreyPalette |
|
|
|
389 |
SystemWindow::EnableSaveBackground |
|
|
|
390 |
OutputDevice::IsTextFillColor |
|
|
|
391 |
OutputDevice::AddTextRectActions |
|
|
|
392 |
Window::GetLastPointerPosPixel |
|
|
|
393 |
OutputDevice::GetTextFillColor |
|
|
|
394 |
SystemWindow::ShowTitleButton |
|
|
|
395 |
Window::IsChildPointerOverwrite |
|
|
|
396 |
Window::IsParentUpdateMode |
|
|
|
397 |
Window::IsDialog |
|
|
|
398 |
Window::GetExtendedStyle |
|
|
|
399 |
SystemWindow::GetRollUpOutputSizePixel |
|
|
|
400 |
OutputDevice::SetConnectMetaFile |
|
|
|
401 |
OutputDevice::SetTriangleClipRegion |
|
|
|
402 |
Window::IsControlForeground |
|
|
|
403 |
Window::IsControlBackground |
|
|
|
404 |
SystemWindow::GetResizeOutputSizePixel |
|
|
|
405 |
Dialog::IsModalInputMode |
|
|
|
406 |
SystemWindow::IsSaveBackgroundEnabled |
|
|
|
407 |
Window::IsChildTransparentModeEnabled |
|
|
|
408 |
Window::GetBorder |
|
|
|
409 |
Bitmap::CreateRegion |
|
|
|
410 |
Window::IsAutoScroll |
|
|
|
411 |
Window::GetBorderStyle |
|
|
|
412 |
Window::EnableAllResize |
|
|
|
413 |
Window::SetParentClipMode |
|
|
|
414 |
BitmapEx::IsAlpha |
|
|
|
415 |
Window::HasCompoundControlFocus |
|
|
|
416 |
Bitmap::GetColorTransformedBitmap |
|
|
|
417 |
OutputDevice::GetUnoGraphicsList |
|
|
|
418 |
Window::GetCursorExtTextInputWidth |
|
|
|
419 |
OutputDevice::DrawEPS |
|
|
|
420 |
OutputDevice::SetExtOutDevData |
|
|
|
421 |
Window::IsMouseOver |
|
|
|
422 |
OutputDevice::GetPDFWriter |
|
|
|
423 |
OutputDevice::IsRefPoint |
|
|
|
424 |
Window::IsInInitShow |
|
|
|
425 |
OutputDevice::RemoveFontSubstitute |
|
|
|
426 |
Bitmap::CopyPixel |
|
|
|
427 |
Window::IsTopWindow |
|
|
|
428 |
Window::IsAlwaysEnableInput |
|
|
|
429 |
Window::CalcTitleWidth |
|
|
|
430 |
Window::IsPaintEnabled |
|
|
|
431 |
SystemWindow::IsTitleButtonVisible |
|
|
|
432 |
Window::EndExtTextInput |
|
|
|
433 |
OutputDevice::MoveClipRegion |
|
|
|
434 |
Window::IsParentPathVisible |
|
|
|
435 |
SystemWindow::GetMenuBarMode |
|
|
|
436 |
WorkWindow::IsMaximized |
|
|
|
437 |
Window::GetCurrentModButtons |
|
|
|
438 |
Window::IsInPaint |
|
|
|
439 |
SystemWindow::GetIcon |
|
|
|
440 |
OutputDevice::IsOutputEnabled |
|
|
|
441 |
Window::IsCompoundControl |
|
|
|
442 |
Window::IncrementLockCount |
|
|
|
443 |
Window::GetParentClipMode |
|
|
|
444 |
Window::IsMouseTransparent |
|
|
|
445 |
Window::IsTracking |
|
|
|
446 |
OutputDevice::GetKerningPairCount |
|
|
|
447 |
Window::SetPointerPosPixel |
|
|
|
448 |
Window::GetCursorRect |
|
|
|
449 |
OutputDevice::AddTempDevFont |
|
|
|
450 |
Window::SetWindowRegionPixel |
|
|
|
451 |
OutputDevice::HasGlyphs |
|
|
|
452 |
Window::DecrementLockCount |
|
|
|
453 |
SystemWindow::RollDown |
|
|
|
454 |
SystemWindow::GetZLevel |
|
|
|
455 |
Window::GetSmartHelpId |
|
|
|
456 |
Window::IsAllResizeEnabled |
|
|
|
457 |
Window::GetPrevExtendedStyle |
|
|
|
458 |
Window::GetDrawPixelFont |
|
|
|
459 |
OutputDevice::GetGlyphBoundRects |
|
|
|
460 |
OutputDevice::GetOutOffXPixel |
|
|
|
461 |
Window::GetActivateMode |
|
|
|
462 |
Window::SetSmartUniqueId |
|
|
|
463 |
OutputDevice::GetAlphaBitCount |
|
|
|
464 |
BitmapEx::GetColorTransformedBitmapEx |
|
|
|
465 |
Window::IsZoom |
|
|
|
466 |
Window::StartAutoScroll |
|
|
|
467 |
Window::HasActiveChildFrame |
|
|
|
468 |
Window::GetDisplayText |
|
|
|
469 |
Window::GetControlForeground |
|
|
|
470 |
OutputDevice::GetOutOffYPixel |
|
|
|
471 |
Window::SaveBackground |
|
|
|
472 |
Dialog::GetDrawWindowBorder |
|
|
|
473 |
OutputDevice::IsMapMode |
|
|
|
474 |
OutputDevice::BeginFontSubstitution |
|
|
|
475 |
Window::IsClipSiblingsEnabled |
|
|
|
476 |
SystemWindow::SetZLevel |
|
|
|
477 |
Window::IsReallyShown |
|
|
|
478 |
Window::GetFontResolution |
|
|
|
479 |
Window::GetSmartUniqueOrHelpId |
|
|
|
480 |
OutputDevice::GetFontSubstitute |
|
|
|
481 |
SystemWindow::IsPined |
|
|
|
482 |
Bitmap::HasGreyPalette |
|
|
|
483 |
WorkWindow::Maximize |
|
|
|
484 |
SystemWindow::GetMaxOutputSizePixel |
|
|
|
485 |
OutputDevice::GetFontSubstituteCount |
|
|
|
|
Sum |
28734 |
|
|
- = The function is not directly supported, but can implemented using a more general one.
- = The function is not directly supported, but the Event object has a parameter to know when a context menu should be opened.
- = The function is provided by get/setProperty call at VCLXWindow interface.
(?) = Number is to high for this function. There can be clashes with some other functions with the same name.
The following table summarizes the current VCL function coverage of the awt toolkit API.
|
Number |
Coverage |
Current toolkit |
19087 |
66.4% |
---|
Conclusion
The awt toolkit API covers a good amount of the most used functions of VCL. The overall coverage is about 66%, where the top 20 is covered by about 75%. Looking deeper into the current coverage one will reveal that this value has to be increased as some important functions are missing. It's obvious that many interfaces support to set values, but lacks to retrieve them.
- Get and set the parent of a window (
Get/SetParent
). - Get and set the (extended) style of windows (
Get/SetStyle
,Get/SetExtendedStyle
). The current toolkit already supports some of the styles, but not all of them. Most are bound to controls belonging to a dialog. - Simple functions to manipulate/retrieve the state of the cursor (
EnterWait, LeaveWait, IsWait, GetPointerPosPixel
). - Functions to calculate pixel values relative to the output area, parent window and screen (
AbsoluteScreenToOutputPixel, ScreenToOutputPixel, OutputToScreenPixel
). - Functions to capture the mouse input (
CaptureMouse, ReleaseMouse
). - Functions to manipulate the input state of a window (
EnableInput
). - Special window functions (
Is/SetFullScreenMode, Is/SetPresentationMode, SetUpdateMode
) - More functions for the handling of child windows, e.g. travel through the child window list, determine that a child window has the focus (
HasChildPathFocus, GetChild, GetChildCount
). - Handler which support notifications (mouse clicks, keyboard events, activate/deactivate) in child/parent window hierarchies. This is essential for several scenarios e.g. Embedded objects, frame hierarchies etc.
- Functions to get/set a string based help ID/URL, set the help text and retrieve the quick help text on a window (
Get/SetSmartHelpId, SetHelpText
,GetHelpText
,GetQuickHelpText, RequestHelp
). Currently the awt toolkit API only supports a numerical based help ID. This is not an acceptable solution as clashes cannot be excluded for the future, especially if more and more extensions are available. The property itself is string based therefore only the implementation must be adapted. The help functions are tightly coupled with the OpenOffice.org help system. Currently there are investigation to open the help system for extensions, therefore enhancements in the help area should be synchronized. - Functions to get/set a unique ID (based
Get/SetSmartUniqueId
) to support the test tool. This unique ID has to be string based, so with a good name schema clashes can be prevented. It must be discussed if a help URL - Handler to get notifications that Office settings have been changed ( fonts, colors, accessibility) and function to retrieve these settings (
DataChanged, Get/SetSettings
). A better system integration is an important key feature for customers and therefore extensions should also support it.
As a canvas API is currently in development the following missing features should be implemented there.
- Using output device map modes.
- Manipulating bitmaps/images ( e.g.
SetSizePixel
,Scale
,Filter
) - Generic graphical output.
Some classes/features should be provided by higher level libraries as they need a much tighter integration into the OpenOffice.org framework. This integration guarantees support for additional features like: customization, persistence and consistent look&feel. The following classes are already part of these higher level libraries or will be supported by a UNO API in the near future.
- Toolbars
A normal OpenOffice.org toolbar which can be docked and customized. - Menubar
A menu bar provided by an application module. - Statusbar
A status bar provided by an application module. - Docking windows
Currently not supported by the framework based layout manager API. Support will be added in the near future and is therefore not dependent from the awt toolkit API work.
Analysis in dialog dependent code/resources
This chapter analyses which controls generic dialogs typically use, how they use controls and which functions. It's safe to assume that extension developers will use dialogs to provide their functions to users. Therefore awt toolkit API has to provide a good coverage, so developers are able to create easy to use dialogs.
Usage of controls in OpenOffice.org dialogs
The following tables shows the usage of controls in the OpenOffice.org application dialogs and tab pages which are defined by a resource file. A green background color marks the controls which can be created by the current awt toolkit implementation.
Control Type |
ModalDialog |
ModelessDialog |
TabPage |
Sum |
CancelButton |
231 [#sdfootnote1anc 1]A SvTreeListBox control provides functions to represent hierarchical data. Nodes with sub-nodes can be opened/closed with a +/- symbol in front of the node. The Tools - Options dialog uses a SvTreeListBox control to organize the options belonging to a specific application module or function. [#sdfootnote2anc 2]A ValueSet control provides a set of images where the user can select one of them. It's often used where images give a better feedback what the function really does (e.g. Left, center, right, justified use images with lines). The Writer dialog accessible via Format - Columns offers a ValueSet control between the Columns field and the page image. |
25 |
6 |
262 |
---|---|---|---|---|---|---|---|---|---|
CheckBox |
306 |
56 |
501 |
863 | |||||
ComboBox |
32 |
10 |
33 |
75 | |||||
Control |
77 |
11 |
122 |
210 | |||||
CurrencyBox |
|||||||||
CurrencyField |
|||||||||
DateBox |
|||||||||
DateField |
2 |
2 |
4 | ||||||
Edit |
163 |
41 |
192 |
396 | |||||
FixedBitmap |
16 |
16 | |||||||
FixedImage |
16 |
27 |
43 | ||||||
FixedLine |
302 |
37 |
464 |
803 | |||||
FixedText |
532 |
92 |
1047 |
1671 | |||||
GroupBox |
1 |
2 |
8 |
11 | |||||
HelpButton |
193 |
22 |
215 | ||||||
ImageButton |
31 |
29 |
74 |
134 | |||||
ImageRadioButton |
5 |
12 |
17 | ||||||
ListBox |
148 |
38 |
324 |
510 | |||||
LongCurrencyBox |
|||||||||
LongCurrencyField |
|||||||||
MenuButton |
4 |
1 |
8 |
13 | |||||
MetricBox |
10 |
10 | |||||||
MetricField |
60 |
228 |
288 | ||||||
MoreButton |
5 |
7 |
12 | ||||||
MultiLineEdit (*) |
24 |
1 |
11 |
36 | |||||
MultiListBox |
6 |
1 |
12 |
19 | |||||
NumericBox |
|||||||||
NumericField |
39 |
95 |
134 | ||||||
OKButton |
224 |
16 |
3 |
243 | |||||
PatternBox |
|||||||||
PatternField |
1 |
1 | |||||||
PushButton |
208 |
45 |
215 |
468 | |||||
RadioButton |
229 |
4 |
227 |
460 | |||||
ScrollBar |
3 |
2 |
2 |
7 | |||||
SpinField |
15 |
15 | |||||||
TabControl |
2 |
1 |
1 |
4 | |||||
TimeBox |
|||||||||
TimeField |
4 |
3 |
7 | ||||||
ToolBox |
2 |
1 |
4 |
7 | |||||
Window |
25 |
6 |
54 |
85 | |||||
Sum |
2890 |
448 |
3701 |
7039 |
(*) The UnoControlEditModel service which documents the supported properties of an edit control describes a boolean property called MultiLine. That means although the awt toolkit API is not able to create a multilineedit control using the awt toolkit factory, it has multi line support via properties.
Once again this is an evidence that the whole awt toolkit API design is not easy to understand for the typical developer with VCL knowledge. There is a central factory which can create windows and controls, but from VCL point of view some are missing. The missing controls are part of a property set provided by another control. This is a good example where a documentation could really help developers to understand the design concepts. It should describe the design goals and the general structure of the API.
The control type Control is a special placeholder in resource files for controls which cannot be completely initialized by resources. The real control type is created by the implementation of the dialog at runtime. The analysis of the source code revealed the following special controls:
Control Type |
Count |
Proportion |
SvTreeListBox[#sdfootnote1sym 1] |
44 |
23.8% |
---|---|---|---|---|---|
SvTabListBox (based on SvTreeListBox) |
12 |
6.5% | |||
EditBrowseBox |
4 |
2.2% | |||
_HeaderTabListBox (based on SvTabListBox) |
6 |
3.2% | |||
SvHeaderTabListBox (based on SvTabListBox) |
4 |
2.2% | |||
HeaderBar |
1 |
0.5% | |||
GraphCtrl |
2 |
1.1% | |||
SvxCheckListBox (based on SvTreeListBox) |
14 |
7.6% | |||
ValueSet[#sdfootnote2sym 2] |
25 |
13.5% | |||
DialControl |
5 |
2.7% | |||
FrameSelector |
1 |
0.5% | |||
WrapField |
2 |
1.1% | |||
SuggestionDisplay |
1 |
0.5% | |||
SvxRectCtl |
11 |
5.9% | |||
FixedBorder |
2 |
1.1% | |||
PreviewWindow |
4 |
2.2% | |||
SvxXRectPreview |
10 |
5.4% | |||
SvxMeasurePreview |
1 |
0.5% | |||
SvxPixelCtl |
1 |
0.5% | |||
SvxXConnectionPreview |
1 |
0.5% | |||
SvxShowCharSet |
1 |
0.5% | |||
SvxShowText |
2 |
1.1% | |||
SvxXLinePreview |
4 |
2.2% | |||
ColorConfigCtrl_Impl |
1 |
0.5% | |||
SwDropCapsPict (Writer) |
1 |
0.5% | |||
SwAssignFieldsControl (Writer) |
1 |
0.5% | |||
ScDPFieldWindow (Calc) |
5 |
2.7% | |||
ScEditBox (Calc based on MultiLineEdit) |
1 |
0.5% | |||
ScEditWindow (Calc) |
12 |
6.5% | |||
SdHtmlAttrPreview (Draw) |
1 |
0.5% | |||
SmShowFont (Math) |
1 |
0.5% | |||
SmShowSymbolSet (Math) |
2 |
1.1% | |||
SmShowSymbol (Math) |
2 |
1.1% | |||
Sum |
185 |
100.0% |
Some of the controls are implemented in the application projects for context specific purposes, so it make no sense to provide them via toolkit (light blue background in the table above).
There is one complex control which is very often used (SvTreeListBox)
, it has a usage count of about 44% (including derivatives like SvCheckListBox,SvTabListBox,SvHeaderTabListBox,_HeaderTabListBox
). The next control on the list has less than a third the usage count of the SvTreeListBox
control and is called ValueSet
. It offers a image based radio button group and often used to show the effect of a function/mode, e.g. the different text alignments are provided as images with lines where users can see the future text layout. It's very interesting that there is a class of some controls which have a usage count of about 6-7% following on third place.
Conclusion
About 40% of all dialogs use the controls SvTreeListBox
(including derivatives) and/or ValueSet
which are currently not supported by the awt toolkit API. As these controls are very powerful, often used and it's not easy to design dialogs with complex data without them, awt toolkit should support them.
The form controls collection enfolds a GridControl (called Table Control) which can also be valuable for the awt toolkit API. May be it's very easy to integrate it into the toolkit implementation. This should be further investigated. It has to be discussed if other complex controls should be supported by the awt toolkit API (e.g. SvTabListBox, EditBrowseBox, SvxCheckListBox, SvxRectCtl, SvxXRectPreview
). They can be valuable in some situations, but it's not clear if they are important enough to invest so much time integrate them. There is also a technical problem as the toolkit only depends on VCL. Therefore it cannot easily use classes from higher level projects, like svtools and svx.
Functions used in dialog implementations regarding controls
The implementation of a dialog focuses on different aspects than normal Office code. The most important parts of a dialog implementation is:
- Set the correct state for every control
- The user can interact with all controls.
- Retrieve or track the current state of all controls.
Therefore using handlers and set, get and change the state of the controls are very important tasks.
The following table shows the most used functions of the analyzed OpenOffice.org dialog implementations and which are currently supported by the awt toolkit API. The analysis used the following base control types:
- Button
- Edit
- PushButton
- CheckBox
- RadioButton
- FixedText
- ListBox
- FixedLine
- ComboBox
- MetricField
- SpinField
The function column always use a single class where it's possible that several different classes could be involved (e.g. the classes RadioButton and CheckBox use a couple of same methods like Check(), IsChecked()).
Methods which are supported by the awt toolkit API have a green background color.
|
Function |
Usage count |
Proportion |
Accumlated |
---|---|---|---|---|
1 |
Window::Enable |
1994 |
13.9% |
13.9% |
2 |
Window::SetText |
1006 |
7.0% |
20.9% |
3 |
RadioButton::Check |
940 |
6.6% |
27.5% |
4 |
Button::SetClickHdl |
751 |
5.2% |
32.8% |
5 |
Window::Hide |
715 |
5.0% |
37.7% |
6 |
Window::Show |
613 |
4.3% |
42.0% |
7 |
RadioButton::IsChecked |
576 |
4.0% |
46.0% |
8 |
ComboBox::GetSelectEntryPos (3) |
539 |
3.8% |
49.8% |
9 |
Window::GetText |
525 |
3.7% |
53.5% |
10 |
ComboBox::SelectEntryPos |
519 |
3.6% |
57.1% |
11 |
RadioButton::SaveValue |
518 |
3.6% |
60.7% |
12 |
ComboBox::InsertEntry |
416 |
2.9% |
63.6% |
13 |
ComboBox::SetSelectHdl |
320 |
2.2% |
65.9% |
14 |
Edit::SetModifyHdl |
260 |
1.8% |
67.7% |
15 |
Window::GrabFocus |
249 |
1.7% |
69.4% |
16 |
ComboBox::Clear |
222 |
1.6% |
71.0% |
17 |
Window::GetPosPixel |
221 |
1.5% |
72.5% |
18 |
Window::SetPosPixel |
209 |
1.5% |
74.0% |
19 |
PushButton::SetState |
187 |
1.3% |
75.3% |
20 |
Window::Invalidate |
183 |
1.3% |
76.5% |
21 |
Window::GetSizePixel |
170 |
1.2% |
77.7% |
22 |
Window::SetHelpId |
162 |
1.1% |
78.9% |
23 |
Window::SetUpdateMode |
141 |
1.0% |
79.8% |
24 |
ComboBox::GetEntryCount |
128 |
0.9% |
80.7% |
25 |
ComboBox::GetEntry |
123 |
0.9% |
81.6% |
26 |
Window::SetSizePixel |
122 |
0.9% |
82.5% |
27 |
ComboBox::GetEntryData |
119 |
0.8% |
83.3% |
28 |
Window::DataChanged |
98 |
0.7% |
84.0% |
29 |
ComboBox::GetEntryPos (1) |
97 |
0.7% |
84.6% |
30 |
ComboBox::RemoveEntry |
92 |
0.6% |
85.3% |
31 |
Control::SetLoseFocusHdl |
88 |
0.6% |
85.9% |
32 |
ComboBox::SetNoSelection |
88 |
0.6% |
86.5% |
33 |
Window::KeyInput |
83 |
0.6% |
87.1% |
34 |
CheckBox::EnableTriState |
75 |
0.5% |
87.6% |
35 |
Edit::SetSelection |
74 |
0.5% |
88.1% |
36 |
Window::SetPosSizePixel |
67 |
0.5% |
88.6% |
37 |
PushButton::GetState |
66 |
0.5% |
89.1% |
38 |
ComboBox::SetEntryData |
65 |
0.5% |
89.5% |
39 |
Button::SetModeImage |
61 |
0.4% |
89.9% |
40 |
Window::SetStyle |
61 |
0.4% |
90.4% |
41 |
Window::Paint |
58 |
0.4% |
90.8% |
42 |
SpinField::SetLast |
48 |
0.3% |
91.1% |
43 |
ComboBox::SetDoubleClickHdl (2) |
48 |
0.3% |
91.4% |
44 |
Window::Notify |
47 |
0.3% |
91.8% |
45 |
RadioButton::GetSavedValue |
46 |
0.3% |
92.1% |
46 |
Window::GetWindow |
45 |
0.3% |
92.4% |
47 |
SpinField::SetFirst |
45 |
0.3% |
92.7% |
48 |
Window::MouseButtonDown |
44 |
0.3% |
93.0% |
49 |
Control::SetGetFocusHdl |
44 |
0.3% |
93.3% |
50 |
Window::PreNotify |
43 |
0.3% |
93.6% |
51 |
SpinField::GetFirst |
39 |
0.3% |
93.9% |
52 |
Window::StateChanged |
39 |
0.3% |
94.2% |
53 |
RadioButton::SetToggleHdl |
35 |
0.2% |
94.4% |
54 |
Edit::GetSelection |
31 |
0.2% |
94.6% |
55 |
Edit::ClearModifyFlag |
30 |
0.2% |
94.9% |
56 |
Window::GetType |
30 |
|
|
57 |
Window::IsEnabled |
30 |
|
|
58 |
Window::GetParent |
27 |
|
|
59 |
Window::Resize |
26 |
|
|
60 |
Window::SetOutputSizePixel |
24 |
|
|
61 |
Window::Update |
24 |
|
|
62 |
Window::Command |
22 |
|
|
63 |
Window::MouseButtonUp |
20 |
|
|
64 |
Spinfield::SetUpHdl |
19 |
|
|
65 |
Edit::SetReadOnly |
19 |
|
|
66 |
Spinfield::SetDownHdl |
19 |
|
|
67 |
Window::SetZOrder |
18 |
|
|
68 |
Window::SetType |
16 |
|
|
69 |
ComboBox::SetDropDownLineCount |
16 |
|
|
70 |
Edit::SetModifyFlag |
16 |
|
|
71 |
Window::SetBorderStyle |
14 |
|
|
72 |
Window::MouseMove |
14 |
|
|
73 |
RadioButton::SetModeRadioImage |
14 |
|
|
74 |
Window::SetHelpText |
13 |
|
|
75 |
Window::IsVisible |
12 |
|
|
76 |
MetricField::ConvertValue |
11 |
|
|
77 |
ComboBox::GetSelectEntryCount |
11 |
|
|
78 |
Window::GetFocus |
11 |
|
|
79 |
Window::SetUniqueId |
10 |
|
|
80 |
Edit::SetMaxTextLen |
9 |
|
|
81 |
Window::Disable |
9 |
|
|
82 |
Window::LoseFocus |
9 |
|
|
83 |
Window::SetParent |
9 |
|
|
84 |
SpinField::GetLast |
9 |
|
|
85 |
Edit::IsModified |
9 |
|
|
86 |
Window::ToTop |
8 |
|
|
87 |
Edit::IsReadOnly |
8 |
|
|
88 |
Window::HasChildPathFocus |
8 |
|
|
89 |
Window::SetQuickHelpText |
8 |
|
|
90 |
Window::GetUniqueId |
7 |
|
|
91 |
Window::GetHelpId |
7 |
|
|
92 |
Window::OutputToScreenPixel |
7 |
|
|
93 |
ComboBox::IsEntryPosSelected |
6 |
|
|
94 |
Spinfield::SetFirstHdl |
6 |
|
|
95 |
ComboBox::CalcWindowSizePixel |
6 |
|
|
96 |
Spinfield::SetLastHdl |
5 |
|
|
97 |
Window::RequestHelp |
5 |
|
|
98 |
Window::GetQuickHelpText |
5 |
|
|
99 |
Window::EnableInput |
5 |
|
|
100 |
Window::Move |
5 |
|
|
101 |
ComboBox::EnableAutocomplete |
5 |
|
|
102 |
Window::SetData |
5 |
|
|
103 |
PushButton::EndSelection |
5 |
|
|
104 |
Button::GetStandardText |
5 |
|
|
105 |
Window::InvertTracking |
5 |
|
|
106 |
Window::GetStyle |
4 |
|
|
107 |
Edit::GetSelected |
4 |
|
|
108 |
Window::RemoveUserEvent |
4 |
|
|
109 |
CheckBox::GetCheckImage |
4 |
|
|
110 |
Edit::Undo |
4 |
|
|
111 |
MetricField::ConvertDoubleValue |
4 |
|
|
112 |
Window::LeaveWait |
4 |
|
|
113 |
Window::Invert |
4 |
|
|
114 |
Window::GetHelpText |
4 |
|
|
115 |
Window::EnterWait |
4 |
|
|
116 |
Window::ScreenToOutputPixel |
4 |
|
|
117 |
Edit::ReplaceSelected |
4 |
|
|
118 |
Window::Deactivate |
4 |
|
|
119 |
Window::Sync |
3 |
|
|
120 |
Window::IsWindowOrChild |
3 |
|
|
121 |
Window::SetSettings |
3 |
|
|
122 |
Button::SetImageAlign |
3 |
|
|
123 |
Edit::GetMaxTextLen |
3 |
|
|
124 |
Window::IsActive |
3 |
|
|
125 |
Window::Activate |
3 |
|
|
126 |
Control::GetLineCount |
3 |
|
|
127 |
Window::GetPointerPosPixel |
2 |
|
|
128 |
Window::SetControlBackground |
2 |
|
|
129 |
Edit::SetUpdateDataHdl |
2 |
|
|
130 |
Window::KeyUp |
2 |
|
|
131 |
Window::EnablePaint |
2 |
|
|
132 |
Window::Flush |
2 |
|
|
133 |
Window::SetControlForeground |
2 |
|
|
134 |
Window::GetChild |
2 |
|
|
135 |
Window::GetChildCount |
2 |
|
|
136 |
PushButton::SetSymbol |
2 |
|
|
137 |
Button::GetClickHdl |
2 |
|
|
138 |
Button::EnableImageDisplay |
1 |
|
|
139 |
Window::HasFocus |
1 |
|
|
140 |
Window::Tracking |
1 |
|
|
141 |
Window::SetCursor |
1 |
|
|
142 |
ComboBox::EnableMultiSelection |
1 |
|
|
143 |
Window::HideFocus |
1 |
|
|
144 |
Edit::GetSubEdit |
1 |
|
|
145 |
Window::SaveFocus |
1 |
|
|
146 |
PushButton::GetSymbol |
1 |
|
|
147 |
Edit::SetInsertMode |
1 |
|
|
148 |
Window::EndSaveFocus |
1 |
|
|
149 |
Window::GetCursor |
1 |
|
|
150 |
ComboBox::SetSeparatorPos |
1 |
|
|
151 |
Window::GetDesktopRectPixel |
1 |
|
|
152 |
Window::IsInputEnabled |
1 |
|
|
153 |
Window::CalcZoom |
1 |
|
|
154 |
Button::SetFocusRect |
1 |
|
|
155 |
Window::IsDefaultPos |
1 |
|
|
156 |
Window::ShowFocus |
1 |
|
|
157 |
Button::EnableTextDisplay |
1 |
|
|
158 |
Window::CalcOutputSize |
1 |
|
|
159 |
ComboBox::EnableDDAutoWidth |
1 |
|
|
160 |
Spinfield::CalcMinimumSize |
1 |
|
|
161 |
Window::GetControlFont |
1 |
|
|
162 |
Window::GetData |
1 |
|
|
163 |
Window::SetControlFont |
1 |
|
|
164 |
Window::GetWindowExtentsRelative |
1 |
|
|
165 |
Window::ReleaseMouse |
1 |
|
|
|
Sum |
14322 |
|
|
The following table summarizes the current awt toolkit API coverage of the base VCL controls.
|
Number |
Coverage |
Current toolkit |
11615 |
81.1% |
---|
The overall coverage of about 81% of the most used function calls looks very promising. The top nine methods are all supported which cover about 54% of all function calls. There are also some controls which misses a better API support, like the MetricField
(the most used field control that has no own control model) or the missing method SelectEntryPos
.
UNO API support to create dialogs (awt toolkit API, Basic dialogs)
The awt toolkit API supports more than one way to create dialogs, although only one way looks convincing as the other need much more implementation work. The Basic IDE supports to create dialogs which are stored as XML files (the file format is based on XUL). The dialog resources must be part of a Basic library and can then be used to create awt toolkit API based dialogs via a factory (without using any Basic macro). The service com.sun.star.awt.DialogProvider
API offers the factory function createDialog
( string dialogResourceURL ) via com.sun.star.awt.XDialogProvider
. This solution is documented in the Developer's Guide (see chapter 11.5.2 OpenOffice.org Basic and Dialogs "Programming Dialogs and Dialog Controls" and 18.3.4 Creating dialogs from macros).
The latest feature of the com.sun.star.awt.DialogProvider
API (accessible by the interface com.sun.star.awt.XDialogProvider2
and function createDialogWithHandler
) calls automatically an event handler. Therefore developers can create most dialogs very easily by using the this feature.
A dialog is a control container which provides easy access to its controls. Most controls support a control model that offers a large set of properties to customize them. The property set interface makes flexible enhancements possible as only new properties must be added. There is no need to create a new interfaces or add new methods (which is not allowed for published interfaces).
One drawback, especially for Java developers, could be that there is not layout manager for dialogs. Controls must be absolute positioned and the size of dialogs cannot really be altered. If developers want to support this they have to implement their own layout management. Currently the size of most OpenOffice.org dialogs cannot be altered and VCL has also no generic layout management for dialogs. It must be further discussed how important is this missing feature. Could it hold off developers to implement extensions for OpenOffice.org?
Conclusion
The overall support for dialogs in awt toolkit API is on a level where most developers should be able to implement simple to medium complex dialogs. The awt toolkit dialog provider API makes it easy to create dialogs via resource files and even a generic handler mechanism is supported. To make all these features more accessible for developers there should be an integrated solution (creating dialogs, store the resulting XML file, create code for the controls, create and deploy the whole extension). There are gaps in the awt toolkit API when developers need special controls to present complex data to the user or want to better control over the behavior of the controls.
Therefore it should be extended to support the following missing features:
- A tree-based based control
- A value set control
- A grid control (must be discussed)
- A better support for some of the field controls (e.g. Metricfield has no own control model).
- Some missing functions provided by VCL which have a high usage count
- SelectEntryPos for ComboBoxes, ListBoxes
- SaveValue/GetSavedValue for Buttons
- SetNoSelection for ComboBoxes, ListBoxes
- Get/SetEntryData for ComboBoxes, ListBoxes
- Get/SetState for Buttons
- SetModeImage for Buttons
Missing functions, classes, controls and information in the awt toolkit API
This chapter tries to determine which functions, classes, controls and information are currently missing and could be valuable or vital for developers using the OpenOffice.org Software Development Kit. As this chapters is based on a small amount of data, e.g. community feedback, analyzing some extensions/add-ons sources, only hints can be drawn for the awt toolkit future.
Features demanded by the community
The community was asked to participate in the gap analysis and provide their point of view where things should improve and what's missing in the current awt toolkit API. Although the feedback of the community was not overwhelming some interesting information could be extracted. The most important issue from their point of view is a control which can represent complex or a huge amount data. A couple people clearly stated that something like a grid control is desperately missing. If a developer wants to represent hierarchical data (e.g. a directory of a file system) a tree-based control is also needed. That's not completely the same information which chapter 2.2.1.1 Conclusion revealed, analyzing the current application module dialogs. A grid control is not very often used by the application module dialogs, where a tree-list based control is clearly the number one of all complex controls. Analyzing the current code base cannot provide the whole picture of the OpenOffice.org development. Therefore the demand for a grid control should be taken serious as the current OpenOffice.org form control set already offers a grid-control called "Table Control".
Requirements by extension developers
The review of current extension sources and discussions with extension developers disclosed that nearly the same problems were discovered what the previous chapters reveal. The missing documentation was a real problem as the IDL documentation is not comprehensive enough. Developers were often forced to use the "trail and error" method to fix their special problem. Sometimes work a rounds were implemented although a function to solve the issue is already available.
The next interesting point is that the awt toolkit API is missing some complex controls which are part of modern user interfaces, e.g. a grid control, a tree-list control. While OpenOffice.org itself uses these complex controls in dialogs and docking windows, there is no way to create/control them via awt toolkit API.
Some extension developers miss helper classes/functions to cover recurring tasks regarding dialogs and message boxes. For example VCL supports a couple of different message boxes (info box, warning box, error box, ...) which can easily be used. In contrast an awt toolkit API developer has to create the dialog and all controls separately. It must be further discussed where these helper should be implemented as there are two possible solutions:
- Use the SDK which has to support the two core languages C++ and Java.
- Use the UNO API and provide a language independent solution.
A SDK implementation could offer additional features supported the core languages and their concepts ( e.g. provide base classes, templates ).
The next problem revealed a shortcoming of the awt toolkit API in the aspects of drawing and graphical output. As described previously OpenOffice.org 2.0 (see chapter 1) offers a feature rich canvas UNO API and it should be used for graphical operations. It must be guaranteed that awt toolkit and canvas API can be used in combination by developers. Therefore extending the awt toolkit API to fill the function gap makes no sense. The canvas API has to completely take over this role.
Another interesting problem was discovered when an extension used background processing and calls via UNO OpenOffice.org (e.g. an interval based job). Using a thread to call into OpenOffice.org resulted into certain deadlocks, especially when accessibility support was turned on. There exists an interface called com.sun.star.awt.XReschedule
which offers a reschedule() function. An extension which starts a longer tasks could use reschedule() to keep OpenOffice.org responsive. This solution has some drawbacks which makes it less convincing.
- A low-level function like reschedule() shouldn't be part of the toolkit API.
- The overhead to call a low-level function like reschedule() via UNO.
- Runtime of reschedule() is not known in advanced.
- Creating a message loop in an extension is dangerous.
A better solution would be to support a timer based callback service, which calls back whenever a certain amount of time elapsed. The extension could process a task and call OpenOffice.org without any problems regarding deadlocks.
There was a complaint that the current image control doesn't offer image animation. Extending the image control would be the easiest way to support. It has to get all the necessary information to do the animation on its own. There were some complaints about non-working interfaces and services (e.g. the image observer/consumer infrastructure which includes support for animated images does not work)
Conclusions
The following requirements for extension developers can be derived from the reviews and discussions:
- A comprehensive documentation is needed describing the design idea, all services, interfaces and properties. It's also crucial that good examples are available which are often used by developers as starting point for their own work. The documentation has to reference the canvas API (
com.sun.star.rendering
) which is the correct API to implement graphical operations. - Support complex controls. Especially a tree-list and grid control were very often mentioned. A rich-text control was also demanded, but it must be further discussed how important is this control for extension developers. An image animation control could also attract developers to create extensions (animations are very common in current GUIs to show that a lengthy task is processed).
- Support a timer-based callback mechanism which will solve multithreading/deadlock problems with the current OpenOffice.org API implementation. It must be discussed, if the new threading framework is able to solve these kind of problems in the near future.
- There were some complaints about non-working services/interfaces. Therefore the awt toolkit API has to be carefully checked to guarantee that all provided services and interfaces correctly work as documented.
- Internationalization must be supported. It must be discussed what parts have to be covered by the awt toolkit API. The UNO dialog resource concept should support internationalization for user-defined dialogs. May be it can be extended to also provide resources for the default message boxes and dialogs.
Final conclusion
The analysis revealed that the awt toolkit API doesn't deserve its a bad reputation. The function coverage is on an average level where the most prominent functions are supported. The control and dialog support is even better and give developers the opportunity to create normal dialogs.
It should be clear that developers who need more control over the GUI elements, need special controls or special functions will quickly learn that it is not a complete GUI API. The awt toolkit API supports several simple controls, but is missing more complex ones. The analysis revealed that at least a tree-list based control, a value set control and (demanded by the community and several extensions developers) a grid control are missing. Some controls are missing often used functions and therefore should be extended to increase the overall function coverage. The central window interfaces lack functions to better integrate into the OpenOffice.org environment. For example to retrieve the settings for colors, sizes, fonts and others. We need support for the Testtool to profit from automatic testing, functions to have a better control of child windows, handler support for window hierarchies and some special functions which cannot be achieved using the current API set. Internationalization is another key point where the awt toolkit API completely lacks support. Currently extension developers have to implement their own resource concept. It's planed to extended the UNO dialog resource format to offer internationalization for dialogs. It must be discussed how we want to solve internationalization for other use cases and classes (e.g. windows, docking windows with user interface elements) which are normally not defined by resources.
One important result of the analysis is that a developer documentation is absolutely missing and a huge barrier to start using the awt toolkit API. The Developer's Guide references several awt interfaces and services, but completely lacks a chapter where the awt toolkit API is explained in detail. The IDL based comments and descriptions are clearly not enough and create more questions than answers. It's important to describe the design idea of the toolkit API and all available classes with their functions and properties. Working examples are also needed to offer developers best practices for several use cases. Additionally the Office SDK could be extended with helper classes which cover recurring tasks that normally would need manual work by developers.
The current state of the awt toolkit API is not fully known as only a fraction of the current awt toolkit API is normally used by the accepted OpenOffice.org projects. Additionally it was deprecated for quite some time and reactivated for OpenOffice.org 2.0. Extension developers found several issues using the awt toolkit API. Therefore test cases (including complex tests) should be written to find bugs and stabilize the implementation.
Nevertheless the awt toolkit can be extended to better support more developers in a short to medium time frame. Even OpenOffice.org application projects could benefit using the awt toolkit API (a working reference concept, no direct dependency to VCL, awt toolkit objects can be provided to external developers via an UNO interface). It must be carefully discussed how far the awt toolkit API should be extended. It should be clear that it cannot be a full featured wrapper for the C++ based VCL. Therefore the next step should be to discuss the outcome of this document, define the future role of the awt toolkit API in the OpenOffice.org environment and to create a schedule which defines the most important development steps.