ruby-****@sourc*****
ruby-****@sourc*****
2003年 10月 21日 (火) 21:10:26 JST
-------------------------
REMOTE_ADDR = 218.231.205.39
REMOTE_HOST =
URL = http://ruby-gnome2.sourceforge.jp/?Gdk%3A%3ADrawable
-------------------------
= class Gdk::Drawable
Gdk::Drawable is the base class for all objects that can accept drawing commands.
- The Gdk::Drawable interface enables one to draw lines, points, elliptical arcs, rectangles, text, or images. In order to use a Gdk::Drawable, you must also have a Gdk:GC (graphics context) object to control the style of your drawing. The Gdk:GC can control the color, for example. In all of the functions that take a width or height parameter, -1 may be used to indicate that the largest possible meaningful value should be used instead of giving an explicit dimension.
+ The Gdk::Drawable interface enables one to draw lines, points, elliptical arcs, rectangles, text, or images. In order to use a Gdk::Drawable, you must also have a Gdk::GC (graphics context) object to control the style of your drawing.
+ The Gdk::GC can control the color, for example. In all of the methods that take a width or height parameter, -1 may be used to indicate that the largest possible meaningful value should be used instead of giving an explicit dimension.
== Object Hierarchy
* Object
* Glib::Instantiable
* Glib::Object
* Gdk::Drawable
- == Class Methods
-
== Instance Methods
+ --- display
+ Returns the Gdk::Display associated with this object. ((* Since 2.2 *))
+ * Returns: the Gdk::Display associated with this object
- --- visual()
- Returns the Gdk::Drawable (or derived class) itself. (TODO)
- * Returns: the Gdk::Drawable (or derived class) itself (TODO)
+ --- screen
+ Returns the Gdk::Screen associated with this object. ((* Since 2.2 *))
+ * Returns: the Gdk::Screen associated with this object
- --- colormap()
- Gets this object's Gdk::Colormap
- * Returns: the Gdk::Colormap that this object is using
+ --- visual
+ Gets the Gdk::Visual describing the pixel format of this object.
+ * Returns: a Gdk::Visual
- --- set_colormap(color)
- Sets this object's Gdk::Colormap
- * Returns: self
+ --- colormap
+ Gets the colormap for this object, if one is set; returns nil otherwise.
+ * Returns: the Gdk::Colormap that this object is using
- --- depth()
- Gets the depth of this Gdk::Drawable, in bits per pixel
- * Returns: a number representing how many bits are used for each pixel
+ --- colormap=(colormap)
+ Sets the colormap associated with the Gdk::Drawable. Normally this will happen automatically when the drawable is created; you only need to use this method if the drawable-creating method 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 Gdk::GC to draw to a Gdk::Drawable, or copying one Gdk::Drawable to another, the colormaps should match.
+ * colormap: a Gdk::Colormap
+ * Returns: colormap
- --- size()
- Gets the size of this Gdk::Drawable, as a 2-element array
- * Returns: a two-element Array representing the width and height of this Gdk::Drawable, respectively
-
- --- clip_region()
- Gets the Gdk::Region used for clipping (restricting drawing to a box)
- * Returns: the currently active clipping rectangle as a Gdk::Region
-
- --- visible_region()
- Gets the Gdk::Region that is visible
- * Returns: the visible region as a Gdk::Region
-
- --- draw_arc(gc, filled, x, y, w, h, a1, a2)
- Draws a partial or full arc of an elipse.
- * gc: a Gdk::GC graphics context to control the drawing style
- * filled: boolean indicating if this arc should be filled or not
- * x: X coordinate of the top left corner of the rectangle containing this ellipse
- * y: Y coordinate of the top left corner of the rectangle containing this ellipse
- * w: The width, in pixels, of the ellipse, or -1 for the whole region
- * h: The height, in pixels, of the ellipse, or -1 for the whole region
- * a1: The start of the arc, relative to the 3 o'clock position, counter-clockwise, in 1/64ths of a degree
- * a2: The end angle of the arc, relative to the 3 o'clock position, in 1/64ths of a degree
+ --- set_colormap(color)
+ Same as colormap=.
+ * colormap: a Gdk::Colormap
* Returns: self
- --- draw_image(gc, image, xsrc, ysrc, xdst, ydst, w, h)
- Draws a (rectangular part or whole) Gdk::Image into this Gdk::Drawable.
- * image: a Gdk::Image object to draw
- * xsrc: X source coordinate in the image of the upper left corner of the rectangle to copy
- * ysrc: Y source coordinate in the image of the upper left corner of the rectangle to copy
- * xdst: X destination coordinate in this Gdk::Drawable of the upper left corner of the rectangle to overwrite with image
- * ydst: Y destination coordinate in this Gdk::Drawable of the upper left corner of the rectangle to copy
- * w: width, in pixels, of the rectangle to copy, or -1 for the whole region
- * h: height, in pixels, of the rectangle to copy, or -1 for the whole region
- * Returns: self
+ --- depth
+ Gets the depth of this Gdk::Drawable, in bits per pixel, that is, the number of bits that make up a pixel in the visual of the Gdk::Drawable.
+ * Returns: a number representing how many bits are used for each pixel
- --- draw_glyphs(gc, font, x, y, glyphs)
- Draws a sequence of language glyphs. (TODO)
- * Returns: self
+ --- size
+ Gets the size of this Gdk::Drawable, as a 2-element array. On the X11 platform, if drawable is a Gdk::Window, the returned size is the size reported in the most-recently-processed configure event, rather than the current size on the X server.
+ * Returns: [width, height] or nil
+ * width: the width of this Gdk::Drawable
+ * height: the height of this Gdk::Drawable
- --- draw_layout(gc, x, y, layout, fg, bg)
- Draws a Pango::Layout (block of rendered text)
- * x: X coordinate of the left side of the string
- * y: Y coordinate of the text rendering baseline
- * layout: a Pango::Layout containing the rendered single line of text
- * fg: the foreground Gdk::Color
- * bg: the foreground Gdk::Color
- * Returns: self
+ --- clip_region
+ Gets the Gdk::Region used for clipping (restricting drawing to a box). 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.
+ * Returns: the currently active clipping rectangle as a Gdk::Region
- --- draw_layout(gc, x, y, layout)
- Draws a Pango::Layout (block of rendered text) with default foreground and background
- * x: X coordinate of the left side of the string
- * y: Y coordinate of the text rendering baseline
- * layout: a Pango::Layout containing the rendered single line of text
- * Returns: self
+ --- visible_region
+ Gets the Gdk::Region that is visible. This does not necessarily take into account if the window is obscured by other windows, but no area outside of this region is visible.
+ * Returns: the visible region as a Gdk::Region
- --- draw_layout_line(gc, x, y, line, fg, bg)
- Draws a Pango::LayoutLine (line of rendered text)
- * x: X coordinate of the left side of the string
- * y: Y coordinate of the text rendering baseline
- * line: a Pango::LayoutLine containing the rendered single line of text
- * fg: the foreground Gdk::Color
- * bg: the foreground Gdk::Color
+ --- draw_point(gc, x, y)
+ Draws a point, using the foreground color and other attributes of the Gdk::GC.
+ * gc: a Gdk::GC graphics context to control the drawing style
+ * x: X coordinate of point
+ * y: Y coordinate of point
* Returns: self
- --- draw_layout_line(gc, x, y, line)
- Draws a Pango::LayoutLine (line of rendered text) with default foreground and background
- * x: X coordinate of the left side of the string
- * y: Y coordinate of the text rendering baseline
- * line: a Pango::LayoutLine containing the rendered single line of text
+ --- draw_points(gc, points)
+ Draws a sequence of points, using the foreground color and other attributes of the Gdk::GC
+ * gc: a Gdk::GC graphics context to control the drawing style
+ * points: [[x1, y1], [x2, y2], [x3, y3], ... ] : an array of points to draw.
+ Each point is represented as an array of two elements, which correspond to the x and y coordinates.
* Returns: self
--- draw_line(gc, x1, y1, x2, y2)
- Draws a line.
+ Draws a line, using the foreground color and other attributes of the Gdk::GC.
* gc: a Gdk::GC graphics context to control the drawing style
* x1: the X coordinate of first endpoint of line
* y1: the Y coordinate of first endpoint of line
* x2: the X coordinate of second endpoint of line
* y2: the Y coordinate of second endpoint of line
* Returns: self
--- draw_lines(gc, points)
- Draws a connected sequence of lines.
+ Draws a connected sequence of lines. The way in which joins between lines are draw is determined by the ((<GdkCapStyle|Gdk::GC#GdkCapStyle>)) value in the Gdk::GC. This can be set with Gdk::GC#set_line_attributes.
* gc: a Gdk::GC graphics context to control the drawing style
- * points: a list of points to connect. Each point is represented as an array of two elements, which correspond to the x and y coordinates. This is an Array of these 2-element Array's.
+ * points: [[x1, y1], [x2, y2], [x3, y3], ... ] : an array of points to draw.
+ Each point is represented as an array of two elements, which correspond to the x and y coordinates.
* Returns: self
- --- draw_point(gc, x, y)
- Draws a point.
+ --- draw_pixbuf(gc, pixbuf, src_x, src_y, dest_x, dest_y, width, height, dither, x_dither, y_dither)
+ Renders a rectangular portion of a pixbuf to a drawable. 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-nil window argument. Otherwise a colormap must be set on them with Gdk::Drawable#colormap=.
+ On older X servers, rendering pixbufs with an alpha channel involves round trips to the X server, and may be somewhat slow. ((* Since 2.2 *))
+ * gc: a Gdk::GC, used for clipping, or nil
+ * pixbuf: a Gdk::Pixbuf
+ * src_x: Source X coordinate within pixbuf.
+ * src_y: Source Y coordinates within pixbuf.
+ * dest_x: Destination X coordinate within drawable.
+ * dest_y: Destination Y coordinate within drawable.
+ * width: Width of region to render, in pixels, or -1 to use pixbuf width.
+ * height: Height of region to render, in pixels, or -1 to use pixbuf height.
+ * dither: Dithering mode(((<GdkRgbDither|Gdk::RGB#GdkRgbDither>))) for Gdk::RGB.
+ * x_dither: X offset for dither.
+ * y_dither: Y offset for dither.
+
+ --- draw_segments(gc, segments)
+ Draws an arbitrary set of segments.
* gc: a Gdk::GC graphics context to control the drawing style
- * x: X coordinate of point
- * y: Y coordinate of point
+ * segments: [[x11, y11, x12, y12], [x21, y21, x22, y22], ...] :an array of segments to connect.
* Returns: self
- --- draw_points(gc, points)
- Draws a sequence of points.
+ --- draw_rectangle(gc, filled, x, y, width, height)
+ Draws a rectangular outline or filled rectangle, using the foreground color and other attributes of the Gdk::GC.
+ A rectangle drawn filled is 1 pixel smaller in both dimensions than a rectangle outlined. Calling Gdk::Drawable#draw_rectangle(gc, true, 0, 0, 20, 20) results in a filled rectangle 20 pixels wide and 20 pixels high. Calling Gdk::Drawable#draw_rectangle(gc, false, 0, 0, 20, 20) results in an outlined rectangle with corners at (0, 0), (0, 20), (20, 20), and (20, 0), which makes it 21 pixels wide and 21 pixels high.
* gc: a Gdk::GC graphics context to control the drawing style
- * points: a list of points to draw. Each point is represented as an array of two elements, which correspond to the x and y coordinates. This is an Array of these 2-element Array's.
+ * filled: true if this rectangle should be filled or outline
+ * x: X coordinate of the top left corner of the rectangle
+ * y: Y coordinate of the top left corner of the rectangle
+ * width: The width, in pixels, of the rectangle, or -1 for the whole region
+ * height: The height, in pixels, of the rectangle, or -1 for the whole region
* Returns: self
+ --- draw_arc(gc, filled, x, y, width, height, angle1, angle2)
+ Draws a partial or full arc of an elipse.
+ * gc: a Gdk::GC graphics context to control the drawing style
+ * filled: true if this arc should be filled, producing a 'pie slice'
+ * x: X coordinate of the left edge of the bounding rectangle
+ * y: Y coordinate of the top edge of the bouding rectangle
+ * width: The width, in pixels, of the ellipse, or -1 for the whole region
+ * height: The height, in pixels, of the ellipse, or -1 for the whole region
+ * angle1: The start of the arc, relative to the 3 o'clock position, counter-clockwise, in 1/64ths of a degree
+ * angle2: The end angle of the arc, relative to the 3 o'clock position, in 1/64ths of a degree
+ * Returns: self
+
--- draw_polygon(gc, filled, points)
- Draws a closed polygon.
+ Draws an outlined or filled polygon.
* gc: a Gdk::GC graphics context to control the drawing style
- * filled: boolean indicating if this rectangle should be filled or outline
- * points: a list of points corresponding to each vertex in order. Each point is represented as an array of two elements, which correspond to the x and y coordinates. This is an Array of these 2-element Array's. The polygon is closed automatically, connecting the last point to the first point if necessary.
+ * filled: true if the polygon should be filled. The polygon is closed automatically, connecting the last point to the first point if necessary.
+ * points: [[x1, y1], [x2, y2], [x3, y3], ... ] : an array of points specifying the points making up the polygon
* Returns: self
- --- draw_rectangle(gc, filled, x, y, w, h)
- Draws a rectangle.
+ --- draw_glyphs(gc, font, x, y, glyphs)
+ This is a low-level method; 99% of text rendering should be done using Gdk::Drawable#draw_layout instead.
+ A glyph is a character in a font. This method 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 Gdk::Drawable#draw_layout instead of this method, Gdk::Drawable#draw_layout handles the details.
* gc: a Gdk::GC graphics context to control the drawing style
- * filled: boolean indicating if this rectangle should be filled or outline
- * x: X coordinate of the top left corner of the rectangle
- * y: Y coordinate of the top left corner of the rectangle
- * w: The width, in pixels, of the rectangle, or -1 for the whole region
- * h: The height, in pixels, of the rectangle, or -1 for the whole region
+ * font: a Pango::Font to be used
+ * x: X coordinate of baseline origin
+ * y: Y coordinate of baseline origin
+ * glyphs: Pango::GlyphString to render
* Returns: self
- --- draw_segments(gc, segments)
- Draws an arbitrary set of segments.
+ --- draw_layout_line(gc, x, y, line, fg = nil, bg = nil)
+ Render a Pango::LayoutLine (line of rendered text) onto an Gdk::Drawable.
* gc: a Gdk::GC graphics context to control the drawing style
- * segments: a list of segments to connect. Each segment is represented as an array of four elements, which correspond to the x1, y1, x2, and y2 coordinates of the two endpoints. This is an Array of these 4-element Array's.
+ * x: the x position of start of string (in pixels)
+ * y: the y position of baseline (in pixels)
+ * line: a Pango::LayoutLine containing the rendered single line of text
+ * fg: the foreground Gdk::Color, nil for none
+ * bg: the foreground Gdk::Color, nil for none
* Returns: self
- --- get_image(x, y, w, h)
- Creates a Gdk::Image from a rectangular area of this Gdk::Drawable
+ --- draw_layout(gc, x, y, layout, fg = nil, bg = nil)
+ Render a Pango::Layout onto a Gdk::Drawable, overriding the layout's normal colors with foreground and/or background. foreground and background need not be allocated.
+ * gc: a Gdk::GC graphics context to control the drawing style
+ * x: the X position of the left of the layout (in pixels)
+ * y: the Y position of the top of the layout (in pixels)
+ * layout: a Pango::Layout containing the rendered single line of text
+ * fg: the foreground Gdk::Color
+ * bg: the foreground Gdk::Color
+ * Returns: self
+
+ --- draw_drawable(gc, src, xsrc, ysrc, xdest, ydest, width, height)
+ Copies the width x height region of src at coordinates (xsrc, ysrc) to coordinates (xdest, ydest) in drawable. width and/or height may be given as -1, in which case the entire src drawable will be copied.
+ Most fields in gc are not used for this operation, but notably the clip mask or clip region will be honored.
+ 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 Gdk::GC, then use Gdk::Drawable#draw_rectangle to draw a rectangle clipped to the bitmap.
+ * gc: a GdkGC sharing the drawable's visual and colormap
+ * src: another GdkDrawable
+ * xsrc: X position in src of rectangle to draw
+ * ysrc: Y position in src of rectangle to draw
+ * xdest: X position in drawable where the rectangle should be drawn
+ * ydest: Y position in drawable where the rectangle should be drawn
+ * width: width of rectangle to draw, or -1 for entire src width
+ * height: height of rectangle to draw, or -1 for entire src height
+
+ --- draw_image(gc, image, xsrc, ysrc, xdest, ydest, width, height)
+ Draws a (rectangular part or whole) Gdk::Image onto a Gdk::Drawable. The depth of the Gdk::Image must match the depth of the Gdk::Drawable.
+ * image: a Gdk::Image to draw
+ * xsrc: the left edge of the source rectangle within the Gdk::Image.
+ * ysrc: the top of the source rectangle within the Gdk::Image.
+ * xdest: the x coordinate of the destination within this Gdk::Drawable.
+ * ydest: the y coordinate of the destination within this Gdk::Drawable.
+ * width: the width of the area to be copied, or -1 to make the area extend to the right edge of the Gdk::Image.
+ * height: the height of the area to be copied, or -1 to make the area extend to the bottom edge of the Gdk::Image.
+ * Returns: self
+
+ --- get_image(x, y, width, height)
+ A Gdk::Image stores client-side image data (pixels). In contrast, Gdk::Pixmap and Gdk::Window are server-side objects. Gdk::Drawable#get_image obtains the pixels from a server-side drawable as a client-side Gdk::Image. The format of a Gdk::Image depends on the Gdk::Visual of the current display, which makes manipulating Gdk::Image extremely difficult; therefore, in most cases you should use Gdk::Pixbuf.from_drawable instead of this lower-level method. A Gdk::Pixbuf contains image data in a canonicalized RGB format, rather than a 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.
+ x, y, width, and height define the region of the Gdk::Drawable to obtain as an image.
+ 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.
+ If the X server or other windowing system backend is on the local machine, this method may use shared memory to avoid copying the image data.
+ If the Gdk::Drawable is a Gdk::Window and partially offscreen or obscured, then the obscured portions of the returned image will contain undefined data.
* x: X coordinate of the top left corner of the rectangle
* y: Y coordinate of the top left corner of the rectangle
- * w: The width, in pixels, of the rectangle, or -1 for the whole region
- * h: The height, in pixels, of the rectangle, or -1 for the whole region
+ * width: The width, in pixels, of the rectangle, or -1 for the whole region
+ * height: The height, in pixels, of the rectangle, or -1 for the whole region
* Returns: the Gdk::Image that was read from the rectangle
- --- xid()
+ --- xid
Returns the X11 (X Window) XID of this Gdk::Drawable, as a number
* Returns: the X11 (X Window) XID of this Gdk::Drawable, as a number
- --- display()
- Returns the Gdk::Display associated with this object
- * Returns: the Gdk::Display associated with this object
-
- --- screen()
- Returns the Gdk::Screen associated with this object
- * Returns: the Gdk::Screen associated with this object
-
- * ((<cilibrar>)) (this document started by cilibrar)
+ * 2003-10-21: ((<Masao>)) Revised.
+ * 2003-10-20: ((<cilibrar>)) (this document started by cilibrar)