Chapter 1: Building A First MUX-Window Program

MUX-Window System programming begins with an understanding of MUX-Window's structure. It is a network-based window system that divides the workload into two parts: the server controls a display screen, and clients (or application programs) request services of the server, such as opening windows and drawing lines or text into the windows. All MUX-Window applications are clients of the server. The first step in any MUX-Window program is connecting to the server.

The Connect() function opens up a network connection to the server. Typically, this connection will simply be through the MUX device, but could just as easily be through a modem, serial cable or some other device.

Connect() takes two parameters: the name of your program, and what type of program it is (an editor, a spreadsheet, etc.) This information is mainly worried about by the Window Manager running on the server (so that the user can, for example, choose a program to get to by its name). It returns a value letting you know if the connection was successful. You can connect to the server using the code below:

    INCLUDE "MUXW.ACT"

    Connect("EXAMPLE PROGRAM","DEMO")

This 'registers' the program as a demo named "Example Program".

The Stat Type

Many MUX-Window functions, including Connect(), return a simple value letting you know if what you asked for actually happened. In the MUX-Window library for Action!, this type is called Stat.

The two values which exist of the type Stat are included as the global constants SUCCESS and FAILURE, which should be pretty self-explanatory. If a Connect() call returns FAILURE, you're in big trouble and should exit!

    if (Connect()=FAILURE) then
      printe("Can't connect!!!")
      break()
    fi

Exploring The MUX-Window Environment

Once you've established a connection to the MUX-Window server, you should ask if it supplies color or monochrome and the size of the screen. If the screen is 160 x 192 pixels, you don't want to create a window at location 200,60, because that location wouldn't be on the screen!

The number of "bit planes" is returned by the function GetDepth().

    int depth

    depth=GetDepth()

If the depth is 1, you have a monochrome system and/or window manager.

The size of the screen is returned from two functions: GetWidth() and GetHeight().

 
    int width, height

    width=GetWidth()
    height=GetHeight()

These functions return the size of the display in pixels (or picture elements), the number of dots on the screen in the vertical (GetHeight()) and horizontal (GetWidth()) directions.

Other useful information includes the name, or "model", and version of the Window Manager running on the server, who the vendor, or manufacturer who wrote it was, and when it was released. GetModel() does all of this:

    String model(40),ver(10),date(40),manuf(40)

    GetModel(model,ver,date,manuf)
    printf("Model=%S v.%S%E",model,ver)
    printf("      by %S%E",manuf)
    printf("      %S%E",date)

The String Type

A new variable type is used above called String, however, it is not actually a new type. It's simply another way of saying "Char Array". If you wish to create a new String, do it exactly as you would a Char Array in Action!:

    String NAME(SIZE)

The Colors Black and White

Every MUX-Window server has at least two colors: black and white. Never assume that your program can display more than this. If you're writing a simple text reader, you won't care if you have more colors than black and white, but if you're writing a paint package, you'll need to either compensate for the lack of bit planes, or exit with an error.

Even though different servers and Window Managers have different palettes, they use the same values to represent black and white. In the MUX-Window Action! library, these values are stored in the global constants "BLACK" and "WHITE".

For most of the examples in this guide, since no Window Manager currently supports more than black and white, we will only use the colors black and white.

Closing The Connection

When you're done with the connection to the MUX-Window server (usually at the end of your program), it's smart to close the connection. Disconnect() closes a connection; once called, you can no longer use any MUX-Window routines (unless you "reconnect").

    Disconnect()

The First MUX-Window Program Code

The first MUX-Window program presented in this guide simply opens a connection to the MUX-Window server and reports some information about it.

Since we have not yet discussed creating windows or outputting text to them, we'll simply display the information from our program as if it's not a MUX-Window program at all.

On a typical MUX-network-based setup, the output for any particulare client is its own monitor, so that is where our information is displayed. (If you are using the MUX-networkless stand-alone MUX-Window Action! libraries, "MUX-Less-W", the window manager's graphics screen will appear breifly as we call "Connect", but then disappear and our information will be displayed in a normal text screen).

Source-code: chap1.act
Screen-shot: chap1out.txt

Compiling The Example Program

To compile the CHAP1.ACT example, load it into the Action! editor ([SHIFT]+[CONTROL]+[R]), switch to the monitor ([SHIFT]+[CONTROL]+[M]), compile it ("C"), and run it ("R").

Or, you can simply switch to the monitor and compile it from disk and run it all at once. ("C CHAP1.ACT" and then "R", or simply "R CHAP1.ACT")

Note: This will be true for all of the example programs in this guide.

Summary

All MUX-Window applications start by setting up a connection to the server. This involves a basic call with Connect(). At this time, you'll want to ask the server (more specifically, the Window Manager running on the server) to provide basic information about itself, including model and version numbers, if color is supported, and the size of the screen.

MUXW Library Functions, Types and Constants Introduced in this Chapter

Functions: Types: Constants: