From graphics-request at octave dot org Sun Dec 19 16:48:08 2004
Subject: Re: Octave GUI API: Proposal.
From: N Smethurst <nick dot smethurst at free dot fr>
To: graphics at octave dot org
Date: Sun, 19 Dec 2004 23:46:42 +0100

--Boundary-00=_STgxBN9xmTTWIR8
Content-Type: text/plain;
  charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

On Sunday 19 December 2004 20:02, Shai Ayal wrote:
> Presto! you have an instant API, no deep knowledge of octave is needed,
> and the responsibility of writing all the interface is now on the
> programmer of each application which is highly motivated to have his
> application fit in the API. We also do not impose a callback structure
> on the applications.

The reason I had for implementing the basic handle graphics objects in Octa=
ve=20
was to provide the possibility for the external graphics application to=20
initiate function callbacks to Octave. For example, the user creates a butt=
on=20
object in the graphical application window by issuing a command in Octave.=
=20
The button is linked to an Octave function. When the button is clicked, the=
=20
graphical application sends Octave the callback function name. Without this=
,=20
there is no possibility of creating interactive Octave GUIs.

A system with callbacks cannot be implemented using only external files (we=
=20
would need some kind of message insertion mechanism in to the Octave thread=
).=20
Hence I thought the most appropriate solution would be to implement the cor=
e=20
handle graphics object types (root, figure, axes, line, text, surface, patc=
h)=20
in Octave along with an incoming message handler thread. Then, as you=20
suggest, everything else coulds be implemented as m or oct files.

Hence:

internal Octave types linked to plugin and message handler:
   1. Base objects: figure,axes,line,text,surface,patch

m or oct files:
   2. Base manipulators: =A0get,set,delete,gcf,gca,clf,cla
   3. plot,surf,mesh etc..

The bulk of the work would still be common (maintained elsewhere as you say=
).=20
Only the base object implementation would be unique to each visualisation=20
application (which it would have to be anyway, even if we implement the=20
Octave end as m files), and even then it would share a common built-in Octa=
ve=20
interface leading to the application's plugin.

There is another advantage to this approach. It allows the use of a syntax=
=20
more appropriate to an object based system:

=46or example, instead of:
   mysurface =3D surface(X, Y, Z);
   set(mysurface, 'AmbientStrength', 0.5);
   set(mysurface, 'DiffuseStrength', 0.8);
   strength =3D get(mysurface, 'AmbientStrength');

One would say:
   mysurface =3D surface(X, Y, Z);
   mysurface.AmbientStrength =3D 0.5;
   mysurface.DiffuseStrength =3D 0.8;
   strength =3D mysurface.AmbientStrength;

This type of syntax seems to be prefered by some other people as well:

http://www.octave.org/mailing-lists/octave-graphics/1999/17

> As I've said before, if there is a better way of doing things, I think
> we should use the better way with the idea of being able to provide a
> compatibility layer.  For example, would
>=20
>   gui_object.background_color =3D "blue";
>   gui_object.geometry =3D "...";
>
> jwe

As John mentioned back in 1999, the set/get mechanism could be provided as =
a=20
compatibility layer.

However, as I said in my past email, I've watched the same or similar=20
discussions take place over a period of 5 years, and no one has done anythi=
ng=20
in this time!

To begin, we need to implement the core graphical object types in the Octav=
e=20
code base by creating something similar to an non-configurable octave struc=
t.

Example:

axes
    aLim                (double[2])
    ambientLightColor   (double[3])
    cameraPosition      (double[3])
    cameraTarget        (double[3])
    cameraUpVector      (double[3])
    cameraViewAngle     (double)
    cLim                (double[2])
    color               (double[3])
    dataAspectRatio     (double[3])
    gridLineStyle       (enum)
    lineWidth           (double)
    plotBoxAspectRatio  (double[3])
    tickLength          (double[2])
    xColor              (double[3])
    xLim                (double[2])
    xTick               (double array)
    xTickLabel          (string array)
    yColor              (double[3])
    yLim                (double[2])
    yTick               (double array)
    yTickLabel          (string array)
    zColor              (double[3])
    zLim                (double[2])
    zTick               (double array)
    zTickLabel          (string array)
 =20
The contents can be modified, but not configured (i.e. the user cannot add=
=20
other objects into the object as with a normal struct).

After we have the core objects, the rest will naturally follow with the=20
community writing m and oct files for the higher level functionality. The=20
callback manager can wait till later.

Nic

--Boundary-00=_STgxBN9xmTTWIR8
Content-Type: text/html;
  charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

<html><head><meta name=3D"qrichtext" content=3D"1" /></head><body style=3D"=
font-size:10pt;font-family:Courier 10 Pitch">
<p>On Sunday 19 December 2004 20:02, Shai Ayal wrote:</p>
<p>&gt; Presto! you have an instant API, no deep knowledge of octave is nee=
ded,</p>
<p>&gt; and the responsibility of writing all the interface is now on the</=
p>
<p>&gt; programmer of each application which is highly motivated to have hi=
s</p>
<p>&gt; application fit in the API. We also do not impose a callback struct=
ure</p>
<p>&gt; on the applications.</p>
<p></p>
<p>The reason I had for implementing the basic handle graphics objects in O=
ctave </p>
<p>was to provide the possibility for the external graphics application to =
</p>
<p>initiate function callbacks to Octave. For example, the user creates a b=
utton </p>
<p>object in the graphical application window by issuing a command in Octav=
e. </p>
<p>The button is linked to an Octave function. When the button is clicked, =
the </p>
<p>graphical application sends Octave the callback function name. Without t=
his, </p>
<p>there is no possibility of creating interactive Octave GUIs.</p>
<p></p>
<p>A system with callbacks cannot be implemented using only external files =
(we </p>
<p>would need some kind of message insertion mechanism in to the Octave thr=
ead). </p>
<p>Hence I thought the most appropriate solution would be to implement the =
core </p>
<p>handle graphics object types (root, figure, axes, line, text, surface, p=
atch) </p>
<p>in Octave along with an incoming message handler thread. Then, as you </=
p>
<p>suggest, everything else coulds be implemented as m or oct files.</p>
<p></p>
<p>Hence:</p>
<p></p>
<p>internal Octave types linked to plugin and message handler:</p>
<p>   1. Base objects: figure,axes,line,text,surface,patch</p>
<p></p>
<p>m or oct files:</p>
<p>   2. Base manipulators: =A0get,set,delete,gcf,gca,clf,cla</p>
<p>   3. plot,surf,mesh etc..</p>
<p></p>
<p>The bulk of the work would still be common (maintained elsewhere as you =
say). </p>
<p>Only the base object implementation would be unique to each visualisatio=
n </p>
<p>application (which it would have to be anyway, even if we implement the =
</p>
<p>Octave end as m files), and even then it would share a common built-in O=
ctave </p>
<p>interface leading to the application's plugin.</p>
<p></p>
<p>There is another advantage to this approach. It allows the use of a synt=
ax </p>
<p>more appropriate to an object based system:</p>
<p></p>
<p>For example, instead of:</p>
<p>   mysurface =3D surface(X, Y, Z);</p>
<p>   set(mysurface, 'AmbientStrength', 0.5);</p>
<p>   set(mysurface, 'DiffuseStrength', 0.8);</p>
<p>   strength =3D get(mysurface, 'AmbientStrength');</p>
<p></p>
<p>One would say:</p>
<p>   mysurface =3D surface(X, Y, Z);</p>
<p>   mysurface.AmbientStrength =3D 0.5;</p>
<p>   mysurface.DiffuseStrength =3D 0.8;</p>
<p>   strength =3D mysurface.AmbientStrength;</p>
<p></p>
<p>This type of syntax seems to be prefered by some other people as well:</=
p>
<p></p>
<p>http://www.octave.org/mailing-lists/octave-graphics/1999/17</p>
<p></p>
<p>&gt; As I've said before, if there is a better way of doing things, I th=
ink</p>
<p>&gt; we should use the better way with the idea of being able to provide=
 a</p>
<p>&gt; compatibility layer.  For example, would</p>
<p>&gt; </p>
<p>&gt;   gui_object.background_color =3D &quot;blue&quot;;</p>
<p>&gt;   gui_object.geometry =3D &quot;...&quot;;</p>
<p>&gt;</p>
<p>&gt; jwe</p>
<p></p>
<p>As John mentioned back in 1999, the set/get mechanism could be provided =
as a </p>
<p>compatibility layer.</p>
<p></p>
<p>However, as I said in my past email, I've watched the same or similar </=
p>
<p>discussions take place over a period of 5 years, and no one has done any=
thing </p>
<p>in this time!</p>
<p></p>
<p>To begin, we need to implement the core graphical object types in the Oc=
tave </p>
<p>code base by creating something similar to an non-configurable octave st=
ruct.</p>
<p></p>
<p>Example:</p>
<p></p>
<p>axes</p>
<p>    aLim                (double[2])</p>
<p>    ambientLightColor   (double[3])</p>
<p>    cameraPosition      (double[3])</p>
<p>    cameraTarget        (double[3])</p>
<p>    cameraUpVector      (double[3])</p>
<p>    cameraViewAngle     (double)</p>
<p>    cLim                (double[2])</p>
<p>    color               (double[3])</p>
<p>    dataAspectRatio     (double[3])</p>
<p>    gridLineStyle       (enum)</p>
<p>    lineWidth           (double)</p>
<p>    plotBoxAspectRatio  (double[3])</p>
<p>    tickLength          (double[2])</p>
<p>    xColor              (double[3])</p>
<p>    xLim                (double[2])</p>
<p>    xTick               (double array)</p>
<p>    xTickLabel          (string array)</p>
<p>    yColor              (double[3])</p>
<p>    yLim                (double[2])</p>
<p>    yTick               (double array)</p>
<p>    yTickLabel          (string array)</p>
<p>    zColor              (double[3])</p>
<p>    zLim                (double[2])</p>
<p>    zTick               (double array)</p>
<p>    zTickLabel          (string array)</p>
<p>  </p>
<p>The contents can be modified, but not configured (i.e. the user cannot a=
dd </p>
<p>other objects into the object as with a normal struct).</p>
<p></p>
<p>After we have the core objects, the rest will naturally follow with the =
</p>
<p>community writing m and oct files for the higher level functionality. Th=
e </p>
<p>callback manager can wait till later.</p>
<p></p>
<p>Nic</p>
<p></p>
</body></html>
--Boundary-00=_STgxBN9xmTTWIR8--