This module describes general steps to follow in writing an HLU program; it provides examples for writing a TextItem program in Fortran and C.
A recommended approach is to look at the many examples existing under ng4ex and select the one which is closest to your desired task.
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.
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.
Fortran:
call nhlfinitialize
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.
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.
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.
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.
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)
Fortran:
call nhlfclose
stop
end
This section of code destroys all existing objects, closes the HLU library, and exits our program.
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.
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.
C:
NhlInitialize();
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.
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.
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.
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.
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);
C:
NhlClose();
exit(0);
This section of code destroys all existing objects, closes the HLU library, and exits our program.
NG4.1 Home, Index, Examples, Glossary, Feedback, UG Contents, UG WhereAmI?