From 84e59131c4d1c2545f5bcd8b5e23fd70d124443f Mon Sep 17 00:00:00 2001 From: Merlijn Wajer Date: Sat, 12 Jun 2010 22:11:31 +0200 Subject: [PATCH] Extension doc. --- Doc/sphinx/docdoc.rst | 9 +- Doc/sphinx/reference.rst | 1 + Doc/sphinx/simbaref/extensions.rst | 192 +++++++++++++++++++- Doc/sphinx/simbaref/extraextensionhooks.sex | 67 +++++++ 4 files changed, 264 insertions(+), 5 deletions(-) create mode 100644 Doc/sphinx/simbaref/extraextensionhooks.sex diff --git a/Doc/sphinx/docdoc.rst b/Doc/sphinx/docdoc.rst index d3e8d8c..2f6e484 100644 --- a/Doc/sphinx/docdoc.rst +++ b/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``) diff --git a/Doc/sphinx/reference.rst b/Doc/sphinx/reference.rst index d52ca24..d787218 100644 --- a/Doc/sphinx/reference.rst +++ b/Doc/sphinx/reference.rst @@ -4,6 +4,7 @@ Simba Reference All Simba documentation should be in here. .. toctree:: + :maxdepth: 2 simbaref/extensions.rst diff --git a/Doc/sphinx/simbaref/extensions.rst b/Doc/sphinx/simbaref/extensions.rst index 3d7c830..1398b60 100644 --- a/Doc/sphinx/simbaref/extensions.rst +++ b/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 diff --git a/Doc/sphinx/simbaref/extraextensionhooks.sex b/Doc/sphinx/simbaref/extraextensionhooks.sex new file mode 100644 index 0000000..59b84ea --- /dev/null +++ b/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.