Framework/Article/Gap Analysis Tookit API

From OpenOffice.org Wiki

Jump to: navigation, search

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.

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 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