Open Document Create Scripts

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.

Get The Macro Library Script Path

  1. Return to the running Octopus application.
  2. Examine the main menu and select File » Get Application Script Path from the listed options.

    The application displays a dialog that allows you to search for application scripts.

    This is a picture of the app script search box.
  3. Type app_octopus_create_document_scripts.ssl in the text entry.

    Copy Text To Clipboard

    app_octopus_create_document_scripts.ssl

    The script entry appears in the dialog.

  4. Left click the entry named app_octopus_create_document_scripts.ssl and click OK or hit ENTER when you are finished.

    The application copies the script path to the Windows® clipboard.

Open The Macro Library Script

  1. Start a text editor of your choice and select the option to open a file from disk.
  2. Select CTRL + V to paste the script command library file path (into the place in the dialog where you specify the file to open).
  3. Open the file.

    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.

Get The Utility Library Script Path

  1. Return to the running Octopus application.
  2. Examine the main menu and select File » Get Application Script Path from the listed options.

    The application displays a dialog that allows you to search for application scripts.

    This is a picture of the app script search box.
  3. Type app_octopus_create_document_util.ssl in the text entry.

    Copy Text To Clipboard

    app_octopus_create_document_util.ssl

    The script entry appears in the dialog.

  4. Left click the entry named app_octopus_create_document_util.ssl and click OK or hit ENTER when you are finished.

    The application copies the script path to the Windows® clipboard.

Open The Utility Library Script

  1. Return to the running text editor and select the option to open a file from disk.
  2. Select CTRL + V to paste the utility library file path (into the place in the dialog where you specify the file to open).
  3. Open the file.

    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.