Mirrors_UI_SDK/GacUI
1
0
Fork 0
mirror of https://github.com/vczh-libraries/Release.git synced 2026-08-18 01:44:28 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update prompts

Browse Source
This commit is contained in:
vczh
2026-02-05 15:53:47 -08:00
parent b9ee2b3e22
commit fe2a56d5bf
40 changed files with 1125 additions and 1793 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/Guidelines/Building.md
+34
View File
@@ -0,0 +1,34 @@
# Building a Solution
- Only run `copilotBuild.ps1` to build a solution.
- DO NOT use msbuild by yourself.
- The script builds all projects in a solution.
## Executing copilotBuild.ps1
Before building, ensure the debugger has stopped.
If there is any error message, it means the debugger is not alive, it is good.
```
& REPO-ROOT\.github\Scripts\copilotDebug_Stop.ps1
```
And then run this script to build the solution:
```
cd SOLUTION-ROOT
& REPO-ROOT\.github\Scripts\copilotBuild.ps1
```
## The Correct Way to Read Compiler Result
- The only source of trust is the raw output of the compiler.
- Wait for the script to finish before reading the log file.
- DO NOT need to read the output from the script.
- Building takes a long time. DO NOT hurry.
- When the script finishes, the result is saved to `REPO-ROOT/.github/Scripts/Build.log`.
- A temporary file `Build.log.unfinished` is created during building. It will be automatically deleted as soon as the building finishes. If you see this file, it means the building is not finished yet.
- When build succeeds, the last several lines of `Build.log` indicates the number of warnings and errors in the following pattern:
- "Build succeeded."
- "0 Warning(s)"
- "0 Error(s)"
.github/Guidelines/Debugging.md
+71
View File
@@ -0,0 +1,71 @@
## Debugging a Project
Debugging would be useful when you lack necessary information.
In this section I offer you a set of PowerShell scripts that work with CDB (Microsoft's Console Debugger).
CDB accepts the exact same commands as WinDBG.
### Start a Debugger
Read `REPO-ROOT/.github/Project.md` to understand the solution folder and the unit test project name you are working with.
Additional information could be found in THE FIRST LINE in `REPO-ROOT/.github/Scripts/Execute.log`.
Execute the following PowerShell commands:
```
cd SOLUTION-ROOT
start powershell {& REPO-ROOT\.github\Scripts\copilotDebug_Start.ps1 -Executable PROJECT-NAME}
```
The `start powershell {}` is necessary; otherwise the script will block the execution forever causing you to wait infinitely.
The script will finish immediately, leaving a debugger running in the background. You can send commands to the debugger.
The process being debugged is paused at the beginning, you are given a chance to set breakpoints.
After you are prepared, send the `g` command to start running.
### Stop a Debugger
You must call this script to stop the debugger.
Do not stop the debugger using any command.
This script is also required to run before compiling only when Visual Studio Code tasks are not available to you.
```
& REPO-ROOT\.github\Scripts\copilotDebug_Stop.ps1
```
If there is any error message, it means the debugger is not alive, it is good.
### Sending Commands to Debugger
```
& REPO-ROOT\.github\Scripts\copilotDebug_RunCommand.ps1 -Command "Commands"
```
The effect of commands lasts across multiple `copilotDebug_RunCommand.ps1` calls. For example, after you executed `.frame X`, you do not need to repeat it to use `dx` under the same call stack frame in later calls, as `.frame X` is already effective.
Multiple commands can be executed sequentially separated by ";".
The debugger is configured to be using source mode, which means you can see source files and line numbers in the call stack, and step in/out/over are working line by line.
CDB accepts exactly same commands as WinDBG, and here are some recommended commands:
- **g**: continue until hitting a breakpoint or crashing.
- **k**n: print current call stack.
- **kn LINES**: print first `LINES` of the current call stack.
- **.frame NUMBER**: inspect the call stack frame labeled with `NUMBER`. `kn` will show the number, file and line along with the call stack.
- **dv**: list all available variables in the current call stack frame.
- **dx EXPRESSION**: evaluate the `EXPRESSION` and print the result. `EXPRESSION` can be any valid C programming language expression. When you specify a type (especially when doing casting), full namespaces are required, do not start with `::`.
- **bp `FILE:LINE`**: set a breakpoint at the specified line in `FILE`, starting from 0. A pair of "`" characters are required around the target, this is not a markdown syntax.
- **bl**, **.bpcmds**, **be NUMBERS**, **bd NUMBERS**, **bc NUMBERS**, **bsc NUMBER CONDITION**: list, list with attached commands, enable, disable, delete, attach a command to breakpoint(s).
- **p**: step over, aka execute the complete current line.
- **t**: step in, aka execute the current line, if any function is called, goes into the function.
- **pt**: step out, aka run until the end of the current function.
An `.natvis` file is automatically offered with the debugger,
it formats some primitive types defined in the `Vlpp` project,
including `WString` and other string types, `Nullable`, `Variant`, container types, etc.
The formatting applies to the **dx** command,
when you want to see raw data instead of formatted printing,
use **dx (EXPRESSION),!**.
You can also use `dv -rX` to expand "X" levels of fields, the default option is `-r0` which only expands one level of fields.
### Commands to Avoid
- Only use **dv** without any parameters.
- DO NOT use **dt**.
- DO NOT use **q**, **qd**, **qq**, **qqd** etc to stop the debugger, always use `copilotDebug_Stop.ps1`.
.github/Guidelines/GacUIXmlResource.md
+223
View File
@@ -0,0 +1,223 @@
# Syntax of GacUI XML Resources
- This is a brief introduction for GacUI XML Resource.
- Detailed document can be found in `REPO-ROOT/.github/KnowledgeBase/Index.md` under `# Copy of Online Manual`:
- In `## GacUI`, the `GacUI XML Resource` item and all sub items detailed explain the syntax for GacUI XML Resource.
- In `## Workflow Script`, the `Syntax` item and all sub items detailed explain the syntax for the script language used in GacUI XML Resource.
## Mapping XML Entity to C++ Entity
Most XML tags are calling constructors for classes in the following folder:
- Source\Controls
- Source\Application
- Source\GraphicsCompositions
- Source\GraphicsElement
All mappings are:
- presentation::controls::Gui*
- presentation::elements::Gui*Element
- presentation::compositions::Gui*Composition
- presentation::compositions::Gui*
- presentation::templates::Gui*
- system::*
- system::reflection::*
- presentation::*
- presentation::Gui*
- presentation::controls::*
- presentation::controls::list::*
- presentation::controls::tree::*
- presentation::elements::*
- presentation::elements::Gui*
- presentation::elements::text::*
- presentation::compositions::*
- presentation::templates::*
- presentation::theme::*
When you see `<Button>`,
try all mappings and for example `presentation::elements::Gui*`,
replacing `*` with the tag and you will get `presentation::elements::GuiButton`,
it is an existing C++ class!
So `<Button>` means `presentation::controls::GuiButton`.
Following the same rule, `<Table>` would be `presentation::compositions::GuiTableComposition` and `<SolidLabel>` would be `presentation::elements::GuiSolidLabelElement`.
Take this file `Test\Resources\Metadata\Reflection64.txt` as an index, it collects all valid C++ classes and their members, but written in my own format.
When there is a `@FullName` on top of a class, it means the full name in C++, the class name will be the full name in XML.
When there is no `@FullName` but the class name begins with `presentation::`, the full name in C++ begins with `vl::presentation::`.
## XML in a Single String
To define an empty window, the XML looks like:
```xml
<Resource>
<Instance name="MainWindowResource">
<Instance ref.Class="gacuisrc_unittest::MainWindow">
<Window ref.Name="self" Text="GuiRibbonGallery" ClientSize="x:480 y:320">
</Window>
</Instance>
</Instance>
</Resource>
```
The first `<Instance>` defines the resource named `MainWindowResource`, the `<Instance>` inside is the content. You can also add a script like this:
```xml
<Resource>
<Instance name="MainWindowResource">
<Instance ref.Class="gacuisrc_unittest::MainWindow">
<Window ref.Name="self" Text="GuiRibbonGallery" ClientSize="x:480 y:320">
<Label Text="This is a demo"/>
</Window>
</Instance>
</Instance>
<Folder name="Scripts">
<Script name="ViewModelResource">
<Workflow>
<![CDATA[
module viewmodel;
using system::*;
using presentation::*;
namespace demo
{
enum MyCategory
{
Black = 0,
Red = 1,
Lime = 2,
Blue = 3,
White = 4,
}
func ToString(value : DateTime) : string
{
return $"$(value.month)/$(value.day)/$(value.year)";
}
}
]]>
</Workflow>
</Script>
</Folder>
</Resource>
```
One more `Scripts\ViewModelResource` is added to the resource, and the content of the new resource is defined by `<Workflow>`. Code inside `<Workflow>` will always be Workflow Script instead of C++.
## UI Layout
This is the GacUI XML document for UI layout: https://gaclib.net/doc/current/gacui/components/compositions/home.html
To expand a composition to the whole parent client area:
```XML
<AnyComposition AlignmentToParent="left:0 top:0 right:0 bottom:0"/>
```
- `MinSizeLimitation="LimitToElementAndChildren"` for a composition limits its minimum size to the sum of all its children.
- `AlignmentToParent="left:8 top:8 right:8 bottom:8"` for a composition sticks itself to the parent's whole client area with 8 pixels on each side. If the number is -1, it means it doesn't stick to the specific parent's client area side. When both `left` and `right` are -1, it sticks to the left. When both `top` and `bottom` are -1, it sticks to the top. The default value is all -1.
`BoundsComposition` of a control is its boundary composition. To expand a control to the whole parent client area:
```XML
<AnyControl>
<att.BoundsComposition-set AlignmentToParent="left:0 top:0 right:0 bottom:0"/>
</AnyControl>
```
`<Cell>`, `<RowSplitter>`, `<ColumnSplitter>`, `<StackItem>` and `<FlowItem>` are controlled by its parent composition, no positions or size limits need to be adjusted.
### Bounds
`<Bounds>` is useful to define a space.
### Table
The most useful composition is `<Table>`, it is a grid layout with rows and columns. There are 3 sizing modes for rows and columns:
- `<_>composeType:MinSize</_>`: The size is decided by its content.
- `<_>composeType:Absolute absolute:10</_>`: The size is 10.
- `<_>composeType:Percentage percentage:0.5</_>`: The size is 50% of all space excludes MinSizes and Absolutes.
The `CellPadding` property defines the space between cells, default 0. The `BorderVisible` adds `CellPadding` around the border, default true. Obviously the following two tables are identical.
```XML
<Table AlignmentToParent="left:8 top:8 right:8 bottom:8" CellPadding="5" BorderVisible="false"/>
<Table AlignmentToParent="left:3 top:3 right:3 bottom:3" CellPadding="5" BorderVisible="true"/>
```
In order to make a table expanded to the whole window and placing a button at the center:
- Set rows to Percentage 0.5; MinSize; Percentage 0.5
- Set columns to Percentage 0.5; MinSize; Percentage 0.5
- Put the button to the center cell, which is `Site="row:1 column:1"`
We can also list 3 buttons vertically in the top-left corner of the window:
- Set rows to MinSize; MinSize; MinSize; Percentage 1.0
- Set columns to MinSize; Percentage 1.0
- Put 3 button to all MinSize cells, which is `Site="row:0 column:0"`, `Site="row:1 column:0"`, `Site="row:2 column:0"`
To make a dialog with big content with OK and Cancel buttons at the bottom-right corner:
- Set rows to Percentage 1.0; MinSize
- Set columns to Percentage 1.0; MinSize; MinSize
- Put the content to the cell that automatically expands to the rest of the space, which is `Site="row:0 column:0"`
- Put 2 button to all MinSize cells, which is `Site="row:1 column:1"`, `Site="row:1 column:2"`
### Others
Please read the document of GacUI XML for other compositions: https://gaclib.net/doc/current/gacui/components/compositions/home.html
- Stack/StackItem
- Flow/FlowItem
- SharedSizeRoot/SharedSizeItem
- SideAligned
- PartialView
- etc
## Properties
There are two ways to add a property:
```xml
<Label Text="This is a demo"/>
```
```xml
<Label>
<att.Text>This is a demo</att.Text>
</Label>
```
If the object assigned to a property cannot be written as a string, the second way is the only way to do that, for example:
```xml
<Label>
</Label>
```
To access properties in the nested level, the `-set` binding is required:
```xml
<Label>
<att.BoundsComposition-set AlignmentToParent="left:0 top:0 right:0 bottom:0"/>
</Label>
```
This example changes the property `AlignmentToParent` to the object in label's `BoundsComposition` property.
If a property name looks like `Name-binding`, it means the property `Name` should interpret the content using the specified way `-binding`. There are more predefined bindings like `-ref`, `-uri`, `-eval`, `-bind`, etc.
## Events
An event is subscribed like:
```xml
<Button>
<ev.Clicked-eval><![CDATA[{
// some code
}]]></ev.Clicked-eval>
</Button>
```
It means when button's `Clicked` event happens, execute some code.
Code in an event of in the `<Workflow>` resource item should be Workflow Script instead of C++.
.github/Guidelines/Running-CLI.md
+3
View File
@@ -0,0 +1,3 @@
# Running a CLI Application Project
(to edit ...)
.github/Guidelines/Running-GacUI.md
+3
View File
@@ -0,0 +1,3 @@
# Running a GacUI Application Project
(to edit ...)
.github/Guidelines/Running-UnitTest.md
+56
View File
@@ -0,0 +1,56 @@
# Running a Unit Test Project
- Only run `copilotExecute.ps1` to run a unit test project.
- DO NOT call executables or scripts yourself.
## Executing copilotExecute.ps1
`PROJECT-NAME` is the name of the project.
Before testing, ensure the debugger has stopped.
If there is any error message, it means the debugger is not alive, it is good.
```
& REPO-ROOT\.github\Scripts\copilotDebug_Stop.ps1
```
And then run test cases in `SOLUTION-ROOT\PROJECT-NAME\PROJECT-NAME.vcxproj`:
```
cd SOLUTION-ROOT
& REPO-ROOT\.github\Scripts\copilotExecute.ps1 -Executable PROJECT-NAME
```
## Ensure Expected Test Files are Selected
Test cases are organized in multiple test files.
In `PROJECT-NAME\PROJECT-NAME.vcxproj.user` there is a filter, when it is effective, you will see filtered test files marked with `[SKIPPED]` in `Execute.log`.
The filter is defined in this XPath: `/Project/PropertyGroup@Condition="'$(Configuration)|$(Platform)'=='Debug|x64'"/LocalDebuggerCommandArguments`.
The filter is effective only when the file exists and the element exists with one or multiple `/F:FILE-NAME.cpp`, listing all test files to execute, unlisted files are skipped.
If the element exists but there is no `/F:FILE-NAME.cpp`, it executes all test files, none is skipped.
**IMPORTANT**:
ONLY WHEN test files you want to run is skipped, you can edit `PROJECT-NAME\PROJECT-NAME.vcxproj.user` to activate your filter.
- This would typically happen when:
- A new test file is added.
- A test file is renamed.
You can clean up the filter to remove unrelated files that are either not existing or are totally unrelated to the current task you are working on.
If the current task does not work on that test file, but it tests a closely related topic, you should better keep it in the list.
DO NOT delete this `*.vcxproj.user` file.
DO NOT clean the filter (aka delete all `/FILE-NAME.cpp`) by yourself. I put a filter there because running everything is slow and unnecessary for the current task.
Ignore `LocalDebuggerCommandArgumentsHistory` in `*.vcxproj.user`.
## The Correct Way to Read Test Result
- The only source of trust is the raw output of the unit test process.
- Wait for the script to finish before reading the log file.
- DO NOT need to read the output from the script.
- Testing takes a long time. DO NOT hurry.
- When the script finishes, the result is saved to `REPO-ROOT/.github/Scripts/Execute.log`.
- A temporary file `Execute.log.unfinished` is created during testing. It will be automatically deleted as soon as the testing finishes. If you see this file, it means the testing is not finished yet.
- When all test cases pass, the last several lines of `Execute.log` should be in the following pattern; otherwise it crashed at the last shown test case:
- "Passed test files: X/X"
- "Passed test cases: Y/Y"
.github/Guidelines/SourceFileManagement.md
+16
View File
@@ -0,0 +1,16 @@
# Solution and Project File Structure
- A solution file (`*.sln` or `*.slnx`) contains multiple project files.
- Typical C++ project files are XML files in `*.vcxproj` or `*.vcxitems` naming.
- The XML file `*.vcxitems.filters` or `*.vcxproj.filters` organizes source files in solution explorer folders (virtual folders) that could be different from physical file system, which creates a human friendly view.
- The XML file `*.vcxproj.user` contains some temporary local configuration for a project. This file is not tracked by git, but it contains arguments for running the project.
- When adding a source file to a specific solution explorer folder:
- It must be also added to one or multiple project files.
- Find the `*.vcxitems.filters` or `*.vcxproj.filters` file with the same name.
- Each file must be attached to a solution explorer folder, described in this XPath: `/Project/ItemGroup/ClCompile@Include="PhysicalFile"/Filter`.
- Inside the `Filter` tag there is the solution explorer folder.
- Edit that `*.vcxitems.filters` or `*.vcxproj.filters` file to include the source file.
## Renaming and Removing Source Files
- All affected `*.vcxitems`, `*.vcxproj`, `*.vcxitems.filters` and `*.vcxproj.filters` must be updated.