Chapter 8: Miscellaneous Routines | OpenOffice.org Macros Explained

This chapter introduces the subroutines and functions supported by OpenOffice.org Basic that do not easily fit into another larger category-for example, routines related to flow control, user input, user output, error handling, inspecting variables , color , and display-as well as those routines that you should not use.

I was tempted to call this chapter "Leftovers" because it contains the routines that were left over after I grouped the others into chapters. Although the word "leftovers" frequently has a negative connotation, this is certainly not the case for the routines discussed in this chapter. The eclectic mix of routines includes some of the more interesting and useful routines that are varied enough to prevent boredom from pulling you off to sleep.

Display and Color

The OOo Basic functions related to color manipulations and determining screen metrics are shown in Table 1 . The screen metrics provide the size of each pixel so that you can write macros to create objects at a given size and position objects more precisely.

Table 1: Display- and color-related functions in OOo Basic.
Function	Description
Blue(color)	Get the blue component
GetGuiType	Get the GUI type: Mac, Windows, Unix
Green(color)	Get the green component
QBColor(dos_color)	Return RGB for standard color
Red(color)	Get the red component
RGB(red, green, blue)	RGB to colorNumber
TwipsPerPixelX	Width of each pixel in twips
TwipsPerPixelY	Height of each pixel in twips

Determine the GUI Type

The GetGuiType function returns an integer corresponding to the graphical user interface (GUI). In other words, you can find out what type of computer is running the macro ... well, sort of. This function only mentions the GUI type, not the operating system-for example, just Windows, not Windows 98 or Windows XP. The function GetGuiType is only included for backward compatibility with previous versions of OOo Basic.

One of my associates runs OpenOffice.org as a server on his computer at home. He then connects to his home computer from work as a client. The value returned by GetGuiType is not defined while OOo is running in a client/server environment.

Table 2 shows the return values, as documented by the OOo help and seen in the source code as of version 1.1.

Table 2: Return values from GetGuiType.
#	OOo Help	Source Code
1	Windows	Windows (sometimes OS/2, which runs Windows)
2	Not mentioned, OS/2 is no longer supported	OS/2
3	Mac	Not currently returned
4	Unix	Unix
-1	Mentioned as an undefined value	Unsupported OS

The macro in Listing 1 demonstrates the GetGuiType function.

Listing 1: DisplayGUIType is found in the Misc module in this chapter's source code files as SC08.sxw.

 Sub DisplayGUIType()    Dim s As String    Select Case GetGUIType()      Case 1        s = "Windows"      Case 2        s = "OS/2"     'No longer supported      Case 3        s = "Mac OS"   'Not yet supported as of version 1.1      Case 4        s = "UNIX"      Case Else        s = "Unknown value " & CStr(GetGUIType()) & CHR$(10) &_            "Probably running in Client/Server mode"    End Select    MsgBox "GUI type is " & s, 0, "GetGUIType()" End Sub

Determine Pixel Size (in Twips)

OOo Basic has two functions to determine the size of each display pixel (dot) in twips: TwipsPerPixelX and TwipsPerPixelY. The word "twip" is short for "twentieth of a PostScript point." There are 72 PostScript points in an inch, thus 1440 twips in an inch.

In 1886, the American Typefounders Association proposed a unit of measure for typesetting called the "American Printer's Point." There are approximately 72.27000072 Printer's Points in an inch. Years later while developing the PostScript page description language for Adobe Systems, Jim Warnock and Charles Geschke defined the PostScript point as exactly 72 points to an inch. When dot-matrix printers were released, they could print at either 10 or 12 characters per inch. Twips were created as a unit of measure that worked well for both dot-matrix printers and PostScript points.

Note	There are 1440 twips in an inch. This number is important because OOo uses twips for many measurements.

Twips are the standard on which all Microsoft Windows graphics routines are based. Twips are used in the Rich Text Format, printer drivers, screen drivers, and many other products and platforms-including OpenOffice.org. The macro in Listing 2 obtains the number of twips per pixel in both the X and Y direction (horizontal and vertical) and displays the number of pixels per inch.

Listing 2: DisplayPixelSize is found in the Misc module in this chapter's source code files as SC08.sxw.

 Sub DisplayPixelSize   Dim s As String   s = s & TwipsPerPixelX() & " Twips per X-Pixel or " &_       CStr(1440 \ TwipsPerPixelX()) & " X-Pixels per Inch" & CHR$(10)   s = s & TwipsPerPixelY() & " Twips per Y-Pixel or " &_       CStr(1440 \ TwipsPerPixelY()) & " Y-Pixels per Inch"   MsgBox s, 0, "Pixel Size" End Sub

Figure 1: Number of pixels per inch on my computer.

Use Color Functions

Colors on computer monitors , digital cameras , scanners -and those seen by the human eye-are produced by adding the three primary colors of light: red, green, and blue (RGB). When printing or painting, color is produced by absorbing some colors and reflecting others. Color printing uses a different set of colors, called primary pigments: cyan, magenta , yellow, and black (CMYK). These two different systems are based on real physical models. The RGB model is based on how light combines to form colors. The CMYK model is based on what happens when you mix paint of different colors.

OOo Basic uses the RGB model, allowing for 256 different shades of each of the primary colors. This number is stored as a Long Integer. Use the functions Red, Green, and Blue to extract the red, green, and blue components from a color in OOo. Use the RGB function to combine the individual color components and obtain the long integer used by OOo. The RGB function accepts three arguments, each representing one of the primary colors. Each of the color components must be a value from 0 through 255. The RGB function performs no validity checking, so consider the results undefined if you break the rules. In summary, OOo Basic represents RGB colors as a single integer; the functions Red, Green, and Blue extract the red, green and blue components; and the function RGB accepts the red, green, and blue components and returns the OOo Basic representation of the RGB color.

 Dim nRed As Integer            'Can only be 0 through 255 Dim nGreen As Integer          'Can only be 0 through 255 Dim nBlue As Integer           'Can only be 0 through 255 Dim nOOoColor As Long          'Can only be 0 through 16,581,375 nOOoColor = RGB(128, 3, 101)   '8,389,477 nRed   = Red(nOOoColor)        '128 nGreen = Green(nOOoColor)      '3 nBlue  = Blue(nOOoColor)       '101

In the old days of DOS, BASIC supported 16 colors. In Table 3 , the Name column is the name of the color and the DOS Color column is the number used by DOS to represent the color. The OOo Color column contains the corresponding number as represented by OOo. The Red, Green, and Blue columns contain the values returned by the corresponding OOo Basic functions. The QBColor function is designed to accept the DOS Color as an argument and return the corresponding OOo Color.

Table 3: Color representation in OpenOffice.org.
Name	DOS Color	OOo Color	Red	Green	Blue
Black
Blue	1	128			128
Green	2	32768		128
Cyan	3	32896		128	128
Red	4	8388608	128
Magenta	5	8388736	128		128
Yellow	6	8421376	128	128
White	7	8421504	128	128	128
Gray	8	12632256	192	192	192
Light Blue	9	255			255
Light Green	10	65280		255
Light Cyan	11	65535		255	255
Light Red	12	16711680	255
Light Magenta	13	16711935	255		255
Light Yellow	14	16776960	255	255
Bright White	15	16777215	255	255	255

 QBColor(dos_color)

Bug	As of version 1.1, the QBColor function always returns zero.

Campatibility

Visual Basic does not support the functions Red, Blue, Green, TwipsPerPixelX, TwipsPerPixelY, or GetGuiType.