Chapter 10. Utility Classes and Objects

Table of Contents
.SystemErrorCode
DlgUtil Class
Rect Class
Point Class
Size Class
DlgArea Class
DlgAreaU Class
VirtualKeyCodes Class

The ooDialog framework provides a number of utility classes that are useful when writing more complex programs. These classes do not easily fit into the category of a type of dialog or a type of dialog control and are therefore documented separately. In addition ooDialog places some globally available objects in the .local envirnoment.

The classes and objects in the following table are described in this chapter:

Table 10-1. ooDialog Utilitiy Classes and Objects

Utility Class or ObjectDescription
.SystemErrorCode.SystemErrorCode
DlgArea ClassDlgArea Class
DlgAreaU ClassDlgAreaU Class
DlgUtil ClassDlgUtil Class
Point ClassPoint Class
Rect ClassRect Class
Size ClassSize Class
VirtualKeyCodes ClassVirtualKeyCodes Class

.SystemErrorCode

The .SystemErrorCode can be used, at times, to obtain additional information when the invocation of a method generates an operating system error.

ooDialog provides an interface to the Windows operating system APIs. To be specific, the Win32 APIs, and mostly those dealing with dialogs and other graphical aspects of the user interface. Some of the Win32 APIs will set a system error code when something goes wrong. (On the other hand, many of the Win32 APIs do not set a system error code.)

When the ooDialog framework first intializes, it sets the value of .SystemErrorCode to 0. Some, of the methods of the ooDialog classes will set the .SystemErrorCode to the value of the system error code when the method detects that a Win32 API has failed and has set the error code. Most methods do not change the value of .SystemErrorCode. Only those methods that explicitly document they use .SystemErrorCode will ever change its value.

One consequence of the fact that most methods do not change .SystemErrorCode is that its value is only meaningful immediately after the invocation of a method that is documented as using .SystemErrorCode. Those methods will set the code to 0 and, if they detect a Win32 API has set the system error code to non-zero, they will then set .SystemErrorCode to the value of the system error. Checking .SystemErrorCode after the invocation of a method that does not set .SystemErrorCode will tell the programmer nothing. Neither that a system error happened, or that it did not happen.

The getImage() method of the .Image class is one method that does change .SystemErrorCode. This is an example of a possible usage:

image = .Image~getImage("resources\bogus.bmp")
if image~isNull then do
  say "Error getting the bogus.bmp image."
  if .SystemErrorCode <> 0 then do
    say 'System error code:' .SystemErrorCode
    say '  system message:' SysGetErrorText(.SystemErrorCode)
  end
end

/*
  Output on the screen might be:

Error getting the bogus.bmp image.
System error code: 2
  system message: The system cannot find the file specified.
*/