Introduction  |  Core Component  |  Communications  |  Additional Topics  |  Reference Guide

---

Using the Core Component

The ARK Core Component is the central piece of the ARK framework. ARK-based applications may be distributed with entirely different sets of controller components and product component libraries (for more on these read the subsequent sections or the ARK White Paper), but ARK-based applications all must include the Core Component.

The first thing that an ARK-based application does when starting up is access the Core Component through an interface called ARK.ICore, which is exposed by a class called ARK.Core2. The word "ARK" in ARK.Core2 is the library name for the ARK Core Component, and "Core2" is the name of the new implementation of the core class in ARK 2. ARK 2 is the umbrella term that applies to all of the components built with ARKaid 2.0.0 or newer, or ARKonline. ARK.Core2 contains two collection classes that provide a list of the controller components and a list of the product component libraries that are installed on the system. The most noticeable improvement in ARK.Core2 is that the method used to register components during installation and query the system registry for installed components is much faster. This method does not detect components created with ARK 1, but the previous version of ARK.Core is also included for backwards compatibility. Internally, the Core Component also manages many of the common classes and objects that are often used by controller and product components, and ARK-based applications, but this is invisible to the application developer.

The Starting Point: Getting a reference to the Core Component

The first thing that the developer has to do in a new ARK-based Visual Basic application is to select the ARK type library as a reference, as is done with other COM components. To do this, select Project->References... from the menu bar. When the dialog box appears, check the box next to "ARK 1.0 Type Library" and click OK. This causes Visual Basic to load in all of the standard ARK class, interface, and type definitions. The type library can be viewed in the Object Browser by pressing F2 and selecting "ARK" in the upper left drop-down list box that should initially contain "<All Libraries>".

Next, declare a global reference to the ARK.ICore interface by putting the following line in the declarations section of the form code, outside of any function or subroutine:

Dim m_ark as ARK.ICore

This reference does not actually create an instance of the ARK.Core2 class; it is just an empty reference to the ARK.ICore interface (The I in ICore stands for interface). To actually create the object, add the following line to the Form_Load procedure:

Private Sub Form_Load()
    Set m_ark = New ARK.Core2
End Sub

To make sure that the object is unloaded properly when the program exits, it is necessary to explicitly unload it in the Form_Unload subroutine as follows:

Private Sub Form_Unload(Cancel As Integer)
    Set m_ark = Nothing
End Sub

This should be done for all objects that were created in the application.

There are other ways to get a reference to the Core Component in Visual Basic, but this is the most generic, and probably most similar to the way that the same task would be accomplished in other programming languages. Another example of how to create a new instance of ARK.Core2 in VB is shown in the following example:

Private Sub ARKRefTest_Click()
    Dim myark As New ARK.Core2
End Sub

This syntax is possible because ARK.ICore is defined as the default interface to ARK.Core2 in the type library. In this case, specifying the interface name explicitly is not required.

The Catalogs
The Core Component contains three properties that are exposed to application developers. The first is Version, a read-only string property that contains the version of the Core Component and the date on which it was released. The other two properties return the Programmers collection and the Libraries collection. The Programmers collection automatically loads a list of installed controller components when the ARK.Core2 object is created. Similarly, the Libraries collection automatically loads a list of installed product component libraries. These two collections are called catalog collections because they provide catalogs of available components.

Catalog collections contain CatalogEntry objects that are accessed through the ICatalogEntry2 interface. The ICatalogEntry2 interface is fully described in the reference guide. The interface contains properties that can be used to identify the component (Name, Title, and LibraryID) and its creator (ManID). To actually instantiate the component and load the DLL, the CreateObject method is used. The following excerpts from the Params example source code demonstrate how the Catalog collections can be used to populate drop-down list boxes that allow the user to choose which components they want to use.

First is the Form_Load subroutine that initializes the list boxes.

Private Sub Form_Load()
    Dim i As Integer
    On Error GoTo HandleError
    m_LastParameterMap = ""
    m_LastProgChoice = -1
    m_LastLibChoice = -1
    m_LastOp = OP_CLOSE
    ' Instantiate the core component
    Set m_Core = New ARK.Core2
    ' Fill in the programmers drop-down list box
    For i = 0 To m_Core.Programmers.Count - 1
        cmbProgrammers.AddItem m_Core.Programmers(i).Title
        cmbProgrammers.ItemData(cmbProgrammers.NewIndex) = i
    Next i
    If cmbProgrammers.ListCount > 0 Then cmbProgrammers.ListIndex = 0
    ' Fill in the libraries drop-down list box
    For i = 0 To m_Core.Libraries.Count - 1
        cmbLibraries.AddItem m_Core.Libraries(i).Title
        cmbLibraries.ItemData(cmbLibraries.NewIndex) = i
    Next i
    If cmbLibraries.ListCount > 0 Then cmbLibraries.ListIndex = 0
    UpdateState OP_CLOSE
    Exit Sub
HandleError:
    MsgBox Err.Description, vbOKOnly Or vbExclamation, "Error"
End Sub

The purpose of the UpdateState subroutine is explained in the section on "Communication and Parameter Mapping".

When an item is selected from the Programmer drop-down list box, the following event is triggered.

Private Sub cmbProgrammers_Click()
    On Error GoTo HandleError
    With cmbProgrammers
        Set m_Prog = m_Core.Programmers(.ItemData(.ListIndex)).CreateObject
        m_LastProgChoice = .ListIndex
    End With
    Exit Sub
HandleError:
    MsgBox Err.Description, vbOKOnly Or vbExclamation, "Error"
    cmbProgrammers.ListIndex = m_LastProgChoice
End Sub

Similarly, the following event is triggered when an item is selected from the Library list box.

Private Sub cmbLibraries_Click()
    Dim i As Integer
    On Error GoTo HandleError
    With cmbLibraries
        Set m_Lib = m_Core.Libraries(.ItemData(.ListIndex)).CreateObject
        m_LastLibChoice = .ListIndex
    End With
    ' Refill the products drop-down list box
    cmbProducts.Clear
    For i = 0 To m_Lib.Products.Count - 1
        cmbProducts.AddItem m_Lib.Products(i).Title
        cmbProducts.ItemData(cmbProducts.NewIndex) = i
    Next i
    If cmbProducts.ListCount > 0 Then cmbProducts.ListIndex = 0
    Exit Sub
HandleError:
    MsgBox Err.Description, vbOKOnly Or vbExclamation, "Error"
    cmbLibraries.ListIndex = m_LastLibChoice
End Sub

This event is slightly more complicated than cmbProgrammers_Click because it is also responsible for filling the Product list box. Product component libraries contain one or more products, so once a library is selected the user then has to select a product from within the library. The event that responds when an item is selected from the Product list is listed and described in the section entitled "Additional Topics".

IMPORTANT NOTE: It is not recommended that the fitting software user be permitted to choose from all of the controller components or product component libraries installed on his/her system. It is likely that components installed by other manufacturers are also present. For controller components, it is recommended that fitting software only allow the user to choose from the components that are distributed along with the fitting software, possibly by hard-coding in the names of the controller components. For product component libraries, it is recommended that the fitting software use the ManID property of the catalog entries to ensure that only libraries created by the appropriate manufacturer are made available. In most hybrids, the ManID can be stored in the hybrid itself. In PARAGON DIGITAL, the ManID, LibraryID and ProductID can be stored (refer to the section on PARAGON Special Features.

In the Form_Unload subroutine, global variables that point to objects, such as m_Prog and m_Lib, are set to Nothing. This explicitly releases the reference to the components and is considered to be good practice.

---

NEXT: Communications