From ee25744dfbb259d76089e892e5a1b1f1d855f79d Mon Sep 17 00:00:00 2001 From: vczh Date: Wed, 23 Sep 2026 23:02:32 -0700 Subject: [PATCH] Document UiaListApp and GitTui usage --- .github/KnowledgeBase/Index_GacUI.md | 12 ++++++++ .../KnowledgeBase/KB_GacUI_Design_GitTui.md | 29 ++++++++++++++++++ .../KnowledgeBase/KB_GacUI_Design_UiaList.md | 30 +++++++++++++++++++ Project.md | 11 +++++++ README.md | 2 ++ 5 files changed, 84 insertions(+) create mode 100644 .github/KnowledgeBase/KB_GacUI_Design_GitTui.md create mode 100644 .github/KnowledgeBase/KB_GacUI_Design_UiaList.md diff --git a/.github/KnowledgeBase/Index_GacUI.md b/.github/KnowledgeBase/Index_GacUI.md index 7c839636..61939985 100644 --- a/.github/KnowledgeBase/Index_GacUI.md +++ b/.github/KnowledgeBase/Index_GacUI.md @@ -32,6 +32,18 @@ Testing GacUI applications without real OS windows or rendering, using the remot ### Design Explanation +#### UiaList Windows Inspector + +Use UiaListApp to discover Windows application windows, inspect UI Automation nodes and properties, and invoke supported target actions. + +[Usage Guide](./KB_GacUI_Design_UiaList.md) + +#### GitTui Repository Browser + +Use GitTui to browse working-tree diffs and local branch history in a terminal, refresh after external changes, and explicitly pull from origin. + +[Usage Guide](./KB_GacUI_Design_GitTui.md) + #### Windows UI Automation - The Windows GDI and Direct2D providers expose GacUI controls and logical list/tree/grid/calendar items through UIA COM providers. diff --git a/.github/KnowledgeBase/KB_GacUI_Design_GitTui.md b/.github/KnowledgeBase/KB_GacUI_Design_GitTui.md new file mode 100644 index 00000000..0251513f --- /dev/null +++ b/.github/KnowledgeBase/KB_GacUI_Design_GitTui.md @@ -0,0 +1,29 @@ +# GitTui: Browse Git in a Terminal + +GitTui is the terminal application in `GacUI/Tools/GitView`. It browses working-tree changes and local branch history on Windows, Linux and macOS. Git must be on PATH. Open an interactive terminal in a Git working tree or one of its subfolders, then run `GitTui` by its absolute path. A submodule is treated as its own repository. All application resources are embedded. + +## Browse Changes and History + +- **CHANGES** groups staged, unstaged and new files. Select a file to read its diff. Added lines have a dark green background and deleted lines have a dark red background. The diff shows line numbers and three context lines around changes; separators mark omitted gaps. Binary and submodule changes have brief summaries. +- **HISTORY** lists commits on the selected local branch. Select a commit and then a file to read its diff. The status area shows the commit hash, author and date above file details. Merge commits compare with their first parent; root commits show their initial contents. +- **BRANCH** selects the history to browse. It does not check out a branch. **CHANGES** continues to describe the current working tree. +- **ACTIONS → REFRESH** reloads branches, changes and history and clears selections. Use it after changing files or running Git externally; GitTui does not watch for changes in the background. + +Browsing does not change the index, working tree or checked-out branch. GitTui does not provide staging, committing or conflict resolution. + +## Pull from Origin + +Despite their labels, the fetch commands perform a pull and can change repository files: + +- **FETCH ORIGIN** pulls the checked-out branch from `origin` and can create a merge commit. +- **FETCH ORIGIN and REBASE** first attempts the same pull. If it creates merge conflicts, GitTui aborts that merge and retries with rebase. Remaining conflicts are reported and left for resolution in another terminal. + +Both commands require a clean working tree, no unfinished Git operation, and the checked-out branch selected in **BRANCH**. They check the actual checkout again when invoked, including changes made in another terminal. Detached HEAD and branch mismatches are reported without pulling. Configure remote credentials before launching; commands run synchronously and network operations wait for Git. Commit or stash work, resolve conflicts and complete unfinished operations externally, then refresh. + +## Navigation and Launch + +Use Tab, arrow keys and Enter, or terminal mouse input. Drag column dividers to resize panes. The status area supports selecting and scrolling long error text. **ACTIONS → EXIT** closes the application. + +On Windows, press Alt followed by `B` for branches, `A` for actions, `C` or `H` for the tabs, `F` for files, `M` for commits, `D` for the diff, or `S` for status. Standalone Alt activation is unavailable in the current Linux/macOS terminal backend; use the other navigation methods there. Use an interactive UTF-8 terminal on Linux/macOS. + +Build instructions are in `GacUI/Tools/GitView/README.md` and `Release/Tools/README.md`. Linux/macOS builds require the matching platform provider libraries described there. Launch from the repository you want to inspect, even when the executable is stored elsewhere. diff --git a/.github/KnowledgeBase/KB_GacUI_Design_UiaList.md b/.github/KnowledgeBase/KB_GacUI_Design_UiaList.md new file mode 100644 index 00000000..a1b40ece --- /dev/null +++ b/.github/KnowledgeBase/KB_GacUI_Design_UiaList.md @@ -0,0 +1,30 @@ +# UiaList: Windows UI Automation Inspector + +UiaListApp is the Windows desktop inspector in `GacUI/Tools/UiaList`. Use it to discover application windows, inspect their UI Automation trees, read properties, and exercise supported actions. Run `UiaListApp.exe`; its resources are embedded, so no resource files need to accompany it. + +## Inspect a Window + +1. In **Processes**, select a process from the hierarchical dropdown beside **Refresh**. The list shows that process's visible top-level windows. An ancestor retained only because it has visible descendants can have an empty window list. +2. Single-click a window row, or select it and press Enter. **UI** opens a captured snapshot of that window. +3. Hover over the snapshot to outline the deepest matching UI Automation node. Click to reveal that node in **Nodes**. Scroll when the snapshot is larger than the preview area. +4. In **Nodes**, right-click a node and choose **Inspect**, or select it and press Enter. Double-click expands or collapses the tree. + +The preview is a snapshot. Clicking it selects an inspector node; it does not click the inspected application. A minimized or otherwise unavailable preview does not necessarily prevent inspecting the window's nodes. **Refresh** explicitly refreshes process discovery and preserves surviving selections; selecting a different process only changes the window list. + +## Properties and Actions + +The inspection window has **Properties** and **Actions** tabs. Properties lists supported values, including false, zero, empty and read-only values. Editable properties offer an embedded editor or a **...** button opening a multiline editor. Unsupported properties are omitted; not every property has a setter. + +Actions groups the target's supported operations by provider. Parameterless getters display their results directly. Parameterized getters run when valid edits are committed, such as with Enter or focus loss. Mutations and text-range workspace commands require explicit activation. These actions operate on the inspected application, so invoking them can change its state. + +Returned element references can be inspected; references within the selected tree can also be revealed in **Nodes**. Text-range workspaces support inspecting and manipulating ranges. Refresh or target mutation can invalidate an earlier range and require acquiring it again. Availability depends on what the target application's UI Automation providers expose. + +The surrounding UI selects English, Simplified Chinese or Japanese from Windows' preferred UI languages. Standard interface names and text from the target retain their original spelling. + +## Launch and Automation + +The executable is Windows-only. Build and launch instructions are in `GacUI/Tools/UiaList/README.md`; the release tool build instructions are in `Release/Tools/README.md`. + +Debug builds expose `http://localhost:8888/Automation/UiaListApp/Controls` and `/IO`. Pass `/AsPort:8891`, for example, when another application uses the default port. One decimal port from 1 through 65535 is accepted. Release builds do not start an HTTP automation endpoint; Windows UI Automation remains available. + +For GacUI applications' own UI Automation support, see [Windows UI Automation](./KB_GacUI_Design_UIAutomation.md). diff --git a/Project.md b/Project.md index b5a4a664..99d11817 100644 --- a/Project.md +++ b/Project.md @@ -1,3 +1,14 @@ # Projects to Work on Take a look at [the GacUI repo example](https://github.com/vczh-libraries/GacUI/blob/master/Project.md) for better understanding about how to prepare this file. + +## Content of This Project + +### Tools + +`Tools/Executables/Executables.sln` builds the release executables. See [Tools/README.md](Tools/README.md) for building and copying them into `Tools`. + +- [UiaListApp](.github/KnowledgeBase/KB_GacUI_Design_UiaList.md) is a Windows UI Automation inspector for discovering application windows, inspecting nodes and properties, and invoking supported actions. +- [GitTui](.github/KnowledgeBase/KB_GacUI_Design_GitTui.md) browses Git working-tree diffs and local branch history in a terminal on Windows, Linux and macOS. Launch it inside the repository to inspect. Its explicit pull commands can update that repository. + +Their source files are maintained in `GacUI/Tools/UiaList` and `GacUI/Tools/GitView` and copied here by `Tools/Tools/Build.ps1 -Project UpdateRelease` in the sibling Tools repository. Edit the owning sources and run the release update instead of editing the copied files. diff --git a/README.md b/README.md index 058f24e2..9d720375 100644 --- a/README.md +++ b/README.md @@ -111,6 +111,8 @@ You can copy the whole `.github` folder to your own repo. - **Import** Gaclib source code - **Skins** Predefined control templates. You will need to call `vl::presentation::theme::RegisterTheme` to set a default skin before creating any controls. Read [WinMain.cpp](https://github.com/vczh-libraries/Release/blob/master/Tutorial/Lib/GacUILite/WinMain.cpp) for details. - **Tools** + - [**UiaListApp.exe**](.github/KnowledgeBase/KB_GacUI_Design_UiaList.md) Windows UI Automation inspector for application windows, properties and supported actions + - [**GitTui**](.github/KnowledgeBase/KB_GacUI_Design_GitTui.md) Terminal Git browser for working-tree diffs and branch history on Windows, Linux and macOS, with explicit pull commands - [**GacGen.exe**](.github/KnowledgeBase/KB_GacUI_Design_GacGenAndGacBuild.md) GacUI resource compiler and C++ code generator for x86 and x64 - [**CppMerge.exe**](.github/KnowledgeBase/KB_Workflow_Design_CppMerge.md) Merge GacUI generated code for x86 and x64 to architecture-independent code - [**GlrParserGen.exe**](.github/KnowledgeBase/KB_VlppParser2_Design_GlrParserGen.md) General LR parser to C++ code generator