Custom Windows

Learn how to create standalone UI windows with custom layouts, positioning, and interactive elements.

📋 Table of Contents

• Overview
• Creating Your First Window
• Window Sizing
• Positioning Elements
• Advanced Layouts
• Best Practices
• Common Patterns

Overview

Custom windows are standalone UI panels that appear separately from ZUI's main menu. They allow you to:

• ✅ Create pixel-perfect layouts
• ✅ Position elements exactly where you want them
• ✅ Display images, text, and buttons
• ✅ Build admin panels, dashboards, and control interfaces
• ✅ Organize complex functionality in a dedicated space

Main Menu vs Custom Window

Creating Your First Window

Here's a complete example of creating a custom window:

private void CreateCustomWindow()
{
    // 1. Set your plugin context
    Call("SetPlugin", "MyMod");
    
    // 2. Target a custom window (give it a unique name)
    Call("SetTargetWindow", "MyControlPanel");
    
    // 3. Set the window dimensions (width x height in pixels)
    Call("SetUI", 600, 400);
    
    // 4. Set the window title
    Call("SetTitle", "<color=#4ECDC4>Control Panel</color>");
    
    // 5. Add content with positioning
    Call("AddText", "Welcome to the control panel!", 20f, 50f);
    Call("AddText", "Version 1.0", 20f, 80f);
    
    Call("AddCategory", "<color=#FFE66D>Actions:</color>", 20f, 120f);
    
    Call("AddButton", "Execute Command", ".mycommand", 20f, 160f);
    Call("AddButton", "Show Status", ".status", 20f, 210f);
    
    // 6. Optional: Add an image
    Call("AddImage", "logo.png", 20f, 280f, 560f, 100f);
}

Result: A 600x400 pixel window with a title, text labels, buttons, and an image - all positioned exactly where you specified.

Window Sizing

Choosing Dimensions

When calling SetUI(width, height), consider:

Recommended Sizes:

• Small: 400x300 - Simple panels with a few buttons
• Medium: 600x400 - Standard control panels
• Large: 800x600 - Complex dashboards
• Extra Large: 1000x700+ - Full-featured interfaces

Guidelines:

• Minimum: ~300x200 (avoid smaller, hard to use)
• Maximum: ~2000x1200 (avoid larger, might not fit on screen)
• Consider common resolutions (1920x1080, 2560x1440)
• Leave room for window borders and title bar

Example Sizes

// Compact status display
Call("SetUI", 400, 250);

// Standard control panel
Call("SetUI", 600, 400);

// Large admin interface
Call("SetUI", 900, 650);

// Wide dashboard
Call("SetUI", 1200, 500);

Positioning Elements

Coordinate System

Custom windows use a pixel-based coordinate system:

(0, 0) ──────────────► X
  │
  │      Your Window
  │
  ▼
  Y

• Origin (0, 0) = Top-left corner of the window
• X increases going right
• Y increases going down

Positioning Examples

Call("SetUI", 500, 300);

// Top-left area
Call("AddText", "Top Left", 10f, 10f);

// Top-right area (account for text width)
Call("AddText", "Top Right", 400f, 10f);

// Center-ish (window is 500 wide, 300 tall)
Call("AddText", "Center", 225f, 140f);

// Bottom area
Call("AddButton", "Bottom Button", ".cmd", 10f, 250f);

Spacing Guidelines

Margins:

• Leave 10-20 pixels from window edges
• Prevents content from touching borders

Vertical Spacing:

• Text lines: 25-35 pixels apart
• Buttons: 10-15 pixels apart
• Sections: 40-60 pixels apart

Example with Good Spacing:

Call("SetUI", 500, 400);

float margin = 20f;
float lineHeight = 30f;
float buttonSpacing = 50f;

Call("AddText", "Section 1", margin, margin);
Call("AddButton", "Action 1", ".cmd1", margin, margin + buttonSpacing);
Call("AddButton", "Action 2", ".cmd2", margin, margin + buttonSpacing + 50f);

Call("AddText", "Section 2", margin, margin + 180f);
Call("AddButton", "Action 3", ".cmd3", margin, margin + 230f);

Advanced Layouts

Multi-Column Layout

Call("SetUI", 700, 400);

// Left column
float leftX = 20f;
Call("AddCategory", "Player Tools", leftX, 20f);
Call("AddButton", "Heal", ".heal", leftX, 60f);
Call("AddButton", "Speed", ".speed", leftX, 110f);
Call("AddButton", "Fly", ".fly", leftX, 160f);

// Right column
float rightX = 370f;
Call("AddCategory", "Admin Tools", rightX, 20f);
Call("AddButton", "God Mode", ".god", rightX, 60f);
Call("AddButton", "Teleport", ".tp", rightX, 110f);
Call("AddButton", "Spawn", ".spawn", rightX, 160f);

Header + Content Layout

Call("SetUI", 600, 500);

// Header section
Call("AddText", "<size=20><b>Admin Control Panel</b></size>", 20f, 20f);
Call("AddText", "Version 2.0 | Status: <color=#2ECC71>Active</color>", 20f, 55f);
Call("AddImage", "divider.png", 20f, 85f, 560f, 2f); // Horizontal line

// Content sections
float contentStart = 100f;

Call("AddCategory", "<color=#3498DB>Player Management</color>", 20f, contentStart);
Call("AddButton", "Heal All", ".healall", 20f, contentStart + 40f, 250f, 35f);
Call("AddButton", "Kick Player", ".kick", 20f, contentStart + 85f, 250f, 35f);

Call("AddCategory", "<color=#E74C3C>Server Control</color>", 310f, contentStart);
Call("AddButton", "Save World", ".save", 310f, contentStart + 40f, 250f, 35f);
Call("AddButton", "Restart", ".restart", 310f, contentStart + 85f, 250f, 35f);

// Footer
Call("AddText", "<i>Use commands responsibly</i>", 20f, 460f);

Grid Layout

Call("SetUI", 650, 450);

float startX = 20f;
float startY = 60f;
float buttonWidth = 190f;
float buttonHeight = 35f;
float spacingX = 210f;  // buttonWidth + gap
float spacingY = 50f;   // buttonHeight + gap

Call("SetTitle", "Command Grid");

// Row 1
Call("AddButton", "Command 1", ".cmd1", startX, startY, buttonWidth, buttonHeight);
Call("AddButton", "Command 2", ".cmd2", startX + spacingX, startY, buttonWidth, buttonHeight);
Call("AddButton", "Command 3", ".cmd3", startX + spacingX * 2, startY, buttonWidth, buttonHeight);

// Row 2
Call("AddButton", "Command 4", ".cmd4", startX, startY + spacingY, buttonWidth, buttonHeight);
Call("AddButton", "Command 5", ".cmd5", startX + spacingX, startY + spacingY, buttonWidth, buttonHeight);
Call("AddButton", "Command 6", ".cmd6", startX + spacingX * 2, startY + spacingY, buttonWidth, buttonHeight);

// Row 3
Call("AddButton", "Command 7", ".cmd7", startX, startY + spacingY * 2, buttonWidth, buttonHeight);
Call("AddButton", "Command 8", ".cmd8", startX + spacingX, startY + spacingY * 2, buttonWidth, buttonHeight);
Call("AddButton", "Command 9", ".cmd9", startX + spacingX * 2, startY + spacingY * 2, buttonWidth, buttonHeight);

Best Practices

1. Use Variables for Positioning

Bad:

Call("AddButton", "Button 1", ".cmd", 20f, 100f);
Call("AddButton", "Button 2", ".cmd", 20f, 150f);
Call("AddButton", "Button 3", ".cmd", 20f, 200f);

Good:

float margin = 20f;
float buttonY = 100f;
float buttonGap = 50f;

Call("AddButton", "Button 1", ".cmd", margin, buttonY);
Call("AddButton", "Button 2", ".cmd", margin, buttonY + buttonGap);
Call("AddButton", "Button 3", ".cmd", margin, buttonY + buttonGap * 2);

2. Plan Your Layout First

Before coding, sketch your layout:

• Where will major sections go?
• How much space does each element need?
• What's the visual hierarchy?

Or use the Visual Designer to design visually!

3. Test Different Resolutions

Your window should be usable at common resolutions:

• 1920x1080 (most common)
• 2560x1440
• 3840x2160 (4K)

Avoid making windows too large for 1920x1080 screens.

4. Use Descriptive Window Names

// Bad
Call("SetTargetWindow", "Panel1");

// Good
Call("SetTargetWindow", "AdminControlPanel");
Call("SetTargetWindow", "PlayerStatsDisplay");
Call("SetTargetWindow", "ServerSettings");

5. Group Related Elements

Keep related functionality together:

// Player tools section
Call("AddCategory", "Player", 20f, 50f);
Call("AddButton", "Heal", ".heal", 20f, 90f);
Call("AddButton", "Speed", ".speed", 20f, 140f);

// Server tools section  
Call("AddCategory", "Server", 20f, 220f);
Call("AddButton", "Save", ".save", 20f, 260f);
Call("AddButton", "Restart", ".restart", 20f, 310f);

Common Patterns

Dashboard Pattern

Information display with some interactive elements:

Call("SetUI", 800, 500);
Call("SetTitle", "Server Dashboard");

// Status section
Call("AddText", "<size=18><b>Server Status</b></size>", 20f, 20f);
Call("AddText", "Players Online: <color=#2ECC71>24/50</color>", 20f, 55f);
Call("AddText", "Uptime: <color=#3498DB>12h 34m</color>", 20f, 85f);
Call("AddText", "TPS: <color=#F39C12>20.0</color>", 20f, 115f);

// Quick actions
Call("AddCategory", "Quick Actions", 20f, 170f);
Call("AddButton", "Announce", ".announce", 20f, 210f, 200f, 35f);
Call("AddButton", "Save World", ".save", 20f, 255f, 200f, 35f);

// Large display area
Call("AddImage", "server_map.png", 250f, 20f, 530f, 460f);

Settings Panel Pattern

Form-like interface with options:

Call("SetUI", 500, 600);
Call("SetTitle", "Mod Settings");

float margin = 20f;
float y = 20f;
float spacing = 60f;

Call("AddText", "<b>General Settings</b>", margin, y);
y += 40f;

Call("AddText", "Enable Feature A:", margin, y);
Call("AddButton", "Toggle", ".toggle_a", 200f, y - 5f, 100f, 30f);
y += spacing;

Call("AddText", "Enable Feature B:", margin, y);
Call("AddButton", "Toggle", ".toggle_b", 200f, y - 5f, 100f, 30f);
y += spacing;

Call("AddText", "<b>Advanced Settings</b>", margin, y);
y += 40f;

Call("AddText", "Debug Mode:", margin, y);
Call("AddButton", "Toggle", ".toggle_debug", 200f, y - 5f, 100f, 30f);
y += spacing;

Call("AddButton", "Save Settings", ".save_settings", margin, y + 40f, 460f, 40f);

Action Panel Pattern

Focused on buttons for executing commands:

Call("SetUI", 600, 400);
Call("SetTitle", "Admin Actions");

Call("AddText", "Select an action to execute:", 20f, 20f);

float btnY = 60f;
float btnHeight = 45f;
float btnGap = 10f;

Call("AddButton", "Heal All Players", ".healall", 20f, btnY, 560f, btnHeight);
btnY += btnHeight + btnGap;

Call("AddButton", "Give All Resources", ".giveall", 20f, btnY, 560f, btnHeight);
btnY += btnHeight + btnGap;

Call("AddButton", "Teleport to Spawn", ".tpspawn", 20f, btnY, 560f, btnHeight);
btnY += btnHeight + btnGap;

Call("AddButton", "Clear Inventory", ".clearinv", 20f, btnY, 560f, btnHeight);
btnY += btnHeight + btnGap;

Call("AddText", "<color=#E74C3C>⚠ Warning: These actions affect all players</color>", 20f, btnY + 20f);

🎨 Visual Designer

Skip the manual coordinate calculations! Use the ZUI Visual Designer to:

• Design your layout visually with drag-and-drop
• See real-time preview of your window
• Adjust positions and sizes interactively
• Export ready-to-use code
• Test different layouts quickly

Workflow:

1. Visit https://zanakinz.github.io/ZUI
2. Set your window dimensions
3. Add and position elements visually
4. Export the code
5. Paste into your mod

Related Pages

• API Reference - Detailed method documentation
• Getting Started - Basic setup guide
• Working with Images - Adding custom graphics
• Color & Styling - Text formatting options
• Examples & Tutorials - More practical examples

Ready to build amazing custom UIs? Start with the Visual Designer or dive into the code!