User Tools

Site Tools


DzScriptPane

A pane for viewing/authoring DAZ Scripts.

More...

Inherits :

Methods

Signals

Detailed Description

This pane provides users with an Integrated Development Environment (IDE) that is specifically tailored to the development of DAZ Script for use in Daz Studio. It includes several standard features expected in a modern IDE, such as line numbering, syntax highlighting, and code folding. In addition to these core features, the pane allows users to execute a script directly within Daz Studio while the script is being developed, making testing/debugging easier.

The Script IDE pane is accessible within the UI via the Window > Panes (Tabs) menu. Triggering the “Script IDE” action will toggle visibility of the pane. As is the case for any pane in the application, this pane can float (be undocked) in its own pane group or be docked with other panes, as desired.

The Script IDE pane is accessible through the scripting API using DzPaneMgr::findPane().

MenuBar and Menus

A menubar, with menus and actions that pertain specifically to the IDE, is located at the top of the pane. Many of the actions found here provide access to basic file operations, such as opening, closing, and saving scripts or basic editing operations, such as copy, paste and find/replace. Also found here are actions that provides access to attributes of the script, such as API version and type, as well as preferences that provide control over look, feel and formatting.

Script Tabs

Multiple script documents can be open within the Script IDE pane at the same time. Script tabs provide access to the individual script documents. Each tab displays the shortname of the file that the script document was loaded from. If the script document was not loaded from a file, the script tab displays “Untitled” for its name.

Output Window

At the bottom of the pane is an output window that displays error and warning messages when there is an issue with a script that has been executed from within the Script IDE pane. These messages can be helpful for narrowing down the cause of a failure in the script.

Also displayed within this window are the results of calls made to Global::print() and Global::debug().

Extending the Script IDE

Edit Menu

The Edit menu, specifically, has the ability to be extended by placing scripts that use the DzScriptTab API to access and/or manipulate the contents of an open script document within specific directories that are known to the application:

  • <application_home>/resources/Script IDE/…
  • <mapped_native_dir>/data/resources/Script IDE/<vendor_name>/<product_name>/…
  • <daz_connect_product>/data/resources/script ide/<vendor_name>/<product_name>/…

The folder/file structure that resides within these specific directories is reflected within the middle portion of the Edit menu. Where an adjacent and corresponding PNG exists for a given script within this structure, that PNG will be used for the script action's icon. In the case of relative path collisions.

Events

There are three specific events that occur in the Script IDE that you have the ability to directly extend the functionality of:

  1. When a new script is created:
    • Script IDE: File > New Script
  2. When a script document is opened from file
    • Script IDE: File > Open Script…
    • Drag from OS file browser, drop onto Script IDE pane
    • Asset View Context Menu: Open in Script IDE…
  3. When a script document is saved to file
    • Script IDE: File > Save Script
    • Script IDE: File > Save Script As…
    • Script IDE: File > Save Encrypted Script…

These three events are extended by placing a corresponding script, which use the DzScriptTab API to access and/or manipulate the contents of the invoking script document, within the <application_home>/resources/Script IDE/ directory:

  1. _new.dsa
  2. _open.dsa
  3. _save.dsa

Transient Variables

When extending the Script IDE pane, the scripts described above provide transient global variables that provide convenient access to key objects:

  • Pane - refers to the Script IDE pane
  • Tab - refers to the DzScriptTab that invoked execution of the script

Encryption

It is important to understand that while the ability to open and execute encrypted scripts from within the Script IDE pane is provided, the contents of any such script cannot be accessed directly from within the Script IDE pane; placeholder text indicating that the contents of the script is encrypted will be displayed instead. The DzScript object that holds the contents of any loaded script and the DzScriptTab that displays the contents of a script are separate distinct objects.

Methods


Boolean : closeAllScripts()

Causes all open scripts to be closed; prompting the user to save changes as needed.

Return Value:

  • true if all scripts were closed, otherwise false.

See Also:


Boolean : closeAllScriptsExceptCurrent()

Causes all open scripts except the current one to be closed; prompting the user to save changes as needed.

Return Value:

  • true if all scripts except this one were closed, otherwise false.

See Also:

Since:

  • 4.11.0.221

Boolean : closeScript()

Causes the active script to be closed; prompting the user to save changes as needed.

Return Value:

  • true if the file was closed, otherwise false.

Boolean : copySelection()

Copies the selected text in the active script to the clipboard.

Return Value:

  • true if the script is not encrypted, otherwise false.

DzScriptTab : currentScriptTab()

Return Value:

  • The 'current' (top) visible script tab.

Number : currentScriptTabIndex()

Return Value:

  • The index of the 'current' (top) visible script tab.

Boolean : cutSelection()

Copies the selected text in the active script to the clipboard and deletes it from the document.

Return Value:

  • true if the script is not encrypted, otherwise false.

Boolean : deleteSelection()

If there is no text selected in the active script, deletes the character at the current cursor position, otherwise deletes the selected text.

Return Value:

  • true if the script is not encrypted, otherwise false.

Boolean : execute()

Executes the active script.

Return Value:

  • true if the script executed successfully, otherwise false.

Boolean : findFirst()

Finds the first/last occurrence of the “Find” text from the Find/Replace frame and if the “Find” text is not found, displays a message to the user.

Return Value:

  • true if the search found a match, otherwise false.

Boolean : findNext()

Finds the next occurrence of the “Find” text (based on the current cursor position) from the Find/Replace frame and if the “Find” text is not found, displays a message to the user.

Return Value:

  • true if the search found a match, otherwise false.

Boolean : findPrevious()

Finds the previous occurrence of the “Find” text (based on the current cursor position) from the Find/Replace frame and if the “Find” text is not found, displays a message to the user.

Return Value:

  • true if the search found a match, otherwise false.

String : getFindText()

Return Value:

  • The “Find” text in the Find/Replace frame.

Number : getNumScriptTabs()

Return Value:

  • The number of script tabs.

Since:

  • 4.11.0.137

String : getReplaceText()

Return Value:

  • The “Replace” text in the Find/Replace frame.

DzScriptTab : getScriptTab( Number index )

Parameter(s):

  • index - The index of the script tab to get.

Return Value:

  • The script tab at the specified index (if any), otherwise null.

Since:

  • 4.11.0.137

Boolean : gotoLine( Number line=-1 )

Moves the cursor to the given line number.

Parameter(s):

  • line - The line number to move the cursor to.

Return Value:

  • true if the cursor could be moved to the line number specified, otherwise false.

Boolean : indent( Number levels=1 )

Indents the selected line(s) by the specified amount.

Parameter(s):

  • levels - The number of indentions to apply.

Return Value:

  • true if the script is not encrypted and the operation was successful, otherwise false.

Number : indexOf( DzScriptTab scriptTab )

Parameter(s):

  • scriptTab - The script tab to get the index of.

Return Value:

  • The index of scriptTab.

Number : indexOfFile( String filename )

Parameter(s):

  • filename - The filename of the script to get the index of.

Return Value:

  • The index if the specified file (if any), otherwise -1.

Since:

  • 4.16.1.21

Boolean : isFileOpen( String filename )

Return Value:

  • true if the specified file is open, otherwise false.

Since:

  • 4.11.0.237

Boolean : isFindMatchCaseChecked()

Return Value:

  • true if the Case Sensitive option in the Find/Replace frame is checked, otherwise false.

Boolean : isFindRegExpChecked()

Return Value:

  • true if the “Regular Expression” option in the Find/Replace frame is checked, otherwise false.

See Also:


Boolean : isFindWholeWordsChecked()

Return Value:

  • true if the “Whole Words Only” option in the Find/Replace frame is checked, otherwise false.

Boolean : needsSave()

Return Value:

  • true if the contents of any script has not been saved, the contents of any script has been modified since it was last saved, the version number of any script does not match the version number last saved, the type of any script does not match the type last saved, otherwise false.

void : newScript()

Creates a new empty script.


void : openFile( String filename )

Opens a script at the specified path in a new tab.

Parameter(s):

  • filename - The filename of the script to open.

Attention:

  • If a script tab for filename is already open, that tab will become the 'current' tab.

See Also:


Boolean : openScript()

Prompts the user to open a script.

Return Value:

  • true if a file was opened, otherwise false.

See Also:


Boolean : pasteAtCursor()

Pastes the text from the clipboard into the active script, at the current cursor position.

Return Value:

  • true if the script is not encrypted, otherwise false.

void : refreshEditMenu()

Causes the Edit menu for the pane to be rebuilt.

Attention:

  • The significance of this function comes from the fact that a portion of the Edit menu is dynamically populated from the folder/file structure of specific directories on disk. The first directory used to populate the Edit menu is named “Script IDE” and resides within the application's resources path (i.e., “<application_home>/resources/Script IDE/…”). In addition, the contents of any “./data/resources/Script IDE/…” directory within a mapped native content directory (or any Daz Connect installed product) will likewise be used to populate the Edit menu. Where an adjacent PNG exists, it will be used for the script action's icon within the menu.

See Also:

Since:

  • 4.11.0.140

Boolean : reloadScript()

Causes the active script to be reloaded from disk.

Return Value:

  • true if a file was reloaded, otherwise false.

See Also:


Boolean : replaceAll()

Replaces all occurrences of the “Find” text with the “Replace” text and notifies the user with the number of replacements made.

Return Value:

  • true if the operation was successful, otherwise false.

Boolean : replaceNext()

Replaces the selected text with the “Replace” text if it matches the “Find” text of the Find/Replace frame. If there is no selection or the text does not match the “Find” text, a findNext() operation is performed.

Return Value:

  • true if the selected text matches the “Find” text and the replace was successful, otherwise false.

Boolean : replacePrevious()

Replaces the selected text with the “Replace” text if it matches the “Find” text of the Find/Replace frame. If there is no selection or the text does not match the “Find” text, a findPrevious() operation is performed.

Return Value:

  • true if the selected text matches the “Find” text and the replace was successful, otherwise false.

Boolean : saveEncryptedScript()

Prompts the user to save the active script to an encrypted file.

Return Value:

  • true if the script is not encrypted and a file was saved, otherwise false.

See Also:


Boolean : saveFile( String filename )

Saves the contents of the active script to the specified path.

Parameter(s):

  • filename - The filename of the script to save.

Return Value:

  • true if the script is not encrypted and the operation is successful, otherwise false.

Boolean : saveScript()

Saves the contents of the active script to file, prompting as needed.

Return Value:

  • true if the script is not encrypted and a file was saved, otherwise false.

See Also:


Boolean : saveScriptAs()

Prompts the user to save the active script.

Return Value:

  • true if the script is not encrypted and a file was saved, otherwise false.

See Also:


Boolean : selectAll()

Selects all text in the active script.

Return Value:

  • true if the script is not encrypted, otherwise false.

void : setCurrentScriptTab( Number index )

Sets the current script tab in the pane.

Parameter(s):

  • index - The index of the script tab to make the current tab.

void : setFindMatchCaseChecked( Boolean yesNo )

Sets whether or not the “Case Sensitive” option in the Find/Replace frame is checked.

Parameter(s):

  • yesNo - If true, the “Case Sensitive” option in the Find/Replace frame is checked.

void : setFindRegExpChecked( Boolean yesNo )

Sets whether or not the “Regular Expression” option in the Find/Replace frame is checked.

Parameter(s):

  • yesNo - If true, the “Regular Expression” option in the Find/Replace frame is checked.

See Also:


void : setFindText( String text )

Sets the “Find” text in the Find/Replace frame.

Parameter(s):

  • text - The text to set.

void : setFindWholeWordsChecked( Boolean yesNo )

Sets whether or not the “Whole Words Only” option in the Find/Replace frame is checked.

Parameter(s):

  • yesNo - If true, the “Whole Words Only” option in the Find/Replace frame is checked.

void : setReplaceText( String text )

Sets the “Replace” text in the Find/Replace frame.

Parameter(s):

  • text - The text to set.

void : showAttributesFrame( Boolean onOff )

Sets whether or not the Attributes frame is visible.

Parameter(s):

  • onOff - If true, the Attributes frame will be made visible. If false, the Attributes frame will be hidden.

void : showFindReplaceFrame( Boolean onOff )

Sets whether or not in the Find/Replace frame is visible.

Parameter(s):

  • onOff - If true, the Find/Replace frame will be made visible. If false, the Find/Replace frame will be hidden.

Boolean : showPreferences()

Shows the preferences dialog for the pane.

Return Value:

  • true if the dialog is accepted, otherwise false.

Boolean : unindent( Number levels=1 )

Unindent the selected line(s) by the specified amount.

Parameter(s):

  • levels - The number of unindentions to apply.

Return Value:

  • true if the script is not encrypted and the operation was successful, otherwise false.

Signals


void : attributesToggleChanged( Boolean onOff )

Signature:“attributesToggleChanged(bool)”

Emitted when the option to show/hide the attributes panel has changed.

Parameter(s):

  • onOff - The new state of the the option.

void : findReplaceToggleChanged( Boolean onOff )

Signature:“findReplaceToggleChanged(bool)”

Emitted when the option to show/hide the find/replace panel has changed.

Parameter(s):

  • onOff - The new state of the the option.