Public Function GetRootsOfFilterMatches(reqID As Long) As HierarchySupportList

' Get requirements that match or have descendents that match a filter
' Determine if a member of the list matches the filter


'###############################################################
' This example shows the use of the IHierarchyFilter to determine
' which sub-trees under a specific requirement contain at least
' one requirement that matches the filter.
'
' The example runs on a requirement tree with the requirements below.
' Each requirement has as ParentID the ID of the requirement one step
' above according to the numbers that are part of the name.
' For example, the ParentID of Grandson 1.1.1 is the ID of Child 1.1,
' and the ParentID of Grandson 1.4.1.1 is the ID of Son 1.4.1

' The first item, Req1, is the root of the search tree. The
' ReqID argument to this example is Req1.ID
'
' The filter is:
'    Requirement.Name = "*Son* OR SubNode*" AND
'    Requirement.Product = "Emma OR 'Mansfield Park'"
' The items that match the filter in the example are marked with
' an asterisk.
'----------------------------------------------------------------------------
'    Name               | Description              | Priority     | Product
'----------------------------------------------------------------------------
'    Req1               | Root of search tree      | 2-Medium    | Persuasion
'    Child 1.1          | Child 1 of Req1          | 5-Urgent    | Persuasion
' *  Grandson 1.1.1     | GrandSon of Req1 1.1.1   | 2-Medium    | Emma
' *  Grandson 1.1.2     | GrandSon of Req1 1.1.2   | 2-Medium     | Emma

'    Child 1.2          | Child 2 of Req1          | 4-Very High | Mansfield Park
' *  Grandson 1.2.1     | GrandSon of Req1 1.2.1   | 5-Urgent    | Emma
'
'    Child 1.3          | Child 3 of Req1          | 3-High      | Persuasion
'    Child 1.3.1        | Grandchild of Req1 1.3.1 | 2-Medium    | Emma
'    Child 1.3.1.1      | GreatGrandChild of Req1 1.3.1.1
'            | 2-Medium    | Mansfield Park
' *  GGGrndSon1.3.1.1.1 | Has Son in name          | 2-Medium    | Mansfield Park
'
'    Child 1.4          | Child 4 of Req1          | 2-Medium    | Northanger Abbey
'    Son 1.4.1          | GrandChild Req1          | 3-High      | Persuasion
'    Grandson 1.4.1.1   | Grandson of Req 1.4      | 5-Urgent    | Persuasion
'    Son 1.4.2          | Son 2 of Req 1.4         | 5-Urgent    | Persuasion
'
' *  Son 1.5            |Child 5 of Req1           | 3-High      |Emma


    Dim reqF As ReqFactory
    Dim hierFilter As HierarchyFilter
    Dim reqHierL As HierarchySupportList, reqL As List
    Dim rq As Req
    
    On Error GoTo GetHListErr
    'tdc is the global TDConnection object.
    Set reqF = tdc.ReqFactory
    Set hierFilter = reqF.Filter

    '  Get the parent nodes by setting KeepHierarchical = True.
    '  Note that this setting is required to get
    '  a HierarchySupportList. If KeepHierarchical
    '  is False or not set, HierarchyFilter.NewList
    '  returns a List, not a HierarchySupportList.
    hierFilter.KeepHierarchical = True
 

    ' Set a filter on RQ_FATHER_ID.
    ' The subtree with that node as its root
    ' is searched. The returned requirements are
    ' the direct children of the RQ_FATHER_ID node
    ' that either match the filter, or have descendants
    ' that match the  filter.
    ' Search in the subtree starting at the node passed
    ' as a parameter to this routine.
    hierFilter("RQ_FATHER_ID") = reqID


    ' Name filter matches "Son", "GrandSon", and "SubNode."
    hierFilter("RQ_REQ_NAME") = "*Son* OR SubNode*"
    
    ' Set the product condition to a condition that matches some requirements.
    hierFilter("RQ_REQ_PRODUCT") = "Emma OR 'Mansfield Park'"
   

    
    'Set the order of the results.
    hierFilter.order("RQ_REQ_PRODUCT") = 1
    hierFilter.order("RQ_REQ_PRIORITY") = 2
    
    Set reqHierL = hierFilter.NewList
    
    Debug.Print "Number of records found is " & CStr(reqHierL.Count)
    'Number of records found is 4
    
    ' Note that there are 5 requirements that match the filter.
    ' The 4 that are returned are the direct children of the searched
    ' root node that have at least one match in the sub-tree of which they
    ' are the root. The number of matching descendents does not affect the result.
    '
    ' Son 1.5 has no descendents that match the filter, but Son 1.5
    ' itself matches the filter. Since Son 1.5 matches the filter, IsInFilter is True.
    
    Dim i%
    For i = 1 To reqHierL.Count
        Set rq = reqHierL(i)
        With rq
            Debug.Print .name & " is in list = " & CStr(reqHierL.IsInFilter(i))
            Debug.Print "   " & .Product & ", " & .comment & ", " & .Priority
            ' Son 1.5 is in list = True
            '     Emma, Child 5 of Req1, 3-High
            ' Child 1.2 is in list = False
            '     Mansfield Park, Child 2 of Req1, 4-Very High
            ' Child 1.3 is in list = False
            '     Persuasion, Child 3 of Req1, 3-High
            ' Child 1.1 is in list = False
            '     Persuasion, Child 1 of Req1, 5-Urgent
        End With
    Next i

    Set GetRootsOfFilterMatches = reqHierL

Exit Function
GetHListErr:
    On Error Resume Next
    Set GetRootsOfFilterMatches = Null
End Function