diff --git a/.github/KnowledgeBase/Index.md b/.github/KnowledgeBase/Index.md index fe15f721..709f1bd4 100644 --- a/.github/KnowledgeBase/Index.md +++ b/.github/KnowledgeBase/Index.md @@ -136,6 +136,11 @@ Detailed project guidance: [Index_GacUI.md](./Index_GacUI.md) - [Using Streams](./manual/vlppos/using-streams.md) - [Using Threads and Locks](./manual/vlppos/using-threads.md) +- [Using Inter-Process Channels](./manual/vlppos/using-inter-process.md) + +## Vlpp Reflection + +- [Registration Macros and Attributes](./manual/vlppreflection/registration-macros.md) ## Vlpp Parser2 @@ -188,6 +193,9 @@ Detailed project guidance: [Index_GacUI.md](./Index_GacUI.md) - [Example: Calculator](./manual/workflow/lang/state_calculator.md) - [Index of Keywords](./manual/workflow/lang/index.md) - [Index of Errors](./manual/workflow/lang/error.md) +- [Attributes](./manual/workflow/attributes.md) +- [RPC](./manual/workflow/rpc.md) + - [JSON RPC Channel Setup](./manual/workflow/rpc/json-channel.md) - [Runtime Instructions](./manual/workflow/ins.md) - [C++ Code Generation](./manual/workflow/codegen.md) @@ -331,7 +339,20 @@ Detailed project guidance: [Index_GacUI.md](./Index_GacUI.md) - [Hosted Mode and Remote Protocol](./manual/gacui/modes/home.md) - [Remote Protocol Core Application](./manual/gacui/modes/remote_core.md) - [Remote Protocol Client Application](./manual/gacui/modes/remote_client.md) - - [Implementing a Communication Protocol](./manual/gacui/modes/remote_communication.md) + - [Remote Protocol Channel Layer](./manual/gacui/modes/remote_communication.md) +- Coding Agent Supports + - [AutomationService](./manual/gacui/coding-agent/automation-service.md) + +## Working with Coding Agent + +- Installing required tools + - [Windows](./manual/coding-agent/installing/windows.md) + - [Linux](./manual/coding-agent/installing/linux.md) + - [macOS](./manual/coding-agent/installing/macos.md) +- [Preparing Context Files](./manual/coding-agent/context.md) + - [Writing Project.md](./manual/coding-agent/project-md.md) +- [Investigate and Refine Jobs](./manual/coding-agent/jobs.md) +- [AutomationService and Basic Computer Use](./manual/coding-agent/gacui-debugging.md) ## Unit Testing diff --git a/.github/KnowledgeBase/manual/coding-agent/context.md b/.github/KnowledgeBase/manual/coding-agent/context.md new file mode 100644 index 00000000..4c664c77 --- /dev/null +++ b/.github/KnowledgeBase/manual/coding-agent/context.md @@ -0,0 +1,22 @@ +# Preparing Context Files + +Copy the coding-agent context from the Release repository into the root of the application repository. The minimum copied set is: +- `.github`: prompts, guidelines, scripts, Linux build helpers, local learning files, task-log files, and the copied knowledge base. +- `AGENTS.md`: common entry instructions used by Codex and other agents that read this file. +- `CLAUDE.md`: the same entry instructions for Claude-style agents. +- `Project.md`: application-specific repository map and verification policy, written by the application owner. + +The copied `.github` folder contains several kinds of files: +- `copilot-instructions.md`: the main instruction file. It tells the agent to read `Project.md`, use the knowledge base, and prefer provided scripts. +- `Guidelines`: build, run, debug, source-file, coding, and GacUI resource instructions. +- `prompts`: job prompts such as `ask.prompt.md`, `investigate.prompt.md`, `refine.prompt.md`, and `kb.prompt.md`. +- `Scripts`: Windows PowerShell wrappers for building, executing, debugging, and archiving task logs. +- `Ubuntu`: Linux build wrapper and helper commands. +- `KnowledgeBase`: copied API, design, manual, and learning documents that the agent can read without network access. +- `Learning`: project-local lessons that refine future agent behavior. +- `TaskLogs`: working documents for investigation and knowledge-base jobs. + +Keep the copied context files under source control when they describe stable project behavior. Task-log files may be tracked or ignored according to the repository policy, but the files referenced by the prompts should exist before asking the agent to use those prompts. If the application has different build scripts, test commands, project names, generated files, or platform support, update `Project.md` first. + +See [Writing Project.md](.././coding-agent/project-md.md) for the expected contents of the application-specific file. + diff --git a/.github/KnowledgeBase/manual/coding-agent/gacui-debugging.md b/.github/KnowledgeBase/manual/coding-agent/gacui-debugging.md new file mode 100644 index 00000000..932171fb --- /dev/null +++ b/.github/KnowledgeBase/manual/coding-agent/gacui-debugging.md @@ -0,0 +1,28 @@ +# AutomationService and Basic Computer Use + +GacUI applications need an application-level automation path so a coding agent can inspect and operate the UI while debugging. On Windows, the recommended path is to start the GacUI AutomationService HTTP endpoint from the application during startup. This lets the agent read the control tree or remote-renderer DOM and send IO commands without using operating-system UI Automation. + +From the agent user's perspective, this means: +- The application should expose a stable localhost automation URL while it is running. +- The agent should use the automation endpoint for normal GacUI windows and controls. +- The agent should not rely on UI Automation as a fallback, because it can fail when the screen is locked. +- The user can keep using the computer because the agent does not need to drive the physical pointer for normal GacUI operations. + +See [AutomationService](.././gacui/coding-agent/automation-service.md) for the service setup, exact HTTP URLs, setup-function cases, and platform implementation details. + +## When the Agent Gets Blocked + +Application-level automation depends on the application UI thread. A native crash dialog, message box, file dialog, color dialog, or another modal native window can block that thread. When this happens, the agent should stop polling the application automation endpoint and inspect native windows from another process. + +The copied `.github/Guidelines/Running-ComputerUse.md` file explains the unblocking workflow: +- Identify the target process. +- Enumerate top-level and child windows with Win32 APIs. +- Read class names, window text, control ids, and rectangles. +- Prefer direct control messages such as `BM_CLICK`, `WM_SETTEXT`, and combo-box messages. +- Capture a screenshot only when visual confirmation is needed. +- Close or answer the native dialog before returning to AutomationService. + +## Project Preparation + +If the application contains GacUI UI work, mention its automation endpoint in `Project.md`. Include the executable project name, port, URL prefix, whether hosted mode is used, and any native dialogs that commonly appear. This gives the agent enough context to choose AutomationService first and native-window handling only when the application is blocked. + diff --git a/.github/KnowledgeBase/manual/coding-agent/installing/linux.md b/.github/KnowledgeBase/manual/coding-agent/installing/linux.md new file mode 100644 index 00000000..2948dd30 --- /dev/null +++ b/.github/KnowledgeBase/manual/coding-agent/installing/linux.md @@ -0,0 +1,20 @@ +# Installing Required Tools on Linux + +The Linux agent workflow is driven by `.github/Ubuntu/build.sh`. It adds `.github/Ubuntu/vl/cmd` to `PATH`, runs `vmake --make`, and then builds with `vbuild`. The agent instructions deliberately route builds through this script instead of direct `cmake`, `make`, `clang++`, `g++`, or `gdb` calls. + +Prepare a Linux environment with a C++ compiler toolchain, Bash, and LLDB. After copying the Release `.github` folder, make the copied scripts executable if the checkout blocks execution bits: +```bash +chmod +x .github/Ubuntu/build.sh +chmod +x .github/Ubuntu/vl/cmd/* +``` + +Build from the folder that contains the target `vmake` file: +- For a repository with one Linux project, use `REPO-ROOT/Test/Linux`. +- For a repository with multiple Linux projects, use `REPO-ROOT/Test/Linux/PROJECT-NAME`. +- Run `REPO-ROOT/.github/Ubuntu/build.sh` for an incremental build. +- Run `REPO-ROOT/.github/Ubuntu/build.sh -f` for a full rebuild. + +Linux debug work should use `lldb` in an interactive terminal session. The copied guidelines expect the agent to start LLDB from the same folder that contains the `vmake` file so relative paths to binaries and source files remain correct. + +If the application uses Release tools, run `Release/Tools/BuildExecutables.sh` in the Release repository. It produces `CodePack`, `CppMerge`, `GacGen`, and `GlrParserGen` under `Release/Tools`. + diff --git a/.github/KnowledgeBase/manual/coding-agent/installing/macos.md b/.github/KnowledgeBase/manual/coding-agent/installing/macos.md new file mode 100644 index 00000000..77321f4e --- /dev/null +++ b/.github/KnowledgeBase/manual/coding-agent/installing/macos.md @@ -0,0 +1,4 @@ +# Installing Required Tools on macOS + +(to be editing...) + diff --git a/.github/KnowledgeBase/manual/coding-agent/installing/windows.md b/.github/KnowledgeBase/manual/coding-agent/installing/windows.md new file mode 100644 index 00000000..e53ccbe7 --- /dev/null +++ b/.github/KnowledgeBase/manual/coding-agent/installing/windows.md @@ -0,0 +1,21 @@ +# Installing Required Tools on Windows + +The Windows agent scripts build with MSBuild through Visual Studio's developer environment and debug with CDB. Install Visual Studio with the C++ desktop workload, a Windows SDK, and the Windows debugging tools that provide `cdb.exe`. If CDB is not available, install the Windows Driver Kit or the Windows debugging tools component from the Visual Studio Installer. + +Define these environment variables before asking the agent to build or debug: +- `VLPP_VSDEVCMD_PATH`: absolute path to `VsDevCmd.bat`, for example `C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\VsDevCmd.bat`. +- `CDBPATH`: absolute path to `cdb.exe`, for example `C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\cdb.exe`. + +After copying the Release `.github` folder, the agent should use these scripts instead of calling tools directly: +- `.github\Scripts\copilotBuild.ps1`: builds the solution found from `Project.md` context and writes `Build.log`. +- `.github\Scripts\copilotExecute.ps1`: runs unit-test or CLI projects and writes `Execute.log` for unit tests. +- `.github\Scripts\copilotDebug_Start.ps1` and `copilotDebug_RunCommand.ps1`: start CDB and send debugger commands. + +If the application uses the tools shipped by Release, build them from the Release repository: +- Open `Tools\Executables\Executables.sln` in Visual Studio. +- Build `Release` with `x64`. +- Run `Tools\CopyExecutables.ps1`. +- Confirm `CodePack.exe`, `CppMerge.exe`, `GacGen.exe`, and `GlrParserGen.exe` exist in `Release\Tools`. + +For debugger readability, copy `Import\vlpp.natvis` from Release to Visual Studio's visualizers folder. The CDB startup script also loads the natvis file for debugger commands such as `dx`. + diff --git a/.github/KnowledgeBase/manual/coding-agent/jobs.md b/.github/KnowledgeBase/manual/coding-agent/jobs.md new file mode 100644 index 00000000..2a1e69c6 --- /dev/null +++ b/.github/KnowledgeBase/manual/coding-agent/jobs.md @@ -0,0 +1,28 @@ +# Investigate and Refine Jobs + +`AGENTS.md` and `CLAUDE.md` route short request keywords to prompt files in `.github/prompts`. These jobs make agent work repeatable because the agent writes durable task documents, uses the copied knowledge base, and follows the repository's build and debug scripts. + +## investigate + +Use `investigate` for coding work that needs analysis, implementation, verification, and a record of decisions. It is not limited to bug fixing. It can handle new features, refactoring, behavior changes, regressions, and deep research that may end in source edits. + +Common request forms are: +- `investigate repro ...`: start a fresh task and copy the problem or feature request into `Copilot_Investigate.md`. +- `investigate continue ...`: append an update to the current investigation and continue from the existing proposals. +- `investigate report ...`: ask the agent to summarize confirmed proposals and tradeoffs. + +The job writes `.github/TaskLogs/Copilot_Investigate.md`. It records the problem description, tests or confirmation criteria, proposed solutions, code changes, and confirmation or denial for each proposal. The prompt expects the agent to build, run tests, and debug when needed. + +## refine + +Use `refine` after completed work has produced task logs that contain reusable lessons. The job reads archived task documents, extracts user preferences and project-specific lessons, and writes them to: +- `.github/KnowledgeBase/Learning.md`: general learnings across projects. +- `.github/Learning/Learning_Coding.md`: source-code learnings for this repository. +- `.github/Learning/Learning_Testing.md`: test-code and verification learnings for this repository. + +The refine job is intentionally document-only. It should not modify source code. It is useful when a correction, review discussion, or debugging result should influence future agent behavior. + +## Other Keywords + +The copied context also includes `ask` for analysis-only questions and `kb` for drafting or updating knowledge-base documents. If a user request does not start with a known keyword, the root instructions classify ordinary coding work as an `investigate repro` style task. + diff --git a/.github/KnowledgeBase/manual/coding-agent/project-md.md b/.github/KnowledgeBase/manual/coding-agent/project-md.md new file mode 100644 index 00000000..837fe898 --- /dev/null +++ b/.github/KnowledgeBase/manual/coding-agent/project-md.md @@ -0,0 +1,64 @@ +# Writing Project.md + +`Project.md` is the repository map that tells the agent where to build, what to run, which generated files are protected, and which platform folders matter. The Release copy only points to the GacUI example; an application repository should replace it with concrete project facts. + +## Recommended Shape + +A useful `Project.md` usually contains: +- Solution to work on: the solution file and the meaning of `SOLUTION-ROOT`. +- Projects for verification: unit-test, CLI, code-generation, metadata, or UI projects that must run after relevant changes. +- Execution order: required ordering when one project generates files consumed by another project. +- Files not allowed to modify directly: generated folders, imported dependencies, released binaries, and generated baselines. +- Code generation triggers: which files require running generators and which outputs they refresh. +- Platform notes: Linux `Test/Linux` folders, unsupported platforms, special tools, and available configurations. +- Application-specific debugging notes: services, ports, sample data, dialogs, or local servers that matter for the app. + +## Small Application Example + +A small GacUI application can use this shape: +```markdown +# Project Specific Instruction + +## Solution to Work On + +You are working on the solution `REPO-ROOT/App/App.sln`, +therefore `SOLUTION-ROOT` is `REPO-ROOT/App`. + +## Projects for Verification + +The `REPO-ROOT/App/AppTests/AppTests.vcxproj` project is the unit test project. +When any `*.h`, `*.cpp`, `*.xml`, or Workflow script file is changed, build the solution +and run `AppTests`. + +The `REPO-ROOT/App/App/App.vcxproj` project is the interactive GacUI application. +Run it when the change affects windows, dialogs, command routing, or application startup. + +## Files not Allowed to Modify + +Files in these folders are generated and must not be edited directly: +- `REPO-ROOT/App/Generated` +- `REPO-ROOT/App/Resources/Compiled` + +Fix the source resource or generator input instead. + +## Code Generation + +If `REPO-ROOT/App/Resources/*.xml` changes, run `GacGen` through the project build. +If generated files change, rebuild and run `AppTests`. + +## Linux Specific + +This repository has no Linux build for the application. +Do not try to create one unless the task explicitly asks for it. +``` + +## Large Repository Patterns + +The library repositories use the same idea with more detail: +- Vlpp, VlppOS, and VlppRegex define one unit-test solution and one Linux folder. +- VlppReflection adds metadata generation and metadata round-trip tests when reflection types change. +- VlppParser2 and Workflow list ordered generator and test projects because later projects consume files produced by earlier projects. +- GacUI lists generated folders, reflection metadata projects, GacUI compiler triggers, remote protocol generation, AutomationService-enabled applications, and Linux project folders. + +Use these examples as patterns, not templates to copy blindly. The important part is that every instruction names the exact project, folder, generated output, or trigger that applies to the application repository. + diff --git a/.github/KnowledgeBase/manual/gacui/advanced/alt.md b/.github/KnowledgeBase/manual/gacui/advanced/alt.md index d1af8dd2..e9d71910 100644 --- a/.github/KnowledgeBase/manual/gacui/advanced/alt.md +++ b/.github/KnowledgeBase/manual/gacui/advanced/alt.md @@ -1,14 +1,14 @@ # ALT Sequence and Control Focus -If a focusable control is put on a window, by setting the[Alt](../.././gacui/components/controls/basic/home.md)property to a value, for example "X", then it could get focused by pressing**ALT**followed by**X**(not**ALT+X**). +If a focusable control is put on a window, by setting the [Alt](../.././gacui/components/controls/basic/home.md) property to a value, for example "X", then it could get focused by pressing **ALT** followed by **X** (not **ALT+X**). -The**Alt**property could accept a sequence of characters, not just one. Characters in such a sequence needs to be entered to activate this control. +The **Alt** property could accept a sequence of characters, not just one. Characters in such a sequence needs to be entered to activate this control. -If**ESC**is pressed, it goes back to the previous container. +If **ESC** is pressed, it goes back to the previous container. -If**BACKSPACE**is pressed, it cancels the last character in the sequence. +If **BACKSPACE** is pressed, it cancels the last character in the sequence. -When**ALT**is pressed, all valid**ALT**sequences will be printed on the window. All labels rendering these sequences will get changed +When **ALT** is pressed, all valid **ALT** sequences will be printed on the window. All labels rendering these sequences will get changed ## Example @@ -16,7 +16,7 @@ When**ALT**is pressed, all valid**ALT**sequences will be printed on the window. The operation is done by pressing the following keys: - **ALT**: Enter the ALT sequence mode. -- **P**: There are two controls with the**Alt**property set to "P". It filters them out and wait for a number key. +- **P**: There are two controls with the **Alt** property set to "P". It filters them out and wait for a number key. - **0**: The dropdown button is activated, a sub menu is opened. - **ESC**: Close the sub menu and go back to the previous container, which is the window. - **P**: Filter again. @@ -30,49 +30,49 @@ The operation is done by pressing the following keys: ## Behavior after being Focused -There are three kinds of behaviors when a control is focused by a**ALT**sequence. If a control is focused by**TAB**, it could behaves differently. +There are three kinds of behaviors when a control is focused by a **ALT** sequence. If a control is focused by **TAB**, it could behaves differently. - `empty list item` **Just being focused** Controls with complex keyboard behaviors like editors or list controls, will just get focused and do nothing else. - `empty list item` **Execute a Command** - Controls with simple executable behaviors like buttons, will do what it does when clicked, after being focused by an**ALT**sequence. + Controls with simple executable behaviors like buttons, will do what it does when clicked, after being focused by an **ALT** sequence. - `empty list item` **Just being focused** - Controls that are not executable but contains executable items, like menu items with a sub menu, will render all executable items after being focused by an**ALT**sequence. - A menu item with a sub menu does nothing when it is clicked. But if it is activated by an**ALT**sequence, the sub menu will be opened and wait for more keys. + Controls that are not executable but contains executable items, like menu items with a sub menu, will render all executable items after being focused by an **ALT** sequence. + A menu item with a sub menu does nothing when it is clicked. But if it is activated by an **ALT** sequence, the sub menu will be opened and wait for more keys. ## Create your own Behavior -If a new control class is created, there are multiple ways to customize the behavior about how a control should react to an**ALT**sequence: +If a new control class is created, there are multiple ways to customize the behavior about how a control should react to an **ALT** sequence: ### Using IGuiAltAction -**IGuiAltAction**is a protected base class of all controls. If a new control is created, methods could be overriden. +**IGuiAltAction** is a protected base class of all controls. If a new control is created, methods could be overriden. -Properly assigning an**ALT**sequence to the**Alt**property of a control could also make these methods behave as expected easily.**IsAltEnabled**returns**true**if the control is visible and enabled.**IsAltAvailable**returns**true**if the control is focusable and the**Alt**property is not empty. +Properly assigning an **ALT** sequence to the **Alt** property of a control could also make these methods behave as expected easily. **IsAltEnabled** returns **true** if the control is visible and enabled. **IsAltAvailable** returns **true** if the control is focusable and the **Alt** property is not empty. -When the window is in the**ALT**sequence mode, a label rendering the sequence for this control will be put in the composition from**GetAltComposition**. +When the window is in the **ALT** sequence mode, a label rendering the sequence for this control will be put in the composition from **GetAltComposition**. -If both**IsAltEnabled**and**IsAltAvailable**returns**true**, then the result of**GetAlt()**, which is also the value from the**Alt**property by default, becomes one of an candidate.**OnActiveAlt**will be called when this control is selected by a**ALT**sequence. +If both **IsAltEnabled** and **IsAltAvailable** returns **true**, then the result of **GetAlt()**, which is also the value from the **Alt** property by default, becomes one of an candidate. **OnActiveAlt** will be called when this control is selected by a **ALT** sequence. ### Using IGuiAltActionContainer -**IGuiAltActionContainer**is a[service object](../.././gacui/components/controls/basic/home.md). A service object could be attached to a control by calling**AddService**or overriding**QueryService**. +**IGuiAltActionContainer** is a [service object](../.././gacui/components/controls/basic/home.md). A service object could be attached to a control by calling **AddService** or overriding **QueryService**. -If an**IGuiAltActionContainer**instance is attached to a control, then all methods in**IGuiAltAction**are ignored. Instead, multiple**IGuiAltAction**object returned from this interface will be used. +If an **IGuiAltActionContainer** instance is attached to a control, then all methods in **IGuiAltAction** are ignored. Instead, multiple **IGuiAltAction** object returned from this interface will be used. -You could now assign multiple**ALT**sequence to a control, with each sequence binded to a different behavior. +You could now assign multiple **ALT** sequence to a control, with each sequence binded to a different behavior. -All**IGuiAltAction**returned from**IGuiAltActionContainer**must be enabled and available. +All **IGuiAltAction** returned from **IGuiAltActionContainer** must be enabled and available. ### Using IGuiAltActionHost -An**IGuiAltActionHost**instance could be attached to a control by calling**SetActivatingAltHost**or overriding**GetActivatingAltHost**. +An **IGuiAltActionHost** instance could be attached to a control by calling **SetActivatingAltHost** or overriding **GetActivatingAltHost**. -When a control is selected by a**ALT**sequence, if**IGuiAltActionHost**is attached to this control, then the**ALT**sequence mode will not exit. Instead, this**IGuiAltActionHost**is treated as a nested container, and GacUI calls**CollectAltActions**to collect all valid**IGuiAltAction**, renders all**ALT**and wait for keyboard input. +When a control is selected by a **ALT** sequence, if **IGuiAltActionHost** is attached to this control, then the **ALT** sequence mode will not exit. Instead, this **IGuiAltActionHost** is treated as a nested container, and GacUI calls **CollectAltActions** to collect all valid **IGuiAltAction**, renders all **ALT** and wait for keyboard input. -All top level controls like a window or a menu are attached by an**IGuiAltActionHost**by default. If a sub menu is created on a menu item,**IGuiAltActionHost**is attached to this control. So when it is activated, it opens the sub menu and continue to wait for more keys, instead of executing this menu item. +All top level controls like a window or a menu are attached by an **IGuiAltActionHost** by default. If a sub menu is created on a menu item, **IGuiAltActionHost** is attached to this control. So when it is activated, it opens the sub menu and continue to wait for more keys, instead of executing this menu item. -**GuiAltActionHostBase**is the default implementation of**IGuiAltActionHost**. If it is attached to a control, all child controls with valid**IGuiAltAction**are not visible from the container, instead they are available when the parent control is selected by an**ALT**sequence.**GuiAltActionHostBase::SetAltControl**must be called to initialize this class, it tells this implementation where to search for child controls to collect**IGuiAltAction**. +**GuiAltActionHostBase** is the default implementation of **IGuiAltActionHost**. If it is attached to a control, all child controls with valid **IGuiAltAction** are not visible from the container, instead they are available when the parent control is selected by an **ALT** sequence. **GuiAltActionHostBase::SetAltControl** must be called to initialize this class, it tells this implementation where to search for child controls to collect **IGuiAltAction**. diff --git a/.github/KnowledgeBase/manual/gacui/advanced/animations.md b/.github/KnowledgeBase/manual/gacui/advanced/animations.md index 2696d6bf..c66a49b8 100644 --- a/.github/KnowledgeBase/manual/gacui/advanced/animations.md +++ b/.github/KnowledgeBase/manual/gacui/advanced/animations.md @@ -1,6 +1,6 @@ # Animations -The GacUI XML[](../.././gacui/xmlres/tag_animation.md)resource creates helper classes for animations. It creates a class like this: +The GacUI XML [](../.././gacui/xmlres/tag_animation.md) resource creates helper classes for animations. It creates a class like this: ``` class MyAnimation { @@ -9,7 +9,7 @@ class MyAnimation func CreateAnimation(target: STATE_CLASS^, time: UInt64); } ``` -**STATE_CLASS**is a class with fields of number types or**Color**. By creating an**MyAnimation^**in a window like this: +**STATE_CLASS** is a class with fields of number types or **Color**. By creating an **MyAnimation^** in a window like this: ``` ``` -You are able to bind the expression**self.myAnimation.Current.FIELD**to any compatible property. When the animation is running, fields in**self.myAnimation.Current**will keep updating, so that to animate the UI. + You are able to bind the expression **self.myAnimation.Current.FIELD** to any compatible property. When the animation is running, fields in **self.myAnimation.Current** will keep updating, so that to animate the UI. ## Interpolation Functions -The first step to animate a field in**self.myAnimation.Current**is to set a proper interpolation function, which is described in[](../.././gacui/xmlres/tag_animation.md). Only fields that mentioned by a**\**tag could be animated. All animated fields must associate an interpolation function. There is also a place for a default interpolation function, which will apply on all animated fields unless one is specified in**\**. +The first step to animate a field in **self.myAnimation.Current** is to set a proper interpolation function, which is described in [](../.././gacui/xmlres/tag_animation.md). Only fields that mentioned by a **\** tag could be animated. All animated fields must associate an interpolation function. There is also a place for a default interpolation function, which will apply on all animated fields unless one is specified in **\**. -An interpolation function is an Workflow expression in a function type, which takes a**double**and returns a**double**. +An interpolation function is an Workflow expression in a function type, which takes a **double** and returns a **double**. -The function parameter is the progress of the animation from**0**to**1**. If an animation is 10 seconds long, then**0**is the beginning,**1**is the ending, and**0.4**means**10 seconds * 0.4**which is at the end of the 4th second. +The function parameter is the progress of the animation from **0** to **1**. If an animation is 10 seconds long, then **0** is the beginning, **1** is the ending, and **0.4** means **10 seconds * 0.4** which is at the end of the 4th second. -The return value is the interpolation of the animation from**0**to**1**. If the begin state is**5**and the end state is**15**, then returning**0**means**5**, returning**1**means**15**, and returning**0.4**means the**5 + (15 - 5) * 0.4**which is**9**. +The return value is the interpolation of the animation from **0** to **1**. If the begin state is **5** and the end state is **15**, then returning **0** means **5**, returning **1** means **15**, and returning **0.4** means the **5 + (15 - 5) * 0.4** which is **9**. The interpolation calculate that, where a field should go given the progress of the animation. If a linear interpolation function is expected, then just return the parameter. Such a function would typically be: -- for[ordered lambda expression](../.././workflow/lang/expr.md):**[$1]** -- for[lambda expression](../.././workflow/lang/expr.md): for example:**func (progress: double) : double { return progress; }**Sometimes it is better to make the field accelerate at the first half and decelerate at the second half, such a function could be easily created using: +- for [ordered lambda expression](../.././workflow/lang/expr.md) : **[$1]** +- for [lambda expression](../.././workflow/lang/expr.md) : for example: **func (progress: double) : double { return progress; }** Sometimes it is better to make the field accelerate at the first half and decelerate at the second half, such a function could be easily created using: ``` func (x: double): double { @@ -42,16 +42,15 @@ func (x: double): double } ``` - ## Running an Animation -In the**\**generated class, there is a**CreateAnimation(state, time)**function, which means the animation begins from the current state, and run towards**state**in**time**milliseconds. +In the **\** generated class, there is a **CreateAnimation(state, time)** function, which means the animation begins from the current state, and run towards **state** in **time** milliseconds. -Calling this function doesn't make the animation run, instead it returns an**(vl::)presentation::controls::IGuiAnimation^**object.**AddAnimation**and**KillAnimation**of**(vl::)presentation::controls::GuiInstanceRootObject**controls how the animation run. This class is the base class for all UI[root instances](../.././gacui/xmlres/instance/root_instance.md), so**AddAnimation**and**KillAnimation**, or**self.AddAnimation**and**self.KillAnimation**, are accessible in the XML. +Calling this function doesn't make the animation run, instead it returns an **(vl::)presentation::controls::IGuiAnimation^** object. **AddAnimation** and **KillAnimation** of **(vl::)presentation::controls::GuiInstanceRootObject** controls how the animation run. This class is the base class for all UI [root instances](../.././gacui/xmlres/instance/root_instance.md), so **AddAnimation** and **KillAnimation**, or **self.AddAnimation** and **self.KillAnimation**, are accessible in the XML. -**AddAnimation**adds an**IGuiAnimation**object to the UI object, and start the animation immediately. +**AddAnimation** adds an **IGuiAnimation** object to the UI object, and start the animation immediately. -**KillAnimation**stops an**IGuiAnimation**object that has been added to the UI object, and stop the animation immediately. +**KillAnimation** stops an **IGuiAnimation** object that has been added to the UI object, and stop the animation immediately. For animations that need to switch from state to state for multiple times, like a button when the mouse is moving in and out, there is a pattern to control the animation: ``` @@ -65,25 +64,24 @@ KillAnimation(lastAnimation); lastAnimation = newAnimation; AddAnimation(lastAnimation); ``` -When the state needs to move to a new state when the animation is running, this piece of code stops the current running animation, and replace it with a new one. The new animation moves the current state from where it is to a new state, and it should look smooth. + When the state needs to move to a new state when the animation is running, this piece of code stops the current running animation, and replace it with a new one. The new animation moves the current state from where it is to a new state, and it should look smooth. -**KillAnimation**could accept**null**, and it does nothing. +**KillAnimation** could accept **null**, and it does nothing. ## Managing Multiple Animations It is easy to copy the above pattern multiple times for each animation. -Please remember that, the created**lastAnimation**will change**myAnimation.Current.FIELD**when it is executing, so if multiple animation needs to run at the same time, multiple**lastAnimation**and**myAnimation**should be created at the same time. Please give them good names to make the code looks clear. +Please remember that, the created **lastAnimation** will change **myAnimation.Current.FIELD** when it is executing, so if multiple animation needs to run at the same time, multiple **lastAnimation** and **myAnimation** should be created at the same time. Please give them good names to make the code looks clear. -When a UI object is disposing, e.g. when the close button on a window is clicked, all animations will be shut down, and calling**AddAnimation**will result in an exception. +When a UI object is disposing, e.g. when the close button on a window is clicked, all animations will be shut down, and calling **AddAnimation** will result in an exception. It is function idential to split all fields to multiple animation objects. But if multiple fields represent different parts of the same animation, do your best to make one animation for all these fields to increase the performance. -In[this tutorial project](https://github.com/vczh-libraries/Release/blob/master/SampleForDoc/GacUI/XmlRes/kb_animation/Resource.xml), a button is controlled by 4 colors, which changes in one animation because they represent different parts of the same animation. So only one**\**and only one instance of it is needed for one button. +In [this tutorial project](https://github.com/vczh-libraries/Release/blob/master/SampleForDoc/GacUI/XmlRes/kb_animation/Resource.xml), a button is controlled by 4 colors, which changes in one animation because they represent different parts of the same animation. So only one **\** and only one instance of it is needed for one button. Here is how it looks like: - -- Source code:[kb_animation](https://github.com/vczh-libraries/Release/blob/master/SampleForDoc/GacUI/XmlRes/kb_animation/Resource.xml) +- Source code: [kb_animation](https://github.com/vczh-libraries/Release/blob/master/SampleForDoc/GacUI/XmlRes/kb_animation/Resource.xml) - ![](https://gaclib.net/doc/gacui/kb_animation.gif) diff --git a/.github/KnowledgeBase/manual/gacui/advanced/bindings.md b/.github/KnowledgeBase/manual/gacui/advanced/bindings.md index 3d073eca..565c5374 100644 --- a/.github/KnowledgeBase/manual/gacui/advanced/bindings.md +++ b/.github/KnowledgeBase/manual/gacui/advanced/bindings.md @@ -1,23 +1,22 @@ # Data Bindings -Data bindings in GacUI relies on[Workflow expression](../.././workflow/lang/bind.md). Basically, an expression is observable if it uses properties, and these properties must be observable by having their property changing events on the object. You are still able to combine some events on a property temporary just for this expression to make it observable. +Data bindings in GacUI relies on [Workflow expression](../.././workflow/lang/bind.md). Basically, an expression is observable if it uses properties, and these properties must be observable by having their property changing events on the object. You are still able to combine some events on a property temporary just for this expression to make it observable. -In GacUI XML Resource,[-bind](../.././gacui/xmlres/instance/properties.md),[-format](../.././gacui/xmlres/instance/properties.md)and[-str](../.././gacui/xmlres/instance/properties.md)are based on data bindings. +In GacUI XML Resource, [-bind](../.././gacui/xmlres/instance/properties.md), [-format](../.././gacui/xmlres/instance/properties.md) and [-str](../.././gacui/xmlres/instance/properties.md) are based on data bindings. ## Binding to Control Properties This is the most basic kind of data binding. -If you are binding something to a text property which will be displayed on the UI, e.g.**Text**of a**\