GG: GG::Wnd Class Reference

Window Geometry
The coordinates of Wnd boundaries are STL-style, as are most range-values throughout GG, meaning that LowerRight() denotes the "last + 1" pixel of a Wnd. The on-screen representation of a rectangular Wnd covers the pixels from UpperLeft() to LowerRight() - Pt(1, 1), not UpperLeft() to LowerRight(). Each Wnd has a client area from ClientUpperLeft() to ClientLowerRight(). These two methods are virtual, and may return anything the user likes; the default implementation is to return UpperLeft() and LowerRight(), respectively, meaning that the client area is the entire window.

Child Windows
It is assumed that child windows exists within the boundaries of their parents, although this is not required. By default, Wnds do not clip their children; child clipping can be turned on or off using EnableChildClipping(), which clips all children to the client area of the Wnd. Subclasses can override BeginClipping() and EndClipping() if the clipping desired is something other than the client area of the Wnd, or if the Wnd is not rectangular. Regardless of clipping, all clicks that land on a child but outside of the parent will not reach the child, since clicks are detected by seaching the top-level Wnds and then searching the children within the ones that are hit. Ideally, "sibling" child windows should not overlap (unless they can without interfering). If this is impossible or undesirable and control is needed over the order in which children are rendered, MoveChildUp() and MoveChildDown() provide such control.

Effects of Window-Creation Flags
Resizable() windows are able to be stretched by the user, by dragging the areas of the window outside the client area. So the RESIZABLE flag will have no effect on a window that does not have non-default ClientUpperLeft() and/or ClientLowerRight(). The WindowRegion() method can also be overidden in derived classes, and can return regions that are appropriate to nonrectangular windows, or those whose client area must cover the entire window.
OnTop() windows are drawn after all others (except Modal() ones), to ensure that they remain on top. This means that other non-OnTop() windows that are moved to the top of the z-order stop at some z-value below the lowest OnTop() window in the z-order. On-topness is useful for modeless dialog boxes, among other things.
Modal() windows are available (by setting the MODAL window creation flag), and are also always-on-top, but are handled differently and do not have ONTOP specified in their creation flags. Modal windows are executed by calling Run(), which registers them as modal windows and starts the local execution of the GUI's event pump. Execution of the code that calls Run() is effectively halted until Run() returns. Derived classes that wish to use modal execution should set m_done = true to escape from the modal execution loop. EventPump has more information about processing during modal dialog execution.
Note that OnTop() and Modal() flags only apply to top-level (Parent()-less) Wnds.

Signal Considerations
Wnd inherits from boost::signals::trackable. This means that any slots contained in a Wnd object or Wnd-derived object will automatically be disconnected from any connected signals when the Wnd is destroyed. Every Wnd responds to input as driven by the singleton GUI object.

Event Filters
Every Wnd can also have its incoming WndEvents filtered by an arbitrary number of other Wnds. Each such Wnd in a Wnd's "filter chain" gets an opportunity, one at a time, to process an incoming WndEvent, or pass it on to the next filter in the chain. If all EventFilter() calls in the chain return false, the filtered Wnd then gets the chance to process the WndEvent as normal. Filter Wnds are traversed in reverse order that they are installed, and no filter Wnd can be in a filter chain more than once. Installing the same filter Wnd more than once removes the Wnd from the filter chain and re-adds it to the beginning of the chain. Note that the default implementation of EventFilter() is to return false and do nothing else, so installing a Wnd-derived type with no overridden EventFilter() in a filter Wnd will have no effect. Also note that just as it is legal for keyboard accelerator slots to do nontrivial work and still return false (causing a keystroke event to be generated), EventFilter() may return false even when it does nontrivial work, and the next filter in the chain will also get a chance to process the WndEvent. It is even possible to have an arbitrary number of filters that all do processing on an WndEvent, and finally let the filtered Wnd do its normal WndEvent processing.

Layouts
Layouts arrange children in the client area of a window, and can be assigned to a window in 4 ways. HorizontalLayout(), VerticalLayout(), and GridLayout() all arrange the window's client-area children automatically, and take ownership of them as their own children, becoming the window's only client-area child. Any existing layout is removed first. SetLayout() allows you to attach a pre-configured Layout object directly, without automatically arranging the window's client-area children. Because SetLayout() does no auto-arrangement, it does not know how to place any client-area children the window may have at the time it is called; for this reason, it not only removes any previous layout, but deletes all current client-area children as well. Therefore, SetLayout() should usually only be called before any client-area children are attached to a window; all client-area children should be attached directly to the layout.
When a window has an attached layout and is resized, it resizes its layout automatically. Further, if a window is part of a layout, it notifies its containing layout whenever it is moved, resized, or has its MinSize() changed. This ensures that layouts are always current. Note the use of the phrase "client-area children". This refers to children entirely within the client area of the window.

Browse Info
Browse info is a non-interactive informational window that pops up after the user keeps the mouse over the Wnd for a certain period of time. This can reproduce "tooltip"-like functionality, but is not limited to displaying only text. An arbitrary BrowseInfoWnd-derived window can be displayed. There can be multiple browse info modes, numbered 0 through N - 1. Each mode has a time associated with it, and after the associated time has elapsed, that mode is entered. This is intended to allow different levels of detail to be shown for different lengths of mouse presence. For instance, hovering over a Wnd for 1 second might produce a box that says "FooWnd", but leaving it there a total of 2 seconds might produce a box that says "FooWnd: currently doing nothing". When the mouse leaves the Wnd, a click occurs, etc., the Wnd reverts to browse mode -1, indicating that no browse info should be displayed. By default, every Wnd has a single browse info mode at time DefaultBrowseTime(), using the DefaultBrowseInfoWnd(), with no associated text. Note that DefaultBrowseInfoWnd() returns a null window unless it is set by the user. As this implies, it is legal to have no BrowseInfoWnd associated with a browse mode, in which case nothing is shown. Also note that it is legal to have no text associated with a browse mode.

Style Factory
A StyleFactory is responsible for creating controls and dialogs that other Wnds may need (e.g. when Slider needs to create a Button for its sliding tab). There is an GUI-wide StyleFactory available, but for complete customization, each Wnd may have one installed as well. The GetStyleFactory() method returns the one installed in the Wnd, if one exists, or the GUI-wide one otherwise.

Note that while a Wnd can contain arbitrary Wnd-derived children, in order for such children to be automatically serialized, any user-defined Wnd subclasses must be registered. See the boost serialization documentation for details, and/or the serialization tutorial for examples.

Constructor & Destructor Documentation

virtual GG::Wnd::~Wnd ( ) [virtual]

virtual dtor

GG::Wnd::Wnd ( ) [protected]

default ctor

GG::Wnd::Wnd	(	int	x,
		int	y,
		int	w,
		int	h,
		Flags< WndFlag >	flags = `CLICKABLE\|DRAGABLE`
	)			`[protected]`

ctor that allows a size and position to be specified, as well as creation flags

Member Function Documentation

bool GG::Wnd::Clickable ( ) const

does a click over this window pass through?

bool GG::Wnd::RepeatButtonDown ( ) const

should holding a mouse button down over this Wnd generate multiple *ButtonDown messages?

bool GG::Wnd::Dragable ( ) const

does a click here become a drag?

bool GG::Wnd::Resizable ( ) const

can this window be resized using the mouse?

bool GG::Wnd::OnTop ( ) const

is this an on-top window?

bool GG::Wnd::Modal ( ) const

is this a modal window?

bool GG::Wnd::ClipChildren ( ) const

is child clipping enabled?

bool GG::Wnd::Visible ( ) const

is the window visible?

const std::string& GG::Wnd::WindowText ( ) const

returns text associated with this window

const std::string& GG::Wnd::DragDropDataType ( ) const

returns the string key that defines the type of data that this Wnd represents in drag-and-drop drags.

Returns the empty string when this Wnd cannot be used in drag-and-drop.

Pt GG::Wnd::UpperLeft ( ) const

returns the upper-left corner of window in screen coordinates (taking into account parent's screen position, if any)

Referenced by GG::Spin< T >::Render().

Pt GG::Wnd::LowerRight ( ) const

returns (one pixel past) the lower-right corner of window in screen coordinates (taking into account parent's screen position, if any)

Referenced by GG::Spin< T >::Render().

Pt GG::Wnd::RelativeUpperLeft ( ) const

returns the upper-left corner of window, relative to its parent's client area, or in screen coordinates if no parent exists.

Referenced by GG::Spin< T >::SetButtonWidth().

Pt GG::Wnd::RelativeLowerRight ( ) const

returns (one pixel past) the lower-right corner of window, relative to its parent's client area, or in screen coordinates if no parent exists.

Referenced by GG::Spin< T >::SetButtonWidth().

int GG::Wnd::Width ( ) const

returns width of window in pixels

Referenced by GG::Spin< T >::SetButtonWidth(), and GG::Spin< T >::SizeMove().

int GG::Wnd::Height ( ) const

returns width of window in pixels

Referenced by GG::Spin< T >::SizeMove().

int GG::Wnd::ZOrder ( ) const

returns the position of this window in the z-order (root (non-child) windows only)

Pt GG::Wnd::Size ( ) const

returns a Pt packed with width in x and height in y

Pt GG::Wnd::MinSize ( ) const

returns the minimum allowable size of window

Pt GG::Wnd::MaxSize ( ) const

returns the maximum allowable size of window

virtual Pt GG::Wnd::MinUsableSize ( ) const [virtual]

returns the size of the minimum bounding box that can enclose the Wnd and still show all of its elements, plus enough room for interaction with those elements (if applicable).

For example, a TextControl's MinUsableSize() is just the area of its text, and a Scroll's RenderableMinSize() is the combined sizes of its up-button, down-button, and tab (plus a bit of room in which to drag the tab).

Reimplemented in GG::StateButton, GG::RadioButtonGroup, GG::Edit, GG::Layout, GG::ListBox, GG::MenuBar, GG::MultiEdit, GG::Scroll, GG::Slider, GG::Spin< T >, GG::TabWnd, GG::TabBar, and GG::TextControl.

virtual Pt GG::Wnd::ClientUpperLeft ( ) const [virtual]

returns upper-left corner of window's client area in screen coordinates (or of the entire area, if no client area is specified).

Virtual because different windows have different shapes (and so ways of calculating client area)

Reimplemented in GG::DropDownList, GG::Edit, GG::ListBox, and GG::PopupMenu.

virtual Pt GG::Wnd::ClientLowerRight ( ) const [virtual]

returns (one pixel past) lower-right corner of window's client area in screen coordinates (or of the entire area, if no client area is specified).

Virtual because different windows have different shapes (and so ways of calculating client area)

Reimplemented in GG::DropDownList, GG::Edit, GG::ListBox, and GG::MultiEdit.

Pt GG::Wnd::ClientSize ( ) const

returns the size of the client area

See also:: Size()

int GG::Wnd::ClientWidth ( ) const

returns the width of the client area

int GG::Wnd::ClientHeight ( ) const

returns the height of the client area

Pt GG::Wnd::ScreenToWindow ( const Pt & pt ) const

returns pt translated from screen- to window-coordinates

Pt GG::Wnd::ScreenToClient ( const Pt & pt ) const

returns pt translated from screen- to client-coordinates

virtual bool GG::Wnd::InWindow ( const Pt & pt ) const [virtual]

returns true if screen-coordinate point pt falls within the window

virtual bool GG::Wnd::InClient ( const Pt & pt ) const [virtual]

returns true if screen-coordinate point pt falls within the window's client area

const std::list<Wnd*>& GG::Wnd::Children ( ) const

returns child list; the list is const, but the children may be manipulated

Wnd* GG::Wnd::Parent ( ) const

returns the window's parent (may be null)

Wnd* GG::Wnd::RootParent ( ) const

returns the earliest ancestor window (may be null)

Layout* GG::Wnd::GetLayout ( ) const

returns the layout for the window, if any

Layout* GG::Wnd::ContainingLayout ( ) const

returns the layout containing the window, if any

const std::vector<BrowseInfoMode>& GG::Wnd::BrowseModes ( ) const

returns the browse modes for the Wnd, including time cutoffs (in milliseconds), the BrowseInfoWnds to be displayed for each browse info mode, and the text (if any) to be displayed in each mode.

As the time that the cursor is over this Wnd exceeds each mode's time, the corresponding Wnd is shown superimposed over this Wnd and its children. Set the first time cutoff to 0 for immediate browse info display.

const std::string& GG::Wnd::BrowseInfoText ( int mode ) const

returns the text to display for browse info mode mode.

Exceptions:

std::out_of_range

May throw std::out_of_range if mode is not a valid browse mode.

const boost::shared_ptr<StyleFactory>& GG::Wnd::GetStyleFactory ( ) const

returns the currently-installed style factory if none exists, or the GUI-wide one otherwise

virtual WndRegion GG::Wnd::WindowRegion ( const Pt & pt ) const [virtual]

also virtual b/c of different window shapes

void GG::Wnd::SetDragDropDataType ( const std::string & data_type )

sets the string key that defines the type of data that this Wnd represents in a drag-and-drop drag.

This should be set to the empty string when this Wnd cannot be used in drag-and-drop.

virtual void GG::Wnd::StartingChildDragDrop	(	const Wnd *	wnd,
		const Pt &	offset
	)			`[virtual]`

indicates to the Wnd that a child Wnd wnd is being dragged in a drag-and-drop operation, which gives it the opportunity to add other associated drag-and-drop Wnds (see GUI::RegisterDragDropWnd()).

offset indicates the position of the mouse relative to wnd's UpperLeft().

Reimplemented in GG::Layout, and GG::ListBox.

virtual void GG::Wnd::AcceptDrops	(	std::list< Wnd * > &	wnds,
		const Pt &	pt
	)			`[virtual]`

handles a drop of one or more drag-and-drop wnds into this Wnd; the accepted wnds remain in the list wnds; the rejected ones do not.

This function must not not alter the order of the elements in wnds. It may only remove elements.

Reimplemented in GG::Control, and GG::ListBox.

virtual void GG::Wnd::CancellingChildDragDrop ( const std::list< Wnd * > & wnds ) [virtual]

handles the cancellation of the dragging of one or more child windows, whose dragging was established by the most recent call to StartingChildDragDrop().

Note that even if an accepting Wnd Accept()s some but not all Wnds, this function will be called on those Wnds not accepted. Note that CancellingChildDragDrop() and ChildrenDraggedAway() are always called in that order, and are always called at the end of any drag-and-drop sequence performed on a child of this Wnd, whether the drag-and-drop is successful or not.

Reimplemented in GG::Layout.

virtual void GG::Wnd::ChildrenDraggedAway	(	const std::list< Wnd * > &	wnds,
		const Wnd *	destination
	)			`[virtual]`

handles the removal of one or more child windows that have been dropped onto another window which has accepted them as drops.

The accepting window retains ownership, so this function must not delete the children. Note that CancellingChildDragDrop() and ChildrenDraggedAway() are always called in that order, and are always called at the end of any drag-and-drop sequence performed on a child of this Wnd, whether the drag-and-drop is successful or not.

Reimplemented in GG::Layout, and GG::ListBox.

virtual void GG::Wnd::SetText ( const std::string & str ) [virtual]

set window text

Reimplemented in GG::TextBoxBrowseInfoWnd, GG::Edit, GG::MultiEdit, and GG::TextControl.

void GG::Wnd::Hide ( bool children = true )

suppresses rendering of this window (and possibly its children) during render loop

void GG::Wnd::Show ( bool children = true )

enables rendering of this window (and possibly its children) during render loop

virtual void GG::Wnd::ModalInit ( ) [virtual]

called during Run(), after a modal window is registered, this is the place that subclasses should put specialized modal window initialization, such as setting focus to child controls

void GG::Wnd::EnableChildClipping ( bool enable = true )

enables or disables clipping of child windows to the boundaries of this Wnd

virtual void GG::Wnd::BeginClipping ( ) [virtual]

sets up child clipping for this window

virtual void GG::Wnd::EndClipping ( ) [virtual]

restores state to what it was before BeginClipping() was called

void GG::Wnd::MoveTo ( const Pt & pt )

moves upper-left corner of window to pt

void GG::Wnd::OffsetMove ( const Pt & pt )

moves window by pt pixels

virtual void GG::Wnd::SizeMove	(	const Pt &	ul,
		const Pt &	lr
	)			`[virtual]`

resizes and/or moves window to new upper-left and lower right boundaries

Reimplemented in GG::StateButton, GG::DropDownList, GG::Layout, GG::ListBox, GG::MenuBar, GG::MultiEdit, GG::Scroll, GG::Slider, GG::Spin< T >, GG::TabBar, and GG::TextControl.

Referenced by GG::Spin< T >::SizeMove().

void GG::Wnd::Resize ( const Pt & sz )

resizes window without moving upper-left corner

void GG::Wnd::SetMinSize ( const Pt & sz )

sets the minimum allowable size of window pt

void GG::Wnd::SetMaxSize ( const Pt & sz )

sets the maximum allowable size of window pt

void GG::Wnd::AttachChild ( Wnd * wnd )

places wnd in child ptr list, sets's child's m_parent member to this

void GG::Wnd::MoveChildUp ( Wnd * wnd )

places wnd at the end of the child ptr list, so it is rendered last (on top of the other children)

void GG::Wnd::MoveChildDown ( Wnd * wnd )

places wnd at the beginning of the child ptr list, so it is rendered first (below the other children)

void GG::Wnd::DetachChild ( Wnd * wnd )

removes wnd from child ptr list, sets child's m_parent = 0

void GG::Wnd::DetachChildren ( )

removes all Wnds from child ptr list, sets childrens' m_parent = 0

void GG::Wnd::DeleteChild ( Wnd * wnd )

removes, detaches, and deletes wnd; does nothing if wnd is not in the child list

void GG::Wnd::DeleteChildren ( )

removes, detaches, and deletes all Wnds in the child list

void GG::Wnd::InstallEventFilter ( Wnd * wnd )

adds wnd to the front of the event filtering chain

void GG::Wnd::RemoveEventFilter ( Wnd * wnd )

removes wnd from the filter chain

void GG::Wnd::HorizontalLayout ( )

places the window's client-area children in a horizontal layout, handing ownership of the window's client-area children over to the layout.

Removes any current layout which may exist.

void GG::Wnd::VerticalLayout ( )

places the window's client-area children in a vertical layout, handing ownership of the window's client-area children over to the layout.

Removes any current layout which may exist.

void GG::Wnd::GridLayout ( )

places the window's client-area children in a grid layout, handing ownership of the window's client-area children over to the layout.

Removes any current layout which may exist.

void GG::Wnd::SetLayout ( Layout * layout )

sets layout as the layout for the window.

Removes any current layout which may exist, and deletes all client-area child windows.

void GG::Wnd::RemoveLayout ( )

removes the window's layout, handing ownership of all its children back to the window, with the sizes and positions they had before the layout resized them.

If no layout exists for the window, no action is taken.

Layout* GG::Wnd::DetachLayout ( )

removes the window's layout, including all attached children, and returns it.

If no layout exists for the window, no action is taken.

void GG::Wnd::SetLayoutBorderMargin ( int margin )

sets the margin that should exist between the outer edges of the windows in the layout and the edge of the client area.

If no layout exists for the window, this has no effect.

void GG::Wnd::SetLayoutCellMargin ( int margin )

sets the margin that should exist between the windows in the layout.

If no layout exists for the window, this has no effect.

virtual void GG::Wnd::Render ( ) [virtual]

draws this Wnd.

Note that Wnds being dragged for a drag-and-drop operation are rendered twice -- once in-place as normal, once in the location of the drag operation, attached to the cursor. Such Wnds may wish to render themselves differently in those two cases. To determine which render is being performed, they can call GUI::GetGUI()->RenderingDragDropWnds().

Reimplemented in GG::BrowseInfoWnd, GG::TextBoxBrowseInfoWnd, GG::Button, GG::StateButton, GG::RadioButtonGroup, GG::Control, GG::HueSaturationPicker, GG::ValuePicker, GG::ColorDlg::ColorDisplay, GG::ColorDlg, GG::FileDlg, GG::ThreeButtonDlg, GG::DropDownList, GG::DynamicGraphic, GG::Edit, GG::Layout, GG::ListBox::Row, GG::ListBox, GG::MenuBar, GG::PopupMenu, GG::MultiEdit, GG::Scroll, GG::Slider, GG::Spin< T >, GG::StaticGraphic, GG::TabWnd, GG::TabBar, and GG::TextControl.

virtual void GG::Wnd::LButtonDown	(	const Pt &	pt,
		Flags< ModKey >	mod_keys
	)			`[virtual]`

respond to left button down msg.

A window receives this whenever any input device button changes from up to down while over the window.

Note:: If this Wnd was created with the REPEAT_BUTTON_DOWN flag, this method may be called multiple times during a single button press-release cycle.

See also:: GG::GUI

Reimplemented in GG::Button, GG::HueSaturationPicker, GG::ValuePicker, GG::Edit, GG::MenuBar, GG::MultiEdit, and GG::Scroll.

virtual void GG::Wnd::LDrag	(	const Pt &	pt,
		const Pt &	move,
		Flags< ModKey >	mod_keys
	)			`[virtual]`

respond to left button drag msg (even if this Wnd is not dragable).

Drag messages are only sent to the window over which the button was pressed at the beginning of the drag. A window receives this whenever any input device button is down and the cursor is moving while over the window. The window will also receive drag messages when the mouse is being dragged outside the window's area.

Reimplemented in GG::Button, GG::HueSaturationPicker, GG::ValuePicker, GG::Edit, GG::PopupMenu, and GG::MultiEdit.

virtual void GG::Wnd::LButtonUp	(	const Pt &	pt,
		Flags< ModKey >	mod_keys
	)			`[virtual]`

respond to release of left mouse button outside this Wnd, if it was originally depressed over this Wnd.

A Wnd will receive an LButtonUp() message whenever a drag that started over its area ends, even if the cursor is not currently over the window when this happens.

Reimplemented in GG::Button, GG::PopupMenu, and GG::Scroll.

virtual void GG::Wnd::LClick	(	const Pt &	pt,
		Flags< ModKey >	mod_keys
	)			`[virtual]`

respond to release of left mouse button over this Wnd, if it was also originally depressed over this Wnd.

A Wnd will receive an LButtonUp() message whenever a drag that started over its area ends over its area as well.

Reimplemented in GG::Button, GG::StateButton, GG::DropDownList, GG::Edit, GG::PopupMenu, GG::Scroll, and GG::Slider.

virtual void GG::Wnd::LDoubleClick	(	const Pt &	pt,
		Flags< ModKey >	mod_keys
	)			`[virtual]`

respond to second left click in window within the time limit.

A window will receive an LDoubleClick() message instead of an LButtonDown() or LClick() message if the left input device button is pressed over a window that was l-clicked within a double-click time interval. Note that this means a double click is always preceded by a click. For a double click to occur, no other window may have received a *Click() or *ButtonDown() message in during the interval.

virtual void GG::Wnd::MButtonDown	(	const Pt &	pt,
		Flags< ModKey >	mod_keys
	)			`[virtual]`

respond to middle button down msg.

See also:: LButtonDown()

virtual void GG::Wnd::MDrag	(	const Pt &	pt,
		const Pt &	move,
		Flags< ModKey >	mod_keys
	)			`[virtual]`

respond to middle button drag msg (even if this Wnd is not dragable).

See also:: LDrag()

virtual void GG::Wnd::MButtonUp	(	const Pt &	pt,
		Flags< ModKey >	mod_keys
	)			`[virtual]`

respond to release of middle mouse button outside this Wnd, if it was originally depressed over this Wnd.

See also:: LButtonUp()

virtual void GG::Wnd::MClick	(	const Pt &	pt,
		Flags< ModKey >	mod_keys
	)			`[virtual]`

respond to release of middle mouse button over this Wnd, if it was also originally depressed over this Wnd.

See also:: LClick()

virtual void GG::Wnd::MDoubleClick	(	const Pt &	pt,
		Flags< ModKey >	mod_keys
	)			`[virtual]`

respond to second middle click in window within the time limit.

See also:: LDoubleClick()

virtual void GG::Wnd::RButtonDown	(	const Pt &	pt,
		Flags< ModKey >	mod_keys
	)			`[virtual]`

respond to right button down msg.

See also:: LButtonDown()

virtual void GG::Wnd::RDrag	(	const Pt &	pt,
		const Pt &	move,
		Flags< ModKey >	mod_keys
	)			`[virtual]`

respond to right button drag msg (even if this Wnd is not dragable).

See also:: LDrag()

virtual void GG::Wnd::RButtonUp	(	const Pt &	pt,
		Flags< ModKey >	mod_keys
	)			`[virtual]`

respond to release of right mouse button outside this Wnd, if it was originally depressed over this Wnd.

See also:: LButtonUp()

Reimplemented in GG::PopupMenu.

virtual void GG::Wnd::RClick	(	const Pt &	pt,
		Flags< ModKey >	mod_keys
	)			`[virtual]`

respond to release of right mouse button over this Wnd, if it was also originally depressed over this Wnd.

See also:: LClick()

Reimplemented in GG::PopupMenu.

virtual void GG::Wnd::RDoubleClick	(	const Pt &	pt,
		Flags< ModKey >	mod_keys
	)			`[virtual]`

respond to second right click in window within the time limit.

See also:: LDoubleClick()

virtual void GG::Wnd::MouseEnter	(	const Pt &	pt,
		Flags< ModKey >	mod_keys
	)			`[virtual]`

respond to cursor entering window's coords

virtual void GG::Wnd::MouseHere	(	const Pt &	pt,
		Flags< ModKey >	mod_keys
	)			`[virtual]`

respond to cursor moving about within the Wnd, or to cursor lingering within the Wnd for a long period of time.

A MouseHere() message will not be generated the first time the cursor enters the window's area. In that case, a MouseEnter() message is generated.

Reimplemented in GG::Button, GG::MenuBar, GG::PopupMenu, and GG::Scroll.

virtual void GG::Wnd::MouseLeave ( ) [virtual]

respond to cursor leaving window's coords

Reimplemented in GG::Button, and GG::MenuBar.

virtual void GG::Wnd::MouseWheel	(	const Pt &	pt,
		int	move,
		Flags< ModKey >	mod_keys
	)			`[virtual]`

respond to movement of the mouse wheel (move > 0 indicates the wheel is rolled up, < 0 indicates down)

Reimplemented in GG::Control, GG::Layout, GG::ListBox, GG::MultiEdit, and GG::Spin< T >.

virtual void GG::Wnd::DragDropEnter	(	const Pt &	pt,
		const std::map< Wnd *, Pt > &	drag_drop_wnds,
		Flags< ModKey >	mod_keys
	)			`[virtual]`

respond to the cursor entering the Wnd's coords while dragging drag-and-drop Wnds.

The Pts in drag_drop_wnds are the Wnds' offsets from pt.

Reimplemented in GG::ListBox.

virtual void GG::Wnd::DragDropHere	(	const Pt &	pt,
		const std::map< Wnd *, Pt > &	drag_drop_wnds,
		Flags< ModKey >	mod_keys
	)			`[virtual]`

respond to cursor moving about within the Wnd, or to cursor lingering within the Wnd for a long period of time, while dragging drag-and-drop Wnds.

A DragDropHere() message will not be generated the first time the cursor enters the window's area. In that case, a DragDropEnter() message is generated The Pts in drag_drop_wnds are the Wnds' offsets from pt.

Reimplemented in GG::ListBox.

virtual void GG::Wnd::DragDropLeave ( ) [virtual]

respond to cursor leaving the Wnd's bounds while dragging drag-and-drop Wnds.

Reimplemented in GG::ListBox.

virtual void GG::Wnd::KeyPress	(	Key	key,
		Flags< ModKey >	mod_keys
	)			`[virtual]`

respond to down-keystrokes (focus window only).

A window may receive KeyPress() messages passed up to it from its children. For instance, Control-derived classes pass KeyPress() messages to their Parent() windows by default.

Note:: Though mouse clicks consist of a press and a release, all Control classes by default respond immediately to KeyPress(), not KeyRelease(); in fact, by default no Wnd class does anything at all on a KeyRelease event.

Reimplemented in GG::Control, GG::ColorDlg, GG::FileDlg, GG::ThreeButtonDlg, GG::DropDownList, GG::Edit, GG::Layout, GG::ListBox, GG::MultiEdit, GG::Slider, and GG::Spin< T >.

virtual void GG::Wnd::KeyRelease	(	Key	key,
		Flags< ModKey >	mod_keys
	)			`[virtual]`

respond to up-keystrokes (focus window only).

A window may receive KeyRelease() messages passed up to it from its children. For instance, Control-derived classes pass KeyRelease() messages to their Parent() windows by default.

Reimplemented in GG::Control, and GG::Layout.

virtual void GG::Wnd::GainingFocus ( ) [virtual]

respond to this window gaining the input focus

Reimplemented in GG::Edit.

virtual void GG::Wnd::LosingFocus ( ) [virtual]

respond to this window losing the input focus

Reimplemented in GG::Edit.

virtual void GG::Wnd::TimerFiring	(	int	ticks,
		Timer *	timer
	)			`[virtual]`

respond to Timer timer firing at time ticks

Reimplemented in GG::ListBox.

virtual int GG::Wnd::Run ( ) [virtual]

this executes a modal window and gives it its modality.

For non-modal windows, this function is a no-op. It returns 0 if the window is non-modal, or non-zero after successful modal execution.

Reimplemented in GG::PopupMenu.

void GG::Wnd::SetBrowseModeTime	(	int	time,
		int	mode = `0`
	)

sets the time cutoff (in milliseconds) for a browse info mode.

If mode is not less than the current number of modes, extra modes will be created as needed. The extra nodes will be set to the value of the last time at the time the method is called, or time if there were initially no modes.

void GG::Wnd::SetBrowseInfoWnd	(	const boost::shared_ptr< BrowseInfoWnd > &	wnd,
		int	mode = `0`
	)

sets the Wnd that is used to show browse info about this Wnd in the browse info mode mode.

Exceptions:

std::out_of_range

May throw std::out_of_range if mode is not a valid browse mode.

void GG::Wnd::SetBrowseText	(	const std::string &	text,
		int	mode = `0`
	)

sets the browse info window for mode mode to a Wnd with the specified color and border color which contains the specified text.

Exceptions:

std::out_of_range

May throw std::out_of_range if mode is not a valid browse mode.

void GG::Wnd::SetBrowseModes ( const std::vector< BrowseInfoMode > & modes )

sets the browse modes for the Wnd, including time cutoffs (in milliseconds), the BrowseInfoWnds to be displayed for each browse info mode, and the text (if any) to be displayed in each mode.

void GG::Wnd::SetStyleFactory ( const boost::shared_ptr< StyleFactory > & factory )

sets the currently-installed style factory

virtual void GG::Wnd::DefineAttributes ( WndEditor * editor ) [virtual]

provides the attributes of this object that are appropriate for a user to edit in a WndEditor; see WndEditor for details.

Reimplemented in GG::Button, GG::StateButton, GG::RadioButtonGroup, GG::Control, GG::DropDownList, GG::DynamicGraphic, GG::Edit, GG::Layout, GG::ListBox, GG::MenuBar, GG::MultiEdit, GG::Scroll, GG::Slider, GG::Spin< T >, GG::StaticGraphic, and GG::TextControl.

static int GG::Wnd::DefaultBrowseTime ( ) [static]

returns the single time to place in the browse modes during Wnd construction.

static void GG::Wnd::SetDefaultBrowseTime ( int time ) [static]

sets the single time to place in the browse modes during Wnd construction.

static const boost::shared_ptr<BrowseInfoWnd>& GG::Wnd::DefaultBrowseInfoWnd ( ) [static]

returns the single BrowseInfoWnd to place in the browse modes during Wnd construction.

This returns a TextBoxBrowseInfoWnd with a default parameterization.

static void GG::Wnd::SetDefaultBrowseInfoWnd ( const boost::shared_ptr< BrowseInfoWnd > & browse_info_wnd ) [static]

sets the single BrowseInfoWnd to place in the browse modes during Wnd construction.

GG::Wnd::GG_ABSTRACT_EXCEPTION ( Exception )

The base class for Wnd exceptions.

Reimplemented in GG::FileDlg, GG::DynamicGraphic, GG::Layout, and GG::ListBox.

GG::Wnd::GG_CONCRETE_EXCEPTION	(	BadLayout	,
		GG::Wnd	,
		Exception
	)

Thrown when a request to perform a layout fails due to child Wnds in illegal starting positions, or when a SetLayout() call would result in an illegal state.

virtual bool GG::Wnd::EventFilter	(	Wnd *	w,
		const WndEvent &	event
	)			`[protected, virtual]`

handles an WndEvent destined for Wnd w, but which this Wnd is allowed to handle first.

Returns true if this filter processed the message.

Reimplemented in GG::ListBox, GG::Scroll, GG::Slider, GG::Spin< T >, and GG::TabBar.

void GG::Wnd::HandleEvent ( const WndEvent & event ) [protected]

handles all messages, and calls appropriate function (LButtonDown(), LDrag(), etc.)

Friends And Related Function Documentation

friend class GUI [friend]

GUI needs access to m_zorder, m_children, etc.

Definition at line 608 of file Wnd.h.

friend class Timer [friend]

Timer needs to be able to call HandleEvent.

Definition at line 610 of file Wnd.h.

friend class ZList [friend]

ZList needs access to m_zorder in order to order windows.

Definition at line 611 of file Wnd.h.

Member Data Documentation

std::string GG::Wnd::m_text [protected]

text associated with the window, such as a window title or button label, etc.

Definition at line 569 of file Wnd.h.

Referenced by GG::TextControl::GetValue(), and GG::TextControl::operator>>().

bool GG::Wnd::m_done [protected]

derived modal Wnd's set this to true to stop modal loop

Definition at line 570 of file Wnd.h.


Structors
virtual	~Wnd ()
Accessors
bool	Clickable () const
bool	RepeatButtonDown () const
bool	Dragable () const
bool	Resizable () const
bool	OnTop () const
bool	Modal () const
bool	ClipChildren () const
bool	Visible () const
const std::string &	WindowText () const
const std::string &	DragDropDataType () const
Pt	UpperLeft () const
Pt	LowerRight () const
Pt	RelativeUpperLeft () const
Pt	RelativeLowerRight () const
int	Width () const
int	Height () const
int	ZOrder () const
Pt	Size () const
Pt	MinSize () const
Pt	MaxSize () const
virtual Pt	MinUsableSize () const
virtual Pt	ClientUpperLeft () const
virtual Pt	ClientLowerRight () const
Pt	ClientSize () const
int	ClientWidth () const
int	ClientHeight () const
Pt	ScreenToWindow (const Pt &pt) const
Pt	ScreenToClient (const Pt &pt) const
virtual bool	InWindow (const Pt &pt) const
virtual bool	InClient (const Pt &pt) const
const std::list< Wnd * > &	Children () const
Wnd *	Parent () const
Wnd *	RootParent () const
Layout *	GetLayout () const
Layout *	ContainingLayout () const
const std::vector< BrowseInfoMode > &	BrowseModes () const
const std::string &	BrowseInfoText (int mode) const
const boost::shared_ptr< StyleFactory > &	GetStyleFactory () const
virtual WndRegion	WindowRegion (const Pt &pt) const
Mutators
void	SetDragDropDataType (const std::string &data_type)
virtual void	StartingChildDragDrop (const Wnd *wnd, const Pt &offset)
virtual void	AcceptDrops (std::list< Wnd * > &wnds, const Pt &pt)
virtual void	CancellingChildDragDrop (const std::list< Wnd * > &wnds)
virtual void	ChildrenDraggedAway (const std::list< Wnd * > &wnds, const Wnd *destination)
virtual void	SetText (const std::string &str)
void	Hide (bool children=true)
void	Show (bool children=true)
virtual void	ModalInit ()
void	EnableChildClipping (bool enable=true)
virtual void	BeginClipping ()
virtual void	EndClipping ()
void	MoveTo (const Pt &pt)
void	OffsetMove (const Pt &pt)
virtual void	SizeMove (const Pt &ul, const Pt &lr)
void	Resize (const Pt &sz)
void	SetMinSize (const Pt &sz)
void	SetMaxSize (const Pt &sz)
void	AttachChild (Wnd *wnd)
void	MoveChildUp (Wnd *wnd)
void	MoveChildDown (Wnd *wnd)
void	DetachChild (Wnd *wnd)
void	DetachChildren ()
void	DeleteChild (Wnd *wnd)
void	DeleteChildren ()
void	InstallEventFilter (Wnd *wnd)
void	RemoveEventFilter (Wnd *wnd)
void	HorizontalLayout ()
void	VerticalLayout ()
void	GridLayout ()
void	SetLayout (Layout *layout)
void	RemoveLayout ()
Layout *	DetachLayout ()
void	SetLayoutBorderMargin (int margin)
void	SetLayoutCellMargin (int margin)
virtual void	Render ()
virtual void	LButtonDown (const Pt &pt, Flags< ModKey > mod_keys)
virtual void	LDrag (const Pt &pt, const Pt &move, Flags< ModKey > mod_keys)
virtual void	LButtonUp (const Pt &pt, Flags< ModKey > mod_keys)
virtual void	LClick (const Pt &pt, Flags< ModKey > mod_keys)
virtual void	LDoubleClick (const Pt &pt, Flags< ModKey > mod_keys)
virtual void	MButtonDown (const Pt &pt, Flags< ModKey > mod_keys)
virtual void	MDrag (const Pt &pt, const Pt &move, Flags< ModKey > mod_keys)
virtual void	MButtonUp (const Pt &pt, Flags< ModKey > mod_keys)
virtual void	MClick (const Pt &pt, Flags< ModKey > mod_keys)
virtual void	MDoubleClick (const Pt &pt, Flags< ModKey > mod_keys)
virtual void	RButtonDown (const Pt &pt, Flags< ModKey > mod_keys)
virtual void	RDrag (const Pt &pt, const Pt &move, Flags< ModKey > mod_keys)
virtual void	RButtonUp (const Pt &pt, Flags< ModKey > mod_keys)
virtual void	RClick (const Pt &pt, Flags< ModKey > mod_keys)
virtual void	RDoubleClick (const Pt &pt, Flags< ModKey > mod_keys)
virtual void	MouseEnter (const Pt &pt, Flags< ModKey > mod_keys)
virtual void	MouseHere (const Pt &pt, Flags< ModKey > mod_keys)
virtual void	MouseLeave ()
virtual void	MouseWheel (const Pt &pt, int move, Flags< ModKey > mod_keys)
virtual void	DragDropEnter (const Pt &pt, const std::map< Wnd *, Pt > &drag_drop_wnds, Flags< ModKey > mod_keys)
virtual void	DragDropHere (const Pt &pt, const std::map< Wnd *, Pt > &drag_drop_wnds, Flags< ModKey > mod_keys)
virtual void	DragDropLeave ()
virtual void	KeyPress (Key key, Flags< ModKey > mod_keys)
virtual void	KeyRelease (Key key, Flags< ModKey > mod_keys)
virtual void	GainingFocus ()
virtual void	LosingFocus ()
virtual void	TimerFiring (int ticks, Timer *timer)
virtual int	Run ()
void	SetBrowseModeTime (int time, int mode=0)
void	SetBrowseInfoWnd (const boost::shared_ptr< BrowseInfoWnd > &wnd, int mode=0)
void	SetBrowseText (const std::string &text, int mode=0)
void	SetBrowseModes (const std::vector< BrowseInfoMode > &modes)
void	SetStyleFactory (const boost::shared_ptr< StyleFactory > &factory)
virtual void	DefineAttributes (WndEditor *editor)
Exceptions
	GG_ABSTRACT_EXCEPTION (Exception)
	GG_CONCRETE_EXCEPTION (BadLayout, GG::Wnd, Exception)
Structors
	Wnd ()
	Wnd (int x, int y, int w, int h, Flags< WndFlag > flags=CLICKABLE\|DRAGABLE)
Mutators
virtual bool	EventFilter (Wnd *w, const WndEvent &event)
void	HandleEvent (const WndEvent &event)
Static Public Member Functions
static int	DefaultBrowseTime ()
static void	SetDefaultBrowseTime (int time)
static const boost::shared_ptr< BrowseInfoWnd > &	DefaultBrowseInfoWnd ()
static void	SetDefaultBrowseInfoWnd (const boost::shared_ptr< BrowseInfoWnd > &browse_info_wnd)
Protected Attributes
std::string	m_text
bool	m_done
Friends
class	GUI
class	GUIImpl
class	Timer
class	ZList
Classes
struct	BrowseInfoMode
	The data necessary to represent a browse info mode. More...

GG::Wnd Class Reference

Structors

Accessors

Mutators

Exceptions

Structors

Mutators

Static Public Member Functions

Protected Attributes

Friends

Classes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation