Index of refc

---

Introduction

This page begins the discussion of another key component of the Windows API: the structure. Structures allow a function to receive or return a large amount of information without cluttering the argument list. Structures almost always group related information, allowing related data to remain in a single package. The usage of structures is important in the more complex (and therefore more useful) API functions.

Structure Fundamentals

A structure is an object used in programming to group multiple related variables. A structure consists solely of one or more individual variables having any data type (including that of another structure). To use a structure, create a variable having that structure as its data type. This structure variable now has one of each member of the structure inside of it. Usually these data members store information about a related thing.

Structures in Visual Basic

To define a structure in Visual Basic, the Type block is used. Structure definitions can only appear in the (declarations) section of a form or module. The Type block has the following syntax:

[(Public | Private}] Type type_name   member1 As data_type1   member2 As data_type2   ... End Type

The Public/Private indicator works the same way as it does for functions. Structures are public unless otherwise specified. The following list identifies the various components of the Type block:

type_name

The name to give the structure. This name will then be used as the data type of whatever variables you want to use the structure.

member1, member2, ...

The name of an individual member of the structure. These are effectively variables stored in the structure.

data_type1, data_type2, ...

The data type of a particular item in the structure. Valid types include the Byte, Integer, Long, and String data types. This could also be another structure (although of course not the one being defined). This could also be a fixed-length string, having the data type of String * numchars, where numchars is the size in characters of the fixed-length string.

For example, consider the following hypothetical structure:

Type EXAMPLESTRUCT   longvar As Long   another As Long   s As String   fixed As String * 24   astruct As RECT End Type

In this example, the structure has five data members. longvar and another are both 32-bit integers. s is a regular string, but fixed is a string which has a fixed length of 24 characters. astruct is a variable of the RECT structure type.

To access a data member of the structure (after you have defined a variable to use the structure), simply use the . (period) operator between the variable name and the member name. Apart from that, the data members inside the variable can be treated exactly as a regular variable. For example, all of the following code is perfectly valid:

Dim ex As EXAMPLESTRUCT  ' ex is the structure ex.longvar = 54 ex.another = ex.longvar * 65 - 9 ex.s = "This is a sample string." ex.fixed = "Fixed-length string."  ' this will be right-padded with spaces Debug.Print ex.fixed ex.astruct.left = 54

API Structures

Many functions in the Windows API use structures as one or more of their arguments. This allows large amounts of related information to be passed to and from the function relatively easily. Although some structures are used by dozens of different functions, you cannot link to a structure in any of the API DLL files. Instead, you must define any API structures you use yourself in your program. Naturally, you must use the exact same definition of the structure in your code, or else fatal errors are likely to appear. For example, if you wish to use the RECT structure in your program, the following definition must also appear in your program:

Type RECT   left As Long   top As Long   right As Long   bottom As Long End Type

Here, the RECT structure provides a convenient way to keep the necessary coordinates of a rectangle grouped together. Each member of this particular structure holds one component of one of the two coordinate pairs used to identify the rectangle. Without this structure, four individual variables would be necessary to hold the same information. This structure is commonly used in graphics API routines.

Still not convinced about the usefulness of structures? This example taken from the API should be able to persuade you. There are two functions that create a font object: CreateFont and CreateFontIndirect. Both take identical information and perform the same operations to create the desired font. However, one accepts a LOGFONT structure to receive all the necessary information, whereas the other needs each member of the structure to be passed individually. Below are the declarations for each function.

Declare Function CreateFontIndirect Lib "gdi32.dll" Alias "CreateFontIndirectA" (lplf As LOGFONT) As Long

Declare Function CreateFont Lib "gdi32.dll" Alias "CreateFontA" (ByVal nHeight As Long, ByVal nWidth As Long, ByVal nEscapement As Long, ByVal nOrientation As Long, ByVal fnWeight As Long, ByVal fdwItalic As Long, ByVal fdwUnderline As Long, ByVal fdwStrikeOut As Long, ByVal fdwCharSet As Long, ByVal fdwOutputPrecision As Long, ByVal fdwClipPrecision As Long, ByVal fdwQuality As Long, ByVal fdwPitchAndFamily As Long, ByVal lpszFace As String) As Long

Clearly, the use of structures greatly simplifies the use of some functions, especially when large amounts of information need to be passed to or from the function. Notice that when a structure is passed to a function, it is always passed ByRef. Structures are generally easy to use in the API and should not cause any great problem using them.

<< Back to Part 3 | Contents of Introduction | Forward to Part 5 >>

Go back to the Articles section index.
Go back to the Windows API Guide home page.

---

Last Modified: January 15, 2000
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000
Go back to the Windows API Guide home page.
E-mail: [e-mail] Send Encrypted E-Mail
This page is at http://www.vb-world.net/articles/intro/part04.html