[Scripting][Series]RGSS: Windows - Lesson 1: An Introduction to Windows Options

[ccoa]

Ccoa's Guide To Windows In RGSS

What is a window?

Let's start out with the basics. What is a window? A window is essentially an image that you can draw on. The image is "skinned" with a windowskin that you specify. Windows are the backbone of all the scenes in RMXP.

Making a Simple Window

Let's jump right in and get our feet wet, yes?

Open up your script editor in a new project. Right click Arrow_Base and select Insert. Name the new section Window_First. Type the following in the script editor:

CODE

class Window_First < Window_Base
  
end

This tells the Ruby interpreter that there is a new class named Window_First, and that it is descended from Window_Base. The magic of inheritance means that Window_First has inherited all of Window_Base's data members and methods. In plain English, Window_First can now do anything Window_Base can do.

However, it can't do anything of its own. Let's remedy that, shall we?

CODE

class Window_First < Window_Base
  #--------------------------------------------------------------------------
  # * Object Initialization
  #--------------------------------------------------------------------------
  def initialize
    super(0, 0, 256, 96)
  end
end

The initialize method is special. It's what's automatically called when you create a new object of the class (in this case, a new window). The super keyword tells the interpreter to go to the parent class, and look for a method of the same name. In this case, it's looking in Window_Base for a method named initialize. Look in Window_Base:

CODE

  #--------------------------------------------------------------------------
  # * Object Initialization
  #     x      : window x-coordinate
  #     y      : window y-coordinate
  #     width  : window width
  #     height : window height
  #--------------------------------------------------------------------------
  def initialize(x, y, width, height)
    super()
    @windowskin_name = $game_system.windowskin_name
    self.windowskin = RPG::Cache.windowskin(@windowskin_name)
    self.x = x
    self.y = y
    self.width = width
    self.height = height
    self.z = 100
  end

See the (x, y, width, height) parameters? These line up with the (0, 0, 256, 96) arguments we passed into the super call. In other words, we're making a window that is a coordinate 0, 0, and is 256 pixels wide and 96 pixels high.

Not bad, but the window still isn't doing anything! Let's add some text to it.

CODE

class Window_First < Window_Base
  #--------------------------------------------------------------------------
  # * Object Initialization
  #--------------------------------------------------------------------------
  def initialize
    super(0, 0, 256, 96)
    self.contents = Bitmap.new(width - 32, height - 32)
    
    refresh
  end
  
  #--------------------------------------------------------------------------
  # * Refresh
  #--------------------------------------------------------------------------
  def refresh
    self.contents.clear
    
    self.contents.draw_text(0, 0, 256, 32, "Hello, World")
  end
end

Let's take this a little at a time.

CODE

    self.contents = Bitmap.new(width - 32, height - 32)

This creates a new bitmap for the window to draw on. This line is necessary if you want to place any text or draw images on the window. Because of the limitations of the Window classes, there is a 16 pixel border inside every window that cannot be drawn on. Thus the - 32's.

CODE

    refresh

This is a call to the method titled refresh. Everything in that method will execute until it reaches the end of the method or it hits a return statement, and only then will we return to the initialize method to finish.

CODE

  def refresh

We just defined a method called refresh. Looking around, you'll notice most of the RGSS Window classes have refresh methods. They usually do exactly what they sound like - refresh the image.

CODE

    self.contents.clear

This "erases" anything that might already have been drawn on the bitmap.

CODE

    self.contents.draw_text(0, 0, 256, 32, "Hello, World")

This asks the bitmap object to draw some text on itself. The draw_text method looks like this:

draw_text(x, y, width, height, text, alignment)

x is the x coordinate to draw it at, and y is the y coordinate. Note that these are coordinates on the window, not the screen. 0, 0 is the upper left corner of the window.

Width is how wide to fit the text into. If the text won't fit, the method will try to squeeze it in, making the text narrower. Height works similarly for height.

Text is the text you want to draw. In this case, Hello, World.

Alignment is optional. By default, it's 0, which is aligned left. 1 would center the text, 2 would right align it. So if we changed the above line to

CODE

    self.contents.draw_text(0, 0, 256, 32, "Hello, World", 1)

The text will be drawn centered inside the 256 pixel width you specified.

Now let's take a look at this window. Create a new event. Place the following in a Script event command:

CODE

$window = Window_First.new

$window is the name of your variable. The $ indicates that it's a global variable - that is, you can access it from anywhere. This is the name of your window object.

Window_First.new tells the interpreter that you want a new object of class Window_First. This will automatically call the initialize method we wrote just a moment ago.

Now put in a short wait, say 80 frames, using the Wait event command.

Finally, put the following in a Script event command:

CODE

$window.dispose

The dispose method will make the window disappear. It's very important to dispose windows, even if they're not currently visible. If you don't, they'll hang around forever and lag your game.

But wait, you say. We didn't write a dispose method!

That's okay, the dispose method exists in Window_Base:

CODE

  #--------------------------------------------------------------------------
  # * Dispose
  #--------------------------------------------------------------------------
  def dispose
    # Dispose if window contents bit map is set
    if self.contents != nil
      self.contents.dispose
    end
    super
  end

Remember when I said Window_First can do anything Window_Base can do? That means accessing any and all methods defined in Window_Base.

The end result:



Homework

Try it yourself. Play with the code, show me what you can do. Some time after I get at least 5 homework assignments, I'll write the next part.

[LOD]

dammit what happened? i followed all the steps by copying the scripting and all i get is a message of error saying that an error ocurred on Window_First!

[storymasterq]

dammit what happened? i followed all the steps by copying the scripting and all i get is a message of error saying that an error ocurred on Window_First!

Can you be specific and tell us what the error was?

Cheers,
SQ