Displays CodeBehind Reference

Add logic to displays with CodeBehind.

How-to Guides → Pillars → Operator → Displays → CodeBehind | How-To Guide | Reference

Language Support

Portable and WPF Displays

• VB.NET - Visual Basic syntax
• C# - C-Sharp syntax
• Auto-conversion between languages
• Note: C# is more restrictive on type conversions

HTML5-Only Displays

• JavaScript tab appears alongside VB.NET/C#
• Both execute side-by-side in web runtime
• Legacy approach (WebAssembly preferred)
• Similar method structure to .NET languages

Pre-defined Methods

Every display includes these event handlers:

Example Structure

csharp

public void DisplayOpening()
{
    // Initialize display
}

public void DisplayIsOpen()  
{
    // Called continuously while open
    // Use sparingly for performance
}

public void DisplayClosing()
{
    // Cleanup before close
}

public int DialogOnOK()
{
    // Dialogs only - validate and return
    if (ValidateInput())
        return 1; // Allow close
    else
        return 0; // Prevent close
}

Custom Properties

Local variables exclusive to the display instance:

Benefits

• Reduce communication points
• Store display-specific state
• Access from both display and CodeBehind
• Link to tags for extended functionality

Limitations

• Data doesn't persist between pages
• Specific to display instance
• Lost when display closes

Runtime Methods

csharp

// Set property value
SetCustomPropertyValue("PropertyName", value);

// Get property value
var value = GetCustomPropertyValue("PropertyName");

// Get all as string
string allProps = GetCustomPropertiesAsString();

// Clear all properties
ClearCustomProperties();

See → Custom Properties for detailed documentation.

Performance Considerations

UI Blocking

• CodeBehind runs on client thread
• Display locks during execution
• User cannot interact while code runs

Solutions

1. Use Async Functions

csharp

   public async void DisplayOpening()
   {
       await Task.Run(() => LongRunningOperation());
   }

1. Offload to Scripts
   • Use Script Tasks for heavy processing
   • Run on server or background thread
   • Prevents UI freezing
2. Optimize Code
   • Minimize DisplayIsOpen() logic
   • Cache calculations
   • Avoid loops in event handlers

Display Namespace Access

CurrentDisplay Object

Special object available in CodeBehind:

csharp

// Access current display properties
this.CurrentDisplay.Width
this.CurrentDisplay.Height
this.CurrentDisplay.Name

// Get display framework element
this.CurrentDisplay.GetThis()

Opening Displays

Multiple methods available:

Mouse Wheel Example

csharp

public void DisplayIsOpen()
{
    this.CurrentDisplay.GetThis().PreviewMouseWheel += PreviewMouseWheelChanged;
}

private void PreviewMouseWheelChanged(object sender, MouseWheelEventArgs e)
{
    e.Handled = true;
    
    if (e.Delta > 0)
        @Display.MainPage.ZoomLevel += 0.1;
    else if (e.Delta < 0)
        @Display.MainPage.ZoomLevel -= 0.1;
}

Multiple Popups Management

Key Considerations

• Each popup is independent instance
• Use unique identifiers for tracking
• Consider memory usage
• Handle cleanup properly

Common Pattern

csharp

// Track popup instances
private List<object> openPopups = new List<object>();

public void OpenNewPopup(string data)
{
    var popup = @Display.DetailPopup.NewPopup();
    popup.SetCustomPropertyValue("Data", data);
    openPopups.Add(popup);
}

public void CloseAllPopups()
{
    foreach(var popup in openPopups)
    {
        popup.Close();
    }
    openPopups.Clear();
}

See → Multiple Popups for advanced scenarios.

Code Editor Features

• Syntax highlighting
• IntelliSense support
• Error checking
• Find/Replace
• Code folding
• Breakpoint debugging (development mode)

See → Code Editor for complete feature documentation.

External References

For using custom DLLs and assemblies:

• Add references via Scripts → References
• Available to all CodeBehind
• Shared with Script modules

See → Scripts References for configuration.

Best Practices

1. Keep Methods Light - Avoid heavy processing in event handlers
2. Use Async When Needed - Prevent UI blocking
3. Clean Up Resources - Use DisplayClosing() for cleanup
4. Cache References - Store frequently used objects
5. Handle Errors - Try-catch in event handlers
6. Document Code - Comment complex logic
7. Test Performance - Monitor UI responsiveness

Common Patterns

Initialize Once

csharp

private bool initialized = false;

public void DisplayIsOpen()
{
    if (!initialized)
    {
        InitializeDisplay();
        initialized = true;
    }
}

Periodic Updates

csharp

private DateTime lastUpdate = DateTime.MinValue;

public void DisplayIsOpen()
{
    if (DateTime.Now - lastUpdate > TimeSpan.FromSeconds(1))
    {
        UpdateDisplay();
        lastUpdate = DateTime.Now;
    }
}

Troubleshooting

Display Freezing:

• Check for blocking code in events
• Use async methods
• Move heavy logic to Scripts

Methods Not Firing:

• Verify method signatures
• Check display is correct type (Page/Popup/Dialog)
• Review build errors

Variable Scope Issues:

• Use Custom Properties for persistence
• Class-level variables for display lifetime
• Static variables for cross-display data

In this section...