CarnegieMellonGraphics2
Class Window

Direct Known Subclasses:

FullScreenWindow

class Window

The Window class is used to represent that actual drawing surfaces. Currently on creating a new window object, a new window will open in user's operating environment. The background color is black by default.

Two different input paradigms have been provided. One is event based, and requires deriving a new Window class and then starting the CarnegieMellonGraphics event handler (described below). For this derived class to do something interesting, one or more of the "handle" member functions listed below must be overridden.

The other method of input works within the standard structured programming framework, and involves polling the "isQueueEmpty" functions to see if an event has occurred, removing the event from the queue, and processing it as desired.

Drawing into the window is then simply a matter of calling the appropriate member functions on the window.

Updates:

• A new method of input has been added: see isKeyDown and isButtonDown.
• To go into fullscreen mode, specify this as an additional parameter to the constructor: Window.

If you're working on a game, you will probably be interested in investigating the following functions: disableAutoPageFlip, flipPage, isKeyDown, isButtonDown, isModifierDown, and Window (fullscreen mode).

Window

public Window( const int width = 640, const int height = 480, const std::string& title = std::string("CarnegieMellonGraphics Window" ), bool fullscreen = false, int bitdepth = 32, int refreshrate = 60 );

Construct a new window with the specified size and title. (defaults to 640 by 480, with "CarnegieMellonGraphics Window" as the title)

This is the appropriate way to go into full screen mode. To create a regular windowed application, construct a window as follows:

  Window myWindow();

or

  Window myWindow(640,480,"my window"); // the last parameter defaults to false

To create a fullscreen window, pass true as the fourth parameter:

  Window myFullScreenWindow(640,480,"my full screen window",true);

If the dimensions of the window are not a standard dimension or one that is not supported by your video card, the window will probably not be constructed and no error will be reported. Dimensions such as 320x200, 320x240, 400x300, 640x480, 800x600, 1024x768, etc. are recommended for full screen mode.

Window

public Window( int xpos, int ypos, int width, int height, const std::string& title = std::string("CarnegieMellonGraphics Window" ), bool fullscreen = false, int bitdepth = 32, int refreshrate = 60 );

An alternate constructor where you get to choose the position of the window as well as all of the other usual parameters.

Since:

2.1.5

Window

private Window( const Window& window );

~Window

public virtual ~Window();

addKeyboardEvent

public void addKeyboardEvent( const KeyboardEvent& keyboard );

Functions to add events to the input queues. These should generally not be used, but it is possible they may be useful in some circumstances.

Note: calling this function will not set the key to be down

See Also:

getKeyboardEvent

addMouseEvent

public void addMouseEvent( const MouseEvent& mouse );

Functions to add events to the input queues. These should generally not be used, but it is possible they may be useful in some circumstances.

Note: calling this function will not set the button to be down

See Also:

getMouseEvent

addTimerEvent

public void addTimerEvent( const TimerEvent& timer );

Functions to add events to the input queues. These should generally not be used, but it is possible they may be useful in some circumstances.

See Also:

getTimerEvent, registerNewTimerEvent

autoFlushKeyboardQueue

public void autoFlushKeyboardQueue( bool enable );

Automatically lets you ignore the events in the keyboard message queue. You should use this if you want to ignore the event queue altogether. Enabling/disabling this will not affect isKeyDown. It is possible that the queue will at some point contain messages, but it will be flushed eventually.

Since:

2.1.2

See Also:

autoFlushMouseQueue, autoFlushTimerQueue, flushKeyboardQueue, getKeyboardEvent, isKeyboardQueueEmpty, isKeyDown, isModifierDown

autoFlushMouseQueue

public void autoFlushMouseQueue( bool enable );

Automatically lets you ignore the events in the mouse message queue. You should use this if you want to ignore the event queue altogether. Enabling/disabling this will not affect isButtonDown. It is possible that the queue will at some point contain messages, but it will be flushed eventually.

Since:

2.1.2

See Also:

autoFlushKeyboardQueue, autoFlushTimerQueue, flushMouseQueue, getMouseEvent, isButtonDown, isModifierDown, isMouseQueueEmpty

autoFlushTimerQueue

public void autoFlushTimerQueue( bool enable );

Automatically lets you ignore the events in the timer message queue. You should use this if you want to ignore the event queue altogether. Enabling/disabling this will not affect getTimerCount. It is possible that the queue will at some point contain messages, but it will be flushed eventually.

Since:

2.1.2

See Also:

autoFlushKeyboardQueue, autoFlushMouseQueue, flushTimerQueue, getTimerCount, getTimerEvent, isTimerQueueEmpty, registerNewTimerEvent

copyRegion

public void copyRegion( const int x1, const int y1, const int x2, const int y2, const int width, const int height );

Copy the rectangular region at (x1, y1) to (x2, y2)

createImage

public Image createImage( const int x, const int y, const int width, const int height );

Create an image from the rectangular region with an upper-left hand corner at (x, y)

See Also:

Image, drawImage

disableAntialiasing

public void disableAntialiasing();

Renderer dependent capability. If not supported by current renderer these will be ignored. Initial state is also dependent on the supplied renderer.

disableAutoPageFlip

public void disableAutoPageFlip();

By default each window will handle refreshing the graphics automatically for the user. However in some circumstances it may be desirable to perform these refreshes manually. First call disableAutoPageFlip to disable automatic refreshes and then flipPage whenever you want to show what you've drawn. enableAutoPageFlip may then be used to enable automatic refreshes.

See Also:

enableAutoPageFlip, flipPage, isAutoPageFlipEnabled

disableFullScreen

public void disableFullScreen();

Deprecated. Do not use. This works only on some systems. To ensure that you will always go into fullscreen mode, use the constructor Window.

drawArc

public void drawArc( const Style& s, const int x1, const int y1, const int x2, const int y2, const double start, const double end );

Draw an elliptical arc from angle start to end in degrees. The x and y coordinates specify the bounding box of the ellipse

drawBezierCurve

public void drawBezierCurve( const Style& s, const std::vector< int >& xcoords, const std::vector< int >& ycoords );

Draw a bezier curve using the specified style, and the two vectors specifying the control points

drawChordFilled

public void drawChordFilled( const Style& s, const int x1, const int y1, const int x2, const int y2, const double start, const double end );

Draw a filled elliptical chord with from start to end degrees The two points (x1, y1) and (x2, y2) specify the bounding box

drawChordOutline

public void drawChordOutline( const Style& s, const int x1, const int y1, const int x2, const int y2, const double start, const double end );

Draw an elliptical chord outline with from start to end degrees The two points (x1, y1) and (x2, y2) specify the bounding box

drawCircleFilled

public void drawCircleFilled( const Style& s, const int x, const int y, const int radius );

Draw a filled circle with style s and the specified radius at point (x, y)

drawCircleOutline

public void drawCircleOutline( const Style& s, const int x, const int y, const int radius );

Draw a circle outline with style s and the specified radius at point (x, y)

drawEllipseFilled

public void drawEllipseFilled( const Style& s, const int x1, const int y1, const int x2, const int y2 );

Draw a filled ellipse with inside the bounding box specfied by the two points (x1, y1) and (x2, y2)

drawEllipseOutline

public void drawEllipseOutline( const Style& s, const int x1, const int y1, const int x2, const int y2 );

Draw an ellipse outline with inside the bounding box specified by the two points (x1, y1) and (x2, y2)

drawImage

public void drawImage( const Image& image, const int x, const int y );

Draw the image at with its upper right-hand corner located at (x,y)

See Also:

drawImage(constImage&,constint,constint,constTransform&), Image

drawImage

public void drawImage( const Image& image, const int x, const int y, const Transform& transform );

Draw the image at with its upper right-hand corner located at (x,y) using the specified transform

Since:

2.10

See Also:

drawImage(constImage&,constint,constint), Image

drawLine

public void drawLine( const Style& s, const int x1, const int y1, const int x2, const int y2 );

Draw a line from (x1,y1) to (x2, y2) with style s

drawPixel

public void drawPixel( const Style& s, const int x, const int y );

Draw a pixel at (x,y) with style s. If you want to do a lot of bit manipulation, you should use EditableImage. drawPixel can be slow if you do a lot of pixel-level editing.

See Also:

EditableImage

drawPolygonFilled

public void drawPolygonFilled( const Style& s, const std::vector< int >& xcoords, const std::vector< int >& ycoords );

Draw a filled polygon using the specified style and the two vectors to specifiy vertices

drawPolygonOutline

public void drawPolygonOutline( const Style& s, const std::vector< int >& xcoords, const std::vector< int >& ycoords );

Draw a polygon outline using the specified style and the two vectors to specifiy vertices

drawPolyLine

public void drawPolyLine( const Style& s, const std::vector< int >& xcoords, const std::vector< int >& ycoords );

Draw a polyline using the specified style and the two vectors to specifiy vertices

drawRectangleFilled

public void drawRectangleFilled( const Style& s, const int x1, const int y1, const int x2, const int y2 );

Draw a filled rectangle with (x1, y1) as the upper left-hand corner, and (x2, y2) as the lower right-hand corner with style s

drawRectangleOutline

public void drawRectangleOutline( const Style& s, const int x1, const int y1, const int x2, const int y2 );

Draw a rectangle outline with (x1, y1) as the upper left-hand corner, and (x2, y2) as the lower right-hand corner with style s

drawText

public void drawText( const Style& s, const Font& f, const int x, const int y, const std::string& text );

Draw text in the specified font and style

See Also:

drawText(constStyle&,constFont&,constint,constint,conststring&,constTransform&), numberToString(int), numberToString(double)

drawText

public void drawText( const Style& s, const Font& f, const int x, const int y, const std::string& text, const Transform& transform );

Draw text in the specified font and style, using the specified transform

Since:

2.10

See Also:

drawText(constStyle&,constFont&,constint,constint,conststring&,constTransform&), numberToString(int), numberToString(double)

drawTriangleFilled

public void drawTriangleFilled( const Style& s, const int x1, const int y1, const int x2, const int y2, const int x3, const int y3 );

Draw a filled triangle with vertices (x1, y1), (x2, y2), (x3, y3) with in style s

drawTriangleOutline

public void drawTriangleOutline( const Style& s, const int x1, const int y1, const int x2, const int y2, const int x3, const int y3 );

Draw a triangle outline with vertices (x1, y1), (x2, y2), (x3, y3) with in style s

drawWedgeFilled

public void drawWedgeFilled( const Style& s, const int x1, const int y1, const int x2, const int y2, const double start, const double end );

Draw a filled elliptical wedge with from start to end degrees The two points (x1, y1) and (x2, y2) specify the bounding box

drawWedgeOutline

public void drawWedgeOutline( const Style& s, const int x1, const int y1, const int x2, const int y2, const double start, const double end );

Draw an elliptical wedge outline with from start to end degrees The two points (x1, y1) and (x2, y2) specify the bounding box

enableAntialiasing

public void enableAntialiasing();

Renderer dependent capability. If not supported by current renderer these will be ignored. Initial state is also dependent on the supplied renderer.

enableAutoPageFlip

public void enableAutoPageFlip();

Enabled by default; everything you draw will automatically appear on screen. To get much better performance, use flipPage and disableAutoPageFlip.

See Also:

disableAutoPageFlip, flipPage, isAutoPageFlipEnabled

enableFullScreen

public void enableFullScreen( int bitdepth = 16, int refreshrate = 60 );

Deprecated. Do not use. This works only on some systems. To ensure that you will always go into fullscreen mode, use the constructor Window.

flipPage

public void flipPage();

Make the changes that you've made appear on screen. All drawing is done off screen, this will show the user the off-screen page.

See Also:

disableAutoPageFlip, enableAutoPageFlip, isAutoPageFlipEnabled

flushKeyboardQueue

public void flushKeyboardQueue();

Remove all pending messages in the keyboard event queue.

See Also:

autoFlushKeyboardQueue, getKeyboardEvent, isKeyboardQueueEmpty, isKeyDown, waitForKeyboardEvent

flushMouseQueue

public void flushMouseQueue();

Remove all pending messages in the mouse event queue.

See Also:

autoFlushMouseQueue, getMouseEvent, isButtonDown, isMouseQueueEmpty, waitForMouseEvent

flushTimerQueue

public void flushTimerQueue();

Remove all pending messages in the timer event queue.

See Also:

autoFlushTimerQueue, getTimerCount, getTimerEvent, isTimerQueueEmpty, registerNewTimerEvent, waitForTimerEvent

getHeight

public int getHeight() const;

Return the height of the window.

See Also:

getWidth

getKeyboardEvent

public KeyboardEvent getKeyboardEvent();

Pull events off the front of the Keyboard event queue. Use isKeyDown if you're interested in less precise input processing (i.e. when you're making a game).

See Also:

flushKeyboardQueue, ignoreKeyRepeat, isKeyboardQueueEmpty, isKeyDown, waitForKeyboardEvent

getKeyboardFilter

public KeyboardEvent getKeyboardFilter();

Set filters on the input queues, useful in eliminating non-interesting events. Intended for advanced users only. If set to NULL, no filtering is performed. If set to some value, only events that do not match the event pattern will be placed into the queue. There is no default keyboard filter.

See Also:

setKeyboardFilter

getMouseEvent

public MouseEvent getMouseEvent();

Pull events off the front of the Mouse event queue Use isButtonDown if you're interested in less precise input processing (i.e. when you're making a game).

See Also:

flushMouseQueue, isButtonDown, isMouseQueueEmpty, waitForMouseEvent

getMouseFilter

public MouseEvent getMouseFilter();

Set filters on the input queues, useful in eliminating non-interesting events. Intended for advanced users only. If set to NULL, no filtering is performed. If set to some value, only events that do not match the event pattern will be placed into the queue. By default, when not using the CarnegieMellonGraphics event handler, MOUSE_MOVE events are filtered out to prevent unnecessary events from cluttering the queue.

See Also:

setMouseFilter

getMouseX

public int getMouseX() const;

Return the last location of mouse X position.

See Also:

getMouseEvent, getMouseY, isButtonDown

getMouseY

public int getMouseY() const;

Return the last location of mouse Y position.

See Also:

getMouseEvent, getMouseX, isButtonDown

getPosition

public void getPosition( int& x, int& y );

Retrieves the current position of the window.

Parameters:

x - [out] x position of the window

y - [out] y position of the window

Since:

2.1.5

See Also:

resize, setTitle, setPosition

getTimerCount

public int getTimerCount( const TimerEvent& te );

Get the number of times this timer event has occurred. Generally used in conjunction with @setTimerCount, this is very good for making sure that your program keeps a time (like maintaining a framerate).

Since:

2.1.2

See Also:

getTimerEvent, registerNewTimerEvent, setTimerCount

getTimerEvent

public TimerEvent getTimerEvent();

Pull events off the front of the Timer event queue Use getTimerCount to get lower-overhead event processing.

See Also:

flushTimerEvent, isTimerQueueEmpty, waitForTimerEvent, registerNewTimerEvent

getTimerFilter

public TimerEvent getTimerFilter();

Set filters on the input queues, useful in eliminating non-interesting events. Intended for advanced users only. If set to NULL, no filtering is performed. If set to some value, only events that do not match the event pattern will be placed into the queue. There is no default timer filter.

See Also:

setTimerFilter

getWidth

public int getWidth() const;

Return the width of the window.

See Also:

getHeight

handleIdleEvent

public virtual void handleIdleEvent();

Event handlers for when in event handling mode. To be useful you must derive your own version of Window that overides these functions

See Also:

WindowManager

handleKeyboardEvent

public virtual void handleKeyboardEvent( const KeyboardEvent& event );

Event handlers for when in event handling mode. To be useful you must derive your own version of Window that overides these functions

See Also:

WindowManager

handleMouseEvent

public virtual void handleMouseEvent( const MouseEvent& event );

Event handlers for when in event handling mode. To be useful you must derive your own version of Window that overides these functions

See Also:

WindowManager

handleTimerEvent

public virtual void handleTimerEvent( const TimerEvent& event );

Event handlers for when in event handling mode. To be useful you must derive your own version of Window that overides these functions

See Also:

WindowManager

hide

public void hide();

Hide this window.

See Also:

isHidden, show

ignoreKeyRepeat

public void ignoreKeyRepeat( bool ignore );

Ignore repeated keystrokes sent to this window. If this is disabled, keystrokes will occur repeatedly which might be unwanted for games using the keyboard.

Since:

2.1.2

See Also:

autoFlushKeyboardQueue, getKeyboardEvent, isKeyDown

isAutoPageFlipEnabled

public bool isAutoPageFlipEnabled();

Will return whether or not auto page flipping is enabled.

Since:

2.1.5

See Also:

disableAutoPageFlip, enableAutoPageFlip, flipPage

isButtonDown

public bool isButtonDown( MouseEvent::Button b );

Tells whether a specified mouse button is down. You can check for "chording" of mouse buttons in this fashion. For example:

if (isButtonDown(MouseEvent::LEFT_BUTTON) && isButtonDown(MouseEvent::RIGHT_BUTTON)) 
  // do something if both buttons are down

This is the recommended method of input if you are writing a game. If you need absolute precision, then do not use this function. There is no guarantee that if a button is pressed checking it in this fashion will ever show that it has been pressed.

This should probably be used in conjuction with autoFlushMouseQueue.

Since:

2.1.2

See Also:

autoFlushMouseQueue, flushMouseQueue, getMouseEvent, isButtonDown, isModifierDown, isMouseQueueEmpty, waitForMouseEvent

isHidden

public bool isHidden();

Tell if this window is hidden or not.

See Also:

hide, show

isKeyboardQueueEmpty

public bool isKeyboardQueueEmpty();

Check whether there is input sitting in the Keyboard Queue.

See Also:

flushKeyboardQueue, getKeyboardEvent, waitForKeyboardEvent

isKeyDown

public bool isKeyDown( int key );

Tells whether the specified key is down. key can either be an ascii character, like 'a' or a NamedKey, like NamedKey::ESCAPE. isKeyDown will always return the same value for lowercase and uppercase version of the same letter. This is because there are ways to have a key be pressed in its lowercase form and then be raised in its uppercase form (e.g. press 'a', then press shift, then release 'a'). You can use isModifierDown to test if a modifier was pressed at the time that the character was.

Since:

2.1.2

See Also:

autoFlushKeyboardQueue, flushKeyboardQueue, getKeyboardEvent, ignoreKeyRepeat, isKeyboardQueueEmpty, isKeyDown, isModifierDown, waitForKeyboardEvent

isModifierDown

public bool isModifierDown( KeyModifiers km );

Tells whether the specified modifier was pressed during the last recorded mouse or keyboard event. This will be accurate if there is a lot of keyboard/mouse input going on, but will probably be innaccurate in other instances. It is recommended that if you need precision to use the eventqueues. This is an approximate way of getting whether a modifier is down.

Since:

2.1.2

See Also:

isButtonDown, isKeyDown

isMouseQueueEmpty

public bool isMouseQueueEmpty();

Check whether there is input sitting in the Mouse Queue.

See Also:

flushMouseQueue, getMouseEvent, waitForMouseEvent

isTimerQueueEmpty

public bool isTimerQueueEmpty();

Check whether there is input sitting in the Timer Queue.

See Also:

flushTimerQueue, getTimerEvent, waitForTimerEvent, registerNewTimerEvent

numberToString

public static std::string numberToString( int n );

Convert the given number to a string. Recommended for use with drawText.

Since:

2.1.4a

See Also:

drawText(constStyle&,constFont&,constint,constint,conststring&,constTransform&), drawText(constStyle&,constFont&,constint,constint,conststring&,constTransform&), int)

numberToString

public static std::string numberToString( double d, int precision =-1 );

Convert the given double number to a string. Recommended for use with drawText.

Parameters:

d - [in] number to convert to string

precision - [in, optional] number of digits of precision (numbers after decimal point)

Since:

2.1.4a

See Also:

drawText(constStyle&,constFont&,constint,constint,conststring&,constTransform&), drawText(constStyle&,constFont&,constint,constint,conststring&,constTransform&), numberToString(int)

readPixel

public Color readPixel( const int x, const int y );

Return the color at point (x, y)

registerNewTimerEvent

public TimerEvent registerNewTimerEvent( const int milliseconds );

Deprecated. This has unnecessary overhead. Use startTimer instead.

Register a timer event to occur after the specified number of milliseconds. Only causes the timer to go off once. If you want repeated occurrences, you must re-register when you recieve the event.

See Also:

getTimerCount, getTimerEvent, setTimerCount, startTimer, stopTimer

resize

public void resize( int newwidth, int newheight );

Changes the size of the window after creation.

Since:

2.1.5

See Also:

getPosition, setPosition, setTitle

setKeyboardFilter

public void setKeyboardFilter( const KeyboardEvent& filter );

Change the filter for the keyboard queue.

See Also:

getKeyboardFilter

setMouseFilter

public void setMouseFilter( const MouseEvent& filter );

Change the filter for the mouse queue.

See Also:

getMouseFilter

setPosition

public void setPosition( int x, int y );

Changes the position of the window after creation.

Since:

2.1.5

See Also:

getPosition, resize, setTitle

setTimerCount

public void setTimerCount( const TimerEvent& te, int count = 0 );

Changes the count for a timer. This is useful for resetting a timer's count once you've checked it.

Since:

2.1.2

See Also:

getTimerCount, getTimerEvent, registerNewTimerEvent

setTimerFilter

public void setTimerFilter( const TimerEvent& filter );

Change the filter for the timer queue.

See Also:

getTimerFilter

setTitle

public void setTitle( const std::string& title );

Changes the title of the window after creation.

Since:

2.1.5

See Also:

getPosition, setPosition, resize

show

public void show();

Show this window.

See Also:

hide, isHidden

startTimer

public TimerEvent startTimer( int milliseconds );

Register a timer event to occur every specified interval until you stop it using stopTimer.

Since:

2.1.5

See Also:

getTimerCount, getTimerEvent, isTimerQueueEmpty, setTimerCount, stopTimer

stopTimer

public void stopTimer( const TimerEvent& timer );

Stop a timer that was started with startTimer.

Since:

2.1.5

See Also:

getTimerCount, getTimerEvent, isTimerQueueEmpty, setTimerCount, startTimer

waitForKeyboardEvent

public KeyboardEvent waitForKeyboardEvent();

Wait for a keyboard event to occur and then return the event. If there are already events in the queue the function will return immediately.

See Also:

flushKeyboardQueue, getKeyboardEvent, ignoreKeyRepeat, isKeyboardQueueEmpty, isKeyDown

waitForMouseEvent

public MouseEvent waitForMouseEvent();

Wait for a mouse event to occur and then return the event. If there are already events in the queue the function will return immediately.

See Also:

flushMouseQueue, getMouseEvent, isButtonDown, isMouseQueueEmpty

waitForTimerEvent

public TimerEvent waitForTimerEvent();

Wait for a timer event to occur and then return the event. If there are already events in the queue the function will return immediately.

See Also:

flushTimerQueue, getTimerCount, getTimerEvent, registerNewTimerEvent, isTimerQueueEmpty