Setting search (#41285)

<!-- Enter a brief description/summary of your PR here. What does it
fix/what does it change/how was it tested (even manually, if necessary)?
-->
## Summary of the Pull Request

<!-- Please review the items on the PR checklist before submitting-->
## PR Checklist

- [ ] Closes: #xxx
- [ ] **Communication:** I've discussed this with core contributors
already. If the work hasn't been agreed, this work might be rejected
- [x] **Tests:** Added/updated and all pass
- [ ] **Localization:** All end-user-facing strings can be localized
- [ ] **Dev docs:** Added/updated
- [ ] **New binaries:** Added on the required places
- [ ] [JSON for
signing](https://github.com/microsoft/PowerToys/blob/main/.pipelines/ESRPSigning_core.json)
for new binaries
- [ ] [WXS for
installer](https://github.com/microsoft/PowerToys/blob/main/installer/PowerToysSetup/Product.wxs)
for new binaries and localization folder
- [ ] [YML for CI
pipeline](https://github.com/microsoft/PowerToys/blob/main/.pipelines/ci/templates/build-powertoys-steps.yml)
for new test projects
- [ ] [YML for signed
pipeline](https://github.com/microsoft/PowerToys/blob/main/.pipelines/release.yml)
- [ ] **Documentation updated:** If checked, please file a pull request
on [our docs
repo](https://github.com/MicrosoftDocs/windows-uwp/tree/docs/hub/powertoys)
and link it here: #xxx

<!-- Provide a more detailed description of the PR, other things fixed,
or any additional comments/features here -->
## Detailed Description of the Pull Request / Additional comments

<!-- Describe how you validated the behavior. Add automated tests
wherever possible, but list manual validation steps taken as well -->
## Validation Steps Performed
Localized search:
<img width="1576" height="480" alt="image"
src="https://github.com/user-attachments/assets/dd6e5e9f-419b-40b1-b796-f0799481ecfc"
/>


## AI summary
This pull request introduces infrastructure and code to support search
functionality for PowerToys settings, including a new search index
specification, a dedicated search library, and updates to the solution
configuration. The main changes are the addition of a spec describing
how settings should be indexed and navigated, the creation of a new
`Common.Search` project with a fuzz search implementation, and updates
to the solution file to include these new components.

**Settings Search Feature Implementation**

* Documentation:
* Added a detailed specification (`settings-search.md`) describing the
structure of PowerToys settings pages, how to index settings, navigation
logic, runtime search, result grouping, build-time indexing strategy,
and corner cases.

* New Search Library:
* Added the new `Common.Search` project to the solution, including its
project file and implementation of a fuzz search service
(`FuzzSearchService<T>`), match options, match results, and search
precision scoring.
[[1]](diffhunk://#diff-ddc06fa41e4e723e54181b0cb85cdd00f57f75725d51ceefa242d4d651a9a363R1-R8)
[[2]](diffhunk://#diff-1a2ca29fc33bcccf338a7843a040ca2c31ba821e8cab7064fab0dbb1224d454cR1-R39)
[[3]](diffhunk://#diff-242764d948b795f39653a84d9b6bfcdc52730100deab2e3a0995be95bb8e7868R1-R10)
[[4]](diffhunk://#diff-61e525491ed916ebd65dabb66dd4f5dc720320d7e295ef1e0bd6d506ea0f7df6R1-R67)
[[5]](diffhunk://#diff-a775f6de2e8d42982829b4161668f49dedbbd9dcbb05ce20003de7e62275c57aR1-R12)

* Solution Configuration:
* Updated `PowerToys.sln` to include `Common.Search` and
`Settings.UI.XamlIndexBuilder` projects, and configured their build
settings for various platforms and mapped project dependencies.
[[1]](diffhunk://#diff-ca837ce490070b91656ffffe31cbad8865ba9174e0f020231f77baf35ff3f811R714-R716)
[[2]](diffhunk://#diff-ca837ce490070b91656ffffe31cbad8865ba9174e0f020231f77baf35ff3f811R2704-R2727)
[[3]](diffhunk://#diff-ca837ce490070b91656ffffe31cbad8865ba9174e0f020231f77baf35ff3f811R2889)
[[4]](diffhunk://#diff-ca837ce490070b91656ffffe31cbad8865ba9174e0f020231f77baf35ff3f811R3157-R3158)

**Spell-check Dictionary Updates**

* Added new terms related to navigation and settings UI components (such
as `Navigatable`, `NavigatablePage`, `settingscard`, `Tru`, `tweakable`)
to the spell-check dictionary to support the new search and indexing
features.
[[1]](diffhunk://#diff-5dcab162c1b233a49973ae010f2b88c7ec4844382abd705e6154685e62bd5c4dR1020-R1021)
[[2]](diffhunk://#diff-5dcab162c1b233a49973ae010f2b88c7ec4844382abd705e6154685e62bd5c4dR1498)
[[3]](diffhunk://#diff-5dcab162c1b233a49973ae010f2b88c7ec4844382abd705e6154685e62bd5c4dR1755-R1761)

---------

Co-authored-by: Niels Laute <niels.laute@live.nl>
Co-authored-by: Gordon Lam (SH) <yeelam@microsoft.com>
Co-authored-by: Gordon Lam <73506701+yeelam-gordon@users.noreply.github.com>
This commit is contained in:
Kai Tao
2025-08-25 21:23:07 +08:00
committed by GitHub
parent 64dc8e0f27
commit 4ad951eb56
99 changed files with 3734 additions and 558 deletions

View File

@@ -1,10 +1,15 @@
// Copyright (c) Microsoft Corporation
// Copyright (c) Microsoft Corporation
// The Microsoft Corporation licenses this file to you under the MIT license.
// See the LICENSE file in the project root for more information.
using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using Common.Search;
using Common.Search.FuzzSearch;
using ManagedCommon;
using Microsoft.PowerToys.Settings.UI.Helpers;
using Microsoft.PowerToys.Settings.UI.Library;
@@ -14,6 +19,8 @@ using Microsoft.UI.Windowing;
using Microsoft.UI.Xaml;
using Microsoft.UI.Xaml.Automation.Peers;
using Microsoft.UI.Xaml.Controls;
using Microsoft.UI.Xaml.Input;
using Settings.UI.Library;
using Windows.Data.Json;
using Windows.System;
using WinRT.Interop;
@@ -23,7 +30,7 @@ namespace Microsoft.PowerToys.Settings.UI.Views
/// <summary>
/// Root page.
/// </summary>
public sealed partial class ShellPage : UserControl
public sealed partial class ShellPage : UserControl, IDisposable
{
/// <summary>
/// Declaration for the ipc callback function.
@@ -125,7 +132,17 @@ namespace Microsoft.PowerToys.Settings.UI.Views
public static bool IsUserAnAdmin { get; set; }
public CommunityToolkit.WinUI.Controls.TitleBar TitleBar => AppTitleBar;
private Dictionary<Type, NavigationViewItem> _navViewParentLookup = new Dictionary<Type, NavigationViewItem>();
private List<string> _searchSuggestions = [];
private CancellationTokenSource _searchDebounceCts;
private const int SearchDebounceMs = 500;
private bool _disposed;
// Tracing id for correlating logs of a single search interaction
private static long _searchTraceIdCounter;
/// <summary>
/// Initializes a new instance of the <see cref="ShellPage"/> class.
@@ -134,7 +151,7 @@ namespace Microsoft.PowerToys.Settings.UI.Views
public ShellPage()
{
InitializeComponent();
SetWindowTitle();
var settingsUtils = new SettingsUtils();
ViewModel = new ShellViewModel(SettingsRepository<GeneralSettings>.GetInstance(settingsUtils));
DataContext = ViewModel;
@@ -144,8 +161,7 @@ namespace Microsoft.PowerToys.Settings.UI.Views
// NL moved navigation to general page to the moment when the window is first activated (to not make flyout window disappear)
// shellFrame.Navigate(typeof(GeneralPage));
IPCResponseHandleList.Add(ReceiveMessage);
Services.IPCResponseService.Instance.RegisterForIPC();
SetTitleBar();
IPCResponseService.Instance.RegisterForIPC();
if (_navViewParentLookup.Count > 0)
{
@@ -159,6 +175,7 @@ namespace Microsoft.PowerToys.Settings.UI.Views
foreach (var child in parent.MenuItems.OfType<NavigationViewItem>())
{
_navViewParentLookup.TryAdd(child.GetValue(NavHelper.NavigateToProperty) as Type, parent);
_searchSuggestions.Add(child.Content?.ToString());
}
}
}
@@ -293,11 +310,6 @@ namespace Microsoft.PowerToys.Settings.UI.Views
}
}
private void OobeButton_Click(object sender, RoutedEventArgs e)
{
OpenOobeWindowCallback();
}
private bool navigationViewInitialStateProcessed; // avoid announcing initial state of the navigation pane.
private void NavigationView_PaneOpened(NavigationView sender, object args)
@@ -350,17 +362,17 @@ namespace Microsoft.PowerToys.Settings.UI.Views
}
}
private void OOBEItem_Tapped(object sender, Microsoft.UI.Xaml.Input.TappedRoutedEventArgs e)
private void OOBEItem_Tapped(object sender, TappedRoutedEventArgs e)
{
OpenOobeWindowCallback();
}
private async void FeedbackItem_Tapped(object sender, Microsoft.UI.Xaml.Input.TappedRoutedEventArgs e)
private async void FeedbackItem_Tapped(object sender, TappedRoutedEventArgs e)
{
await Launcher.LaunchUriAsync(new Uri("https://aka.ms/powerToysGiveFeedback"));
}
private void WhatIsNewItem_Tapped(object sender, Microsoft.UI.Xaml.Input.TappedRoutedEventArgs e)
private void WhatIsNewItem_Tapped(object sender, TappedRoutedEventArgs e)
{
OpenWhatIsNewWindowCallback();
}
@@ -372,12 +384,12 @@ namespace Microsoft.PowerToys.Settings.UI.Views
{
Type pageType = selectedItem.GetValue(NavHelper.NavigateToProperty) as Type;
if (_navViewParentLookup.TryGetValue(pageType, out var parentItem) && !parentItem.IsExpanded)
if (pageType != null && _navViewParentLookup.TryGetValue(pageType, out var parentItem) && !parentItem.IsExpanded)
{
parentItem.IsExpanded = true;
ViewModel.Expanding = parentItem;
NavigationService.Navigate(pageType);
}
NavigationService.Navigate(pageType);
}
}
@@ -419,43 +431,47 @@ namespace Microsoft.PowerToys.Settings.UI.Views
NavigationService.EnsurePageIsSelected(typeof(DashboardPage));
}
private void SetTitleBar()
private void SetWindowTitle()
{
var u = App.GetSettingsWindow();
if (u != null)
{
// A custom title bar is required for full window theme and Mica support.
// https://docs.microsoft.com/windows/apps/develop/title-bar?tabs=winui3#full-customization
u.ExtendsContentIntoTitleBar = true;
u.AppWindow.TitleBar.PreferredHeightOption = TitleBarHeightOption.Tall;
WindowHelpers.ForceTopBorder1PixelInsetOnWindows10(WindowNative.GetWindowHandle(u));
u.SetTitleBar(AppTitleBar);
var loader = ResourceLoaderInstance.ResourceLoader;
AppTitleBarText.Text = App.IsElevated ? loader.GetString("SettingsWindow_AdminTitle") : loader.GetString("SettingsWindow_Title");
var loader = ResourceLoaderInstance.ResourceLoader;
AppTitleBar.Title = App.IsElevated ? loader.GetString("SettingsWindow_AdminTitle") : loader.GetString("SettingsWindow_Title");
#if DEBUG
DebugMessage.Visibility = Visibility.Visible;
AppTitleBar.Subtitle = "Debug";
#endif
}
}
private void ShellPage_Loaded(object sender, RoutedEventArgs e)
{
SetTitleBar();
Logger.LogDebug("[Search][Index] Scheduling BuildIndex...");
var swIndex = Stopwatch.StartNew();
Task.Run(() =>
{
Logger.LogDebug("[Search][Index] BuildIndex started");
SearchIndexService.BuildIndex();
})
.ContinueWith(t =>
{
swIndex.Stop();
if (t.IsFaulted)
{
Logger.LogDebug($"[Search][Index] BuildIndex FAILED after {swIndex.ElapsedMilliseconds} ms: {t.Exception?.Flatten().InnerException?.Message}");
}
else
{
Logger.LogDebug($"[Search][Index] BuildIndex completed in {swIndex.ElapsedMilliseconds} ms.");
}
});
}
private void NavigationView_DisplayModeChanged(NavigationView sender, NavigationViewDisplayModeChangedEventArgs args)
{
if (args.DisplayMode == NavigationViewDisplayMode.Compact || args.DisplayMode == NavigationViewDisplayMode.Minimal)
{
PaneToggleBtn.Visibility = Visibility.Visible;
AppTitleBar.Margin = new Thickness(48, 0, 0, 0);
AppTitleBarText.Margin = new Thickness(12, 0, 0, 0);
AppTitleBar.IsPaneButtonVisible = true;
}
else
{
PaneToggleBtn.Visibility = Visibility.Collapsed;
AppTitleBar.Margin = new Thickness(16, 0, 0, 0);
AppTitleBarText.Margin = new Thickness(16, 0, 0, 0);
AppTitleBar.IsPaneButtonVisible = false;
}
}
@@ -481,5 +497,279 @@ namespace Microsoft.PowerToys.Settings.UI.Views
IntPtr hWnd = NativeMethods.FindWindow(ptTrayIconWindowClass, ptTrayIconWindowClass);
NativeMethods.SendMessage(hWnd, NativeMethods.WM_COMMAND, ID_CLOSE_MENU_COMMAND, 0);
}
private List<SettingEntry> _lastSearchResults = new();
private string _lastQueryText = string.Empty;
private async void SearchBox_TextChanged(AutoSuggestBox sender, AutoSuggestBoxTextChangedEventArgs args)
{
// Only respond to user input, not programmatic text changes
if (args.Reason != AutoSuggestionBoxTextChangeReason.UserInput)
{
return;
}
var query = sender.Text?.Trim() ?? string.Empty;
var traceId = Interlocked.Increment(ref _searchTraceIdCounter);
var swOverall = Stopwatch.StartNew();
Logger.LogDebug($"[Search][TextChanged][{traceId}] start. query='{query}'");
// Debounce: cancel previous pending search
_searchDebounceCts?.Cancel();
_searchDebounceCts?.Dispose();
_searchDebounceCts = new CancellationTokenSource();
var token = _searchDebounceCts.Token;
if (string.IsNullOrWhiteSpace(query))
{
sender.ItemsSource = null;
sender.IsSuggestionListOpen = false;
_lastSearchResults.Clear();
_lastQueryText = string.Empty;
Logger.LogDebug($"[Search][TextChanged][{traceId}] empty query. end");
return;
}
try
{
await Task.Delay(SearchDebounceMs, token);
}
catch (TaskCanceledException)
{
// A newer keystroke arrived; abandon this run
Logger.LogDebug($"[Search][TextChanged][{traceId}] debounce canceled at +{swOverall.ElapsedMilliseconds} ms");
return;
}
if (token.IsCancellationRequested)
{
Logger.LogDebug($"[Search][TextChanged][{traceId}] token canceled post-debounce at +{swOverall.ElapsedMilliseconds} ms");
return;
}
// Query the index on a background thread to avoid blocking UI
List<SettingEntry> results = null;
try
{
// If the token is already canceled before scheduling, the task won't start.
var swSearch = Stopwatch.StartNew();
Logger.LogDebug($"[Search][TextChanged][{traceId}] dispatch search...");
results = await Task.Run(() => SearchIndexService.Search(query, token), token);
swSearch.Stop();
Logger.LogDebug($"[Search][TextChanged][{traceId}] search done in {swSearch.ElapsedMilliseconds} ms. results={results?.Count ?? 0}");
}
catch (OperationCanceledException)
{
Logger.LogDebug($"[Search][TextChanged][{traceId}] search canceled at +{swOverall.ElapsedMilliseconds} ms");
return;
}
if (token.IsCancellationRequested)
{
Logger.LogDebug($"[Search][TextChanged][{traceId}] token canceled after search at +{swOverall.ElapsedMilliseconds} ms");
return;
}
_lastSearchResults = results;
_lastQueryText = query;
List<SuggestionItem> top;
if (results.Count == 0)
{
// Explicit no-results row
var rl = ResourceLoaderInstance.ResourceLoader;
var noResultsPrefix = rl.GetString("Shell_Search_NoResults");
if (string.IsNullOrEmpty(noResultsPrefix))
{
noResultsPrefix = "No results for";
}
var headerText = $"{noResultsPrefix} '{query}'";
top =
[
new()
{
Header = headerText,
IsNoResults = true,
},
];
Logger.LogDebug($"[Search][TextChanged][{traceId}] no results -> added placeholder item (count={top.Count})");
}
else
{
// Project top 5 suggestions
var swProject = Stopwatch.StartNew();
top = [.. results.Take(5)
.Select(e =>
{
string subtitle = string.Empty;
if (e.Type != EntryType.SettingsPage)
{
var swSubtitle = Stopwatch.StartNew();
subtitle = SearchIndexService.GetLocalizedPageName(e.PageTypeName);
if (string.IsNullOrEmpty(subtitle))
{
// Fallback: look up the module title from the in-memory index
var swFallback = Stopwatch.StartNew();
subtitle = SearchIndexService.Index
.Where(x => x.Type == EntryType.SettingsPage && x.PageTypeName == e.PageTypeName)
.Select(x => x.Header)
.FirstOrDefault() ?? string.Empty;
swFallback.Stop();
Logger.LogDebug($"[Search][TextChanged][{traceId}] fallback subtitle for '{e.PageTypeName}' took {swFallback.ElapsedMilliseconds} ms");
}
swSubtitle.Stop();
Logger.LogDebug($"[Search][TextChanged][{traceId}] subtitle for '{e.PageTypeName}' took {swSubtitle.ElapsedMilliseconds} ms");
}
return new SuggestionItem
{
Header = e.Header,
Icon = e.Icon,
PageTypeName = e.PageTypeName,
ElementName = e.ElementName,
ParentElementName = e.ParentElementName,
Subtitle = subtitle,
IsShowAll = false,
};
})];
swProject.Stop();
Logger.LogDebug($"[Search][TextChanged][{traceId}] project suggestions took {swProject.ElapsedMilliseconds} ms. topCount={top.Count}");
if (results.Count > 5)
{
// Add a tail item to show all results if there are more than 5
top.Add(new SuggestionItem { IsShowAll = true });
Logger.LogDebug($"[Search][TextChanged][{traceId}] added 'Show all results' item");
}
}
var swUi = Stopwatch.StartNew();
sender.ItemsSource = top;
sender.IsSuggestionListOpen = top.Count > 0;
swUi.Stop();
swOverall.Stop();
Logger.LogDebug($"[Search][TextChanged][{traceId}] UI update took {swUi.ElapsedMilliseconds} ms. total={swOverall.ElapsedMilliseconds} ms");
}
private void SearchBox_SuggestionChosen(AutoSuggestBox sender, AutoSuggestBoxSuggestionChosenEventArgs args)
{
// Do not navigate on arrow navigation. Let QuerySubmitted handle commits (Enter/click).
// AutoSuggestBox will pass the chosen item via args.ChosenSuggestion to QuerySubmitted.
// No action required here.
}
private void NavigateFromSuggestion(SuggestionItem item)
{
var queryText = _lastQueryText;
if (item.IsShowAll)
{
// Navigate to full results page
var searchParams = new SearchResultsNavigationParams(queryText, _lastSearchResults);
NavigationService.Navigate<SearchResultsPage>(searchParams);
SearchBox.Text = string.Empty;
return;
}
// Navigate to the selected item
var pageType = GetPageTypeFromName(item.PageTypeName);
if (pageType != null)
{
if (string.IsNullOrEmpty(item.ElementName))
{
NavigationService.Navigate(pageType);
}
else
{
var navigationParams = new NavigationParams(item.ElementName, item.ParentElementName);
NavigationService.Navigate(pageType, navigationParams);
}
// Clear the search box after navigation
SearchBox.Text = string.Empty;
}
}
private static Type GetPageTypeFromName(string pageTypeName)
{
if (string.IsNullOrEmpty(pageTypeName))
{
return null;
}
var assembly = typeof(GeneralPage).Assembly;
return assembly.GetType($"Microsoft.PowerToys.Settings.UI.Views.{pageTypeName}");
}
private void CtrlF_Invoked(KeyboardAccelerator sender, KeyboardAcceleratorInvokedEventArgs args)
{
SearchBox.Focus(FocusState.Programmatic);
}
private void SearchBox_GotFocus(object sender, RoutedEventArgs e)
{
// do not prompt unless search for text.
return;
}
private async void SearchBox_QuerySubmitted(AutoSuggestBox sender, AutoSuggestBoxQuerySubmittedEventArgs args)
{
var swSubmit = Stopwatch.StartNew();
Logger.LogDebug("[Search][Submit] start");
// If a suggestion is selected, navigate directly
if (args.ChosenSuggestion is SuggestionItem chosen)
{
Logger.LogDebug($"[Search][Submit] chosen suggestion -> navigate to {chosen.PageTypeName} element={chosen.ElementName ?? "<page>"}");
NavigateFromSuggestion(chosen);
return;
}
var queryText = (args.QueryText ?? _lastQueryText)?.Trim();
if (string.IsNullOrWhiteSpace(queryText))
{
Logger.LogDebug("[Search][Submit] empty query -> navigate Dashboard");
NavigationService.Navigate<DashboardPage>();
return;
}
// Prefer cached results (from live search); if empty, perform a fresh search
var matched = _lastSearchResults?.Count > 0 && string.Equals(_lastQueryText, queryText, StringComparison.Ordinal)
? _lastSearchResults
: await Task.Run(() =>
{
var sw = Stopwatch.StartNew();
Logger.LogDebug($"[Search][Submit] background search for '{queryText}'...");
var r = SearchIndexService.Search(queryText);
sw.Stop();
Logger.LogDebug($"[Search][Submit] background search done in {sw.ElapsedMilliseconds} ms. results={r?.Count ?? 0}");
return r;
});
var searchParams = new SearchResultsNavigationParams(queryText, matched);
Logger.LogDebug($"[Search][Submit] navigate to SearchResultsPage (results={matched?.Count ?? 0})");
NavigationService.Navigate<SearchResultsPage>(searchParams);
swSubmit.Stop();
Logger.LogDebug($"[Search][Submit] total {swSubmit.ElapsedMilliseconds} ms");
}
public void Dispose()
{
if (_disposed)
{
return;
}
_searchDebounceCts?.Cancel();
_searchDebounceCts?.Dispose();
_searchDebounceCts = null;
_disposed = true;
GC.SuppressFinalize(this);
}
}
}