# Introduction to Using PxPlus

Graphical User Interfaces |

Your graphical user interface may be the biggest selling feature of your application, and PxPlus has the all tools necessary to adapt and incorporate powerful, effective graphical functionality. This includes the development of panels (windows or forms), menus, toolbars, buttons, radio buttons, check boxes, list boxes, and scrollbars - just to name a few. It also has the flexibility to take your application from the Windows environment into Web-based accessibility.

A graphical user interface application is designed so that the user is able to interact with the software in a manner similar to the physical manipulations in the real world. For example, in a typical "windowing" operating system, files are represented by file icons. Data in a file can be moved to a new location by simply moving the icon via the mouse pointer. Behind-the-scenes, this physical interaction is translated into commands sent automatically to the application.

In PxPlus, the reusable graphical user interface tools (menus, toolbars, buttons, text entry boxes, etc.) are referred to as graphical controls. To respond to user input, a program needs to lay out various controls within the application window and set functions to be called when the user performs actions, such as selecting a menu item or clicking on a button.

## Concepts and Terminology

Graphical user interface development is similar to other types of programming, except for the following:

- Graphical user interfaces are almost exclusively event driven by nature, which means they perform tasks in response to events. A graphical user interface spends most of the time in an idle state waiting for the operating system to send an event that can arrive in the form of a user action (clicking a mouse) or an operation invoked by the operating system itself (screen refresh). See Event-Driven Methodology.
- Most modern graphical user interfaces are designed and built within an IDE (Integrated Development Environment). While it is quite feasible to build all your graphical user interface objects programmatically in PxPlus (see Syntax Elements), most developers find it easier to design and implement their graphical user interface applications using an application that is itself graphical user interface based; i.e. in NOMADS. See NOMADS Graphical Application.

Terminology

This table lists the terms that are used in the context of PxPlus graphical user interface development:

Term | Description
Control | A control is a graphical object used for "controlling" the application in a graphical user interface environment. Controls have properties and generate events. Typical controls include buttons, list boxes, grids, menus, scrollbars, folders, etc. See Graphical Controls.
CTL Value | When controls are created, they are assigned a unique CTL identifier (ctl_id). This value is used by a graphical user interface program to determine what actions have been performed by the user or operating system. See CTL Values.
Dialogue | Typically, a dialogue box is an independent (pop up) window object that is used to request information from the user or to supply information the user may need. See Windows Categories.
Event | In graphical user interface programming, an event is the reporting of an action generated by the user (or the graphical user interface operating system itself) to which a program might respond. Examples of events include a mouse click, keystroke or a focus change. See Event-Driven Methodology.
Mnemonic | PxPlus syntax element used to control an application window in a graphical user interface application. See Graphical Mnemonics.
NOMADS | Completely graphical user interface based development environment that simplifies the building and implementation of graphical applications in PxPlus. See NOMADS Graphical Application.
Panel | In PxPlus, a panel is the primary display area that is under the control of an application at run time. It provides the layout for controls required by the user to interact with an application. Some graphical user interface environments refer to this as the application window. See Windows Categories.
Property | A property is a named attribute of a graphical control object in PxPlus. Each control may be referenced and modified dynamically using its assigned CTL value, followed by the apostrophe operator (tick) and property name. See Dynamic Control Properties.
Window | A window is the generic term for a rectangular display object that presents its contents (e.g. controls, information, images, etc.) seemingly independent of the rest of the graphical user interface operating system. See Interface Windows.

Event-Driven Methodology

Event-driven methodology is one of the most significant concepts in graphical user interface programming. Whereas a typical batch program runs all of its operations in a linear fashion from start to finish, an interactive user interface must be designed to run its operations in a fairly random order. This behavior is expected by users and is nearly impossible to implement without being "event driven".

The general criteria for designing a graphical user interface application in PxPlus can be broken down into distinct implementation stages:

- Separate the User Interface from the Data Processing
  Partitioning an application into graphical user interface and non-graphical user interface components has several advantages, one being that it is much easier to maintain platform independence when building a distributed/server-based system.
- Determine User Actions
  How will the interface allow the user to carry out these actions? Which steps are required by the user to exercise all the necessary functionality?
- Determine Events
  Determine which events in your code will need to be triggered when each action is taken. A typical graphical user interface is input/output intensive. Each event may be generated by input from the keyboard, the mouse and system devices (e.g. menus, buttons and scrollbars) and can occur in any order and at any time.
- Organize Events
  For more complex behavior, it may be useful to map graphical user interface events visually using a state-transition diagram or table. This would illustrate the various states of an object, the events that cause a transition from one state to another, and the actions that result from a transition.
- Associate Events with Graphical User Interface Controls
  Focus for (mouse and keyboard) input events are usually associated with the top window in a graphical user interface desktop. Overlapping windows are hierarchically ordered. Events generated by child windows are frequently delivered up the window hierarchy for handling. See CTL Values.
  The events can be dispatched in several ways. They can be asynchronously sent to controls as messages. Controls or logic can poll queues or devices. Controls may register a callback, a pointer to a function for handling each event - the window manager invokes the functionality whenever the specified event type occurs.

#### Note:
The activities described above emphasize the event-driven aspects of graphical user interface development. Designing a graphical user interface tends to be an incremental process; however, in practice, these steps may proceed concurrently and in a different order.

General Design Principles

Although the functionality of your application is important, the way in which it delivers that functionality may be more important to your users. PxPlus includes several tools for performing similar graphical user interface tasks. Some may be better suited to your users' requirements than others, but how do you make the right usability choices in your design?

Some basic guidelines for designing a usable graphical user interface are:

- Know Your Users
  Developing any user interface requires careful thought about how your users intend to use it. One excellent way to verify your design choices is to test your interface with potential users.
- Ensure Consistency
  Whether they are arbitrary, precisely task-oriented, or follow an operating system standard, the "rules" behind a graphical element should be readily perceived by the intended user. Put your buttons in consistent places on all your windows, use the same wording in labels and messages, and use a consistent colour scheme throughout.
- Provide Clear Labeling
  Assist navigation by providing good textual clues on or near each graphical control. The interface may be "graphical", but most users recognize words faster than they recognize icons, especially first-timers. Terminology should be defined so that the same term always has the same meaning anywhere in the application.
- Use Feature Layering and Navigation Mechanisms
  Crowded panels can overwhelm users with extraneous details. Most people would prefer to see only the important features exposed at any time, saving advanced or peripheral functionality until it is actually needed. Provide clear and easy routes between the different panels users will need for accessing particular tasks. By convention, certain graphical components are designed specifically for feature layering; i.e. menus, toolbars, tabs and dialogues.
- Apply Redundancy
  Offer alternate methods to perform common tasks. While it is important to build on a familiar look and feel, the graphical user interface should not trap users into a single linear path to everything in the application. As users learn the steps within the larger process, the seemingly "helpful" aspects of your interface may actually work against its usability. By providing several access methods (i.e. menu items, toolbar icons and quick key sequences), you allow users to control their own productivity.
- Expect Mistakes, Allow for "Undo"
  Give users a clean way out of a confusing (possibly destructive) situation. When a graphical user interface provides navigation that is easily reversible, new users will feel much more confident about exploring the capabilities of your application. Of course, the best remedy is to also include an Undo or Cancel option. This way, if users reach a point where they have made some serious mistakes, they could simply go back to their earlier work.

The above guidelines are not "hard-and-fast" rules and can apply to a variety of interface applications. There are plenty of good detailed resources out there on the principles of high-level interface design. Check the Internet for titles specific to the design of usable interfaces; i.e. Web applications, mobile devices and traditional desktop graphical user interfaces.

## Graphical User Interface Development in PxPlus

Not only does PxPlus offer complete graphical user interface functionality, it is easily adapted for building graphical components on top of existing (non-graphical user interface) programs. PxPlus is flexible in that it allows more than one approach to graphical user interface development. You also have the option to create and position controls programmatically or use the visual, interactive building blocks provided under the NOMADS Development Environment.

Depending on your situation, there are four approaches to the development and implementation of graphical user interface based applications in PxPlus:

- Retrofit graphical user interface functionality into an existing program by introducing graphical Syntax Elements (directives, properties, etc.). With this approach, the onus is on the PxPlus developer to create the necessary control objects and trap events. The conditional logic will presumably already be in the existing code; therefore, this portion of the development has been completed.
- Construct your graphical user interface application from the start using all the necessary graphical syntax elements, events, etc.
- Employ the NOMADS toolkit to create and implement the desktop graphical user interface. This development environment provides a fast, visually oriented framework for creating panels, populating them with controls, and then associating event-driven code with these controls (pointing to logic in the already-written program).
- Develop your graphical user interface at the file or database level. Using NOMADS, you can define the database or files, apply all the controlling data to each field, and then use screen generation facilities (dictionary-based development) to automatically create parts of the application based on these file specifications.

Windowing Environment

Coding a graphical user interface application begins with the implementation of an Interface Window. This is the interactive display area that is under the control of your PxPlus application when running in a graphical operating system; i.e. MS Windows. It also defines the layout for the controls required by the user to interact with your application.

PxPlus uses special graphical user interface mnemonics for the creation and management of windows and dialogues. Multiple windows may be opened and closed at run time.

Graphical Controls

These are the objects that can be manipulated by the user within the window. They provide different methods for displaying information, inputting data, and handling event processing within an application window.

PxPlus supports a full range of Graphical Directives for creating and maintaining various Control Objects. Interactive properties are identified via CTL Values, which generate specific events in your application at run time.

Various Control Options allow you to define the initial appearance and functionality of each control when it is first created. Once they are created, controls may be further modified via Dynamic Control Properties.

Graphical Objects

Other graphical object types are used to produce images and text or define the layout of your application. These are output on the graphic plane using Graphical Mnemonics via the PRINT directive and have no events associated with them.

Object Focus

A key concept in PxPlus graphical user interface programming is the handling of focus, the condition where a window or control object has the exclusive ability to receive input via keyboard or mouse actions.

One simple example of focus is when an input-capable field shows that it has the cursor - this means that the field holds focus and is ready to receive the next input from the keyboard. In a windowing environment, several windows may be visible at the same time but usually only one has focus to accept and display user input. The focused window is usually positioned on the top of the stack, overlapping other non-focused windows. (However, NOMADS can be set to allow multiple active windows.)

Focus can be enabled in PxPlus in several ways:

- Upon creation of a control object or window
- When an object is selected by the user (mouse or keyboard) at run time
- SET_FOCUS directive (forcing transfer to a control object)
- 'GOTO' or 'WG' mnemonic (forcing transfer to a window)

Focus is also used in event handling; i.e. certain (get focus, lose focus) events can be associated with graphical user interface objects to generate a CTL value for triggering application logic.

Portable User Interfaces

PxPlus supports Windows and browser access to PxPlus graphical user interface applications running on UNIX, Linux, Mac OS X, or Windows. PxPlus syntax elements for graphical user interface development were originally designed for a Windows-only environment and were added to the language back when there were few other options. However, with the availability of PxPlus products, such as WindX, it is now feasible to build a high quality graphical user interface in PxPlus that is truly operating system (and device) independent.

For information on the full range of PxPlus multi-platform options, see Client/Server.

How to Change the Color Used When Printing with the 'SB' Mnemonic on Windows

In recent years, Windows has changed the brightness of the Gray color it uses on buttons and windows. By default, the Windows Gray colors are used by PxPlus to define the Light and Dark Gray colors so that windows and controls created in PxPlus match the colors used by Windows. These Gray colors are also used by the system when displaying Black or White text with the 'SB' (Set Background) mnemonic enabled - Dark Gray for Black text and Light Gray for White text.

However, these colors have become paler than they used to be, making Light Gray (#15) almost White, which causes a problem when displaying White text with the 'SB' mnemonic. This is especially challenging if you are running text-mode applications and have changed the display to use a Black background with White text.

To address this situation, two solutions are available.

The easiest solution is to simply change the Light Gray to be a bit darker. This can be done by using the following command:

> SETDEV (0) SET "Color15" TO "#A0A0A0"

This sets the color of Light Gray (color index 15) to a slightly darker color (Red, Green and Blue all set at 160/255). However, this solution does have its drawbacks, as it changes Light Gray everywhere so that PxPlus windows with a Light Gray background will no longer match the Windows color scheme.

The alternate solution is to define a new color index to use for White text with the 'SB' mnemonic. PxPlus has 15 standard colors (0-15). See Color Names and Numbers. However, for this, you would be required to define a new color, such as Color16, and then change the Video Palette index table for White with the 'SB' mnemonic enabled to use this color. The Video Palette index table consists of a series of six 8-byte color index values as bytes, which identify the actual color index to use. Each 8-byte entry has a 1-byte color index for the colors Black, Red, Green, Yellow, Blue, Magenta, Cyan and White - in that order.

The second 8-byte table defines the colors to use when 'SB' is active. Since White is color number 8, you need to change byte 16, second table eighth byte, to CHR(16). See VIDEO_PALETTE directive.

The code that you will need to do this is as follows:

> SETDEV (0) SET "Color16" TO "#A0A0A0"
> VIDEO_PALETTE INDEXED READ X$
> X$(16,1) = CHR(16)
> VIDEO_PALETTE INDEXED X$

If running WindX, setting the Video Palette needs to be done on the workstation and not on the server; therefore, the first solution is often much easier to implement in this environment.

Once the colors have been changed, you need Windows to refresh your page; otherwise, you will only get the new color on areas on the screen that are being updated.

#### Note:
The above information is intended for use with Windows and not with normal terminals that will use the escape sequence in the *dev driver programs.

## Syntax Elements

The PxPlus language includes a variety of commands for creating graphical user interface windows, controls and other display components - the basic building blocks used in the creation of a graphical user interface application.

Below is an overview of the syntax elements (i.e. Graphical Directives, Graphical Mnemonics, CTL Values, Control Options and Dynamic Control Properties) used to develop graphical user interface applications at the language level.

If you prefer a graphical approach to graphical user interface development where the underlying code is generated for you automatically, see the NOMADS Graphical Application development toolset.

Graphical Directives

PxPlus supports a full range of directives for creating and maintaining various control objects in a graphical user interface application:

| BUTTON | H_SCROLLBAR | TRISTATE_BOX
| CHART | LIST_BOX | VARDROP_BOX
| CHECK_BOX | MULTI_LINE | VARLIST_BOX
| DROP_BOX | RADIO_BUTTON | V_SCROLLBAR
| GRID |  |

For descriptions and examples on the use of these types of directives, see Control Objects.

Other graphical user interface directives include GET_FILE_BOX for generating a standard files/directory selection box and MSGBOX for launching a popup message box.

Graphical Mnemonics

Generating non-interactive graphical output from a PxPlus application requires the use of mnemonics such as 'TEXT', 'FONT', 'PICTURE', 'ARC', 'PIE', 'CIRCLE', 'LINE', 'POLYGON', 'RECTANGLE' and 'IMAGE'. Mnemonics are inserted within a PRINT statement to draw these types of components on the graphical plane. See Display Objects.

See Mnemonics for detailed information and a complete list of mnemonics.

CTL Values

When each graphical control object is created, it is assigned a unique CTL value (ctl_id), which is returned when an action has been performed on the control. Your program processes this value to discover what actions have been performed by the user. CTL values are also used to identify the control for assigning Dynamic Control Properties.

CTL values can signal various events that include:

- Button pushed
- Menu/tool bar items selected
- Scrollbars adjusted
- List/drop boxes selected, edited

These events are sent to the program to deal with one at a time. Eventually, the user will perform an action that terminates the program. See Event-Driven Methodology and Submitting Input (CTL Values).

Control Options

Several options (ctrlopt) are available for use in graphical user interface directives to specify format type, customize appearance and define the behavior of graphical objects. For information on how these are used, see Control Objects.

| ERR=stmtref | Defines program line number/line label for on-error transfer. Can be used with any directive.
| HLP=string$ | Help message identifier for defining AutoComplete and Calendar functionality in a Multi-Line control.
| FNT="font,size[,attr]" | Sets font name, size, and optional attributes for control object directives that support text.
| FMT=def$ | mask$ | Specifies the format definition (def$) in directives used to create different styles of Chart, Grid, and List Box controls. Used for character string mask$ in a Multi-Line.
| KEY=char$ | Defines hot key character in a Drop Box, List Box, Multi-Line, Variable Drop Box, and Variable List Box.
| LEN=num | Defines maximum number of input characters allowed in a Multi-Line, Variable Drop Box, and Variable List Box.
| MSG=text$ | Supplies the text that is to appear on the message line when the control object has focus.
| MNU=ctl | Assigns ctl value to be associated with a right click Popup Menu event for when the mouse pointer is positioned over the graphical user interface control object.
| NUL=string$ | Defines the null field display value in a Multi-Line control.
| OPT=char$ | Applies single character attribute/behaviour settings. Some characters may be combined (e.g. the combination OPT="VUTf" on a button creates an HTML-style hotspot).
| SEP=char$ | Sets the input line or column separator for Chart, Grid, List Box and Multi-Line controls. Hex or ASCII value (e.g. SEP=":" or SEP=$3A$ ...).
| TBL=char$ | Table of single character values to represent the displayed options. The first character represents the first entry, etc.
| TIP=text$ | Provides text to be used as the floating tip message when the mouse pointer hovers over the control.

Dynamic Control Properties

Graphical user interface control objects have a variety of properties associated with them. The Apostrophe Operator (tick) allows dynamic access to the property names used to define these attributes for a given graphical user interface control. Any numeric variable containing the CTL number associated with a control can be used with the apostrophe operator. This feature allows you to redesign a control object dynamically in your application by assigning or resetting its properties/attributes.

Example:

A button's location, size, text, and color would be represented by properties named Col, Line, Text$, TextColor$, etc. You could change the text of a button control (called MyButton) as follows:

> MyButton.ctl'Text$ = "Hit me now"

Other common property names include:

| 'Col | Starting column
| 'Line | Starting line
| 'Cols | Width of control
| 'Lines | Height of control
| 'Tip$ | Tip message
| 'Msg$ | Message line
| 'Fmt$ | Format mask
| 'BackColor$ | Background color
| 'Enabled | Enabled state
| 'Lock | Locked state
| 'Value$ | Current value/state of control

To obtain a complete list of properties for a given control, read the logical attribute *.

Example:

> X=100
> PRINT X'*

> This example results in a list of the attributes for the control defined with a CTL value of 100.

There is virtually no end to what can be changed on the fly within your controls. Most control commands can be changed by accessing attributes.

#### Warning!
NOMADS stores the current value of a control in a variable with the same name as the control.
If you change a control value using the 'Value$ property, you must also change the control's variable to keep NOMADS in sync.