Strategies for learning HLUs
The following steps outline a basic strategy for learning how to use the HLU interface.
Step 1. Do a first reading of the HLU section of the User Guide
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 User Guide documentation, 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.
Step 2. Understand the types of classes available and the class hierarchy
If you skimmed this area of the HLU User Guide in Step 1 above, review it again carefully.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:
- An App object that will identify the application represented by your HLU program, name your application resource file, and tell where it is located.
- One or more View objects. View objects are used to create the graphics. View objects include Title, TickMark (for grids as well as tick marks), Legend, LabelBar, XyPlot, ContourPlot, StreamlinePlot, VectorPlot, MapPlot, and TextItem.
- One or more Workstation objects. The types of Workstation objects include PSWorkstation for PostScript output, PDFWorkstation for PDF output, XWorkstation for display in an X Window, and NcgmWorkstation to produce an NCAR-encoded Computer Graphics Metafile (file named with a ".ncgm" extension).
- An optional DataItem object. If you are creating an XyPlot, ContourPlot, StreamlinePlot, or VectorPlot, you will also need to create a DataItem object containing the data to be plotted.
Step 3. Review the resource set of a couple classes
HLU objects use resources like traditional subroutines use parameters or arguments. They allow for the selection of options that define the object behavior. For example, in the case of a graphical object, resources might be used to select line widths, colors, fonts, or other graphical entities.The resources table 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.
Step 4. Review some example programs
Study some examples using the Basic Examples 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.
Step 5. Write your own HLU program
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.
Step 6. Execute your program
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.
Step 7. Refine the graphics
Review your graphical output, change the resource values in your code and/or in the resource file, execute the module again, and study the many ways you can refine your output. As you become a more proficient user of HLUs, the content of the HLU User Guide will become more useful to you, and you will find the HLU documentation to be a rich source of detailed information.See also: