# Using GrADS with Athena Widgets

# Contents

1. Introduction
2. Running the sample script
3. Writing simple scripts
4. Writing the sample script
5. Going further...
6. Reference Section

# Introduction

Starting with version 1.7, GrADS offers a simpler way of creating a Graphical User Interface (GUI) based on libsx, the Simple X Library by Dominic Giampaolo. Libsx is a C library layered on top of the Athena widget set which allows the programming reasonable interfaces with minimum effort. We have built a GrADS interface to libsx, so that users can enjoy the same simplicity when creating basic graphical user interfaces in GrADS. In this document we will refer to this GrADS interface to libsx as GAGUI. Parts of this documentation are adapted from the libsx manual by Dominic Giampaolo.

If you've ever wanted to just open a window with a few buttons and automate some of the GrADS functions, but were turned away by the complexity of trying to do that with a gs script, then GAGUI may be your ticket. GAGUI is capable of easily creating many types of user-interface components each with a single function call of a few arguments. The interface supports the following ``widgets'':

- Labels
- Buttons
- Menus
- Toggle buttons
- File finder
- Variable selection
- Opened file selection
- Display of GrADS expressions
- Text file browser for help files
- GrADS command window with scrollable history
- Access to GrADS commands

The goal of GAGUI is to make the creation and manipulation of each of these items as simple as possible. The standard simplicity litmus test is a Hello World script, which in GAGUI is:

> MakeLabel(w,"Hello World")
> MainLoop()

More complicated interfaces use a similar style of creation and complete applications usually require less than 30 lines of user defined script to create an entire user interface complete with menus, buttons, file finder, etc. For example, to create a script that opens a window with a file finder and a Quit button, all one must do is:

> MakeButton( open, "Open", Load, "open" )
> MakeButton( close, "Close", CloseWindow, NULL )
> SetWidgetPos(close, PLACE_RIGHT, open, NO_CARE, NULL)
> MainLoop()

The precise meaning of each of the arguments of MakeButton() and the other GUI functions is discussed is subsequent sections.

If you are familiar X Widgets available with the gs scripting language, you will notice that GAGUI, unlike the gs X widgets, uses the event driven paradigm for building widgets. The actual function to be executed when the user clicks on a button is specified during the definition of the widgets; there is no need for the user to write additional code to handle the widget selection beyond this definition step. This provides for fewer lines of code and ease of maintenance.

GAGUI was originally written to facilitate the development of Graphical User Interface for data CDROMs produced at NASA's Data Assimilation Office (DAO). Please notice that the current version of GAGUI is still experimental. Function arguments as well as the syntax of the GUI scripting language is likely to undergo changes in the near future.

This document is organized as follows:

- Section Running the sample script explains how to run one of the provided sample scripts, introducing the main features of GAGUI from the user point of view. If you don't plan to do any programming with GAGUI you should stop here.
- Section Writing simple scripts introduces the main features of GAGUI scripting through a simple example.
- Section Writing the sample script gives a walkthrough of a relatively complex GAGUI script, the same one we showed you how to run.
- Section Going further... wraps things up, indicating which additional features not covered in the previous sections can be found in other provided sample scripts.
  DAO users: Also discussed here is a script customized for use on melrose.
- Section Reference Section lists alphabetically all GUI functions and callbacks available.

### If you don't like reading documentation

Then don't read this document. You should be able to get by reading one of the annotated sample scripts, say sample.gui. Take a look at the Going further... section for a list of additional sample scripts. With a bit of hacking you should be able to customize these scripts for your own taste and needs. The Reference Section can be consulted if you are unsure about some specific syntax.

Good Luck!

Next section: Running the sample script