document-interface.xml revision c596be6d145df956e779f427dde5aabc8559dd6c
c9d44c649b67bea43e7549e2bf52870db9e770d0dugan xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd"
c9d44c649b67bea43e7549e2bf52870db9e770d0dugan <!-- MISC FUNCTIONS -->
c9d44c649b67bea43e7549e2bf52870db9e770d0dugan <doc:summary>The string id of a verb. For example: "EditSelectAll".</doc:summary>
c9d44c649b67bea43e7549e2bf52870db9e770d0dugan <doc:para>This method allows you to call any Inkscape verb using it's associated string. Every button and menu item has an associated verb, so this allows access to some extra functionality if one is willing to do the prerequisite research. The list of verbs can be found at:</doc:para>
c9d44c649b67bea43e7549e2bf52870db9e770d0dugan <!-- CREATION FUNCTIONS -->
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>X coordinate for the top left corner of the rectangle.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>Y coordinate for the top left corner of the rectangle.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <annotation name="org.freedesktop.DBus.GLib.ReturnVal" value="error"/>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>The name of the new rectangle.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:para>This method creates a rectangle in the current layer using the current document style.</doc:para>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:para>It is recommended that you save the return value if you will want to modify this particular shape later.</doc:para>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:para>cx and cy: set these anywhere from zero to half the width or height respectively of the rectangle to give it rounded corners.</doc:para>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:seealso><doc:ref type="interface" to="Coordinate System">Coordinate System</doc:ref></doc:seealso>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>X coordinate for the top left corner of the ellipse.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>Y coordinate for the top left corner of the ellipse.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <annotation name="org.freedesktop.DBus.GLib.ReturnVal" value="error"/>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>The name of the new ellipse.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:para>This method creates a ellipse in the current layer using the current document style.</doc:para>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:para>It is recommended that you save the return value if you will want to modify this particular shape later.</doc:para>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:para>"sodipodi:start" and "sodipodi:end": set these between 0 and Pi to create wedges or Pacman like shapes.</doc:para>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:seealso><doc:ref type="interface" to="Coordinate System">Coordinate System</doc:ref></doc:seealso>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>X coordinate for the center of the polygon.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>Y coordinate for the center of the polygon.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>Radius from the center to one of the points.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>Angle in degrees to rotate. 0 will have the first point pointing straight up.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>Number of sides of the polygon.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <annotation name="org.freedesktop.DBus.GLib.ReturnVal" value="error"/>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>The name of the new polygon.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:para>This method creates a polygon in the current layer using the current document style.</doc:para>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:para>It is recommended that you save the return value if you will want to modify this particular shape later.</doc:para>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:para>Note: this is actually a <doc:ref type="method" to="document.star">star</doc:ref> with "sodipodi:flatsided" set to true, which causes it to ignore the arg2 and r2 values.</doc:para>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:seealso><doc:ref type="interface" to="Coordinate System">Coordinate System</doc:ref></doc:seealso>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>X coordinate for the center of the star.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>Y coordinate for the center of the star.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>distance from the center for the first point.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>distance from the center for the second point.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>Angle in radians for the first point. 0 is 90 degrees to the right of straight up.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>Angle in radians for the second point. 0 is 90 degrees to the right of straight up.</doc:summary>
5979b9ca430f3ed6281aaa1b4e53506430dde4cfdugan <doc:summary>Number of times to repeat the points around the star.</doc:summary>
5979b9ca430f3ed6281aaa1b4e53506430dde4cfdugan <doc:summary>How rounded to make the star. 0 to 1 recommended for moderate to medium curves. 10 for extreme curves.</doc:summary>
5979b9ca430f3ed6281aaa1b4e53506430dde4cfdugan <annotation name="org.freedesktop.DBus.GLib.ReturnVal" value="error"/>
5979b9ca430f3ed6281aaa1b4e53506430dde4cfdugan <doc:para>This method creates a star in the current layer using the current document style.</doc:para>
5979b9ca430f3ed6281aaa1b4e53506430dde4cfdugan <doc:para>It is recommended that you save the return value if you will want to modify this particular shape later.</doc:para>
5979b9ca430f3ed6281aaa1b4e53506430dde4cfdugan <doc:para>Stars are quite complicated. Here is how they are represented: There are two points, represented by sodipodi:arg1 and sodipodi:arg2 for angle in radians and sodipodi:r1 and sodipodi:r2 for respective radius from the center point. The further one is a point of the star, the shorter one one of the valleys. This point and valley are repeated according to sodipodi:sides. sodipodi:rounded controls their control handles.</doc:para>
5979b9ca430f3ed6281aaa1b4e53506430dde4cfdugan <doc:seealso><doc:ref type="interface" to="Coordinate System">Coordinate System</doc:ref></doc:seealso>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>X coordinate for the center of the spiral.</doc:summary>
5979b9ca430f3ed6281aaa1b4e53506430dde4cfdugan <doc:summary>Y coordinate for the center of the spiral.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <annotation name="org.freedesktop.DBus.GLib.ReturnVal" value="error"/>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>The name of the new spiral.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:para>This method creates a spiral in the current layer using the current document style. However, fill is automatically set to "none". Stroke is unmodified.</doc:para>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:para>It is recommended that you save the return value if you will want to modify this particular shape later.</doc:para>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:para>"sodipodi:expansion": at 1 the spiral gets bigger at a constant rate. Less than one and the loops get tighter and tighter as it goes. More than one and they get looser and looser. This affects the number of revolutions so that it might not actually match the "sodipodi:revolutions" argument.</doc:para>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:para>"sodipodi:t0": at 0 the entire spiral is drawn, at 0.5 it is only drawn %50 of the way (starting from the outside) etc.</doc:para>
c9d44c649b67bea43e7549e2bf52870db9e770d0dugan <doc:para>"sodipodi:argument": Rotates the spiral. In radians.</doc:para>
c9d44c649b67bea43e7549e2bf52870db9e770d0dugan <doc:seealso><doc:ref type="interface" to="Coordinate System">Coordinate System</doc:ref></doc:seealso>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>X coordinate for the first point.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>Y coordinate for the first point.</doc:summary>
a6493af91df0cc29da01268c6032835ce6b28cf0dugan <doc:summary>X coordinate for the second point.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>Y coordinate for the second point.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <annotation name="org.freedesktop.DBus.GLib.ReturnVal" value="error"/>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:para>This method creates a line in the current layer using the current document style. It's a path, so the only attribute it will pay any attention to is "transform".</doc:para>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:seealso><doc:ref type="interface" to="Coordinate System">Coordinate System</doc:ref></doc:seealso>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <annotation name="org.freedesktop.DBus.GLib.ReturnVal" value="error"/>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>The name of the new text object.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:para>This method creates some text in the current layer.</doc:para>
a3ede39a2d699f615af402eceba24bb4cf9ec72ddugan <doc:summary>The type of node, probably "svg:path"</doc:summary>
48caec4536978f20f2f90a44a661f7add63dc5c9dugan <annotation name="org.freedesktop.DBus.GLib.ReturnVal" value="error"/>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:para>Make any kind of node you want. Mostly for making paths. (May need to allow updateRepr to be called for it to show up.)</doc:para>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <!-- ENVIRONMENT FUNCTIONS -->
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <annotation name="org.freedesktop.DBus.GLib.ReturnVal" value=""/>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:para>Retrieve the width of the current document. anything outside the boundary will not be printed or exported but will be saved.</doc:para>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <annotation name="org.freedesktop.DBus.GLib.ReturnVal" value=""/>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:para>Retrieve the height of the current document. anything outside the boundary will not be printed or exported but will be saved.</doc:para>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <annotation name="org.freedesktop.DBus.GLib.ReturnVal" value="error"/>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>CSS attribute string for the document.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:para>Get the current style for the document. All new shapes will use this style if it exists.</doc:para>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:seealso><doc:ref type="interface" to="Style Strings">Style Strings</doc:ref></doc:seealso>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>A new CSS attribute string for the document.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:para>Set the current style for the document. All new shapes will use this style if it exists.</doc:para>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:seealso><doc:ref type="interface" to="Style Strings">Style Strings</doc:ref></doc:seealso>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>A new CSS attribute string for the document.</doc:summary>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:para>Merge this this string with the current style for the document. All new shapes will use this style if it exists.</doc:para>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:seealso><doc:ref type="interface" to="Style Strings">Style Strings</doc:ref>, <doc:ref type="method" to="document.merge_css">merge_css()</doc:ref></doc:seealso>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:para>Resize the document to contain all of the currently selected objects.</doc:para>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:para>This ensures that the image is not clipped when printing or exporting.</doc:para>
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <!-- OBJECT FUNCTIONS -->
31ef6298b4179ddca52d4b1d0aad873af9d17155dugan <doc:summary>The new value of the attribute. This will overwrite anything already set. To merge styles, see <doc:ref type="method" to="document.merge_css">merge_css()</doc:ref>. </doc:summary>
<doc:para>Set any attribute, the available attributes depend on what kind of shape the object node represents. See <doc:ref type="method" to="document.rectangle">shape creation functions</doc:ref> for more details.</doc:para>
<doc:summary>The new value of the attribute. This will overwrite anything already set.</doc:summary>
<doc:para>Set any attribute, the available attributes depend on what kind of shape the object node represents. See <doc:ref type="method" to="document.rectangle">shape creation functions</doc:ref> for more details.</doc:para>
<doc:para>This is a convenience function for <doc:ref type="method" to="document.set_attribute">set_attribute()</doc:ref>.</doc:para>
<doc:summary>The new value of the attribute. This will overwrite anything already set.</doc:summary>
<doc:para>Set any attribute, the available attributes depend on what kind of shape the node represents. See <doc:ref type="method" to="document.rectangle">shape creation functions</doc:ref> for more details.</doc:para>
<doc:para>This is a convenience function for <doc:ref type="method" to="document.set_attribute">set_attribute()</doc:ref>.</doc:para>
<doc:para>Get the value of any attribute. Not all objects will have every attribute their type supports, some are optional. See <doc:ref type="method" to="document.rectangle">shape creation functions</doc:ref> for more details.</doc:para>
<doc:para>This may be accomplished with transformation attributes or by changing x and y attributes depending on the state of the object.</doc:para>
<doc:seealso><doc:ref type="interface" to="Coordinate System">Coordinate System</doc:ref></doc:seealso>
<doc:para>This will move a shape (or any object) to an absolute location. The point moved is the center of the bounding box, which is usually similar to the center of the shape.</doc:para>
<doc:para>Note that creating a rectangle or ellipse at 100,100 and calling move_to to move it to 100,100 will not produce the same results.</doc:para>
<doc:para>This may be accomplished with transformation attributes or by changing x and y attributes depending on the state of the object.</doc:para>
<doc:seealso><doc:ref type="interface" to="Coordinate System">Coordinate System</doc:ref></doc:seealso>
<doc:para>Turns an object into a path. Most objects contain paths (except rectangles) but are not paths themselves. </doc:para>
<doc:para>This will remove every attribute except d (the path attribute) style and id. id will not change. The appearance will be the same as well, it essentially encodes all information about the shape into the path.</doc:para>
<doc:para>After doing this you will no longer be able to modify the shape using shape specific attributes (cx, radius etc.) except transform</doc:para>
<doc:para>Required for certain functions that work on paths (not yet present in this API.)</doc:para>
<doc:para>Takes a transformation string ("matrix(0.96629885,0.25742286,-0.25742286,0.96629885,0,0)" or "rotate(45)") and applies it to any shape or path.</doc:para>
<doc:para>Retrieve the style of a object. Equivalent to calling <doc:ref type="method" to="document.get_attribute">get_attribute()</doc:ref> for "style".</doc:para>
<doc:para>Set a particular attribute of a style string. Overwrites just that part of the style.</doc:para>
<doc:para>Takes a CSS Style string and merges it with the objects current style, overwriting only the elements present in stylestring.</doc:para>
<doc:para>Returns an array of all of the X,Y coordinates of the points in the objects path.</doc:para>
<doc:para>Saves the current document with current name or a default name if has not been saved before.</doc:para>
<doc:seealso><doc:ref type="interface" to="document.document_resize_to_fit_selection">document_resize_to_fit_selection()</doc:ref></doc:seealso>
<doc:para>When updates are paused Inkscape will not draw every change as it is made. Also you will not be able to undo individual actions made while updates were paused and will only be able to undo them in a group. Inkscape may refresh the screen every couple of seconds even with updates off.</doc:para>
<doc:para>The advantage is a 2-5x speed increase, depending on the type of functions being called. This is most useful when creating large numbers of shapes.</doc:para>
<doc:para>Resume updates after they have been paused. If undo is called at this point it will undo everything that happened since pause_updates() was called.</doc:para>
<doc:para>This will update the display to show any changes that happened while updates were paused, a separate call to update() is not necessary.</doc:para>
<doc:para>This will update the document once if updates are paused but it will not resume updates.</doc:para>
<doc:para>This could be used to check on the progress of a complex drawing function, or to add in undo steps at certain points in a render.</doc:para>
<doc:para>Returns the current selection in the form of a list of ids of selected objects.</doc:para>
<doc:para>This method finds all of the objects inside the box and adds them to the current selection. If replace is true it will clear the old selection first.</doc:para>
<doc:para>To paste to a particular location, simply use selection_paste() followed by <doc:ref type="method" to="document.selection_move_to">selection_move_to()</doc:ref>.</doc:para>
<doc:summary>The amount to scale the selection, 1 has no effect. Between 0 and 1 will shrink it proportionally. Greater than one will grow it proportionally.</doc:summary>
<doc:para>This may be accomplished with transformation attributes or by changing x and y attributes depending on the state of the objects in the selection.</doc:para>
<doc:seealso><doc:ref type="interface" to="Coordinate System">Coordinate System</doc:ref></doc:seealso>
<doc:para>This may be accomplished with transformation attributes or by changing x and y attributes depending on the state of the objects in the selection.</doc:para>
<doc:seealso><doc:ref type="interface" to="Coordinate System">Coordinate System</doc:ref></doc:seealso>
<doc:seealso><doc:ref type="interface" to="Layers and Levels">Layers and Levels</doc:ref></doc:seealso>
<doc:seealso><doc:ref type="interface" to="Coordinate System">Coordinate System</doc:ref></doc:seealso>
<doc:seealso><doc:ref type="method" to="document.object_to_path">object_to_path()</doc:ref></doc:seealso>
<doc:para>Will erase all objects in the selection and replace with a single aggregate path.</doc:para>
<doc:para>Union: The new shape is all of the other shapes put together, even if they don't overlap (paths can have multiple non-contiguous areas.)</doc:para>
<doc:para>Intersection: The new shape is composed of the area where ALL the objects in the selection overlap. If there is no area where all shapes overlap the new shape will be empty.</doc:para>
<doc:para>Difference: The area of the second shape is subtracted from the first, only works with two objects.</doc:para>
<doc:para>Exclusion: The new shape is the area(s) where none of the objects in the selection overlaped. Only works with two objects.</doc:para>
<doc:para>Division: the first object is split into multiple segments by the second object. Only works with two objects and if multiple paths result they are grouped and the group id is returned.</doc:para>
<doc:summary>True if the objects changed levels. False if they don't(if they were already on top when being raised for example.)</doc:summary>
<doc:para>Will change the level of a selection, respective of other objects in the same layer. Will not affect the overlap of objects in different layers. Will do nothing if the selection contains objects in multiple layers.</doc:para>
<doc:para>"to_top" of "to_bottom": Move the selection above all other objects or below all other objects.</doc:para>
<doc:seealso><doc:ref type="interface" to="Layers and Levels">Layers and Levels</doc:ref></doc:seealso>
<doc:seealso><doc:ref type="interface" to="Layers and Levels">Layers and Levels</doc:ref></doc:seealso>
<doc:seealso><doc:ref type="interface" to="Layers and Levels">Layers and Levels</doc:ref></doc:seealso>
<doc:summary>True if the layer was moved. False if it was not (if it was already on top when being raised for example.)</doc:summary>
<doc:para>Will change the level of a layer, respective of other layers. Will not affect the relative level of objects within the layer.</doc:para>
<doc:para>"to_top" of "to_bottom": Move the layer above all other layers or below all other layers.</doc:para>
<doc:seealso><doc:ref type="interface" to="Layers and Levels">Layers and Levels</doc:ref></doc:seealso>