Overview
The iomenu utility facilitates creation of graphical user interfaces for
command-line applications. A computer program that uses the iomenu utility
has the following structure:
- Fill in a structure describing the command-line parameters.
- Call iomenu(). iomenu() creates the user interface and waits for user
interaction. Parts of the user interface are created automatically
by iomenu(). Others are created by callback routines you provide.
The controls created by iomenu() are handled internally by iomenu()
though there are two hooks for calling your own code: one for handling
when the application exits and the other for handling changes to the
file parameters or the region selected.
BatchRegion.html describes for the end user
what the controls automatically generated by iomenu() are. To summarize,
the basic pattern of user interaction is:
- The user selects the primary input file. This has the side effect of
changing the region selected to cover the full size of the input and
to change the names of the output files.
- The user edits the other parameters. Except for the file parameters,
these interactions will be directly handled by your code.
- The user requests that the current parameters be written out as a
script which the option of running that script immediately either on
the local machine or through some sort of queueing system.
The iomenu utility has both C/C++ and Fortran interfaces. For details on
how to use the C/C++ interface, consult the
C Details section; for details on how to use the
Fortran interface, consult the Fortran Details
section.
Topics
Overview |
C details |
Fortran details |
Release notes
Related Priism Topics
User documentation for iomenu() interfaces |
Priism
Example
The file, sample_iomenu_c.c,
in the EXAMPLE directory of the Priism distribution demonstrates how to
use the iomenu utility from C. The Makefile
in the same directory includes a rule to build an executable from
sample_iomenu_c.c.
Initializing the command-line parameter structure
The command line generated by the iomenu utility has the form
application_name file1 ... filen \
switch1_labelswitch1_values ... \
switchn_labelswitchn_values
file1 through filen are the required input
and output files for the application. Each switch consists of a label
(customarily -name if the switch has no values or
-name= if it has values) which may
(depending on the type of switch) be followed by a colon separated list
of values.
The contents of the command line are controlled by the entries in the
Iomenu structure passed, via a pointer, to iomenu(). The Iomenu structure is
defined in iomenu.h as
typedef struct Iomenu {
IomenuFile* files;
IomenuParameter* parameters;
void* closure;
int file_count;
int parameter_count;
char xyztw_size[4 + IW_MAX_WAVE][16];
int iparm, nxyztw[5], ixyztw[4 + IW_MAX_WAVE][3], mode;
float dmin, dmax, dmean, delxyz[3];
} Iomenu;
The elements of the structure that you need to initialize before calling
iomenu() are:
- files
- Points to the first element of an array of IomenuFile structures. You
set the length of the array by the file_count field. The array defines
the required file arguments for the command-line application (i.e.
file1 through filen). An IomenuFile structure
contains four fields: filename, filter, label, and type. You must
initialize the type field to one of the following values:
- IOMENU_PRIMARY_IMAGE
- The file will be treated as a primary input file. Before generating
a script via the "Do It" button, the iomenu utility requires that the
user specify the names of all primary input files and that those files
must exist. When the user changes the name of a primary input file
from the user interface, the iomenu utility resets the processing
region to cover the entire range of the input and updates the
corresponding controls in the graphical user interface. It resets
the names of all the files of type IOMENU_OUTPUT_DEFAULT so that they
have the same name as the primary input followed by an extension
specified by the filter field for the IOMENU_OUTPUT_DEFAULT file. The
Because of those side effects, the typical case is to have exactly one
primary input file (customarily the first one in the list). More than
one is possible, but may lead to confusion on the part of user.
Having zero primary input files is also possible, but the user
interface is biased toward selecting a region from an existing file
rather than specifying from scratch the bounds for a new file. In
addition, there is no direct way to specify the default values for the
size if you do not have a primary input file: as a crude hack, you
could initialize the nxyztw, ixyztw, and xyztw_size fields of the
Iomenu structure (see the description of the handle_file_proc callback
for details about those fields) from within the menu_proc or
special_menu_proc callbacks and then use WMUpdateGroup(1) to update
the corresponding interface controls.
- IOMENU_OTHER_INPUT
- The file will be treated as a required input file (but not a
primary input file which the iomenu utility uses to set the default
region for processing and the default names for output files). Before
generating a script via the "Do It" button, the iomenu utility
requires that the user specify the names of all required input files
and that those files must exist.
- IOMENU_OUTPUT_DEFAULT
- The file will be treated as a required output file whose default name
is the name of the primary input file with the contents of the
filter field for the output file appended. Before generating a script
via the "Do It" button, the iomenu requires that all required output
files have some sort of name specified.
- IOMENU_OTHER_OUTPUT
- The file will be treated as a required output file; the iomenu
utility does not automatically generate a default name for the file
when a new primary input file is selected. Before generating a script
via the "Do It" button, the iomenu requires that all required output
files have some sort of name specified.
The iomenu utility uses the label field in the user interface controls for
the file. Each file has a button and a text field, and the contents of
the label field are displayed as the label for the button. Initialize the
label field with a null-terminated string that contains short name which
indicates the the nature of the file to be selected. If the type field is
IOMENU_PRIMARY_IMAGE or IOMENU_OTHER_INPUT, the iomenu utility uses the
contents of the filter field as the selection pattern argument to
WMAddGetFile, and you should initialize
the filter field accordingly. If the type field is IOMENU_OUTPUT_DEFAULT,
the iomenu utility appends the contents of the filter field to the
name of the primary input file to form the default name of the file. If
the type field is IOMENU_OTHER_OUTPUT, the iomenu utility ignores the
filter field. The filename field holds the name of the file. You would
normally initialize the filename field to an empty string except for
IOMENU_OTHER_INPUT or IOMENU_OTHER_OUTPUT files for which you have
a reasonable default.
- parameters
- Points to the first element of an array IomenuParameter structures. You
set the length of the array by the parameter_count field. The array
defines the command-line switches. An IomenuParameter structure contains
three fields: label, v, and type. You must initialize the type field to
one of the following values:
- IOMENU_INTEGER
- When the iomenu utility writes out the switch on the command line,
it prints the switch as the contents of the label field followed by a
colon-separated list of integers. The v.i.count field holds the number
of integers, and the v.i.values field points to the first element of
the array holding the values for the integers.
- IOMENU_REAL
- When the iomenu utility writes out the switch on the command line,
it prints the switch as the contents of the label field followed by a
colon-separated list of floating-point values. The v.r.count field
holds the number of floating-point values, and the v.r.values field
points to the first element of the array holding the values for the
floating-point numbers.
- IOMENU_ACTIVE_WHEN_NONZERO
- When the iomenu utility writes out the switch on the command line, it
prints out the contents of the label field if *(v.pb) is not zero;
otherwise, it does not print out anything for the switch.
- IOMENU_ACTIVE_WHEN_ZERO
- When the iomenu utility writes out the switch on the command line, it
prints out the contents of the label field if *(v.pb) is zero;
otherwise, it does not print out anything for the switch.
- IOMENU_STRING
- When the iomenu utility write out the switch on the command line, it
prints out the contents of the label field followed by a colon-
separated list of character strings. Each element in the list is
surrounded by double quotes. The v.c.count field holds the number of
elements in the list. The v.c.values field is the array of
null-terminated character strings holding the values.
The v field is a union. The elements and their meanings are described
above for the different type codes; initialize v accordingly. The iomenu
utility prints out the contents of the label field when printing the
command-line switch. By convention, labels for IOMENU_INTEGER,
IOMENU_REAL, and IOMENU_STRING switches have the form
-name=. By convention, labels for the
IOMENU_ACTIVE_WHEN_NONZERO and IOMENU_ACTIVE_WHEN_ZERO switches have the
form -name.
- closure
- The closure field is not used internally by the iomenu utility but you
can use it to pass along additional information to the callback routines.
- file_count
- Is the number of elements in the array whose first element is pointed to
by the files field.
- parameter_count
- Is the number of elements in the array whose first element is pointed to
by the parameters field.
Calling iomenu()
The iomenu() function is declared in iomenu.h as
void iomenu(
const char* title,
const char* submenu_title,
const char* app_name,
Iomenu* iom,
void (*menu_proc)(Iomenu*),
void (*special_menu_proc)(Iomenu*),
void (*handle_file_proc)(Iomenu*),
void (*handle_exit_proc)(Iomenu*)
);
The arguments are:
- title
- title is the name that will appear on the title bar of the
main dialog.
- submenu
- The iomenu utility can display a button in the main dialog that will
open a child dialog. The most common use for this is to group rarely
changed parameters in this child dialog. submenu is the
name that will appear on the button in the main dialog to open the
child dialog. If submenu is zero or points to an empty string,
the button to open the child dialog will not be created.
- app_name
- app_name is the name of the command-line application to run.
If app_name does not begin with / and the environment variable
IVE_ENV_SETUP is not set, the iomenu utility will prepend
app_name with the name of the Priism executable directory when
writing the script file. app_name is also used as the base
for the default names of the script and log files as well as the base for
the name used when saving or restoring the current contents of the dialog
via the Save and Restore buttons.
- iom
- Points to the Iomenu structure (defined in iomenu.h) describing the
command line parameters.
- menu_proc
- Is the routine the iomenu utility will call to add application-specific
controls to the main dialog. See the
Callbacks section below for more details.
menu_proc may be zero and is ignored in that case.
- special_menu_proc
- If submenu is not zero and does not point to an empty string,
special_menu_proc is the routine the iomenu utility will call
to add application-specific controls to the child dialog. See the
Callbacks section below for more details. If
submenu is zero or points to an empty string,
special_menu_proc is ignored. special_menu_proc may
be zero and is ignored in that case.
- handle_file_proc
- Is the routine the iomenu utility will call when the user changes the
name of one of the required files or changes the bounds of the region to
process. See the Callbacks section below
for more details. handle_file_proc may be zero and is ignored
in that case.
- handle_exit_proc
- Is the routine the iomenu utility will call when the user exits the
application via the button labeled "Exit" in the main dialog or via the
window manager. See the Callbacks section
below for more details. handle_exit_proc may be zero and is
ignored in that case.
For the C/C++ interface to the iomenu utility, you set the callbacks via
the last four arguments to iomenu().
If the menu_proc argument to iomenu() is not zero, the iomenu
utility calls the function pointed to by menu_proc after it has
initialized the WM library (with WMInit), and
added the controls for the required files and the region bounds to the main
dialog. After calling the function pointed to by menu_proc, the
iomenu utility will complete the main dialog by adding an optional button to
open a child dialog (see the description of the submenu_title
argument to iomenu() for more information) and a series of buttons, labeled
"Exit", "Save", "Restore", "Options, and "Do It", at the bottom of the dialog.
The iomenu utility passes personal() a single argument, the pointer to an
Iomenu structure that you passed to iomenu(). Normally, you would use
the menu_proc callback to add the graphical user interface
components to the main dialog that are necessary to control the command-line
switches you defined in the Iomenu structure.
If the special_menu_proc argument to iomenu() is not zero and
the submenu_title argument to iomenu() is not zero and does not
point to an empty string, the iomenu utility calls the function pointed to by
special_menu_proc after it has created the main dialog and
initialized an empty child dialog. After calling the function pointed to by
special_menu_proc, the iomenu utility will add a button, labeled,
"OK", for closing the child dialog; the iomenu utility will then enter
the loop to process user interactions. The iomenu utility passes the function
pointed to by special_menu_proc a single argument, the pointer to
an Iomenu structure that you passed to iomenu(). Normally, you would use the
special_menu_proc callback to add the graphical user interface
components that you did not put in the main dialog.
If the handle_file_proc argument to iomenu() is not zero, the
iomenu_utility calls the function pointed to by handle_file_proc
when the user changes the name of one of the required files or changes the
bounds of the region to process. The iomenu utility passes the function
pointed to by handle_file_proc a single argument, the pointer to
an Iomenu structure that you passed to iomenu(). Before calling the function
pointed to by handle_file_proc, the iomenu utility changes the
value of the iparm field in the Iomenu structure. If the function pointed to
by handle_file_proc is to be called because the user changed one
of the names of the required files, the iomenu_utility sets iparm to one plus
the index of that file in the files array of the Iomenu structure. If the file
changed was a primary input file, the iomenu utility will also read the header
of that field and reset the following fields of the Iomenu structure:
- ixyztw
- ixyztw holds the bounds of the region to process. ixyztw[0][0] is the
first x pixel, and ixyztw[0][1] is the last x pixel. After changing a
primary input file, ixyztw[0][0] will be zero and ixyztw[0][1] will be the
size of the x dimension in pixels minus one. ixyztw[1][0] is the
first y pixel, and ixyztw[1][1] is the last y pixel. After changing a
primary input file, ixyztw[1][0] will be zero and ixyztw[1,1] will be the
size of the y dimension in pixels minus one. ixyztw[2][0] is the
first z section, and ixyztw[2][1] is the last z section. After changing a
primary input file, ixyztw[2][0] will be zero and ixyztw[2][1] will be the
number of z sections minus one. ixyztw[3][0] is the first time point,
ixyztw[3][1] is the last time point, and ixyztw[3][2] is the time point
increment. After changing a primary input file, ixyztw[3][0] will be
zero, ixyztw[3][1] will be the number of time points minus one, and
ixyztw[3][2] will be one. ixyztw[j][0] where j is
greater than three is the wavelength for the (j-3)rd channel.
ixyztw[j][1] where j is greater than three is zero if
the (j-3)rd channel has been selected for processing and
is otherwise non-zero. After changing a primary input file, the
wavelengths will match the values in the header (to the nearest integer)
and all wavelengths will be selected for processing (in the current
implementation an exception is made for cases where the wavelength is
less than or equal to 100 or greater than or equal to 999; in that case
ixyztw[j][0] and ixyztw[j][1] are set to zero).
- nxyztw
- Holds the dimensions of the file. nxyztw[0] is the number of x pixels
minus one. nxyztw[1] is the number of y pixels minus one. nxyztw[2] is
the number of z sections minus one. nxyztw[3] is the number of time points
minus one. nxyztw[4] is the number of wavelengths.
- xyztw_size
- Holds printable versions of the full range of the file and the
wavelengths. xyztw_size[0] is the x range printed as 0:n where
n is the number of x pixels minus one. xyztw_size[1] is the y
range printed as 0:n where n is the number of y
pixels minus one. xyztw_size[2] is the z range printed as 0:n
where n is the number of z sections minus one. xyztw_size[3]
is the time range printed as 0:n where n is the number of time
points minus one. xyztw_size[j] where j is greater
than three is the printed version of the wavelength for the
(j-3)rd wavelength (if the wavelength is less than or equal to
100 and greater than or equal to 999, the current implementation sets
xyztw_size[j] to " ").
- mode
- Holds the pixel type of the
file.
- dmin, dmax, and dmean
- Holds the minimum, maximum, and mean value, respectively, recorded for
the first wavelength in the file's header.
- delxyz
- Holds the pixel spacing recorded in the file's header.
If the function pointed to by handle_file_proc is to be called
because the user changed the bounds of the region, iparm will be negative one
if the x range changed, negative two if the y range changed, negative three if
the z range changed, negative four if the time range changed, or negative five
if the wavelengths selected changed. The ixyztw field of the Iomenu structure
(see above for details) will hold the current region bounds.
If the handle_exit_proc argument to iomenu() is not zero,
The iomenu utility calls the function pointed to by handle_exit_proc
when the user presses the button labeled "Exit" in the main dialog or when the
user force the application to exit via the window manager. The iomenu utility
passes the function pointed to by handle_exit_proc a single
argument, the pointer to an Iomenu structure that you passed to iomenu().
Compiling and linking
For compilation, iomenu.h is located in the INCLUDE directory of the
Priism distribution. For linking, you will need to link against the
library, libiomenu.a, in addition to the WM library and IM or IWL libraries.
All those libraries are in the LIB directory of the Priism distribution, and
the linker options you could use to link against them are:
-Lpriism_dir/LIB -liomenu -lWM -lIWL
where you would have to replace priism_dir with the path to
where Priism is installed.
Topics
Overview |
C details |
Fortran details |
Release notes
Example
The file, sample_iomenu_f.f,
in the EXAMPLE directory of the Priism distribution demonstrates how to
use the iomenu utility from Fortran. The
Makefile in the same directory includes a
rule to build an executable from sample_iomenu_f.f.
Initializing the command-line parameter structure
The command line generated by the iomenu utility has the form
application_name file1 ... filen \
switch1_labelswitch1_values ... \
switchn_labelswitchn_values
file1 through filen are the required input
and output files for the application. Each switch consists of a label
(customarily -name if the switch has no values or
-name= if it has values) which may
(depending on the type of switch) be followed by a colon separated list
of values. The Fortran iomenu interface can handle a maximum of 10 required
files and 19 switches.
The contents of the command line are controlled by the entries in the
iomenu_struct structure passed to iomenu(). The iomenu_struct structure is
defined in iomenu.inc as
structure /iomenu_struct/
integer*4 itypes(2,20), ivals(40), ifiletype(11), iuser(20)
real*4 rvals(20), ruser(20)
character*80 cvals(10)
character*80 labels(20), filelabels(10)
character*80 filenames(10)
character*80 filefilter(10)
character*10 xyztw_size(9)
integer*4 iparm, nxyztw(5), ixyztw(3, 9), mode
real*4 dmin, dmax, dmean, delxyz(3)
end structure
The elements of the structure that you need to initialize before calling
iomenu() are:
- ifiletype
- Sets the number and type (input or output) of the required
files. ifiletype(i) sets the type of the ith file
and must be one of the following values:
- 0
- Marks the end of the list, i.e. if ifiletype(i) is
zero and no earlier element of ifiletype is zero, then there will
be i minus one files printed at the start of the command
line.
- 1
- Specifies that the file is a primary input file. Before
generating a script via the "Do It" button, the iomenu utility requires
that the user specify the names of all primary input files and that
those files must exist. When the user changes the name of a primary
input file from the user interface, the iomenu utility resets the
processing region to cover the entire range of the input and updates
the corresponding controls in the graphical user interface. It resets
the names of all the output files of type 3 so that they have the
same name as the primary input followed by an extension specified by
the element of the filefilter field for that output file. Because of
those side effects, the typical case is to have exactly one primary
input file (customarily the first one in the list). More than one is
possible, but may lead to confusion on the part of user. Having zero
primary input files is also possible, but the user interface is biased
toward selecting a region from an existing file rather than specifying
from scratch the bounds for a new file. In addition, there is no
direct way to specify the default values for the size if you do not
have a primary input file: as a crude hack, you could initialize the
nxyztw, ixyztw, and xyztw_size fields (see the description of the
custom_ifile() callback for details about those fields) from within
the personal() or special_parameters() callbacks and then use
WMUpdateGroup(1) to update the corresponding interface controls.
- 2
- Specifies that the file is a required input file (but not
a primary input file which the iomenu utility uses to set the default
region for processing and the default names for output files). Before
generating a script via the "Do It" button, the iomenu utility
requires that the user specify the names of all required input files
and that those files must exist.
- 3
- Specifies that the file is an output file. When
ifiletype(i) is three, the default name for that output
file will be the name of the primary input file with the contents of
filefilter(i) appended. Before generating a script via the
"Do It" button, the iomenu utility requires that all the files of type
three have some sort of name specified.
- 4
- Specifies that the file is an output file but, unlike files of
type three, the iomenu utility does not automatically generate a
default name when the user selects a primary input file. Before
generating a script via the "Do It" button, the iomenu utility requires
the all the files of type four have some sort of name specified.
- filenames
- filenames(i) holds the name of the ith
required file. You would normally initialize the names for the files you
use to be all spaces (or use an appropriate compiler switch to do so for
you) except for input files of type two and output files of type three
for which you have a reasonable default.
- filelabels
- In the user interface, each required file has a
corresponding button and text field; these controls appear at the top of
the main dialog. filelabels(i) sets the label on the button for
the i button. You should initialize the labels for the files
you use to some short names indicating the nature of the file to be
selected.
- filefilter
- If ifiletype(i) is one or two,
filefilter(i) is used as the selection pattern argument
to WMAddGetFile and should be
initialized accordingly. If ifiletype(i) is three,
filefilter(i) is appended to the name of the primary input file
to form the default name for the ith file. If
ifiletype(i) is four, the value of filefilter(i) is
ignored.
- itypes
- Defines the type and number of values associated with each
command-line switch. itypes(1,i) sets the number of parameters
associated with the switch; the first value j where
itypes(1,j) is less than zero terminates the list of switches
(i.e. there will be j minus one switches printed on the
command line). itypes(2,i) is the type of the switch
and must be one of the following:
- 1
- The switch has itypes(1,i) integer
values (the next itypes(1,i) values from the ivals field)
associated with it. When the switch is printed out for the command
line, the integers are printed out in a colon-separated list
immediately after the switch label.
- 2
- The switch has itypes(1,i)
floating-point values (the next itypes(1,i) values from
the rvals field) associated with it. When the switch is printed out
for the command line, the floating-point values are printed out in a
colon-separated list immediately after the switch label. In the
current implementation, values whose absolute value is greater than one
are printed out to at most two decimal places of accuracy; values
whose absolute value is less than one are printed out to approximately
three significant digits.
- 3
- The switch has one integer (the next element
from the ivals field) associated with it. If that value is not zero
when the command line is printed, then labels(i) will be
printed on the command line (without any values following it); if that
value is zero when the command line is printed, then
labels(i) will not be printed.
- -3
- The switch has one integer (the next element
from the ivals field) associated with it. If that value is zero
when the command line is printed, then labels(i) will
be printed on the command line (without any values following it);
if that value is not zero when the command line is printed, then
labels(i) will not be printed.
- 4
- The switch has itypes(1,i)
character arrays (the next itypes(1,i) elements from the
cvals field) associated with it. When the switch is printed out for
the command line, the contents of those character arrays (for each
array the trailing spaces and null characters are trimmed and the
result is then enclosed in double quotes) will be printed out as
a colon-separated list immediately after the switch label.
- labels
- labels(i) specifies the switch name printed on the command
line for the ith switch. If itypes(2,i) is one,
two, or four, the switch name, by convention, would have the form
-name=. If itypes(2,i)
is three or negative three, a conventional switch name would have the
form -name.
- ivals
- Holds the values associated with switches of types one, three, and
negative three. Because ivals has forty elements, you are limited to
at most forty integer values for the command line.
- rvals
- Holds the values associated with switches of type two. Because rvals has
twenty elements, you are limited to at most twenty floating-point values
for the command line.
- cvals
- Holds the values associated with switches of type three. Because cvals
has ten elements, you are limited to at most ten character array values
for the command line.
- ixyztw
- Unless you compile your application so that the structure values are
initialized to zero, set ixyztw(1,i) and ixyztw(2,i)
to zero for values of i from one to nine. For more details
about the ixyztw field, see the description of the custom_ifile callback.
- nxyztw
- Unless you compile your application so that the structure values are
initialized to zero, set nxyztw(i) to zero for values of
i from one to five. For more details about the nxyztw field,
see the description of the custom_ifile callback.
Calling iomenu()
The iomenu() subroutine is declared as
subroutine iomenu(title, submenu, iroot, iom)
character title*(*), submenu*(*), iroot*(*)
record /iomenu_struct/ iom
The arguments are:
- title
- title is the name that will appear on the title bar of the
main dialog.
- submenu
- The iomenu utility can display a button in the main dialog that will
open a child dialog. The most common use for this is to group rarely
changed parameters in this child dialog. submenu is the
name that will appear on the button in the main dialog to open the
child dialog. If submenu is a character array which only
contains spaces or null characters or %LOC(submenu) is equal to
zero, the button to open the child dialog will not be created.
- iroot
- iroot is the name of the command-line application to run.
If iroot does not begin with / and the environment variable
IVE_ENV_SETUP is not set, the iomenu utility will prepend iroot
with the name of the Priism executable directory when running the
script file. iroot is also used as the base for the default
names of the script and log files as well as the base for the name used
when saving or restoring the current contents of the dialog via the Save
and Restore buttons.
- iom
- Is a instance of the iomenu_struct structure (defined in iomenu.inc)
which defines the command-line parameters.
Callbacks
The Fortran interface to the iomenu utility expects you to define four
other subroutines: personal(), special_parameters(), custom_ifile(), and
call_exit().
The iomenu utility calls personal() after it has initialized the WM library
(with WMInit), and added the controls for the
required files and the region bounds to the main dialog. After calling
personal(), the iomenu utility will complete the main dialog by adding an
optional button to open a child dialog (see the description of the
submenu argument to iomenu() for more information) and a series of
buttons, labeled "Exit", "Save", "Restore", "Options, and "Do It", at the
bottom of the dialog. The iomenu utility passes personal() a single argument,
the instance of the iomenu_struct structure that you passed to iomenu(). If
you need to pass additional information to the personal() subroutine you can
use the iuser and and ruser elements of the iomenu_struct structure or use
common blocks. Normally, you would use personal() to add the graphical user
interface components to the main dialog that are necessary to control the
command-line switches you defined in the iomenu_struct structure.
special_parameters() is only called if the submenu argument
to iomenu() was a character array that did not contain only spaces or null
characters. The iomenu utility calls special_parameters() after if has created
the main dialog and initialized an empty child dialog. After calling
special_parameters(), the iomenu utility will add a button, labeled
"OK", for closing the child dialog; the iomenu utility will then enter
the loop to process user interactions. The iomenu utility passes
special_parameters() a single argument, the instance of the iomenu_struct
structure that you passed to iomenu(). If you need to pass additional
information to the special_parameters() subroutine you can use the iuser and
and ruser elements of the iomenu_struct structure or use common blocks.
Normally, you would use special_parameters() to add the graphical user
interface components that you did not put in the main dialog.
The iomenu utility calls custom_ifile() when the user changes the name of
one of the required files or changes the bounds of the region to process.
The iomenu utility passes custom_ifile() a single argument, the instance
of the iomenu_struct structure that you passed to iomenu(). If you need to
pass additional information to the custom_ifile() subroutine you can use the
iuser and and ruser elements of the iomenu_struct structure or use common
blocks. Before calling custom_ifile(), the iomenu utility changes the value
of the iparm field in the iomenu_struct structure. If custom_ifile() is to be
called because the user changed one of the names of the required files, the
iomenu utility sets iparm to the index of that file in the ifiletype and
filenames array. If the file changed was a primary input file, the iomenu
utility will also read the header of that file and reset the following fields
of the iomenu_struct structure:
- ixyztw
- ixyztw holds the bounds of the region to process. ixyztw(1,1) is the
first x pixel, and ixyztw(2,1) is the last x pixel. After changing a
primary input file, ixyztw(1,1) will be zero and ixyztw(2,1) will be the
size of the x dimension in pixels minus one. ixyztw(1,2) is the
first y pixel, and ixyztw(2,2) is the last y pixel. After changing a
primary input file, ixyztw(1,2) will be zero and ixyztw(2,2) will be the
size of the y dimension in pixels minus one. ixyztw(1,3) is the
first z section, and ixyztw(2,3) is the last z section. After changing a
primary input file, ixyztw(1,3) will be zero and ixyztw(2,3) will be the
number of z sections minus one. ixyztw(1,4) is the first time point,
ixyztw(2,4) is the last time point, and ixyztw(3,4) is the time point
increment. After changing a primary input file, ixyztw(1,4) will be
zero, ixyztw(2,4) will be the number of time points minus one, and
ixyztw(3,4) will be one. ixyztw(1,j) where j is
greater than four is the wavelength for the (j-4)th channel.
ixyztw(2,j) where j is greater than four is zero if
the (j-4)th channel has been selected for processing and
is otherwise non-zero. After changing a primary input file, the
wavelengths will match the values in the header (to the nearest integer)
and all wavelengths will be selected for processing (in the current
implementation an exception is made for cases where the wavelength is
less than or equal to 100 or greater than or equal to 999; in that case
ixyztw(1,j) and ixyztw(2,j) are set to zero).
- nxyztw
- Holds the dimensions of the file. nxyztw(1) is the number of x pixels
minus one. nxyztw(2) is the number of y pixels minus one. nxyztw(3) is
the number of z sections minus one. nxyztw(4) is the number of time points
minus one. nxyztw(5) is the number of wavelengths.
- xyztw_size
- Holds printable versions of the full range of the file and the
wavelengths. xyztw_size(1) is the x range printed as 0:n where
n is the number of x pixels minus one. xyztw_size(2) is the y
range printed as 0:n where n is the number of y
pixels minus one. xyztw_size(3) is the z range printed as 0:n
where n is the number of z sections minus one. xyztw_size(4)
is the time range printed as 0:n where n is the number of time
points minus one. xyztw_size(j) where j is greater
than four is the printed version of the wavelength for the
(j-4)th wavelength (if the wavelength is less than or equal to
100 and greater than or equal to 999, the current implementation sets
xyztw_size(j) to "___").
- mode
- Holds the pixel type of the
file.
- dmin, dmax, and dmean
- Holds the minimum, maximum, and mean value, respectively, recorded for
the first wavelength in the file's header.
- delxyz
- Holds the pixel spacing recorded in the file's header.
If custom_ifile() is to be called because the user changed the bounds of the
region, iparm will be negative one if the x range changed, negative two if the
y range changed, negative three if the z range changed, negative four if the
time range changed, or negative five if the wavelengths selected changed.
The ixyztw field of the iomenu_struct structure (see above for details) will
hold the current region bounds.
The iomenu utility calls call_exit() when the user presses the button
labeled "Exit" in the main dialog. The iomenu utility passes call_exit() a
single argument, the instance of the iomenu_struct structure that you passed
to iomenu(). If you need to pass additional information to the call_exit()
subroutine you can use the iuser and and ruser elements of the iomenu_struct
structure or use common blocks. In the current implementation, call_exit() is
not called when the user exits the application via the window manager (you
would have to call WMSetExitFunction
from within the personal() or special_parameters() routines if you wanted to
trap that case).
Compiling and linking your application
For compilation, iomenu.inc is located in the INCLUDE directory of the
Priism distribution. For linking, you will need to link against either
iomenu.o or libiomenu.a (the latter is only present in the March 2004 release
of Priism and later releases). You will also need to link with the WM library
and the IM or IWL libraries. All those libraries or object files are in the
LIB directory of the Priism distribution, and the linker options you could use
to link against them are
priism_dir/LIB/iomenu.o -Lpriism_dir -lWM -lIWL
where you would have to replace priism_dir with the path to
where Priism is installed.
Topics
Overview |
C details |
Fortran details |
Release notes
The C interface was added in March 2004 release of IVE 3.3. Prior versions
had a different version of iomenu.h but only a Fortran subroutine interface.
Use of QUECOM environment variable, described in the
Queue section of BatchRegion.html, was
added in the August 2000 version of IVE 3.3 and has always been in the IVE 4
version. Use of the IVE_ENV_SETUP environment variable was added in the
June 1999 versions of IVE 3.3 and has always been in the IVE 4 version.
Topics
Overview |
C details |
Fortran details |
Release notes