XDL_VIEW - VOLUME 3
===================

Version: 4.0

John W. Campbell, CCLRC Daresbury Laboratory


CONTENTS
--------



CHAPTER 1: THE XDL_VIEW MANAGEMENT ROUTINES

1.1  INTRODUCTION
1.2  Application Callable Management Routines
     1.2.1    Introduction
     1.2.2    XDL_VIEW initialisation - xdl_open_view
     1.2.3    XDL_VIEW event handling - xdl_get_events
     1.2.4    XDL_VIEW event flushing - xdl_flush_events
     1.2.5    Delete an XDL_VIEW view-object - xdl_delete_view_object
     1.2.6    Pointers list index of a Fortran character string - xdlstr
     1.2.7    Get root coordinates - xdl_view_object_rootxy
     1.2.8    Raise a view-object - xdl_view_object_raise
     1.2.9    Lower a view-object - xdl_view_object_lower
1.3  Special Purpose Application Callable Routines
     1.3.1    Introduction
     1.3.2    Event handling with time out- xdl_get_events_timeout
     1.3.3    XDL_VIEW event and standard input handling - xdl_getio_events
     1.3.4    Get string after xdl_getio_events call - xdl_getio_string
     1.3.5    Read a string from the terminal - xdl_tread
     1.3.6    XDL_VIEW timer driven event handling - xdl_timer_events
     1.3.7    XDL_VIEW XSync/XSyschronise calls - xdl_sync
     1.3.8    Delay - xdl_delay
1.4  Creating Windows when Coding View-Objects
     1.4.1    Introduction
     1.4.2    Create a base frame window - xdl_create_base_frame_window
     1.4.3    Create a frame window - xdl_create_frame_window
     1.4.4    Create a paint window - xdl_create_paint_window
1.5  Creating Active Strips when Coding View-Objects
     1.5.1    Introduction
     1.5.2    Create an active strip - xdl_create_active_strip
     1.5.3    Set active strip to 'on' - xdl_active_strip_on
     1.5.4    Set active strip to 'off' - xdl_active_strip_off
1.6  Registering View-Objects and Windows when Coding View-Objects
     1.6.1    Introduction
     1.6.2    Add a new view-object - xdl_new_view_object
     1.6.3    Add a window to the windows list - xdl_add_window
     1.6.4    Add a library window to windows list - xdl_add_libwin
     1.6.5    Add to level window callbacks - xdl_add_top_callbacks
1.7  Getting Items from a View-Objects List when Coding View-Objects
     1.7.1    Introduction
     1.7.2    Get offset in view-objects list from handle - xdl_getiv
     1.7.3    Get global data area from window id - xdl_get_global
     1.7.4    Get view-object handle from window id - xdl_get_vh
1.8  Deleteing a Panel Item when Coding View-Objects
     1.8.1    Introduction
     1.8.2    Delete a panel item - xdl_delete_panel_item
1.9  Handling Selections when Coding View-Objects
     1.9.1    Introduction
     1.9.2    Request selection ownership - xdl_select_owner
     1.9.3    Cancel selection ownership - xdl_select_cancel
     1.9.4    Request a selection - xdl_select_request
     1.9.5    Receive selection data - xdl_select_receive
1.10 Outputting Error Messages when Coding View-Objects
     1.10.1   Introduction
     1.10.2   Output an XDL_VIEW error message - xdl_view_errmsg
     1.10.3   'View-object not found' error message - xdl_view_iv_errmsg
     1.10.4   Error message for wrong type - xdl_view_type_errmsg
1.11 Miscellaneous Routines used when Coding View-Objects
     1.11.1   Introduction
     1.11.2   Get root x, y coordinates - xdl_rootxy
     1.11.3   Copy an output string - xdl_copy_chars
     1.11.4   Test for a blank string - xdl_blank_string
     1.11.5   Chop trailing blanks - xdl_chop_blanks
     1.11.6   Number of digits in an integer - xdl_ndigit
     1.11.7   Convert a string to upper case - xdl_upc
     1.11.8   Convert a string to lower case - xdl_lwc
     1.11.9   Convert a character to upper case - xdl_upcc
     1.11.10  Convert a character to lower case - xdl_lwcc
     1.11.11  Random number, 0-32767 - xdl_rand16
     1.11.12  Get character size - xdl_ch_size
     1.11.13  Set a 64 level gray scale - xdl_set64gray
     1.11.14  Set a 64 level gray + yellow scale - xdl_set64gray_yel
     1.11.15  Set a 64 level colour scale - xdl_set64color
     1.11.16  Get a 64 level gray scale - xdl_get64gray
     1.11.17  Get a 64 level gray + yellow scale - xdl_get64gray_yel
     1.11.18  Get a 64 level colour scale - xdl_get64color
     1.11.19  Delete view-object children - xdl_delete_children
     1.11.20  See if a view-object has children - xdl_any_children

 
CHAPTER 2: APPLICATION CALLABLE VIEW-OBJECT ROUTNES
 

2.1    THE BASE FRAME VIEW-OBJECT ROUTINES
2.1.1  INTRODUCTION
2.1.2  Creating and Handling a Base Frame View-Object
       2.1.2.1  Introduction
       2.1.2.2  Create a base frame view-object - xdl_base_frame


2.2    THE MENU AREA VIEW-OBJECT ROUTINES
2.2.1  INTRODUCTION
2.2.2  Creating and Handling a Menu Area View-Object
       2.2.2.1  Introduction
       2.2.2.2  Create a menu area view-object - xdl_menu_area
       2.2.2.3  Set up a new menu - xdl_menu_area_setmenu
       2.2.2.4  Get the selected item number - xdl_menu_area_getitem
       2.2.2.5  Get position of selected item - xdl_menu_area_getrootxy
       2.2.2.6  Get menu area size requirements - xdl_menu_area_getsize


2.3    THE PARAMETER TABLE VIEW-OBJECT ROUTINES
2.3.1  INTRODUCTION
2.3.2  Creating and Handling a Parameter Table View-Object
       2.3.2.1  Introduction
       2.3.2.2  Create a parameter table view-object - xdl_param_table
       2.3.2.3  Get an input value string - xdl_param_table_getvalue
       2.3.2.4  Parameter table error handling - xdl_param_table_error
       2.3.2.5  Set a parameter table item - xdl_param_table_setitem
       2.3.2.6  Set a parameter value string - xdl_param_table_setvalue
       2.3.2.7  Set a parameter values menu - xdl_param_table_setmenu
       2.3.2.8  Set a parameter values button - xdl_param_table_setbutton
       2.3.2.9  Clear a parameter values menu - xdl_param_table_clrmenu
       2.3.2.10 Set item(s) to 'silent' - xdl_param_table_silent
       2.3.2.11 Set item(s) to 'normal' - xdl_param_table_normal
       2.3.2.12 Set item(s) to 'bold' - xdl_param_table_bold
       2.3.2.13 Reset all items to 'normal' - xdl_param_table_all_normal
       2.3.2.14 Delete a parameter table item - xdl_param_table_delitem
       2.3.2.15 Clear the parameter table - xdl_param_table_clearitems
       2.3.2.16 Output a new title - xdl_param_table_newtitle
       2.3.2.17 Calculate size requirements - xdl_param_table_getsize


2.4    THE I/O WINDOW VIEW-OBJECT ROUTINES
2.4.1  INTRODUCTION
2.4.2  Creating and Handling an I/O Window View-Object
       2.4.2.1  Introduction
       2.4.2.2  Create an I/O window view-object - xdl_io_window
       2.4.2.3  Output a text string - xdl_io_window_print
       2.4.2.4  Get an input text string - xdl_io_window_getstring
       2.4.2.5  Reset active strip message - xdl_io_window_input_message
       2.4.2.6  Set keyboard focus - xdl_io_window_set_focus
       2.4.2.7  Get a root window position - xdl_io_window_rootxy
       2.4.2.8  Calculate size requirements - xdl_io_window_getsize


2.5    THE TEXT TABLE VIEW-OBJECT ROUTINES
2.5.1  INTRODUCTION
2.5.2  Creating and Handling a Text Table View-Object
       2.5.2.1  Introduction
       2.5.2.2  Create a text table view-object - xdl_text_table
       2.5.2.3  Create a text cell view-object - xdl_text_table_cell
       2.5.2.4  Output a text string - xdl_text_table_text
       2.5.2.5  Output a symbol - xdl_text_table_symbol
       2.5.2.6  Clear the text table - xdl_text_table_clear
       2.5.2.7  Clear a section - xdl_text_table_clearsect
       2.5.2.8  Reset active strip message - xdl_text_table_input_message
       2.5.2.9  Define an input cell - xdl_text_table_define_cell
       2.5.2.10 Clear input cell(s) - xdl_text_table_clear_cell
       2.5.2.11 Get selected input cell number - xdl_text_table_getinp
       2.5.2.12 Calculate size requirements - xdl_text_table_getsize
       2.5.2.13 Calculate cell text size  - xdl_text_table_getcsize


2.6    THE GRAPH WINDOW VIEW-OBJECT ROUTINES
2.6.1  INTRODUCTION
2.6.2  Creating and Handling a Graph Window View-Object
       2.6.2.1  Introduction
       2.6.2.2  Create a graphics window view-object - xdl_graph_win
       2.6.2.3  Set mapping option - xdl_graph_win_map
       2.6.2.4  Set style parameters - xdl_graph_win_style
       2.6.2.5  Reset a colour - xdl_graph_win_set_colour
       2.6.2.6  Draw a line - xdl_graph_win_line
       2.6.2.7  Draw a polyline - xdl_graph_win_polyline
       2.6.2.8  Draw a text string - xdl_graph_win_stext
       2.6.2.9  Draw a text string - xdl_graph_win_xtext
       2.6.2.10 Draw a symbol - xdl_graph_win_symbol
       2.6.2.11 Draw polysymbols - xdl_graph_win_polysymbol
       2.6.2.12 Draw a rectangle - xdl_graph_win_rectangle
       2.6.2.13 Draw a polygon - xdl_graph_win_polygon
       2.6.2.14 Draw an arc - xdl_graph_win_arc
       2.6.2.15 Draw a horizontal axis - xdl_graph_win_ax1
       2.6.2.16 Draw a vertical axis - xdl_graph_win_ax2
       2.6.2.17 Get an input cursor position - xdl_graph_win_getcurs
       2.6.2.18 Reset active strip message - xdl_graph_win_input_message
       2.6.2.19 Reset current group id - xdl_graph_win_setid
       2.6.2.20 Delete graphics objects - xdl_graph_win_delete
       2.6.2.21 Calculate size requirements - xdl_graph_win_getsize


2.7    THE POP-UP NOTICE VIEW-OBJECT ROUTINES
2.7.1  INTRODUCTION
2.7.2  Create and Handle a Pop-up Notice View-Object
       2.7.2.1  Introduction
       2.7.2.2  Display a pop-up notice - xdl_popup_notice


2.8    THE POP-UP DIALOGUE BOX ROUTINES
2.8.1  INTRODUCTION
2.8.2  Creating and Handling a Pop-up Dialogue Box View-Object
       2.8.2.1  Introduction
       2.8.2.2  Display a pop-up dialog box - xdl_popup_dialog


2.9    THE POP-UP MENU VIEW-OBJECT ROUTINES
2.9.1  INTRODUCTION
2.9.2  Creating and Handling a Pop-up Menu View-Object
       2.9.2.1  Introduction
       2.9.2.2  Display a pop-up menu - xdl_popup_menu


2.10    THE POP-UP FRAME VIEW-OBJECT ROUTINES
2.10.1  INTRODUCTION
2.10.2  Creating and Handling a Pop-up Frame View-Object
        2.10.2.1 Introduction
        2.10.2.2 Create a popup frame view-object - xdl_popup_frame


2.11    THE PROGRESS BAR VIEW-OBJECT
2.11.1  INTRODUCTION
2.11.2  Create and Handle a Progress Bar View-Object
        2.11.2.1 Introduction
        2.11.2.2 Create a progress bar view-object - xdl_progress_bar
        2.11.2.3 Set the current value - xdl_progress_bar_value


2.12    THE CONTROL PANEL ITEMS VIEW-OBJECT ROUTINES
2.12.1  INTRODUCTION
2.12.2  Panel Choice Item Routines
        2.12.2.1 Introduction
        2.12.2.2 View_object with a Panel Choice Item - xdl_control_choice
        2.12.2.3 Reset selected choice - xdl_control_choice_reset
        2.12.2.4 Get selected item number - xdl_control_choice_getdata
        2.12.2.5 Get required size - xdl_control_choice_getzize
2.12.3  Panel Button Item Routines
        2.12.3.1 Introduction
        2.12.3.2 View_object with a Panel Button Item - xdl_control_button
        2.12.3.3 Set new label string - xdl_control_button_set
        2.12.3.4 Get required size - xdl_control_button_getzize
2.12.4  Panel Label Item Routines
        2.12.4.1 Introduction
        2.12.4.2 View_object with a Panel Label Item - xdl_control_label
        2.12.4.3 Set new label string - xdl_control_label_set
        2.12.4.4 Get required size - xdl_control_label_getzize
2.12.5  Panel Value Item Routines
        2.12.5.1 Introduction
        2.12.5.2 View_object with a Panel Value Item - xdl_control_value
        2.12.5.3 Set new value string - xdl_control_value_set
        2.12.5.4 Get input value string - xdl_control_value_getdata
        2.12.5.5 Get required size - xdl_control_value_getzize
2.12.6  Panel Slider Item Routines
        2.12.6.1 Introduction
        2.12.6.2 View_object with a Panel Slider Item - xdl_control_slider
        2.12.6.3 Set new slider position - xdl_control_slider_reset
        2.12.6.4 Get input slider position - xdl_control_slider_getdata
        2.12.6.5 Get required size - xdl_control_slider_getzize
2.12.7  Panel I/O Item Routines
        2.12.7.1 Introduction
        2.12.7.2 View_object with a Panel I/O Item - xdl_control_io
        2.12.7.3 Set new prompt string - xdl_control_io_prompt
        2.12.7.4 Clear I/O item - xdl_control_io_clear
        2.12.7.5 Set keyboard focus for I/O item - xdl_control_io_kbfocus
        2.12.7.6 Get input string - xdl_control_io_getdata
        2.12.7.7 Get required size - xdl_control_io_getzize


2.13    THE BLANK OBJECT VIEW-OBJECT ROUTINES
2.13.1  INTRODUCTION
2.13.2  Creating and Handling a Blank View-Object
        2.13.2.1 Introduction
        2.13.2.2 Create a blank object view-object - xdl_blank_object


2.14    THE IMAGE DISPLAY VIEW-OBJECT ROUTINES
2.14.1  INTRODUCTION
2.14.2  Creating and Handling an Image Display View-Object
        2.14.2.1 Introduction
        2.14.2.2 Create an image view-object - xdl_image
        2.14.2.3 Get selected pixel position - xdl_image_getpix
        2.14.2.4 Get pixel position from an overlay - xdl_image_getpix_ovly
        2.14.2.5 Get selected rectangle - xdl_image_getrect
        2.14.2.6 Get display settings - xdl_image_settings
        2.14.2.7 Reset current display settings - xdl_image_reset
        2.14.2.8 Set local axis names - xdl_image_axnames
        2.14.2.9 Display the image now - xdl_image_display_now
        2.14.2.10 Set background image - xdl_image_background
        2.14.2.11 Set a new image - xdl_image_newimg
        2.14.2.12 Reset overlay offset values - xdl_image_ovly_offset
        2.14.2.13 Reset an overlay colour - xdl_image_set_colour
        2.14.2.14 Reset user defined colour map - xdl_image_set_colormap
        2.14.2.15 Store and display an overlay symbol - xdl_image_symbol
        2.14.2.16 Store and display overlay symbols - xdl_image_symbols
        2.14.2.17 Clear overlay symbols - xdl_image_clear_symbols
        2.14.2.18 Delete an overlay symbol - xdl_image_del_symbol
        2.14.2.19 Store and display an overlay vector - xdl_image_vect
        2.14.2.20 Store and display overlay vectors - xdl_image_vects
        2.14.2.21 Store and display overlay vectors - xdl_image_vects_pos
        2.14.2.22 Store and display overlay boxes - xdl_image_boxes
        2.14.2.23 Clear overlay vectors - xdl_image_clear_vectors
        2.14.2.24 Delete an overlay vector - xdl_image_del_vect
        2.14.2.25 Output a text string - xdl_image_text
        2.14.2.26 Delete a text string - xdl_image_del_text
        2.14.2.27 Clear all text strings - xdl_image_clear_text
        2.14.2.28 Reset active strip message - xdl_image_input_message
        2.14.2.29 Calculate the size requirements - xdl_image_getsize


2.15    THE LAUE SIMULATIONS VIEW-OBJECT ROUTINES
2.15.1  INTRODUCTION
2.15.2  Creating and Handling a Laue Simulations View-Object
        2.15.2.1 Introduction
        2.15.2.2 Create a Laue simulation view-object - xdl_laue_sim
        2.15.2.3 Calculate size requirements - xdl_laue_sim_getsize
        2.15.2.4 Display a new simulation - xdl_laue_sim_new


2.16    THE ROTATION IMAGE SIMULATION VIEW-OBJECT ROUTINES
2.16.1  INTRODUCTION
2.16.2  Creating and Handling a Rotation Simulation View-Object
        2.16.2.1 Introduction
        2.16.2.2 Create a rotation simulation view-object - xdl_rot_sim
        2.16.2.3 Calculate size requirements - xdl_rot_sim_getsize
        2.16.2.4 Display a new simulation - xdl_rot_sim_new


2.17    THE SHOW UNIQUE DATA VIEW-OBJECT ROUTINES
2.17.1  INTRODUCTION
2.17.2  Creating and Handling a Show Unique Data View-Object
        2.17.2.1 Introduction
        2.17.2.2 Create a show unique view-object - xdl_show_unq
        2.17.2.3 Return selected spot position - xdl_show_unq_getdata

 
CHAPTER 3: IMAGE FILE HANDLING AND BACKGROUND ROUTINES
 

3.1    IMAGE FILE READING ROUTINES
3.1.1  INTRODUCTION
3.1.2  Film Image File Routines
       3.1.2.1  Introduction
       3.1.2.2  Open a film image file - xdl_open_film_file
       3.1.2.3  Read a full film image file - xdl_read_full_film
       3.1.2.4  Close a film image file - xdl_close_film_file
3.1.3  Image-Plate Image File Routines
       3.1.3.1  Introduction
       3.1.3.2  Open an image plate (i2) file - xdl_open_i2
       3.1.3.3  Read a full image-plate image file - xdl_read_full_i2
       3.1.3.4  Close an image plate (i2) file - xdl_close_i2
3.1.4  MAR Image-Plate File Routines
       3.1.4.1  Introduction
       3.1.4.2  Read a MAR image plate file - xdl_read_mar
       3.1.4.3  Read and squash a MAR image plate file - xdl_rdsquash_mar
       3.1.4.4  Read a Photon Factory Log Byte File - xdl_read_pfbyte
3.1.5  Axis Order Decoding Routines
       3.1.5.1  Introduction
       3.1.5.2  Interpret axis order string - xdl_axord


3.2    IMAGE BACKGROUND CALCULATION ROUTINES
3.2.1  INTRODUCTION
3.2.2  Background Calculation Routines
       3.2.2.1  Introduction
       3.2.2.2  Calculate background image using a 2-D search - xdl_bg_calc
       3.2.2.3  Background 2-D search with progress bar - xdl_bg_calc_prog
       3.2.2.4  Calculate radially averaged background - xdl_bg_strip
       3.2.2.5  Form radially averaged background image - xdl_bg_radimg
       3.2.2.6  Get background value from background function - xdl_bg_val
       3.2.2.7  Get background value from background image - xdl_bg_valimg


CHAPTER 4: THE PANEL ITEM ROUTINES AND CALLBACKS

4.1  INTRODUCTION
4.2  Panel Choice Item Routines
     4.2.1    Introduction
     4.2.2    Create a panel choice item - xdl_panel_choice
     4.2.3    Reset panel choice item - xdl_panel_choice_reset
     4.2.4    Get window id - xdl_panel_choice_wid
     4.2.5    Get size - xdl_panel_choice_size
4.3  Panel Button Item Routines
     4.3.1    Introduction
     4.3.2    Create a panel button item - xdl_panel_button
     4.3.3    Set a new button label string - xdl_panel_button_set
     4.3.4    Get window id - xdl_panel_button_wid
     4.3.5    Get size - xdl_panel_button_size
4.4  Panel Label Item Routines
     4.4.1    Introduction
     4.4.2    Create a panel label item - xdl_panel_label
     4.4.3    Set a new panel label string - xdl_panel_label_set
     4.4.4    Get window id - xdl_panel_label_wid
     4.4.5    Get size - xdl_panel_label_size
4.5  Panel Value Item Routines
     4.5.1    Introduction
     4.5.2    Create a panel value item - xdl_panel_value
     4.5.3    Set a new panel value string - xdl_panel_value_set
     4.5.4    Get window id - xdl_panel_value_wid
     4.5.5    Get size - xdl_panel_value_size
4.6  Panel Slider Item Routines
     4.6.1    Introduction
     4.6.2    Create a panel slider item - xdl_panel_slider
     4.6.3    Reset a panel slider position - xdl_panel_slider_reset
     4.6.4    Get window id - xdl_panel_slider_wid
     4.6.5    Get size - xdl_panel_slider_size
4.7  Panel I/O Item Routines
     4.7.1    Introduction
     4.7.2    Create a panel io item - xdl_panel_io
     4.7.3    Set a new panel i/o item prompt - xdl_panel_io_prompt
     4.7.4    Clear/reset a panel i/o item - xdl_panel_io_clear
     4.7.5    Get window id - xdl_panel_io_wid
     4.7.6    Get size - xdl_panel_io_size


CHAPTER 5: XDL_VIEW LAYOUT ROUTINES

5.1  INTRODUCTION
5.2  Determining XDL_VIEW Layout Parameters
     5.2.1    Introduction
     5.2.2    Initialise lists - xdl_layout_init
     5.2.3    Define a single object - xdl_layout_set_single
     5.2.4    Give details for a table - xdl_layout_set_table
     5.2.5    Give details of layout pair - xdl_layout_set_pair
     5.2.6    Determine the layout - xdl_layout
     5.2.7    Get object position and size - xdl_layout_get_position
     5.2.8    Reset objects in table - xdl_layout_reset_table
     5.2.9    Reset single object position - xdl_layout_reset_single


CHAPTER 1: THE XDL_VIEW MANAGEMENT ROUTINES 
===========================================


1.1 INTRODUCTION
 
This file contains a series of routines concerned with the  management  and
coding of XDL_VIEW view-objects. Some are  application  callable  and  have
Fortran interfaces whereas the others  are  for  internal  use  within  the
source code of the view-objects.
 
The following sets of routines are available:
 
   Application Callable Management Routines
   Special Purpose Application Callable Routines
   Creating Windows when Coding View-Objects
   Creating Active Strips when Coding View-Objects
   Registering View-Objects and Windows when Coding View-Objects
   Getting Items from a View-Objects List when Coding View-Objects
   Deleteing a Panel Item when Coding View-Objects
   Handling Selections when Coding View-Objects
   Outputting Error Messages when Coding View-Objects
   Miscellaneous Routines used when Coding View-Objects
 
1.2 APPLICATION CALLABLE MANAGEMENT ROUTINES
 
1.2.1 Introduction
 
These are routines commonly used by the application programmer  making  use
of the xdl_view package. There are  routines  to  initialise  the  XDL_VIEW
package, handle events and delete view-objects. A routine is provided which
must be used when passing character strings from a Fortran  program.  There
are further routines to raise and lower windows and get their positions.
 
 
The following routines are available:
 
   XDL_VIEW initialisation - xdl_open_view
   XDL_VIEW event handling - xdl_get_events
   XDL_VIEW event flushing - xdl_flush_events
   Delete an XDL_VIEW view-object - xdl_delete_view_object
   Pointers list index of a Fortran character string - xdlstr
   Get root coordinates - xdl_view_object_rootxy
   Raise a view-object - xdl_view_object_raise
   Lower a view-object - xdl_view_object_lower
 
1.2.2 XDL_VIEW initialisation - xdl_open_view
 
The initialisation routine xdl_open_view (xdlf_open_view)  must  be  called
before any other XDL_VIEW routine. It initialises the list of view-objects.
It also sets up, in addition to a a small default colour map which contains
the colours black, white and the six primary and secondary colours,  colour
maps based on the user's requirements for the application if  possible.  In
addition to these items, a number of other global data items, which may  be
used within the code for the individual view-objects, are  set  up  by  the
initialisation routine.
 
Fonts will normally be defined as X-windows resources Xdl*font1...Xdl*font5
and Xdl*boldFont1...Xdl*boldFont5. There are  five  normal  and  five  bold
fonts. These should normally be fixed width fonts. Each series must  be  in
ascending size order. Bold fonts must match normal fonts to within 1  pixel
in width and two in height. Some of the view-objects assume that the  small
font does not exceed 7x13 in pixels in size; a warning will  be  output  if
this size is exceeded.
 
The following defaults are used by xdl_open_view if the font resources 
are not defined:

Normal fonts

    *adobe-courier-medium-r*--8*
    *adobe-courier-medium-r*--12*
    *adobe-courier-medium-r*--14*
    *adobe-courier-medium-r*--18*
    *adobe-courier-medium-r*--24*

Bold fonts

    *adobe-courier-bold-r*--8*
    *adobe-courier-bold-r*--12*
    *adobe-courier-bold-r*--14*
    *adobe-courier-bold-r*--18*
    *adobe-courier-bold-r*--24*
 
 
Fortran call:
 
         CALL XDLF_OPEN_VIEW (NUMC, NCOLORS, NPLANES, IERR)
 
 
Parameters:
 
NUMC     (R)  No. of colorsets (see numc)
NCOLORS  (R)  Integer array of nos. of colors (see ncolors)
NPLANES  (R)  Integer array of nos. of overlay planes 
              (see nplanes)
IERR     (W)  Returns the status from the xdl_open_view call
 
 
'C' call:
 
int xdl_open_view (numc, ncolors, nplanes)
 
 
Parameters:
 
int numc;           /*Number of colorsets to be allocated in addition
                      to the standard short pallette (may be 0) (R)*/
int ncolors[];      /*Array of 'ncolors' values for the XAllocColorCells
                      routines (numc values) (R)*/
int nplanes[];      /*Array of 'nplanes' values for the XAllocColorCells
                      routines (numc values) (R)*/

 
 
Return:  =0 if OK, >0 if error:
                      bit 0  set unable to allocate the requested 
                             colorsets.
                             (XDL_csets_alloc will be set to 0)
                             non-fatal - view-objects should cope with this
                             case.
 
 
1.2.3 XDL_VIEW event handling - xdl_get_events
 
An important part of XDL_VIEW is the X event handling  mechanism.  This  is
normally done through a call from the application program  to  the  routine
xdl_get_events (xdlf_get_events). When the  routine  is  called,  the  user
specifies a list of the view objects from which the  program  is  ready  to
receive input ('active' view-objects).  The  routine  services  all  the  X
events, passing them on to the approriate event handling routines until  an
event causes program input from one of the active view-objects;  when  this
occurs, a return is made from the routine giving the view-object handle  of
the routine from which the input originated.
 
Fortran call:
 
         CALL XDLF_GET_EVENTS (NUMIVH, IVHLIST, IVH)
 
 
Parameters:
 
NUMIVH   (R)  Number of view-objects to return data (see num-vh)
IVHLIST  (R)  Array of NUMIVH view object handles (see vh_list)
IVH      (W)  Returns the view-object handle of object returning
              the data (return from xdl_get_events)
              the data (return from xdl_get_events)
 
 
'C' call:
 
int xdl_get_events (num_vh, vh_list)
 
 
Parameters:
 
int num_vh;      /* Number of view objects from which data are to be
                    returned (may be 0 if no return is required)
                    if -num_vh is given then the routine be in a no wait
                    mode and will return when either input is received or
                    all current events have been flushed (R)*/
int vh_list[];   /* Array of the num_vh view-object handles (R)*/

 
 
Return:  The view-object handle of the view object returning the data.
         (May be 0 in no wait mode)
 
 
1.2.4 XDL_VIEW event flushing - xdl_flush_events
 
The routine xdl_flush_events (xdlf_flush_events) services queued up events.
It may be called at intervals during  a  long  calculation  to  keep  event
handling going. It is only used when the  application  is  not  waiting  to
receive data from a view-object. It returns when the event queue is empty.
 
Fortran call:
 
         CALL XDLF_FLUSH_EVENTS (IDUM)
 
 
Parameters:
 
IDUM     (R)  Dummy parameter
 
 
'C' call:
 
void xdl_flush_events (dummy)
 
 
Parameters:
 
int dummy;       /* Dummy parameter (R)*/

 
 
Return:  None
 
 
1.2.5 Delete an XDL_VIEW view-object - xdl_delete_view_object
 
The  routine  xdl_delete_view_object  (xdlf_delete_view_object)  deletes  a
view-object and any of its children.
 
Fortran call:
 
         CALL XDLF_DELETE_VIEW_OBJECT (IVH, IERR)
 
 
Parameters:
 
IVH     (R)   View-object handle (see vh)
IERR    (W)   Return from xdl_delete_view_object routine
 
 
'C' call:
 
int xdl_delete_view_object (vh)
 
 
Parameters:
 
int vh;               /* The view object handle (R) */

 
 
Return:  0 = OK, 1 = requested view object not found
 
 
1.2.6 Pointers list index of a Fortran character string - xdlstr
 
The routine xdlstr is used to return an index to a list of character string
pointers held within XDL_VIEW and used where  a  Fortran  callable  routine
passes character data to  or  from  the  routine.  The  actual  paramter(s)
expected by the C routine are machine dependent. The Fortran call is of the
form:
 
               XDLSTR (CHS)   where CHS is a Fortran character variable  or
                              string.
 
The function XDLSTR must be declared in the calling Fortran program  as  an
INTEGER FUNCTION.
 
 
'C' call:
 
{
   XDL_pointers_index++;
   if (XDL_pointers_index>=MAXPOINTERS) XDL_pointers_index = 0;
   XDL_pointers[XDL_pointers_index] = ch;
   return XDL_pointers_index;
}

#endif

#if CHAR_STRING_TYPE == 2

typedef struct
{
   short int len;
   unsigned char type;
   unsigned char class;
   char * addr;
}
   Vax_ch_desc;

int xdlstr (ch_desc)
 
 
Parameters:
 
Vax_ch_desc *ch_desc;     /* Pointer to character descriptor (R)*/

 
 
Return:  Index in the XDL_pointers list from 0 to MAXPOINTERS-1
 
 
1.2.7 Get root coordinates - xdl_view_object_rootxy
 
The  routine  xdl_view_object_rootxy  (xdlf_view_object_rootxy)is  used  to
convert x, y coordinates within a view object to xroot,  yroot  coordinates
relative to the root window.
 
Fortran call:
 
         CALL XDLF_VIEW_OBJECT_ROOTXY (IVH, IX, IY, IXROOT, IYROOT, IERR)
 
 
Parameters:
 
IVH         (R)  View-object handle (see vh)
IX          (R)  X coordinate within the view-object (see x)
IY          (R)  Y coordinate within the view-object (see y)
IXROOT      (W)  Returns the root window X coordinate (see xroot)
IYROOT      (W)  Returns the root window Y coordinate (see yroot)
IERR        (W)  Return from the xdl_view_object_rootxy call
 
 
'C' call:
 
int xdl_view_object_rootxy (vh, x, y, xroot, yroot)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int x;           /* x coordinate within view-object (R)*/
int y;           /* y coordinate within view-object (R)*/
int *xroot;      /* Returns x coordinate with respect to the root 
                    window (W)*/
int *yroot;      /* Returns y coordinate with respect to the root 
                    window (W)*/

 
 
Return:  =0 OK, =1 view-object not found
 
 
1.2.8 Raise a view-object - xdl_view_object_raise
 
The routine xdl_view_object_raise (xdlf_view_object_raise) is used to raise
a view-object to the top (i.e to the front) of the stacking  order  amongst
its siblings (view-objects with the same parent) on the screen.
 
Fortran call:
 
         CALL XDLF_VIEW_OBJECT_RAISE (IVH, IERR)
 
 
Parameters:
 
IVH         (R)  View-object handle (see vh)
IERR        (W)  Return from the xdl_view_object_raise call
 
 
'C' call:
 
int xdl_view_object_raise (vh)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/

 
 
Return:  =0 OK, =1 view-object not found
 
 
1.2.9 Lower a view-object - xdl_view_object_lower
 
The routine xdl_view_object_lower (xdlf_view_object_lower) is used to lower
a view-object to the bottom (i.e to the back) of the stacking order amongst
its siblings (view-objects with the same parent) on the screen.
 
Fortran call:
 
         CALL XDLF_VIEW_OBJECT_LOWER (IVH, IERR)
 
 
Parameters:
 
IVH         (R)  View-object handle (see vh)
IERR        (W)  Return from the xdl_view_object_lower call
 
 
'C' call:
 
int xdl_view_object_lower (vh)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/

 
 
Return:  =0 OK, =1 view-object not found
 
 
1.3 SPECIAL PURPOSE APPLICATION CALLABLE ROUTINES
 
1.3.1 Introduction
 
These are some additional special purpose routines which may be used by the
application programmer  if  needed.  They  include  routines  for  handling
non-blocking  terminal  input,  handling  events   at   timed   interrupts,
synchronising X calls and introducing a program delay.
 
 
The following routines are available:
 
   Event handling with time out- xdl_get_events_timeout
   XDL_VIEW event and standard input handling - xdl_getio_events
   Get string after xdl_getio_events call - xdl_getio_string
   Read a string from the terminal - xdl_tread
   XDL_VIEW timer driven event handling - xdl_timer_events
   XDL_VIEW XSync/XSyschronise calls - xdl_sync
   Delay - xdl_delay
 
1.3.2 Event handling with time out- xdl_get_events_timeout
 
An important part of XDL_VIEW is the X event handling  mechanism.  This  is
normally done through a call from the application program  to  the  routine
xdl_get_events (xdlf_get_events). When the  routine  is  called,  the  user
specifies a list of the view objects from which the  program  is  ready  to
receive input ('active' view-objects).  The  routine  services  all  the  X
events, passing them on to the approriate event handling routines until  an
event causes program input from one of the active view-objects;  when  this
occurs, a return is made from the routine giving the view-object handle  of
the routine from which the  input  originated.  The  xdl_get_events_timeout
(xdlf_get_events_timeout) routine has the additional function that a return
will be made after a requested interval if there  has  not  been  a  return
occasioned by input to an active window. The time out interval may be taken
from the invocation of the routine or from the last time an  event  occured
in any of a list of specified view-objects.
 
Fortran call:
 
         CALL XDLF_GET_EVENTS_TIMEOUT (NUMIVH, IVHLIST, MSECS, 
        +                              NUMIVH2, IVHLIST2, IVH)
 
 
Parameters:
 
NUMIVH   (R)  Number of view-objects to return data (see num_vh)
IVHLIST  (R)  Array of NUMIVH view object handles (see vh_list)
MSECS    (R)  Return after this number of milliseconds if no
              input has been done (0 = no time out)
NUMIVH2  (R)  Number of view-objects in list 2 for re-setting
              the time interval (see IVHLIST2); may be 0.
IVHLIST2 (R)  Array of NUMIVH2 view object handles; the time out
              period will be re-started whenever an event takes place
              in any of these listed view-objects so that the
              time out return will only occur when no events have
              taken place in these objects for the time out period.
IVH      (W)  Returns the view-object handle of object returning
              the data (return from xdl_get_events)
 
 
'C' call:
 
int xdl_get_events_timeout (num_vh, vh_list, msecs, num_vh2, vh_list2)
 
 
Parameters:
 
int num_vh;      /* Number of view objects from which data are to be
                    returned (may be 0 if no return is required)
                    if -num_vh is given then the routine be in a no wait
                    mode and will return when either input is received or
                    all current events have been flushed (R)*/
int vh_list[];   /* Array of the num_vh view-object handles (R)*/
int msecs;       /* Return after this number of milliseconds if no
                    input has been done (0 = no time out) (R)*/
int num_vh2;     /* Number of view objects in list 2 (see vh_list2)
                    for re-setting the time interval; may be 0 (R)*/
int vh_list2[];  /* Array of NUMIVH2 view object handles; the time out
                    period will be re-started whenever an event takes 
                    place in any of these listed view-objects so that 
                    the time out return will only occur when no events 
                    have taken place in these objects for the time out 
                    period. (R)*/

 
 
Return:  The view-object handle of the view object returning the data.
         May be 0 in no wait mode or  -1 if the return is due to timing 
         out after the requested interval.
 
 
1.3.3 XDL_VIEW event and standard input handling - xdl_getio_events
 
An important part of XDL_VIEW is the X event handling  mechanism.  This  is
normally done through a call from the application program  to  the  routine
xdl_get_events (xdlf_get_events). When the  routine  is  called,  the  user
specifies a list of the view objects from which the  program  is  ready  to
receive input ('active' view-objects).  The  routine  services  all  the  X
events, passing them on to the approriate event handling routines until  an
event causes program input from one of the active view-objects;  when  this
occurs, a return is made from the routine giving the view-object handle  of
the routine from which the input originated. If, in  addition  to  handling
these window events, the user wishes to read data from the  standard  input
stream then this input must be done in a 'non-blocking' mode or  the  whole
process may hang. The routine xdl_getio_events  (xdlf_getio_events)  allows
such input in addition to any other event handling required.
 
Fortran call:
 
         CALL XDLF_GETIO_EVENTS (NUMIVH, IVHLIST, IVH)
 
 
Parameters:
 
NUMIVH   (R)  Number of view-objects to return data (see num-vh)
              (may be 0)
IVHLIST  (R)  Array of NUMIVH view object handles (see vh_list)
IVH      (W)  Returns the view-object handle of object returning
              the data (return from xdl_getio_events) or 0 is 
              there was input from stdin.
 
 
'C' call:
 
int xdl_getio_events (num_vh, vh_list)
 
 
Parameters:
 
int num_vh;      /* Number of view objects from which data are to be
                    returned (may be 0) (R)*/
int vh_list[];   /* Array of the num_vh view-object handles (R)*/

 
 
Return:  The view-object handle of the view object returning the data.
         or 0 if input data was from stdin.
 
 
1.3.4 Get string after xdl_getio_events call - xdl_getio_string
 
The routine xdl_getio_string (xdlf_getio_string) is called  to  return  the
last string input from the terminal (in a non-blocking read mode) when  the
routine xdl_getio_events (xdlf_getio_events) returns a  view-object  handle
of 0.
 
Fortran call:
 
         CALL XDLF_GETIO_STRING (XDLSTR(STRING), MAXLEN, IERR)
 
 
Parameters:
 
STRING    (W)      Returned string (see string)
                   ** Pass address using the XDLSTR function **
MAXLEN    (R)      Maximum allowed length for the returned string
                   ( > 0 ) (cf max_len)
IERR      (W)      Return status from the xdl_getio_string call
 
 
'C' call:
 
int xdl_getio_string (string, max_len)
 
 
Parameters:
 
char string[];   /* Returned string (W)*/
int max_len;     /* if >0 Maximum length of returned string allowed
                          (excluding terminating null - string must be at
                          least max_len + 1 characters in length)
                    if <0 abs(max_len) characters will be returned padded
                          with blanks if needed (for 'fortran' use) (R)*/

 
 
Return: = 0 OK string present, =1 blank/null string
 
 
1.3.5 Read a string from the terminal - xdl_tread
 
The routine xdl_tread (xdlf_tread) is  used  to  read  a  string  from  the
terminal (standard input). The routine performs  reads  in  a  non-blocking
mode and the background handling of X  events  for  the  view-objects  will
continue. Normal reads should not be used as this will block event handling
and can cause a hang-up.
 
Fortran call:
 
         CALL XDLF_TREAD (XDLSTR(STRING), MAXLEN, IERR)
 
 
Parameters:
 
STRING    (W)      Returned string (see string)
                   ** Pass address using the XDLSTR function **
MAXLEN    (R)      Maximum allowed length for the returned string
                   ( > 0 ) (cf max_len)
IERR      (W)      Return status from the xdl_tread call
 
 
'C' call:
 
int xdl_tread (string, max_len)
 
 
Parameters:
 
char string[];   /* Returned string (W)*/
int max_len;     /* if >0 Maximum length of returned string allowed
                          (excluding terminating null - string must be at
                          least max_len + 1 characters in length)
                    if <0 abs(max_len) characters will be returned padded
                          with blanks if needed (for 'fortran' use) (R)*/

 
 
Return: = 0 OK string returned, =1 blank/null string returned
 
 
1.3.6 XDL_VIEW timer driven event handling - xdl_timer_events
 
An important part of XDL_VIEW is the X event handling  mechanism.  This  is
normally done through a call from the application program  to  the  routine
xdl_get_events (xdlf_get_events). In  some  applications,  it  may  not  be
convenient to handle events  in  this  way  and  this  routine  provides  a
mechanism to keep the event queue serviced at  regular  intervals  using  a
system timer. It may also be used during lengthy calculations to  keep  the
event queue serviced. The routine is only used  when  the  program  is  not
waiting for input from one or more view-objects. It should be noted that  a
call    to    xdl_get_events    (xdlf_get_events)    or    xdl_getio_events
(xdlf_getio_events) switches off the timer driven event handling so that it
will need to be switched on again after such  a  call  if  required.  Where
possible, the use of this routine should be avoided.
 
Fortran call:
 
         CALL XDLF_TIMER_EVENTS (IOPT)
 
 
Parameters:
 
IOPT     (R)  = 0 turn off timer driven event handling, 
              = 1 turn on timer driven event handling
 
 
'C' call:
 
int xdl_timer_events (on_off)
 
 
Parameters:
 
int on_off;      /* = 1 turn timer driven event handling on,
                    = 0 turn timer driven event handling off (R)*/
 
 
Return:  
 
 
1.3.7 XDL_VIEW XSync/XSyschronise calls - xdl_sync
 
The routine xdl_sync (xdlf_sync) routine enables access  to  the  X-windows
XSync and XSynchronize functions in case these are needed.
 
Fortran call:
 
         CALL XDLF_SYNC (IOPT)
 
 
Parameters:
 
IOPT     (R)  Flag =1 XSync, no discard
                   =2 XSync, discard
                   =3 XSynchronize on
                   =4 XSynchronize off
 
 
'C' call:
 
void xdl_sync (opt)
 
 
Parameters:
 
int opt;       /* Flage =1 XSync, no discard
                        =2 XSync, discard
                        =3 XSynchronize on
                        =4 XSynchronize off (R)*/

 
 
Return:  None
 
 
1.3.8 Delay - xdl_delay
 
The routine xdl_delay (xdlf_delay) is used to introduce a program delay for
a requested no. of milliseconds e.g. to wait for new windows to be exposed.
 
Fortran call:
 
         CALL XDLF_DELAY (MSEC)
 
 
Parameters:
 
MSEC       (R)  Time of delay in milliseconds
 
 
'C' call:
 
void xdl_delay (msec)
 
 
Parameters:
 
int msec;          /* Delay in milliseconds (R)*/

 
 
Return:  none
 
 
1.4 CREATING WINDOWS WHEN CODING VIEW-OBJECTS
 
1.4.1 Introduction
 
These are routines used to create windows when coding a new view-object.
 
The following routines are available:
 
   Create a base frame window - xdl_create_base_frame_window
   Create a frame window - xdl_create_frame_window
   Create a paint window - xdl_create_paint_window
 
1.4.2 Create a base frame window - xdl_create_base_frame_window
 
The routine xdl_create_base_frame_window is used to create (and map) a base
frame window. This window is a child of the Rootwindow. The routine sends a
title, icon label, hints etc. to the window manager.
 
'C' call:
 
Window xdl_create_base_frame_window (title, icon_label, x, y, 
                                     width, height)
 
 
Parameters:
 
char * title;       /*Title for passing to window manager (null term) (R)*/
char * icon_label;  /*Icon label for passing to window manager 
                      (null term) (R)*/
int x;              /*Root x coordinate for window (-1 to leave selection
                      to the window manager) (R)*/
int y;              /*Root y coordinate for window (-1 to leave selection
                      to the window manager) (R)*/
int width;          /*Window width (including border of 1 at each side) 
                      (R)*/
int height;         /*Window height (including border of 1 at top and 
                      bottom (R)*/

 
 
Return:  The window id
 
 
1.4.3 Create a frame window - xdl_create_frame_window
 
The routine xdl_create_frame_window is used to create  (and  map)  a  frame
window. Such a window is normally  used  as  the  top  level  window  of  a
view-object when it has a parent view-object.
 
'C' call:
 
Window xdl_create_frame_window (wparent, x, y, width, height, cset)
 
 
Parameters:
 
Window wparent;     /*Window id of the parent window (R)*/
int x;              /*x position of top left pixel (of border) (R)*/
int y;              /*y position of top left pixel (of border) (R)*/
int width;          /*Window width (including border of 1 at each side) 
                      (R)*/
int height;         /*Window height (including border of 1 at top and 
                      bottom (R)*/
int cset;           /*XDL_VIEW Colorset number (R)*/

         /* Note: Origin pixel at top left within border */
 
 
Return:  The window id
 
 
1.4.4 Create a paint window - xdl_create_paint_window
 
The  routine  xdl_create_paint_window  is  used  to  create  (and  map)  an
input/output paint window.
 
'C' call:
 
Window xdl_create_paint_window (wparent, x, y, brdw, width, height, 
                                cset)
 
 
Parameters:
 
Window wparent;     /*Window id of the parent window (R)*/
int x;              /*x position of top left pixel (of border) (R)*/
int y;              /*y position of top left pixel (of border) (R)*/
int brdw;           /*Border width in pixels (normally 1)*/
int width;          /*Window width (including border at each side) (R)*/
int height;         /*Window height (including border at top and 
                      bottom (R)*/
int cset;           /*XDL_VIEW Colorset number (R)*/

         /* Note: Origin pixel at top left within border */
         /*       Paintable width  = width - 2*brdw      */
         /*       Paintable height = height - 2*brdw     */
 
 
Return:  The window id
 
 
1.5 CREATING ACTIVE STRIPS WHEN CODING VIEW-OBJECTS
 
1.5.1 Introduction
 
These are  routines  used  to  create  active  strips  when  coding  a  new
view-object.
 
The following routines are available:
 
   Create an active strip - xdl_create_active_strip
   Set active strip to 'on' - xdl_active_strip_on
   Set active strip to 'off' - xdl_active_strip_off
 
1.5.2 Create an active strip - xdl_create_active_strip
 
The routine xdl_create_active_strip is  used  to  create  an  active  strip
window and add it to the view-object's window list.  This  strip  indicates
whether or not the application is waiting for input from a view object. The
on/off  states  are   set   by   the   routines   xdl_active_strip_on   and
xdl_active_strip_off. A filled square in green (or black  if  b/w  display)
indicates that input is awaited and a text string indicates the  nature  of
the required input. An open square indicates that input is not awaited. The
strip will be placed with its origin at 4, 4 of the parent  window  with  a
depth of 20. The required width (normally the parent window width -  8)  is
passed to the routine. Bold text should be used when  the  window  has  the
keyboard focus and normal text be used otherwise.
 
'C' call:
 
Window xdl_create_active_strip (wparent, vh, width, repaint)
 
 
Parameters:
 
Window wparent;        /* The parent window for which the strip is to be 
                          created (R) */
int vh;                /* View-object handle (The view object must have
                          been added to the list of view-objects using 
                          the routine xdl_add_new_view_object before 
                          xdl_create_active_strip is called (R) */
int width;             /* The width for the strip (R) */
void (*repaint)();     /* Active strip repaint function (R)*/

 
 
Return:  The created window
 
 
1.5.3 Set active strip to 'on' - xdl_active_strip_on
 
The routine xdl_active_strip_on is used to set an active strip to its  'on'
state.
 
'C' call:
 
void xdl_active_strip_on (wid, str, bold)
 
 
Parameters:
 
Window wid;          /* The active strip window id (R) */
char * str;          /* The string to be displayed (R) */
int bold;            /* =1 Use bold text (to indicate keyboard focus) or
                        =0 Use normal text (R) */

 
 
Return:  None
 
 
1.5.4 Set active strip to 'off' - xdl_active_strip_off
 
The routine xdl_active_strip_off is used to set  an  active  strip  to  its
'off' state.
 
'C' call:
 
void xdl_active_strip_off (wid)
 
 
Parameters:
 
Window wid;      /* The active strip window id (R) */

 
 
Return:  None
 
 
1.6 REGISTERING VIEW-OBJECTS AND WINDOWS WHEN CODING VIEW-OBJECTS
 
1.6.1 Introduction
 
These are routines used to register new view-objects by adding them  to  an
internal list and to add window information to that list when coding a  new
view-object.
 
 
The following routines are available:
 
   Add a new view-object - xdl_new_view_object
   Add a window to the windows list - xdl_add_window
   Add a library window to windows list - xdl_add_libwin
   Add to level window callbacks - xdl_add_top_callbacks
 
1.6.2 Add a new view-object - xdl_new_view_object
 
The routine xdl_new_view_object is used to add a  new  view-object  to  the
list of view-objects and to initialiase its associated data.
 
'C' call:
 
int xdl_new_view_object (vh, wid, vh_parent, gd, type, on_off, tidy_up)
 
 
Parameters:
 
int vh;                 /*The view_object handle for the new view object
                          (vh) (R)*/
Window wid;             /*The parent window of the new view object (R)*/
int vh_parent;          /*The view-object handle for the parent 
                          (0 if none) (R)*/
char * gd;              /*Pointer to the global data area used by the 
                          view-object's routines (R)*/
int type;               /*A unique integer for the view-object type (R)*/
void (*on_off)();       /*Pointer to the input on/off function for the
                          view object. May be NULL if not required or
                          implemented. (Used by xdl_get_events) (R)*/
void (*tidy_up)();      /*Pointer to the tidy up routine for the 
                          view-object. This routine will be called by 
                          xdl_delete_view_object when the view object
                          is deleted. It should be used for example
                          to free any memory areas allocated by the 
                          view-object (except for the global data area 
                          which will be automatically freed by 
                          xdl_delete_view_object). May be NULL if not 
                          required or implemented. (R)*/

 
 
Return: The offset in the XDL_view_objects array for the new view object.
 
 
1.6.3 Add a window to the windows list - xdl_add_window
 
The routine xdl_add_window is used to add a derived (child/subwindow) to  a
list of such windows for the view-object.
 
'C' call:
 
void xdl_add_window (vh, wid, repaint, ehp)
 
 
Parameters:
 
int vh;              /*The view-object handle for the view-object to 
                       whose derived windows list the new window is to 
                       be appended (R)*/
Window wid;          /*The id of the window to be added (R)*/
void (*repaint)();   /*Address of repaint routine for the window 
                       (may be NULL) (R)*/
void (*ehp)();       /*Address of event handling procedure for the window 
                       (may be NULL) (R)*/

 
 
Return:  None.
 
 
1.6.4 Add a library window to windows list - xdl_add_libwin
 
The routine xdl_add_libwin is  used  to  add  a  derived  (child/subwindow)
library routine window to the list of windows for a view-object.
 
'C' call:
 
void xdl_add_libwin (vh, wid, gd, repaint, ehp, callback, tidy_up)
 
 
Parameters:
 
int vh;              /*The view-object handle for the view-object to 
                       whose derived windows list the new window is to 
                       be appended (R)*/
Window wid;          /*The id of the window to be added (R)*/
char *gd;            /*The global data area associated with the window -
                       normally that of the parent view-object's global
                       data area for routines forming part of the code
                       for a view-object. Normally a separately defined
                       area for special library routine window objects 
                       (R)*/
void (*repaint)();   /*Address of repaint routine for the window 
                       (may be NULL) (R)*/
void (*ehp)();       /*Address of event handling procedure for the window 
                       (may be NULL) (R)*/
void (*callback)();  /*Address of callback routine if required. 
                       Normally NULL except when using a library routine 
                       window which will return data to the calling 
                       view-object (R)*/
void (*tidy_up)();   /*Routine to be called when a window is deleted to
                       tidy up (e.g. free allocated memory areas or other
                       allocated resources). May be NULL if not required.
                       For a window set up by a routine forming part of 
                       the specific code for the view object, all the 
                       tidying up will normally be done by the one 
                       tidy_up routine associated with its top level 
                       window (R)*/
                       
 
 
Return:  None.
 
 
1.6.5 Add to level window callbacks - xdl_add_top_callbacks
 
The  routine  xdl_add_top_callbacks  allows  the  normally  NULL  callbacks
(repaint and event handling) to be reset for the top level window of a view
object.
 
'C' call:
 
void xdl_add_top_callbacks (vh, repaint, ehp)
 
 
Parameters:
 
int vh;              /*The view-object handle for the view-object to 
                       whose derived windows list the new window is to 
                       be appended (R)*/
void (*repaint)();   /*Address of repaint routine for the window 
                       (may be NULL) (R)*/
void (*ehp)();       /*Address of event handling procedure for the window 
                       (may be NULL) (R)*/

 
 
Return:  None.
 
 
1.7 GETTING ITEMS FROM A VIEW-OBJECTS LIST WHEN CODING VIEW-OBJECTS
 
1.7.1 Introduction
 
These are routines used to get data items from a view-objects internal list
when coding a new view object.
 
 
The following routines are available:
 
   Get offset in view-objects list from handle - xdl_getiv
   Get global data area from window id - xdl_get_global
   Get view-object handle from window id - xdl_get_vh
 
1.7.2 Get offset in view-objects list from handle - xdl_getiv
 
The routine xdl_getiv is used to find the offset  in  the  XDL_view_objects
array for a requested view-object handle.
 
'C' call:
 
int xdl_getiv (vh)
 
 
Parameters:
 
int vh;              /*The view-object handle (vh) (R)*/

 
 
Return:  The offset (>=0) or -1 if view object-handle not present.
 
 
1.7.3 Get global data area from window id - xdl_get_global
 
The routine xdl_get_global is used to get a pointer to the main view-object
global data area for a given window.
 
'C' call:
 
char * xdl_get_global (wid)
 
 
Parameters:
 
Window wid;      /* The window id for which the view-object's data area 
                    is to be found (R)*/

 
 
Return:  The pointer to the global data (0 if none found)
 
 
1.7.4 Get view-object handle from window id - xdl_get_vh
 
The routine xdl_get_vh is used  to  get  the  view-object  handle  for  the
view-object to which a given window belongs.
 
'C' call:
 
int xdl_get_vh (wid)
 
 
Parameters:
 
Window wid;      /* The window id for which the view-object handle is 
                    to be found (R)*/

 
 
Return:  The view-object handle (0 if none found)
 
 
1.8 DELETEING A PANEL ITEM WHEN CODING VIEW-OBJECTS
 
1.8.1 Introduction
 
These are routines used to delete panel items if required when coding a new
view-object.
 
 
The following routines are available:
 
   Delete a panel item - xdl_delete_panel_item
 
1.8.2 Delete a panel item - xdl_delete_panel_item
 
The routine xdl_delete_panel_item is used to delete a panel item while  the
view-object is still in use.
 
'C' call:
 
void xdl_delete_panel_item (vh, wid)
 
 
Parameters:
 
int vh;      /* View-object handle for the view-object to which the
                panel item belongs (R) */
Window wid;  /* The window id. of the panel item (R)*/

 
 
Return:  None
 
 
1.9 HANDLING SELECTIONS WHEN CODING VIEW-OBJECTS
 
1.9.1 Introduction
 
These are routines used assit with the handling of text selections  from/to
a window if this is required when coding a new view-object.
 
 
The following routines are available:
 
   Request selection ownership - xdl_select_owner
   Cancel selection ownership - xdl_select_cancel
   Request a selection - xdl_select_request
   Receive selection data - xdl_select_receive
 
1.9.2 Request selection ownership - xdl_select_owner
 
The routine xdl_select_owner is used to get the selection ownership of  the
XA_PRIMARY selection  (for  an  example  of  the  use  of  these  selection
routines, see the xdl_io_window.c view-object code).
 
'C' call:
 
void xdl_select_owner (wid)
 
 
Parameters:
 
Window wid;      /* The window id of the window requesting the selection
                    ownership (R) */

 
 
Return:  None
 
 
1.9.3 Cancel selection ownership - xdl_select_cancel
 
The routine xdl_select_cancel is used to cancel the selection ownership  of
the XA_PRIMARY selection (for an example of  the  use  of  these  selection
routines, see the xdl_io_window.c view-object code).
 
'C' call:
 
void xdl_select_cancel ()
 
 
Parameters:
 
{
    XSetSelectionOwner (XDL_display, XA_PRIMARY, None, CurrentTime);
    return;
}
/*
*******************************
**     xdl_select_respond    **
******************************

Purpose: Respond to selection request (XA_PRIMARY)

Return:  None

Author:  John W. Campbell, August 1993
*/

/*Doc:
Respond to selection request - xdl_select_respond

The routine xdl_select_respond is used to respond to a selection request
from another client on XA_PRIMARY. Only string requests are translated; 
otherwise a null reply is given (for an example of the use of these selection
routines, see the xdl_io_window.c view-object code).
*/

void xdl_select_respond (event, str, nitems)

XEvent * event;  /* The selection request event (R)*/
char *str;       /* The string containing the currently selected data (R)*/
int nitems;      /* Number of characters in the string to be sent (excluding
                    any null terminator); may be 0 (R) */

 
 
Return:  None
 
 
1.9.4 Request a selection - xdl_select_request
 
The routine xdl_select_request is used to request a (string) selection from
the XA_PRIMARY selection (for an example of  the  use  of  these  selection
routines, see the xdl_io_window.c view-object code).
 
'C' call:
 
void xdl_select_request (event, wid)
 
 
Parameters:
 
XEvent *event;   /* The event triggering the request (for timing) */
Window wid;      /* The window id of the window requesting the selection (R)*/

 
 
Return:  None
 
 
1.9.5 Receive selection data - xdl_select_receive
 
The routine xdl_select_receive is used to get the  (string)  data  received
following a  selection  request.  This  will  only  be  successful  if  the
selection owner can translate the request to  the  required  (string)  form
(for  an  example  of  the  use  of  these  selection  routines,  see   the
xdl_io_window.c view-object code).
 
'C' call:
 
int xdl_select_receive (event,wid,str,nitems,maxinstring)
 
 
Parameters:
 
XEvent *event;   /* The selection notify event (R)*/
Window wid;      /* The window id of the window requesting the selection
                    ownership (R) */
char **str;      /* Pointer to the received data 

                    NOTE   This data is allocated by the routine
                    ====   and should be freed after it has been 
                           used unless it is a null pointer; this is
                           only needed if the return is 1 (true) as
                           it will already be freed by this routine
                           when the return is 0 (R)*/

int *nitems;     /* Returns the number of items in the string (excluding
                    terminating null (W)*/
int maxinstring; /* Maximum number of items (characters) which may be
                    received */

 
 
Return:  =1 string received; =0 request could not be satisfied
 
 
1.10 OUTPUTTING ERROR MESSAGES WHEN CODING VIEW-OBJECTS
 
1.10.1 Introduction
 
These are routines used to output error messages in a standard format  when
coding a new view-object.
 
 
The following routines are available:
 
   Output an XDL_VIEW error message - xdl_view_errmsg
   'View-object not found' error message - xdl_view_iv_errmsg
   Error message for wrong type - xdl_view_type_errmsg
 
1.10.2 Output an XDL_VIEW error message - xdl_view_errmsg
 
The routine xdl_view_errmsg is used to output an error message for xdl_view
routines.
 
The error message will be of the form:  .  **  xdl_view  error  in  routine
xdl_routine_name ** ** user supplied error message ** .  The  stars  around
the user's message are supplied by the routine.
 
'C' call:
 
void xdl_view_errmsg (routine_name, message)
 
 
Parameters:
 
char *routine_name;   /* The name of the routine giving the error (null
                         terminated string (R) */
char *message;        /* A null terminated string describing the error */

 
 
1.10.3 'View-object not found' error message - xdl_view_iv_errmsg
 
The routine xdl_view_iv_errmsg is used  to  output  an  error  message  for
xdl_view routines for when a requested view-object handle is not  found  in
the list of view objects.
 
The error message will be of the form:  .  **  xdl_view  error  in  routine
xdl_routine_name ** ** view-object handle n not found in  current  list  of
view-objects ** .
 
'C' call:
 
void xdl_view_iv_errmsg (routine_name, vh)
 
 
Parameters:
 
char *routine_name;   /* The name of the routine giving the error 
                         (null terminated string) (R) */
int vh;               /* The view-object handle */
 
 
1.10.4 Error message for wrong type - xdl_view_type_errmsg
 
The routine xdl_view_type_errmsg is used to output  an  error  message  for
xdl_view routines for when a requested view-object  handle  is  used  in  a
routine which corresponds to an incorrect type  of  view  object.  e.g.  an
xdl_menu_area_setmenu routine was called with a view  handle  corresponding
to an xdl_param_table view-object.
 
The error message will be of the form:  .  **  xdl_view  error  in  routine
xdl_routine_name  **  **  view-object  for  handle  n  is   not   of   type
view_object_type ** .
 
'C' call:
 
void xdl_view_type_errmsg (routine_name, vh, view_object_type)
 
 
Parameters:
 
char *routine_name;     /* The name of the routine giving the error (null
                           terminated string)
                           e.g. "xdl_param_table_setvalue" (R) */
int vh;                 /* The view-object handle (R)*/
char *view_object_type; /* Null terminated string giving the view-object
                           type to which the routine belongs
                           e.g. "xdl_param_table" (R) */
 
 
1.11 MISCELLANEOUS ROUTINES USED WHEN CODING VIEW-OBJECTS
 
1.11.1 Introduction
 
These are some miscellaneous routines which may be used  if  required  when
coding a new view-object.
 
 
The following routines are available:
 
   Get root x, y coordinates - xdl_rootxy
   Copy an output string - xdl_copy_chars
   Test for a blank string - xdl_blank_string
   Chop trailing blanks - xdl_chop_blanks
   Number of digits in an integer - xdl_ndigit
   Convert a string to upper case - xdl_upc
   Convert a string to lower case - xdl_lwc
   Convert a character to upper case - xdl_upcc
   Convert a character to lower case - xdl_lwcc
   Random number, 0-32767 - xdl_rand16
   Get character size - xdl_ch_size
   Set a 64 level gray scale - xdl_set64gray
   Set a 64 level gray + yellow scale - xdl_set64gray_yel
   Set a 64 level colour scale - xdl_set64color
   Get a 64 level gray scale - xdl_get64gray
   Get a 64 level gray + yellow scale - xdl_get64gray_yel
   Get a 64 level colour scale - xdl_get64color
   Delete view-object children - xdl_delete_children
   See if a view-object has children - xdl_any_children
 
1.11.2 Get root x, y coordinates - xdl_rootxy
 
The routine xdl_rootxy is used to get the root window x, y coordinates from
the x, y coordinates within a given window.
 
'C' call:
 
void xdl_rootxy (wid, x, y, xroot, yroot)
 
 
Parameters:
 
Window wid;    /*The window id of the window to which x, y coordinates 
                 apply (R)*/
int x;         /*The x coordinate (R)*/
int y;         /*The y coordinate (R)*/
int *xroot;    /*Returns the x coordinate in the root window (W)*/
int *yroot;    /*Returns the y coordinate in the root window (W)*/

 
 
Return:  xroot, yroot via parameters list
 
 
1.11.3 Copy an output string - xdl_copy_chars
 
The routine xdl_copy_chars is  used  to  copy  an  output  string  from  an
XDL_VIEW view-object routine. The output string may be either  a  'c'  type
string which will be null terminated, or a 'fortran' type string which will
be padded with blanks if required but will have no terminating null.
 
'C' call:
 
void xdl_copy_chars (string_in, string_out, max_len)
 
 
Parameters:
 
char * string_in;    /*The string to be copied (must be null terminated) 
                       (R)*/
char * string_out;   /*The output string address for the copied string 
                       (W) */
int    max_len;      /*If >0 it is the maximum length allowed for the null
                             terminated copied string. string_out must be 
                             at least (max_len + 1) characters in length.
                       if <0 then up to abs(max_len) characters are copied 
                             to the output string. If the number of 
                             characters in the input string is less than 
                             this then the output string will be padded to 
                             abs(max_len) characters with blanks. (R) */
 
 
1.11.4 Test for a blank string - xdl_blank_string
 
The routine xdl_blank_string is used to test for a blank (/null)  character
string.
 
'C' call:
 
int xdl_blank_string (str)
 
 
Parameters:
 
char str[];   /*String to test (null terminated) (R)*/

 
 
Return:  =1 (true) blank or null string found,
         =0 not a blank/null string
 
 
1.11.5 Chop trailing blanks - xdl_chop_blanks
 
The routine xdl_chop_blanks is  used  to  remove  trailing  blanks  from  a
character string.
 
'C' call:
 
void xdl_chop_blanks (str)
 
 
Parameters:
 
char str[];   /*String from which trailing blanks are to be removed 
                (null terminated on input and output) (M)*/

 
 
1.11.6 Number of digits in an integer - xdl_ndigit
 
The routine xdl_ndigit finds the number of decimal  digits  in  an  integer
value.
 
'C' call:
 
int xdl_ndigit (i)
 
 
Parameters:
 
int i;     /*The integer value for which the number of digits is to 
             be found (R)*/

 
 
Return:  The number of digits.
 
 
1.11.7 Convert a string to upper case - xdl_upc
 
The routine xdl_upc is a machine independent routine to convert a character
string to upper case.
 
'C' call:
 
void xdl_upc (str)
 
 
Parameters:
 
char str[];    /*String to be converted to upper case 
                 (null terminated) (M)*/

 
 
1.11.8 Convert a string to lower case - xdl_lwc
 
The routine xdl_lwc is a machine independent routine to convert a character
string to lower case.
 
'C' call:
 
void xdl_lwc (str)
 
 
Parameters:
 
char str[];    /*String to be converted to lower case 
                 (null terminated) (M)*/

 
 
1.11.9 Convert a character to upper case - xdl_upcc
 
The routine  xdl_upcc  is  a  machine  independent  routine  to  convert  a
character to upper case.
 
'C' call:
 
void xdl_upcc (ch)
 
 
Parameters:
 
char *ch;    /*Pointer to character to be converted to upper case (M)*/

 
 
1.11.10 Convert a character to lower case - xdl_lwcc
 
The routine  xdl_lwcc  is  a  machine  independent  routine  to  convert  a
character to lower case.
 
'C' call:
 
void xdl_lwcc (ch)
 
 
Parameters:
 
char *ch;    /*Pointer to character to be converted to lower case (M)*/

 
 
1.11.11 Random number, 0-32767 - xdl_rand16
 
The routine xdl_rand16  is  a  machine  independent  routine  to  return  a
pseudo-random number in the range 0 to 32767. The seed may  be  reset  with
the routine xdl_srand16; its initial value is 1.
 
'C' call:
 
int xdl_rand16 ()
 
 
Parameters:
 
{
   xdl_next_seed = xdl_next_seed*1103515245 + 12345;
   return (unsigned int) (xdl_next_seed/65536)%32768;
}

/*
***************************
**      xdl_srand16      **
***************************

Purpose: Set new seed for random number routine xdl_rand16

Author:  John Campbell, July 1992 (from K&R)

*/

/*Doc:
Set seed for xdl_rand16 - xdl_srand16

The routine xdl_srand16 is used to reset the seed value for the pseudo-random
number routine xdl_rand16.
*/


void xdl_srand16 (seed)

unsigned int seed;  /* New seed value (R)*/

 
 
1.11.12 Get character size - xdl_ch_size
 
The routine xdl_ch_size is used to get the character size for  a  character
in one of the XDL_VIEW standard fonts; this may be for  a  normal  font,  a
bold font or the larger or smaller dimensions of the two.
 
'C' call:
 
void xdl_ch_size (font_type, opt, ch_width, ch_height, ascent, descent)
 
 
Parameters:
 
int font_type;     /* Font type (1 to 5) (R)*/
int opt;           /* = 0, normal font
                      = 1, bold font
                      = 2, larger dimensions of the normal/bold fonts
                      = 3, smaller dimensions of the normal/bold fonts
                      (R)*/
int *ch_width;     /* Returns the character width in pixels (W)*/
int *ch_height;    /* Returns the character height in pixels (W)*/
int *ascent;       /* Returns font ascent (W)*/
int *descent;      /* Returns font descent (W)*/

 
 
1.11.13 Set a 64 level gray scale - xdl_set64gray
 
The routine xdl_set64gray is used to set up a  64  level  gray  scale.  The
colorset must have been allocated when xdl_open_view  (xdlf_open_view)  was
called and must have at least 64 colorcells allocated.
 
'C' call:
 
int xdl_set64gray (cset, contrast_val, type)
 
 
Parameters:
 
int cset;         /* The colorset number (R)*/
int contrast_val; /* Contrast value from 1 to 1024 (R)*/
int type;         /* =1 high density = black, 
                     =2 high density = white (R)*/

 
 
Return:  1=OK, 0= colorset not allocated or has <64 cells or 
                  contast parameter out of range
 
 
1.11.14 Set a 64 level gray + yellow scale - xdl_set64gray_yel
 
The routine xdl_set64gray_yel is used to set up a 64 level gray scale  with
the top level gray being replaced by yellow. The colorset  must  have  been
allocated when xdl_open_view (xdlf_open_view) was called and must  have  at
least 64 colorcells allocated.
 
'C' call:
 
int xdl_set64gray_yel (cset, contrast_val, type)
 
 
Parameters:
 
int cset;         /* The colorset number (R)*/
int contrast_val; /* Contrast value from 1 to 1024 (R)*/
int type;         /* =1 high density = black, 
                     =2 high density = white (R)*/

 
 
Return:  1=OK, 0= colorset not allocated or has <64 cells 
                  or contrast parameter out of range
 
 
1.11.15 Set a 64 level colour scale - xdl_set64color
 
The routine xdl_set64color is used to set up a 64 level colour  scale.  The
colour   scale   is   blue..purple..red..orange..yellow   with   increasing
brightness or the same colour sequence in reverse order. The  routine.  The
colorset must have been allocated when xdl_open_view  (xdlf_open_view)  was
called and must have at least 64 colorcells allocated.
 
'C' call:
 
int xdl_set64color (cset, contrast_val, type)
 
 
Parameters:
 
int cset;         /* The colorset number (R)*/
int contrast_val; /* Contrast value from 1 to 1024 (R)*/
int type;         /* =1 high density at blue end of scale
                     =2 high density at yellow end of scale (R)*/

 
 
Return:  1=OK, 0= colorset not allocated or <64 cells 
                  or contrast parameter out of range
 
 
1.11.16 Get a 64 level gray scale - xdl_get64gray
 
The routine xdl_get64gray is used to get a 64 level gray scale. The nearest
colours available will be allocated.
 
'C' call:
 
int xdl_get64gray (pixels, contrast_val, type)
 
 
Parameters:
 
unsigned long pixels[64];         /* The returned pixels list (W)*/
int contrast_val;                 /* Contrast value from 1 to 1024 (R)*/
int type;                         /* =1 high density = black, 
                                     =2 high density = white (R)*/

 
 
Return:  1=OK, 0= contast parameter out of range
 
 
1.11.17 Get a 64 level gray + yellow scale - xdl_get64gray_yel
 
The routine xdl_get64gray_yel is used to get a 64 level gray scale with the
top level gray being replaced by yellow. The nearest available colours  are
allocated.
 
'C' call:
 
int xdl_get64gray_yel (pixels, contrast_val, type)
 
 
Parameters:
 
unsigned long pixels[64];         /* The returned pixels list (W)*/
int contrast_val;                 /* Contrast value from 1 to 1024 (R)*/
int type;                         /* =1 high density = black, 
                                     =2 high density = white (R)*/

 
 
Return:  1=OK, 0= contrast parameter out of range
 
 
1.11.18 Get a 64 level colour scale - xdl_get64color
 
The routine xdl_get64color is used to get a  64  level  colour  scale.  The
colour   scale   is   blue..purple..red..orange..yellow   with   increasing
brightness or the same  colour  sequence  in  reverse  order.  The  nearest
available colours are allocated.
 
'C' call:
 
int xdl_get64color (pixels, contrast_val, type)
 
 
Parameters:
 
unsigned long pixels[64];         /* The returned pixels list (W)*/
int contrast_val;                 /* Contrast value from 1 to 1024 (R)*/
int type;                         /* =1 high density at blue end of scale
                                     =2 high density at yellow end of scale 
                                        (R)*/

 
 
Return:  1=OK, 0= contrast parameter out of range
 
 
1.11.19 Delete view-object children - xdl_delete_children
 
The routine xdl_delete_children  is  used  to  delete  the  children  of  a
view-object. (Recursively)
 
'C' call:
 
void xdl_delete_children (vh_parent)
 
 
Parameters:
 
int vh_parent;           /* View-object handle of the parent (R) */

 
 
Return:  None
 
 
1.11.20 See if a view-object has children - xdl_any_children
 
The routine xdl_any_children is used to find whether or not  a  view-object
has any child view-objects.
 
'C' call:
 
int xdl_any_children (vh)
 
 
Parameters:
 
int vh;           /* View-object handle (R) */

 
 
Return:  =1 (true) child or children found, =0 no children;
 
 
 
CHAPTER 2: APPLICATION CALLABLE VIEW-OBJECT ROUTNES
===================================================
 

2.1 THE BASE FRAME VIEW-OBJECT ROUTINES
=======================================


2.1.1 INTRODUCTION
 
The base frame view-object is just an empty 'top  level'  window  on  which
other view-objects may be laid out. The window manager will usually  add  a
frame of some kind round such  a  window  and  its  exact  appearance  will
therefore depend  on  the  system  on  which  the  program  is  being  run.
Frequently the added frame will display a title which has been supplied  by
the application programmer. Any operations on the base frame  (e.g.  moving
it or resizing it) are functions of the particular window manager which  is
running.
 
The following sets of routines are available:
 
   Creating and Handling a Base Frame View-Object
 
2.1.2 CREATING AND HANDLING A BASE FRAME VIEW-OBJECT
 
2.1.2.1 Introduction
 
The following routines are available:
 
   Create a base frame view-object - xdl_base_frame
 
2.1.2.2 Create a base frame view-object - xdl_base_frame
 
The routine xdl_base_frame (xdlf_base_frame) is used to create a  new  base
frame view-object. The size of the frame is given  and  a  title  and  icon
label are supplied. A preferred  position  may  be  specified  if  required
though this is  just  a  request  to  the  window  manager  which  may  not
necesssarily be honoured.
 
Fortran call:
 
         CALL XDLF_BASE_FRAME (IVH, IWIDTH, IHEIGHT, XDLSTR(TITLE), 
        +                      ITLEN, ICON_LABL, ILEN, IX, IY)
 
 
Parameters:
 
IVH        (R)  View-object handle (see vh)
IWIDTH     (R)  Frame width (see width)
IHEIGHT    (R)  Frame height (see height)
TITLE      (R)  Fortran character string containing the title
                ** Pass address using the XDLSTR function **
                (cf title)
ITITL      (R)  The title length (> 0) (cf title_len)
ICON_LABL  (R)  Fortran character string containing the icon label
                ** Pass address using the XDLSTR function **
                (cf icon_label)
ILEN       (R) The icon label length (> 0) (cf icon_len)
IX         (R) The requested 'x' position on the root window
               for the frame (-1 allow window manager to choose)
               (see x)
IY         (R) The requested 'y' position c.f. IX
IY         (R) The requested 'y' position c.f. IX
 
 
'C' call:
 
void xdl_base_frame (vh, width, height, title, title_len, 
                     icon_label, icon_len, x, y)
 
 
Parameters:
 
int vh;             /* User selected view-object handle (R)*/
int width;          /* Frame width (including border width of 1 at each 
                       side but excluding any window manager additions) 
                       (R)*/
int height;         /* Frame height (including border width of 1 at top
                       and bottom but excluding any window manager 
                       additions) (R)*/
char * title;       /* Title string (R)*/
int title_len;      /* The length of the title string; if the string is
                       null terminated then 0 may be given and the program
                       will determine the string length (R)*/
char * icon_label;  /* Icon label string (R)*/
int icon_len;       /* The length of the icon label string; if the string 
                       is null terminated then 0 may be given and the 
                       program will determine the string length (R)*/
int x;              /* Requested root window 'x' position. This acts
                       as a hint to the window manager (if x=-1 and
                       y=-1 then the choice of position is left to
                       the window manager (R)*/
int y;              /* Requested root window 'y' position. c.f. 'x' (R)*/

 
 
Return:  None
 
 

2.2 THE MENU AREA VIEW-OBJECT ROUTINES
======================================


2.2.1 INTRODUCTION
 
The menu area view-object provides an area containing  a  menu  from  which
items may be selected by the user by means  of  the  mouse.  Typically,  an
application will use the same menu area for a series  of  different  menus.
The menu area has an optional title. It also has  an  optional  extra  menu
item situated below the other menu items and separated from them. This item
is typically used either as a 'Quit' item or as an item which will instruct
the program to return to the previously displayed menu. The menu area  also
has an 'active strip' at the top of the area.
 
The following sets of routines are available:
 
   Creating and Handling a Menu Area View-Object
 
2.2.2 CREATING AND HANDLING A MENU AREA VIEW-OBJECT
 
2.2.2.1 Introduction
 
The following routines are available:
 
   Create a menu area view-object - xdl_menu_area
   Set up a new menu - xdl_menu_area_setmenu
   Get the selected item number - xdl_menu_area_getitem
   Get position of selected item - xdl_menu_area_getrootxy
   Get menu area size requirements - xdl_menu_area_getsize
 
2.2.2.2 Create a menu area view-object - xdl_menu_area
 
The routine xdl_menu_area (xdlf_menu_area) is used to  create  a  new  menu
area view-object. The maximum lengths for  text  strings  and  the  maximum
number of items are give. The actual  menu  items  are  subsequently  added
using the xdl_menu_area_setmenu (xdlf_menu_area_setmenu) routine.
 
Fortran call:
 
         CALL XDLF_MENU_AREA (IVH, IVHPARENT, IX, IY, ICSET, MAXITEMS, 
        +                     MAXLEN, IFONT, IQUIT, MAXTITL, MINWIDTH, 
        +                     MINHEIGHT, IERR)
 
 
Parameters:
 
IVH       (R)   View-object handle (see vh)
IVHPARENT (R)   View-object handle for parent 0=none 
                (see vh_parent)
IX        (R)   X position (may be -1 if no parent) (see x)
IY        (R)   Y position (may be -1 if no parent) (see y)
ICSET     (R)   Colorset number (see cset)
MAXITEMS  (R)   Max. no. of menu items (see max_items)
MAXLEN    (R)   Max. no. chars in an item name 
                (see max_name_chars)
IFONT     (R)   Font type (1->5 verysmall->extralarge) 
                (see font_type)
IQUIT     (R)   =1 allow, =0 disallow quit box (see quit_box)
MAXTITL   (R)   Maximum title length (see max_title_len)
MINWIDTH  (R)   Minimum width or 0 (see min_width)
MINHEIGHT (R)   Minimum height or 0 (see min_height)
IERR      (W)   Returns status from xdl_menu_area call

 
 
'C' call:
 
int xdl_menu_area (vh, vh_parent, x, y, cset, max_items, max_name_chars, 
              font_type, quit_box, max_title_len, min_width, min_height)
 
 
Parameters:
 
int       vh;             /* User selected view-object handle (R)*/
int       vh_parent;      /* View-object handle for the parent view-object,
                             if 0 then a base frame is created to
                             enclose the menu area view-object (R)*/
int       x;              /* x coordinate for the view-object.
                             If no parent may be -1 to give default x (R)*/
int       y;              /* y coordinate for the view-object.
                             If no parent may be -1 to give default y (R)*/
int       cset;           /* Number of the colorset to be used - normally 0 
                             (R)*/
int       max_items;      /* Maximum number of possible items in the 
                             menu (R)*/
int       max_name_chars; /* Maximum number of characters in a menu item 
                             name string (R)*/
int       font_type;      /* Font type for menu items and title to be used 
                             in calculating the size requirements:
                             1 = very small 
                             1 = small
                             2 = medium
                             3 = large 
                             4 = extra-large (R)*/
int       quit_box;       /* = 1, Allow room for a menu 'quit/return' 
                             item box in addition to the max_items other 
                             menu items.
                             The string for the quit box must not exceed
                             max_name_chars in length; = 0, do not (R)*/
int       max_title_len;  /* Maximum length of the title string in 
                             characters; 0 if no title will be used (R)*/
int       min_width;      /* The minimum width for the Menu area 
                             view-object. This will be used only if it 
                             exceeds the width calculated from the details 
                             supplied above. If 0 then the calculated 
                             width will be used (R)*/
int       min_height;     /* The minimum height for the Menu area 
                             view-object. This will be used only if it 
                             exceeds the height calculated from the 
                             details supplied above. If 0 then the 
                             calculated height will be used (R)*/
 
 
Return:  Status flag =0 OK, >0 error
                bit 0 set: Requested parent not found in view-objects list
                bit 1 set: Unable to get memory for global data structure
                bit 2 set; Unable to get memory for 'text' array
                bit 3 set; Unable to get memory for menu item details array
                bit 4 set; Unable to get memory for copy of title
                bit 5 set; A required font not available
 
 
2.2.2.3 Set up a new menu - xdl_menu_area_setmenu
 
The routine xdl_menu_area_setmenu (xdlf_menu_area_setmenu) is used  to  set
an initial or new menu within a previously created menu  area  view-object.
The length of the text strings and the number of items must be  within  the
limits set for the menu area but the routine takes care of  the  layout  of
the items on the displayed menu.
 
Fortran call:
 
         CALL XDLF_MENU_AREA_SETMENU (IVH, NITEMS, XDLSTR(NAMES), NAMLEN, 
        +                          XDLSTR(TITLE), ITLEN, XDLSTR(QUITNAM),
        +                          IQLEN, IFONT, IERR)
 
 
Parameters:
 
IVH        (R)  View-object handle (see vh)
NITEMS     (R)  Number of menu items (see num_items)
NAMES      (R)  Fortran array of character strings containing
                the menu item names.
                [CHARACTER*NAMLEN NAMES(NITEMS)].
                ** Pass address using XDLSTR function **
                (see names) 
NAMLEN     (R)  Length of the menu item names character strings
                (Must be >0 cf name_len)
TITLE      (R)  Title character string (see title)
                ** Pass address using XDLSTR function **
ITLEN      (R)  Length of title string if > 0; -1 if no title 
                (cf title_len)
QUITNAM    (R)  Quit-box character string (see quit_name)
                ** Pass address using XDLSTR function **
IQLEN      (R)  Length of quit-box string if > 0; -1 if no 
                quit-box (cf quit_len)
IFONT      (R)  Font type (1 to 4 small to extralarge or 0 for 
                largest that there is room for) (see font_type)
IERR       (W)  Returns the status from xdl_menu_area_setmenu call
 
 
'C' call:
 
int xdl_menu_area_setmenu (vh, num_items, names, name_len, title, 
                           title_len, quit_name, quit_len, font_type)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int num_items;   /* No. of items in the menu (R)*/
char * names;    /* Item names - this may either an array of pointers to
                    num_items null terminated character strings 
                    (len_name=0) or a character string num_items*len_name
                    in length with each name occupying len_name characters 
                    (left justified and padded to the right with blanks 
                    if needed) (R)*/
int name_len;    /* Item name length (0 = array of pointers to 
                    null-terminated character strings (e.g. for 'C' 
                    programs) or the length of each name string 
                    (e.g. for Fortran programs). See also the previous 
                    item (R) */
char * title;    /* Title string (R)*/
int title_len;   /* If 0 then the length of the title string is 
                    determined assuming that 'title' is a null terminated
                    string; if > 0 it is the length of the title string; 
                    if = -1 then do not output a title ('title' ignored 
                    in this case) (R) */
char * quit_name;/* Quit box name string (R)*/
int quit_len;    /* If 0 then the length of the quit box string is 
                    determined assuming that 'quit_name' is a null 
                    terminated string; if > 0 it is the length of the 
                    title string; if = -1 then do not output a quit 
                    box ('quit_name' ignored in this case) (R) */
int font_type;   /* Font type: if 1-5, use very-small/small/medium/large/
                    extra-large font respectively if space permitting. 
                    (If not the the font size will be reduced till a
                    suitable one is found); if 0, use the largest
                    font which fits (R)*/

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.2.2.4 Get the selected item number - xdl_menu_area_getitem
 
The routine xdl_menu_area_getitem (xdlf_menu_area_getitem) returns the item
number of the last selected menu item. It will normally be called after the
return from a call to xdl_get_events  (xdlf_get_events)  indicates  that  a
menu_area view-object has returned input.
 
Fortran call:
 
         CALL XDLF_MENU_AREA_GETITEM (IVH, ITEM, IQUIT)
 
 
Parameters:
 
IVH    (R)  The view-object handle (see vh)
ITEM   (W)  Returns the menu item number (see item)
IQUIT  (W)  Returns 0 for normal item, 1 for quit box (see quit)
 
 
'C' call:
 
int xdl_menu_area_getitem (vh, item, quit)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int *item;       /* Returns the selected item number (W) */
int *quit;       /* Returns 0 for a normal item, 1 if quit box (W) */

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.2.2.5 Get position of selected item - xdl_menu_area_getrootxy
 
The routine  xdl_menu_area_getrootxy  (xdlf_menu_area_getrootxy)  gets  the
root x, y position of the last selected menu item; this is taken  as  being
half way up right hand side of the item box. It may be used for example  as
a focus for an error message if required. It will normally be called  after
a call to the routine xdl_menu_area_getitem (xdlf_menu_area_getitem).
 
Fortran call:
 
         CALL XDLF_MENU_AREA_GETROOTXY (IVH, IXROOT, IYROOT)
 
 
Parameters:
 
IVH    (R)  The view-object handle (see vh)
IXROOT (W)  Returns the root x position (see xroot)
IYROOT (W)  Returns the root y position (see yroot)
 
 
'C' call:
 
int xdl_menu_area_getrootxy (vh, xroot, yroot)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int *xroot;      /* Returns the x root position (half way up right hand
                    side of item box) of the last selected menu item) (W)*/
int *yroot;      /* Returns the y root position cf xroot (W)*/

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.2.2.6 Get menu area size requirements - xdl_menu_area_getsize
 
The  routine  xdl_menu_area_getsize  (xdlf_menu_area_getsize)  is  used  to
calculate the size requirements for  a  menu  area  based  on  the  maximum
lengths of text strings required and  the  maximum  number  of  menu  items
required.
 
Fortran call:
 
         CALL XDLF_MENU_AREA_GETSIZE (MAXITEMS, MAXNAM, IFONT, IQUIT,
        +                             MAXTITL, IWIDTH, IHEIGHT)
 
 
Parameters:
 
MAXITEMS   (R)  Max. no. of menu items (see max_items)
MAXNAM     (R)  Max. item name length (chars) 
                (see max_name_chars)
IFONT      (R)  Font type (1-4) (see font_type)
IQUIT      (R)  =1 allow quit box , =0 do not (see quit_box)
MAXTITL    (R)  Max. title length, 0 if no title 
                (see max_title_len)
IWIDTH     (W)  Returns the width required (see w)
IHEIGHT    (W)  Returns the height required (see h)
 
 
'C' call:
 
void xdl_menu_area_getsize (max_items, max_name_chars, font_type, 
                            quit_box, max_title_len, w, h)
 
 
Parameters:
 
int       max_items;      /* Maximum number of possible items in the 
                             menu (R)*/
int       max_name_chars; /* Maximum number of characters in a menu item 
                             name string (R)*/
int       quit_box;       /* = 1, Allow room for a menu 'quit/return' 
                             item box in addition to the max_items other 
                             menu items.
                             The string for the quit box must not exceed
                             max_name_chars in length; = 0, do not (R)*/
int       font_type;      /* Font type for menu items and title to be 
                             used in calculating the size requirements:
                             1 = very small font,
                             2 = small font,
                             3 = medium font,
                             4 = large font,
                             5 = extra-large font (R)*/
int       max_title_len;  /* Maximum length of the title string in 
                             characters; 0 if no title will be used (R)*/
int *w;                   /* Returns the width required (0 if font not 
                             found) (W)*/
int *h;                   /* Returns the height required (0 if font not 
                             found) (W)*/

 
 
Return:  None
 
 

2.3 THE PARAMETER TABLE VIEW-OBJECT ROUTINES
============================================


2.3.1 INTRODUCTION
 
The parameter table view-object provides an  area  containing  an  editable
table of parameter values. The parameter table has an optional  title.  The
table itself consists of one or more columns, each with a  number  of  rows
containing a parameter name and a parameter value. The parameter table  has
an 'active strip' at the top to indicate when the entries  may  be  edited.
When the program is prepared to service parameter  value  edits,  then  the
message 'Edits allowed' is displayed in the active strip.
 
In some cases, parameter values may be displayed as 'toggle' values.  These
are either a 'Yes/No' toggle or an 'On/Off' toggle.  The  toggle  value  is
displayed enclosed in a box. Label items with no values are  also  allowed;
these may be useful to group parameters under different headings.
 
A parameter table item may have a popup values menu associated with  it  to
enable the selection of a value from  a  predefined  list  of  values.  The
presence of a menu associated with a parameter  value  is  indicated  by  a
rectangle containing a downward pointing arrow positioned at the right hand
side of the value field. As an alternative, a step-button may be displayed;
this has two parts the upper right portion and the lower left portion which
may be selected to enable stepping forward or backward through a series  of
items (e.g. incrementing or decrementing a count); the actual action  taken
is under the control of the calling program. (For a given  parameter  item,
toggle values and a popup menu (or step-button) are mutually exclusive)
 
Sometimes, the  application  may  choose  to  emphasise  certain  items  by
displaying them in bold print,  perhaps  to  bring  particularly  important
items to the attention of the user. Also,  sometimes  the  application  may
choose to make some items 'silent'. These are effectively removed from  the
display and cannot be seen or modified until restored by the program.
 
If parameter values are too long to be displayed, then scrolling  may  take
place.
 
When a value is being input, text may be 'pasted in' from another window by
pressing the middle mouse button.
 
The following sets of routines are available:
 
   Creating and Handling a Parameter Table View-Object
 
2.3.2 CREATING AND HANDLING A PARAMETER TABLE VIEW-OBJECT
 
2.3.2.1 Introduction
 
The following routines are available:
 
   Create a parameter table view-object - xdl_param_table
   Get an input value string - xdl_param_table_getvalue
   Parameter table error handling - xdl_param_table_error
   Set a parameter table item - xdl_param_table_setitem
   Set a parameter value string - xdl_param_table_setvalue
   Set a parameter values menu - xdl_param_table_setmenu
   Set a parameter values button - xdl_param_table_setbutton
   Clear a parameter values menu - xdl_param_table_clrmenu
   Set item(s) to 'silent' - xdl_param_table_silent
   Set item(s) to 'normal' - xdl_param_table_normal
   Set item(s) to 'bold' - xdl_param_table_bold
   Reset all items to 'normal' - xdl_param_table_all_normal
   Delete a parameter table item - xdl_param_table_delitem
   Clear the parameter table - xdl_param_table_clearitems
   Output a new title - xdl_param_table_newtitle
   Calculate size requirements - xdl_param_table_getsize
 
2.3.2.2 Create a parameter table view-object - xdl_param_table
 
The routine xdl_param_table (xdlf_param_table) is  used  to  create  a  new
parameter table view-object. The requirements for the  table  such  as  the
numbers of rows and columns of items and the maximum lengths of  item  name
and value strings are given together with a title if required.  The  actual
items  are  set  individually  at  a  later   stage   using   for   example
xdl_param_table_setitem (xdlf_param_table_setitem).
 
Fortran call:
 
         CALL XDLF_PARAM_TABLE (IVH, IVHPARENT, IX, IY, ICSET, NCOLS, 
        +                       NROWS, LENNAM, LENVAL, MAXVAL,
        +                       XDLSTR(TITLE), 
        +                       ITLEN, IFONT, IMENU, IERR)
 
 
Parameters:
 
IVH       (R)   View-object handle (see vh)
IVHPARENT (R)   View-object handle for parent 0=none 
                (see vh_parent)
IX        (R)   X position (may be -1 if no parent) (see x)
IY        (R)   Y position (may be -1 if no parent) (see y)
ICSET     (R)   Colorset number (see cset)
NCOLS     (R)   Max. no. of cols of items (see num_cols)
NROWS     (R)   Max. no. rows of items (see num_rows)
LENNAM    (R)   Maximum parameter name length in characters (see
                max_name_chars)
LENVAL    (R)   Maximum length in characters of a parameter value
                string (displayed) (see max_value_disp)
MAXVAL    (R)   Maximum length of value which may be saved
                (if > lenval, then scrolling allowed) (see
                max_value_chars)
TITLE     (R)   Title string for the parameter table (see title)
                ** Pass address using the XDLSTR function **
ITLEN     (R)   The title length > 0 or -1 if no title required 
                (see nt)
IFONT     (R)   Font type (1->5 verysmall->extralarge) 
                (see font_type)
IMENU     (R)   = 1 Allow popup values menus and/or step-button, 
                = 0 do not.
IERR      (W)   Returns status from xdl_param_table call
 
 
'C' call:
 
int xdl_param_table (vh, vh_parent, x, y, cset, num_cols, num_rows, 
                     max_name_chars, max_value_disp, max_value_chars, 
                     title, nt, font_type, menus_allowed)
 
 
Parameters:
 
int       vh;             /* User selected view-object handle (R)*/
int       vh_parent;      /* View-object handle for the parent base frame,
                             if 0 then a base  level frame is created to
                             enclose the i/o window view-object (R)*/
int       x;              /* x coordinate for the view-object.
                             If no parent may be -1 to give default x (R)*/
int       y;              /* y coordinate for the view-object.
                             If no parent may be -1 to give default y (R)*/
int       cset;           /* Number of the colorset to be used - 
                             normally 0 (R)*/
int       num_cols;       /* Maximum number of columns of items in the 
                             parameter table (R)*/
int       num_rows;       /* Maximum number of rows of items in the 
                             parameter table (R)*/
int       max_name_chars; /* Maximum number of characters in a parameter 
                             name string (R)*/
int       max_value_disp; /* Maximum number of characters in a parameter
                             value string which may be displayed (R)*/
int       max_value_chars;/* Maximum number of characters in a parameter 
                             value string which may be stored (R)*/
char      *title;         /* Title string (R)*/
int       nt;             /* Length of title string; if 0 then length 
                             found assuming that 'title' is null 
                             terminated; if -1 then assume that no title 
                             is required (R)*/
int       font_type;      /* Font type (1-5) for very-small, small, medium,
                             large or extra-large font (R)*/
int       menus_allowed;  /* =1 if popup values menus and/or a step-buttons 
                                may be required,
                             =0 if no popup menus or step-buttons are to be 
                                used (R)*/
 
 
Return:  Status flag =0 OK, >0 error
                bit 0 set: Requested parent not found in view-objects list
                bit 1 set: Unable to get memory for global data structure
                bit 2 set; Unable to get memory for 'text' array
                bit 3 set; Unable to get memory for parameter details array
                bit 4 set; Unable to get memory for copy of title
 
 
2.3.2.3 Get an input value string - xdl_param_table_getvalue
 
The routine xdl_param_table_getvalue (xdlf_param_table_getvalue) is used to
return the new value string after a parameter value  has  been  edited.  It
will normally be called after the return  from  a  call  to  xdl_get_events
(xdlf_get_events) indicates that a parameter table view-object has returned
input. (If a step-button was selected, then the step-button string will  be
returned)
 
Fortran call:
 
         CALL XDLF_PARAM_TABLE_GETVALUE (IVH, ITEM, XDLSTR(STRING), 
        +                                MAXLEN, IERR)
 
 
Parameters:
 
IVH     (R)   View-object handle (see vh)
ITEM    (W)   Returned item number (see item)
STRING  (W)   Returned value character string (see string)
              ** Pass address using the XDLSTR function **
MAXLEN  (R)   Maximum allowed length for returned string ( > 0)
              (cf max_len)
IERR    (W)   Returned status from xdl_param_table_getvalue call
 
 
'C' call:
 
int xdl_param_table_getvalue (vh, item, string, max_len)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int *item;       /* Returns the parameter item number associated with
                    the input value string, 0 if none (W)*/
char string[];   /* Returned string (W)*/
int max_len;     /* If >0 Maximum length of returned string allowed 
                          (excluding terminating null - string must be 
                          at least max_len + 1 characters in length).
                    if <0 abs(max_len) characters will be returned padded
                          with blanks if needed (for 'fortran' use) (R)*/

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.3.2.4 Parameter table error handling - xdl_param_table_error
 
The  routine  xdl_param_table_error  (xdlf_param_table_error)  is  used  to
display an error notice (using a popup-notice) and  replace  the  parameter
value with the old value old value. It will normally be used after  a  call
to xdl_param_table_getvalue  (xdlf_param_table_getvalue)  if  the  returned
value  was  found  to  be  invalid.  (Note:  that  error  checking  is  the
responsibility of the  application  program;  the  parameter  table  merely
returns the string as input.
 
Fortran call:
 
         CALL XDLF_PARAM_TABLE_ERROR (IVH, ITEM, XDLSTR(ERRSTR), LEN, 
        +                             IERR)
 
 
Parameters:
 
IVH     (R)   View-object handle (see vh)
ITEM    (R)   Item number (see item)
ERRSTR  (R)   Error message character string (see errstr)
              ** Pass address using the XDLSTR function **
LEN     (R)   Length of the error string ( > 0 ) (see len)
IERR    (W)   Returned status from xdl_param_table_error call
 
 
'C' call:
 
int xdl_param_table_error (vh, item, errstr, len)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int item;        /* The item number (R) */
char errstr[];   /* The error message for the notice (R)*/
int len;         /* The length of the string; If 0 is given then the 
                    length will be determined assuming a null terminated 
                    string (R) */

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.3.2.5 Set a parameter table item - xdl_param_table_setitem
 
The routine xdl_param_table_setitem (xdlf_param_table_setitem) is  used  to
set a parameter name and value string in  a  parameter  table.  Items  with
toggle values may also be  set  using  this  routine.  Label  items  (items
without values) may also be set. Any value menus required are  subsequently
set using calls to xdlf_param_table_setmenu (xdl_param_table_setmnu) or any
step-buttons using xdlf_param_table_setbutton (xdl_param_table_setbutton).
 
Fortran call:
 
         CALL XDLF_PARAM_TABLE_SETITEM (IVH, ITEM, XDLSTR(NAME), LENNAM, 
        +                              XDLSTR(VALUE), LENVAL, ITOG, 
        +                              IEMPH, IERR)
 
 
Parameters:
 
IVH     (R)   View-object handle (see vh)
ITEM    (R)   Item number (see item)
NAME    (R)   Parameter name character string (see name)
              ** Pass address using the XDLSTR function **
LENNAM  (R)   Length of the name string ( > 0 ) (see len_name)
VALUE   (R)   Parameter value character string (see value)
              ** Pass address using the XDLSTR function **
LENVAL  (R)   Length of the value string ( > 0 ) (see len_value)
ITOG    (R)   Toggle type flag: 0 = normal value, 1,2 on/off 
              toggle, 3,4 yes/no toggle; =-1 Label item 
              (see toggle)
IEMPH   (R)   =0 normal print, =1 bold, =-1 silent (see emphasize)
IERR    (W)   Returned status from xdl_param_table_setitem call
 
 
'C' call:
 
int xdl_param_table_setitem (vh, item, name, len_name, value, 
                             len_value, toggle, emphasize)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int item;        /* Item number (R) */
char * name;     /* Parameter name string (R) */
int len_name;    /* Length of parameter name string; if 0 then
                    length will be found assuming a null terminated 
                    string (R) */
char * value;    /* Parameter value string (ignored for a toggle or label
                    item) (R) */
int len_value;   /* Length of parameter value string; if 0 then
                    length will be found assuming a null terminated 
                    string (ignored for a toggle item) (R) */
int toggle;      /* =0 normal item with a value, =1,2 on/off toggle 
                    (1=on by default, 2=off), =3,4 yes/no toggle 
                    (3=yes by default 4=no), =-1 label item. If toggle is
                     non-zero then the value string is ignored (R) */
int emphasize;   /* =0 normal print, =1 emphasized, =-1 'silent'. Silent
                    items will not appear in the table. They may be made
                    to appear by calling xdl_param_table_all_normal or
                    xdl_param_table_normal or xdl_param_table_bold (R) */

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.3.2.6 Set a parameter value string - xdl_param_table_setvalue
 
The routine xdl_param_table_setvalue (xdlf_param_table_setvalue) is used to
set or change the value string for a parameter item. A toggle value may  be
set if required or an item may be converted to a label item.  If  a  toggle
value is set, then any popup menu currently defined for the  item  will  be
removed.
 
Fortran call:
 
         CALL XDLF_PARAM_TABLE_SETVALUE (IVH, ITEM, XDLSTR(VALUE), 
        +                                LENVAL, ITOG, IERR)
 
 
Parameters:
 
IVH     (R)   View-object handle (see vh)
ITEM    (R)   Item number (see item)
VALUE   (R)   Parameter value character string (see value)
              ** Pass address using the XDLSTR function **
LENVAL  (R)   Length of the value string ( > 0 ) (see len_value)
ITOG    (R)   Toggle type flag: 0 = normal value, 1,2 on/off 
              toggle, 3,4 yes/no toggle, =-1 change item to
              a label item. (if not 0, value is ignored)
              (see toggle)
IERR    (W)   Returned status from xdl_param_table_setvalue call
 
 
'C' call:
 
int xdl_param_table_setvalue (vh, item, value, len_value, toggle)
 
 
Parameters:
 
int vh;          /* View-object handle (R) */
int item;        /* Item number (R) */
char * value;    /* Parameter value string (ignored if a toggle value set)
                    (R) */
int len_value;   /* Length of parameter value string; if 0 then
                    length will be found assuming a null terminated 
                    string (R) */
int toggle;      /* =0 normal item with a value, =1,2 on/off toggle 
                    (1=on, 2=off), =3,4 yes/no toggle (3=yes, 4=no),
                    =-1 convert to a label item. If toggle is
                    non-zero, then the value string is ignored (R)*/

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.3.2.7 Set a parameter values menu - xdl_param_table_setmenu
 
The routine xdl_param_table_setmenu (xdlf_param_table_setmenu) is  used  to
set or change a popup values menu for a parameter item. No menu will be set
if the parameter item has a toggle value though one is allowed for a  label
item.
 
Fortran call:
 
         CALL XDLF_PARAM_TABLE_SETMENU (IVH, ITEM, NVALS, 
        +                               XDLSTR(VALUES), LENV, IERR)
 
 
Parameters:
 
IVH     (R)   View-object handle (see vh)
ITEM    (R)   Parameter table item number (see item)
NVALS   (R)   Number of menu items in the menu (see num_menu_vals)
VALUES  (R)   Fortran array of character strings containing the
              menu item value strings.
              [CHARACTER*LENV VALUES(NVALS)].
              ** Pass address using XDLSTR function **
              (see values)
LENV    (R)   Length of the menu item value character strings
              (must be >0 cf len_vals)
IERR    (W)   Returned status from xdl_param_table_setmenu call
 
 
'C' call:
 
int xdl_param_table_setmenu (vh, item, num_menu_vals, values, len_vals)
 
 
Parameters:
 
int vh;            /* View-object handle (R) */
int item;          /* Item number (R) */
int num_menu_vals; /* Number of value strings in the menu (R)*/
char * values;     /* Value strings - this may either be an array of
                      pointers to num_menu_vals null terminated character
                      strings (len_vals=0) or a character string 
                      num_menu_vals*len_vals in length with each value
                      string occupying len_vals characters (left 
                      justified and padded to the right with blanks if 
                      needed. The strings must remain in place during the 
                      lifetime of the menu in the parameter table (i.e. 
                      until the menu is cleared or the parameter table 
                      deleted) as no copies are made of the strings (R)*/
int len_vals;      /* Values strings length (0 = array of pointers to
                      null terminated character strings (e.g. for 'C'
                      programs) or the length of each value string 
                      (e.g. for Fortran programs). See also the previous
                      item. (R) */
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set;  Parameter table not set up to allow menus
 
 
2.3.2.8 Set a parameter values button - xdl_param_table_setbutton
 
The routine xdl_param_table_setbutton (xdlf_param_table_setbutton) is  used
to set or change a step-button for a parameter item. The step-button allows
one of two value flags to be returned to the  calling  program  which  will
then adjust the parameter value.  It  is  intended  to  enable  forward  or
backward stepping through item values (e.g. incrementing or decrementing  a
count). No step-button will be set if the parameter item is a label or  has
a toggle value.
 
Fortran call:
 
         CALL XDLF_PARAM_TABLE_SETBUTTON (IVH, ITEM,
        +                               XDLSTR(VALUES), LENV, IERR)
 
 
Parameters:
 
IVH     (R)   View-object handle (see vh)
ITEM    (R)   Parameter table item number (see item)
VALUES  (R)   Fortran array of character strings containing the
              two step button values which may be returned to
              indicate which part of the step-button has been 
              selected (first=top right, 2'nd=bottom left)
              [CHARACTER*LENV VALUES(NVALS)].
              ** Pass address using XDLSTR function **
              (see values)
LENV    (R)   Length of the step-button item value character 
              strings (must be >0 cf len_vals)
IERR    (W)   Returned status from xdl_param_table_setbutton call
 
 
'C' call:
 
int xdl_param_table_setbutton (vh, item, values, len_vals)
 
 
Parameters:
 
int vh;            /* View-object handle (R) */
int item;          /* Item number (R) */
char * values;     /* Value strings - this may either be an array of
                      pointers to two null terminated character
                      strings (len_vals=0) or a character string 
                      2*len_vals in length with each value
                      string occupying len_vals characters (left 
                      justified and padded to the right with blanks if 
                      needed. The strings must remain in place during the 
                      lifetime of the button in the parameter table (i.e. 
                      until the button is cleared or the parameter table 
                      deleted) as no copies are made of the strings (R)*/
int len_vals;      /* Values strings length (0 = array of pointers to
                      null terminated character strings (e.g. for 'C'
                      programs) or the length of each value string 
                      (e.g. for Fortran programs). See also the previous
                      item. (R) */
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set;  Parameter table not set up to allow menus
 
 
2.3.2.9 Clear a parameter values menu - xdl_param_table_clrmenu
 
The routine xdl_param_table_clrmenu (xdlf_param_table_clrmenu) is  used  to
clear (i.e. remove) a popup values menu (or button) for a parameter item.
 
Fortran call:
 
         CALL XDLF_PARAM_TABLE_CLRMENU (IVH, ITEM, IERR)
 
 
Parameters:
 
IVH     (R)   View-object handle (see vh)
ITEM    (R)   Parameter table item number (see item)
IERR    (W)   Returned status from xdl_param_table_clrmenu call
 
 
'C' call:
 
int xdl_param_table_clrmenu (vh, item)
 
 
Parameters:
 
int vh;            /* View-object handle (R) */
int item;          /* Item number (R) */

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.3.2.10 Set item(s) to 'silent' - xdl_param_table_silent
 
The routine xdl_param_table_silent  (xdlf_param_table_silent)  is  used  to
reset the text_emphasis mode for one  or  more  parameter  table  items  to
'silent' mode. These items will no longer be displayed and cannot be edited
whilst in this mode. However the parameter item name and  value  are  still
stored  and  the  item  may  be  reinstated  using  one  of  the  routines:
xdl_param_table_normal   (xdlf_param_table_normal),    xdl_param_table_bold
(xdlf_param_table_bold)            or            xdl_param_table_all_normal
(xdlf_param_table_all_normal).
 
Fortran call:
 
         CALL XDLF_PARAM_TABLE_SILENT (IVH, NITEMS, ITEMS, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
NITEMS   (R)  Number of items to set (see num_items)
ITEMS    (R)  Integer array of NITEMS item numbers (see items)
IERR     (W)  Returns status from xdl_param_table_silent call
 
 
'C' call:
 
int xdl_param_table_silent (vh, num_items, items)
 
 
Parameters:
 
int vh;          /* View-object handle (R) */
int num_items;   /* Number of items to be set (R) */
int items[];     /* Array of the num_items item numbers to be set (R) */

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.3.2.11 Set item(s) to 'normal' - xdl_param_table_normal
 
The routine xdl_param_table_normal  (xdlf_param_table_normal)  is  used  to
reset the text_emphasis mode for one  or  more  parameter  table  items  to
'normal' mode.
 
Fortran call:
 
         CALL XDLF_PARAM_TABLE_NORMAL (IVH, NITEMS, ITEMS, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
NITEMS   (R)  Number of items to set (see num_items)
ITEMS    (R)  Integer array of NITEMS item numbers (see items)
IERR     (W)  Returns status from xdl_param_table_normal call
 
 
'C' call:
 
int xdl_param_table_normal (vh, num_items, items)
 
 
Parameters:
 
int vh;          /* View-object handle (R) */
int num_items;   /* Number of items to be set (R) */
int items[];     /* Array of the num_items item numbers to be set (R) */
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.3.2.12 Set item(s) to 'bold' - xdl_param_table_bold
 
The routine xdl_param_table_bold (xdlf_param_table_bold) is used  to  reset
the text_emphasis mode for one or more  parameter  table  items  to  'bold'
mode. These items are the same as 'normal' items except that the text is in
bold print.
 
Fortran call:
 
         CALL XDLF_PARAM_TABLE_BOLD (IVH, NITEMS, ITEMS, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
NITEMS   (R)  Number of items to set (see num_items)
ITEMS    (R)  Integer array of NITEMS item numbers (see items)
IERR     (W)  Returns status from xdl_param_table_bold call
 
 
'C' call:
 
int xdl_param_table_bold (vh, num_items, items)
 
 
Parameters:
 
int vh;          /* View-object handle (R) */
int num_items;   /* Number of items to be set (R) */
int items[];     /* Array of the num_items item numbers to be set (R) */

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.3.2.13 Reset all items to 'normal' - xdl_param_table_all_normal
 
The  routine  xdl_param_table_all_normal  (xdlf_param_table_all_normal)  is
used to reset the text_emphasis mode for all the parameter table  items  to
'normal' mode.
 
Fortran call:
 
         CALL XDLF_PARAM_TABLE_ALL_NORMAL (IVH, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
IERR     (W)  Returns status from xdl_param_table_all_normal call
 
 
'C' call:
 
int xdl_param_table_all_normal (vh)
 
 
Parameters:
 
int vh;          /* View-object handle (R) */

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.3.2.14 Delete a parameter table item - xdl_param_table_delitem
 
The routine xdl_param_table_delitem (xdlf_param_table_delitem) is  used  to
delete (remove) a parameter item from the parameter table. The position  in
the table may subsequently be used for another item if required.
 
Fortran call:
 
         CALL XDLF_PARAM_TABLE_DELITEM (IVH, ITEM, IERR)
 
 
Parameters:
 
IVH     (R)   View-object handle (see vh)
ITEM    (R)   Item number (see item)
IERR    (W)   Returned status from xdl_param_table_delitem call
 
 
'C' call:
 
int xdl_param_table_delitem (vh, item)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int item;        /* Item number (R) */

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.3.2.15 Clear the parameter table - xdl_param_table_clearitems
 
The  routine  xdl_param_table_clearitems  (xdlf_param_table_clearitems)  is
used to clear all parameter items from the parameter table. New  items  may
subsequently be set up if required.
 
Fortran call:
 
         CALL XDLF_PARAM_TABLE_CLEARITEMS (IVH, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
IERR     (W)  Returns status from xdl_param_table_clearitems call
 
 
'C' call:
 
int xdl_param_table_clearitems (vh)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.3.2.16 Output a new title - xdl_param_table_newtitle
 
The routine xdl_param_table_newtitle (xdlf_param_table_newtitle) is used to
output a new title for the  parameter  table.  Note  that  a  title  string
(possibly  blank)  must  have  been  specified  when  the  parameter  table
view-object was created and the size of the view-object may depend on  this
original title length. Thus if a longer title is to be output  at  a  later
stage, it would be wise to create the view-object with a  title  string  of
the maximum length required; this could be blank and then reset using  this
new title routine if desired. If the new title string is too long  for  the
space available, it will be truncated.
 
Fortran call:
 
         CALL XDLF_PARAM_TABLE_NEWTITLE (IVH, XDLSTR(TITLE), 
        +                                ITLEN, IERR)
 
 
Parameters:
 
IVH       (R)   View-object handle (see vh)
TITLE     (R)   Title string for the parameter table (see title)
                ** Pass address using the XDLSTR function **
ITLEN     (R)   The title length (> 0) 
IERR      (W)   Returned status from xdl_param_table_newtitle call
 
 
'C' call:
 
int xdl_param_table_newtitle (vh, title, nt)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
char *title;     /* Title string (R)*/
int nt;          /* Length of title string; if 0 then length 
                    found assuming that 'title' is null 
                    terminated (R)*/
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set:  cannot allocate memory for title
 
 
2.3.2.17 Calculate size requirements - xdl_param_table_getsize
 
The routine xdl_param_table_getsize (xdlf_param_table_getsize) is  used  to
get the required size of a parameter table view-object given  the  required
number of rows and columns of items and maximum lengths of  item  name  and
value strings.
 
Fortran call:
 
         CALL XDLF_PARAM_TABLE_GETSIZE (NCOLS, NROWS, MAXNAM, MAXVDISP, 
     +                               NT, IFONT, IMENU, IWIDTH, IHEIGHT)
 
 
Parameters:
 
NCOLS      (R)  No. of columns of parameters (see num_cols)
NROWS      (R)  No. of rows of parameters (see num_rows)
MAXNAM     (R)  Maximum parameter name length (chars) 
                (see max_name_chars)
MAXVDISP   (R)  Maximum value string length which may be displayed
                (chars) (see max_value_disp)
NT         (R)  >=0 title present; =-1 no title (see nt)
IFONT      (R)  Font type 1-4 (see font_type)
IMENU      (R)  =1 popup values menus allowed, =0 not 
                (see menus_allowed)
IWIDTH     (W)  Returns the width required (see w)
IHEIGHT    (W)  Returns the height required (see h)
 
 
'C' call:
 
void xdl_param_table_getsize (num_cols, num_rows, max_name_chars,
                              max_value_disp, nt, font_type, 
                              menus_allowed, w, h)
 
 
Parameters:
 
int       num_cols;       /* Maximum number of columns of items in the 
                             parameter table (R)*/
int       num_rows;       /* Maximum number of rows of items in the 
                             parameter table (R)*/
int       max_name_chars; /* Maximum number of characters in a parameter 
                             name string (R)*/
int       max_value_disp; /* Maximum number of characters in a parameter 
                             value string which may be displayed (R)*/
int       nt;             /* >=0 title present; =-1 no title (R)*/
int       font_type;      /* Font type (1-5) for very_small, small, medium,
                             large or extra-large font. (R)*/
int       menus_allowed;  /* =1 popup values menus allowed, =0 not (R)*/
int *w;                   /* Returns the width required (W)*/
int *h;                   /* Returns the height required (W)*/

 
 
Return:  None
 
 

2.4 THE I/O WINDOW VIEW-OBJECT ROUTINES
=======================================


2.4.1 INTRODUCTION
 
The I/O window view-object provides an area for the output of text from the
program and input of text strings by the user when  required  (e.g.  for  a
question and answer sequence). The I/O window has an 'active strip' at  the
top to indicate whether or not the program is waiting for a reply string to
be input by the user. When the program  is  waiting  for  input,  then  the
message 'Input reply'  is  displayed  in  the  active  strip.  Options  are
available for text editing, selecting/pasting, command  recall  and  window
scrolling.
 
The following sets of routines are available:
 
   Creating and Handling an I/O Window View-Object
 
2.4.2 CREATING AND HANDLING AN I/O WINDOW VIEW-OBJECT
 
2.4.2.1 Introduction
 
The following routines are available:
 
   Create an I/O window view-object - xdl_io_window
   Output a text string - xdl_io_window_print
   Get an input text string - xdl_io_window_getstring
   Reset active strip message - xdl_io_window_input_message
   Set keyboard focus - xdl_io_window_set_focus
   Get a root window position - xdl_io_window_rootxy
   Calculate size requirements - xdl_io_window_getsize
 
2.4.2.2 Create an I/O window view-object - xdl_io_window
 
The routine xdl_io_window (xdlf_io_window) is used  to  create  a  new  I/O
window view-object. The user may specify the size of the window  in  pixels
or in terms of the required numbers of rows and columns of characters.
 
Fortran call:
 
         CALL XDLF_IO_WINDOW (IVH, IVHPARENT, IX, IY, ICSET, NCOLS, 
        +                     NROWS, MINW, MINH, IFONT, NSCROLL, IERR)
 
 
Parameters:
 
IVH       (R)   View-object handle (see vh)
IVHPARENT (R)   View-object handle for parent 0=none 
                (see vh_parent)
IX        (R)   X position (may be -1 if no parent) (see x)
IY        (R)   Y position (may be -1 if no parent) (see y)
ICSET     (R)   Colorset number (see cset)
NCOLS     (R)   No. of cols of characters or 0 (see ncols)
NROWS     (R)   No. of rows of characters or 0 (see nrows)
MINW      (R)   Minimum width in pixels (see min_width)
MINH      (R)   Minimum height in pixels (see min_height)
IFONT     (R)   Font type (1->5 very-small->extra-large) 
                (see font_type)
NSCROLL   (R)   The number of pages (of nrows lines) to be
                saved for scrolling option (0 if no scrolling)
IERR      (W)   Returns status from xdl_io_window call
 
 
'C' call:
 
int xdl_io_window (vh, vh_parent, x, y, cset, ncols, nrows, min_width, 
                   min_height, font_type, nscroll)
 
 
Parameters:
 
int       vh;             /* User selected view-object handle (R)*/
int       vh_parent;      /* View-object handle for the parent base frame, 
                             if 0 then a base  level frame is created to
                             enclose the i/o window view-object (R)*/
int       x;              /* x coordinate for the view-object.
                             If no parent may be -1 to give default x (R)*/
int       y;              /* y coordinate for the view-object.
                             If no parent may be -1 to give default y (R)*/
int       cset;           /* Number of the colorset to be used - 
                             normally 0 (R)*/
int       ncols;          /* Number of columns of characters (if 0 then
                             this will be calculated from min_width which
                             must then be given a value > 0. (R)*/
int       nrows;          /* Number of rows of characters (if 0 then
                             this will be calculated from min_height which
                             must then be given a value > 0. (R)*/
int       min_width;      /* Minimum window width in pixels. If this is
                             greater than the width calculated from the
                             number of character columns requirement then 
                             this value will be used as the window width 
                             (R)*/
int       min_height;     /* Minimum window height in pixels. If this is
                             greater than the height calculated from the
                             number of character rows requirement then 
                             this value will be used as the window height
                             (R)*/
int       font_type;      /* Font type (1-5) for very_small, small, medium,
                             large or extra-large font. (R)*/
int       nscroll;        /* No. of pages which may be back scrolled;
                             0 if no scrolling */
 
 
Return:  Status flag =0 OK, >0 error
                bit 0 set: Requested parent not found in view-objects list
                bit 1 set: Memory allocation error
 
 
2.4.2.3 Output a text string - xdl_io_window_print
 
The routine xdl_io_window_print (xdlf_io_window_print) is used to output  a
text string to an I/O window view object. The string for the C routine  may
contain newline characters and the Fortran routine has options for newlines
at the start and/or end of the string.
 
Fortran call:
 
         CALL XDLF_IO_WINDOW_PRINT (IVH, XDLSTR(STRING), LEN, NEWLIN, 
        +                           IERR)
 
 
Parameters:
 
IVH     (R)  View-object handle (see vh)
STRING  (R)  The string to be printed (see string)
             ** Pass the address using the XDLSTR function **
LEN     (R)  Length of the string (>0) (cf len_str)
NEWLIN  (R)  =0 no newlines, =1 newline before printing the 
                string,
             =2 newline after printing the string, =3 newlines
             before and after printing the string
IERR    (W)  Returns the status from xdl_io_window_print call
 
 
'C' call:
 
int xdl_io_window_print (vh, string, len_str)
 
 
Parameters:
 
int vh;               /* The xdl_io_window view-object handle (R)*/
char string[];        /* The string to be printed 
                         Note: \f, \r and \v will all be treated as \n
                               (newline)
                               \b is ignored
                               \t (tab) is converted to  a space
                         (R)*/
int len_str;          /* The length of the string. If the string is null
                         terminated, then 0 may be given and the length
                         of the string will then be determined by the
                         routine (R)*/

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.4.2.4 Get an input text string - xdl_io_window_getstring
 
The routine xdl_io_window_getstring (xdlf_io_window_getstring) is  used  to
return an input text string. It will normally be called  after  the  return
from a call to  xdl_get_events  (xdlf_get_events)  indicates  that  an  I/O
window view-object has returned input.
 
Fortran call:
 
         CALL XDLF_IO_WINDOW_GETSTRING (IVH, XDLSTR(STRING), MAXLEN, 
        +                               IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
STRING   (W)  Returned string (see string)
              ** Pass address using the XDLSTR function **
MAXLEN   (R)  Maximum allowed length for the returned string 
              ( > 0) (cf max_len)
IERR     (W)  Returns status from xdl_io_window_getstring call
 
 
'C' call:
 
int xdl_io_window_getstring (vh, string, max_len)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
char string[];   /* Returned string (W)*/
int max_len;     /* if >0 Maximum length of returned string allowed 
                          (excluding terminating null - string must be 
                          at least max_len + 1 characters in length)
                    if <0 abs(max_len) characters will be returned padded 
                          with blanks if needed (for 'fortran' use) (R)*/
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.4.2.5 Reset active strip message - xdl_io_window_input_message
 
The routine xdl_io_window_input_message  (xdlf_io_window_input_message)  is
used to reset the message which will appear in the active strip when  input
is requested When the  I/O  window  view-object  is  created,  the  default
message is 'Input reply'.
 
Fortran call:
 
         CALL XDLF_IO_WINDOW_INPUT_MESSAGE (IVH, XDLSTR(MESSAGE), 
        +                                    LEN, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
MESSAGE  (R)  Character string containing the message 
              (see message)
              ** Pass address using the XDLSTR function **
LEN      (R)  Length of the message string - must be >0 
              (cf len) (max 60 chars) 
IERR     (W)  Returns status from xdl_io_window_input_message 
              call
 
 
'C' call:
 
int xdl_io_window_input_message (vh, message, len)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
char *message;   /* Message string (max of 60 chars long) (R)*/
int len;         /* Length of the message string; if 0 then length 
                    will be found assuming a null terminated string 
                    (R)*/

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.4.2.6 Set keyboard focus - xdl_io_window_set_focus
 
The routine xdl_io_window_set_focus (xdlf_io_window_set_focus) is  used  to
reset the keyboard focus to the i/o window. If the window is not  currently
viewable, an attempt will  be  made  again  after  a  requested  number  of
milliseconds and this will be repeated if needed up to a maximum  requested
number of times. This procedure may be needed, for example, if  a  new  i/o
window view-object has just been created.
 
Fortran call:
 
         CALL XDLF_IO_WINDOW_SET_FOCUS (IVH, MSEC, NTRY, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
MSEC     (R)  If window not currently visable, retry after 'MSEC' 
              milliseconds
NTRY     (R)  Maximum no. of retries to attempt.
IERR     (W)  Returns status from xdl_io_window_set_focus call
 
 
'C' call:
 
int xdl_io_window_set_focus (vh, msec, ntry)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int msec;        /* If window not currently visable, retry after  
                    'msec' milliseconds (R)*/
int ntry;        /* Maximum no. of retries to attempt (R)*/
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.4.2.7 Get a root window position - xdl_io_window_rootxy
 
The  routine  xdl_io_window_rootxy  (xdlf_io_windowrootxy)  gets  the  root
window x, y position at the right hand side of the io_window  on  the  line
above the one currently containing the cursor. It is basically intended  to
be used as a position for an error  message  popup-notice  if  the  program
finds some kind of error in an input text string.
 
Fortran call:
 
         CALL XDLF_IO_WINDOW_ROOTXY (IVH, IXROOT, IYROOT, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
IXROOT   (W)  Returns the required x root position (see xroot)
IYROOT   (W)  Returns the required y root position (see yroot)
IERR     (W)  Returns status from xdl_io_window_rootxy call
 
 
'C' call:
 
int xdl_io_window_rootxy (vh, xroot, yroot)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int *xroot;      /* Returns the required xroot position e.g for use with
                    an error notice after the input of an incorrect string
                    (W)*/
int *yroot;      /* Returns the required yroot position (W)*/
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.4.2.8 Calculate size requirements - xdl_io_window_getsize
 
The routine xdl_io_window_getsize (xdlf_io_window_getsize) is used  to  get
the required size for an I/O window view-object given the numbers  of  rows
and columns of characters required.
 
Fortran call:
 
         CALL XDLF_IO_WINDOW_GETSIZE (NCOLS, NROWS, IFONT, NSCROLL, IWIDTH, 
        +                             IHEIGHT)
 
 
Parameters:
 
NCOLS     (R)   No. of cols of characters or 0 (see ncols)
NROWS     (R)   No. of rows of characters or 0 (see nrows)
IFONT     (R)   Font type (1->5 very-small->extra-large) 
                (see font_type)
NSCROLL   (R)   No. of scrolling pages or 0 if no scrolling;
                (any value >0 has the same effect)
IWIDTH    (W)   Returns the width required (see w)
IHEIGHT   (W)   Returns the height required (see h)
 
 
'C' call:
 
void xdl_io_window_getsize (ncols, nrows, font_type, nscroll, w, h)
 
 
Parameters:
 
int       ncols;          /* Number of columns of characters ( > 0 ) (R)*/
int       nrows;          /* Number of rows of characters ( > 0 ) (R)*/
int       font_type;      /* Font type (1-5) for very-small, small, medium,
                             large or extra-large font. (R)*/
int       nscroll;        /* No. of scrolling pages to save */
int *w;                   /* Returns the width required (W)*/
int *h;                   /* Returns the height required (W)*/

 
 
Return:  None
 
 

2.5 THE TEXT TABLE VIEW-OBJECT ROUTINES
=======================================


2.5.1 INTRODUCTION
 
The text table view-object provides an area for the simple output  of  text
from a program. Text strings may be output at any character position within
the window. There is no scrolling. An alternative  option  allows  for  the
definition of active cells which respond to mouse input.
 
The following sets of routines are available:
 
   Creating and Handling a Text Table View-Object
 
2.5.2 CREATING AND HANDLING A TEXT TABLE VIEW-OBJECT
 
2.5.2.1 Introduction
 
The following routines are available:
 
   Create a text table view-object - xdl_text_table
   Create a text cell view-object - xdl_text_table_cell
   Output a text string - xdl_text_table_text
   Output a symbol - xdl_text_table_symbol
   Clear the text table - xdl_text_table_clear
   Clear a section - xdl_text_table_clearsect
   Reset active strip message - xdl_text_table_input_message
   Define an input cell - xdl_text_table_define_cell
   Clear input cell(s) - xdl_text_table_clear_cell
   Get selected input cell number - xdl_text_table_getinp
   Calculate size requirements - xdl_text_table_getsize
   Calculate cell text size  - xdl_text_table_getcsize
 
2.5.2.2 Create a text table view-object - xdl_text_table
 
The routine xdl_text_table (xdlf_text_table) is used to create a  new  text
table window view-object. The user may specify the size of  the  window  in
pixels or in  terms  of  the  required  numbers  of  rows  and  columns  of
characters.
 
Fortran call:
 
         CALL XDLF_TEXT_TABLE (IVH, IVHPARENT, IX, IY, ICSET, NCOLS, 
        +                      NROWS, MINW, MINH, IFONT, IERR)
 
 
Parameters:
 
IVH       (R)   View-object handle (see vh)
IVHPARENT (R)   View-object handle for parent 0=none 
                (see vh_parent)
IX        (R)   X position (may be -1 if no parent) (see x)
IY        (R)   Y position (may be -1 if no parent) (see y)
ICSET     (R)   Colorset number (see cset)
NCOLS     (R)   No. of cols of characters or 0 (see ncols)
NROWS     (R)   No. of rows of characters or 0 (see nrows)
MINW      (R)   Minimum width in pixels (see min_width)
MINH      (R)   Minimum height in pixels (see min_height)
IFONT     (R)   Font type (1->5 very-small->extra-large) 
                (see font_type)
IERR      (W)   Returns status from xdl_text_table call
 
 
'C' call:
 
int xdl_text_table (vh, vh_parent, x, y, cset, ncols, nrows, min_width, 
                   min_height, font_type)
 
 
Parameters:
 
int       vh;             /* User selected view-object handle (R)*/
int       vh_parent;      /* View-object handle for the parent base frame, 
                             if 0 then a base  level frame is created to
                             enclose the i/o window view-object (R)*/
int       x;              /* x coordinate for the view-object.
                             If no parent may be -1 to give default x (R)*/
int       y;              /* y coordinate for the view-object.
                             If no parent may be -1 to give default y (R)*/
int       cset;           /* Number of the colorset to be used - 
                             normally 0 (R)*/
int       ncols;          /* Number of columns of characters (if 0 then
                             this will be calculated from min_width which
                             must then be given a value > 0. (R)*/
int       nrows;          /* Number of rows of characters (if 0 then
                             this will be calculated from min_height which
                             must then be given a value > 0. (R)*/
int       min_width;      /* Minimum window width in pixels. If this is
                             greater than the width calculated from the
                             number of character columns requirement then 
                             this value will be used as the window width 
                             (R)*/
int       min_height;     /* Minimum window height in pixels. If this is
                             greater than the height calculated from the
                             number of character rows requirement then 
                             this value will be used as the window height
                             (R)*/
int       font_type;      /* Font type (1-5) for very_small, small, medium,
                             large or extra-large font. (R)*/
 
 
Return:  Status flag =0 OK, >0 error
                bit 0 set: Requested parent not found in view-objects list
                bit 1 set: Unable to allocate required memory
 
 
2.5.2.3 Create a text cell view-object - xdl_text_table_cell
 
The routine xdl_text_table_cell (xdlf_text_table_cell) is used to create  a
new text table window view-object.  In  contrast  with  the  standard  text
table, the user may define active cells within the window which respond  to
mouse input. An active strip may be displayed if  required.  The  user  may
specify the size of the window in  pixels  or  in  terms  of  the  required
numbers of rows and columns of characters.
 
Fortran call:
 
         CALL XDLF_TEXT_TABLE_CELL (IVH, IVHPARENT, IX, IY, ICSET, IACT, 
        +                MAX_CELLS, NCOLS, NROWS, MINW, MINH, IFONT, 
        +                HIGHL_FN, IERR)
 
 
Parameters:
 
IVH       (R)   View-object handle (see vh)
IVHPARENT (R)   View-object handle for parent 0=none 
                (see vh_parent)
IX        (R)   X position (may be -1 if no parent) (see x)
IY        (R)   Y position (may be -1 if no parent) (see y)
ICSET     (R)   Colorset number (see cset)
IACT      (R)   Display active strip flag =1 yes, =0 no
MAX_CELLS (R)   Maximum no. of input cells needed (0 if none)
NCOLS     (R)   No. of cols of characters or 0 (see ncols)
NROWS     (R)   No. of rows of characters or 0 (see nrows)
MINW      (R)   Minimum width in pixels (see min_width)
MINH      (R)   Minimum height in pixels (see min_height)
IFONT     (R)   Font type (1->5 very-small->extra-large) 
                (see font_type)
HIGHL_FN  (R)   Subroutine to call when highlighting/unhighlighting 
                takes place in a cell to allow additional user defined
                actions to be carried out.
                
                Call wiil be:    CALL HIGHL_FN (IVH, ICELL, IFLAG)

                Parameters:   IVH    (R)     The file handle
                              ICELL  (R)     The cell number
                              IFLAG  (R)     Flag =1 highlight on 
                                                  =0 highlight off
                Note: Will still be called when not in input selection 
                      mode even if the highlight option selected for this 
                      mode via CALL XDLF_TEXT_TABLE_DEFINE_CELL is 0.

IERR      (W)   Returns status from xdl_text_table call
 
 
'C' call:
 
int xdl_text_table_cell (vh, vh_parent, x, y, cset, iact, max_cells,
                         ncols, nrows, min_width, min_height, font_type,
                         highl_fn)
 
 
Parameters:
 
int       vh;             /* User selected view-object handle (R)*/
int       vh_parent;      /* View-object handle for the parent base frame, 
                             if 0 then a base  level frame is created to
                             enclose the i/o window view-object (R)*/
int       x;              /* x coordinate for the view-object.
                             If no parent may be -1 to give default x (R)*/
int       y;              /* y coordinate for the view-object.
                             If no parent may be -1 to give default y (R)*/
int       cset;           /* Number of the colorset to be used - 
                             normally 0 (R)*/
int       iact;           /* =1 active strip, =0 no active strip (R)*/
int       max_cells;      /* Maximum no. of cells allowed (R)*/
int       ncols;          /* Number of columns of characters (if 0 then
                             this will be calculated from min_width which
                             must then be given a value > 0. (R)*/
int       nrows;          /* Number of rows of characters (if 0 then
                             this will be calculated from min_height which
                             must then be given a value > 0. (R)*/
int       min_width;      /* Minimum window width in pixels. If this is
                             greater than the width calculated from the
                             number of character columns requirement then 
                             this value will be used as the window width 
                             (R)*/
int       min_height;     /* Minimum window height in pixels. If this is
                             greater than the height calculated from the
                             number of character rows requirement then 
                             this value will be used as the window height
                             (R)*/
int       font_type;      /* Font type (1-5) for very_small, small, medium,
                             large or extra-large font. (R)*/
void (*highl_fn)();       /*  Function to call when highlighting or 
                              unhighlighting takes place in a cell to allow 
                              additional user define actions to be carried 
                              out. (May be a NULL function)
                
                              Call:  highl_fn (ivh, icell, iflag)

                Parameters:   int *ivh       The file handle (R)
                              int *icell     The cell number (R)
                              int *iflag     Flag =1 highlight on 
                                                  =0 highlight off 

                              Pointers used for parameters to allow
                              for Fortran case.

                Note: Will still be called when not in input selection 
                      mode even if the highlight option selected for this 
                      mode via CALL XDLF_TEXT_TABLE_DEFINE_CELL is 0.
                              (R)*/     
 
 
Return:  Status flag =0 OK, >0 error
                bit 0 set: Requested parent not found in view-objects list
                bit 1 set: Unable to allocate required memory
 
 
2.5.2.4 Output a text string - xdl_text_table_text
 
The routine xdl_text_table_text (xdlf_text_table_text) is used to output  a
text string to a text table view object.
 
Fortran call:
 
         CALL XDLF_TEXT_TABLE_TEXT (IVH, XDLSTR(STRING), LEN, IROW, ICOL,
        +                           IBOLD, IERR)
 
 
Parameters:
 
IVH     (R)  View-object handle (see vh)
STRING  (R)  The string to be output (see string)
             ** Pass the address using the XDLSTR function **
LEN     (R)  Length of the string (>0) (cf len_str)
IROW    (R)  Row number for the output of the text string 
             (see row)
ICOL    (R)  Column number for the output of the text string
             (see col)
IBOLD   (R)  Flag =0 normal print, =1 bold print (black)
                  = 2/3   Red     normal/bold print
                  = 4/5   Yellow  normal/bold print
                  = 6/7   Green   normal/bold print
                  = 8/9   Cyan    normal/bold print
                  = 10/11 Blue    normal/bold print
                  = 12/13 Magenta normal/bols print
IERR    (W)  Returns the status from xdl_text_table_text call
IERR    (W)  Returns the status from xdl_text_table_text call
 
 
'C' call:
 
int xdl_text_table_text (vh, string, len_str, row, col, bold)
 
 
Parameters:
 
int vh;               /* The xdl_text_table view-object handle (R)*/
char string[];        /* The string to be printed (R)*/
int len_str;          /* The length of the string. If the string is null
                         terminated, then 0 may be given and the length
                         of the string will then be determined by the
                         routine (R)*/
int row;              /* The row number for outputting the string (R)*/
int col;              /* The start column number for outputting the
                         text string (R)*/
int bold;             /* Flag =0 normal print, =1 bold print (black)
                              = 2/3   Red     normal/bold print
                              = 4/5   Yellow  normal/bold print
                              = 6/7   Green   normal/bold print
                              = 8/9   Cyan    normal/bold print
                              = 10/11 Blue    normal/bold print
                              = 12/13 Magenta normal/bols print
                         (R)*/

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set:  Position for start of text string outside
                              window
 
 
2.5.2.5 Output a symbol - xdl_text_table_symbol
 
The routine xdl_text_table_symbol (xdlf_text_table_symbol is used to output
a symbol to a text table view object. The symbol lies within the space of a
single character and its exact size depends on the character font used  for
the text output.
 
Fortran call:
 
         CALL XDLF_TEXT_TABLE_SYMBOL (IVH, ISYMB, IROW, ICOL,
        +                             ICOLR, IERR)
 
 
Parameters:
 
IVH     (R)  View-object handle (see vh)
ISYMB   (R)  Symbol number
             = 0  Open circle (within character)
             = 1  Disk (within character)
             = 2  Disk with black border (within character)
             = 3  Open square (within character)
             = 4  Filled square (within character)
             = 5  Filled square with black border (within character)
             = 6  Open square (full character width)
             = 7  Filled square (full character width)
             = 8  Filled square with black border (full character
                  width)
             = 9  Open rectangle (full character size)
             = 10 Filled rectangle (full character size)
             = 11 Filled rectangle with black border (full character
                  size)
IROW    (R)  Row number for the output of the text string 
             (see row)
ICOL    (R)  Column number for the output of the text string
             (see col)
ICOLR   (R)  Colour flag 0 = black
                         1 = red
                         2 = yellow
                         3 = green
                         4 = cyan
                         5 = blue
                         6 = magenta
IERR    (W)  Returns the status from xdl_text_table_symbol call
IERR    (W)  Returns the status from xdl_text_table_symbol call
 
 
'C' call:
 
int xdl_text_table_symbol (vh, symb, row, col, colr)
 
 
Parameters:
 
int vh;               /* The xdl_text_table view-object handle (R)*/
int symb;             /* Symbol code
                         = 0  Open circle (within character)
                         = 1  Disk (within character)
                         = 2  Disk with black border (within character)
                         = 3  Open square (within character)
                         = 4  Filled square (within character)
                         = 5  Filled square with black border (within 
                              character)
                         = 6  Open square (full character width)
                         = 7  Filled square (full character width)
                         = 8  Filled square with black border (full
                              character width)
                         = 9  Open rectangle (full character size)
                         = 10 Filled rectangle (full character size)
                         = 11 Filled rectangle with black border (full
                              character size)
                         (R)*/
int row;              /* The row number for outputting the string (R)*/
int col;              /* The start column number for outputting the
                         text string (R)*/
int colr;             /* Colour code 
                            0 = black
                            1 = red
                            2 = yellow
                            3 = green
                            4 = cyan
                            5 = blue
                            6 = magenta
                         (R)*/

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set:  Position for symbol outside window
 
 
2.5.2.6 Clear the text table - xdl_text_table_clear
 
The routine xdl_text_table_clear (xdlf_text_table_clear) is used  to  clear
the text table.
 
Fortran call:
 
         CALL XDLF_TEXT_TABLE_CLEAR (IVH, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
IERR     (W)  Returns status from xdl_text_table_clear
IERR     (W)  Returns status from xdl_text_table_clear
 
 
'C' call:
 
int xdl_text_table_clear (vh)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.5.2.7 Clear a section - xdl_text_table_clearsect
 
The routine xdl_text_table_clearsect (xdlf_text_table_clearsect) is used to
clear a section of the text table.
 
Fortran call:
 
         CALL XDLF_TEXT_TABLE_CLEARSECT (IVH, IROW1, ICOL1, 
        +                                IROW2, ICOL2, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
IROW1    (R)  Row number of top left character of area to be 
              cleared
ICOL1    (R)  Column no. of top left character of area to be 
              cleared
IROW2    (R)  Row number of bottom right character of area to be 
              cleared
ICOL2    (R)  Column no. of bottom right character of area to be 
              cleared
IERR     (W)  Returns status from xdl_text_table_clearsect
IERR     (W)  Returns status from xdl_text_table_clearsect
 
 
'C' call:
 
int xdl_text_table_clearsect (vh, row1, col1, row2, col2)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int row1;        /* Row number of top left character of area to be 
                    cleared (R)*/
int col1;        /* Column no. of top left character of area to be 
                    cleared (R)*/
int row2;        /* Row number of bottom right character of area to be 
                    cleared (R)*/
int col2;        /* Column no. of bottom right character of area to be 
                    cleared (R)*/
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.5.2.8 Reset active strip message - xdl_text_table_input_message
 
The routine xdl_text_table_input_message (xdlf_text_table_input_message) is
used to reset the message which will appear in the active strip when  input
is requested When the  view-object  is  created,  the  default  message  is
'Select input'.
 
Fortran call:
 
         CALL XDLF_TEXT_TABLE_INPUT_MESSAGE (IVH, XDLSTR(MESSAGE), 
        +                                    LEN, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
MESSAGE  (R)  Character string containing the message 
              (see message)
              ** Pass address using the XDLSTR function **
LEN      (R)  Length of the message string - must be >0 
              (cf len) (max 60 chars) 
IERR     (W)  Returns status from xdl_text_table_input_message 
              call
 
 
'C' call:
 
int xdl_text_table_input_message (vh, message, len)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
char *message;   /* Message string (max of 60 chars long) (R)*/
int len;         /* Length of the message string; if 0 then length 
                    will be found assuming a null terminated string 
                    (R)*/

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.5.2.9 Define an input cell - xdl_text_table_define_cell
 
The  routine  xdl_text_table_define_cell  (xdlf_text_table_define_cell)  is
used to define an input cell within the text table. This  may  be  selected
via the mouse and will be highlighted when the pointer lies within the cell
area.
 
Fortran call:
 
         CALL XDLF_TEXT_TABLE_DEFINE_CELL (IVH, INUM, IROW1, ICOL1, 
        +                                  IROW2, ICOL2, IHIGH, IHIGH_N,
        +                                  ICOLR_BG, ICOLR_L,
        +                                  IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
INUM     (R)  Cell number (must be in range define when text table set up
IROW1    (R)  First row of cell
ICOL1    (R)  First column of cell
IROW2    (R)  Final row of cell
ICOL2    (R)  Final column of cell
IHIGH    (R)  Highlight option (when text table in input selection mode)
              = 1 coloured bg (underline if not colour)
              = 2 coloured bg (surround box if not colour)
              = 3 underline
              = 4 surround box 
IHIGH_2  (R)  Highlight option when text table not in input selection 
              mode. As above but may be 0 for non such highlighting
ICOLR_BG (R)  Colour for background highlght (1-7) Black, Red, Yellow, Green,
              Cyan, Blue, Magenta
ICOLR_L  (R)  Colour for highlght lines(1-7) Black, Red, Yellow, Green,
              Cyan, Blue, Magenta
IERR     (W)  Returns status from xdl_text_table_define_cell
              call
 
 
'C' call:
 
int xdl_text_table_define_cell (vh, num, row1, col1, row2, col2, hightyp,
                                high_nosel, colr_bg, colr_l)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int num;         /* Cell number (must be in range define when text 
                    table set up (R)*/
int row1;        /* First row of cell (R)*/
int col1;        /* First column of cell (R)*/
int row2;        /* Final row of cell (R)*/
int col2;        /* Final column of cell (R)*/
int hightyp;     /* Highlight option (when text table in input 
                    selection mode)
                    = 1 coloured bg (underline if not colour)
                    = 2 coloured bg (surround box if not colour)
                    = 3 underline
                    = 4 surround box 
                    (R)*/
int high_nosel;  /* Highlight option (when text table not in input 
                    selection mode)
                    As above but may be 0 for no highlighting in this
                    mode (R)*/
int colr_bg;     /* Colour for background highlght (1-7) Black, Red,
                    Yellow, Green, Cyan, Blue, Magenta (R)*/
int colr_l;      /* Colour for highlght lines(1-7) Black, Red, Yellow, 
                    Green, Cyan, Blue, Magenta (R)*/
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set:  Invalid cell number
                  bit 4 set:  Other invalid parameters
 
 
2.5.2.10 Clear input cell(s) - xdl_text_table_clear_cell
 
The routine xdl_text_table_clear_cell (xdlf_text_table_clear_cell) is  used
to clear an input cell or all input cells within the text table. This  dose
not affect the text drawn in such areas just the input control.
 
Fortran call:
 
         CALL XDLF_TEXT_TABLE_CLEAR_CELL (IVH, INUM, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
INUM     (R)  Cell number (must be in range define when text table set up)
              or 0 to clear all cells
IERR     (W)  Returns status from xdl_text_table_clear_cell
              call
 
 
'C' call:
 
int xdl_text_table_clear_cell (vh, num)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int num;         /* Cell number (must be in range define when text 
                    table set up) or 0 to claer all cells (R)*/
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set:  Invalid cell number
 
 
2.5.2.11 Get selected input cell number - xdl_text_table_getinp
 
The routine xdl_text_table_getinp (xdlf_text_table_getinp) is used find the
cell number of the last input cell that was selected using the mouse.
 
Fortran call:
 
         CALL XDLF_TEXT_TABLE_GETINP (IVH, INUM, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
INUM     (W)  Last selected cell number 0 if none
IERR     (W)  Returns status from xdl_text_table_clear_cell
              call
 
 
'C' call:
 
int xdl_text_table_getinp (vh, num)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int *num;        /* Last selected cell number 0 if none (W)*/
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.5.2.12 Calculate size requirements - xdl_text_table_getsize
 
The routine xdl_text_table_getsize (xdlf_text_table_getsize) is used to get
the required size for a text table view-object given the  numbers  of  rows
and columns of characters required.
 
Fortran call:
 
         CALL XDLF_TEXT_TABLE_GETSIZE (NCOLS, NROWS, IFONT, IWIDTH, 
        +                             IHEIGHT)
 
 
Parameters:
 
NCOLS     (R)   No. of cols of characters or 0 (see ncols)
NROWS     (R)   No. of rows of characters or 0 (see nrows)
IFONT     (R)   Font type (1->5 very-small->extra-large) 
                (see font_type)
IWIDTH    (W)   Returns the width required (see w)
IHEIGHT   (W)   Returns the height required (see h)
 
 
'C' call:
 
void xdl_text_table_getsize (ncols, nrows, font_type, w, h)
 
 
Parameters:
 
int       ncols;          /* Number of columns of characters ( > 0 ) (R)*/
int       nrows;          /* Number of rows of characters ( > 0 ) (R)*/
int       font_type;      /* Font type (1-5) for very-small, small, medium,
                             large or extra-large font. (R)*/
int *w;                   /* Returns the width required (W)*/
int *h;                   /* Returns the height required (W)*/

 
 
Return:  None
 
 
2.5.2.13 Calculate cell text size  - xdl_text_table_getcsize
 
The routine xdl_text_table_getcsize (xdlf_text_table_getcsize) is  used  to
get the required size for a text cell view-object given the numbers of rows
and columns of characters required. and whether or not an activestip is  to
be displayed.
 
Fortran call:
 
         CALL XDLF_TEXT_TABLE_GETCSIZE (NCOLS, NROWS, IFONT, IACT,
        +                              IWIDTH, IHEIGHT)
 
 
Parameters:
 
NCOLS     (R)   No. of cols of characters or 0 (see ncols)
NROWS     (R)   No. of rows of characters or 0 (see nrows)
IFONT     (R)   Font type (1->5 very-small->extra-large) 
                (see font_type)
IACT      (R)   <=0 no active strip, =1 active strip present
IWIDTH    (W)   Returns the width required (see w)
IHEIGHT   (W)   Returns the height required (see h)
 
 
'C' call:
 
void xdl_text_table_getcsize (ncols, nrows, font_type, iact, w, h)
 
 
Parameters:
 
int       ncols;          /* Number of columns of characters ( > 0 ) (R)*/
int       nrows;          /* Number of rows of characters ( > 0 ) (R)*/
int       font_type;      /* Font type (1-5) for very-small, small, medium,
                             large or extra-large font. (R)*/
int       iact;           /* <=0 no active strip =1 active strip (R)*/
int *w;                   /* Returns the width required (W)*/
int *h;                   /* Returns the height required (W)*/

 
 
Return:  None
 
 

2.6 THE GRAPH WINDOW VIEW-OBJECT ROUTINES
=========================================


2.6.1 INTRODUCTION
 
The graphics  window  view-object  provides  an  area  for  the  output  of
graphics. A number of routines are supplied to give access to a  basic  set
of line plotting functions including drawing of  rectangles,  polygons  and
arcs. Filled areas may also be drawn. Symbol and  text  plotting  functions
are also available and there are  two  simple  axis  drawing  routines.  An
option is available to produce Postscript files from the plots in order  to
obtain hard copies. Sections of the plot may be identified by  an  graphics
object group identifier enabling parts of the plot to be deleted or redrawn
under program control. Simple cursor input is provided. A number of options
are available for defining the mapping of the  user  coordinates  onto  the
window and for handling possible re-sizing of  the  graphics  window.  When
plotting, a current graphics style is used; this determines the colour, the
line width and the X-font to be  used.  This  style  may  be  changed  when
required.
 
The following sets of routines are available:
 
   Creating and Handling a Graph Window View-Object
 
2.6.2 CREATING AND HANDLING A GRAPH WINDOW VIEW-OBJECT
 
2.6.2.1 Introduction
 
The following routines are available:
 
   Create a graphics window view-object - xdl_graph_win
   Set mapping option - xdl_graph_win_map
   Set style parameters - xdl_graph_win_style
   Reset a colour - xdl_graph_win_set_colour
   Draw a line - xdl_graph_win_line
   Draw a polyline - xdl_graph_win_polyline
   Draw a text string - xdl_graph_win_stext
   Draw a text string - xdl_graph_win_xtext
   Draw a symbol - xdl_graph_win_symbol
   Draw polysymbols - xdl_graph_win_polysymbol
   Draw a rectangle - xdl_graph_win_rectangle
   Draw a polygon - xdl_graph_win_polygon
   Draw an arc - xdl_graph_win_arc
   Draw a horizontal axis - xdl_graph_win_ax1
   Draw a vertical axis - xdl_graph_win_ax2
   Get an input cursor position - xdl_graph_win_getcurs
   Reset active strip message - xdl_graph_win_input_message
   Reset current group id - xdl_graph_win_setid
   Delete graphics objects - xdl_graph_win_delete
   Calculate size requirements - xdl_graph_win_getsize
 
2.6.2.2 Create a graphics window view-object - xdl_graph_win
 
The routine xdl_graph_win (xdlf_graph_win) is used to create a new graphics
window view-object. The user may specify the size of the window in  pixels.
The required options for handling the possible re-sizing  of  the  graphics
window are selected. On a colour display a default colour map of 8  colours
(black, white, red, yellow,  green,  cyan,  blue  and  magenta)  is  always
available. If required, the user may define an additional colour map to  be
used to provide additional colours. Such colours need to be set  via  calls
to the routine xdl_graph_win_set_colour (xdlf_graph_win_set_colour)  before
being used.
 
Fortran call:
 
         CALL XDLF_GRAPH_WIN (IVH, IVHPARENT, IX, IY, ICSET, NCOLRS, 
        +                     IGWIDTH, IGHEIGHT, 
        +                     MINW, MINH, IEXPAND, IPOSN, IERR)
 
 
Parameters:
 
IVH       (R)   View-object handle (see vh)
IVHPARENT (R)   View-object handle for parent 0=none 
                (see vh_parent)
IX        (R)   X position (may be -1 if no parent) (see x)
IY        (R)   Y position (may be -1 if no parent) (see y)
ICSET     (R)   Colorset number for optional additional
                colorset of NCOLRS colours (0 if not needed) 
                (see cset)
NCOLRS    (R)   No. of colours in additional colorset
IGWIDTH   (R)   Required width of graphics area in pixels
                excluding border (see gr_width)
IGHEIGHT  (R)   Required height of graphics area in pixels
                excluding border (see gr_height)
MINW      (R)   Minimum width of view-object in pixels 
                (see min_width)
MINH      (R)   Minimum height of view-object in pixels 
                (see min_height)
IEXPAND   (R)   Flag for handling of expanded/contracted
                graphics area.
                = 0, do not expand/contract
                = 1, expand/contract to fit window size but
                     preserve ratio of axes
                = 2, expand/contact in both directions to
                     fit window
IPOSN     (R)   = 0, Position in centre of window
                = 1, Position at bottom left of window
IERR      (W)   Returns status from xdl_graph_win call
 
 
'C' call:
 
int xdl_graph_win (int vh, int vh_parent, int x, int y, int cset, 
                   int ncolrs, int gr_width, int gr_height, 
                   int min_width, int min_height, 
                   int expand, int posn)
 
 
Parameters:
 
int       vh;              User selected view-object handle (R)
int       vh_parent;       View-object handle for the parent base frame, 
                           if 0 then a base  level frame is created to
                           enclose the graphics window view-object (R)
int       x;               x coordinate for the view-object.
                           If no parent may be -1 to give default x (R)
int       y;               y coordinate for the view-object.
                           If no parent may be -1 to give default y (R)
int       cset;            Colorset number for optional additional 
                           colorset of 'ncolrs' colours. Set to 0 if not
                           required. The colours for this set will be 
                           numbered from 8 upwards (with 0-7 
                           being used for the default colours) (R)
int       ncolrs;          No. of colours in the additional colorset if
                           used (R) 
int       gr_width;        Required width of graphics window in pixels 
                           excluding border (R)
int       gr_height;       Required height of graphics window in pixels 
                           excluding border (R)
int       min_width;       Minimum window width of view-object in pixels. 
                           If this is greater than the width calculated 
                           from the graph area width requirement etc. 
                           then this value will be used as the window 
                           width (R)
int       min_height;      Minimum window height of view-object in 
                           pixels. If this is greater than the height 
                           calculated from the graph area height 
                           requirement etc. then this value will be 
                           used as the window height (R)
int       expand;          Flag for handling of expanded/contracted
                           graphics area.
                           = 0, do not expand/contract
                           = 1, expand/contract to fit window size but
                                preserve ratio of axes
                           = 2, expand/contact in both directions to
                                fit window (R)
int       posn;            = 0, Position in centre of window
                           = 1, Position at bottom left of window (R)
 
 
Return:  Status flag =0 OK, >0 error
                bit 0 set: Requested parent not found in view-objects list
                bit 1 set: Memory allocation error
 
 
2.6.2.3 Set mapping option - xdl_graph_win_map
 
The routine xdl_graph_win_map  (xdlf_graph_win_map)  is  used  to  set  the
current mapping between coordinate space and display space.
 
Fortran call:
 
         CALL XDLF_GRAPH_WIN_MAP (IVH, AX1_MIN, AX1_MAX, AX2_MIN, AX2_MAX,
        +                         DAX1_MIN, DAX1_MAX, DAX2_MIN, DAX2_MAX,
        +                         ITYP, IERR)
 
 
Parameters:
 
IVH          (R)  View-object handle (see vh)
AX1_MIN      (R)  Minimum axis 1 coord. in coordinate space
AX1_MAX      (R)  Maximum axis 1 coord. in coordinate space 
AX2_MIN      (R)  Minimum axis 2 coord. in coordinate space
AX2_MAX      (R)  Maximum axis 2 coord. in coordinate space 
DAX1_MIN     (R)  Minimum axis 1 coord. in display space
                  (see ityp below)
DAX1_MAX     (R)  Maximum axis 1 coord. in display space 
                  (see ityp below)
DAX2_MIN     (R)  Minimum axis 2 coord. in display space
                  (see ityp below)
DAX2_MAX     (R)  Maximum axis 2 coord. in display space 
                  (see ityp below)
ITYP         (R)  Display space type = 0 display coordinates
                                         0.0 to 1.0 in axis 1 and
                                         axis 2 represent the full
                                         size of the requested
                                         graphics window when the
                                         graphics window object
                                         was created.
                                     = 1 display coordinates
                                         0.0 to 1.0 in axis 1 and
                                         axis 2 represent the unit
                                         square. 
IERR         (W)  Returns the status from xdl_graph_win_map call
 
 
'C' call:
 
int xdl_graph_win_map (int vh, float ax1_min, float ax1_max, 
                       float ax2_min, float ax2_max, 
                       float dax1_min, float dax1_max, 
                       float dax2_min, float dax2_max, int ityp)
 
 
Parameters:
 
int vh;               The xdl_graph_win view-object handle (R)
float ax1_min;        Minimum axis 1 coord. in coordinate space (R)
float ax1_max;        Maximum axis 1 coord. in coordinate space (R)
float ax2_min;        Minimum axis 2 coord. in coordinate space (R)
float ax2_max;        Maximum axis 2 coord. in coordinate space (R)
float dax1_min;       Minimum axis 1 coord. in display space
                      (see ityp below) (R)
float dax1_max;       Maximum axis 1 coord. in display space 
                      (see ityp below) (R)
float dax2_min;       Minimum axis 2 coord. in display space
                      (see ityp below) (R)
float dax2_max;       Maximum axis 2 coord. in display space 
                      (see ityp below) (R)
int ityp;             Display space type = 0 display coordinates
                                             0.0 to 1.0 in axis 1 and
                                             axis 2 represent the full
                                             size of the requested
                                             graphics window when the
                                             graphics window object
                                             was created.
                                         = 1 display coordinates
                                             0.0 to 1.0 in axis 1 and
                                             axis 2 represent the unit
                                             square. (R)

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.6.2.4 Set style parameters - xdl_graph_win_style
 
The routine xdl_graph_win_style (xdlf_graph_win_style) is used to  set  the
current style required for the  plotting.  The  style  parameters  are  the
colour, the line width and the X-windows font to be used.
 
Fortran call:
 
         CALL XDLF_GRAPH_WIN_STYLE (IVH, IFG_COLR, LINW, IFONT, IERR)
 
 
Parameters:
 
IVH         (R)  View-object handle (see vh)
IFG_COLR    (R)  Foreground colour -1 = current value
                                    0 = black
                                    1 = white
                                    2 = red
                                    3 = yellow
                                    4 = green
                                    5 = cyan
                                    6 = blue
                                    7 = magenta  
                                    8 upwards (colours from additional
                                      colorset if defined). Set via 
                                      xdl_graph_win_set_colour)
LINW        (R)  Line width in pixels (-1 = current value) 
IFONT       (R)  Font type -1 = current font
                            1 = standard font (very small)
                            2 = standard font (small)
                            3 = standard font (medium)
                            4 = standard font (large)
                            5 = standard font (very large)
IERR        (W)  Returns the status from xdl_graph_win_style call
 
 
'C' call:
 
int xdl_graph_win_style (int vh, int fg_colr, int line_width, 
                         int font_type)
 
 
Parameters:
 
int vh;               The xdl_graph_win view-object handle (R)
int fg_colr;          Foreground colour -1 = current value
                                         0 = black
                                         1 = white
                                         2 = red
                                         3 = yellow
                                         4 = green
                                         5 = cyan
                                         6 = blue
                                         7 = magenta  
                                         8 upwards (colours from 
                                           additional colorset if 
                                           defined - set via 
                                           xdl_graph_win_set_colour)
                      (R)
int line_width;       Line width in pixels (-1 = current value) (R)
int font_type;        Font type -1 = current font
                                 1 = standard font (very small)
                                 2 = standard font (small)
                                 3 = standard font (medium)
                                 4 = standard font (large)
                                 5 = standard font (very large)
                      (R)

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set;  Memory allocation failure
 
 
2.6.2.5 Reset a colour - xdl_graph_win_set_colour
 
The routine xdl_graph_win_set_colour (xdlf_graph_win_set_colour) is used to
reset a colour. The routine will only  have  an  effect  if  a  non-default
colorset of additional colours is being used  for  the  graph  window  view
object.
 
Fortran call:
 
         CALL XDLF_GRAPH_WIN_SET_COLOUR (IVH, ICOLR, IRED, IGREEN, 
        +                                 IBLUE, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
ICOLR    (R)  Colour number (8 upwards) (see icolr)
IRED     (R)  Red component 0 to 65535 (see red)
IGREEN   (R)  Green component 0 to 65535 (see green)
IBLUE    (R)  Blue component 0 to 65535 (see blue)
IERR     (W)  Returns status from xdl_image_set_colour call
 
 
'C' call:
 
int xdl_graph_win_set_colour (int vh, int icolr, int red, int blue, 
                              int green)
 
 
Parameters:
 
int vh;          View-object handle (R)
int icolr;       Colour number 8 upwards (R)
int red;         Red component 0 to 65535 (R)
int green;       Green component 0 to 65535 (R)
int blue;        Blue component 0 to 65535 (R)

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.6.2.6 Draw a line - xdl_graph_win_line
 
The routine xdl_graph_win_line (xdlf_graph_win_line) is used to draw a line
on a graphics window view object. The current colour  and  line  width  are
used and the coordinates are based on the current mapping.
 
Fortran call:
 
         CALL XDLF_GRAPH_WIN_LINE (IVH, AX1_START, AX2_START,
        +                          AX1_END, AX2_END, IERR)
 
 
Parameters:
 
IVH           (R)  View-object handle (see vh)
AX1_START     (R)  Start position of line axis 1 coordinate 
AX2_START     (R)  Start position of line axis 2 coordinate 
AX1_END       (R)  End position of line axis 1 coordinate 
AX2_END       (R)  End position of line axis 2 coordinate 

                   Note: Coordinates are in 'coordinate' space as set 
                         by  the mapping routine.

IERR          (W)  Returns the status from xdl_graph_win_line call
 
 
'C' call:
 
int xdl_graph_win_line (int vh, float ax1_start, float ax2_start, 
                        float ax1_end, float ax2_end)
 
 
Parameters:
 
int vh;               The xdl_graph_win view-object handle (R)
float ax1_start;      Start position of line axis 1 coordinate (R)
float ax2_start;      Start position of line axis 2 coordinate (R)
float ax1_end;        End position of line axis 1 coordinate (R)
float ax2_end;        End position of line axis 2 coordinate (R)

                      Coordinates are in 'coordinate' space as set by
                         the mapping routine.

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.6.2.7 Draw a polyline - xdl_graph_win_polyline
 
The routine xdl_graph_win_polyline  (xdlf_graph_win_polyline)  is  used  to
draw lines on a graphics window view object connecting a  given  series  of
points. The current colour and line width are used and the coordinates  are
based on the current mapping.
 
Fortran call:
 
         CALL XDLF_GRAPH_WIN_POLYLINE (IVH, AX1_COORDS, AX2_COORDS,
        +                            NPOINTS, IERR)
 
 
Parameters:
 
IVH            (R)  View-object handle (see vh)
AX1_COORDS     (R)  Axis 1 coordinates
AX2_COORDS     (R)  Axis 2 coordinates
NPOINTS        (R)  No. of points

                    Note: Coordinates are in 'coordinate' space as set
                          by the mapping routine.

IERR           (W)  Returns the status from xdl_graph_win_polyline call
 
 
'C' call:
 
int xdl_graph_win_polyline (int vh, float * ax1_coords, float * ax2_coords,
                            int  npoints)
 
 
Parameters:
 
int vh;               The xdl_graph_win view-object handle (R)
float ax1_coords[];   Axis 1 coordinates (R)
float ax2_coords[];   Axis 2 coordinates (R)
int npoints;          No. of points (at least 2) (R)

                      Coordinates are in 'coordinate' space as set by
                         the mapping routine. 

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set:  Unable to allocate memory
 
 
2.6.2.8 Draw a text string - xdl_graph_win_stext
 
The routine xdl_graph_win_stext (xdlf_graph_win_stext) is used  to  draw  a
text string on a graphics window view object using the  internal  scaleable
font. The current colour and line width are used and  the  coordinates  are
based on the current mapping. The current X-windows font definition is  not
used by this routine. Two positioning options are available  and  the  text
may be drawn at any angle required.
 
Fortran call:
 
         CALL XDLF_GRAPH_WIN_STEXT (IVH, AX1_COORD, AX2_COORD,
        +                           XDLSTR(TXT), LENTXT, 
        +                           SIZE1, SIZE2, ISIZOPT, ICENT,
        +                           ANGLE, IERR)
 
 
Parameters:
 
IVH           (R)  View-object handle (see vh)
AX1_COORD     (R)  Start position of text axis 1 coordinate 
AX2_COORD     (R)  Start position of text axis 2 coordinate 

                    Note: Coordinates are in 'coordinate' space as set 
                          by mapping routine.

TXT           (R)  Text string
                    ** Pass address using XDLSTR function **
LENTXT        (R)  Length of the text string (>0)
SIZE1         (R)  Size of the characters along axis 1 (may be 0.0 if
                   size2 > 0.0)
SIZE2         (R)  Size of the characters along axis 2 (may be 0.0 if
                   size1 > 0.0)
ISIZOPT       (R)  Character size (height) definition option
                   = 0 sizes are in unit square units (0.0 - 1.0)
                   = 1 sizes are relative to current axis mapping
                   If a zero size value is given then it will be 
                   calculated from the other size assuming the 
                   standard character shape with a height:width ratio 
                   of 20:12
ICENT         (R)  = 0 position is for bottom left of text
                   = 1 centre text string (both directions)
ANGLE         (R)  Rotate text string anticlockwise by angle degrees
                   from the starting horizontal position (if ICENT is
                   0 the rotation is about the bottom left point of
                   the text string and if ICENT is 1 then it is about
                   the mid point of the string). Note: the size
                   calculations for the text are done before the
                   string is rotated.
IERR          (W)  Returns the status from xdl_graph_win_stext call
 
 
'C' call:
 
int xdl_graph_win_stext (int vh, float ax1_coord, float ax2_coord, 
                         char * txt, int lentxt, float size1,
                         float size2, int sizopt, int cent, 
                         float angle)
 
 
Parameters:
 
int vh;               The xdl_graph_win view-object handle (R)
float ax1_coord;      Start position of text axis 1 coordinate (R)
float ax2_coord;      Start position of text axis 2 coordinate (R)
                      Coordinates are in 'coordinate' space as set by
                      the mapping routine. 
char *txt;            Text string to be drawn (ascii) (R)
int lentxt;           Length of text string (may be 0 if a null
                      terminated string was given) (R)
float size1;          Size of the characters along axis 1 (may be 0.0 if
                      size2 > 0.0) (R)
float size2;          Size of the characters along axis 2 (may be 0.0 if
                      size1 > 0.0) (R)
int sizopt;           Character size definition option

                        = 0 sizes are in unit square units (0.0 - 1.0)
                        = 1 sizes are relative to current axis mapping
  
                      If a zero size value is given then it will be 
                      calculated from the other size assuming the 
                      standard character shape with a height:width 
                      ratio of 20:12 (R)

int cent;             = 0 position is for bottom left of text
                      = 1 centre text string (both directions) (R)
float angle;          Rotate text string anticlockwise by angle degrees
                      from the starting horizontal position (if cent==0
                      the rotation is about the bottom left point of
                      the text string and if cent==1 then it is about
                      the mid point of the string). Note: the size
                      calculations for the text are done before the
                      string is rotated. (R)
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.6.2.9 Draw a text string - xdl_graph_win_xtext
 
The routine xdl_graph_win_xtext (xdlf_graph_win_xtext) is used  to  draw  a
text string on a graphics window view object  using  the  current  xdl_view
standard X-windows font. The text is drawn  in  the  current  colour.  Only
horizontal text strings may be drawn using this  routine.  Two  positioning
options are available defined using the current coordinate mapping.
 
Fortran call:
 
         CALL XDLF_GRAPH_WIN_XTEXT (IVH, AX1_COORD, AX2_COORD,
        +                           XDLSTR(TXT), LENTXT, 
        +                           ICENT, IERR)
 
 
Parameters:
 
IVH           (R)  View-object handle (see vh)
AX1_COORD     (R)  Start position of text axis 1 coordinate 
AX2_COORD     (R)  Start position of text axis 2 coordinate 

                   Note: Coordinates are in 'coordinate' space as set 
                         by mapping routine.

TXT           (R)  Text string
                   ** Pass address using XDLSTR function **
LENTXT        (R)  Length of the text string (>0)
ICENT         (R)  = 0 position is for bottom left of text
                   = 1 centre text string (both directions)
IERR          (W)  Returns the status from xdl_graph_win_xtext call
 
 
'C' call:
 
int xdl_graph_win_xtext (int vh, float ax1_coord, float ax2_coord, 
                         char * txt, int lentxt, int cent)
 
 
Parameters:
 
int vh;               The xdl_graph_win view-object handle (R)
float ax1_coord;      Start position of text axis 1 coordinate (R)
float ax2_coord;      Start position of text axis 2 coordinate (R)
                      Coordinates are in 'coordinate' space as set by
                      mapping routine. 
char *txt;            Text string to be drawn (ascii) (R)
int lentxt;           Length of text string (may be 0 if a null
                      terminated string was given) (R)
int cent;             = 0 position is for bottom left of text
                      = 1 centre text string (both directions) (R)
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.6.2.10 Draw a symbol - xdl_graph_win_symbol
 
The routine xdl_graph_win_symbol (xdlf_graph_win_symbol)is used to  draw  a
symbol on a graphics window view object using one of the scaleable  symbols
available. The current colour and line width are used and  the  coordinates
are based on the current mapping.
 
Fortran call:
 
         CALL XDLF_GRAPH_WIN_SYMBOL (IVH, AX1_COORD, AX2_COORD, ISYMB,
        +                           SIZE, ISIZOPT, IERR)
 
 
Parameters:
 
IVH           (R)  View-object handle (see vh)
AX1_COORD     (R)  Symbol position axis 1 coordinate 
AX2_COORD     (R)  Symbol position axis 2 coordinate 

                   Note: Coordinates are in 'coordinate' space as set
                         by the mapping routine.

ISYMB         (R)  Symbol type  0 = point (single pixel)
                                1 = variable sized point
                                2 = vertical cross
                                3 = diagonal cross
                                4 = square
                                5 = diamond
SIZE          (R)  Size of the symbol (see ISIZOPT)
ISIZOPT       (R)  Symbol size definition option
                    = 0 size is in unit square units (0.0 - 1.0)
                    = 1 size is relative to current axis 1 axis 
                        mapping
                    = 2 size is relative to current axis 2 axis 
                        mapping
IERR    (W)        Returns the status from xdl_graph_win_symbol call
 
 
'C' call:
 
int xdl_graph_win_symbol (int vh, float ax1_coord, float ax2_coord, 
                          int symb, float size, int sizopt)
 
 
Parameters:
 
int vh;               The xdl_graph_win view-object handle (R)
float ax1_coord;      Symbol position axis 1 coordinate (R)
float ax2_coord;      Symbol position axis 2 coordinate (R)
                      Coordinates are in 'coordinate' space as set by
                      the mapping routine. 
int symb;             Symbol type  0 = point (single pixel)
                                   1 = variable sized point
                                   2 = vertical cross
                                   3 = diagonal cross
                                   4 = square
                                   5 = diamond
                      (R)
float size;           Size of the symbol (see sizopt) (R)
int sizopt;           Symbol size definition option

                          = 0 size is in unit square units (0.0 - 1.0)
                          = 1 size is relative to current axis 1 axis 
                              mapping
                          = 2 size is relative to current axis 2 axis 
                              mapping
                      (R)

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set:  Unable to allocate memory
 
 
2.6.2.11 Draw polysymbols - xdl_graph_win_polysymbol
 
The routine xdl_graph_win_polysymbol (xdlf_graph_win_polysymbol) is used to
draw a set of symbols on a graphics window view object for given series  of
points.
 
Fortran call:
 
         CALL XDLF_GRAPH_WIN_POLYSYMBOL (IVH, AX1_COORDS, AX2_COORDS,
        +                            NPOINTS, ISYMB, SIZE, ISIZOPT, IERR)
 
 
Parameters:
 
IVH           (R)  View-object handle (see vh)
AX1_COORDS    (R)  Axis 1 coordinates
AX2_CORDS     (R)  Axis 2 coordinates
NPOINTS       (R)  No. of points
                   Note: Coordinates are in 'coordinate' space as set
                         by the mapping routine.
ISYMB         (R)  Symbol type  0 = point (single pixel)
                                1 = variable sized point
                                2 = vertical cross
                                3 = diagonal cross
                                4 = square
                                5 = diamond
SIZE          (R)  Size of the symbol (see ISIZOPT)
ISIZOPT       (R)  Symbol size definition option
                    = 0 size is in unit square units (0.0 - 1.0)
                    = 1 size is relative to current axis 1 axis 
                        mapping
                    = 2 size is relative to current axis 2 axis 
                        mapping
IERR          (W)  Returns the status from xdl_graph_win_polysymbol call
 
 
'C' call:
 
int xdl_graph_win_polysymbol (int vh, float * ax1_coords, 
                              float * ax2_coords, int npoints, int symb,
                              float size, int sizopt)
 
 
Parameters:
 
int vh;               The xdl_graph_win view-object handle (R)
float ax1_coords[];   Axis 1 coordinates (R)
float ax2_coords[];   Axis 2 coordinates (R)
int npoints;          No. of points (at least 2) (R)
int symb;             Symbol type  0 = point (single pixel)
                                   1 = variable sized point
                                   2 = vertical cross
                                   3 = diagonal cross
                                   4 = square
                                   5 = diamond
                      (R)
float size;           Size of the symbol (see sizopt) (R)
int sizopt;           Symbol size definition option

                          = 0 size is in unit square units (0.0 - 1.0)
                          = 1 size is relative to current axis 1 axis 
                              mapping
                          = 2 size is relative to current axis 2 axis 
                              mapping
                      (R)

                      Coordinates are in 'coordinate' space as set by
                      the mapping routine.

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set:  Unable to allocate memory
 
 
2.6.2.12 Draw a rectangle - xdl_graph_win_rectangle
 
The routine xdl_graph_win_rectangle (xdlf_graph_win_rectangle) is  used  to
draw a rectangle on a graphics window view object.  The  rectangle  may  be
filled if desired. For an unfilled rectangle, the current colour  and  line
width are used and for a filled rectangle, the current colour is used.  The
coordinates are based on the current mapping.
 
Fortran call:
 
         CALL XDLF_GRAPH_WIN_RECTANGLE (IVH, AX1_START, AX2_START,
        +                          AX1_END, AX2_END, IFILL, IERR)
 
 
Parameters:
 
IVH           (R)  View-object handle (see vh)
AX1_START     (R)  Start corner axis 1 coordinate 
AX2_START     (R)  Start corner axis 2 coordinate 
AX1_END       (R)  End corner axis 1 coordinate 
AX2_END       (R)  End corner axis 2 coordinate 

                   Note: Coordinates are in 'coordinate' space as set 
                         by the mapping routine.

IFILL         (R)  = 0 do not fill, = 1 fill
IERR          (W)  Returns the status from xdl_graph_win_rectangle call
 
 
'C' call:
 
int xdl_graph_win_rectangle (int vh, float ax1_start, float ax2_start, 
                             float ax1_end, float ax2_end, int fill)
 
 
Parameters:
 
int vh;               The xdl_graph_win view-object handle (R)
float ax1_start;      Start corner axis 1 coordinate (R)
float ax2_start;      Start corner axis 2 coordinate (R)
float ax1_end;        End corner axis 1 coordinate (R)
float ax2_end;        End corner axis 2 coordinate (R)

                      Coordinates are in 'coordinate' space as set by
                      the mapping routine.
int fill;             = 1 fill, = 0 do not (R)

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set:  Unable to allocate memory
 
 
2.6.2.13 Draw a polygon - xdl_graph_win_polygon
 
The routine xdl_graph_win_polygon (xdlf_graph_win_polygon) is used to  draw
a polygon on a graphics window view object. The polygon may  be  filled  if
desired. The points must define a non-intersecting  polygon.  If  the  last
point is not the same as the first point, the polygon will be automatically
closed. For an unfilled polygon, the current colour and line width are used
and for a filled polygon, the current colour is used. The  coordinates  are
based on the current mapping.
 
Fortran call:
 
         CALL XDLF_GRAPH_WIN_POLYLGON (IVH, AX1_COORDS, AX2_COORDS,
        +                            NPOINTS, IFILL, IERR)
 
 
Parameters:
 
IVH           (R)  View-object handle (see vh)
AX1_COORDS    (R)  Axis 1 coordinates
AX2_COORDS    (R)  Axis 2 coordinates
NPOINTS       (R)  No. of points

                   Note: Coordinates are in 'coordinate' space as set
                         by the mapping routine.

IFILL         (R)  = 1 fill, = 0 do not.
IERR          (W)  Returns the status from xdl_graph_win_polygon call
 
 
'C' call:
 
int xdl_graph_win_polygon (int vh, float * ax1_coords, float * ax2_coords,
                           int npoints, int fill)
 
 
Parameters:
 
int vh;               The xdl_graph_win view-object handle (R)
float ax1_coords[];   Axis 1 coordinates (R)
float ax2_coords[];   Axis 2 coordinates (R)
int npoints;          No. of points (at least 3) (R)

                      Coordinates are in 'coordinate' space as set by
                         the mapping routine. 
int fill;             = 1 fill, = 0 do not (R)

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set:  Unable to allocate memory
 
 
2.6.2.14 Draw an arc - xdl_graph_win_arc
 
The routine xdl_graph_win_arc (xdlf_graph_win_arc) is used to draw  an  arc
on a graphics window view object. The arc may be filled if desired  in  one
of two ways, either as a sector (pie slice) or as a filled  chord.  For  an
unfilled arc, the current colour and line width are used and for  a  filled
arc, the current colour is used. The coordinates are based on  the  current
mapping.
 
Fortran call:
 
         CALL XDLF_GRAPH_WIN_ARC (IVH, AX1_CEN, AX2_CEN, RAD1, RAD2,
        +                         ANGLE_START, ANGLE_RANGE, IFILL, IERR)
 
 
Parameters:
 
IVH             (R)  View-object handle (see vh)
AX1_CEN         (R)  Centre position along axis 1
AX2_CEN         (R)  Centre position along axis 2
RAD1            (R)  Radius along axis 1
RAD2            (R)  Radius along axis 2
ANGLE_START     (R)  Start angle (degrees) (anti clockwise 
                     from 3 o'clock)
ANGLE_RANGE     (R)  Angle range (anticlockwise) in degrees
IFILL           (R)  =0 do not fill, 
                     =1 fill as sector (pie slice),
                     =2 fill chord

                     Note: Coordinates & radii are in 'coordinate' space 
                           as set by the mapping routine.

IERR            (W)  Returns the status from xdl_graph_win_arc call
 
 
'C' call:
 
int xdl_graph_win_arc (int vh, float ax1_cen, float ax2_cen, 
                       float rad1, float rad2, float angle_start,
                       float angle_range, int fill)
 
 
Parameters:
 
int vh;               The xdl_graph_win view-object handle (R)
float ax1_cen;        Centre position along axis 1 (R)
float ax2_cen;        Centre position along axis 2 (R)
float rad1;           Radius along axis 1 (R)
float rad2;           Radius along axis 2 (R)
float angle_start;    Start angle (degrees) (anti clockwise from 3 
                      o'clock) (R)
float angle_range;    Angle range (anticlockwise) in degrees (R)
int fill;             =0 do not fill, 
                      =1 fill as sector (pie slice),
                      =2 fill chord (R)

                      Coordinates & radii are in 'coordinate' space 
                         as set by the mapping routine. 

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set:  Unable to allocate memory
 
 
2.6.2.15 Draw a horizontal axis - xdl_graph_win_ax1
 
The routine xdl_graph_win_ax1  (xdlf_graph_win_ax1)  is  used  to  draw  an
annotated horizontal graph axis on  a  graphics  window  view  object.  The
coordinates are based on the current mapping. Tick sizes,  character  sizes
and annotation intevals are set by the user.
 
Fortran call:
 
         CALL XDLF_GRAPH_WIN_AX1 (IVH, AX1_ORIG, AX2_ORIG, AXLEN,
        +                         NDIV, AX1_DIV, ND, HTICK, SIZ, 
        +                         ISIZOPT, IERR)
 
 
Parameters:
 
IVH           (R)  View-object handle (see vh)
AX1_ORIG      (R)  Origin (axis 1) (see note)
AX2_ORIG      (R)  Origin (axis 2) (see note)
AXLEN         (R)  Axis length (see note)
NDIV          (R)  No. of divisions for annotation (if not use AX1_DIV)
AX1_DIV       (R)  Division along axis 1 for annotation if NDIV = 0
                   (see note)
ND            (R)  No. of decimal places for axis values
HTICK         (R)  Height of ticks (see ISIZOPT)
SIZ           (R)  Character height for annotation (see ISIZOPT)
ISIZOPT       (R)  Symbol size definition option
                    = 0 size is in unit square units (0.0 - 1.0)
                    = 1 size is relative to current axis 1 axis 
                        mapping
                    = 2 size is relative to current axis 2 axis 
                        mapping
IERR          (W)  Returns the status from xdl_graph_win_ax1 call

                   Note: Coordinates are in 'coordinate' space 
                         as set by the mapping routine.
 
 
'C' call:
 
int xdl_graph_win_ax1 (int vh, float ax1_orig, float ax2_orig, float axlen,
                       int  ndiv, float ax1_div, int nd,
                       float htick, float siz, int sizopt)
 
 
Parameters:
 
int vh;               The xdl_graph_win view-object handle (R)
float ax1_orig;       Origin (axis 1) (see note) (R)
float ax2_orig;       Origin (axis 2) (see note) (R)
float axlen;          Axis length (see note) (R)
int ndiv;             No. of divisions for annotation (if 0 then use
                      ax1_div) (R)
float ax1_div;        Division along axis 1 for annotation if ndiv = 0
                      (see note) (R)
int nd;               No. of decimal places for axis values (R)
float htick;          Height of ticks (see sizopt) (R)
float siz;            Character height for annotation (see sizopt) (R)
int sizopt;           Symbol size definition option

                        = 0 size is in unit square units (0.0 - 1.0)
                        = 1 size is relative to current axis 1 axis 
                            mapping
                        = 2 size is relative to current axis 2 axis 
                            mapping (R)

                      Note: Coordinates are in 'coordinate' space 
                            as set by the mapping routine. 

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set:  Unable to allocate memory
 
 
2.6.2.16 Draw a vertical axis - xdl_graph_win_ax2
 
The routine xdl_graph_win_ax2  (xdlf_graph_win_ax2)  is  used  to  draw  an
annotated vertical graph  axis  on  a  graphics  window  view  object.  The
coordinates are based on the current mapping. Tick sizes,  character  sizes
and annotation intevals are set by the user.
 
Fortran call:
 
         CALL XDLF_GRAPH_WIN_AX2 (IVH, AX1_ORIG, AX2_ORIG, AXLEN,
        +                         NDIV, AX2_DIV, ND, HTICK, SIZ, 
        +                         ISIZOPT, IERR)
 
 
Parameters:
 
IVH           (R)  View-object handle (see vh)
AX1_ORIG      (R)  Origin (axis 1) (see note)
AX2_ORIG      (R)  Origin (axis 2) (see note)
AXLEN         (R)  Axis length (see note)
NDIV          (R)  No. of divisions for annotation (if not use AX2_DIV)
AX2_DIV       (R)  Division along axis 2 for annotation if NDIV = 0
                   (see note)
ND            (R)  No. of decimal places for axis values
HTICK         (R)  Width of ticks (see ISIZOPT)
SIZ           (R)  Character height for annotation (see ISIZOPT)
ISIZOPT       (R)  Symbol size definition option
                    = 0 size is in unit square units (0.0 - 1.0)
                    = 1 size is relative to current axis 1 axis 
                        mapping
                    = 2 size is relative to current axis 2 axis 
                        mapping
IERR          (W)  Returns the status from xdl_graph_win_ax1 call

                   Note: Coordinates are in 'coordinate' space 
                         as set by the mapping routine.
 
 
'C' call:
 
int xdl_graph_win_ax2 (int vh, float ax1_orig, float ax2_orig, float axlen,
                       int ndiv, float ax2_div, int nd,
                       float wtick, float siz, int sizopt)
 
 
Parameters:
 
int vh;               The xdl_graph_win view-object handle (R)
float ax1_orig;       Origin (axis 1) (see note) (R)
float ax2_orig;       Origin (axis 2) (see note) (R)
float axlen;          Axis length (see note) (R)
int ndiv;             No. of divisions for annotation 
                      (if 0 use ax2_div)(R)
float ax2_div;        Division along axis 2 for annotation if ndiv = 0
                      (see note) (R)
int nd;               No. of decimal places for axis values (R)
float wtick;          Width of ticks (see sizopt) (R)
float siz;            Character height for annotation (see sizopt) (R)
int sizopt;           Symbol size definition option

                        = 0 size is in unit square units (0.0 - 1.0)
                        = 1 size is relative to current axis 1 axis 
                            mapping
                        = 2 size is relative to current axis 2 axis 
                            mapping (R)

                      Note: Coordinates are in 'coordinate' space 
                            as set by the mapping routine. 

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set:  Unable to allocate memory
 
 
2.6.2.17 Get an input cursor position - xdl_graph_win_getcurs
 
The  routine  xdl_graph_win_getcurs  (xdlf_graph_win_getcurs)  is  used  to
return an selcted cursor position. It should be  called  after  the  return
from a call to xdl_get_events  (xdlf_get_events)  indicates  that  a  graph
window view-object has returned input. The coordinates returned  are  based
on the current mapping.
 
Fortran call:
 
         CALL XDLF_GRAPH_WIN_GETCURS (IVH, AX1_COORD, AX2_COORD, IERR)
 
 
Parameters:
 
IVH            (R)  View-object handle (see vh)
AX1_COORD      (W)  Returns the axis 1 coordinate value (current 
                    mapping)
AX2_COORD      (W)  Returns the axis 2 coordinate value (current 
                    mapping)
IERR           (W)  Returns status from xdl_graph_win_getcurs call
 
 
'C' call:
 
int xdl_graph_win_getcurs (int vh, float * ax1_coord, float * ax2_coord)
 
 
Parameters:
 
int vh;                 View-object handle (R)
float *ax1_coord;       Returns the axis 1 coordinate (current mapping) 
                        (W)
float *ax2_coord;       Returns the axis 2 coordinate (current mapping) 
                        (W)
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.6.2.18 Reset active strip message - xdl_graph_win_input_message
 
The routine xdl_graph_win_input_message  (xdlf_graph_win_input_message)  is
used to reset the message which will appear in the active strip when cursor
input is requested. When the graphics window view-object  is  created,  the
default message is 'Input position'.
 
Fortran call:
 
         CALL XDLF_GRAPH_WIN_INPUT_MESSAGE (IVH, XDLSTR(MESSAGE), 
        +                                    LEN, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
MESSAGE  (R)  Character string containing the message 
              (see message)
              ** Pass address using the XDLSTR function **
LEN      (R)  Length of the message string - must be >0 
              (cf len) (max 60 chars) 
IERR     (W)  Returns status from xdl_graph_win_input_message 
              call
 
 
'C' call:
 
int xdl_graph_win_input_message (int vh, char * message, int len)
 
 
Parameters:
 
int vh;          View-object handle (R)
char *message;   Message string (max of 60 chars long) (R)
int len;         Length of the message string; if 0 then length 
                 will be found assuming a null terminated string 
                 (R)

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.6.2.19 Reset current group id - xdl_graph_win_setid
 
The routine xdl_graph_win_setid (xdlf_graph_win_setid) is used to reset the
current value of the graphics objects group id. This id is associated  with
each graphics object drawn and enables selected sets of graphics objects to
be deleted or moved under program control if required. The default starting
id is 1. The valid range is from 1 to 127.
 
Fortran call:
 
         CALL XDLF_GRAPH_WIN_SETID (IVH, ID, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
ID       (R)  Graphics objects group id (1 to 127)
IERR     (W)  Returns status from xdl_graph_win_setid call
 
 
'C' call:
 
int xdl_graph_win_setid (int vh, int id)
 
 
Parameters:
 
int vh;          View-object handle (R)
int id;          New value for graphics objects group id (1-127) (R)

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set:  Invalid group id (not in range 1-127)
 
 
2.6.2.20 Delete graphics objects - xdl_graph_win_delete
 
The routine xdl_graph_win_delete (xdlf_graph_win_delete) is used to  delete
a set of drawn graphics objects identified by the current graphics  objects
group id in force when the objects were drawn. A value of zero  clears  all
graphics objects.
 
Fortran call:
 
         CALL XDLF_GRAPH_WIN_DELETE (IVH, ID, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
ID       (R)  The id of the group of graphics objects to be 
              deleted (0=all)
IERR     (W)  Returns status from xdl_graph_win_delete call
 
 
'C' call:
 
int xdl_graph_win_delete (int vh, int id)
 
 
Parameters:
 
int vh;          View-object handle (R)
int id;          The id of the group of graphics objects to be deleted
                 (1-127) or 0 to delete all (R)

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set:  Invalid id (not in range 0-127)
 
 
2.6.2.21 Calculate size requirements - xdl_graph_win_getsize
 
The routine xdl_graph_win_getsize (xdlf_graph_win_getsize) is used  to  get
the required size for a graphics window view-object given the size  of  the
graphics area required.
 
Fortran call:
 
         CALL XDLF_GRAPH_WIN_GETSIZE (IGWIDTH, IHEIGHT, IWIDTH, 
        +                             IHEIGHT)
 
 
Parameters:
 
IGWIDTH   (R)   Width of graphics area in pixels
IGHEIGHT  (R)   Height of graphics area in pixels
IWIDTH    (W)   Returns the width required (see w)
IHEIGHT   (W)   Returns the height required (see h)
 
 
'C' call:
 
void xdl_graph_win_getsize (int gr_width, int gr_height, int * w, int * h)
 
 
Parameters:
 
int       gr_width;       Required width of graphics area in pixels 
                          (R)
int       gr_height;      Required height of graphics area in 
                          pixels (R)
int *w;                   Returns the width required (W)
int *h;                   Returns the height required (W)

 
 
Return:  None
 
 

2.7 THE POP-UP NOTICE VIEW-OBJECT ROUTINES
==========================================


2.7.1 INTRODUCTION
 
The pop-up notice view-object is used to bring important information to the
user's attention. The program will only proceed after the user has selected
one of the buttons displayed within the notice. It  is  typically  used  to
indicate error  conditions  or  to  request  confirmation  for  a  possibly
dangerous choice made by the user.  The  notice  may  contain  one  or  two
messages and may have one or two buttons.
 
The following sets of routines are available:
 
   Create and Handle a Pop-up Notice View-Object
 
2.7.2 CREATE AND HANDLE A POP-UP NOTICE VIEW-OBJECT
 
2.7.2.1 Introduction
 
The following routines are available:
 
   Display a pop-up notice - xdl_popup_notice
 
2.7.2.2 Display a pop-up notice - xdl_popup_notice
 
The routine xdl_popup_notice  (xdlf_popup_notice)  is  used  to  display  a
pop-up notice containing one or two messages and wait till its  button  (or
one of it's two buttons) is 'pressed'.  Note  that  the  pop-up  notice  is
rather different from other view-objects in that it is a  temporary  object
and does not have a view-object handle.
 
Fortran call:
 
         CALL XDLF_POPUP_NOTICE (IXROOT, IYROOT, MSG1, LENMSG1, 
        +                        MSG2, LENMSG2,
        +                        BUTSTR1, LENBUTSTR1, 
        +                        BUTSTR2, LENBUTSTR2,
        +                        IFONT, IARROW, IBUTTON)
 
 
Parameters:
 
IXROOT    (R)  X (rootwindow) position for notice (top left) 
               (see xroot)
IYROOT    (R)  Y (rootwindow) position for notice (top left)
               (see yroot)
MSG1      (R)  Address of character string containing first
               message.
               ** Pass address using the XDLSTR function **
               (see msg1)
LENMSG1   (R)  Length of the MSG1 character string (>0) 
               (cf lenmsg1)
MSG2      (R)  Address of character string containing second 
               message.
               ** Pass address using the XDLSTR function **
               (see msg2)
LENMSG2   (R)  Length of the MSG2 character string (>0). If 
               there is no second message to output then give 
               a value of -1. (cf lenmsg2)
BUTSTR1   (R)  Address of character string for the first button
               ** Pass address using the XDLSTR function **
               (see butstr1)
LENBUTSTR1 (R) Length of the BUTSTR1 character string (>0) 
               (cf lenbutstr1)
BUTSTR2   (R)  Address of character string for the second button
               ** Pass address using the XDLSTR function **
               (see butstr2)
LENBUTSTR2 (R) Length of the BUTSTR2 character string (>0). If no
               second button is required then give a value of -1.
               (cf lenbutstr2)
IFONT     (R)  Font type (1 to 5, very small to extra large) 
               (see font_type)
IARROW    (R)  =1 display an arrow pointing to the top left corner
               of the notice provided that it can be placed in the
               requested position, =0 do not. (see arrow)
IBUTTON   (W)  Returns the button number selected (1 or 2)
 
 
'C' call:
 
int xdl_popup_notice (xroot, yroot, msg1, lenmsg1, msg2, lenmsg2, 
                      butstr1, lenbutstr1, butstr2, lenbutstr2, 
                      font_type, arrow)
 
 
Parameters:
 
int xroot;          /* x position of the notice popup area 
                       (wrt root) (R)*/
int yroot;          /* y position of the notice popup area 
                       (wrt root) (R)*/
char * msg1;        /* First message (null terminated) string (R)*/
int lenmsg1;        /* Length of message 1. If 0 then the routine will
                       find the length assuming a null terminated 
                       string (R)*/
char * msg2;        /* Second message (null terminated) string - may be 
                       null if no second message required (R)*/
int lenmsg2;        /* Length of message 2. -1 if no second message. 
                       If 0 then the routine will find the length 
                       assuming a null terminated string. (R)*/
char * butstr1;     /* Label string for first button (null terminated) 
                       (R)*/
int lenbutstr1;     /* Length of button 1 string. If 0 then the routine 
                       will find the length assuming a null terminated 
                       string (R)*/
char * butstr2;     /* Label string for second button (null terminated) - 
                       may be null if only one button required (R)*/
int lenbutstr2;     /* Length of button 2 string. -1 if no second button. 
                       If 0 then the routine will find the length assuming 
                       a null terminated string. (R)*/
int font_type;      /* Font type 1 to 5, very-small to extra-large (R)*/
int arrow;          /* =1 draw arrow pointing to origin (provided that
                       notice may be positioned where requested), =0 do
                       not (R)*/
 
 
Return:  =1 button one from notice presssed, 
         =2 button two from notice pressed
 
 

2.8 THE POP-UP DIALOGUE BOX ROUTINES
====================================


2.8.1 INTRODUCTION
 
The pop-up dialog box view-object is used to request the immediate input of
a text string in response to a prompt. The program will only proceed  after
the user has input a reply (or pressed the Escape key to abort the  input).
It is typically used to input information such as a file name. If possible,
the use of this view-object should be avoided as it 'grabs the keyboard and
the pointer' and alternatives such as a control view-object  with  a  Panel
I/O item should be considered.
 
The following sets of routines are available:
 
   Creating and Handling a Pop-up Dialogue Box View-Object
 
2.8.2 CREATING AND HANDLING A POP-UP DIALOGUE BOX VIEW-OBJECT
 
2.8.2.1 Introduction
 
The following routines are available:
 
   Display a pop-up dialog box - xdl_popup_dialog
 
2.8.2.2 Display a pop-up dialog box - xdl_popup_dialog
 
The routine xdl_popup_dialog  (xdlf_popup_dialog)  is  used  to  display  a
pop-up dialog box containing a prompt and to wait till a reply is input (or
the Escape key is pressed to abort the input). Note that the pop-up  dialog
box is rather different from most  other  view-objects  in  that  it  is  a
temporary object and does not have a view-object handle.
 
Fortran call:
 
         CALL XDLF_POPUP_DIALOG (IXROOT, IYROOT, PROMPT, LENP, 
        +                        IWIDTH,
        +                        REPLY, LENR,
        +                        IFONT, IARROW, IRETURN)
 
 
Parameters:
 
IXROOT    (R)  X (rootwindow) position for dialog (top left) 
               (see xroot)
IYROOT    (R)  Y (rootwindow) position for dialog (top left)
               (see yroot)
PROMPT    (R)  Address of character string containing the prompt.
               ** Pass address using the XDLSTR function **
               (see prompt)
LENP      (R)  Length of the PROMPT character string (>0) 
               (cf lenp)
IWIDTH    (R)  Width of box as the number of characters in
               the prompt string + the number to be displayed
               in the reply string (note: the reply string can 
               be scrolled using the cursor left and right keys)
               (see width)
REPLY     (W)  Address of character string to contain the reply
               message.
               ** Pass address using the XDLSTR function **
               (see reply)
MAXLEN    (R)  Maximum length for the returned reply string (>0).
               (cf max_len)
IFONT     (R)  Font type (1 to 5, very small to extra large) 
               (see font_type)
IBOLD     (R)  =0 Prompt and input string in normal text
               =1 Prompt bold, input string normal
               =2 Prompt normal, input string bold
               =3 Both strings bold
               (see bold)
IARROW    (R)  =1 display an arrow pointing to the top left corner
               of the dialog box provided that it can be placed 
               in the requested position, =0 do not. (see arrow)
IRETURN   (W)  Return flag = 0 Blank string
                           = 1 String returned (non-blank)
                           =-1 Input aborted (via Escape key)
                           =-2 Unable to allocate memory for
                               temporary input string
                           =-3 No room for an input string
 
 
'C' call:
 
int xdl_popup_dialog (xroot, yroot, prompt, lenp, width, reply, max_len, 
                      font_type, bold, arrow)
 
 
Parameters:
 
int xroot;          /* x position of the dialog popup area 
                       (wrt root) (R)*/
int yroot;          /* y position of the dialog popup area 
                       (wrt root) (R)*/
char * prompt;      /* Prompt string (R)*/
int lenp;           /* Length of prompt string. If 0 then the routine will
                       find the length assuming a null terminated 
                       string (R)*/
int width;          /* Width of box as the number of characters in
                       the prompt string + the number to be displayed
                       in the reply string (note: the reply string can 
                       be scrolled using the cursor left and right keys)
                       (R)*/
char * reply;       /* Address for returned string (W)*/
int max_len;        /* if >0 Maximum length of return string allowed
                             (excluding terminating null - reply must be
                             at least max_len+1 characters in length)
                       if <0 abs(max_len) characters will be returned
                             padded with blanks if needed (for 'fortran'
                             use) (R)*/
int font_type;      /* Font type 1 to 5, very-small to extra-large (R)*/
int bold;           /*  =0 Prompt and input string in normal text
                        =1 Prompt bold, input string normal
                        =2 Prompt normal, input string bold 
                        =3 Both strings bold  (R)*/
int arrow;          /* =1 draw arrow pointing to origin (provided that
                       dialog may be positioned where requested), =0 do
                       not (R)*/
 
 
Return:  = 0,  Blank reply
         = 1,  Text string was input
         =-1,  Input aborted
         =-2,  Unable to allocate memory for temporary input string
         =-3,  No room for an input string
 
 

2.9 THE POP-UP MENU VIEW-OBJECT ROUTINES
========================================


2.9.1 INTRODUCTION
 
The pop-up menu view-object is used to request the immediate  input  of  an
option via a popup menu. The program will only proceed after the  user  has
selected an option or cancelled the menu.
 
The following sets of routines are available:
 
   Creating and Handling a Pop-up Menu View-Object
 
2.9.2 CREATING AND HANDLING A POP-UP MENU VIEW-OBJECT
 
2.9.2.1 Introduction
 
The following routines are available:
 
   Display a pop-up menu - xdl_popup_menu
 
2.9.2.2 Display a pop-up menu - xdl_popup_menu
 
The routine xdl_popup_menu (xdlf_popup_menu) is used to  display  a  pop-up
menu containing a set of user selectable options. Note that the pop-up menu
is rather different from most other view-objects in that it is a  temporary
object and does not have a view-object handle.
 
If Button1 or Button3 held down when menu popped up then:

     a) First release of the button on the menu selects item.

     b) First release of the button off the menu leaves menu displayed.

        then 1) Click Button1 or Button3 on the menu to select item.

             2) Click Button1 or Button3 off the menu to dismiss menu.

If Button1 and Button3 are up when the menu is popped up then

    a) Click Button1 or Button3 on the menu to select item.

    b) Click Button1 or Button3 off the menu to dismiss menu.

 
 
Fortran call:
 
         CALL XDLF_POPUP_MENU (IXROOT, IYROOT, NITEMS, XDLSTR(STRNGS),
        +                      LENS, IFONT, IBRDR, ICENT, ITEM)
 
 
Parameters:
 
IXROOT    (R)  X (rootwindow) position for menu (top left) 
               (see xroot)
IYROOT    (R)  Y (rootwindow) position for menu (top left)
               (see yroot)
NITEMS   (R)   Number of menu items in the menu (see num_items)
STRNGS   (R)   Fortran array of character strings containing the
               menu item strings.
               [CHARACTER*LENS STRNGS(NITEMS)].
               ** Pass address using XDLSTR function **
               (see strings)
LENS     (R)   Length of the menu item character strings
               (must be >0 cf len_strs)
IFONT    (R)   Font type (1->5 verysmall->extralarge)
               (see font_type)
IBRDR    (R)   =0, no coloured border added (just a narrow black
                   border will be drawn)
               =1, Red border
               =2, Yellow border
               =3, Green border
               =4, Cyan border
               =5, Blue border (Preferred option when border used)
               =6, Magenta border 
               (see brdr_colr)
ICENT    (R)   =1, centre menu text strings
               =0, do not (strings will be left justified)
               (see cent)
ITEM     (W)   =0, no item selected
               >0, selected menu item number (1 to NITEMS)
               (the return from xdl_popup_menu)
 
 
'C' call:
 
int xdl_popup_menu (xroot, yroot, num_items, strings, len_strs, 
                    font_type, brdr_colr, cent)
 
 
Parameters:
 
int xroot;          /* x position of the menu popup area 
                       (wrt root) (R)*/
int yroot;          /* y position of the menu popup area 
                       (wrt root) (R)*/
int num_items;      /* Number of strings in the menu (R)*/
char * strings;     /* Menu item strings - this may either be an array of
                       pointers to num_items null terminated character
                       strings (len_strs=0) or a character string 
                       num_items*len_strs in length with each string
                       occupying len_strs characters (left justified and
                       padded to the right with blanks if needed). (R)*/
int len_strs;       /* Strings length (0 = array of pointers to
                       null terminated character strings (e.g. for 'C'
                       programs) or the length of each string 
                       (e.g. for Fortran programs). See also the previous
                       item. (R) */
int font_type;      /* Font type (1-5) for very-small, small, medium,
                       large or Extra-large font (R)*/
int brdr_colr;      /* =0, no coloured border added (just a narrow black
                           border will be drawn)
                       =1, Red border
                       =2, Yellow border
                       =3, Green border
                       =4, Cyan border
                       =5, Blue border (Preferred option when border used)
                       =6, Magenta border (R)*/
int cent;           /* =1, centre menu text strings
                       =0, do not (strings will be left justified)
                       (R)*/
 
 
Return:  = 0,  No item selected
         > 0,  The selected item number
 
 

2.10 THE POP-UP FRAME VIEW-OBJECT ROUTINES
==========================================


2.10.1 INTRODUCTION
 
The popup frame view-object is just an empty 'top level'  window  on  which
other view-objects may be laid out. As it is a popup window, there will  be
no added frame etc. by the window manager. The window will have an external
black border 1 pixel thick and, optionally, an internal coloured  border  4
pixels thick. A popup window cannot be moved or resized and should normally
only be used in an essentially temporary  fashion.  (Note:  Only  one  such
popup frame must be used  at  a  time;  Pointer  and  Keyboard  events  are
reported only to the client creating the popup frame while it is displayed)
 
The following sets of routines are available:
 
   Creating and Handling a Pop-up Frame View-Object
 
2.10.2 CREATING AND HANDLING A POP-UP FRAME VIEW-OBJECT
 
2.10.2.1 Introduction
 
The following routines are available:
 
   Create a popup frame view-object - xdl_popup_frame
 
2.10.2.2 Create a popup frame view-object - xdl_popup_frame
 
The routine xdl_popup_frame (xdlf_popup_frame) is  used  to  create  a  new
popup frame view-object. The position, size and border requirements of  the
frame are specified.
 
Fortran call:
 
         CALL XDLF_POPUP_FRAME (IVH, IXROOT, IYROOT, IWIDTH, IHEIGHT, 
        +                      IBRDR)
 
 
Parameters:
 
IVH        (R)  View-object handle (see vh)
IXROOT     (R)  X (rootwindow) position for frame (top left)
                (see xroot)
IYROOT     (R)  Y (rootwindow) position for frame (top left)
                (see yroot)
IWIDTH     (R)  Frame width (including internal border) 
                (see width)
IHEIGHT    (R)  Frame height (including internal border)
                (see height)
IBRDR      (R)  =0 No internal coloured (just an external 1 
                   pixel width black border)
                =1 Internal Red border (4 pixels wide)
                =2 Internal Yellow border (4 pixels wide)
                =3 Internal Green border (4 pixels wide)
                =4 Internal Cyan border (4 pixels wide)
                =5 Internal Blue border (4 pixels wide)
                   (preferred option if frame used for
                    a temporary menu, parameter table etc.)
                =6 Internal Magenta border (4 pixels wide)
                   (see brd_colr)
 
 
'C' call:
 
void xdl_popup_frame (vh, xroot, yroot, width, height, brdr_colr)
 
 
Parameters:
 
int vh;             /* User selected view-object handle (R)*/
int xroot;          /* x position of the popup frame (wrt Root)
                       (May be adjusted to get frame within display) (R)*/
int yroot;          /* y position of the popup frame (wrt Root)
                       (May be adjusted to get frame within display) (R)*/
int width;          /* Frame width (including any internal border but
                       excluding the external border of width 1 pixel)
                       (R)*/
int height;         /* Frame height (including any internal border but
                       excluding the external border of height 1 pixel)
                       (R)*/
int brdr_colr;      /* =0 No internal coloured (just an external 1 
                          pixel width black border)
                       =1 Internal Red border (4 pixels wide)
                       =2 Internal Yellow border (4 pixels wide)
                       =3 Internal Green border (4 pixels wide)
                       =4 Internal Cyan border (4 pixels wide)
                       =5 Internal Blue border (4 pixels wide)
                          (preferred option if frame used for
                           a temporary menu, parameter table etc.)
                       =6 Internal Magenta border (4 pixels wide) (R)*/

 
 
Return:  None
 
 

2.11 THE PROGRESS BAR VIEW-OBJECT
=================================


2.11.1 INTRODUCTION
 
The progress bar view-object is used to indicate the  progress  of  a  time
consuming operation e.g. reading in of a large file or performing a lengthy
calculation. The progress bar is a window containing a title  and  the  bar
itself. The bar starts a an empty rectangle which is  gradually  filled  in
colour (or black on a black and white display) as the  operation  proceeds.
The program needs to be able to pass the current degree of progress to  the
view-object at reasonably frequent intervals for its use to be effective.
 
The following sets of routines are available:
 
   Create and Handle a Progress Bar View-Object
 
2.11.2 CREATE AND HANDLE A PROGRESS BAR VIEW-OBJECT
 
2.11.2.1 Introduction
 
The following routines are available:
 
   Create a progress bar view-object - xdl_progress_bar
   Set the current value - xdl_progress_bar_value
 
2.11.2.2 Create a progress bar view-object - xdl_progress_bar
 
The routine  xdl_progress_bar  (xdlf_progress_bar)  is  used  to  create  a
progress bar view-object.
 
Fortran call:
 
         CALL XDLF_PROGRESS_BAR (IVH, IXROOT, IYROOT, 
        +                        XDLSTR(TITLE), ITLEN,
        +                        IND_LEN, MAX_VAL, IFONT, ICOLR)
 
 
Parameters:
 
IVH        (R)  View-object handle (see vh)
IXROOT     (R)  Root x position for the window (see xroot)
IYROOT     (R)  Root y position for the window (see yroot)
TITLE      (R)  Fortran character string containing the title
                ** Pass address using the XDLSTR function **
                (cf title)
ITITL      (R)  The title length (> 0) (cf title_len)
IND_LEN    (R)  Length of the 'indicator bar' in pixels 
                (see ind_len)
MAX_VAL    (R)  Maximum value indicating completion (see max_val)
IFONT      (R)  Font type 1 to 5 very-small to extra-large (see 
                font_type)
ICOLR      (R)  Colour type 1 to 6 for red, yellow, green, cyan, 
                blue, magenta (see colr)
 
 
'C' call:
 
void xdl_progress_bar (vh, xroot, yroot, title, title_len, ind_len, 
                       max_val, font_type, colr)
 
 
Parameters:
 
int vh;             /* User selected view-object handle (R)*/
int xroot;          /* x root position for top left of window (may be
                       repositioned if necessary) (R) */
int yroot;          /* y root position for top left of window (may be
                       repositioned if necessary) (R) */
char * title;       /* Title string (R)*/
int title_len;      /* The length of the title string; if the string is
                       null terminated then 0 may be given and the 
                       program will determine the string length (R)*/
int ind_len;        /* Length of the indicator bar in pixels. This will
                       start as an open bar which will be filled up as
                       values indicating progress are supplied (R)*/
int max_val;        /* The maximum value which indicates completion of the 
                       task (R)*/
int font_type;      /* Font type 1 to 5 very-small to extra-large */
int colr;           /* Colour type for filling the indicator bar (if 
                       colour available) 1 to 6 for Red, Yellow, Green, 
                       Cyan, Blue, Magenta (R)*/
/*
     Note: Calls xdl_flush_events to enable initial painting.
*/
 
 
Return:  None
 
 
2.11.2.3 Set the current value - xdl_progress_bar_value
 
The routine xdl_progress_bar_value  (xdlf_progress_bar_value)  is  used  to
pass the value indicating the current state of progress to the progress bar
view-object. It must be called  at  reasonably  frequent  intervals  to  be
effective. Note that each call also calls xdl_flush_events which  therefore
need not be called during a time consuming process monitored by  using  the
progress bar as described.
 
Fortran call:
 
         CALL XDLF_PROGRESS_BAR_VALUE (IVH, IVAL, IERR)
 
 
Parameters:
 
IVH    (R)   View-object handle (see vh)
IVAL   (R)   The current value (see value)
IERR   (W)   The return from the xdl_progress_bar_value call
 
 
'C' call:
 
int xdl_progress_bar_value (vh, value)
 
 
Parameters:
 
int vh;          /* View-object handle for the progress bar object (R)*/
int value;       /* The current value indicating the progress (up to the
                    max_val value passed to xdl_progress_bar) (R)*/
/*
   Note: Calls xdl_flush_events on each valid call.
*/
 
 
Return:  = 0 OK, >0 error
           bit 0 set: View-object handle not found
           bit 1 set: View handle does not match view object;
 
 

2.12 THE CONTROL PANEL ITEMS VIEW-OBJECT ROUTINES
=================================================


2.12.1 INTRODUCTION
 
The control panel view-objects give  access  from  an  application  to  the
individual Panel Items within XDL_VIEW (Panel choice, button, slider etc.).
The documentation on these items should be used in  conjunction  with  this
documentation. For those items which  have  an  input  to  the  application
program, an active strip may be included within the control item and should
be used where possible to fit in with the general philosophy  of  input  to
application programs via XDL_VIEW view-objects.
 
The following sets of routines are available:
 
   Panel Choice Item Routines
   Panel Button Item Routines
   Panel Label Item Routines
   Panel Value Item Routines
   Panel Slider Item Routines
   Panel I/O Item Routines
 
2.12.2 PANEL CHOICE ITEM ROUTINES
 
2.12.2.1 Introduction
 
These are routines for creating an  handling  a  view-object  containing  a
panel choice item.
 
 
The following routines are available:
 
   View_object with a Panel Choice Item - xdl_control_choice
   Reset selected choice - xdl_control_choice_reset
   Get selected item number - xdl_control_choice_getdata
   Get required size - xdl_control_choice_getzize
 
2.12.2.2 View_object with a Panel Choice Item - xdl_control_choice
 
The routine xdl_control_choice (xdlf_control_choice) is used  to  create  a
view object containing a Panel Choice item (See Panel  Item  Routines).  An
active strip may be displayed if desired.
 
Fortran call:
 
         CALL XDLF_CONTROL_CHOICE (IVH, IVHPARENT, IX, IY, IACT,
        +                          IHCEN, IVCEN, IFONT, IBRDR,
        +                          XDLSTR(LABEL), LLEN,
        +                          NITEMS, XDLSTR(STRINGS), LENSTRS,
        +                          IDFITEM, MSG, LENMSG,
        +                          MINW, MINH,IERR)
 
 
Parameters:
 
IVH       (R)   View-object handle (see vh)
IVHPARENT (R)   View-object handle for parent 0=none 
                (see vh_parent)
IX        (R)   X position (may be -1 if no parent) (see x)
IY        (R)   Y position (may be -1 if no parent) (see y)
IACT      (R)   Display active strip flag 1=yes, 0=no (see
                act_strip)
IHCEN     (R)   =1 Centre panel item horizontally, = 0 do
                not (left justify instead) (see hcen)
IVCEN     (R)   =1 Centre panel item vertically, = 0 do
                not (top justify instead) (see vcen)
IFONT     (R)   Font type (1-5) very small to very large (see
                font_type)
IBRDR     (R)   Flag =1 border, =0 no border (see brdr)
LABEL     (R)   Address of label string for panel choice.
                ** Pass address using the XDLSTR function **
LLEN      (R)   Length of the label string (>0)
NITEMS    (R)   No. of panel choice item strings (see
                num_items)
STRINGS   (R)   Fortran array of character strings cotaining
                the panel choice item strings.
                [CHARACTER*LENSTRS STRINGS(NITEMS)].
                ** Pass address using XDLSTR function **
                (see strings)
LENSTRS   (R)   Length of the panel choice item strings
                (>0 (see len_strs)
IDFITEM   (R)   Default item number (see df_item)
MSG       (R)   Address of character string for active strip
                message. May be a blank string if IACT = 0.
                ** Pass address using XDLSTR function **
                (see msg)
LENMSG    (R)   Length of active strip message string (>0)
                (see len_msg)
MINW      (R)   Minimum width required (may be 0) 
MINH      (R)   Minimum height required (may be 0)
IERR      (W)   Returns status from xdl_control_choice call
 
 
'C' call:
 
int xdl_control_choice (vh, vh_parent, x, y, act_strip, hcen, vcen,
                        font_type, brdr, label, llen, 
                        num_items, strings, len_strs, 
                        df_item, msg, len_msg, minw, minh)
 
 
Parameters:
 
int       vh;             /* User selected view-object handle (R)*/
int       vh_parent;      /* View-object handle for the parent base frame, 
                             if 0 then a base  level frame is created to
                             enclose the view-object (R)*/
int       x;              /* x coordinate for the view-object.
                             If no parent may be -1 to give default x (R)*/
int       y;              /* y coordinate for the view-object.
                             If no parent may be -1 to give default y (R)*/
int       act_strip;      /* Display active strip flag 1=yes, 0=no (R)*/
int       hcen;           /* =1 Centre panel item horizontally, = 0 do
                             not (left justify instead) (R)*/
int       vcen;           /* =1 Centre panel item vertically, = 0 do
                             not (top justify instead) (R)*/
int       font_type;      /* Font type (1-5) very small to very large (R)*/
int       brdr;           /* Flag =1 border, =0 no border to be drawn round
                             panel item (R)*/
char    * label;          /* Label string (R)*/
int       llen;           /* Label length, may be 0 if null terminated
                             string passed (R)*/
int       num_items;      /* No. of panel choice item strings (R) */
char    * strings;        /* Panel choice item strings. This may 
                             either be an array of pointers to num_items 
                             null terminated character strings (len_strs=0)
                             or a character string num_items*len_strs in 
                             length with each string occupying len_strs 
                             characters (left justified and padded to the 
                             right with blanks if needed). (R)*/
int       len_strs;       /* Strings length (0 = array of pointers to
                             null terminated character strings (e.g. for 
                             'C' programs) or the length of each string 
                             (e.g. for Fortran programs). See also the 
                             previous item. (R) */
int       df_item;        /* Default item number (R)*/
char    * msg;            /* Message for active strip, may be null if
                             no active strip required (R)*/
int       len_msg;        /* Length of active strip message string; may
                             be 0 is a null terminated string given for
                             msg (R)*/
int minw;                 /* Minimum width required (may be 0) (R)*/
int minh;                 /* Minimum height required (may be 0) (R)*/
 
 
Return:  Status flag =0 OK, >0 error
         bit 0 set: Requested parent not found in the view-objects list
         bit 1 set: Cannot allocate memory required
 
 
2.12.2.3 Reset selected choice - xdl_control_choice_reset
 
The routine xdl_control_choice_reset (xdlf_control_choice_reset) is used to
reset the selecte item number for a control Panel Choice view-object.
 
Fortran call:
 
         CALL XDLF_CONTROL_CHOICE_RESET (IVH, ITEM, IERR)
 
 
Parameters:
 
IVH       (R)  View-object handle (see vh)
ITEM      (R)  New selected item number
IERR      (W)  Returns status from xdl_control_choice_reset call
 
 
'C' call:
 
int xdl_control_choice_reset (vh, item)
 
 
Parameters:
 
int vh;                   /* View-object handle (R)*/
int item;                 /* Rest item number (R)*/
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.12.2.4 Get selected item number - xdl_control_choice_getdata
 
The  routine  xdl_control_choice_getdata  (xdlf_control_choice_getdata)  is
used to determine the selected item number after a return from an  XDL_VIEW
event handling routine such as xdl_get_events  (xdlf_get_events)  indicates
that there was input from the view-object in question.
 
Fortran call:
 
         CALL XDLF_CONTROL_CHOICE_GETDATA (IVH, ITEM, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
ITEM     (W)  Selected choice item number
IERR     (W)  Returns status from xdl_control_choice_getdata call
 
 
'C' call:
 
int xdl_control_choice_getdata (vh, item)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int *item;       /* Returns selected item number (W)*/
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.12.2.5 Get required size - xdl_control_choice_getzize
 
The  routine  xdl_control_choice_getsize  (xdlf_control_choice_getsize)  is
used to determine the required size for a control view-object containing  a
Panel Choice Item given various details about the requirements of the item.
 
Fortran call:
 
         CALL XDLF_CONTROL_CHOICE_GETSIZE (IACT, IFONT, IBRDR,
        +                          LLEN, LENSTRS, IWIDTH, IHEIGHT)
 
 
Parameters:
 
IACT      (R)   =1 include active strip, =0 do not
IFONT     (R)   Font type (1-5) very small to very large (see
                font_type)
IBRDR     (R)   Flag =1 border, =0 no border (see brdr)
LLEN      (R)   Length of the label string (>0)
LENSTRS   (R)   Length (maximum) of the panel choice item 
                strings (>0 (see len_strs)
IWIDTH    (W)   Width required for view-object
IHEIGHT   (W)   Height required for view-object
 
 
'C' call:
 
void xdl_control_choice_getsize (act_strip, font_type, brdr, llen,
                                 len_strs, width, height)
 
 
Parameters:
 
int       act_strip;      /* Display active strip flag 1=yes, 0=no (R)*/
int       font_type;      /* Font type (1-5) very small to very large (R)*/
int       brdr;           /* Flag =1 border, =0 no border to be drawn round
                             panel item (R)*/
int       llen;           /* Required label length (>0) (R)*/
int       len_strs;       /* Panel choice strings length (maximum) 
                             (>0) (R)*/
int     * width;          /* Returns the required width in pixels (W)*/
int     * height;         /* Returns the required height in pixels (W)*/
 
 
Return:  None
 
 
2.12.3 PANEL BUTTON ITEM ROUTINES
 
2.12.3.1 Introduction
 
These are routines for creating an  handling  a  view-object  containing  a
panel button item.
 
 
The following routines are available:
 
   View_object with a Panel Button Item - xdl_control_button
   Set new label string - xdl_control_button_set
   Get required size - xdl_control_button_getzize
 
2.12.3.2 View_object with a Panel Button Item - xdl_control_button
 
The routine xdl_control_button (xdlf_control_button) is used  to  create  a
view object containing a Panel Button item (See Panel  Item  Routines).  An
active strip may be displayed if desired.
 
Fortran call:
 
         CALL XDLF_CONTROL_BUTTON (IVH, IVHPARENT, IX, IY, IACT,
        +                          IHCEN, IVCEN, IFONT, IBRDR,
        +                          XDLSTR(LABEL), LLEN, MAXLEN,
        +                          XDLSTR(MSG), LENMSG,
        +                          IBOLD, ICENT,
        +                          MINW, MINH,IERR)
 
 
Parameters:
 
IVH       (R)   View-object handle (see vh)
IVHPARENT (R)   View-object handle for parent 0=none 
                (see vh_parent)
IX        (R)   X position (may be -1 if no parent) (see x)
IY        (R)   Y position (may be -1 if no parent) (see y)
IACT      (R)   Display active strip flag 1=yes, 0=no (see
                act_strip)
IHCEN     (R)   =1 Centre panel item horizontally, = 0 do
                not (left justify instead) (see hcen)
IVCEN     (R)   =1 Centre panel item vertically, = 0 do
                not (top justify instead) (see vcen)
IFONT     (R)   Font type (1-5) very small to very large (see
                font_type)
IBRDR     (R)   Button border width (>0)
LABEL     (R)   Address of label string for panel choice.
                ** Pass address using the XDLSTR function **
LLEN      (R)   Length of the label string (>0)
MAXLEN    (R)   Maximum length to allow for a label string
                (label may be changed)
MSG       (R)   Address of character string for active strip
                message. May be a blank string if IACT = 0.
                ** Pass address using XDLSTR function **
                (see msg)
LENMSG    (R)   Length of active strip message string (>0)
                (see len_msg)
IBOLD     (R)   = 1 bold print, = 0 normal print for label
ICENT     (R)   = 1 centre label in button, = 0 do not
MINW      (R)   Minimum width required (may be 0) 
MINH      (R)   Minimum height required (may be 0)
IERR      (W)   Returns status from xdl_control_button call
 
 
'C' call:
 
int xdl_control_button (vh, vh_parent, x, y, act_strip, hcen, vcen,
                        font_type, brdr, label, llen, maxlen,
                        msg, len_msg,
                        bold, cent, minw, minh)
 
 
Parameters:
 
int       vh;             /* User selected view-object handle (R)*/
int       vh_parent;      /* View-object handle for the parent base frame, 
                             if 0 then a base  level frame is created to
                             enclose the view-object (R)*/
int       x;              /* x coordinate for the view-object.
                             If no parent may be -1 to give default x (R)*/
int       y;              /* y coordinate for the view-object.
                             If no parent may be -1 to give default y (R)*/
int       act_strip;      /* Display active strip flag 1=yes, 0=no (R)*/
int       hcen;           /* =1 Centre panel item horizontally, = 0 do
                             not (left justify instead) (R)*/
int       vcen;           /* =1 Centre panel item vertically, = 0 do
                             not (top justify instead) (R)*/
int       font_type;      /* Font type (1-5) very small to very large (R)*/
int       brdr;           /* Border width for the button (>0) (R)*/
char    * label;          /* Label string (R)*/
int       llen;           /* Label length, may be 0 if null terminated
                             string passed (R)*/
int       maxlen;         /* Maximum length required for a label (button
                             label may be reset (R)*/
char    * msg;            /* Message for active strip, may be null if
                             no active strip required (R)*/
int       len_msg;        /* Length of active strip message string; may
                             be 0 is a null terminated string given for
                             msg (R)*/
int       bold;           /* = 1 bold print, = 0 normal print for label
                             (R)*/
int       cent;           /* = 1 centre label in button, = 0 do not (R)*/
int minw;                 /* Minimum width required (may be 0) (R)*/
int minh;                 /* Minimum height required (may be 0) (R)*/
 
 
Return:  Status flag =0 OK, >0 error
         bit 0 set: Requested parent not found in the view-objects list
         bit 1 set: Cannot allocate memory required
 
 
2.12.3.3 Set new label string - xdl_control_button_set
 
The routine xdl_control_button_set (xdlf_control_button_set) is used to set
a new label string for a control Panel Button view-object.
 
Fortran call:
 
         CALL XDLF_CONTROL_BUTTON_SET (IVH, XDLSTR(LABEL), LLEN, 
        +                                IBOLD, ICENT, IERR)
 
 
Parameters:
 
IVH       (R)  View-object handle (see vh)
LABEL     (R)  Address of new label string
               ** Pass address using the XDLSTR function **
LLEN      (R)  Length of the label string (>0)
IBOLD     (R)   = 1 bold print, = 0 normal print for label
ICENT     (R)   = 1 centre label in button, = 0 do not
IERR      (W)  Returns status from xdl_control_button_set call
 
 
'C' call:
 
int xdl_control_button_set (vh, label, llen, bold, cent)
 
 
Parameters:
 
int vh;                   /* View-object handle (R)*/
char    * label;          /* Label string (R)*/
int       llen;           /* Label length, may be 0 if null terminated
                             string passed (R)*/
int       bold;           /* = 1 bold print, = 0 normal print for label
                             (R)*/
int       cent;           /* = 1 centre label in button, = 0 do not (R)*/

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.12.3.4 Get required size - xdl_control_button_getzize
 
The  routine  xdl_control_button_getsize  (xdlf_control_button_getsize)  is
used to determine the required size for a control view-object containing  a
Panel Button item given various details about the requirements of the item.
 
Fortran call:
 
         CALL XDLF_CONTROL_BUTTON_GETSIZE (IACT, IFONT, IBRDR,
        +                          MAXLEN, IWIDTH, IHEIGHT)
 
 
Parameters:
 
IACT      (R)   =1 include active strip, =0 do not
IFONT     (R)   Font type (1-5) very small to very large (see
                font_type)
IBRDR     (R)   Required border width (>0)
MAXLEN    (R)   Maximum required length of the label string (>0)
IWIDTH    (W)   Width required for view-object
IHEIGHT   (W)   Height required for view-object
 
 
'C' call:
 
void xdl_control_button_getsize (act_strip, font_type, brdr, maxlen,
                                 width, height)
 
 
Parameters:
 
int       act_strip;      /* Display active strip flag 1=yes, 0=no (R)*/
int       font_type;      /* Font type (1-5) very small to very large (R)*/
int       brdr;           /* Button border width (>0) (R)*/
int       maxlen;         /* maximum required label length (>0) (R)*/
int     * width;          /* Returns the required width in pixels (W)*/
int     * height;         /* Returns the required height in pixels (W)*/
 
 
Return:  None
 
 
2.12.4 PANEL LABEL ITEM ROUTINES
 
2.12.4.1 Introduction
 
These are routines for creating an  handling  a  view-object  containing  a
panel label item.
 
 
The following routines are available:
 
   View_object with a Panel Label Item - xdl_control_label
   Set new label string - xdl_control_label_set
   Get required size - xdl_control_label_getzize
 
2.12.4.2 View_object with a Panel Label Item - xdl_control_label
 
The routine xdl_control_label (xdlf_control_label) is used to create a view
object containing a Panel Label item (See Panel Item Routines).
 
Fortran call:
 
         CALL XDLF_CONTROL_LABEL (IVH, IVHPARENT, IX, IY, 
        +                          IHCEN, IVCEN, IFONT, IBRDR,
        +                          XDLSTR(LABEL), LLEN, MAXLEN,
        +                          IBOLD, MINW, MINH,IERR)
 
 
Parameters:
 
IVH       (R)   View-object handle (see vh)
IVHPARENT (R)   View-object handle for parent 0=none 
                (see vh_parent)
IX        (R)   X position (may be -1 if no parent) (see x)
IY        (R)   Y position (may be -1 if no parent) (see y)
IHCEN     (R)   =1 Centre panel item horizontally, = 0 do
                not (left justify instead) (see hcen)
IVCEN     (R)   =1 Centre panel item vertically, = 0 do
                not (top justify instead) (see vcen)
IFONT     (R)   Font type (1-5) very small to very large (see
                font_type)
IBRDR     (R)   = 1 draw border, =0 do not
LABEL     (R)   Address of label string for panel choice.
                ** Pass address using the XDLSTR function **
LLEN      (R)   Length of the label string (>0)
MAXLEN    (R)   Maximum length to allow for a label string
                (label may be changed)
IBOLD     (R)   = 1 bold print, = 0 normal print for label
MINW      (R)   Minimum width required (may be 0) 
MINH      (R)   Minimum height required (may be 0)
IERR      (W)   Returns status from xdl_control_label call
 
 
'C' call:
 
int xdl_control_label (vh, vh_parent, x, y, hcen, vcen,
                        font_type, brdr, label, llen, maxlen,
                        bold, minw, minh)
 
 
Parameters:
 
int       vh;             /* User selected view-object handle (R)*/
int       vh_parent;      /* View-object handle for the parent base frame, 
                             if 0 then a base  level frame is created to
                             enclose the view-object (R)*/
int       x;              /* x coordinate for the view-object.
                             If no parent may be -1 to give default x (R)*/
int       y;              /* y coordinate for the view-object.
                             If no parent may be -1 to give default y (R)*/
int       hcen;           /* =1 Centre panel item horizontally, = 0 do
                             not (left justify instead) (R)*/
int       vcen;           /* =1 Centre panel item vertically, = 0 do
                             not (top justify instead) (R)*/
int       font_type;      /* Font type (1-5) very small to very large (R)*/
int       brdr;           /* = 1 draw border, = 0 do not (R)*/
char    * label;          /* Label string (R)*/
int       llen;           /* Label length, may be 0 if null terminated
                             string passed (R)*/
int       maxlen;         /* Maximum length required for a label 
                             (label may be reset) (R)*/
int       bold;           /* = 1 bold print, = 0 normal print for label
                             (R)*/
int minw;                 /* Minimum width required (may be 0) (R)*/
int minh;                 /* Minimum height required (may be 0) (R)*/
 
 
Return:  Status flag =0 OK, >0 error
         bit 0 set: Requested parent not found in the view-objects list
         bit 1 set: Cannot allocate memory required
 
 
2.12.4.3 Set new label string - xdl_control_label_set
 
The routine xdl_control_label_set (xdlf_control_label_set) is used to set a
new label string for a control Panel Label view-object.
 
Fortran call:
 
         CALL XDLF_CONTROL_LABEL_SET (IVH, XDLSTR(LABEL), LLEN, 
        +                                IBOLD, IERR)
 
 
Parameters:
 
IVH       (R)  View-object handle (see vh)
LABEL     (R)  Address of new label string
               ** Pass address using the XDLSTR function **
LLEN      (R)  Length of the label string (>0)
IBOLD     (R)   = 1 bold print, = 0 normal print for label
IERR      (W)  Returns status from xdl_control_label_set call
 
 
'C' call:
 
int xdl_control_label_set (vh, label, llen, bold)
 
 
Parameters:
 
int vh;                   /* View-object handle (R)*/
char    * label;          /* Label string (R)*/
int       llen;           /* Label length, may be 0 if null terminated
                             string passed (R)*/
int       bold;           /* = 1 bold print, = 0 normal print for label
                             (R)*/

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.12.4.4 Get required size - xdl_control_label_getzize
 
The routine xdl_control_label_getsize (xdlf_control_label_getsize) is  used
to determine the required size for a control view-object containing a Panel
Label item given various details about the requirements of the item.
 
Fortran call:
 
         CALL XDLF_CONTROL_LABEL_GETSIZE (IFONT, IBRDR,
        +                          MAXLEN, IWIDTH, IHEIGHT)
 
 
Parameters:
 
IFONT     (R)   Font type (1-5) very small to very large (see
                font_type)
IBRDR     (R)   = 1 draw border, = 0 do not
MAXLEN    (R)   Maximum required length of the label string (>0)
IWIDTH    (W)   Width required for view-object
IHEIGHT   (W)   Height required for view-object
 
 
'C' call:
 
void xdl_control_label_getsize (font_type, brdr, maxlen,
                                 width, height)
 
 
Parameters:
 
int       font_type;      /* Font type (1-5) very small to very large (R)*/
int       brdr;           /* = 1 draw border, = 0 do not (R)*/
int       maxlen;         /* maximum required label length (>0) (R)*/
int     * width;          /* Returns the required width in pixels (W)*/
int     * height;         /* Returns the required height in pixels (W)*/
 
 
Return:  None
 
 
2.12.5 PANEL VALUE ITEM ROUTINES
 
2.12.5.1 Introduction
 
These are routines for creating an  handling  a  view-object  containing  a
panel value item.
 
 
The following routines are available:
 
   View_object with a Panel Value Item - xdl_control_value
   Set new value string - xdl_control_value_set
   Get input value string - xdl_control_value_getdata
   Get required size - xdl_control_value_getzize
 
2.12.5.2 View_object with a Panel Value Item - xdl_control_value
 
The routine xdl_control_value (xdlf_control_value) is used to create a view
object containing a Panel Value item (See Panel Item Routines).  An  active
strip may be displayed if desired.
 
Fortran call:
 
         CALL XDLF_CONTROL_VALUE (IVH, IVHPARENT, IX, IY, IACT,
        +                          IHCEN, IVCEN, IFONT, IBRDR,
        +                          XDLSTR(LABEL), LLEN, 
        +                          XDLSTR(VALUE), IVLEN, MAXVLEN,
        +                          XDLSTR(MSG), LENMSG,
        +                          MINW, MINH,IERR)
 
 
Parameters:
 
IVH       (R)   View-object handle (see vh)
IVHPARENT (R)   View-object handle for parent 0=none 
                (see vh_parent)
IX        (R)   X position (may be -1 if no parent) (see x)
IY        (R)   Y position (may be -1 if no parent) (see y)
IACT      (R)   Display active strip flag 1=yes, 0=no (see
                act_strip)
IHCEN     (R)   =1 Centre panel item horizontally, = 0 do
                not (left justify instead) (see hcen)
IVCEN     (R)   =1 Centre panel item vertically, = 0 do
                not (top justify instead) (see vcen)
IFONT     (R)   Font type (1-5) very small to very large (see
                font_type)
IBRDR     (R)   = 1 draw border, = 0 do not
LABEL     (R)   Address of label string for panel choice.
                ** Pass address using the XDLSTR function **
LLEN      (R)   Length of the label string (>0)
VALUE     (R)   Address of value string for panel value.
                ** Pass address using the XDLSTR function **
IVLEN     (R)   Length of the value string (>0)
MAXVLEN   (R)   Maximum length to allow for a value string
                (value may be changed)
MSG       (R)   Address of character string for active strip
                message. May be a blank string if IACT = 0.
                ** Pass address using XDLSTR function **
                (see msg)
LENMSG    (R)   Length of active strip message string (>0)
                (see len_msg)
MINW      (R)   Minimum width required (may be 0) 
MINH      (R)   Minimum height required (may be 0)
IERR      (W)   Returns status from xdl_control_value call
 
 
'C' call:
 
int xdl_control_value (vh, vh_parent, x, y, act_strip, hcen, vcen,
                        font_type, brdr, label, llen, 
                        value, vlen, maxvlen,
                        msg, len_msg,
                        minw, minh)
 
 
Parameters:
 
int       vh;             /* User selected view-object handle (R)*/
int       vh_parent;      /* View-object handle for the parent base frame, 
                             if 0 then a base  level frame is created to
                             enclose the view-object (R)*/
int       x;              /* x coordinate for the view-object.
                             If no parent may be -1 to give default x (R)*/
int       y;              /* y coordinate for the view-object.
                             If no parent may be -1 to give default y (R)*/
int       act_strip;      /* Display active strip flag 1=yes, 0=no (R)*/
int       hcen;           /* =1 Centre panel item horizontally, = 0 do
                             not (left justify instead) (R)*/
int       vcen;           /* =1 Centre panel item vertically, = 0 do
                             not (top justify instead) (R)*/
int       font_type;      /* Font type (1-5) very small to very large (R)*/
int       brdr;           /* = 1 draw border, = 0 do not (R)*/
char    * label;          /* Label string (R)*/
int       llen;           /* Label length, may be 0 if null terminated
                             string passed (R)*/
char    * value;          /* Value string (R)*/
int       vlen;           /* Value length, may be 0 if null terminated
                             string passed (R)*/
int       maxvlen;        /* Maximum length required for a value string
                             (value may be reset) (R)*/
char    * msg;            /* Message for active strip, may be null if
                             no active strip required (R)*/
int       len_msg;        /* Length of active strip message string; may
                             be 0 is a null terminated string given for
                             msg (R)*/
int minw;                 /* Minimum width required (may be 0) (R)*/
int minh;                 /* Minimum height required (may be 0) (R)*/
 
 
Return:  Status flag =0 OK, >0 error
         bit 0 set: Requested parent not found in the view-objects list
         bit 1 set: Cannot allocate memory required
 
 
2.12.5.3 Set new value string - xdl_control_value_set
 
The routine xdl_control_value_set (xdlf_control_value_set) is used to set a
new value string for a control Panel Value view-object.
 
Fortran call:
 
         CALL XDLF_CONTROL_VALUE_SET (IVH, XDLSTR(VALUE), IVLEN, IERR)
 
 
Parameters:
 
IVH       (R)  View-object handle (see vh)
VALUE     (R)  Address of new value string
               ** Pass address using the XDLSTR function **
IVLEN     (R)  Length of the value string (>0)
IERR      (W)  Returns status from xdl_control_value_set call
 
 
'C' call:
 
int xdl_control_value_set (vh, value, vlen)
 
 
Parameters:
 
int vh;                   /* View-object handle (R)*/
char    * value;          /* Value string (R)*/
int       vlen;           /* Value length, may be 0 if null terminated
                             string passed (R)*/
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.12.5.4 Get input value string - xdl_control_value_getdata
 
The routine xdl_control_value_getdata (xdlf_control_value_getdata) is  used
to return the input value string after a  return  from  an  XDL_VIEW  event
handling routine such as xdl_get_events  (xdlf_get_events)  indicates  that
there was input from the view-object in question.
 
Fortran call:
 
         CALL XDLF_CONTROL_VALUE_GETDATA (IVH, XDLSTR(VALSTR), MAXV, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
VALSTR   (W)  Address of character string in which to place
              returned value string
               ** Pass address using the XDLSTR function **
MAXV     (W)  Max length of VALSTR (>0)
IERR     (W)  Returns status from xdl_control_value_getdata call
 
 
'C' call:
 
int xdl_control_value_getdata (vh, valstr, maxv)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
char * valstr;   /* String in which to return value (W)*/
int maxv;        /* if >0 Maximum length of returned string allowed 
                          (excluding terminating null - string must be 
                          at least max_len + 1 characters in length)
                    if <0 abs(max_len) characters will be returned padded 
                          with blanks if needed (for 'fortran' use) (R)*/
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.12.5.5 Get required size - xdl_control_value_getzize
 
The routine xdl_control_value_getsize (xdlf_control_value_getsize) is  used
to determine the required size for a control view-object containing a Panel
value item given various details about the requirements of the item.
 
Fortran call:
 
         CALL XDLF_CONTROL_VALUE_GETSIZE (IACT, IFONT, IBRDR,
        +                        LLEN,  MAXVLEN, IWIDTH, IHEIGHT)
 
 
Parameters:
 
IACT      (R)   =1 include active strip, =0 do not
IFONT     (R)   Font type (1-5) very small to very large (see
                font_type)
IBRDR     (R)   = 1 draw border, = 0 do not
LLEN      (R)   Length of label ((>0)
MAXVLEN   (R)   Maximum required length of the value string (>0)
IWIDTH    (W)   Width required for view-object
IHEIGHT   (W)   Height required for view-object
 
 
'C' call:
 
void xdl_control_value_getsize (act_strip, font_type, brdr, llen, maxvlen,
                                 width, height)
 
 
Parameters:
 
int       act_strip;      /* Display active strip flag 1=yes, 0=no (R)*/
int       font_type;      /* Font type (1-5) very small to very large (R)*/
int       brdr;           /* = 1 draw border, = 0 do not (R)*/
int       llen;           /* Label length (>0) (R)*/
int       maxvlen;        /* Maximum required value length (>0) (R)*/
int     * width;          /* Returns the required width in pixels (W)*/
int     * height;         /* Returns the required height in pixels (W)*/
 
 
Return:  None
 
 
2.12.6 PANEL SLIDER ITEM ROUTINES
 
2.12.6.1 Introduction
 
These are routines for creating an  handling  a  view-object  containing  a
panel slider item.
 
 
The following routines are available:
 
   View_object with a Panel Slider Item - xdl_control_slider
   Set new slider position - xdl_control_slider_reset
   Get input slider position - xdl_control_slider_getdata
   Get required size - xdl_control_slider_getzize
 
2.12.6.2 View_object with a Panel Slider Item - xdl_control_slider
 
The routine xdl_control_slider (xdlf_control_slider) is used  to  create  a
view object containing a Panel Slider item (See Panel  Item  Routines).  An
active strip may be displayed if desired.
 
Fortran call:
 
         CALL XDLF_CONTROL_SLIDER (IVH, IVHPARENT, IX, IY, IACT,
        +                          IHCEN, IVCEN, IFONT, IBRDR,
        +                          XDLSTR(LABEL), LLEN, 
        +                          ITRAVEL, ISTART,
        +                          XDLSTR(MSG), LENMSG,
        +                          MINW, MINH,IERR)
 
 
Parameters:
 
IVH       (R)   View-object handle (see vh)
IVHPARENT (R)   View-object handle for parent 0=none 
                (see vh_parent)
IX        (R)   X position (may be -1 if no parent) (see x)
IY        (R)   Y position (may be -1 if no parent) (see y)
IACT      (R)   Display active strip flag 1=yes, 0=no (see
                act_strip)
IHCEN     (R)   =1 Centre panel item horizontally, = 0 do
                not (left justify instead) (see hcen)
IVCEN     (R)   =1 Centre panel item vertically, = 0 do
                not (top justify instead) (see vcen)
IFONT     (R)   Font type (1-5) very small to very large (see
                font_type)
IBRDR     (R)   = 1 draw border, = 0 do not
LABEL     (R)   Address of label string for panel slider.
                ** Pass address using the XDLSTR function **
LLEN      (R)   Length of the label string (>0)
ITRAVEL   (R)   Travel length of slider (in pixels)
                (see travel_len)
ISTART    (R)   Start position of slider from 0 to ITRAVEL
                (see startpos)
MSG       (R)   Address of character string for active strip
                message. May be a blank string if IACT = 0.
                ** Pass address using XDLSTR function **
                (see msg)
LENMSG    (R)   Length of active strip message string (>0)
                (see len_msg)
MINW      (R)   Minimum width required (may be 0) 
MINH      (R)   Minimum height required (may be 0)
IERR      (W)   Returns status from xdl_control_slider call
 
 
'C' call:
 
int xdl_control_slider (vh, vh_parent, x, y, act_strip, hcen, vcen,
                        font_type, brdr, label, llen, 
                        travel_len, startpos,
                        msg, len_msg,
                        minw, minh)
 
 
Parameters:
 
int       vh;             /* User selected view-object handle (R)*/
int       vh_parent;      /* View-object handle for the parent base frame, 
                             if 0 then a base  level frame is created to
                             enclose the view-object (R)*/
int       x;              /* x coordinate for the view-object.
                             If no parent may be -1 to give default x (R)*/
int       y;              /* y coordinate for the view-object.
                             If no parent may be -1 to give default y (R)*/
int       act_strip;      /* Display active strip flag 1=yes, 0=no (R)*/
int       hcen;           /* =1 Centre panel item horizontally, = 0 do
                             not (left justify instead) (R)*/
int       vcen;           /* =1 Centre panel item vertically, = 0 do
                             not (top justify instead) (R)*/
int       font_type;      /* Font type (1-5) very small to very large (R)*/
int       brdr;           /* = 1 draw border, = 0 do not (R)*/
char    * label;          /* Label string (R)*/
int       llen;           /* Label length, may be 0 if null terminated
                             string passed (R)*/
int       travel_len;     /* Slider travel length in pixels. The slider
                             positions will represent travel_len + 1
                             discrete values (R)*/
int       startpos;       /* Start position of slider from 0 to travel_len
                             (R)*/
char    * msg;            /* Message for active strip, may be null if
                             no active strip required (R)*/
int       len_msg;        /* Length of active strip message string; may
                             be 0 is a null terminated string given for
                             msg (R)*/
int minw;                 /* Minimum width required (may be 0) (R)*/
int minh;                 /* Minimum height required (may be 0) (R)*/
 
 
Return:  Status flag =0 OK, >0 error
         bit 0 set: Requested parent not found in the view-objects list
         bit 1 set: Cannot allocate memory required
 
 
2.12.6.3 Set new slider position - xdl_control_slider_reset
 
The routine xdl_control_slider_reset (xdlf_control_slider_reset) is used to
set a new slider position for a control Panel Slider view-object.
 
Fortran call:
 
         CALL XDLF_CONTROL_SLIDER_RESET (IVH, ISLIDE, IERR)
 
 
Parameters:
 
IVH       (R)  View-object handle (see vh)
ISLIDE    (R)  New slider position (0 to ITRAVEL)
IERR      (W)  Returns status from xdl_control_slider_reset call
 
 
'C' call:
 
int xdl_control_slider_reset (vh, islide)
 
 
Parameters:
 
int vh;                   /* View-object handle (R)*/
int islide;               /* new slider position (0 to travel_len) (R)*/
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.12.6.4 Get input slider position - xdl_control_slider_getdata
 
The  routine  xdl_control_slider_getdata  (xdlf_control_slider_getdata)  is
used to return the input slider position after a return  from  an  XDL_VIEW
event handling routine such as xdl_get_events  (xdlf_get_events)  indicates
that there was input from the view-object in question.
 
Fortran call:
 
         CALL XDLF_CONTROL_SLIDER_GETDATA (IVH, IPOS, ITRAVEL, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
IPOS     (W)  The returned slider position (0 to ITRAVEL)
ITRAVEL  (W)  The travel length for reference
IERR     (W)  Returns status from xdl_control_slider_getdata call
 
 
'C' call:
 
int xdl_control_slider_getdata (vh, ipos, travel_len)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int *ipos;       /* returns the current slider position (W)*/
int *travel_len; /* Returns the travel length for reference (W)*/
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.12.6.5 Get required size - xdl_control_slider_getzize
 
The  routine  xdl_control_slider_getsize  (xdlf_control_slider_getsize)  is
used to determine the required size for a control view-object containing  a
Panel Slider item given various details about the requirements of the item.
 
Fortran call:
 
         CALL XDLF_CONTROL_SLIDER_GETSIZE (IACT, IFONT, IBRDR,
        +                        LLEN,  ITRAVEL, IWIDTH, IHEIGHT)
 
 
Parameters:
 
IACT      (R)   =1 include active strip, =0 do not
IFONT     (R)   Font type (1-5) very small to very large (see
                font_type)
IBRDR     (R)   = 1 draw border, = 0 do not
LLEN      (R)   Length of label ((>0)
ITRAVEL   (R)   Travel length
IWIDTH    (W)   Width required for view-object
IHEIGHT   (W)   Height required for view-object
 
 
'C' call:
 
void xdl_control_slider_getsize (act_strip, font_type, brdr, llen, 
                                 travel_len, width, height)
 
 
Parameters:
 
int       act_strip;      /* Display active strip flag 1=yes, 0=no (R)*/
int       font_type;      /* Font type (1-5) very small to very large (R)*/
int       brdr;           /* = 1 draw border, = 0 do not (R)*/
int       llen;           /* Label length (>0) (R)*/
int       travel_len;     /* Travel length (R)*/
int     * width;          /* Returns the required width in pixels (W)*/
int     * height;         /* Returns the required height in pixels (W)*/
 
 
Return:  None
 
 
2.12.7 PANEL I/O ITEM ROUTINES
 
2.12.7.1 Introduction
 
These are routines for creating an  handling  a  view-object  containing  a
panel input/output item.
 
 
The following routines are available:
 
   View_object with a Panel I/O Item - xdl_control_io
   Set new prompt string - xdl_control_io_prompt
   Clear I/O item - xdl_control_io_clear
   Set keyboard focus for I/O item - xdl_control_io_kbfocus
   Get input string - xdl_control_io_getdata
   Get required size - xdl_control_io_getzize
 
2.12.7.2 View_object with a Panel I/O Item - xdl_control_io
 
The routine xdl_control_io (xdlf_control_io)  is  used  to  create  a  view
object containing a Panel I/O item (See Panel  Item  Routines).  An  active
strip may be displayed if desired.
 
Fortran call:
 
         CALL XDLF_CONTROL_IO (IVH, IVHPARENT, IX, IY, IACT,
        +                          IHCEN, IVCEN, IFONT, IBRDR,
        +                          MAX_PR, MIN_RP, MAX_RP, ICH,
        +                          XDLSTR(MSG), LENMSG,
        +                          MINW, MINH,IERR)
 
 
Parameters:
 
IVH       (R)   View-object handle (see vh)
IVHPARENT (R)   View-object handle for parent 0=none 
                (see vh_parent)
IX        (R)   X position (may be -1 if no parent) (see x)
IY        (R)   Y position (may be -1 if no parent) (see y)
IACT      (R)   Display active strip flag 1=yes, 0=no (see
                act_strip)
IHCEN     (R)   =1 Centre panel item horizontally, = 0 do
                not (left justify instead) (see hcen)
IVCEN     (R)   =1 Centre panel item vertically, = 0 do
                not (top justify instead) (see vcen)
IFONT     (R)   Font type (1-5) very small to very large (see
                font_type)
IBRDR     (R)   = 1 draw border, = 0 do not
MAX_PR    (R)   Maximum length for prompt field
MIN_RP    (R)   Minimum length for reply field
MAX_RP    (R)   Maximum length for reply
ICH       (R)   = 1 show character count, = 0 do not
MSG       (R)   Address of character string for active strip
                message. May be a blank string if IACT = 0.
                ** Pass address using XDLSTR function **
                (see msg)
LENMSG    (R)   Length of active strip message string (>0)
                (see len_msg)
MINW      (R)   Minimum width required (may be 0) 
MINH      (R)   Minimum height required (may be 0)
IERR      (W)   Returns status from xdl_control_io call
 
 
'C' call:
 
int xdl_control_io (vh, vh_parent, x, y, act_strip, hcen, vcen,
                        font_type, brdr, 
                        max_pr, min_rp, max_rp, ch_count,
                        msg, len_msg,
                        minw, minh)
 
 
Parameters:
 
int       vh;             /* User selected view-object handle (R)*/
int       vh_parent;      /* View-object handle for the parent base frame, 
                             if 0 then a base  level frame is created to
                             enclose the view-object (R)*/
int       x;              /* x coordinate for the view-object.
                             If no parent may be -1 to give default x (R)*/
int       y;              /* y coordinate for the view-object.
                             If no parent may be -1 to give default y (R)*/
int       act_strip;      /* Display active strip flag 1=yes, 0=no (R)*/
int       hcen;           /* =1 Centre panel item horizontally, = 0 do
                             not (left justify instead) (R)*/
int       vcen;           /* =1 Centre panel item vertically, = 0 do
                             not (top justify instead) (R)*/
int       font_type;      /* Font type (1-5) very small to very large (R)*/
int       brdr;           /* = 1 draw border, = 0 do not (R)*/
int       max_pr;         /* Maximum length for prompt field (R)*/
int       min_rp;         /* Minimum length for reply field (R)*/
int       max_rp;         /* Maximum length for reply (R)*/
int       ch_count;       /* = 1 show character count, = 0 do not (R)*/
char    * msg;            /* Message for active strip, may be null if
                             no active strip required (R)*/
int       len_msg;        /* Length of active strip message string; may
                             be 0 is a null terminated string given for
                             msg (R)*/
int minw;                 /* Minimum width required (may be 0) (R)*/
int minh;                 /* Minimum height required (may be 0) (R)*/
 
 
Return:  Status flag =0 OK, >0 error
         bit 0 set: Requested parent not found in the view-objects list
         bit 1 set: Cannot allocate memory required
 
 
2.12.7.3 Set new prompt string - xdl_control_io_prompt
 
The routine xdl_control_io_prompt (xdlf_control_io_prompt) is used to set a
new prompt string for a control Panel I/O view-object.
 
Fortran call:
 
         CALL XDLF_CONTROL_IO_PROMPT (IVH, XDLSTR(PROMPT), IPLEN,
        +                             IFLAG, IERR)
 
 
Parameters:
 
IVH       (R)  View-object handle (see vh)
PROMPT    (R)  Address of new prompt string
               ** Pass address using the XDLSTR function **
IPLEN     (R)  Length of the prompt string (>0)
IFLAG     (R)  Flag to be passed to callback identifying
               prompt (if required)
IERR      (W)  Returns status from xdl_control_io_prompt call
 
 
'C' call:
 
int xdl_control_io_prompt (vh, prompt, plen, iflag)
 
 
Parameters:
 
int vh;                   /* View-object handle (R)*/
char    * prompt;         /* Prompt string (R)*/
int       plen;           /* Prompt length, may be 0 if null terminated
                             string passed (R)*/
int       iflag;          /* User selected flag to identify flag (will
                             be passed to callback (R)*/
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.12.7.4 Clear I/O item - xdl_control_io_clear
 
The routine xdl_control_io_clear (xdlf_control_io_clear) is used to clear a
control Panel I/O view-object. It will remain inactive till another  prompt
is output via xdl_control_io_prompt (xdlf_control_io_prompt).
 
Fortran call:
 
         CALL XDLF_CONTROL_IO_CLEAR (IVH, IERR)
 
 
Parameters:
 
IVH       (R)  View-object handle (see vh)
IERR      (W)  Returns status from xdl_control_io_clear call
 
 
'C' call:
 
int xdl_control_io_clear (vh)
 
 
Parameters:
 
int vh;                   /* View-object handle (R)*/
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.12.7.5 Set keyboard focus for I/O item - xdl_control_io_kbfocus
 
The routine xdl_control_io_kbfocus (xdlf_control_io_kbfocus) is used to set
the keyboard focus for a control Panel I/O view-object.
 
Fortran call:
 
         CALL XDLF_CONTROL_IO_KBFOCUS (IVH, IERR)
 
 
Parameters:
 
IVH       (R)  View-object handle (see vh)
IERR      (W)  Returns status from xdl_control_io_kbfocus call
 
 
'C' call:
 
int xdl_control_io_kbfocus (vh)
 
 
Parameters:
 
int vh;                   /* View-object handle (R)*/
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.12.7.6 Get input string - xdl_control_io_getdata
 
The routine xdl_control_io_getdata  (xdlf_control_io_getdata)  is  used  to
return the input string after a return  from  an  XDL_VIEW  event  handling
routine such as xdl_get_events (xdlf_get_events) indicates that  there  was
input from the view-object in question.
 
Fortran call:
 
         CALL XDLF_CONTROL_IO_GETDATA (IVH, REPLY, MAXR, IRET,
        +                              IFLAG, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
REPLY    (W)  Address of character string in which to place
              returned input string
               ** Pass address using the XDLSTR function **
MAXR     (W)  Max length of REPLY (>0)
IRET     (W)  Returns input status flag = 1 non-blank string
                                        = 0 blank string
                                        =-1 escape pressed
IFLAG    (W)  User flag defined when setting prompt
IERR     (W)  Returns status from xdl_control_io_getdata call
 
 
'C' call:
 
int xdl_control_io_getdata (vh, reply, maxr, iret, iflag)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
char * reply;    /* String in which to return value (W)*/
int maxr;        /* if >0 Maximum length of returned string allowed 
                          (excluding terminating null - string must be 
                          at least max_len + 1 characters in length)
                    if <0 abs(max_len) characters will be returned padded 
                          with blanks if needed (for 'fortran' use) (R)*/
int * iret;      /* Returns input status flag = 1 non-blank string
                                              = 0 blank string
                                              =-1 escape pressed (W)*/
int *iflag;      /* User flag defined when setting prompt (W)*/
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.12.7.7 Get required size - xdl_control_io_getzize
 
The routine xdl_control_io_getsize  (xdlf_control_io_getsize)  is  used  to
determine the required size for a control view-object  containing  a  Panel
I/O item given various details about the requirements of the item.
 
Fortran call:
 
         CALL XDLF_CONTROL_IO_GETSIZE (IACT, IFONT, IBRDR,
        +                        MAX_PR, MIN_RP, MAX_RP, ICH, 
        +                        IWIDTH, IHEIGHT)
 
 
Parameters:
 
IACT      (R)   =1 include active strip, =0 do not
IFONT     (R)   Font type (1-5) very small to very large (see
                font_type)
IBRDR     (R)   = 1 draw border, = 0 do not
MAX_PR    (R)   Maximum length for prompt field
MIN_RP    (R)   Minimum length for reply field
MAX_RP    (R)   Maximum length for reply
ICH       (R)   = 1 show character count, = 0 do not
IWIDTH    (W)   Width required for view-object
IHEIGHT   (W)   Height required for view-object
 
 
'C' call:
 
void xdl_control_io_getsize (act_strip, font_type, brdr, max_pr, min_rp,
                             max_rp, ch_count, width, height)
 
 
Parameters:
 
int       act_strip;      /* Display active strip flag 1=yes, 0=no (R)*/
int       font_type;      /* Font type (1-5) very small to very large (R)*/
int       brdr;           /* = 1 draw border, = 0 do not (R)*/
int       max_pr;         /* Maximum length for prompt field (R)*/
int       min_rp;         /* Minimum length for reply field (R)*/
int       max_rp;         /* Maximum length for reply (R)*/
int       ch_count;       /* = 1 show character count, = 0 do not (R)*/
int     * width;          /* Returns the required width in pixels (W)*/
int     * height;         /* Returns the required height in pixels (W)*/
 
 
Return:  None
 
 

2.13 THE BLANK OBJECT VIEW-OBJECT ROUTINES
==========================================


2.13.1 INTRODUCTION
 
The blank object view-object is merely a window with a  surrounding  border
similar to that used in other view-objects which may be output on a display
for aesthetic reasons to indicate the position on  a  tiled  display  which
will be occupied by another view-object later.
 
The following sets of routines are available:
 
   Creating and Handling a Blank View-Object
 
2.13.2 CREATING AND HANDLING A BLANK VIEW-OBJECT
 
2.13.2.1 Introduction
 
The following routines are available:
 
   Create a blank object view-object - xdl_blank_object
 
2.13.2.2 Create a blank object view-object - xdl_blank_object
 
THe routine xdl_blank_object (xdlf_blank_object) is used to  create  a  new
blank object view-object. The size of the object is supplied by the user.
 
Fortran call:
 
         CALL XDLF_blank_OBJECT (IVH, IVHPARENT, IX, IY, ICSET, IWIDTH, 
        +                        IHEIGHT, IERR)
 
 
Parameters:
 
IVH       (R)   View-object handle (see vh)
IVHPARENT (R)   View-object handle for parent 0=none 
                (see vh_parent)
IX        (R)   X position (may be -1 if no parent) (see x)
IY        (R)   Y position (may be -1 if no parent) (see y)
ICSET     (R)   Colorset number (see cset)
IWIDTH    (R)   Width in pixels (see width)
IHEIGHT   (R)   Height in pixels (see height)
IERR      (W)   Returns status from xdl_blank_object call
 
 
'C' call:
 
int xdl_blank_object (vh, vh_parent, x, y, cset, width, height)
 
 
Parameters:
 
int       vh;             /* User selected view-object handle (R)*/
int       vh_parent;      /* View-object handle for the parent base frame,
                             if 0 then a base  level frame is created to
                             enclose the blank view-object (R)*/
int       x;              /* x coordinate for the view-object.
                             If no parent may be -1 to give default x (R)*/
int       y;              /* y coordinate for the view-object.
                             If no parent may be -1 to give default y (R)*/
int       cset;           /* Number of the colorset to be used - 
                             normally 0 (R)*/
int       width;          /* Window width in pixels (R)*/
int       height;         /* Window height in pixels (R)*/
 
 
Return:  Status flag =0 OK, >0 error
                bit 0 set: Requested parent not found in view-objects list
 
 

2.14 THE IMAGE DISPLAY VIEW-OBJECT ROUTINES
===========================================


2.14.1 INTRODUCTION
 
The image view-object is designed ,in  particular,for  displaying  film  or
image-plate images used in Protein Crystallography.  It  may  be  used  for
measuring spot positions and has facilities for overlaying symbols or other
vectors on top of the displayed  image.  A  magnifying  window  within  the
view-object shows a magnified version of a portion of the  image  from  the
main image display area. The image may also  be  zoomed.  A  control  panel
allows for a series of adjustments to the display.
 
The following sets of routines are available:
 
   Creating and Handling an Image Display View-Object
 
2.14.2 CREATING AND HANDLING AN IMAGE DISPLAY VIEW-OBJECT
 
2.14.2.1 Introduction
 
The following routines are available:
 
   Create an image view-object - xdl_image
   Get selected pixel position - xdl_image_getpix
   Get pixel position from an overlay - xdl_image_getpix_ovly
   Get selected rectangle - xdl_image_getrect
   Get display settings - xdl_image_settings
   Reset current display settings - xdl_image_reset
   Set local axis names - xdl_image_axnames
   Display the image now - xdl_image_display_now
   Set background image - xdl_image_background
   Set a new image - xdl_image_newimg
   Reset overlay offset values - xdl_image_ovly_offset
   Reset an overlay colour - xdl_image_set_colour
   Reset user defined colour map - xdl_image_set_colormap
   Store and display an overlay symbol - xdl_image_symbol
   Store and display overlay symbols - xdl_image_symbols
   Clear overlay symbols - xdl_image_clear_symbols
   Delete an overlay symbol - xdl_image_del_symbol
   Store and display an overlay vector - xdl_image_vect
   Store and display overlay vectors - xdl_image_vects
   Store and display overlay vectors - xdl_image_vects_pos
   Store and display overlay boxes - xdl_image_boxes
   Clear overlay vectors - xdl_image_clear_vectors
   Delete an overlay vector - xdl_image_del_vect
   Output a text string - xdl_image_text
   Delete a text string - xdl_image_del_text
   Clear all text strings - xdl_image_clear_text
   Reset active strip message - xdl_image_input_message
   Calculate the size requirements - xdl_image_getsize
 
2.14.2.2 Create an image view-object - xdl_image
 
The routine xdl_image (xdlf_image) is used  to  create  a  new  image  view
object. The parameters give details of the image to be displayed.
 
Fortran call:
 
         CALL XDLF_IMAGE (IVH, IVHPARENT, IX, IY, ICSET, IMGDATA, ITYPE,
        +                 NS_RAS, NF_RAS, NF_OFF, 
        +                 IO_AX1, IO_AX2, NREQ_AX1, NREQ_AX2, NCMP,
        +                 IORDER, JORDER,
        +                 MINVAL, MAXVAL, MINTHR, MAXTHR, MINW, MINH, 
        +                 IBG, IOVLY, ICONTRAST, IDISP_NOW, IERR)
 
 
Parameters:
 
IVH       (R)   View-object handle (see vh)
IVHPARENT (R)   View-object handle for parent 0=none 
                (see vh_parent)
IX        (R)   X position (may be -1 if no parent) (see x)
IY        (R)   Y position (may be -1 if no parent) (see y)
ICSET     (R)   Colorset number  (see cset)
IMGDATA   (R)   Array holding the full image data (see imgdata)
ITYPE     (R)   1 = unsigned byte data
                2 = unsigned two-byte data (i2)
                3 = signed integer data
                4 = 'squashed i2' data (if stored I<0
                    ipix = -i*8
                5 = 'squashed i2' data if stored I<0
                    ipix = (I+32768)*8
                6 = 'squashed i2' data if stored I<0
                    ipix = (I+32768)*32
                7 = 'squashed i2' data if stored I<0
                    ipix = -(I+1)*256 + 32768
                (see type)
NS_RAS    (R)   Number of rasters in image along slow axis
                (see ns_ras)
NF_RAS    (R)   Number of rasters in image along fast axis
                (see nf_ras)
NF_OFF    (R)   Number of rasters offset between rows of stored
                image data (see nf_off)
IO_AX1    (R)   Origin (local axis 1) pixel for section to be 
                displayed (see o_ax1) (from 1 upwards)
IO_AX2    (R)   Origin (local axis 2) pixel for section to be 
                displayed (see o_ax2) (from 1 upwards)
NREQ_AX1  (R)   Size of section required along local axis 1
                (see nreq_ax1)
NREQ_AX2  (R)   Size of section required along local axis 2
                (see nreq_ax2)
NCMP      (R)   No. of pixels to compress into one pixel
                along each axis (if NCMP>0, pixel averaging will
                be done; give -NCMP to sample rather than average
                (quicker)) (see ncmp)
IORDER    (R)   Order of the data in the input image 
                with respect to two local axes ax1, ax2 e.g.
                (xf, yf) as a number from 1 to 8.
                    1   +ax1 slow   +ax2 fast    (+xf, +yf)
                    2   +ax1 slow   -ax2 fast    (+xf, -yf)
                    3   -ax1 slow   +ax2 fast    (-xf, +yf)
                    4   -ax1 slow   -ax2 fast    (-xf, -yf)
                    5   +ax2 slow   +ax1 fast    (+yf, +xf)
                    6   +ax2 slow   -ax1 fast    (+yf, -xf)
                    7   -ax2 slow   +ax1 fast    (-yf, +xf)
                    8   -ax2 slow   -ax1 fast    (-yf, -xf)
JORDER    (R)   Display order with respect to the two
                local axes (1 to 8) along the X-windows
                axes X horizontal (left to right), Y vertical 
                (top to bottom ) with origin at top left
                1  +ax1 X (horiz)   +ax2 Y (vert)   (+xf, +yf)
                2  +ax1 X (horiz)   -ax2 Y (vert)   (+xf, -yf)
                3  -ax1 X (horiz)   +ax2 Y (vert)   (-xf, +yf)
                4  -ax1 X (horiz)   -ax2 Y (vert)   (-xf, -yf)
                5  +ax2 X (horiz)   +ax1 Y (vert)   (+yf, +xf)
                6  +ax2 X (horiz)   -ax1 Y (vert)   (+yf, -xf)
                7  -ax2 X (horiz)   +ax1 Y (vert)   (-yf, +xf)
                8  -ax2 X (horiz)   -ax1 Y (vert)   (-yf, -xf)
                    
                    (2 was standard for Laue programs)
MINVAL    (R)   Minimum pixel value present (see min_val)
MAXVAL    (R)   Maximum pixel value present (see max_val)
MINTHR    (R)   Minimum threshold for scaling 
                (see min_thresh)
MAXTHR    (R)   Maximum threshold for scaling 
                (see max_thresh)
MINW      (R)   Min. width for view-object or 0 (see min_width)
MINH      (R)   Min. height for view-object or 0 (see min_height)
IBG       (R)   =0 no background choice menu, 
                =1 background choice menu (Set background via
                   xdlf_image_background
                   (see bg_typ)
IOVLY     (R)   = 1 Overlay options are on/off/offset
                = 2 Overlay options are on/off/1 on/2 on
                (see ovly_typ)
ICONTRAST (R)   Start contrast value 1-1024
IDISP_NOW (R)   Display now flag =1 to display immediately; =0
                to wait fo a call to XDLF_IMAGE_DISPLAY_NOW
                before displaying (to enable other parameters
                to be set first) (see disp_now)
IERR      (W)   Returns status from xdl_image call
 
 
'C' call:
 
int xdl_image (vh, vh_parent, x, y, cset, imgdata, type, 
                    ns_ras, nf_ras, nf_off,
                    o_ax1, o_ax2, nreq_ax1, nreq_ax2, ncmp_in,
                    iorder, jorder,
                    min_val, max_val, min_thresh, max_thresh, 
                    min_width, min_height, bg_typ, ovly_typ,
                    contrast, disp_now)
 
 
Parameters:
 
int       vh;             /* User selected view-object handle (R)*/
int       vh_parent;      /* View-object handle for the parent base frame,
                             if 0 then a base  level frame is created to
                             enclose the image plate image view-object 
                             (R)*/
int       x;              /* x coordinate for the view-object.
                             If no parent may be -1 to give default x (R)*/
int       y;              /* y coordinate for the view-object.
                             If no parent may be -1 to give default y (R)*/
int       cset;           /* Number of the colorset to be used for the 
                             image display; must have 72 or more 
                             colorcells allocated (R)*/
char      *imgdata;       /* Pointer to the image data in byte, i2 or int
                             format as indicated by the 'type' parameter.
                             The image data must remain in place as long
                             as the view object is being used as it will 
                             be accessed again if the scaling thresholds 
                             etc. are changed. (R)*/
int       type;           /* 1 = unsigned byte data
                             2 = unsigned two-byte data
                             3 = signed integer data 
                             4 = 'squashed i2' data (if stored I<0
                                 ipix = -i*8
                             5 = 'squashed i2' data if stored I<0
                                 ipix = (I+32768)*8
                             6 = 'squashed i2' data if stored I<0
                                 ipix = (I+32768)*32
                             7 = 'squashed i2' data if stored I<0
                                 ipix = -(I+1)*256 + 32768
                             (R) */
int       ns_ras;         /* No. of rasters in slow moving direction of
                             full image (R)*/
int       nf_ras;         /* No. of rasters in fast moving direction of
                             full image (R)*/
int       nf_off;         /* Offset between the start of each stored
                             image row in fast axis rasters (to allow 
                             storage of image in a pre-dimensioned 2-D 
                             array (length of 2'nd dimension in 'C' and 
                             1'st dimension in Fortran)) (R)*/
int       o_ax1;          /* The local 'ax1' (e.g.xf) origin pixel number 
                             (pixels numbered from 1 up) for the section of 
                             image to be displayed (R)*/
int       o_ax2;          /* The local 'ax2' (e.g. yf) origin pixel number 
                             (pixels numbered from 1 up) for the section of 
                             image to be displayed (R)*/
int       nreq_ax1;       /* Requested size along the first local axis 
                             (ax1) of the section of the image to be 
                             displayed; the actual size may be reduced by 
                             up to ncmp-1 pixels if nreq_ax1 is not a 
                             multiple of ncmp (see below). The actual size 
                             will be ncmp*(nreq_ax1/ncmp) (R)*/
int       nreq_ax2;       /* Requested size along the second local axis 
                             (ax2) of the section of the image to be 
                             displayed; the actual size may be reduced by 
                             up to ncmp-1 pixels if nreq_ax2 is not a 
                             multiple of ncmp (see below). The actual size 
                             will be ncmp*(nreq_ax2/ncmp) (R)*/
int       ncmp_in;        /* The number of image pixels in both axis
                             direction to be combined into 1 pixel in the
                             displayed image (e.g. 4 will reduce a 
                             2400x2400 image to a 600x600 image. Give 
                             -ncmp if compression by sampling rather than 
                             averaging required (R) */
int       iorder;         /* Order of the data in the input image 
                             with respect to two local axes ax1, ax2 e.g.
                             (xf, yf) as a number from 1 to 8.
                             1   +ax1 slow   +ax2 fast    (+xf, +yf)
                             2   +ax1 slow   -ax2 fast    (+xf, -yf)
                             3   -ax1 slow   +ax2 fast    (-xf, +yf)
                             4   -ax1 slow   -ax2 fast    (-xf, -yf)
                             5   +ax2 slow   +ax1 fast    (+yf, +xf)
                             6   +ax2 slow   -ax1 fast    (+yf, -xf)
                             7   -ax2 slow   +ax1 fast    (-yf, +xf)
                             8   -ax2 slow   -ax1 fast    (-yf, -xf)
                             (R)*/
int       jorder;         /* Display order with respect to the two
                             local axes (1 to 8) along the X-windows
                             axes X horizontal, Y vertical with origin
                             at top left
                              +ax1 X (horiz) +ax2 Y (vert)  (+xf, +yf)
                             2 +ax1 X (horiz) -ax2 Y (vert)  (+xf, -yf)
                             3 -ax1 X (horiz) +ax2 Y (vert)  (-xf, +yf)
                             4 -ax1 X (horiz) -ax2 Y (vert)  (-xf, -yf)
                             5 +ax2 X (horiz) +ax1 Y (vert)  (+yf, +xf)
                             6 +ax2 X (horiz) -ax1 Y (vert)  (+yf, -xf)
                             7 -ax2 X (horiz) +ax1 Y (vert)  (-yf, +xf)
                             8 -ax2 X (horiz) -ax1 Y (vert)  (-yf, -xf)
                             
                             (2 was standard for Laue programs)
                             (R) */
int       min_val;        /* Minimum value of a pixel in the image.
                             Used as a lower limit for min_thresh (R)*/
int       max_val;        /* Maximum value of a pixel in the image.
                             Used as upper limit for max_thresh. (R)*/
int       min_thresh;     /* Minimum threshold value for the initial 
                             intensity scaling. min_val<=min_thesh<max_val. 
                             (R)*/
int       max_thresh;     /* Maximum threshold value for the initial
                             intensity scaling. 
                             min_thresh<max_thresh<=max_val. (R)*/
int       min_width;      /* minimum width for the displayed view-object.
                             The program will calculate the required width
                             for the view-object based on the image width,
                             the space required for the magnified image,
                             slider bars, menus etc. If this is less than
                             min_width then min_width will be used and the
                             view-object will be set out as appropriate. 
                             (R)*/
int       min_height;     /* minimum height for the displayed view object.
                             cf min_width (R) */
int       bg_typ;         /* =0 no background choice menu, 
                             =1 background choice menu (Set background via
                                xdl_image_background routine) (R)*/
int       ovly_typ;       /* = 1 Overlay options are on/off/offset.
                             = 2 Overlay options are on/off/1 on/2 on.
                                 Two separate sets of overlay symbols may
                                 be drawn.
                                 In case 1, the offset only applies to
                                 to overlay 1; In case 2 no offsetting is
                                 done but it is possible to switch between
                                 the two overlays. (R)*/
int       contrast;       /* Starting contrast value (1-1024) (R)*/
int       disp_now;       /* = 1 display image when this routine has been
                                 called.
                             = 0 do not display yet, wait for other 
                                 parameters to be set (e.g. contrast, 
                                 colour options) and a call to the  
                                 xdl_image_display_now routine (R)*/
 
 
Return:  Status flag =0 OK, >0 error
                bit 0 set: Requested parent not found in view-objects list
                bit 1 set: Unable to allocate memory for global data area
                bit 2 set: Unable to allocate memory for internal image 
                           data
                bit 4 set: Unable to allocate memory for magnifying window
                           image areas.
                bit 5 set: Unable to allocate memory for compress array
 
 
2.14.2.3 Get selected pixel position - xdl_image_getpix
 
The routine xdl_image_getpix (xdlf_image_getpix) is used to return the last
selected input pixel (spot)  position  to  the  calling  program.  It  will
normally  be  called  after  the  return  from  a  call  to  xdl_get_events
(xdlf_get_events) indicates that an image view-object has returned input.
 
Fortran call:
 
         CALL XDLF_IMAGE_GETPIX (IVH, IAX1PIX, IAX2PIX, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
IAX1PIX  (W)  Returns local axis 1 pixel position 
              (see ax1pix_img)
IAX2PIX  (W)  Returns local axis 2 pixel position 
              (see ax2pix_img)
IERR     (W)  Returns status from xdl_image_getpix call
 
 
'C' call:
 
int xdl_image_getpix (vh, ax1pix_img, ax2pix_img)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int *ax1pix_img; /* Returns the local axis 1 pixel position 
                    (from 1 up - refers to complete uncompressed 
                    image) (W) */
int *ax2pix_img; /* Returns the local axis 2 pixel position (W) */

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.14.2.4 Get pixel position from an overlay - xdl_image_getpix_ovly
 
The  routine  xdl_image_getpix_ovly  (xdlf_image_getpix_ovly)  is  used  to
return the last selected input pixel (e.g. symbol) position from an overlay
to   the   calling    program.    It    differs    from    xdl_image_getpix
(xdlf_image_getpix) in that it makes an allowance for any offsetting of the
overlay currently in force. It will normally be  called  after  the  return
from a call to xdl_get_events (xdlf_get_events)  indicates  that  an  image
view-object has returned input.
 
Fortran call:
 
         CALL XDLF_IMAGE_GETPIX_OVLY (IVH, IOV, IXPIX, IYPIX, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
IOV      (R)  Overlay number (1 o 2) (see ov_num)
IAX1PIX  (W)  Returns local axis 1 pixel position 
              (see ax1pix_img)
IAX2PIX  (W)  Returns local axis 2 pixel position 
              (see ax2pix_img)
IERR     (W)  Returns status from xdl_image_getpix_ovly call
 
 
'C' call:
 
int xdl_image_getpix_ovly (vh, ov_num, ax1pix_img, ax2pix_img)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int ov_num;      /* Overlay number (1 or 2) 
                    Note: Overlay 2 is never offset.
                          Overlay 1 will be offset if the overlay type
                          is on/off/offset and the offset option has
                          been selected  (R)*/
int *ax1pix_img; /* Returns the local axis 1 pixel position (from 1 up 
                    - refers to complete uncompressed image); any 
                    overlay offset is subtracted from the value before 
                    it is returned (W) */
int *ax2pix_img; /* Returns the local axis 2 pixel position (W) */

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.14.2.5 Get selected rectangle - xdl_image_getrect
 
The routine xdl_image_getrect (xdlf_image_getrect) is used  to  return  the
last selected rectangle coordinates in pixels to the  calling  program.  It
will normally be called after the return  from  a  call  to  xdl_get_events
(xdlf_get_events) indicates that an image view-object has returned input.
 
Fortran call:
 
         CALL XDLF_IMAGE_GETRECT (IVH, IAX1PIX1, IAX2PIX1, 
        +          IAX1PIX2, IAX2PIX2, IVECT, ICOLR, IOV, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
IAX1PIX1 (W)  Returns 1'st local axis 1 pixel position 
              (see ax1pix_dn)
IAX2PIX1 (W)  Returns 1'st local axis 2 pixel position 
              (see ax2pix_dn)
IAX1PIX2 (W)  Returns 2'nd local axis 1 pixel position 
              (see ax1pix_up)
IAX2PIX2 (W)  Returns 2'nd local axis 2 pixel position 
              (see ax2pix_up)
IVECT    (R)  Vector identifier for drawing box at selected
              position (1-65535); 0 if no box is to be 
              drawn (see also description of 
              xdlf_image_drawvect routine)
ICOLR    (R)  Vector colour (1 to 6) if needed (see color)
IOV      (R)  Overlay number 1 or 2 if needed (see ov_num)
IERR     (W)  Returns status from xdl_image_getrect call
 
 
'C' call:
 
int xdl_image_getrect (vh, ax1pix_dn, ax2pix_dn, ax1pix_up, ax2pix_up,
                            vect_id, color, ov_num)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int *ax1pix_dn;  /* Returns the local axis 1 pixel position (from 1 up 
                    - refers to complete uncompressed image) of rectangle 
                    corner where Button1 was pressed (W) */
int *ax2pix_dn;  /* Returns the local axis 2 pixel position where Button1 
                    was pressed (W) */
int *ax1pix_up;  /* Returns the local axis 1 pixel position (from 1 up 
                    - refers to complete uncompressed image) of rectangle 
                    corner where Button1 was released (W) */
int *ax2pix_up;  /* Returns the local axis 2 pixel position where Button1 
                    was released (W) */
int vect_id;     /* Vector identifier (1-65535) to draw a box on the
                    image display at the selected rectangle position;
                    0 if no box is to be drawn. (see xdl_image_vect) */
int color;       /* Overlay colour type 1 to 6; Red, Yellow, Green, Cyan,
                    Blue, Magenta (by default) if needed*/
int ov_num;      /* Overlay number 1 or 2 (R) if needed*/

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.14.2.6 Get display settings - xdl_image_settings
 
The routine xdl_image_settings (xdlf_image_settings) is used to obtain  the
current display settings so that they can  be  used  for  example  for  the
display of another image.
 
Fortran call:
 
         CALL XDLF_IMAGE_SETTINGS (IVH, MIN_THR, MAX_THR, MONO_THR,
        +                          ICONTRAST, ICOLOR_OPT, IOVLY_OPT,
        +                          IBG_OPT, MAG_OPT, ISHOW_INT, IERR)
 
 
Parameters:
 
IVH        (R)  View-object handle (see vh)
MIN_THR    (W)  Returns the minimum scaling threshold 
                (see min_thr)
MAX_THR    (W)  Returns the maximum scaling threshold 
                (see max_thr)
MONO_THR   (W)  Returns the current threshold for monochome 
                display  0-63 (see mono_thr)
ICONTRAST  (W)  Returns the contrast value 1-1024 (see contrast)
ICOLOR_OPT (W)  Returns the colour choice option 1-7 for colour,
                1-2 for monochrome  (see color_opt)
IOVLY_OPT  (W)  Returns overlay option 1-3 or 1-4 (see ovly_opt)
IBG_OPT    (W)  Returns the background option 1-3 (see bg_opt)
MAG_OPT    (W)  Returns the current magnification option 1-7
                for colour or 1-10 for monochrome (see mag_opt)
ISHOW_INT  (W)  Returns flag for whether intensity values are 
                to be shown on zooming 0-1 (see show_int)
IERR       (W)  Returns status from xdl_image_settings call
 
 
'C' call:
 
int xdl_image_settings (vh, min_thr, max_thr, mono_thr, contrast,
                        color_opt, ovly_opt, bg_opt, mag_opt, show_int)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int *min_thr;    /* Returns the minimum scaling threshold (W) */
int *max_thr;    /* Returns the maximum scaling threshold (W) */
int *mono_thr;   /* Returns the current threshold for monochome 
                    display  0-63 (W)*/
int *contrast;   /* Returns the contrast value 1-1024 (W) */
int *color_opt;  /* Returns the colour choice option 1-7 for colour,
                    1-2 for monochrome (W) */
int *ovly_opt;   /* Returns overlay option 1-3 or 1-4 (W) */
int *bg_opt;     /* Returns the background option 1-3 (W) */
int *mag_opt;    /* Returns the current magnification option 1-7
                    for colour or 1-10 for monochrome (W) */
int *show_int;   /* Returns flag for whether intensity values are to be
                    shown on zooming 0-1 (W) */

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.14.2.7 Reset current display settings - xdl_image_reset
 
The routine xdl_image_reset (xdlf_image_reset) is used to  set  new  values
for the display settings such as the scaling thresholds, contrast level and
colour options.
 
Fortran call:
 
         CALL XDLF_IMAGE_RESET (IVH, MIN_THR, MAX_THR, MONO_THR,
        +                       ICONTRAST, ICOLOR_OPT, IOVLY_OPT,
        +                       IBG_OPT, MAG_OPT, ISHOW_INT, IERR)
 
 
Parameters:
 
IVH        (R)  View-object handle (see vh)
MIN_THR    (R)  Sets the minimum scaling threshold (see min_thr)
MAX_THR    (R)  Sets the maximum scaling threshold (see max_thr)
MONO_THR   (R)  Sets the current threshold for monochome 
                display  0-63 (see mono_thr)
ICONTRAST  (R)  Sets the contrast value 1-1024 (see contrast)
ICOLOR_OPT (R)  Sets the colour choice option 1-7 for colour,
                1-2 for monochrome  (see color_opt)
                    1 = Black on white
                    2 = White on black
                    3 = Yellow if sat.
                    4 = Colour 1
                    5 = Colour 2
                    6 = User defined
                    7 = Random
IOVLY_OPT  (R)  Sets overlay option 1-3 or 1-4 (see ovly_opt)
                1'st case 1=on, 2=off, 3=offset
                2'nd case 1=on, 2=off, 3=ov1 on, 4=ov2 on
IBG_OPT    (R)  Sets the background option 1-3 (see bg_opt)
                1=included, 2=subtracted, 3=background only 
MAG_OPT    (R)  Sets the current magnification option 1-7
                for colour or 1-10 for monochrome (see mag_opt)
                1=x2, 2=x3, 3=X4, 4=x5, 5=x6, 6=x7, 7=x8
                8=x3G, 9=x6G, 10=x9G (monochrome simulated gray) 
ISHOW_INT  (R)  Sets flag for whether intensity values are 
                to be shown on zooming 0-1 0=no, 1-yes
                (see show_int)
IERR       (W)  Returns status from xdl_image_reset call
 
 
'C' call:
 
int xdl_image_reset (vh, min_thr, max_thr, mono_thr, contrast,
                        color_opt, ovly_opt, bg_opt, mag_opt, show_int)
 
 
Parameters:
 
int vh;         /* View-object handle (R)*/
int min_thr;    /* Sets the minimum scaling threshold (ignore if <=
                   -10,000,000) (R) */
int max_thr;    /* Sets the maximum scaling threshold (ignore if <=
                   -10,000,000 (R) */
int mono_thr;   /* Sets the current threshold for monochome 
                    display  0-63  (ignore if < 0) (R)*/
int contrast;   /* Sets the contrast value 1-1024 (R) */
int color_opt;  /* Sets the colour choice option 1-7 
                    1-7 for colour, 1-2 for monochrome (ignore if < 0) 
                    1 = Black on white
                    2 = White on black
                    3 = Yellow if sat.
                    4 = Colour 1
                    5 = Colour 2
                    6 = User defined
                    7 = Random
                    (R) */
int ovly_opt;   /* Sets overlay option 1-3 (overlay type 1 on
                   initial call or 1-4 for overlay type 2 on
                   initial call to xdl_image.
                   1'st case 1=on, 2=off, 3=offset
                   2'nd case 1=on, 2=off, 3=ov1 on, 4=ov2 on
                   (ignore if < 0) 
                   (R) */
int bg_opt;     /* Sets the background option 1-3 (ignore if < 0) 
                   1=included, 2=subtracted, 3=background only (R) */
int mag_opt;    /* Sets the current magnification option 1-7
                   for colour or 1-10 for monochrome (ignore if < 0) 
                   1=x2, 2=x3, 3=X4, 4=x5, 5=x6, 6=x7, 7=x8
                   8=x3G, 9=x6G, 10=x9G  (monochrome simulated gray)
                   (R) */
int show_int;   /* Sets flag for whether intensity values are to be
                   shown on zooming 0-1 0=no, 1=yes (ignore if < 0) 
                   (R) */

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.14.2.8 Set local axis names - xdl_image_axnames
 
The routine xdl_image_axnames (xdlf_image_axnames) is  used  to  reset  the
names of the local axes (the default starting values are  'ax1'  and  'ax2'
for the two axes.
 
Fortran call:
 
         CALL XDLF_IMAGE_AXNAMES (IVH, XDLSTR(NAME1), LEN1,
        +                         XDLSTR(NAME2), LEN2, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
NAME1    (R)  Character string containing the name of the 1'st
              local axis (max 4 characters in length)
              ** Pass address using the XDLSTR function **
LEN1     (R)  Length of the name string - must be >0 
              (cf len1) (max 4 chars) 
NAME2    (R)  Character string containing the name of the 2'nd
              local axis (max 4 characters in length)
              ** Pass address using the XDLSTR function **
LEN2     (R)  Length of the name string - must be >0 
              (cf len1) (max 4 chars) 
IERR     (W)  Returns status from xdl_image_axnames call
 
 
'C' call:
 
int xdl_image_axnames (vh, name1, len1, name2, len2)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
char *name1;     /* Name of 1'st local axis (max 4 chars long) (R)*/
int len1;        /* Length of name (may give 0 if a null terminated string
                    is passed) (R)*/
char *name2;     /* Name of 2'nd local axis (max 4 chars long) (R)*/
int len2;        /* Length of name (may give 0 if a null terminated string
                    is passed) (R)*/

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.14.2.9 Display the image now - xdl_image_display_now
 
The  routine  xdl_image_display_now  (xdlf_image_display_now)  is  used  to
display the image. It will normally be used if non-default display settings
are required and disp_now (IDISP_NOW) was set to zero on the  initial  call
to xdl_image (xdlf_image)
 
Fortran call:
 
         CALL XDLF_IMAGE_DISPLAY_NOW (IVH, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
IERR     (W)  Returns status from xdl_image_display_now call
 
 
'C' call:
 
int xdl_image_display_now (vh)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.14.2.10 Set background image - xdl_image_background
 
The routine xdl_image_background (xdlf_image_background) is used to pass  a
background image to the image view-object. This has the same data order  as
the original image but is compressed by a factor (bg_cmp (IBG_CMP)) in  the
direction of both image axes. If  bg_typ  (IBG)  was  set  to  1  when  the
xdl_image (xdlf_image) routine was called then the background options  will
be handled via the background choice menu on the control  panel;  otherwise
the background image will be ignored.
 
Fortran call:
 
         CALL XDLF_IMAGE_BACKGROUND (IVH, IBGDATA, IBG_CMP, NF_BGOFF)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
IBGDATA  (R)  Array holding background image data (same format
              and size as for a compressed image as described
              in the call to the main xdlf_image routine.)
              (e.g. pass as in integer array with the data
              packed as needed)
              Note: a compressed background image is given
              here even if a full image was passed to the
              main routine.
              (bg_data)
IBG_CMP  (R)  Compression factor in background image (fast & slow
              axes ) 
NF_BGOFF (R)  Offset in pixels between stored rows of background
              image (to allow for storage in pre-dimensioned 2-D
              arrays.
IERR     (W)  Returns status from xdl_film_background call
 
 
'C' call:
 
int xdl_image_background (vh, bg_data, bg_cmp, nf_bgoff)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
char * bg_data;  /* Background image data; the size of the image is the
                    size of the compressed image passed to the 
                    xdl_image routine (or formed by it from the full 
                    image). The data format is the same as for the main 
                    image. (R)*/
int bg_cmp;      /* Compression factor in background image (fast & slow
                    axes (R)*/
int nf_bgoff;    /* Offset in pixels between stored rows of background
                    image (to allow for storage in pre-dimensioned 2-D
                    arrays (R)*/
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.14.2.11 Set a new image - xdl_image_newimg
 
The routine xdl_film_newimg (xdlf_image_newimg) is used to reset the  image
in the display to a new image. This image must be of the same type and have
the same dimensions as the original image.
 
Fortran call:
 
         CALL XDLF_IMAGE_NEWIMG (IVH, IMGDATA, IDISP_NOW, IERR)
 
 
Parameters:
 
IVH       (R)  View-object handle (see vh)
IMGDATA   (R)   Array holding compressed data (e.g. pass as an 
                integer array with data packed as needed)  
                (see imgdata)
IDISP_NOW (R)   Display flag =1 display immediately, =0 wait for 
                XDLF_IMAGE_DISPLAY_NOW call
IERR      (W)   Returns status from xdl_image_newimg call
 
 
'C' call:
 
int xdl_image_newimg (vh, imgdata, disp_now)
 
 
Parameters:
 
int vh;                   /* View-object handle (R)*/
char *imgdata;            /* The new image (see xdl_image call for
                             full details (R)*/
int disp_now;             /* Display now flag =1, =0 wait for 
                             xdl_image_display_now call (R)*/
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.14.2.12 Reset overlay offset values - xdl_image_ovly_offset
 
The routine xdl_image_ovly_offset (xdlf_image_ovly_offset) is used to reset
the amount by which an overlay is offset when the overlay offset option  is
selected via the image view-object control  panel.  The  default  when  the
image view-object is created is four pixels on the main image display  area
to the left and down (xoff=-4, yoff=4).
 
Fortran call:
 
         CALL XDLF_IMAGE_OVLY_OFFSET (IVH, IXOFF, IYOFF, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
IXOFF    (R)  Overlay x offset (see xoff)
IYOFF    (R)  Overlay y offset (see yoff)
IERR     (W)  Returns status from xdl_image_ovly_offset call
 
 
'C' call:
 
int xdl_image_ovly_offset (vh, xoff, yoff)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int xoff;        /* New x overlay offset (in pixels of main film 
                    display) (R)*/
int yoff;        /* New y overlay offset (R) */

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.14.2.13 Reset an overlay colour - xdl_image_set_colour
 
The routine xdl_image_set_colour (xdlf_image_set_colour) is used  to  reset
one of the 6 colours used for the overlay symbols to a user selected colour
or the colour used to  indicate  the  position  of  a  'frozen'  magnifying
window.
 
Fortran call:
 
         CALL XDLF_IMAGE_SET_COLOUR (IVH, ICOLR, IRED, IGREEN, 
        +                                 IBLUE, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
ICOLR    (R)  Overlay colour number (1 to 7) (see icolr)
IRED     (R)  Red component 0 to 65535 (see red)
IGREEN   (R)  Green component 0 to 65535 (see green)
IBLUE    (R)  Blue component 0 to 65535 (see blue)
IERR     (W)  Returns status from xdl_image_set_colour call
 
 
'C' call:
 
int xdl_image_set_colour (vh, icolr, red, blue, green)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int icolr;       /* Overlay colour number 1 to 6 for symbols or 7 
                    for the magnifying window position indicating 
                    box (R)*/
int red;         /* Red component 0 to 65535 (R)*/
int green;       /* Green component 0 to 65535 (R)*/
int blue;        /* Blue component 0 to 65535 (R)*/

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.14.2.14 Reset user defined colour map - xdl_image_set_colormap
 
The routine xdl_image_set_colormap  (xdlf_image_set_colormap)  is  used  to
reset the 'user defined' 64 colour colour map used to  display  the  image.
The use of the map is selected via the colour choice menu on the image view
object. Note that the contrast slider will have no  effect  when  the  user
defined colour map is selected.
 
Fortran call:
 
         CALL XDLF_IMAGE_SET_COLORMAP (IVH, IRED, IGREEN, 
        +                                 IBLUE, IERR)
 
 
Parameters:
 
IVH          (R)  View-object handle (see vh)
IRED(64)     (R)  64 Red components 0 to 65535 (see red)
IGREEN(64)   (R)  64 Green components 0 to 65535 (see green)
IBLUE(64)    (R)  64 Blue components 0 to 65535 (see blue)
IERR         (W)  Returns status from xdl_image_set_colormap
                  call
 
 
'C' call:
 
int xdl_image_set_colormap (vh, red, green, blue)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int red[];       /* 64 Red components 0 to 65535 (R)*/
int green[];     /* 64 Green components 0 to 65535 (R)*/
int blue[];      /* 64 Blue components 0 to 65535 (R)*/

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.14.2.15 Store and display an overlay symbol - xdl_image_symbol
 
The routine xdl_image_symbol (xdlf_image_symbol) is used to  store  details
of an overlay symbol and to display that symbol if overlays  are  currently
being displayed. Two sets of  overlay  symbols  may  be  stored.  (If  many
symbols  are  to  be   added   then,   if   possible,   use   the   routine
xdl_image_symbols (xdlf_image_symbols) instead)
 
Fortran call:
 
         CALL XDLF_IMAGE_SYMBOL (IVH, IAX1PIX, IAX2PIX, ISYMB, 
        +                             ICOLR, IOV, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
IAX1PIX  (R)  Local axis 1 pixel position in full image 
              (see ax1_pixel)
IAX2PIX  (R)  Local axis 2 pixel position in full image 
              (see ax2_pixel)
ISYMB    (R)  Symbol type (see symbol)
ICOLR    (R)  Symbol colour (1 to 6) (see color)
IOV      (R)  Overlay number 1 or 2 (see ov_num)
IERR     (W)  Returns status from xdl_image_symbol call
 
 
'C' call:
 
int xdl_image_symbol (vh, ax1_pixel, ax2_pixel, symbol, color, ov_num)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int ax1_pixel;   /* The local axis 1 pixel position (from 1 up 
                    - refers to complete uncompressed image (R) */
int ax2_pixel;   /* The local axis 2 pixel position (R) */
int symbol;      /* The symbol type
                    = 1 to 10   vertical cross - increasing size 
                                                 1 to 19 pixels
                                                 in steps of 2.
                    = 11 to 20  cross - increasing size 1 to 19 pixels 
                                        height.
                    = 21 to 30  square - increasing size 1 to 19 pixels.
                                Note: 1, 11 and 21 are single points */
int color;       /* Overlay colour type 1 to 6; Red, Yellow, Green, Cyan,
                    Blue, Magenta (by default)*/
int ov_num;      /* Overlay number 1 or 2 (R)*/

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set:  Unable to allocate additional space for
                              storing the new symbol's details
 
 
2.14.2.16 Store and display overlay symbols - xdl_image_symbols
 
The routine xdl_image_symbols (xdlf_image_symbols) is used to store details
of overlay symbols and to display those symbols if overlays  are  currently
being displayed. The symbols are added to an internal symbols list and then
sorted. Use this routine when possible if  may  symbols  are  to  be  added
rather than using individual calls to xdl_image_symbol (xdlf_image_symbol).
Two sets of overlay symbols may be used.
 
Fortran call:
 
         CALL XDLF_IMAGE_SYMBOLS (IVH, NSYMB, IAX1PIX, IAX2PIX, ISYMB, 
        +                             ICOLR, IOV, NT, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
NSYMB    (R)  No. of symbols to store (see nsymb)
IAX1PIX  (R)  Array of local axis 1 pixel positions in full 
              image (NSYMB values) (see ax1_pixel)
IAX2PIX  (R)  Array of local axis 2 pixel positions in full 
              image (NSYMB values) (see ax2_pixel)
ISYMB    (R)  Array of Symbol types or Symbol type as indicated
              by NT (see symbol)
ICOLR    (R)  Array of Symbol colours or Symbol colour as 
              indicated by NT (1 to 6) (see color)
IOV      (R)  Array of overlay numbers (1 or 2) or overlay
              number as indicated by NT (see ov_num)
NT       (R)  =1 give a single symbol type, colour and overlay 
                 number
              =0 give arrays of NSYMB symbols, colours and overlay
                 numbers (see nt)
IERR     (W)  Returns status from xdl_image_symbol call
 
 
'C' call:
 
int xdl_image_symbols (vh, nsymb, ax1_pixel, ax2_pixel, symbol, color, 
                            ov_num, nt)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int nsymb;       /* The number of symbols to be added */
int ax1_pixel[]; /* Array of local axis 1 pixel positions (from 1 up 
                    - refers to complete uncompressed image) (R) */
int ax2_pixel[]; /* Array of local axis 2 pixel positions (R) */
int symbol[];    /* Array of symbol types (nsymb values or 1 value, see nt)
                    = 1 to 10   vertical cross - increasing size 
                                                 1 to 19 pixels
                                                 in steps of 2.
                    = 11 to 20  cross - increasing size 1 to 19 pixels 
                                        height.
                    = 21 to 30  square - increasing size 1 to 19 pixels.
                                Note: 1, 11 and 21 are single points (R) */
int color[];     /* Array of Overlay colour types (nsymb values or 1 value,
                    see nt)
                    1 to 6; Red, Yellow, Green, Cyan,Blue, Magenta 
                    (by default but may be reset) (R)*/
int ov_num[];    /* Array of overlay numbers (1 or 2) (nsymb values or 1
                    value, see nt) (R)*/
int nt;          /* =0 give nsymb values for symbol types and colours
                    =1 give a single value for the symbol type and colour 
                       and use this for all the symbols being added (R)*/

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set:  Unable to allocate additional space for
                              storing the new symbol's details
 
 
2.14.2.17 Clear overlay symbols - xdl_image_clear_symbols
 
The routine xdl_image_clear_symbols (xdlf_image_clear_symbols) is  used  to
clear all overlay symbols from the symbols list and from the display.
 
Fortran call:
 
         CALL XDLF_IMAGE_CLEAR_SYMBOLS (IVH, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
IERR     (W)  Returns status from xdl_image_clear_symbols 
              call
 
 
'C' call:
 
int xdl_image_clear_symbols (vh)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.14.2.18 Delete an overlay symbol - xdl_image_del_symbol
 
The routine xdl_image_del_symbol (xdlf_image_del_symbol) is used to  delete
an overlay symbol from the symbols list and remove it from the display.  If
there are many symbols to delete it may be quicker  to  clear  all  symbols
(xdl_image_clear_symbols (xdlf_image_clear_symbols)) and create a new  list
using xdl_image_symbols (xdlf_image_symbols)
 
Fortran call:
 
         CALL XDLF_IMAGE_DEL_SYMBOL (IVH, IAX1PIX, IAX2PIX, ISYMB,
        +                                 ICOLR, IOV, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
IAX1PIX  (R)  Local axis 1 pixel position of symbol (full 
              image pixel numbering) (see ax1_pixel)
IAX2PIX  (R)  Local axis 2 pixel position (see ax2_pixel)
ISYMB    (R)  If > 0, only delete the symbol if it is of the 
              type ISYMB (see symbol)
ICOLR    (R)  If > 0, only delete the symbol if it is of the 
              colour ICOLR (see color)
IOV      (R)  If > 0, only delete the symbol if it is of the
              overlay number IOV (see ov_num)
IERR     (W)  Returns status from xdl_image_del_symbol call
 
 
'C' call:
 
int xdl_image_del_symbol (vh, ax1_pixel, ax2_pixel, symbol, color, 
                               ov_num)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int ax1_pixel;   /* Local axis 1 pixel position of the symbol (from 1 up
                    - refers to complete uncompressed image) (R)*/
int ax2_pixel;   /* Local axis 2 pixel position of the symbol (from 1 up 
                    - refers to complete uncompressed image) (R)*/
int symbol;      /* If > 0 then only delete the symbol if it is of the
                    type 'symbol' (see xdl_image_symbol routine for
                    details of symbol types) (R)*/
int color;       /* If > 0 then only delete the symbol if it is of the 
                    colour 'color' (see xdl_image_symbol routine 
                    for details of the colour types) (R)*/
int ov_num;      /* If > 0 then only delete the symbol if it is of
                    the overlay number ov_num (1 or 2) (R)*/

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set;  Symbol not found
 
 
2.14.2.19 Store and display an overlay vector - xdl_image_vect
 
The routine xdl_image_vect (xdlf_image_vect) is used to store details of an
overlay vector and to display that vector if overlays are  currently  being
displayed. Two sets of overlay vectors may be stored. The user  supplies  a
vector identifier number for a vector and this is used to identify a vector
or set of vectors for deletion if required.
 
Fortran call:
 
         CALL XDLF_IMAGE_VECT (IVH, IVECT, IAX1PIX1, IAX2PIX1, 
        +                           IAX1PIX2, IAX2PIX2,
        +                           ICOLR, IOV, MAGUPD, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
IVECT    (R)  User selected number to identify vector
              (0-65535). The same number may be used
              for more than one vector to identify a
              set of vectors (see vect_id)
IAX1PIX1 (R)  Local axis 1 start pixel position in full image 
              (see ax1_1_pixel)
IAX2PIX1 (R)  Local axis 2 start pixel position in full image 
              (see ax2_1_pixel)
IAX1PIX2 (R)  Local axis 1 end pixel position in full image 
              (see ax2_2_pixel)
IAX2PIX2 (R)  Local axis 2 end pixel position in full image 
              (see ax2_2_pixel)
ICOLR    (R)  Vector colour (1 to 6) (see color)
IOV      (R)  Overlay number 1 or 2 (see ov_num)
MAGUPD   (R)  =1 Update magnifying window and flush X buffer
                 after drawing vector,
              =0 do not (see magw_upd)
IERR     (W)  Returns status from xdl_image_vect call
 
 
'C' call:
 
int xdl_image_vect (vh, vect_id, ax1_1_pixel, ax2_1_pixel, 
                         ax1_2_pixel, ax2_2_pixel, color, ov_num, magw_upd)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int vect_id;     /* User selected number to identify vector (0-65535). 
                    The same number may be used for more than one vector to 
                    identify a set of vectors (R)*/
int ax1_1_pixel; /* The vector start local axis 1 pixel position (from 1 
                    up - refers to complete uncompressed image (R) */
int ax2_1_pixel; /* The vector start local axis 2 pixel position (R) */
int ax1_2_pixel; /* The vector end local axis 1 pixel position (R) */
int ax2_2_pixel; /* The vector end local axis 2 pixel position (R) */
int color;       /* Overlay colour type 1 to 6; Red, Yellow, Green, Cyan,
                    Blue, Magenta (by default)*/
int ov_num;      /* Overlay number 1 or 2 (R)*/
int magw_upd;    /* =1 Update the magnifying window and flush X buffer
                       after drawing the  vector; this should be used 
                       when a single vector is drawn or when the final 
                       vector of a series of vectors is drawn.
                    =0 Do not; this enables a series of vectors to be
                       drawn much more rapidly; it should be used when
                       a series of vectors is to be drawn for all but
                       the final vector (R)*/

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set:  Unable to allocate additional space for
                              storing the new vector's details
 
 
2.14.2.20 Store and display overlay vectors - xdl_image_vects
 
The routine xdl_image_vects (xdlf_image_vects) is used to store details  of
a set of overlay vectors and to  display  those  vectors  if  overlays  are
currently being displayed. Two sets of overlay vectors may be  stored.  The
user supplies a vector identifier set number for the vectors  and  this  is
used to identify the set of vectors for deletion if required.
 
Fortran call:
 
         CALL XDLF_IMAGE_VECTS (IVH, IVECT, NUM_VECT, IAX1PIX1, IAX2PIX1, 
        +                           IAX1PIX2, IAX2PIX2,
        +                           ICOLR, IOV, MAGUPD, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
IVECT    (R)  User selected number to identify vector set
              (0-65535). (see vect_id)
NUM_VECT (R)  The number of vectors
IAX1PIX1 (R)  Local axis 1 start pixel positions in full image 
              (see ax1_1_pixel) (array of NUM_VECT values)
IAX2PIX1 (R)  Local axis 2 start pixel positions in full image 
              (see ax2_1_pixel) (array of NUM_VECT values)
IAX1PIX2 (R)  Local axis 1 end pixel positions in full image 
              (see ax2_2_pixel) (array of NUM_VECT values)
IAX2PIX2 (R)  Local axis 2 end pixel positions in full image 
              (see ax2_2_pixel) (array of NUM_VECT values)
ICOLR    (R)  Vector colour (1 to 6) (see color)
IOV      (R)  Overlay number 1 or 2 (see ov_num)
MAGUPD   (R)  =1 Update magnifying window after drawing vector,
              =0 do not (see magw_upd)
IERR     (W)  Returns status from xdl_image_vects call
 
 
'C' call:
 
int xdl_image_vects (vh, vect_id, num_vect, ax1_1_pixel, ax2_1_pixel, 
                         ax1_2_pixel, ax2_2_pixel, color, ov_num, magw_upd)
 
 
Parameters:
 
int vh;           /* View-object handle (R)*/
int vect_id;      /* User selected number to identify vector (0-65535). 
                     The same number may be used for more than one vector to 
                     identify a set of vectors (R)*/
int num_vect;     /* Number of vectors to be added */
int *ax1_1_pixel; /* The vector start local axis 1 pixel positions (from 1 
                     up - refers to complete uncompressed image 
                     (array of num_vect values (R) */
int *ax2_1_pixel; /* The vector start local axis 2 pixel positions
                     (array of num_vect values  (R) */
int *ax1_2_pixel; /* The vector end local axis 1 pixel positions
                     (array of num_vect values  (R) */
int *ax2_2_pixel; /* The vector end local axis 2 pixel positions
                     (array of num_vect values  (R) */
int color;        /* Overlay colour type 1 to 6; Red, Yellow, Green, Cyan,
                     Blue, Magenta (by default)*/
int ov_num;       /* Overlay number 1 or 2 (R)*/
int magw_upd;     /* =1 Update the magnifying window after drawing the 
                        vectors; this should be used when all the
                        required vectors have been defined.
                     =0 Do not (R) */

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set:  Unable to allocate additional space for
                              storing the new vector's details
 
 
2.14.2.21 Store and display overlay vectors - xdl_image_vects_pos
 
The routine xdl_image_vects_pos (xdlf_image_vects_pos)  is  used  to  store
details of a set of  overlay  vectors  and  to  display  those  vectors  if
overlays are currently being displayed. Two sets of overlay vectors may  be
stored. The user supplies a vector identifier set number  for  the  vectors
and this is used to identify the set of vectors for deletion  if  required.
In contrast to xdl_image_vects (xdlf_image_vects)  which  always  positions
the vector ends at the centre of a displayed pixel, this routine allows the
user some further options for positioning the vector ends with  respect  to
the displayed pixels.
 
Fortran call:
 
         CALL XDLF_IMAGE_VECTS_POS (IVH, IVECT, NUM_VECT, 
        +                           IAX1PIX1, IAX2PIX1, 
        +                           IAX1PIX2, IAX2PIX2,
        +                           IAX1POS1, IAX2POS1, 
        +                           IAX1POS2, IAX2POS2,
        +                           ICOLR, IOV, MAGUPD, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
IVECT    (R)  User selected number to identify vector set
              (0-65535). (see vect_id)
NUM_VECT (R)  The number of vectors
IAX1PIX1 (R)  Local axis 1 start pixel positions in full image 
              (see ax1_1_pixel) (array of NUM_VECT values)
IAX2PIX1 (R)  Local axis 2 start pixel positions in full image 
              (see ax2_1_pixel) (array of NUM_VECT values)
IAX1PIX2 (R)  Local axis 1 end pixel positions in full image 
              (see ax2_2_pixel) (array of NUM_VECT values)
IAX2PIX2 (R)  Local axis 2 end pixel positions in full image 
              (see ax2_2_pixel) (array of NUM_VECT values)
IAX1POS1 (R)  Position option flags for local axis 1 start pixels
              (array of NUM_VECT values)
IAX2POS1 (R)  Position option flags for local axis 2 start pixels
              (array of NUM_VECT values)
IAX1POS2 (R)  Position option flags for local axis 1 end pixels
              (array of NUM_VECT values)
IAX2POS2 (R)  Position option flags for local axis 2 end pixels
              (array of NUM_VECT values)
ICOLR    (R)  Vector colour (1 to 6) (see color)
IOV      (R)  Overlay number 1 or 2 (see ov_num)
MAGUPD   (R)  =1 Update magnifying window after drawing vector,
              =0 do not (see magw_upd)
IERR     (W)  Returns status from xdl_image_vects_pos call

              Note: Position flags   = 0   Centre of displayed pixel
                                     =-1   Low side of displayed pixel
                                     =+1   High side of displayed pixel
                                     =-2   Just outside low side
                                     =+2   Just outside high side
 
 
'C' call:
 
int xdl_image_vects_pos (vh, vect_id, num_vect, ax1_1_pixel, ax2_1_pixel, 
                       ax1_2_pixel, ax2_2_pixel, ax1_1_pos, ax2_1_pos,
                       ax1_2_pos, ax2_2_pos, color, ov_num, magw_upd)
 
 
Parameters:
 
int vh;           /* View-object handle (R)*/
int vect_id;      /* User selected number to identify vector (0-65535). 
                     The same number may be used for more than one vector to 
                     identify a set of vectors (R)*/
int num_vect;     /* Number of vectors to be added */
int *ax1_1_pixel; /* The vector start local axis 1 pixel positions (from 1 
                     up - refers to complete uncompressed image 
                     (array of num_vect values (R) */
int *ax2_1_pixel; /* The vector start local axis 2 pixel positions
                     (array of num_vect values  (R) */
int *ax1_2_pixel; /* The vector end local axis 1 pixel positions
                     (array of num_vect values  (R) */
int *ax2_2_pixel; /* The vector end local axis 2 pixel positions
                     (array of num_vect values  (R) */
int *ax1_1_pos;   /* Position option flags for local axis 1 start pixels
                     (array of num_vect values  (R) */
int *ax2_1_pos;   /* Position option flags for local axis 2 start pixels
                     (array of num_vect values  (R) */
int *ax1_2_pos;   /* Position option flags for local axis 1 end pixels
                     (array of num_vect values  (R) */
int *ax2_2_pos;   /* Position option flags for local axis 2 end pixels
                     (array of num_vect values  (R) */
int color;        /* Overlay colour type 1 to 6; Red, Yellow, Green, Cyan,
                     Blue, Magenta (by default)*/
int ov_num;       /* Overlay number 1 or 2 (R)*/
int magw_upd;     /* =1 Update the magnifying window after drawing the 
                        vectors; this should be used when all the
                        required vectors have been defined.
                     =0 Do not (R) */

         /*   Note: Position flags   = 0   Centre of displayed pixel
                                     =-1   Low side of displayed pixel
                                     =+1   High side of displayed pixel
                                     =-2   Just outside low side
                                     =+2   Just outside high side  */
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set:  Unable to allocate additional space for
                              storing the new vector's details
 
 
2.14.2.22 Store and display overlay boxes - xdl_image_boxes
 
The routine xdl_image_boxes (xdlf_image_boxes) is used to store details  of
a set of overlay boxes surrounding a rectangle of  pixels  and  to  display
those boxes if overlays are currently being displayed.  The  routine  saves
each box as a set of vectors (see also xdl_image_vect  and  xdlf_image_vect
etc.). The user supplies a vector identifier set number for the box vectors
and this is used to identify the set of vectors for deletion if required.
 
Fortran call:
 
         CALL XDLF_IMAGE_BOXES (IVH, IVECT, NUM_BOX, IAX1PIX1, IAX2PIX1, 
        +                       IAX1PIX2, IAX2PIX2, IPOS, 
        +                       ICOLR, IOV, MAGUPD, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
IVECT    (R)  User selected number to identify vector set associated 
              with the boxes (0-65535). (see vect_id)
NUM_BOX  (R)  The number of boxes
IAX1PIX1 (R)  Local axis 1 start corner pixel positions in full image 
              (see ax1_1_pixel) (array of NUM_BOX values)
IAX2PIX1 (R)  Local axis 2 start corner pixel positions in full image 
              (see ax2_1_pixel) (array of NUM_BOX values)
IAX1PIX2 (R)  Local axis 1 end corner pixel positions in full image 
              (see ax2_2_pixel) (array of NUM_BOX values)
IAX2PIX2 (R)  Local axis 2 end corner pixel positions in full image 
              (see ax2_2_pixel) (array of NUM_BOX values)
IPOS     (R)  = 1 position just within pixel boundaries
              = 2 position just outside pixel boundaries
ICOLR    (R)  Vector colour (1 to 6) (see color)
IOV      (R)  Overlay number 1 or 2 (see ov_num)
MAGUPD   (R)  =1 Update magnifying window after drawing vector,
              =0 do not (see magw_upd)
IERR     (W)  Returns status from xdl_image_boxes call
 
 
'C' call:
 
int xdl_image_boxes (vh, vect_id, num_box, ax1_1_pixel, ax2_1_pixel, 
                         ax1_2_pixel, ax2_2_pixel, ipos,
                         color, ov_num, magw_upd)
 
 
Parameters:
 
int vh;           /* View-object handle (R)*/
int vect_id;      /* User selected number to identify vector (0-65535). 
                     The same number may be used for more than one vector to 
                     identify a set of vectors (R)*/
int num_box;      /* Number of boxes to be added */
int *ax1_1_pixel; /* The vector start corner local axis 1 pixel positions 
                     (from 1 up - refers to complete uncompressed image 
                     (array of num_box values (R) */
int *ax2_1_pixel; /* The vector startcorner local axis 2 pixel positions
                     (array of num_box values  (R) */
int *ax1_2_pixel; /* The vector end corner local axis 1 pixel positions
                     (array of num_box values  (R) */
int *ax2_2_pixel; /* The vector end corner local axis 2 pixel positions
                     (array of num_box values  (R) */
int ipos;         /*  = 1 position just within pixel boundaries
                      = 2 position just outside pixel boundaries (R) */
int color;        /* Overlay colour type 1 to 6; Red, Yellow, Green, Cyan,
                     Blue, Magenta (by default)*/
int ov_num;       /* Overlay number 1 or 2 (R)*/
int magw_upd;     /* =1 Update the magnifying window after drawing the 
                        boxes; this should be used when all the
                        required boxes have been defined.
                     =0 Do not (R) */

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set:  Unable to allocate additional space for
                              storing the new vector's details
 
 
2.14.2.23 Clear overlay vectors - xdl_image_clear_vectors
 
The routine xdl_image_clear_vects (xdlf_image_clear_vects) is used to clear
all overlay vectors from the vectors list and from the display.
 
Fortran call:
 
         CALL XDLF_IMAGE_CLEAR_VECTS (IVH, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
IERR     (W)  Returns status from xdl_image_clear_vects
              call
 
 
'C' call:
 
int xdl_image_clear_vects (vh)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.14.2.24 Delete an overlay vector - xdl_image_del_vect
 
The routine xdl_image_del_vect (xdlf_image_del_vect) is used to  delete  an
overlay vector (or set of vectors with a common vector identifier) from the
vectors list and remove it (them) from  the  display.  If  there  are  many
vectors  to   delete   it   may   be   quicker   to   clear   all   vectors
(xdl_image_clear_vects (xdlf_image_clear_vects))  and  create  a  new  list
using xdl_image_vect (xdlf_image_vect)
 
Fortran call:
 
         CALL XDLF_IMAGE_DEL_VECT (IVH, IVECT, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
IVECT    (R)  The vector identifier of the vector or set of
              vectors to be deleted (see vect_id)
IERR     (W)  Returns status from xdl_image_del_vect call
 
 
'C' call:
 
int xdl_image_del_vect (vh, vect_id)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int vect_id;     /* Vector identifier for the vector or set of vectors
                    to be deleted (R) */

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set;  Vector not found
 
 
2.14.2.25 Output a text string - xdl_image_text
 
The routine xdl_image_text (xdlf_image_text)  is  used  to  output  a  text
string to the main display area.
 
Fortran call:
 
         CALL XDLF_IMAGE_TEXT (IVH, ITEXT, IAX1PIXEL, IAX2PIXEL,
        +                      XDLSTR(STRING), LEN, ICOLOR, IFONT, 
        +                      IBOLD, IOV_NUM, IERR)
 
 
Parameters:
 
IVH        (R)  View-object handle (see vh)
ITEXT      (R)  User selected text string identifier (used
                to identify a string or set of strings for
                deletion) (0-65535) 
IAX1PIXEL  (R)  Pixel position wrt. local axis 1 for start of text
                string output
IAX2PIXEL  (R)  Pixel position wrt. local axis 2 for start of text
                string output
STRING     (R)  The text string 
                ** Pass address using the XDLSTR function **
LEN        (R)  The length of the string; must be > 0 (cf len)
ICOLOR     (R)  Overlay colour type =0 for black or 1 to 6; Red, 
                Yellow, Green, Cyan, Blue, Magenta (by default)
IFONT      (R)  Font no. 1-5 very-small, small, medium, large,
                very-large
IBOLD      (R)  = 0 normal text, =1 bold text
IOV_NUM    (R)  Overlay number 1 or 2 
IERR       (W)  Returns status from xdl_image_text call
 
 
'C' call:
 
int xdl_image_text (vh, text_id, ax1_pixel, ax2_pixel, string, len,
                    color, font_type, bold, ov_num)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int text_id;     /* User selected text string identifier (used
                    to identify a string or set of strings for
                    deletion) (0-20000) (R) */
int ax1_pixel;   /* Pixel position wrt. local axis 1 for start of text
                    string output (R)*/
int ax2_pixel;   /* Pixel position wrt. local axis 2 for start of text
                    string output (R)*/
char * string;   /* The text string */
int len;         /* The length of the text string; may give 0 if the
                    string is null terminated (R)*/
int color;       /* Overlay colour type =0 for black or 1 to 6; Red, 
                    Yellow, Green, Cyan, Blue, Magenta (by default)*/
int font_type;   /* Font type number 1-5, very-small, small, medium,
                    large, very-large (R)*/
int bold;        /* =0 normal text, =1 bold text */
int ov_num;      /* Overlay number 1 or 2 (R)*/
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.14.2.26 Delete a text string - xdl_image_del_text
 
The routine xdl_image_del_text (xdlf_image_del_text) is used to  delete  an
overlay text string (or set of text strings with a common text  identifier)
from the text strings list and remove it (them) from the display. If  there
are many text strings to delete it may be quicker to  clear  all  the  text
strings (xdl_image_clear_text (xdlf_image_clear_text)) and create a new set
using xdl_image_text (xdlf_image_text)
 
Fortran call:
 
         CALL XDLF_IMAGE_DEL_TEXT(IVH, ITEXT, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
ITEXT    (R)  The text string identifier of the text string 
              or set of text strings to be deleted (see text_id)
IERR     (W)  Returns status from xdl_image_del_text call
 
 
'C' call:
 
int xdl_image_del_text (vh, text_id)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
int text_id;     /* Text identifier for the text string or set of text
                    strings to be deleted (R) */

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  bit 2 set;  Vector not found
 
 
2.14.2.27 Clear all text strings - xdl_image_clear_text
 
The routine xdl_image_clear_text (xdlf_image_clear_text) is used  to  clear
(delete) all text strings which were previously output to the main  display
window.
 
Fortran call:
 
         CALL XDLF_IMAGE_CLEAR_TEXT (IVH, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
IERR     (W)  Returns status from xdl_image_clear_text call
 
 
'C' call:
 
int xdl_image_clear_text (vh)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.14.2.28 Reset active strip message - xdl_image_input_message
 
The routine xdl_image_input_message (xdlf_image_input_message) is  used  to
reset the message which will appear  in  the  active  strip  when  a  pixel
position or selected rectangle is to be input. When the  image  view-object
is created, the default message is 'Input spot positions'.
 
Fortran call:
 
         CALL XDLF_IMAGE_INPUT_MESSAGE (IVH, XDLSTR(MESSAGE), 
        +                                    LEN, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
MESSAGE  (R)  Character string containing the message 
              (see message)
              ** Pass address using the XDLSTR function **
LEN      (R)  Length of the message string - must be >0 
              (cf len) (max 60 chars) 
IERR     (W)  Returns status from xdl_image_input_message 
              call
 
 
'C' call:
 
int xdl_image_input_message (vh, message, len)
 
 
Parameters:
 
int vh;          /* View-object handle (R)*/
char *message;   /* Message string (max of 60 chars long) (R)*/
int len;         /* Length of the message string; if 0 then length 
                    will be found assuming a null terminated string 
                    (R)*/

 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
 
 
2.14.2.29 Calculate the size requirements - xdl_image_getsize
 
The routine xdl_image_getsize (xdlf_image_getsize) is used to calculate the
size of an image view-object given the size of the image to be displayed.
 
Fortran call:
 
         CALL XDLF_IMAGE_GETSIZE (NREQ_AX1, NREQ_AX2, IORDER, JORDER,
                                  NCMP, IWIDTH, IHEIGHT)
 
 
Parameters:
 
NREQ_AX1   (R)  Section size along local axis 1 (see nreq_ax1)
NREQ_AX2   (R)  Section size along local axis 2 (see nreq_ax1)
IORDER     (R)  Image data order wrt. local axes (1-8)
                (see XDLF_IMAGE routine) 
JORDER     (R)  Display axis order wrt. local axes (1-8)
                (see XDLF_IMAGE routine) 
NCMP       (R)  No. of pixels compressed into 1 pixel
                along each axis
IWIDTH     (W)  Returns the width required (see w)
IHEIGHT    (W)  Returns the height required (see h)
 
 
'C' call:
 
void xdl_image_getsize (nreq_ax1, nreq_ax2, iorder, jorder, ncmp, w, h)
 
 
Parameters:
 
int nreq_ax1;            /* Section size along local axis 1 (R) */
int nreq_ax2;            /* Section size along local axis 2 (R) */
int iorder;              /* Image data order wrt. local axes (1-8)
                            (see xdl_image routine) (R)*/
int jorder;              /* Display axis order wrt. local axes (1-8)
                            (see xdl_image routine) (R)*/
int ncmp;                /* No. of pixels compressed into 1 pixel
                            along each axis */
int *w;                  /* Returns the width required (W)*/
int *h;                  /* Returns the height required (W)*/

 
 
Return:  None
 
 

2.15 THE LAUE SIMULATIONS VIEW-OBJECT ROUTINES
==============================================


2.15.1 INTRODUCTION
 
The Laue simulation view-object is used to display the simulation of a Laue
pattern (the pattern prediction itself  must  be  done  externally  to  the
routine). The view-object allows either for colour coded simulations or for
black and white simulations where the  soft  limits  can  be  modified  via
sliders to show the effects that they have on the patterns. The indices  of
selected spots may be displayed. Labels may be drawn on the black and white
simulations. The view-object also provides a hard  copy  (Postscript  file)
option. As an alternative, the  simulation  may  also  be  displayed  as  a
gnomonic projection if desired.
 
The following sets of routines are available:
 
   Creating and Handling a Laue Simulations View-Object
 
2.15.2 CREATING AND HANDLING A LAUE SIMULATIONS VIEW-OBJECT
 
2.15.2.1 Introduction
 
The following routines are available:
 
   Create a Laue simulation view-object - xdl_laue_sim
   Calculate size requirements - xdl_laue_sim_getsize
   Display a new simulation - xdl_laue_sim_new
 
2.15.2.2 Create a Laue simulation view-object - xdl_laue_sim
 
The routine xdl_laue_sim (xdlf_laue_sim) is  used  to  create  a  new  Laue
simulation  display  view-object.  The  simulation  itself  is   calculated
externally to the routine and the details are passed  to  the  routine  for
display. The simulation may also be displayed as a gnomonic  projection  if
desired.
 
Fortran call:
 
         CALL XDLF_LAUE_SIM (IVH, IVHPARENT, IX, IY, ICSET, ITYPE, ISIZE,
        +                    NSPOT, IHKL, XF, YF, ALAM, DTHR, MULTI,FLAGS, 
        +                    NODHKLS, IDXLAM, IDXDMIN, IDXNOD, FILMR, 
        +                    GNOMR, ALMIN, ALMAX, DMIN, D_LMIN, D_LMAX, 
        +                    D_DMIN, CELL, PHIS, LATT, CTOF,
        +                    MINW, MINH, IERR)
 
 
Parameters:
 
IVH       (R)   View-object handle (see vh)
IVHPARENT (R)   View-object handle for parent 0=none 
                (see vh_parent)
IX        (R)   X position (may be -1 if no parent) (see x)
IY        (R)   Y position (may be -1 if no parent) (see y)
ICSET     (R)   Colorset number (see cset)
ITYPE     (R)   Simulation type =1 Colour, = 2 Monochrome with
                soft limits options etc. (see type)
ISIZE     (R)   Half width/height for displayed pattern in 
                pixels (see size)
NSPOT     (R)   Number of spots predicted (see nspot)
IHKL      (R)   Array of NSPOT packed indices (see hkl)
XF        (R)   Array of NSPOT 'xf' coordinates (see xf)
YF        (R)   Array of NSPOT 'yf' coordinates (see yf)
ALAM      (R)   Array of NSPOT lambda values (see lam)
DTHR      (R)   Array of NSPOT (1/dmin)**2 thresholds (see dthr)
MULTI     (R)   Array of NSPOT multiplicict data flags (see multi)
FLAGS     (R)   Array of NSPOT reflection flags (see flags)
NODHKLS   (R)   Array of NSPOT packed nodal indices (see nodhkls)
IDXLAM    (R)   Index array for lambda sorted data;
                NSPOT values from 1 to NSPOT (see idxlam)
IDXDMIN   (R)   Index array for dmin sorted data;
                NSPOT values from 1 to NSPOT (see idxdmin)
IDXNOD    (R)   Index array for packed nodal index values 
                (see idxnod)
FILMR     (R)   Pattern radius in mm (see filmr)
GNOMR     (R)   Minimum radius in mm (>0.1) from image centre for 
                conversion of plot to a gnomonic projection. For
                a normal Laue simulation, give a value of 0.0
ALMIN     (R)   Lambda minimum of prediction (see lmin)
ALMAX     (R)   Lambda maximum of prediction (see lmax)
DMIN      (R)   Dmin value of prediction (see dmin)
D_LMIN    (R)   Interval for lambda-min slider (see d_lmin)
D_LMAX    (R)   Interval for lambda-max slider (see d_lmax)
D_DMIN    (R)   Interval for dmin slider (see d_dmin)
CELL      (R)   Array of the 6 real cell dimensions (see cell)
PHIS      (R)   Array of 4 setting angles, Phix, Phiy, Phiz and
                spindle (see phis)
LATT      (R)   4 integer array; crystal system, lattice type,
                rotation axis, beam axis (see latt)
CTOF      (R)   Crystal to film distance (mm) (see ctof)
MINW      (R)   Minimum width for view-object or 0 
                (see min_width)
MINH      (R)   Minimum height for view-object or 0 
                (see min_height)
IERR      (W)   Returns status from xdl_laue_sim call
 
 
'C' call:
 
int xdl_laue_sim (int vh, int vh_parent, int x, int y, int cset, int type, 
                  int size, int nspot, int * hkl, float * xf, float * yf, 
                  float * lam, float * dthr, int * multi, int * flags, 
                  int * nodhkls, int * idxlam, int * idxdmin, int * idxnod, 
                  float filmr, float gnomr, float lmin, float lmax,  
                  float dmin, float d_lmin, float d_lmax, float d_dmin, 
                  float * cell, float * phis, int * latt, float ctof,
                  int min_width, int min_height)
 
 
Parameters:
 
int       vh;              User selected view-object handle (R)
int       vh_parent;       View-object handle for the parent base frame, 
                           if 0 then a base  level frame is created to
                           enclose the view-object (R)
int       x;               x coordinate for the view-object.
                           If no parent may be -1 to give default x (R)
int       y;               y coordinate for the view-object.
                           If no parent may be -1 to give default y (R)
int       cset;            Number of the colorset to be used; must
                           have 53 or more colorcells allocated (R) 
int       type;            Simulation type =1 Colour, =2 Monochrome with
                           soft limit sliders etc.
int       size;            Pattern display area half width/height in
                           pixels (R)
int       nspot;           Number of spots predicted (R)
int       hkl[];           Array of 'nspot' 'hkl' packed indices 
                           (as LRL) (R)
float     xf[];            Array of 'nspot' 'xf' coordinates in mm from
                           the pattern centre (R) 
float     yf[];            Array of 'nspot' 'yf' coordinates in mm from
                           the pattern centre (R) 
float     lam[];           Array of 'nspot' lambda values (R)
float     dthr[];          Array of 'nspot' (1/dmin)**2 threshold values
                           (R)
int       multi[];         Array of 'nspot' multiplicity flags (format
                           as for 'LRL' data 
                               = 1 single
                               > 1 2**20*mult + 2**12*min-hrm 
                                   + 2**4*max-hrm + harm_inc 
int       flags[];         Array of 'nspot' reflection flags
                           Flags format as for 'LRL' data
                           Bit 0 set = spatial overlap; this is the only
                                       bit used by this routine.
                           (R)
int       nodhkls[];       Array of 'nspot' packed nodal indices; packed
                           as 2**20(h+512)+2**10(k+512)+l+512 (R)
int       idxlam[];        Index array for data sorted by lambda, 'nspot'
                           values from 1 to nspot (R)
int       idxdmin[];       Index array for data sorted by dmin 'nspot'
                           values from 1 to nspot (R)
int       idxnod[];        Index array for data sorted by packed nodal
                           index from 1 to nspot (R)
float     filmr;           Pattern radius in mm (R)
float     gnomr;           Minimum radius in mm (>0.1) from image 
                           centre for conversion of plot to a gnomonic 
                           projection. For a normal Laue simulation, 
                           give a value of 0.0 (R) 
float     lmin;            Lambda minimum of prediction (R)
float     lmax;            Lambda maximum of prediction (R)
float     dmin;            Dmin value of prediction (R)
float     d_lmin;          Lambda interval in Angstoms for lambda-min
                           slider (R)
float     d_lmax;          Lambda interval in Angstoms for lambda-max
                           slider (R)
float     d_dmin;          Dmin interval in Angstoms for dmin slider 
                           (R)
float     cell[6];         Real cell dimensions a, c, c, alpha, beta, 
                           gamma (R)
float     phis[4];         Setting angles phix, phiy, phiz, spindle (R)
int       latt[4];         Crystal system, lattice, rotation axis,
                           beam axis (R)
float     ctof;            Crystal to film distance (mm) 
int       min_width;       The program will calculate the width required
                           for the view-object based on the display area
                           width, control panel width etc. If this is
                           less than min_width then min_width will be
                           used instead and the layout altered to reflect
                           this (R)
int       min_height;      minimum height cf min_width (R)

 Note: Data arrays hkl[],.....idxnod[] must remain in place during
         the lifetime of the view-object 

 
 
Return:  Status flag =0 OK, >0 error
         bit 0 set: Requested parent not found in the view-objects list
         bit 1 set: Unable to allocate memory for x, y pixel positions
                    arrays.
 
 
2.15.2.3 Calculate size requirements - xdl_laue_sim_getsize
 
The routine xdl_laue_sim_getsize (xdlf_laue_sim_getsize) is used to get the
required size for a Laue simulation display view-object.
 
Fortran call:
 
         CALL XDLF_LAUE_SIM_GETSIZE (ITYPE, ISIZE, IWIDTH, IHEIGHT)
 
 
Parameters:
 
ITYPE     (R)   Simulation type =1 Colour, = 2 Monochrome with
                soft limits options etc. (see type)
ISIZE     (R)   Half width/height for displayed pattern in 
                pixels (see size)
IWIDTH    (W)   Returns the width required (see w)
IHEIGHT   (W)   Returns the height required (see h)
 
 
'C' call:
 
void xdl_laue_sim_getsize (type, size, w, h)
 
 
Parameters:
 
int       type;           /* Simulation type =1 Colour, =2 Monochrome with
                             soft limit sliders etc.*/
int       size;           /* Pattern display area half width/height in
                             pixels (R)*/
int *w;                   /* Returns the width required (W)*/
int *h;                   /* Returns the height required (W)*/

 
 
Return:  None
 
 
2.15.2.4 Display a new simulation - xdl_laue_sim_new
 
The routine xdl_laue_sim_new (xdlf_laue_sim_new) is used to display  a  new
Laue simulation in a Laue simulation view-object.  The  currently  selected
options for the view-object are unchanged. If, for type 2 plots, the lambda
limits or dmin value are changed then new current  values  for  lambda-min,
lambda-max and  dmin  will  be  calculated  based  on  the  current  slider
positions. All current labels will be removed.
 
Fortran call:
 
         CALL XDLF_LAUE_SIM_NEW (IVH, NSPOT, IHKL, XF, YF, 
        +                    ALAM, DTHR, MULTI, FLAGS,
        +                    NODHKLS, IDXLAM, IDXDMIN, IDXNOD, FILMR, 
        +                    GNOMR, ALMIN, ALMAX, DMIN, 
        +                    CELL, PHIS, LATT, CTOF, IERR)
 
 
Parameters:
 
IVH       (R)   View-object handle (see vh)
NSPOT     (R)   Number of spots predicted (see nspot)
IHKL      (R)   Array of NSPOT 'packed' indices (see hkl)
IK        (R)   Array of NSPOT 'k' indices (see k)
IL        (R)   Array of NSPOT 'l' indices (see l)
XF        (R)   Array of NSPOT 'xf' coordinates (see xf)
YF        (R)   Array of NSPOT 'yf' coordinates (see yf)
ALAM      (R)   Array of NSPOT lambda values (see lam)
DTHR      (R)   Array of NSPOT (1/dmin)**2 thresholds (see dthr)
MULTI     (R)   Array of NSPOT multiplicities flags (see multi)
FLAGS     (R)   Array of NSPOT reflection flags (see flags)
NODHKLS   (R)   Array of NSPOT packed nodal indices (see nodhkls)
IDXLAM    (R)   Index array for lambda sorted data;
                NSPOT values from 1 to NSPOT (see idxlam)
IDXDMIN   (R)   Index array for dmin sorted data;
                NSPOT values from 1 to NSPOT (see idxdmin)
IDXNOD    (R)   Index array for packed nodal index values 
                (see idxnod)
FILMR     (R)   Pattern radius in mm (see filmr)
GNOMR     (R)   Minimum radius in mm (>0.1) from image centre for 
                conversion of plot to a gnomonic projection. For
                a normal Laue simulation, give a value of 0.0
ALMIN     (R)   Lambda minimum of prediction (see lmin)
ALMAX     (R)   Lambda maximum of prediction (see lmax)
DMIN      (R)   Dmin value of prediction (see dmin)
CELL      (R)   Array of the 6 real cell dimensions (see cell)
PHIS      (R)   Array of 4 setting angles, Phix, Phiy, Phiz and
                spindle (see phis)
LATT      (R)   4 integer array; crystal system, lattice type,
                rotation axis, beam axis (see latt)
CTOF      (R)   Crystal to film distance (mm) (see ctof)
IERR      (W)   Returns status from xdl_laue_sim_new call
 
 
'C' call:
 
int xdl_laue_sim_new (int vh, int nspot, int * hkl, float * xf, float * yf, 
                      float * lam, float * dthr, int * multi, int * flags, 
                      int * nodhkls, int * idxlam, int * idxdmin, 
                      int * idxnod, float filmr, float gnomr,
                      float lmin, float lmax, float dmin, float * cell, 
                      float * phis, int * latt, float ctof)
 
 
Parameters:
 
int       vh;              User selected view-object handle (R)
int       nspot;           Number of spots predicted (R)
int       hkl[];           Array of 'nspot' 'hkl' packed indices (as LRL)
                           2**20(h+512)+2**10*(k+512)+l+512 (R)
float     xf[];            Array of 'nspot' 'xf' coordinates in mm from
                           the pattern centre (R) 
float     yf[];            Array of 'nspot' 'yf' coordinates in mm from
                           the pattern centre (R) 
float     lam[];           Array of 'nspot' lambda values (R)
float     dthr[];          Array of 'nspot' (1/dmin)**2 threshold values 
                           (R)
int       multi[];         Array of 'nspot' multiplicities flags as for
                           'LRL' data (see main routine) (R)
int       flags[];         Array of 'nspot' reflection flags
                           Flags format as for LRL' data
                           Bit 0 set = spatial overlap; this is the only
                                       bit used by this routine.
                           (R)
int       nodhkls[];       Array of 'nspot' packed nodal indices; packed
                           as 2**20(h+512)+2**10(k+512)+l+512 (R)
int       idxlam[];        Index array for data sorted by lambda, 'nspot'
                           values from 1 to nspot (R)
int       idxdmin[];       Index array for data sorted by dmin 'nspot'
                           values from 1 to nspot (R)
int       idxnod[];        Index array for data sorted by packed nodal
                           index from 1 to nspot (R)
float     filmr;           Pattern radius in mm (R)
float     gnomr;           Minimum radius in mm (>0.1) from image 
                           centre for conversion of plot to a gnomonic 
                           projection. For a normal Laue simulation, 
                           give a value of 0.0 (R) 
float     lmin;            Lambda minimum of prediction (R)
float     lmax;            Lambda maximum of prediction (R)
float     dmin;            Dmin value of prediction (R)
float     cell[6];         Real cell dimensions a, c, c, alpha, beta, 
                           gamma (R)
float     phis[4];         Setting angles phix, phiy, phiz, spindle (R)
int       latt[4];         Crystal system, lattice, rotation axis,
                           beam axis (R)
float     ctof;            Crystal to film distance (mm) 

 
 
Return:  Status flag =0 OK, >0 error
         bit 0 set: View-object handle not found
         bit 1 set: View handle does not match view object
         bit 2 set: Unable to allocate required memory
 
 

2.16 THE ROTATION IMAGE SIMULATION VIEW-OBJECT ROUTINES
=======================================================


2.16.1 INTRODUCTION
 
The  rotation  pattern  simulation  view-object  is  used  to  display  the
simulation of a single crystal  monochromatic  X-ray  rotation  diffraction
pattern (the pattern prediction itself  must  be  done  externally  to  the
routine and the reflections stored in a list using  the  appropriate  'rpf'
functions). The view-object allows either for colour coded  simulations  or
for interactive black and white simulations where various parameters may be
modified via a slider to show the effects that they have on  the  patterns.
The indices of selected spots may be displayed. Labels may be drawn on  the
interactive black and white simulations. The view-object  also  provides  a
hard copy (Postscript file) option.
 
The following sets of routines are available:
 
   Creating and Handling a Rotation Simulation View-Object
 
2.16.2 CREATING AND HANDLING A ROTATION SIMULATION VIEW-OBJECT
 
2.16.2.1 Introduction
 
The following routines are available:
 
   Create a rotation simulation view-object - xdl_rot_sim
   Calculate size requirements - xdl_rot_sim_getsize
   Display a new simulation - xdl_rot_sim_new
 
2.16.2.2 Create a rotation simulation view-object - xdl_rot_sim
 
The routine xdl_rot_sim (xdlf_rot_sim) is used to  create  a  new  rotation
image simulation display view-object. The simulation itself  is  calculated
externally to the routine.
 
Fortran call:
 
         CALL XDLF_ROT_SIM  (IVH, IVHPARENT, IX, IY, ICSET, ITYPE, ISIZE,
        +                    IORD, MINDX, ICRYS, IMGNUM, FILMR, SCAX,
        +                    ROTS, ROTE, ISYN, ETA, DIVV, DIVH, DELAMB,
        +                    DELCOR, IAX_V, IAX_H, NWMAX, CUR_ROTR,
        +                    CUR_ETA, CUR_DIVV, CUR_DIVH, CUR_DELAMB,
        +                    CELL, UMAT, DELPHI, WAVE, LSYS, CTOD,
        +                    NAME1, LEN1, NAME2, LEN2, MINW, MINH, IERR)
 
 
Parameters:
 
IVH       (R)   View-object handle (see vh)
IVHPARENT (R)   View-object handle for parent 0=none 
                (see vh_parent)
IX        (R)   X position (may be -1 if no parent) (see x)
IY        (R)   Y position (may be -1 if no parent) (see y)
ICSET     (R)   Colorset number (see cset)
ITYPE     (R)   Simulation type =1 Colour, = 2 Monochrome with
                soft limits options etc. (see type)
ISIZE     (R)   Half width/height for displayed pattern in 
                pixels (see size)
IORD      (R)   Order of local detector axes flag. First axis
                along X windows 'x' direction on screen (to
                right), second axis along X-windows 'y' direction 
                (down).
                1  +ax1 +ax2
                2  +ax1 -ax2
                3  -ax1 +ax2
                4  -ax1 -ax2
                5  +ax2 +ax1
                6  +ax2 -ax1
                7  -ax2 +ax1
                8  -ax2 -ax1
MINDX     (R)   Index to spot list (as returned from 
                rpff_reflist_init call)
ICRYS     (R)   Crystal number
IMGNUM    (R)   Image number
FILMR     (R)   Pattern radius in mm (see filmr)
SCAX(3)   (R)   Rotation (scan) axis vector as used in the 
                prediction 
ROTS      (R)   Rotation start for current image (degrees) as used
                in the prediction
ROTE      (R)   Rotation end for current image (>ROTS) (degrees) 
                as used in the prediction
ISYN      (R)   Flag =1 synchrotron, =0 lab source as used in the
                prediction
ETA       (R)   Mosaicity (halfwidth, radians) as used in the 
                prediction
DIVV      (R)   Verical divergence (half width, radians) as used
                in the prediction
DIVH      (R)   Horizontal divergence (half width, radians) as
                used in the prediction
DELAMB    (R)   Delta-lambda/lambda as used in the prediction    
DELCOR    (R)   Correlated dispersion (half width, radians as used in
                the prediction
IAX_V     (R)   No. of vertical axis (lab frame) 1=X, 2=Y, 3=Z
                as used in the prediction
IAX_H     (R)   No. of horizontal axis (lab frame) 1=X, 2=Y, 3=Z
                as used in the prediction
NWMAX     (R)   Maximum no. of images to treat as a non too-wide
                partial as used in the prediction
CUR_ROTR  (R)   Current rotation range for type 2 plots (must
                be <= predicted range)
CUR_ETA   (R)   Current 'eta' value for type 2 plots (must
                be <= value used in the prediction)
CUR_DIVV  (R)   Current 'divv' value for type 2 plots (must
                be <= value used in the prediction)
CUR_DIVH  (R)   Current 'divh' value for type 2 plots (must
                be <= value used in the prediction)
CUR_DELAMB(R)   Current 'delamb' value for type 2 plots (must
                be <= value used in the prediction)
CELL(6)   (R)   Real cell parameters in Angstroms and degrees
                for annotation of type 2 Postscript plots
UMAT(3,3) (R)   'U' matrix for annotation of type 2 Postscript 
                plots
DELPHI(3) (R)   Missetting angles in degrees for annotation of 
                type 2 Postscript plots
WAVE      (R)   Wavelength in Angstroms for annotation of type 2 
                Postscript plots
LSYS(2)   (R)   Crystal system 1-7, Lattice type 1-7
CTOD      (R)   Crystal to detector distance (mm)
MINW      (R)   Minimum width for view-object or 0 
                (see min_width)
MINH      (R)   Minimum height for view-object or 0 
                (see min_height)
NAME1     (R)   Character string containing the name of the 1'st
                decector axis (max 4 characters in length)
                ** Pass address using the XDLSTR function **
LEN1      (R)   Length of the name string - must be >0 
                (cf len1) (max 4 chars) 
NAME2     (R)   Character string containing the name of the 2'nd
                detector axis (max 4 characters in length)
                ** Pass address using the XDLSTR function **
LEN2      (R)   Length of the name string - must be >0 
                (cf len1) (max 4 chars) 
IERR      (W)   Returns status from xdl_rot_sim call
 
 
'C' call:
 
int xdl_rot_sim (int vh, int vh_parent, int x, int y, int cset, int type, 
                 int size, int iord, int mindx, int icrys, int imgnum, 
		 float filmr, float * scax, float rots, float rote, 
                 int isyn, float eta, float divv, float divh, float delamb, 
                 float delcor, int iax_v, int iax_h, int nwmax, 
                 float cur_rotr, float cur_eta, float cur_divv, 
                 float cur_divh, float cur_delamb, 
                 float * cell, float * umat, float * delphi, 
                 float wave, int * lsys, float ctod,
                 char * name1, int len1, char * name2, int len2, 
                 int min_width, int min_height)
 
 
Parameters:
 
int       vh;              User selected view-object handle (R)
int       vh_parent;       View-object handle for the parent base frame, 
                           if 0 then a base  level frame is created to
                           enclose the view-object (R)
int       x;               x coordinate for the view-object.
                           If no parent may be -1 to give default x (R)
int       y;               y coordinate for the view-object.
                           If no parent may be -1 to give default y (R)
int       cset;            Number of the colorset to be used; must
                           have 53 or more colorcells allocated (R) 
int       type;            Simulation type =1 Colour, =2 Monochrome with
                           soft limit sliders etc.
int       size;            Pattern display area half width/height in
                           pixels (R)
int       iord;            Order of local detector axes flag. First axis
                           along X windows 'x' direction on screen (to
                           right), second axis along X-windows 'y' 
                           direction (down).
                             1  +ax1 +ax2
                             2  +ax1 -ax2
                             3  -ax1 +ax2
                             4  -ax1 -ax2
                             5  +ax2 +ax1
                             6  +ax2 -ax1
                             7  -ax2 +ax1
                             8  -ax2 -ax1
                             (R)
 int       mindx;          Reflection list index as returned from
                           prl_init (R)
int       icrys;           Crystal number (R)
int       imgnum;          Image number (R)
float     filmr;           Pattern radius in mm (R)
float     scax[3];         Rotation (scan) axis vector as used in the
                           prediction (R)
float     rots;            Rotation start for current image (degrees) as
                           used in the prediction (R)
float     rote;            Rotation end for current image (>ROTS) 
                           (degrees) as usedin the prediction (R)
int       isyn;            Flag =1 synchrotron, =0 lab source as used
                           in the prediction (R)
float     eta;             Mosaicity (half width, radians) as used in the 
                           prediction (R)
float     divv;            Verical divergence (half width) (radians) as
                           used in the prediction (R)
float     divh;            Horizontal divergence (half width) (radians)
                           as used in the prediction (R)
float     delamb;          Delta-lambda/lambda as used in the
                           prediction (R)    
float     delcor;          Correlated dispersion (half width) as used
                           in the prediction (R)
int       iax_v;           No. of vertical axis (lab frame) 
                           1=X, 2=Y, 3=Z as used in the prediction (R)
int       iax_h;           No. of horizontal axis (lab frame) 
                           1=X, 2=Y, 3=Z  as used in the prediction (R)
int       nwmax;           Maximum no. of images to treat as a non 
                           too-wide partial as used in the 
                           prediction (R) 
float     cur_rotr;        Current rotation range for type 2 plots (must
                           be <= predicted range) (R)
float     cur_eta;         Current 'eta' value for type 2 plots (must
                           be <= value used in the prediction) (R)
float     cur_divv;        Current 'divv' value for type 2 plots (must
                           be <= value used in the prediction) (R)
float     cur_divh;        Current 'divh' value for type 2 plots (must
                           be <= value used in the prediction) (R)
float     cur_delamb;      Current 'delamb' value for type 2 plots (must
                           be <= value used in the prediction) (R)
float     cell[6];         Real cell parameters in Angstroms and degrees
                           for annotation of type 2 Postscript plots 
                           (R)
float     umat[9];         'U' matrix for annotation of type 2 Postscript 
                           plots (R)
float     delphi[3];       Missetting angles in degrees for annotation of 
                           type 2 Postscript plots (R)
float     wave;            Wavelength in Angstroms for annotation of 
                           type 2 Postscript plots (R)
int       lsys[2];         Crystal system 1-7, lattice type 1-7 for
                           annotation of type 2 Postscript plots (R)
float     ctod;            Crystal to detector distance in mm for
                           annotation of type 2 Postscript plots (R)
char      *name1;          Name of 1'st detector axis (max 4 chars long) 
                           (R)
int       len1;            Length of name (may give 0 if a null terminated 
                           string is passed) (R)
char      *name2;          Name of 2'nd detector axis (max 4 chars long)
                           (R)
int       len2;            Length of name (may give 0 if a null terminated 
                           string is passed) (R)
int       min_width;       The program will calculate the width required
                           for the view-object based on the display area
                           width, control panel width etc. If this is
                           less than min_width then min_width will be
                           used instead and the layout altered to reflect
                           this (R)
int       min_height;      minimum height cf min_width (R)


 
 
Return:  Status flag =0 OK, >0 error
         bit 0 set: Requested parent not found in the view-objects list
         bit 1 set: Unable to allocate memory for x, y pixel positions
                    arrays.
 
 
2.16.2.3 Calculate size requirements - xdl_rot_sim_getsize
 
The routine xdl_rot_sim_getsize (xdlf_rot_sim_getsize) is used to  get  the
required size for a rotation pattern simulation display view-object.
 
Fortran call:
 
         CALL XDLF_ROT_SIM_GETSIZE (ITYPE, ISIZE, IWIDTH, IHEIGHT)
 
 
Parameters:
 
ITYPE     (R)   Simulation type =1 Colour, = 2 Monochrome with
                soft limits options etc. (see type)
ISIZE     (R)   Half width/height for displayed pattern in 
                pixels (see size)
IWIDTH    (W)   Returns the width required (see w)
IHEIGHT   (W)   Returns the height required (see h)
 
 
'C' call:
 
void xdl_rot_sim_getsize (type, size, w, h)
 
 
Parameters:
 
int       type;           /* Simulation type =1 Colour, =2 Monochrome with
                             soft limit sliders etc.*/
int       size;           /* Pattern display area half width/height in
                             pixels (R)*/
int *w;                   /* Returns the width required (W)*/
int *h;                   /* Returns the height required (W)*/

 
 
Return:  None
 
 
2.16.2.4 Display a new simulation - xdl_rot_sim_new
 
The routine xdl_rot_sim_new (xdlf_rot_sim_new) is used  to  display  a  new
rotation pattern simulation  in  a  rotation  simulation  view-object.  The
current simulation type (colour/interactive)  and  the  currently  selected
options for the view-object are unchanged (apart from  the  orientation  if
desired). Any labels will be removed.
 
Fortran call:
 
         CALL XDLF_ROT_SIM_NEW (IVH, IORD, NAME1, LEN1, NAME2, LEN2,
        +                       MINDX, ICRYS, IMGNUM, 
        +                       FILMR, SCAX, ROTS, ROTE, ISYN, ETA, 
        +                       DIVV, DIVH, DELAMB, DELCOR, 
        +                       IAX_V, IAX_H, NWMAX, CELL, UMAT, 
        +                       DELPHI, WAVE, LSYS, CTOD, IERR)
 
 
Parameters:
 
IVH       (R)   View-object handle (see vh)
IORD      (R)   Order of local detector axes flag 1-8 (0 if no change in
                which case axis names will also be left unchanged)
NAME1     (R)   Character string containing the name of the 1'st
                decector axis (max 4 characters in length)
                ** Pass address using the XDLSTR function **
LEN1      (R)   Length of the name string - must be >0 
                (cf len1) (max 4 chars) 
NAME2     (R)   Character string containing the name of the 2'nd
                detector axis (max 4 characters in length)
                ** Pass address using the XDLSTR function **
LEN2      (R)   Length of the name string - must be >0 
                (cf len1) (max 4 chars) 
MINDX     (R)   Index to spot list (as returned from 
                rpff_reflist_init call)
ICRYS     (R)   Crystal number
IMGNUM    (R)   Image number
FILMR     (R)   Pattern radius in mm (see filmr)
SCAX(3)   (R)   Rotation (scan) axis vector as used in the 
                prediction 
ROTS      (R)   Rotation start for current image (degrees) as used
                in the prediction
ROTE      (R)   Rotation end for current image (>ROTS) (degrees) 
                as used in the prediction
ISYN      (R)   Flag =1 synchrotron, =0 lab source as used in the
                prediction
ETA       (R)   Mosaicity (radians) as used in the prediction
DIVV      (R)   Verical divergence (half width) (radians) as used
                in the prediction
DIVH      (R)   Horizontal divergence (half width) (radians) as
                used in the prediction
DELAMB    (R)   Delta-lambda/lambda as used in the prediction    
DELCOR    (R)   Correlated dispersion (half width) as used in
                the prediction
IAX_V     (R)   No. of vertical axis (lab frame) 1=X, 2=Y, 3=Z
                as used in the prediction
IAX_H     (R)   No. of horizontal axis (lab frame) 1=X, 2=Y, 3=Z
                as used in the prediction
NWMAX     (R)   Maximum no. of images to treat as a non too-wide
                partial as used in the prediction
CELL(6)   (R)   Real cell parameters in Angstroms and degrees
                for annotation of type 2 Postscript plots
UMAT(3,3) (R)   'U' matrix for annotation of type 2 Postscript 
                plots
DELPHI(3) (R)   Missetting angles in degrees for annotation of 
                type 2 Postscript plots
WAVE      (R)   Wavelength in Angstroms for annotation of type 2 
                Postscript plots
LSYS(2)   (R)   Crystal system 1-7, Lattice type 1-7
CTOD      (R)   Crystal to detector distance (mm)
IERR      (W)   Returns status from xdl_rot_sim_new call
 
 
'C' call:
 
int xdl_rot_sim_new (int vh, int iord, char * name1, int len1, 
                     char * name2, int len2, int mindx, int icrys, 
                     int imgnum, float filmr, float * scax, 
                     float rots, float rote, int isyn, float eta, 
                     float divv, float divh, float delamb, float delcor, 
                     int iax_v, int iax_h, int nwmax, float * cell, 
                     float * umat, float *delphi, float wave, int * lsys, 
                     float ctod) 
 
 
Parameters:
 
int       vh;              User selected view-object handle (R)
int       iord;            Order of local detector axes flag 1-8 (if
                           0 then axis order and axis names will
                           remain unchanged) (R)
char      *name1;          Name of 1'st detector axis (max 4 chars long) 
                           (R)
int       len1;            Length of name (may give 0 if a null terminated 
                           string is passed) (R)
char      *name2;          Name of 2'nd detector axis (max 4 chars long)
                           (R)
int       len2;            Length of name (may give 0 if a null terminated 
                           string is passed) (R)
int       mindx;           Reflection list index as returned from
                           prl_init (R)
int       icrys;           Crystal number (R)
int       imgnum;          Image number (R)
float     filmr;           Pattern radius in mm (R)
float     scax[3];         Rotation (scan) axis vector as used in the
                           prediction (R)
float     rots;            Rotation start for current image (degrees) as
                           used in the prediction (R)
float     rote;            Rotation end for current image (>ROTS) 
                           (degrees) as usedin the prediction (R)
int       isyn;            Flag =1 synchrotron, =0 lab source as used
                           in the prediction (R)
float     eta;             Mosaicity (radians) as used in the 
                           prediction (R)
float     divv;            Verical divergence (half width) (radians) as
                           used in the prediction (R)
float     divh;            Horizontal divergence (half width) (radians)
                           as used in the prediction (R)
float     delamb;          Delta-lambda/lambda as used in the
                           prediction (R)    
float     delcor;          Correlated dispersion (half width) as used
                           in the prediction (R)
int       iax_v;           No. of vertical axis (lab frame) 
                           1=X, 2=Y, 3=Z as used in the prediction (R)
int       iax_h;           No. of horizontal axis (lab frame) 
                           1=X, 2=Y, 3=Z  as used in the prediction (R)
int       nwmax;           Maximum no. of images to treat as a non 
                           too-wide partial as used in the 
                           prediction (R) 
float     cell[6];         Real cell parameters in Angstroms and degrees
                           for annotation of type 2 Postscript plots 
                           (R)
float     umat[9];         'U' matrix for annotation of type 2 Postscript 
                           plots (R)
float     delphi[3];       Missetting angles in degrees for annotation of 
                           type 2 Postscript plots (R)
float     wave;            Wavelength in Angstroms for annotation of 
                           type 2 Postscript plots (R)
int       lsys[2];         Crystal system 1-7, lattice type 1-7 for
                           annotation of type 2 Postscript plots (R)
float     ctod;            Crystal to detector distance in mm for
                           annotation of type 2 Postscript plots (R)

 
 
Return:  Status flag =0 OK, >0 error
         bit 0 set: View-object handle not found
         bit 1 set: View handle does not match view object
         bit 2 set: Unable to allocate required memory
 
 

2.17 THE SHOW UNIQUE DATA VIEW-OBJECT ROUTINES
==============================================


2.17.1 INTRODUCTION
 
The show unique view-object is used to give a pictorial  representation  of
sections of the reciprocal lattice showing the unique data and which  parts
of that data have been measured (or  potentially  measured)  for  simulated
data,
 
The following sets of routines are available:
 
   Creating and Handling a Show Unique Data View-Object
 
2.17.2 CREATING AND HANDLING A SHOW UNIQUE DATA VIEW-OBJECT
 
2.17.2.1 Introduction
 
The following routines are available:
 
   Create a show unique view-object - xdl_show_unq
   Return selected spot position - xdl_show_unq_getdata
 
2.17.2.2 Create a show unique view-object - xdl_show_unq
 
This routine is used to create a view-object for showing  the  coverage  of
the reciprocal space unique data.
 
Fortran call:
 
         CALL XDLF_SHOW_UNQ (IVH, IVHPARENT, IX, IY, ICSET, IRAD,
        +                    MINDX_UNQ, DSTMAX, BMATR, 
        +                    XDLSTR(TITLE), LENT, MINW, MINH, IERR)
 
 
Parameters:
 
IVH        (R)   View-object handle (see vh)
IVHPARENT  (R)   View-object handle for parent 0=none 
                 (see vh_parent)
IX         (R)   X position (may be -1 if no parent) (see x)
IY         (R)   Y position (may be -1 if no parent) (see y)
ICSET      (R)   Colorset number (see cset)
ISIZE      (R)   Half width/height for displayed pattern in 
                 pixels (see size)
MINDX_UNQ  (R)   Index to unique data list (unq.c functions)
                 (preferably sorted on 'l' to give much better
                 performance)
DSTMAX     (R)   Maximum value of d*
BMATR(3,3) (R)   Orthogonalising 'B' matrix (Fortran order
                 BMATR(1,1) BMATR(2,1) BMATR(3,1) BMATR(1,2)...)
TITLE      (R)   Title string (max 120 characters)
                 ** Pass address using the XDLSTR function **
LENT       (R)   Length of title string
MINW       (R)   Minimum width for view-object or 0 
                 (see min_width)
MINH       (R)   Minimum height for view-object or 0 
                 (see min_height)
IERR       (W)   Returns status from xdl_show_unq call
 
 
'C' call:
 
int xdl_show_unq (int vh, int vh_parent, int x, int y, int cset, int size, 
                  int mindx_unq, float dstmax, float bmatr[3][3], 
                  char * title, int lent, int min_width, int min_height)
 
 
Parameters:
 
int       vh;             User selected view-object handle (R)
int       vh_parent;      View-object handle for the parent base frame, 
                          if 0 then a base  level frame is created to
                          enclose the view-object (R)
int       x;              x coordinate for the view-object.
                          If no parent may be -1 to give default x (R)
int       y;              y coordinate for the view-object.
                          If no parent may be -1 to give default y (R)
int       cset;           Number of the colorset to be used; needs
                          at least 8 colorcells allocated  (R) 
int       size;           Pattern display area half width/height in
                          pixels (R)
int       mindx_unq;      Index to unique data list (see unq.c functions) 
                          preferably sorted on 'l' as this will give
                          much better performance (R)
float     dstmax;         Maximum d* value (R)
float     bmatr[3][3];    'B' matrix (C order) (R) 
char      *title;         Title string (max of 120 characters) (R)
int       lent;           Length of title string (may give 0 if a null 
                          terminated string is passed) (R)
int       min_width;      The program will calculate the width required
                          for the view-object based on the display area
                          width, control panel width etc. If this is
                          less than min_width then min_width will be
                          used instead and the layout altered to reflect
                          this (R)
int       min_height;     minimum height cf min_width (R)
 
 
Return:  Status flag =0 OK, >0 error
         bit 0 set: Requested parent not found in the view-objects list
         ...
 
 
2.17.2.3 Return selected spot position - xdl_show_unq_getdata
 
This routine returns  the  position  of  the  last  mouse  selected  (spot)
position from a show unique data view-object.
 
Fortran call:
 
         CALL XDLF_SHOW_UNQ_GETDATA (IVH, X, Y, IERR)
 
 
Parameters:
 
IVH      (R)  View-object handle (see vh)
X        (R)  'X' coordinate
Y        (W)  'Y' coordinate
IERR     (W)  Returns status from xdl_show_unq_gedata call
 
 
'C' call:
 
int xdl_show_unq_getdata (int vh, float * x, float * y)
 
 
Parameters:
 
int vh;          View-object handle (R)
float *x;        Returned 'x' coordinate (W)
float *y;        Returned 'y' coordinate (W)
 
 
Return:  Status = 0 OK, >0 error
                  bit 0 set:  View-object handle not found
                  bit 1 set:  View handle does not match view object
                  ...
 
 
 
CHAPTER 3: IMAGE FILE HANDLING AND BACKGROUND ROUTINES
======================================================
 

3.1 IMAGE FILE READING ROUTINES
===============================


3.1.1 INTRODUCTION
 
These are a set of routines for reading film image  and  image  plate  (i2)
files (without header information) or MAR image plate files.  The  routines
are written in C. Fortran interfaces are provided. They  were  written,  in
particular, for use with programs using XDL_VIEW routines.
 
The following sets of routines are available:
 
   Film Image File Routines
   Image-Plate Image File Routines
   MAR Image-Plate File Routines
   Axis Order Decoding Routines
 
3.1.2 FILM IMAGE FILE ROUTINES
 
3.1.2.1 Introduction
 
These are routines for reading a film  image  binary  file  without  header
information and with one unsigned byte per pixel.
 
 
The following routines are available:
 
   Open a film image file - xdl_open_film_file
   Read a full film image file - xdl_read_full_film
   Close a film image file - xdl_close_film_file
 
3.1.2.2 Open a film image file - xdl_open_film_file
 
The routine xdl_open_film_file (xdlf_open_film_file) is used to open a film
image file and return the file descriptor.
 
Fortran call:
 
         CALL XDLF_OPEN_FILM_FILE (XDLSTR(FILNAM), LENF, IFD, IERR)
 
 
Parameters:
 
FILNAM      (R)   Character string holding the filename 
                  (see filename)
                  ** Pass address using the XDLSTR routine **
LENF        (R)   Length of the filename string (see lenf)
IFD         (W)   Returns the file descriptor (see fd)
IERR        (W)   Returns the status from the xdl_open_film_file 
                  call
 
 
'C' call:
 
int xdl_open_film_file (filename, lenf, fd)
 
 
Parameters:
 
char  * filename;       /* The name of the film image file (R)*/
int     lenf;           /* Length of the file name. If the filename is a
                           null terminated string then the length will be
                           determined by the routine if lenf is 0 (R)*/
int   * fd;             /* Returns the file descriptor (W)*/

 
 
Return:  =0 OK; =1 Unable to open the file;
 
 
3.1.2.3 Read a full film image file - xdl_read_full_film
 
The routine xdl_read_full_film (xdlf_read_full_film)  is  used  to  read  a
complete film image file and return the image data in an  array.  The  film
file may have its data in any of the eight possible orders (the default  is
assumed to have yf moving fastest and xf slowest) and is in  unsigned  byte
format without any header. The number of x rasters  and  the  number  of  y
rasters must be supplied.
 
Fortran call:
 
         CALL XDLF_READ_FULL_FILM (IFD, IORD, NXRASTS, NYRASTS,
        +                         IVH_BAR, IXROOT, IYROOT, IMG_FULL,
        +                         IERR)
 
 
Parameters:
 
IFD      (R)   The file descriptor (see fd)
IORD     (R)   Order of the data in the film image file (1 to 8)
               (see order)
NXRASTS  (R)   The number of x rasters (see nxrasts)
NYRASTS  (R)   The number of y rasters (see nyrasts)
IVH_BAR  (R)   View-object handle for displaying a read progress
               bar >0 on 0 if none required (see vh_bar)
IXROOT   (R)   x root position for progress bar display if
               required (see xroot)
IYROOT   (R)   y root position for progress bar display if 
               required (see yroot)
IMG_FULL (W)   Array to hold the read data (pass as an
               integer array sufficiently large to hold the
               returned image data) (see img_full)
IERR     (W)   Returns the status from the xdl_read_full_film call
 
 
'C' call:
 
int xdl_read_full_film (fd, order,nxrasts, nyrasts, vh_bar, 
                        xroot, yroot, img_full)
 
 
Parameters:
 
int fd;           /* The file descriptor of the opened film format 
                     file (R)*/
int order;        /* Order of the data in the input film image file
                     in terms of the xf, yf coordinate system as
                     a number from 1 to 8.
                     1   +xf slow   +yf fast
                     2   +xf slow   -yf fast
                     3   -xf slow   +yf fast
                     4   -xf slow   -yf fast
                     5   +yf slow   +xf fast
                     6   +yf slow   -xf fast
                     7   -yf slow   +xf fast
                     8   -yf slow   -xf fast
                     (R)*/
int nxrasts;      /* The number of x rasters (R)*/
int nyrasts;      /* The number of y rasters (R)*/
int vh_bar;       /* View-object handle (>0) for display bar showing the
                     progress of the read, 0 if none required (R) */
int xroot;        /* The root x position for the top left of the display
                     bar area if required (R)*/
int yroot;        /* The root y position for the top left of the display
                     bar area if required (R)*/
unsigned char img_full[];
                  /* Array returning the read image data; 
                     The slower moving index in
                     the returned data is x going from low x to
                     high x and the faster moving index is y going 
                     from low y to high y. (W)*/
 
 
Return:  =0 OK; >0 Record number where a read error occurred; -1 unable
         to allocate temporary buffer space.
 
 
3.1.2.4 Close a film image file - xdl_close_film_file
 
The routine xdl_close_film_file (xdlf_close_film_file) is used to  close  a
film image file.
 
Fortran call:
 
         CALL XDLF_CLOSE_FILM_FILE (IFD, IERR)
 
 
Parameters:
 
IFD         (R)   The file descriptor (see fd)
IERR        (W)   Returns the status from the xdl_close_film_file 
                  call
 
 
'C' call:
 
int xdl_close_film_file (fd)
 
 
Parameters:
 
int   fd;             /* The file descriptor (R)*/

 
 
Return:  =0 OK; =1 Unable to close the file;
 
 
3.1.3 IMAGE-PLATE IMAGE FILE ROUTINES
 
3.1.3.1 Introduction
 
These are routines for reading a  image-plate  image  binary  file  without
header information and with one unsigned two-byte integer per pixel.
 
 
The following routines are available:
 
   Open an image plate (i2) file - xdl_open_i2
   Read a full image-plate image file - xdl_read_full_i2
   Close an image plate (i2) file - xdl_close_i2
 
3.1.3.2 Open an image plate (i2) file - xdl_open_i2
 
The routine xdl_open_i2 (xdlf_open_i2) is used to open an 'i2' unsigned  16
bit integer format image file and return the file  descriptor.  It  can  in
fact be used with any format (image) file.
 
Fortran call:
 
         CALL XDLF_OPEN_I2 (XDLSTR(FILNAM), LENF, IFD, IERR)
 
 
Parameters:
 
FILNAM      (R)   Character string holding the filename 
                  (see filename)
                  ** Pass address using the XDLSTR routine **
LENF        (R)   Length of the filename string (see lenf)
IFD         (W)   Returns the file descriptor (see fd)
IERR        (W)   Returns the status from the xdl_open_i2 call
 
 
'C' call:
 
int xdl_open_i2 (filename, lenf, fd)
 
 
Parameters:
 
char  * filename;       /* The name of the 'i2' format image file (R)*/
int     lenf;           /* Length of the file name. If the filename is a
                           null terminated string then the length will be
                           determined by the routine if lenf is 0 (R)*/

int   * fd;             /* Returns the file descriptor (W)*/

 
 
Return:  =0 OK; =1 Unable to open the file,
         =2 error in reading the file header
 
 
3.1.3.3 Read a full image-plate image file - xdl_read_full_i2
 
The routine xdl_read_full_i2 (xdlf_read_full_i2) is used to read a complete
image-plate image  file  and  return  the  image  data  in  an  array.  The
image-plate file may have its data in any of the eight possible orders  and
may be byte swapped if necessary (the default is assumed to have yf  moving
fastest and xf slowest) and is in unsigned two byte integer format  without
any header. The number of x rasters and the number of  y  rasters  must  be
supplied.
 
Fortran call:
 
         CALL XDLF_READ_FULL_I2 (IFD, IORD, NXRASTS, NYRASTS,
        +                         IVH_BAR, IXROOT, IYROOT, IMG_FULL,
        +                         MINVAL, MAXVAL, IERR)
 
 
Parameters:
 
IFD      (R)   The file descriptor (see fd)
IORD     (R)   Order of the data in the film image file (1 to 8)
               (-IORD can be given to swap bytes in the data as
               well as re-order it ) (see order)
NXRASTS  (R)   The number of x rasters (see nxrasts)
NYRASTS  (R)   The number of y rasters (see nyrasts)
IVH_BAR  (R)   View-object handle for displaying a read progress
               bar >0 on 0 if none required (see vh_bar)
IXROOT   (R)   x root position for progress bar display if
               required (see xroot)
IYROOT   (R)   y root position for progress bar display if 
               required (see yroot)
IMG_FULL (W)   Array to hold the read data (pass as an
               integer array sufficiently large to hold the
               returned image data) (see img_full)
MINVAL   (W)   The minimum pixel value in the image (see minval)
MAXVAL   (W)   The maximum pixel value in the image (see maxval)
IERR     (W)   Returns the status from the xdl_read_full_film call
 
 
'C' call:
 
int xdl_read_full_i2 (fd, order, nxrasts, nyrasts, vh_bar, xroot, yroot, 
                      img_full, minval, maxval)
 
 
Parameters:
 
int fd;           /* The file descriptor of the opened film format 
                     file (R)*/
int order;        /* Order of the data in the input film image file
                     in terms of the xf, yf coordinate system as
                     a number from 1 to 8. (-order can be given to
                     byte swap the data as well as change the order)
                     1   +xf slow   +yf fast
                     2   +xf slow   -yf fast
                     3   -xf slow   +yf fast
                     4   -xf slow   -yf fast
                     5   +yf slow   +xf fast
                     6   +yf slow   -xf fast
                     7   -yf slow   +xf fast
                     8   -yf slow   -xf fast
                     (R)*/
int nxrasts;      /* The number of x rasters (R)*/
int nyrasts;      /* The number of y rasters (R)*/
int vh_bar;       /* View-object handle (>0) for display bar showing the
                     progress of the read, 0 if none required (R) */
int xroot;        /* The root x position for the top left of the display
                     bar area if required (R)*/
int yroot;        /* The root y position for the top left of the display
                     bar area if required (R)*/
unsigned short img_full[];
                  /* Array returning the read image data; 
                     The slower moving index in
                     the returned data is x going from low x to
                     high x and the faster moving index is y going 
                     from low y to high y i.e. the same order as in the
                     file. (W)*/
int *minval;      /* Returns the minimum pixel value in the image (W)*/
int *maxval;      /* Returns the maximum pixel value in the image (W)*/
 
 
Return:  =0 OK; >0 Record number where a read error occurred.
 
 
3.1.3.4 Close an image plate (i2) file - xdl_close_i2
 
The routine xdl_close_i2 (xdlf_close_i2) is used to close  an  image  plate
'i2' format file. It can in fact be used with any format (image) file.
 
Fortran call:
 
         CALL XDLF_CLOSE_I2 (IFD, IERR)
 
 
Parameters:
 
IFD         (R)   The file descriptor (see fd)
IERR        (W)   Returns the status from the xdl_close_i2 call
 
 
'C' call:
 
int xdl_close_i2 (fd)
 
 
Parameters:
 
int   fd;             /* The file descriptor (R)*/

 
 
Return:  =0 OK; =1 Unable to close the file;
 
 
3.1.4 MAR IMAGE-PLATE FILE ROUTINES
 
3.1.4.1 Introduction
 
These are  routines  for  reading  a  MAR  image-plate  system  image  file
including the header information and overflow data.
 
 
The following routines are available:
 
   Read a MAR image plate file - xdl_read_mar
   Read and squash a MAR image plate file - xdl_rdsquash_mar
   Read a Photon Factory Log Byte File - xdl_read_pfbyte
 
3.1.4.2 Read a MAR image plate file - xdl_read_mar
 
The routine xdl_read_mar (xdlf_read_mar) is used to  read  a  complete  MAR
image-plate image file and return the image data in an array. Overload data
are include. The returned image contains signed integer*4  data.  The  data
will be byte swapped on input if required.
 
Fortran call:
 
         CALL XDLF_READ_MAR (IFD, IVH_BAR, IXROOT, IYROOT, 
        +                    IMG_FULL, NXPIX, NYPIX, NS_RAS, NF_RAS, 
        +                    MINVAL, MAXVAL, IERR)
 
 
Parameters:
 
IFD      (R)   The file descriptor (see fd)
IVH_BAR  (R)   View-object handle for displaying a read progress
               bar >0 on 0 if none required (see vh_bar)
IXROOT   (R)   x root position for progress bar display if
               required (see xroot)
IYROOT   (R)   y root position for progress bar display if 
               required (see yroot)
IMG_FULL (W)   Array to hold the read data (pass as an
               integer array sufficiently large to hold the
               returned image data) (see img_full)
NXPIX    (W)   Returns no. of 'x' pixels
NYPIX    (W)   Returns no. of 'y' pixels
NS_RAS   (W)   Returns no. of slow rasters
NF_RAS   (W)   Returns no. of fast rasters
MINVAL   (W)   The minimum pixel value in the image (see minval)
MAXVAL   (W)   The maximum pixel value in the image (see maxval)
IERR     (W)   Returns the status from the xdl_read_mar call
 
 
'C' call:
 
int xdl_read_mar (fd, vh_bar, xroot, yroot, img_full, 
                  nxpix, nypix, ns_ras, nf_ras, minval, maxval)
 
 
Parameters:
 
int fd;           /* The file descriptor of the opened film format 
                     file (R)*/
int vh_bar;       /* View-object handle (>0) for display bar showing the
                     progress of the read, 0 if none required (R) */
int xroot;        /* The root x position for the top left of the display
                     bar area if required (R)*/
int yroot;        /* The root y position for the top left of the display
                     bar area if required (R)*/
int img_full[];   /* Array returning the read image data (W) */
int *nxpix;       /* Returns the no. of 'x' pixels (W)*/
int *nypix;       /* Returns the no. of 'y' pixels (W)*/
int *ns_ras;      /* Returns the no. of 'slow' rasters */
int *nf_ras;      /* Returns the no. of 'fast' rasters */
int *minval;      /* Returns the minimum pixel value in the image (W)*/
int *maxval;      /* Returns the maximum pixel value in the image (W)*/
 
 
Return:  =0 OK; >0 Record number where a read error occurred.
         -1 error in allocating memory
         -2 error reading header
         -3 error reading overflow data
 
 
3.1.4.3 Read and squash a MAR image plate file - xdl_rdsquash_mar
 
The routine xdl_rdsquash_mar (xdlf_rdsquash_mar) is used to read a complete
MAR image-plate image file and return the image data in an array.  Overload
data are included. The returned image contains each data item  packed  into
two  bytes  with  intensities>32767  being  stored  as  (65536-intensity/8)
(unsigned) values. The data will be byte swapped on input if required.
 
Fortran call:
 
         CALL XDLF_RDSQUASH_MAR (IFD, IVH_BAR, IXROOT, IYROOT, 
        +                    IMG_FULL, NXPIX, NYPIX, NS_RAS, NF_RAS, 
        +                    MINVAL, MAXVAL, IERR)
 
 
Parameters:
 
IFD      (R)   The file descriptor (see fd)
IVH_BAR  (R)   View-object handle for displaying a read progress
               bar >0 on 0 if none required (see vh_bar)
IXROOT   (R)   x root position for progress bar display if
               required (see xroot)
IYROOT   (R)   y root position for progress bar display if 
               required (see yroot)
IMG_FULL (W)   Array to hold the read data (pass as an
               integer array sufficiently large to hold the
               returned image data) (see img_full)
NXPIX    (W)   Returns no. of 'x' pixels
NYPIX    (W)   Returns no. of 'y' pixels
NS_RAS   (W)   Returns no. of slow rasters
NF_RAS   (W)   Returns no. of fast rasters
MINVAL   (W)   The minimum pixel value in the image (see minval)
MAXVAL   (W)   The maximum pixel value in the image (see maxval)
IERR     (W)   Returns the status from the xdl_rdsquash_mar call
 
 
'C' call:
 
int xdl_rdsquash_mar (fd, vh_bar, xroot, yroot, img_full, 
                      nxpix, nypix, ns_ras, nf_ras, minval, maxval)
 
 
Parameters:
 
int fd;           /* The file descriptor of the opened film format 
                     file (R)*/
int vh_bar;       /* View-object handle (>0) for display bar showing the
                     progress of the read, 0 if none required (R) */
int xroot;        /* The root x position for the top left of the display
                     bar area if required (R)*/
int yroot;        /* The root y position for the top left of the display
                     bar area if required (R)*/
unsigned short img_full[];   /* Array returning the read image data as 
                                squashed two-byte data (W) */
int *nxpix;       /* Returns the no. of 'x' pixels (W)*/
int *nypix;       /* Returns the no. of 'y' pixels (W)*/
int *ns_ras;      /* Returns the no. of 'slow' rasters */
int *nf_ras;      /* Returns the no. of 'fast' rasters */
int *minval;      /* Returns the minimum pixel value in the image (W)*/
int *maxval;      /* Returns the maximum pixel value in the image (W)*/
 
 
Return:  =0 OK; >0 Record number where a read error occurred.
         -1 error in allocating memory
         -2 error reading header
         -3 error reading overflow data
 
 
3.1.4.4 Read a Photon Factory Log Byte File - xdl_read_pfbyte
 
The routine xdl_read_pfbyte (xdlf_read_pfbyte) is used to read  a  complete
Photon Fcatory image plate file and return the image data in an array.  The
file may have its data in any of the eight possible orders (the default  is
assumed to have yf moving fastest and xf slowest). Each pixel stores a  log
value for the pixel intensity (unsigned byte). The file has no header.  The
number of x rasters and the number of y rasters must be supplied. The  data
are returned in a packed integer array with
 
Fortran call:
 
         CALL XDLF_READ_PFBYTE (IFD, IORD, NXRASTS, NYRASTS,
        +                       IVH_BAR, IXROOT, IYROOT, IMG_FULL,
        +                       IERR)
 
 
Parameters:
 
IFD      (R)   The file descriptor (see fd)
IORD     (R)   Order of the data in the image file (1 to 8)
               (see order)
NXRASTS  (R)   The number of x rasters (see nxrasts)
NYRASTS  (R)   The number of y rasters (see nyrasts)
IVH_BAR  (R)   View-object handle for displaying a read progress
               bar >0 on 0 if none required (see vh_bar)
IXROOT   (R)   x root position for progress bar display if
               required (see xroot)
IYROOT   (R)   y root position for progress bar display if 
               required (see yroot)
IMG_FULL (W)   Array to hold the read data (pass as an
               integer array sufficiently large to hold the
               returned image data) (see img_full)
IERR     (W)   Returns the status from the xdl_read_pfbyte call
 
 
'C' call:
 
int xdl_read_pfbyte (fd, order, nxrasts, nyrasts, vh_bar, 
                     xroot, yroot, img_full)
 
 
Parameters:
 
int fd;           /* The file descriptor of the opened film format 
                     file (R)*/
int order;        /* Order of the data in the input film image file
                     in terms of the xf, yf coordinate system as
                     a number from 1 to 8.
                     1   +xf slow   +yf fast
                     2   +xf slow   -yf fast
                     3   -xf slow   +yf fast
                     4   -xf slow   -yf fast
                     5   +yf slow   +xf fast
                     6   +yf slow   -xf fast
                     7   -yf slow   +xf fast
                     8   -yf slow   -xf fast
                     (R)*/
int nxrasts;      /* The number of x rasters (R)*/
int nyrasts;      /* The number of y rasters (R)*/
int vh_bar;       /* View-object handle (>0) for display bar showing the
                     progress of the read, 0 if none required (R) */
int xroot;        /* The root x position for the top left of the display
                     bar area if required (R)*/
int yroot;        /* The root y position for the top left of the display
                     bar area if required (R)*/
unsigned short img_full[];
                  /* Array returning the read image data as two byte
                     unsigned quantities; 
                     The slower moving index in
                     the returned data is x going from low x to
                     high x and the faster moving index is y going 
                     from low y to high y. (W)*/
 
 
Return:  =0 OK; >0 Record number where a read error occurred; -1 unable
         to allocate temporary buffer space.
 
 
3.1.5 AXIS ORDER DECODING ROUTINES
 
3.1.5.1 Introduction
 
These are routines for decoding the axis order codes use  to  indicate  the
order of the data in an image file.
 
 
The following routines are available:
 
   Interpret axis order string - xdl_axord
 
3.1.5.2 Interpret axis order string - xdl_axord
 
The routine xdl_axord (xdlf_axord) is used to  interpret  a  user  supplied
string defining the axis order in an input film  or  image-plate  file.  An
option to request or nullify byte swapping (only relevant for  image  plate
data) may also be given. The string defines the axis order in  terms  of  x
and y (the film xf, yf  axes).  The  slower  moving  axis  is  given  first
followed by the faster moving axis. Minus signs are used when the order  of
an axis is reversed. The code 's' if present indicates that  byte  swapping
is to be done and the code 'n' indicates that no byte  swapping  is  to  be
done (byte swapping only relevant for image plate data). Characters,  other
than 'x', 'y', '-', '+', 's' and 'n', or their upper case equivalents,  are
ignored. Some examples follow and the returned flags are  indicated:  .  xy
order = 1, swaptyp = 0 +x+y order = 1, swaptyp = 0 -xy order = 3, swaptyp =
0 x-y s order = 2, swaptyp = 2 -Y, +X, n order = 7, swaptyp = 1 S  order  =
0, swaptyp = 2 +yf, +xf order = 4, swaptyp = 0
 
Invalid strings: +x-x (Same axis defined twice) +x+y-x (More than two  axes
                 defined) xysn (Byte swapping and  no  byte  swapping  both
                 defined) .
 
Fortran call:
 
         CALL XDLF_AXORD (STR, LEN, IORD, ISWAP, IERR)
 
 
Parameters:
 
STR         (R)   Character string containing the axis order
                  (and byte swapping option) definition
                  (see str)
                  ** Pass address using the XDLSTR routine **
LEN         (R)   The length of the character string
IORD        (W)   Returns the axis order as a number from 1-8
                  (0 if not specified or syntax error) 
                  (see order)
ISWAP       (W)   Returns the byte swap flag =1 no byte swap
                                             =2 byte swap data
                                             =0 not specified (or
                                                syntax error)
IERR        (W)   Returns the status from the xdl_axord call
 
 
'C' call:
 
int xdl_axord (str,len,order,swaptyp)
 
 
Parameters:
 
char *str;       /* String containing the axes order and byte swap flags
                    (R)*/
int len;         /* Length of the string; if 0 then assume a null
                    terminated string was passed (R) */
int *order;      /* Returns the axis order given as a number from 1 to 8
                    (If none specified (or syntax error) return 0)
                     1   +xf slow   +yf fast
                     2   +xf slow   -yf fast
                     3   -xf slow   +yf fast
                     4   -xf slow   -yf fast
                     5   +yf slow   +xf fast
                     6   +yf slow   -xf fast
                     7   -yf slow   +xf fast
                     8   -yf slow   -xf fast
                     (W)*/
int *swaptyp;    /* Returns byte swap type   =1 do not swap bytes
                                             =2 swap bytes
                                             =0 not specified (or syntax
                                                error)
                    (W)*/

 
 
Return:  Error flag =0 no error; 
                    >0 syntax error   =1 Only one axis defined.
                                      =2 Both axes the same.
                                      =3 More than two axes defined.
                                      =4 Byte swapping and no byte
                                         swapping defined.
 
 

3.2 IMAGE BACKGROUND CALCULATION ROUTINES
=========================================


3.2.1 INTRODUCTION
 
These are a  set  of  routines  for  calculating  a  background  image  and
background values from  a  single  crystal  X-ray  diffraction  image.  The
routines are written in C.  Fortran  interfaces  are  provided.  They  were
written, in particular, for use with programs using XDL_VIEW  routines,  in
particular xdl_image (xdlf_image) and related routines.
 
The following sets of routines are available:
 
   Background Calculation Routines
 
3.2.2 BACKGROUND CALCULATION ROUTINES
 
3.2.2.1 Introduction
 
The following routines are available:
 
   Calculate background image using a 2-D search - xdl_bg_calc
   Background 2-D search with progress bar - xdl_bg_calc_prog
   Calculate radially averaged background - xdl_bg_strip
   Form radially averaged background image - xdl_bg_radimg
   Get background value from background function - xdl_bg_val
   Get background value from background image - xdl_bg_valimg
 
3.2.2.2 Calculate background image using a 2-D search - xdl_bg_calc
 
The routine xdl_bg_calc (xdlf_bg_calc) is used to  calculate  a  background
image from an image. This is for single crystal  X-ray  diffraction  images
(i.e. one with spots over a fairly slowly changing background). The  method
calculates the background at a pixel by taking the average  of  the  lowest
pixel values in a box surrounding the pixel such that the  number  of  such
values is a requested percentage of the total number of pixels in the  box.
To optimise the calculation, the box is walked through the image  moving  a
pixel at a time starting at the top left. It then repeats  the  process  of
left from to right, then one pixel down, then from right to left, and  then
one pixel down etc. until  the  film  image  has  been  covered.  (In  this
description the slow moving image index is visualised as being from top  to
bottom and the fast one from left to right). The routines will cope with  a
maximum background level up to around 65000.
 
Fortran call:
 
         CALL XDLF_BG_CALC (IMG, ITYPE, NSRASTS, NFRASTS, NFOFF, 
        +                   NCMP, NPBOX, IPCNT, IMG_BG, NFBGOFF, IERR)
 
 
Parameters:
 
IMG         (R)   Array holding the image data 
                  (normally packed into an integer array) 
                  (see 'img')
ITYPE       (R)   Image data type =1 unsigned byte, 
                                  =2 unsigned two-byte, 
                                  =3 signed integer 
                                  =4 squashed i2
                  (see 'type')
NSRASTS     (R)   No. rasters along slow image axis 
                  (see 'ns_rasts')
NFRASTS     (R)   No. rasters along fast image axis
                  (see 'nf_rasts')
NFOFF       (R)   Offset (in pixels) between successive slow
                  rasters (see 'nf_off')
NCMP        (R)   Compress (sample) NCMP into 1 pixel in each 
                  direction for background image (see ncmp)
NPBOX       (R)   Dimension of background calculation box in
                  pixels of compressed imagee (preferably odd) 
                  (see 'npbox')
IPCNT       (R)   Percentage of pixels to treat as background.
                  If -IPCNT is given, then pixel values of zero
                  will be omitted from the calculation.
                  (see 'percent')
IMG_BG      (W)   Array to hold the returned background image.
                  (pass an integer array large enough to hold 
                  the returned image data) (see 'img_bg')
NFBGOFF     (R/W) Offset between start of lines in returned
                  background image (allows for padding if 
                  required). If zero on input then value will
                  be returned for no padding cases (see nf_bgoff)
IERR        (W)   Returns the status from the xdl_bg_calc
                  call
 
 
'C' call:
 
int xdl_bg_calc (img, type, ns_rasts, nf_rasts, nf_off, ncmp, npbox, 
                 percent, img_bg, nf_bgoff)
 
 
Parameters:
 
char *img;                 /* Image from which to calculate the background 
                              image (R)*/
int type;                  /* Image (and backgound image) data type
                              =1 unsigned byte
                              =2 unsigned two-byte data
                              =3 signed integer data
                              =4 'squashed i2' data (if Intensity>32767
                                 store as 65536-Intensity/8)
                              (R)*/
int ns_rasts;              /* No. of slow moving rasters in the image (R)*/
int nf_rasts;              /* No. of fast moving rasters in the image (R)*/
int nf_off;                /* Offset in the image (in pixels) between start
                              of each line of the image as stored (allows
                              for padding at the end of each line if 
                              used) (R)*/
int ncmp;                  /* No. of pixels to compress into 1 in each
                              direction for the background image. The
                              size of the background image will be
                              ns_rasts/ncmp * nf_rasts/ncmp (integer
                              divisions) (R)*/
int npbox;                 /* Size of box (after compression of the image)
                              for each background calculation
                              in pixels (box is npbox*npbox) - preferably
                              an odd number (R)*/
int percent;               /* Percentage of pixels to treat as background 
                              If -percent is given, then pixel values of 
                              zero will be omitted from the calculation
                              (R)*/
char *img_bg;              /* Returns background image in same data format
                              as the input image. The size of the 
                              background image will be
                              ns_rasts/ncmp * nf_rasts/ncmp (integer
                              divisions) (see also mf_bgoff) (W)*/
int *nf_bgoff;             /* Offset between start of image lines in
                              returned background image. If value
                              given is less than nf_rasts/ncmp then
                              it will be reset to nf_rasts/ncmp (R/W)*/
                              
 
 
Return:  =0 OK; =1 background too high (> 65000); =2 box too big for image
 
 
3.2.2.3 Background 2-D search with progress bar - xdl_bg_calc_prog
 
The  routine  xdl_bg_calc_ptrog  (xdlf_bg_calc_prog)   is   the   same   as
xdl_bg_calc (xdlf_bg_calc) except that it has allows  for  routines  to  be
passed to it to monitor the progress of the background calculation  and  to
cancel i the calculation if required.
 
Fortran call:
 
         CALL XDLF_BG_CALC_PROG (IMG, ITYPE, NSRASTS, NFRASTS, NFOFF, 
        +                   NCMP, NPBOX, IPCNT, IMG_BG, NFBGOFF, 
        +                   PROGRESS, CANCEL, IERR)
 
 
Parameters:
 
IMG         (R)   Array holding the image data 
                  (normally packed into an integer array) 
                  (see 'img')
ITYPE       (R)   Image data type =1 unsigned byte, 
                                  =2 unsigned two-byte, 
                                  =3 signed integer 
                                  =4 squashed i2
                  (see 'type')
NSRASTS     (R)   No. rasters along slow image axis 
                  (see 'ns_rasts')
NFRASTS     (R)   No. rasters along fast image axis
                  (see 'nf_rasts')
NFOFF       (R)   Offset (in pixels) between successive slow
                  rasters (see 'nf_off')
NCMP        (R)   Compress (sample) NCMP into 1 pixel in each 
                  direction for background image (see ncmp)
NPBOX       (R)   Dimension of background calculation box in
                  pixels of compressed imagee (preferably odd) 
                  (see 'npbox')
IPCNT       (R)   Percentage of pixels to treat as background.
                  If -IPCNT is given, then pixel values of zero
                  will be omitted from the calculation.
                  (see 'percent')
IMG_BG      (W)   Array to hold the returned background image.
                  (pass an integer array large enough to hold 
                  the returned image data) (see 'img_bg')
NFBGOFF     (R/W) Offset between start of lines in returned
                  background image (allows for padding if 
                  required). If zero on input then value will
                  be returned for no padding cases (see nf_bgoff)
PROGRESS    (R)   Subroutine to monitor progress. Will be
                  called after each processing 'strip' 
                  as follows:
                  as follows:
                  CALL PROGRESS (IFLAG, NSTRIP, ISTRIP)
                  CALL PROGRESS (IFLAG, NSTRIP, ISTRIP)
                  IFLAG    (R)   =0 start, =1 in progress, 
                                 =2 done
                  NSTRIP   (R)   Total no. of strips of image to 
                                 process
                  ISTRIP   (R)   Current strip (1 to NSTRIP)
                  ISTRIP   (R)   Current strip (1 to NSTRIP)
CANCEL      (R)   This routine will be called at intervals to
                  see if a cancel state has been set.
                  see if a cancel state has been set.
                  The call is:
                  The call is:
                  CALL CANCEL (ICANCL)
                  CALL CANCEL (ICANCL)
                  ICANCL   (W)  Return 0 to continue, 1 to cancel
                  ICANCL   (W)  Return 0 to continue, 1 to cancel
IERR        (W)   Returns the status from the xdl_bg_calc_prog
                  call
 
 
'C' call:
 
int xdl_bg_calc_prog (img, type, ns_rasts, nf_rasts, nf_off, ncmp, npbox, 
                 percent, img_bg, nf_bgoff, progress, cancel)
 
 
Parameters:
 
char *img;                 /* Image from which to calculate the background 
                              image (R)*/
int type;                  /* Image (and backgound image) data type
                              =1 unsigned byte
                              =2 unsigned two-byte data
                              =3 signed integer data
                              =4 'squashed i2' data (if Intensity>32767
                                 store as 65536-Intensity/8)
                              (R)*/
int ns_rasts;              /* No. of slow moving rasters in the image (R)*/
int nf_rasts;              /* No. of fast moving rasters in the image (R)*/
int nf_off;                /* Offset in the image (in pixels) between start
                              of each line of the image as stored (allows
                              for padding at the end of each line if 
                              used) (R)*/
int ncmp;                  /* No. of pixels to compress into 1 in each
                              direction for the background image. The
                              size of the background image will be
                              ns_rasts/ncmp * nf_rasts/ncmp (integer
                              divisions) (R)*/
int npbox;                 /* Size of box (after compression of the image)
                              for each background calculation
                              in pixels (box is npbox*npbox) - preferably
                              an odd number (R)*/
int percent;               /* Percentage of pixels to treat as background 
                              If -percent is given, then pixel values of 
                              zero will be omitted from the calculation
                              (R)*/
char *img_bg;              /* Returns background image in same data format
                              as the input image. The size of the 
                              background image will be
                              ns_rasts/ncmp * nf_rasts/ncmp (integer
                              divisions) (see also mf_bgoff) (W)*/
int *nf_bgoff;             /* Offset between start of image lines in
                              returned background image. If value
                              given is less than nf_rasts/ncmp then
                              it will be reset to nf_rasts/ncmp (R/W)*/
void (*progress)();        /* Function passed to the routine to monitor
                              the progress of the background calculation.
                              called as follows: 

                              progress (iflag, nstrip, istrip);

                              int *iflag;    =0 start, =1 in progress, 
                                             =2 done
                              int *nstrip;   Total no. of strips of image to 
                                             process
                              int *istrip;   Current strip (1 to nstrip)

                              (May be a NULL)
                              (R)*/
void (*cancel)();          /* Function passed to the routine to enable
                              cancellation. Called as follows:

                              cancel (icancl);

                              int *icancl;  Function must return 0 to 
                                            continue, or 1 to cancel.
                              (May be a NULL)
                              (R)*/                              
 
 
Return:  =0 OK; =1 background too high (> 65000); =2 box too big for image
         -1 interrupted
 
 
3.2.2.4 Calculate radially averaged background - xdl_bg_strip
 
The routine xdl_bg_strip (xdlf_bg_strip) is used to  calculate  a  radially
averaged background from an image. The method calculates the background  at
a pixel by taking  the  average  of  the  lowest  pixel  values  in  a  box
surrounding the pixel such that the number of such values  is  a  requested
percentage of the total number of pixels in the box. The background  values
are found for a horizontal (fast axis) or vertical  (slow  axis)  strip  of
pixels running through the centre of the image and the values from the  two
halves of  the  strip  are  averaged.  The  routine  will  only  cope  with
background levels up to around 65000.
 
Fortran call:
 
         CALL XDLF_BG_STRIP (IMG, ITYPE, NSRASTS, NFRASTS, NFOFF, NCMP, 
        +                    NPBOX, IPCNT, IOPT, IBGAVE, NBG, IERR)
 
 
Parameters:
 
IMG         (R)   Array holding the image data .
                  (normally packed into an integer array) 
                  (see 'img')
ITYPE       (R)   Image data type 1 = unsigned byte, 2 =
                  unsigned two-byte, 3 = signed integer,
                  4 = 'squashed i2' (see 'type')
NSRASTS     (R)   No. rasters in slow image direction 
                  (see 'ns_rasts')
NFRASTS     (R)   No. rasters in fast image direction 
                  (see 'nf_rasts')
NFOFF       (R)   Offset (in pixels) between successive slow
                  rasters (see 'nf_off')
NCMP        (R)   Compress NCMP into 1 pixel in each direction
                  for background image (actually sample)
                  (see ncmp)
NPBOX       (R)   Dimension of background calculation box in
                  pixels of compressed image (preferably odd) 
                  (see 'npbox')
IPCNT       (R)   Percentage of pixels to treat as background
                  (see 'percent')
IOPT        (R)   =1 strip across the centre along fast axis
                  =2 strip through the centre along slow axis
IBGAVE      (W)   Array returning radially averaged background
                  values (see bgave)
NBG         (W)   The number of values returned in IBGAVE
                  (maxr_off+1, see maxr_off)
IERR        (W)   Returns the status from the xdl_bg_strip
                  call
 
 
'C' call:
 
int xdl_bg_strip (img, type, ns_rasts, nf_rasts, nf_off, ncmp, npbox, 
                  percent, iopt, bgave, maxr_off)
 
 
Parameters:
 
char *img;                 /* Full image data (R) */
int type;                  /* Data type =1 unsigned byte data
                                        =2 unsigned two-byte data
                                        =3 signed integer data
                                        =4 'squashed i2' data
                              (R)*/
int ns_rasts;              /* No. of slow rasters in image (R) */
int nf_rasts;              /* No. of fast rasters in image (R) */
int nf_off;                /* Offset in rasters between lines of
                              stored image (allows for padding) (R)*/
int ncmp;                  /* Compress ncmp pixels in each direction
                              into 1 before calculating background 
                              (data are actually sampled) (R)*/
int npbox;                 /* Size of box for each background calculation
                              in pixels (box is npbox*npbox) - preferably
                              an odd number (box is for compressed
                              image) (R)*/
int percent;               /* Percentage of pixels to treat as background 
                              (R)*/
int iopt;                  /* =1, strip through centre along fast axis
                              =2, strip through centre along slow axis 
                              (R)*/
int bgave[];               /* Returns radially averaged background function
                              in intervals of pixels of the compressed
                              image and starting from the centre of that
                              image; dimension to >= (nf_rasts/ncmp)/2
                              for iopt 1 and (ns_rasts/ncmp)/2 for iopt 2 
                              (W)*/
int *maxr_off;             /* Maximum offset in returned 'bgave' array 
                              (W)*/
 
 
Return:  =0 OK; 
         =1 Background too high (>65000)
         =2 box too big for image
         =3 Unable to allocate memory for temporary arrays;
 
 
3.2.2.5 Form radially averaged background image - xdl_bg_radimg
 
The routine xdl_bg_radimg (xdlf_bg_radimg) is used to  form  a  a  radially
averaged background image from the radially  averaged  background  function
returned by xdl_bg_strip (xdlf_bg_strip).
 
Fortran call:
 
         CALL XDLF_BG_RADIMG (ITYPE, NS_BG, NF_BG, NF_BGOFF, IBGAVE, 
        +                     NBG, IMG_BG, IERR)
 
 
Parameters:
 
ITYPE       (R)   Required data type for background image
                  =1 unsigned byte
                  =2 unsigned two-byte
                  =3 signed integer
                  =4 'squashed i2'
                  (see type)
NS_BG       (R)   No. of rasters in background image along
                  slow moving axis (see ns_bg)
NF_BG       (R)   No. of rasters in background image along
                  fast moving axis (see nf_bg)
NF_BGOFF    (R)   Offset required between successive lines of
                  returned image (allows for padding if required)
                  (see nf_bgoff)
IBGAVE      (R)   Array with radially averaged background
                  values (see bgave)
NBG         (W)   The number of values in IBGAVE
                  (maxr_off+1, see maxr_off)
IMG_BG      (W)   Integer array returning background image
                  (must be large enough to hold 
                  NS_BG*NF_BGOFF data pixels) (see img_bg)
IERR        (W)   Returns the status from the xdl_bg_radimg
                  call
 
 
'C' call:
 
int xdl_bg_radimg (type, ns_bg, nf_bg, nf_bgoff, bgave, maxr_off, 
                   img_bg)
 
 
Parameters:
 
int type;               /* Background image data type 
                           =1 unsigned byte
                           =2 unsigned two-byte
                           =3 signed integer
                           =4 'squashed i2'
                           (R) */
int ns_bg;              /* No. rasters in backgound image along slow 
                           moving axis (R) */
int nf_bg;              /* No. rasters in backgound image along fast
                           moving axis (R) */
int nf_bgoff;           /* Required offset between successive lines of
                           returned background image (allows for padding
                           if required) (R) */
int bgave[];            /* Radially average background values from
                           xdl_bg_strip (R)*/
int maxr_off;           /* Maximum offset in 'bgave' from xdl_bg_strip 
                           (R)*/
char *img_bg;           /* Returns the compressed radially averaged 
                           background image (ns_bg*nf_bg padded if 
                           required) (W)*/
 
 
Return:  =0 OK; 
 
 
3.2.2.6 Get background value from background function - xdl_bg_val
 
The routine xdl_bg_val (xdlf_bg_val) is used to get a background value at a
given pixel position in the full image from a radially averaged  background
function as returned by  xdl_bg_strip  (xdlf_bg_strip).  If  the  pixel  is
outside the range of the background  function  the  value  at  the  maximum
available radius will be returned.
 
Fortran call:
 
         CALL XDLF_BG_VAL (ISLOW, IFAST, IBGAVE, NBG, NSRASTS, NFRASTS,
                           NCMP, IVAL, IERR)
 
 
Parameters:
 
ISLOW       (R)   Pixel  position along slow axis in full image 
                  (from 1 up)
IFAST       (R)   Pixel  position along fast axis in full image 
                  (from 1 up)
IBGAVE      (R)   Array with radially averaged background
                  values (see bgave)
NBG         (R)   The number of values in IBGAVE
                  (maxr_off+1, see maxr_off)
NSRASTS     (R)   No. rasters along slow axis in full image from 
                  which the background was calculated
NFRASTS     (R)   No. rasters along fast axis in full image from 
                  which the background was calculated
NCMP        (R)   No. pixels in each direction compressed into
                  1 for the background calculation.
IVAL        (W)   Returned background value (see ival)
IERR        (W)   Returns the status from the xdl_bg_val
                  call
 
 
'C' call:
 
int xdl_bg_val (islow, ifast, bgave, maxr_off, ns_rasts, nf_rasts,
                ncmp, ival)
 
 
Parameters:
 
int islow;              /* The pixel position in the full image
                           along the slow axis (from 1 up) (R)*/
int ifast;              /* The pixel position in the full image
                           along the fast axis (from 1 up) (R)*/
int bgave[];            /* Radially average background values from
                           xdl_bg_strip (R)*/
int maxr_off;           /* Maximum offset in 'bgave' from xdl_bg_strip 
                           (R)*/
int ns_rasts;           /* No. of rasters along the slow axis of the image 
                           used to calculate background function (R)*/
int nf_rasts;           /* No. of rasters along the fast axis of the image 
                           used to calculate background function (R)*/
int ncmp;               /* No. of pixels in each direction compressed into
                           1 for the background calcn. (R)*/
int *ival;              /* Returns background value (W)*/
 
 
Return:  =0 OK; 
 
 
3.2.2.7 Get background value from background image - xdl_bg_valimg
 
The routine xdl_bg_valimg (xdlf_bg_valimg) is  used  to  get  a  background
value at a given pixel  position  in  the  full  image  from  a  previously
calculated background image (e.g. from  xdl_bg_radimg  (xdlf_bg_radimg)  or
xdl_bg_calc (xdlf_bg_calc)). If the pixel  is  outside  the  range  of  the
background image the background value at the edge will be returned.
 
Fortran call:
 
         CALL XDLF_BG_VALIMG (ISLOW, IFAST, IMG_BG, ITYPE, NF_BGOFF,
        +                         NCMP, IVAL, IERR)
 
 
Parameters:
 
ISLOW       (R)   Pixel  position along slow axis in full image 
                  (from 1 up)
IFAST       (R)   Pixel  position along fast axis in full image 
                  (from 1 up)
IMG_BG      (R)   Background image (e.g. from xdl_bg_calc
                  or xdl_bg_radimg (see img_bg)
ITYPE       (R)   Data type for background image
                  =1 unsigned byte
                  =2 unsigned two-byte
                  =3 signed integer
                  =4 'squashed i2'
                  (see type)
NF_BGOFF    (R)   Offset between successive lines of background
                  image (allowing for padding if used)
                  (see nf_bgoff)
NCMP        (R)   No. pixels in each direction compressed into
                  1 for the background calculation.
IVAL        (W)   Returned background value (see ival)
IERR        (W)   Returns the status from the xdl_bg_valimg
                  call
 
 
'C' call:
 
int xdl_bg_valimg (islow, ifast, img_bg, type, nf_bgoff,
                    ncmp, ival)
 
 
Parameters:
 
int islow;              /* The pixel position in the full image
                           along the slow axis (from 1 up) (R)*/
int ifast;              /* The pixel position in the full image
                           along the fast axis (from 1 up) (R)*/
char *img_bg;           /* Background image (R)*/
int type;               /* Background image data type 
                           =1 unsigned byte
                           =2 unsigned two-byte
                           =3 signed integer
                           =4 'squashed i2'
                           (R) */
int nf_bgoff;           /* Offset between successive lines of
                           background image (allowing for padding
                           if used) (R)*/
int ncmp;               /* No. of pixels in each direction compressed into
                           1 for the background calcn. (R)*/
int *ival;              /* Returns background value (W)*/
 
 
Return:  =0 OK; 
 
 

CHAPTER 4: THE PANEL ITEM ROUTINES AND CALLBACKS 
================================================


4.1 INTRODUCTION
 
The xdl_panel_item routines provide standard window items which may be used
within the coding of view-objects. They differ from the  main  view-objects
in that they are used to serve the internal needs of a  view-object  rather
than being directly called from an application program.
 
The following sets of routines are available:
 
   Panel Choice Item Routines
   Panel Button Item Routines
   Panel Label Item Routines
   Panel Value Item Routines
   Panel Slider Item Routines
   Panel I/O Item Routines
 
4.2 PANEL CHOICE ITEM ROUTINES
 
4.2.1 Introduction
 
These are routines for creating and handling a panel choice item.
 
The following routines are available:
 
   Create a panel choice item - xdl_panel_choice
   Reset panel choice item - xdl_panel_choice_reset
   Get window id - xdl_panel_choice_wid
   Get size - xdl_panel_choice_size
 
4.2.2 Create a panel choice item - xdl_panel_choice
 
The routine xdl_panel_choice is used to create a panel choice item  with  a
popup menu. The item has a label, an indicator box to indicate a drop  down
menu and a display of the currently selected menu item. A callback  routine
is invoked when a menu item is selected.
 
'C' call:
 
Panel_object xdl_panel_choice (vh, wid, x, y, label, nstrings, strings, 
                               df_item, font_type, brdr, 
                               min_width, min_height, callback)
 
 
Parameters:
 
int vh;             /* View-object handle (R)*/
Window wid;         /* Window id of panel choice's parent window (R)*/
int x;              /* x position of the panel choice area (R)*/
int y;              /* y position of the panel choice area (R)*/
char *label;        /* Label for panel choice (null terminated string)
                       (R)*/
int nstrings;       /* Number of items in choice options menu (R)*/
char **strings;     /* Pointer to list of null terminated strings with 
                       choice options (R)*/
int df_item;        /* Default item number (1 to nstrings) (R)*/
int font_type;      /* Font type 1 to 5, very-small to extra-large (R)*/
int brdr;           /* =1 draw border (1 thick), =0 do not (R)*/
int min_width;      /* Minimum width of the panel choice item; this will 
                       be used if it is greater than the width calculated
                       using the length of the strings, font type etc. 
                       (R)*/
int min_height;     /* Minimum height of the panel choice item; this will 
                       be used if it is greater than the height calculated 
                       using the font type etc. (R)*/
void (*callback)(); /* Callback routine to take returned choice 
                       selection (R)*/

/*
Callback:  (*callback)(int iv, int item)

           iv     The offset in the XDL_view_objects array for the parent
                  view-object to which the panel choice item belongs.

           item   The selected item number from the popup menu.
*/

 
 
Return:  None
 
 
4.2.3 Reset panel choice item - xdl_panel_choice_reset
 
The routine xdl_panel_choice_reset is used to reset the selected item for a
panel choice item.
 
'C' call:
 
void xdl_panel_choice_reset (panel_object, item)
 
 
Parameters:
 
Panel_object panel_object;   /*The panel object returned when the panel
                               choice item was created using 
                               xdl_panel_choice (R)*/
int item;                    /*The number of the item to select from 
                               1 up (R)*/

 
 
Return:  None
 
 
4.2.4 Get window id - xdl_panel_choice_wid
 
The routine xdl_panel_choice_wid is used to return the window identifier of
the panel item's window.
 
'C' call:
 
void xdl_panel_choice_wid (panel_object, wid)
 
 
Parameters:
 
Panel_object panel_object;   /*The panel object returned when the panel
                               item was created (R) */
Window *wid;                 /*Returns the window identifier (W) */

 
 
Return:  None
 
 
4.2.5 Get size - xdl_panel_choice_size
 
The routine xdl_panel_choice_size is used to predetermine  the  size  of  a
panel choice item.
 
'C' call:
 
void xdl_panel_choice_size (max_len, max_string, brdr, font_type, 
                            width, height)
 
 
Parameters:
 
int max_len;    /* Maximum length of label string */
int max_string; /* Maximum length of menu choice string */
int brdr;       /* =1 draw border (1 thick), =0 do not (R)*/
int font_type;  /* Font size (1-5) (R)*/
int *width;     /* Returns the required width (W)*/
int *height;    /* Returns the required height (W)*/

 
 
Return:  None
 
 
4.3 PANEL BUTTON ITEM ROUTINES
 
4.3.1 Introduction
 
These are routines for creating and handling a panel button item.
 
The following routines are available:
 
   Create a panel button item - xdl_panel_button
   Set a new button label string - xdl_panel_button_set
   Get window id - xdl_panel_button_wid
   Get size - xdl_panel_button_size
 
4.3.2 Create a panel button item - xdl_panel_button
 
The routine xdl_panel_button  creates  a  panel  button  item.  A  callback
routine is invoked when the panel button is selected.
 
'C' call:
 
Panel_object xdl_panel_button (vh, wid, x, y, label, max_len, 
                              font_type, brdw, min_width, min_height, 
                              bold, cntr, button_number, callback)
 
 
Parameters:
 
int vh;             /* View-object handle (R)*/
Window wid;         /* Window id of panel button's parent window (R)*/
int x;              /* x position of the panel button area (R)*/
int y;              /* y position of the panel button area (R)*/
char *label;        /* Label for panel button (null terminated string) 
                       (copy will be made) (R)*/
int max_len;        /* Maximum no. of characters to be allowed for the
                       label string (R)*/
int font_type;      /* Font type 1 to 5, very-small to extra-large (R)*/
int brdw;           /* Border width for button (0 upwards) (R)*/
int min_width;      /* Minimum width of the panel button item; this 
                       will be used if it is greater than the width 
                       calculated using the length of the label, font 
                       type etc. (R)*/
int min_height;     /* Minimum height of the panel button item; this 
                       will be used if it is greater than the height 
                       calculated using the font type etc. (R)*/
int bold;           /* =1 bold print, =0 normal (R)*/
int cntr;           /* =0 left justified, =1 centered (R)*/
int button_number;  /* Button number to pass onto callback routine;
                       enables the same callback routine to be used
                       for several buttons if required provided that
                       each button is assigned a different number (R)*/
void (*callback)(); /* Callback routine when button selected (R)*/

/*
Callback:  (*callback)(int iv, int button_number)

           iv               The offset in the XDL_view_objects array 
                            for the parent view-object to which the 
                            panel button item belongs.

           button_number    The button number given when the button was
                            created.
*/

 
 
Return:  Panel_object for created item.
 
 
4.3.3 Set a new button label string - xdl_panel_button_set
 
The routine xdl_panel_button_set is used to output a new label string in  a
panel button.
 
'C' call:
 
void xdl_panel_button_set (panel_object, label, len, bold, cntr)
 
 
Parameters:
 
Panel_object panel_object;   /*The panel object returned when the label
                               was created using xdl_panel_button (R)*/
char * label;                /*String containing the new label (R)*/
int len;                     /*Length of string; if 0 then length will 
                               be determined assuming a null terminated 
                               string (R)*/
int bold;                    /*Bold print flag =1 bold print, 
                               =0 normal (R)*/
int cntr;                    /*=0 left justified, =1 centered (R)*/

 
 
Return:  None
 
 
4.3.4 Get window id - xdl_panel_button_wid
 
The routine xdl_panel_button_wid is used to return the window identifier of
the panel item's window.
 
'C' call:
 
void xdl_panel_button_wid (panel_object, wid)
 
 
Parameters:
 
Panel_object panel_object;   /*The panel object returned when the panel
                               item was created (R) */
Window *wid;                 /*Returns the window identifier (W) */

 
 
Return:  None
 
 
4.3.5 Get size - xdl_panel_button_size
 
The routine xdl_panel_button_size is used to predetermine  the  size  of  a
panel button item.
 
'C' call:
 
void xdl_panel_button_size (max_len, font_type, brdw, width, height)
 
 
Parameters:
 
int max_len;    /* Maximum length of label string */
int font_type;  /* Font size (1-5) (R)*/
int brdw;       /* Border width (R)*/
int *width;     /* Returns the required width (W)*/
int *height;    /* Returns the required height (W)*/

 
 
Return:  None
 
 
4.4 PANEL LABEL ITEM ROUTINES
 
4.4.1 Introduction
 
These are routines for creating and handling a panel label item.
 
The following routines are available:
 
   Create a panel label item - xdl_panel_label
   Set a new panel label string - xdl_panel_label_set
   Get window id - xdl_panel_label_wid
   Get size - xdl_panel_label_size
 
4.4.2 Create a panel label item - xdl_panel_label
 
The routine xdl_panel_label is used to create  a  panel  label  item.  This
merely displays a text string which may be changed when required.
 
'C' call:
 
Panel_object xdl_panel_label (vh, wid, x, y, label, max_len, 
                              font_type, brdr, 
                              min_width, min_height, bold)
 
 
Parameters:
 
Window wid;         /* Window id of panel label's parent window (R)*/
int x;              /* x position of the panel label area (R)*/
int y;              /* y position of the panel label area (R)*/
int vh;             /* View-object handle (R)*/
char *label;        /* Label for panel label (null terminated string) 
                       (copy will be made) (R)*/
int max_len;       /* Maximum no. of characters to be allowed for the
                       label string (R)*/
int font_type;      /* Font type 1 to 5, very-small to extra-large (R)*/
int brdr;           /* =1 draw border (1 thick), =0 do not (R)*/
int min_width;      /* Minimum width of the panel label item; this will 
                       be used if it is greater than the width calculated 
                       using the length of the label, font type etc. (R)*/
int min_height;     /* Minimum height of the panel label item; this will 
                       be used if it is greater than the height calculated 
                       using the font type etc. (R)*/
int bold;           /* =1 bold print, =0 normal (R)*/

 
 
Return:  Panel_object for created item.
 
 
4.4.3 Set a new panel label string - xdl_panel_label_set
 
The routine xdl_panel_label_set is used to output a new label  text  string
for a panel label item.
 
'C' call:
 
void xdl_panel_label_set (panel_object, label, len, bold)
 
 
Parameters:
 
Panel_object panel_object;   /*The panel object returned when the label
                               was created using xdl_panel_label (R)*/
char * label;                /*String containing the new label (R)*/
int len;                     /*Length of string; if 0 then length will be
                               determined assuming a null terminated 
                               string (R)*/
int bold;                    /*Bold print flag =1 bold print, 
                               =0 normal (R)*/

 
 
Return:  None
 
 
4.4.4 Get window id - xdl_panel_label_wid
 
The routine xdl_panel_label_wid is used to return the window identifier  of
the panel item's window.
 
'C' call:
 
void xdl_panel_label_wid (panel_object, wid)
 
 
Parameters:
 
Panel_object panel_object;   /*The panel object returned when the panel
                               item was created (R) */
Window *wid;                 /*Returns the window identifier (W) */

 
 
Return:  None
 
 
4.4.5 Get size - xdl_panel_label_size
 
The routine xdl_panel_label_size is used to  predetermine  the  size  of  a
panel label item.
 
'C' call:
 
void xdl_panel_label_size (max_len, font_type, brdr, width, height)
 
 
Parameters:
 
int max_len;    /* Maximum length of label string */
int font_type;  /* Font size (1-5) (R)*/
int brdr;       /* =1 draw border (1 thick), =0 do not (R)*/
int *width;     /* Returns the required width (W)*/
int *height;    /* Returns the required height (W)*/

 
 
Return:  None
 
 
4.5 PANEL VALUE ITEM ROUTINES
 
4.5.1 Introduction
 
These are routines for creating and handling a panel value item.
 
The following routines are available:
 
   Create a panel value item - xdl_panel_value
   Set a new panel value string - xdl_panel_value_set
   Get window id - xdl_panel_value_wid
   Get size - xdl_panel_value_size
 
4.5.2 Create a panel value item - xdl_panel_value
 
The routine xdl_panel_value is used to create  a  panel  value  item.  This
displays a label and an value string. The value string may  be  changed  by
the user causing a callback routine to be invoked.
 
'C' call:
 
Panel_object xdl_panel_value (vh, wid, x, y, label, valstr, maxv_len, 
                              font_type, brdr, 
                              min_width, min_height, callback)
 
 
Parameters:
 
Window wid;         /* Window id of panel value's parent window (R)*/
int x;              /* x position of the panel value area (R)*/
int y;              /* y position of the panel value area (R)*/
int vh;             /* View-object handle (R)*/
char *label;        /* Label for panel value (null terminated string) (R)*/
char *valstr;       /* Initial value string (null terminated) (R)*/
int maxv_len;       /* Maximum no. of characters to be allowed for the
                       value string (R)*/
int font_type;      /* Font type 1 to 5, very-small to extra-large (R)*/
int brdr;           /* =1 draw border (1 thick), =0 do not (R)*/
int min_width;      /* Minimum width of the panel value item; this will be
                       used if it is greater than the width calculated 
                       using the length of the label, length of the value, 
                       font type etc. (R)*/
int min_height;     /* Minimum height of the panel value item; this will be
                       used if it is greater than the height calculated 
                       using the font type etc. (R)*/
void (*callback)(); /* Callback routine to take returned value 
                       position (R)*/

/*
Callback:  (*Callback)(int iv, char * valstr, int len, int max_len)

           iv        The offset in the XDL_view_objects array for the 
                     parent view-object to which the panel value item 
                     belongs.

           valstr    Pointer to the returned value string

           len       Length of the returned value string

           max_len   Maximum allowed length of a value string
*/

 
 
Return:  Panel_object for created item.
 
 
4.5.3 Set a new panel value string - xdl_panel_value_set
 
The routine xdl_panel_value_set is used to replace the current panel  value
string with a new value string.
 
'C' call:
 
void xdl_panel_value_set (panel_object, valstr, len)
 
 
Parameters:
 
Panel_object panel_object;   /*The panel object returned when the panel 
                               value was created using xdl_panel_value 
                               (R)*/
char * valstr;               /*String containing the new value (R)*/
int len;                     /*Length of string; if 0 then length will be
                               determined assuming a null terminated 
                               string (R)*/
 
 
Return:  None
 
 
4.5.4 Get window id - xdl_panel_value_wid
 
The routine xdl_panel_value_wid is used to return the window identifier  of
the panel item's window.
 
'C' call:
 
void xdl_panel_value_wid (panel_object, wid)
 
 
Parameters:
 
Panel_object panel_object;   /*The panel object returned when the panel
                               item was created (R) */
Window *wid;                 /*Returns the window identifier (W) */

 
 
Return:  None
 
 
4.5.5 Get size - xdl_panel_value_size
 
The routine xdl_panel_value_size is used to  predetermine  the  size  of  a
panel value item.
 
'C' call:
 
void xdl_panel_value_size (max_len, maxv_len, font_type, brdr, width, 
                           height)
 
 
Parameters:
 
int max_len;    /* Maximum length of label string */
int maxv_len;   /* Maximum no. of characters to be allowed for the
                   value string (R)*/
int font_type;  /* Font type 1 to 5, very-small to extra-large (R)*/
int brdr;       /* =1 draw border (1 thick), =0 do not (R)*/
int *width;     /* Returns the required width (W)*/
int *height;    /* Returns the required height (W)*/

 
 
Return:  None
 
 
4.6 PANEL SLIDER ITEM ROUTINES
 
4.6.1 Introduction
 
These are routines for creating and handling a panel slider item.
 
The following routines are available:
 
   Create a panel slider item - xdl_panel_slider
   Reset a panel slider position - xdl_panel_slider_reset
   Get window id - xdl_panel_slider_wid
   Get size - xdl_panel_slider_size
 
4.6.2 Create a panel slider item - xdl_panel_slider
 
The routine xdl_panel_slider is used to create a panel  slider  item.  This
has a label and a slider bar with a moveable grip box. When the grip box on
the slider is moved a callback routine is invoked.
 
'C' call:
 
Panel_object xdl_panel_slider (vh, wid, x, y, label, font_type, 
                               travel_len, startpos, brdr, 
                               min_width, min_height, callback)
 
 
Parameters:
 
Window wid;         /* Window id of panel slider's parent window (R)*/
int x;              /* x position of the panel slider area (R)*/
int y;              /* y position of the panel slider area (R)*/
int vh;             /* View-object handle (R)*/
char *label;        /* Label for panel slider (null terminated string) 
                       (R)*/
int font_type;      /* Font type 1 to 5, very-small to extra-large (R)*/
int travel_len;     /* Travel length of slider (in pixels). The
                       slider positions will represent travel_len+1
                       discrete values (R)*/
int startpos;       /* Start position of the slider from 0 to 
                       travel_len (R)*/
int brdr;           /* =1 draw border (1 thick), =0 do not (R)*/
int min_width;      /* Minimum width of the panel slider item; this 
                       will be used if it is greater than the width 
                       calculated using the length of the label, 
                       length of the slider, font type etc. (R)*/
int min_height;     /* Minimum height of the panel slider item; this 
                       will be used if it is greater than the height 
                       calculated using the font type etc. (R)*/
void (*callback)(); /* Callback routine to take returned slider 
                       position (R)*/

/*
Callback:  (*callback)(int iv, int curpos, int travel_len)

           iv           The offset in the XDL_view_objects array for 
                        the parent view-object to which the panel 
                        slider item belongs.

           cupos        The current position of the grip box along
                        the slider.

           travel_len   The total travel length along the slider.
*/

 
 
Return:  None
 
 
4.6.3 Reset a panel slider position - xdl_panel_slider_reset
 
The routine xdl_panel_slider_reset is used to set a new slider position for
a panel slider item.
 
'C' call:
 
void xdl_panel_slider_reset (panel_object, islide)
 
 
Parameters:
 
Panel_object panel_object;   /*The panel object returned when the panel 
                               i/o item was created using xdl_panel_io
                               (R)*/
int islide;                  /*The slider position from 0 to 'travel_len' 
                               (R)*/
 
 
Return:  None
 
 
4.6.4 Get window id - xdl_panel_slider_wid
 
The routine xdl_panel_slider_wid is used to return the window identifier of
the panel item's window.
 
'C' call:
 
void xdl_panel_slider_wid (panel_object, wid)
 
 
Parameters:
 
Panel_object panel_object;   /*The panel object returned when the panel
                               item was created (R) */
Window *wid;                 /*Returns the window identifier (W) */

 
 
Return:  None
 
 
4.6.5 Get size - xdl_panel_slider_size
 
The routine xdl_panel_slider_size is used to predetermine  the  size  of  a
panel slider item.
 
'C' call:
 
void xdl_panel_slider_size (max_len, font_type, travel_len, brdr, 
                            width, height)
 
 
Parameters:
 
int max_len;    /* Maximum length of label string */
int font_type;  /* Font size (1-5) (R)*/
int travel_len; /* Travel length of slider (in pixels). The
                   slider positions will represent travel_len+1
                   discrete values (R)*/
int brdr;       /* =1 draw border (1 thick), =0 do not (R)*/
int *width;     /* Returns the required width (W)*/
int *height;    /* Returns the required height (W)*/

 
 
Return:  None
 
 
4.7 PANEL I/O ITEM ROUTINES
 
4.7.1 Introduction
 
These are routines for creating and handling a panel i/o item.
 
The following routines are available:
 
   Create a panel io item - xdl_panel_io
   Set a new panel i/o item prompt - xdl_panel_io_prompt
   Clear/reset a panel i/o item - xdl_panel_io_clear
   Get window id - xdl_panel_io_wid
   Get size - xdl_panel_io_size
 
4.7.2 Create a panel io item - xdl_panel_io
 
The routine xdl_panel_io is used to create a panel i/o item. This  displays
a prompt string and an input reply area. This reply area enables  the  user
to input a character string. If this reply is longer than the  reply  space
available then scrolling will take place. When a string  is  terminated  by
the Return or Enter key or if the Escape key is pressed, a callback routine
will be invoked.
 
'C' call:
 
Panel_object xdl_panel_io (vh, wid, x, y, max_pr, min_rp, max_rp,
                              font_type, brdr, ch_count,
                              min_width, min_height, callback)
 
 
Parameters:
 
Window wid;         /* Window id of panel i/o item's parent window (R)*/
int x;              /* x position of the panel i/o item area (R)*/
int y;              /* y position of the panel i/o item area (R)*/
int vh;             /* View-object handle (R)*/
int max_pr;         /* Max. no. of chars in prompt (R)*/
int min_rp;         /* Minimum width of displayed reply field (in 
                       characters) (R)*/
int max_rp;         /* Maximum allowed reply string length (R)*/
int font_type;      /* Font type 1 to 5, very-small to extra-large (R)*/
int brdr;           /* =1 draw border (1 thick), =0 do not (R)*/
int ch_count;       /* =1 show character count, =0 do not (R)*/
int min_width;      /* Minimum width of the panel i/o item; this will be
                       used if it is greater than the width calculated 
                       using the maximum length of the prompt, mimimum
                       length of the reply field, font type etc. (R)*/
int min_height;     /* Minimum height of the panel i/o item; this will be
                       used if it is greater than the height calculated 
                       using the font type etc. (R)*/
void (*callback)(); /* Callback routine to take returned reply (R)*/

/*
Callback:  (*Callback)(int iv, char * reply, int len, int max_rp, 
                       int flag, int iret)

           iv        The offset in the XDL_view_objects array for the 
                     parent view-object to which the panel value item 
                     belongs.

           reply     Pointer to the returned value string

           len       Length of the returned reply string

           max_rp    Maximum allowed length of a reply string

           flag      Flag passed on from call to xdl_panel_io_prompt

           iret      = 1 non-blank string
                     = 0 blank string
                     =-1 escape pressed
         
*/

 
 
Return:  Panel_object for created item.
 
 
4.7.3 Set a new panel i/o item prompt - xdl_panel_io_prompt
 
The routine xdl_panel_io_prompt is used to set a new prompt and prepare for
a new input reply string.
 
'C' call:
 
void xdl_panel_io_prompt (panel_object, prompt, len, flag)
 
 
Parameters:
 
Panel_object panel_object;   /*The panel object returned when the panel 
                               i/o item was created using xdl_panel_io
                               (R)*/
char * prompt;               /*String containing the new prompt (R)*/
int len;                     /*Length of prompt; if 0 then length will be
                               determined assuming a null terminated 
                               string (R)*/
int flag;                    /*Flag to be passed to callback routine to
                               identify current prompt etc. */
 
 
Return:  None
 
 
4.7.4 Clear/reset a panel i/o item - xdl_panel_io_clear
 
The routine xdl_panel_io_clear is used to clear a panel i/o item.  It  will
remain inactive until another call of the routine xdl_panel_io_prompt.
 
'C' call:
 
void xdl_panel_io_clear (panel_object)
 
 
Parameters:
 
Panel_object panel_object;   /*The panel object returned when the panel 
                               i/o item was created using xdl_panel_io
                               (R)*/
 
 
Return:  None
 
 
4.7.5 Get window id - xdl_panel_io_wid
 
The routine xdl_panel_io_wid is used to return the window identifier of the
panel item's window.
 
'C' call:
 
void xdl_panel_io_wid (panel_object, wid)
 
 
Parameters:
 
Panel_object panel_object;   /*The panel object returned when the panel
                               item was created (R) */
Window *wid;                 /*Returns the window identifier (W) */

 
 
Return:  None
 
 
4.7.6 Get size - xdl_panel_io_size
 
The routine xdl_panel_io_size is used to predetermine the size of  a  panel
I/O item.
 
'C' call:
 
void xdl_panel_io_size (max_pr, min_rp, max_rp, font_type, brdr, ch_count,
                        width, height)
 
 
Parameters:
 
int max_pr;         /* Max. no. of chars in prompt (R)*/
int min_rp;         /* Minimum width of displayed reply field (in 
                       characters) (R)*/
int max_rp;         /* Maximum allowed reply string length (R)*/
int font_type;      /* Font type 1 to 5, very-small to extra-large (R)*/
int brdr;           /* =1 draw border (1 thick), =0 do not (R)*/
int ch_count;       /* =1 show character count, =0 do not (R)*/
int *width;         /* Returns the required width (W)*/
int *height;        /* Returns the required height (W)*/

 
 
Return:  None
 
 

CHAPTER 5: XDL_VIEW LAYOUT ROUTINES 
===================================


5.1 INTRODUCTION
 
The  xdl_view  layout  routines  are  designed  to  assist  the  layout  of
view-objects for a program where several objects are to be fitted  together
to give a tidy looking  layout.  The  basic  look  of  the  layout  may  be
preserved and new positions and sizes automatically calculated if the  size
requirements of any of  the  individual  objects  are  changed.  The  basic
procedure requires that the layout is defined in terms of pairs of  objects
and/or previously defined pairs. Each  newly  defined  pair  may  be  in  a
horizontal or vertical direction. Minimum size requirements are  given  for
the individual objects and recursive procedures are used to  calculate  the
overall size requirement  for  the  layout  and  to  reset  the  sizes  and
positions of the individual objects. There is also an option to  include  a
table (regular rows and columns of single objects) as an item of a pair.
 
The following sets of routines are available:
 
   Determining XDL_VIEW Layout Parameters
 
5.2 DETERMINING XDL_VIEW LAYOUT PARAMETERS
 
5.2.1 Introduction
 
The following routines are available:
 
   Initialise lists - xdl_layout_init
   Define a single object - xdl_layout_set_single
   Give details for a table - xdl_layout_set_table
   Give details of layout pair - xdl_layout_set_pair
   Determine the layout - xdl_layout
   Get object position and size - xdl_layout_get_position
   Reset objects in table - xdl_layout_reset_table
   Reset single object position - xdl_layout_reset_single
 
5.2.2 Initialise lists - xdl_layout_init
 
The routine xdl_layout_init (xdlf_layout_init) is used  to  initialise  the
lists of single objects, tables of objects and layout  pairs.  It  must  be
called before using any other  routine  and  again  if  it  is  desired  to
re-initialise the lists.
 
Fortran call:
 
         CALL XDLF_LAYOUT_INIT (IERR)
 
 
Parameters:
 
IERR     (W)  Returns status from xdl_layout_init call
 
 
'C' call:
 
int xdl_layout_init ()
 
 
Parameters:
 
{
   ns = 0;
   nt = 0;
   np = 0;
   return 0;
}

/* Fortran binding: xdlf_layout_init */

void xdlf_layout_init (ierr)
int *ierr;
 
 
Return:  Status = 0 OK
 
 
5.2.3 Define a single object - xdl_layout_set_single
 
The routine xdl_layout_set_single (xdlf_layout_set_single) is used to  give
details of each single object to be included in  the  layout.  The  minimum
needed with and height must be given. Details are also given for what is to
happen if the space available for the object is expanded as the  layout  is
determined.
 
Fortran call:
 
         CALL XDLF_LAYOUT_SET_SINGLE (XDLSTR(NAME), LEN, IW, IH, 
        +                             IHJUST, IVJUST, IERR)
 
 
Parameters:
 
NAME     (R)  Name by which to identify the single object
              (max 20 chars)
              ** Pass address using the XDLSTR function **
LEN      (R)  Length of the name (>0)
IW       (R)  Minimum width needed (e.g. from a ..getsize routine)
IH       (R)  Minimum height needed
IHJUST   (R)  Horizontal justification required if width is
              expanded.
              0=expand allowed, 
              1=left justify,
              2=right justify,
              3=centre     
IVJUST   (R)  Vertical justification required if height is
              expanded.
              0=expand allowed, 
              1=top justify,
              2=bottom justify,
              3=centre     
IERR     (W)  Returns status from xdl_layout_set_single call
 
 
'C' call:
 
int xdl_layout_set_single(name, len, w, h, hjust, vjust)
 
 
Parameters:
 
char *name;       /* Name used to identify the object (max 20 chars) (R)*/
int len;          /* Length of the name string (may be 0 if a null terminated
                     string is passed) (R)*/
int w;            /* Minimum width needed for the object (R)*/
int h;            /* Minimum height needed for the object (R)*/
int hjust;        /* Horizontal justification required if width is
                     expanded.
                     0=expand allowed, 
                     1=left justify,
                     2=right justify,
                     3=centre           (R)*/
int vjust;        /* Vertical justification required if height is
                     expanded.
                     0=expand allowed, 
                     1=top justify,
                     2=bottom justify,
                     3=centre           (R)*/
 
 
Return:  Status = 0 OK, >0 error
                        =1 name already used
                        =2 list of single objects full
 
 
5.2.4 Give details for a table - xdl_layout_set_table
 
The routine xdl_layout_set_table (xdlf_layout_set_table) is used to to give
details of a table of single objects set  out  in  a  series  of  rows  and
columns. An equal amount of space will be allocated to each  object  though
the  placing  of  the  object  within  that  space  will  depend   on   the
justification  codes  given  when  that  single  object  is  defined  using
xdl_layout_set_single (xdlf_layout_set_single).
 
Fortran call:
 
         CALL XDLF_LAYOUT_SET_TABLE (XDLSTR(NAME), LEN, NROWS, NCOLS,
        +                            XDLSTR(NAMES), NAMLEN, IORDER, 
        +                            IWIDTH, IHEIGHT,
        +                            IERR)
 
 
Parameters:
 
NAME       (R)  Name used to identify the table (max 20
                chars) 
LEN        (R)  Length of the naem string (>0)
NROWS      (R)  Number of rows of items
NCOLS      (R)  Number of columns of items
NAMES      (R)  Fortran array of character strings containing
                the single object names.
                [CHARACTER*NAMLEN NAMES(NITEMS)].
                ** Pass address using XDLSTR function **
                Can pass a blank string for an absent item.
                (see names) 
NAMLEN     (R)  Length of the single object names character strings
                (Must be >0 cf name_len)
IORDER     (R)  Order of items in the names list =1 column fastest,
                =2 row fastest 
IWIDTH     (R)  Mimimum width required for the table (may be 0) 
IHEIGHT    (R)  Minimum height required for the table (may be 0) 
IERR       (W)  Returns status from xdl_layout_set_table call
 
 
'C' call:
 
int xdl_layout_set_table (name, len, nrows, ncols, names, name_len, 
                          order, w, h)
 
 
Parameters:
 
char *name;      /* Name used to identify the table (max 20 chars) (R)*/
int len;         /* Length of the name (may be 0 if a null terminated
                    string is passed to the routine (R)*/
int nrows;       /* Number of rows of objects in the table (R)*/
int ncols;       /* Number of columns of objects in the table (R)*/
char * names;    /* Single object names - this may either an array of 
                    pointers to num_items null terminated character strings 
                    (len_name=0) or a character string num_items*len_name
                    in length with each name occupying len_name characters 
                    (left justified and padded to the right with blanks 
                    if needed) Can pass blank name string or null string 
                    for an absent item (R)*/
int name_len;    /* Item name length (0 = array of pointers to 
                    null-terminated character strings (e.g. for 'C' 
                    programs) or the length of each name string 
                    (e.g. for Fortran programs). See also the previous 
                    item (R) */
int order;       /* Order of items in the names list =1 column fastest,
                    =2 row fastest (R) */
int w;           /* Mimimum width required for the table (may be 0) (R)*/
int h;           /* Minimum height required for the table (may be 0) (R)*/
 
 
Return:  Status = 0 OK, >0 error
                        =1 name already used
                        =2 list of tables full
                        =3 single not defined
                        =4 single already used
 
 
5.2.5 Give details of layout pair - xdl_layout_set_pair
 
The routine xdl_layout_set_pair (xdlf_layout_set_pair) is used to  go  give
details of a layout pair. The full layout is made  by  combining  pairs  in
succession. Each pair in the layout may be either horizontal  or  vertical.
Each of the two children of a pair may be another pair, a single object  or
a table of single objects.
 
Fortran call:
 
         CALL XDLF_LAYOUT_SET_PAIR (IHORV, JUST, XDLSTR(NAME), LEN,
        +                          XDLSTR(NAME_CH1), LEN1, 
        +                          XDLSTR(NAME_CH2), LEN2,
        +                          IWIDTH, IHEIGHT, ISEP, IPCNT, IERR)
 
 
Parameters:
 
IHORV    (R)  =0 horizontal pair, =1 vertical pair
JUST     (R)  Layout/justification code for the two children
               = 1 Expand both children
               = 2 Fix left (top), expand right (bottom)
               = 3 Expand left (top), fix right (bottom)
               = 4 Left/left (top/top) justify 
               = 5 Left/right (top/bottom) justify
               = 6 Right/right) (bottom/bottom) justify
NAME     (R)  Name string used to identify the pair (max 20 chars)
              ** Pass address using XDLSTR function **
LEN      (R)  Length of the name string (>0)
NAME_CH1 (R)  Name string of the first child (previously set
              single, table or another pair)
              ** Pass address using XDLSTR function **
LEN1     (R)  Length of name for child 1 (>0)
NAME_CH2 (R)  Name string of the second child (previously set
              single, table or another pair)
              ** Pass address using XDLSTR function **
LEN2     (R)  Length of name for child 2 (>0)
IWIDTH   (R)  Minumum width required (may be 0)
IHEIGHT  (R)  Minimum height required (may be 0)
ISEP     (R)  Separation required between the halves of the pair
IPCNT    (R)  Suggested allocation of width/height between the
              two halves of the pair if both expanded.
IERR     (W)  Returns status from xdl_layout_set_pair call
 
 
'C' call:
 
int xdl_layout_set_pair (h_or_v, just, name, len, name_child1, len1,
                         name_child2, len2, w, h, sep, percent)
 
 
Parameters:
 
int h_or_v;            /* =0 horizontal pair, =1 vertical pair (R) */
int just;              /* Layout/justification code for the two children
                        = 1 Expand both children
                        = 2 Fix left (top), expand right (bottom)
                        = 3 Expand left (top), fix right (bottom)
                        = 4 Left/left (top/top) justify 
                        = 5 Left/right (top/bottom) justify
                        = 6 Right/right) (bottom/bottom) justify
                        (R) */
char *name;            /* Name used to identify the pair (max 20 chars) 
                          (R)*/
int len;               /* Length of name; may be 0 if 'name' is a null 
                          terminated string (R) */
char *name_child1;     /* Name of first (previously defined) child (R)*/
int len1;              /* Length of this name; may be 0 if name_child1
                          is a null terminated string (R)*/
char *name_child2;     /* Name of second (previously defined) child (R)*/
int len2;              /* Length of this name; may be 0 if name_child2
                          is a null terminated string (R)*/
int w;                 /* Minimum width required (may be 0) (R)*/
int h;                 /* Minimum height required (may be 0) (R)*/
int sep;               /* Separation required between the halves of the
                          pair (R)*/
int percent;           /* Suggested allocation of width/height between the
                          two halves of the pair if both expanded (R)*/
 
 
Return:  Status = 0 OK, >0 error
                        =1 name already used
                        =2 list of pairs full
                        =3 child 1 not yet defined
                        =4 child 1 already used
                        =5 child 2 not yet defined
                        =6 child 2 already used
 
 
5.2.6 Determine the layout - xdl_layout
 
The routine xdl_layout (xdlf_layout) is used to determine the  layout  from
the previously defined layout pairs, tables of objects and single  objects.
The position and size parameters for each individual  object  can  then  be
found using the routine xdl_layout_get_position (xdlf_layout_get_position)
 
Fortran call:
 
         CALL XDLF_LAYOUT (XDLSTR(NAME), LEN, IX, IY, IWIDTH, IHEIGHT,
        +                  IERR)
 
 
Parameters:
 
NAME     (R)  Name string used to identify the top level
              pair  for the layout (max 20 chars)
              ** Pass address using XDLSTR function **
LEN      (R)  Length of the name string (>0)
IX       (R)  Required x coordinate for the top left of the layout 
IY       (R)  Required y coordinate for the top left of the layout 
IWIDTH   (W)  Returns the calculated width of the layout 
IHEIGHT  (W)  Returns the calculated height of the layout 
IERR     (W)  Returns status from xdl_layout call
 
 
'C' call:
 
int xdl_layout (name, len, x, y, w, h)
 
 
Parameters:
 
char *name;       /* Name of the top level pair for the layout (R)*/
int len;          /* Length of the name (may be 0 if the name string is
                     null terminated) (R)*/
int x;            /* Required x coordinate for the top left of the layout 
                     (R)*/
int y;            /* Required y coordinate for the top left of the layout 
                     (R)*/
int *w;           /* Returns the calculated width of the layout (W)*/
int *h;           /* Returns the calculated height of the layout (W)*/

 
 
Return:  Status = 0 OK, >0 error
                        =1 top level pair not found
 
 
5.2.7 Get object position and size - xdl_layout_get_position
 
The routine xdl_layout_get_position (xdlf_layout_get_position) is  used  to
get the position and size for  each  individual  single  object  after  the
layout has been determined using the xdl_layout (xdlf_layout) routine.
 
Fortran call:
 
         CALL XDLF_LAYOUT_GET_POSITION (XDLSTR(NAME), LEN, IX, IY,
                                       IWIDTH, IHEIGHT, IERR)
 
 
Parameters:
 
NAME     (R)  Name of the single object
              ** Pass address using XDLSTR function **
LEN      (R)  Length of the name string (>0)
IX       (W)  Returns the x coordinate for the top left of the 
              single object
IY       (W)  Returns the y coordinate for the top left of the 
              single object
IWIDTH   (W)  Returns the calculated width of the single object
IHEIGHT  (W)  Returns the calculated height of the single object
IERR     (W)  Returns status from xdl_layout_get_position call
 
 
'C' call:
 
int xdl_layout_get_position (name, len, x, y, w, h)
 
 
Parameters:
 
char *name;     /* The name of the single object (R)*/
int len;        /* The length of the string (may be 0 if a null terminated
                   string was given) (R)*/
int *x;         /* Returns the x coordinate for the top left of the 
                   single object (W) */
int *y;         /* Returns the y coordinate for the top left of the 
                   single object (W) */
int *w;         /* Returns the calculated width of the single object (W)*/
int *h;         /* Returns the calculated height of the single object (W)*/

 
 
Return:  Status = 0 OK, >0 error
                        =1 object not found (or not a single object)
 
 
5.2.8 Reset objects in table - xdl_layout_reset_table
 
The routine xdl_layout_reset_table  (xdlf_layout_reset_table)  is  used  to
reset the positions of the objects within a table after the  required  size
and position of the table have been determined. It will normally be  called
internally via the xdl_layout (xdlf_layout) routine but is  made  available
for user access if required just to layout a table.
 
Fortran call:
 
         CALL XDLF_LAYOUT_RESET_TABLE (XDLSTR(NAME), LEN, IX, IY,
                                      IWIDTH, IHEIGHT, IERR)
 
 
Parameters:
 
NAME     (R)  Name of the table
              ** Pass address using XDLSTR function **
LEN      (R)  Length of the name string (>0)
IX       (R)  Required x coordinate for the top left of the table
IY       (R)  Required y coordinate for the top left of the table
IWIDTH   (R)  Required width of the table 
              (>= min width required)
IHEIGHT  (R)  Required height of the table 
              (>= min height required)
IERR     (W)  Returns status from xdl_layout_reset_table call
 
 
'C' call:
 
int xdl_layout_reset_table (name, len, x, y, w, h)
 
 
Parameters:
 
char *name;       /* Name of the table (R)*/
int len;          /* Length of the name (may be 0 if the name string is
                     null terminated (R)*/
int x;            /* Required x position for the top left of the table (R)*/
int y;            /* Required y position for the top left of the table (R)*/
int w;            /* Required width of the table (must be >= minimum width 
                     needed) (R) */
int h;            /* Required height of the table (must be >= minimum 
                     height needed) (R) */
 
 
Return:  Status = 0 OK, >0 error
                        =1 name not found or not a table
 
 
5.2.9 Reset single object position - xdl_layout_reset_single
 
The routine xdl_layout_reset_single (xdlf_layout_reset_single) is  used  to
reset the position of a single object after the required size and  position
of the object have been determined. It will normally be  called  internally
via the xdl_layout (xdlf_layout) routine but is  made  available  for  user
access if required just to reset the position of a single object.
 
Fortran call:
 
         CALL XDLF_LAYOUT_RESET_SINGLE (XDLSTR(NAME), LEN, IX, IY,
                                      IWIDTH, IHEIGHT, IERR)
 
 
Parameters:
 
NAME     (R)  Name of the single object
              ** Pass address using XDLSTR function **
LEN      (R)  Length of the name string (>0)
IX       (R)  Required x coordinate for the top left of the object
IY       (R)  Required y coordinate for the top left of the object
IWIDTH   (R)  Required width of the object 
              (>= min width required)
IHEIGHT  (R)  Required height of the object 
              (>= min height required)
IERR     (W)  Returns status from xdl_layout_reset_single call
 
 
'C' call:
 
int xdl_layout_reset_single (name, len, x, y, w, h)
 
 
Parameters:
 
char *name;       /* Name of the single object (R)*/
int len;          /* Length of the name (may be 0 if the name string is
                     null terminated (R)*/
int x;            /* Required x position for the top left of the object (R)*/
int y;            /* Required y position for the top left of the object (R)*/
int w;            /* Required width of the object (must be >= minimum width 
                     needed) (R) */
int h;            /* Required height of the object (must be >= minimum 
                     height needed) (R) */
 
 
Return:  Status = 0 OK, >0 error
                        =1 name not found or not a single object
 
 
