CIP Visual Basic.NET documentation for interface "IpfcSession"

Interface IpfcSession

Description

The Creo Parametric session.

To each application, Creo assigns a unique session, which contains the application licensing information, its IpfcCreoCompatibility and other data. The application can obtain this session by calling CMpfcSession.GetCurrentSession(). However, when assigning the session, Creo sets its compatibility (in associated IpfcAppInfo) to CompatibilityUndefined. This makes setting the compatibility be the responsibility of the application. To do this, when obtaining the assigned session the first time, the application must call CMpfcSession.GetCurrentSessionWithCompatibility() and pass a specific Creo compatibility to it. Otherwise, calls to CMpfcSession.GetCurrentSession() will be throwing IpfcXCompatibilityNotSet. Setting the comatiblity can be done only once during the runtime, although doing this always is a save approach to avoid the exception. For instance, if a Java toolkit application has more than one starting method, each such method must set the compatibility when obtaining the assigned session the first time.

Another function to obtain the assigned session is <reference to unknown entity pfcGlobal::GetProESession>. It does not throw exceptions, but if it is used as the first call to obtain the session, then it sets the compatibility to C3Compatible. This is done to provide the forward compatibility for applications based on earlier versions of Creo. This behavior can be changed by calling first CMpfcSession.GetCurrentSessionWithCompatibility() with compatibility passed as desired. Then all subsequent calls to <reference to unknown entity pfcGlobal::GetProESession> will return the session with same compatibility. Such behavior facilitates the migration of pre-Creo4 applications: it is enough to replace only the first call to <reference to unknown entity pfcGlobal::GetProESession> with CMpfcSession.GetCurrentSessionWithCompatibility()(C4Compatible), while leaving all subsequent calls to <reference to unknown entity pfcGlobal::GetProESession> without a change.

Please note that using <reference to unknown entity pfcGlobal::GetProESession>is deprecated. In subsequent releases it will result in an exception.

Direct Parent Classes:: IpfcBaseSession

Property Summary


`Property`	`CurrentSelectionBuffer`	`as IpfcSelectionBuffer`
	The current selection buffer object.

Method Summary


`Function`	`GetAppInfo () as IpfcAppInfo`
	Returns the application information from the applicatoin session.

`Function`	`ModelDescrContainsOrigin (Descr as IpfcModelDescriptor) as Boolean`


`Sub`	`NavigatorPaneBrowserAdd (PaneName as String, IconFileName as String [optional], URL as String)`
	Adds a new Navigator Pane.

`Sub`	`NavigatorPaneBrowserIconSet (PaneName as String, IconFileName as String)`
	Set the icon for a Navigator Pane.

`Sub`	`NavigatorPaneBrowserURLSet (PaneName as String, URL as String)`
	Set the url for a Navigator Pane.

`Sub`	`RibbonDefinitionfileLoad (FileName as String)`
	Loads ribbon definition file from a default path.

`Sub`	`SetAppInfo (Info as IpfcAppInfo)`
	Sends the application information for the application session.

`Sub`	`UIAddButton (Command as IpfcUICommand, MenuName as String, NeighborButton as String [optional], ButtonName as String, Message as String, MsgFile as String)`
	Adds a new button to an existing menu.

`Sub`	`UIAddMenu (MenuName as String, NeighborItem as String, FileName as String, ParentMenu as String [optional])`
	Creates a new menu.

`Sub`	`UIClearMessage ()`
	Scrolls the text in the message area up one line after a call to `IpfcSession.UIDisplayMessage()` . This command produces only one carriage return; if called multiple times, the command is ignored.

`Function`	`UICreateCommand (Name as String, Action as IpfcUICommandActionListener) as IpfcUICommand`
	Creates a command with the specified name.

`Function`	`UICreateMaxPriorityCommand (Name as String, Action as IpfcUICommandActionListener) as IpfcUICommand`
	Creates a command with the specified name. This command differs from a command created by `IpfcSession.UICreateCommand()` in that it uses the maximum command priority available. Maximum command priority should be used only in commands which open and activate a new model in a window. All other commands should be created using `IpfcSession.UICreateCommand()` because commands created with maximum priority may dismiss context of the current model in certain situations.

`Sub`	`UIDisplayFeatureParams (Selection as IpfcSelection, Type as IpfcParamType)`
	Displays parameters of a selected feature.

`Sub`	`UIDisplayLocalizedMessage (MsgFile as String, Format as String, Messages as Istringseq [optional])`
	Prints a text message to the message area in Creo Parametric.

`Sub`	`UIDisplayMessage (MsgFile as String, Format as String, Messages as Istringseq [optional])`
	Prints a text message to the message area in Creo Parametric.

`Function`	`UIGetCommand (Name as String) as IpfcUICommand [optional]`
	Finds the identifier of the specified action or option.

`Function`	`UIGetCurrentMouseStatus (SnapToGrid as Boolean) as IpfcMouseStatus`
	Returns the status of mouse at this particular moment. This method returns whenever the mouse is moved or a button is pressed.

`Function`	`UIGetNextMousePick (ExpectedButton as IpfcMouseButton [optional]) as IpfcMouseStatus`
	Returns the mouse status at the time that the user makes a mouse pick.

`Function`	`UIOpenFile (Options as IpfcFileOpenOptions) as String`
	Prompts the standard file browser interface of Creo Parametric.

`Function`	`UIPickMouseBox (FirstCorner as IpfcPoint3D [optional]) as IpfcOutline3D`
	Prompt the user to select a rectangle using the mouse.

`Function`	`UIReadIntMessage (LowerLimit as Long, UpperLimit as Long) as Long [optional]`
	Reads an integer from the keyboard.

`Function`	`UIReadRealMessage (LowerLimit as Double, UpperLimit as Double) as Double [optional]`
	Reads a double-precision float from the keyboard.

`Function`	`UIReadStringMessage (HideInput as Boolean [optional]) as String [optional]`
	Reads a line of keyboard input and returns the contents as a wide string.

`Function`	`UISaveFile (Options as IpfcFileSaveOptions) as String`
	Prompts the standard file browser interface of Creo Parametric, set up for the purpose of allowing the user to save a file.

`Function`	`UISelectDirectory (Options as IpfcDirectorySelectionOptions) as String`
	Prompts the standard file browser interface of Creo Parametric, set up for the purpose of allowing the user to select a directory.

`Function`	`UIShowMessageDialog (Message as String, Options as IpfcMessageDialogOptions [optional]) as IpfcMessageButton`
	Displays the UI Message Dialog.

Property Detail

Property CurrentSelectionBuffer as IpfcSelectionBuffer

The current selection buffer object.

It is necessary to have a model active in the session before calling the Get method for the above attribute.

Method Detail

Function GetAppInfo () as IpfcAppInfo

Returns the application information from the applicatoin session.

Returns:

Function ModelDescrContainsOrigin (Descr as IpfcModelDescriptor) as Boolean

Parameters:

Descr

Returns:

Sub NavigatorPaneBrowserAdd (PaneName as String, IconFileName as String [optional], URL as String)

Adds a new Navigator Pane.

Parameters:

PaneName: The name of the new navigator pane
IconFileName: The name of the icon file
URL: URL of the pane

Sub NavigatorPaneBrowserIconSet (PaneName as String, IconFileName as String)

Set the icon for a Navigator Pane.

Parameters:

PaneName: The name of the new navigator pane
IconFileName: The name of the icon file

Sub NavigatorPaneBrowserURLSet (PaneName as String, URL as String)

Set the url for a Navigator Pane.

Parameters:

PaneName: The name of the new navigator pane
URL: URL to set in the pane

Sub RibbonDefinitionfileLoad (FileName as String)

Loads ribbon definition file from a default path.

Exceptions thrown (but not limited to):

IpfcXToolkitNotFound - The ribbon definition file was not found.

IpfcXToolkitInvalidFile - The file specified was not a ribbon definition file.

Parameters:

FileName

Name of ribbon definition file including extension name. The default search paths for finding the ribbon definition file are:

Current directory
Creo Parametric Loadpoint/text/ribbon
Application text dir/ribbon
Application text dir/(language)/ribbon

Sub SetAppInfo (Info as IpfcAppInfo)

Sends the application information for the application session.

Parameters:

Info

Sub UIAddButton (Command as IpfcUICommand, MenuName as String, NeighborButton as String [optional], ButtonName as String, Message as String, MsgFile as String)

Adds a new button to an existing menu.

This method is deprecated. Use Customize UI dialog to create menus in Creo Parametric Ribbon UI

Exceptions thrown (but not limited to):

IpfcXToolkitMsgNotFound - The specified message was not found in the message file.

IpfcXToolkitFound - a menubar entity with this name already exists.

Parameters:

Command: The menu command
MenuName: The name of the menu to which to add the button
NeighborButton: The name of the neighboring menu button. To determine thename of a menu button, check the trail file after the menu button has beenselected from the parent menu.
ButtonName: The label for the name of the button to add to the menu, as declared in the message file.
Message: The label for the one-line help message displayed when your cursor is over thenew button, as declared in the message file.
MsgFile: The name of the message file used for the menu

Sub UIAddMenu (MenuName as String, NeighborItem as String, FileName as String, ParentMenu as String [optional])

Creates a new menu.

This method is deprecated. Use Customize UI dialog to create menus in Creo Parametric Ribbon UI

Exceptions thrown (but not limited to):

IpfcXToolkitMsgNotFound - The specified message was not found in the message file.

IpfcXToolkitFound - a menubar entity with this name already exists.

Parameters:

MenuName: The name of the new menu
NeighborItem: The neighbor item in the parent menu
FileName: The name of the menu file
ParentMenu: The name of the parent menu, or NULL if the menu is along the toolbar.

Sub UIClearMessage ()

Scrolls the text in the message area up one line after a call to IpfcSession.UIDisplayMessage() . This command produces only one carriage return; if called multiple times, the command is ignored.

You could use this function to remove a message once the user has responded to it, so it is clear that the system received the response.

Function UICreateCommand (Name as String, Action as IpfcUICommandActionListener) as IpfcUICommand

Creates a command with the specified name.

Exceptions thrown (but not limited to):

IpfcXToolkitFound - An action already exists under action_name.

See Also:: IpfcSession.UICreateMaxPriorityCommand()

Parameters:

Name: The name of the new command
Action: The corresponding action listener, which will be run when the command is activated.

Returns:: A pointer to the new command

Function UICreateMaxPriorityCommand (Name as String, Action as IpfcUICommandActionListener) as IpfcUICommand

Creates a command with the specified name. This command differs from a command created by IpfcSession.UICreateCommand() in that it uses the maximum command priority available. Maximum command priority should be used only in commands which open and activate a new model in a window. All other commands should be created using IpfcSession.UICreateCommand() because commands created with maximum priority may dismiss context of the current model in certain situations.

Exceptions thrown (but not limited to):

IpfcXToolkitFound - An action already exists under action_name.

Parameters:

Name: The name of the new command
Action: The corresponding action listener, which will be run when the command is activated.

Returns:: A pointer to the new command

Sub UIDisplayFeatureParams (Selection as IpfcSelection, Type as IpfcParamType)

Displays parameters of a selected feature.

Exceptions thrown (but not limited to):

IpfcXToolkitNotFound - The model is not the top-level model in the window.

Manual References:: Session Objects: Displaying Feature Parameters

Parameters:

Selection

A selection object in which the selected model item is a feature.

Type

Specifies the type of parameter to display. The options are:

DIM_PARAM
PATTERN_PARAM
REFDIM_PARAM
ALL_PARAMS
GTOL_PARAM
SURFFIN_PARAM

Sub UIDisplayLocalizedMessage (MsgFile as String, Format as String, Messages as Istringseq [optional])

Prints a text message to the message area in Creo Parametric.

This method supports non-ASCII character strings as messages. Remember that Web.Link applications, as unregistered web pages, do not currently support setting of the PTC Creo Parametric text directory. All the resource files for messages must be located at $PRO_DIRECTORY/text folder.

Exceptions thrown (but not limited to):

IpfcXToolkitNotFound - The specified message file was not found.

IpfcXToolkitCantOpen - The system could not read the message file.

IpfcXToolkitMsgNotFound - The specified message was not found in the message file.

IpfcXToolkitMsgNoTrans - The message text (in the current language of the user interface) was not found.

IpfcXToolkitMsgFmtError - There was a format error in the message text.

IpfcXToolkitMsgTooLong - The message was longer than 259 characters and has been truncated to fit.

IpfcXToolkitFound - The message file had been read in before this call and the message was not in it.

Parameters:

MsgFile: The name of the message file containing the format
Format: The format of the message: the first line of the section of the message file that uniquely identifies the message
Messages: A sequence of strings which will replace any occurrences of %#w in the message file, where '#' is the numerical identifier of the replacement. This method does not support formats using %#s.

Sub UIDisplayMessage (MsgFile as String, Format as String, Messages as Istringseq [optional])

Prints a text message to the message area in Creo Parametric.

This method supports only ASCII character strings as messages. Remember that Web.Link applications, as unregistered web pages, do not currently support setting of the PTC Creo Parametric text directory. All the resource files for messages must be located at $PRO_DIRECTORY/text folder.

Exceptions thrown (but not limited to):

IpfcXToolkitNotFound - The specified message file was not found.

IpfcXToolkitCantOpen - The system could not read the message file.

IpfcXToolkitMsgNotFound - The specified message was not found in the message file.

IpfcXToolkitMsgNoTrans - The message text (in the current language of the user interface) was not found.

IpfcXToolkitMsgFmtError - There was a format error in the message text.

IpfcXToolkitMsgTooLong - The message was longer than 80 characters and has been truncated to fit.

IpfcXToolkitFound - The message file had been read in before this call and the message was not in it.

Parameters:

MsgFile: The name of the message file containing the format
Format: The format of the message: the first line of the section of the message file that uniquely identifies the message
Messages: A sequence of strings which will replace any occurrences of %#s in the message format, where '#' is the numerical identifier of the replacement. This method does not support formats using %#w.

Function UIGetCommand (Name as String) as IpfcUICommand [optional]

Finds the identifier of the specified action or option.

Parameters:

Name: The name of the action or option.

Returns:: A pointer to the command.

Function UIGetCurrentMouseStatus (SnapToGrid as Boolean) as IpfcMouseStatus

Returns the status of mouse at this particular moment. This method returns whenever the mouse is moved or a button is pressed.

Exceptions thrown (but not limited to):

IpfcXToolkitAbort - The user aborted input.

Parameters:

SnapToGrid: Boolean specifying whether or not the mouse positions should be indicated as the closest gridpoint.

Returns:: Data object with the current mouse position and button status.

Function UIGetNextMousePick (ExpectedButton as IpfcMouseButton [optional]) as IpfcMouseStatus

Returns the mouse status at the time that the user makes a mouse pick.

Parameters:

ExpectedButton: The button that the user should press, or null, which means any button will cause the function to return.

Returns:: Data object containing the current mouse position and button status.

Function UIOpenFile (Options as IpfcFileOpenOptions) as String

Prompts the standard file browser interface of Creo Parametric.

This method cannot be used for NX models in the current release.

Exceptions thrown (but not limited to):

IpfcXToolkitUserAbort - The user aborted from the user interface.

Parameters:

Options: The various options for file open dialog.

Returns:: The selected file.

Function UIPickMouseBox (FirstCorner as IpfcPoint3D [optional]) as IpfcOutline3D

Prompt the user to select a rectangle using the mouse.

Parameters:

FirstCorner: The location of the first corner of the rectangle, or null, in which case the user willbe able to select both corners.

Returns:: The two boundary points, in screen coordinates.

Function UIReadIntMessage (LowerLimit as Long, UpperLimit as Long) as Long [optional]

Reads an integer from the keyboard.

If the user types a value outside the specified range of values, the functions prompts the user to enter the value again.

Exceptions thrown (but not limited to):

IpfcXToolkitMsgUserQuit - The user canceled input by typing ESC.

Parameters:

LowerLimit: The lower limit of the range of valid values
UpperLimit: The upper limit of the range of valid values

Returns:: A pointer to the value entered

Function UIReadRealMessage (LowerLimit as Double, UpperLimit as Double) as Double [optional]

Reads a double-precision float from the keyboard.

If the user types a value outside the specified range of values, the function prompts the user to enter the value again.

Exceptions thrown (but not limited to):

IpfcXToolkitMsgUserQuit - The user canceled input by typing ESC.

Parameters:

LowerLimit: The lower limit of the range of valid values
UpperLimit: The upper limit of the range of valid values

Returns:: A pointer to the value entered

Function UIReadStringMessage (HideInput as Boolean [optional]) as String [optional]

Reads a line of keyboard input and returns the contents as a wide string.

Leading and trailing blanks are stripped from the string.

Default values are displayed in the text box as input. Note that this value will not be returned if the user hits a carriage return; instead, the function will return constant string "use_default_string" and the application must interpret that the user intends to use the default.

Exceptions thrown (but not limited to):

IpfcXToolkitMsgUserQuit - The user canceled input by typing <ESC>.

Parameters:

HideInput: A Boolean flag that specifies whether the input should be hidden, such as when you type in a password

Returns:: The string entered

Function UISaveFile (Options as IpfcFileSaveOptions) as String

Prompts the standard file browser interface of Creo Parametric, set up for the purpose of allowing the user to save a file.

For Multi-CAD objects, this method does not support local disk saving location in a Windchill connected session.

Exceptions thrown (but not limited to):

IpfcXToolkitUserAbort - The user aborted from the user interface.

Parameters:

Options: The various options for save file dialog.

Returns:: The saved file.

Function UISelectDirectory (Options as IpfcDirectorySelectionOptions) as String

Prompts the standard file browser interface of Creo Parametric, set up for the purpose of allowing the user to select a directory.

Exceptions thrown (but not limited to):

IpfcXToolkitUserAbort - The user aborted from the user interface.

Parameters:

Options: The various options for directory selection dialog.

Returns:: The selected directory path.

Function UIShowMessageDialog (Message as String, Options as IpfcMessageDialogOptions [optional]) as IpfcMessageButton

Displays the UI Message Dialog.

Parameters:

Message: The message text to be displayed in the dialog.
Options: The various options for message dialog. If null, a default message dialog is displayed, with only an OK button and an Info icon and title.

Returns:: The identifier of the button that the user pressed to dismiss the dialog.