Sei sulla pagina 1di 20

Chapter 6: User Interface Functions Application Authors Guide

User Interface Functions


Main Panel Buttons 111 116 117 106

Dialog Box Inputs Box

106 Application Authors Guide


Main Panel

Main Panel
AAUI.mainpanel_include_steps
Description: This function will display the analysis steps in the main step selection box. It is called by the function AAI.allsteps_display() which reads the drive pages and obtains the information to display. Input: INTEGER STRING num_steps step_ids[4](num_steps) This value specifies the number of analysis steps to create switch items for. This value specifies the step ids or labels for the switch items. Note: multi-byte characters are NOT allowed for step ids. This value specifies whether a step is completed or not. The single character values will be a blank, a C or an X indicating not tested yet, completed, or completion test failed respectively. This value specifies the descriptions assigned to the steps. (num_steps, step_ids, completed, step_names)

STRING

completed[1](num_steps)

STRING Output:

step_names[36](num_steps)

Error Conditions: None


Remarks:

Note that the application author is not expected to make this call. The function AAI.allsteps_display is typically called upon completion of analysis step-1 after the NEXTPAGE user response variable is recorded.
Example:

None

Chapter 6: User Interface Functions 107


Main Panel

AAUI.mainpanel_current_step
Description:

(step_id)

This function will provide the step id label for the current step as selected on the UI main panel. If no step is currently selected, the value returned will be the last step that was previously selected. Input: Output: STRING None.
Remarks:

step_id[4]

This value returns the current step id.

Error Conditions:

None
Example:

None

AAUI.mainpanel_step_complete
Description:

(step_id, complete)

This function will change the display of the completeness indicator for an analysis step displayed in the main step selection box. Input: STRING STRING step_id[4] complete[1] This value specifies the step id that will be modified. This value specifies the value the completion indicator will be set to. The values (blank), C or X are expected in normal practice.

Output: Error Conditions: None.


Remarks:

Note that calling this function changes the main panel display only. Usually an additional call to AASTATE.record_ur_string, 88 is also made to record the completion indicator in the State Table.

108 Application Authors Guide


Main Panel

Example:

None.

AAUI.mainpanel_lock_steps
Description:

()

This function will disable the main step selection box widget so that a user cannot make a new step selection. This is useful to force the completion of one step before another can be selected. Input: Output: Error Conditions: None.
Remarks:

Note that a call to AAUI.mainpanel_step_complete, 107 will not successfully change the display while steps are locked. Steps must be unlocked before changing the display.
Example:

None

AAUI.mainpanel_unlock_steps
Description:

()

This function will reverse the action of the lock_steps function, enabling the main step selection box switches to be selected. Unlocking also enables any subsequent display change of completion indicators. Input: Output: Error Conditions: None.
Remarks:

None
Example:

None

Chapter 6: User Interface Functions 109


Main Panel

AAUI.mainpanel_unselect_steps
Description:

()

This function will change the state of the main step selection box switch widget to a null state, so that no analysis step is currently selected. Input: Output: Error Conditions: None.
Remarks:

This call is typically made as part of a step_wrapup() function at the conclusion of each analysis step. It is also useful to call in conjunction with an error dialog that excludes the user from executing the selected step.
Example:

None

AAUI.switch_highlight
Description:

(step_id)

This function selects a step on the UI form main step selection box in an automated mode. This is a software method of selecting a step as opposed to having the user select the step manually. Input: STRING Output: INTEGER Error Conditions: None.
Remarks:

step_id[4]

This value specifies the step id that will be highlighted. This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.

A good use for this function is to create an automatic process which cycles until a particular condition has been satisfied. Alternatively, the author may choose to write applications with all automated step selection. In this case, the step selection box serves as a status indicator only.

110 Application Authors Guide


Main Panel

Example:

None

AAUI.switch_highlight_restorer
Description:

(step_id)

This function is automatically called by the platform software upon re-opening an existing database. This function automatically selects the correct step for continuing, and precisely the next dialog for the user to act upon. Input: STRING Output: INTEGER Error Conditions: None.
Remarks:

step_id[4]

This value specifies the step id that will be highlighted. This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.

The application author is not expected to use this function call. The platform software automatically invokes this call upon re-opening of an existing database. See the function AAUI.switch_highlight, 109 for automated cycling through steps.
Example:

None

Chapter 6: User Interface Functions 111


Buttons

Buttons
AAUI.sthelp_helpcb
Description: This function will be called as part of the call back from the Help button. It will call
AAI.step_help_doc, 130 in order to display a help document in the Browser.

()

Input: Output: Error Conditions: None.


Remarks:

The application author is not expected to use this call.


Example:

None.

AAUI.helpdoc_display
Description:

(doc_URL)

This function will display any specified HTML document available on the file system, or display any http: URL address. Input: STRING doc_URL[] This value specifies the path or URL address for the document to be displayed by the commercial browser that is used for auxiliary display.

Output: Error Conditions: None.


Remarks:

This call spawns the auxiliary HTML browser display as a separate process. Once initiated there is no further communication available to change the browser display or to close the process.

112 Application Authors Guide


Buttons

The format for the doc_URL argument can reference either a local file (relative or absolute path) or a http address. For relative path references, the home drive page directory defined by the environment variable ACUMEN_APPLICATIONS is appended onto the beginning of the relative path. Important: Because of parsing issues, the format for http references needs to be http_//www.... instead of http://www..... Example of a relative path for doc_URL:
AAUI.helpdoc_display(helpdocs/st2help.html)

Example of an absolute path for doc_URL:


AAUI.helpdoc_display(d:/testing/step_test/helpdocs/st2help.html)

Example of a web address for doc_URL:


AAUI.helpdoc_display(http_//www.macsch.com/helpdocs/st2help.html)

AAUI.quickreview_quickcb
Description:

()

This function will post the Quick Review form to the screen. This is called as part of the callback from the Quick Review button. The Quick Review form displays user response variables from the State Table as indicated by the <uresponse> tags for each analysis step. Input: Output: Error Conditions: None.
Remarks:

The application author is not expected to make this call.


Example:

None

Chapter 6: User Interface Functions 113


Buttons

AAUI.quit_quitcb
Description:

()

This function will close down the MSC Acumen GUI. This is called as part of the callback for the Quit button. Input: Output: Error Conditions: None.
Remarks:

This call is also useful as a method to close down the application from a hyertext link selection. This method of quitting is preferred over the MSC Patran built-in PCL call to close down the database and quit, because it also provides for storing the current contents of the memory State Table to the modeling database before shutting down.
Example:

None

AAUI.backup_backupcb
Description:

()

This function will cause the dialog to back up to the previous dialog. This call is made as part of the callback to the Dialog Backup button. Input: Output: INTEGER Error Conditions: None.
Remarks:

This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.

The application author is not expected to make this call.

114 Application Authors Guide


Buttons

Example:

None

AAUI.backup_status
Description:

(backup)

This function will indicate whether or not a backup action is in progress. Input: Output: LOGICAL backup This value returns TRUE if the dialog backup action is in progress, or a FALSE if a dialog backup action is not in progress.

Error Conditions: None.


Remarks:

A call to this function indicates whether or not the current dialog arrived at through action of the Dialog Backup button. Note that functions indicated as the value of an undo attribute to the <dialog> tag are automatically executed upon a Dialog Backup action. The platform software uses this interface call to determine such backup status. As soon as the new dialog is displayed, then a AAUI.notify_backup_done, 114 call is automatically made.
Example:

None

AAUI.notify_backup_done
Description:

()

This function will reset the backup status to FALSE, so any subsequent call to AAUI.backup_status() will return FALSE. Input: Output: Error Conditions: None.

Chapter 6: User Interface Functions 115


Buttons

Remarks:

The application author is not expected to use this call.


Example:

None.

AAUI.backup_enable
Description:

(on_off)

This function provides a mechanism for independent enabling and disabling of the UI form "Dialog Backup" button. Use this function to guard against <dialog> backup actions within a step where the workflow sequence is not designed to support a backup. Input: STRING on_off[] If this value is "ON" then the Dialog Backup button is enabled so that a user can select it. If this value is "OFF" (actually any value other than "ON") then the button is disabled so that no backup action selection is possible.

Output: Error Conditions: None.


Remarks:

Use of this function is recommended only as an exception to normal operation. Note that the "Dialog Backup" button is automatically enabled upon step selection and display of the first step <dialog>. The button is automatically disabled at the termination of a step when the AAUI.mainpanel_unselect_steps() call is made.
Example:

Following is an example of how a call to this function which disables backups is made in the initftn attribute of a <dialog>. <dialog dlgid="first" inputid="null" initftn="FUNC:AAUI.backup_enable;STR:off" ...

116 Application Authors Guide


Dialog Box

Dialog Box
AAUI.dialog_put_text
Description: This function will display the HTML data in the UI form dialog box widget. Input: STRING Output: Error Conditions: None.
Remarks:

(HTML_text)

HTML_text[]

This value specifies the HTML data in the form of <HTML> ....insert your text here.... </HTML>.

The application author is discouraged from using this lower level interface call. Please see the AAI.next_dialog, 131 and AAI.dynamic_next_dialog, 132 functions as methods for displaying HTML listed with drive page <dialog> tags.
Example:

None

Chapter 6: User Interface Functions 117


Inputs Box

Inputs Box
AAUI.inputs_refresh
Description: This function will display the required user input widgets in the Inputs Box and prepare the PCL function associated with input_id. This call is made automatically by the platform software when a new <dialog> is obtained. Input: STRING Output: Error Conditions: None.
Remarks:

(input_id)

input_id[32]

This value specifies the index id located in the function definitions file.

The application author is not expected to make this call.


Example:

None

AAUI.inputs_applycb
Description:

()

This function will call the function referenced by the inputid index on the functions definitions text file. This call is made as part of the callback to the Apply Inputs button. Input: Output: INTEGER Error Conditions: None.
Remarks:

This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.

The application author is not expected to make this call.

118 Application Authors Guide


Inputs Box

Example:

None.

AAUI.selectdatabox_read_raw
Description:

(num_select_databox, vstring)

This function will return the value in the specified select databox that is displayed in the UI form Inputs area. Input: INTEGER num_select_databox This value specifies which displayed select databox to read data from. 1 for the first select databox displayed, 2 for the second select databox displayed, etc. This value returns the data in the specified select databox. The memory is allocated with in this function. This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.

Output: STRING INTEGER vstring[VIRTUAL]

Error Conditions: None.


Remarks:

This is an auxiliary utility function that may be used inside of a custom PCL function that is called by the Apply Inputs action. This method of obtaining data is in addition to the normal call sequence argument value passing.
Example:

None.

AAUI.selectdatabox_read_ids
Description:

(num_select_databox, num_ids, ids)

This function will process data that is displayed in a select databox on the Inputs area of the UI form. It will return the ids of the entities selected. It is only supported for specific data types, like Point, Node, Element, Curve, Surface, Solid. Duplicate entries are eliminated. Input:

Chapter 6: User Interface Functions 119


Inputs Box

INTEGER

num_select_databox

This value specifies the displayed select databox to read data from. 1 for the first select databox displayed, 2 for the second select databox displayed, etc. This value returns the number of id values returned. This value returns the ids. The memory is allocated within this function. This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.

Output: INTEGER INTEGER INTEGER num_ids ids(VIRTUAL)

Error Conditions: None. Remarks: This is an auxiliary utility function that may be used inside of a custom PCL function that is called by the Apply Inputs action. This method of obtaining data is in addition to the normal call sequence argument value passing. Example: None.

AAUI.selectdatabox_read_coords

(num_select_databox, num, x_comp, y_comp, z_comp)

Description: This function will process data that is displayed in a select databox on the Inputs area of the UI form. It will return the global coordinate positions for either Nodes or Points that were screen selected and displayed in a select databox. Input: INTEGER num_select_databox This value specifies the displayed select databox to read data from.1 for the first select databox displayed, 2 for the second select databox displayed, etc. This value returns the number of coordinates returned. This value returns the X coordinate values. The memory is allocated within this function.

Output: INTEGER REAL num x_comp(VIRTUAL)

120 Application Authors Guide


Inputs Box

REAL REAL INTEGER

y_comp(VIRTUAL) z_comp(VIRTUAL)

This value returns the Y coordinate values. The memory is allocated within this function. This value returns the Z coordinate values. The memory is allocated within this function. This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.

Error Conditions: None


Remarks:

This is an auxiliary utility function that may be used inside of a custom PCL function that is called by the Apply Inputs action. This method of obtaining data is in addition to the normal call sequence argument value passing.
Example:

None

AAUI.selectdatabox_assread_raw

(num_select_databox, entity, parent, entity_type, assoc_entities)

Description: This function will return a list of all entities associated with the parent entities that were selected in the select databox. Input: INTEGER num_select_databox This value specifies the displayed select databox to read data from.1 for the first select databox displayed, 2 for the second select databox displayed, etc. This value specifies the desired entity type. The supported values are: curve, elem, node, point and surface. This value specifies the general type of entities contained by the select databox. The supported values are: geo, and elem. This value specifies the element shape to filter on when the entity is set to elem. Otherwise it is ignored. See the remarks below for more information.

STRING

entity[]

STRING

parent[]

INTEGER

entity_type

Output:

Chapter 6: User Interface Functions 121


Inputs Box

STRING INTEGER

assoc_entities[VIRTUAL]

This value returns a pick list of entities that match the given criteria. This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.

Error Conditions: None.


Remarks:

This is an auxiliary utility function that may be used inside of a custom PCL function that is called by the Apply Inputs action. This method of obtaining data is in addition to the normal call sequence argument value passing. The input value entity_type controls which element type will be returned. This data is only used when the entity is set to elem. The following table identifies the entity type for each value.: Value 0 1 2 3 4 5 6 7 8
Example:

Entity type Any Element Point Element Beam Element Tri Element Quad Element Tet Element Wedge Element (not used) Hex Element

None

122 Application Authors Guide


Inputs Box

AAUI.selectdatabox_assread_ids

(num_select_databox, entity, parent, entity_type, num_ids, ids)

Description: This function will return all the entity ids associated with the parent entities in the select databox. Input: INTEGER num_select_databox This value specifies the displayed select databox to read data from.1 for the first select databox displayed, 2 for the second select databox displayed, etc. This value specifies the desired entity type. The supported values are: curve, elem, node, point and surface. This value specifies the general type of entities contained by the select databox. The supported values are: geo, and elem. This value specifies the element shape to filter on when the entity is set to elem. Otherwise it is ignored. See the remarks below for more information. This value returns the number of id values returned. This value returns the ids. The memory is allocated within this function. This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.

STRING

entity[]

STRING

parent[]

INTEGER

entity_type

Output: INTEGER INTEGER INTEGER num_ids ids(VITRUAL)

Error Conditions: None.


Remarks:

This is an auxiliary utility function that may be used inside of a custom PCL function that is called by the Apply Inputs action. This method of obtaining data is in addition to the normal call sequence argument value passing. The input value entity_type controls which element type will be returned. This data is only used when the entity is set to elem.

Chapter 6: User Interface Functions 123


Inputs Box

The following table identifies the entity type for each value: Value 0 1 2 3 4 5 6 7 8
Example:

Entity type Any Element Point Element Beam Element Tri Element Quad Element Tet Element Wedge Element (not used) Hex Element

None

AAUI.selectdatabox_assread_coords

(num_select_databox, entity, parent, num, x_comp, y_comp, z_comp)

Description: This function will return the global coordinate positions for either nodes or points associated with parent entities in the specified select databox. Input: INTEGER num_select_databox This value specifies the displayed select databox to read data from.1 for the first select databox displayed, 2 for the second select databox displayed, etc. This value specifies the desired entity type. The supported values are: node or point. This value specifies the general type of entities contained by the select databox. The supported values are: geo, and elem. This value returns the number of coordinates returned. This value returns the X coordinate values. The memory is allocated within this function. This value returns the Y coordinate values. The memory is allocated within this function.

STRING STRING

entity[] parent[]

Output: INTEGER REAL REAL num x_comp(VIRTUAL) y_comp(VIRTUAL)

124 Application Authors Guide


Inputs Box

REAL INTEGER

z_comp(VIRTUAL)

This value returns the Z coordinate values. The memory is allocated within this function. This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.

Error Conditions: None.


Remarks:

This is an auxiliary utility function that may be used inside of a custom PCL function that is called by the Apply Inputs action. This method of obtaining data is in addition to the normal call sequence argument value passing.
Example:

None