.ds f. examples.sec
.NH 1 "EXAMPLE XVROUTINES"
.XS
\s12\*(SN  EXAMPLE XVROUTINES\s0
.XE
.sp 2
.PP
This section provides example xvroutines for you to look at when you are
writing an Khoros xvroutine;  the first uses the \fIxvgraphics\fP library
to draw lines, while the second uses the \fIxvdisplay\fP library to display
an image.  The entire programs are not listed here;  only the "library" files
and the "run_exampleX.c" files that provide the functionality.  
If you would like to look at the programs
in their entirety, with their PS files, code generated by \fBghostwriter\fP,
and code generated by \fBconductor\fP, they are located in 
\f(CW$KHOROS_CONTRIB/src/xvroutines/example1\fP and 
\f(CW$KHOROS_CONTRIB/src/xvroutines/example2\fP.   Their *.form files are
located in \f(CW$KHOROS_CONTRIB/repos/xvroutines\fP, and their man1 pages
can be found in \f(CW$KHOROS_CONTRIB/man/man1\fP.
.PP
.bp
.sp 2
.NH 2 "EXAMPLE 1"
.XS
      \*(SN  EXAMPLE 1
.XE
.sp
.DS L
.ps 9
.vs 11
\f(CW
/*
 *----------------------------------------------------------------------
 *
 * Copyright 1991, University of New Mexico.  All rights reserved.
 * Permission to copy and modify this software and its documen-
 * tation only for internal use in your organization is hereby
 * granted, provided that this notice is retained thereon and
 * on all copies.  UNM makes no representations as to the sui-
 * tability and operability of this software for any purpose.
 * It is provided "as is" without express or implied warranty.
 * 
 * UNM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FIT-
 * NESS.  IN NO EVENT SHALL UNM BE LIABLE FOR ANY SPECIAL,
 * INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY OTHER DAMAGES WHAT-
 * SOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
 * IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
 * ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PER-
 * FORMANCE OF THIS SOFTWARE.
 * 
 * No other rights, including, for example, the right to redis-
 * tribute this software and its documentation or the right to
 * prepare derivative works, are granted unless specifically
 * provided in a separate license agreement.
 *---------------------------------------------------------------------
 */

#include "unmcopyright.h"        /* Copyright 1991 by UNM */

/*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>  <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
 >>>>
 >>>>         File Name: lexample1.c
 >>>>
 >>>>      Program Name: example1
 >>>>
 >>>> Date Last Updated: Wed Apr 24 09:33:22 1991 
 >>>>
 >>>>          Routines: lexample1 - the library call for example1
 >>>>
 >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<*/


#include "xvinclude.h"


/* -library_includes */
#include "example1.h"

/* -library_includes_end */


/****************************************************************
*
* Routine Name: lexample1 - library call for example1
*
* Purpose:  runs the example1 program
*
* Input: argc, argv - command line arguments
*	 program - program name, example1
* Output: none
* Written By:  Danielle Argiro
*
****************************************************************/


/* -library_def */
run_example1(argc, argv, program)
int     argc;
char    *argv[];
char    *program;
/* -library_def_end */

/* -library_code */
{
        xvf_form  *form;
        example1 example1_info;
        char *form_filestring;
        char *form_pathname;
        Window workspace_window;
        Coord wc_min, wc_max;
        Widget workspace;
        Arg args[MaxArgs];
        int i;
        unsigned long bg;

        static char *colornames[]=
        {
          "White",        "MediumSpringGreen",  "Yellow",    "Cyan",
          "MediumOrchid", "Magenta",            "Orange",    "Wheat",
          "LimeGreen",    "Turquoise",          "Pink",      "LightGrey",
          "PeachPuff",    "Lavender",           "MintCream", "SlateBlue",
          "Aquamarine",   "SeaGreen",           "YellowGreen", "RosyBrown",
        };
        

        id = 1;

        /*
         * initialize the display & the forms - 
         * NOTE: assuming a global 'Display *display'
         */
        display = xvf_initialize(ac, av, program);
        if (display == NULL)
        {
             fprintf(stderr, "Could not open connection to server");
             exit(0);
        }

        /*
         * Substitute below the correct filename and directory path
         * of the User Interface Description file to be used
         */
        form_filestring = xvf_strcpy("example1.form");
        form_pathname   = xvf_strcpy("$KHOROS_CONTRIB/repos/xvroutines");
        form_filestring = vfullpath(form_filestring, form_pathname, NULL);

        /*
         * Create the forms 
         */
        if (!(form = xvf_create_form(form_filestring, av, ac, SIMPLE, NULL,
                                     -1, -1)))
           exit(0);

        /*
         * Initialize the auto-generated information structure
         */
        _xvf_init_example1(form,  &example1_info);

        /*
         *  initialize workspace - want black background 
         */
        workspace = example1_info.sub->one->workspace;
        XtAddEventHandler(workspace, ExposureMask, False,
                          refresh_workspace, NULL);
        workspace_window = XtWindow(workspace);

        bg = BlackPixel(display, DefaultScreen(display));
        i = 0;
        XtSetArg(args[i], XtNbackground, bg);                     i++;
        XtSetValues(workspace, args, i);


        /*
         *  initialize graphics library 
         */
        X3D_init_graphics(id, X2D);
        X3D_set_X11(id, display, workspace_window, workspace);
        X2D_set_window(id, 0, 0, 511, 139);
        X2D_set_viewport(id, 0.05, 0.95, 0.05, 0.95);
        wc_min.x = 0;
        wc_min.y = 0;
        wc_max.x = 511;
        wc_max.y = 139;
        X2D_set_wc_min_max(id, wc_min, wc_max);
        
        /*
         *  initially allocate colors & initialize other globals 
         */
        X3D_allocate_named_colors(display, colornames, Colors, COLORNUM,
                                  false, X3D_WHITE);
        colornum = 0;
        linecount = 1;

        /*
         * Map the forms
         */
        xvf_change_active(form, true);

        do
        {
             /*
              * run the forms
              */
             form = xvf_run_form();
             if (form == NULL) break;

             /*
              * get information from the master
              */
             _xvf_get_example1(form, &example1_info);

             /*
              * action came from the 'sub' subform
              */
             if (example1_info.sub_selected)
             {
                  run_sub(form, example1_info.sub);
             }


        xvf_clear_selections(form->db, form->line_num);
        } while (!example1_info.sub->one->quit);    /* end user interface loop */
   return(TRUE);
}


/********************************************************
*
*  Routine Name:  refresh_workspace
*
*       Purpose:  event handler to update workspace on exposure
*
*         Input:  widget - the widget that the event handler was
*                          installed on (workspace)
*                 event  - event that initiated the event handler (Exposure)
*                 clientData - 
*                          used to pass a data structure if needed; we don't 
*                          need one here.  if we had, we would have passed its 
*                          pointer to XtAddEventHandler as the last argument, 
*                          instead of NULL.
*
*        Output:  refreshes colored lines on the workspace
*
*     Called By:  X Toolkit on Exposure Events
*
*    Written By:  Danielle Argiro 
*
********************************************************/

void refresh_workspace(widget, event, clientData)
Widget widget;
XEvent *event;
caddr_t clientData;
{
        Coord coord1, coord2;
        int i;
        int colorindex;

        /* the first line was this */
        coord1.x = 5;
        coord1.y = 5;
        coord2.x = 5;
        coord2.y = 135;

        colorindex = 0;

        /* the next lines were these */
        for(i = 0; i < linecount; i++)
        {
           X2D_draw_line(id, coord1, coord2, &Colors[colorindex]);
           colorindex++; if (colorindex > COLORNUM) colorindex = 0;
           coord1.x+=5;
           coord2.x+=5;
        }
        XFlush(display);
}


/* -library_code_end */
.bp

/*
 *---------------------------------------------------------------------
 *            Copyright 1990 University of New Mexico
 * 
 * Permission to copy and modify this software and its documen- 
 * tation only for internal use in your organization is hereby 
 * granted, provided that this notice is retained thereon and 
 * on all copies.  UNM makes no representations as too the sui- 
 * tability and operability of this software for any purpose. 
 * It is provided 'as is' without express or implied warranty. 
 *  
 * UNM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 
 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FIT- 
 * NESS.  IN NO EVENT SHALL UNM BE LIABLE FOR ANY SPECIAL, 
 * INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY OTHER DAMAGES WHAT- 
 * SOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER 
 * IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS 
 * ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PER- 
 * FORMANCE OF THIS SOFTWARE. 
 *  
 * No other rights, including for example, the right to redis- 
 * tribute this software and its documentation or the right to 
 * prepare derivative works, are granted unless specifically 
 * provided in a separate license agreement. 
 * 
 *---------------------------------------------------------------------
 */
#include "unmcopyright.h"
#include "example1.h"



/********************************************************
*
*  Routine Name:  run_sub
*
*       Purpose:  drives the subform 'sub'
*
*         Input:  form - pointer to the form tree 
*		  sub_info  - information structure for subform 'sub'
*        Output:  action of the application program
*
*     Called By:  run_example1()
*
*   Automatically Generated By:  conductor -i example1.pane -l 1 -b
*
********************************************************/


run_sub(form, sub_info)

xvf_form *form;
example1_sub *sub_info;
{

	/*
	 * action came from the 'one' pane
	 */
	if (sub_info->one_selected)
	    run_one(form, sub_info->one);


}   /* end run_sub */





/********************************************************
*
*  Routine Name:  run_one
*
*       Purpose:  drives the pane 'one'
*
*         Input:  form - pointer to the form tree 
*		  one_info  - information structure for pane 'one'
*        Output:  action of the application program
*
*     Called By:  run_sub()
*
*   Automatically Generated By:  conductor -i example1.pane -l 1 -b
*
********************************************************/

static int coordx1 = 5, coordx2 = 5;
static int coordy1 = 5, coordy2 = 135;

run_one(form, one_info)

xvf_form *form;
sub_one *one_info;
{
	Coord coord1, coord2;

	/*
	 * user clicked on pane action button 'add'
	 */
	if (one_info->add)
	{
                colornum++;
                if (colornum == COLORNUM)
                    colornum = 0;

                coordx1 += 5;
                coordx2 += 5;
                coord1.x = coordx1;
                coord1.y = coordy1;
                coord2.x = coordx2;
                coord2.y = coordy2;
                X2D_draw_line (1, coord1, coord2, &Colors[colornum]);
		linecount++;
	}
}
\fP
.DE
.ps 11
.vs 13
.bp
.sp 3
.NH 2 "EXAMPLE2"
.XS
      \*(SN  EXAMPLE2
.XE
.bp
.sp 2
.DS L
.ps 9
.vs 11
\f(CW
/*
 *----------------------------------------------------------------------
 *
 * Copyright 1991, University of New Mexico.  All rights reserved.
 * Permission to copy and modify this software and its documen-
 * tation only for internal use in your organization is hereby
 * granted, provided that this notice is retained thereon and
 * on all copies.  UNM makes no representations as to the sui-
 * tability and operability of this software for any purpose.
 * It is provided "as is" without express or implied warranty.
 * 
 * UNM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FIT-
 * NESS.  IN NO EVENT SHALL UNM BE LIABLE FOR ANY SPECIAL,
 * INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY OTHER DAMAGES WHAT-
 * SOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
 * IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
 * ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PER-
 * FORMANCE OF THIS SOFTWARE.
 * 
 * No other rights, including, for example, the right to redis-
 * tribute this software and its documentation or the right to
 * prepare derivative works, are granted unless specifically
 * provided in a separate license agreement.
 *---------------------------------------------------------------------
 */

#include "unmcopyright.h"        /* Copyright 1991 by UNM */

/*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>  <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
 >>>>
 >>>>         File Name: lexample2.c
 >>>>
 >>>>      Program Name: example2
 >>>>
 >>>> Date Last Updated: Wed Apr 24 09:50:42 1991 
 >>>>
 >>>>          Routines: lexample2 - the library call for example2
 >>>>
 >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<*/


#include "xvinclude.h"


/* -library_includes */
#include "example2.h"
/* -library_includes_end */


/****************************************************************
*
* Routine Name: lexample2 - library call for example2
*
* Purpose: runs the example2 program
*
* Input: argc, argv - command line arguments
*        program - program name, example1
* Output: none
*
* Written By: Danielle Argiro
****************************************************************/


/* -library_def */
run_example2(argc, argv, program)
int     argc;
char    *argv[];
char    *program;
/* -library_def_end */

/* -library_code */
{
        xvf_form  *form;
        master example2_info;
        char *form_filestring;
        char *form_pathname;

        Widget canvas;          /* simple widget created with -w */
        Widget viewport;        /* viewport backplane with scroll bar */
        int    i, wksp_width, wksp_height, vp_width, vp_height;
        Arg    arg[MaxArgs];
        struct xvimage   *image;

        /*
         * initialize the display & the forms - 
         * NOTE: assuming a global 'Display *display'
         */
        display = xvf_initialize(ac, av, program);
        if (display == NULL)
        {
             fprintf(stderr, "Could not open connection to server");
             exit(0);
        }

        /*
         * Substitute below the correct filename and directory path
         * of the User Interface Description file to be used
         */
        form_filestring = xvf_strcpy("example2.form");
        form_pathname   = xvf_strcpy("$KHOROS_CONTRIB/repos/xvroutines");
        form_filestring = vfullpath(form_filestring, form_pathname, NULL);

        /*
         * Create the forms 
         */
        if (!(form = xvf_create_form(form_filestring, av, ac, SIMPLE, NULL,
                                     -1, -1)))
           exit(0);

        /*
         * Initialize the auto-generated information structure
         */
        _xvf_init_master(form,  &example2_info);

        /*
         *  the Simple Widget created with [-w] will be the parent of 
         *  the widgets that we will be creating
         */
         canvas = example2_info.sub->pane->canvas;

        /*
         * want to display an image
         */
         xvd_initialize(display);
         
         if (example2->i != NULL) 
            image = readimage(example2->i);
         else
            image = NULL;
         xvdisplay = xvd_init_image(display, image, NULL, NULL, NULL,
                                    False, False, False, NULL);
         /*
          *  determine width & height of viewport
          */
         if (example2->w_flag)
            vp_width = example2->w; 
         else if (image != NULL)
            vp_width    = (int) image->row_size/2;
         else vp_width = 255;

         if (example2->h_flag)
            vp_height = example2->h; 
         else if (image != NULL)
            vp_height   = (int) image->col_size/2;
         else vp_height = 255;

         if (image == NULL)
         {
            wksp_width  = 512;
            wksp_height = 512;
         }
         else 
         {
            wksp_width  = image->row_size;
            wksp_height = image->col_size;
         }

        /*
         * create the viewport widget which will provide backplane 
         * with scroll bar - we'll give it a Form Widget as a child
         */

         i = 0;
         XtSetArg(arg[i], XtNallowVert, True);                          i++;
         XtSetArg(arg[i], XtNallowHoriz, True);                         i++;
         XtSetArg(arg[i], XtNwidth,   vp_width);                        i++;
         XtSetArg(arg[i], XtNheight,  vp_height);                       i++;
         XtSetArg(arg[i], XtNforceBars, True);                          i++;
         viewport = XtCreateManagedWidget("viewport",viewportWidgetClass,
                                          canvas,arg,i);

        /*
         * create the Simple Widget on which actual display will take place -
         * it is a child of the Viewport widget
         */
         i = 0;
         XtSetArg(arg[i],XtNborderWidth,0);           i++;
         XtSetArg(arg[i],XtNdefaultDistance,0);       i++;
         XtSetArg(arg[i],XtNwidth,   wksp_width);     i++;
         XtSetArg(arg[i],XtNheight,  wksp_height);    i++;
         workspace = XtCreateManagedWidget("workspace",formWidgetClass,
                                           viewport,arg,i);

         xvd_create_raster(display, workspace, xvdisplay, False);


        /*
         * Map the forms
         */
        xvf_change_active(form, true);

        do
        {
             /*
              * run the forms
              */
             form = xvf_run_form();
             if (form == NULL) break;

             /*
              * get information from the master
              */
             _xvf_get_master(form, &example2_info);

             /*
              * action came from the 'sub' subform
              */
             if (example2_info.sub_selected)
             {
                  run_sub(form, example2_info.sub);
             }


        xvf_clear_selections(form->db, form->line_num);
        } while (!example2_info.sub->pane->quit);    /* end user interface loop */
        return(TRUE);
}
/* -library_code_end */

.bp

/*
 *---------------------------------------------------------------------
 *            Copyright 1990 University of New Mexico
 * 
 * Permission to copy and modify this software and its documen- 
 * tation only for internal use in your organization is hereby 
 * granted, provided that this notice is retained thereon and 
 * on all copies.  UNM makes no representations as too the sui- 
 * tability and operability of this software for any purpose. 
 * It is provided 'as is' without express or implied warranty. 
 *  
 * UNM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 
 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FIT- 
 * NESS.  IN NO EVENT SHALL UNM BE LIABLE FOR ANY SPECIAL, 
 * INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY OTHER DAMAGES WHAT- 
 * SOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER 
 * IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS 
 * ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PER- 
 * FORMANCE OF THIS SOFTWARE. 
 *  
 * No other rights, including for example, the right to redis- 
 * tribute this software and its documentation or the right to 
 * prepare derivative works, are granted unless specifically 
 * provided in a separate license agreement. 
 * 
 *---------------------------------------------------------------------
 */
#include "unmcopyright.h"
#include "example2.h"

/********************************************************
*
*  Routine Name:  run_sub
*
*       Purpose:  drives the subform 'sub'
*
*         Input:  form - pointer to the form tree 
*		  sub_info  - information structure for subform 'sub'
*        Output:  action of the application program
*
*     Called By:  run_example2()
*
*   Automatically Generated By:  conductor -i example2.pane -l 1 -b
*
********************************************************/


run_sub(form, sub_info)

xvf_form *form;
master_sub *sub_info;
{

	/*
	 * action came from the 'pane' pane
	 */
	if (sub_info->pane_selected)
	    run_pane(form, sub_info->pane);


}   /* end run_sub */





/********************************************************
*
*  Routine Name:  run_pane
*
*       Purpose:  drives the pane 'pane'
*
*         Input:  form - pointer to the form tree 
*		  pane_info  - information structure for pane 'pane'
*        Output:  action of the application program
*
*     Called By:  run_sub()
*
*   Automatically Generated By:  conductor -i example2.pane -l 1 -b
*
********************************************************/


run_pane(form, pane_info)

xvf_form *form;
sub_pane *pane_info;
{

	char *filename;
	struct xvimage *image;
	char temp[MaxLength];

	/* 
	 * make sure they've provided a filename 
         */
	if (pane_info->i == NULL)
        {
             xvf_error_wait("Error! No filename specified.", 
			    "run_pane", NULL);
                 return;
        }
	filename = vfullpath(pane_info->i, NULL, NULL);

	/*
         *  read in the new image
         */
        if (!(image = readimage(filename)))
        {
           /* error in readimage */
	   sprintf(temp, "Unable to read image from file %s.", filename);
           xvf_error_wait(temp, "run_file", NULL);
	   return;
	}
	/*
	 *  update with the new image
	 */
	xvd_update_image(xvdisplay, image);
	xvd_set_colormap(workspace, xvdisplay->colormap, True);
	free(filename);
}
\fP
.DE
.ps 11
.vs 13
.bp
.sp 3
