Kanzi  3.9.6
Kanzi Studio API
KanziStudio Interface Reference

Get notifications about Kanzi Studio events and get access to the core Kanzi Studio operations, such as access to the Kanzi Studio project, get input from the user, and show notifications. More...

Inheritance diagram for KanziStudio:
[legend]
Collaboration diagram for KanziStudio:
[legend]

Public Member Functions

void BeginEmphasize (EmphasizeFlag target)
 Starts emphasizing an ongoing operation. More...
 
bool CanExecutePluginCommand (PluginCommand command, IEnumerable< ProjectItem > items)
 
bool CanExecutePluginCommand (string commandName, IEnumerable< ProjectItem > items)
 
void ExecutePluginCommand (PluginCommand command, IEnumerable< ProjectItem > items)
 
void ExecutePluginCommand (string commandName, IEnumerable< ProjectItem > items)
 
void FinishEmphasize (EmphasizeFlag type)
 Ends emphasizing an ongoing operation and allows Kanzi Studio to return to the normal state. More...
 
DateTime GetExpirationDateForLicensedFeature (string featureId)
 Gets the expiration date of the license of an optional feature. More...
 
string GetFolderPathFromUser (string dialogTitle, string initialPath)
 
string GetFolderPathFromUser (string dialogTitle, string initialDirectory, string userPreferencesSetting)
 Prompts the user to provide a path to a directory. More...
 
string GetPathFromUser (string dialogTitle, string initialDirectory, string userPreferencesSetting, string defaultExtension, string filter, PathDialogType pathDialogType, bool multiselect)
 Opens a Windows dialog that allows the user to browse their computer to select a path. More...
 
string GetUserInput (string title, string prompt)
 Creates a dialog box which prompts the user to provide input. More...
 
string GetUserInput (string title, string prompt, string initialValue)
 Creates a dialog box which prompts the user to provide input. More...
 
string GetUserInput (string title, string prompt, IEnumerable< string > options, string initialValue)
 Displays a dialog box which prompts the user to select a value from one of the predefined options using a drop-down menu. More...
 
MessageBoxResult GetUserInput (string title, string prompt, MessageBoxButton messageBoxButton)
 
string GetUserInput (string title, string prompt, MessageBoxButton messageBoxButton, string extraOptionText)
 
void Log (string message, LogLevel logLevel)
 Writes to the Kanzi Studio Log window. More...
 
void Log (string message, Exception exception)
 Writes information about an exception to the Kanzi Studio Log window. More...
 
void Log (string message)
 Writes to the Kanzi Studio Log window. More...
 
void Redo ()
 
bool RegisterPropertyRouter (PropertyRouter router)
 Registers a property router. More...
 
void SendPreviewCommand (string name, object[] args)
 Sends commands to the Kanzi Studio Preview. More...
 
void ShowMessageBox (string text, bool isModal)
 Creates a window with a message. More...
 
void ShowMessageBox (string text, string caption, bool isModal)
 Displays a window with a title and a message. More...
 
void SubscribeToPropertyValueChanges (string projectItemPath, string propertyName)
 Tracks property changes in the Kanzi Studio Preview for the project item you set in this function. More...
 
void Undo ()
 
bool UnregisterPropertyRouter (PropertyRouter router)
 Unregisters a property router. More...
 
void UnsubscribeFromPropertyValueChanges (string projectItemPath, string propertyName)
 Stops tracking the property changes in the Kanzi Studio Preview for the project item you set in this function. More...
 

Properties

Project ActiveProject [get]
 
IEnumerable< ProjectItemClipboardItems [get]
 
Commands Commands [get]
 
string FactoryContentPath [get]
 
string KanziEnvironmentVariablesBatPath [get]
 
DirectoryInfo KanziExecutableDirectory [get]
 
string KanziHome [get]
 
DirectoryInfo KanziWorkspaceDirectory [get]
 
IPackageUriAccessor PackageUriAccessor [get]
 
string Prefab3DCompositionRootName [get]
 If the Prefab composition root is a 3D node, Preview patching makes the root node point to "&lt;Isolation Preview Viewport&gt;/&lt;Isolation Preview Scene Placeholder&gt;/&lt;Isolation preview model placeholder&gt;". More...
 
Project PrimaryProject [get]
 
Project Project [get]
 Since introduction of multi-project feature, the project to use is not anymore self-evident, making KanziStudio.Project obsolete. More...
 
IEnumerable< ProjectItemSelectedItems [get]
 
Solution Solution [get]
 
string StatusBarText [get, set]
 
IUserPreferences UserPreferences [get]
 Provides access to Kanzi Studio user preferences. More...
 
IGenericUtilities Utilities [get]
 
Version Version [get]
 Gets the version of Kanzi Studio where you run the plugin. More...
 

Events

EventHandler< ProjectEventArgs > BinaryExported
 Occurs after Kanzi Studio exports the kzb file of the project. More...
 
EventHandler PreviewExited
 Occurs when the Kanzi Studio Preview closes. More...
 
EventHandler< PreviewPropertyChangedEventArgs > PreviewPropertyChanged
 
EventHandler PreviewStarted
 Occurs when the Kanzi Studio Preview starts. More...
 
EventHandler< PreviewStartingEventArgs > PreviewStarting
 Occurs when the Kanzi Studio Preview is starting. More...
 
EventHandler< ProjectPathEventArgs > ProjectClosed
 Occurs when the project is closed. More...
 
EventHandler< ProjectEventArgs > ProjectOpened
 Occurs when the project is opened. More...
 
EventHandler< ProjectSavingEventArgs > ProjectSaved
 Occurs when the project is saved. More...
 
EventHandler SelectionChanged
 Occurs when the selection of a node or a resource in Kanzi Studio changes. More...
 
EventHandler< ProjectPathEventArgs > SolutionClosed
 Occurs when the primary project is closed. More...
 
EventHandler< ProjectEventArgs > SolutionOpened
 Occurs when a new primary project is created or loaded. More...
 
EventHandler< StatusEventArgs > StatusChanged
 

Detailed Description

Get notifications about Kanzi Studio events and get access to the core Kanzi Studio operations, such as access to the Kanzi Studio project, get input from the user, and show notifications.

Member Function Documentation

◆ BeginEmphasize()

void BeginEmphasize ( EmphasizeFlag  target)

Starts emphasizing an ongoing operation.

Parameters
targetTarget location, for example a preview window.
See also
FinishEmphasize

◆ FinishEmphasize()

void FinishEmphasize ( EmphasizeFlag  type)

Ends emphasizing an ongoing operation and allows Kanzi Studio to return to the normal state.

Parameters
typeTarget location, for example a preview window.
See also
BeginEmphasize

◆ GetExpirationDateForLicensedFeature()

DateTime GetExpirationDateForLicensedFeature ( string  featureId)

Gets the expiration date of the license of an optional feature.

Parameters
featureIdThe feature ID of the optional feature.
Returns
One of these values:
  • Expiration date, if a license exists for the feature ID
  • DateTime.MaxValue, if the license is permanent
  • Null, if no license exists for the feature ID.

◆ GetFolderPathFromUser()

string GetFolderPathFromUser ( string  dialogTitle,
string  initialDirectory,
string  userPreferencesSetting 
)

Prompts the user to provide a path to a directory.

Parameters
dialogTitleThe title of the dialog box.
initialDirectoryInitial directory where the folder dialog is opened.
userPreferencesSettingA key to be used for storing the last selected folder in the user preferences. Set as null not to save the path. If an existing value is found from user preferences, that is used over the value supplied in initialDirectory parameter.
Returns
The select folder path or null if cancelled.

◆ GetPathFromUser()

string GetPathFromUser ( string  dialogTitle,
string  initialDirectory,
string  userPreferencesSetting,
string  defaultExtension,
string  filter,
PathDialogType  pathDialogType,
bool  multiselect 
)

Opens a Windows dialog that allows the user to browse their computer to select a path.

You can use this function to get a path to either open or save a file.

Parameters
dialogTitleThe title of the dialog box.
initialDirectoryThe initial directory where to open the dialog.
userPreferencesSettingThe user preferences key to use to store the last selected directory. Set as null not to save the path. If an existing value is found from user preferences, that is used over the value supplied in initialDirectory parameter.
defaultExtensionThe default file extension to use to open or save the file.
filterThe filter definition that sets which file extensions the dialog allows the user to select.
pathDialogTypeThe type of the dialog. Use PathDialogType.OPEN for the open file dialog and PathDialogType.SAVE for the save file dialog.
multiselectWhen opening files, sets whether the user is allowed to select multiple files.
Returns
The absolute path to the selected file. If user cancels the operation, the function returns null.
See also
GetUserInput(string, string)

Examples

To open a Windows dialog which allows the user to browse their computer and select a path:

public void Execute(PluginCommandParameter parameter)
{
// Open the standard Windows dialog box where you can select which file on your computer you want to open.
// In the dialog box set:
// - Title to "Select the file you want to open".
// - Open the dialog in the current directory.
// - Store the path to the selected directory in the GetPathFromUser key in the Kanzi Studio user preferences.
// - Use .xml as the default extension for opening the file.
// - Allow the user to select only files with .xml and .txt extensions.
// - Create an open dialog.
// - Allow selection of multiple files in the dialog.
studio.GetPathFromUser(
"Select the file you want to open",
".",
"GetPathFromUser",
".xml",
"XML files (*.xml)|*.xml|Plain text files (*.txt)|*.txt",
PathDialogType.OPEN,
true);
}

◆ GetUserInput() [1/3]

string GetUserInput ( string  title,
string  prompt 
)

Creates a dialog box which prompts the user to provide input.

For example, you can use this function to get the path of a node where you want your plugin to start executing its commands.

Parameters
titleThe title of the dialog box.
promptThe message you want to show in the dialog box.
Returns
The user input. If user cancels the operation, the function returns null.

Examples

To create a dialog box with a title and prompt:

public void Execute(PluginCommandParameter parameter)
{
// Display a dialog box with:
// - Title "Where do you want to create the node?"
// - Prompt message "Enter the path where you want to create the node"
studio.GetUserInput(
"Where do you want to create the node?",
"Enter the path where you want to create the node");
}

◆ GetUserInput() [2/3]

string GetUserInput ( string  title,
string  prompt,
string  initialValue 
)

Creates a dialog box which prompts the user to provide input.

For example, you can use this function to get the path of a node where you want your plugin to start executing its commands.

Parameters
titleThe title of the dialog box.
promptThe message you want to show in the dialog box.
initialValueThe predefined value entered in the prompt.
Returns
The user input. If user cancels the operation, the function returns null.
See also
GetPathFromUser

Examples

To create a dialog box with a title, a prompt, and a text box with a predefined value:

public void Execute(PluginCommandParameter parameter)
{
// Display a dialog box with:
// - Title "Where do you want to create the node?"
// - Prompt message "Enter the path where you want to create the node"
// - Text box with a predefined value set to "Screen/Screens/RootPage"
studio.GetUserInput(
"Where do you want to create the node?",
"Enter the path where you want to create the node",
"Screen/Screens/RootPage");
}

◆ GetUserInput() [3/3]

string GetUserInput ( string  title,
string  prompt,
IEnumerable< string >  options,
string  initialValue 
)

Displays a dialog box which prompts the user to select a value from one of the predefined options using a drop-down menu.

Parameters
titleThe title of the dialog box.
promptThe message you want to show in the dialog box.
optionsThe options shown in a drop-down box from which the user can select.
initialValueThe value preselected in the drop-down menu.
Returns
The user input. If user cancels the operation, the function returns null.

◆ Log() [1/3]

void Log ( string  message,
LogLevel  logLevel 
)

Writes to the Kanzi Studio Log window.

For example, you can use this function to inform the user about the plugin progress in the Log window.

Parameters
messageThe message you want to print to the Log window.
logLevelThe level of the message you want to print to the Log window.

Examples

To print a message to the Log window as a regular notification:

public void Execute(PluginCommandParameter parameter)
{
// Print "Hello world!" to the Kanzi Studio Log window.
studio.Log("Hello world!", LogLevel.INFO);
}

To print a message to the Log window as a warning:

public void Execute(PluginCommandParameter parameter)
{
// Print "Warning!" with a yellow background to the Kanzi Studio Log window.
studio.Log("Warning!", LogLevel.WARNING);
}

◆ Log() [2/3]

void Log ( string  message,
Exception  exception 
)

Writes information about an exception to the Kanzi Studio Log window.

Parameters
messageThe message you want to print to the Log window before the exception information.
exceptionThe exception to be logged.

◆ Log() [3/3]

void Log ( string  message)

Writes to the Kanzi Studio Log window.

For example, you can use this function to inform the user about the plugin progress in the Log window.

Parameters
messageThe message you want to print to the Log window.

Examples

To print a message to the Kanzi Studio Log window:

public void Execute(PluginCommandParameter parameter)
{
// Print "Success!" to the Kanzi Studio Log window.
studio.Log("Success!");
}

◆ RegisterPropertyRouter()

bool RegisterPropertyRouter ( PropertyRouter  router)

Registers a property router.

A property router can interfere when a user edits properties in Kanzi Studio.

Parameters
routerThe router to register.
Returns
True, if router was registered. False, if the router is already registered.
See also
UnregisterPropertyRouter

◆ SendPreviewCommand()

void SendPreviewCommand ( string  name,
object []  args 
)

Sends commands to the Kanzi Studio Preview.

Parameters
nameThe name of the command you want to send to the Preview.
argsThe command arguments you want to send (must be serializable.)

◆ ShowMessageBox() [1/2]

void ShowMessageBox ( string  text,
bool  isModal 
)

Creates a window with a message.

For example, you can use this function to show a message to the user.

Parameters
textThe message you want to show in the window.
isModalWhether the window is modal. When set to true you cannot use the main Kanzi Studio window until you confirm the message in this window.

Examples

To create a modal window which displays a message:

public void Execute(PluginCommandParameter parameter)
{
// Display a modal window with the message "All nodes created".
// The second parameter sets whether the window is modal.
studio.ShowMessageBox("All nodes created.", true);
}

◆ ShowMessageBox() [2/2]

void ShowMessageBox ( string  text,
string  caption,
bool  isModal 
)

Displays a window with a title and a message.

For example, you can use this function to show a message to the user.

Parameters
textThe message you want to show in the window.
captionThe title of the window.
isModalWhether the window is modal. When set to true you cannot use the main Kanzi Studio window until you confirm the message in this window.

Examples

To create a modal window with a title and which displays a message:

public void Execute(PluginCommandParameter parameter)
{
// Display a modal window with the title "Success!" and the message "All nodes created".
// The third parameter sets whether the window is modal.
studio.ShowMessageBox("All nodes created.", "Success!", true);
}

◆ SubscribeToPropertyValueChanges()

void SubscribeToPropertyValueChanges ( string  projectItemPath,
string  propertyName 
)

Tracks property changes in the Kanzi Studio Preview for the project item you set in this function.

Triggers change events in project item and in this class.

Parameters
projectItemPathThe path to the project item for which you want to track property changes.
propertyNameThe name of the property the changes of which you want to track.
See also
UnsubscribeFromPropertyValueChanges

◆ UnregisterPropertyRouter()

bool UnregisterPropertyRouter ( PropertyRouter  router)

Unregisters a property router.

A property router can interfere when a user edits properties in Kanzi Studio.

Parameters
routerThe router to unregister.
Returns
True, if the router was successfully unregistered. False, if no such router was registered.
See also
RegisterPropertyRouter

◆ UnsubscribeFromPropertyValueChanges()

void UnsubscribeFromPropertyValueChanges ( string  projectItemPath,
string  propertyName 
)

Stops tracking the property changes in the Kanzi Studio Preview for the project item you set in this function.

Parameters
projectItemPathThe path to the project item for which you want to stop tracking property changes.
propertyNameThe name of the property the changes of which you want to stop tracking.
See also
SubscribeToPropertyValueChanges

Property Documentation

◆ Prefab3DCompositionRootName

string Prefab3DCompositionRootName
get

If the Prefab composition root is a 3D node, Preview patching makes the root node point to "&lt;Isolation Preview Viewport&gt;/&lt;Isolation Preview Scene Placeholder&gt;/&lt;Isolation preview model placeholder&gt;".

This member returns the new name of the composition root node.

The new name of the composition root node when composing Prefab of a 3D node.

◆ Project

Since introduction of multi-project feature, the project to use is not anymore self-evident, making KanziStudio.Project obsolete.

Use PrimaryProject to get the root of the project hierarchy. Use ActiveProject to get the project that is currently active in UI. This member will return the ActiveProject.

◆ UserPreferences

IUserPreferences UserPreferences
get

Provides access to Kanzi Studio user preferences.

Use this to store settings that are not project dependent.

◆ Version

Version Version
get

Gets the version of Kanzi Studio where you run the plugin.

The version of Kanzi Studio.

Examples

To get the major, minor, revision, and build numbers of the Kanzi Studio where you run the plugin:

public void Execute(PluginCommandParameter parameter)
{
// Print the Kanzi Studio version in the format Major.Minor.Revision.Build
// to the Kanzi Studio Log window.
studio.Log(
studio.Version.Major + "." +
studio.Version.Minor + "." +
studio.Version.Revision + "." +
studio.Version.Build);
}

Event Documentation

◆ BinaryExported

EventHandler<ProjectEventArgs> BinaryExported

Occurs after Kanzi Studio exports the kzb file of the project.

Examples

To subscribe to the BinaryExported event:

// Create the event handler and subscribe to the BinaryExported event to get
// notified when Kanzi Studio finishes exporting the kzb file of the project.
public void Execute(PluginCommandParameter parameter)
{
// Create the event handler that is set off when Kanzi Studio finishes
// exporting the kzb file of the project.
studio.BinaryExported += Studio_BinaryExported;
}
private void Studio_BinaryExported(object sender, ProjectEventArgs e)
{
// When Kanzi Studio finishes exporting the kzb file of the project,
// print a message to the Kanzi Studio Log window.
studio.Log("Finished exporting the kzb file of the project \"" + e.Project.Name + "\".");
}

◆ PreviewExited

EventHandler PreviewExited

Occurs when the Kanzi Studio Preview closes.

See also
PreviewStarted

Examples

To subscribe to the PreviewExited event:

// Create the event handler and subscribe to the PreviewExited event to get notified
// when the Kanzi Studio Preview closes.
public void Execute(PluginCommandParameter parameter)
{
// Create the event handler that is set off when the Preview closes.
studio.PreviewExited += Studio_PreviewExited;
}
private void Studio_PreviewExited(object sender, EventArgs e)
{
// When the Preview closes, print a message to the Kanzi Studio Log window.
studio.Log("The Preview closed.");
}

◆ PreviewStarted

EventHandler PreviewStarted

Occurs when the Kanzi Studio Preview starts.

See also
PreviewExited

Examples

To subscribe to the PreviewStarted event:

// Create the event handler and subscribe to the PreviewStarted event to get notified
// when the Kanzi Studio Preview starts.
public void Execute(PluginCommandParameter parameter)
{
// Create the event handler that is set off when the Preview starts.
studio.PreviewStarted += Studio_PreviewStarted;
studio.Log("PreviewStarted subscribed.");
}
private void Studio_PreviewStarted(object sender, EventArgs e)
{
// When the Preview starts, print a message to the Kanzi Studio Log window.
studio.Log("The Preview started.");
}

◆ PreviewStarting

EventHandler<PreviewStartingEventArgs> PreviewStarting

Occurs when the Kanzi Studio Preview is starting.

You can cancel this event.

See also
PreviewStarted

Examples

To subscribe to the PreviewStarting event:

// Create the event handler and subscribe to the PreviewStarting event to get notified
// when the Kanzi Studio Preview is starting.
public void Execute(PluginCommandParameter parameter)
{
// Create the event handler that is set off when the Preview is starting.
studio.PreviewStarting += Studio_PreviewStarting;
studio.Log("PreviewStarting subscribed.");
}
private void Studio_PreviewStarting(object sender, PreviewStartingEventArgs e)
{
// When the Preview is starting, cancel it.
e.Cancel("Preview startup canceled by an example for demonstration purposes.");
}

◆ ProjectClosed

EventHandler<ProjectPathEventArgs> ProjectClosed

Occurs when the project is closed.

See also
ProjectOpened, ProjectSaved

Examples

To subscribe to the ProjectClosed event:

// Create the event handler and subscribe to the ProjectClosed event to get notified when a project is closed.
public void Execute(PluginCommandParameter parameter)
{
// Create the event handler that is set off when a project is closed.
studio.ProjectClosed += Studio_ProjectClosed;
}
private void Studio_ProjectClosed(object sender, ProjectPathEventArgs e)
{
// When the project is closed, show a dialog box with a message about project closing.
studio.ShowMessageBox("The project \"" + e.ProjectPath + "\" is closed.", false);
}

◆ ProjectOpened

EventHandler<ProjectEventArgs> ProjectOpened

Occurs when the project is opened.

This can happen when the primary project of solution is loaded / created or when a sub-project is loaded or created.

See also
ProjectClosed, ProjectSaved

Examples

To subscribe to the ProjectOpened event:

// Create the event handler and subscribe to the ProjectOpened event to get notified when a project is opened.
public void Execute(PluginCommandParameter parameter)
{
// Create the event handler that is set off when a project is opened.
studio.ProjectOpened += Studio_ProjectOpened;
}
private void Studio_ProjectOpened(object sender, EventArgs e)
{
// When the project is opened, show a dialog box with the message "The project is opened."
studio.Log("The project is opened.");
}

◆ ProjectSaved

EventHandler<ProjectSavingEventArgs> ProjectSaved

Occurs when the project is saved.

See also
ProjectOpened, ProjectClosed

Examples

To subscribe to the ProjectSaved event:

// Create the event handler and subscribe to the ProjectSaved event to get notified when a project is saved.
public void Execute(PluginCommandParameter parameter)
{
// Create the event handler that is set off when a project is saved.
studio.ProjectSaved += Studio_ProjectSaved;
}
private void Studio_ProjectSaved(object sender, ProjectEventArgs e)
{
// When the project is saved, print a message to the Kanzi Studio Log window.
studio.Log("The project \"" + e.Project.Name + "\" is saved.");
}

◆ SelectionChanged

EventHandler SelectionChanged

Occurs when the selection of a node or a resource in Kanzi Studio changes.

For example, Kanzi Studio sets off this event when you select a node in a Project or Nodes windows, when you select a library, a directory, or a resource in the Library, or any of the resource windows.

Examples

To subscribe to the SelectionChanged event:

// Create the event handler and subscribe to the SelectionChanged event to get notified
// when the selection of a node or a resource in Kanzi Studio changes.
public void Execute(PluginCommandParameter parameter)
{
// Create the event handler that is set off when the selection of a node or a resource
// in Kanzi Studio changes.
studio.SelectionChanged += Studio_SelectionChanged;
}
private void Studio_SelectionChanged(object sender, EventArgs e)
{
// When the selection of a node or a resource in Kanzi Studio changes,
// print a message to the Kanzi Studio Log window.
studio.Log("The node or resource selection changed.");
}

◆ SolutionClosed

EventHandler<ProjectPathEventArgs> SolutionClosed

Occurs when the primary project is closed.

Examples

To subscribe to the SolutionClosed event:

// Create the event handler and subscribe to the SolutionClosed event to get notified when a Kanzi solution is closed.
public void Execute(PluginCommandParameter parameter)
{
// Create the event handler that is set off when a project is closed.
studio.SolutionClosed += Studio_SolutionClosed;
}
private void Studio_SolutionClosed(object sender, EventArgs e)
{
// When the solution is closed, show a dialog box with the message "The solution is closed."
studio.ShowMessageBox("The solution is closed.", false);
}

◆ SolutionOpened

EventHandler<ProjectEventArgs> SolutionOpened

Occurs when a new primary project is created or loaded.