My sunday morning documentation contribution

svn path=/trunk/gtk-sharp/; revision=43854
This commit is contained in:
Miguel de Icaza 2005-05-01 17:32:57 +00:00
parent 9f5eb0a70d
commit cc54bbe5ed

View File

@ -62,17 +62,18 @@
</Parameters>
<Docs>
<summary>Render a <see cref="T:Pango.Layout" /> onto the Drawable
object with the specified colors.</summary>
<param name="gc">A <see cref="T:Gdk.GC" />, the graphics context to use</param>
<param name="x">the X position of the left of the layout (in pixels)</param>
<param name="y"> the Y position of the top of the layout (in pixels)</param>
<param name="layout">the layout to render</param>
<param name="foreground">the foreground color</param>
<param name="background">the background color</param>
<remarks>Render a <see cref="T:Pango.LayoutLine" /> onto the Drawable
object, overriding the layout's normal colors with
<paramref name="foreground" /> and/or <paramref name="background" />.
<paramref name="foreground" /> and <paramref name="background" />
need not be allocated.</summary>
<param name="gc">A <see cref="T:Gdk.GC" />, the graphics context to use</param>
<param name="x">A <see cref="T:System.Int32" />, the X position of the left of the layout (in pixels)</param>
<param name="y">A <see cref="T:System.Int32" />, the Y position of the top of the layout (in pixels)</param>
<param name="layout">A <see cref="T:Pango.Layout" />, the layout to render</param>
<param name="foreground">A <see cref="T:Gdk.Color" />, the foreground color</param>
<param name="background">A <see cref="T:Gdk.Color" />, the background color</param>
<remarks />
need not be allocated.</remarks>
</Docs>
</Member>
<Member MemberName="DrawLayoutLine">
@ -113,17 +114,21 @@
</Parameters>
<Docs>
<summary>Render a <see cref="T:Pango.LayoutLine" /> onto the Drawable
object, overriding the layout's normal colors.</summary>
<param name="gc">A <see cref="T:Gdk.GC" />, the graphics context to use</param>
<param name="x">the X position of the start of string (in pixels)</param>
<param name="y">the Y position of the baseline (in pixels)</param>
<param name="layout">A <see cref="T:Pango.LayoutLine" />, a line of text to render</param>
<param name="foreground">the foreground color</param>
<param name="background">the background color</param>
<remarks>Render a <see cref="T:Pango.LayoutLine" /> onto the Drawable
object, overriding the layout's normal colors with
<paramref name="foreground" /> and/or <paramref name="background" />.
<paramref name="foreground" /> and <paramref name="background" />
need not be allocated.</summary>
<param name="gc">A <see cref="T:Gdk.GC" />, the graphics context to use</param>
<param name="x">A <see cref="T:System.Int32" />, the X position of the start of string (in pixels)</param>
<param name="y">A <see cref="T:System.Int32" />, the Y position of the baseline (in pixels)</param>
<param name="layout">A <see cref="T:Pango.LayoutLine" />, a line of text to render</param>
<param name="foreground">A <see cref="T:Gdk.Color" />, the foreground color</param>
<param name="background">A <see cref="T:Gdk.Color" />, the background color</param>
<remarks />
<para>
<paramref name="foreground" /> and <paramref name="background" />
need not be allocated.
</para></remarks>
</Docs>
</Member>
<Member MemberName="DrawLayout">
@ -140,11 +145,16 @@
</Parameters>
<Docs>
<summary>Render a <see cref="T:Pango.Layout" /> onto a <see cref="T:Gdk.Drawable" /></summary>
<param name="gc">A <see cref="T:Gdk.GC" /></param>
<param name="x">A <see cref="T:System.Int32" /></param>
<param name="y">A <see cref="T:System.Int32" /></param>
<param name="gc">The base <see cref="T:Gdk.GC" /> to use.</param>
<param name="x">the X position of the left of the layout (in pixels)</param>
<param name="y"> the Y position of the top of the layout (in pixels)</param>
<param name="layout">A <see cref="T:Pango.Layout" /></param>
<remarks>If you are using Gtk, the usual way to obtain a <see cref="T:Pango.Layout" /> is <see cref="M:Gtk.Widget.CreatePangoLayout()" />.</remarks>
<remarks>
<para>
If the layout's PangoContext has a transformation matrix set, then x and y specify the position of the top left corner of the bounding box (in device space) of the transformed layout.
</para>
If you are using Gtk, the usual way to obtain a <see cref="T:Pango.Layout" /> is <see cref="M:Gtk.Widget.CreatePangoLayout()" />.</remarks>
</Docs>
</Member>
<Member MemberName="GetSize">
@ -205,21 +215,21 @@
<Parameter Name="glyphs" Type="Pango.GlyphString" />
</Parameters>
<Docs>
<summary>
<p>This is a low-level function; 99% of text rendering should be done
using <see cref="M:Gdk.Drawable.DrawLayout" /> instead.</p>
<p>A glyph is a character in a font. This function draws a sequence of
glyphs. To obtain a sequence of glyphs you have to understand a
lot about internationalized text handling, which you don't want to
understand; thus, use <see cref="M:Gdk.Drawable.DrawLayout" /> instead of this function,
<see cref="M:Gdk.Drawable.DrawLayout" /> handles the details.</p>
</summary>
<summary>Low-level glyph drawing function.</summary>
<param name="gc">A <see cref="T:Gdk.GC" /></param>
<param name="font">A <see cref="T:Pango.Font" /></param>
<param name="x">A <see cref="T:System.Int32" /></param>
<param name="y">A <see cref="T:System.Int32" /></param>
<param name="glyphs">A <see cref="T:Pango.GlyphString" /></param>
<remarks />
<remarks>
<para>This is a low-level function; 99% of text rendering should be done
using <see cref="M:Gdk.Drawable.DrawLayout" /> instead.</para>
<para>A glyph is a character in a font. This function draws a sequence of
glyphs. To obtain a sequence of glyphs you have to understand a
lot about internationalized text handling, which you don't want to
understand; thus, use <see cref="M:Gdk.Drawable.DrawLayout" /> instead of this function,
<see cref="M:Gdk.Drawable.DrawLayout" /> handles the details.</para>
</remarks>
</Docs>
</Member>
<Member MemberName="GetImage">
@ -235,14 +245,20 @@
<Parameter Name="height" Type="System.Int32" />
</Parameters>
<Docs>
<summary>
<p>
<summary>Returns a client-side <see cref="T:Gdk.Image" /> representing the server-side <see cref="T:Gdk.Drawable" />.</summary>
<param name="x">A <see cref="T:System.Int32" />, X coordinate of the upper left corner of the region to get as a drawable</param>
<param name="y">A <see cref="T:System.Int32" />, Y coordinate of the upper left corner of the region to get as a drawable.</param>
<param name="width">A <see cref="T:System.Int32" />, width of the rectangle</param>
<param name="height">A <see cref="T:System.Int32" />, height of the rectangle.</param>
<returns>A <see cref="T:Gdk.Image" /> containing the contents of this Drawable object.</returns>
<remarks>
<para>
A <see cref="T:Gdk.Image" /> stores client-side image data (pixels). In contrast,
<see cref="T:Gdk.Pixmap" /> and <see cref="T:Gdk.Window" /> are server-side
objects. This method obtains the pixels from a
server-side drawable as a client-side <see cref="T:Gdk.Image" />.
</p>
<p>
</para>
<para>
The format of a <see cref="T:Gdk.Image" /> depends on
the <see cref="T:Gdk.Visual" /> of the current display, which
makes manipulating <see cref="T:Gdk.Image" /> extremely difficult;
@ -254,39 +270,29 @@
display-dependent format. Of course, there's a convenience vs.
speed tradeoff here, so you'll want to think about what makes
sense for your application.
</p>
</summary>
<param name="x">A <see cref="T:System.Int32" />, X coordinate of the upper left corner of the region to get as a drawable</param>
<param name="y">A <see cref="T:System.Int32" />, Y coordinate of the upper left corner of the region to get as a drawable.</param>
<param name="width">A <see cref="T:System.Int32" />, width of the rectangle</param>
<param name="height">A <see cref="T:System.Int32" />, height of the rectangle.</param>
<returns>A <see cref="T:Gdk.Image" /> containing the contents of this Drawable object.</returns>
<remarks>
<p>
</p>
<p>
</para>
<para>
<paramref name="x" />, <paramref name="y" />,
<paramref name="width" />, and <paramref name="height" /> define
the region of the drawable to obtain as an image.
</p>
<p>
</para>
<para>
You would usually copy image data to the client side if you intend
to examine the values of individual pixels, for example to darken
an image or add a red tint. It would be prohibitively slow to
make a round-trip request to the windowing system for each pixel,
so instead you get all of them at once, modify them, then copy
them all back at once.
</p>
<p>
</para>
<para>
If the X server or other windowing system backend is on the local
machine, this function may use shared memory to avoid copying
the image data.
</p>
<p>
If the source drawable is a #GdkWindow and partially offscreen
</para>
<para> If the source drawable is a #GdkWindow and partially offscreen
or obscured, then the obscured portions of the returned image
will contain undefined data.
</p>
</para>
</remarks>
</Docs>
</Member>
@ -307,14 +313,7 @@
<Parameter Name="height" Type="System.Int32" />
</Parameters>
<Docs>
<summary>
Copies the <paramref name="width" />x<paramref name="height" /> region of <paramref name="src" /> at coordinates (<paramref name="xsrc" />,
<paramref name="ysrc" />) to coordinates (<paramref name="xdest" />, <paramref name="ydest" />) in <paramref name="drawable" />.
<paramref name="width" /> and/or <paramref name="height" /> may be given as -1, in which case the entire
<paramref name="src" /> drawable will be copied.
Most fields in <paramref name="gc" /> are not used for this operation, but notably the
clip mask or clip region will be honored.
</summary>
<summary>Draws a portion of a drawable into another.</summary>
<param name="gc">A <see cref="T:Gdk.GC" /></param>
<param name="src">A <see cref="T:Gdk.Drawable" />, the source Drawable. </param>
<param name="xsrc">A <see cref="T:System.Int32" /></param>
@ -324,15 +323,25 @@
<param name="width">A <see cref="T:System.Int32" /></param>
<param name="height">A <see cref="T:System.Int32" /></param>
<remarks>
<para>
Copies the <paramref name="width" /> x <paramref name="height" /> region of <paramref name="src" /> at coordinates (<paramref name="xsrc" />,
<paramref name="ysrc" />) to coordinates (<paramref name="xdest" />, <paramref name="ydest" />) in <paramref name="drawable" />.
<paramref name="width" /> and/or <paramref name="height" /> may be given as -1, in which case the entire
<paramref name="src" /> drawable will be copied.
Most fields in <paramref name="gc" /> are not used for this operation, but notably the
clip mask or clip region will be honored.
</para>
The source and destination drawables must have the same visual and
colormap, or errors will result. (On X11, failure to match
visual/colormap results in a BadMatch error from the X server.)
A common cause of this problem is an attempt to draw a bitmap to
a color drawable. The way to draw a bitmap is to set the
bitmap as a clip mask on your #GdkGC, then use gdk_draw_rectangle()
bitmap as a clip mask on your #GdkGC, then use <see cref="M:Gdk.Drawable.DrawRectangle" />
to draw a rectangle clipped to the bitmap.
<p>TODO: This API needs to be adjusted; <paramref name="src" /> should
probably not exist.</p></remarks>
</remarks>
</Docs>
</Member>
<Member MemberName="DrawImage">
@ -420,17 +429,10 @@
<Parameters>
</Parameters>
<Docs>
<summary>The color map for this Drawable. You only need to set
the color map if the drawable-creating function did not have a
way to determine the colormap, and you then use drawable operations
that require a colormap. The colormap for all drawables and
graphics contexts you intend to use together should match. i.e.
when using a #GdkGC to draw to a drawable, or copying one drawable
to another, the colormaps should match.
</summary>
<param name="value">A <see cref="T:Gdk.Colormap" /></param>
<returns>A <see cref="T:Gdk.Colormap" /></returns>
<remarks />
<summary>The color map for this Drawable. </summary>
<param name="value">The new <see cref="T:Gdk.Colormap" /> for the Drawable.</param>
<returns>The current <see cref="T:Gdk.Colormap" /> on the Drawable.</returns>
<remarks>You only need to set the color map if the drawable-creating function did not have a way to determine the colormap, and you then use drawable operations that require a colormap. The colormap for all drawables and graphics contexts you intend to use together should match. i.e. when using a #GdkGC to draw to a drawable, or copying one drawable to another, the colormaps should match.</remarks>
</Docs>
</Member>
<Member MemberName="VisibleRegion">
@ -440,9 +442,13 @@
<ReturnType>Gdk.Region</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added</summary>
<summary>Computes the region of a drawable that is potentially visible.</summary>
<returns>A <see cref="T:Gdk.Region" /></returns>
<remarks />
<remarks>This does not necessarily take into account if the window is obscured by other windows, but no area outside of this region is visible.
<para>
You must call <see cref="M:Gdk.Region.Destroy()" /> when done.
</para></remarks>
</Docs>
</Member>
<Member MemberName="ClipRegion">
@ -452,9 +458,13 @@
<ReturnType>Gdk.Region</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added</summary>
<returns>A <see cref="T:Gdk.Region" /></returns>
<remarks />
<summary>Computes the region of a drawable that potentially can be written to by drawing primitives.</summary>
<returns>A <see cref="T:Gdk.Region" />. You must call <see cref="M:Gdk.Region.Destroy()" /> when done.</returns>
<remarks>Computes the region of a drawable that potentially can be written to by drawing primitives. This region will not take into account the clip region for the GC, and may also not take into account other factors such as if the window is obscured by other windows, but no area outside of this region will be affected by drawing primitives.
<para>
You must call the Destroy method on the returned region when done.
</para></remarks>
</Docs>
</Member>
<Member MemberName="Visual">
@ -464,7 +474,7 @@
<ReturnType>Gdk.Visual</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added</summary>
<summary>Gets the <see cref="T:Gdk.Visual" /> describing the pixel format of drawable.</summary>
<returns>A <see cref="T:Gdk.Visual" /></returns>
<remarks />
</Docs>
@ -476,9 +486,9 @@
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added</summary>
<returns>A <see cref="T:System.Int32" /></returns>
<remarks />
<summary>Obtains the bit depth of the drawable.</summary>
<returns>The bit depth.</returns>
<remarks>Obtains the bit depth of the drawable, that is, the number of bits that make up a pixel in the drawable's visual. Examples are 8 bits per pixel, 24 bits per pixel, etc.</remarks>
</Docs>
</Member>
<Member MemberName="Screen">
@ -488,7 +498,7 @@
<ReturnType>Gdk.Screen</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added</summary>
<summary>Gets the <see cref="T:Gdk.Screen" /> associated with a <see cref="T:Gdk.Drawable." /></summary>
<returns>a <see cref="T:Gdk.Screen" /></returns>
<remarks />
</Docs>
@ -500,8 +510,8 @@
<ReturnType>Gdk.Display</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added</summary>
<returns>a <see cref="T:Gdk.Display" /></returns>
<summary>Gets the <see cref="T:Gdk.Display" /> associated with the <see cref="T:Gdk.Drawable" />.</summary>
<returns>The <see cref="T:Gdk.Display" />.</returns>
<remarks />
</Docs>
</Member>
@ -516,10 +526,10 @@
<Parameter Name="points" Type="Gdk.Point[]" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>Draws a series of lines connecting the given points.</summary>
<param name="gc">a <see cref="T:Gdk.GC" /></param>
<param name="points">a <see cref="T:Gdk.Point[]" /></param>
<remarks />
<remarks>The way in which joins between lines are draw is determined by the <see cref="E:Gdk.CapStyle" /> value in the <see cref="T:Gdk.GC" />. This can be set with <see cref="M:Gdk.GC.LineAttributes" /> property.</remarks>
</Docs>
</Member>
<Member MemberName="DrawPolygon">
@ -574,7 +584,7 @@
<Parameter Name="y2_" Type="System.Int32" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>Draws a line, using the foreground color and other attributes of the <see cref="T:Gdk.GC" /></summary>
<param name="gc">a <see cref="T:Gdk.GC" /></param>
<param name="x1_">a <see cref="T:System.Int32" /></param>
<param name="y1_">a <see cref="T:System.Int32" /></param>
@ -600,23 +610,19 @@
<Parameter Name="angle2" Type="System.Int32" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>Draws an arc or a filled 'pie slice'.</summary>
<param name="gc">a <see cref="T:Gdk.GC" /></param>
<param name="filled">a <see cref="T:System.Boolean" /></param>
<param name="x">a <see cref="T:System.Int32" /><para>
The x-coordinate of the upper left hand of the bounding box of the arc.
</para></param>
<param name="y">a <see cref="T:System.Int32" /><para>
The y-coordinate of the upper left hand of the bounding box of the arc.
</para></param>
<param name="width">a <see cref="T:System.Int32" /></param>
<param name="height">a <see cref="T:System.Int32" /></param>
<param name="angle1">a <see cref="T:System.Int32" /><para>
The starting angle of the arc in the clockwise direction in reference to the 3'oclock position in terms of 1/64th of a degree.
</para></param>
<param name="angle2">a <see cref="T:System.Int32" /><para>
The number of 1/64ths of a degree to sweep the arc in a clockwise direction relative to the starting angle.
</para></param>
<param name="x">The x-coordinate of the upper left hand of the bounding box of the arc.
</param>
<param name="y">The y-coordinate of the upper left hand of the bounding box of the arc.
</param>
<param name="width"> the width of the bounding rectangle.</param>
<param name="height">the height of the bounding rectangle.</param>
<param name="angle1">The starting angle of the arc in the clockwise direction in reference to the 3'oclock position in terms of 1/64th of a degree.
</param>
<param name="angle2">The number of 1/64ths of a degree to sweep the arc in a clockwise direction relative to the starting angle.
</param>
<remarks>
<example>
Draw the left side of a circle with a radius of 5 units.
@ -646,19 +652,24 @@ The number of 1/64ths of a degree to sweep the arc in a clockwise direction rela
<Parameter Name="y_dither" Type="System.Int32" />
</Parameters>
<Docs>
<summary>To be added</summary>
<param name="gc">a <see cref="T:Gdk.GC" /></param>
<param name="pixbuf">a <see cref="T:Gdk.Pixbuf" /></param>
<param name="src_x">a <see cref="T:System.Int32" /></param>
<param name="src_y">a <see cref="T:System.Int32" /></param>
<param name="dest_x">a <see cref="T:System.Int32" /></param>
<param name="dest_y">a <see cref="T:System.Int32" /></param>
<param name="width">a <see cref="T:System.Int32" /></param>
<param name="height">a <see cref="T:System.Int32" /></param>
<param name="dither">a <see cref="T:Gdk.RgbDither" /></param>
<param name="x_dither">a <see cref="T:System.Int32" /></param>
<param name="y_dither">a <see cref="T:System.Int32" /></param>
<remarks />
<summary>Renders a rectangular portion of a <see cref="T:Gdk.Pixbuf" /> to a <see cref="T:Gdk.Drawable" /></summary>
<param name="gc">A <see cref="T:Gdk.GC" /> used for clipping.</param>
<param name="pixbuf">The <see cref="T:Gdk.Pixbuf" /> to render</param>
<param name="src_x">Source X coordinate within pixbuf.</param>
<param name="src_y">Source Y coordinates within pixbuf.</param>
<param name="dest_x">Destination X coordinate within drawable.</param>
<param name="dest_y">Destination Y coordinate within drawable.</param>
<param name="width">Width of region to render, in pixels, or -1 to use pixbuf width. </param>
<param name="height"> Height of region to render, in pixels, or -1 to use pixbuf height.</param>
<param name="dither">Dithering mode for GdkRGB.</param>
<param name="x_dither">X offset for dither.</param>
<param name="y_dither">Y offset for dither.</param>
<remarks>The destination drawable must have a colormap. All windows have a colormap, however, pixmaps only have colormap by default if they were created with a non-NULL window argument. Otherwise a colormap must be set on them on the <see cref="P:Gdk.Drawable.Colormap" /> property.
<para>
On older X servers, rendering pixbufs with an alpha channel involves round trips to the X server, and may be somewhat slow.
</para><para>
The clip mask of gc is ignored, but clip rectangles and clip regions work fine.
</para></remarks>
</Docs>
</Member>
<Member MemberName="DrawRectangle">
@ -942,13 +953,13 @@ The number of 1/64ths of a degree to sweep the arc in a clockwise direction rela
<Parameter Name="text" Type="System.String" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>Deprecated: use <see cref="M:Gdk.Drawable.DrawLayout" /> instead.</summary>
<param name="font">a <see cref="T:Gdk.Font" /></param>
<param name="gc">a <see cref="T:Gdk.GC" /></param>
<param name="x">a <see cref="T:System.Int32" /></param>
<param name="y">a <see cref="T:System.Int32" /></param>
<param name="text">a <see cref="T:System.String" /></param>
<remarks>To be added</remarks>
<remarks>Deprecated.</remarks>
</Docs>
</Member>
<Member MemberName="DrawTextWc">
@ -965,14 +976,14 @@ The number of 1/64ths of a degree to sweep the arc in a clockwise direction rela
<Parameter Name="text_length" Type="System.Int32" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>Deprecated: draws a numbre of wide-char characters</summary>
<param name="font">a <see cref="T:Gdk.Font" /></param>
<param name="gc">a <see cref="T:Gdk.GC" /></param>
<param name="x">a <see cref="T:System.Int32" /></param>
<param name="y">a <see cref="T:System.Int32" /></param>
<param name="text_length">a <see cref="T:System.Int32" /></param>
<returns>a <see cref="T:System.UInt32" /></returns>
<remarks>To be added</remarks>
<remarks>Use <see cref="M:Gdk.Drawable.DrawLayout" /> instead.</remarks>
</Docs>
</Member>
<Member MemberName="DrawString">
@ -989,7 +1000,7 @@ The number of 1/64ths of a degree to sweep the arc in a clockwise direction rela
<Parameter Name="str1ng" Type="System.String" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>Deprecated: use <see cref="M:Gdk.Drawable.DrawLayout" /> instead.</summary>
<param name="font">a <see cref="T:Gdk.Font" /></param>
<param name="gc">a <see cref="T:Gdk.GC" /></param>
<param name="x">a <see cref="T:System.Int32" /></param>
@ -1008,7 +1019,7 @@ The number of 1/64ths of a degree to sweep the arc in a clockwise direction rela
<Parameter Name="key" Type="System.String" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>This method is deprecated, do not use.</summary>
<param name="key">a <see cref="T:System.String" /></param>
<returns>a <see cref="T:System.IntPtr" /></returns>
<remarks>To be added</remarks>
@ -1043,7 +1054,7 @@ The number of 1/64ths of a degree to sweep the arc in a clockwise direction rela
<Parameter Name="height" Type="System.Int32" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>Copies a portion of drawable into the client side image structure image.</summary>
<param name="image">a <see cref="T:Gdk.Image" /></param>
<param name="src_x">a <see cref="T:System.Int32" /></param>
<param name="src_y">a <see cref="T:System.Int32" /></param>
@ -1079,11 +1090,12 @@ The number of 1/64ths of a degree to sweep the arc in a clockwise direction rela
<Parameter Name="destroy_func" Type="System.IntPtr" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>This method is deprecated and should not be used with new code.</summary>
<param name="key">a <see cref="T:System.String" /></param>
<param name="data">a <see cref="T:System.IntPtr" /></param>
<param name="destroy_func">a <see cref="T:System.IntPtr" /></param>
<remarks>To be added</remarks>
<remarks>This method is deprecated and should not be used in newly-written code.
</remarks>
</Docs>
</Member>
<Member MemberName="DrawRectangleAlphaLibgtkOnly">