Symbol Object Class

Overview

The Symbol object class allows the application to define and draw custom symbols. The Symbol object class defines a simple ASCII language that can be used to describe a user symbol. Once defined, Symbol objects can be resized, moved, selected, output to hardcopy like any other objects based on the Graphic class.

The size of a symbol can be specified in pixels (for a fixed size symbol) using resources XmNsymbolWidth and XmNsymbolHeight or in user coordinates using resource XmNsymbolScale. When a symbol size is specified in user coordinates, its size will change when the coordinate system changes.

The Symbol object defines a text primitive which draws text inside a symbol. This text, which is fully scalable, is drawn using an outline font technology provided with the INT library. When this text primitive is used, the symbol object must access a file containing a description of the outline for the specified font. The font descriptions, must reside in a directory which you can specify as follows:

Set CompBase resource XmNfontPath on the Symbol parent widget.
Set environment variable INT_FONT_PATH.

If neither of these is defined, the current directory will be searched. If a valid font description is not found, a stroke font will be used.

Symbol Editor

A symbol editor is built in the symbol object class. This editor allows the end-user to create or modify a symbol object interactively. This editor, like other object editors, can be invoked by double clicking on a symbol object. The editor can also be invoked from an application using function XintEditObjectManageResourceDialog.

Inherited Behavior and Resources

The Symbol object class inherits behavior and resources from the Xt Object and Graphic classes.

The class pointer is xintSymbolObjectClass.
The class name is XintSymbol.
The header file is included as <Xint/Symbol.h>.

The following resources are defined by the Symbol object class:
Name	Type	Default	Access
XmNlabelGravity	int	EastGravity	CSG
XmNlabelSpacing	int	10	CSG
XmNsymbolData	XintSymbolData *	NULL	CSG
XmNsymbolHeight	int	21	CSG
XmNsymbolWidth	int	21	CSG
XmNsymbolLocation	XintSymbolLocation *	NULL	CSG
XmNsymbolScale	XintSymbolScale *	NULL	CSG

XmNlabelGravity

Specifies where to draw an optional label string, defined using the Graphic resource XmNname. The label will appear at the specified location if Graphic resource XmNdisplayName is set to True. You can specify one of the following constants:

Resource Value Description
NorthGravity Label is drawn above the symbol.
EastGravity (default) Label is drawn to the right of the symbol.
SouthGravity Label is drawn below the symbol.
WestGravity Label is drawn to the left of the symbol.

Resource Value	Description
NorthGravity	Label is drawn above the symbol.
EastGravity (default)	Label is drawn to the right of the symbol.
SouthGravity	Label is drawn below the symbol.
WestGravity	Label is drawn to the left of the symbol.

XmNlabelSpacing

Specifies the space in pixels between the symbol and the label. See resource XmNlabelGravity for information on how to display a symbol label.

XmNsymbolData

Specifies a pointer to an opaque structure of type XintSymbolData that contains a parsed description of a symbol. See function XintSymbolCreate to create a parsed symbol.

XmNsymbolHeight, XmNsymbolWidth

Specifies the height and width of the symbol in pixels. If you want to specify the size of the symbol in user coordinates, use resource XmNsymbolScale instead.

XmNsymbolLocation

Specifies the position of the center of the symbol in user coordinates. This resource is specified using a pointer to a structure of type XintSymbolLocation which takes the following form:

   typedef struct {
                   float x;
                   float y;
   } XintSymbolLocation;

XmNsymbolScale

Specifies the size of the symbol in user coordinates. This resource is specified using a pointer to a structure of type XintSymbolScale which takes the following form:

   typedef struct {
                   float width;
                   float height;
   } XintSymbolScale;

To specify a symbol with a fixed size in pixels, set resource XmNsymbolScale to NULL and specify the symbol size using resources XmNsymbolWidth and XmNsymbolHeight instead.

Symbol Keywords

The following table lists the keywords available for describing a symbol:

Keyword Arguments Description
BoundingBox minx miny maxx maxy Specifies the bounding box, which defines the coordinate system used to specify the symbol. The origin is located at the upper left corner.
LineColor color_name Specifies the current color used to draw lines.
FillColor color_name Specifies the current fill color.
LineThickness line_thickness Specifies the current line width in pixels.
LineStyle line_style Specifies the current line style. Possible choices are line_on_off_dash, line_double_dash and line_solid.
Line x1 y1 x2 y2 To draw a line from coordinate (x1, y1) to (x2, y2). Coordinates are specified within the coordinate system defined by BoudingBox.
Polyline x1 y1 x2 y2...xn yn To draw a polyline through the specified points.
Polygon x1 y1 x2 y2...xn yn To draw a filled polygon through the specified points.
Rectangle x y width height To draw a rectangle.
FillRectangle x y width height To draw a filled rectangle.
Arc x y width height angle1 angle2 To draw an arc inside a box, starting at angle1 with extension angle2. Angles are expressed in degrees.
FillArc x y width height angle1 angle2 To draw a filled arc inside a box, starting at angle1 with extension angle2. Angles are expressed in degrees.
Font family weight slant To select a font to be used by the Text command.Argument family can be set to helvetica, times, courier, symbol or new-century, weight can be set to medium or bold, and slant can be set to regular or italic.
Text x y width height string To draw a string in the specified bounding box. If argument width is set to 0, the text width is calculated automatically based on the height specification. If argument height is set to 0, the text height is calculated automatically based on the width specification.

Keyword	Arguments	Description
BoundingBox	minx miny maxx maxy	Specifies the bounding box, which defines the coordinate system used to specify the symbol. The origin is located at the upper left corner.
LineColor	color_name	Specifies the current color used to draw lines.
FillColor	color_name	Specifies the current fill color.
LineThickness	line_thickness	Specifies the current line width in pixels.
LineStyle	line_style	Specifies the current line style. Possible choices are line_on_off_dash, line_double_dash and line_solid.
Line	x1 y1 x2 y2	To draw a line from coordinate (x1, y1) to (x2, y2). Coordinates are specified within the coordinate system defined by BoudingBox.
Polyline	x1 y1 x2 y2...xn yn	To draw a polyline through the specified points.
Polygon	x1 y1 x2 y2...xn yn	To draw a filled polygon through the specified points.
Rectangle	x y width height	To draw a rectangle.
FillRectangle	x y width height	To draw a filled rectangle.
Arc	x y width height angle1 angle2	To draw an arc inside a box, starting at angle1 with extension angle2. Angles are expressed in degrees.
FillArc	x y width height angle1 angle2	To draw a filled arc inside a box, starting at angle1 with extension angle2. Angles are expressed in degrees.
Font	family weight slant	To select a font to be used by the Text command.Argument family can be set to helvetica, times, courier, symbol or new-century, weight can be set to medium or bold, and slant can be set to regular or italic.
Text	x y width height string	To draw a string in the specified bounding box. If argument width is set to 0, the text width is calculated automatically based on the height specification. If argument height is set to 0, the text height is calculated automatically based on the width specification.

Symbol Description Syntax

If specified, keyword BoundingBox must be placed first (default is-100 -100 100 100). Other keywords can be specified in any order, each starting on a new line.

The following is an example of a symbol description:

   BoundingBox -100 -100 100 100
   LineColor blue
   FillColor red
   LineThickness 5
   Line -28.4116 20.4211 -40.0447 -13.2632
   Polyline -19.9105 -13.6842 -9.17226 21.6842 2.01342 -14.9474 
            13.6465 21.2 632
   Polyline 21.2528 19.5789 42.7293 19.1579 39.5973 19.5789
   Line 32.4385 19.5789 22.5951 -16.2105
   Polyline -16.7785 85.2632 -81.6555 16.2105 -81.6555 -9.89474 
            -12.7517 -69.6842 12.7517 -69.6842 76.7338 -16.2105 
            76.7338 15.3684 18.5682 84.8421 1.56599 85.2632
   Polyline 11.8568 73.8947 62.8635 13.6842 62.8635 -11.1579 
            10.0671 -56.2105 12.7517 -69.6842 75. 3915 -17.0526 
            75.8389 14.9474 18.1208 84.8421 12.7517 84.4211 
            12.7517 74.3158

Symbol Callbacks

The Symbol object class does not define any new callbacks. However, the callback structure returned with callback XmNverifyCallback (see class Graphic) is redefined. The following ordered table lists the members of the callback structure XintSymbol VerifyCallbackStruct:

Data Type Member Description
int reason Indicates why the call back was invoked.
XEvent * event Points to the XEvent that triggered the callback.
Boolean doit Set to False to cancel the operation.
XintSymbolLocation * location Pointer to the new location proposed for the Symbol object.
int symbol_width Proposed width for the symbol in pixels.
int symbol_height Proposed height for the symbol in pixels.

Data Type	Member	Description
int	reason	Indicates why the call back was invoked.
XEvent *	event	Points to the XEvent that triggered the callback.
Boolean	doit	Set to False to cancel the operation.
XintSymbolLocation *	location	Pointer to the new location proposed for the Symbol object.
int	symbol_width	Proposed width for the symbol in pixels.
int	symbol_height	Proposed height for the symbol in pixels.

Symbol Functions

The Symbol object class defines the following functions for creating a Symbol object, and creating and freeing parsed symbol data structures:

Function Name Description
XintCreateSymbol Creates a Symbol object.
XintSymbolCreate Creates a parsed symbol from a description string.
XintSymbolFree Free a parsed symbol data structure.

Function Name	Description
XintCreateSymbol	Creates a Symbol object.
XintSymbolCreate	Creates a parsed symbol from a description string.
XintSymbolFree	Free a parsed symbol data structure.

XintCreateSymbol

This function creates a symbol object.

     Object XintCreateSymbol (...)

Widget parent Parent of new Symbol object.
char * name Name of new Symbol object.
ArgList arglist List of resource/value items.
Cardinal argcount Number of items in arglist.

XintSymbolCreate

This function converts a string containing a symbol description into a parsed symbol data structure that can be passed to resource XmNsymbolData. A symbol data structure can be shared between several Symbol objects.

     XintSymbolData *XintSymbolCreate (char *symbol_string)

where symbol_string is a string containing a description of the symbol to parse. Structure XintSymbolData is an opaque structure that is not documented.

XintSymbolFree

This function frees a parsed symbol data structure. You can free a parsed symbol descriptor immediately after its creation or after a set values operation since it is no longer needed (the Symbol object makes a copy).

     void XintSymbolFree(XintSymbolData *parsed_symbol)

where parsed_symbol is a pointer to the parsed symbol data structure to free.

Macros

Macro XintIsSymbol returns True if the specified object is a Symbol object.

     Boolean XintIsSymbol (Object object)

Widget	parent	Parent of new Symbol object.
char *	name	Name of new Symbol object.
ArgList	arglist	List of resource/value items.
Cardinal	argcount	Number of items in arglist.