Copyright (c) by Matthew S. Harris

Transcription

1 Documentation & How-To Didjiman's Forms Instance Manager Class For MS Access 2007 and Higher Version v

2 Copyright (c) by Matthew S. Harris Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front- Cover Texts, and no Back-Cover Texts. The Didjiman.com graphics, "Didjiman.com", and the name "Didjiman" are part of the original author's identity and may not be reproduced except as part of the original Copyright notices required by the GNU Free Documentation License, the GNU Lesser General Public License and GNU General Public License. A copy of the documentation license is included in the section entitled "GNU Free Documentation License" (page 67). This code and documentation is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. The Visual Basic for Applications (VBA) code in this document is licensed to you under the terms of the GNU Lesser General Public License (LGPL), which incorporates and extends the GNU General Public License (GPL). Copies of the GNU LGPL and GNU GPL are included in this document (pages 73 and 76, respectively). IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED IN THE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

3 Didjiman's Forms Instance Manager Class for MS Access 2007 and Higher Table of Contents Introduction... 5 Overview... 7 Methods & Properties of the Forms Instance Manager Class... 8 Private Class Data & Constants... 8 COUNT Property... 8 FINDFORM_MATCH Property... 9 ADD Method...10 ITEM Method...13 REMOVE Method...15 REMOVEBYREFERENCE Method...17 CLEAR Method...19 SETFOCUS Method...20 SETFOCUSBYREFERENCE Method...22 KEYTAG_EXISTS Method...24 FORMREFERENCE_EXISTS Method...26 GET_KEYTAG_FROM_FORMNAME Method...27 FINDFORMS Method...29 Putting the Forms Instance Manager Class to Work The Demonstration Database...32 The TEST_INSTANCEMGR Module The Main Form: FRM_MAIN The "Auto Add" Form: FRM_INSTANCE_AUTOADD The "Manual Add" Form: FRM_INSTANCE_MANUALADD The "Find Results" Form: FRM_INSTANCES_FOUND Creating a FORMSINSTANCEMANAGERCLASS Instance...37 Referring to Your FORMSINSTANCEMANAGERCLASS Instance...38 Creating Forms for Use With the Instance Manager...38 Mandatory Code for the Unload Event Optional Code for the Load Event ("Auto-Add" Form) Adding Forms to the Instance Manager...41 Removing Forms from the Instance Manager...42 Referencing a Form's Properties & Methods Via the Instance Manager...43 Iterating the Forms Instance Manager's Collection...44 Finding Groups of Forms With Similar Names...45 Code Listings Forms Instance Manager Class Code Listing...48 The TEST_INSTANCEMGR Module...56 The FRM_INSTANCE_AUTOADD Form Module...60 The FRM_INSTANCE_MANUALADD Form Module...63 The FRM_INSTANCES_FOUND Form Module...65 GNU Free Documentation License (FDL)... 67

4 Software Licenses GNU Lesser General Public License (LGPL)...73 GNU General Public License (GPL)...76 Copyright by Matthew S. Harris. All Rights Reserved. Page 4 of 83

5 Introduction The ability to create instanced forms has existed in MS Access' Visual Basic for Applications (VBA) at least since MS Access 95. Instanced forms potentially offer MS Office developers flexibility and options not available with standard forms. If you want to display, for example, multiple forms showing different search results, then you must create a separate form for each possible view, or accept the limitation of being able to show only one form of a particular type at a time. The need to have a dedicated form for each and every purpose tends to bloat the number of forms the developer must create and maintain. Instanced forms have the potential to enable a developer to use a single form, and create multiple instances of that form as needed for various purposes. Instanced forms in MS Office VBA, however, have a couple of significant drawbacks: NOTE This document assumes you are familiar with Visual Basic for Applications (VBA) -- its data types, syntax, and built-in objects and classes. This document is written exclusively from the point of view of the MS Access development environment. Instanced forms cannot be managed by the parent application's forms system. Each instance of a form has the same name, so tools provided in the parent application (such as the Forms collection) cannot distinguish between any given form instance and any other instance of the same form. The lifetime of an instanced form is limited to the lifetime of any variable holding a reference to the form instance. A form instance is unloaded as soon as the variable holding its reference goes out of scope. If you want to keep an instanced form open, you must either declare a global variable to hold the form reference, or use looping code to prevent procedures from ending and having the form reference go out of scope. Neither approach is satisfactory having large numbers of global variables is poor programming practice, and having multiple DoEvents loops increases overall code execution time. A review of currently available information from Internet postings indicates that many MS Access developers have given up on using instanced forms, finding them generally too difficult to implement because of their drawbacks. Unwilling to forego the benefits and flexibility inherent in the concept of instanced forms, Matthew S. Harris developed a VBA class object for these purposes: Control the lifespan of instanced forms Distinguish one instance from another Provide basic tools to manage a collection of instanced forms This document describes the third released version (v ) of the Forms Instance Manager Class, which is designed (and intended for use in) MS Access VBA. The Forms Instance Manager class object should be usable in any version of MS Office 2007 or higher, and usable in any MS Office application that implements instanced forms. Copyright by Matthew S. Harris. All Rights Reserved. Page 5 of 83

6 The following sections of this document cover these topics: Methods & Properties of the Forms Instance Manager Class the Forms Instance Manager object implements two properties and 11 methods. The class' methods enable you to add, remove and reference instanced forms. The class' methods also include some basic tools to help use the class and manage your collection of instanced forms. Putting the Forms Instance Manager to Work the Forms Instance Manager class object is distributed by Matthew S. Harris in an MS Access 2007 database format named Forms Instance Manager Class (v ).accdb. The database includes forms and code to demonstrate how to use the object class. Putting the Forms Instance Manager to Work (pg. 31) shows examples of using the class object's methods and how to accomplish common tasks such as adding or removing form instances, iterating the collection of instanced forms, and others. Documentation & Source Code Licenses This document, the source code in this document, and the source code contained in the Forms Instance Manager Class (v ).accdb database are released to you under one or more of the GNU licenses. Each pertinent GNU license is included in full at the end of this document. You agree to be bound by these license agreements at such time as you utilize the VBA source code, and/or distribute this or new versions of the code and/or this document. The next section provides an overview of the Forms Instance Manager Class. Copyright by Matthew S. Harris. All Rights Reserved. Page 6 of 83

7 Overview The Forms Instance Manager (FIM) is implemented as a class object, and is declared in a class module named FormsInstanceManagerClass. For the FIM to work correctly, any variable of the FIM class must have global scope. Refer to Putting the Forms Instance Manager to Work (page 31) for information on declaring and using a FIM class instance variable. The FIM encapsulates a standard VBA Collection data type as its only private data, and provides methods to ensure that the FIM collection is managed effectively for Form objects. Each instanced form in the FIM's collection has its Tag property set to a unique string value. This enables a form to provide a FIM reference to processes external to the form and to FIM. The unique string identifier stored in the form's Tag property is called the Key Tag for the form. You may choose your own Key Tag, or use FIM to generate unique Key Tags based on the form's name. The Forms Instance Manager class has these methods and properties: Count a read-only property. Returns the current count of instanced forms in the FIM. FindForm_Match a read-only property. Returns True or False depending on whether the last use of the FindForms method successfully found matching forms in FIM. Add this method adds an existing instanced form to the FIM. Note that the Add method will change the Tag property for the form being added. Item returns a reference to a specified form in FIM. You may specify a form with a string or a numeric index. Remove removes an instanced form from the FIM's collection. The form to be removed is specified by a string or a numeric index. If FIM is the only object holding a reference to the instanced form, the instanced form is automatically unloaded (destroyed). RemoveByReference also removes an instanced form from the FIM'S collection. The form to be removed is specified by a form reference. As with the Remove method, the form is unloaded if FIM is the only object holding a reference to the form. Clear removes all forms from FIM. Any form not referenced by another object is unloaded when removed from FIM. SetFocus assigns focus to a form in the collection. You may use either a string or a numeric index to specify a form in the FIM's collection.. SetFocusByReference assigns the focus to a form in the collection, using a reference to the form as an index. KeyTag_Exists returns True or False depending on whether a given string is found in FIM as a Key Tag string. FormReference_Exists returns True or False depending on whether a given form reference is found in FIM. Get_KeyTag_From_FormName returns a unique Key Tag string based on the form's name. For example, if a form is named "Foo", and that name already exists in FIM, then this method returns "Foo1", "Foo2" and so on as needed to produce a unique Key Tag. FindForms returns an array of form objects whose Key Tag matches a string pattern. Must be used in conjunction with the FindForm_Match property to determine whether the FindForms search found any matching forms. Now that you have a sense of the Forms Instance Manager Class' overall structure and features, the next section, Methods & Properties of the Forms Instance Manager Class, show you how each method works. The section after that, Putting the Forms Instance Manager Class To Work (page 31) provides examples of how to use the Forms Instance Manager Class methods, in the context of typical tasks. Copyright by Matthew S. Harris. All Rights Reserved. Page 7 of 83

8 Methods & Properties of the Forms Instance Manager Class This section describes each method and property of the Forms Instance Manager Class in detail. Each step of every method's code is explained, along with the design choices behind each method's coding. In Putting the Forms Instance Manager Class To Work (page 31), you will learn how to use these methods in your own code. Private Class Data & Constants The Forms Instance Manager declares two private data variables. The first private data variable is: Private MyForms As New Collection The MyForms variable holds the collection of instanced forms managed by the FIM class. The second private data variable is: Private IsMatch As Boolean The IsMatch variable is an internal flag indicating whether the last use of the FindForms method successfully found matching forms. The Forms Instance Manager declares 21 constants, all of which are used in error-reporting. Refer to the section Forms Instance Manager Class Code Listing (page 48) to see the constant declarations. FIM raises several runtime errors if its methods are used with incorrect or invalid arguments. The constants enable using the VBA Err object to raise runtime errors with meaningful text descriptions of the error. COUNT Property The Count property is read-only (there is no Let declaration), and returns the count of the private MyForms collection. The syntax for using the Count property is: object.count where object is any reference to an object of the FormsInstanceManagerClass type. This is the code for the Count property: 1 Property Get Count() As Long 2 Count = MyForms.Count 3 End Property Use the Count property to obtain the count of instanced forms currently in the FIM. Analysis of the COUNT Property Line 1 is the property declaration. Line 2 sets the return value of the FIM Count property as the value of the MyForms.Count method. Giving FIM its own Count property follows the rules of data encapsulation do not allow code outside an object to directly manipulate the object's data in any way. Copyright by Matthew S. Harris. All Rights Reserved. Page 8 of 83

9 FINDFORM_MATCH Property The FindForm_Match property is read-only. It returns True if the last use of the FindForms method successfully found forms whose Key Tag matched the search pattern, False otherwise. The FindForm_Match property is only useful immediately after a call to the FindForms method. The syntax for using the FindForm_Match property is: object.findform_match where object is any reference to an object of the FormsInstanceManagerClass type. This is the code for the FindForm_Match property: 1 Property Get FindForm_Match() As Boolean 2 FindForm_Match = IsMatch 3 End Property Use the FindForm_Match property to determine whether a call to the FindForms method successfully found any matches in the FIM collection (see pg. 29). Note that the value returned by the FindForm_Match property is only meaningful when used immediately after using the FindForms method. Analysis of the FINDFORM_MATCH Property Line 1 is the property declaration. Line 2 sets the return value of the FIM Count property as the value of the IsMatch private variable. Refer to the description of using the FindForms method on page 29 for more information on using the FindForm_Match property. Copyright by Matthew S. Harris. All Rights Reserved. Page 9 of 83

10 ADD Method The Add method enables you to add a form instance to the FIM. The syntax for using the Add method is: object.add formreference, keyvalue where object is any reference to an object of the FormsInstanceManagerClass type, formreference is a valid reference to a Form object, and keyvalue is a String unique to the FIM collection. The complete listing of the Add method's code is immediately below, followed by an analysis of the code. Line numbers have been added to make it easier to identify particular statements in the analysis of the code. 1 Public Sub Add(frmForm As Form, ByVal skeytag As String) 2 'add a new instance of a form to the collection. 3 'the form instance must be created prior to calling this method Const MethodName = "FormsInstanceManagerClass.Add -- " 7 8 skeytag = Trim(sKeyTag) 'no whitespace 9 10 'ensure that frmform is not Nothing 11 If frmform Is Nothing Then Err.Raise Err_Form_Nothing, MyClassName, MethodName & Err_Form_Nothing_msg 'ensure that frmform is unique 14 If Me.FormReference_Exists(frmForm) Then Err.Raise Err_Form_NotUnique, MyClassName, _ 15 MethodName & Err_Form_NotUnique_msg 'ensure that skeytag is not empty 18 If skeytag = "" Then Err.Raise Err_KeyTag_Empty, MyClassName, MethodName & Err_KeyTag_Empty_msg 'ensure that skeytag is unique 21 If Me.KeyTag_Exists(sKeyTag) Then Err.Raise Err_KeyTag_NotUnique, MyClassName, _ 22 MethodName & Err_KeyTag_NotUnique_msg 'okay, now we can actually add this new form 25 frmform.tag = skeytag 'set the skeytag argument into the form's Tag property. 26 MyForms.Add frmform, skeytag 27 End Sub Copyright by Matthew S. Harris. All Rights Reserved. Page 10 of 83

11 Analysis of the ADD Method Line 1 of the Add method is a public declaration. Notice that Add requires two arguments an object reference of type Form, and a String variable for the Key Tag. The Add method's arguments must meet these criteria: The argument frmform can be a reference to any form. frmform may not be Nothing (that is, uninitialized), and it may not duplicate any reference already in the FIM. The skeytag argument can be any valid string. skeytag may not be blank, and it may not duplicate any existing collection Key in the FIM. Line 6 declares a string constant identifying the method currently executing (Add). This constant is used to create informative error messages. (Lines 11, 14, 18, and 21.) Line 8 removes extraneous leading or trailing spaces from skeytag (and is the reason skeytag is passed by value). Line 11 raises a runtime error if the Add method has been passed a value of Nothing for the frmform argument. Line 14 also raises a runtime error, this time if the reference in frmform already exists in FIM. The FIM method FormReference_Exists is called to determine whether the frmform reference already exists. Line 18 raises a runtime error if the skeytag argument is an empty string, while line 21 raises a runtime error if the skeytag argument represents a string already in the FIM. The FIM method KeyTag_Exists is called to determine whether skeytag already exists. Because raising a runtime error halts code execution, we only get to lines 25 and 26 if the frmform and skeytag arguments pass their validation tests. Line 25 ensures that the Tag property of the form instance being added is the same as the skeytag. Why Raise Runtime Errors? The Forms Instance Manager is intended for use as a "black box" programming tool. It is therefore important to avoid any condition which might cause the code in the FIM to produce a runtime error with the error line inside the class module. Each method of the FIM therefore screens all of its inputs for validity, and then uses the built-in VBA Err object to raise a runtime error with an appropriate error description identifying the method and class object that raised the runtime error. With this technique, the locus of the runtime error will be in the user's code, and the programmer-user receives an explicit message as to what is wrong. This is much better than dumping the user somewhere inside the Forms Instance Manager's code and leaving the user to figure out why. In general, this is a preferred technique for any class object programming. ** CAUTION ** The Forms Instance Manager assumes it has exclusive use of the Tag property, and that no other processes will alter the form's Tag property. If any code changes the value of the Tag property, then synchronization between that form and FIM will be lost, with unpredictable results. Line 26 uses the Add method of the private Collection variable (named MyForms) to store the form reference from frmform. The frmform reference is used as the Item argument of the MyForms.Add method, and skeytag is used as the Key argument of MyForms.Add. Refer to the VBA Help system to learn more about the VBA Collection data type and its Add method. Copyright by Matthew S. Harris. All Rights Reserved. Page 11 of 83

12 Why Use the Form's Tag Property? The Forms Instance Manager's Add method requires the programmer to provide both a valid form reference, and a Key Tag value a unique string as an ID for the form. Further, the Add method writes the Key Tag value into the form's Tag property. One reason for this design choice is to propagate the interface of the base Collection object that FIM is built around. The base Collection object stores an item (a form reference in FIM's case) and, optionally, a unique string identifier for the item. The form's Key Tag ID string corresponds to the key argument used in the Collection object. (Refer to the VBA Help in MS Office for more information about the Collection object.) Another, more important reason, is that the Key Tag gives the form a unique identity, other than the form object reference. (As you recall, one of the drawbacks of instanced forms is their lack of inherent unique identifiers). By putting a unique string identifier in the form's Tag property, the form not only gains a unique identity, but an identity easily accessible through the form's properties for use by code processes external to the form and the Forms Instance Manager. Finally, a string identifier enables forms in FIM to be handled in groups by way of partial string matching. For example, if you instance several forms, and some of them have names such as "SalesJan", "SalesFeb" and so on, you can use the FindForms method to return an array of form objects whose Key Tag matches the pattern "Sales*" (see page 29). Alternatively, you may iterate the FIM's collection using an ordinal numeric index (1 through Count) and test the forms' Tag property for the substring "Sales" to identify all of the sales-related forms in FIM. Copyright by Matthew S. Harris. All Rights Reserved. Page 12 of 83

13 ITEM Method Like the Item method of any collection, the Forms Instance Manager's Item method enables you to reference a particular member of the collection. You may use either a numeric index or a string index to reference a member in the collection. The syntax for using the Item method is: object.item(index) where object is a variable of the FormsInstanceManagerClass type, and Index is either an integer or string value. The code listing below shows the Item method's code. 1 Public Function Item(ByVal Index As Variant) As Form 2 'return a Form object reference from this collection, specified by Index 3 'Index may not be empty 4 'Index must be an integer, a long integer, or a string data type 5 'If Index is an integer/long, it must be > 0 and <= Count 6 'if Index is a string, it must not be empty and must exist in the collection 7 8 Const MethodName = "FormsInstanceManagerClass.Item -- " 9 10 'Test Index for correct data type and range 11 If ((VarType(Index) = vbinteger) Or (VarType(Index) = vblong)) Then 12 'Index is integer/long -- ensure its value is in an appropriate range 13 If (Index <= 0) Or (Index > MyForms.Count) Then Err.Raise Err_Index_OutOfRange, _ 14 MyClassName, MethodName & Err_Index_OutOfRange_msg 15 ElseIf (VarType(Index) = vbstring) Then 'Index is a string 16 Index = Trim(Index) 'no whitespace 17 'ensure the Index string is not blank 18 If Index = "" Then Err.Raise Err_KeyTag_Empty, MyClassName, MethodName & Err_KeyTag_Empty_msg 19 'ensure the Index string exists as a key in our collection 20 If Not Me.KeyTag_Exists(CStr(Index)) Then Err.Raise Err_KeyTag_NotFound, _ 21 MyClassName, MethodName & Err_KeyTag_NotFound_msg 22 Else 'Index is not one of the data types required (integer, long, string) 23 Err.Raise Err_Invalid_Argument, MyClassName, MethodName & Err_Invalid_Argument_msg 24 End If 'now we can return the item 27 Set Item = MyForms(Index) 28 End Function Copyright by Matthew S. Harris. All Rights Reserved. Page 13 of 83

14 Analysis of the ITEM Method Line 1 contains the declaration of the Item method. Item is declared as a function, because it returns a Form object reference. Notice that the Index argument is passed by value, and that it is a Variant data type. The Variant type is used so that the Item method can receive either a numeric value as an index, or a string as an index. This way the Forms Instance Manager's Item method behaves, and can be used, the same as the Item method of any of the built-in collections of either VBA or the host application (e.g. MS Access). Note that the VBA programming environment does not enable creating default methods, so the FIM's Item method must always be used explicitly: object.item(index) Line 8 declares a constant to identify the currently executing FIM method for use in any runtime errors that may be raised. Collection Indexes In Visual Basic for Applications, the first element of all Collection data types is element 1. Lines 11 through 24 evaluate the data type and value of the Index argument by using the VBA function VarType to return the specific data type of the value in the Variant type and an If ElseIf decision-tree. Line 11 tests whether the Index argument is an Integer or Long data type. If so, line 13 executes, and tests whether the Index value is within an acceptable range. Collection objects in VBA are subscripted as 1-based arrays, so the Index argument cannot be 0 or a negative number. Line 13 also ensures that the Index argument is not greater than the number of elements in the collection. If the Index argument is not within the permissible range, line 13 raises a runtime error for "Index out of range." If the Index argument is not an integer, execution passes to line 15, which tests whether the Index argument contains a String data type. If the Index argument is a string, the Trim function is used to remove any leading or trailing spaces from the string (line 16). Line 18 tests whether the Index string is empty, raising a runtime error if it is. Next, line 20 uses the KeyTag_Exists function (part of the FIM object) to ensure that the Index string is in the FIM collection. It the Index string is not in the FIM collection of forms, line 20 raises a runtime error. Line 23 is executed if the Index argument is neither an Integer, Long, nor String data type, raising an "Invalid Argument" runtime error. Line 27 is executed only if the Index argument is an acceptable data type, and represents a value that will actually reference a member of the FIM's forms collection. Line 27 sets the return value of the Item method to the member of FIM's private collection (MyForms) subscripted by the validated Index value. Copyright by Matthew S. Harris. All Rights Reserved. Page 14 of 83

15 REMOVE Method Use the Remove method to delete a form from the Forms Instance Manager. Using the Remove method unloads (destroys) the form instance (assuming FIM is the only reference to the form). The Remove method is designed to behave the same way as the Remove method of any built-in Collection object. The syntax for using the Remove method is: object.remove Index where object is a variable of the FormsInstanceManagerClass type, and Index is either an integer or string value. Note that the Remove method is the preferred way to remove items from the Forms Instance Manager's collection. The RemoveByReference method (discussed next) involves more iterative code than the Remove method, and is intended only for circumstances where the correct ordinal or string index value is less readily available than a form reference. The code listing below shows the FIM Remove method's code. 1 Public Sub Remove(ByVal Index As Variant) 2 'remove a specified form instance from the collection, specified by its numeric index or string key tag. 3 'This is the preferred method of removing an instanced form 4 'Index may not be empty 5 'Index must be an integer, a long integer, or a string data type 6 'If Index is an integer/long, it must be > 0 and <= Count 7 'if Index is a string, it must not be empty and must exist in the collection 8 9 Const MethodName = "FormsInstanceManagerClass.Remove -- " 'Test Index for correct data type and range 12 If ((VarType(Index) = vbinteger) Or (VarType(Index) = vblong)) Then 13 'Index is integer/long -- ensure its value is in an appropriate range 14 If (Index <= 0) Or (Index > MyForms.Count) Then Err.Raise Err_Index_OutOfRange, _ 15 MyClassName, MethodName & Err_Index_OutOfRange_msg 16 ElseIf (VarType(Index) = vbstring) Then 'Index is a string 17 Index = Trim(Index) 'no whitespace 18 'ensure the Index string is not blank 19 If Index = "" Then Err.Raise Err_KeyTag_Empty, MyClassName, MethodName & Err_KeyTag_Empty_msg 20 'ensure the Index string exists as a key in our collection 21 If Not Me.KeyTag_Exists(CStr(Index)) Then Err.Raise Err_KeyTag_NotFound, MyClassName, _ 22 MethodName & Err_KeyTag_NotFound_msg 23 Else 'Index is not one of the data types required (integer, long, string) 24 Err.Raise Err_Invalid_Argument, MyClassName, MethodName & Err_Invalid_Argument_msg 25 End If 'okay, now we can remove it 28 MyForms.Remove Index 29 End Sub Copyright by Matthew S. Harris. All Rights Reserved. Page 15 of 83

16 Analysis of the REMOVE Method Line 1 contains the declaration of the Remove method. Notice that the Index argument is passed by value, and that it is a Variant data type. The Variant type is used so that the Remove method can receive either a numeric value or a string as an index. The Forms Instance Manager's Remove method behaves, and can be used, the same as the Remove method of any of the built-in collections of either VBA or the host application (e.g. MS Access). Line 9 declares a constant to identify the currently executing FIM method for use in any runtime errors that may be raised. Lines 12 through 25 evaluate the data type and value of the Index argument by using the VBA function VarType to return the specific data type of the value in the Variant type and an If ElseIf decision-tree. Line 12 tests whether the Index argument is an Integer or Long data type. If so, line 14 executes, and tests whether the Index value is within an acceptable range. Collection objects in VBA are subscripted as 1-based arrays, so the Index argument cannot be 0 or a negative number. Line 14 also ensures that the Index argument is not greater than the number of elements in the collection. If the Index argument is not within the permissible range, line 14 raises a runtime error for "Index out of range." If the Index argument is not an integer, execution passes to line 16, which tests whether the Index argument contains a String data type. If the Index argument is a string, the Trim function is used to remove any leading or trailing spaces from the string (line 17). Line 19 tests whether the Index string is empty, raising a runtime error if it is. Next, line 21 uses the KeyTag_Exists function (part of the FIM object) to ensure that the Index string is in the FIM collection. If the Index string is not in the FIM collection of forms, line 21 raises a runtime error. Line 24 is executed if the Index argument is neither an Integer, Long, nor String data type, raising an "Invalid Argument" runtime error. Line 28 is executed only when the Index argument is an acceptable data type, and represents a value that will actually reference a member of the FIM's forms collection. Line 28 uses the Remove method of FIM's private collection (MyForms) subscripted by the validated Index value to remove the specified form from the FIM collection. Why do the Item, Remove and some other methods have redundant code? You may have noticed that the Item method and the Remove method (and later you'll see the same code in the SetFocus method) contain identical code to evaluate the Index argument. Usually, good programming practice says that identical code segments should be placed into individual functions or procedures. In this case, because the redundant code raises runtime errors, there are a couple of good reasons to endure the redundant code. First, any procedure or function designed to perform the validation of the Index argument and produce a detailed error message will require that string variables be passed as arguments to the validation procedure. Pushing additional string data onto the calling stack increases code execution time, and we want our object's methods to have the lowest execution time reasonably possible. Second, generating the runtime errors in a validation procedure displaces the actual location of the runtime error out of the method where the runtime error occurs. This is likely to be confusing to anyone stepping through code execution with the VBA Debugger, because they will see the error raised in the validation procedure, instead of the method code where the error actually occurs. For these reasons, it is better to have identical testing blocks local to each method that requires validating the Index argument. Copyright by Matthew S. Harris. All Rights Reserved. Page 16 of 83

17 REMOVEBYREFERENCE Method The RemoveByReference method removes a form from the Forms Instance Manager's collection, based on a form reference value as the collection index.. Using the RemoveByReference method unloads (destroys) the form instance (assuming FIM is the only reference to the form). The syntax for using the RemoveByReference method is: object.removebyreference FormReference where object is a variable of the FormsInstanceManagerClass type, and FormReference is a reference to a Form object. The RemoveByReference method provides an alternative to the Remove method. Use the RemoveByReference method when a reference to the form you want to remove is more readily available than the form's ordinal or Key Tag index. In general, you should use the Remove method whenever possible, as the RemoveByReference method involves more iterative code and is therefore somewhat slower than the Remove method. The code listing below shows the FIM RemoveByReference method's code. 1 Public Sub RemoveByReference(frmForm As Form) 2 'remove a specified form instance from the collection, specified by the form reference 3 'this is an alternative method to remove forms from the collection 4 'frmform may not be nothing 5 'frmform must exist in the collection 6 7 Const MethodName = "FormsInstanceManagerClass.RemoveByReference -- " 8 9 Dim objform As Form 10 Dim idx As Long 'ensure that frmform is not Nothing 13 If frmform Is Nothing Then Err.Raise Err_Form_Nothing, MyClassName, MethodName & Err_Form_Nothing_msg 'ensure that the frmform reference exists in the collection 16 If Not Me.FormReference_Exists(frmForm) Then Err.Raise Err_Form_NotFound, _ 17 MyClassName, MethodName & Err_Form_NotFound_msg 'get the form's ordinal position 20 idx = 0 21 For Each objform In MyForms 22 idx = idx If frmform Is objform Then Exit For 'found it, no more work 24 Next 'okay, now we can remove the form 27 MyForms.Remove idx 'remove by ordinal number 28 End Sub Copyright by Matthew S. Harris. All Rights Reserved. Page 17 of 83

18 Analysis of the REMOVEBYREFERENCE Method Line 1 is the RemoveByReference method's declaration. Notice that it takes a single argument a reference to a Form object to specify which form to remove from the Forms Instance Manager's collection. Line 7 declares a constant to identify the currently executing FIM method for use in any runtime errors that may be raised. Lines 9 and 10 declare local variables needed to carry out the method's task. objform is a Form object used to iterate the entire collection of forms, and idx is a Long integer used to hold the numeric index of the form to be removed. Line 13 tests the frmform argument and raises a runtime error if it is Nothing. Line 16 uses the FormReference_Exists method of FIM to determine whether the form reference exists in the FIM collection, and raises a runtime error if it does not. Line 20 sets idx to an initial value of 0. Although numeric variables in VBA are created with a default value of 0, it is best practice to initialize any and all variables before use. Lines 21 through 24 are a For Each Next loop. This loop iterates the private collection (MyForms) to determine the numeric index of the form to be removed. Remember, this method only receives a form reference, and a Collection object can only be indexed with a numeric or string value, so RemoveByReference must determine the ordinal numeric index of the form reference before it can remove it from the private Collection object. Line 22 increments the value of idx. The first time through this loop, idx will have a value of 1, the second time through the loop it will have a value of 2, and so on. When the loop ends, idx contains the ordinal numeric index of the form to be removed. Line 23 uses the Is operator to compare the frmform argument's value to the current objform value in the MyForms collection. If the two form references are the same, an Exit For statement is executed to end the loop. At the time the loop ends, idx contains the numeric index of the form referenced by the frmform argument. Line 27 uses the Remove method inherent to the VBA Collection object (MyForms) to remove the form from the Forms Instance Manager. Copyright by Matthew S. Harris. All Rights Reserved. Page 18 of 83

19 CLEAR Method The Clear method removes all of the Forms Instance Manager's forms from the collection. The Clear method has no arguments. All forms in the FIM collection will be unloaded, provided FIM contains the only valid reference to all its form instances. The syntax for using the Clear method is: object.clear where object is a variable of the FormsInstanceManagerClass type. The code listing below shows the FIM Clear method's code. 1 Public Sub Clear() 2 'remove ALL forms from the managed collection. 3 Dim k As Long 4 5 With MyForms 6 For k =.Count To 1 Step -1 7.Remove k 8 Next 9 End With 10 End Sub Analysis of the CLEAR Method Line 1 is the declaration of the Clear method. Line 3 declares a Long integer variable k for use as a counter in a For Next loop. (Use of "k" as a loop-counting variable name is an ancient tradition "k" is more readable than "c", and enjoys the brevity of being a single-keystroke name for a frequently used variable, so it's "k" for "kount"!) Line 5 begins a With block referencing MyForms. Line 6 begins a For Next loop. Notice that this loop starts at the highest count of items in the MyForms collection, and counts down by 1 each loop iteration. Line 7 uses the MyForms collection's Remove method with k as the numeric index value. The effect of the For Next loop in lines 6-8 is to remove forms from the collection starting at the end of the collection and working back to the beginning of the list. Practical experience indicates this technique is the fastest and most reliable way of removing all elements from any Collection object. Line 8 closes the For Next loop, line 9 closes the With block, and line 10 is the end of the method code. Copyright by Matthew S. Harris. All Rights Reserved. Page 19 of 83

20 SETFOCUS Method Use the SetFocus method of the Forms Instance Manager to give the focus to a specified form in the collection. The syntax for using the SetFocus method is: object.setfocus Index where object is a variable of the FormsInstanceManagerClass type, and Index is either an integer or string value. Note that the following two lines of code have identical effect (fmanager is an initialized instance of FormsInstanceManagerClass type and "foo" is the Key Tag of a form in the collection): fmanager.item("foo").setfocus fmanager.setfocus "foo" The SetFocus method (in the second line above) is a slightly more terse means of moving focus to a specified form than referencing a form through the FIM Item method to call the form's own SetFocus method. (first line above). The code listing below shows the FIM SetFocus method's code. 1 Public Sub SetFocus(ByVal Index As Variant) 2 'make the form specified by Index have the focus by using the form's own SetFocus method 3 'Index may not be empty 4 'Index must be an integer, a long integer, or a string data type 5 'If Index is an integer/long, it must be > 0 and <= Count 6 'if Index is a string, it must not be empty and must exist in the collection 7 8 Const MethodName = "FormsInstanceManagerClass.SetFocus -- " 9 10 'Test Index for correct data type and range 11 If ((VarType(Index) = vbinteger) Or (VarType(Index) = vblong)) Then 12 'Index is integer/long -- ensure its value is in an appropriate range 13 If (Index <= 0) Or (Index > MyForms.Count) Then Err.Raise Err_Index_OutOfRange, _ 14 MyClassName, MethodName & Err_Index_OutOfRange_msg 15 ElseIf (VarType(Index) = vbstring) Then 'Index is a string 16 Index = Trim(Index) 'no whitespace 17 'ensure the Index string is not blank 18 If Index = "" Then Err.Raise Err_KeyTag_Empty, MyClassName, MethodName & Err_KeyTag_Empty_msg 19 'ensure the Index string exists as a key in our collection 20 If Not Me.KeyTag_Exists(CStr(Index)) Then Err.Raise Err_KeyTag_NotFound, _ 21 MyClassName, MethodName & Err_KeyTag_NotFound_msg 22 Else 'Index is not one of the data types required (integer, long, string) 23 Err.Raise Err_Invalid_Argument, MyClassName, MethodName & Err_Invalid_Argument_msg 24 End If 'now we can set focus 27 MyForms(Index).SetFocus 28 End Sub Copyright by Matthew S. Harris. All Rights Reserved. Page 20 of 83

21 Analysis of the SETFOCUS Method Line 1 is the declaration for the SetFocus method. Like the Item and Remove methods, the Index argument is a Variant data type, so that calling code may use either a numeric or string value to index the Forms Instance Manager's collection of forms. Line 8 declares a constant to identify the currently executing FIM method for use in any runtime errors that may be raised. Lines 11 through 24 validate the Index argument. The validation process is the same as that used in the Item and Remove methods. Refer to Analysis of the ITEM Method (page 14) for an explanation of how the Index argument is validated. Line 25 uses the private MyForms collection of the FIM to reference the indexed form, and calls the form's SetFocus method. Copyright by Matthew S. Harris. All Rights Reserved. Page 21 of 83

22 SETFOCUSBYREFERENCE Method The SetFocusByReference method sets the focus to a form in the Forms Instance Manager, indexed by the form's reference. The syntax for using the SetFocusByReference method is: object.setfocusbyreference FormReference where object is a variable of the FormsInstanceManagerClass type, and FormReference is a reference to a Form object. The SetFocusByReference method provides an alternative to the SetFocus method. Use the SetFocusByReference method when a reference to the form you want to set the focus to is more readily available than the form's ordinal or Key Tag index. In general, you should use the SetFocus method whenever possible, as the SetFocusByReference method involves more iterative code and is therefore somewhat slower than the SetFocus method. The code listing below shows the FIM SetFocusByReference method's code. 1 Public Sub SetFocusByReference(frmForm As Form) 2 'make the form specified by the frmform reference have the focus 3 'frmform may not be Nothing 4 'frmform must exist in the collection 5 6 Const MethodName = "FormsInstanceManagerClass.SetFocusByReference -- " 7 8 Dim objform As Form 9 Dim idx As Long 'ensure that frmform is not Nothing 12 If frmform Is Nothing Then Err.Raise Err_Form_Nothing, MyClassName, MethodName & Err_Form_Nothing_msg 'ensure that the frmform reference exists in the collection 15 If Not Me.FormReference_Exists(frmForm) Then Err.Raise Err_Form_NotFound, _ 16 MyClassName, MethodName & Err_Form_NotFound_msg 'get the form's ordinal position 19 idx = 0 20 For Each objform In MyForms 21 idx = idx If frmform Is objform Then Exit For 'found it, no more work 23 Next 'now we can set focus 26 MyForms(idx).SetFocus 27 End Sub Copyright by Matthew S. Harris. All Rights Reserved. Page 22 of 83

23 Analysis of the SETFOCUSBYREFERENCE Method Line 1 is the SetFocusByReference method's declaration. The method takes a single argument a reference to a Form object to specify which form to set the focus on. Line 6 declares a constant to identify the currently executing FIM method for use in any runtime errors that may be raised. Lines 8 and 9 declare the local variables needed to carry out the method's task. objform is a Form object used to iterate the entire collection of forms, and idx is a Long integer used to hold the numeric index of the form to move the focus to. Line 12 tests the frmform argument and raises a runtime error if it is Nothing. Line 15 uses the FormReference_Exists method of FIM to determine whether the form reference exists in the FIM collection, and raises a runtime error if it does not. Line 19 initializes the initial value for idx to 0. Lines 20 through 23 are a For Each Next loop. This loop iterates the private collection (MyForms) to determine the numeric index of the form to be removed. Remember, this method only receives a form reference, and a Collection object can only be indexed with a numeric or string value, so SetFocusByReference must determine the ordinal numeric index of the form reference before it can reference it in the private Collection object. Line 21 increments the value of idx. The first time through this loop, idx will have a value of 1, the second time through the loop it will have a value of 2, and so on. When the loop ends, idx will contain the ordinal numeric index of the form to be removed. Line 22 uses the Is operator to compare the frmform argument's value to the current objform value in the MyForms collection. If the two form references are the same, an Exit For statement is executed to end the loop. At the time the loop ends, idx contains the numeric index of the form referenced by the frmform argument. Line 26 uses the private MyForms collection of the FIM to reference the indexed form, and calls the form's SetFocus method. Copyright by Matthew S. Harris. All Rights Reserved. Page 23 of 83

24 KEYTAG_EXISTS Method The KeyTag_Exists function returns True if a specified string exists as a Key Tag value in the Forms Instance Manager's collection of forms, False if it does not. Use this method to determine whether any given string is valid to use as a Key Tag for other FIM methods such as Item, Remove, and SetFocus. The KeyTag_Exists method is used internally by several FIM methods as part of the code that checks the validity of index arguments. The syntax for using the KeyTag_Exists method is: object.keytag_exists(key) where object is a variable of the FormsInstanceManagerClass type, and key is a string value. The code listing below shows the FIM KeyTag_Exists method's code. 1 Public Function KeyTag_Exists(sKeyTag As String) As Boolean 2 'Returns True if the skeytag exists, false otherwise 3 Dim objform As Form 4 5 KeyTag_Exists = False 'presume the skeytag is not found 6 7 For Each objform In MyForms 8 If UCase(sKeyTag) = UCase(objForm.Tag) Then 9 KeyTag_Exists = True 10 Exit For 'found it, no more work 11 End If 12 Next 13 End Function Analysis of the KEYTAG_EXISTS Method Line 1 is the declaration of the KeyTag_Exists method. This method takes one argument skeytag, the string to be tested to see if it exists in the FIM's collection of forms. Line 3 declares a local variable, objform, which is a Form object used to iterate the entire collection of forms. To simplify the logic flow of this method's code, line 5 makes a return value assignment to KeyTag_Exists of False. The presumption behind this statement is that we will not find the skeytag in the private MyForms collection. This avoids any If Then Else branching code, which increases the readability of the code for humans, and slightly speeds execution of the method's code. Lines 7 through 12 are a For Each loop that iterates through the private MyForms collection of the Forms Instance Manager. Line 8 tests whether the skeytag is equal to the referenced form's Tag property (that is, the form referenced by objform as the For...Each loop iterates through the MyForms collection). The "=" comparison operator should be faster than the VBA StrComp function, but unlike StrComp, the comparison is always binary and therefore case-sensitive. Line 8 uses the VBA UCase function to ensure that comparison is being made between two upper-case strings. If the skeytag argument and the form's Tag property are the same, then lines 9 and 10 are executed. Copyright by Matthew S. Harris. All Rights Reserved. Page 24 of 83

25 Line 9 sets the return value of KeyTag_Exists to be True. Line 10 is an Exit For statement to terminate the loop and avoid unnecessary iterations. If the loop in lines 7-12 completes without the test in line 8 ever being True, then KeyTag_Exists returns False. If the test in line 8 is True, then KeyTag_Exists returns True. Copyright by Matthew S. Harris. All Rights Reserved. Page 25 of 83

26 FORMREFERENCE_EXISTS Method The FormReference_Exists function returns True if a specified form reference exists in the Forms Instance Manager's collection of forms, False if it does not. Use this method to determine whether any given form reference is valid for use as an index value for other FIM methods such as RemoveByReference, or SetFocusByReference. The FormReference_Exists method is used internally by several FIM methods as part of the code that checks the validity of index arguments. The syntax for using the FormReference_Exists method is: object.formreference_exists(formreference) where object is a variable of the FormsInstanceManagerClass type, and FormReference is a valid reference to a Form object. The code listing below shows the FIM FormReference_Exists method's code. 1 Public Function FormReference_Exists(frmForm As Form) As Boolean 2 'Returns True if the form reference exists, false otherwise 3 Dim objform As Form 4 5 FormReference_Exists = False 'presume it is not found 6 7 For Each objform In MyForms 8 If frmform Is objform Then 9 FormReference_Exists = True 10 Exit For 'found it, no more work 11 End If 12 Next 13 End Function Analysis of the FORMREFERENCE_EXISTS Method Line 1 is the declaration for the FormReference_Exists method. The method takes a single argument a reference to a Form object. Line 3 declares a local variable, objform, which is a Form object used to iterate the entire collection of forms. Like the KeyTag_Exists method, the logic flow of this method's code is simplified by assuming the form reference will not be found. Line 5 therefore assigns the return value FormReference_Exists of False. Lines 7 through 12 are a For Each loop that iterates through the private MyForms collection of the Forms Instance Manager. Line 8 uses the Is operator to test whether the form reference passed as an argument in frmform is the same as the objform reference in the current iteration of the loop. If the two form references are the same, then lines 9 and 10 are executed. Line 9 sets the return value of FormReference_Exists to be True. Line 10 is an Exit For statement to terminate the loop and avoid unnecessary iterations. If the loop in lines 7-12 completes without the test in line 8 ever being True, then FormReference_Exists returns False. If the test in line 8 is True, then FormReference_Exists returns True. Copyright by Matthew S. Harris. All Rights Reserved. Page 26 of 83

27 GET_KEYTAG_FROM_FORMNAME Method This method is not strictly essential to the tasks of managing the collection of instanced forms. It does, however offer a major convenience to programmers using the Forms Instance Manager it provides a means of generating unique Key Tag values based on a form's name. The Get_KeyTag_From_FormName method makes it possible to implement instanced forms that "automatically" add themselves to the Forms Instance Manager's collection, as shown in Creating Forms for Use With the Instance Manager (page 38). The syntax for using the Get_KeyTag_From_FormName method is: object.get_keytag_from_formname(formreference) where object is a variable of the FormsInstanceManagerClass type, and FormReference is a valid reference to a Form object. If a form instance of a given name has not yet been add to the FIM collection, Get_KeyTag_From_FormName will return the form name as the unique result. For example, if the form is named "SalesAgents", and no form named SalesAgents has yet been added to the FIM collection, then the return value of Get_KeyTag_From_FormName will be "SalesAgents". If the FIM already contains forms with a given name, then the return value of Get_KeyTag_From_FormName will be the form name with a numeric suffix. Continuing the example of a form named SalesAgents, for the second SalesAgents form the return value of Get_KeyTag_From_FormName will be "SalesAgents1", the third would be "SalesAgents2" and so on. The code listing below shows the FIM Get_KeyTag_From_FormName method's code. 1 Public Function Get_KeyTag_From_FormName(frmForm As Form) As String 2 'returns a string with a unique key tag value based on the form's name 3 'frmform may not be Nothing 4 5 Const MethodName = "FormsInstanceManagerClass.Get_KeyTag_From_FormName -- " 6 7 Dim s As String 8 Dim k As Long 9 10 'ensure that frmform is not Nothing 11 If frmform Is Nothing Then Err.Raise Err_Form_Nothing, MyClassName, MethodName & Err_Form_Nothing_msg s = frmform.name If Me.KeyTag_Exists(s) Then 16 'the base form name already exists as a key, need to build a unique name 17 k = 1 18 Do Until Not Me.KeyTag_Exists(s & k) 'loop for a name + count value that doesn't already exist 19 k = k Loop 21 Get_KeyTag_From_FormName = s & k 22 Else 23 'we can just use the base form name as-is 24 Get_KeyTag_From_FormName = s 25 End If 26 End Function Copyright by Matthew S. Harris. All Rights Reserved. Page 27 of 83

28 Analysis of the GET_KEYTAG_FROM_FORMNAME Method Line 1 is the declaration for the FormReference_Exists method. The method takes a single argument a reference to a Form object and returns a String. Line 5 declares a constant to identify the currently executing FIM method for use in any runtime errors that may be raised. Lines 7 and 8 declare a couple of "scratch" variables needed for the task a String variable, s, to hold various possible names as the method executes, and a Long variable, k, to hold various suffix numbers for the form name. Line 11 tests to ensure that the frmform argument is not Nothing, and raises a runtime error if it is Nothing. Line 13 initializes s as the name of the form referenced by frmform. This will be the first possible unique name for this method's return value. Line 15 uses the KeyTag_Exists method to determine whether the form name in s already exists in the FIM's collection of forms. If the form name does exist, then lines 17 through 21 are executed. Otherwise, line 24 is executed. Lines 17 through 21 carry out the task of adding an incremental number to the string in s, until a name is arrived at that does not already exist in the Forms Instance Manager's collection. Line 17 initializes the value of k to 1. Line 18 starts a Do Until loop. This loop will execute for as long as the name formed by the combination of s suffixed by k already exists in the FIM collection. When the loop ends, line 21 sets the return value of Get_KeyTag_From_FormName to be the combination of the form's name (in s) suffixed by the number in k. Line 24 executes when the test in line 15 indicates that the unmodified form name does not already exist in the FIM collection; the return value of Get_KeyTag_From_FormName is the form's unmodified name. Copyright by Matthew S. Harris. All Rights Reserved. Page 28 of 83

29 FINDFORMS Method The FindForms function returns a Variant containing an array of form references. Use the FindForms function to find all of the forms in the FIM collection whose Key Tag value matches a specific string pattern. The search for matching Key Tag values is case-insensitive. To determine whether the FindForms function has successfully found any matching forms, you must use the FindForm_Match property of the FIM collection (see pg. 9). The syntax for using the FindForms method is: object.findforms(stringpattern) where object is a variable of the FormsInstanceManagerClass type, and StringPattern is a string containing a pattern to be matched. The StringPattern argument should contain a pattern-matching string conforming to the rules for the VBA Like operator (* to represent any number of characters,? to represent any single character, # to represent numeric digits, and so on). Refer to the VBA online Help reference for more information about pattern-matching strings used with the Like operator. Why use a separate property to determine the success of the FindForms method? To determine whether FindForms has found any matching forms, you must use the FindForm_Match property. Although checking a separate property may seem awkward, it is much less awkward than requiring FIM users to write code to determine whether an array returned by FindForms has any elements. The original FIM developer (Matthew S Harris) chose to emulate the methodology used by the MS Access VBA FindFirst/FindNext commands. When using FindFirst, a programmer must check the value returned by the NoMatch function to determine whether any matching records were found. Similarly, programmers using FIM must check the FindForm_Match property to determine whether any matching forms were found by the FindForms method. The code listing below shows the FIM FindForms method's code. 1 Public Function FindForms(ByVal smatch As String) As Variant 2 'return a Variant containing an array of form references where Key Tag matches the pattern in smatch. 3 'smatch must contain at least 1 character. 4 'NOTE: user code must check the value of the FindForm_Match property to determine whether matches found. 5 'NOTE: this code presumes that the default zero-based array option is in effect. 6 7 Dim objform As Form 8 Dim frmarray() As Form 9 Dim ifound As Long 'ensure that smatch is at least 1 character, raise runtime error if not 12 If (Len(sMatch) < 1) Then Err.Raise Err_Invalid_Argument_String, MyClassName, _ 13 "FormsInstanceManagerClass.FindForms -- " & Err_Invalid_Argument_String_msg smatch = UCase(sMatch) 'convert strings to upper case so matching is not case sensitive 16 ifound = For Each objform In MyForms 18 If UCase(objForm.Tag) Like smatch Then 19 ifound = ifound ReDim Preserve frmarray(ifound) 21 Set frmarray(ifound) = objform 22 End If 23 Next Copyright by Matthew S. Harris. All Rights Reserved. Page 29 of 83

30 24 25 FindForms = frmarray 'set function return value 26 'set internal global flag to indicate whether or not matches were found 27 If ifound >= 0 Then IsMatch = True Else IsMatch = False 28 End Function Analysis of the FINDFORMS Method Line 1 is the declaration of the FindForms method. FindForms takes a single string argument (presumed to be a pattern-matching string for use with the VBA Like operator), and returns a Variant (which contains an array of form references). Refer to the VBA online Help for information on how pattern-matching strings for the Like operator are constructed. Notice that the smatch argument is explicitly declared as pass by value (ByVal) as the code in the FindForms method alters the argument. Line 7 declares the objform variable for use in a For Each loop iterating the FIM's private collection of Form references. Line 8 declares a local array of Form objects, which is filled during the execution of the FindForms method and is returned as the method's result. Line 9 declares a Long type variable. ifound is used as an index for frmarray() as it is populated. Line 12 checks that the smatch argument contains at least one character, and raises a runtime error if it does not. Line 15 converts the smatch argument to all upper-case using the VBA UCase function. All string comparisons in the FindForms method are performed using upper-case characters only, in order to make a case-insensitive search. This makes the method's code independent of any Option Compare settings which might affect the case-sensitivity of the string comparisons. Line 16 initializes the ifound variable used as an array index. ifound is initialized as -1 to simplify the code needed to re-dimension frmarray() and to determine whether any matching forms were found. Lines 17 through 23 contain a For Each loop that iterates the FIM collection of forms (MyForms). Line 18 contains an If Then statement that uses the VBA Like operator to determine whether the Tag property of a form matches the string-matching pattern in the smatch argument. Notice that the Tag property is converted to all upper-case (using the VBA UCase function) so that the comparison is guaranteed to be case insensitive. Lines 19 through 21 only execute if the test performed in line 18 is true. Line 19 increments the ifound array index. The first time this loop executes, ifound will be zero (0), which is the first element of a zero-based array. FIM code presumes that the default zero-based array numbering is in effect. Line 20 re-dimensions the array of forms, frmarray(), preserving any existing values. The first time this loop executes, ifound is zero (0), and frmarray() is dimensioned to have its first element with index 0. Line 21 assigns the form reference of the form in the loop's current iteration to the newly created frmarray() element. Line 25 assigns frmarray() as the FindForms returned result. Notice that, if no matching forms were found in the FIM collection, that an uninitialized array is returned as the function result. Line 27 contains an If Then statement that appropriately sets the internal global IsMatch variable, which is the source of the value returned by the FindForm_Match property (see pg. 9). IsMatch is set True if forms were found, False otherwise. ifound is initialized as -1 (line 16). ifound is incremented by 1 each time a matching form is found (line 16). Therefore, if ifound is 0 or greater, then at least one matching form has been found. Copyright by Matthew S. Harris. All Rights Reserved. Page 30 of 83

31 Putting the Forms Instance Manager Class to Work This section uses code from the demonstration database to illustrate practical uses of the Forms Instance Manager Class. The demonstration database for version v of the Forms Instance Manager Class is in a MS Access database file named Forms Instance Manager Class (v ).accdb and is available for download from The immediately following section, The Demonstration Database, describes the components of the demonstration database. The practical how-to sections begin on page 37. You will find sections on individual how-to topics: Creating forms for use with the Forms Instance Manager (page 38) Creating and referencing instances of the Forms Instance Manager class object (page 37) Adding and removing form instances with the Forms Instance Manager (page 38) Iterating the Forms Instance Manager's collection of forms (page 44) Accessing a form's properties and methods through the Forms Instance Manager (page 43) Finding groups of forms in the Forms Instance Manager (page 45) Notes on Multiple Instances of the Same Form Object One of the primary reasons to show multiple instances of the same Form object is to re-use a single form for multiple purposes. For example, you may have designed a form to show the results of a particular search operation, and want to use multiple instances of that form to show the results of searches using different search criteria. You will need to consider carefully whether to allow record additions and edits in multiple instances of the same form, and even whether you want the multiple forms bound to the same data source. If you have multiple instances of the same form, bound to the same data source, users may end up (even in a single-user application) editing records in more than one of your instanced forms. This may result in editing collisions and confusion for your users. In a worst-case situation, your users may end up losing records and/or over-writing data that they didn't intend to. For this reason, multiple instances of the same form should probably be set to prohibit additions and edits. Copyright by Matthew S. Harris. All Rights Reserved. Page 31 of 83

32 The Demonstration Database The Forms Instance Manager Class (v ).accdb is a MS Access 2007 database file format. It contains these items: The Forms Instance Manager's Class module (FormsInstanceManagerClass). A full listing of the class' source code is also found in Forms Instance Manager Class Code Listing (page 48) of this document. A module named test_instancemgr which contains code showing how to perform basic operations with the Forms Instance Manager, such as creating a class instance, adding and removing instanced forms in the manager, and other tasks. The TEST_INSTANCEMGR Module (page 56) contains the full source code of this module. A Main form to invoke routines from the test_instancemgr module and provide access to the documentation and licenses stored in the demo database. (Source code for this form is not contained in this document.) An "auto-add" form (frm_instance_autoadd) which demonstrates how to set up a form to automatically add itself to the Forms Instance Manager whenever an instance of the form is created. The FRM_INSTANCE_AUTOADD Form Module (page 60) contains the full source code listing. A "manual add" form (frm_instance_manualadd) to demonstrate how instanced forms are manually added with code to the Forms Instance Manager. The FRM_INSTANCE_MANUALADD Form Module (page 63) contains the full source code listing. A "find results" form (frm_instances_found) to demonstrate how to use the FindForms method. THE FRM_INSTANCES_FOUND FORM MODULE (page 65) contains the full source code listing. A single table (tbl_documentation) which has a single Attachment field containing this document and copies of the GNU Licenses under which this code is distributed. The next few sub-sections of this document provide an overview of the forms and test module used to demonstrate the Forms Instance Manager. Copyright by Matthew S. Harris. All Rights Reserved. Page 32 of 83

33 The TEST_INSTANCEMGR Module The test_instancemgr module contains a global declaration for an instance of the Forms Instance Manager Class object, and a few procedures used to provide examples of using the abilities of the FIM. Procedure test_manual_add shows how to create new form instances and add them to the FIM's collection of forms. Procedure test_autoadd shows how to use a form rigged to automatically add itself to the FIM's collection of forms. Procedure test_all executes both the manual and auto-add test procedures, and shows the basic technique for accessing a form's properties through the FIM. Procedure test_findforms shows how to use the FindForms method to find groups of forms in FIM that have similar names. The how-to sections (beginning on page 37) show specific procedures and code snippets from this and other modules in the demonstration database. The Main Form: FRM_MAIN The main form of the demonstration database (frm_main) is shown in the illustration at right. This form acts as a control panel for the demonstration code, and provides ready access to the documentation (this document) and license agreements under which the Forms Instance Manager is distributed. Run Code to Demonstrate "Auto-Add" Instanced Forms click this button to create three instances of the frm_instance_autoadd form and add them to the FIM's collection. Specifically, clicking this button executes the test_autoadd procedure in the test_instancemgr module. (Refer to the listing on page 56.) NOTE: You can click this button as many times as you like, each time three new form instances will be created. Run Code to Demonstrate Manually Added Instanced Forms click this button to create three instances of the frm_instance_manualadd form and add them to the FIM's collection. Specifically, clicking this button executes the test_manual_add procedure in the test_instancemgr module. (Refer to the listing on page 56.) NOTE: Clicking this button more than once will result in a runtime error the form instances are added to the FIM collection manually, each run of this test code uses the same names as the first run, the consequence being a "Key Tag is not unique" runtime error. Copyright by Matthew S. Harris. All Rights Reserved. Page 33 of 83

34 Run Code to Demonstrate FindForms Method click this button to execute a test of the FindForms method. Clicking this button executes the test_findforms procedure in the test_instancemanager module. (Refer to the listing on page 56.) Documentation & License Attachments double-click the attachment box to gain access to the documents attached to the demonstration database: a copy of this documentation, and a copy of the GNU licenses under which the program code is distributed. NOTE that this code is not in the public domain, but is licensed to users for free. The how-to sections (beginning on page 37) show specific procedures and code snippets from this and other modules in the demonstration database. The "Auto Add" Form: FRM_INSTANCE_AUTOADD The form named frm_instance_autoadd provides an example of how to configure a form so that each new instance of the form automatically adds itself to the Forms Instance Manager. It also contains examples of: The mandatory code for a form's Unload event-handler to maintain synchronization with the Forms Instance Manager The optional code for a form's Load event-handler to enable a form to add itself to the FIM Getting the count of forms in the FIM Iterating the FIM collection of forms Referencing and identifying forms in the manager How to code a form to close itself How to close all form instances The figure below shows an example of frm_instance_autoadd in View mode. (The figure below shows all of the form tabs after clicking first the Run Code to Demonstrate "Auto-Add" Instanced Forms button and then the Run Code to Demonstrate Manually Added Instanced Forms button on the demo's Main form.) Copyright by Matthew S. Harris. All Rights Reserved. Page 34 of 83

35 Controls on the frm_instance_autoadd form are: Form's Tag Property this label is updated by the form's Activate event-handler, and displays the contents of the form's Tag property. The Tag property contains the text key which identifies this instance in the Forms Instance Manager. (The sample code sets the instance's Caption property to match its Tag property.) List of Instanced Forms in the Manager this Listbox shows all of the Tag values (that is, custom form names) in the FIM's collection. The Listbox control is populated by a procedure named populate_instancelist which is called from the form's Activate event-handler. The populate_instancelist procedure provides an example of how to iterate the contents of the Forms Instance Manager. Show Count of Forms in the Manager uses the built-in MsgBox procedure to display the current count of forms in the FIM, obtained from the Forms Instance Manager's Count property. Close This Form via Instance Manager uses FIM to close the current form instance, providing an example of how to use the RemoveByReference method, and of how to have an instanced form close itself. Close All Instanced Forms uses the FIM Clear method to close all open form instances. Open Search Form displays the Search Results dialog form. Change Focus to Selected Form uses the FIM SetFocus method to move the focus to an instanced form which the user has selected in the list of instanced forms. Refresh List Refreshes the contents of the Listbox control. A complete listing of the code for frm_instance_autoadd begins on page 60, The FRM_INSTANCE_AUTOADD Form Module. Copyright by Matthew S. Harris. All Rights Reserved. Page 35 of 83

36 The "Manual Add" Form: FRM_INSTANCE_MANUALADD The form named frm_instance_manualadd provides an example of a form intended to be manually added to the Forms Instance Manager's collection when a new instance of the form is created. The "Manual Add" form is identical to the "Auto Add" form, except that it does not have a Load event-handler. See the preceding section for a description of the controls on frm_instance_manualadd. The figure below shows an example of frm_instance_manualadd in View mode. (The figure below shows all of the form tabs after clicking first the Run Code to Demonstrate "Auto-Add" Instanced Forms button and then the Run Code to Demonstrate Manually Added Instanced Forms button on the demo's Main form.) A complete listing of the code for frm_instance_manualadd begins on page 63, The FRM_INSTANCE_MANUALADD Form Module. Copyright by Matthew S. Harris. All Rights Reserved. Page 36 of 83

37 The "Find Results" Form: FRM_INSTANCES_FOUND The form named frm_instances_found is a popup/modal form, and provides an example of how to use the FindForms method. You can display the frm_instances_found form by clicking the Run Code to Demonstrate FindForms Method button on the main form. The figure below shows an example of the frm_instances_found form in View mode. Click the Perform A New Search button to test additional matching patterns. Click the Close button to close the frm_instances_found form. A complete listing of the code for frm_instances_found begins on page 65, The FRM_INSTANCES_FOUND Form Module. Creating a FORMSINSTANCEMANAGERCLASS Instance To create a usable instance of the Forms Instance Manager Class object, you must have a declaration in a regular module (not a form or class module) with the following syntax Public Name As New FormsInstanceManagerClass where Name is any valid variable name. For example, the test_instancemgr module of the demo package contains the following declaration to create its class instance: Public frmmanager As New FormsInstanceManagerClass Your instance of the FIM class object must be global in scope to your application. If your instance of the FIM class object goes out of scope, all of the forms it manages will be closed! Copyright by Matthew S. Harris. All Rights Reserved. Page 37 of 83