DEV Community

Peter + AI
Peter + AI

Posted on

🚀 Mastering Uniface newinstance: Dynamic Component Creation Made Easy

#uniface #programming #database #development

Working with Uniface? Then you've probably encountered the newinstance statement - one of the most powerful features for dynamic component management. With the help of AI assistance, I've compiled this comprehensive guide based on the official Uniface 10.4 documentation to help you master this essential command! 💪

🎯 What is newinstance?

The newinstance statement creates a new instance of a specified component in Uniface. Think of it as your gateway to dynamic application architecture where components can be spawned on-demand.

📝 Basic Syntax 

newinstance{/sync | /async} {/attached} ComponentName, Handle | InstanceName {, InstanceProperties}
Enter fullscreen mode Exit fullscreen mode

🛠️ Key Features & Qualifiers

Communication Modes

  • /sync 🔄 - Synchronous operation (default behavior)
  • /async ⚡ - Asynchronous operation for non-blocking execution
  • /attached 📎 - Attaches the new instance to the current component

Parameters Breakdown

  • ComponentName: String (max 16 bytes for Uniface components, 32 for others)
  • Handle: Empty handle variable for instance reference
  • InstanceName: Named instance (max 32 bytes, letters/digits/underscores)
  • InstanceProperties: Associative list for form component properties

💡 Practical Examples

Using Handles (Recommended for most cases) 

variables
 handle vHandle
endvariables

newinstance "MYCOMPONENT", vHandle

// Activate operations using the handle
vHandle->myOperation(myParam)
Enter fullscreen mode Exit fullscreen mode

Using Instance Names (Required for web applications) 

// Perfect for dynamic server pages
newinstance "WEBCOMPONENT", "MyUniqueInstance", "MODALITY=NON-MODAL"

// Later activate using the name
activate "WEBCOMPONENT", "MyUniqueInstance", "EXEC"
Enter fullscreen mode Exit fullscreen mode

Creating Multiple Non-Modal Forms 

trigger apStart
    // Create multiple forms
    newinstance "form10", $1, "MODALITY=NON-MODAL"
    newinstance "form20", $2, "MODALITY=NON-MODAL"
    newinstance "form40", $3, "MODALITY=NON-MODAL"

    // Execute them
    $1->EXEC()
    $2->EXEC()
    $3->EXEC()

    // Cleanup detached instances
    getitem $1, $detachedinstances, 1
    while ( $status > 0 )
        deleteinstance $1
        getitem $1, $detachedinstances, 1
    endwhile
end
Enter fullscreen mode Exit fullscreen mode

⚠️ Important Considerations

🎯 When to Use Handles vs Instance Names

  • Handles: Same process communication (desktop apps, server-side logic)
  • Instance Names: Cross-process communication (web applications, distributed systems)

🚫 Common Pitfalls

  • Stateless Components: You cannot create instances of stateless components
  • Invalid Names: Instance names must start with a letter
  • Memory Management: Always clean up handles by setting them to 0

🔍 Error Handling

Always check $status and $procerror after newinstance:

newinstance "MYCOMPONENT", vHandle
if ($status < 0)
    // Handle errors based on $procerror
    switch($procerror)
    case -58: // Component not found
        message "Component not found!"
    case -154: // Instance name exists
        message "Instance already exists!"
    // ... other error cases
    endswitch
endif
Enter fullscreen mode Exit fullscreen mode

🎨 Instance Properties for Forms

Form components support various properties:

newinstance "MYFORM", vHandle, "Display=True;Query=True;Transaction=True;WindowType=Popup"
Enter fullscreen mode Exit fullscreen mode

Available Properties:

  • Display: Show/hide the form
  • Dimension: Set position and size
  • Query: Enable query mode
  • Modality: Modal or non-modal behavior
  • Transaction: Enable transaction support

🏆 Best Practices

  1. Use handles for single-process scenarios 🎯
  2. Use unique instance names for web applications 🌐
  3. Always implement cleanup to prevent memory leaks 🧹
  4. Handle errors gracefully with proper status checking ✅
  5. Consider /attached for child-parent relationships 👨‍👩‍👧‍👦

🎉 Conclusion

The newinstance statement is a cornerstone of dynamic Uniface development. Whether you're building desktop applications with handles or web applications with instance names, understanding these concepts will make your Uniface applications more flexible and maintainable.

Happy coding! 💻✨

This guide is based on the official Uniface 10.4 documentation. For the most up-to-date information, always refer to the official Uniface documentation.

Top comments (0)