User Interface Functions

PCL and Customization > User Interface and List Processor Functions > User Interface Functions

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">

BUTTON Functions


ui_button_create	(parent, callback, x, y, width, height, label, [unused], highlight)

According to OSF/Motif terminology, the Patran button widget is of the XmPushButtonGadget class.

A button has only one option: it is clicked to initiate an action. No manipulation of data occurs in terms of direct input.


Description:
Create a button widget.
Input:
widget	parent	Parent widget of newly created widget. Must be a form.
STRING	callback	Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events for this widget are not of interest.
NUMERIC	x	X location of widget in inches relative to the parent.
NUMERIC	y	Y location of widget in inches relative to the parent.
NUMERIC	width	Width of widget in inches. If zero, the button will be sized automatically to fit the text.
NUMERIC	height	Height of widget in inches. If zero, the button will be sized automatically to fit the text.
STRING	label	Text that will be displayed in button.
LOGICAL	[unused]	Use TRUE.
LOGICAL	highlight	TRUE if button is highlighted as the default button. Only one button per form may be highlighted as the default.
Output:
widget	<Return Value>	Button widget ID. NULL if button not created.
Error Conditions:
None.

BUTTON Functions


ui_buttonicon_create	(parent, callback, x, y, icon)

A button icon falls into the same class and works exactly the same as the button widget. Instead of a text label on the button icon, an icon visually describes the widget’s function.


Description:
Create a button icon widget.
Input:
widget	parent	Parent widget of newly created widget. Must be a form.
STRING	callback	Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events for this widget are not of interest. The first space character in the name/callback signifies that the rest of the string value is the pop-up help for the icon, and delimits the preceding string without the space as the name/callback of the widget.
NUMERIC	x	X location of widget in inches relative to the parent.
NUMERIC	y	Y location of widget in inches relative to the parent.
STRING	icon	Name of the file containing the icon data. Use a !!PATH in your p3midilog.pcl file if this file does not appear along the standard path.
Output:
widget	<Return Value>	Button widget ID. NULL if button not created.
Error Conditions:
None.

CASCADE Item Functions


ui_cascadeitem_create	(parent, name, label)

This widget resides in the OSF/Motif defined XmCascadeButtonGadget class. Although not often used in Patran, this widget provides the ability to bring a pull-down menu from an item contained within a higher-level pull-down menu. (To operate a cascade item from the keyboard, press the space bar. The arrow keys will move focus to other items.)


Description:
Creates an item widget to be used to bring up a cascading menu.
Input:
widget	parent	ID of the parent widget. Must be a menu or popup menu.
STRING	name	Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events for this widget are not of interest.
STRING	label	Label to be displayed indicating the widgets action. Unlike for ui_item_create(), specifying the label as ““ will not create a separator, but will create a menu item whose label is ““.
Output:
widget	<Return Value>	Item widget ID. NULL_WIDGET if item not created.
Error Conditions:
None.

Comments:

This function may be used to create menu items that does not have an associated menu. However, it is recommended that ui_item_create() is used in such a case.

COLOR WIDGET Functions


ui_colormenu_create	(parent, callback, x, y, width, height, label, label_position, label_x, label_y, color, user_data)


Description:
Create a colormenu.
Input:
widget	parent	Parent widget ID. Parent widget must be a form, modal form or a frame.
STRING	callback	Name of the PCL function called when a color from the popup menu, posted from this widget, is selected.
NUMERIC	x	x location of the widget.
NUMERIC	y	y location of the widget.
NUMERIC	width	Wwidth of the widget.
NUMERIC	height	Height of the widget.
STRING	label	Widget label.
STRING	label_position	String specifying the position of the label. The label_position string must be from among the following. “Top”: Place the label at the top of the menu button. “Left”: Place the label at the left of the menu button. “Right”: Place the label at the right of the menu button. “None”: Place the label at the position specified by the label_x and label_y parameters.
NUMERIC	label_x	x location of the widget label. Used only if label_position is “None”.
NUMERIC	label_y	y location of the widget label. Used only if label_position is “None”.
INTEGER	color	Background color of the button. If 1< color < 16 the widget will be assigned the appropriate color from the Patran colors. Otherwise, the widget will show multiple colors to indicate ambiguity or nonuniqueness.
INTEGER	user_data	Data specific to this widget. This will be passed to the callback function (see below.)
Output:
widget	<Return Value>	Colormenu widget id. NULL if the widget is not created.
Error Conditions:
None.

Comments:

The PCL callback needs to be defined if the callback string passed to the creation function is not a null string. The syntax of the callback function is as follows.

FUNCTION color_cb ( wid, user_data, index )
WIDGET wid
INTEGER user_data, index

where,

wid is the widget id of the colormenu that caused this callback.
user_data is the value passed to the colormenu creation call.
index is the new color value.


ui_colorbar_create	(parent, callback, x, y, width, height, label, ncolors, user_data)


Description:
Create a colormenu.
Input:
widget	parent	Parent widget ID. Parent widget must be a form, modal form or a frame.
STRING	callback	Name of the PCL function called when a color button from this widget is selected.
NUMERIC	x	x location of the widget.
NUMERIC	y	y location of the widget.
NUMERIC	width	Width of the widget.
NUMERIC	height	Height of the widget.
STRING	label	Widget label.
INTEGER	ncolors	Numbers of color buttons in the widget. Must be between 1 and 16.
INTEGER	user_data	Data specific to this widget. This will be passed to the callback function (see below.)
Output:
widget	<Return Value>	Colorbar widget ID. NULL if the widget is not created.

Comments:

The PCL callback needs to be defined if the callback string passed to the creation function is not a null string. The syntax of the callback function is as follows.

FUNCTION color_cb( wid, user_data, index )
WIDGET wid
INTEGER user_data, index

where,
wid is the widget id of the colorbar that caused this callback.
user_data is the value passed to the colorbar creation call.
index is the number of the depressed color button when the callback is called.

The following parameters may be set using ui_wid_set call and may be obtained using ui_wid_get call.


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is to be displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.
INTEGER(2)	ITEMCOLOR	Item color of the widget. The ui_wid_set or ui_wid_get call must be passed an array of size two. The first element of the carry should contain the item number. On a call to ui_wid_set the second element of the array should contain the index of the color desired. A call to the function ui_wid_get will return the color index in the second element.
INTEGER	CURRENTITEM	Currently depressed color button of the colorbar.
INTEGER	NITEMS	Number of color buttons in the colorbar.

CURSOR Functions


ui_cursor_set	(mode, cursor)


Description:
Set the window cursor for the assigned windows.
Input:
STRING	mode	“ALL”, any window “GRAPHICS”, Graphics window ”NONGRAPHICS” , Any non-graphics window ”NONMODAL”, Non-modal window ”MODAL”, Modal window
STRING	cursor	“dotbox” - Square with dot in it. “cross” - Cross hair “left_ptr” - Hand pointing
Output:
None.
Error Conditions:
None.

Example:

gu_view_center is used to pick the view center from the View menu.

 /*$$ gu_view_center

	 * Purpose: To set a flag so that the next pick rectangle will be

			 * used for a change view center operation.

 * Input:

 * Output:

 * Log:

 * Notes:

*/

 FUNCTION gu_view_center( )

 GLOBAL INTEGER view_center

 view_center = 1

 ui_cursor_set( “graphics”, “dotbox” )

DATABOX Functions


ui_databox_create	(parent, callback, x, y, label_length, box_length, label, value, label_above, datatype, num_vals)

Databoxes are defined by OSF/Motif to be text widgets which can only accept three kinds of user input: 1) integers, 2) real numbers and 3) character strings. This input may be typed or “pasted” from another databox or an X window.

Although a databox will accept only one line of information, this line can sometimes be quite long.

Depending on the application of a databox, the type of data as well as the number of data values which can be input by the user is sometimes limited, in which case a warning bell or message will be issued.


Description:
Creates a databox widget
Input:
widget	parent	Parent widget ID. May be a form or a scroll frame.
STRING	callback	Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events for this widget are not of interest.
NUMERIC	x	X location of the databox in inches relative to the parent.
NUMERIC	y	Y location of the databox in inches relative to the parent.
NUMERIC	label_length	Used only if label_above is FALSE. Distance between the beginning of the label and the beginning of the box, in inches. If zero, the length of the label string will be used. Specifying the label_length is useful when lining up several databoxes.
NUMERIC	box_length	Length of the box in inches.
STRING	label	Displayed text describing the value associated with the databox. To have no label initially but plan on using ui_wid_set() to change the label, assign label to be “ “. If not assigning a label, use ““ and set label_above to FALSE.
DYNAMIC	value	Value displayed inside the databox. This value is of the datatype specified. If the databox is to be empty upon startup, specify ““as the initial value for all datatypes.
LOGICAL	label_above	TRUE is the label is to be displayed above of the databox, FALSE if the label is to be displayed to the left of the databox.
STRING	datatype	Type of data to accept. “INTEGER,” “REAL,” or “STRING.” All values must be of the same datatype.
INTEGER	num_vals	Upper limit of the number of values of type datatype to accept. If “STRING” is the assigned datatype, this value is ignored.
Output:
widget	<Return Value>	Widget ID. NULL if the widget could not be created.
Error Conditions:
None.

Comments:

The data is checked to be consistent with datatype and num_vals each time the contents of the databox is changed.


ui_databox_get_current	( )


Description:
Get the current databox which has focus.
Input:
None.
Output:
widget	<Return Value>
Error Conditions:
None.

EXEC Functions


ui_exec_function	( classname, functionname )


Description:
Invokes a class's function. This function should be used to properly register a class containing a ui_form_create() call by calling ui_exec_function(classname, “DISPLAY”). If the INIT function is called improperly using a classname.init() call, problems will occur when attempting to display the form. By using ui_exec_function() to initialize and display forms, problems will be avoided.
Input:
STRING	classname	Name of the class containing the function to be executed.
STRING	functionname	Name of the function to be executed.
Output:
None.
Error Conditions:
None.

Comments:

If the function name is “DISPLAY”, Patran will ensure that the class's INIT function has be executed first. As a result, it is not necessary to call ui_exec_function() twice, the first time assigning the function name as INIT, the second time assigning the function name as DISPLAY; a call to ui_exec_function(classname, “DISPLAY”) will suffice.

FILE Functions


ui_file_create	(parent_id, callback_func, x_location, y_location, width, number_rows, filter_label, filter_mask, directory_label, files_label, selection_label, file_name, ok_label, filterbutton_label, cancel_label )


Description:
This function will create a file selection form.
Input:
widget	parent_id	This value specifies a widget identifier for the parent widget of this form.
STRING	callback_func[]	This value specifies the name of the PCL function that will be called for an event representing a form event. This call back function must be a member of the class in which this widget is created.
REAL	x_location	This value specifies the x axis location of the file widget in pixels relative to the upper left corner of the parent widget.
REAL	y_location	This value specifies the y axis location of the file widget in pixels relative to the upper left corner of the parent widget.
REAL	width	This value specifies the width of the widget in pixels, excluding the border.
INTEGER	number_rows	This value specifies the number of rows that will be displayed in files and directory list boxes of the form.
STRING	filter_label[]	This value specifies the title used on the form to describe the filter databox.
STRING	filter_mask[]	This value specifies the path and filter mask that determines which files will be displayed in the file list box.
STRING	directory_label[]	This value specifies the text used on the form to describe the directory databox.
STRING	files_label[]	This value specifies the text used on the form to describe the files databox.
STRING	selection_label[]	This value specifies the text used on the form to describe the selection databox.
STRING	file_name[]	This value specifies a file name to be displayed in the selection databox. If the file name specified is listed in the file list box the file list box entry will be highlighted.
STRING	ok_label[]	This value specifies the text used to label the “OK” button.
STRING	filterbutton_label[]	This value specifies the text used to label the “Filter” button.
STRING	cancel_label[]	This value specifies the text used to label the “Cancel” button.
Output:
widget	<Return Value>	This function returns avalid form widget identifier when executed successfully and a value on WIDGET_NULL to indicate a change an error.
Error Conditions:
None.

Remarks:

The PCL callback function will be called when the “OK” or the “Cancel button” is selected. This PCL callback fuction should be designed to accept two strings as arguments and to return nothing. When the “OK” button is selected the callback function will have the complete path and name of the selected file passed as the first argument and the work “OPEN” passed as the second argument. When the “Cancel” button is selected an empty string or ““ will be passed as the first argument and the work “CANCEL” will be passed as the second argument.

The following input values can be manipulated through a call to the function ui_wid_set().


	Input Value Name	Corresponding ui_wid_set() Parameter Name

	callback_function	NAME
	x_location	X
	y_location	Y
	width	WIDTH
	number_rows	None available.
	filter_label[]	FILTERLABEL
	filter_mask[]	DIRECTORY and FILTER
	directory_label[]	None available.
	files_label[]	FILESLABEL
	selection_label[]	FILENAMELABEL
	file_name[]	FILENAME
	ok_label[]	OKBUTTONLABEL
	filterbutton_label[]	FILTERBUTTONLABEL
	cancel_label[]	CANCELBUTTONLABEL

The file widget follows the OSF/Motif standard XmFileSelectionBox. It is unique in that the file widget contains a group of closely related widgets. The filter is used to list only the desired files in the list box below and to the right. The “*” character is a wild card.

Example:

None.

FORM Functions


ui_form_create	( callback, x, y, position, width, height, label, [unused] )

Forms are separate operating system windows that serve as backgrounds for widgets. They follow the OSF/Motif standard XmBulletinBoard type. They are enclosed by window manager borders. Two types of forms exist: forms and modal forms. See ui_modalform_create, 337 for information on modal forms.


Description:
Create a form widget.
Input:
STRING	callback	Name of PCL function called for an event in this widget. Use ““ since forms do not register events.
NUMERIC	x	X location of the form in inches relative to the screen.
NUMERIC	y	Y location of the form in inches relative to the screen.
STRING	position	Indicates which corners of the screen and form to use when measuring the x and y locations. Options: “UL,” “UR,” “LL” and “LR” for upper-left, upper-right, lower-left, and lower-right, respectively.
NUMERIC	width	Width of the form in inches.
NUMERIC	height	Height of the form in inches.
STRING	label	Label to appear in title bar.
STRING	[unused]
Output:
widget	<Return Value>	ID of the created form widget. NULL if the form is not created properly.
Error Conditions:
None.

FORM Functions


ui_form_delete	( classname )


Description:
Delete a form widget.
Input:
STRING	classname	Name of the class containing the definition of the form to be deleted.
Output:
None.
Error Conditions:
None.

Comments:

The form will be hidden prior to deletion. This function is useful for developing new PCL forms and widgets since a call to ui_exec_function() will re-run the INIT function. However, during normal execution, all the widgets settings are lost as a result of deleting which removes them from memory. Use ui_form_hide() instead.

If class_wide variables are set upon initialization, be careful when using this function because it will cause the INIT function to be re-executed, sometimes producing un-expected results.


ui_form_display	( classname )


Description:
Displays a form defined in class classname and all of its visible children.
Input:
STRING	classname	Name of the class containing the definition of the form to be displayed.
Output:
None.
Error Conditions:
None.

Comments:

Child widgets that have been hidden by calling ui_wid_set (widget, “DISPLAY”, FALSE) will not be displayed. It is preferable to use ui_exec_function(classname, “DISPLAY”).


Description:
Hides a form defined in class classname and all of its children.
Input:
STRING	classname	Name of the class containing the definition of the form to be hidden.
Output:
None.
Error Conditions:
None.

FORM Functions


ui_form_to_file	( classname, level )


Description:
Given the string classname as the name of a class which has a form currently displayed, this function will create a file classname.fd.version file which contains the form and widget descriptions.
Input:
STRING	classname	Classname which contains form of interest.
INTEGER	level	Optional and defaults to 0.
Output:
	<Return Value>
Error Conditions:
None.

Example:

Typing in:

ui_form_to_file( “uil_app_asm”,1)

at command line with geometry panel displayed results in file uil_app_asm.fd.01 which contains:

Form title: “Geometry”

Optmenu: “Construct”

Label: “Action: “

Optmenu: “Grid”

Label: “Object: “

Optmenu: “XYZ”

Label: “Method: “

Databox Value: “9”

Label: “Grid ID List”

Select: “Coord 0”

Label: “Refer. Coordinate Frame”

Select: “[0 0 0]”

Label: “Point Coordinates List”

Toggle: “Auto Execute” [On]

Button: “-Apply-” [Default]

FORM Functions


ui_form_to_frame	( classname, scale )


Description:
Given the string classname as the name of a class which has a form currently displayed, this function will create a framemaker file classname.mif file which contains the form at a scale factor of scale.
Input:
STRING	classname	Name of the PCL class containing the form to be used.
INTEGER	scale	Scale factor for translation. Optional and defaults to 1.0.
Output:
None.
Error Conditions:
None.

Comments:

Creates FrameMaker objects when imported into a FrameMaker document through the import file menu pick.

FRAME Functions


ui_frame_create	( parent, callback, x, y, width, height, label, options )

The frame widget, OSF/Motif standard type XmFrame, is strictly a visual aid. Its “etched in,” narrow appearance groups associated widgets together in a form. Thus, no user interaction occurs with this widget type. Frames may have titles (text strings) at the top left corner.


Description:
Creates a frame widget.*
Input:
widget	parent	ID of the parent widget. Must be a form, modalform, or window
STRING	callback	Name of the PCL function called for an event in this widget. Use ““ since frames are not registering events.
NUMERIC	x	X location of the frame in inches relative to its parent.
NUMERIC	y	Y location of the frame in inches relative to its parent.
NUMERIC	width	Width of the frame in inches.
NUMERIC	height	Height of the frame in inches.
STRING	label	Label to appear describing the contents of the frame.
INTEGER	options	Optional argument defaults to 0. FRAME_CANRESIZE(1) - Allow resizable frames.
Output:
widget	<Return Value>	Item widget ID. NULL if frame not created.
Error Conditions:
None.

Comments:

Widgets placed inside of the frame are positioned relative to the upper left corner of the frame. Widgets positioned with an x or y value that is too large will only partially appear or will not be displayed at all.


ui_framemaker	( option[, scale] )


Description:
Set automatic framemaker generation. If option is 1, whenever ui_form_display() is called, the classname is echoed to the history window. This gives you the classname in order to type a ui_form_to_frame() command. If option is 2, then whenever ui_form_display() is called, the name of the class is echoed, and a call is automatically made to ui_form_to_frame() with the specified scale factor. If option is 0, then ui_form_display() reverts back to normal operation.
Input:
INTEGER	option	Specifies how the function works. See Description above.
REAL	scale	Scale factor for translation. Optional and defaults to 1.0.
Output:
None.
Error Conditions:
None.

ITEM Functions


ui_item_create	( parent, name, label, toggleable, options )

Four different item types exist: menu items, listbox items, option menu items, and switch items.


Description:
Creates an item widget to be used as a child of a menu, menubar, option menu, or switch widget. To create items in a listbox see ui_listbox_items_create, 332.
Input:
widget	parent	ID of the parent widget. Must be a menu, popup menu, menubar, option menu, listbox, or a switch.
STRING	name	Name of the widget. This name is frequently used as an argument for the callback function for the item's parent.
STRING	label	Label to be displayed indicating the widget’s action. If label is “ ” and the parent is a menu or option menu, the item will be defined as a separator.
LOGICAL	toggleable	Value used only for menu items; ignored if the item is not a menu item. If TRUE, the item will display a toggle box next to the item. If FALSE, the item will have only one value.
INTEGER	options	Optional argument with default value of 0 can be the sum of a combination of the following values and are ignored if the parent is the wrong type: MNUITEM_HAS_UNIQUE_CB(1) - Menu item has unique callback specified in the name argument above. MNUITEM_SYMBL_1OFN(4) - The toggle item has a 1-of-many(diamond) symbol. This specification is required only for menu toggle items where by default they will have the N-of-many(square) symbol. To imitate switch-like behavior you are required to implement it the menu’s PCL callback function. MNUITEM_ISLABL(8)- Menu item is a label.
Output:
widget	<Return Value>	Item widget ID. NULL if item not created.
Error Conditions:
None.

Comments:

Menus, menubars, option menus, listboxes, and switches use item widgets. The functional attributes of the item are defined by the parent widget type. The position of the item relative to other currently existing children for the parent widget is specified by the order in which the items are created, i.e., the item created first will appear first in the parent widget, the last item created will appear last.

Use ui_cascadeitem_create() if a cascading menu is desired upon selection of this item.


ui_item_delete	( listbox_id, item_id )


Description:
Deletes a listbox item from it’s parent listbox.
Input:
widget	listbox_id	Item's parent listbox.
widget	item_id	Item's ID.
Output:
None.
Error Conditions:
None.

Comments:

The parent must be a listbox. Do not reference a listbox item after a ui_item_delete() call.


ui_item_deleteall	( parent )


Description:
Deletes all items from it’s parent. The parent must be a listbox or an option menu.
Input:
widget	listbox_id	Item's parent. Must be a listbox or an option menu.
Output:
None.
Error Conditions:
None.

Comments:

The parent must be a listbox or an option menu. Do not reference items after they have been deleted.

ITEM Functions


ui_item_deleteselected	( listbox_id )


Description:
Deletes selected items from a listbox.
Input:
widget	listbox_id	Listbox from which selected items are to be deleted.
Output:
None.
Error Conditions:
None.

Comments:

The parent must be a listbox. Do not reference items after they have been deleted.


ui_item_display	( item )


Description:
Displays a menu item, a switch item, or an option menu item after a call to ui_item_hide().
Input:
widget	item	Item widget ID to be displayed.
Output:
None.
Error Conditions:
None.

Comments:

The parent may not be a listbox.


ui_item_hide	( item )


Description:
Hides a menu item, a switch item, or an option menu item.
Input:
widget	item	Item widget ID to be hidden.
Output:
None.
Error Conditions:
None.

ITEM Functions


ui_item_idfromlabel	( parent, label )


Description;
Returns the item's ID given it's parent and it's label.
Input:
widget	parent	Item's parent.
STRING	label	Item's label.
Output:
widget	<Return Value>	Item's ID.
Error Conditions:
None.

Comments:

If the specified parent does not have an item with the specified label, NULL will be returned.


ui_item_labelfromname	( parent, name, label )


Description:
Outputs the item's label givens it’s parent and it’s name.
Input:
widget	parent	Item's parent.
STRING	name	Item's name.
Output:
STRING	label	Item's label.
Error Conditions:
None.

Comments:

If the specified parent does not have an item with the specified name, the string “NONE” will be returned.

ITEM Functions


ui_item_namefromlabel	( parent, label, name )


Description:
Outputs the item's name givens it’s parent and it’s label.
Input:
widget	parent	Item's parent.
STRING	label	Item's label.
Output:
STRING	name	Item's name.
Error Conditions:
None.

Comments:

If the specified parent does not have an item with the specified label, the string “NONE” will be returned.


ui_item_relabel	( listbox_id, old_label, new_label )


Description:
Replaces an old string for a listbox item with a new string.
Input:
widget	listbox_id	Listbox containing the string to be replaced.
STRING	old_label	String to be replaced.
STRING	new_label	New label.
Output:
None.
Error Conditions:
None.

Comments:

The items will be sorted if sort is set to TRUE in the ui_listbox_create() call for this listbox (Refer to the ui_listbox_create() call for more information.).

ITEM Functions


ui_itemicon_create	( parent, name, iconname, toggleable, options )

The only item icon type is the switch item icon. They may be keyboard-selected using the arrow keys to move from one item to the next, then pressing the space bar.


Description:
Creates an icon item widget to be used as a child of a menu, or switch widget.
Input:
widget	parent	ID of the parent widget. Must be a menu, menubar, or a switch.
STRING	name	Name of the widget. This name is frequently used as an argument for the callback function for the item's parent. The first space character in the name/callback signifies that the rest of the string value is the pop-up help for the icon, and delimits the preceding string without the space as the name/callback of the widget.
STRING	iconname	Name of the file containing the hex information that is used to describe the icon.
LOGICAL	toggleable	Value used only for menu items; ignored if the item is not a menu item. If TRUE, the item will display a toggle box next to the item. If FALSE, the item will behave as a (push) button if it is not used as the parent for a (cascading)menu.
INTEGER	options	Optional argument with default value of 0 can be the sum of a combination of the following values and are ignored if the parent is the wrong type: MNUITEM_HAS_UNIQUE_CB(1) - Menu item has unique callback specified in the name argument above. MNUITEM_ISTOGL(2) - The item is a toggle. If specified overrides the value of the toggleable argument.) MNUITEM_SYMBL_1OFN(4) - The toggle item has a 1-of-many(diamond) symbol. This specification is required only for menu toggle items where by default they will have the N-of-many(square) symbol. To imitate switch-like behavior you are required to implement it the menu’s PCL callback function. MNUITEM_ISLABL(8) - Menu item is a (title)label.
Output:
widget	<Return Value>	Item widget ID. NULL if item not created.
Error Conditions:
None.

Comments:

Menus, menubars, and switches use itemicon widgets. The functional attributes of the item are defined by the parent widget type. The position of the item relative to other currently existing children for the parent widget is specified by the order in which the items are created, i.e., the item created first will appear first in the parent widget, the last item created will appear last.

LABEL Functions


ui_label_create	( parent, callback, x, y, label )

Labels are used only to label other widgets and cannot be selected. They provide additional information to the user.


Description:
Create a label widget
Input:
widget	parent	Parent widget of newly created widget. Must be a frame, a form, or a modal form.
STRING	callback	Not used.
NUMERIC	x	X location of the widget in inches relative to the parent.
NUMERIC	y	Y location of the widget in inches relative to the parent.
STRING	label	Text to be displayed.
Output:
widget	<Return Value>	Label widget ID. NULL if label not created.
Error Conditions:
None.

LABELICON Functions


ui_labelicon_create	( parent, callback, x, y, iconname )

Label icons and labels are exactly alike except that label icons label other widgets with an icon; not text. See ui_label_create, 328 for more information.


Description:
Create a label icon widget
Input:
widget	parent	Parent widget of newly created widget. Must be a frame, a form, or a modal form.
STRING	callback	Not used.
NUMERIC	x	X location of the widget in inches relative to the parent.
NUMERIC	y	Y location of the widget in inches relative to the parent.
STRING	iconname	Name of the file containing the hex information describing the icon. The file must be in the path described by the !!PATH directive assigned during session initialization.
Output:
widget	<Return Value>	Label widget ID. NULL if label not created.
Error Conditions:
None.

LISTBOX Functions


ui_listbox_create	( parent, callback, x, y, width, num_rows, label, selection_type, sort )

This widget is considered by OSF/Motif as an XmList contained within an XmScrolledWindow.


Description:
Create a listbox widget
Input:
widget	parent	Parent widget of newly created widget. Must be a frame, a form, or a modal form.
STRING	callback	Name of the PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events in this widget are not of interest.
NUMERIC	x	X location of the widget in inches relative to the parent.
NUMERIC	y	Y location of the widget in inches relative to the parent.
NUMERIC	width	Width of the listbox in inches.
INTEGER	num_rows	Number of rows of items displayed in the listbox.
STRING	label	Label displayed to describe the listbox.
STRING	selection_type	“BROWSE”, “EXTEND”, “MULTIPLE”, or “SINGLE”. See selection_type Modes, 330.
LOGICAL	sort	TRUE if the items should be sorted alphabetically, FALSE if not.
Output:
widget	<Return Value>	Widget ID of listbox widget. NULL if not created.
Error Conditions:
None.

Comments:

In order to add items to a listbox see ui_listbox_items_create, 332. Due to a Motif bug a listbox created in a form that is already displayed will have incorrect num_rows. To work around this problem you have to call ui_wid_set( <listbox>, “ROWS”, num_rows ) after creating the listbox successfully.

selection_type Modes

Four different selection_type modes exist for the listbox, as follows:


Single	Allows only one pick at a time. Here, pressing down on an item will automatically pick it. Any scrolling done afterwards or a releasing of the mouse button on another item will be inconsequential. Arrow keys highlight subsequent items which also selects one at a time.
Browse	Allows only one selection to be made at a time. Pressing down on an item only initiates picking, then you may scroll up and down through the other choices without making a selection. As the cursor moves over the items, the item corresponding to the cursor location will become highlighted. Releasing the mouse button on the highlighted item makes the selection. Keyboard selection works the same for browse mode as for single mode.
Multiple	Allows picking of more than one item by clicking each one separately. It will also toggle off previously highlighted items. The arrow keys highlight the items while the space bar selects and deselects them.
Extend	Also permits multiple picking of items. Pressing down on the left mouse button with the cursor on the first (base) item desired will initiate picking. Next, dragging through any adjacent items will highlight them also. These highlights are temporary and can be changed by dragging elsewhere in the listbox. Releasing the mouse button on another item will pick all items between the base and last item inclusively.

LISTBOX Functions


ui_listbox_items_create	( listbox, names, labels, num_items, wid_array )


Description:
Create items in a listbox. This routine differs from ui_item_create by creating items in a listbox from an array of labels. The result is that items are created much faster with this routine than by creating them one at a time. This call ignores the DUPLICATEITEM resource setting of the listbox. The caller of this function is responsible for eliminating duplicate items when necessary.
Input:
widget	listbox	Listbox ID returned from the ui_listbox_create() call containing the items to be selected.
STRING[]()	names	Names of the widgets to be created in the listbox. These are frequently used as arguments for the callback function for the item’s parent.
STRING[]()	labels	Labels to be displayed indicating the widgets action.
INTEGER	num_items	Number of items in listbox.
Output:
WIDGET()	wid_array	Array that will contain the uims widgets created for each label. If uims widgets are not needed, pass the global WIDGET_NULL instead of wid_array
INTEGER	<Return Value>	Status. 0 if no error occurred, 1 otherwise.
Error Conditions:
None.


ui_listbox_items_delete	( listbox )


Description:
Delete all items contained in the listbox.
Input:
widget	listbox	Listbox ID returned from the ui_listbox_create() call containing the items to be deleted.
Output:
None.
Error Conditions:
None.

LISTBOX Functions


ui_listbox_select_items	( listbox, start, num_items )


Description:
Select all items contained in the listbox.
Input:
widget	listbox	Listbox ID returned from the ui_listbox_create() call containing the items to be selected.
INTEGER	start	Starting position of items to select.
INTEGER	num_items	Number of items in listbox to select.
Output:
None.
Error Conditions:
None.

Comments:

This routine will work with listboxes created with a selection type of EXTENDED or MULTIPLE. It will not work with listboxes created with a selection type of BROWSE or SINGLE.

• If start is greater than the actual number of items in the listbox no items will be selected.

• If start + num_items is greater than the actual number of items in the listbox, items will be selected from position start through the last item in the listbox.

• If start is negative, then the first num_items + start items will be selected.

• If num_items is negative, no items will be selected.


ui_list_select_nitems	( listbox, item_labels, start, num_items )


Description:
Select items specified in the listbox.
Input:
widget	listbox	Listbox ID returned from the ui_listbox_create() call containing the items to be deleted.
STRING ARRAY	item_labels	Array of item labels.
INTEGER	start	Starting position of item labels to select.
INTEGER	num_items	Number of item labels from start to select.
Output:
None.
Error Conditions:
None.

Comments:

This routine will work with listboxes created with a selection type of EXTENDED or MULTIPLE. It will not work with listboxes created with a selection type of BROWSE or SINGLE.


ui_listbox_unselectall	( listbox )


Description:
Unselect all items contained in the listbox.
Input:
widget	listbox	Listbox ID returned from the ui_listbox_create() call containing the items to be deleted.
Output:
None.
Error Conditions:
None.

MENU Functions


ui_menu_create	( parent, callback, label, options )

The menu bar contains a horizontal grouping of menus. However, the menus listed within a menu bar are not displayed in their entirety. Instead, a menu label representing each menu is shown.


Description:
Create a menu widget.
Input:
widget	parent	Parent widget of a newly created widget. The parent must be a cascade_item or a menubar. The Patran menubar ID can be determined by calling menubar = uil_primary.get_menubar_id().
STRING	callback	Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events in this widget are not of interest.
STRING	label	Label that will be displayed in menubar.
INTEGER	options	Optional argument defaults to 0. It can have a sum of the following values: MENU_IS_SWITCH(4) - Menu behaves like a switch. MENU_HAS_NO_CB(8) - Each menu item has its own callback. The optional argument values are defined in ui_options.p and it is required to include the file to access the options by the default names.
Output:
widget	<Return Value>	Menu widget ID. NULL if menu not created.
Error Conditions:
None.

Comments:

Menus are vertical groupings of item widgets. The size and number of items added to the menu widget determines the menu's size.

MODAL FORM Functions


ui_modalform_create	( name, x, y, position, width, height, [unused], options )


Description:
Create a modal form widget.
Input:
STRING	name	Name of the modal form.
NUMERIC	x	X location of the form in inches relative to the screen.
NUMERIC	y	Y location of the form in inches relative to the screen.
STRING	position	Indicates which corners of the screen and modal form to use when measuring the x and y locations. Options include “UL”, “UR”, “LL”, and “LR”.
NUMERIC	width	Width of the modal form in inches.
NUMERIC	height	Height of the modal form in inches.
STRING	[unused]	Unused. Specify ““.
INTEGER	options	Optional argument defaults to 0. MODAL_LOC_ISFIXED(8) - Uses the location specified to position the modal dialog form. Without this option the form is placed centered at the mouse pointer location.
Output:
widget	<Return Value>	Modal form widget ID. NULL if modal form not created.
Error Conditions:
None.

OPTION MENU Functions


ui_optionmenu_create	( parent, callback, x, y, label_length, label, label_above )

According to OSF/Motif terminology, an option menu is defined as a class XmOptionMenu widget. An option menu is a vertical grouping of items; however, only one of the items is visible until the user clicks on the item.


Description:
Create a option menu widget.
Input:
widget	parent	Parent ID. Must be a frame, a window, a form or a modal form.
STRING	callback	Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events in this widget are not of interest.
NUMERIC	x	X location in inches relative to the parent.
NUMERIC	y	Y location in inches relative to the parent.
NUMERIC	label_length	Length of the space between the beginning of the label and the option menu button. Used only if label_above is FALSE. If 0., the actual length of the label will be used.
STRING	label	Label to appear describing the option menu.
LOGICAL	label_above	TRUE if the label is to appear above the menu. FALSE if the label is to appear to the left of the menu.
Output:
widget	<Return Value>	Option menu widget ID. NULL if the option menu was not created.
Error Conditions:
None.

Comments:

The PCL callback will be called when an option menu item is selected unless the selected item is the currently displayed option menu item.

PERCENT COMPLETE Functions


pcntcomplete_close	( )


Description:
Remove the percent complete form from the screen.
Input:
None.
Output:
None.
Error Conditions:
None.

Comments:

pcntcomplete_close is PCL, Fortran and C callable. The Fortran syntax is:

PCNTCOMPLETE_CLOSE( )

The C syntax is:

PcntcompleteClose( )


pcntcomplete_init	( message )


Description:
Display the percent complete form and assign the message to be displayed.
Input:
STRING[256]	message	Message to be displayed describing the operation that is being performed.
Output:
None.
Error Conditions:
None.

Comments:

pcntcomplete_init is PCL, Fortran and C callable. The Fortran syntax is:

PCNTCOMPLETE_INIT( MESSAGE )

The C syntax is:

PcntcompleteInit( message )

PERCENT COMPLETE Functions


pcntcomplete_update	(new_pcnt )


Description:
Update the value indicated in the slidebar in the percent complete form.
Input:
REAL	new_pcnt	The new value to be displayed. This value should be between 0. and 100., inclusive. If new_pcnt is less than 0., the UIMS will reassign the value to 0. If new_pcnt is greater than 100., the UIMS will reassign the value to 100. Although there is nothing stopping the PCL developer from counting from 100 to 0, it would be more intuitive to count up.
Output:
None.
Error Conditions:
None.

Comments:

pcntcomplete_update is PCL, Fortran and C callable. The Fortran syntax is:

PCNTCOMPLETE_UPDATE( NEW_PCNT )

The C syntax is:

PcntcompleteInit( new_pcnt ).

The percent complete functions are to be used to indicate to the user that progress is being made. If the operation occurs too quickly (heaven forbid), it is possible for the X queue to receive the pcntcomplete_close call and therefore the instruction to hide the pcntcomplete form before the pcntcomplete_init call has had a chance to display the form. This will result in the inability to hide the form. For these operations, it is not necessary to use the pcntcomplete functions.

RING BELL Functions


ui_ring_bell	(new_pcnt )


Description:
Rings bell.
Input:
None.
Output:
None.
Error Conditions:
None.

POPUP MENU Functions


ui_c_popupmenu	( parent, callback, options )

A popup menu bar contains a horizontal grouping of menus activated by clicking the right mouse button. However, the menus listed within a menu bar are not displayed in their entirety. Instead, a menu label representing each menu is shown.


Description:
Create a menu widget.
Input:
widget	parent	Should be a NULL widget if popup menu is created. Should be a widget of type created using UI_CASCADEITEM_CREATE if submenu is created.
STRING	callback	Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events in this widget are not of interest.
INTEGER	options	Optional argument defaults to 0. It can have a sum of the following values: MENU_IS_SWITCH(4) - Menu behaves like a switch. MENU_HAS_NO_CB(8) - Each menu item has its own callback. The optional argument values are defined in ui_options.p and it is required to include the file to access the options by the default names.
Output:
widget	<Return Value>	Menu widget ID. NULL if menu not created.
Error Conditions:
None.

Comments:

Only tree widget entities currently support right mouse button to display popup menus. Use ui_item_create() to add items to the popup menu widget in the same manner you would for ui_menu_create(). The same for cascading menu items.

POPUP MENU Functions


ui_post_popupmenu	( wid )

Posts a previously created popup menu widget.


Description:
Create a menu widget.
Input:
widget	wid	The variable of type WIDGET created using UI_C_POPUPMENU().
Output:
widget	<Return Value>	None.
Error Conditions:
None.

Comments:

Where the popup menu appears is based on setting the X and Y positions of the popuup menu using UI_WID_SET() before making this call.

SCROLLFRAME Functions


ui_scrollframe_create	(parent, callback, x, y, width, height, label, working_width, working_height, needstaticscrolls )

The scroll frame can contain several widgets and text. To use a scroll frame, click on either of the horizontal or vertical scroll arrows to move the contents incrementally. Otherwise, click and drag either of the scroll bars to quickly move the scroll frame contents. Any applicable widget may be selected as long as it is in the visible portion of the scroll frame.


Description:
Create a frame widget that scrolls.
Input:
widget	parent	Parent widget ID of newly created widget. Must be form, modalform, or window.
STRING	callback	Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ since frames are not registering events.
NUMERIC	x	X location of the scrollframe in inches relative to parent
NUMERIC	y	Y location of the scrollframe in inches relative to parent.
NUMERIC	width	Width of the scrollframe in inches.
NUMERIC	height	Height of the scrollframe in inches.
STRING	label	Label to appear describing the contents of the frame.
NUMERIC	working_width	Width of the scrollable area inside of the scrollframe on which widgets are placed, in inches.
NUMERIC	working_height	Height of the scrollable area inside of the scrollframe on which widgets are placed, in inches.
LOGICAL	needstaticscrolls	Optional argument defaults to TRUE. Set to FALSE, whenever scrolls are to be displayed only when required.
Output:
widget	<Return Value>	ID of the created scrollframe widget. NULL if the scrollframe is not created properly.
Error Conditions:
None.

Comments:

Slidebars used for scrolling will be drawn as needed. Widgets placed inside of the scrollframe widget are positioned relative to the upper left corner of the scrollframe. Widgets positioned with an x or y value that is too large will only partially appear or will not be displayed at all.


ui_scrollitem_setvisible	(parent, item, lrMargin, tbMargin )


Description:
Make an invisible or partially visible scrollframe item visible.
Input:
widget	parent	Parent widget ID. Must be a scroll frame.
widget	item	Item widget ID. Must be a descendent of scroll frame parent.
INTEGER	lrMargin	Margin to use between left or right edge of the item and the associated edge of the parent.
INTEGER	tbMargin	Margin to use between top or bottom edge of the item and the associated edge of the parent.
Output:
None.
Error Conditions:
None.

SELECTDATABOX Functions


ui_selectdatabox_create	(parent, name, x, y, label_width, box_width, label, cvalue, label_above, datatype, prompt, pick_callback )

Although select databoxes fall into the same OSF/Motif widget class as databoxes, several differences exist. Visibly, a select databox and a databox look exactly alike; however, only the select databox, or a group of them, is surrounded by a select frame. See ui_selectframe_create, 351 for more details.

In terms of user input, a select databox has all of the features of a databox. In addition, it also allows mouse picking. See ui_databox_create, 306 for a complete description. Select databoxes are tightly linked to graphics windows in that they allow the selection of entities in a viewport if that data is relevant. If screen selection is appropriate, a select menu may appear on the bottom of the screen when the select databox is clicked, depending on the type of data expected in the select databox. See Screen Picking (p. 33) in the Patran Reference Manual for more details.


Description:
Creates a select databox widget.
Input:
WIDGET	parent	Parent WIDGET ID. Must be a select frame.
STRING	name	Name of the data box. See widget Function Descriptions, 256 for more information.
NUMERIC	x	X location of the databox in inches relative to parent
NUMERIC	y	Y location of the databox in inches relative to parent.
NUMERIC	label_width	Used only if label_above is FALSE. Distance between the beginning of the label and the beginning of the box, in inches. If zero, the length of the label string will be used. Specifying the label_width is useful when lining up several databoxes.
NUMERIC	box_width	Width of the box in inches.
STRING	label	Displayed text describing the value associated with the databox. To have no label initially but plan on using ui_wid_set() to change the label, assign label to be “ “. If not assigning a label, use ““ and set label_above to FALSE.
STRING	cvalue	Value displayed inside the databox. This value is of the datatype specified.
LOGICAL	label_above	TRUE is the label is to be displayed above of the databox, FALSE if the label is to be displayed to the left of the databox.
STRING	datatype	Type of data to accept. For specific types, see Comments section.
STRING	prompt	The prompt that will appear in the text widget in the select menu when the select databox is expecting selecting to occur.
STRING	pick_callback	This argument is optional. Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events for this widget are not of interest.
Output:
widget	<Return Value>	Widget ID. NULL if the widget could not be created.
Error Conditions:
None.

Comments:

The PCL callback will be called when widget receives input focus, when the widget loses input focus, and when a carriage return (<CR>) is entered.

This function will accept any datatype, but selecting/picking will report an error if the datatype is not one of the following valid types:


datatype string	description
"ALL_SWEEP"	Curves, surfaces, edges, faces, nodes, bar elements, 2D elements, edge elements, face elements
"ANY"	Any entity; points, curves, surfaces, solids, coords, planes, vectors, nodes, elements, MPCs
"ANY_POINT"	Points, geometry vertex, nodes
"ASM"	ASM Menu; points, curves, surfaces, solids, coords, planes, vectors,
"BEAMELEM"	Beam elements; bar elements
"CID"	Coords
"CID1"	Coord axis 1
"CID2"	Coord axis 2
"CID3"	Coord axis 3
"CONNECTOR"	User entity
"CURVE"	Curve Menu; curves
"CURVE_EDGE"	Curves and edges; curves, geometry edges
"DECOMPSURF"	Edges on surface, verticies on surface, points, points on decomposed surface
"DEF_NODE"	Nodes
"DEF_POINT"	Points, geometric verticies
"EDGE"	Edges
"EDGEONSURFACE"	Edges on surfaces
"ELEDGE"	Element edges
"ELEDGE_BEAM"	Bar element edges, element edges
"ELEDGE_FREE"	Element edges, free element edges
"ELEM2D"	2D elements
"ELEM2_SWEEP"	Nodes, bar elements, 2D elements, element edges
"ELEM3D"	3D elements
"ELEMENT"	Elements
"ELEM_EDGE_2D"	2D element edges
"ELEM_EDGE_2D_FREE"	2D element edges, free element edges
"ELEM_NODE"	Element node
"ELEM_SWEEP"	Nodes, point elements, bar elements, 2D elements, element edges, element faces
"ELFACE"	Element faces
"ELFACE_FREE"	Element faces, free element faces.
"ELFACE_QUAD_TRI"	Quad elements, Tria elements, element faces
"FACE"	Geometry faces
"FEM"	Nodes, elements, MPCs
"FEM_AND_GEO_0D"	Points, point elements
"FEM_AND_GEO_1D"	Curves, geometry edges, and bar elements
"FEM_AND_GEO_2D"	Surfaces, geometry faces, 2D elements
"FEM_AND_GEO_3D"	Solids, 3D elements
"FEM_SHELL_BNDRY"	2D element edges, element edges
"FRAME"	Coordinate frames
"FREE_EDGE_ELEMS"	2D elements, 3D elements, element free edges
"FREE_FACE_ELEMS"	3D elements, element free faces
"FREE_FACE_SOLIDS"	Geometric free faces, solids
"GEOMETRY"	Curves, surfaces, solids, planes, vectors
"GEO_BEAM"	Curves, geometric edges
"GEO_CURVE_EDGE"	Curves, geometric edges
"GEO_FEATURES"	Solids, surfaces, geometric faces, curve mask, geometric edges,
"GEO_SHELL"	Surfaces, geometric faces
"GEO_SOLID"	Geometric solid
"GEO_SOLID_BNDRY"	Geometric faces
"GEO_SURFACE_FACE"	Surfaces, geometric faces
"GRID"	Geometric points
"HEXELEM"	Hex elements
"HPAT"	Geometric solids
"LINE"	Geometric curves
"MESH"	Surfaces, solids, geometric edges, geometric faces, nodes, elements, MPCs
"MESH_SWEEP"	Curves, surfaces, geometric edges, geometric faces
"MPC"	MPCs
"NODE"	Nodes
"PATCH"	Surfaces
"PLANE"	Planes
"POINT"	Points
"POINTELEM"	Point elements
"POINTONNODE"	Points on nodes
"POINT_VERTEX"	Points, geometric verticies
"PTONCURVE"	Points on curves
"PTONSURFACE"	Points on decomposed surfaces
"QUADELEM"	Quad elements
"SOLID"	Solids
"SOLIDFACE_FREE"	Geometric faces, geometric free faces
"SP"	Screen points
"SURFACE"	Surfaces
"SURFACE_EDGE"	Surfaces edges
"SURFACE_FACE"	Surfaces, geometric faces
"TETELEM"	Tet elements
"TRIELEM"	Tria elements
"TRIMSURFACE"	Trimmed surfaces
"VECTOR"	Vectors
"VERTEX"	Geometric verticies
"VERTEXONSURFACE"	Verticies on surfaces
"WEDGEELEM"	Wedge elements

SELECTFRAME Functions


ui_selectframe_create	(parent, callback, x, y, width, height, label, recycle )

Select frames act as containers for one or more select databoxes. See ui_selectdatabox_create, 346. Select frames follow the OSF/Motif style “etched-out” frame.

Select frames can also have an attached toggle. This toggle will most often be the Auto Execute option. If a series of select databoxes is necessary for an application, then the Auto Execute function automatically advances the cursor to the next select databox as soon the previous one is filled if the select databox was filled using mouse selection. In some cases after all the select databoxes have been filled, Auto Execute may indicate to Patran to perform the function. In addition, partial data as it is input by the user will be immediately applied instead of waiting for a complete set of data before acting. Thus, if the Auto Execute option is used, the need for clicking the Apply button is eliminated.


Description:
Create a select frame widget. This widget is used to visually and functionally group select databoxes.
Input:
widget	parent	Parent widget ID of newly created widget. Must be form.
STRING	callback	The callback function assigned will only be called when: (1) the toggle is set to ON, and (2) the last select databox in this select frame has just been filled with a list created using the select mechanism. Typically, this callback will be the function called for the action button for a form.
NUMERIC	x	X location of the frame in inches relative to parent
NUMERIC	y	Y location of the frame in inches relative to parent.
NUMERIC	width	Width of the frame in inches.
NUMERIC	height	Height of the frame in inches.
STRING	label	Label of toggle describing the automatic traversal functionality. This toggle will indicate whether the select databoxes are to be automatically traversed. If the label is ““, the toggle will not be visible.
LOGICAL	recycle	TRUE if the first databox in the frame is to regain input focus after the last databox in the frame loses input focus otherwise focus remains in the last databox.
Output:
widget	<Return Value>	ID of the created frame widget. NULL if the frame is not created properly.
Error Conditions:
None.

Comments:

The toggle that indicates whether single or multiple select is to occur is currently disabled since the functionality to automatically move to the next selectdatabox is not present. Databoxes placed inside of the selectframe widget are positioned relative to the upper left corner of the frame.

Use ui_wid_set(widget_id, “TOGGLEVALUE”, FALSE) to turn the toggle to OFF if default ON is not desired.

SEPARATOR Functions


ui_separator_create	(parent, name, x, y, length, horizontal )


Description:
Create a separator widget.
Input:
widget	parent	Parent widget ID of newly created widget. Must be a frame, a form, or a modal form.
STRING	name	Name of the separator.
NUMERIC	x	X location of the widget in inches relative to parent
NUMERIC	y	Y location of the widget in inches relative to parent.
NUMERIC	length	Length of the widget in inches.
LOGICAL	horizontal	TRUE if separator is horizontally oriented, FALSE if separator is vertically oriented.
Output:
widget	<Return Value>	Separator widget ID. NULL if widget is not created
Error Conditions:
None.


ui_set_fixedfont	(wid )


Description:
Set the global fixed font for a widget.
Input:
widget	wid	Widget ID.
Output:
INTEGER	<Return Value>	1 if successful, 0 if font is not set.
Error Conditions:
None.

Comments:

This function will obtain the global fixed font specified using Patran.fixedFont resource in the Patran resource file, verify if the font exists on the X display server that Patran windows are shown, and then set the font resource for the widget.

SET FOCUS Functions


ui_set_focus	(wid )


Description:
Set the input focus for a widget
Input:
widget	wid	Widget ID to set focus ON.
Output:
None.
Error Conditions:
None.

Comments:

When used in conjunction with select_focus.select_manager(), in the class display function will cause the select mechanism to immediately allow picking of graphical entities of the type specified if the widget is a select databox.

Example:

FUNCTION display

/*

    * Enable the select menu for immediate picking

*/

   select_focus.select_manager( /*  widget  */  entities_sdbox,           @

                                /* datatype */ “ANY”,                     @

                                /*  prompt  */ “Input Entity IDs or “ //  @

                                               “pick a Select Menu Icon.” )

/*

    * Display the form

*/

   ui_form_display( “uil_imaging_plot_erase” )

/*

    * Set the input focus on the selectdatabox for immediate typing

*/

   ui_set_focus( entities_sdbox )

END FUNCTION /* display */

FUNCTION callback( treeWidget, event, callData, userData )

   WIDGET  treeWidget

   STRING  event []

   WIDGET  callData

   STRING  userData []

…

END FUNCTION

SLIDEBAR Functions


ui_slidebar_create	(parent, callback, x, y, length, label, value, num_digits, horizontal, minlabel, maxlabel, show_value, minvalue, maxvalue )

Slide bars allow values to be increased by moving the slider to the right or decreased by moving the slider to the left.

Slide bars can be adjusted several ways. The slider may be dragged to a desired position with the mouse. Or, the slider may be repositioned to the cursor position by clicking the middle mouse button inside the slide bar. Remember that the terms “click” and “drag” mean to use the left mouse button unless otherwise noted. By clicking inside the slide bar, the slider will move toward the cursor by one default increment. Clicking and holding the left mouse button inside the slide bar will incrementally move the slide bar toward the cursor until the button is released.

Once a slide bar has focus, the arrow keys may be used to move the slider.


Description:
Create a slide bar widget.
Input:
widget	parent	Parent widget ID of newly created widget. Must be a frame, a form, or a modal form.
STRING	callback	Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events for this widget are not of interest.
NUMERIC	x	X location of the widget in inches relative to parent
NUMERIC	y	Y location of the widget in inches relative to parent.
NUMERIC	length	Length of the widget in inches.
STRING	label	Label to appear describing the slidebar.
NUMERIC	value	Current value of the slidebar.
INTEGER	num_digits	Number of digits beyond the decimal to display.
LOGICAL	horizontal	TRUE if separator is horizontally oriented, FALSE if separator is vertically oriented.
STRING	minlabel	Label to appear at the minimum end of the slidebar.
STRING	maxlabel	Label to appear at the maximum end of the slidebar.
LOGICAL	show_value	TRUE if slidebar value is to be displayed adjacent to the slidebar value indicator.
NUMERIC	minvalue	Minimum value the slidebar will allow.
NUMERIC	maxvalue	Maximum value the slidebar will allow.
Output:
widget	<Return Value>	Slidebar widget ID. NULL if widget is not created.
Error Conditions:
None.

Comments:

The PCL callback will be called for either of the following events:

the user drags the slider, which instructs the UIMS to assign the string “DRAG” to be the second argument of the callback,

the user stops dragging the slider, which instructs the UIMS to assign the string “VALUE_CHANGED” to be the second argument of the callback, or

the user clicks in the slide area but not in the slider, which also instructs the UIMS to assign the string “VALUE_CHANGED” to be the second argument of the callback.

SPREADSHEET Functions


ui_spread_cell_delete	(wid, col, row, lay )


Description:
Delete a spreadsheet cell
Input:
widget	wid	Spreadsheet widget ID.
INTEGER	col	Column number
INTEGER	row	Row number
INTEGER	lay	Layer number
Output:
widget	<Return Value>	Separator widget ID. NULL if widget is not created
Error Conditions:
None.


ui_spread_cells_delete	(wid, fr_col, fr_row, to_col, to_row, lay )


Description:
Delete a block of spreadsheet cells
Input:
widget	wid	Spreadsheet widget ID.
INTEGER	fr_col	Starting column
INTEGER	fr_row	Starting row
INTEGER	to_col	Ending column
INTEGER	to_row	Ending row
INTEGER	lay	Layer
Output:
None.
Error Conditions:
None.

SPREADSHEET Functions


ui_spread_create	(parent, callback, x, y, width, height, label_width, num_vis_cols, num_cols, num_rows, num_layers, col_labels, row_labels, label, layer_label, layer_value_label, selection_type )

The spreadsheet is an MSC-developed widget.

The spreadsheet widget contains several features. It consists of rows and columns of cells with numerical values entered by the user. Each cell has an address designated by the row and column in which it resides. After entering data in a cell or multiple cells, the data may be manipulated in various ways. An entire row or column may be selected by clicking on its label. Or, an individual cell may be selected by clicking inside the cell. Also, multiple cells may be selected by dragging the mouse cursor over the desired cells.


Description:
Creates a spreadsheet widget.
Input:
widget	parent	Parent widget ID of newly created widget. Must be a frame, a form, or a modal form.
INTEGER	callback	Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events for this widget are not of interest.
NUMERIC	x	X location of spreadsheet in inches relative to the parent.
NUMERIC	y	Y location of spreadsheet in inches relative to the parent.
NUMERIC	width	Width of the spreadsheet in inches.
NUMERIC	height	Height of the spreadsheet in inches.
NUMERIC	label_width	Width of the row labels in inches.
INTEGER	num_vis_cols	Number of visible columns.
INTEGER	num_cols	Total number of columns.
INTEGER	num_rows	Total number of rows.
INTEGER	num_layers	Total number of layers.
STRINGARRAY	col_labels	2D array of column labels, (columns, layers).
STRINGARRAY	row_labels	2D array of row labels, (rows, layers).
STRING	label	Spreadsheet label.
STRING	layer_label	Layer databox label (for 3D).
STRING	layer_value_label	Layer value databox label (for 3D).
STRING	selection_type	“SINGLE”, “ROWSELECT”, “EXTEND”, “READONLY”. See comments below.
Output:
widget	<Return Value>	Widget ID of spreadsheet widget. NULL if not created.
Error Conditions:
None.

Comments:

Four different selection_type modes exist, as follows:


SINGLE	May pick only one cell. Dragging the mouse and picking labels has no effect.
ROWSELECT	Picking a cell or label selects the entire row. Dragging the mouse has no effect. Used for the coupled listbox.
EXTEND	Allows picking of more than one item by clicking each one separately. It will also toggle off previously highlighted items. The arrow keys highlight the items while the space bar selects and deselects them.
READONLY	Cells are not pickable. Scrollbars are still active. No callback is called.

The PCL callback will be called when the user clicks on the cell display portion of the spreadsheet unless the selection_type has been set to “READONLY”.

A databox must accompany this widget if data entry, editing, and expansion of cell contents is needed. The application transfers data into and out of the spreadsheet using ui_spread_set_cell and ui_spread_get_cell and the callback information.

Clicking on a row or column label selects the entire row or column.

SPREADSHEET Functions


ui_spread_get_cell	( widget_id, col, row, layer, value )


Description:
Get a spreadsheet cell.
Input:
widget	widget_id	Must be a spreadsheet.
INTEGER	col	Column to retrieve.
INTEGER	row	Row to retrieve.
INTEGER	layer	Layer to retrieve.
Output:
STRING	value	Value in cell.
Error Conditions:
None.

Comments:

One cell accessed at a time.


ui_spread_get_cell_info	(widget_id, col, row, layer, value )


Description:
Gets a spreadsheet cell information dot.
Input:
widget	widget_id	Must be a spreadsheet.
INTEGER	col	Column to access.
INTEGER	row	Row to access.
INTEGER	layer	Layer to access.
Output:
LOGICAL	value	TRUE or FALSE if dot is set or not.
Error Conditions:
None.

Comments:

The dot that shows up in the cell is used to signify that there is extra information associated with this cell. It is up to the programmer to store the structure containing this information. See ui_spread_set_cell_info (p. 369).

SPREADSHEET Functions


ui_spread_get_cell_length	(widget_id, col, row, layer, length )


Description:
Gets the number of visible characters in a spreadsheet cell.
Input:
widget	widget_id	Must be a spreadsheet.
INTEGER	col	Column to retrieve.
INTEGER	row	Row to retrieve.
INTEGER	layer	Layer to retrieve.
Output:
INTEGER	length	Number of visible characters in cell.
Error Conditions:
None.


ui_spread_get_layer_value	(widget_id, layer, value )


Description:
Gets a layer value from a 3D spreadsheet.
Input:
widget	widget_id	Must be a spreadsheet.
INTEGER	layer	Layer to requested.
Output:
STRING	value	Value of the given layer as displayed in the layer value databox.
Error Conditions:
None.

Comments:

This value is displayed in the layer value databox.

SPREADSHEET Functions


ui_spread_get_num_vis_rows	(wid, num_vis_rows )


Description:
Get a spreadsheet number of visible rows.
Input:
widget	wid	Spreadsheet widget ID.
Output:
INTEGER	num_vis_rows	Number of visible rows.
Error Conditions:
None.

Comments:

See ui_spread_get_top_row, 365 to determine which rows are visible.


ui_spread_get_selected	(widget_id, from_col, from_row, to_col, to_row, layer )


Description:
Retrieves the starting and ending column and row positions and layer for the currently selected (highlighted) cells of a given spreadsheet.
Input:
widget	widget_id	Must be a spreadsheet.
Output:
INTEGER	from_col	Starting column.
INTEGER	from_row	Starting row.
INTEGER	to_col	Ending column.
INTEGER	to_row	Ending row.
INTEGER	layer	Layer.
Error Conditions:
None.

Comments:

The callback from ui_spread_create returns the same information. If the from and to values are the same, only one cell is selected (highlighted).

SPREADSHEET Functions


ui_spread_get_top_row	(widget_id, top_row )


Description:
Gets the top visible row number of a spreadsheet.
Input:
widget	widget_id	Must be a spreadsheet.
Output:
INTEGER	top_row	Row to get.
Error Conditions:
None.


ui_spread_row_create	(widget_id, label )


Description:
Add a spreadsheet row.
Input:
widget	widget_id	Must be a spreadsheet.
STRING	label	Row label.
Output:
None.
Error Conditions:
None.

Comments:

Add a row after the last row of the spreadsheet.


ui_spread_row_delete	(widget_id, row_num )


Description:
Delete a spreadsheet row.
Input:
widget	widget_id	Must be a spreadsheet.
INTEGER	row_num	Row number to be deleted.
Output:
None.
Error Conditions:
None.

Comments:

The row numbers are counted from the first row altogether and NOT the first currently visible one in the spreadsheet. Hence the rows following the deleted one are decremented by one. The application needs to account for this when deleting multiple rows. For example, all rows can be deleted by deleting row 1 repeatedly.


ui_spread_set_cell	(widget_id, col, row, layer, value )


Description:
Sets a spreadsheet cell.
Input:
widget	widget_id	Must be a spreadsheet.
INTEGER	col	Column to access.
INTEGER	row	Row to access.
INTEGER	layer	Layer to access.
STRING	value	Value to be set.
Output:
None.
Error Conditions:
None.

Comments:

One cell is set at a time. If setting cell to the empty string, use ui_spread_cell_delete instead.

SPREADSHEET Functions


ui_spread_set_cells	(wid, fr_col, fr_row, to_col, to_row, lay, values )


Description:
Set multiple spreadsheet cell contents.
Input:
widget	widget_id	Spreadsheet widget ID.
INTEGER	fr_col	Start column.
INTEGER	fr_row	Start row.
INTEGER	to_col	End column.
STRING	to_row	End row.
INTEGER	lay	Layer.
STRINGARRAY	values	Data to display in cells.
Output:
None.
Error Conditions:
None.

Comments:

Improved performance over ui_spread_set_cell.


ui_spread_set_cell_info	(widget_id, col, row, layer, value )


Description:
Sets a spreadsheet cell information dot.
Input:
widget	widget_id	Must be a spreadsheet.
INTEGER	col	Column to access.
INTEGER	row	Row to access.
INTEGER	layer	Layer to access.
STRING	value	TRUE or FALSE to display or hide the dot.
Output:
None.
Error Conditions:
None.

Comments:

SPREADSHEET Functions


ui_spread_set_display	(parent, state )


Description:
Modify the display state of the spreadsheet.
Input:
widget	parent	Spreadsheet widget ID.
STRING	state	Determines the display characteristics of a spreadsheet: “COL_ROW_LINE” - Draw heavy lines after the first row and column. ”COL_LINE” - Heavy line after first column. “ROW_LINE”- Heavy line after first row. ““- Default (No heavy lines).
Output:
None.
Error Conditions:
None.


ui_spread_set_label	(widget_id, col_row, index, layer, label )


Description:
Sets a spreadsheet column or row label.
Input:
widget	widget_id	Must be a spreadsheet.
INTEGER	col_row	1 for col, 2 for row.
INTEGER	index	Column or row number.
INTEGER	layer	Layer to set.
STRING	label	Label to set.
Output:
None.
Error Conditions:
None.

Comments:

The new label will be truncated if it is larger than the existing space for the labels.

SPREADSHEET Functions


ui_spread_set_layer_value	(widget_id, layer, value )


Description:
Sets a layer value of a 3D spreadsheet.
Input:
widget	widget_id	Must be a spreadsheet.
INTEGER	layer	Layer to set.
STRING	value	Value to be set.
Output:
None.
Error Conditions:
None.

Comments:

This value is displayed in the layer value databox.


ui_spread_set_selected	(widget_id, from_col, from_row, to_col, to_row )


Description:
Selects (highlights) the starting and ending column and row positions for the currently visible layer of a given spreadsheet.
Input:
widget	widget_id	Must be a spreadsheet.
INTEGER	from_col	Starting column.
INTEGER	from_row	Starting row.
INTEGER	to_col	Ending column.
INTEGER	to_row	Ending row.
Output:
None.
Error Conditions:
None.

SPREADSHEET Functions


ui_spread_set_top_row	(widget_id, top_row )


Description:
Sets the top visible row number of a spreadsheet.
Input:
widget	widget_id	Must be a spreadsheet.
INTEGER	top_row	Row to set.
Output:
None.
Error Conditions:
None.


ui_spread_set_value_label	(widget_id, label )


Description:
In a 3D spreadsheet, sets a spreadsheet layer label.
Input:
widget	widget_id	Must be a spreadsheet.
STRING	label	Label to set.
Output:
None.
Error Conditions:
None.

Comments:

The new label will be truncated if it is larger than the existing space for the layer label.

SWITCH Functions


ui_switch_create	(parent, callback, x, y, num_cols, label, always_one )

Switches exist in either a “regular” mode or an “always one” mode. Most switches are in the “always one” mode, which means that there is always one (and only one) switch item selected at all times. The “always one” switch items do not toggle on⁄off as the “regular” switch items do to select/deselect items.

One way to pick a switch item is to click on it with the mouse. To select a switch item, click anywhere inside its active area. (Switch items may be keyboard-selected using the arrow keys to move from one item to the next, then pressing the space bar.)


Description:
Creates a switch widget.
Input:
widget	parent	Parent widget ID. Must be a frame or a form.
STRING	callback	Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events for this widget are not of interest.
NUMERIC	x	X location of switch in inches relative to parent
NUMERIC	y	Y location of switch in inches relative to parent.
INTEGER	num_cols	Number of columns of items the switch is to have (see Comments section below).
STRING	label	Displayed text to describe switch.
LOGICAL	always_one	TRUE if one item in switch must always be ON. FALSE if it is allowable to have no items selected.
Output:
widget	<Return Value>	Widget ID of switch widget. NULL if not created.
Error Conditions:
None.

Comments:

Items in switches are organized vertically. A switch contains an arbitrary number of item widgets. Only one of the item widgets may be set to ON at any given time; setting an item ON automatically sets all other items for the switch OFF. If always_one is set to FALSE, clicking on an ON item will set it to OFF.

The num_cols parameter does not work intuitively for most values. Motif takes the number of switch items, divides it by num_cols, truncates any remainder and adds one if a remainder was truncated. The resulting value is used as the number of rows. The items are then added to the switch in row-major format. For example, if num_cols is three and four switch items are supplied, the end will be:

1. item 1 item 3

2. item 2 item 4

The PCL callback will be called when a switch item is selected.

TEXT Functions


ui_text_create	(parent, callback, x, y, width, num_rows, label, text, editable, needHScroll)

The textbox is mostly for informational read-only use. However, some textboxes allow the user to input data when appropriate. If the amount of text exceeds the available visible space, use the scroll bar to vertically scroll through the material.


Description:
Create a text widget.
Input:
widget	parent	Parent of the text widget. Must be a frame, a form, a modalform, or a window.
STRING	callback	Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ since text widgets do not register events.
NUMERIC	x	X location of widget in inches relative to parent
NUMERIC	y	Y location of widget in inches relative to parent.
NUMERIC	width	Width of the widget, in inches.
INTEGER	num_rows	Number of rows that will contain the text.
STRING	label	Label to appear with the text widget.
STRING	text	Text string to initially appear in the widget. Include “\n” in the string to indicate a newline.
LOGICAL	editable	TRUE if the user is allowed to edit the text.
LOGICAL	needHScroll	TRUE if horizontal scrollbar is required. Optional and defaults to FALSE.
Output:
widget	<Return Value>	Text widget ID. NULL if text not created.
Error Conditions:
None.

TOGGLE Functions


ui_toggle_create	(parent, callback, x, y, label)

A toggle can only be in one of two states: “TRUE” or “FALSE.” To reverse a toggle’s state, click anywhere in its active area. (If a toggle has focus, the space bar may be used to toggle its value.)


Description:
Creates a toggle widget.
Input:
widget	parent	Parent widget ID. Must be a frame, a form, or a modalform.
STRING	callback	Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events for this widget are not of interest.
NUMERIC	x	X location of toggle in inches relative to parent
NUMERIC	y	Y location of toggle in inches relative to parent.
STRING	label	Label describing toggle.
Output:
widget	<Return Value>	Toggle widget ID. NULL if toggle widget not created.
Error Conditions:
None.

Comments:

The PCL callback function will be called when the user clicks on the toggle.

TOGGLEICON Functions


ui_toggleicon_create	(parent, callback, x, y, icon)


Description:
Creates a toggleicon widget.
Input:
widget	parent	Parent widget ID. Must be a frame, a form, or a modalform.
STRING	callback	Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events for this widget are not of interest. The first space character in the name/callback signifies that the rest of the string value is the pop-up help for the icon, and delimits the preceding string without the space as the name/callback of the widget.
NUMERIC	x	X location of toggle in inches relative to parent
NUMERIC	y	Y location of toggle in inches relative to parent.
STRING	icon	Name of the icon to display describing the toggle.
Output:
widget	<Return Value>	Toggleicon widget ID. NULL if toggleicon widget not created.
Error Conditions:
None.

Tree Widget Functions


ui_tree_create	( parent, callback, x, y, width, height, label, selection_type, options )


Description:
creates a tree view widget
Input:
widget	parent	Parent form or frame containing this tree widget
STRING	callback	Name of the PCL function called for an event in this widget.
REAL	x
REAL	y
REAL	width
REAL	height
STRING	label
STRING	selection_type	One of SINGLE, BROWSE, MULTIPLE, EXTEND
INTEGER	options	Optional and defaults to 0.
Output:
INTEGER	<Return Value>	ID of the widget created. NULL if creation fails.

Example:

The PCL function “callback” must be defined as shown in the example below.

FUNCTION callback( treeWidget, event, callData, userData )

WIDGET treeWidget

STRING  event

WIDGET callData

STRING userData

…

	END FUNCTION

Where:

TreeWidget is the ID of the tree widget that caused the callback event can be one of the following:

EXPANDED

COLLAPSED

SELCHANGED

userdata is the string data set with the ui_wid_set with “CALLBACKDATA” as the parameter.

callData is the information pertaining to the event that triggered this callback. Note that this data is transient and is not valid once the callback returns. It can be queried using ui_tree_calldata_get_count and ui_tree_calldata_get_items (described below) before the call returns to get the affected items.


ui_tree_calldata_get_count	(callData, event, itemCount )


Description:
Retrieves the item count related to the callback from the tree widget
Input:
widget	callData	This is the callData argument passed to the callback
STRING	reason	one of the following EXPANDED, COLLAPSED, SELECTED or UNSELECTED
Output:
INTEGER	itemCount	number of items that changed their state


ui_tree_calldata_get_items	(callData, event, itemCount, items )


Description:
Retrieves the items related to the callback from the tree widget
Input:
widget	callData	This is the callData argument passed to the callback
STRING	event	one of the following EXPANDED, COLLAPSED, SELECTED or UNSELECTED
Output:
INTEGER	itemCount	size of the items array
INTEGER ()	items	virtual array to hold the items that changed their state
INTEGER	<Return Value>	Number of items returned in items array.
		>=0 number items -1 event parameter is not valid -2 not enough memory to return the items.


ui_tree_add_item	( treeWidget, parent, insertAfter, name, image, selectedImage )


Description:
adds an item to the tree widget
Input:
widget	treeWidget
INTEGER	parent
INTEGER	insertafter	ID of the item after which the item will be inserted into the tree =0 item is inserted as the first item of the parent = -1 item is appended to the parent >0 ID of the sibling item after which the new item is inserted if this ID is not a child of the parent then the behavior is undefined.
String	label
INTEGER	image
INTEGER	selectedImage
Output:
INTEGER	<Return Value>	ID of the item created. 0 if creation fails.


ui_tree_add_items	( treeWidget, parent, insertAfter, name, image, selectedImage, nitems )


Description:
adds an item to the tree widget
Input:
widget	treeWidget
INTEGER	nitems
INTEGER()	parent
INTEGER()	insertafter
String[]()	label
INTEGER()	image
INTEGER()	selectedImage
Output:
INTEGER	<Return Value>	ID of the last item created. nitems items are created with this return value being the ID of the last item. Return value of 0 indicates failure.


ui_tree_delete_item	( treeWidget, itemToDelete )


Description:
deletes an item from the tree.
Input:
widget	treeWidget
INTEGER	itemToDelete
Output:
logical	<Return Value>	TRUE if no error.


ui_tree_delete_items	( treeWidget, nitems, itemsArray)


Description:
deletes an item from the tree.
Input:
widget	treeWidget
INTEGER	nitems
INTEGER()	itemsArray
Output:
logical	<Return Value>	TRUE if no error.


ui_tree_select_item	( treeWidget, itemToSelect, selectionFlag )


Description:
selects/deselects an item in the tree.
Input:
widget	treeWidget
INTEGER	itemToSelect
LOGICAL	selectionFlag	TRUE indicates selection FALSE indicates deselection
Output:
logical	<Return Value>	TRUE if no error.


ui_tree_select_items	( treeWidget, itemsArray, nitems, selectionFlag )


Description:
selects/deselects multiple items from the tree.
Input:
widget	treeWidget
INTEGER()	itemsArray
INTEGER	nitems
LOGICAL	selectionFlag	TRUE indicates selection FALSE indicates deselection
Output:
logical	<Return Value>	TRUE if no error.


ui_tree_select_node	( treeWidget, nodeToSelect, selectionFlag )


Description:
selects/deselects a node and all its children in the tree.
Input:
widget	treeWidget
INTEGER	nodeToSelect
LOGICAL	selectionFlag	TRUE indicates selection FALSE indicates deselection
Output:
logical	<Return Value>	TRUE if no error.


ui_tree_expand_item	( treeWidget, itemId, expandOrCollapse)


Description:
expands/collapse an item (that has children) in the tree.
Input:
widget	treeWidget
INTEGER	nodeToSelect
LOGICAL	expandOrCollapse	TRUE indicates expansion FALSE indicates collapse
Output:
logical	<Return Value>	TRUE if no error.


ui_tree_add_image	( treeWidget, imageFile )


Description:
add an image to a tree.
Input:
widget	treeWidget
STRING	imageFile	Name of the file containing the icon data.
Output:
INTEGER	<Return Value>	ID of the created image.


ui_tree_delete_image	( treeWidget, imageId )


Description:
delete an image from a tree.
Input:
widget	treeWidget
INTEGER	imageId	ID of the image obtained from ui_tree_add_image.
Output:
LOGICAL	<Return Value>	TRUE if image was successfully deleted.


ui_treeitem_set_image	( treeWidget, itemId, imageId, selectedImageId )


Description:
set images for a tree item.
Input:
widget	treeWidget
INTEGER	itemId	ID of the item for which images are to be set.
INTEGER	imageId	ID of the image to display in unselected state.
INTEGER	selectedImageId	ID of the image to display in selected state.
Output:
LOGICAL	<Return Value>	TRUE if images were successfully modified.


ui_treeitem_set_label	( treeWidget, itemId, label )


Description:
sets the label for a tree item.
Input:
widget	treeWidget
INTEGER	itemId	ID of the item for which images are to be set.
STRING	label	text to be displayed.
Output:
LOGICAL	<Return Value>	TRUE if the label was successfully modified.


ui_treeitem_get_image	( treeWidget, itemId, imageId, selectedImageId )


Description:
get images for a tree item.
Input:
widget	treeWidget
INTEGER	itemId	ID of the item for which images are to be set.
Output:
INTEGER	imageId	ID of the image to display in unselected state.
INTEGER	selectedImageId	ID of the image to display in selected state.
LOGICAL	<Return Value>	TRUE if images were successfully obtained.


ui_treeitem_get_label	( treeWidget, itemId, label, length )


Description:
Obtains the label for a tree item.
Input:
widget	treeWidget
INTEGER	itemId	ID of the item for which label needs to be returned.
INTEGER	length	size of label string
Output:
STRING	label	text displayed.
LOGICAL	<Return Value>	TRUE if the label was successfully obtained.


ui_treeitem_is_selected	( treeWidget, itemId )


Description:
returns whether a tree item is selected
Input:
widget	treeWidget
INTEGER	itemId	ID of the item for which the information is desired.
Output:
LOGICAL	<Return Value>	TRUE if the item is selected FALSE if the item is not selected or does not exist.


ui_treeitem_is_ expanded	( treeWidget, itemId )


Description:
returns whether a tree item is expanded or collapsed.
Input:
widget	treeWidget
INTEGER	itemId	ID of the item for which the information is desired.
Output:
LOGICAL	<Return Value>	TRUE if the item is expanded. FALSE if the item is collapsed or has no children or does not exist.


ui_tree_set_selection	( treeWidget, itemIds, itemCount )


Description:
replaces the selected items in the tree with the input list
Input:
widget	treeWidget
INTEGER()	itemIds
INTEGER	temCount
Output:
logical	<Return Value>	TRUE if no error.


ui_tree_get_selection	( treeWidget, itemIds, itemCount )


Description:
obtains the list of currently selected items in the tree
Input:
widget	treeWidget
Output:
INTEGER()	itemIds	virtual array to hold the items
INTEGER	itemCount
logical	<Return Value>	TRUE if no error. FALSE if failed to allocate memory.


ui_tree_clear_selection	( treeWidget )


Description:
clears selection. All items in the tree are unselected after this call
Input:
widget	treeWidget
Output:
None.


ui_treeitem_get_parent	( treeWidget, itemId )


Description:
gets the ID of the parent of the item
widget	treeWidget
INTEGER	itemId	ID of the item for which parent needs to be returned.
Output:
INTEGER	<Return Value>	ID of the parent item. –1 if itemId is invalid.


ui_treeitem_get_child_count	( treeWidget, itemId )


Description:
gets the number of children of the item
widget	treeWidget
INTEGER	itemId	ID of the item for which parent needs to be returned.
Output:
INTEGER	<Return Value>	number of immediate children of the item. –1 if itemId is invalid.


ui_treeitem_get_children	( treeWidget, itemId, childIds, childCount )


Description:
gets the ids of the child items of the given parent item
widget	treeWidget
INTEGER	itemId	ID of the item for which parent needs to be returned.
Output:
INTEGER()	childIds	virtual array to hold the child items
INTEGER	childCount
LOGICAL	<Return Value>	TRUE if no error. FALSE if failed to allocate memory.

VERIFY NAME Functions


ui_verify_name	(name)


Description:
Verify whether the given name has the syntax for a valid name.
Input:
STRING	name	Name to verify.
Output:
INTEGER	<Return Value>	= 0 if name is valid. = 1 if name is too long. = 2 if name contains white space. = 3 if name contains a illegal char. = 4 if name is NULL or ““.
Error Conditions:
None.

WIDGET Functions


ui_wid_delete	(wid)


Description:
Delete and destroy the widget.
Input:
widget	wid	Widget to delete and destroy.
Output:
None.
Error Conditions:
None.

Comments:

Removes the widget from memory and destroys it. To delete and destroy a form, modal form, or window use ui_form_delete instead.


ui_wid_exists	(widget)


Description:
Determine whether the given widget exists.
Input:
widget	widget	Widget whose existence is to be queried.
Output:
LOGICAL	<Return Value>	TRUE if widget exists, FALSE if not.
Error Conditions:
None.

WIDGET Functions


ui_wid_get	(widget, parm, value)


Description:
Get the value of a widget parameter.
Input:
widget	widget	Widget whose value is to be queried.
STRING	parm	Name of parameter. Upper or lower case is permitted.
Output:
SEE BELOW	value	Value of parameter.
LOGICAL	<Return Value>	TRUE, if no error.
Error Conditions:
None.

Comments:

The datatype of the return value must be that of the widget's parm. For example, for a call to:

ui_wid_get (button, “ENABLE”, logical_variable)

the third argument must be declared as a logical. For the call

ui_wid_get (button, “NAME”, string_variable)

the third argument must be declared as a string.

Possible parm names:

Button parameters:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is to be displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.
REAL	HEIGHT	Height of the widget.
STRING	LABEL	String that appears in the button.
STRING	NAME	Name of the widget.
REAL	WIDTH	Width of the widget.
REAL	X	X location of widget.
REAL	y	Y location of widget.

Cascade Item parameters:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is to be displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.
STRING	ACCELERATOR	Accelerator key to drop the menu.
STRING	LABEL	Text to be displayed.
STRING	NAME	Name of the widget.
STRING	MNEMONIC	Key mnemonic to drop the menu.

Color Bar parameters:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is to be displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.
INTEGER(2)	ITEMCOLOR	Item color of the widget. The ui_wid_set or ui_wid_get call must be passed an array of size two. The first element of the carry should contain the item number. On a call to ui_wid_set the second element of the array should contain the index of the color desired. A call to the function ui_wid_get will return the color index in the second element.
INTEGER	CURRENTITEM	Currently depressed color button of the colorbar.
INTEGER	NITEMS	Number of color buttons in the colorbar.
STRING	LABEL	Label of the accompanying label widget. Returns a null string if colorbar is not created with a label.

Color Menu parameters:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.
INTEGER	COLOR	Color of the widget.
STRING	LABEL	Label of the accompanying label widget.Returns a null string if colorbar is not created with a label.

Databox and Selectdatabox parameters:


Data Type	Parameter Name	Description
INTEGER	COLUMNS	Width of the widget as the number of visible characters. Valid only for databoxes.
STRING	DATATYPE	Name of the type of data that will be accepted by the databox.
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is to be displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.
	FILTER_ENTITY	Valid only for selectdataboxes.
REAL	HEIGHT	Height of the widget.
STRING	LABEL	Label of the accompanying label widget.
INTEGER	MAXNUMCHARS	Maximum number of characters that can appear in a databox. Valid only for databoxes.
STRING	NAME	Name of the widget.
INTEGER	NUMCHARS	Number of characters in the databox. Valid only for databoxes.
INTEGER	NUMVALS	Number of reals or integers that are in the databox. Valid only for databoxes.
STRING	PROMPT	Prompt to appear in the select menu when the selectdatabox has focus. Valid only for selectdataboxes.
LOGICAL	READONLY	TRUE if the databox can not be edited. Valid only for databoxes.
LOGICAL	SINGLESELECT	TRUE if the selectdatabox should not allow multiple picking. Valid only for selectdataboxes.
LOGICAL	UNSELECT	FALSE if all text is to be selected.
(type defined by the databox's datatype)	VALUE	Current value of the databox.
LOGICAL	WIDSETNOTIFY	TRUE if the widget’s callback will be called for a ui_wid_set(..., “VALUE”,...) call.
REAL	WIDTH	Width of the widget.
REAL	X	X location of widget.
REAL	Y	Y location of widget.

File parameters:


Data Type	Parameter Name	Description
STRING	DIRECTORY	Directory path.
LOGICAL	DISPLAY or VISIBLE	TRUE if the widget is to be displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.
STRING	FILENAME	Name of the file to appear in the file databox.
STRING	FILTER	Value of the directory filter.
STRING	FILTERPATH	Value of the filter databox.
REAL	HEIGHT	Height of the widget.
STRING	NAME	Name of the widget.
REAL	WIDTH	Width of the widget.
REAL	X	X location of widget.
REAL	Y	Y location of widget.

Form and Modalform parameters:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is currectly displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.
REAL	HEIGHT	Height of the widget.
STRING	LABEL	Label to appear in the banner of the form.
STRING	NAME	Name of the widget.
REAL	WIDTH	Width of the form.
REAL	X	X location of form.
REAL	Y	Y location of form.

Frame, Scrollframe, and Selectframe parameters:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if the frame’s children are displayed.
LOGICAL	ENABLE	TRUE if frame’s children are selectable.
REAL	HEIGHT	Height of the widget.
STRING	LABEL	Label accompanying the frame.
STRING	NAME	Name of the widget.
LOGICAL	TOGGLEVALUE	Valid only for selectframes.
REAL	WIDTH	Width of the widget.
	WORKINGHEIGHT	Valid only for scrollframes.
	WORKINGWIDTH	Valid only for scrollframes.
REAL	X	X location of widget.
REAL	y	Y location of widget.

Item parameters:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if widget is currently displayed. Invalid for listbox items.
CHAR	ACCELERATOR	Character used with the <control> key to assign the item’s accelerator. Invalid for listbox items.
LOGICAL	ENABLE	TRUE if this widget is selectable. Not valid for listbox items.
STRING	LABEL	String describing the item.
CHAR	MNEMONIC	Character used to enable the item’s mnemonic. Invalid for listbox items.
STRING	NAME	Name of the widget.
LOGICAL	VALUE	Value of the widget. Invalid for menu bar items and menu items which are not toggles.

Label parameters:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is to be displayed.
LOGICAL	ENABLE	TRUE if the label is in bold print.
REAL	HEIGHT	Height of the widget.
STRING	LABEL	Text to be displayed. Valid only for widgets created with ui_label_create.
STRING	NAME	Name of the widget.
REAL	WIDTH	Width of the widget.
REAL	X	X location of widget.
REAL	y	Y location of widget.

Listbox parameters:


Data Type	Parameter Name	Description
STRING	BOTTOMITEM	Label of the item to appear at the bottom of the listbox.
INTEGER	BOTTOMPOS	Number of the item to appear at the bottom of the listbox.
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is to be displayed.
LOGICAL	DEFAULTEVENT	TRUE if the recent callback was due to a Return or Enter key pressed when selection type is “SINGLE”.
LOGICAL	DUPLICATEITEM	TRUE if this listbox allows items having the same value to appear more than once.
LOGICAL	ENABLE	TRUE if this widget is selectable.
REAL	HEIGHT	Height of the widget.
STRING ARRAY	ITEMS	All items in the listbox whether selected or not selected.
STRING	LABEL	Label to describe the listbox.
STRING	NAME	Name of the widget.
INTEGER	NITEMS	Number of items in widget.
INTEGER	NSELECTED	Number of items selected in widget.
INTEGER	ROWS	Number of rows that can be visible in the displayed listbox.
STRING	SELECTIONTYPE	“SINGLE”, “MULTIPLE”, “BROWSE”, “EXTEND”, or “READONLY”.
STRING	TOPITEM	Label of the item to appear at the top of the listbox.
STRING ARRAY	VALUE	Selected items of the widget.
REAL	WIDTH	Width of the widget.
REAL	X	X location of widget.
REAL	Y	Y location of widget.

Menu and Popup Menu parameters:


Data Type	Parameter Name	Description
LOGICAL	ENABLE	TRUE if this widget is selectable.
STRING	LABEL	Label of the menu.
INTEGER	MNEMONIC	Character that assigns the mnemonic to the menu.
REAL	X	X location of popup menu.
REAL	y	Y location of popup menu.

Menubar parameters:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if the widget is to be displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.

Optionmenu parameters:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.
STRING	LABEL	Label of the optionmenu.
STRING	NAME	Name of the optionmenu.
STRING	VALUE	Currently displayed name of the optionmenu.
REAL	X	X location of widget.
REAL	y	Y location of widget.

Popup Menu parameters:

See Menu and Popup Menu parameters:, 401.

Selectdatabox parameters:

See Databox and Selectdatabox parameters:, 396.

Separator:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is displayed.
REAL	HEIGHT	Height of the widget.
REAL	WIDTH	Width of the widget.
REAL	X	X location of widget.
REAL	y	Y location of widget.

Slidebar parameters:


Data Type	Parameter Name	Description
INTEGER	DECPOINTS	Number of digits to appear after the decimal point. Used only when show_value (see ui_slidebar_create, 356) is TRUE.
LOGICAL	DISPLAY or VISIBLE	TRUE if the widget is to be displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.
REAL	HEIGHT	Height of the widget.
STRING	LABEL	Label of the slidebar.
STRING	MAXLABEL	Label at the upper end of the slidebar.
STRING	MINLABEL	Label at the lower end of the slidebar.
STRING	NAME	Name of the widget.
REAL	VALUE	Value of the widget.
REAL	WIDTH	Width of the widget.
REAL	X	X location of the widget.
REAL	Y	Y location of the widget.

Spreadsheet:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if the widget is to be displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.
STRING	LABEL	Label of the spreadsheet.
INTEGER	NITEMS	Number of rows in spreadsheet widget

Switch parameters:


Data Type	Parameter Name	Description
INTEGER	COLUMNS	Number of columns of items that the switch should contain.
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is to be displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.
STRING	LABEL	Label of the widget.
STRING	NAME	Name of the widget.
STRING	VALUE	Name of the item that is currently on.
REAL	X	X location of the widget.
REAL	Y	Y location of the widget.

Text:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is displayed.
LOGICAL	EDITABLE	TRUE if the user can type in the widget.
LOGICAL	ENABLE	TRUE if this widget is selectable.
REAL	HEIGHT	Height of the widget.
INTEGER	MAXNUMCHARS	Maximum number of characters that can be entered into the widget.
STRING	NAME	Name of the widget.
INTEGER	NUMCHARS	Number of characters in the text box.
INTEGER	POSITION	Location of the insertion bar in the text box.
STRING	VALUE	Text that appears in the widget.
REAL	WIDTH	Width of the widget.
REAL	X	X location of the widget.
REAL	Y	Y location of the widget.

Toggle parameters:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is to be displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.
STRING	LABEL	Label that describes the toggle.
STRING	NAME	Name of the widget.
LOGICAL	VALUE	Value of the widget.
REAL	WIDTH	Width of the widget.
REAL	X	X location of the widget.
REAL	Y	Y location of the widget.

Window parameters:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is currently displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.
REAL	HEIGHT	Height of the widget.
STRING	LABEL	String to appear in the window’s namestripe.
STRING	NAME	Name of the window.
REAL	WIDTH	Width of the widget.
REAL	X	X location of the widget.
REAL	Y	Y location of the widget.

WIDGET Functions


ui_wid_get_vstring	(widget, parm, vstr )


Description:
Get the value of a widget's string parameter and return the value in a virtual string.
Input:
widget	widget	Widget whose value is to be queried.
STRING	parm	Name of parameter. Upper or lower case is permitted
Output:
STRING	[VIRTUAL] vstr	Value of string parameter.
Error Conditions:
None.

Comments:

All parameter names from ui_wid_get() that return a string are valid.


ui_wid_refresh	( )


Description:
Calls the refresh function for all classes with forms currently visible.
Input:
None.
Output:
None.
Error Conditions:
None.

Comments:

Used to keep the contents of widgets up-to-date when events occur which might change the information displayed on a form. Normally ui_wid_refresh is called at the end of a callback which adds, modifies or removes an entity from the database.

The refresh function in a class should update the contents of the displayed widgets which might change from actions on unrelated forms.

WIDGET Functions


ui_wid_restore	(class_name )


Description:
Restores the values of all of the widgets in the class class_name to the values assigned due to the last call to ui_wid_save (class_name).
Input:
STRING	class_name	Name of the form’s class.
Output:
LOGICAL	<Return Value>	TRUE if no error.
Error Conditions:
None.

Comments:

The widget values restored are those last saved using the ui_wid_save function. If used in conjunction with a ui_form_hide(), do the hide first, then the restore, to avoid flicker.


ui_wid_save	(class_name )


Description:
Saves the values of all of the widgets in the class class_name.
Input:
STRING	class_name	Name of the form’s class.
Output:
LOGICAL	<Return Value>	TRUE if no error.
Error Conditions:
None.

Comments:

The widget values saved using this function can be restored back into the form using ui_wid_restore. If used in conjunction with a ui_form_hide(), do the hide first, then the save, to avoid flicker.

WIDGET Functions


ui_wid_set	(widget_id, parameter_name, parameter_value)


Description:
This function will set a widget parameter value.
Input:
widget	widget_id	This value specifies the identifier of the widget that will be modified.
STRING	parameter_name[]	This value specifies the name of the parameter to be modified. See below for more information.
DYNAMIC_ILRS	parameter_value	This value specifies the array of flags used to identify the specific entity types to be exported. See the remarks below for more information.
Output:
LOGICAL	<Return Value>	This function returns a value of TRUE when executed successfully and a non TRUE value to indicate a change in status or an error.
Error Conditions:
This function may return a nonzero value if an error occurs.

Remarks:

The data type of the input value parameter_value must match the data type specified for the input value paramter_name as listed in the tables below. The parameter names that can be used and the functions used to create the widgets with which they can be used are listed in the tables below.

Button parameters:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is to be displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.
REAL	HEIGHT	Height of the widget.
STRING	LABEL	Text to be displayed.
STRING	NAME	Name of the widget.
REAL	WIDTH	Width of the widget.
REAL	X	X location of widget.
REAL	y	Y location of widget.

Cascade Item parameters:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is to be displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.
STRING	ACCELERATOR	Accelerator key to drop the menu.
STRING	LABEL	Text to be displayed.
STRING	NAME	Name of the widget.
STRING	MNEMONIC	Key mnemonic to drop the menu.

Color Bar parameters:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.
INTEGER(2)	ITEMCOLOR	Item color of the widget. The ui_wid_set or ui_wid_get call must be passed an array of size two. The first element of the carry should contain the item number. On a call to ui_wid_set the second element of the array should contain the index of the color desired. A call to the function ui_wid_get will return the color index in the second element.
INTEGER	CURRENTITEM	Currently depressed color button of the colorbar.
INTEGER	NITEMS	Number of color buttons in the colorbar.
STRING	LABEL	Label of the accompanying label widget. Invalid if colorbar is not created with a label.

Color Menu parameters:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is to be displayed.
INTEGER	COLOR	Color of the widget.
STRING	LABEL	Label of the accompanying label widget. Invalid if colorbar is not created with a label.
REAL	WIDTH	Width of the widget.
REAL	HEIGHT	Height of the widget.

Databox and Selectdatabox parameters:


Data Type	Parameter Name	Description
STRING	APPENDVALUE	Append the string onto the current value.
INTEGER	COLUMNS	Width of the widget as the number of visible characters. Valid only for databoxes.
STRING	DATATYPE	Name of the type of data that will be accepted by the databox.
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is to be displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.
	FILTER_ENTITY	Valid only for selectdataboxes.
REAL	HEIGHT	Height of the widget.
STRING	LABEL	Label of the databox.
INTEGER	MAXNUMCHARS	Upper limit of characters allowed in the databox. Valid only for databoxes.
STRING	NAME	Name of the widget.
STRING	PROMPT	Prompt to be displayed when the selectdatabox has focus and if the datatype displays a selection menu. Valid only for selectdataboxes.
	READONLY	Valid only for databoxes.
LOGICAL	SINGLESELECT	Used only for selectdataboxes. TRUE for the selectdatabox if only one pick is to appear in the selectdatabox.
LOGICAL	UNSELECT	FALSE if all text is to be selected.
(type defined by the databox's datatype)	VALUE	Current value of the databox.
LOGICAL	WIDSETNOTIFY	TRUE if the callback function is to be called for ui_wid_set calls.
REAL	WIDTH	Width of the widget.
REAL	X	X location of widget.
REAL	Y	Y location of widget.

File Parameters:

See the ui_file_create, 309 function description for more information.


Data Type	Parameter Name	Description
STRING	CANCELBUTTONLABEL	This value specifies the text used to label the “Cancel” button. See the input value cancel_label in the ui_file_create() function description for more information.
STRING	DIRECTORY	This value specifies the path which is used together with the filter mask specified with the input variable parameter_name value FILTER to determine which files and directories are displayed in the form. See the parameter_name value FILTERPATH for more information. See the input value filter_mask in the ui_file_create() function description for more information.
LOGICAL	ENABLE	This value specifies, when set to TRUE, that the file form can be selected, is active, and can be used for input. If this value is set to FALSE, the form will be grayed out and cannot be selected and used for input.
STRING	FILENAME	This value specifies a file name to be displayed in the selection databox. If the file name specified is listed in the file list box the file list box entry will be highlighted. See the input value file_name in the ui_file_create() function description for more information.
STRING	FILENAMELABEL	This value specifies the text used on the form to describe the selection databox. See the input value selection_label in the ui_file_create() function description for more information.
STRING	FILESLABEL	This value specifies the text used on the form to describe the files databox. See the input value files_label in the ui_file_create() function description.
STRING	FILTER	This value specifies the filter mask which is used together with the path specified with the input variable parameter_name value DIRECTORY to determine which files and directories are displayed in the form. See the parameter_name value FILTERPATH for more information.See the input value filter_mask in the ui_file_create() function description for more information.
STRING	FILTERBUTTONLABEL	This value specifies the text used to label the “Filter” button. See the input value filterbutton_label in the ui_file_create() function description.
STRING	FILTERLABEL	This value specifies the title used on the form to describe the filter databox. See the input value filter_label in the ui_file_create() function description.
STRING	FILTERPATH	This value sets the path and filter mask value in the filter databox and determines what will be displayed in the directory and files databoxes. This parameter_name value combines the operations of the parameter_name values DIRECTORY and FILTER. See the input value filter_mask in the ui_file_create() function description for more information.
REAL	HEIGHT	This value specifies the height of the widget in inches, excluding the border.
STRING	NAME	This value specifies the name of the PCL function that will be called for an event representing a form event. This call back function must be a member of the class in which the ui_file_create() widget is created. See the input value callback_func in the ui_file_create() function description for more information.
STRING	OKBUTTONLABEL	This value specifies the text used to label the “OK” button. See the input value ok_label in the ui_file_create() function description for more information.
STRING	WIDTH	This value specifies the width of the widget in inches, excluding the border. See the input value width in the ui_file_create() function description for more information.
REAL	X	This value specifies the x axis location of the file widget in inches relative to the upper left corner of the parent widget. See the input value x_location in the ui_file_create() function description for more information.
REAL	Y	This value specifies the y axis location of the file widget in inches relative to the upper left corner of the parent widget. See the input value y_location in the ui_file_create() function description for more information.

Form and modalform parameters:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is currently displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.
REAL	HEIGHT	Height of the widget.
STRING	LABEL	Label to appear in the banner of the form.
STRING	NAME	Name of the widget.
REAL	WIDTH	Width of the widget.
REAL	X	X location of widget.
REAL	y	Y location of widget.

Frame, Scrollframe, and Selectframe parameters:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if the frame’s children that have been specifically left ON via a ui_wid_set() are to be displayed.
LOGICAL	DISPLAYALL or VISIBLEALL	TRUE if the frame’s children are to be displayed regardless of whether the children have been displayed or hidden via a ui_wid_set().
LOGICAL	ENABLE	TRUE if frame’s children are to be selectable.
REAL	HEIGHT	Height of the widget.
STRING	LABEL	String to appear above the frame.
STRING	NAME	Name of the widget.
LOGICAL	TOGGLEVALUE	Valid only for selectframes.
REAL	WIDTH	Width of the widget.
	WORKINGHEIGHT	Valid only for scrollframes.
	WORKINGWIDTH	Valid only for scrollframes.
REAL	X	X location of widget.
REAL	y	Y location of widget.

Item parameters:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if widget is currently displayed. Invalid for listbox items.
CHAR	ACCELERATOR	Specifies CRTL<char> sequence to invoke item. Item need not be visible for accelerator to work. Invalid for listbox items.
LOGICAL	ENABLE	TRUE if this widget is selectable. Not valid for listbox items.
STRING	ICON	Name of the icon used in lieu of the label. See ui_itemicon_create, 326.
STRING	LABEL	Text to be displayed.
CHAR	MNEMONIC	Specifies key to invoke item. Item must be visible for mnemonic to work. Only valid for menu items.
STRING	NAME	Name of the widget.
LOGICAL	VALUE	Value of the widget. Invalid for menu bar items.

Label parameters:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is to be displayed.
LOGICAL	ENABLE	TRUE if the label is in bold print.
REAL	HEIGHT	Height of the widget.
STRING	ICON	Name of the icon to be displayed in lieu of the label. Valid only for widgets created with ui_labelicon_create.
STRING	LABEL	Text to be displayed.
STRING	NAME	Name of the widget.
REAL	WIDTH	Width of the widget.
REAL	X	X location of widget.
REAL	y	Y location of widget.

Listbox parameters:


Data Type	Parameter Name	Description
STRING	BOTTOMITEM	Label of the item that is to be the bottom visible item.
INTEGER	BOTTOMPOS	Number of the items to appear at the bottom of the listbox.
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is to be displayed.
LOGICAL	DUPLICATEITEM	TRUE if this listbox allows items having the same value to appear more than once.
LOGICAL	ENABLE	TRUE if this widget is selectable.
REAL	HEIGHT	Height of the widget.
STRING	LABEL	Label to describe the listbox.
STRING	NAME	Name of the listbox.
INTEGER	ROWS	Number of rows that can be visible in the displayed listbox.
STRING	SELECTIONTYPE	Selection type of the listbox. “SINGLE”, “MULTIPLE”, “BROWSE”, “EXTEND”, or “READONLY”.
STRING	TOPITEM	Label of the item that is to be the top visible item.
STRING ARRAY	VALUE	Selected items of the widget.
REAL	WIDTH	Width of the widget.
REAL	X	X location of widget.
REAL	Y	Y location of widget.
LOGICAL	UNSELECT	FALSE if all items are to be selected.

Menu and Popup Menu parameters:


Data Type	Parameter Name	Description
LOGICAL	ENABLE	TRUE if this widget is selectable.
STRING	LABEL	Label of the menu.
CHAR	MNEMONIC	Specifies key to invoke menu.
REAL	X	X location of popup menu widget.
REAL	y	Y location of popup menu widget.

Menubar parameters:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is to be displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.

Optionmenu parameters:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is to be displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.
STRING	LABEL	Label of the optionmenu.
STRING	NAME	Name of the optionmenu.
STRING	VALUE	Currently displayed item label of the optionmenu.
REAL	X	X location of widget.
REAL	y	Y location of widget.

Popup Menu parameters:

See Menu and Popup Menu parameters:, 415.

Selectdatabox parameters:

See Databox and Selectdatabox parameters:, 409.

Separator:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is displayed.
REAL	HEIGHT	Height of the widget.
REAL	WIDTH	Width of the widget.
REAL	X	X location of widget.
REAL	y	Y location of widget.

Slidebar parameters:


Data Type	Parameter Name	Description
INTEGER	DECPOINTS	Number of digits to appear after the decimal point. Used only when show_value (see ui_slidebar_create, 356) is TRUE.
LOGICAL	DISPLAY or VISIBLE	TRUE if the widget is to be displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.
STRING	LABEL	Text to be displayed.
STRING	MAXLABEL	Label at the upper end of the slidebar.
REAL	MAXVALUE	Maximum allowable value.
STRING	MINLABEL	Label to appear at the lower end of the slidebar.
REAL	MINVALUE	Minimum allowable value.
STRING	NAME	Name of the widget.
REAL	VALUE	Value of the widget.
REAL	X	X location of the widget.
REAL	Y	Y location of the widget.

Spreadsheet:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if the widget is currently displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.
STRING	LABEL	Main label to be displayed with the widget.
LOGICAL	UNSELECT	TRUE to unselect all cells. FALSE does nothing.

Switch parameters:


Data Type	Parameter Name	Description
INTEGER	COLUMNS	Number of columns of items that the switch should contain.
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is to be displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.
STRING	LABEL	Label to be displayed with the widget.
STRING	NAME	Name of the widget.
STRING	VALUE	Name of the item that is currently on. If “NONE”, all switch items will be turned OFF.
REAL	X	X location of the widget.
REAL	Y	Y location of the widget.

Text:


Data Type	Parameter Name	Description
STRING	APPENDVALUE	String to append onto the current value.
LOGICAL	DISPLAY or VISIBLE	TRUE if the widget is currently displayed.
LOGICAL	EDITABLE	TRUE if the user may alter the text value.
LOGICAL	ENABLE	TRUE if this widget is selectable.
REAL	HEIGHT	Height of the widget.
INTEGER	MAXNUMCHARS	Maximum number of characters that can be contained in the widget.
STRING	NAME	Name of the widget.
INTEGER	POSITION	Location of the insertion bar in the text box.
LOGICAL	UNSELECT	FALSE if all text is to be selected.
STRING	VALUE	Text that appears in the widget. To include a newline character, place “\n” in the string.
REAL	WIDTH	Width of the widget.
REAL	X	X location of the widget.
REAL	Y	Y location of the widget.

Toggle parameters:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is currently displayed.
LOGICAL	ENABLE	TRUE if this widget is selectable.
STRING	ICON	Name of icon to be used, valid only when created with ui_toggleicon_create.
STRING	LABEL	Text to be displayed to describe the toggle.
STRING	NAME	Name of the widget.
LOGICAL	VALUE	Value of the widget.
REAL	WIDTH	Width of the widget.
REAL	X	X location of the widget.
REAL	Y	Y location of the widget.

Window parameters:


Data Type	Parameter Name	Description
LOGICAL	DISPLAY or VISIBLE	TRUE if this widget is currently displayed.
LOGICAL	ENABLE	TRUE if this window is selectable.
REAL	HEIGHT	Height of the widget.
STRING	LABEL	String to appear in the window’s banner.
STRING	NAME	Name of the window.
REAL	WIDTH	Width of the widget.
REAL	X	X location of the widget.
REAL	Y	Y location of the widget.