Class Rubygame::Rect
In: lib/rubygame/rect.rb
Parent: Array

A Rect is a representation of a rectangle, with four core attributes (x offset, y offset, width, and height) and a variety of functions for manipulating and accessing these attributes.

Like all coordinates in Rubygame (and its base library, SDL), x and y offsets are measured from the top-left corner of the screen, with greater y offsets being lower. Thus, specifying the x and y offsets of the Rect is equivalent to setting the location of its top-left corner.

In Rubygame, Rects are used for collision detection and describing the area of a Surface to operate on.

Methods

b   b=   bl   bl=   bottom   bottom=   bottomleft   bottomleft=   bottomright   bottomright=   br   br=   c   c=   center   center=   centerx   centerx=   centery   centery=   clamp   clamp!   clip   clip!   collide_array   collide_array_all   collide_hash   collide_hash_all   collide_point?   collide_rect?   contain?   cx   cx=   cy   cy=   h   h=   height   height=   inflate   inflate!   inspect   l   l=   left   left=   mb   mb=   midbottom   midbottom=   midleft   midleft=   midright   midright=   midtop   midtop=   ml   ml=   move   move!   mr   mr=   mt   mt=   new   new_from_object   normalize   normalize!   r   r=   right   right=   size   size=   t   t=   tl   tl=   to_s   top   top=   topleft   topleft=   topright   topright=   tr   tr=   union   union!   union_all   union_all!   w   w=   width   width=   x   x=   y   y=  

Public Class methods

Create a new Rect, attempting to extract its own information from the given arguments. The arguments must fall into one of these cases:

  - 4 integers +(x, y, w, h)+.
  - 1 Rect or Array containing 4 integers +([x, y, w, h])+.
  - 2 Arrays containing 2 integers each +([x,y], [w,h])+.
  - 1 object with a +rect+ attribute which is a valid Rect object.

All rect core attributes (x,y,w,h) must be integers.

[Source]

# File lib/rubygame/rect.rb, line 86
        def initialize(*argv)
                case argv.length
                when 1
                        if argv[0].kind_of? Array; super(argv[0])
                        elsif argv[0].respond_to? :rect; super(argv[0])
                        end
                when 2
                        super(argv[0].concat(argv[1]))
                when 4
                        super(argv)
                end
                return self
        end

Extract or generate a Rect from the given object, if possible, using the following process:

 1. If it's a Rect already, return a duplicate Rect.
 2. Elsif it's an Array with at least 4 values, make a Rect from it.
 3. Elsif it has a +rect+ attribute., perform (1) and (2) on that.
 4. Otherwise, raise TypeError.

See also Surface#make_rect()

[Source]

# File lib/rubygame/rect.rb, line 109
        def Rect.new_from_object(object)
                case(object)
                when Rect
                        return object.dup
                when Array 
                        if object.length >= 4
                                return Rect.new(object)
                        else
                                raise(ArgumentError,"Array does not have enough indices to be made into a Rect (%d for 4)."%object.length )
                        end
                else
                        begin
                                case(object.rect)
                                when Rect
                                        return object.rect.dup
                                when Array
                                        if object.rect.length >= 4
                                                return Rect.new(object.rect)
                                        else
                                                raise(ArgumentError,"Array does not have enough indices to be made into a Rect (%d for 4)."%object.rect.length )
                                        end
                                end                         # case object.rect
                        rescue NoMethodError # if no rect.rect
                                raise(TypeError,"Object must be a Rect or Array [x,y,w,h], or have an attribute called 'rect'. (Got %s instance.)"%object.class)
                        end
                end # case object
        end

Public Instance methods

b()

Alias for bottom

b=(b)

Alias for bottom=

bl()

Alias for bottomleft

bl=(bottomleft)

Alias for bottomleft=

Return the y coordinate of the bottom side of the Rect.

[Source]

# File lib/rubygame/rect.rb, line 214
        def bottom; return self.at(1)+self.at(3); end

Set the y coordinate of the bottom side of the Rect by translating the Rect (adjusting the y offset).

[Source]

# File lib/rubygame/rect.rb, line 218
        def bottom=(b); self[1] = b - self.at(3); return b; end

Return the x and y coordinates of the bottom-left corner of the Rect

[Source]

# File lib/rubygame/rect.rb, line 285
        def bottomleft; return self.at(0), self.bottom; end

Set the x and y coordinates of the bottom-left corner of the Rect by translating the Rect (adjusting the x and y offsets).

[Source]

# File lib/rubygame/rect.rb, line 289
        def bottomleft=(bottomleft)
                raise ArgumentError, "Rect#bottomleft= takes an Array of form [x, y]." if bottomleft.size != 2
                self[0], self.bottom = bottomleft
                return bottomleft
        end

Return the x and y coordinates of the bottom-right corner of the Rect

[Source]

# File lib/rubygame/rect.rb, line 299
        def bottomright; return self.right, self.bottom; end

Set the x and y coordinates of the bottom-right corner of the Rect by translating the Rect (adjusting the x and y offsets).

[Source]

# File lib/rubygame/rect.rb, line 303
        def bottomright=(bottomright)
                raise ArgumentError, "Rect#bottomright= takes an Array of form [x, y]." if bottomright.size != 2
                self.right, self.bottom = bottomright
                return bottomright
        end
br()

Alias for bottomright

br=(bottomright)

Alias for bottomright=

c()

Alias for center

c=(center)

Alias for center=

Return the x and y coordinates of the center of the Rect.

[Source]

# File lib/rubygame/rect.rb, line 224
        def center; return self.centerx, self.centery; end

Set the x and y coordinates of the center of the Rect by translating the Rect (adjusting the x and y offsets).

[Source]

# File lib/rubygame/rect.rb, line 228
        def center=(center)
            raise ArgumentError, "Rect#center= takes an Array of the form [x,y]." if center.size != 2
                self.centerx, self.centery = center
                center
        end

Return the x coordinate of the center of the Rect

[Source]

# File lib/rubygame/rect.rb, line 237
        def centerx; return self.at(0)+(self.at(2).div(2)); end

Set the x coordinate of the center of the Rect by translating the Rect (adjusting the x offset).

[Source]

# File lib/rubygame/rect.rb, line 241
        def centerx=(x); self[0] = x - (self.at(2).div(2)); return x; end

Return the y coordinate of the center of the Rect

[Source]

# File lib/rubygame/rect.rb, line 247
        def centery; return self.at(1)+(self.at(3).div(2)); end

Set the y coordinate of the center of the Rect by translating the Rect (adjusting the y offset).

[Source]

# File lib/rubygame/rect.rb, line 251
        def centery=(y); self[1] = y- (self.at(3).div(2)); return y; end

As clamp!, but the original caller is not changed.

[Source]

# File lib/rubygame/rect.rb, line 378
        def clamp(rect)
                self.dup.clamp!(rect)
        end

Translate the calling Rect to be entirely inside the given Rect. If the caller is too large along either axis to fit in the given rect, it is centered with respect to the given rect, along that axis.

[Source]

# File lib/rubygame/rect.rb, line 385
        def clamp!(rect)
                nself = self.normalize
                rect = Rect.new_from_object(rect)
                #If self is inside given, there is no need to move self
                unless rect.contain?(nself)

                        #If self is too wide:
                        if nself.at(2) >= rect.at(2)
                                self[0] = rect.centerx - nself.at(2).div(2)
                                #Else self is not too wide
                        else
                                #If self is to the left of arg
                                if nself.at(0) < rect.at(0)
                                        self[0] = rect.at(0)
                                #If self is to the right of arg
                                elsif nself.right > rect.right
                                        self[0] = rect.right - nself.at(2)
                                #Otherwise, leave x alone
                                end
                        end

                        #If self is too tall:
                        if nself.at(3) >= rect.at(3)
                                self[1] = rect.centery - nself.at(3).div(2)
                                #Else self is not too tall
                        else
                                #If self is above arg
                                if nself.at(1) < rect.at(1)
                                        self[1] = rect.at(1)
                                #If self below arg
                                elsif nself.bottom > rect.bottom
                                        self[1] = rect.bottom - nself.at(3)
                                #Otherwise, leave y alone
                                end
                        end
                end
                return self
        end

As clip!, but the original caller is not changed.

[Source]

# File lib/rubygame/rect.rb, line 425
        def clip(rect)
                self.dup.clip!(rect)
        end

Crop the calling Rect to be entirely inside the given Rect. If the caller does not intersect the given Rect at all, its width and height are set to zero, but its x and y offsets are not changed.

As a side effect, the Rect is normalized.

[Source]

# File lib/rubygame/rect.rb, line 434
        def clip!(rect)
                nself = self.normalize
                other = Rect.new_from_object(rect).normalize!
                if self.collide_rect?(other)
                        self[0] = [nself.at(0), other.at(0)].max
                        self[1] = [nself.at(1), other.at(1)].max
                        self[2] = [nself.right, other.right].min - self.at(0)
                        self[3] = [nself.bottom, other.bottom].min - self.at(1)
                else #if they do not intersect at all:
                        self[0], self[1] = nself.topleft
                        self[2], self[3] = 0, 0
                end
                return self
        end

Iterate through all elements in the given Array, and return the index of the first element which is a Rect that collides with the caller.

[Source]

# File lib/rubygame/rect.rb, line 477
        def collide_array(array_rects)
                for i in (0...(array_rects.length))
                        if array_rects[i].collide_rect?(self)
                                return i
                        end
                end
                return nil
        end

Iterate through all elements in the given Array, and return an Array containing the indices of every element that is a Rect that collides with the caller.

[Source]

# File lib/rubygame/rect.rb, line 489
        def collide_array_all(array_rects)
                indexes = []
                for i in (0...(array_rects.length))
                        if array_rects[i].collide_rect?(self)
                                indexes += [i]
                        end
                end
                return indexes
        end

Iterate through all key/value pairs in the given hash table, and return the first pair whose value is a Rect that collides with the caller.

Because a hash table is unordered, you should not expect any particular Rect to be returned first.

[Source]

# File lib/rubygame/rect.rb, line 455
        def collide_hash(hash_rects)
                hash_rects.each { |key,value|
                        if value.collide_rect?+(self); return [key,value]; end
                }
                return nil
        end

Iterate through all key/value pairs in the given hash table, and return an Array of every pair whose value is a Rect that collides the caller.

Because a hash table is unordered, you should not expect the returned pairs to be in any particular order.

[Source]

# File lib/rubygame/rect.rb, line 468
        def collide_hash_all(hash_rects)
                hash_rects.select { |key,value|
                        value.collide_rect?+(self)
                }
        end

True if the point is inside (including on the border) of the caller. If you have Array of coordinates, you can use collide_point?(*coords).

[Source]

# File lib/rubygame/rect.rb, line 501
        def collide_point?(x,y)
                nself = normalize()
                x.between?(nself.left,nself.right) && y.between?(nself.top,nself.bottom)
        end

True if the caller and the given Rect overlap (or touch) at all.

[Source]

# File lib/rubygame/rect.rb, line 507
        def collide_rect?(rect)
                nself = self.normalize
                rect  = Rect.new_from_object(rect).normalize!
                return ((nself.l >= rect.l && nself.l <= rect.r) or (rect.l >= nself.l && rect.l <= nself.r)) &&
                       ((nself.t >= rect.t && nself.t <= rect.b) or (rect.t >= nself.t && rect.t <= nself.b))
        end

True if the given Rect is totally within the caller. Borders may overlap.

[Source]

# File lib/rubygame/rect.rb, line 516
        def contain?(rect)
                nself = self.normalize
                rect = Rect.new_from_object(rect).normalize!
                return (nself.left <= rect.left and rect.right <= nself.right and
                                        nself.top <= rect.top and rect.bottom <= nself.bottom)
        end
cx()

Alias for centerx

cx=(x)

Alias for centerx=

cy()

Alias for centery

cy=(y)

Alias for centery=

Returns self.at(3)

[Source]

# File lib/rubygame/rect.rb, line 186
        def h; return self.at(3); end

Sets self[3] to val

[Source]

# File lib/rubygame/rect.rb, line 188
        def h=(val); self[3] = val; end
height()

Alias for h

height=(val)

Alias for h=

As inflate!, but the original caller is not changed.

[Source]

# File lib/rubygame/rect.rb, line 524
        def inflate(x,y)
                return self.class.new(self.at(0) - x.div(2),
                                                                                                        self.at(1) - y.div(2),
                                                                                                        self.at(2) + x,
                                                                                                        self.at(3) + y)
        end

Increase the Rect’s size is the x and y directions, while keeping the same center point. For best results, expand by an even number. X and y inflation can be given as an Array or as separate values.

[Source]

# File lib/rubygame/rect.rb, line 534
        def inflate!(x,y)
                self[0] -= x.div(2)
                self[1] -= y.div(2)
                self[2] += x
                self[3] += y
                return self
        end

Print the Rect in the form “+#+“

[Source]

# File lib/rubygame/rect.rb, line 142
        def inspect; "#<Rect:#{self.object_id} [%s,%s,%s,%s]>"%self; end
l()

Alias for x

l=(val)

Alias for x=

left()

Alias for x

left=(val)

Alias for x=

mb()

Alias for midbottom

mb=(midbottom)

Alias for midbottom=

Return the x and y coordinates of the midpoint on the left side of the Rect.

[Source]

# File lib/rubygame/rect.rb, line 359
        def midbottom; return self.centerx, self.bottom; end

Set the x and y coordinates of the midpoint on the bottom side of the Rect by translating the Rect (adjusting the x and y offsets).

[Source]

# File lib/rubygame/rect.rb, line 363
        def midbottom=(midbottom)
        raise ArgumentError, "Rect#midbottom= takes an Array of form [x, y]." if midbottom.size != 2
                self.centerx, self.bottom = midbottom
                return midbottom
        end

Return the x and y coordinates of the midpoint on the left side of the Rect.

[Source]

# File lib/rubygame/rect.rb, line 314
        def midleft; return self.at(0), self.centery; end

Set the x and y coordinates of the midpoint on the left side of the Rect by translating the Rect (adjusting the x and y offsets).

[Source]

# File lib/rubygame/rect.rb, line 318
        def midleft=(midleft)
        raise ArgumentError, "Rect#midleft= takes an Array of form [x, y]." if midleft.size != 2
                self[0], self.centery = midleft
                return midleft
        end

Return the x and y coordinates of the midpoint on the left side of the Rect.

[Source]

# File lib/rubygame/rect.rb, line 344
        def midright; return self.right, self.centery; end

Set the x and y coordinates of the midpoint on the right side of the Rect by translating the Rect (adjusting the x and y offsets).

[Source]

# File lib/rubygame/rect.rb, line 348
        def midright=(midright)
        raise ArgumentError, "Rect#midright= takes an Array of form [x, y]." if midright.size != 2
                self.right, self.centery = midright
                return midright
        end

Return the x and y coordinates of the midpoint on the left side of the Rect.

[Source]

# File lib/rubygame/rect.rb, line 329
        def midtop; return self.centerx, self.at(1); end

Set the x and y coordinates of the midpoint on the top side of the Rect by translating the Rect (adjusting the x and y offsets).

[Source]

# File lib/rubygame/rect.rb, line 333
        def midtop=(midtop)
        raise ArgumentError, "Rect#midtop= takes an Array of form [x, y]." if midtop.size != 2
                self.centerx, self[1] = midtop
                return midtop
        end
ml()

Alias for midleft

ml=(midleft)

Alias for midleft=

As move!, but the original caller is not changed.

[Source]

# File lib/rubygame/rect.rb, line 543
        def move(x,y)
                self.dup.move!(x,y)
        end

Translate the Rect by the given amounts in the x and y directions. Positive values are rightward for x and downward for y. X and y movement can be given as an Array or as separate values.

[Source]

# File lib/rubygame/rect.rb, line 550
        def move!(x,y)
                self[0]+=x; self[1]+=y
                return self
        end
mr()

Alias for midright

mr=(midright)

Alias for midright=

mt()

Alias for midtop

mt=(midtop)

Alias for midtop=

As normalize!, but the original caller is not changed.

[Source]

# File lib/rubygame/rect.rb, line 556
        def normalize
                self.dup.normalize!()
        end

Fix Rects that have negative width or height, without changing the area it represents. Has no effect on Rects with non-negative width and height. Some Rect methods will automatically normalize the Rect.

[Source]

# File lib/rubygame/rect.rb, line 563
        def normalize!
                if self.at(2) < 0
                        self[0], self[2] = self.at(0)+self.at(2), -self.at(2)
                end
                if self.at(3) < 0
                        self[1], self[3] = self.at(1)+self.at(3), -self.at(3)
                end
                self
        end
r()

Alias for right

r=(r)

Alias for right=

Return the x coordinate of the right side of the Rect.

[Source]

# File lib/rubygame/rect.rb, line 204
        def right; return self.at(0)+self.at(2); end

Set the x coordinate of the right side of the Rect by translating the Rect (adjusting the x offset).

[Source]

# File lib/rubygame/rect.rb, line 208
        def right=(r); self[0] = r - self.at(2); return r; end

Return the width and height of the Rect.

[Source]

# File lib/rubygame/rect.rb, line 194
        def size; return self[2,2]; end

Set the width and height of the Rect.

[Source]

# File lib/rubygame/rect.rb, line 197
        def size=(size)
         raise ArgumentError, "Rect#size= takes an Array of form [width, height]." if size.size != 2
         self[2,2] = size
         size
        end
t()

Alias for y

t=(val)

Alias for y=

tl()

Alias for topleft

tl=(topleft)

Alias for topleft=

Print the Rect in the form “+#<Rect [x,y,w,h]>+“

[Source]

# File lib/rubygame/rect.rb, line 139
        def to_s; "#<Rect [%s,%s,%s,%s]>"%self; end
top()

Alias for y

top=(val)

Alias for y=

Return the x and y coordinates of the top-left corner of the Rect

[Source]

# File lib/rubygame/rect.rb, line 257
        def topleft; return self[0,2].to_a; end

Set the x and y coordinates of the top-left corner of the Rect by translating the Rect (adjusting the x and y offsets).

[Source]

# File lib/rubygame/rect.rb, line 261
        def topleft=(topleft)
            raise ArgumentError, "Rect#topright= takes an Array of form [x, y]." if topleft.size != 2
                self[0,2] = topleft
                return topleft
        end

Return the x and y coordinates of the top-right corner of the Rect

[Source]

# File lib/rubygame/rect.rb, line 271
        def topright; return self.right, self.at(1); end

Set the x and y coordinates of the top-right corner of the Rect by translating the Rect (adjusting the x and y offsets).

[Source]

# File lib/rubygame/rect.rb, line 275
        def topright=(topright)
            raise ArgumentError, "Rect#topright= takes an Array of form [x, y]." if topright.size != 2
                self.right, self[1] = topright
                return topright
        end
tr()

Alias for topright

tr=(topright)

Alias for topright=

As union!, but the original caller is not changed.

[Source]

# File lib/rubygame/rect.rb, line 574
        def union(rect)
                self.dup.union!(rect)
        end

Expand the caller to also cover the given Rect. The Rect is still a rectangle, so it may also cover areas that neither of the original Rects did, for example areas between the two Rects.

[Source]

# File lib/rubygame/rect.rb, line 581
        def union!(rect)
                self.normalize!
    rleft, rtop = self.topleft
    rright, rbottom = self.bottomright
                r2 = Rect.new_from_object(rect).normalize!

                rleft = [rleft, r2.left].min
                rtop = [rtop, r2.top].min
                rright = [rright, r2.right].max
                rbottom = [rbottom, r2.bottom].max

                self[0,4] = rleft, rtop, rright - rleft, rbottom - rtop
                return self
        end

As union_all!, but the original caller is not changed.

[Source]

# File lib/rubygame/rect.rb, line 597
        def union_all(array_rects)
                self.dup.union_all!(array_rects)
        end

Expand the caller to cover all of the given Rects. See also union!

[Source]

# File lib/rubygame/rect.rb, line 602
        def union_all!(array_rects)
                array_rects.each do |r|
      self.union!(r)
                end
                return self
        end

Returns self.at(2)

[Source]

# File lib/rubygame/rect.rb, line 178
        def w; return self.at(2); end

Sets self[2] to val

[Source]

# File lib/rubygame/rect.rb, line 180
        def w=(val); self[2] = val; end
width()

Alias for w

width=(val)

Alias for w=

Returns self.at(0)

[Source]

# File lib/rubygame/rect.rb, line 158
        def x; return self.at(0); end

Sets self[0] to val

[Source]

# File lib/rubygame/rect.rb, line 160
        def x=(val); self[0] = val; end

Returns self.at(1)

[Source]

# File lib/rubygame/rect.rb, line 168
        def y; return self.at(1); end

Sets self[1] to val

[Source]

# File lib/rubygame/rect.rb, line 170
        def y=(val); self[1] = val; end

[Validate]