NCL Website header
NCL Home > Documentation > HLUs > Classes

App class

The App class is used to manage resource databases.

Synopsis

Header file:		ncarg/hlu/App.h
Class name:		appClass
Class pointer:		NhlappClass
Fortran class function:	NHLFAPPCLASS
Superclass:		Base
Composite classes:	<None>
Note: If the HLU library is initialized with the NhlOpen function, then the default App class object will be named hlu.

Resources

Local resources

+---------------------------------------------------------------+
|			App Resource Set			|
|---------------------------------------------------------------|
| NAME				TYPE			ACCESS	|
|	CLASS				DEFAULT			|
|===============================================================|
| appUsrDir			NhlTString		RCG*	|
|	AppUsrDir			./			|
|---------------------------------------------------------------|
| appSysDir			NhlTString		RCG*	|
|	AppSysDir			<Dynamic>		|
|---------------------------------------------------------------|
| appFileSuffix			NhlTString		RCG*	|
|	AppFileSuffix			.res			|
|---------------------------------------------------------------|
| appDefaultParent		NhlTBoolean		RCSG	|
|	AppDefaultParent		<Dynamic>		|
|---------------------------------------------------------------|
| appResources			NhlTStringGenArray	RCG	|
|	AppResources			NULL			|
+---------------------------------------------------------------+
* These resources are settable from the resource database; however, they cannot be specified in the application-specific resource files.

Superclass resources

There are no Superclass resources.


Description

All HLU applications must create at least one App class object. This is because each object in the HLU library needs to have an App object for its most top-level parent. It keeps track of the Resource Database for all objects that are created as descendants of it. The first App object that is created is somewhat special. It becomes the parent of the Error and Workspace object. Therefore, Error and Workspace resources can only be set in resource files used by the first App object in the application.

Initializing the HLU library

All HLU applications must initialize the HLU library in one of two ways:

First, the easiest method is to simply call the NhlOpen convenience function. If this method is used, it is not possible to interact with the App object directly. The Resource Database managed by this internal App object is made up from the $(NCARG_USRRESFILE) and the $(NCARG_SYSRESFILE), with the user's file taking precedence over the system file. This internal App object is named hlu. This is important to know for specifying resources in these two resource files if this App object is used as the parent for any other objects.

The other way of initializing the library is to call the NhlInitialize function, and then explicitly create an App object. The only reason to select this method is if the application programmer wants to provide an Application specific resource file. This would be a resource file, in the same format as the $(NCARG_SYSRESFILE), but it would only be used to load the Resource Database of the given application. This is especially useful for applications that are shared by a number of users. An application programmer could put a system Application specific resource file in a system directory like $(NCARG_SYSAPPRES). Then, the application programmer can provide appropriate defaults for the application for all users.

Additionally, the end user also has the ability to provide an Application specific resource file in this case. If the application explicitly creates the App object, then there are four resource files that get used, in an increasing order of precedence:

  1. $(NCARG_SYSRESFILE)
  2. System Application Specific Resource file.
  3. $(NCARG_USRRESFILE)
  4. Users Application Specific Resource file.
The Application Specific resource files are found by using the resources in the App class object. The name of the App class object indicates the base name of the Application resource files. The appFileSuffix resource indicates the suffix of the Application resource files.

The appUsrDir resource indicates the directory to look for the Users Application resource file. While the appSysDir resource is used to specify the directory the System Application Specific resource file can be found in.

The appResources resources is a very useful resource for Application developers. It allows you to defined your own resource names. This resource contains an array of string names. Each one of the names contained in this resource will become a valid resource to that App object. Resource names should be picked with some care, since not all names will work. For example, since the "." (period) is a special character for resource file syntax, a name containing a period would not be a good choice. Also, if you pick a name that is already a resource name for the App object, you will actually be interacting with the App object defined resource, and not the Application defined one. It is important to realize that all resource values for appResources defined resources are stored as strings. This means that all assigns are converted to strings, and all getvalues are converted from strings.


Support functions

The App object defines the following support functions:
NhlAppGetDefaultParentId
This function is used to retrieve the ID of the App object that currently has it's appDefaultParent resource set to True.
NhlIsApp
This function just determines if a given object id identifies an App class object.

See also