Added further documentation for sfx2

Added further documentation on the sfx2 framework. Turned the packed odg file into a git-friendly html+svg file. Change-Id: I0b86f00ffb9355d4cbc911a7b406b1b76dbf62ac Signed-off-by: Lennard Wasserthal <Wasserthal@nefkom.net> Reviewed-on: https://gerrit.libreoffice.org/3871 Reviewed-by: Norbert Thiebaud <nthiebaud@gmail.com> Tested-by: Norbert Thiebaud <nthiebaud@gmail.com>
author: Lennard Wasserthal <Wasserthal@nefkom.net> 2013-05-12 17:26:14 +0200
committer: Norbert Thiebaud <nthiebaud@gmail.com> 2013-05-13 18:17:32 +0000
commit: 42824b9c5639d8d2ab621e33825b0d19ededff82 (patch)
tree: b4a55e0e25ff4bd2539beb4c5f196896d2c6209a /sfx2/doc
parent: 1887d2e944510b59b975c5ffbc8c0e12335d1a57 (diff)
3 files changed, 177 insertions, 0 deletions
diff --git a/sfx2/doc/sfx2doc.html b/sfx2/doc/sfx2doc.html
new file mode 100644
index 000000000000..4ac9f29bea2c
--- /dev/null
+++ b/sfx2/doc/sfx2doc.html
@@ -0,0 +1,78 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<HTML>
+<BODY LANG="de-DE" DIR="LTR">
+<P CLASS="western">Signal processing in the sfx2 Interface.
+State of 5.5.2013<BR><BR>
+related modules are: svidl (idl compiler), framework (command processing routines), rsc (resource compiler, see below), vcl (command processing routines)<BR>
+Here is a chart how the "slot-model" of the command processing framework works.
+<BR>
+Menu commands and Key accelerators are stored
+asynchronously into a UNO command stack and later executed
+seqentially.<BR>
+</P>
+<P CLASS="western" STYLE="margin-bottom: 0.5cm"><IMG SRC="sfx2doc0001.svg" NAME="Grafik1" ALIGN=BOTTOM WIDTH=950 HEIGHT=350 BORDER=0></P>
+<P CLASS="western" STYLE="margin-bottom: 0.5cm"><BR><BR>
+
+Changing the system: <b>In Order to add a function to a shell,
+Add an entry to the .sdi file corresponding to that SfxShell</b><BR>
+<FONT style="color: red">Example:</FONT>
+<BR>
+<PRE><FONT style="background-color: black" color="white">SID_PASTE  [ ExecMethod = ExecDrawFunc; StateMethod = GetDrawFuncState; Export = FALSE; ]</FONT></PRE><BR>
+The "state" method is the method called to checked whether that command is active now. The "exec" method is called when the command should be processed by the shell. Both functions obtain a SfxRequest Object as a parameter, declared in ./include/sfx2/request.hxx.<BR>
+Each Application Window has ONE Dispatcher.
+This registers all SfxShells (or rather their
+subclasses) which can get commands from the user AT THE MOMENT.
+These shells are created when the edit mode they
+are part of is first used, but not discarded until the window closes.
+./sfx2/source/control/dispatch.cxx:
+void SfxDispatcher::Pop receives Pushes and Pops
+of the shell to/from the stack.
+The real Pushing/Popping, however, is done during
+SfxDispatcher::FlushImpl
+Main dispatching routine In
+./sfx2/source/control/unoctitm.cxx
+SfxDispatchController_Impl::dispatch.
+<BR>
+SfxDispatchController::_FindServer
+gets the SfxInterfaces of the shells. They are defined by macro calls
+to SFX_IMPL_INTERFACE, defined in include/sfx2/shell.hxx .
+
+Upon GetInterface, they yield their pInterface,
+which, upon GetSlot, returns a SfxSlot of that Shell
+For that command, which is then Executed with
+Dispatcher::Execute.
+If the program is set into another mode, for
+example by clicking a hovering object in writer
+after Text editing, all shells are removed from
+the dispatcher and new shells are pushed
+to match the current mode.
+<BR>
+<B> How to build menus</B><BR>
+In order to introduce a menu command, the uno command must be linked to a slot name.<BR>
+This is done in different sdi files, such as sfx2/sdi/sfx.sdi.
+There, you <U>define</U> the slot:<BR>
+<FONT style="color: red">Structure:</FONT>
+
+<PRE>
+<FONT style="background-color: black" color="white">
+SfxVoidItem uno_name_the_part_after_colon SID_COMMAND_NAME
+()                                                        
+[                                                         
+  /* initialization of variables is coming here */        
+]                                                         
+</PRE>
+</FONT>
+In ./include/sfx2/sfxsids.hrc, the defines of the slot names and their numbers are entered. The numbers are just needed because definitions cannot be enums, and for compatibility.<BR>
+
+In ./officecfg/registry/data/org/openoffice/Office/UI,
+there are .xcu ended xml files that define the single menu items.
+They contain the US- language name and the .uno: command.<BR>
+In ./include/sfx2/sfxcommands.h, the uno command names are listed.
+
+
+<BR><BR>
+The resource compiler, which creates files some GetState methods refer to, is in the ./rsc directory. It is a separate executable, invoked at compile time.<BR>
+
+</P>
+</BODY>
+</HTML>
+\ No newline at end of file
diff --git a/sfx2/doc/sfx2doc.odg b/sfx2/doc/sfx2doc.odg
deleted file mode 100644
index 01d13bbd9e30..000000000000
--- a/sfx2/doc/sfx2doc.odg
+++ /dev/null
diff --git a/sfx2/doc/sfx2doc0001.svg b/sfx2/doc/sfx2doc0001.svg
new file mode 100644
index 000000000000..070f7568fca4
--- /dev/null
+++ b/sfx2/doc/sfx2doc0001.svg
@@ -0,0 +1,99 @@
+<!DOCTYPE svg>
+<svg xmlns="http://www.w3.org/2000/svg"
+     xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 950 350">
+  <defs>
+    <g id="box00" transform="translate(50,75)">
+      <rect height="50" width="100" style="fill:none;stroke-width:1;stroke:rgb(0,0,0)"/>
+      <text x="10" y="20" font-size="16">SfxView</text>
+      <text x="10" y="40" font-size="16">Subclass</text>
+    </g>
+    <g id="box01" transform="translate(50,75)">
+      <rect height="50" width="100" style="fill:none;stroke-width:1;stroke:rgb(0,0,0)"/>
+      <text x="70" y="40" font-size="7">Missing</text>
+    </g>
+    <g id="box02" transform="translate(50,75)">
+      <rect height="50" width="100" style="fill:none;stroke-width:1;stroke:rgb(0,0,0)"/>
+      <text x="10" y="10" font-size="10">Ability to process</text>
+      <text x="60" y="40" font-size="7">SfxSlot</text>
+    </g>
+  </defs>
+  <g>
+  <use xlink:href="#box00" transform="translate(150,0)"/>
+  <g transform="translate(250,0)">
+    <use xlink:href="#box02" />
+    <text x="60" y="100" font-size="10">"SID_PASTE"</text>
+  </g>
+  <g transform="translate(350,0)">
+    <use xlink:href="#box02" />
+    <text x="60" y="100" font-size="10">"SID_CUT"</text>
+  </g>
+  <use xlink:href="#box01" transform="translate(450,0)"/>
+  <use xlink:href="#box01" transform="translate(550,0)"/>
+  <use xlink:href="#box01" transform="translate(650,0)"/>
+  <use xlink:href="#box00" transform="translate(150,50)"/>
+  <g transform="translate(250,50)">
+    <use xlink:href="#box02" />
+    <text x="60" y="100" font-size="10">"SID_PASTE"</text>
+  </g>
+  <use xlink:href="#box01" transform="translate(350,50)"/>
+  <use xlink:href="#box01" transform="translate(450,50)"/>
+  <use xlink:href="#box01" transform="translate(550,50)"/>
+  <g transform="translate(650,50)">
+    <use xlink:href="#box02" />
+    <text x="60" y="100" font-size="10">"SID_FLOAT"</text>
+  </g>
+  <use xlink:href="#box00" transform="translate(150,100)"/>
+  <g transform="translate(250,100)">
+    <use xlink:href="#box02" />
+    <text x="60" y="100" font-size="10">"SID_PASTE"</text>
+  </g>
+  <g transform="translate(350,100)">
+    <use xlink:href="#box02" />
+    <text x="60" y="100" font-size="10">"SID_CUT"</text>
+  </g>
+  <use xlink:href="#box01" transform="translate(450,100)"/>
+  <g transform="translate(550,100)">
+    <use xlink:href="#box02" />
+    <text x="60" y="100" font-size="10">"SID_VOMIT"</text>
+  </g>
+  <g transform="translate(650,100)">
+    <use xlink:href="#box02" />
+    <text x="60" y="100" font-size="10">"SID_FLOAT"</text>
+  </g>
+  <g transform="translate(350,0)">
+    <polygon fill="red" points="-20 80 -10 80 -10 0 10 0 10 80 20 80 0 100"/>
+    <text fill="white" stroke="white" stroke-width="0.1" transform="translate(-6,0) rotate(90, 0, 0) "> SID_PASTE </text>
+  </g>
+  <g transform="translate(450,0)">
+    <polygon fill="cyan" points="-20 80 -10 80 -10 0 10 0 10 80 20 80 0 100"/>
+    <text fill="white" stroke="white" stroke-width="0.1" transform="translate(-6,0) rotate(90, 0, 0) "> SID_CUT </text>
+  </g>
+  <g transform="translate(550,0)">
+    <polygon fill="lightsteelblue" points="-20 230 -10 230 -10 0 10 0 10 230 20 230 0 250"/>
+    <text fill="white" stroke="white" stroke-width="0.1" transform="translate(-6,0) rotate(90, 0, 0) "> SID_NEY </text>
+  </g>
+  <g transform="translate(650,0)">
+    <polygon fill="orange" points="-20 180 -10 180 -10 0 10 0 10 180 20 180 0 200"/>
+    <text fill="white" stroke="white" stroke-width="0.1" transform="translate(-6,0) rotate(90, 0, 0) "> SID_VOMIT </text>
+  </g>
+  <g transform="translate(100,25)">
+    <polygon fill="steelblue" points="-100 130 -50 130 -50 200 50 200 50 130 100 130 0 50"/>
+    <text fill="black" stroke="none" transform="translate(-40,100) " font-size="10">last pushed</text>
+    <text fill="black" stroke="none" transform="translate(-40,115) " font-size="10">=lower nSlot</text>
+    <text fill="black" stroke="none" transform="translate(-40,135) " font-size="10">last pushed slots</text>
+    <text fill="black" stroke="none" transform="translate(-40,150) " font-size="10">go first</text>
+  </g>
+  <path d="M200,75 a10,10 0 0,1 10,-10 l35,0 l5,-10 l5,10 l35,0 a10,10 0 0,1 10,10" stroke-width="1" stroke="rgb(0,0,0)" style="fill:none"/>
+  <text fill="black" stroke="none" transform="translate(200,10)" font-size="10"> dispatcher's Shell stack</text>
+  <text fill="black" stroke="none" transform="translate(200,25)" font-size="10"> (a Stack of pointers) </text>
+  <text fill="black" stroke="none" transform="translate(200,40)" font-size="10"> Declared in dispatch.cxx </text>
+  <text fill="black" stroke="none" transform="translate(200,55)" font-size="10"> As SfxShellStack_Impl </text>
+  <text fill="black" stroke="none" transform="translate(475,270)" font-size="20"> Command ignored </text>
+  <polygon fill="black" points="750,110 750,90 755,95 845,45 855,55 765,105 770,110"/>
+  <text fill="black" stroke="none" transform="translate(850,30)" font-size="10">Empty: no entry in</text>
+  <text fill="black" stroke="none" transform="translate(850,40)" font-size="10">sdi file corresponding</text>
+  <text fill="black" stroke="none" transform="translate(850,50)" font-size="10">to that subclass</text>
+  </g>
+
+</svg>
+<!-- vim:set shiftwidth=2 softtabstop=2 expandtab: -->
author	Lennard Wasserthal <Wasserthal@nefkom.net>	2013-05-12 17:26:14 +0200
committer	Norbert Thiebaud <nthiebaud@gmail.com>	2013-05-13 18:17:32 +0000
commit	42824b9c5639d8d2ab621e33825b0d19ededff82 (patch)
tree	b4a55e0e25ff4bd2539beb4c5f196896d2c6209a /sfx2/doc
parent	1887d2e944510b59b975c5ffbc8c0e12335d1a57 (diff)