GacUI/.github/KnowledgeBase/KB_VlppReflection_StructRegistration.md

Struct Registration

Registration patterns for structure types with field access capabilities.

VlppReflection provides specific macros for registering structure types, enabling runtime access to struct fields through the reflection system. This allows structures to be used in dynamic programming scenarios while maintaining their value-type semantics.

Basic Struct Registration

Registration Pattern

• Use BEGIN_STRUCT_MEMBER and END_STRUCT_MEMBER for struct registration
• Provides the foundation for making struct types accessible through reflection
• Enables dynamic field access and manipulation

BEGIN_STRUCT_MEMBER(MyStruct)
    STRUCT_MEMBER(FirstField)
    STRUCT_MEMBER(SecondField)
END_STRUCT_MEMBER(MyStruct)

Field Registration

• Use STRUCT_MEMBER to register each accessible field
• Each field registered becomes accessible through the reflection system
• Supports both reading and writing field values dynamically

Registration Requirements

Struct Definition

The struct must be properly defined and accessible:

• Must be a valid C++ struct type
• Fields to be registered must be public members
• Should follow value-type semantics

Field Accessibility

• Only register fields that should be accessible through reflection
• Private and protected fields cannot be registered directly
• Consider data encapsulation principles when choosing which fields to expose

Usage Example

Register a struct like this:

BEGIN_STRUCT_MEMBER(MyStruct)
    STRUCT_MEMBER(FirstField)
    STRUCT_MEMBER(SecondField)
END_STRUCT_MEMBER(MyStruct)

This registration pattern enables:

• Dynamic field access by name
• Type-safe field value retrieval and assignment
• Integration with the broader reflection system
• Use in Workflow scripts and other dynamic contexts

Extra Content

Advanced Registration Scenarios

Complex Field Types

Struct fields can be of various types:

• Primitive types (int, double, bool, etc.)
• String types (WString, etc.)
• Other registered structs
• Enum types

Nested Structs

When registering structs that contain other struct types:

1. Register the nested struct types first
2. Then register the containing struct
3. The reflection system will automatically handle the relationships

Read-Only Fields

While STRUCT_MEMBER typically requires both reading and writing:

• Some fields may be conceptually read-only
• Consider the design implications of exposing mutable access
• Document field mutability expectations clearly

Best Practices

1. Selective Registration: Only register fields that need dynamic access
2. Type Consistency: Ensure all field types are also properly registered
3. Documentation: Document the purpose and constraints of registered fields
4. Testing: Verify registration works correctly with dynamic access patterns

Performance Considerations

• Struct registration has minimal overhead at registration time
• Dynamic field access is slightly slower than direct access
• Consider performance implications for frequently accessed fields
• Batch operations when possible for better performance

Integration with Other Systems

Registered structs can be used with:

• Workflow script language
• GacUI data binding
• Serialization systems
• Dynamic configuration systems