Complete the help informations for the graphical module - gsl-shell.git - gsl-shell

diff --git a/help/graphics.lua b/help/graphics.lua
index 33c09e53..7e80641d 100644
--- a/help/graphics.lua
+++ b/help/graphics.lua

@@ -3,6 +3,10 @@ local REG = debug.getregistry()

local Window = REG['GSL.window'].__index

local plot_index = REG['GSL.plot'].__index

local Plot = function(k) return plot_index(nil, k) end

+local Path = REG['GSL.path'].__index

+

+local text_index = REG['GSL.text'].__index

+local Text = function(k) return text_index(nil, k) end

local M = {

[graph.fxplot] = [[

@@ -36,7 +40,7 @@ graph.fibars(f, a, b[, color, fill_ratio])

[graph.fxline] = [[

graph.fxline(f, xi, xs[, n])

- This function returns an graphical object of type :class:`Path`

+ This function returns an graphical object of type Path

given by the points (x, f(x)) for x going from xi to xs

with n sampling point.

]],

@@ -67,7 +71,9 @@ graph.ipath(f)

[graph.ibars] = [[

graph.ibars(f)

- This function takes an iterator function f and returns a :class:`Path` object that draws many adjacent rectangular boxes corresponding to the points (x, y) returned by the iterator f.

+ This function takes an iterator function f and returns a Path

+ object that draws many adjacent rectangular boxes corresponding to

+ the points (x, y) returned by the iterator f.

]],

[graph.rgb] = [[

@@ -118,7 +124,7 @@ graph.plot([title])

Create a new empty plot with an optional title. The plot is not

attached to any window and is therefore not visible. To show the

- plot on the screen use either the :func:`show` plot's method or

+ plot on the screen use either the "show" plot's method or

use the :meth:`~Window.attach` window's method to attach the plot to a

specific window.

]],

@@ -129,8 +135,8 @@ graph.canvas([title])

Like the function above it does create a new empty plot with fixed

limits. This latter kind of plot differs in that it will not update

automatically its limits to fit the graphical objects. The method

- :func:`limits` should be used instead to set the logical limits of

- plotting area. The other difference with the :func:`graph.plot`

+ "limits" should be used instead to set the logical limits of

+ plotting area. The other difference with the "graph.plot"

function is that the property sync will be initialized to false.

This kind of plot is generally better suited for animations.

]],

@@ -138,116 +144,116 @@ graph.canvas([title])

[Plot'add'] = [[

<plot>:add(obj, color[, post_trans, pre_trans])

- Add the :ref:`graphical object <graphics-objects>` obj to

- the plot with the given color. The optional arguments

- post_trans and pre_trans should be a table of

- :ref:`graphical transformations <graphics-transforms>`.

+ Add the graphical object obj to the plot with the given color. The

+ optional arguments post_trans and pre_trans should be a table of

+ graphical transformations.

]],

[Plot'addline'] = [[

<plot>:addline(obj, color[, post_trans, pre_trans])

- Add the :ref:`graphical object <graphics-objects>` obj to

- the plot by performing automatically a stroke of it. It is

- useful because you often need to draw lines and not filled

- polygons. It is equivalent to add a 'stroke' operations of

- unitary size in the viewport coordinates system.

+ Add the graphical object obj to the plot to be rendered by a stroke

+ transformation. In this way the object is shown as a line instead of

+ as a filled polygon. It is equivalent to add a 'stroke' operations of

+ one pixel size.

]],

[Plot'limits'] = [[

<plot>:limits(x1, y1, x2, y2)

- Set the logical limits of the area displayed by the plot to the

- rectangle with lower-left corner (x1, y1) and upper-right corner

- (x2, y2). This method is used for plots with fixed limits

- obtained with the function :func:`canvas`.

+ Set the logical limits of the area displayed by the plot to the

+ rectangle with lower-left corner (x1, y1) and upper-right corner

+ (x2, y2). This method is used for plots with fixed limits obtained

+ with the function "canvas".

]],

[Plot'show'] = [[

<plot>:show()

- Create a new window to show the plot on the screen.

+ Create a new window to show the plot on the screen.

]],

[Plot'clear'] = [[

<plot>:clear()

- Remove all the graphical elements into the current

- :ref:`graphical layer <graphical-layer>`.

+ Remove all the graphical elements into the current graphical layer.

]],

[Plot'flush'] = [[

<plot>:flush()

- All the pending operations on a plot are processed and all the

- windows attached to the plot are updated. This method is only

- useful when the attribute sync is set to false.

+ All the pending operations on a plot are processed and all the

+ windows attached to the plot are updated. This method is only

+ useful when the attribute sync is set to false.

]],

+

[Plot'pushlayer'] = [[

<plot>:pushlayer()

- Add a new :ref:`graphical layer <graphical-layer>` and into the

- plot so that it becomes the current one and all the elements

- added with methods :meth:`~Plot.add` or :meth:`~Plot.addline`

- are associated with this new layer.

+ Add a new graphical layer and into the plot so that it becomes the

+ current one and all the elements added with methods "add" or

+ "addline" are associated with this new layer.

]],

+

[Plot'poplayer'] = [[

<plot>:poplayer()

- Remove the current :ref:`graphical layer <graphical-layer>` and

- all its graphical elements and make the previous level the

- current one.

+ Remove the current graphical layer and all its graphical elements

+ and make the previous level the current one.

]],

+

[Plot'save'] = [[

<plot>:save(filename[, w, h])

- Save the plot in a file in a bitmap image format. The first

- argument is the file name without extension while the other

- optional arguments are the width and the height in pixel of the

- image. The format used is BMP on windows and PPM on Linux.

+ Save the plot in a file in a bitmap image format. The first

+ argument is the file name without extension while the other

+ optional arguments are the width and the height in pixel of the

+ image. The format used is BMP on windows and PPM on Linux.

]],

+

[Plot'save_svg'] = [[

<plot>:save_svg(filename[, w, h])

- Save the plot in the given filename in SVG format. Two optional

- parameters can be given to specify the width and height of the

- drawing area.

+ Save the plot in the given filename in SVG format. Two optional

+ parameters can be given to specify the width and height of the

+ drawing area.

]],

+

[Plot'set_legend'] = [[

<plot>:set_legend(p[, placement])

- Add the plot p as a legend is the side area of the main plot.

- The argument placement is used to give the placement of the mini

- plot and should be on of the letters 'l', 'r', 'b', 't'. They

- stands for "left", "right", "bottom" and "top" respectively. By

- default the placement of the mini plot is on the right side.

+ Add the plot p as a legend is the side area of the main plot.

+ The argument placement is used to give the placement of the mini

+ plot and should be on of the letters 'l', 'r', 'b', 't'. They

+ stands for "left", "right", "bottom" and "top" respectively. By

+ default the placement of the legend is on the right side.

]],

[Plot'get_legend'] = [[

<plot>:get_legend([placement])

- Return the plot legend stored in the given placement.

- The placement parameter is interpreted as in the :meth:`~Plot.set_legend` method.

+ Return the plot legend stored in the given placement. The

+ placement parameter is interpreted as in the "set_legend" method.

]],

+

[Plot'legend'] = [[

<plot>:legend(text, color, symbol[, trans])

- Add to the plot a new legend item with the given text. The

- symbol used is determinated by the string symbol. Possible

- values are 'line', 'square' or anything accepted by

- :func:`graph.marker`. The optional trans parameter should be a

- :ref:`graphical transform <graphics-transforms>`. If omitted the

- appropriate default is chosen based on the symbol type.

+ Add to the plot a new legend item with the given text. The symbol

+ used is determinated by the string symbol. Possible values are

+ 'line', 'square' or anything accepted by "graph.marker". The

+ optional trans parameter should be a graphical transform. If

+ omitted the appropriate default is chosen based on the symbol type.

]],

[Plot'set_categories'] = [[

<plot>:set_categories(axis, categories)

- Configure the given axis (a letter, 'x' or 'y') to use a custom

- set of labels specified by categories. This latter should be a

- list of that gives in a sequence, the values where the label

- should be placed and the label text itself. The coordinate

- refers to the plot system of coordinates.

+ Configure the given axis (a letter, 'x' or 'y') to use a custom set

+ of labels specified by categories. This latter should be a list of

+ that gives in a sequence, the values where the label should be

+ placed and the label text itself. The coordinate refers to the plot

+ system of coordinates.

]],

--[[

@@ -302,84 +308,65 @@ graph.canvas([title])

The default value is true.

.. _graphical-layer:

+]]

-Graphical Layers

-~~~~~~~~~~~~~~~~

-

-When you want to perform animations with plot you can take advantage of the :ref:`graphical layers <graphical-layer>` that allows to clear and redraw only some graphical elements while keeping other elements always present in the background. The idea is that if you want to make an animation you will probably clear and redraw over and over some graphical elements but you may want to keep some of them fixed in the background. In order to obtain that you can

-

- * add normally all the fixed graphical elements

- * add a new :ref:`graphical layer <graphical-layer>` with the method :meth:`~Plot.pushlayer`

- * clear and redraw all the elements using the new topmost layer

-

-Here an simple example::

-

- p = graph.canvas('Animation Test')

- p:limits(-100, -100, 100, 100)

- p:show()

-

- p:add(graph.circle(0, 0, 80), 'blue', {{'stroke', width= 5}})

-

- x, y = 0, 0

- vx, vy = 2, 5

- R = 20

-

- p:pushlayer()

- for k=1, 100 do

- if x + vx + R > 100 or x + vx - R < -100 then vx = -vx end

- if y + vy + R > 100 or y + vy - R < -100 then vy = -vy end

- x = x + vx

- y = y + vy

-

- p:clear()

- p:add(graph.circle(x, y, R), 'red')

- p:flush()

- end

+ [graph.path] = [[

+graph.path([x, y])

-.. _graphics-objects:

-

-Graphical Objects

------------------

-

-.. function:: path([x, y])

-

- Creates an empty path. If the two coordinates (x, y) are provided set the initial point of the path to (x, y).

-

-.. class:: Path

-

- .. method:: move_to(x, y)

+ Creates an empty path. If the two coordinates (x, y) are provided

+ set the initial point of the path to (x, y).

+]],

- Move the current point to the coordinates (x, y) and start here a new path.

- .. method:: line_to(x, y)

+ [Path.move_to] = [[

+<path>:move_to(x, y)

- Add a line into the path from the previous point to the specified (x, y) coordinates.

- As a special case, if the path is empty, this method is equivalent to :meth:`~Path.move_to`.

+ Move the current point to the coordinates (x, y) and start here a new

+ path.

+]],

+ [Path.line_to] = [[

+<path>:line_to(x, y)

- .. hint::

- If you want to define a polygonal line you don't need to use the :meth:`~Path.move_to` method for the first point.

- Instead you can use the method :meth:`~Path.line_to` to add each point.

+ Add a line into the path from the previous point to the specified

+ (x, y) coordinates. As a special case, if the path is empty, this

+ method is equivalent to "move_to".

+]],

- .. method:: close()

+ [Path.close] = [[

+<path>:close()

- Close the polygon.

+ Close the path.

+]],

- .. method:: arc_to(x, y, angle, large_arc, sweep, rad_x, rad_y)

+ [Path.arc_to] = [[

+<path>:arc_to(x, y, angle, large_arc, sweep, rad_x, rad_y)

- Add as arc or ellipse with radius rx and ry up to the point (x, y).

+ Add as arc or ellipse with radius rx and ry up to the point (x, y).

+]],

- .. method:: curve3(x_ctrl, y_ctrl, x, y)

+ [Path.curve3] = [[

+<path>:curve3(x_ctrl, y_ctrl, x, y)

- Add a conic bezier curve up to (x, y) with a single control point. The curve will be displayed as such only if a 'curve' :ref:`graphical transformation <graphics-transforms>` is used in the transformations pipeline.

+ Add a quadratic bezier curve up to (x, y) with a single control

+ point. The curve will be displayed as such only if a 'curve'

+ graphical transformation is used in

+ the transformations pipeline.

+]],

- .. method:: curve4(x1_ctrl, y1_ctrl, x2_ctrl, y2_ctrl, x, y)

+ [Path.curve4] = [[

+<path>:curve4(x1_ctrl, y1_ctrl, x2_ctrl, y2_ctrl, x, y)

- Add a conic bezier curve up to (x, y) with two control points. The same remarks for the method :func:`curve3` applies to :func:`curve4`.

+ Add a cubic bezier curve up to (x, y) with two control points. The

+ same remarks for the method "curve3" applies to "curve4".

+]],

-.. function:: text(x, y, text, [height])

+ [graph.text] = [[

+graph.text(x, y, text, [height])

- Create a text object with the given text at the position (x,y).

- The first optional argument height indicate the text height.

+ Create a text object with the given text at the position (x,y). The

+ first optional argument height indicate the text height.

+]],

+--[[

.. class:: Text

A text object is used to display a text.

@@ -389,110 +376,40 @@ Graphical Objects

.. attribute:: angle

Rotate the text of the given angle (in radians).

+]]

- .. method:: justif(hv)

+ [Text'justif'] = [[

+<text>:justif(hv)

- Set the justification of the text.

- The argument hv should be a string of the form 'xy' where x is a letter among 'l', 'c' or 'r' that determine the horizontal justification and y is a letter among 't', 'c' or 'b' for the vertical justification.

-

- .. method:: set(x, y)

-

- Set the position where the test is displayed. It corresponds to

- the bottom left corner of the text.

-

-.. function:: textshape(x, y, text, size)

-

- Create a text shape graphical object of given text and size at the position x, y.

-

-.. class:: TextShape

-

- A text shape object is used to display a text.

- The difference with a simple text object is that a text shape has a well definite shape and extension in the plot system of coordinates.

- One of the implications is that the text shape will occupy a well definite area and the plot can adapt its area to include the text itself.

- For the other side text shape could be deformed if a different scale is used for x and y axis.

- If the aspect ration of coordinate system is not unitary a simple "text" object should be used instead.

-

- The text shape has currently no methods and its properties are determined during the creation of the object.

-

- .. tip::

- Text shape objects are useful to create plot legends.

- In this case the size and position of the text shape can be expressed in screen coordinates (pixel).

- The reason is that when a mini plot is added to a plot the area of the screen used to display the mini plot is equal to the bounding box of the mini plot itself.

-

-.. function:: marker(x, y, symbol, size)

-

- Create a marker object with the given symbol and size at the position x, y.

- A marker object is a graphical symbol drawn at the given coordinates and can be useful to mark a geometic point.

- The accepted symbol strings are the same of those accepted by the 'marker' graphical transformation.

-

-.. _graphics-transforms:

-

-Graphical transformations

--------------------------

-

-A generic graphical transformation is expressed in the form of table with the following layout::

-

- {'name',

- property1 = value1,

- property2 = value2,

- ...

- }

-

-For example, to express a 'stroke' transform you can write::

-

- {'stroke', width= 5}

-

-to mean a stroke transformation with a stroke width of 5.

-

-Here a complete list of all the available transforms:

-

- **stroke**

- A stroke create an outline of the given path. The properties are:

-

- * **width**, the width of the stroke, default value is width=1

- * **cap**, can be 'round', 'butt' or 'square'. The default value is 'butt'.

- * **join**, can be 'miter', 'miter.rev', 'miter.round', 'round' and 'bevel'

-

- **dash**

- Transform the path to a sequence of dashes. The following elements in the table are the length of the dashes and gaps.

-

- For example, to express a dash-dot line you can write {'dash', 7,3,3,3}.

-

- **curve**

- This transformation make the 'curve3' and 'curve4' path elements became real curves.

-

- **marker**

- Replace each vertex of the path with a circular mark

-

- * **size**, the size of the marker

- * **mark**, a string, an integer number or a graphical object indicating the symbol to be used for the markers.

- Available symbols are 'circle', 'triangle', 'square', 'diamond', 'plus', 'cross'.

- If a number is given the symbol will be chosen in the list given above.

- If a graphical object is supplied its extension should be such that is contained in a box of size 1 and centered in (0, 0).

- The object will be automatically scaled according to the parameter size.

- * **outline**, if it is true draw the marker in outline

-

- **translate**

- A translation along the x and y axis. This transformation can be used only in the user coordinate system.

+ Set the justification of the text. The argument hv should be a

+ string of the form 'xy' where x is a letter among 'l', 'c' or 'r'

+ that determine the horizontal justification and y is a letter among

+ 't', 'c' or 'b' for the vertical justification.

+]],

- * **x**, translation along the x axis

- * **y**, translation along the y axis

+ [Text'set'] = [[

+<text>:set(x, y)

- **scale**

- A scaling of the image around the point (0, 0). Only one numeric

- parameter should be supplied to indicate the scaling factor. For

- example {'scale', 2} will scale the image of a factor two.

+ Set the position where the test is displayed. It corresponds to the

+ bottom left corner of the text.

+]],

- **extend**

- Shrink or expand a shape of a given amount.

+ [graph.textshape] = [[

+graph.textshape(x, y, text, size)

- * **width**, the size of the shrink/expansion.

- If positive is an expansion otherwise is a shrink.

+ Create a text shape graphical object of given text and size at the

+ position x, y.

+]],

- **rotate**

- A rotation of a given angle with respect of the origin. This transformation can be used only in the user coordinate system.

+ [graph.marker] = [[

+graph.marker(x, y, symbol, size)

- * **angle**, the angle of the rotation, in radians. ]]

+ Create a marker object with the given symbol and size at the

+ position x, y. A marker object is a graphical symbol drawn at the

+ given coordinates and can be useful to mark a geometic point. The

+ accepted symbol strings are the same of those accepted by the

+ 'marker' graphical transformation.

+]]

}

-- alias