DEV Community

Peter + AI
Peter + AI

Posted on

🚀 Mastering Uniface Macro Statements: Your Complete Guide to Structure Editor Automation

#uniface #programming #automation #development

If you're working with Uniface 10.4 and want to streamline your form interactions, understanding the macro statement is essential! 📝 This powerful feature allows you to queue structure editor functions and automate user interface operations in ways that can significantly enhance your application's user experience.

This comprehensive guide is based on the official Uniface 10.4 documentation, and I've had AI assistance to help structure this content for better readability.

🎯 What is the Macro Statement?

The macro statement is a Uniface command that places specified structure editor requests into the event input queue of a form component. Think of it as a way to "program" user interactions - instead of requiring manual input, you can automate sequences of editor functions.

Basic Syntax 

macro{/exit} RequestCodes
Enter fullscreen mode Exit fullscreen mode

Example:

macro "^RETRIEVE"
Enter fullscreen mode Exit fullscreen mode

⚙️ Key Features and Qualifiers

The /exit Qualifier

When you use macro{/exit}, it queues the structure editor functions for the current form and returns control to the previous form. This is particularly useful in menu-driven applications where you need to execute commands and then return to the parent form.

🔧 Understanding Request Codes

Request codes are the heart of the macro statement. They can be:

  • Character codes: Preceded by a caret (^)
  • Mnemonics: Human-readable function names
  • Literal text: Direct text input

📊 Essential Function Categories

🔄 Session Control Functions

Function Code Purpose
^ACCEPT ^127^009 End edit session positively
^QUIT ^127^010 End edit session negatively
^CLEAR ^127^012 Clear form data without saving

🗄️ Database Operations

Function Code Purpose
^RETRIEVE ^127^005 Activate retrieve trigger
^STORE ^127^011 Activate store trigger
^ERASE ^127^008 Delete component data

🧭 Navigation Functions

Function Code Purpose
^NEXT_FIELD ^127^046 Move to next field
^PREV_FIELD ^127^047 Move to previous field
^HOME ^127^022 Move to top of form
^CURSOR_DOWN ^127^017 Move cursor down one line

💡 Practical Examples

Example 1: Auto-Retrieve on Data Entry 

trigger startModification
  macro "^127^005"  ; This triggers ^RETRIEVE
end; startModification
Enter fullscreen mode Exit fullscreen mode

This automatically retrieves data when a user starts entering information in a field. Perfect for lookup scenarios! 🔍

Example 2: Smart Salutation Insertion 

trigger startModification
if ($char = 68) ; User typed "D"
  if (GENDER = "M")
    $1 = "Mr."
  else
    $1 = "Ms."
  endif
  macro "^127^096ear %%$1 %%SURNAME, ^CURSOR_RIGHT"
endif
end; startModification
Enter fullscreen mode Exit fullscreen mode

This clever example automatically inserts appropriate salutations based on gender data when the user types "D" - presumably for "Dear". 💬

⚠️ Important Considerations

🎭 Understanding Menu vs Normal Forms

The macro statement works differently depending on your form's behavior:

  • Normal forms: Direct execution
  • Menu forms: Queues commands for the parent form

🔄 Return Values and Status Handling

The macro statement sets $status values:

  • 0: Successful execution
  • 9: After macro ^ACCEPT
  • 10: After macro ^QUIT
  • >0: Error occurred (check $procerror)

⚡ Performance Tips

  • Macro statements implicitly return 0, so any code after them is ignored
  • Commands are queued, not immediately executed
  • Multiple macros append to the queue sequentially
  • Only use Uniface Font 0 characters in literal text

🎯 Best Practices

  1. Plan your sequences: Think through the user workflow before implementing macros
  2. Test thoroughly: Macro behavior can vary between different form types
  3. Use meaningful names: When possible, use mnemonic codes rather than numeric ones
  4. Handle errors gracefully: Always check $status and $procerror values
  5. Document your macros: Complex sequences can be hard to debug later

🔚 Conclusion

The Uniface macro statement is a powerful tool for creating sophisticated, automated user interfaces. Whether you're building data entry forms, implementing complex navigation patterns, or creating smart user assistance features, mastering macros will significantly enhance your Uniface applications. 🎉

Remember to always test your macro implementations thoroughly and consider the user experience - automation should make things easier, not more confusing!

Happy coding with Uniface! 🚀

Top comments (0)