Introduction
This tutorial is intended to be a practical introduction to developing software with the Application Resource Kit™ (ARK). It covers using ARK-based components in end-user applications, with code examples derived from the Params example source code which is available in both a C++/MFC version which is compatible with Microsoft Visual C++ 6, and a Visual Basic version which is compatible with Visual Basic 6. The source code examples are included in ARKsdk, which can be downloaded using the link below. Ports to other languages may be done in the future if there is interest. The excerpts in this tutorial are from the Visual Basic version, although it should be straightforward to locate the equivalent code in an implementation for another language.
Download ARKsdk
The tutorial now includes a reference guide that describes each interface and data type that is included in the ARK framework. The reference guide can be reached directly by clicking here.
Background
COM
ARK heavily relies on Microsoft's Component Object Model (COM). COM allows ARK to be integrated into many different Windows programming languages. Although it is extremely helpful to have a basic understanding of COM before getting into ARK, it should be possible to read this tutorial without this knowledge. That being said, the terms "class", "object", "interface", and "collection" are used frequently so it would be helpful to know what these terms mean.
A class is a user-defined data type that has a state and some operations.
An object is an instance of a class in the same way that a variable is an instance of a type. Objects are the actual entities that take up memory when a program is running to store their internal state, like ordinary variables do. In COM, how an object works (its class, or its implementation) is separate from what the object looks like (its interface). The term instantiation refers to creating an instance of an object from a particular class.
An interface defines the way in which an object exposes its services or functionality. Through an interface, an object exposes its content or data members via the interface's properties, and a subset of its internal operations or functions via the interface's methods. By separating the object's interface from its implementation, the internal behaviour of an object can change after a program is written and still be backwards-compatible as long as the interface remains constant.
A collection object contains a group of related objects, as an array does, but in a more flexible way. In ARK, all of the objects in a collection have the same interface or are of the same type.
Collection interfaces generally have two read-only properties, Count and Item. The Count property returns the number of objects in the collection, and Item is used to obtain a reference to an object in the collection by specifying an index. In most cases the index can either be an integer or a string, the string being the short name of the object (more on this later). It is also important to note that collections in ARK are 0-based, which means that the integer indexes range from 0 to Count - 1. The following example demonstrates the use of a collection called Libraries and the various short cuts that are possible with the Item property.
Private Sub CollectionTest_Click()
Dim myark As New ARK.Core ' More on this in the next section.
Dim i As Integer
' The following three lines of code print out the short names
' of all of the objects in the Libraries collection. (The
' .Name property belongs to the objects in the collection.)
Debug.Print "Test 1"
For i = 0 To myark.Libraries.Count - 1
Debug.Print myark.Libraries.Item(i).Name
Next i
' Because the Item property is the default property for the
' Libraries collection, the property name can be omitted as
' follows:
Debug.Print "Test 2"
For i = 0 To myark.Libraries.Count - 1
Debug.Print myark.Libraries(i).Name
Next i
' The following examples demonstrate the use of string indices
' in accessing the Libraries collection. Each line does the
' same thing.
Debug.Print "Test 3"
Debug.Print myark.Libraries.Item("GA3206").Name
Debug.Print myark.Libraries("GA3206").Name
Debug.Print myark.Libraries!GA3206.Name
' The following code demonstrates another feature of ARK
' collections (and most COM collections), the ability to
' iterate/index through the objects in the collection.
Debug.Print "Test 4"
Dim obj As ICatalogEntry
For Each obj In myark.Libraries
Debug.Print obj.Name
Next obj
End Sub
A COM DLL is a special type of DLL that contains implementations for one or more COM classes. A COM DLL may also contain a type library that describes the classes, interfaces, and types that are used in the DLL. COM DLLs are registered when they are installed, so that applications can locate the classes in the DLLs, and so that languages such as Visual Basic can know where to find the type library. An ARK-based component DLL implements one or more classes that expose the standard ARK interfaces, and when registered will identify itself as being an ARK-based component.
A finished program (EXE) can be written so that it is extensible by loading COM DLLs at run-time. This is the feature of COM that makes ARK possible. Compatible DLLs can be installed on a system after the finished program and expose interfaces that were known when the program was written. Programs can locate compatible DLLs by querying the Windows Registry.
To learn more about COM, the book Essential COM by Don Box, published by Addison-Wesley, is highly recommended.
Exception Handling
Exception handling in ARK is handled through the standard COM ISupportErrorInfo interface which is used by Visual Basic and other languages. This allows ARK error handling to integrate well with these languages. When an error occurs in one of the ARK methods, an exception is raised that can be caught with the usual VB error handling routines (On Error, etc.) and identified using the VB Err object. This is demonstrated in the example below. Generally, ARK exceptions include a descriptive error message that ends up in the Err.Description property. The error number, obtainable using the Err.Number property, is also useful in having the application respond appropriately to an exception that has been raised. Refer to the section on ARK Exceptions in the reference guide for the list of exceptions that can be raised by ARK methods, and a description of each. Consult the Visual Basic documentation for more information on handling exceptions in VB.
Private Sub ErrorHandlerTest_Click()
On Error GoTo HandleError
' Do something that might trigger an exception
Exit Sub
HandleError:
' Display a description of the error message in a message box.
MsgBox Err.Description, vbOKOnly Or vbExclamation, "Error"
End Sub
NEXT: Using the Core Component |
