CIP C++ documentation for class "pfcSession"

Class pfcSession

# include <pfcSession.h> class pfcSession : public virtual pfcBaseSession { xaideclare(pfcSession) ... };

Description

The Creo Parametric session.

To each application, Creo assigns a unique session, which contains the application licensing information, its pfcCreoCompatibility and other data. The application can obtain this session by calling pfcGetCurrentSession(). However, when assigning the session, Creo sets its compatibility (in associated pfcAppInfo) 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 pfcGetCurrentSessionWithCompatibility(pfcCreoCompatibility) and pass a specific Creo compatibility to it. Otherwise, calls to pfcGetCurrentSession() will be throwing pfcXCompatibilityNotSet. 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 pfcGetProESession(). 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 pfcGetCurrentSessionWithCompatibility(pfcCreoCompatibility) with compatibility passed as desired. Then all subsequent calls to pfcGetProESession() 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 pfcGetProESession() with pfcGetCurrentSessionWithCompatibility(pfcCreoCompatibility)(C4Compatible), while leaving all subsequent calls to pfcGetProESession() without a change.

Please note that using pfcGetProESession()is deprecated. In subsequent releases it will result in an exception.

Direct Known Subclasses:: wfcWSession

Method Summary


`pfcAppInfo_ptr`	`GetAppInfo ()`
	Returns the application information from the applicatoin session.

`pfcSelectionBuffer_ptr`	`GetCurrentSelectionBuffer ()`
	The current selection buffer object.

`xbool`	`ModelDescrContainsOrigin (pfcModelDescriptor_ptr Descr)`


`void`	`NavigatorPaneBrowserAdd (xrstring PaneName, optional xrstring IconFileName, xrstring URL)`
	Adds a new Navigator Pane.

`void`	`NavigatorPaneBrowserIconSet (xrstring PaneName, xrstring IconFileName)`
	Set the icon for a Navigator Pane.

`void`	`NavigatorPaneBrowserURLSet (xrstring PaneName, xrstring URL)`
	Set the url for a Navigator Pane.

`void`	`RibbonDefinitionfileLoad (xrstring FileName)`
	Loads ribbon definition file from a default path.

`void`	`SetAppInfo (pfcAppInfo_ptr Info)`
	Sends the application information for the application session.

`void`	`UIAddButton (pfcUICommand_ptr Command, xrstring MenuName, optional xrstring NeighborButton, xrstring ButtonName, xrstring Message, xrstring MsgFile)`
	Adds a new button to an existing menu.

`void`	`UIAddMenu (xrstring MenuName, xrstring NeighborItem, xrstring FileName, optional xrstring ParentMenu)`
	Creates a new menu.

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

`pfcUICommand_ptr`	`UICreateCommand (xrstring Name, pfcUICommandActionListener_ptr Action)`
	Creates a command with the specified name.

`pfcUICommand_ptr`	`UICreateMaxPriorityCommand (xrstring Name, pfcUICommandActionListener_ptr Action)`
	Creates a command with the specified name. This command differs from a command created by `pfcSession::UICreateCommand(xrstring, pfcUICommandActionListener_ptr)` 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 `pfcSession::UICreateCommand(xrstring, pfcUICommandActionListener_ptr)` because commands created with maximum priority may dismiss context of the current model in certain situations.

`void`	`UIDisplayFeatureParams (pfcSelection_ptr Selection, pfcParamType Type)`
	Displays parameters of a selected feature.

`void`	`UIDisplayLocalizedMessage (xrstring MsgFile, xrstring Format, optional xstringsequence_ptr Messages)`
	Prints a text message to the message area in Creo Parametric.

`void`	`UIDisplayMessage (xrstring MsgFile, xrstring Format, optional xstringsequence_ptr Messages)`
	Prints a text message to the message area in Creo Parametric.

`optional pfcUICommand_ptr`	`UIGetCommand (xrstring Name)`
	Finds the identifier of the specified action or option.

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

`pfcMouseStatus_ptr`	`UIGetNextMousePick (optional pfcMouseButton ExpectedButton)`
	Returns the mouse status at the time that the user makes a mouse pick.

`xstring`	`UIOpenFile (pfcFileOpenOptions_ptr Options)`
	Prompts the standard file browser interface of Creo Parametric.

`pfcOutline3D_ptr`	`UIPickMouseBox (optional pfcPoint3D_ptr FirstCorner)`
	Prompt the user to select a rectangle using the mouse.

`optional xint`	`UIReadIntMessage (xint LowerLimit, xint UpperLimit)`
	Reads an integer from the keyboard.

`optional xreal`	`UIReadRealMessage (xreal LowerLimit, xreal UpperLimit)`
	Reads a double-precision float from the keyboard.

`optional xstring`	`UIReadStringMessage (optional xbool HideInput)`
	Reads a line of keyboard input and returns the contents as a wide string.

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

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

`pfcMessageButton`	`UIShowMessageDialog (xrstring Message, optional pfcMessageDialogOptions_ptr Options)`
	Displays the UI Message Dialog.

Methods Inherited from Class pfcActionSource:: AddActionListener, RemoveActionListener, AddActionListenerWithType

Methods Inherited from Class pfcParent:: GetChild

Methods Inherited from Class pfcDisplay:: CreateDisplayList2D, Invalidate, DrawArc2D, DrawPolygon2D, DrawText2D, CreateDisplayList3D, DrawCircle, DrawLine, SetPenPosition, DrawPolyline, GetDefaultFont, GetCurrentFont, SetCurrentFont, GetFontById, GetFontByName, GetTextHeight, SetTextHeight, GetRotationAngle, SetRotationAngle, GetSlantAngle, SetSlantAngle, GetWidthFactor, SetWidthFactor, ResetTextAttributes, GetCurrentGraphicsMode, SetCurrentGraphicsMode, GetCurrentGraphicsColor, SetCurrentGraphicsColor

Methods Inherited from Class pfcBaseSession:: CopyFileFromWS, CopyFileToWS, GetCurrentWindow, SetCurrentWindow, CreateModelWindow, GetModelWindow, OpenFile, ListWindows, GetWindow, FlushCurrentWindow, ListModels, ListModelsByType, GetCurrentModel, GetActiveModel, CreatePart, CreateAssembly, CreateDrawingFromTemplate, Import2DModel, GetByRelationId, RetrieveModel, RetrieveModelWithOpts, GetModel, GetModelFromDescr, GetModelFromFileName, EraseUndisplayedModels, Select, QueryFeatureEdit, SetConfigOption, GetConfigOption, GetConfigOptionValues, RunMacro, SetTextColor, GetRGBFromStdColor, SetStdColorFromRGB, SetLineStyle, ExportDirectVRML, LoadConfigFile, GetCurrentDirectory, ChangeDirectory, ListFiles, ListSubdirectories, GetEnvironmentVariable, CheckoutToWS, ExportFromCurrentWS, ImportToCurrentWS, SetWSExportOptions, ExportCurrentRasterImage, RetrieveAssemSimpRep, RetrieveGraphicsSimpRep, RetrieveSymbolicSimpRep, RetrieveGeomSimpRep, RetrievePartSimpRep, RetrieveGraphicsPartRep, RetrieveGeometryPartRep, RetrieveSymbolicPartRep, GetCurrentWS, SetCurrentWS, GetImportSourceType, ImportNewModel, LoadProToolkitDll, LoadProToolkitLegacyDll, GetProToolkitDll, StartJLinkApplication, IsConfigurationSupported, IsGeometryRepSupported, GetDimensionDisplayMode, SetDimensionDisplayMode, AuthenticateBrowser, RegisterServer, ListServers, GetServerByAlias, GetServerByUrl, GetServerLocation, GetActiveServer, GetUrlFromAliasedUrl, GetAliasFromAliasedUrl, GetModelNameFromAliasedUrl, GetConnectionId, ExecuteModelCheck, RegisterCustomModelCheck, RegisterRelationFunction, GetMessageContents, GetLocalizedMessageContents, UIRegisterFileSave, UIRegisterFileOpen, GetPrintPlacementOptions, GetPrintPrinterOptions, GetPrintMdlOptions, GetPrintPCFOptions, PLMSInitialize, AllowDuplicateModelItems, WLBInitialize, ExportProfileLoad

Method Detail

void UIAddMenu (xrstring MenuName, xrstring NeighborItem, xrstring FileName, optional xrstring ParentMenu)

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):

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

pfcXToolkitFound - 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.

Returns:

pfcUICommand_ptr UICreateCommand (xrstring Name, pfcUICommandActionListener_ptr Action)

Creates a command with the specified name.

Exceptions thrown (but not limited to):

pfcXToolkitFound - An action already exists under action_name.

See Also:: pfcSession::UICreateMaxPriorityCommand(xrstring, pfcUICommandActionListener_ptr)

Manual References:: Action Listeners: UI Command Action Listeners, Action Listeners: UI Command Action Listeners, Menus, Commands, and Pop-up Menus: Menu Buttons and Menus, Menus, Commands, and Pop-up Menus: Menu Buttons and Menus

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

pfcUICommand_ptr UICreateMaxPriorityCommand (xrstring Name, pfcUICommandActionListener_ptr Action)

Creates a command with the specified name. This command differs from a command created by pfcSession::UICreateCommand(xrstring, pfcUICommandActionListener_ptr) 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 pfcSession::UICreateCommand(xrstring, pfcUICommandActionListener_ptr) because commands created with maximum priority may dismiss context of the current model in certain situations.

Exceptions thrown (but not limited to):

pfcXToolkitFound - An action already exists under action_name.

Manual References:: Menus, Commands, and Pop-up Menus: Menu Buttons and Menus, Menus, Commands, and Pop-up Menus: Menu Buttons and Menus

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

void UIAddButton (pfcUICommand_ptr Command, xrstring MenuName, optional xrstring NeighborButton, xrstring ButtonName, xrstring Message, xrstring MsgFile)

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):

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

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

Returns:

void UIDisplayMessage (xrstring MsgFile, xrstring Format, optional xstringsequence_ptr Messages)

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):

pfcXToolkitNotFound - The specified message file was not found.

pfcXToolkitCantOpen - The system could not read the message file.

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

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

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

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

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

Manual References:: Session Objects: Accessing the Message Window, Session Objects: Accessing the Message Window, Session Objects: Accessing the Message Window

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.

Returns:

void UIDisplayLocalizedMessage (xrstring MsgFile, xrstring Format, optional xstringsequence_ptr Messages)

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):

pfcXToolkitNotFound - The specified message file was not found.

pfcXToolkitCantOpen - The system could not read the message file.

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

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

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

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

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

Manual References:: Session Objects: Accessing the Message Window, Session Objects: Accessing the Message Window, Session Objects: Accessing the Message Window

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.

Returns:

void UIClearMessage ()

Scrolls the text in the message area up one line after a call to pfcSession::UIDisplayMessage(xrstring, xrstring, optional xstringsequence_ptr) . 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.

Manual References:: Session Objects: Accessing the Message Window

Returns:

optional xint UIReadIntMessage (xint LowerLimit, xint UpperLimit)

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):

pfcXToolkitMsgUserQuit - The user canceled input by typing ESC.

Manual References:: Session Objects: Message Classification, Session Objects: Message Classification

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

optional xreal UIReadRealMessage (xreal LowerLimit, xreal UpperLimit)

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):

pfcXToolkitMsgUserQuit - The user canceled input by typing ESC.

Manual References:: Session Objects: Message Classification

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

optional xstring UIReadStringMessage (optional xbool HideInput)

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):

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

Manual References:: Session Objects: Message Classification

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

void UIDisplayFeatureParams (pfcSelection_ptr Selection, pfcParamType Type)

Displays parameters of a selected feature.

Exceptions thrown (but not limited to):

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

Returns:

pfcOutline3D_ptr UIPickMouseBox (optional pfcPoint3D_ptr FirstCorner)

Prompt the user to select a rectangle using the mouse.

Manual References:: Graphics: Drawing a Mouse Box

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.

pfcMouseStatus_ptr UIGetCurrentMouseStatus (xbool SnapToGrid)

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):

pfcXToolkitAbort - The user aborted input.

Manual References:: Graphics: Getting Mouse 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.

pfcMouseStatus_ptr UIGetNextMousePick (optional pfcMouseButton ExpectedButton)

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

Manual References:: Graphics: Getting Mouse Input, Graphics: Getting Mouse Input

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.

pfcMessageButton UIShowMessageDialog (xrstring Message, optional pfcMessageDialogOptions_ptr Options)

Displays the UI Message Dialog.

Manual References:: Session Objects: Writing a Message Using a Message Pop-up Dialog Box

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.

xstring UIOpenFile (pfcFileOpenOptions_ptr Options)

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):

pfcXToolkitUserAbort - The user aborted from the user interface.

Manual References:: Session Objects: File Dialogs, Session Objects: File Dialogs

Parameters:

Options: The various options for file open dialog.

Returns:: The selected file.

xstring UISelectDirectory (pfcDirectorySelectionOptions_ptr Options)

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):

pfcXToolkitUserAbort - The user aborted from the user interface.

Manual References:: Session Objects: File Dialogs, Session Objects: File Dialogs

Parameters:

Options: The various options for directory selection dialog.

Returns:: The selected directory path.

xstring UISaveFile (pfcFileSaveOptions_ptr Options)

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):

pfcXToolkitUserAbort - The user aborted from the user interface.