Writing an HLU program

This module describes general steps to follow in writing an HLU program; it provides examples for writing a TextItem program in Fortran and C.

Write an HLU program in either Fortran or C using API functions. The logical program steps are:
- Select a header file that matches each object type to be created.
- Open the HLU library.
- Create an App object to provide access to the resource database (optional).
- Create a DataItem object (only needed for XyPlot or ContourPlot objects).
- Create workstation object(s) (XWorkstation, NcgmWorkstation, or PSWorkstation).
- Create view object(s) (ContourPlot, XyPlot, TextItem, etc.).
- Assign resources to objects in the code or in a resource file.
- Draw to send the graphics to the output workstation.
- Frame to cause a pause or erase (X11), or a picture advance (PS, NCGM).
- Destroy all created objects.
- Close the HLU library.
A recommended approach is to look at the many examples existing under ng4ex and select the one which is closest to your desired task.
Create a resource data file. Set resources to desired values.
Compile and execute the program using nhlcc, nhlf77, or the make files.
Run the program module and look at the graphical output.
Change resources in the resource file and re-execute the program module.

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 X11 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, TextItem, and XWorkstation are the classes that 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 needed to configure the application object, clears the list, sets the NhlNappUsrDir resource of the App class, with a NhlRLSetString call, to the current working directory ("./"), then creates an application object whose id is returned within the parameter appid. Since the name of the application is set to "tx01" in the create call, the resource file is named tx01 with a .res appended: tx01.res. This app object is of type NhlappClass.
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, sets a resource which will cause the XWorkstation object to pause when NhlFrame is called on the the XWorkstation object. This is done by setting the XWorkstation resource NhlNwkPause to True. The XWorkstation object is then created an XWorkstation object. The id is returned in wid. This is an object of type NhlxWorkstationClass.
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,'txFontHeightF',.2,ierr)

      call nhlfrlsetstring(rlist,'txString','NCAR Graphics',ierr)

      call nhlfcreate(pid,'TextItems',nhlftextitemclass,

     $     wid,rlist,ierr)
```
This section of code clears the resource list, defines the position to locate the output text string in the X11 window. The position is set to (.5,.5) in (X,Y) viewport coordinates, called normalized device coordinates. The entire viewport is 0. to 1. in both dimensions. This section also sets the height of the output string to be .2 or approximately one fifth of the X11 window. The resources NhlNtxPosXF, NhlNtxPosYF, and NhlNtxFontHeightF are added to rlist using the NhlRLSetFloat function and NhlNtxString is set using the NhlRLSetString functions. The TextItem object is then created and returns its id in pid. This is an object of type NhltextItemClass, it has the parent wid, and its resources are set by rlist.
Note: The location, height and string resources could also be set in the resource file tx01.res.
Output the graphics to the X11 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 mouse 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 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 that 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 X11 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/hlu.h>
The HLU library header is always required.
C:
```
#include <ncarg/hlu/App.h>

#include <ncarg/hlu/TextItem.h>

#include <ncarg/hlu/XWorkstation.h>
```
App, TextItem, and XWorkstation 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 needed to configure the application object, clears the list, sets the NhlNappUsrDir resource of the App class, with a SetString call, to the current working directory ("./"), then creates an application object whose id is returned within the parameter appid. Since the name of the application is set to "tx01" in the create call, the resource file is named tx01 with a .res appended: tx01.res. This app object is of type NhlappClass.
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.
C:
```
	NhlRLClear(rlist);

	NhlRLSetInteger(rlist,NhlNwkPause,True);

	NhlCreate(&wid,"txxwork",NhlxWorkstationClass,NhlDEFAULT.APP,rlist);
```
This section of code clears the resource list, sets a resource which will cause the XWorkstation object to pause when NhlFrame is called on the the XWorkstation object. This is done by setting the XWorkstation resource NhlNwkPause to True. The XWorkstation object is then created an XWorkstation object. The id is returned in wid. This is an object of type NhlxWorkstationClass.
Set any resources in rlist (optional) and create a TextItem object.
C:
```
	NhlRLClear(rlist);

	NhlRLSetFloat(rlist,NhlNtxPosXF,.5);

	NhlRLSetFloat(rlist,NhlNtxPosYF,.5);

	NhlRLSetFloat(rlist,NhlNtxFontHeightF,.2);

	NhlRLSetString(rlist,NhlNtxString,"NCAR Graphics");

	NhlCreate(&pid,"TextItems",

		  NhltextItemClass,wid,rlist);
```
This section of code clears the resource list, defines the position to locate the output text string in the X11 window. The position is set to (.5,.5) in (X,Y) viewport coordinates, called normalized device coordinates. The entire viewport is 0. to 1. in both dimensions. This section also sets the height of the output string to be .2 or approximately one fifth of the X11 window. The resources NhlNtxPosXF, NhlNtxPosYF, and NhlNtxFontHeightF are added to rlist using the NhlRLSetFloat function and NhlNtxString is set using the NhlRLSetString functions. The TextItem object is then created and returns its id in pid. This is an object of type NhltextItemClass, it has the parent wid, and its resources are set by rlist.
Note: The location, height and string resources could also be set in the resource file tx01.res.
Output the graphics to the X11 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 mouse 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 to Step 9.
C:
```
	NhlDestroy(appid);

	NhlDestroy(pid);

	NhlDestroy(wid);
```
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.

User Guide Control Panel

NG4.1 Home, Index, Examples, Glossary, Feedback, UG Contents, UG WhereAmI?

$Revision: 1.24 $ $Date: 1998/07/31 00:52:04 $

Writing an HLU program

Components of a TextItem program

Building a Fortran program

Building a C program

See also:

User Guide Control Panel