NOTE: This exercise assumes you have completed the previous exercise.
In this exercise you'll learn to open the new scripts that were created when you made the Octopus app. There are two new scripts:
Table 1.1. New Scripts
Script File | Description |
---|---|
app_octopus_create_document_scripts.ssl | Contains macros (commands) that can be installed in the user interface of a Scenome application. May also contain functions. You can only install command macros as items in Scenome app user interfaces. |
app_octopus_create_document_util.ssl | Contains functions only. These functions are used by other functions or command macros. You cannot install functions as command items in Scenome app user interfaces. By convention, macros are never stored in Scenome Scripting Language files ending in _util.ssl. |
This is a common script document pattern. Scripts that contain commands (called macros) that can be installed in the interface of an application use _scripts.ssl in their name. Related script libraries that store functions used by the command library use the same name, but the term _scripts.ssl is replaced with _util.ssl.
In this exercise, we'll open both these scripts.
The application displays a dialog that allows you to search for application scripts.
app_octopus_create_document_scripts.ssl
The script entry appears in the dialog.
The application copies the script path to the Windows® clipboard.
There will be minor differences in your script and what you see below. For example: your macro GUID will be different from the GUID shown at the bottom of this script.
///////////////////////////////////////////////////////////////////////////////
//
// $author Scenomics LLC
// $description Implements commands for creating new Octopus documents.
//
// Copyright 2023 Scenomics LLC. All Rights Reserved.
//
///////////////////////////////////////////////////////////////////////////////
[Package="Scenome-Package-App-Octopus"]
import library "app_service_assert_util.ssl";
import library "app_service_console_util.ssl";
import library "app_service_create_document_util.ssl";
import library "app_service_file_util.ssl";
import library "app_service_generate_menu_util.ssl";
import library "app_service_main_util.ssl";
import library "app_service_message_box_util.ssl";
import library "app_service_shell_util.ssl";
import library "type_file_path_algorithms.ssl";
import library "type_node_buffer_algorithms.ssl";
import library "type_service_create_util.ssl";
import library "type_service_enumeration_util.ssl";
import library "type_str_list_util.ssl";
import library "type_str_util.ssl";
import library "app_octopus_create_document_util.ssl";
///////////////////////////////////////////////////////////////////////////////
// function
///////////////////////////////////////////////////////////////////////////////
function void GenerateMenu(
CommandBarEvent event,
string p_sCallback
)
{
string a_sGuid = "{9C47F182-D6D2-45C0-91C2-C38798DE5759}";
auto StrList a_slTitles;
auto Int32Array a_aiIndices;
auto TypeInfoArray a_aoTypes;
auto TypeArray a_aoItemImages;
int a_nCount = LibOctopusCreateDocument.PopulateMenu( a_slTitles );
a_aiIndices.SetCount( a_slTitles.GetCount() );
auto Int32ArrayAlgorithms a_aiAlgorithms;
auto Int32ArrayView src_view = a_aiIndices.GetView();
a_aiAlgorithms.Iota( src_view.First, src_view.Last, 0 );
a_aoTypes.AddTypeSequence( Node, a_nCount );
LibOctopusCreateDocument.GetIconImages( a_aoTypes, a_aoItemImages );
// Call the function that is going to
// populate our menu with items.
LibAppServiceGenerateMenu.BuildMenuFromInt32Array(
event.Bar,
-1,
a_sGuid,
Script,
p_sCallback,
a_slTitles,
a_aiIndices,
a_aoItemImages );
}
///////////////////////////////////////////////////////////////////////////////
// function
///////////////////////////////////////////////////////////////////////////////
function void AppOctopusCreateDocument_OnShowPopupMenu( CommandBarEvent event )
[HandleEvent="SPA.ShellUIEvents.ShowPopupMenu"]
{
CommandItem a_oItem = event.Bar.GetItemByText(
0, "CreateOctopusDocument" );
string a_sTitle = "&New";
if( a_oItem )
{
a_oItem.Text = a_sTitle;
a_oItem.IsPopup = true;
}
if( event.Bar.Title == a_sTitle )
{
event.Bar.RemoveAllItems();
string a_sCallback = "CreateOctopusDocument";
GenerateMenu( event, a_sCallback );
}
}
///////////////////////////////////////////////////////////////////////////////
// function
///////////////////////////////////////////////////////////////////////////////
function void CreateOctopusDocument(
ApplicationEventSource sender,
CommandExecutionEvent event,
string p_sMenuTitle,
int p_nIndex
)
{
if( p_sMenuTitle == LibOctopusCreateDocument.GetNewDocumentString() )
{
LibOctopusCreateDocument.Execute( event );
}
}
///////////////////////////////////////////////////////////////////////////////
// function
///////////////////////////////////////////////////////////////////////////////
function void CreateOctopusDocument_OnUpdate(
ApplicationEventSource sender,
CommandUpdateEvent event,
string p_sMenuTitle,
int p_nIndex
)
{
if( p_sMenuTitle == LibOctopusCreateDocument.GetNewDocumentString() )
{
event.Info.Status.SetHint( "Creates a new CPU/GPU workload document" );
}
}
///////////////////////////////////////////////////////////////////////////////
// macro
///////////////////////////////////////////////////////////////////////////////
macro AppOctopusCreateDocument()
[Category="Create Commands", Package="Scenome-Package-App-Octopus",
Guid="{9C47F182-D6D2-45C0-91C2-C38798DE5759}", Image=".\\icons\\generic_script_icon.bmp"]
{
// Stub to reserve the GUID and associate the image.
}
Let's review the contents of this script file.
Table 1.2. Script Contents
Section | Description |
---|---|
Header | A brief description of the document. |
Package Declaration | Declares the package with which this script is associated. |
Imports | Library imports that allow us to call functions implemented in function libraries. |
GenerateMenu | This function is invoked by the function AppOctopusCreateDocument_OnShowPopupMenu, which is the handler for popup menu events. This function populates the popup menu with menu items when the user selects the popup menu in the user interface. |
AppOctopusCreateDocument_OnShowPopupMenu | This function is the popup menu event handler. It scans the UI during popup menu events and transforms command items with matching names into popup menus. First it changes the name of the menu item from the stub text ('CreateOctopusDocument') to the menu item name seen by the user ('&New'), and then it calls GenerateMenu to populate the menu with items. |
CreateOctopusDocument | This function executes when the user chooses an item from the popup menu. In this case, we only have one popup menu item. If we had additional popup menu items, this function would probably test the name of the popup menu item and implement different behavior depending on which popup menu item the user selects. |
CreateOctopusDocument_OnUpdate | This function controls whether or not the command is 'grayed out'. A command that has been 'grayed out' is visible to the user in the interface, but it cannot be selected by the user. In general, for this use case, we won't have any special filtering, but we will set the hint text that appears in the status bar when the user mouses over the command. |
macro AppOctopusCreateDocument | This macro implements a Scenome application command that can be installed in the user interface. Like all Scenome application command macros, this macro must have a unique name and GUID. We are specifying the generic script icon, which makes sure that this command has no associated icon when it appears in the user interface. NOTE: in this case we don't want a command icon. |
The application displays a dialog that allows you to search for application scripts.
app_octopus_create_document_util.ssl
The script entry appears in the dialog.
The application copies the script path to the Windows® clipboard.
The script appears in the text editor.
///////////////////////////////////////////////////////////////////////////////
//
// $author Scenomics LLC
// $description Implements functions for creating new Octopus layout documents.
//
// Copyright 2004-2021 Scenomics LLC. All Rights Reserved.
//
///////////////////////////////////////////////////////////////////////////////
library LibOctopusCreateDocument;
import library "app_service_assert_util.ssl";
import library "app_service_main_util.ssl";
import library "app_service_message_box_util.ssl";
import library "type_service_enumeration_util.ssl";
import library "type_service_create_util.ssl";
import library "type_service_find_util.ssl";
import library "type_variable_node_util.ssl";
///////////////////////////////////////////////////////////////////////////////
// function
///////////////////////////////////////////////////////////////////////////////
function string GetFilterInfo()
{
return "Octopus Box Files (*.box)|*.box|All Files (*.*)|*.*||";
}
///////////////////////////////////////////////////////////////////////////////
// function
///////////////////////////////////////////////////////////////////////////////
function int PopulateMenu( StrList p_slTitles )
{
p_slTitles.Add( "&New Document" );
return p_slTitles.GetCount();
}
///////////////////////////////////////////////////////////////////////////////
// function
///////////////////////////////////////////////////////////////////////////////
function void GetIconImages( TypeInfoArray p_aoTypes, TypeArray p_aoItemImages )
{
auto FilePath a_oIconPath = new FilePath(
LibAppServiceMain.GetIconsPath() );
a_oIconPath.AppendPath( "root_icon.bmp" );
for( int i = 0; i < p_aoTypes.GetCount(); ++i )
{
Image a_oImage = new Image;
a_oImage.OpenFile( a_oIconPath.GetPath() );
p_aoItemImages.Add( a_oImage );
}
}
Let's review the contents of this script file.
Table 1.3. Script Contents
Section | Description |
---|---|
Header | A brief description of the document. |
Library Declaration | Declares this document as a library so that its functions can be accessed from other utility and command libraries. You must use the library name to access these functions from other files. For example: LibOctopusCreateDocument.GetFilterInfo(). |
Imports | Library imports that allow us to call functions implemented in other function libraries. |
GetFilterInfo | This function returns a string that sets Windows® common file dialog file extension filtering options. |
PopulateMenu | This function populates a <StrList> with the names of menu items. In this case, the popup menu described in the previous section will have a single command item named New Document when the popup menu is displayed in the user interface. The & assigns a keyboard accelerator that activates this command. For example: so you can invoke this command by hitting ALT + F + N in the application. |
GetIconImages | This function populates a <TypeArray> with <Image> objects representing icons that appear on the left side of each command in the menu. |
This exercise is complete. Please proceed to the next exercise.