scripting:events:start

Book Creator
 Add this page to your book
Book Creator
 Remove this page from your book  

 Manage book(0 page(s))
 Help

Events

If you want to write you own script plugin, there is no way to do it if you are not familiar with HippoEDIT events.

Events are the callbacks (same as handlers) you can assign to some plugs to be called when specific action has been executed.

Basics

There are no magic in events design (as you need to define “special” named functions etc).
To subscribe on event, you just assign your handler function to appropriate named plug from engine (plugs are members of Application object). Something like this:

doc_save_handler.js
function myDocumentSaveHandler() {
    alert("Some document was Saved!");
}
Application.onNewDocument = myDocumentSaveHandler;

The code above will show message box, as far as any document saved.

Handlers always have this object, that represents source of event and can have parameters (can be checked in API documentation), which forward additional information to handler.
To receive them you need to define input parameters of your functions in the sequence as it defined by API. If you do not need some trailing parameters, you can skip their definition in handler signature (even if you catch no parameters it will work). And of course, you can always access Application object - it is global.

on_file_rename.js
Application.onDocumentNameChange = function(old_name, new_name, rename) {
  Output().writeln("onDocumentNameChange : old_name = " + old_name + ", 
  new_name = " + new_name + ", rename = " + rename);
}

The above code will be called on file rename and shall output old and new file name together with rename indicator passed as event parameters.

Following code executed when a document is modified or saved and uses this object, that represent a document here, to get Title text. The type of this pointer for every handler can be checked in the documentation, but normally it is clear from handler purpose.

on_file_modified.js
Application.onModifiedChanged = function (modified) {
  Output().writeln("onModifiedChanged : document = " + this.Title + ", modified = " + modified);
}

In-line and Unnamed Handlers

If you have some simple handler function and do not need parameters except of this, you can directly assign handler code to a event plug - HippoEDIT will convert it to function handler internally: 

Application.onDocumentListUpdate = "Output().writeln(\"onDocumentListUpdate\")";

or, if scripting engine support this (JavaScript supports) do in-place assignment of unnamed function to event plug: 

onModifiedChanged = function (modified) {
  Output().writeln("onModifiedChanged : document = " + this.Title + ", modified = " + modified);  
}

as Application is global object, you can avoid it and directly write event plug name (on example above).

Unregistering handlers

To unregister event handler, reset plug by assigning to it null object. 

onModifiedChanged = function (modified) {
  Output().writeln("onModifiedChanged : document = " + this.Title + ", modified = " + modified);  
  onModifiedChanged = null;
}

the code above will execute handler only once, because event plug is reseted after first handler execution.

Event Hubs

Sometimes you want to connect more than one event handler to same event plug. Of course, you can do it also in code by creating one hub handler and dispatching the event to every single handler, but there is the easier way. You can use dedicated functions from HippoEDIT scripting framework:

  • boolean attachEvent(string EventName, object eventHandler) - helper to attach more than one handler to event plug
  • boolean detachEvent(string EventName, object eventHandler) - helper to detach handler from event plug
////////////////////////////////////////////////////////////////////////
// attach/detach event tests
// this is extended technique if you want to have more than one handler 
// attached to same event from same script and normally is not needed, 
// while you can also copy previous handler and call it inside of your 
// handler as an alternative
function onDocumentListUpdate2() { 	
  Output().writeln("onDocumentListUpdate2"); 
}
 
function onDocumentListUpdate3() { 	
  Output().writeln("onDocumentListUpdate3"); 
  if (Application.detachEvent("onDocumentListUpdate", onDocumentListUpdate3))
    Output().writeln("onDocumentListUpdate3 detached");
}
 
if (Application.attachEvent("onDocumentListUpdate", onDocumentListUpdate2))
  Output().writeln("onDocumentListUpdate2 attached");
 
if (Application.attachEvent("onDocumentListUpdate", onDocumentListUpdate3))
  Output().writeln("onDocumentListUpdate3 attached");

Commands

The easiest way to integrate your functionality in HippoEDIT scripting infrastructure is to model you functionality as command objects. If you have command object it is automatically visible in command list in keyboard settings, you can add to menu, ToolBar or StatusBar.

UI Events

There is no way to modify UI directly from any part of code. UI can be changed only during dedicated events, that provide you helper objects and ensure that UI modifications are done in right sequence, objects you want to modify already available and actions you did in code can be undone.

You can use following UI initialization events for modifications:

List Pane events

Service Events

In addition to UI events, there are of course, normal, functional events informing you about internal processes as: changing of cursor position, changing of active document, closing of the workspace, change of global settings etc.

Here is list of events you can subscribe:

Document Events

View Events

Workspace Events

Project Events

Framework Events