psychWithJava
Class NormalWindow

java.lang.Object
  java.awt.Component
      java.awt.Container
          javax.swing.JComponent
              javax.swing.JPanel
                  psychWithJava.NormalWindow

All Implemented Interfaces:

java.awt.event.KeyListener, java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, java.util.EventListener, javax.accessibility.Accessible

public class NormalWindow
extends javax.swing.JPanel
implements java.awt.event.KeyListener

NormalWindow class provides methods to display visual stimuli and interact with the observer in a normal window environment.

Unlike FullScreen, NormalWindow doesn't operate in Full Screen Exclusive Mode. However the method signitures are identical to those in FullScreen class, which makes it simple to convert a FullScreen application into a normal window application. A normal window application has several benefits. One benefit is that once an experiment is converted into a normal window application it can easily be shared with collegues and placed on a web page.

Some methods of FullScreen class do not exist in NormalWindow. Those methods specific to Full Screen Exclusive Mode are: setNBuffers(), getNBuffers(), closeScreen(), isFullScreenSupported(), setDisplayMode(), isDisplayModeAvailable(), reportDisplayMode(), getDisplayMode(), isDisplayChangeSupported(), reportDisplayModes(), getDisplayModes(). Also there is no constructor in NormalWindow where one can specify the screenID.

On the other hand there are additional methods specific to NormalWindow class. Most notably setPassiveRendering() determines whether to use passive rendering or active rendering. By default a NormalWindow object uses passive rendering, whereas rendering in FullScreen is always active. In active rendering the programmer has the complete control of the graphics interface. In passive rendering the operating system and JVM (Java virtual machine) may intervene and redraw the client's window when necessary. This is useful in a normal window application because windows can be minimized and maximized back, or can get hidden and visible again. In passive rendering JVM updates the client's window automatically whenever necessary, for example when it gets visible again after being hidden behind other windows or minimized. This is useful in normal window but not a concern in Full Screen Mode. Other specific method is isPassiveRendering(), which reports whether or not the NormalWindow object uses passive rendering.

Whether passive or active rendering, NormalWindow always uses double buffering.

Converting a FullScreen experiment into NormalWindow application. NormalWindow inherits from JPanel of core Java library. A JPanel object has to be placed in a lower level container before displayed on screen. A suitable container is JFrame. The program can create a JFrame and then place the new NormalWindow object inside it. Also the invokation of FullScreen specific methods should be eliminated (setNBuffers() etc.). In the end FullScreen's closeScreen() method should be eliminated and the JFrame's dispose() method should be invoked. For example:

// HPWindow extends NormalWindow, instead of FullScreen
public class HPWindow extends NormalWindow implements Runnable {

  static JFrame mainFrame;
  static final int XO = 100;
  static final int YO = 100;
  static final int W = 612;
  static final int H = 612;

  public static void main(String[] args) {

    HPWindow nw = new HPWindow();

    // The only addition/change to FullScreen is here:
    mainFrame = new JFrame();
    mainFrame.setBounds(XO,YO,W,H);
    mainFrame.add(nw);
    mainFrame.setDefaultCloseOperation(JFrame.DISPOSE_ON_CLOSE);
    // Next two lines are optional 
    mainFrame.setResizable(false);
    mainFrame.setTitle("Hello Psychophysicist");
    // you must set it visible
    mainFrame.setVisible(true);
    // up to here
    // ...
  }

  public void run(){

    try {
      // methods are identical to those in FullScreen
      displayText("Hello Psychophysicist (Normal Window)");
      // ....
    } finally {
      // and replace this
      //fs.closeScreen();
      mainFrame.dispose();
    }
  }
}

Some demos using the NormalWindow class can be found here. See also the implementation in greater detail in Chapter 11: Applets, normal window applications, packaging and sharing your work in The Guide to psychophysics programming with Java.

Matlab and Mathematica development:
It is possible to create Java objects from within Matlab and Mathematica. You can, therefore, create a NormalWindow object (and a JFrame) in Matlab or Mathematica and invoke its methods. In other words, if you choose, you could use this class as a tool for psychophysics programming much like the well known Psychtoolbox package.
Instructions on Matlab and Mathematica development can be found here.

Author:

boyaci

See Also:

FullScreen, Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class javax.swing.JComponent

javax.swing.JComponent.AccessibleJComponent

Nested classes/interfaces inherited from class java.awt.Component

java.awt.Component.BaselineResizeBehavior

Field Summary

Fields inherited from class javax.swing.JComponent

TOOL_TIP_TEXT_KEY, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

NormalWindow()
Constructs a new NormalWindow object.

Method Summary

void	blankScreen() Blanks the whole window using the current background color.
void	displayImage(java.awt.image.BufferedImage bi) Displays a BufferedImage at the center of the window.
void	displayImage(int x, int y, java.awt.image.BufferedImage bi) Displays a BufferedImage at the specified position.
void	displayText(int x, int y, java.lang.String text) Displays text at the specified position.
void	displayText(java.lang.String text) Displays text at the center of the window.
void	flushKeyPressed() Clears both key pressed and when key pressed queues.
void	flushKeyReleased() Clears both key released and when key released queues.
void	flushKeyTyped() Clears both keyTyped and whenKeyTyped queues.
java.lang.Integer	getKeyPressed() Returns the key pressed by the observer.
java.lang.Integer	getKeyPressed(long ms) Returns the key pressed by the observer.
java.lang.Integer	getKeyReleased() Returns the key released by the observer.
java.lang.Integer	getKeyReleased(long ms) Returns the key released by the observer.
java.lang.String	getKeyTyped() Returns the key typed by the observer.
java.lang.String	getKeyTyped(long ms) Returns the key typed by the observer.
java.lang.Long	getWhenKeyPressed() Returns the time of the key pressed event.
java.lang.Long	getWhenKeyReleased() Returns the time of the key released event.
java.lang.Long	getWhenKeyTyped() Returns the time of the key typed event.
void	hideCursor() Renders the cursor invisible.
boolean	isPassiveRendering() Returns the current passive rendering value.
void	keyPressed(java.awt.event.KeyEvent ke)
void	keyReleased(java.awt.event.KeyEvent ke)
void	keyTyped(java.awt.event.KeyEvent ke)
void	setPassiveRendering(boolean pr) Sets passive rendering parameter.
void	showCursor() Renders the cursor visible using default cursor
void	updateScreen() Updates the entire window by bringing the back video buffer front.

Methods inherited from class javax.swing.JPanel

getAccessibleContext, getUI, getUIClassID, setUI, updateUI

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintImmediately, paintImmediately, print, printAll, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, contains, createImage, createImage, createVolatileImage, createVolatileImage, dispatchEvent, enable, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NormalWindow

public NormalWindow()

Constructs a new NormalWindow object.

Method Detail

keyTyped

public void keyTyped(java.awt.event.KeyEvent ke)

Specified by:

keyTyped in interface java.awt.event.KeyListener

keyReleased

public void keyReleased(java.awt.event.KeyEvent ke)

Specified by:

keyReleased in interface java.awt.event.KeyListener

keyPressed

public void keyPressed(java.awt.event.KeyEvent ke)

Specified by:

keyPressed in interface java.awt.event.KeyListener

setPassiveRendering

public void setPassiveRendering(boolean pr)

Sets passive rendering parameter. By default a NormalWindow object uses passive rendering, whereas rendering in FullScreen is always active. In active rendering the programmer has the complete control of the graphics interface. In passive rendering the operating system and JVM (Java virtual machine) may intervene and redraw the client's window when necessary. This is useful in a normal window application because windows can be minimized and maximized back, or can get hidden and visible again. In passive rendering JVM updates the client's window automatically whenever necessary, for example when it gets visible again after being hidden behind other windows or minimized. This is useful in normal window but not a concern in Full Screen Mode.

Parameters:

pr - new passive rendering value, true or false

isPassiveRendering

public boolean isPassiveRendering()

Returns the current passive rendering value. True if passive rendering is on, false if active rendering.

Returns:

current passive rendering value.

updateScreen

public void updateScreen()

Updates the entire window by bringing the back video buffer front. NormalWindow always uses double buffering. The methods displayImage(), displayText() or blankScreen() (see below) always manipulate the back (invisible) video bufer. Upon invoking those methods user has to invoke this updateScreen() method to actually bring the back buffer to front, in other words to make it actually visible on the screen device.

See Also:

displayImage(int, int, BufferedImage), displayText(int, int, String), blankScreen()

displayImage

public void displayImage(java.awt.image.BufferedImage bi)

Displays a BufferedImage at the center of the window. Note that this method draws the image on the back buffer. Therefore user has to invoke the updateScreen() method to actually display the image on the screen.

Parameters:

bi - BufferedImage to display

See Also:

displayImage(int, int, BufferedImage), updateScreen()

displayImage

public void displayImage(int x,
                         int y,
                         java.awt.image.BufferedImage bi)

Displays a BufferedImage at the specified position. Note that this method draws the image on the back buffer. Therefore user has to invoke the updateScreen() method to actually display the image on the screen.

Parameters:

x - horizontal offset of the upper left corner of the image from the upper left corner of the window

y - vertical offset of the upper left corner of the image from the upper left corner of the window

bi - BufferedImage to display

See Also:

displayImage(BufferedImage), updateScreen()

displayText

public void displayText(java.lang.String text)

Displays text at the center of the window. Note that this method draws the text on the back buffer. Therefore user has to invoke the updateScreen() method to actually display the text on the screen.

Parameters:

text - a text message to display

See Also:

displayText(int, int, String), updateScreen()

displayText

public void displayText(int x,
                        int y,
                        java.lang.String text)

Displays text at the specified position. Note that this method draws the text on the back buffer. Therefore user has to invoke the updateScreen() method to actually display the text on the screen.

Parameters:

x - horizontal offset of the upper left corner of the text from the upper left corner of the window

y - vertical offset of the upper left corner of the text from the upper left corner of the window

text - a text message to display

See Also:

displayText(String), updateScreen()

blankScreen

public void blankScreen()

Blanks the whole window using the current background color. Note that this method blanks the back buffer. Therefore user has to invoke the updateScreen() method to actually blank the screen.

See Also:

updateScreen()

hideCursor

public void hideCursor()

Renders the cursor invisible.

See Also:

showCursor()

showCursor

public void showCursor()

Renders the cursor visible using default cursor

See Also:

hideCursor()

getKeyTyped

public java.lang.String getKeyTyped(long ms)

Returns the key typed by the observer.

If the specified wait time is positive: This either (i) method returns the top element in the keyTyped queue immediately if there is at least one element in the keyTyped event queue or (ii) waits up to the specified amount of time for an element to become available. If no key is typed within the specified amount of time it returns null.

If the specified time is zero: Returns the top element in the keyTyped event queue or null if queue is empty.

If the specified wait time is negative: This method either returns the top element in the queue or if the queue is empty it waits indefinetely untill the observer types.

In all cases, the element returned is removed from the event queue.

General principles of event handling in FullScreen: FullScreen captures the key events in a seperate Thread and stores them in Thread safe BlockingQueue objects. Anytime observer types, presses or releases a key, that key and the time of the event are inserted to the end (tail) of the respective queues. When one of the getKeyTyped(), getKeyPressed() or getKeyReleased() methods is invoked, the top (head) of the respective queue is retrived and removed. Similarly, getWhenKeyTyped(), getWhenKeyPressed() and getWhenKeyReleased() methods retrive and remove the head in event time queues. flushKeyTyped(), flushKeyPressed() and flushKeyReleased() methods clear all queues, including the event time queues.

For more information see Chapter 6: Getting observer response of the Guide to Psychophysics programming with Java.

Parameters:

ms - time in milliseconds to wait for a response

Returns:

the key typed

See Also:

getKeyTyped(), flushKeyTyped(), getWhenKeyTyped()

getKeyTyped

public java.lang.String getKeyTyped()

Returns the key typed by the observer. Returns the top element in keyTyped queue or null if queue is empty. Equivelent to invoking getKeyTyped(0).

The element returned is removed from the event queue. See also general principles of event handling in FullScreen above.

For more information see Chapter 6: Getting observer response of the Guide to Psychophysics programming with Java.

Returns:

the key typed

See Also:

getKeyTyped(long), flushKeyTyped(), getWhenKeyTyped()

getWhenKeyTyped

public java.lang.Long getWhenKeyTyped()

Returns the time of the key typed event. Returns the top element in the whenKeyTyped queue, null if queue is empty.

The element returned is removed from the event queue. See also general principles of event handling in FullScreen above.

For more information see Chapter 6: Getting observer response of the Guide to Psychophysics programming with Java.

Returns:

the time of key typed event

See Also:

getKeyTyped(long), flushKeyTyped()

flushKeyTyped

public void flushKeyTyped()

Clears both keyTyped and whenKeyTyped queues. See also general principles of event handling in FullScreen above.

For more information see Chapter 6: Getting observer response of the Guide to Psychophysics programming with Java.

See Also:

getKeyTyped(long), getWhenKeyTyped()

getKeyPressed

public java.lang.Integer getKeyPressed(long ms)

Returns the key pressed by the observer.

If the specified wait time is positive: This method either (i) returns the top element in the keyPressed queue immediately if there is at least one element in the keyPressed event queue or (ii) waits up to the specified amount of time for an element to become available. If no key is pressed within the specified amount of time it returns null.

If the specified time is zero: Returns the top element in the keyPressed event queue or null if queue is empty.

If the specified wait time is negative: This method either returns the top element in the queue or if the queue is empty it waits indefinetely untill the observer presses a key.

In all cases, the element returned is removed from the event queue. See also general principles of event handling in FullScreen above.

For more information see Chapter 6: Getting observer response of the Guide to Psychophysics programming with Java.

Parameters:

ms - time in milliseconds to wait for a response

Returns:

numeric code of the key pressed

See Also:

getKeyPressed(), flushKeyPressed(), getWhenKeyPressed()

getKeyPressed

public java.lang.Integer getKeyPressed()

Returns the key pressed by the observer. Returns the top element in keyPressed queue or null if queue is empty. Equivelent to invoking getKeyPressed(0).

The element returned is removed from the event queue. See also general principles of event handling in FullScreen above.

For more information see Chapter 6: Getting observer response of the Guide to Psychophysics programming with Java.

Returns:

numeric code of the key pressed

See Also:

getKeyPressed(long), flushKeyPressed(), getWhenKeyPressed()

getWhenKeyPressed

public java.lang.Long getWhenKeyPressed()

Returns the time of the key pressed event. Returns the top element in the whenKeyPressed queue, null if queue is empty.

The element returned is removed from the event queue. See also general principles of event handling in FullScreen above.

For more information see Chapter 6: Getting observer response of the Guide to Psychophysics programming with Java.

Returns:

the time of key pressed event

See Also:

getKeyPressed(long), flushKeyPressed()

flushKeyPressed

public void flushKeyPressed()

Clears both key pressed and when key pressed queues. See also general principles of event handling in FullScreen above.

For more information see Chapter 6: Getting observer response of the Guide to Psychophysics programming with Java.

See Also:

getKeyPressed(long), getWhenKeyPressed()

getKeyReleased

public java.lang.Integer getKeyReleased(long ms)

Returns the key released by the observer.

If the specified wait time is positive: This method either (i) returns the top element in the keyReleased queue immediately if there is at least one element in the keyReleased event queue or (ii) waits up to the specified amount of time for an element to become available. If no key is released within the specified amount of time it returns null.

If the specified time is zero: Returns the top element in the keyReleased event queue or null if queue is empty.

If the specified wait time is negative: This method either returns the top element in the queue or if the queue is empty it waits indefinetely untill the observer releases a key.

In all cases, the element returned is removed from the event queue. See also general principles of event handling in FullScreen above.

For more information see Chapter 6: Getting observer response of the Guide to Psychophysics programming with Java.

Parameters:

ms - time in milliseconds to wait for a response

Returns:

numerical code of the key released

See Also:

getKeyReleased(), flushKeyReleased(), getWhenKeyReleased()

getKeyReleased

public java.lang.Integer getKeyReleased()

Returns the key released by the observer. Returns the top element in keyReleased queue or null if queue is empty. Equivelent to invoking getKeyReleased(0).

The element returned is removed from the event queue. See also general principles of event handling in FullScreen above.

For more information see Chapter 6: Getting observer response of the Guide to Psychophysics programming with Java.

Returns:

numerical code of the key released

See Also:

getKeyReleased(long), flushKeyReleased(), getWhenKeyReleased()

getWhenKeyReleased

public java.lang.Long getWhenKeyReleased()

Returns the time of the key released event. Returns the top element in the whenKeyReleased queue, null if queue is empty.

The element returned is removed from the event queue. See also general principles of event handling in FullScreen above.

For more information see Chapter 6: Getting observer response of the Guide to Psychophysics programming with Java.

Returns:

the time of key released event

See Also:

getKeyReleased(long), flushKeyReleased()

flushKeyReleased

public void flushKeyReleased()

Clears both key released and when key released queues. See also general principles of event handling in FullScreen above.

For more information see Chapter 6: Getting observer response of the Guide to Psychophysics programming with Java.

See Also:

getKeyReleased(long), getWhenKeyReleased()