Main Page | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Class Members | File Members

nglWindow Class Reference

#include <nglWindow.h>

Inheritance diagram for nglWindow:

nglContext nglError List of all members.

Detailed Description

OpenGL viewport and rendering management.

A nglWindow gives you an OpenGL context for your GL work and a rendering window for this context. You must instantiate a nglWindow before calling any OpenGL functions. Since you can create any number of windows in an application, you must specify the context of your OpenGL code : even if you have only one window, enclose the OpenGL calls between BeginSession() and EndSession() calls.

The EndSession() method implicitly finishes the rendering (calling glFinish()) and triggers a buffer swap if the window is multi-buffered. If you render to multiple windows in parallel, it is legal to make successive calls to BeginSession() without calling the corresponding EndSession(). In other words, you can interleave BeginSession() and EndSession() calls at will.

Creating a window requires two pieces of information : OpenGL context info and general window properties (geometry and behaviour). The first info is given by the nglContextInfo object, while the second one is simply contained in a nglWindowInfo object.

Choosing an OpenGL context is not necessarily an easy task, and mainly not a very portable job. Keep in mind that the features you ask and get on your configuration might not (and won't) be available on every user's graphics card and OpenGL driver combination. Please have a closer look at the nglContextInfo documentation for this purpose.

Filling the nglWindowInfo is pretty simple. Note that you can change most of the properties later with various methods (excepted the Pos initial position hint, which only makes sense at construction time).

When you just created a new nglWindow instance, you should do in this order :

To effectively destroy the window and release the OpenGL context, simply delete the object.


Public Types

typedef uint Flags
typedef uint EventMask
enum  StateChange {
  eHide,
  eShow,
  eMinimize
}
enum  StateInfo {
  eHidden,
  eVisible
}
enum  CursorModel {
  eCursorNone,
  eCursorArrow,
  eCursorCross,
  eCursorHand,
  eCursorHelp,
  eCursorWait,
  eCursorCaret,
  eCursorDnD,
  eCursorForbid,
  eCursorMove,
  eCursorResize,
  eCursorResizeNS,
  eCursorResizeWE,
  eCursorResizeN,
  eCursorResizeS,
  eCursorResizeW,
  eCursorResizeE,
  eCursorResizeNW,
  eCursorResizeNE,
  eCursorResizeSW,
  eCursorResizeSE
}

Public Member Functions

Life cycle
 nglWindow (uint Width, uint Height, bool IsFullScreen=false)
 nglWindow (const nglContextInfo &rContext, const nglWindowInfo &rInfo, const nglContext *pShared=NULL)
virtual ~nglWindow ()
Geometry
uint GetWidth () const
uint GetHeight () const
void GetSize (uint &rWidth, uint &rHeight) const
bool SetSize (uint Width, uint Height)
void GetPosition (int &rXPos, int &rYPos) const
bool SetPosition (int XPos, int YPos)
bool GetResolution (float &rHorizontal, float &rVertical)
Appearance
StateInfo GetState () const
void SetState (StateChange State)
nglString GetTitle () const
void SetTitle (const nglString &rTitle)
CursorModel GetCursor () const
bool SetCursor (CursorModel Cursor)
Events control
EventMask GetEventMask () const
void SetEventMask (EventMask Events)
Extension
const OSInfo * GetOSInfo () const
Mouse
nglMouseInfo::Mode GetMouseMode () const
void SetMouseMode (nglMouseInfo::Mode Mode)
void GetMouse (nglMouseInfo &rInfo, bool Local=true) const
Keyboard
bool GetKeyRepeat () const
void SetKeyRepeat (bool AllowRepeat=true)
bool IsKeyDown (nglKeyCode Key) const
Rendering
virtual void BeginSession ()
virtual void EndSession ()
void Invalidate ()
User callbacks
virtual void OnCreation ()
virtual void OnDestruction ()
virtual void OnActivation ()
virtual void OnDesactivation ()
virtual void OnClose ()
virtual void OnPaint ()
virtual void OnState (StateInfo State)
virtual void OnResize (uint Width, uint Height)
virtual void OnKeyDown (nglKeyCode Key, nglChar Char)
virtual void OnKeyUp (nglKeyCode Key, nglChar Char)
virtual void OnMouseClick (nglMouseInfo &rInfo)
virtual void OnMouseUnclick (nglMouseInfo &rInfo)
virtual void OnMouseMove (nglMouseInfo &rInfo)

Static Public Member Functions

static void ParseArgs (nglContextInfo &rContext, nglWindowInfo &rInfo)
static const nglChar * GetKeyName (nglKeyCode Key)

Static Public Attributes

static const Flags NoFlag
static const Flags NoResize
static const Flags NoBorder
static const Flags FullScreen
static const EventMask NoEvents
static const EventMask MouseEvents
static const EventMask KeyEvents
static const EventMask AllEvents

Protected Member Functions

virtual const nglChar * OnError (uint &rError) const

Classes

class  OSInfo
 < OS-specific properties More...

Member Typedef Documentation

typedef uint nglWindow::EventMask
 

Controls the reception of keyboard and mouse events, see SetEventMask().

typedef uint nglWindow::Flags
 

Used during nglWindow construction, see nglWindowInfo.

Member Enumeration Documentation

enum nglWindow::CursorModel
 

< See SetCursor() and GetCursor()

Enumeration values:
eCursorNone  No cursor.
eCursorArrow  Standard arrow.
eCursorCross  Crosshair.
eCursorHand  Hand.
eCursorHelp  Question mark with an arrow.
eCursorWait  Hourglass or watch (might be with an arrow).
eCursorCaret  Text caret.
eCursorDnD  Drag'n'drop symbol.
eCursorForbid  DnD forbidden (slashed circle).
eCursorMove  Four way arrow (horizontal and vertical).
eCursorResize  Resize symbol.
eCursorResizeNS  Double arrow pointing North & South.
eCursorResizeWE  Double arrow pointing West & East.
eCursorResizeN  Resize from North.
eCursorResizeS  Resize from South.
eCursorResizeW  Resize from West.
eCursorResizeE  Resize from East.
eCursorResizeNW  Resize from North West corner.
eCursorResizeNE  Resize from North East corner.
eCursorResizeSW  Resize from South West corner.
eCursorResizeSE  Resize from South East corner.

enum nglWindow::StateChange
 

< See SetState()

Enumeration values:
eHide  Withdraw the window, including its icon on the desktop or in the taskbar.
eShow  Display a hidden or minize window.
eMinimize  Minimize a hidden or displayed window.

enum nglWindow::StateInfo
 

< See GetState()

Enumeration values:
eHidden  The window is not visible (might be minimized or withdrawn).
eVisible  The window is displayed on the screen.

Constructor & Destructor Documentation

nglWindow::nglWindow (  uint  Width,
uint  Height,
bool  IsFullScreen = false
) 
 

Simple constructor for the lazy ones.

Parameters:
Width window width
Height window height
IsFullScreen if true, tries to go fullscreen using width*height as resolution
This is equivalent to the following code :

nglWindow*     window;
nglContextInfo context; // Fetch default context
nglWindowInfo  info;

info.Width  = Width;
info.Height = Height;
info.Flags  = IsFullScreen ? FullScreen : NoFlag;

window = new nglWindow (context, info, NULL);

See nglContextInfo and nglWindowInfo for default settings.

Important : do not put your window init code in your inherited class constructor, use the OnCreation() callback for this purpose. The reason being that the system objects might not be ready for use from the constructor.

nglWindow::nglWindow (  const nglContextInfo &  rContext,
const nglWindowInfo &  rInfo,
const nglContext *  pShared = NULL
) 
 

Full constructor for the mighty ones.

Parameters:
rContext OpenGL context info, see nglContextInfo
rInfo Window options, see nglWindowInfo
pShared Share the OpenGL context with *pShared's one.
if pShared is non null, the newly created context will be shared with *pShared's one. Both windows will have distinct contexts working in parallel, but will share display lists and texture names.

virtual nglWindow::~nglWindow (   )  [virtual]
 

Immediatly destroy the window and release the OpenGL context.

Important : you should put your window destroy code in the OnDestruction() callback rather than in the destructor. This callback will be called event if a delete is issued on the nglWindow object.

Member Function Documentation

virtual void nglWindow::BeginSession (   )  [virtual]
 

Set the window OpenGL context as the current context. All further OpenGL calls will refer to this window context.

Implements nglContext.

virtual void nglWindow::EndSession (   )  [virtual]
 

Finish the rendering on the current OpenGL context (implicitly calls glFinish()) and swap frame buffers if appropriate).

Implements nglContext.

CursorModel nglWindow::GetCursor (   )  const
 

Returns:
the current mouse cursor model

EventMask nglWindow::GetEventMask (   )  const
 

Returns:
the current event mask

uint nglWindow::GetHeight (   )  const
 

Return the current (user area) height.

static const nglChar* nglWindow::GetKeyName (  nglKeyCode  Key  )  [static]
 

Retrieve the human readable name of a physical key

Parameters:
Key key code
Returns:
key name
See nglKeyboard.h and the nglKeyboard layouts description.

bool nglWindow::GetKeyRepeat (   )  const
 

Returns:
true if auto key-repeat is active

void nglWindow::GetMouse (  nglMouseInfo &  rInfo,
bool  Local = true
)  const
 

Get the current mouse position and button state.

Parameters:
rInfo mouse information holder
Local if true, returns coordinate relative to the top left corner of the window client area; If false, returns the mouse coordinates relative to the top left corner of the screen
If the mouse mode is eMouseRelative, the coordinates will always be both zero (only the OnMouseMove() callback can provide relative coordinates); the rInfo.Flags state is updated in any case.

Any number of button flags can be set in the rInfo.Buttons bit mask, except ButtonDoubleClick which does not make sense in this context.

nglMouseInfo::Mode nglWindow::GetMouseMode (   )  const
 

Returns:
mouse mode

const OSInfo* nglWindow::GetOSInfo (   )  const
 

Returns:
OS-specific informations (eg. for embedding purposes).

void nglWindow::GetPosition (  int &  rXPos,
int &  rYPos
)  const
 

Get the window (user area) position in screen coordinate space.

Parameters:
rXPos position abscissa
rYPos position ordinate

bool nglWindow::GetResolution (  float &  rHorizontal,
float &  rVertical
) 
 

Retrieve screen resolution in DPI (dots per inch).

Parameters:
rHorizontal horizontal resolution in DPI
rVertical vertical resolution in DPI
Returns:
true if rHorizontal and rVertical contain valid information

void nglWindow::GetSize (  uint &  rWidth,
uint &  rHeight
)  const
 

Get the window (user area) size.

Parameters:
rWidth current width
rHeight current height

StateInfo nglWindow::GetState (   )  const
 

Returns:
the current window display status

nglString nglWindow::GetTitle (   )  const
 

Returns:
the window current title.

uint nglWindow::GetWidth (   )  const
 

Return the current (user area) width.

void nglWindow::Invalidate (   ) 
 

Append a paint event to the event queue. It means the OnPaint() callback will be called as soon as possible when you give the control back to the main loop.

Only one paint event can be queued. Hence you can call Invalidate() many times before returning from an event handler, it will only trigger one paint event.

bool nglWindow::IsKeyDown (  nglKeyCode  Key  )  const
 

Test a physical key state.

Parameters:
Key key code
Returns:
key status, true if currently pressed
See the nglKeyboard layouts description for physical key names.

The key code cannot be converted to a printable character, since it would require the key context (wether a modifier like Alt, Ctl or Apple was hold, or a more complex composing method such as used on asiatic layouts). Use the OnKeyDown() callback if you want to interpret key strokes for text composing purposes.

When a window looses its focus (see OnDesactivation()), all key states are reset (the keys are virtually released at once).

virtual void nglWindow::OnActivation (   )  [virtual]
 

This method is called when the window gets the focus, meaning it can receive keyboard and mouse events.

virtual void nglWindow::OnClose (   )  [virtual]
 

This method is called when the user wants to close a displayed or iconified window.

The window will not be automatically destroyed, it is up to you to decide its fate. It is legal to call delete this, but don't forget to signal the holders of a pointer to this object that it is no longer available.

virtual void nglWindow::OnCreation (   )  [virtual]
 

This method is called when the window object creation succeeded. You should put your init code here, and not in the constructor.

virtual void nglWindow::OnDesactivation (   )  [virtual]
 

This method is called when the window looses the focus, meaning it won't receive further keyboard and mouse events.

virtual void nglWindow::OnDestruction (   )  [virtual]
 

This method is called when the window object is destroyed. You should put your destroy code here, and not in the destructor.

virtual const nglChar* nglWindow::OnError (  uint &  rError  )  const [protected, virtual]
 

Parameters:
rError error code
Returns:
error message, or NULL if rError is out of bounds
When the user invokes GetErrorStr() on an object, the OnError() callback is called with the given error code and should return the corresponding message. When several classes have different string error tables in the same hierarchy, the latest derivation's OnError() is called : it should then use a parent-first search. Example :

const nglChar** ChildErrorTable = {_T("no error"), _T("Bad luck"), NULL};

const nglChar* Child::OnError (uint& rError) const
{
  return FetchError(ChildErrorTable, Parent::OnError(rError), rError);
}

Reimplemented from nglContext.

virtual void nglWindow::OnKeyDown (  nglKeyCode  Key,
nglChar  Char
)  [virtual]
 

This method is called when a key is pressed.

Parameters:
Key key code
Char character value, zero if none
The key code refers to a language and layout independent code. This is useful to specify keys that are located physically on a known place on the keyboard. See nglKeyboard layout>keyboard layouts.

virtual void nglWindow::OnKeyUp (  nglKeyCode  Key,
nglChar  Char
)  [virtual]
 

This method is called when a key is released.

Parameters:
Key key code
Char character value, zero if none
See OnKeyDown() documentation.

virtual void nglWindow::OnMouseClick (  nglMouseInfo &  rInfo  )  [virtual]
 

This method is called as soon as a mouse button is pressed.

Parameters:
rInfo mouse status
See GetMouse() for X and Y values exact interpretation.

ButtonDoubleClick and ButtonTripleClick bits might be set in aButton, together with the hit button flag.

virtual void nglWindow::OnMouseMove (  nglMouseInfo &  rInfo  )  [virtual]
 

This method is called when a mouse motion is detected.

Parameters:
rInfo mouse status
The X and Y values are displacement measures when the eRelative flag is set, or window relative coordinates otherwise (the top left corner of the window is at 0, 0). You can get the current mouse buttons state with the GetMouse() method.

This event is only triggered if the window has the focus (ie. has received a OnActivation() event).

virtual void nglWindow::OnMouseUnclick (  nglMouseInfo &  rInfo  )  [virtual]
 

This method is called when a mouse button is released.

Parameters:
rInfo mouse status
See GetMouse() for X and Y values exact interpretation.

ButtonDoubleClick and ButtonTripleClick bits cannot be set in Buttons.

virtual void nglWindow::OnPaint (   )  [virtual]
 

At least a part of the window must be redrawn. The window might have been explicitely invalidated by the programmer (see Invalidate()).

virtual void nglWindow::OnResize (  uint  Width,
uint  Height
)  [virtual]
 

This method is called when the user resizes the window.

Parameters:
Width new width
Height new height
This method is only called if the NoResize flag is set or the programmer explicitely called SetSize().

virtual void nglWindow::OnState (  StateInfo  State  )  [virtual]
 

This method is called when the window display state changes.

Parameters:
State new display state
State can be either eHidden (the window has been withdrawn or iconified) or eVisible (the window has been unhidden or un-iconified).

static void nglWindow::ParseArgs (  nglContextInfo &  rContext,
nglWindowInfo &  rInfo
)  [static]
 

Command line options parser

Parameters:
rContext is updated with a proper nglContext description
rInfo is updated with a proper nglWindow description
This method will parse some predefined arguments from the command line, and automatically fill in sensible values for a context and a window description. These options will be supported by your application :

  • --geometry [width]x[height] : set window (or fullscreen) resolution

  • --fullscreen : go fullscreen. Use current desktop resolution if --size is not present

bool nglWindow::SetCursor (  CursorModel  Cursor  ) 
 

Sets the window current cursor

Parameters:
Cursor new cursor
Returns:
true if the cursor was succesfully changed

void nglWindow::SetEventMask (  EventMask  Events  ) 
 

Sets a new event mask

Parameters:
Events event mask (combination of EventMask constants)

void nglWindow::SetKeyRepeat (  bool  AllowRepeat = true  ) 
 

Sets key repeat mode

Parameters:
AllowRepeat if false, disable auto key repeat for this window

void nglWindow::SetMouseMode (  nglMouseInfo::Mode  Mode  ) 
 

Sets current mouse mode

Parameters:
Mode new mouse mode

bool nglWindow::SetPosition (  int  XPos,
int  YPos
) 
 

Set the window (user area's top left corner) position in screen coordinate space.

Parameters:
XPos position abscissa
YPos position ordinate
Returns:
true if the window position was updated

bool nglWindow::SetSize (  uint  Width,
uint  Height
) 
 

Sets the window user area size.

Parameters:
Width new width
Height new height
Returns:
true if the window was resized
In window'ed mode, Width and Height are always clamped with a minimum value of 1. If the window has been succesfuly resized, returns true.

In fullscreen mode, this method is ignored.

void nglWindow::SetState (  StateChange  State  ) 
 

Change the window display state.

Parameters:
State new state
All state transitions are supported. For instance, since a window is initially created in the eHidden mode, it is possible to show it directly in minimized mode : simply ask the eMinimize mode.

If the window is 'fullscreen', minimizing or withdrawing the window will restore the default desktop resolution, while showing it will switch back to the right video mode and restore the fullscreen mode.

void nglWindow::SetTitle (  const nglString &  rTitle  ) 
 

Sets the window current title.

Parameters:
rTitle new title
It is legal to pass an empty string (""), the window will have no title.

Member Data Documentation

const EventMask nglWindow::AllEvents [static]
 

Enable all events

const Flags nglWindow::FullScreen [static]
 

This window is full screen (a video mode switch occurs if necessary)

const EventMask nglWindow::KeyEvents [static]
 

Enable key events : OnKeyUp() and OnKeyDown() callbacks are controlled by this flag.

const EventMask nglWindow::MouseEvents [static]
 

Enable mouse events : OnMouseClick(), OnMouseUnclick() and OnMouseMove() callbacks are controlled by this flag.

const Flags nglWindow::NoBorder [static]
 

The window will have no decorations at all; often used for so called 'splash screens'. This type of window is implicitly not user-resizable however the NoResize flag can stay (independently) unset.

const EventMask nglWindow::NoEvents [static]
 

Disable all events

const Flags nglWindow::NoFlag [static]
 

Use defaults (all flags unset)

const Flags nglWindow::NoResize [static]
 

The window manager will prevent the user from resizing the window, however the programmer can still use nglWindow::SetSize with success.

Generated on Thu Feb 3 22:26:10 2005 for NGL by  doxygen 1.4.1