====== WvdS VSCode UI Designer ======

The UI Designer enables visual PXAML development in VS Code - a WYSIWYG editor for Pascal-based user interfaces.

===== Function and Purpose =====

The Designer provides:

  * **Visual Editor** - Drag-and-drop UI design
  * **PXAML Syntax** - WPF/XAML-compatible markup for Pascal
  * **Live Preview** - Real-time preview during editing
  * **Properties Panel** - Visual property editing
  * **Component Palette** - Overview of available controls

===== What is PXAML? =====

PXAML (Pascal XAML) is an XML-based markup format for user interfaces, inspired by WPF/XAML.

==== Example ====

<code xml>
<Window Title="Hello PXAML" Width="400" Height="300">
  <Grid>
    <Grid.RowDefinitions>
      <RowDefinition Height="Auto"/>
      <RowDefinition Height="*"/>
    </Grid.RowDefinitions>

    <Label Grid.Row="0" Content="Welcome!" FontSize="24"/>

    <StackPanel Grid.Row="1" Orientation="Vertical" Margin="10">
      <TextBox x:Name="txtInput" PlaceholderText="Enter name..."/>
      <Button Content="Greet" Click="OnGreetClick"/>
    </StackPanel>
  </Grid>
</Window>
</code>

==== PXAML vs. LFM ====

^ Aspect ^ PXAML ^ LFM (Lazarus) ^
| Format | XML | Proprietary (Binary or Text) |
| Readability | High | Medium |
| Version Control | Excellent (diff-friendly) | Difficult |
| Designer | WvdS Designer | Lazarus IDE |
| Targets | GUI, TUI, Web | GUI only |

===== Commands =====

^ Command ^ Keyboard Shortcut ^ Description ^
| ''WVDS Designer: New PXAML File'' | - | Creates a new PXAML file |
| ''WVDS Designer: Toggle Designer Preview'' | - | Switches between code and design view |
| ''WVDS Designer: Show Properties Panel'' | - | Shows the properties panel |

===== Working with the Designer =====

==== Creating a PXAML File ====

  - ''Ctrl+Shift+P'' -> ''WVDS Designer: New PXAML File''
  - Enter a name
  - The file is created with a base template

==== Opening Design View ====

When you open a .pxaml file, the designer is automatically activated.

The editor shows:
  * **Design Area** - Visual representation of the UI (left)
  * **Properties Panel** - Properties of the selected element (right)
  * **Toolbox** - Available controls (bottom left)

==== Code View ====

To edit the PXAML source code:
  - Click "Source" in the toolbar
  - Or: Right-click -> "View Source"

==== Adding Components ====

**Via Drag & Drop:**
  - Drag a control from the Toolbox
  - Drop it in the Design area
  - Position it as desired

**Via Code:**
  - Switch to Code view
  - Add the element manually
  - The preview updates automatically

==== Editing Properties ====

  - Select an element in the Designer
  - The Properties panel shows all available properties
  - Change values directly in the panel
  - Changes are immediately shown in the preview

===== PXAML Basics =====

==== Namespaces ====

<code xml>
<Window xmlns="http://schemas.wvds.de/pxaml/2024"
        xmlns:x="http://schemas.wvds.de/pxaml/x/2024"
        xmlns:local="clr-namespace:MyApp">
</Window>
</code>

^ Namespace ^ Usage ^
| Standard (no prefix) | Base controls (Button, TextBox, Grid, ...) |
| x: | Markup extensions (x:Name, x:Key, ...) |
| local: | Custom types from the project |

==== Layout Containers ====

^ Container ^ Description ^
| Grid | Row and column layout |
| StackPanel | Stacks elements horizontally or vertically |
| DockPanel | Docks elements to edges |
| Canvas | Absolute positioning |
| WrapPanel | Wrapping arrangement |

==== Common Controls ====

^ Control ^ Description ^
| Button | Button with click event |
| TextBox | Single-line text input |
| Label | Text display |
| CheckBox | On/off selection |
| ComboBox | Dropdown selection |
| ListBox | List selection |
| Image | Image display |
| Border | Border and background |

==== Data Binding ====

<code xml>
<TextBox Text="{Binding Path=UserName, Mode=TwoWay}"/>
<Label Content="{Binding Path=WelcomeMessage}"/>
</code>

==== Event Handlers ====

<code xml>
<Button Content="Save" Click="OnSaveClick"/>
</code>

The handler is implemented in the code-behind unit:

<code pascal>
procedure TMainWindow.OnSaveClick(Sender: TObject);
begin
  // Save logic
end;
</code>

===== Settings =====

The Designer uses the settings of the UI Meta extension for IntelliSense and component information.

===== Multi-Target Rendering =====

PXAML can be rendered for different targets:

^ Target ^ Description ^ Renderer ^
| GUI | Native desktop interface | LCL-based |
| TUI | Terminal interface | Text-based |
| Web | Browser interface | HTML/CSS |

The selection is made at build time, not in the Designer.

===== Troubleshooting =====

==== Designer Shows Empty Page ====

**Cause:** PXAML syntax error or missing components.

**Solution:**
  - Switch to Code view
  - Check the PXAML syntax (XML validation)
  - Ensure all referenced components exist

==== Preview Does Not Update ====

**Cause:** Auto-refresh disabled or error.

**Solution:**
  - Save the file (''Ctrl+S'')
  - Run ''WVDS: Refresh Preview'' manually
  - Check the Output Channel for errors

==== Drag & Drop Does Not Work ====

**Cause:** Wrong area or unsupported container.

**Solution:**
  - Ensure you are dropping in the Design area
  - Check if the target container allows children
  - Some containers (e.g., Border) allow only one child

===== Technical Details =====

^ Property ^ Value ^
| Extension ID | wvds.wvds-vscode-ui-designer |
| Activation | onCustomEditor:wvds.ui.designer.pxaml |
| Dependencies | wvds-vscode-core |
| Min. VS Code | 1.85.0 |
| File Format | .pxaml |

===== See Also =====

  * [[.:meta|UI Meta - Component Registry]]
  * [[.:preview|UI Preview - Live Preview]]
  * [[.:projects|Projects - Project Templates with PXAML]]