Syllable higlevel API: os::Window Class Reference

Window::Window	(	const Rect &	cFrame,
		const String &	cName,
		const String &	cTitle,
		uint32	nFlags = `0`,
		uint32	nDesktopMask = `CURRENT_DESKTOP`
	)

Description:: The window contructor initialize the local object, and initiate the windows connection to the appserver. The window is invisible and locked when the contructor returns. The first call to Show() will unlock the widow, start the looper thread and make it visible. If you want the windows looper to start handling messages before the window is made visible, you can call Start(). This will unlock the window, and start the looper thread without making the window visible. Simply calling Run()/Unlock() will not work, since the internal state of the Window will not be updated.

Parameters:

cFrame

- The size and position of the window.

See also:: Show(), Start(), Looper::Lock(), Looper::Unlock()

Author:: Kurt Skauen ([email protected])

Window::~Window ( )

Description:: The window destructor will delete all View's still atached to it, and shut down the connection to the appserver.

See also:: Window::Window()

Author:: Kurt Skauen ([email protected])

Member Function Documentation

void Window::FrameMoved ( const Point & cDelta ) [virtual]

void Window::FrameSized ( const Point & cDelta ) [virtual]

Reimplemented in os::FileRequester.

void Window::ScreenModeChanged	(	const IPoint &	cNewRes,
		color_space	eColorSpace
	)			`[virtual]`

Description:: ScreenModeChanged( const IPoint & cNewRes, color_space eColorSpace ) will be called when the screenmode changes. This will also happen during a desktop change to the desktop displaying the window if both desktops use different screenmodes.

Parameters:

	cNewRes	- New resolution.
	eColorSpace	- New colorspace.

Author:: Kurt Skauen ([email protected])

void Window::DesktopActivated	(	int	nDesktop,
		bool	bActive
	)			`[virtual]`

Description:: DesktopActivated( int nDesktop, bool bActive ) will be called when the desktop displaying the window will be activated or deactivated.

Parameters:

	nDesktop	- Now activated desktop if bActive is true. Otherwise the old desktop.
	bActive	- True if the desktop is activated.

Author:: Kurt Skauen ([email protected])

void Window::DesktopsChanged	(	uint32	nOldDesktops,
		uint32	nNewDesktops
	)			`[virtual]`

void Window::WindowsChanged ( ) [virtual]

Description:: THIS METHOD WILL BE REMOVED IN ONE OF THE FUTURE SYLLABLE RELEASES. USE THE NEW EVENT INTERFACE INSTEAD.

Note:: This will only work if you have set the WND_SEND_WINDOWS_CHANGED flag.

Author:: Kurt Skauen ([email protected])

void Window::SetFlags ( uint32 nFlags )

uint32 Window::GetFlags ( ) const

void Window::SetSizeLimits	(	const Point &	cMinSize,
		const Point &	cMaxSize
	)

Description:: SetSizeLimits() sets the maximum and minimum size the window can be resized to by the user. The limits are not enforced by ResizeBy(), ResizeTo(), and SetFrame()

Note:: If you want to prevent the user from resizing the window at all it is normally better to set the WND_NOT_RESIZABLE flag in the constructor or with the SetFlags() member than to set the same size as minimum and maximum. Setting the WND_NOT_RESIZABLE flag will cause visual changes to notify the user that the window can not be resized.

Also think twice before making a window non-resizable it is normally better to make the window layout dynamic through the builtin layout engine.

Parameters:

	cMinSize	Minimum size in pixels.
	cMaxSize	Maximum size in pixels.

See also:: SetFlags()

Author:: Kurt Skauen ([email protected])

void Window::SetAlignment	(	const IPoint &	cSize = `IPoint(1, 1)`,
		const IPoint &	cSizeOffset = `IPoint(0, 0)`,
		const IPoint &	cPos = `IPoint(1, 1)`,
		const IPoint &	cPosOffset = `IPoint(0, 0)`
	)

void Window::AddChild	(	View *	pcChild,
		bool	bAssignTabOrder = `false`
	)

Description:: AddChild() add a view to the windows top-view. The view's View::AttachedToWindow() and View::AllAttached() will be called to let the view know about it's new status.

If bAssignTabOrder is true, the view will be assigned a tab order making it possible to activate the view with the keyboard.

Note:: The window share the tab-order counter with the View class.

When the window is later closed, it will automatically delete all remaining child views.

Parameters:

	pcChild	- The View to add to the window.
	bAssignTabOrder	- If true the view will be assigned a tab-order one higher than the previously added view.

Returns:

See also:: RemoveChild(), View::AddChild(), View::AttachedToWindow(), View::SetTabOrder()

Author:: Kurt Skauen ([email protected])

void Window::RemoveChild ( View * pcChild )

Description:: Unlink the view from the windows top-view and call the view's View::DetachedFromWindow() and View::AllDetached()

Parameters:

pcChild

- The view to remove.

See also:: AddChild(), View::RemoveChild()

Author:: Kurt Skauen ([email protected])

void Window::MakeFocus ( bool bFocus = true )

Description:: If bFocus is true the window will gain focus, and start receiving input events generated by the mouse and keyboard. If bFocus is false the window will lose focus to the window that previously had it.

Note:: The appserver keeps a small stack of previously active windows. When a window give up focus volunterly it will then pop one window off the stack and if the stack was not empty that window will receive focus.

Parameters:

bFocus

- True to activate the window, false to deactivate it.

See also:: View::MakeFocus(), SetFocusChild()

Author:: Kurt Skauen ([email protected])

void os::Window::Close ( ) [inline]

void Window::Show ( bool bMakeVisible = true )

Description:

When a window is first constructed, it is not made visible on the screen. You must first call Show(true), The first time Show() is called it will also unlock the window, and start the looper thread if it is not done already by calling Start().

You can nest calls to Show(false). It will then require the same numbers of Show(true) calls to make the window visible.

Note:: The Window visibility state is global across all desktops.

Parameters:

bMakeVisible

- Set to true to make the window visible, and false to hide it.

See also:: Start(), Window::Window()

Author:: Kurt Skauen ([email protected])

Reimplemented in os::FileRequester.

void os::Window::Hide ( ) [inline]

bool Window::IsVisible ( ) const

void Window::Start ( void )

Description:: If you whould like to unlock the window and start the looper thread without making the window visible, you can call Start() instead of Show(). This will invert the locking done by the contructor and make the looper run. It will also prevent Show() from doing the same when it is called later to make the window visible.

See also:: Show(), Window::Window()

Author:: Kurt Skauen ([email protected])

void Window::SetTitle ( const String & cTitle )

Description:: SetTitle() will change the title rendered in the window border.

Parameters:

pzTitle

The new window title.

See also:: GetTitle()

Author:: Kurt Skauen ([email protected])

String Window::GetTitle ( void ) const

Returns:: A const pointer to the internal window title.

See also:: SetTitle()

Author:: Kurt Skauen ([email protected])

void Window::SetIcon ( Bitmap * pcIcon )

Description:: SetIcon() will change the icon assigned to the window.

Note:: The Bitmap will be copied, so you can delete the bitmap afterwards,

Parameters:

pcIcon

The new window icon.

See also:: GetIcon(), SetTitle()

Author:: Arno Klenke ([email protected])

Bitmap * Window::GetIcon ( void ) const

Returns:: Not longer supported.

See also:: SetIcon(), GetTitle()

Author:: Arno Klenke ([email protected])

void Window::Flush ( void )

Description:: When a view is rendering graphics, the render commands is buffered in the window, and sendt to the appserver in batches to reduce the overhead of message passing. When the View::Paint() member is called by the system, the render queue will be automatically flushed when View::Paint() returnes. If the view however desides to render anything between paint messages, the render queue must be flushed manually to execute the rendering.

Note:: Flush() do not guarantee that the pixels are indead on-screen when it returns, it only guarantee that the rendering will take place as soon as possible. If you want to make sure all the pixels is rendered, you must use Sync() instead.

See also:: Sync(), Bitmap::Sync(), Bitmap::Flush(), View::Flush(), View::Sync()

Author:: Kurt Skauen ([email protected])

void Window::Sync ( void )

Description:: Sync() will like the Flush() member flush the render queue. The difference is that Sync() will wait for the appserver to finnish the rendering and send a reply informing that the rendering is done. This means that when Sync() returnes you have a guarante that all the previously issued rendering operations are indead executed.

Note:: Sync() is normally not used on normal windows, since it have a higher overhead than Flush(), and you normally dont need to wait for the appserver to finnish. It is only useful when the window is attached to a bitmap, and you want to assure that the rendering indead have taken place before you start using the bitmap.

See also:: Flush(), Bitmap::Sync(), Bitmap::Flush(), View::Sync(), View::Flush()

Author:: Kurt Skauen ([email protected])

View* os::Window::FindView ( const String & cName ) const [inline]

View * Window::FindView ( const Point & cPos ) const

Description:: FindView( const Point& cPos ) will do a reqursive search through all attached view's to find the topmost view covering the given point. If no view is intersecting the point NULL is returned.

Returns:: Pointer to the View, or NULL.

See also:: FindView( const char* pzName )

Author:: Kurt Skauen ([email protected])

View* os::Window::GetFocusChild ( void ) const [inline]

View * Window::SetFocusChild ( View * pcView )

Description:: Give a view focus, or remove the focus from the current active view by passing in a NULL pointer. This has the same effect as calling pcView->MakeFocus(true).

Parameters:

pcView

- The View that should receive focus, or a NULL pointer to remove focus from the currently active view.

Returns:: Pointer to the previously active view, or NULL if no view had focus.

See also:: View::MakeFocus()

Author:: Kurt Skauen ([email protected])

void Window::SetDefaultButton ( View * pcView )

Description:: Set the default button. The default button will receive KeyDown()/KeyUp() events generated by the <ENTER> key even when not having focus. Since the os::Button class will invoke itself when the <ENTER> key is hit, it will allow the user to activate the default button by simply hitting the <ENTER> key without making the button active first.

Parameters:

pcView

- Pointer to the View that should receive all events generated by the <ENTER> key. This will typically be an instance of the os::Button class.

See also:: GetDefaultButton(), os::Button, View::KeyUp(), View::KeyDown()

Author:: Kurt Skauen ([email protected])

View * Window::GetDefaultButton ( ) const

Description:: Return the pointer last set through SetDefaultButton() or NULL if not default button is assigned. Note that this is a os::View pointer, and if you want to call any os::Button spesific member you must static_cast it to a os::Button. If you are not 100% sure that the View is in fact a os::Button, you should use dynamic_cast, and test the result before touching it.

Returns:: Pointer to the default button, or NULL if no default button is assigned.

See also:: SetDefaultButton()

Author:: Kurt Skauen ([email protected])

void Window::SetDefaultWheelView ( View * pcView )

View * Window::GetDefaultWheelView ( ) const

Rect Window::GetFrame ( ) const

Returns:: The windows client rectangle.

See also:: SetFrame(), GetBounds()

Author:: Kurt Skauen ([email protected])

Rect Window::GetBounds ( void ) const

Description:: Same as GetFrame() except that the rectangle is moved so the left/top corner is located at 0,0.

Returns:: The windows boundary.

See also:: GetFrame(), SetFrame()

Author:: Kurt Skauen ([email protected])

void Window::SetFrame	(	const Rect &	cRect,
		bool	bNotifyServer = `true`
	)

Description:: SetFrame() will set the windows client position and size on the current desktop.

Parameters:

cRect

- The new frame rectangle of the window's client area.

See also:: GetFrame(), GetBounds(), MoveBy(), MoveTo(), ResizeBy(), ResizeTo()

Author:: Kurt Skauen ([email protected])

void Window::MoveBy ( const Point & cDelta )

Parameters:

cDelta

- The distance to move the window.

See also:: MoveTo(), ResizeBy(), ResizeTo(), SetFrame()

Author:: Kurt Skauen ([email protected])

void Window::MoveBy	(	float	vDeltaX,
		float	vDeltaY
	)

Parameters:

	nDeltaX	- The horizontal distance to move the window.
	nDeltaY	- The vertical distance to move the window.

See also:: MoveTo(), ResizeBy(), ResizeTo(), SetFrame()

Author:: Kurt Skauen ([email protected])

void Window::MoveTo ( const Point & cPos )

Description:: Move the window so the upper left corner of the client area is at the given position

Parameters:

cPos

- The new position

See also:: MoveBy(), ResizeBy(), ResizeTo(), SetFrame()

Author:: Kurt Skauen ([email protected])

void Window::MoveTo	(	float	x,
		float	y
	)

Description:: Move the window so the upper left corner of the client area is at the given position.

Parameters:

	x	- The new horizontal position.
	y	- The new vertical position.

See also:: MoveBy(), ResizeBy(), ResizeTo(), SetFrame()

Author:: Kurt Skauen ([email protected])

void Window::CenterInWindow ( Window * pcWin )

Description:: Move the window so the centre of the window is in the centre of the the given window.

Parameters:

pcWin

- The Window to center in.

See also:: MoveTo(), MoveBy(), ResizeBy(), ResizeTo(), SetFrame()

Author:: Rick Caudill

void Window::CenterInScreen ( )

Description:: This method moves the window to the center of the screen.

See also:: MoveTo(), MoveBy(), ResizeBy(), ResizeTo(), SetFrame()

Author:: Rick Caudill

void Window::ResizeBy ( const Point & cDelta )

Parameters:

cDelta

- The distance to move the lower-right corner of the window.

See also:: ResizeTo(), MoveBy(), MoveTo(), SetFrame()

Author:: Kurt Skauen ([email protected])

void Window::ResizeBy	(	float	vDeltaW,
		float	vDeltaH
	)

Parameters:

	nDeltaW	- The horizontal distance to move the lower-right corner of the window.
	nDeltaH	- The vertical distance to move the lower-right corner of the window.

See also:: ResizeTo(), MoveBy(), MoveTo(), SetFrame()

Author:: Kurt Skauen ([email protected])

void Window::ResizeTo ( const Point & cSize )

Parameters:

cSize

- The new size of the windows client area.

See also:: ResizeBy(), MoveBy(), MoveTo(), SetFrame()

Author:: Kurt Skauen ([email protected])

void Window::ResizeTo	(	float	w,
		float	h
	)

Parameters:

	W	- The new width of the windows client area.
	W	- The new heigth of the windows client area.

See also:: ResizeBy(), MoveBy(), MoveTo(), SetFrame()

Author:: Kurt Skauen ([email protected])

void Window::SetShapeRegion ( const Region & cReg )

Note:

Warning:

Parameters:

\return

Error codes:

Since:: 0.3.7

See also:: ClearShapeRegion(), os::View::SetShapeRegion()

Author:: Kurt Skauen ([email protected])

void Window::ClearShapeRegion ( )

Note:

Warning:

Parameters:

\return

Error codes:

Since:: 0.3.7

See also:: SetShapeRegion(), os::View::ClearShapeRegion()

Author:: Kurt Skauen ([email protected])

bool Window::IsActive ( ) const

int Window::ToggleDepth ( )

void Window::AddShortcut	(	const ShortcutKey &	cKey,
		Message *	pcMsg
	)

Description:: Adds a keyboard shortcut to this window. When the keyboard event occurs, a message is sent to the window's message handler. Normally you should not need to use this method directly, menus and widgets will automatically register their shortcuts.

Parameters:

	cKey	- The keyboard event that triggers the shortcut.
	pcMsg	- Message to send to this window (automatically deleted).

See also:: RemoveShortcut()

Author:: Henrik Isaksson ([email protected])

void Window::AddShortcut	(	const ShortcutKey &	cKey,
		View *	pcView
	)

Description:: Adds a keyboard shortcut to this window. When the keyboard event occurs, the assigned View's KeyDown event handler is called. Normally you should not need to use this method directly, menus and widgets will automatically register their shortcuts.

Parameters:

	cKey	- The keyboard event that triggers the shortcut.
	pcView	- View to send the shortcut to.

See also:: RemoveShortcut()

Author:: Henrik Isaksson ([email protected])

void Window::RemoveShortcut ( const ShortcutKey & cKey )

Description:: Remove a keyboard shortcut previously added by one of the AddShortcut() methods. Normally you should not need to use this method directly, menus and widgets will automatically unregister their shortcuts.

Parameters:

cKey

- The keyboard event that triggers the shortcut.

See also:: AddShortcut()

Author:: Henrik Isaksson ([email protected])

void Window::DispatchMessage	(	Message *	pcMessage,
		Handler *	pcHandler
	)			`[virtual]`

Description:: When a message arrives, the looper extract's it from the queue and call this member with the message as a parameter. The default implementation will attempt to pass the message on to a Handler through it's os::Handler::HandleMessage() member. The Handler that should receive the message is selected as follows:

: If the message targets a specific Handler, that Handler will receive the message. DispatchMessage() can determine wether the message had a final destination by examining the pcHandler argument. If not NULL it points at the handler targeted by the message.

: If the message destination however is not fully qualified DispatchMessage() attempts to pass the message on to the Default handler (as set through the SetDefaultHandler()).

: If there is no final destination and no default handler the Looper will handle the message itself by calling its own version of HandleMessage() (The looper is itself a os::Handler)

: Not all messages are passed on to a handler. If the message code is M_QUIT the Looper::OkToQuit() member is called instead and if it return true looper object will be deleted and the looper thread terminated.

: If you would like to handle certain messages directly by the looper, bypassing the normal scheduling you can overload DispatchMessage() to process messages before they are passed on to any handler. If you do so, you should call the loopers version of DispatchMessage() for each message you don't know how to handle.

: Please note however that you should very rarly overload this member. It is normaly better to overload the HandleMessage() member and let the looper handle the message as any other handlers if you want to pass messages to the looper itself.

Note:: The looper is locked when DispatchMessage() is called.
Never do any lengthy operations in any hook members that are called from the looper thread if the looper is involved with the GUI (for example if the looper is a os::Window). The looper will not be able to dispatch messages until the hook returns so spending a long time in this member will make the GUI feel unresponsive.

Parameters:

	pcMsg	- Pointer to the received messge. Note that this message will be deleted when DispatchMessage() returns, unless detatched from the looper through DetachCurrentMessage().
	pcHandler	- Pointer to the handler targeted by this message. If the message was not targeted at any spesific handler this argument is NULL.

See also:: SetDefaultHandler(), GetDefaultHandler(), PostMessage(), GetCurrentMessage()
DetachCurrentMessage(), Handler::HandleMessage()

Author:: Kurt Skauen ([email protected])

Reimplemented from os::Looper.


Public Member Functions
	Window (const Rect &cFrame, const String &cName, const String &cTitle, uint32 nFlags=0, uint32 nDesktopMask=CURRENT_DESKTOP)
	Initialize the window.
	~Window ()
	Destruct a window.
virtual void	FrameMoved (const Point &cDelta)
virtual void	FrameSized (const Point &cDelta)
virtual void	ScreenModeChanged (const IPoint &cNewRes, color_space eColorSpace)
	Called whenever the screenmode changes.
virtual void	DesktopActivated (int nDesktop, bool bActive)
	Called whenever the desktop displaying the window will be activated or deactivated.
virtual void	DesktopsChanged (uint32 nOldDesktops, uint32 nNewDesktops)
virtual void	WindowsChanged ()
	Called whenever the currently shown windows change.
void	SetFlags (uint32 nFlags)
uint32	GetFlags () const
void	SetSizeLimits (const Point &cMinSize, const Point &cMaxSize)
	Limit the minimum and maximum window size.
void	SetAlignment (const IPoint &cSize=IPoint(1, 1), const IPoint &cSizeOffset=IPoint(0, 0), const IPoint &cPos=IPoint(1, 1), const IPoint &cPosOffset=IPoint(0, 0))
void	AddChild (View *pcChild, bool bAssignTabOrder=false)
	Add a view to the window.
void	RemoveChild (View *pcChild)
	Remove a view from the window.
void	MakeFocus (bool bFocus=true)
	Activate/Deactivate the window.
void	Close ()
void	Show (bool bMakeVisible=true)
	Hide/Unhide the window.
void	Hide ()
bool	IsVisible () const
void	Start ()
	Unlock the window and start the looper thread.
void	SetTitle (const String &cTitle)
	Change the window title.
String	GetTitle (void) const
	Obtain the current window title.
void	SetIcon (Bitmap *pcIcon)
	Change the window icon.
Bitmap *	GetIcon (void) const
	Not longer supported.
void	Flush ()
	Flush the windows render queue.
void	Sync ()
	Flush the render queue, and wait til the rendering is done.
View *	FindView (const String &cName) const
View *	FindView (const Point &cPos) const
	Find the view covering a given position on the window.
View *	GetFocusChild (void) const
View *	SetFocusChild (View *pcChild)
	Activate a view.
void	SetDefaultButton (View *pcView)
	Assign a default button.
View *	GetDefaultButton () const
	Return the view assigned as the default button.
void	SetDefaultWheelView (View *pcView)
View *	GetDefaultWheelView () const
Rect	GetFrame () const
	Get the windows position and size on the current desktop.
Rect	GetBounds () const
	Get the window boundary.
void	SetFrame (const Rect &cRect, bool bNotifyServer=true)
	Set the window's position and size.
void	MoveBy (const Point &cDelta)
	Move the window relative to it's current position.
void	MoveBy (float vDeltaX, float vDeltaY)
	Move the window relative to it's current position.
void	MoveTo (const Point &cPos)
	Move the window to an absolute position.
void	MoveTo (float x, float y)
	Move the window to an absolute position.
void	CenterInWindow (Window *pcWin)
	Move the window to the centre of another window.
void	CenterInScreen ()
	Move the window to the center of the screen.
void	ResizeBy (const Point &cDelta)
	Resize the window relative to it's current size.
void	ResizeBy (float vDeltaW, float vDeltaH)
	Resize the window relative to it's current size.
void	ResizeTo (const Point &cSize)
	Resize the window to a new absolute size.
void	ResizeTo (float w, float h)
	Resize the window to a new absolute size.
void	SetShapeRegion (const Region &cReg)
	Description:
void	ClearShapeRegion ()
	Description:
bool	IsActive () const
int	ToggleDepth ()
void	AddShortcut (const ShortcutKey &cKey, Message *pcMsg)
	Add a keyboard shortcut.
void	AddShortcut (const ShortcutKey &cKey, View *pcView)
	Add a keyboard shortcut.
void	RemoveShortcut (const ShortcutKey &cKey)
	Remove a keyboard shortcut.
void	DispatchMessage (Message pcMessage, Handler pcHandler)
	The loopers message handling callback.
Friends
class	View
class	Bitmap
class	MenuItem
class	ScreenOutput
Classes
class	Private

os::Window Class Reference
[The Syllable Graphical User Interface API]

Public Member Functions

Friends

Classes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

os::Window Class Reference [The Syllable Graphical User Interface API]

Public Member Functions

Friends

Classes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

os::Window Class Reference
[The Syllable Graphical User Interface API]