A portable application framework for GLOW

(Currently called GLOWaux, but intended to become part of GLOW.)

John Nagle (nagle@animats.com)
Animats
June, 2002

[Preliminary]

Figure 1 - a GLOWaux document window

GLOWaux provides a simple, portable application framework based on GLOW, GLUT, and OpenGL. Using GLOWaux, you can write portable applications that look and work much like common window-based applications. The usual menu bar and menus are provided. The graphical interface components are those of GLOW.

Window systems have traditionally used separate 2D and 3D drawing systems, because the 3D system was too slow to be used to draw 2D elements. OpenGL implementations are fast enough today that there's no longer any reason for this. Thus, we've developed an application framework that does all its drawing via OpenGL.

Figure 2 - a GLOWaux menu bar menu

Program behavior for GLOWaux applications is conventional. At startup, one document window opens. Additional document windows can be opened and closed. Document windows may have auxiliary windows for palettes and controls. The auxiliary windows are displayed only when the related document has the focus.

Classes

A GLOWaux application consists of a single instance of GlowApplication, subclassed by the user, and multiple instances of GlowDocument, again subclassed by the user. GLOWaux provides a document window with a menu bar, to which the user can add drop-down menus.GLOWaux itself does not implement any menu items.

GlowApplication

A singleton base class, representing the entire application. Should be subclassed.

Member functions:

*public:*
GlowApplication()	Constructor
virtual ~GlowApplication()	Destructor
virtual bool Quit()	Normal quit, closing all documents. May fail if user cancels a save.
*virtual void Init(const char startFile)**	Start, given a start file or null. Never returns. The main program calls this.
*virtual const char GetApplicationTitle() const;**	Override to change the title of the application. Default is "Glow Application".
*GlowDocument GetFocusDocument() const**	Returns the GlowDocument which currently has the focus. May return null.
*virtual void OnMouseEnter(GlowDocument doc)**
virtual void GetAllWindows(std::vector& winids)	Returns a vector of all the window IDs. Primarily for internal use.

GlowDocument

There is one GlowDocument object for each "document". Each GlowDocument has one main GLOW window, with a menu bar, and may have other, auxiliary windows. A subclass of GlowDocument must be provided which does whatever is appropriate for this application.

GlowDocument is a subclass of the following GLOW classes, all of which are public.

GlowWindow

GlowMenuReceiver

GlowIdleReceiver

GlowPushButtonReceiver

GlowSliderReceiver

GlowCheckBoxReceiver,

GlowPopupMenuReceiver

GlowTextFieldWindowReceiver

Member functions:

*public:*
GlowDocument(GlowApplication& app)	Constructor
virtual ~GlowDocument()	Destructor
*virtual void InitDocument(const char fileName)**	Initialize a new document. Usually overridden by subclass.
GlowApplication& GetApplication() const	Returns the application that owns thedocument
virtual bool Close_Document()	Called when a document is being closed.
virtual const std::string& GetFileName() const	Returns the file name of the document.
virtual bool NeedsSave() const	Returns true if the document needs to be saved.
virtual bool HasFileName() const	Returns true if the document has a nonempty file name.
virtual bool DocHasFocus()	Returns true if this document window is on top.

*protected, for use by subclasses:*
virtual void UpdateWindowTitle()	Updates the window title. Not usually called by subclasses.
virtual void SetNeedsSave(bool needsSave)	Set whether the file needs saving.
virtual void SetFileName(const std::string& name)	Sets the document's file name.
virtual void SetFileNameToDefault()	Sets the file name back to the application's default.
*virtual GlowQuickPaletteSubwindow GetMenuBar() const**	Returns the menu bar subwindow.
*virtual void AddMenuBarMenu(const char name, GlowMenu* menu)**	Add another menu to the menu bar.

*protected, and implemented by subclasses:*
virtual void HideAuxWindows()	Hide all this document's miscellaneous windows, if any.
virtual void ShowAuxWindows()	Show this document's miscellaneous windows, if any.
virtual void MenuBarInit()	Initialize the document's menu bar.
virtual bool OpenFile(const std::string& name)	Open and read a file.
*virtual const char GetDefaultFileName() const**	Get the default file name (such as "untitled.txt").
*virtual GlowSubwindow GetDocumentSubwindow()**	Get the content subwindow of the document. This is created by the subclass in its constructor. It appears below the menu bar. GlowDocument sizes and positions it.

*GLOW event handlers.* These behave as documented for GLOW, but apply to this document only.
virtual void OnEndPaint()	Refresh event. Subclass must implement.
virtual void OnReshape( int width, int height)	Reshape event. Subclass must implement.
virtual void OnMouseDown( Glow::MouseButton button, int x, int y, Glow::Modifiers modifiers)	Mouse down
virtual void OnMouseUp( Glow::MouseButton button, int x, int y, Glow::Modifiers modifiers)	Mouse up.
virtual void OnMouseDrag( int x, int y)	Mouse drag, in this window only.
virtual void OnMessage( const GlowIdleMessage& message)	Idle event.
virtual void OnMessage( const GlowMenuMessage& message)	Menu event.
virtual void OnMessage( const GlowPushButtonMessage& message)	Push button event.
virtual void OnMessage( const GlowSliderMessage& message)	Slider event.
virtual void OnMessage( const GlowCheckBoxMessage& message)	Check Box event.
virtual void OnMessage( const GlowPopupMenuMessage& message)	Popup menu event.
virtual void OnMessage( const GlowTextFieldWindowMessage& message)	Text field event.
virtual void OnMouseEnter()
virtual void OnMouseExit()

*Misc.*
virtual void OnDocumentEnter()	The document has just gained the focus.
virtual void OnDocumentExit()	The document has just lost the focus.If the document has computation-intensive animation, it probably should stop. The window should be dimmed.