# HG changeset patch # User Pantxo Diribarne # Date 1413530950 -7200 # Node ID 1f2a16d41ba21a5e76f928fca5262e61095894e6 # Parent 6d8d5d9f226407df75b38be69b63ef40d3b0f179 Automatically generate graphics properties documentation (bug #42536) * doc/interpreter/Makefile.am: include new graphics_poperties.mk file and add $(GRAPH_PROP_TEXI_SRC) to the list of built texinfos. * doc/interpreter/graphics_poperties.mk: new file. Define the list of built texi sources for graphics properties. Write build rules using genpropdoc.m. * doc/interpreter/plot.txi: remove property tables and include built texi sources. * doc/interpreter/genpropdoc.m: new file to generate the properties documentation. diff -r 6d8d5d9f2264 -r 1f2a16d41ba2 doc/interpreter/Makefile.am --- a/doc/interpreter/Makefile.am Wed Oct 15 11:54:04 2014 -0400 +++ b/doc/interpreter/Makefile.am Fri Oct 17 09:29:10 2014 +0200 @@ -170,8 +170,11 @@ TXI_SRC = $(MUNGED_TEXI_SRC:.texi=.txi) +include graphics_properties.mk + BUILT_TEXINFOS = \ contributors.texi \ + $(GRAPH_PROP_TEXI_SRC) \ $(MUNGED_TEXI_SRC) info_TEXINFOS = octave.texi diff -r 6d8d5d9f2264 -r 1f2a16d41ba2 doc/interpreter/genpropdoc.m --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/genpropdoc.m Fri Oct 17 09:29:10 2014 +0200 @@ -0,0 +1,1309 @@ +## Copyright (C) 2014 Pantxo Diribarne +## +## This program is free software; you can redistribute it and/or modify it +## under the terms of the GNU General Public License as published by +## the Free Software Foundation; either version 3 of the License, or +## (at your option) any later version. +## +## This program is distributed in the hope that it will be useful, +## but WITHOUT ANY WARRANTY; without even the implied warranty of +## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +## GNU General Public License for more details. +## +## You should have received a copy of the GNU General Public License +## along with this program. If not, see +## . + +## -*- texinfo -*- +## @deftypefn {Function File} {@var{retval} =} genpropdoc (@var{OBJNAME}, @var{FILENAME}) +## +## Print FILENAME texinfo source file associated to OBJNAME objects. +## This function is meant to be run for generating octave +## documentation (see doc/interpreter/graphics_properties.mk). +## +## All the hard coded documentation is written in getdoc +## function. See the comments in getdoc bellow for instruction on how +## to document a graphics property. +## +## @seealso{} +## @end deftypefn + +function genpropdoc (objname, fname) + objnames = {"root", "figure", "axes", "line", ... + "text", "image", "patch", "surface"}; + + ## Base properties + base = getstructure ("base"); + + ## Object properties + if (any (strcmp (objname, objnames))) + obj = getstructure (objname, base); + else + error ("genpropdoc: unknown object %s", objname); + endif + + ## Docstring + str = printdoc (objname, obj); + + fid = fopen (fname, "w+"); + if (fid < 0) + error ("genpropdoc: couldn't open %s.", fname); + endif + + fprintf (fid, str); + fclose (fid); +endfunction + +function s = getdoc (objname, field, base) + ## Properties are represented by a struct with fields : + ## + ## -"doc": string to be printed verbatim after being expanded + ## through expand_doc function. Special keywords are: + ## "__objname__" further replaced by the current object name; + ## "__prop__" further replaced by the current property name; + ## "__modemsg__" further replaced by a message explaining that + ## the propmode will be toggled to "manual". + ## You may also cross reference properties using the label format + ## OBJNAMEPROPERTY, e.g "@xref{XREFaxescolor, , axes color + ## property}." + ## + ## -"valid": string that describes valid values for the + ## current property. Use "packopt" function to join options with + ## " | " separator and "markdef" to mark default among valid + ## values between curly braces. + ## If not provided, valid values for radio properties are + ## automatically retrieved using set function. + ## + ## -"default": string. If not provided the default value is + ## automatically retrieved using get function. + ## + ## -"printdefault": a boolean (def. true) that sepcifies whether the + ## default value should be printed. It is usefull for properties + ## like root "screendepth" that default to screen dependant values. + + packopt = @(c) strjoin (c, ' | '); + markdef = @(s) ["@{" s "@}"]; + + ## Some generic templates: + valid_color = "colorspec"; + valid_handle = "graphics handle"; + valid_string = "string"; + valid_fcn = packopt ({"string", "function handle"}); + valid_cellstring = packopt ({"string", "cell array of strings"}); + valid_2elvec = "two elements vector"; + valid_3elvec = "three elements vector"; + valid_4elvec = "four elements vector"; + valid_vecmat = packopt ({"vector", "matrix"}); + valid_scalmat = packopt ({"scalar", "matrix"}); + + doc_notimpl = "%s is not yet implemented for __objname__ \ +objects. __prop__ is unused."; + doc_unused = "__prop__ is unused."; + + + ## Initialize structure + if (isfield (base, field)) + s = base.(field); + else + s = struct ("valid", "", "default", "", "doc", "", ... + "printdefault", true); + endif + + ## Base properties: write generic documentation as it will, by + ## default, be included in the list of each graphics object. + ## If a given graphics object interprets the property differently + ## than most others, the doc will have to be rewritten for this object. + if (strcmp (objname, "base")) + switch field + case "beingdeleted" + case "busyaction" + case "buttondownfcn" + s.valid = valid_fcn; + case "children" + s.doc = "Graphics handles of the __objname__'s children."; + s.valid = "vector of graphics handles"; + + case "clipping" + s.doc = "If __prop__ is @qcode{\"on\"}, the __objname__ is \ +clipped in its parent axes limits."; + + case "createfcn" + s.doc = "Callback functions to be executed right after \ +the __objname__ has been created. Those functions have to be set by \ +default using e.g. @code{set (0, \"default__objname__createfcn\", \ +'disp (\"__objname__ created!\")') }."; + s.valid = valid_fcn; + + case "deletefcn" + s.doc = "Callback functions to be executed right before \ +the __objname__ is deleted."; + s.valid = valid_fcn; + + case "handlevisibility" + s.doc = "If __prop__ is @qcode{\"off\"}, the __objname__'s \ +handle is not visible into its parent's children list."; + + case "hittest" + case "interruptible" + case "parent" + s.doc = "Handle of the parent graphics object."; + s.valid = valid_handle; + + case "selected" + case "selectionhighlight" + case "tag" + s.valid = valid_string; + + case "type" + s.doc = "Class name of the graphics object. __prop__ is \ +always @qcode{\"__objname__\"}"; + s.valid = valid_string; + s.printdefault = false; + + case "uicontextmenu" + case "userdata" + case "visible" + s.doc = "If __prop__ is @qcode{\"off\"}, the __objname__ is \ +not rendered on screen."; + endswitch + + ## Root properties: + elseif (strcmp (objname, "root")) + switch field + ## Overridden shared properties + case {"beingdeleted", "busyaction", "buttondownfcn", ... + "clipping", "createfcn", "deletefcn", "handlevisibility", ... + "hittest", "interruptible", "selected", ... + "selectionhighlight", "uicontextmenu", "visible"} + s.doc = doc_unused; + + case "parent" + s.doc = "Root figure has no parent graphics object. __prop__ \ +is always empty."; + + ## Specific properties + case "callbackobject" + s.valid = valid_handle; + + case "commandwindowsize" + case "currentfigure" + s.doc = "Graphics handle of the current figure."; + s.valid = valid_handle; + + case "diary" + s.doc = "If __prop__ is @qcode{\"on\"}, the octave \ +command window session is saved to file. @xref{XREFrootdiaryfile, , \ +diaryfile property}."; + s.valid = valid_string; + + case "diaryfile" + s.doc = "The name of the diary file. \ +@xref{XREFdiary, , diary function}."; + s.valid = valid_string; + + case "echo" + s.doc = "Control whether octave displays commands executed \ +from scripts. @xref{XREFecho, , echo function}."; + + case "errormessage" + s.doc = "The last error message octave raised. \ +@xref{XREFlasterr, , lasterr function}."; + s.valid = valid_string; + + case "fixedwidthfontname" + s.valid = valid_string; + + case "format" + s. doc = "This property is a wrapper around @code{format} \ +function. @xref{XREFformat, , format function}."; + + case "formatspacing" + s. doc = "This property is a wrapper around @code{format} \ +function. @xref{XREFformat, , format function}."; + + case "language" + s.valid = valid_string; + + case "monitorpositions" + s.valid = valid_4elvec; + + case "pointerlocation" + s.valid = valid_2elvec; + + case "pointerwindow" + s.valid = valid_handle; + + case "recursionlimit" + s.doc = "The maximum number of times a function can be \ +called recursively. @xref{XREFmax_recursion_depth, , \ +max_recursion_depth function}."; + s.valid = "double"; + + case "screendepth" + s.valid = "double"; + s.printdefault = false; + + case "screenpixelsperinch" + s.valid = "double"; + s.printdefault = false; + + case "screensize" + s.valid = valid_4elvec; + s.printdefault = false; + + case "showhiddenhandles" + s.doc = "If __prop__ is @qcode{\"on\"}, all graphics objects \ +handle are visible in their parents' children list, regardless of \ +the value of their @code{handlevisibility} property."; + + case "units" + endswitch + + ## Figure properties + elseif (strcmp (objname, "figure")) + switch field + ## Overridden shared properties + case "clipping" + s.doc = doc_unused; + + ## Specific properties + case "alphamap" + s.doc = sprintf (doc_notimpl, "Transparency"); + case "closerequestfcn" + s.valid = valid_fcn; + + case "color" + s.doc = "Color of the figure background. @xref{Colors, , \ +colorspec}."; + s.valid = valid_color; + + case "colormap" + s.doc = "A matrix containing the RGB color map for \ +the current axes."; + s.valid = "N-by-3 matrix"; + + case "currentaxes" + s.doc = "Handle to the graphics object of the current axes."; + s.valid = valid_handle; + + case "currentcharacter" + s.doc = doc_unused; + + case "currentobject" + s.valid = valid_handle; + + case "currentpoint" + s.doc = "A 1-by-2 matrix which holds the coordinates of \ +the point over which the mouse pointer was when a mouse event \ +occurred. The x and y coordinates are in units defined by the \ +figures @qcode{\"units\"} property and their origin is the lower \ +left corner of the plotting area.\ +\n\nEvents which set @qcode{\"currentpoint\"} are\n\ +@table @asis\n\ +@item A mouse button was pressed\n\ +always\n\ +@item A mouse button was released\n\ +only if the figures callback @qcode{\"windowbuttonupfcn\"} is defined\n\ +@item The pointer was moved while pressing mouse button (drag)\n\ + only if the figures callback @qcode{\"windowbuttonmotionfcn\"} is \ +defined \n\ +@end table"; + s.valid = valid_2elvec; + + case "dockcontrols" + s.doc = doc_unused; + + case "doublebuffer" + case "filename" + case "integerhandle" + case "inverthardcopy" + case "keypressfcn" + s.valid = valid_fcn; + + case "keyreleasefcn" + s.doc = "With @code{keypressfcn}, the keyboard callback \ +functions. These callback functions get called when a key is \ +pressed/released respectively. The functions are called with two \ +input arguments. The first argument holds the handle of the calling \ +figure. The second argument holds the event structure which has the \ +following members:\n\ +@table @code\n\ +@item Character:\n\ +The ASCII value of the key\n\ +@item Key:\n\ +lowercase value of the key\n\ +@item Modifier:\n\ +A cell array containing strings representing the modifiers pressed \ +with the key.\n\ +@end table"; + s.valid = valid_fcn; + + case "menubar" + case "mincolormap" + case "name" + s.doc = "Name to be displayed in the figure title bar. If \ +__prop__ is empty, the title of the figure is \"figure\" followed \ +by the figure handle value."; + s.valid = valid_string; + + case "nextplot" + case "numbertitle" + case "outerposition" + s.valid = valid_4elvec; + + case "paperorientation" + case "paperposition" + s.doc = "Vector @qcode{[x0 y0 width height]} defining the \ +position of the figure (in @code{paperunits} units) in the printed \ +page. __modemsg__."; + s.valid = valid_4elvec; + + case "paperpositionmode" + s.doc = "If __prop__ is set to @qcode{\"auto\"}, the \ +@qcode{\"paperposition\"} property is automatically computed: the \ +printed figure will have the same size as on-screen figure and will \ +be centered in the output page."; + case "papersize" + s.doc = "Vector @qcode{[width height]} defining the size of the \ +printing paper. Setting this property forces the @code{papertype} \ +property to be set to @qcode{\"\"}."; + s.valid = valid_2elvec; + + case "papertype" + s.doc = "Name of the paper to be used for printed output. \ +Setting __prop__ also changes @code{papersize} accordingly."; + + case "paperunits" + s.doc = "The unit used to compute the @code{paperposition} \ +property."; + + case "pointer" + case "pointershapecdata" + s.doc = doc_unused; + + case "pointershapehotspot" + s.doc = doc_unused; + + case "position" + s.valid = valid_4elvec; + + case "renderer" + case "renderermode" + case "resize" + case "resizefcn" + s.valid = valid_fcn; + + case "selectiontype" + case "toolbar" + case "units" + s.doc = "The unit used to compute the @code{position} and \ +@code{outerposition} properties."; + case "windowbuttondownfcn" + s.doc = "@xref{XREFfigurewindowbuttonupfcn, , \ +windowbuttonupfcn property}."; + s.valid = valid_fcn; + + case "windowbuttonmotionfcn" + s.doc = "@xref{XREFfigurewindowbuttonupfcn, , \ +windowbuttonupfcn property}."; + s.valid = valid_fcn; + + case "windowbuttonupfcn" + s.doc = "With @code{windowbuttondownfcn} and \ +@code{windowbuttonmotionfcn}, the mouse callback functions. These \ +callback functions get called when the mouse button is pressed, \ +dragged, and released respectively. When these callback functions \ +are called, the @code{currentpoint} property holds the current \ +coordinates of the cursor."; + s.valid = valid_fcn; + + case "windowkeypressfcn" + s.valid = valid_fcn; + + case "windowkeyreleasefcn" + s.valid = valid_fcn; + + case "windowscrollwheelfcn" + s.valid = valid_fcn; + + case "windowstyle" + case "wvisual" + case "wvisualmode" + case "xdisplay" + case "xvisual" + case "xvisualmode" + case "__graphics_toolkit__" + s.doc = "The graphics toolkit that is used to render the \ +figure. @xref{XREFavailable_graphics_toolkits, , \ +available_graphics_toolkits function}."; + endswitch + + ## Axes properties + elseif (strcmp (objname, "axes")) + switch field + ## Overridden shared properties + case "clipping" + s.doc = doc_unused; + + ## Specific properties + case "activepositionproperty" + case "alim" + s.doc = sprintf (doc_notimpl, "Transparency"); + case "alimmode" + case "ambientlightcolor" + s.doc = sprintf (doc_notimpl, "Light"); + case "box" + s.doc = "Control wether the axes has a surrounding box."; + + case "cameraposition" + s.valid = valid_3elvec; + + case "camerapositionmode" + case "cameratarget" + s.valid = valid_3elvec; + + case "cameratargetmode" + case "cameraupvector" + s.valid = valid_3elvec; + + case "cameraupvectormode" + case "cameraviewangle" + s.valid = "scalar"; + + case "cameraviewanglemode" + case "clim" + s.valid = valid_2elvec; + s.doc = "Define the limits for the color axis of image \ +children. __modemsg__. @xref{XREFpcolor, , pcolor function}."; + + case "climmode" + case "color" + s.doc = "Color of the axes background. @xref{Colors, , \ +colorspec}."; + s.valid = valid_color; + + case "colororder" + s.doc = "RGB values to be used by plot function for \ +automatic line coloring."; + s.valid = "N-by-3 RGB matrix"; + + case "currentpoint" + s.doc = "Matrix @qcode{[xf, yf, zf; xb, yb, zb]} which holds \ +the coordinates of the point over which the mouse pointer was when \ +the mouse button was pressed in axes data units. If a mouse \ +callback function is defined, @code{currentpoint} holds the \ +pointer coordinates at the time the mouse button was pressed. For \ +3D plots, the first row of the returned matrix specifies the point \ +nearest to the current camera position and the second rows the \ +furthest point. The two points forms a line which is perpendicular \ +to the screen."; + s.valid = "2-by-3 matrix"; + + case "dataaspectratio" + s.doc = "Specify the relative height and width of the data \ +displayed in the axes. Setting @code{dataaspectratio} to @samp{[1, \ +2]} causes the length of one unit as displayed on the y-axis to be \ +the same as the length of 2 units on the x-axis. __modemsg__."; + s.valid = valid_3elvec; + + case "dataaspectratiomode" + case "drawmode" + case "fontangle" + case "fontname" + s.doc = "Name of the font to be used for axes annotations."; + s.valid = valid_string; + + case "fontsize" + s.doc = "Size of the font to be used for axes annotations. \ +@xref{XREFaxesfontunits, , fontunits property}."; + s.valid = "scalar"; + + case "fontunits" + s.doc = "Unit used to interpret @code{fontsize} property."; + + case "fontweight" + case "gridlinestyle" + case "interpreter" + case "layer" + case "linestyleorder" + case "linewidth" + case "minorgridlinestyle" + case "nextplot" + case "outerposition" + s.doc = "Specify the position of the plot, including titles, \ +axes and legend. The four elements of the vector are the \ +coordinates of the lower left corner and width and height of the \ +plot, in units normalized to the width and height of the plot \ +window. For example, @qcode{[0.2, 0.3, 0.4, 0.5]} sets the lower \ +left corner of the axes at @math{(0.2, 0.3)} and the width and \ +height to be 0.4 and 0.5 respectively. @xref{XREFaxesposition, , position property}."; + s.valid = valid_4elvec; + + case "plotboxaspectratio" + case "plotboxaspectratiomode" + case "position" + s.doc = "Specify the position of the plot, excluding titles, \ +axes and legend. The four elements of the vector are the \ +coordinates of the lower left corner and width and height of the \ +plot, in units normalized to the width and height of the plot \ +window. For example, @qcode{[0.2, 0.3, 0.4, 0.5]} sets the lower \ +left corner of the axes at @math{(0.2, 0.3)} and the width and \ +height to be 0.4 and 0.5 respectively. @xref{XREFaxesouterposition, , \ +outerposition property}."; + s.valid = valid_4elvec; + + case "projection" + case "tickdir" + case "tickdirmode" + case "ticklength" + case "tightinset" + case "title" + s.doc = "Graphics handle of the title text object."; + s.valid = valid_handle; + + case "units" + case "view" + s.doc = "Specify the view point for three-dimensional plots"; + s.valid = valid_2elvec; + + case "xaxislocation" + case "xcolor" + s.doc = "Color of the x-axis. @xref{Colors, , colorspec}."; + s.valid = packopt ({markdef(valid_color), ... + "@qcode{\"none\"}"}); + + case "xdir" + case "xgrid" + s.doc = "Control wether major x grid lines are displayed."; + + case "xlabel" + s.doc = "Graphics handle of the x label text object."; + s.valid = valid_handle; + + case "xlim" + s.doc = "Specify the limits for x-axis. __modemsg__. \ +@xref{XREFxlim, , xlim function}."; + s.valid = valid_2elvec; + + case "xlimmode" + case "xminorgrid" + s.doc = "Control wether minor x grid lines are displayed."; + + case "xminortick" + case "xscale" + case "xtick" + s.doc = "Position of x tick marks. __modemsg__."; + s.valid = "vector"; + + case "xticklabel" + s.doc = "Labels of x tick marks. __modemsg__."; + s.valid = valid_cellstring; + + case "xticklabelmode" + case "xtickmode" + case "yaxislocation" + case "ycolor" + s.doc = "Color of the y-axis. @xref{Colors, , colorspec}."; + s.valid = packopt ({markdef(valid_color), ... + "@qcode{\"none\"}"}); + + case "ydir" + case "ygrid" + s.doc = "Control wether major y grid lines are displayed."; + + case "ylabel" + s.doc = "Graphics handle of the y label text object."; + s.valid = valid_handle; + + case "ylim" + s.doc = "Specify the limits for y-axis. __modemsg__. \ +@xref{XREFylim, , ylim function}."; + s.valid = valid_2elvec; + + case "ylimmode" + case "yminorgrid" + s.doc = "Control wether minor y grid lines are displayed."; + + case "yminortick" + case "yscale" + case "ytick" + s.doc = "Position of y tick marks. __modemsg__."; + s.valid = "vector"; + + case "yticklabel" + s.doc = "Labels of y tick marks. __modemsg__."; + s.valid = valid_cellstring; + + case "yticklabelmode" + case "ytickmode" + case "zcolor" + s.doc = "Color of the z-axis. @xref{Colors, , colorspec}."; + s.valid = packopt ({markdef(valid_color), ... + "@qcode{\"none\"}"}); + + case "zdir" + case "zgrid" + s.doc = "Control wether major z grid lines are displayed."; + + case "zlabel" + s.doc = "Graphics handle of the z label text object."; + s.valid = valid_handle; + + case "zlim" + s.doc = "Specify the limits for z-axis. __modemsg__. \ +@xref{XREFzlim, , zlim function}."; + s.valid = valid_2elvec; + + case "zlimmode" + case "zminorgrid" + s.doc = "Control wether minor z grid lines are displayed."; + + case "zminortick" + case "zscale" + case "ztick" + s.doc = "Position of z tick marks. __modemsg__."; + s.valid = "vector"; + + case "zticklabel" + s.doc = "Labels of z tick marks. __modemsg__."; + s.valid = valid_cellstring; + + case "zticklabelmode" + case "ztickmode" + endswitch + + ## Line properties + elseif (strcmp (objname, "line")) + switch field + ## Overridden shared properties + case "children" + s.doc = doc_unused; + + ## Specific properties + case "color" + s.doc = "Color of the line object. @xref{Colors, , \ +colorspec}."; + s.valid = valid_color; + + case "displayname" + s.doc = "The text of the legend entry corresponding to this \ +line."; + s.valid = valid_cellstring; + + case "erasemode" + s.doc = doc_unused; + + case "interpreter" + case "linestyle" + s.doc = "@xref{Line Styles}."; + + case "linewidth" + s.doc = "Width in points of the line object."; + + case "marker" + s.doc = "The shape of the marker to be used. @xref{Marker \ +Styles}."; + + case "markeredgecolor" + s.doc = "Color of the edge of the markers. If set \ +@qcode{\"auto\"}, the markers edges have the same color as the line. If \ +set @qcode{\"none\"}, the markers edges are not displayed. This property \ +can also be set to any color. @xref{Colors, , colorspec}."; + + case "markerfacecolor" + s.doc = "Color of the face of the markers. If set \ +@qcode{\"auto\"}, the markers faces have the same color as the line. If \ +set @qcode{\"none\"}, the markers faces are not displayed. This property \ +can also be set to any color. @xref{Colors, , colorspec}."; + + case "markersize" + s.doc = "Size of the markers in points."; + s.valid = "scalar"; + + case "xdata" + s.doc = "Vector of x data to be plotted."; + s.valid = "vector"; + + case "xdatasource" + s.valid = valid_string; + s.doc = "Name of the vector in the current base workspace \ +that should be used as x data."; + + case "ydata" + s.doc = "Vector of y data to be plotted."; + s.valid = "vector"; + + case "ydatasource" + s.valid = valid_string; + s.doc = "Name of the vector in the current base workspace \ +that should be used as y data."; + + case "zdata" + s.doc = "Vector of z data to be plotted."; + s.valid = "vector"; + + case "zdatasource" + s.valid = valid_string; + s.doc = "Name of the vector in the current base workspace \ +that should be used as z data."; + + endswitch + + ## Text properties + elseif (strcmp (objname, "text")) + switch field + ## Overridden shared properties + case "children" + s.doc = doc_unused; + + ## Specific properties + case "backgroundcolor" + s.doc = sprintf (doc_notimpl, "Background area"); + s.valid = valid_color; + + case "color" + s.doc = "Color of the text. @xref{Colors, ,colorspec}. "; + s.valid = valid_color; + + case "displayname" + case "edgecolor" + s.doc = sprintf (doc_notimpl, "Background area"); + s.valid = valid_color; + + case "editing" + case "erasemode" + s.doc = doc_unused; + + case "extent" + case "fontangle" + s.doc = "Flag whether the font is italic or normal. \ +@code{fontangle} is currently unused."; + + case "fontname" + s.doc = "The font used for the text."; + s.valid = valid_string; + + case "fontsize" + s.doc = "The font size of the text."; + s.valid = "scalar"; + + case "fontunits" + s.doc = "The units used to interpret @code{fontsize} \ +property."; + + case "fontweight" + s.doc = "Flag whether the font is bold, etc."; + + case "horizontalalignment" + case "interpreter" + case "linestyle" + s.doc = sprintf (doc_notimpl, "Background area"); + + case "linewidth" + s.doc = sprintf (doc_notimpl, "Background area"); + s.valid = "scalar"; + + case "margin" + s.doc = sprintf (doc_notimpl, "Background area"); + s.valid = "scalar"; + + case "position" + s.doc = "Vector @qcode{[X0 Y0 Z0]} where X0, Y0 and Z0 \ +indicate the position of the text anchor as defined by \ +@code{verticalalignment} and @code{horizontalalignment}."; + s.valid = valid_4elvec; + + case "rotation" + s.doc = "The angle of rotation for the displayed text, \ +measured in degrees."; + s.valid = "scalar"; + + case "string" + s.doc = "The text object string content."; + s.valid = valid_string; + + case "units" + case "verticalalignment" + endswitch + + ## Image properties + elseif (strcmp (objname, "image")) + switch field + ## Overridden shared properties + case "children" + s.doc = doc_unused; + + ## Specific properties + case "alphadata" + s.doc = sprintf (doc_notimpl, "Transparency"); + s.valid = valid_scalmat; + + case "alphadatamapping" + s.doc = sprintf (doc_notimpl, "Transparency"); + + case "cdata" + s.valid = "matrix"; + + case "cdatamapping" + case "displayname" + s.doc = "The text of the legend entry corresponding to this \ +image."; + s.valid = valid_cellstring; + + case "erasemode" + s.doc = doc_unused; + + case "xdata" + s.doc = "Two element vector @qcode{[xmin xmax]} specifying the x \ +coordinates of the first and last columns of the image. \ +\n\nSetting @code{xdata} empty matrix makes octave automatically \ +affect it the value @qcode{[1 columns(image)]}."; + s.valid = valid_2elvec; + + case "ydata" + s.doc = "Vector @qcode{[ymin ymax]} specifying the y \ +coordinates of the first and last columns of the image. \ +\n\nSetting @code{ydata} empty matrix makes octave automatically \ +affect it the value @qcode{[1 rows(image)]}."; + s.valid = valid_2elvec; + + endswitch + + ## Surface properties + elseif (strcmp (objname, "surface")) + switch field + ## Overridden shared properties + case "children" + s.doc = doc_unused; + + ## Specific properties + case "alphadata" + s.doc = sprintf (doc_notimpl, "Transparency"); + s.valid = valid_scalmat; + + case "alphadatamapping" + s.doc = sprintf (doc_notimpl, "Transparency"); + + case "ambientstrength" + s.doc = sprintf (doc_notimpl, "Light"); + + case "backfacelighting" + s.doc = sprintf (doc_notimpl, "Light"); + + case "cdata" + s.valid = "matrix"; + + case "cdatamapping" + case "cdatasource" + case "diffusestrength" + s.doc = sprintf (doc_notimpl, "Light"); + + case "displayname" + s.doc = "The text of the legend entry corresponding to this \ +surface."; + + case "edgealpha" + s.doc = sprintf (doc_notimpl, "Transparency"); + s.valid = "scalar"; + + case "edgecolor" + case "edgelighting" + s.doc = sprintf (doc_notimpl, "Light"); + + case "erasemode" + s.doc = doc_unused; + case "facealpha" + s.doc = sprintf (doc_notimpl, "Transparency"); + s.valid = valid_scalmat; + + case "facecolor" + case "facelighting" + s.doc = sprintf (doc_notimpl, "Light"); + + case "interpreter" + case "linestyle" + s.doc = "@xref{Line Styles}."; + + case "linewidth" + s.doc = "@xref{XREFlinelinewidth, , line linewidth \ +property}."; + + case "marker" + s.doc = "@xref{Marker Styles}."; + + case "markeredgecolor" + s.doc = "@xref{XREFlinemarkeredgecolor, , line \ +markeredgecolor property}."; + + case "markerfacecolor" + s.doc = "@xref{XREFlinemarkerfacecolor, , line \ +markerfacecolor property}."; + + case "markersize" + s.doc = "@xref{XREFlinemarkersize, , line \ +markersize property}."; + s.valid = "scalar"; + + case "meshstyle" + case "normalmode" + case "specularcolorreflectance" + s.doc = sprintf (doc_notimpl, "Light"); + + case "specularexponent" + s.doc = sprintf (doc_notimpl, "Light"); + + case "specularstrength" + s.doc = sprintf (doc_notimpl, "Light"); + + case "vertexnormals" + case "xdata" + s.valid = "matrix"; + + case "xdatasource" + case "ydata" + s.valid = "matrix"; + + case "ydatasource" + case "zdata" + s.valid = "matrix"; + + case "zdatasource" + endswitch + + ## Patch properties + elseif (strcmp (objname, "patch")) + switch field + ## Overridden shared properties + case "children" + s.doc = doc_unused; + + ## Specific properties + case "alphadatamapping" + s.doc = sprintf (doc_notimpl, "Transparency"); + + case "ambientstrength" + s.doc = sprintf (doc_notimpl, "Light"); + s.valid = "scalar"; + + case "backfacelighting" + s.doc = sprintf (doc_notimpl, "Light"); + + case "cdata" + s.doc = "Data defining the patch object color.\n\ +Patch color can be defined for faces or for vertices. \n\n\ +If @code{cdata} is a scalar index into the current colormap or a RGB \ +triplet, it defines the color of all faces. \n\n\ +If @code{cdata} is a N-by-1 vector of indices or a N-by-3 (RGB) \ +matrix, it defines the color of each one of the N faces.\n\n\ +If @code{cdata} is a N-by-M or a N-by-M-by-3 (RGB) \ +matrix, it defines the color all vertices."; + s.valid = valid_scalmat; + + case "diffusestrength" + s.doc = sprintf (doc_notimpl, "Light"); + s.valid = "scalar"; + + case "displayname" + s.doc = "The text of the legend entry corresponding to this \ +patch."; + case "edgealpha" + s.doc = sprintf (doc_notimpl, "Transparency"); + s.valid = valid_scalmat; + + case "edgecolor" + case "edgelighting" + s.doc = sprintf (doc_notimpl, "Light"); + + case "erasemode" + s.doc = doc_unused; + + case "facealpha" + s.doc = sprintf (doc_notimpl, "Transparency"); + s.valid = valid_scalmat; + + case "facecolor" + ## Don't provide a default value, and mark colorspec with + ## braces, this forces the default rgb triplet to be displayed + s.valid = packopt ({markdef(valid_color), ... + "@qcode{\"flat\"}", ... + "@qcode{\"none\"}", ... + "@qcode{\"interp\"}"}); + + case "facelighting" + s.doc = sprintf (doc_notimpl, "Light"); + + case "faces" + case "xdata" + s.valid = valid_vecmat; + + case "facevertexalphadata" + s.doc = sprintf (doc_notimpl, "Transparency"); + s.valid = valid_scalmat; + + case "facevertexcdata" + case "interpreter" + s.doc = doc_unused; + + case "linestyle" + case "linewidth" + case "marker" + s.doc = "@xref{XREFlinemarker, , line marker property}."; + + case "markeredgecolor" + s.doc = "@xref{XREFlinemarkeredgecolor, , line \ +markeredgecolor property}."; + + case "markerfacecolor" + s.doc = "@xref{XREFlinemarkerfacecolor, , line \ +markerfacecolor property}."; + + case "markersize" + s.doc = "@xref{XREFlinemarkersize, , line \ +markersize property}."; + s.valid = "scalar"; + + case "normalmode" + case "specularcolorreflectance" + s.doc = sprintf (doc_notimpl, "Light"); + s.valid = "scalar"; + + case "specularexponent" + s.doc = sprintf (doc_notimpl, "Light"); + s.valid = "scalar"; + + case "specularstrength" + s.doc = sprintf (doc_notimpl, "Light"); + s.valid = "scalar"; + + case "vertexnormals" + case "vertices" + s.valid = valid_vecmat; + + case "xdata" + s.valid = valid_vecmat; + + case "ydata" + s.valid = valid_vecmat; + + case "zdata" + s.valid = valid_vecmat; + + endswitch + endif + + ## Replace keywords + if (! isempty (s.doc) && ! strcmp (objname, "base")) + s.doc = expand_doc (s.doc, field, objname); + endif + +endfunction + +function strout = expand_doc (strin, field, objname) + strout = strrep (strin, "__objname__", objname); + strout = strrep (strout, "__prop__", ["@code{" field "}"]); + + modemsg = "Setting @code{%s} also forces the @code{%smode} \ +property to be set to @qcode{\"manual\"}"; + modemsg = sprintf (modemsg, field, field); + strout = strrep (strout, "__modemsg__", modemsg); +endfunction + +function s = getstructure (objname, base = []) + hf = []; + if (! strcmp (objname, "root")) + ## Use an improbable figure number to avoid ishandle to return + ## true for 1 + hf = figure (2265465, "visible", "off"); + endif + + ## Build a default object to extract its properties list and default + ## values. + if (strcmp (objname, "base")) + ## Base properties are extracted from hggroup that only have 2 + ## additional regular (non-hidden) properties, "displayname" and + ## "erasemode". + h = hggroup (); + elseif (strcmp (objname, "root")) + h = 0; + elseif (strcmp (objname, "figure")) + h = hf; + else + if (strcmp (objname, "image")) + ## Disable GraphicsMagick warnings + warning ("off"); + endif + eval (["h = " objname " ();"]); + endif + + gprop = get (h); + sprop = set (h); + + fields = fieldnames (gprop); + nf = numel (fields); + args = cell (2*nf, 1); + for ii = 1:nf + field = fields{ii}; + + ## Get hard coded documentation + val = getdoc (objname, field, base); + + ## Extract the default values that are not hard coded in getdoc + if (isempty (val.default) && val.printdefault) + val.default = getdefault (h, objname, field); + endif + + val.isreadonly = ! isfield (sprop, field); + + ## Extract the valid values that are not hard coded in getdoc + if (! val.isreadonly && isempty (val.valid)) + val.valid = sprop.(field); + if (! isempty (val.valid) && + iscellstr (val.valid)) + ## Add double quotes around string radio properties + val.valid = cellfun (@(s) ["@qcode{\"" s "\"}"], val.valid, + "uniformoutput", false); + val.valid = strjoin (val.valid, ' | '); + endif + endif + + args{2*(ii-1)+1} = field; + args{2*ii} = val; + endfor + + ## Build struct and remove unused fields in base properties + s = struct (args{:}); + + if (strcmp (objname, "base")) + s = rmfield (s, {"displayname", "erasemode"}); + endif + + if (isfigure (hf)) + close (hf) + endif +endfunction + +function def = getdefault (h, objname, field) + ## This function is meant to be run without initialization file so + ## that the properties we get are the default. + def = get (h, field); + + ## Don't print default values for graphics handles + if (isscalar (def) && def != 0 && ishandle (def)) + def = ""; + else + if (ischar (def)) + def = ["@qcode{\"" def "\"}"]; + else + if ((isvector (def) && numel (def) < 5) || + isempty (def)) + ## Use disp to print the default value for short vectors and + ## empty values + str = disp (def); + str(end) = []; # remove linefeed + str = strtrim (str); # remove leading space + + ## Add [] around vector values + if (ismatrix (def) && numel (def) > 1) + str = ["[" str "]"]; + ## Add ";" between columns vector values + if (rows (def) != 1) + str = strrep (str, "\n", "; "); + endif + endif + + ## Replace texinfo reserved characters + def = strrep (str, "{", "@{"); + def = strrep (def, "}", "@}"); + def = strrep (def, "@", "@@"); + + def = ["@code{" def "}"]; + else + args = arrayfun (@(x) num2str (x), size (def), + "uniformoutput", false); + def = [strjoin(args, "-by-") " " class(def)]; + endif + endif + endif +endfunction + +function str = printdoc (objname, obj) + ## Sort fields so that they appear in alphabetic order in the manual + fields = sort (fieldnames (obj)); + nf = numel (fields); + + ## File header and begining of properties table + str = [warn_autogen() "\n\n@table @asis"]; + + + for ii = 1:nf + field = fields{ii}; + str = sprintf ("%s\n\n", str); + + ## @anchor: cross reference using XREFobjnamefield label + ## Concept index: call info from octave with + ## 'doc ("objname field")' + str = sprintf ("%s@anchor{XREF%s%s}\n@cindex %s %s\n", + str, objname, field, objname, field); + + ## Item + str = sprintf ("%s@item @code{%s}", str, field); + + ## Mark item read-only if needed + if (obj.(field).isreadonly) + str = sprintf ("%s (read-only):", str); + else + str = sprintf ("%s:", str); + endif + + ## Print valid and default values + tmp = print_options (obj.(field).valid, + obj.(field).default); + if (! isempty (tmp)) + str = sprintf ("%s %s\n", str, tmp); + else + str = sprintf ("%s\n", str); + endif + + ## Print documentation + str = sprintf ("%s%s\n", str, obj.(field).doc); + endfor + + ## End of properties table + str = sprintf ("%s\n@end table", str); +endfunction + +function str = warn_autogen () + str = "@c DO NOT EDIT! Generated automatically by genpropdoc.m.\n\ +\n\ +@c Copyright (C) 2014 Pantxo Diribarne\n\ +@c\n\ +@c This file is part of Octave.\n\ +@c\n\ +@c Octave is free software; you can redistribute it and/or modify it\n\ +@c under the terms of the GNU General Public License as published by the\n\ +@c Free Software Foundation; either version 3 of the License, or (at\n\ +@c your option) any later version.\n\ +@c\n\ +@c Octave is distributed in the hope that it will be useful, but WITHOUT\n\ +@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or\n\ +@c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License\n\ +@c for more details.\n\ +@c\n\ +@c You should have received a copy of the GNU General Public License\n\ +@c along with Octave; see the file COPYING. If not, see\n\ +@c ."; +endfunction + +function str = print_options (val, default) + str = ""; + if (! isempty (val)) + tmp = strrep (val, default, ["@{" default "@}"]); + if (length (tmp) == length (val) && ! isempty (default)) + str = [tmp ", def. " default]; + else + str = tmp; + endif + elseif (! isempty (default)) + str = ["def. " default]; + endif +endfunction diff -r 6d8d5d9f2264 -r 1f2a16d41ba2 doc/interpreter/graphics_properties.mk --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/graphics_properties.mk Fri Oct 17 09:29:10 2014 +0200 @@ -0,0 +1,34 @@ +GRAPH_PROP_TEXI_SRC= \ + plot-axesproperties.texi \ + plot-figureproperties.texi \ + plot-imageproperties.texi \ + plot-lineproperties.texi \ + plot-patchproperties.texi \ + plot-rootproperties.texi \ + plot-surfaceproperties.texi \ + plot-textproperties.texi + + +plot-axesproperties.texi: genpropdoc.m + $(top_builddir)/run-octave -f -q -H -p $(srcdir) --eval "genpropdoc ('axes', '$@');" || { rm -f $@; exit 1; } + +plot-figureproperties.texi: genpropdoc.m + $(top_builddir)/run-octave -f -q -H -p $(srcdir) --eval "genpropdoc ('figure', '$@');" || { rm -f $@; exit 1; } + +plot-imageproperties.texi: genpropdoc.m + $(top_builddir)/run-octave -f -q -H -p $(srcdir) --eval "genpropdoc ('image', '$@');" || { rm -f $@; exit 1; } + +plot-lineproperties.texi: genpropdoc.m + $(top_builddir)/run-octave -f -q -H -p $(srcdir) --eval "genpropdoc ('line', '$@');" || { rm -f $@; exit 1; } + +plot-patchproperties.texi: genpropdoc.m + $(top_builddir)/run-octave -f -q -H -p $(srcdir) --eval "genpropdoc ('patch', '$@');" || { rm -f $@; exit 1; } + +plot-rootproperties.texi: genpropdoc.m + $(top_builddir)/run-octave -f -q -H -p $(srcdir) --eval "genpropdoc ('root', '$@');" || { rm -f $@; exit 1; } + +plot-surfaceproperties.texi: genpropdoc.m + $(top_builddir)/run-octave -f -q -H -p $(srcdir) --eval "genpropdoc ('surface', '$@');" || { rm -f $@; exit 1; } + +plot-textproperties.texi: genpropdoc.m + $(top_builddir)/run-octave -f -q -H -p $(srcdir) --eval "genpropdoc ('text', '$@');" || { rm -f $@; exit 1; } diff -r 6d8d5d9f2264 -r 1f2a16d41ba2 doc/interpreter/plot.txi --- a/doc/interpreter/plot.txi Wed Oct 15 11:54:04 2014 -0400 +++ b/doc/interpreter/plot.txi Fri Oct 17 09:29:10 2014 +0200 @@ -554,7 +554,7 @@ @DOCSTRING(drawnow) Only figures that are modified will be updated. The @code{refresh} -function can also be used to force an update of the current figure, even if +function can also be used to cause an update of the current figure, even if it is not modified. @DOCSTRING(refresh) @@ -1337,9 +1337,17 @@ * Surface Properties:: @end menu -In this Section the object properties are discussed in detail, starting -with the root figure properties and continuing through the graphics object -hierarchy. +In this Section the graphics object properties are discussed in detail, starting +with the root figure properties and continuing through the objects +hierarchy. The documentation about a specific graphics object can be displayed +using @code{doc} function, e.g. @code{doc ("axes properties")} will show +@ref{Axes Properties}. + +The allowed values for radio (string) properties can be retrieved +programmatically or displayed using the one or +two arguments call to @code{set} function. @xref{XREFset, , set}. + +In the following documentation, default values are enclosed in @{ @}. @node Root Figure Properties @subsubsection Root Figure Properties @@ -1347,72 +1355,8 @@ The @code{root figure} properties are: -@table @code -@item __modified__ ---- Values: @qcode{"on"}, @qcode{"off"} - -@item __myhandle__ - -@item beingdeleted ---- Values: @qcode{"on"}, @qcode{"off"} - -@item busyaction - -@item buttondownfcn - -@item callbackobject - -@item children - -@item clipping - --- Values: @qcode{"on"}, @qcode{"off"} - -@item createfcn - -@item currentfigure - -@item deletefcn - -@item handlevisibility ---- Values: @qcode{"on"}, @qcode{"off"} - -@item hittest ---- Values: @qcode{"on"}, @qcode{"off"} - -@item interruptible ---- Values: @qcode{"on"}, @qcode{"off"} - -@item parent - -@item screendepth - -@item screenpixelsperinch - -@item screensize - -@item selected - -@item selectionhighlight - -@item screendepth - -@item screenpixelsperinch - -@item showhiddenhandles ---- Values: @qcode{"on"}, @qcode{"off"} - -@item tag - -@item type - -@item uicontextmenu - -@item units - -@item userdata - -@item visible -@end table +@include plot-rootproperties.texi + @node Figure Properties @subsubsection Figure Properties @@ -1420,236 +1364,8 @@ The @code{figure} properties are: -@table @code -@item __graphics_toolkit__ ---- The graphics toolkit currently in use. - -@item __enhanced__ - -@item __modified__ - -@item __myhandle__ - -@item __plot_stream__ - -@item alphamap - -@item beingdeleted ---- Values: @qcode{"on"}, @qcode{"off"} - -@item busyaction - -@item buttondownfcn - -@item children -Handle to children. - -@item clipping ---- Values: @qcode{"on"}, @qcode{"off"} - -@item closerequestfcn ---- Handle of function to call on close. - -@item color - -@item colormap -An N-by-3 matrix containing the color map for the current axes. - -@item paperorientation - -@item createfcn - -@item currentaxes -Handle to graphics object of current axes. - -@item currentcharacter - -@item currentobject - -@item currentpoint -An 1-by-2 matrix which holds the coordinates of the point over which -the mouse pointer was when a mouse event occurred. The x and y -coordinates are in units defined by the figures @qcode{"units"} property -and their origin is the lower left corner of the plotting area. - -Events which sets @qcode{"currentpoint"} are - -@table @asis -@item A mouse button was pressed -always - -@item A mouse button was released -only if the figures callback @qcode{"windowbuttonupfcn"} is defined - -@item The pointer was moved while pressing mouse button (drag) -only if the figures callback @qcode{"windowbuttonmotionfcn"} is defined -@end table - -@item deletefcn - -@item dockcontrols ---- Values: @qcode{"on"}, @qcode{"off"} - -@item doublebuffer ---- Values: @qcode{"on"}, @qcode{"off"} - -@item filename - -@item handlevisibility ---- Values: @qcode{"on"}, @qcode{"off"} - -@item hittest - -@item integerhandle - -@item interruptible ---- Values: @qcode{"on"}, @qcode{"off"} - -@item inverthardcopy - -@item keypressfcn -see @qcode{"keypressfcn"} - -@item keyreleasefcn -With @qcode{"keypressfcn"}, the keyboard callback functions. These -callback functions get called when a key is pressed/released -respectively. The functions are called with two input arguments. The -first argument holds the handle of the calling figure. The second -argument holds the event structure which has the following members: - -@table @code -@item Character -The ASCII value of the key - -@item Key -lowercase value of the key - -@item Modifier -A cell array containing strings representing the modifiers pressed with -the key. Possible values are @qcode{"shift"}, @qcode{"alt"}, and -@qcode{"control"}. -@end table - -@item menubar - -@item mincolormap - -@item name - -@item nextplot -May be one of - -@table @asis -@item @qcode{"new"} - -@item @qcode{"add"} - -@item @qcode{"replace"} - -@item @qcode{"replacechildren"} -@end table - -@item numbertitle - -@item paperorientation -Indicates the orientation for printing. Either @qcode{"landscape"} or -@qcode{"portrait"}. - -@item paperposition - -@item paperpositionmode - -@item papersize - -@item papertype - -@item paperunits - -@item pointer - -@item pointershapecdata - -@item pointershapehotspot - -@item position - -@item renderer - -@item renderermode - -@item resize - -@item resizefcn - -@item selected - -@item selectionhighlight ---- Values: @qcode{"on"}, @qcode{"off"} - -@item selectiontype -Holds information about the last mouse button press within the figure. -May be one of - -@table @asis -@item @qcode{"normal"} -Left mouse button click. - -@item @qcode{"extend"} -Shift + left mouse button click. - -@item @qcode{"alternate"} -Ctrl + left mouse button click or right mouse button click. - -@item @qcode{"open"} -Double-click with any mouse button. - -@end table - -@item tag - -@item toolbar - -@item type - -@item units ---- Values: @qcode{"inches"}, @qcode{"centimeters"}, @qcode{"normalized"}, -@qcode{"points"}, @qcode{"pixels"} [default], @qcode{"characters"}. - -Specifies the units which are used for @qcode{"position"}, -@qcode{"outerposition"} and @qcode{"currentpoint"}. - -@item userdata - -@item visible -Either @qcode{"on"} or @qcode{"off"} to toggle display of the figure. - -@item windowbuttondownfcn -See @qcode{"windowbuttonupfcn"} - -@item windowbuttonmotionfcn -See @qcode{"windowbuttonupfcn"} - -@item windowbuttonupfcn -With @qcode{"windowbuttondownfcn"} and @qcode{"windowbuttonmotionfcn"}, -the mouse callback functions. These callback functions get called when -the mouse button is pressed, dragged, and released respectively. When -these callback functions are called, the @qcode{"currentpoint"} property -holds the current coordinates of the cursor. - -@item windowscrollwheelfcn - -@item windowstyle - -@item wvisual - -@item wvisualmode - -@item xdisplay - -@item xvisual - -@item xvisualmode -@end table +@include plot-figureproperties.texi + @node Axes Properties @subsubsection Axes Properties @@ -1657,328 +1373,8 @@ The @code{axes} properties are: -@table @code -@item __modified__ - -@item __myhandle__ - -@item activepositionproperty - -@item alim - -@item alimmode - -@item ambientlightcolor - -@item beingdeleted - -@item box -Box surrounding axes. ---- Values: @qcode{"on"}, @qcode{"off"} - -@item busyaction - -@item buttondownfcn - -@item cameraposition - -@item camerapositionmode - -@item cameratarget - -@item cameratargetmode - -@item cameraupvector - -@item cameraupvectormode - -@item cameraviewangle - -@item cameraviewanglemode - -@item children - -@item clim -Two-element vector defining the limits for the c axis of -an image. See @code{pcolor} property. -Setting this property also forces the corresponding mode -property to be set to @qcode{"manual"}. - -@item climmode -Either @qcode{"manual"} or @qcode{"auto"}. - -@item clipping - -@item color - -@item colororder - -@item createfcn - -@item currentpoint -An 2-by-3 matrix @code{[xf, yf, zf; xb, yb, zb]} which holds the -coordinates of the point over which the mouse pointer was when the -mouse button was pressed in axes data units. If a mouse callback -function is defined, @qcode{"currentpoint"} holds the pointer -coordinates at the time the mouse button was pressed. For 3-D plots, -the first row of the returned matrix specifies the point nearest to -the current camera position and the second rows the furthest point. -The two points forms a line which is perpendicular to the screen. - -@item dataaspectratio -A two-element vector specifying the relative height and width of the -data displayed in the axes. Setting @code{dataaspectratio} to @samp{1, -2]} causes the length of one unit as displayed on the y-axis to be the -same as the length of 2 units on the x-axis. Setting -@code{dataaspectratio} also forces the @code{dataaspectratiomode} -property to be set to @qcode{"manual"}. - -@item dataaspectratiomode -Either @qcode{"manual"} or @qcode{"auto"}. - -@item deletefcn - -@item drawmode - -@item fontangle - -@item fontname - -@item fontsize - -@item fontunits - -@item fontweight - -@item gridlinestyle - -@item handlevisibility - -@item hittest - -@item interpreter - -@item interruptible - -@item layer - -@item linestyleorder - -@item linewidth - -@item minorgridlinestyle - -@item nextplot -May be one of - -@table @asis -@item @qcode{"add"} - -@item @qcode{"replace"} - -@item @qcode{"replacechildren"} -@end table - -@item outerposition -A vector specifying the position of the plot, including titles, axes and -legend. The four elements of the vector are the coordinates of the -lower left corner and width and height of the plot, in units normalized -to the width and height of the plot window. For example, @code{[0.2, -0.3, 0.4, 0.5]} sets the lower left corner of the axes at @math{(0.2, -0.3)} and the width and height to be 0.4 and 0.5 respectively. See also -the @code{position} property. - -@item parent - -@item plotboxaspectratio - -@item plotboxaspectratiomode - -@item position -A vector specifying the position of the plot, excluding titles, axes and -legend. The four elements of the vector are the coordinates of the -lower left corner and width and height of the plot, in units normalized -to the width and height of the plot window. For example, @code{[0.2, -0.3, 0.4, 0.5]} sets the lower left corner of the axes at @math{(0.2, -0.3)} and the width and height to be 0.4 and 0.5 respectively. See also -the @code{outerposition} property. - -@item projection - -@item selected - -@item selectionhighlight - -@item tag - -@item tickdir - -@item tickdirmode - -@item ticklength - -@item tightinset - -@item title -Index of text object for the axes title. - -@item type - -@item uicontextmenu - -@item units - -@item userdata - -@item view -A three element vector specifying the view point for three-dimensional plots. - -@item visible -Either @qcode{"on"} or @qcode{"off"} to toggle display of the axes. - -@item x_normrendertransform - -@item x_projectiontransform - -@item x_rendertransform - -@item x_viewporttransform - -@item x_viewtransform - -@item xaxislocation -Either @qcode{"top"} or @qcode{"bottom"}. - -@item xcolor - -@item xdir -Either @qcode{"forward"} or @qcode{"reverse"}. - -@item xgrid -Either @qcode{"on"} or @qcode{"off"} to toggle display of grid lines. - -@item xlabel -Indices to text objects for the axes labels. - -@item xlim -Two-element vector defining the limits for the x-axis. -Setting this property also forces the corresponding mode -property to be set to @qcode{"manual"}. - -@item xlimmode -Either @qcode{"manual"} or @qcode{"auto"}. - -@item xminorgrid -Either @qcode{"on"} or @qcode{"off"} to toggle display of minor grid lines. - -@item xminortick - -@item xscale -Either @qcode{"linear"} or @qcode{"log"}. - -@item xtick -Set position of tick marks. -Setting this property also forces the corresponding mode -property to be set to @qcode{"manual"}. - -@item xticklabel -Setting this property also forces the corresponding mode -property to be set to @qcode{"manual"}. - -@item xticklabelmode -Either @qcode{"manual"} or @qcode{"auto"}. - -@item xtickmode -Either @qcode{"manual"} or @qcode{"auto"}. - -@item yaxislocation -Either @qcode{"left"} or @qcode{"right"} - -@item ycolor - -@item ydir -Either @qcode{"forward"} or @qcode{"reverse"}. - -@item ygrid -Either @qcode{"on"} or @qcode{"off"} to toggle display of grid lines. - -@item ylabel -Indices to text objects for the axes labels. - -@item ylim -Two-element vectors defining the limits for the x, y, and z axes and the -Setting one of these properties also forces the corresponding mode -property to be set to @qcode{"manual"}. - -@item ylimmode -Either @qcode{"manual"} or @qcode{"auto"}. - -@item yminorgrid -Either @qcode{"on"} or @qcode{"off"} to toggle display of minor grid lines. - -@item yminortick - -@item yscale -Either @qcode{"linear"} or @qcode{"log"}. - -@item ytick -Set position of tick marks. -Setting this property also forces the corresponding mode -property to be set to @qcode{"manual"}. - -@item yticklabel -Setting this property also forces the corresponding mode -property to be set to @qcode{"manual"}. - -@item yticklabelmode -Either @qcode{"manual"} or @qcode{"auto"}. - -@item ytickmode -Either @qcode{"manual"} or @qcode{"auto"}. - -@item zcolor - -@item zdir -Either @qcode{"forward"} or @qcode{"reverse"}. - -@item zgrid -Either @qcode{"on"} or @qcode{"off"} to toggle display of grid lines. - -@item zlabel -Indices to text objects for the axes labels. - -@item zlim -Two-element vector defining the limits for z-axis. -Setting this property also forces the corresponding mode -property to be set to @qcode{"manual"}. - -@item zlimmode -Either @qcode{"manual"} or @qcode{"auto"}. - -@item zminorgrid -Either @qcode{"on"} or @qcode{"off"} to toggle display of minor grid lines. - -@item zminortick - -@item zscale -Either @qcode{"linear"} or @qcode{"log"}. - -@item ztick -Set position of tick marks. -Setting this property also forces the corresponding mode -property to be set to @qcode{"manual"}. - -@item zticklabel -Setting this property also forces the corresponding mode -property to be set to @qcode{"manual"}. - -@item zticklabelmode -Either @qcode{"manual"} or @qcode{"auto"}. - -@item ztickmode -Either @qcode{"manual"} or @qcode{"auto"}. - -@end table +@include plot-axesproperties.texi + @node Line Properties @subsubsection Line Properties @@ -1986,111 +1382,8 @@ The @code{line} properties are: -@table @code -@item __modified__ - -@item __myhandle__ - -@item beingdeleted - -@item busyaction - -@item buttondownfcn - -@item children - -@item clipping - -@item color -The RGB color of the line, or a color name. @xref{Colors}. - -@item createfcn - -@item deletefcn - -@item displayname -The text of the legend entry corresponding to this line. - -@item erasemode - -@item handlevisibility - -@item hittest - -@item interpreter - -@item interruptible - -@item ldata -The lower errorbar in the y direction to be plotted. - -@item linestyle -@itemx linewidth -@xref{Line Styles}. - -@item linewidth - -@item marker - -@item markeredgecolor - -@item markerfacecolor - -@item markersize -@xref{Marker Styles}. - -@item parent - -@item selected - -@item selectionhighlight - -@item tag - -@item type - -@item udata -The upper errorbar in the y direction to be plotted. - -@item uicontextmenu - -@item userdata - -@item visible - -@item xdata -The data to be plotted. - -@item xdatasource - -@item xldata -The lower errorbar to be plotted. - -@item xlim - -@item xliminclude - -@item xudata -The upper errorbar to be plotted. - -@item ydata -The data to be plotted. - -@item ydatasource - -@item ylim - -@item yliminclude - -@item zdata -The data to be plotted. - -@item zdatasource - -@item zlim - -@item zliminclude -@end table +@include plot-lineproperties.texi + @node Text Properties @subsubsection Text Properties @@ -2098,117 +1391,8 @@ The @code{text} properties are: -@table @code -@item __modified__ - -@item __myhandle__ - -@item backgroundcolor - -@item beingdeleted - -@item busyaction - -@item buttondownfcn - -@item children - -@item clipping - -@item color -The color of the text. @xref{Colors}. - -@item createfcn - -@item deletefcn - -@item displayname -The text of the legend entry corresponding to this line. - -@item edgecolor - -@item editing - -@item erasemode - -@item fontangle -Flag whether the font is italic or normal. Valid values are @qcode{"normal"}, -@qcode{"italic"}, and @qcode{"oblique"}. - -@item fontname -The font used for the text. - -@item fontsize -The size of the font, in points to use. - -@item fontunits - -@item fontweight -Flag whether the font is bold, etc. Valid values are @qcode{"normal"}, -@qcode{"bold"}, @qcode{"demi"}, or @qcode{"light"}. - -@item handlevisibility - -@item hittest - -@item horizontalalignment -May be @qcode{"left"}, @qcode{"center"}, or @qcode{"right"}. - -@item interpreter -Determines how the text is rendered. Valid values are @qcode{"none"}, -@qcode{"tex"}, or @qcode{"latex"}. - -@item interruptible - -@item linestyle - -@item linewidth - -@item margin - -@item parent - -@item position -The coordinates of the text object. - -@item rotation -The angle of rotation for the displayed text, measured in degrees. - -@item selected - -@item selectionhighlight - -@item string -The character string contained by the text object. - -@item tag - -@item type - -@item uicontextmenu - -@item units -May be @qcode{"normalized"} or @qcode{"graph"}. - -@item userdata - -@item verticalalignment - -@item visible - -@item xlim - -@item xliminclude - -@item ylim - -@item yliminclude - -@item zlim - -@item zliminclude - -@end table +@include plot-textproperties.texi + @node Image Properties @subsubsection Image Properties @@ -2216,76 +1400,8 @@ The @code{image} properties are: -@table @code -@item __modified__ - -@item __myhandle__ - -@item beingdeleted - -@item busyaction - -@item buttondownfcn - -@item cdata -The data for the image. Each pixel of the image corresponds to an -element of @code{cdata}. The value of an element of @code{cdata} -specifies the row-index into the colormap of the axes object containing -the image. The color value found in the color map for the given index -determines the color of the pixel. - -@item cdatamapping - -@item children - -@item clim - -@item climinclude - -@item clipping - -@item createfcn - -@item deletefcn - -@item handlevisibility - -@item hittest - -@item interruptible - -@item parent - -@item selected - -@item selectionhighlight - -@item tag - -@item type - -@item uicontextmenu - -@item userdata - -@item visible - -@item xdata -Two-element vector specifying the range of the x-coordinates for -the image. - -@item xlim - -@item xliminclude - -@item ydata -Two-element vector specifying the range of the y-coordinates for -the image. - -@item ylim - -@item yliminclude -@end table +@include plot-imageproperties.texi + @node Patch Properties @subsubsection Patch Properties @@ -2293,148 +1409,8 @@ The @code{patch} properties are: -@table @code -@item __modified__ - -@item __myhandle__ - -@item alim - -@item aliminclude - -@item alphadatamapping - -@item ambientstrength - -@item backfacelighting - -@item beingdeleted - -@item busyaction - -@item buttondownfcn - -@item cdata -Data defining the patch object. - -@item cdatamapping - -@item children - -@item clim - -@item climinclude - -@item clipping - -@item createfcn - -@item deletefcn - -@item diffusestrength - -@item displayname -The text of the legend entry corresponding to this line. - -@item edgealpha - -@item edgecolor -The color of the line defining the patch. @xref{Colors}. - -@item edgelighting - -@item erasemode - -@item facealpha -A number in the range [0, 1] indicating the transparency of the patch. - -@item facecolor -The fill color of the patch. @xref{Colors}. - -@item facelighting - -@item faces - -@item facevertexalphadata - -@item facevertexcdata - -@item handlevisibility - -@item hittest - -@item interpreter - -@item interruptible - -@item linestyle -@xref{Line Styles}. - -@item linewidth -@xref{Line Styles}. - -@item marker -@xref{Marker Styles}. - -@item markeredgecolor -@xref{Marker Styles}. - -@item markerfacecolor -@xref{Marker Styles}. - -@item markersize -@xref{Marker Styles}. - -@item normalmode - -@item parent - -@item selected - -@item selectionhighlight - -@item specularcolorreflectance - -@item specularexponent - -@item specularstrength - -@item tag - -@item type - -@item uicontextmenu - -@item userdata - -@item vertexnormals - -@item vertices - -@item visible - -@item xdata -Data defining the patch object. - -@item xlim - -@item xliminclude - -@item ydata -Data defining the patch object. - -@item ylim - -@item yliminclude - -@item zdata -Data defining the patch object. - -@item zlim - -@item zliminclude - -@end table +@include plot-patchproperties.texi + @node Surface Properties @subsubsection Surface Properties @@ -2442,144 +1418,8 @@ The @code{surface} properties are: -@table @code -@item __modified__ - -@item __myhandle__ - -@item alim - -@item aliminclude - -@item alphadata - -@item alphadatamapping - -@item ambientstrength - -@item backfacelighting - -@item beingdeleted - -@item busyaction - -@item buttondownfcn - -@item cdata - -@item cdatamapping - -@item cdatasource - -@item children - -@item clim - -@item climinclude - -@item clipping - -@item createfcn - -@item deletefcn - -@item diffusestrength - -@item displayname -The text of the legend entry corresponding to this surface. - -@item edgealpha - -@item edgecolor - -@item edgelighting - -@item erasemode - -@item facealpha - -@item facecolor - -@item facelighting - -@item handlevisibility - -@item hittest - -@item interpreter - -@item interruptible - -@item linestyle - -@item linewidth - -@item marker - -@item markeredgecolor - -@item markerfacecolor - -@item markersize - -@item meshstyle - -@item normalmode - -@item parent - -@item selected - -@item selectionhighlight - -@item specularcolorreflectance - -@item specularexponent - -@item specularstrength - -@item tag - -@item type - -@item uicontextmenu - -@item userdata - -@item vertexnormals - -@item visible - -@item xdata -The data determining the surface. The @code{xdata} and @code{ydata} -elements are vectors and @code{zdata} must be a matrix. - -@item xdatasource - -@item xlim - -@item xliminclude - -@item ydata -The data determining the surface. The @code{xdata} and @code{ydata} -elements are vectors and @code{zdata} must be a matrix. - -@item ydatasource - -@item ylim - -@item yliminclude - -@item zdata -The data determining the surface. The @code{xdata} and @code{ydata} -elements are vectors and @code{zdata} must be a matrix. - -@item zdatasource - -@item zlim - -@item zliminclude -@end table +@include plot-surfaceproperties.texi + @node Searching Properties @subsection Searching Properties