Cache full schematic sheet list sorted by sheet page number.

The sheet list is returned as a copy of the cached list rather than a
reference to prevent external code from changing the list.  While not as
performant, it eliminates the risk of the sheet list being altered in
ways that could break the schematic.  The sheet list should only be
updated by calling SCHEMATIC::RefreshHierarchy() when any appropriate
sheet changes are made.

Note to developers: there is something inherently different about how the
QA tests are loading and handling schematics versus the schematic editor.
Using the cached sheet list for the SCHEMATIC object will cause some QA
test to fail.  This is why SCHEMATIC::Hierarchy() has not replaced
SCHEMATIC::BuildSheetListSortedByPageNumbers() everywhere.

eeschema/annotate.cpp

@@ -1,7 +1,7 @@
 /*
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
- * Copyright (C) 2004-2023 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2004-2023, 2024 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -39,7 +39,7 @@
 void SCH_EDIT_FRAME::mapExistingAnnotation( std::map<wxString, wxString>& aMap )
 {
     SCH_REFERENCE_LIST references;
-    Schematic().BuildUnorderedSheetList().GetSymbols( references );
+    Schematic().Hierarchy().GetSymbols( references );
 
     for( size_t i = 0; i < references.GetCount(); i++ )
     {
@@ -61,7 +61,7 @@ void SCH_EDIT_FRAME::DeleteAnnotation( ANNOTATE_SCOPE_T aAnnotateScope, bool aRe
                                        REPORTER& aReporter )
 {
 
-    SCH_SHEET_LIST sheets = Schematic().BuildUnorderedSheetList();
+    SCH_SHEET_LIST sheets = Schematic().Hierarchy();
     SCH_SCREEN*    screen = GetScreen();
     SCH_SHEET_PATH currentSheet = GetCurrentSheet();
     SCH_COMMIT     commit( this );
@@ -219,7 +219,7 @@ void SCH_EDIT_FRAME::AnnotateSymbols( SCH_COMMIT* aCommit, ANNOTATE_SCOPE_T  aAn
 
     SCH_REFERENCE_LIST references;
     SCH_SCREENS        screens( Schematic().Root() );
-    SCH_SHEET_LIST     sheets = Schematic().BuildSheetListSortedByPageNumbers();
+    SCH_SHEET_LIST     sheets = Schematic().Hierarchy();
     SCH_SHEET_PATH     currentSheet = GetCurrentSheet();
 
 
@@ -463,7 +463,7 @@ int SCH_EDIT_FRAME::CheckAnnotate( ANNOTATION_ERROR_HANDLER aErrorHandler,
 {
     SCH_REFERENCE_LIST  referenceList;
     constexpr bool      includePowerSymbols = false;
-    SCH_SHEET_LIST      sheets = Schematic().BuildSheetListSortedByPageNumbers();
+    SCH_SHEET_LIST      sheets = Schematic().Hierarchy();
     SCH_SHEET_PATH      currentSheet = GetCurrentSheet();
 
     // Build the list of symbols