NCL Home > Documentation > HLUs > User Guide

HLU plot creation sequence

Components of a TextItem program

Building a Fortran program

Select the needed objects.
First, let's set our resources in a local resource file which is specific to this application. Thus we will use the combination of NhlInitialize and an NhlCreate of an App object. We could also have chosen to use NhlOpen and set the resources in the file whose pathname is given by system variable $(NCARG_USRRESFILE). Or we could choose to set resources directly in the program using arguments in Create calls or by using the NhlSetValues functions.
We do not need a data object since TextItem does not import data. The text string to be written is merely entered as a resource.
Next, we need a workstation object in which to draw or write our graphical instructions. Suppose we just choose an X Window, which is an XWorkstation object.
Finally, we need a View object, namely TextItem.
Select the needed header files.
Now that we know which objects we need, we can define the header files that are needed; these include:
Fortran:
```
      external nhlfappclass
      external nhlfxworkstationclass
      external nhlftextitemclass
```
App, XWorkstation, and TextItem are the classes we are going to use in this program.
Fortran headers lists the headers for all objects.
Open and initialize the HLU library.
Fortran:
```
      call nhlfinitialize
```
Create an application context. Set the app dir to the current directory so the application looks for a resource file in the working directory.
Fortran:
```
      call nhlfrlcreate(rlist,'setrl')
      call nhlfrlclear(rlist)
      call nhlfrlsetstring(rlist,'appDefaultParent','True',ierr)
      call nhlfrlsetstring(rlist,'appUsrDir','./',ierr)
      call nhlfcreate(appid,'tx01',nhlfappclass,0,rlist,ierr)
```
This section of code
- creates a resource list,
- clears the list,
- adds NhlNappUsrDir resource of the App object to the resource list with a setstring call to the current working directory (./), then
- creates an application object.
It returns the id tag appid. The name of the resource file is tx01 with .res appended: tx01.res. This App object is of type NhlappClass. Its resources are initialized using the values in the resource list rlist.
When we run this program, it will expect to find a resource file named tx01.res in the current working directory.
Create an XWorkstation object.
Fortran:
```
      call nhlfrlclear(rlist)
      call nhlfrlsetstring(rlist,'wkPause','True',ierr)
      call nhlfcreate(wid,'tx01Work',nhlfxworkstationclass,
     $     0,rlist,ierr)
```
This section of code
- clears the resource list,
- puts the resource wkPause in the resource list with a value of True, then
- creates an XWorkstation object.
The id is returned in wid. This is an object of type NhlxWorkstationClass. Its resources are defined by initialized by the values in rlist. The class contains defaults for the values that are not defined by rlist or the resource file.
Set any resources in rlist (optional), and create a TextItem object.
Fortran:
```
      call nhlfrlclear(rlist)
      call nhlfrlsetfloat(rlist,'txPosXF',.5,ierr)
      call nhlfrlsetfloat(rlist,'txPosYF',.5,ierr)
      call nhlfrlsetfloat(rlist,'txJust','CenterCenter',ierr)
      call nhlfcreate(pid,'TextItem1',nhlftextitemclass,
     $     wid,rlist,ierr)
```
This section of code
- clears the resource list,
- puts the resources that will define the position of the TextItem in the resource list, then
- creates the TextItem object.
The id is returned in pid, it is an object of type NhltextItemClass, it has the parent wid, and its resources are set by the values in rlist.
Note: The resources could also be set in the resource file tx01.res.
Output the graphics to the X Window.
Fortran:
```
      call nhlfdraw(pid,ierr)           or call nhlfdraw(wid,ierr)
      call nhlfframe(wid,ierr)
```
The draw function causes the TextItem object, id = pid, to be drawn. The frame function flushes the output device. Since we set the NhlNwkPause XWorkstation resource to True, the plot will be drawn and held in the window awaiting a click in the window.
Destroy all objects which are no longer needed (optional).
If you intend to continue the program and create some new and different App, Plot, or Workstation objects, and if you no longer need any of the current objects, then good programming practice is to delete the objects that are no longer required in order to keep the memory size of your program down. If you are about to end the program, go on to Step 9.
Fortran:
```
      call nhlfdestroy(pid,ierr)
      call nhlfdestroy(wid,ierr)
      call nhlfdestroy(appid,ierr)
```
Close the HLU library and exit.
Fortran:
```
      call nhlfclose
      stop
      end
```
This section of code destroys all existing objects, closes the HLU library, and exits our program.

Building a C program;

Select the needed objects.
First, let's set our resources in a local resource file which is specific to this application. Thus we will use the combination of NhlInitialize and an NhlCreate of an App object. We could also have chosen to use NhlOpen and set the resources in the file whose pathname is given by the environment variable $(NCARG_USRRESFILE). Or we could choose to set resources directly in the program using resource list arguments in Create calls or by using the NhlSetValues functions.
We do not need a data object since TextItem does not import data. The text string to be written is merely entered as a resource.
Next, we need a workstation object in which to draw or write our graphical instructions. Suppose we just choose an X Window, which is an XWorkstation object.
Finally, we need a View object, namely TextItem.
Select the needed header files.
Now that we know which objects we need, we can define the header files that are needed; these include:
C:
```
#include <ncarg/hlu/App.h>
#include <ncarg/hlu/TextItem.h>
#include <ncarg/hlu/XWorkstation.h>
```
App, XWorkstation, and TextItem are the objects we are going to use in this program.
C headers lists the headers for all objects.
Open and initialize the HLU library.
C:
```
	NhlInitialize();
```
Create an application context. Set the app dir to the current directory so the application looks for a resource file in the working directory.
C:
```
        rlist = NhlRLCreate(NhlSETRL);
        NhlRLClear(rlist);
	NhlRLSetString(rlist,NhlNappDefaultParent,"True");
	NhlRLSetString(rlist,NhlNappUsrDir,"./");
	NhlCreate(&appid,"tx01",NhlappClass,NhlDEFAULT_APP,rlist);
```
This section of code
- creates a resource list,
- clears the list,
- adds the NhlNappUsrDir resource of the App object to the resource list with a SetString call to the current working directory (./), then
- creates an application object.
It returns the id in appid. The name of the resource file is tx01 with a .res appended: tx01.res. This App object is of type NhlappClass. Its resources are initialized by the resource names and values contained in rlist.
When we run this program, it will expect to find a resource file named tx01.res in the working directory.
Create an XWorkstation object.
C:
```
	NhlRLClear(rlist);
	NhlRLSetInteger(rlist,NhlNwkPause,True);
	NhlCreate(&wid,"txxwork",NhlxWorkstationClass,NhlDEFAULT.APP,rlist);
```
This section of code
- clears the resource list,
- puts the resource NhlNwkPause in the resource list with a value of True, then
- creates an XWorkstation object.
The id is returned in wid. This is an object of type NhlxWorkstationClass. Its resources are initialized by rlist.
Set any resources in rlist (optional) and create a TextItem object.
C:
```
        NhlRLClear(rlist);
	NhlRLSetFloat(rlist,NhlNtxPosXF,.2);
	NhlRLSetFloat(rlist,NhlNtxPosYF,.8);
	NhlRLSetInteger(rlist,NhlNtxJust,NhlCENTERCENTER);
	NhlCreate(&pid,"TextItem1", NhltextItemClass,wid,rlist);
```
This section of code
- clears the resource list,
- puts the resources that will define the position of the TextItem in the resource list, then
- creates the TextItem object.
The id is returned in pid, it is an object of type NhltextItemClass, it has the parent wid, and its resources are set by the values in rlist.
Note: The resources could also be set in the resource file tx01.res.
Output the graphics to the X Window.
C:
```
	NhlDraw(pid);
	NhlFrame(wid);
```
The draw function causes the TextItem object, id = pid, to be drawn. The frame function flushes the output device. Since we set the NhlNwkPause XWorkstation resource to True, the plot will be drawn and held in the window awaiting a click in the window.
Destroy all objects that are no longer needed (optional).
If you intend to continue the program and create some new and different App, Plot, or Workstation objects, and if you no longer need any of the current objects, then good programming practice is to delete the objects that are no longer required in order to keep the memory size of your program down. If you are about to end the program, go on to Step 9.
C:
```
	NhlDestroy(pid);
	NhlDestroy(wid);
	NhlDestroy(appid);
```
Or you could just destroy the App object since it is the ancestor of the other objects; this will cause all of its children to be destroyed as well. (This is also why the destroy calls above must be in the order in which they appear.)
C:
```
	NhlDestroy(appid);
```
Close the HLU library and exit.
C:
```
	NhlClose();
	exit(0);
```
This section of code destroys all existing objects, closes the HLU library, and exits our program.

The TextItem example code

The complete programs for the examples presented above can be loaded into your current directory by issuing the commands:

    ng4ex tx01c

for the C version, or

    ng4ex tx01f

for the Fortran version.

The TextItem resource file

In the TextItem example 01, we set resources for our objects directly in the code. We can also set resource values in the resource file tx01.res. Remember that if you set a resource in both places, the value set in the code takes precedence.

Either of the ng4ex commands above will also load tx01.res into your working directory.

An XyPlot example

Now consider a View object that needs a data object. xy01f.f is a Fortran program that generates an XyPlot using default values for all resources. The list of XyPlot resources are commented in the associated resource file xy01.res. An equivalent C version of this example is xy01c.c. You can view any of these files by typing:

    ng4ex xy01c