Object Architecture

Xt Object Class

The INT Graphic objects are based on the Xt Object class. The Object class is the root of the Xt widget class hierarchy, as well as the root of the INT Graphic class hierarchy. It supports creation, deletion and resource handling. However, it does not support geometry, windows or event handling.

Parent Widget

INT Graphic objects must only be created with a parent that is an EditObject widget or a widget whose class is derived from the EditObject class (such as an EditTable widget, for example). The EditObject class defines the actions and callbacks that allow the end-users to interact with the objects, including actions to select, move, reshape, cut and paste, insert objects interactively and add or delete points. The EditObject class also defines a number of public functions to manipulate objects including hardcopy output to PostScript and optionally CGM, plus ASCII input and output.

Summary of Components

The Graphic object library defines the following object classes:

Graphic. The base class for all graphic objects. It defines the basic resources and methods used by all other INT Graphic objects.
Group.To group primitive objects or other groups into a single group object
Image. To display an image.
Line. To draw a line between two points, with or without arrows at the end.
MultiPoint. Base class for all objects with multiple points such as a polyline.
Oval. To draw oval shaped objects.
Polyline. To draw polyline or polygon objects.
Rectangle. To draw rectangular objects.
Symbol. To draw a user specified symbol.
Text. To draw text.

Coordinate System

By default, all graphic objects use the coordinate system provided by their parent widget. The EditObject class coordinate system ranges between 0.0 and 100.0 in both directions, with the origin at the upper left corner. Some subclasses of EditObject, such as EditTable, redefine the default coordinate system. EditTable, for example, defines a coordinate system that ranges between 0 and ncolumns in the horizontal direction and between 0 and nrows in the vertical direction.

The AxisObject is used by the chart class to define a new coordinate system that matches the user coordinate system inside the plot area.

Class Hierarchy

All graphic objects are based on a class hierarchy, where the subclasses inherit the resources and behavior from their superclass. The following diagram illustrates the class hierarchy for the basic graphic objects defined in the GraphicObject library. See Reference pages for a complete description of the resources and public functions defined by these object classes.

Figure 2: GraphicObject Library Class Hierarchy

The Chart object and all the specialized sub-objects used to build a Chart are also based on a similar hierarchy that is described later in this Chapter.

Object Interface

Objects in the GraphicObject library are declared as data type Object (defined in the Xt Intrinsic.h header file) and can be created in exactly the same manner as Motif widgets. You can use the Xt creation functions:

    Widget XtCreateWidget (String, WidgetClass, ArgList, 
		           Cardinal);
    Widget XtVaCreateWidget (String, WidgetClass,...);

Additionally, a creation convenience function is provided by each object class.

For example, you can create a line object using the Xt creation function as follows:

    Object line_object;
    XintLine line;

    line_object = (Object) XtVaCreateWidget ("line", 
				             (WidgetClass)xintLineObjectClass, 
				              parent,
				              XmNline, &line, 
				              NULL);

or, using the creation function provided by the Line class:

    n = 0;
    XtSetArg (arg[n], XmNline, &line); n++;
    line_object = XintCreateLine (parent, "line", arg, n);

If you use the Xt creation function you must cast the return type to Object and the object class name to WidgetClass for ANSI style compilers.

Note: DO NOT manage objects; this will cause the object record to be corrupted.

Changing object attributes can be accomplished with the Xt functions:

    void XtSetValues (Widget, ArgList, Cardinal);
    void XtVaSetValues (Widget,...);

For example, the following code sample changes the line style of a line object:

    XtVaSetValues ((Widget) line_object, 
	           XmNlineStyle, XintLINE_ON_OFF_DASH, 
	           NULL);

Finally, to destroy an object you can use functions:

    void XtDestroyWidget(Widget);
    void XintEditObjectDestroyObject(Object);

Both functions are equivalent, but the second one is faster.

Pointer Resources

Many resources in the INT library are specified as pointers to data structures, floating point values, or data arrays. Unless specified otherwise, an internal copy of the data is made by the widget or object, so you don't need to keep the memory allocated. For example, the list of points to a polyline object is specified as an array of points using resource XmNpointArray. You can free this array after you have used it to create or modify a polyline object.

Functions XtSetValues and XtVaSetValues, when applied to a pointer resource, return the pointer to the internal widget or object data. You should not modify this data directly. This is a common error that often occurs when trying to modify a resource. The following example, which applies a horizontal translation to a rectangle object, illustrates the problem.

    Object rect_object;
    XintRectangle *rectangle, new_rectangle;
    ...
    XtVaGetValues((Widget) rect_object, XmNrectangle, &rectangle, NULL);

    /* DON'T modify structure rectangle directly; copy data first...*/
    new_rectangle = *rectangle;

    /* apply translation */
    new_rectangle.x1 += tx;
    new_rectangle.x2 += tx;
    XtVaSetValues((Widget) rect_object, 
	           XmNrectangle, &new_rectangle, 
	           NULL);
    ...

Hello World Example

The following example (see file graphic_1.c in directory examples) illustrates how to build a Hello World application using the Text object.

    #include 
    #include 

    main (argc, argv)
    int     argc;
    char    *argv[];
    {
       XtAppContext  app_context;
       Widget        top_level;
       Widget        edit;
       Object        text;
       XintTextLocation text_location;
    
       top_level  = XtAppInitialize(&app_context, "hello_world",
		                    (XrmOptionDescList)NULL, 0, 
                                    &argc, argv,
		                    NULL, NULL, 0);
    
       /* Create an EditObject widget */
       edit = XtVaCreateManagedWidget("edit_object", 
                                      xintEditObjectWidgetClass, top_level,
		                      XmNwidth, 400,
		                      XmNheight, 400,
		                      NULL);
    
       /* Create the Text object */
       text_location.x = 50;
       text_location.y = 50;
       text = (Object) XtVaCreateWidget("Hello World",
		                        (WidgetClass)xintTextObjectClass, 
                                        edit,
		                        XmNtextLocation, &text_location,
		                        XmNtextAnchor, XintCENTER,
		                        XmNtextString, "Hello World",
		                        XmNfontSize, 18,
		                        XmNroundEdge, True,
		                        XmNfillStyle, XintFILL_SOLID,
		                        XmNlineStyle, XintLINE_SOLID,
		                        NULL);
    
       /* Loop */
       XtRealizeWidget(top_level);
       XtAppMainLoop(app_context);
    }

The output from this example is shown below:

Figure 3: Hello World Example