NCL Home > Documentation > HLUs > Classes

Workstation class

A Workstation object manages an instance of an output device.

Synopsis

Header file:		ncarg/hlu/Workstation.h
Class name:		workstationClass
Class pointer:		<Not referenceable>
Fortran class function:	<Not referenceable>
Superclass:		Base
Composite classes:	<None>

Class-defined types

Type name:		NhlTColorIndex
Definition:		typedef int NhlColorIndex;
				Range is -1 to 255 
				-1:	NhlTRANSPARENT
				 0:	NhlBACKGROUND
				 1:	NhlFOREGROUND
                        Available in version 6.1.0 and later.
			The color index type has been expanded to include 
			high numbered values ranging from 1073741824
			to 2147483647 that map to specific 30-bit RGBA values 
			(8 bits for red, green, and blue + 6 bits for 
			opacity).

Type name:		NhlTColorMap
Definition:		A name of a pre-defined colormap, or an array
                        of a combination of RGB values, named colors,
                        and other color specification formats.

Type name:		NhlTColorIndexGenArray
Definition:		An array of NhlTColorIndex elements.

Type name:		NhlTColorDefinitionGenArray
Definition:             A one-dimensional array defining an RGB triplet or an RGBA quadruplet,
                        or a string containing a color name from
                        $NCARG_ROOT/lib/ncarg/database/rgb.txt.

Type name:		NhlTDashIndex
Definition:		typedef int NhlDashIndex;
				Valid Range is 0 to NhlNwkDashTableLength
				 0:	NhlSOLIDLINE	"SolidLine", "Solid"
		                 1:			"Dash", "D4U2"
		                 2:			"Dot",  "DU2"
		                 3:			"DashDot", "D4U2DU2"
		                 4:			"DashDotDot", "D4U2DUDU2"
		                 5:			"D2U"
		                 6:			"D3U"
		                 7:			"DUD2U"
		                 8:			"DUD3U"
		                 9:			"D2UD4U"
		                10:			"D4UD2UDUD2U"
		                11:			"D2U2"
		                12:			"D6U2"
		                13:			"D3UD3U2"
		                14:			"D2U3"
		                15:			"DUDU3"
		                16:			"D5U5"

Type name:		NhlTDashIndexGenArray
Definition:		An array of NhlTDashIndex elements.

Type name:		NhlTFillIndex
Definition:		typedef in NhlFillIndex {
				Valid Range is -1 to NhlNwkFillTableLength
				-1:	NhlHOLLOWFILL	"HollowFill", "Hollow", "NullFill"
				 0:	NhlSOLIDFILL   	"SolidFill", "Solid"
		                 1:             	"HatchHorizontal"
		                 2: 		        "HatchVertical"
		                 3:             	"Hatch_45"
		                 4:             	"Hatch_135"
		                 5:             	"CrossHatch"
		                 6:             	"CrossHatch_45"
		                 7:             	"Hatch_22"
		                 8:             	"Hatch_68"
		                 9:             	"Hatch_112"
		                10:            		"Hatch_158"
		                11:            		"CrossHatch_22"
		                12:            		"CrossHatch_68"
		                13:            		"CrossHatch_0_60"
		                14:            		"CrossHatch_0_60_120"
		                15:            		"CrossHatch_0_45_90"
		                16:            		"CrossHatch_0_45_90_135"
		                17:            		"Stippled"


Type name:		NhlTFillIndexGenArray
Definition:		An array of NhlTFillIndex elements.

Type name:		NhlTMarkerIndex
Definition:		typedef int NhlMarkerIndex;
				Valid Range is 0 to NhlNwkMarkerTableLength
				 0:			"default"
				 1:			"dot"
				 2:			"+"
				 2:			"plus"
				 3:			"*"
				 3:			"asterisk"
				 4:			"hollow_circle"
				 5:			"cross"
				 5:			"x"
				 6:			"hollow_square"
				 7:			"up_triangle"
				 8:			"down_triangle"
				 9:			"diamond"
				10:			"left_triangle_filled"
				11:			"right_triangle_filled"
				12:			"star_5point"
				13:			"star_6point"
				14:			"circle_w_dot"
				15:			"circle_w_cross"
				16:			"circle_filled"

Type name:		NhlTMarkerIndexGenArray
Definition:		An array of NhlTMarkerIndex elements.

Type name:		NhlTMarkLineMode
Definition:
typedef enum _NhlMarkLineMode {
	NhlLINES	= 0,	/* "Lines"	*/
	NhlMARKERS	= 1,	/* "Markers"	*/
	NhlMARKLINES	= 2	/* "MarkLines"	*/
} NhlMarkLineMode;

Type name:		NhlTMarkLineModeGenArray
Definition:		An array of NhlTMarkLineMode elements.

Type name:		NhlTVisualType
Definition:		typedef enum {
				NhlCOLOR	= 0,	/* "Color"	*/
				NhlMONOCHROME	= 3	/* "Monochrome"	*/
			} NhlVisualType;

Type name:		NhlTColorModel
Definition:		typedef enum {
				NhlCMYK		= 0,	/* "CMYK"	*/
				NhlRGB		= 1	/* "RGB"	*/
			} NhlColorModel;

Type name:		NhlTWorkOrientation
Definition:		typedef enum {
				NhlPORTRAIT	= 0,	/* "Portrait"	*/
				NhlLANDSCAPE	= 6	/* "Landscape"	*/
			} NhlWorkOrientation;

Resources

Local resources

+---------------------------------------------------------------+
|			Workstation Resource Set		|
|---------------------------------------------------------------|
| NAME				TYPE			ACCESS	|
|	CLASS				DEFAULT			|
|===============================================================|
| wkColorMap			NhlTColorMap        RCSG        |
|	WkColorMap			<Dynamic>		|
|---------------------------------------------------------------|
| wkColorMapLen			NhlTInteger		G	|
|	WkColorMapLen			<Dynamic>		|
|---------------------------------------------------------------|
| wkBackgroundColor     NhlTColorDefinitionGenArray     RCSG    |
|	WkBackgroundColor		(/0.0,0.0,0.0/)		|
|---------------------------------------------------------------|
| wkForegroundColor     NhlTColorDefinitionGenArray     RCSG    |
|	WkForegroundColor		<Dynamic>		|
|---------------------------------------------------------------|
| wkDashTableLength		NhlTInteger		G	|
|	WkDashTableLength		<Dynamic>		|
|---------------------------------------------------------------|
| wkFillTableLength		NhlTInteger		G	|
|	WkFillTableLength		<Dynamic>		|
|---------------------------------------------------------------|
| wkMarkerTableLength		NhlTInteger		G	|
|	WkMarkerTableLength		<Dynamic>		|
|---------------------------------------------------------------|
| wkGksWorkId			NhlTInteger		G	|
|	WkGksWorkId			<Dynamic>		|
|---------------------------------------------------------------|
| wkDefGraphicStyleId		NhlTObjId		G	|
|	WkDefGraphicStyleId		<Dynamic>		|
|---------------------------------------------------------------|
| wkViews			NhlTObjIdGenArray	G	|
|	WkViews  			<Dynamic>		|
|---------------------------------------------------------------|
| wkTopLevelViews		NhlTObjIdGenArray	G	|
|	WkTopLevelViews			<Dynamic>		|
+---------------------------------------------------------------+

Composite resources

The Workstation object class has no composite class objects.

Superclass resources

The superclasses of the Workstation object class do not define any resources.

Description

In the context of the HLU library, the Workstation object class represents the interface to a generalized output device. It is not designed to be instantiated directly. Instead there exist object classes derived from the Workstation object that are specialized for particular types of output. You must always create an object belonging to the Workstation class for any program using the HLU library. All drawable objects must be created with a Workstation parent. Currently there are four object classes subclassed from the Workstation class: XWorkstation for drawing into a window of a workstation running the X Window System, PSWorkstation for creating a PostScript file, PDFWorkstation for creating PDF output, and NcgmWorkstation for creating an NCAR Computer Graphics Metafile. With NCL 5.2.0, two new experimental subclasses have been added: DocumentWorkstation for document-based file formats, such as postscript and PDF, and ImageWorkstation for image-based formats, specifically PNG.

The Workstation object provides access to a color map and tables of line dash patterns, area fill patterns, and markers. There is a default colormap that is shared by all subclasses of Workstation objects, but it is also possible to create an individual colormap for any instance of a Workstation object. The dash pattern, fill pattern, and marker tables are shared by all Workstation objects and are currently read-only. Eventually, however, there will be methods for creating individual user-defined versions of each of these tables.

The Workstation colormap may contain up to 256 different colors, including the background color. You specify the color of features to be drawn using an HLU color index in the range 0 through 255. An allocated color index is one for which an RGB triple defining a color has been specified. Color index 0 specifies the background color and color index 1 specifies the foreground color. The Workstation colormap is defined to repeat itself. So, if you specify a color index that is greater than any of the currently defined indexes, the index will be mapped into the correct range. If you specify a currently unallocated color index for a feature, the Workstation object will use the foreground color. (This refers to color indexes that are unallocated, but are less than another currently defined index. In other words, the holes in the colormap are filled with the foreground color.) You may allocate a complete colormap using the wkColorMap resource; there are also support functions for allocating and freeing individual colors.

All Workstation class objects share the ability to update and clear the Workstation drawing area. The NhlUpdateWorkstation and NhlClearWorkstation functions perform different tasks depending on the class of Workstation object for which they are invoked. For the NcgmWorkstation, the clear and update functions write special CGM commands into the CGM file that end the current frame and start a new one. For the XWorkstation, the update function causes all pending draw commands to be drawn, and the clear function clears the entire window. There is also a convenience function, NhlFrame, that calls both the update and clear functions. This function operates much like the frame call in the low level NCAR graphics libraries.

Support functions

The Workstation object defines the following support functions:

NhlUpdateWorkstation: The NhlUpdateWorkstation function updates the drawing area of an instance of a Workstation object.
NhlClearWorkstation: The NhlClearWorkstation function clears the drawing area of an instance of a Workstation object.
NhlFrame: The NhlFrame function first updates and then clears the drawing area of an instance of a Workstation object.
NhlNewColor: The NhlNewColor function adds a color specified as an RGB triple to the colormap of a Workstation instance and returns its HLU color index.
NhlSetColor: The NhlSetColor function sets the RGB color values for a specified HLU color index.
NhlFreeColor: The NhlFreeColor function removes a color, specified by its HLU index, from the Workstation color map.
NhlIsAllocatedColor: The boolean function NhlIsAllocatedColor returns True if a color has been assigned to a particular HLU color index, and False otherwise.
NhlIsWorkstation: This function just determines if a given object id identifies a Workstation class object.