🖥️ Creating Character Mode Application Shells in Uniface 10.4: A Simple Guide

This blog post was created with AI assistance based on Uniface 10.4 documentation.

📋 What is a Character Mode Application Shell?

A Character Mode Application Shell is the starting point for Uniface applications that run in text-based environments like Unix or Linux terminals. Think of it as the container that holds your application together and controls how it starts and behaves. 🚀

Unlike graphical applications with windows and buttons, character mode applications work entirely with text and keyboard commands. They're perfect for server environments, remote systems, or situations where you need lightweight applications without graphical overhead.

🎯 Why Use Character Mode Shells?

Character mode shells are ideal when you need:

• Server-side applications that run without a graphical interface 💻
• Remote system access through terminal connections 🌐
• Lightweight performance without GUI resource usage ⚡
• Unix/Linux compatibility for cross-platform deployment 🐧

🛠️ Step-by-Step: Creating Your First Character Mode Shell

Step 1: Create the Project Structure

Before creating your shell, you need a project to organize your application. Open the Uniface IDE and:

1. Click Browse in the U-Bar
2. Select prj (project)
3. Choose your project or create a new one

Step 2: Add the Character Mode Shell Template

Navigate to the Templates tab in the Resource Browser. Find the Character Mode Shell template and drag it onto your project in the Structure view. Easy! ✨

Step 3: Configure Shell Properties

Right-click your new shell and select Open. You'll see the Application Shell Editor where you can configure:

• Shell Type: Set to APC (Application Character Mode) - this tells Uniface it's a text-based app
• Library: Link to global objects like messages and menus if you have them
• Initial Menus and Panels: Set default UI elements for your application
• I/O Message Level: Control debugging output (higher numbers = more detailed logs)

Step 4: Write the Startup Code

The heart of your shell is the apStart trigger. This is where your application comes to life! 🎬

Here's a simple example:

trigger apStart
    ; Set the language for your application
    $language = "ENG"

    ; Connect to database with credentials
    open "|myuser|mypassword", "database_path"

    ; Start your main form
    activate "MAIN_MENU"

    ; Pass control to the user
    apstart
end; apStart

What's happening here? 🤔

• $language: Sets the application language
• open: Connects to a database that needs login information
• activate: Launches your main form component
• apstart: Gives control to the user for interaction

Step 5: Handle User Events

Besides apStart, you can write code in other triggers to respond to user actions:

• receiveMessage: Handle messages from other components 📨
• menu: Respond to menu selections 📋
• keyboardSwitch: React to keyboard layout changes ⌨️
• userKey: Process custom keyboard shortcuts 🔑

🎨 Defining the Screen Layout

Character mode applications use frames to organize the screen. Think of frames as boxes that define different areas of your text interface.

Default Frames

Uniface automatically creates two essential frames:

• MESSAGE: Displays system and application messages at the bottom 💬
• FORMAREA: The main area where your form content appears 📄

Adding Custom Frames

You can add more frames for menus or special areas:

1. Click the More icon in Shell Canvas property
2. Position cursor on a frame name
3. Press Ctrl+F to edit existing frames
4. Press GOLD+F (usually Ctrl+F) to create new frames

Common frame types include:

• PULLDOWN: For drop-down menus 📥
• MENU: For popup menu displays 🍔

⚙️ Advanced Configuration

Custom Properties

Need to store specific settings for your application? Add custom properties:

1. Open the Define Application Shell Properties dialog
2. Go to the More tab
3. Enter property names and values
4. Click + to add more properties

I/O Message Levels

Debug your application by setting the I/O Message Level. Higher numbers give you more detailed information about database operations and component interactions. This is super helpful when troubleshooting performance issues! 🐛

✅ Compile and Run

Once you've configured everything:

1. Click Compile to compile your application shell
2. Fix any compilation errors that appear
3. Run your application from the command line or terminal

💡 Best Practices and Tips

Always Activate at Least One Form

Your apStart trigger should always activate at least one component. If no forms are active when apstart executes, your application will simply exit. This is a common beginner mistake! ⚠️

Handle Database Connections Properly

Use the apStart trigger to open database connections that require credentials. This keeps sensitive information in one place and ensures connections are established before components need them.

Use Exception Handling

Wrap your startup code in try-catch blocks to handle errors gracefully:

trigger apStart
    try
        ; Your initialization code
        activate "MAIN_FORM"
        apstart
    catch
        ; Error handling
        message "Error: Unable to start application"
        putmess "Check database connection and try again"
    end
end; apStart

Control Message Position