`gevents.h`

This interface defines the event types used in the StanfordCPPLib graphics libraries. The structure of this package is adapted from the Java event model.

Classes
GEvent	This class is the root of the hierarchy for all events.
GWindowEvent	This event subclass represents a window event.
GActionEvent	This event subclass represents an action event.
GTimerEvent	This event subclass represents a timer event.
GMouseEvent	This event subclass represents a mouse event.
GKeyEvent	This event subclass represents a key event.
Types
EventClassType	This enumeration type defines the event classes.
WindowEventType	This enumeration type defines the event types for window events.
ActionEventType	This enumeration type defines the event types for action events.
TimerEventType	This enumeration type defines the event types for timer events.
MouseEventType	This enumeration type defines the event types for mouse events.
KeyEventType	This enumeration type defines the event types for keyboard events.
ModifierCodes	This enumeration type defines a set of constants used to check whether modifiers are in effect.
KeyCodes	This enumeration type defines the constants for the special keys on the keyboard.
Functions
startIntervalTimer(delay) startIntervalTimer(delay, count)	Starts an interval timer that fires a timer event repeatedly every `delay` milliseconds.
stopIntervalTimer()	Stops the interval timer.
postEvent(e)	Adds the event to the end of the event queue.
waitForEvent(e)	Dismisses the process until an event occurs.
waitForClick() waitForClick(mouseEvent)	Waits for a mouse click to occur anywhere in the window, discarding any other events.
getNextEvent(e)	Checks to see if there are any events waiting on the event queue.

Type detail

enum EventClassType {
   NULL_EVENT,         /* Indicates an uninitialized event              */
   WINDOW_EVENT,       /* Indicates a window-system event               */
   ACTION_EVENT,       /* Indicates an event with an associated action  */
   TIMER_EVENT,        /* Indicates an interval timer event             */
   MOUSE_EVENT,        /* Indicates a mouse event                       */
   KEY_EVENT           /* Indicates an event generated by the keyboard  */
};

This enumeration type defines the event classes.

enum WindowEventType {
   WINDOW_ACTIVATED,   /* Generated when the window gains focus         */
   WINDOW_CLOSED,      /* Generated when the window is finally closed   */
   WINDOW_CLOSING,     /* Generated when the user clicks the close box  */
   WINDOW_DEACTIVATED, /* Generated when the window loses focus         */
   WINDOW_DEICONIFIED, /* Generated when the window is expanded         */
   WINDOW_ICONIFIED,   /* Generated when the window is minimized        */
   WINDOW_OPENED       /* Generated when the window is opened           */
};

This enumeration type defines the event types for window events.

enum ActionEventType {
   ACTION_PERFORMED    /* Generated when a user action is performed     */
};

This enumeration type defines the event types for action events.

enum TimerEventType {
   TIMER_TICKED        /* Generated when the interval timer ticks       */
};

This enumeration type defines the event types for timer events.

enum MouseEventType {
   MOUSE_PRESSED,      /* Generated when the mouse button is pressed     */
   MOUSE_RELEASED,     /* Generated when the mouse button is released    */
   MOUSE_CLICKED,      /* Generated on clicks after PRESSED and RELEASED */
   MOUSE_MOVED,        /* Generated when the mouse is moved              */
   MOUSE_DRAGGED       /* Generated on mouse motion with the button down */
};

This enumeration type defines the event types for mouse events.

enum KeyEventType {
   KEY_PRESSED,        /* Generated when a key is pressed                */
   KEY_RELEASED,       /* Generated when a key is released               */
   KEY_TYPED           /* Generated after PRESSED and RELEASED on a key  */
};

This enumeration type defines the event types for keyboard events.

enum ModifierCodes {
   SHIFT_DOWN     = 1 << 0,
   CTRL_DOWN      = 1 << 1,
   META_DOWN      = 1 << 2,
   ALT_DOWN       = 1 << 3,
   ALT_GRAPH_DOWN = 1 << 4,
   BUTTON1_DOWN   = 1 << 5,
   BUTTON2_DOWN   = 1 << 6,
   BUTTON3_DOWN   = 1 << 7
};

This enumeration type defines a set of constants used to check whether modifiers are in effect.

enum KeyCodes {
   ESCAPE_KEY = 256,
   DELETE_KEY,
   TAB_KEY,
   RETURN_KEY,
   CLEAR_KEY,
   ENTER_KEY,
   UP_ARROW_KEY,
   DOWN_ARROW_KEY,
   LEFT_ARROW_KEY,
   RIGHT_ARROW_KEY,
   HELP_KEY,
   HOME_KEY,
   PAGE_UP_KEY,
   PAGE_DOWN_KEY,
   FORWARD_DEL_KEY,
   END_KEY,
   F1_KEY,
   F2_KEY,
   F3_KEY,
   F4_KEY,
   F5_KEY,
   F6_KEY,
   F7_KEY,
   F8_KEY,
   F9_KEY,
   F10_KEY,
   F11_KEY,
   F12_KEY,
   F13_KEY,
   F14_KEY,
   F15_KEY,
};

This enumeration type defines the constants for the special keys on the keyboard. These values begin after the char range.

Function detail

void startIntervalTimer(double delay);
void startIntervalTimer(double delay, int count);

Starts an interval timer that fires a timer event repeatedly every delay milliseconds. The count parameter, if specified, indicates the maximum number of events to fire; if this parameter is missing, the timer continues to fire until it is stopped.

Usage:

startIntervalTimer(delay);
startIntervalTimer(delay, count);

void stopIntervalTimer();

Stops the interval timer.

Usage:

stopIntervalTimer();

void postEvent(GEvent e);

Adds the event to the end of the event queue.

Usage:

postEvent(e);

void waitForEvent(GEvent & e);
void waitForEvent(GWindowEvent & e);
void waitForEvent(GActionEvent & e);
void waitForEvent(GTimerEvent & e);
void waitForEvent(GMouseEvent & e);
void waitForEvent(GKeyEvent & e);

Dismisses the process until an event occurs. When it does, the waitForEvent function returns with the details of the event. The parameter e can be either a general GEvent variable or one of the specific subclasses. In the former case, the function returns when any event occurs. Clients should use this approach if they need to respond to more than one class of event. As an example, the following code is the canonical event loop for an animated application that needs to respond to mouse, key, and timer events:

   startIntervalTimer(ANIMATION_DELAY_IN_MILLISECONDS);
   while (true) {
      GEvent e;
      waitForEvent(e);
      switch (e.getEventClass()) {
       case TIMER_EVENT:
         takeAnimationStep();
         break;
       case MOUSE_EVENT:
         handleMouseEvent(GMouseEvent(e));
         break;
       case KEY_EVENT:
         handleKeyEvent(GKeyEvent(e));
         break;
      }
   }

For applications that are interested only in mouse events, for example, this code can be simplified as follows:

   while (true) {
      GMouseEvent e;
      waitForEvent(e);
      handleMouseEvent(e);
   }

Usage:

waitForEvent(e);

void waitForClick();
void waitForClick(GMouseEvent & mouseEvent);

Waits for a mouse click to occur anywhere in the window, discarding any other events. If the client passes a GMouseEvent as a reference parameter, the function will fill in the details of the click event.

Usage:

waitForClick();
waitForClick(mouseEvent);

bool getNextEvent(GEvent & e);
bool getNextEvent(GWindowEvent & e);
bool getNextEvent(GActionEvent & e);
bool getNextEvent(GTimerEvent & e);
bool getNextEvent(GMouseEvent & e);
bool getNextEvent(GKeyEvent & e);

Checks to see if there are any events waiting on the event queue. If so, getNextEvent fills in the structure of the event with the first event in the queue and returns true. If there are no events, getNextEvent returns false. As with waitForEvent, the parameter e can be either a GEvent variable or one of the specific subclasses. Clients should use this form of the call if they need to support animation in the main thread, as in the following code example:

   while (true) {
      GEvent e;
      if (getNextEvent(e)) {
         switch (e.getEventClass()) {
          case MOUSE_EVENT:
            handleMouseEvent(GMouseEvent(e));
            break;
          case KEY_EVENT:
            handleKeyEvent(GKeyEvent(e));
            break;
         }
      } else {
         takeAnimationStep();
      }
   }

Usage:

if (getNextEvent(e)) . . .