Extension doc.

Doc/sphinx/docdoc.rst

@@ -24,7 +24,7 @@ If you want to build the documentation yourself, you should install
 sphinx-python. 
 
 Move to the ``Simba/doc/sphinx`` directory and call ``make all``. 
-This will place the doc in html format in _build/html. 
+This will place the doc in html format in ``_build/html``. 
 
 .. note::
     The build instructions are for Linux only. If you want to build the doc on
@@ -54,6 +54,7 @@ you are writing a new chapter, then placing the file in the correct directory is
 something we'd like you to consider.
 
 If you wrote a chapter for the ``Simba Reference`` or ``Scripting Reference``
-part of the documentation, place it in the ``simbaref`` or ``scriptref``
-repectively. Any other files can be put directly in the root of the sphinx
-folder. (The same place as ``index.rst``)
+part of the documentation, place it in the ``simbaref`` folder or in the
+``scriptref`` folder repectively.
+Any other files can be put directly in the root of the sphinx folder.
+(The same place as ``index.rst``)

Doc/sphinx/reference.rst

@@ -4,6 +4,7 @@ Simba Reference
 All Simba documentation should be in here.
 
 .. toctree::
+    :maxdepth: 2
 
     simbaref/extensions.rst
 

Doc/sphinx/simbaref/extensions.rst

@@ -1,5 +1,195 @@
 Writing Simba Extensions
 ========================
 
+Simba extensions are scripts written in PascalScript that can be embedded into
+Simba. Purposes vary from updaters to full blown dtm and bitmap editors.
+
+.. FIXME link to dtm and bitmap
+
+How they work
+-------------
+
+Extensions are event based. This means you don't have some ``loop`` in your
+program that never ends and does all the logic for you. When a system is event
+based, you implement some functions and those are called on a certain event.
+
+Hooks overview
+--------------
+
+.. references
+
+Extension core hooks
+--------------------
+
+Simba offers several core hooks: init, free, attach and detach. These are used
+to initialize, show, hide and free your extension. GetName and GetVersion are
+called to retreive the name and version of an extension.
+
+init
+~~~~
+
+Called when the Extension is initialized. 
+
+.. code-block:: pascal
+    :linenos:
+
+    procedure init;
+    begin;
+        Writeln('Init your extension here.');
+    end;    
+
+If you want to add a button to the menu, do it now.
+From the SRL updater extension:
+
+.. code-block:: pascal
+    :linenos:
+
+    procedure Init;
+    begin;
+      MainMenuItem := TMenuItem.Create(Simba_MainMenu);  
+      MainMenuItem.Caption := 'SRL';
+      Simba_MainMenu.Items.Add(MainMenuItem);
+    
+      MenuCheck := TMenuItem.Create(MainMenuItem);
+      MenuCheck.Caption := 'Check for new SRL';
+      MenuCheck.OnClick := @OnSRLCheckClick;
+      MainMenuItem.Add(MenuCheck);
+    
+      MenuUpdate := TMenuItem.Create(MainMenuItem);
+      MenuUpdate.Caption := 'Update SRL';
+      MenuUpdate.OnClick := @OnSRLUpdateClick;
+      MainMenuItem.Add(MenuUpdate);
+      
+      AutoUpdate := TMenuItem.Create(MainMenuItem);
+      AutoUpdate.Caption := 'Automatically update';
+      AutoUpdate.OnClick := @SetAutoUpdate;
+      AutoUpdate.Checked := LowerCase(Settings.GetKeyValueDef('AutoUpdate',
+                                    'True')) = 'true';
+      MainMenuItem.Add(AutoUpdate);
+     
+      Timer := TTimer.Create(Simba);
+      Timer.Interval := 5000;
+      Timer.OnTimer := @OnUpdateTimer;
+      Timer.Enabled :=AutoUpdate.Checked;
+    
+      started := True;
+    end;     
+
+free
+~~~~
+
+Called upon freeing the extension. Usually this means that Simba is closed.
+
+.. code-block:: pascal
+    :linenos:
+    
+    procedure free;
+    begin
+        if started then
+            writeln('Init was called');
+    end;
+
+From the SRL updater extension:
+
+.. code-block:: pascal
+    :linenos:
+
+    procedure Free;
+    begin
+      if (started) then
+        Timer.Enabled := False;
+        { Freeing the components is not needed, as they will be freed
+           upon the freeing of Simba. }
+    end;    
+
+attach
+~~~~~~
+
+Called when your extension has been enabled.
+
+From the SRL updater extension:
+
+.. code-block:: pascal
+    :linenos:
+      
+    procedure Attach;
+    begin;
+      Writeln('From now on, you shall be alerted as to when your SRL is out of date!');
+      MainMenuItem.Visible := True;
+      Timer.Enabled := AutoUpdate.Checked;
+    end;        
+
+
+
+detach
+~~~~~~
+
+Called when your extension has been disabled. (This is not the same as freeing)
+
+.. code-block:: pascal
+    :linenos:
+
+    Procedure Detach;
+    begin
+      Timer.Enabled := False;
+      MainMenuItem.Visible := False;
+    end;    
+
+GetName
+~~~~~~~
+
+Called when Simba requests the name of your extension.
+
+.. code-block:: pascal
+    :linenos:
+
+    function GetName : string;
+    begin;
+      result := 'SRL Updater';
+    end;   
+
+GetVersion
+~~~~~~~~~~
+
+Called when Simba requests the version of the extension.
+
+.. code-block:: pascal
+    :linenos:
+
+    function GetVersion : string;
+    begin;
+      result := '1.0';
+    end;    
+
+More extension hooks
+~~~~~~~~~~~~~~~~~~~~
+
+The following hooks are called upon if the event that the name describes has happened.
+
+
+onOpenConnection
+~~~~~~~~~~~~~~~~
+
+onWriteFile
+~~~~~~~~~~~
+
+onOpenFile
+~~~~~~~~~~
+
+onColourPick
+~~~~~~~~~~~~
+
+onScriptStart
+~~~~~~~~~~~~~
+
+
+Example code
+------------
+
+Explanatory code for all:
+
+.. literalinclude:: extraextensionhooks.sex
+    :language: pascal
+    :linenos:
+
 
-Extensions

Doc/sphinx/simbaref/extraextensionhooks.sex

@@ -0,0 +1,67 @@
+program new;
+
+procedure init;
+begin;
+  Writeln('init your extension here');
+end;
+procedure onOpenConnection(var url : string; var Cont : boolean);
+begin
+  Writeln('Opening url: '  + url);
+  Writeln('We shall allow this.. For now!! Gna Gna!');
+  Cont := True;
+end;
+procedure onWriteFile(var FileName : string; var Cont : boolean);
+begin
+  Writeln('So.. You want to write to file: ' + FileName);
+  Writeln('Well for this time only!');
+  Cont := True;
+end;
+
+procedure onOpenFile(var FileName : string; var Cont : boolean);
+begin
+  Writeln('So you want to open this file: ' + filename);
+  Writeln('Well I don''t care much, lets see what the other hooks think!');
+  //Not set Cont as we don't care, while other hooks might
+end;
+
+procedure onColourPick(const Colour,x,y : integer);
+begin
+  Writeln('So you''ve picked a color, huh!?');
+  Writeln(inttostr(colour) + ' attuh (' + inttostr(x) +',' + inttostr(y) + ')');
+end;
+ 
+procedure onScriptStart(var Script : string; var Cont : boolean);
+begin
+  Writeln('So you want to compile the following script!!');
+  Writeln(script);
+  Writeln('lets allow that for now ;)');
+  Cont := True;
+end;
+procedure free;
+begin
+  Writeln('Free your extension here');
+end;
+
+procedure Attach;
+begin;
+  Writeln('Your extension has been enabled, do stuff here');
+end;
+
+Procedure Detach;
+begin
+  Writeln('Your extension has ben disabled, do stuff here');
+end;
+
+//Called to retrieve the name of your extension
+function GetName : string;
+begin;
+  result := 'Leet Extension';
+end;
+
+//Called to retrieve the version of your extension
+function GetVersion : string;
+begin;
+  result := '0.001';
+end;
+begin
+end.