NCL Home > Documentation > HLUs > User Guide

API structure (HLU function interface)

Functions that apply to all HLU classes are called base functions. This is because they are defined for all objects that are members of the Base class. There are specific functions that apply to only one type of class. There is one function, NhlDraw, that applies to two high-level classes that contain many subclasses. Finally, there are a few general functions which are not class-related. The functions are listed below by category.

Base API functions

Most functions in the HLU API are specific to individual class; however, the following four functions apply to every HLU class:

  • NhlCreate

    Creates an instance of any HLU object.

  • NhlSetValues

    Modifies the current values of resources for any HLU object.

  • NhlGetValues

    Retrieves the current values of resources for any HLU object.

  • NhlDestroy

    Destroys any HLU object, freeing all memory and system resources used by the object.

API functions used by more than one class

  • NhlDraw

    This function is called by the user to produce the graphical output. This function is available for View and Workstation objects. If it is called on the View class, that object's graphical output is sent to the workstation. If it is called on the Workstation class, all of the Workstation children are drawn.

Specific API functions by class

Application class

  • NhlAppGetDefaultParent

    Retrieves the ID of the current default parent App object.

Data class

  • NhlAddData

    Associates a DataItem with a data resource.

  • NhlRemoveData

    Unassociates a DataItem from a data resource.

  • NhlUpdateData

    Tells a DataComm object to update its internal state with the changes of any DataItem objects that are associated with its data resources.

Workstation class

  • NhlChangeWorkstation

    Re-routes graphical output to another workstation. It can be used to output a graphic to more than one workstation type.

  • NhlUpdateWorkstation

    Updates the drawing area of an instance of a Workstation object. It flushes any output that has been sent to the workstation but that has not yet been displayed.

  • NhlClearWorkstation

    Clears the drawing area of an instance of a Workstation object.

  • NhlFrame

    Updates and then clears the drawing area of an instance of a Workstation object.

  • NhlNewColor

    Adds a color specified as an RGB triple to the colormap of a Workstation instance and returns its HLU color index.

  • NhlSetColor

    Sets the RGB color values for a specified HLU color index.

  • NhlFreeColor

    Removes a color, specified by its HLU index, from the Workstation color map.

  • NhlIsAllocatedColor

    Returns True if a color has been assigned to a particular HLU color index, and False otherwise. (IsAllocatedColor is a boolean function.)

See also XWorkstation, NcgmWorkstation, and PSWorkstation.

View class

  • NhlGetBB

    Given the id of a View object, returns the coordinates of the left, right, top, and bottom edges of the object's bounding box in NDC units.

Transform class

  • NhlAddAnnotation

    Adds an arbitrary View object to a plot object as an external annotation, and returns the id of the AnnoManager object created to manage it.

  • NhlRemoveAnnotation

    Removes a View object annotation from a plot object, destroying the AnnoManager object created to manage it.

  • NhlAddOverlay

    Adds a Transform object as an overlay plot member to a base plot object.

  • NhlRemoveOverlay

    Removes an overlay plot member from a base plot object.

Error class

  • NhlPError, NHLPERROR, NhlErrGetId, NhlErrNumMsgs, NhlErrGetMsg, NhlErrCleanMsgs, NhlErrAddTable, NhlErrSPrintMsg, NhlErrFPrintMsg

Workspace class

  • NhlGetWorkspaceObjectId

    Retrieves the id of the Workspace object.

API functions not related to class

There are several important functions that are not class-related; these include:

  • NhlOpen

    Opens and initializes the HLU library. If called, it must be the first API function called in an HLU user program. NhlOpen automatically creates an App object which attempts to access the level 1 and 3 application resource files whose pathnames are defined by the $NCARG_SYSRESFILE and $NCARG_USRRESFILE variables. (See alternative call NhlInitialize.)

  • NhlInitialize

    Opens and initializes the HLU library. NhlInitialize differs from NhlOpen in that the programmer must create an App object using NhlCreate before creating any other objects.

  • NhlClose

    Closes the HLU library. It must be the last API function called in an HLU user program.

See also: