Futurebasic/Language/Reference/wndblk

WNDBLK

Syntax

ptr& = WNDBLK

Description

This function returns a pointer to FutureBasic's internal Window Descriptor Block. The Window Descriptor Block is an array of Window Descriptors. Each Window Descriptor is a record which contains information about one of your program's windows; FutureBasic maintains a Window Descriptor for each window that you create using the WINDOW statement. The structure of a Window Descriptor is as follows:

BEGIN RECORD wDescriptor DIM wptr& 'Pointer to window record DIM efdHeadH& 'Handle to the first Edit Field Descriptor DIM activeEfH& 'Handle to active edit field DIM clipH& 'Handle to window's clip region END RECORD

The wptr& element points to the window's window record, which is a structure that the MacOS Window Manager maintains for each open window. This is the same pointer that is returned by the GET WINDOW statement.
The efdHeadH& element is a handle to the first Edit Field Descriptor for the window. There is an Edit Field Descriptor for each edit field or picture field in the window; see below for more information. If there are no edit fields nor picture fields in the window, efdHeadH& is _nil (zero).
The activeEfH& element is a handle to the currently active edit field or picture field (if any) in the window. This is the same as the handle returned by the WINDOW(_efHandle) function when the window is active. If there is no active field in the window, activeEfH& is _nil (zero).
The clipH& element is a handle to the window's clip region. However, if the window's _noAutoClip attribute is set, clipH& is _nil (zero).

You can use the window's assigned ID number to determine the location of its Window Descriptor within the array. The first Window Descriptor in the array corresponds to "window #0," which is a special graphics port that is reserved for FutureBasic's internal use. The next element in the array corresponds to window #1; the next to window #2; and so on. Array elements that don't correspond to the ID of any existing window have undefined contents.

If you define a wDescriptor record type as shown above, you can get a pointer to the Window Descriptor corresponding to window #windowID as follows:

wdPtr& = WNDBLK + (windowID * SIZEOF(wDescriptor))

Alternatively, you can use XREF to access the contents of the array using normal FutureBasic³ array syntax:

wdArray& = WNDBLK XREF wdArray AS wDescriptor

You can then use the syntax wdArray(windowID) to access an individual Window Descriptor.

Edit Field DescriptorsFutureBasic maintains an Edit Field Descriptor for each field that you create using the EDIT FIELD statement or the PICTURE FIELD statement. For each window, there is a linked list of Edit Field Descriptors for the fields in that window; a handle to the first descriptor in the list can be found in the efdHeadH& element of the Window Descriptor record. The structure of an Edit Field Desciptor is as follows:

BEGIN RECORD efDescriptor DIM nextDescH&<spacer type="horizontal" size="134">'Handle to next descriptor in list DIM indexRef%<spacer type="horizontal" size="141">'Field's ID number DIM fieldType``<spacer type="horizontal" size="126">'Field's type DIM jClass``'Text justification & class number DIM teH&<spacer type="horizontal" size="15">'Handle to TextEdit record END RECORD

The nextDescH& element is a handle to the next Edit Field Descriptor in the list. If nextDescH& is _nil, there are no more edit fields nor picture fields in this window.
The indexRef% element is the field's ID number, as assigned by the EDIT FIELD statement or the PICTURE FIELD statement.
The fieldType`` element is the same as the type parameter specified in the EDIT FIELD statement or the PICTURE FIELD statement (it defaults to _framedNoCR (1) if no type was explicitly specified).
The jClass`` element is the same as the efClass parameter specified in the EDIT FIELD statement, or the justparameter specified in the PICTURE FIELD statement. It defaults to zero if the parameter wasn't specified.
The teH& element is a handle to the field's TextEdit Record, which is a structure that the MacOS maintains for each open edit field. This is the same handle that is returned by the TEHANDLE(efID) function. Note that FutureBasic associates a TextEdit Record with picture fields as well as edit fields; you can use a picture field's TextEdit Record, for example, to determine the field's rectangle. See the <a href="http://developer.apple.com/documentation/mac/Text/Text-40.html">"TextEdit" chapter</a> of <a href="http://developer.apple.com/documentation/macos8/mac8.html">Inside Macintosh</a>: <a href="http://developer.apple.com/documentation/mac/Text/Text-2.html">Text</a> for more information.

Example

The following function returns a count of the number of edit fields and picture fields in a specified window. It assumes that the wDescriptor and efDescriptor record types have been defined as shown above.

LOCAL FN EfCount(wndID)
   DIM wdPtr AS POINTER TO wDescriptor
   DIM efdH AS HANDLE TO efDescriptor
   count = 0
   IF WINDOW(-wndID) = 0 <b>THEN EXIT FN '(no such window)
   wdPtr = WNDBLK + (wndID * SIZEOF(wDescriptor))
   efdH = wdPtr.efdHeadH&
   WHILE efdH <> _nil
<spacer type="horizontal" size="48">INC(count)
<spacer type="horizontal" size="48">efdH = efdH..nextDescH&
   WEND
END FN = count

Note

Window Descriptors are maintained only for windows that are created using the WINDOW statement, and Edit Field Descriptors are maintained only for edit fields/picture fields that are created using the EDIT FIELD or PICTURE FIELD statement. If you create a window or an edit field using a MacOS Toolbox routine (such as NewWindow or TENew), there will be no Descriptor associated with it.