The following steps outline a basic strategy for learning how to use the HLU interface.
To see the logical layout of the HLU section of the User Guide, click on the roadmap icon at the top of this page. You can click on any of the boxes in any roadmap to jump to that module in the User Guide.
In the various sections of the User Guide, you will be introduced to a number of Object Oriented (OO) terms including classes, objects, and resources. When you encounter a new term that is not hypertext-linked to a defining area of the documentation, you can check its meaning by clicking on the glossary icon in any control panel at the top of the module, then searching for the term alphabetically.
As a user of HLUs, you will be creating objects from class (functionality) templates, and manipulating the objects by assigning values to resources. For example, you might create a TextItem object and assign different fonts to the text using the txFont resource. In one instance of a TextItem object, you may use the Courier font, such as to create tables where columns line up because all characters in the Courier font have identical widths. In another instance of a TextItem object, you may want to use a font that was designed for better readability.
Within the HLU section of the User Guide, you will learn what kinds of objects can be created, the resources that apply to each object, and how you can set the values of these resources.
Understanding classes and objects describes the types of classes in the HLU library and class relationships that determine how instantiated objects can be manipulated to get the desired results.
For example, there is a View class that provides templates for various graphical objects such as a TextItem or an XyPlot. There is a Workstation class that provides templates for display objects such as an X Window or a file where graphics instructions are stored for later display. In a typical HLU program, you will create objects that define your application, input your data, draw graphics, and determine where the graphics are sent. The chart Class hierarchy diagram shows the hierarchical relationships of the HLU object library.
In a typical HLU program, you will create:
HLU resources - alphabetically contains an alphabetical list of all resources. The first two characters of a resource name are an identifier of the class to which the resource applies. For example, "am" is for AnnoManager. At the top of the list is a set of class names that link you to the beginning of the resources for that class. At first reading, you might want to look at a couple of the classes with a lesser number of resources like TextItem (prefix "tx") and Workstation (prefix "wk"). The number of resources available to the TickMark, XyPlot, ContourPlot, StreamlinePlot, and VectorPlot classes can be rather daunting at first review. Later, however, when you are creating a finely tailored plot, we hope you will enjoy the detailed level of control these resources provide.
Study some examples using the Quick Start Guide and ng4ex.
These facilities provide you with a full range of HLU programs that use both the Fortran and C HLU interfaces. Study the codes and the example graphics.
Example naming
Examples are named as follows: A two-character prefix designates the graphical object type from this list.
Object type two-character prefix on example names ------------ ------------------------------------- ContourPlot cn GraphicStyle pr (stands for "primitives") Legend lg LabelBar lb MapPlot mp TextItem tx TickMark tm Title ti StreamlinePlot st VectorPlot vc XyPlot xy
Following the two-character object identifier is a two-digit example number. Finally, the fifth character designates the language in which the example is coded, using "f" for Fortran, "c" for C, or "n" for NCL. Thus, "cn03c" indicates ContourPlot example number three coded in C.
When you are ready to write your first program, start from an existing example that is similar to what you want to do. There are examples for all of the available graphical objects. You can copy the example code and the example resource file into your working directory using the ng4ex command.
Some useful options include:
ng4ex -list -all list the names of all available examples ng4ex -list -type where type is one of: basic, contourplot, graphicstyle, legend, labelbar, mapplot, streamlineplot, textitem, tickmark, title, vectorplot, or xyplot. ng4ex lg01f Copies the example lg01f into your working directory, compiles the source code, and runs the code to create an output graphic. ng4ex -n lg01f Copies the example lg01f into your working directory without compiling and running the code.
Once you have an example to start from, refer to the Writing an HLU program module and start modifying the code to achieve the results you want.
Commands are available for compiling and loading your C or FORTRAN-coded HLU programs. These commands are called nhlcc (for C programs) and nhlf77 (for FORTRAN programs).
$NCARG_ROOT is the environment variable that gives the pathname to where NCAR Graphics is installed on your system. See your NCAR Graphics Site Representative or NCAR Graphics Site Installer for help with either creating make files, or using the series of commands to run C or Fortran programs that link in all the needed graphics and related libraries.
Once your program has compiled and run your module, either a plot will appear in a window (an XWorkstation object was created) or a graphics file will appear in the directory. If the file is named with a .ncgm suffix, it can be viewed with ctrans. If it has a postscript variant suffix, it can be viewed with a PostScript previewer such as ghostscript, or sent to a PostScript printer.
NG4.1 Home, Index, Examples, Glossary, Feedback, UG Contents, UG WhereAmI?