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.
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.
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 TypeThe 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:
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 TypeIn 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 = 54Many 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 TypeHere, 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: vbapi@vbapi.com Send Encrypted E-Mail
This page is at http://www.vb-world.net/articles/intro/part04.html