Understanding resources

An object can be made to produce many different results. Just as a typical NCAR Graphics library subroutine can be manipulated through setting different arguments in the subroutine call or by parameters via a parameter-setting call, an object can be manipulated by entering different values for its resources. In fact, HLU object resources and LLU parameters are analogous. A typical resource in a View subclass might change a color, the width of a line, or the font of a label.

Three ways to set resources shows where resources can be set. They can be set in the HLU program in two ways. They can also be set in a third way, by using a resource file.

Applying resources to objects

Resource files are ascii files containing lines of data in which values are assigned to object resources. For example, the ng4ex example ti03c.c has an associated resource file ti03.res. The contents of ti03.res are a series of lines of the form: 


   ti03.ti03Work.Titles.tiMainString         : Title Resource Setting
This line sets the value of the resource tiMainString to "Title Resource Setting". Note that quotes are not needed when setting a string in a resource file.

When you assign a value to a resource, you have to make sure that you assign the value to the correct instantiation of the object. The generic assignment path for a Title resource is: 


   {App_obj_name}.{Workstation_obj_name}.{Title_obj_name}.{Resource_name}: Resource_value
The App, Workstation, and Title objects are all assigned a name and id number which delineate the particular instance of that class.

For example, our HLU program ti03c would have the following three create calls in a C program: 


   NhlCreate(&appid,"ti03",NhlappClass,NhlDEFAULT_APP,rlist);
   NhlCreate(&wid,"ti03Work",NhlxWorkstationClass,NhlDEFAULT_APP,rlist);
   NhlCreate(&pid,"Titles", NhltitleClass,wid,rlist);
Argument 1 in these calls returns an object id number. Argument 2 defines an object name. The object names are used in resource linking. For more details, see NhlCreate function overview.

Call 1 sets the App object name for this instance to "ti03".
Call 2 sets the XWorkstation object name for this instance to "ti03Work".
Call 3 sets the Title object name for this instance to "Titles".

In this example, the resource file name will be the App object name with ".res" appended: ti03.res. The X Window where the title object will be displayed is named ti03Work. This particular title object is named Titles. Thus, the resource assignment linkage 


   {App_obj_name}.{Workstation_obj_name}.{Title_obj_name}.{Resource_name}: Resource_value
becomes: 


   ti03.ti03Work.Titles.tiMainString
By adding a colon and the resource value after the resource name we get: 


   ti03.ti03Work.Titles.tiMainString   :   Title Resource Setting

Wild cards

Wild-card (*) designators are allowed for any of the objects. The interpretation is that the designated resource value will apply to all instances of a wild-carded object. Thus, the linkage might be *tiMainString, *Titles.tiMainString, *ti03Work.Titles.tiMainString, or ti03Work*tiMainString.

Instantiations of multiple objects

Consider the following examples of a main title resource: 


   *xwork.Title1.tiMainString          : Ozone Depletion
   *pswork.Title2.tiMainString         : Satellite Tracking
   *ncgmwork.Title1.tiMainString       : Ozone Depletion
In this case, there are three instances of Workstation objects and two instances of the Title object, Title1, and Title2. Title1 gets a main title string of "Ozone Depletion". Title 2 gets a main title of "Satellite Tracking". Title1 gets output to an X Workstation and an NCAR CGM file. Title2 goes to a PostScript file.

In these examples, the App object name has been replaced by a wild-card asterisk. Thus, the resource values we are assigning will be applied to all applications that might be created.

The wild-card replacement capabilities for applying resource values to objects can be very powerful. It is important to realize that the most specific definition of a resource will be used. This makes it possible to wild-card all instances of a particular type of object, but still directly specify one of them.

Assigning values to resources

Syntax for scalar resources

Scalar resources can be of the form integer, real, or string. To set any scalar resource, the value is simply placed after the colon in an assignment line of a resource file. For example, 


   ti02.ti02Work.Titles.tiMainFont             : times-roman
sets a string resource, tiMainFont, to a Times-Roman filled font for the main title of a Title object. A complete listing of all fonts available to the HLUs appears in the NCAR Graphics fonts table.

The line 


   ti02.ti02Work.Titles.tiMainFontHeightF      : .025
sets a scalar real resource, tiMainFontHeightF, to .025. This sets the height of the characters of the main title to .025 NDCs. Since a maximum viewport in NDC space is 1. by 1. this implies a title which is 1/40th of a maximum screen size.

The line 


   ti01.ti01Work.Titles.tiMainFontColor        : 1
sets the integer resource tiMainFontColor to 1. This selects the RGB color index 1 from the color table currently in place. If not set by the user, the HLU default color table will be used.

Syntax for array resources

Array resources can also be set in a resource file. The array of values begins with a left paren and a slash. The values are delimited by commas, and the array ends with a slash and right paren.

For example, consider the following resources from XyPlot example xy04:

Integer resource arrays

The line 

   xy04.xy04Work.xyPlot.xyData.xyLineColors:       (/50,75,100,40/)
shows the assignment of four integer values to an array resource xyLineColors. In this example, an XY plot with four curves is being created. The lines of the four curves are being assigned different color indices from the HLU color table. Unless the user creates and inputs a colormap, the HLU default color table is used.

Note that the above resource assignment path includes an additional object in the pathname. xyLineColors is a resource of an CoordArrays data object created in the HLU program. In C, the call would be: 


   NhlCreate(&dataid,"xyData",NhlcoordArraysClass,NhlDEFAULT_APP,rlist);
   NhlCreate(&dataid,"xyData",NhlcoordArraysClass,NhlDEFAULT_APP,rlist);
In Fortran, the call would be: 


   call NhlFCreate(dataid,'xyData',NhlFCoordArraysClass,0,rlist,ierr)
In this case, the object path is application.workstation.view.data. The Class hierarchy diagrams module shows the hierarchical paths for HLU objects. If a resource can be applied to all instances of parent objects, you can use the path assignment shorthand of *resource_name : resource_value. If you want to assign different resource values to different instances of objects, then you must determine the correct hierarchical path as we showed above when we assigned different main titles for two title objects and three workstation objects in the Instantiations of multiple objects section.

Real resource arrays

The line 

   xy04.xy04Work.xyPlot.xyData.xyLineThicknesses:  (/1.0,2.0,3.0,4.0/)
shows a similar real array assignment of four values. In this case, the four curves are getting line widths of 1. to 4. units. The default width of a line is 1. The curve with a width of 4. will be four times as thick as the curve with a width of 1.

String resource arrays

The lines 

   xy04.xy04Work.xyPlot.xyData.xyExplicitLabels:  (/Curve A,Curve B,Curve C/)
and 


   xy04.xy04Work.xyPlot.xyData.xyExplicitLabels:   (/1,2,3/)
show a string assignment of three values. In the first case, the curves are labeled Curve A, Curve B, and Curve C. In the second case, they are simply labeled 1, 2, and 3.

Resource line continuation

Arrays can span multiple lines in a resource file. Each line before the last one ends with a backslash to escape the carriage return. The end of the array is indicated by the /). There can be any number of blanks at the beginning or end of a line.

The line 


   xy04.xy04Work.xyPlot.xyData.xyLineThicknesses:  (/1.0,\
                                                     2.0,\
                                                     3.0,\
                                                     4.0/)
would also be a legal entry for the xyLineThicknesses array.

Note: In a continuation line, the carriage return must immediately follow the backslash delimiter.

Syntax for assigning a two-dimensional array resource

Suppose we want to use a color table other than the HLU default. We can do this through the Workstation resource wkColorMap. This is a two-dimensional array. The inner (fast varying) dimension is 3 elements (red, green, and blue.) The outer dimension is the number of elements that will exist in the new color table. 


   tx04.tx04work.wkColorMap:   (/(/ 0.00, 0.00, 0.00 /),\
                                 (/ 0.66, 0.66, 0.66 /),\
                                 (/ 0.40, 0.40, 0.40 /),\
                                 (/ 0.00, 1.00, 1.00 /),\
                                 (/ 0.20, 0.56, 0.80 /),\
                                 (/ 0.00, 0.00, 1.00 /),\
                                 (/ 0.50, 0.00, 1.00 /),\
                                 (/ 1.00, 0.00, 1.00 /),\
                                 (/ 0.14, 0.56, 0.14 /),\
                                 (/ 0.00, 1.00, 0.00 /),\
                                 (/ 1.00, 1.00, 0.00 /),\
                                 (/ 0.86, 0.58, 0.44 /),\
                                 (/ 0.65, 0.16, 0.16 /),\
                                 (/ 1.00, 0.50, 0.00 /),\
                                 (/ 1.00, 0.00, 0.00 /)/)
This color table has 15 colors which are: white, light gray, dark gray, cyan, sky blue, blue, blue magenta, magenta, forest green, green, yellow, tan, brown, orange, and red.

Note that the resource assignment path only includes the application (xy04) and the workstation (xy04Work) because this is a Workstation resource.

Ranges of resource values

In many cases, a resource has a limited range of values. For example, the options for tiMainFontQuality are HIGH, MEDIUM, and LOW. There are many fonts available from NCAR Graphics fonts, nine predefined colormaps, sixteen predefined dash patterns, sixteen predefined fill patterns, and seventeen predefined markers.

To find the choices available for a resource such as tiMainFontQuality, you can navigate through the online documentation as follows:

Composite resources

In our discussions of class hierarchy, we have described a composite class. It has access to the resources of its composite member classes. Class hierarchy diagrams shows that the XyPlot class has composite member classes of PlotManager, Legend, LabelBar, TickMark, and Title. It also has superclasses of DataComm, Transform, View, and Base, from which resources are inherited. Thus, within the resource file of an XyPlot object, we can set the values of resources for any of these classes. Consider these resource value assignments from the ng4ex example file xy06.res: 


   xy06.xy06Work.xyPlot.vpXF:                     0.15
   xy06.xy06Work.xyPlot.vpYF:                     0.9
   xy06.xy06Work.xyPlot.vpWidthF:                 0.8
   xy06.xy06Work.xyPlot.vpHeightF:                0.8
   xy06.xy06Work.xyPlot.tiMainString:             Example xy06
   xy06.xy06Work.xyPlot.tiXAxisString:            X
   xy06.xy06Work.xyPlot.tiYAxisString:            Y
   xy06.xy06Work.xyPlot.xyDataDep.xyDashPattern:  0
   xy06.xy06Work.xyPlot.tmXBMinorOn:              False
   xy06.xy06Work.xyPlot.tmYLMinorOn:              False
   xy06.xy06Work.xyPlot.tmXTMinorOn:              False
   xy06.xy06Work.xyPlot.tmYRMinorOn:              False
   xy06.xy06Work.xyPlot.tmXBMode:                 EXPLICIT
   xy06.xy06Work.xyPlot.tmYLMode:                 EXPLICIT

See also:

User Guide Control Panel

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

$Revision: 1.25 $ $Date: 1998/07/31 00:55:30 $