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_thesh0 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