Skip to content
This repository has been archived by the owner on Jun 12, 2019. It is now read-only.

Windows

Jump to bottom
pdinklag edited this page Jan 2, 2013 · 7 revisions

Don't let the title mislead you - this will work on any platform! Well, for Mac OS X, please make sure to read the extra chapter at the bottom - even if you don't use a Mac yourself!

In order to do anything visual using JSFML, you need something to display it in. For this, JSFML provides the RenderWindow class. This class is used to:

  • Open a window
  • Receive and handle user input
  • Display stuff

In future versions, JSFML is set to provide a render canvas that can be put in any Swing window. For now, JSFML applications need to open a dedicated window.

In the Javadoc, you will also find the Window class. It is an abstraction of the RenderWindow class and serves merely as an OpenGL context. This is not very useful for JSFML at the moment, but it might become relevant in the future.

The Code

The following code creates a simple window that is filled with a red color and is closed when the user presses the close button. The code will be elaborated upon in the following chapters.

//Create the window
RenderWindow window = new RenderWindow();
window.create(new VideoMode(640, 480), "Hello JSFML!");

//Limit the framerate
window.setFramerateLimit(30);

//Main loop
while(window.isOpen()) {
    //Fill the window with red
    window.clear(Color.RED);

    //Display what was drawn (... the red color!)
    window.display();

    //Handle events
    for(Event event : window.pollEvents()) {
        if(event.type == Event.Type.CLOSED) {
            //The user pressed the close button
            window.close();
        }
    }
}

RenderWindow

As mentioned above, the RenderWindow class is used to create and manage windows which JSFML can render on.

The [create](http://jsfml.org/javadoc/org/jsfml/window/Window.html#create(org.jsfml.window.VideoMode, java.lang.String, int, org.jsfml.window.ContextSettings)) method will create a window and open it. At least two parameters need to be passed to it: a video mode (see below) and a title that will be displayed in the window's title bar.

The [setFramerateLimit](http://jsfml.org/javadoc/org/jsfml/window/Window.html#setFramerateLimit(int\)) method is used to limit the window's framerate to 30 frames per second. This means that in the main loop, after display was called, the window will wait for a while so that the loop is not executed more frequently than approximately 30 times a second. This heavily reduces the processor and graphics card use of the application and besides, the human eye cannot distinguish between higher framerates. Alternatively to setFrameLimit, you can use [setVerticalSyncEnabled](http://jsfml.org/javadoc/org/jsfml/window/Window.html#setVerticalSyncEnabled(boolean\)) to force vertical synchronization. However, do not use both setFrameLimit and vertical sync at the same time - bad things will happen!

[isOpen](http://jsfml.org/javadoc/org/jsfml/window/Window.html#isOpen(\)) serves an obvious purpose: it is used to check if the window in question is still open. It can be closed using the [close](http://jsfml.org/javadoc/org/jsfml/window/Window.html#close(\)) method. Note that pressing the window's close button will not close the window automatically, but only fire a close event (see below).

As long as the window is open, the main loop is executed.

In there, the window is cleared first. This might seem a little redundant to do every frame (a frame is every time the main loop is executed), but let us assume that we are drawing a shape that moves across the screen a little each frame (we will get to that later): if we didn't clear the window each frame, we would end up with a trail of shapes, which is not what we wanted to achieve.

Clearing the window is done using the [clear](http://jsfml.org/javadoc/org/jsfml/graphics/RenderWindow.html#clear(org.jsfml.graphics.Color\)) method. It optionally takes a color (see below) that the window will be filled with - a background color, so to speak.

Between clear and display, we would draw our objects - if we knew how to. Don't worry, the following chapters will teach you.

To finish drawing, the [display](http://jsfml.org/javadoc/org/jsfml/window/Window.html#display(\)) method will put it into the visible window. All drawing operations really occur in a background buffer (abbreviated backbuffer), because that is very fast. The display method takes care of making it visible to us in our window.

The loop that follows is the event handling loop. A lot of things can happen that the window will be notified about - the user may click on the close button, he may resize the window, he might enter something on the keyboard, etc. These events must be polled regularly. If that doesn't happen, the window becomes unresponsive - it freezes, and we don't want that to happen.

Therefore, we poll all events that occured in the last frame using the [pollEvents](http://jsfml.org/javadoc/org/jsfml/window/Window.html#pollEvents(\)) method. How exactly those events can be handled will be further described in the next chapter of the documentation. In this simple example, we check if the user clicked the window's close button and if so, we close the window. All other events (e.g. keyboard input) are ignored.

When the window gets closed, isOpen will return false in the main loop's header and that will stop it. The application is then finished.

VideoMode

The VideoMode class represents the video mode to be used for the window.

For normal windows (ie not fullscreen), this equals the initial size of the window. In the example above, the window will be created 640x480 pixels large.

If the window will be fullscreen (see below), the video mode needs to be valid, ie it needs to be supported by the monitor. To check if a video mode is valid, use the [isValid](http://jsfml.org/javadoc/org/jsfml/window/VideoMode.html#isValid(\)) function. To get the video mode that the monitor is currently running on (ie the current screen resolution), use the [getDesktopMode](http://jsfml.org/javadoc/org/jsfml/window/VideoMode.html#getDesktopMode(\)) method. The desktop mode is always valid.

To get a list of all video modes that the monitor supports for fullscreen mode, use the [getFullscreenModes](http://jsfml.org/javadoc/org/jsfml/window/VideoMode.html#getFullscreenModes(\)) method.

Color

The Color class provides a simple representation of RGBA colors. There are a bunch of pre-defined colors that can be worked with. Note that colors are immutable in JSFML.

Fullscreen and other window settings

The create method optionally accepts an additional parameter, the window style.

The window style is a bitfield of flags that determine some basic properties:

  • CLOSE - The window has a close button.
  • FULLSCREEN - The window will go into fullscreen mode.
  • RESIZE - The user can resize the window.
  • TITLEBAR - The window has a title bar, displaying a title and an icon.
  • NONE - The window has none of the properties mentioned above.
  • DEFAULT - A combination of CLOSE, RESIZE and TITLEBAR which will be used by default.

Any flag that is not set will not apply. You can combine flags by using the bitwise OR operator. For instance, the DEFAULT style is defined as:

DEFAULT = CLOSE | RESIZE | TITLEBAR;

This means that DEFAULT windows will get a close button and a title bar, and they can be resized by the user. However, they do not run in fullscreen mode.

Setting the window icon

The icon left of the window title can be changed using the [setIcon](http://jsfml.org/javadoc/org/jsfml/window/Window.html#setIcon(org.jsfml.graphics.Image\)) method. This requires an Image, which will be presented in one of the following documentation chapters.

ContextSettings

Additionally to the window's style, another, less common parameter can be passes to the create method: the ContextSettings. These can be used to alter several aspects of the OpenGL context that the window creates:

  • The OpenGL version to use (if available).
  • The number of anti-aliasing samples.
  • The amount of depth buffer bits.
  • The amount of stencil buffer bits.

Anti-aliasing is used for smooth edges on primitives.

The depth and stencil buffers are explained in the article The Framebuffer on GLProgramming.com.

Windows on Mac OS X

Note that the following information is not only for Mac OS X users, but for anybody who wants their JSFML application to work on a Mac.

Our friends at Apple thought of something awesome when designing their window system Cocoa: windows can only be created in an application's main / starting thread. For Java applications, this is bad news, because by default, the JVM runs the main method in a forked thread.

To avoid this, you need to pass the JVM option -XstartOnFirstThread to Java when you are starting it.

Now, to add some extra fun, this flag will prevent the JVM from starting on any system other than Mac OS X, because it is not a standard flag and thus is not known to other JVM implementations.

So, addressing Mac users comes at the cost of providing a special starting script for them. Unfortunately, there's nothing JSFML can do about this.

Clone this wiki locally