Framework/Article/Gap Analysis Tookit API

Gap analysis for awt toolkit API by Carsten Driesner Framework Project 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.

1. The awt toolkit API and VCLUnoHelper
2. OpenOffice.org application code / dialogs and VCL
3. 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.

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 and SetParent, ScreenToOutputPixel and OutputToScreenPixel.
• 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

1. = The function is not directly supported, but can implemented using a more general one.
2. = The function is not directly supported, but the Event object has a parameter to know when a context menu should be opened.
3. = 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 Count = 275	ModelessDialog Count = 33	TabPage Count = 300	Sum Count = 608	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:

1. Use the SDK which has to support the two core languages C++ and Java.
2. 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.

1. A low-level function like reschedule() shouldn't be part of the toolkit API.
2. The overhead to call a low-level function like reschedule() via UNO.
3. Runtime of reschedule() is not known in advanced.
4. 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.