Occult Watcher

Occult Watcher 2.5

--> What extra addins are currently available
--> How to develop your own Add-ins for OccultWatcher

One of the new features of OccultWatcher is that is allows to be extended by custom developed add-ins (or plug-ins). The C2A add-in which is part of the standard distribution of OccultWatcher is an example of such an extension. The C2A Add-in adds the great functionality of plotting occultation charts with a single click from within OccultWatcher.

At the moment there is one extra addin for OccultWatcher ("OW Little Helpers") which includes the following functionality:

1) Looking up whether a given SAO star is included in the Meade Autostar database (used by Meader LX-90 and including 17895 bright SAO stars).
I use this to identify the closest SAO star and slew to it before I do star-hopping to the target.
2) Copying the event details for a given event in a compact format to be used as a reference (ex. printed on your custom star charts)

To install the "OW Little Helpers" add-in follow these steps:

- Download the add-in
- Stop your running OccultWatcher
- Unzip the downloaded file to C:\Program Files\Occult Watcher\OccultWatcher.Addins.dll
- Restart OccultWatcher

You will now have two new items under "Add-ins": "Meade SAO Star Search" and "Copy Event Details"

The "Meade SAO Star Search" will show up a form and ask you to enter a SAO star number. If you already have the number in your clipboard it will use the value from the clipboard as a default value. After you press "Find" if the star is found it will display its coordinates and magnitude.

"Copy Event Details" could be executed from both the "Add-in" menu and the evens list context menu. It will simply copy information about the event in our clipboard and display it. You can then paste it in other programs.

Developing Add-ins for OccultWatcher

If you want to develop your own add-in this page will provide you with the technical information you will need. I have provided really in-depth information so if you don't understand everything (especially if you are new to .NET) then don't worry. Writing an add-in is very simple. Take your time, have a look at the sample code and you can figure out what to do even without reading the information below. The idea of this page is to give you an overview of how add-ins function and integrate with OccultWatcher and also to be used as advanced programming reference for people that want to achieve maximum results.

OccultWatcher is developed using Microsoft .NET Framework 2.0 and the best way to implement add-ins is by using the same technology. Alternately you could implement your add-in as a COM object or an exported function from a DLL using C++, VB6 or other language and then use a simple .NET wrapper which will call your objects/functions from .NET using COM Interop or PI-Invoke. If you know how to do the part in C++ or VB6 but you don't know how to implement the wrapper class in .NET then I can help you with that.

So I will assume that you are implementing the Add-in in .NET and will talk about what you need to do. The same guidelines apply for implementing the wrapper class I mentioned above. So first of all you should download the OccultWatcher SDK. It contains the source code of the file OccultWatcher.SDK.dll which is part of the standard distribution of OccultWatcher and also the full source code of the "OW Little Helpers" add-in which you can use as a reference.

An add-in for OccultWatcher is simply a class that implements the IOWAddin interface and resides in assembly that is copied to the same folder as OccultWatcher. When OccultWatcher starts up it loads all DLL files from the same folder, checks if they are .NET assemblies, then enumerates all classes exposed by those assemblies and checks whether any of them implements the IOWAddin interface. Those classes will be loaded as Add-ins.

After OccultWatcher has enumerated all classes that implement an add-in it will instantiate each of them and will call InitializeAddin(). Then it will retrieve the supported Add-in actions by calling SupportedActions() for each of the add-ins. There are 3 types of actions and they are defined by the OWAddinActionType enum.

AllEventsAction is an action that doesn't operate on any specific event and is enabled at all times. Such an action is the "Meade SAO Stars Search" from OW Little Helpers.

Then the SelectedEventAction operates on the currently selected event and is only enabled when there is a selected event. Such an action is the "Create C2A Occultation Map" from the standard C2A Add-in.

And finally there is an action type called EventReceiver which allows you to define event handler for some events raised by OccultWatcher. These events are defined by the OWEventArguments class and currently include: event indicating when asteroidal occultation events are added by the filer, the analysis has started or completed, the main form has moved or has changed its state or when the current language has been changed by the user. The language change event can be used by your add-in for loading localized settings. If you have an idea for an add-in that requires another event not listed here then I could be able to add it for you if that's possible.

OccultWatcher will create a menu item under "Add-ins" for each AllEventsAction and then will create a menu item under "Add-ins" and also in the events list context menu for each SelectedEventAction. Every time one of these two menus are shown (dropped down or popped up) OccultWatcher will call ShouldDisplayAction() for each SelectedEventAction to determine whether the action should be enabled/disabled for the particular event. This allows you to create actions that operate only on specific asteroidal events.

When the user clicks on one of the menu items representing an add-in action, OccultWatcher will call ExecuteAction() passing the action ID and also some other parameters. Note that the parameter IOWAsteroidEvent astEvent actually implements more than one interface. .NET allows you to cast this IOWAsteroidEvent object to those other interfaces directly by using the "as" operator or an explicit cast. The other two interfaces implemented by astEvent are IOWLocalEventData and IOWUserConfig and you can use them to get local data for the current site in OW or current OW configuration info such as site coordinates, local event time, star altitude, configuration settings etc. Check out the interface members from the SDK for more information.

If you need your Add-in to have your own configuration settings and you want the user to be able to configure it then you should set SupportsConfiguration = true in the OWAddinInfo structure you return by GetAddinInfo(). Then OccultWatcher will add a sub-menu under "Add-ins" -> "Configure Add-ins" for your add-in and will call Configure() when the user clicks on the sub-menu item. It's up to you to save and load your configuration settings. If you choose to use the .NET Isolated File Storage to save/load your configuration setting from then bear in mind that every time you change your assembly version you will effectively reset your configuration and your new assembly will not be able to read the settings from the old version. To avoid this you should consider not changing the assembly version of your add-in at all but instead vary the file version.

OccultWatcher also gives you ability to automatically upgrade your Add-in when you want to publish a new version. The only thing you need to do is to specify the file url where you are going to publish the new versions of the add-in as the UpdateUrl member of the OWAddinInfo structure you return by GetAddinInfo(). Every time OccultWatcher checks for updates it will also check the specified UpdateUrls for all registered add-ins and if a new version of the add-ins is available. Then it will download the file and upgrade the add-in.

You can provide an UpdateUrl to a zip or a dll file. Urls pointing to other file types will be ignored. If you provide a zip file then OccultWatcher will extract all files including the directory structure in the OccultWatcher execution location. Please note that OW will use the HTTP headers to determine whether a new version of the file is available on the web server before proceeding with a download. Then it will check the assembly version and the file version of the assembly that exposes your add-in before proceeding with an upgrade. So make sure you increase your file version (or/and assembly version) of your new version for the upgrade to work properly.

The IOWAddin interface contains the following members:


        /// 

        /// InitializeAddin() is called after the addin is loaded from OccultWatcher.

        /// It will be also called when the Add-ins are reinitialized when the current language settings are changed.

        /// In this method you will typically initialize any shared resources you are going to use from your addin actions.

        /// 


        void InitializeAddin(IOWHost hostInfo);

        

        


        /// 

        /// FinalizeAddin() is called by OccultWatcher when it is about to shut down normally.

        /// It will be also called when the Add-ins are reinitialized when the current language settings have changed.

        /// Note that during the updates it is possible that FinalizeAddin() may not be called and in such a case 

        /// OccultWatcher will restart without notice to the loaded addins

        /// 


        void FinalizeAddin();

        

        

        
        /// 

        /// Return information about the addin.

        /// 


        OWAddinInfo GetAddinInfo();
        

        


        /// 

        /// You can show your own configuration forms in this method

        /// 


        /// owner: OccultWatcher main window handle

        /// 

        void Configure(IWin32Window owner);

        

        

  
        /// 

        /// Returns a list of the supported actions. They must have unique IDs.

        /// 


        /// returns: List of the supported actions

        /// 

        IEnumerable<OWAddinAction> SupportedActions();

        

        

  
        /// 

        /// This method is called by OccultWatcher before displaying the menu item link

        /// that triggers this event. This is a good place to determine whether this action

        /// should be enabled or disabled for the selected event.

        /// 


        /// actionId: The action addin as specified in the OWAddinAction structure returned by SupportedActions()

        /// astEvent: The currently selected event in OccultWatcher

        /// returns: true if the action should be displayed (enabled/visible) for this event, otherwise false

        /// 

        bool ShouldDisplayAction(int actionId, IOWAsteroidEvent astEvent);

        

        

  
        /// 

        /// This is the main method in your addin. This is where you run your custom code to do the useful

        /// things you want to do.

        /// 


        /// actionId: The action addin as specified in the OWAddinAction structure returned by SupportedActions()

        /// astEvent: The currently selected event in OccultWatcher

        /// owner: OccultWatcher main window handle

        /// eventArgs: In a case of event receiver action this are the event arguments

        /// 

        void ExecuteAction(int actionId, IOWAsteroidEvent astEvent, IWin32Window owner, OWEventArguments eventArgs);

Have a look at how OW Little Helpers add-in implements all those members for some more clues and if you end up implementing an add-in that you think may be useful to the others, please contact me and I will put it for download on this page! If you have any additional questions - don't hesitate to contact me and I will be glad to help.

Happy coding!