The Frame Service | OpenOffice.org Macros Explained

The desktop is a com.sun.star.frame.Frame service (remember that an object can, and usually does, implement more than one service at a time). For a document, the primary purpose of a frame is to act as a liaison between the document and the visible window. For the desktop, however, the primary purpose is to act as the root frame, which contains all other frames. A frame can hold a component and zero or more subframes-for simplicity, consider a component to be a document. In the case of the desktop, all the other frames are subframes of the root frame, and the component (document) is a set of data. Simply stated, each document contains a frame that it uses to interact with the visible window, but the desktop is a frame so that it can contain, control, and access all of the document's frames .

Tip	For information about the Frame service, see http://api.openoffice.org/docs/common/ref/com/sun/star/frame/Frame.html .

The service comsun.star.frame.Frame-Frame for short-provides numerous interesting capabilities that are not generally useful as part of the Desktop object. For example, the Title and the StatusIndicator defined as part of the Frame service are of no use for the Desktop object because the Desktop object does not have a displayed window. These objects are meaningful only in a frame that contains a display window. The desktop is a frame so that it can act as the root frame for all the other frames.

Tip	Although it is possible to use the desktop as a Frame service to enumerate the contained frames, the XDesktop interface is generally more useful to enumerate the documents rather than the frames. I usually access frames to obtain window titles.

Use the getActiveFrame() method of the desktop to obtain the active frame (see Listing 1 ). The active frame is the frame that contains the current focus. If the currently focused window is not an OpenOffice.org window, getActiveFrame returns the last OOo frame that had the focus.

Listing 1: Print the title of the current frame.

 Print StarDesktop.getActiveFrame().Title

Use the getFrames() method to enumerate or search all of the frames contained in the desktop. The getFrames() method returns an object that implements the com.sun.star.frame.XFrames interface. A frame can contain other frames; the XFrames interface provides access to the contained frames.

Tip	Use the full interface name to find the Web address for the API information on the XFrames interface. It is important that you learn to find the Web pages on the API site from the full service or interface name .

The XIndexAccess Interface

The XFrames interface is derived from the com.sun.star.container.XIndexAccess interface. As its name implies, this interface allows access to the contained frames using a numeric index. Numerous other interfaces also derive from the XlndexAccess interface, allowing a simple numeric index to access the contained elements. See Listing 2 and Figure 1 .

Figure 1: Titles of top-level frames.

Listing 2: DisplayFrameTitles is found in the Desktop module in this chapter's source code files as SC11.sxw.

 Sub DisplayFrameTitles   Dim vFrames As Variant            'All of the frames   Dim vFrame As Variant             'A single frame   Dim i As Integer                  'Index to enumerate the frames   Dim s As String                   'Contains the string to print   REM start at http://api.openoffice.org/docs/common/ref   REM then use the interface com.sun.star.container.XIndexAccess   REM to find the rest of the Web address for the API information   vFrames = StarDesktop.getFrames() 'Get all of the frames   REM getCount() returns the number of contained frames   REM If there are four frames, then i has the values 1, 2, 3, and 4   REM the getByIndex(i) method, however, is zero based. This means   REM that it requires the values 0, 1, 2, and 3   For i = 1 To vFrames.getCount()     vFrame = vFrames.getByIndex(i-1)     s = s & CStr(i-1) & " . " & vFrame.Title & CHR$(10)   Next   MsgBox s, 0, "Frame Titles" End Sub

Tip	Learn how to use the XlndexAccess interface because OOo uses this service in numerous other places.

Find Frames with FrameSearchFlag Constants

Use the com.sun.star.frame.FrameSearchFlag constants to search the OOo frames (see Table 1 ). FrameSearchFlag constants are used to create an enumerated list of frames from the queryFrames() method defined in the XFrames interface. The FrameSearchFlag constants are also used to find a frame when loading a document and specifying which frames will receive a dispatch. In other words, you will see the FrameSearchFlag constants again.

Table 1: com.sun.star.frame.FrameSearchFlag constants.
#	Name	Description
	AUTO	Deprecated. Use 6 = SELF+CHILDREN.
1	PARENT	Include the parent frame.
2	SELF	Include this frame.
4	CHILDREN	Include the child frames of this frame.
8	CREATE	Create a frame if the requested frame is not found.
16	SIBLINGS	Include the child frames of the parent of this frame.
32	TASKS	Include all frames in all tasks in the current frames hierarchy.
23	ALL	Include all frames except TASKS frames. 23 = 1+2+4+16 = PARENT + SELF + CHILDREN + SIBLINGS.
55	GLOBAL	Include every frame. 55 = 1+2+4+16+32 = PARENT + SELF + CHILDREN + SIBLINGS + TASKS.

Tip

The values in Table 1 are current as of OOo 1.1. Check the API Web site http://api.openoffice.org/docs/common/ref/com/sun/star/frame/FrameSearchFlag.html for the latest values. I already mentioned the Web site numerous times, but it really is important that you learn where to find the latest information for when you really need it.

The values in Table 1 are enumerated constants. OOo has enumerated values for many different purposes. You can access all enumerated values in OOo Basic in a similar fashion. Each constant has an assigned name, as seen in the Name column in Table 1. You can use this name by preceding it with com.sun.star.frame.FrameSearchFlag. For example, use com.sun.star.frame.FrameSearchFlag.TASKS to use the TASKS constant (see Listing 3 ). The name of a constant provides meaningful information while reading the Basic code. Using the constant values directly, although allowed, obfuscates your code-in other words, causes it to be less readable.

Listing 3: Constant names are not case sensitive.

 Print com.sun.star.frame.FrameSearchFlag.TASKS '32 Print COM.SUN.STAR.frame.FrameSearchFLAG.tasKS '32 Case does not matter

Tip	Constant names, like almost everything else in OOo Basic, are not case sensitive. Just remember: If it isn't a string argument, case probably doesn't matter.

The values in Table 1 are flags that may be combined. For example, the values for ALL and GLOBAL exist only as a convenience; they are a combination of the other flags as shown in Table 1. You can create your own values if a suitable combination is not provided. For example, to search ALL and to create a frame if it is not found, use the value 31 = 23 + 8 = ALL + CREATE.

Tip	Not that it really matters, but these are really acting as bit-flags that can be combined by using the OR operator.

The code in Listing 4 uses the FrameSearchFlag constants to search the frames that are children of the Desktop object. The output from Listing 4 duplicates the output from Listing 2 by obtaining a list of all child frames from the Desktop object. Note that the return type from the queryFrames() method is an array. I know this because I looked at the API Web site. Although you can inspect the returned object to see what it is, it isn't possible to determine the values of the arguments to the queryFrames() method by inspection alone.

Listing 4: QueryFrames is in the Desktop module in this chapter's source code files as SC11.sxw.

 Sub QueryFrames   Dim vFrames As Variant           'All of the frames   Dim vFrame As Variant            'A single frame   Dim i As Integer                 'Index to enumerate the frames   Dim s As String                  'Contains the string to print   REM Call the queryFrames() method on the XFrames interface.   REM This takes one argument, a FrameSearchFlag.   REM This searches the children of the desktop.   vFrames = StarDesktop.getFrames().queryFrames(_                   com.sun.star.frame.FrameSearchFlag.CHILDREN)   For i = LBound(vFrames) To UBound(vFrames) ' The return value is an array.     s = s & vFrames(i).Title & CHR$(10)      ' Append the title and a new line.   Next   MsgBox s, 0, "Frame Titles"                ' Display the titles. End Sub

Tip	Some frames return a zero-length string for the Title. For example, open a help window and then enumerate the frames.