Application object

 

 

Application global object.

Syntax

An Application global object is created for you and only this object can exist in the application. It is named Application and is globally accessible, you can also access its properties directly.

Parameters

none.

Property Of

global name space.

Implemented In

ECMerge 2.1

Description

 The Application object let you access global information about the running application.

Properties

Property	Description
current_frame	DocumentFrame object. Read-Only. Active frame in the graphical user interface, null if there is no active frame
executable_path	String. Read-Only. Path to the running executable.
initial_document	Document object. Read-Only / Available only during initial scripts (undefined else). This document is the document built from the command line arguments.
script_url	URL object. Read-Only / Available only during initial scripts (undefined else). This URL points to the currently run script.
scripts_generation	Number. Read-Only. This number gets incremented each time 'Reload macro scripts' is executed, it allows several scripts to cooperate as they know if they are run during a same reload or during successive reloads.
scripts_settings	Object. This object is serialized with toSource() and saved to ECMerge settings file. It is reloaded at application startup with eval() thus restoring this object. This object is to be used to store MRUs and settings for the macro-commands.
ui_language	Locale String. Read-Only. Language used for the User Interface as a locale code (such as: en_US, fr or de)
version	String. Version number of ECMerge, as MAJOR.MINOR.BUILD (e.g. "2.1.65")

 

Methods

add_frame
alert
choose
clone_options_set
clone_shared_options
confirm
execute_macro
exit
gc
get_options_sets_names
log
popup_menu
prompt
prompt_with_choices
set_shared_options

Examples

see functions samples.

See Also 

 Document object, DocumentFrame object.

Method add_frame

Syntax

function add_frame (document, focus)
returns a DocumentFrame

Parameters

document. Document object. Document to be viewed
focus. Boolean. True to give the focus immediately to this frame

Method Of

Application.

Implemented In

ECMerge 2.1

Description

Adds a frame to view a document.

Examples

Example 1.

Loads a document from an ECMT file then add a view for it:

var doc = Document.load ("/home/user/myecmt.ecmt");
add_frame (doc, true);

See Also 

 DocumentFrame object

Method alert

Syntax

 function alert (text)

Parameters

 text. String. Text to display

Method Of

Application

Implemented In

ECMerge 2.1

Description

Displays a text in a message box

Examples

Example 1.

Displays the famous "hello world!" message:

alert ("hello world!");

Methods choose / prompt_with_choices

Syntax

function choose (prompt, text1, text2, text3...)
function choose (prompt, texts_array)
returns chosen index or -1 if cancelled

function prompt_with_choices (prompt, text1, text2, text3...)
function prompt_with_choices (prompt, texts_array)
returns chosen text or undefined if cancelled

Parameters

prompt. String. Prompt to display to the user.
text1, text2, text3... String. Text to display in order.
texts_array. Array of String. Each element is displayed from 0 to length-1 in order.

Method Of

Application

Implemented In

ECMerge 2.1
prompt_with_choices was introduced in ECMerge 2.2

Description

Let the user choose from a list of text strings, with a prompt.

Examples

Example 1.

Prompt the user for a color then displays the index.

var chosen_color = choose ("Please choose a color:", "blue", "red");
if (chosen_color != -1)
    alert ("index " + chosen_color + "was chosen");

Example 2.

Prompt the user for a color from an Array then displays the chosen color.

var colors = ["blue", "red", "yellow", "white"];
var chosen_color = choose ("Please choose a color:", colors);
if (chosen_color != -1)
    alert ("color:" + colors[chosen_colors]);

Example 3.

Prompt the user for a color from an Array then displays the chosen color, letting the user type in another color.

var colors = ["blue", "red", "yellow", "white"];
var chosen_color = prompt_with_choices ("Please choose a color:", colors);
if (chosen_color)
    alert ("color:" + chosen_colors);

Method clone_options_set

Syntax

function clone_options_set ( name )
returns an OptionsSet object

Parameters

name. String. Name of the OptionsSet to retrieve

Method Of

Application.

Implemented In

ECMerge 2.1

Description

 Returns a clone of the named OptionsSet.

Examples

Example 1.

Applies an OptionsSet to an existing document:
var params = mydoc.parameters.clone ( );
params.settings = Application.clone_options_set (Application.get_options_sets_names( ) [0]);
mydoc.parameters = params;

See Also 

  OptionsSet object

Method clone_shared_options

Syntax

function clone_share_options ( )
returns a limited OptionsSet object with only "file_types" and "filters" sections.

Parameters

 none.

Method Of

Application.

Implemented In

ECMerge 2.2

Description

Returns a clone of the shared options of the application, that is, file types and converters (respectively "file_types" and "filters" sections).

See Also 

  OptionsSet object, set_shared_options method

Method confirm

Syntax

function confirm (prompt)
returns true if OK is pressed, false if cancel is pressed 

Parameters

prompt. String. Prompt displayed to the user

Method Of

Application.

Implemented In

ECMerge 2.1

Description

Displays a prompt to the user and makes him/her to press OK or cancel.

Examples

Example 1.

Ask if a file should be deleted.

var i_should = confirm ("Should I deleted this file?");

Method execute_macro

Syntax

 function execute_macro (macro_name)

Parameters

macro_name. String. Name of the macro to execute

Method Of

Application

Implemented In

ECMerge 2.1

Description

Executes a macro-command in the current application context. Macro commands are listed in the user interface in the Key Binding options panel.

Examples

Example 1.

Closes the current frame (potentially asking if the document should be saved or discarded)

execute_macro ("file_close");

Method exit

Syntax

function exit (exit_code)

Parameters

exit_code. Integer. Code to return as the application exit code. Usually 0 means success, any other value indicate an error.

Method Of

Application.

Implemented In

ECMerge 2.1

Description

Terminates the execution of the script, then the execution of the application.

Examples

Example 1.

Returns an exite code depending on a success variable.

var success = true;
exit (success ? 0 : 1);

Method gc

Syntax

 function gc( )

Parameters

none.

Method Of

global name space.

Implemented In

ECMerge 2.1

Description

Forces a garbage collection. Garbage collection is sometime necessary, in particular when resources are locked by objects which were already released, such as Document objects.

Method get_options_sets_names

Syntax

function get_options_sets_names ( )
returns an Array of String

Parameters

none

Method Of

Application.

Implemented In

ECMerge 2.2

Description

 Returns the list of options sets names.

See Also 

 OptionsSet object

Method log

Syntax

function log (text)

Parameters

text. String. Text to be logged.

Method Of

global name space

Implemented In

ECMerge 2.1

Description

Logs a text to the log view or the standard message output in command line mode.

Examples

Example 1.

Logs a text.

log ("this was logged");

Method popup_menu

Syntax

function popup_menu (menu)

Parameters

menu. A menu items Array. Menu to be displayed

Method Of

Application.

Implemented In

ECMerge 2.2

Description

Displays a contextual menu where the mouse cursor is currently placed. The menu is made of menu items defined as below.

Description of menu items

Property	Description
checked	Boolean. For 'check' or 'radio', item indicates if the item has the check or bullet in front of it
event	Function object. Function to call if the menu item is clicked
help_string	String. Text to display as the menu item help string
icon_url	URL object. URL to the icon to be displayed. Only native filesystem URL are supported here.
label	String. Label to display for that menu item. If empty, the item is a separator
sub_menu	Menu items Array. If defined, this item defined a sub-menu and items in sub_menu are displayed inside that sub-menu
type	String. One of 'check' for checkable menu items, 'radio' for radio menu items or empty/undefined for normal menu items

 

Examples

Example 1.

This sample displays a menu with two dummy items:
var menu =  [ { label: "menu item", event: function() { alert("hi hoo") } },
              { label: "menu item 2", event: function() { alert("hi hoo 2") } } ];

Application.popup_menu (menu);

See Also 

 none.

Method prompt

Syntax

function prompt (prompt)
returns a string

Parameters

prompt. String. Prompt for the text.

Method Of

Application

Implemented In

ECMerge 2.1

Description

Prompts for a text.

Examples

Example 1.

Logs the text that the user types.

log (prompt ("Please enter a text to log:"));

 

Method set_shared_options

Syntax

function set_share_options ( sdo )

Parameters

sdo. OptionsSet object limited to shared options. Shared options to set

Method Of

Application.

Implemented In

ECMerge 2.2

Description

Sets the shared options of the Application, those options are immediately propagated to all the master copies of the options sets (those actually sharing file types and converters). In addition, if the master copy of the options set of current view actually evolved, the view gets the changes as if validated by the options set box.

See Also 

  OptionsSet object, clone_shared_options method