GUI Environment. Used as factory and manager of all other GUI elements. More...

#include <jimcpp/core/engine/IGUIEnvironment.hpp>

Inheritance diagram for jpp::gui::IGUIEnvironment:

Collaboration diagram for jpp::gui::IGUIEnvironment:

Public Member Functions
virtual void	drawAll (bool useScreenSize=true)=0
	Draws all gui elements by traversing the GUI environment starting at the root node.

virtual bool	setFocus (IGUIElement *element)=0
	Sets the focus to an element.

virtual IGUIElement *	getFocus () const =0
	Returns the element which holds the focus.

virtual IGUIElement *	getHovered () const =0
	Returns the element which was last under the mouse cursor.

virtual bool	removeFocus (IGUIElement *element)=0
	Removes the focus from an element.

virtual bool	hasFocus (const IGUIElement *element, bool checkSubElements=false) const =0
	Returns whether the element has focus.

virtual video::IVideoDriver *	getVideoDriver () const =0
	Returns the current video driver.

virtual io::IFileSystem *	getFileSystem () const =0
	Returns the file system.

virtual IOSOperator *	getOSOperator () const =0
	returns a pointer to the OS operator

virtual void	clear ()=0
	Removes all elements from the environment.

virtual bool	postEventFromUser (const SEvent &event)=0
	Posts an input event to the environment.

virtual void	setUserEventReceiver (IEventReceiver *evr)=0
	This sets a new event receiver for gui events.

virtual IGUISkin *	getSkin () const =0
	Returns pointer to the current gui skin.

virtual void	setSkin (IGUISkin *skin)=0
	Sets a new GUI Skin.

virtual IGUISkin *	createSkin (EGUI_SKIN_TYPE type)=0
	Creates a new GUI Skin based on a template.

virtual IGUIImageList *	createImageList (video::ITexture *texture, core::dimension2d< s32 > imageSize, bool useAlphaChannel)=0
	Creates the image list from the given texture.

virtual IGUIFont *	getFont (const io::path &filename)=0
	Returns pointer to the font with the specified filename.

virtual IGUIFont *	addFont (const io::path &name, IGUIFont *font)=0
	Adds an externally loaded font to the font list.

virtual void	removeFont (IGUIFont *font)=0
	remove loaded font

virtual IGUIFont *	getBuiltInFont () const =0
	Returns the default built-in font.

virtual IGUISpriteBank *	getSpriteBank (const io::path &filename)=0
	Returns pointer to the sprite bank which was added with addEmptySpriteBank.

virtual IGUISpriteBank *	addEmptySpriteBank (const io::path &name)=0
	Adds an empty sprite bank to the manager.

virtual IGUIElement *	getRootGUIElement ()=0
	Returns the root gui element.

virtual IGUIButton *	addButton (const core::rect< s32 > &rectangle, IGUIElement parent=0, s32 id=-1, const wchar_t text=0, const wchar_t *tooltiptext=0)=0
	Adds a button element.

virtual IGUIWindow *	addWindow (const core::rect< s32 > &rectangle, bool modal=false, const wchar_t text=0, IGUIElement parent=0, s32 id=-1)=0
	Adds an empty window element.

virtual IGUIElement *	addModalScreen (IGUIElement *parent, int blinkMode=3)=0
	Adds a modal screen.

virtual IGUIWindow *	addMessageBox (const wchar_t caption, const wchar_t text=0, bool modal=true, s32 flags=EMBF_OK, IGUIElement parent=0, s32 id=-1, video::ITexture image=0)=0
	Adds a message box.

virtual IGUIScrollBar *	addScrollBar (bool horizontal, const core::rect< s32 > &rectangle, IGUIElement *parent=0, s32 id=-1)=0
	Adds a scrollbar.

virtual IGUIImage *	addImage (video::ITexture image, core::position2d< s32 > pos, bool useAlphaChannel=true, IGUIElement parent=0, s32 id=-1, const wchar_t *text=0)=0
	Adds an image element.

virtual IGUIImage *	addImage (const core::rect< s32 > &rectangle, IGUIElement parent=0, s32 id=-1, const wchar_t text=0, bool useAlphaChannel=true)=0
	Adds an image element.

virtual IGUICheckBox *	addCheckBox (bool checked, const core::rect< s32 > &rectangle, IGUIElement parent=0, s32 id=-1, const wchar_t text=0)=0
	Adds a checkbox element.

virtual IGUIListBox *	addListBox (const core::rect< s32 > &rectangle, IGUIElement *parent=0, s32 id=-1, bool drawBackground=false)=0
	Adds a list box element.

virtual IGUITreeView *	addTreeView (const core::rect< s32 > &rectangle, IGUIElement *parent=0, s32 id=-1, bool drawBackground=false, bool scrollBarVertical=true, bool scrollBarHorizontal=false)=0
	Adds a tree view element.

virtual IGUIMeshViewer *	addMeshViewer (const core::rect< s32 > &rectangle, IGUIElement parent=0, s32 id=-1, const wchar_t text=0)=0
	Adds a mesh viewer. Not 100% implemented yet.

virtual IGUIFileOpenDialog *	addFileOpenDialog (const wchar_t title=0, bool modal=true, IGUIElement parent=0, s32 id=-1, bool restoreCWD=false, io::path::char_type *startDir=0)=0
	Adds a file open dialog.

virtual IGUIColorSelectDialog *	addColorSelectDialog (const wchar_t title=0, bool modal=true, IGUIElement parent=0, s32 id=-1)=0
	Adds a color select dialog.

virtual IGUIStaticText *	addStaticText (const wchar_t text, const core::rect< s32 > &rectangle, bool border=false, bool wordWrap=true, IGUIElement parent=0, s32 id=-1, bool fillBackground=false)=0
	Adds a static text.

virtual IGUIEditBox *	addEditBox (const wchar_t text, const core::rect< s32 > &rectangle, bool border=true, IGUIElement parent=0, s32 id=-1)=0
	Adds an edit box.

virtual IGUISpinBox *	addSpinBox (const wchar_t text, const core::rect< s32 > &rectangle, bool border=true, IGUIElement parent=0, s32 id=-1)=0
	Adds a spin box.

virtual IGUIInOutFader *	addInOutFader (const core::rect< s32 > rectangle=0, IGUIElement parent=0, s32 id=-1)=0
	Adds an element for fading in or out.

virtual IGUITabControl *	addTabControl (const core::rect< s32 > &rectangle, IGUIElement *parent=0, bool fillbackground=false, bool border=true, s32 id=-1)=0
	Adds a tab control to the environment.

virtual IGUITab *	addTab (const core::rect< s32 > &rectangle, IGUIElement *parent=0, s32 id=-1)=0
	Adds tab to the environment.

virtual IGUIContextMenu *	addContextMenu (const core::rect< s32 > &rectangle, IGUIElement *parent=0, s32 id=-1)=0
	Adds a context menu to the environment.

virtual IGUIContextMenu *	addMenu (IGUIElement *parent=0, s32 id=-1)=0
	Adds a menu to the environment.

virtual IGUIToolBar *	addToolBar (IGUIElement *parent=0, s32 id=-1)=0
	Adds a toolbar to the environment.

virtual IGUIComboBox *	addComboBox (const core::rect< s32 > &rectangle, IGUIElement *parent=0, s32 id=-1)=0
	Adds a combo box to the environment.

virtual IGUITable *	addTable (const core::rect< s32 > &rectangle, IGUIElement *parent=0, s32 id=-1, bool drawBackground=false)=0
	Adds a table to the environment.

virtual IGUIProfiler *	addProfilerDisplay (const core::rect< s32 > &rectangle, IGUIElement *parent=0, s32 id=-1)=0
	Adds an element to display the information from the Jimcpp profiler.

virtual IGUIElementFactory *	getDefaultGUIElementFactory () const =0
	Get the default element factory which can create all built-in elements.

virtual void	registerGUIElementFactory (IGUIElementFactory *factoryToAdd)=0
	Adds an element factory to the gui environment.

virtual u32	getRegisteredGUIElementFactoryCount () const =0
	Get amount of registered gui element factories.

virtual IGUIElementFactory *	getGUIElementFactory (u32 index) const =0
	Get a gui element factory by index.

virtual IGUIElement *	addGUIElement (const c8 elementName, IGUIElement parent=0)=0
	Adds a GUI element by its name.

virtual bool	saveGUI (const io::path &filename, IGUIElement *start=0)=0
	Saves the current gui into a file.

virtual bool	saveGUI (io::IWriteFile file, IGUIElement start=0)=0
	Saves the current gui into a file.

virtual bool	loadGUI (const io::path &filename, IGUIElement *parent=0)=0
	Loads the gui. Note that the current gui is not cleared before.

virtual bool	loadGUI (io::IReadFile file, IGUIElement parent=0)=0
	Loads the gui. Note that the current gui is not cleared before.

virtual void	serializeAttributes (io::IAttributes out, io::SAttributeReadWriteOptions options=0) const =0
	Writes attributes of the gui environment.

virtual void	deserializeAttributes (io::IAttributes in, io::SAttributeReadWriteOptions options=0)=0
	Reads attributes of the gui environment.

virtual void	writeGUIElement (io::IXMLWriter writer, IGUIElement element)=0
	writes an element

virtual void	readGUIElement (io::IXMLReader reader, IGUIElement element)=0
	reads an element

virtual IGUIElement *	getNextElement (bool reverse=false, bool group=false)=0
	Find the next element which would be selected when pressing the tab-key.

virtual void	setFocusBehavior (u32 flags)=0
	Set the way the gui will handle automatic focus changes.

virtual u32	getFocusBehavior () const =0
	Get the way the gui does handle focus changes.

virtual void	addToDeletionQueue (IGUIElement *element)=0
	Adds a IGUIElement to deletion queue.

Public Member Functions inherited from jpp::IReferenceCounted
	IReferenceCounted ()
	Constructor.

virtual	~IReferenceCounted ()
	Destructor.

void	grab () const
	Grabs the object. Increments the reference counter by one.

bool	drop () const
	Drops the object. Decrements the reference counter by one.

s32	getReferenceCount () const
	Get the reference count.

const c8 *	getDebugName () const
	Returns the debug name of the object.

Additional Inherited Members
Protected Member Functions inherited from jpp::IReferenceCounted
void	setDebugName (const c8 *newName)
	Sets the debug name of the object.

Detailed Description

GUI Environment. Used as factory and manager of all other GUI elements.

This element can create the following events of type EGUI_EVENT_TYPE (which are passed on to focused sub-elements):

EGET_ELEMENT_FOCUS_LOST
EGET_ELEMENT_FOCUSED
EGET_ELEMENT_LEFT
EGET_ELEMENT_HOVERED

Member Function Documentation

◆ addButton()

virtual IGUIButton * jpp::gui::IGUIEnvironment::addButton	(	const core::rect< s32 > &	rectangle,
		IGUIElement *	parent = `0`,
		s32	id = `-1`,
		const wchar_t *	text = `0`,
		const wchar_t *	tooltiptext = `0`
	)

pure virtual

Adds a button element.

Parameters

rectangle	Rectangle specifying the borders of the button.
parent	Parent gui element of the button.
id	Id with which the gui element can be identified.
text	Text displayed on the button.
tooltiptext	Text displayed in the tooltip.

Returns: Pointer to the created button. Returns 0 if an error occurred. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ addCheckBox()

virtual IGUICheckBox * jpp::gui::IGUIEnvironment::addCheckBox	(	bool	checked,
		const core::rect< s32 > &	rectangle,
		IGUIElement *	parent = `0`,
		s32	id = `-1`,
		const wchar_t *	text = `0`
	)

pure virtual

Adds a checkbox element.

Parameters

checked	Define the initial state of the check box.
rectangle	Rectangle specifying the borders of the check box.
parent	Parent gui element of the check box.
id	Id to identify the gui element.
text	Title text of the check box.

Returns: Pointer to the created check box. Returns 0 if an error occurred. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ addColorSelectDialog()

virtual IGUIColorSelectDialog * jpp::gui::IGUIEnvironment::addColorSelectDialog	(	const wchar_t *	title = `0`,
		bool	modal = `true`,
		IGUIElement *	parent = `0`,
		s32	id = `-1`
	)

pure virtual

Adds a color select dialog.

Parameters

title	The title of the dialog.
modal	Defines if the dialog is modal. This means, that all other gui elements which were created before the dialog cannot be used until it is removed.
parent	The parent of the dialog.
id	The ID of the dialog.

Returns: Pointer to the created file open dialog. Returns 0 if an error occurred. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ addComboBox()

virtual IGUIComboBox * jpp::gui::IGUIEnvironment::addComboBox	(	const core::rect< s32 > &	rectangle,
		IGUIElement *	parent = `0`,
		s32	id = `-1`
	)

pure virtual

Adds a combo box to the environment.

Parameters

rectangle	Rectangle specifying the borders of the combo box.
parent	Parent item of the element, e.g. a window. Set it to 0 to place the combo box directly in the environment.
id	An identifier for the combo box.

Returns: Pointer to the created combo box. Returns 0 if an error occurred. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ addContextMenu()

virtual IGUIContextMenu * jpp::gui::IGUIEnvironment::addContextMenu	(	const core::rect< s32 > &	rectangle,
		IGUIElement *	parent = `0`,
		s32	id = `-1`
	)

pure virtual

Adds a context menu to the environment.

Parameters

rectangle	Rectangle specifying the borders of the menu. Note that the menu is resizing itself based on what items you add.
parent	Parent item of the element, e.g. a window. Set it to 0 to place the menu directly in the environment.
id	An identifier for the menu.

Returns: Pointer to the created context menu. Returns 0 if an error occurred. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ addEditBox()

virtual IGUIEditBox * jpp::gui::IGUIEnvironment::addEditBox	(	const wchar_t *	text,
		const core::rect< s32 > &	rectangle,
		bool	border = `true`,
		IGUIElement *	parent = `0`,
		s32	id = `-1`
	)

pure virtual

Adds an edit box.

Supports Unicode input from every keyboard around the world, scrolling, copying and pasting (exchanging data with the clipboard directly), maximum character amount, marking, and all shortcuts like ctrl+X, ctrl+V, ctrl+C, shift+Left, shift+Right, Home, End, and so on.

Parameters

text	Text to be displayed. Can be altered after creation by setText().
rectangle	Rectangle specifying the borders of the edit box.
border	Set to true if the edit box should have a 3d border.
parent	Parent item of the element, e.g. a window. Set it to 0 to place the edit box directly in the environment.
id	The ID of the element.

Returns: Pointer to the created edit box. Returns 0 if an error occurred. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ addEmptySpriteBank()

virtual IGUISpriteBank * jpp::gui::IGUIEnvironment::addEmptySpriteBank ( const io::path & name )

pure virtual

Adds an empty sprite bank to the manager.

Parameters

name	Name of the new sprite bank.

Returns: Pointer to the sprite bank. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ addFileOpenDialog()

virtual IGUIFileOpenDialog * jpp::gui::IGUIEnvironment::addFileOpenDialog	(	const wchar_t *	title = `0`,
		bool	modal = `true`,
		IGUIElement *	parent = `0`,
		s32	id = `-1`,
		bool	restoreCWD = `false`,
		io::path::char_type *	startDir = `0`
	)

pure virtual

Adds a file open dialog.

Parameters

title	Text to be displayed as the title of the dialog.
modal	Defines if the dialog is modal. This means, that all other gui elements which were created before the message box cannot be used until this messagebox is removed.
parent	Parent gui element of the dialog.
id	Id to identify the gui element.
restoreCWD	If set to true, the current working directory will be restored after the dialog is closed in some way. Otherwise the working directory will be the one that the file dialog was last showing.
startDir	Optional path for which the file dialog will be opened.

Returns: Pointer to the created file open dialog. Returns 0 if an error occurred. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ addFont()

virtual IGUIFont * jpp::gui::IGUIEnvironment::addFont	(	const io::path &	name,
		IGUIFont *	font
	)

pure virtual

Adds an externally loaded font to the font list.

This method allows to attach an already loaded font to the list of existing fonts. The font is grabbed if non-null and adding was successful.

Parameters

name	Name the font should be stored as.
font	Pointer to font to add.

Returns: Pointer to the font stored. This can differ from given parameter if the name previously existed.

◆ addGUIElement()

virtual IGUIElement * jpp::gui::IGUIEnvironment::addGUIElement	(	const c8 *	elementName,
		IGUIElement *	parent = `0`
	)

pure virtual

Adds a GUI element by its name.

Each factory is checked if it can create an element of the given name. The first match will be created.

Parameters

elementName	Name of the element to be created.
parent	Parent of the new element, if not 0.

Returns: New GUI element, or 0 if no such element exists.

◆ addImage() [1/2]

virtual IGUIImage * jpp::gui::IGUIEnvironment::addImage	(	const core::rect< s32 > &	rectangle,
		IGUIElement *	parent = `0`,
		s32	id = `-1`,
		const wchar_t *	text = `0`,
		bool	useAlphaChannel = `true`
	)

pure virtual

Adds an image element.

Use IGUIImage::setImage later to set the image to be displayed.

Parameters

rectangle	Rectangle specifying the borders of the image.
parent	Parent gui element of the image.
id	Id to identify the gui element.
text	Title text of the image (not displayed).
useAlphaChannel	Sets if the image should use the alpha channel of the texture to draw itself.

Returns: Pointer to the created image element. Returns 0 if an error occurred. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ addImage() [2/2]

virtual IGUIImage * jpp::gui::IGUIEnvironment::addImage	(	video::ITexture *	image,
		core::position2d< s32 >	pos,
		bool	useAlphaChannel = `true`,
		IGUIElement *	parent = `0`,
		s32	id = `-1`,
		const wchar_t *	text = `0`
	)

pure virtual

Adds an image element.

Parameters

image	Image to be displayed.
pos	Position of the image. The width and height of the image is taken from the image.
useAlphaChannel	Sets if the image should use the alpha channel of the texture to draw itself.
parent	Parent gui element of the image.
id	Id to identify the gui element.
text	Title text of the image (not displayed).

Returns: Pointer to the created image element. Returns 0 if an error occurred. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ addInOutFader()

virtual IGUIInOutFader * jpp::gui::IGUIEnvironment::addInOutFader	(	const core::rect< s32 > *	rectangle = `0`,
		IGUIElement *	parent = `0`,
		s32	id = `-1`
	)

pure virtual

Adds an element for fading in or out.

Parameters

rectangle	Rectangle specifying the borders of the fader. If the pointer is NULL, the whole screen is used.
parent	Parent item of the element, e.g. a window.
id	An identifier for the fader.

Returns: Pointer to the created in-out-fader. Returns 0 if an error occurred. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ addListBox()

virtual IGUIListBox * jpp::gui::IGUIEnvironment::addListBox	(	const core::rect< s32 > &	rectangle,
		IGUIElement *	parent = `0`,
		s32	id = `-1`,
		bool	drawBackground = `false`
	)

pure virtual

Adds a list box element.

Parameters

rectangle	Rectangle specifying the borders of the list box.
parent	Parent gui element of the list box.
id	Id to identify the gui element.
drawBackground	Flag whether the background should be drawn.

Returns: Pointer to the created list box. Returns 0 if an error occurred. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ addMenu()

virtual IGUIContextMenu * jpp::gui::IGUIEnvironment::addMenu	(	IGUIElement *	parent = `0`,
		s32	id = `-1`
	)

pure virtual

Adds a menu to the environment.

This is like the menu you can find on top of most windows in modern graphical user interfaces.

Parameters

parent	Parent item of the element, e.g. a window. Set it to 0 to place the menu directly in the environment.
id	An identifier for the menu.

Returns: Pointer to the created menu. Returns 0 if an error occurred. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ addMeshViewer()

virtual IGUIMeshViewer * jpp::gui::IGUIEnvironment::addMeshViewer	(	const core::rect< s32 > &	rectangle,
		IGUIElement *	parent = `0`,
		s32	id = `-1`,
		const wchar_t *	text = `0`
	)

pure virtual

Adds a mesh viewer. Not 100% implemented yet.

Parameters

rectangle	Rectangle specifying the borders of the mesh viewer.
parent	Parent gui element of the mesh viewer.
id	Id to identify the gui element.
text	Title text of the mesh viewer.

Returns: Pointer to the created mesh viewer. Returns 0 if an error occurred. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ addMessageBox()

virtual IGUIWindow * jpp::gui::IGUIEnvironment::addMessageBox	(	const wchar_t *	caption,
		const wchar_t *	text = `0`,
		bool	modal = `true`,
		s32	flags = `EMBF_OK`,
		IGUIElement *	parent = `0`,
		s32	id = `-1`,
		video::ITexture *	image = `0`
	)

pure virtual

Adds a message box.

Parameters

caption	Text to be displayed the title of the message box.
text	Text to be displayed in the body of the message box.
modal	Defines if the dialog is modal. This means, that all other gui elements which were created before the message box cannot be used until this messagebox is removed.
flags	Flags specifying the layout of the message box using EMESSAGE_BOX_FLAG. Create a message box with an OK and CANCEL button for example with (EMBF_OK \| EMBF_CANCEL).
parent	Parent gui element of the message box.
id	Id with which the gui element can be identified.
image	Optional texture which will be displayed beside the text as an image

Returns: Pointer to the created message box. Returns 0 if an error occurred. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ addModalScreen()

virtual IGUIElement * jpp::gui::IGUIEnvironment::addModalScreen	(	IGUIElement *	parent,
		int	blinkMode = `3`
	)

pure virtual

Adds a modal screen.

Input focus stays with children of the modal screen. If you have some window x which should keep the input focus you do something like: addModalScreen()->addChild(x). And x will then get the focus and not lose it anymore. The modal screen removes itself when it no longer has any children. Note that it usually works badly to pass the modal screen already as parent when creating a new element. It's better to add that new element later to the modal screen with addChild.

Parameters

parent	Parent gui element of the modal.
blinkMode	Bitset of when to blink (can be combined) 0 = never 1 = focus changes 2 = Left mouse button pressed down

Returns: Pointer to the created modal. Returns 0 if an error occurred. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ addProfilerDisplay()

virtual IGUIProfiler * jpp::gui::IGUIEnvironment::addProfilerDisplay	(	const core::rect< s32 > &	rectangle,
		IGUIElement *	parent = `0`,
		s32	id = `-1`
	)

pure virtual

Adds an element to display the information from the Jimcpp profiler.

Parameters

rectangle	Rectangle specifying the borders of the element.
parent	Parent of the element. When 0 the environment itself will be the parent.
id	An identifier for the element.

◆ addScrollBar()

virtual IGUIScrollBar * jpp::gui::IGUIEnvironment::addScrollBar	(	bool	horizontal,
		const core::rect< s32 > &	rectangle,
		IGUIElement *	parent = `0`,
		s32	id = `-1`
	)

pure virtual

Adds a scrollbar.

Parameters

horizontal	Specifies if the scroll bar is drawn horizontal or vertical.
rectangle	Rectangle specifying the borders of the scrollbar.
parent	Parent gui element of the scroll bar.
id	Id to identify the gui element.

Returns: Pointer to the created scrollbar. Returns 0 if an error occurred. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ addSpinBox()

virtual IGUISpinBox * jpp::gui::IGUIEnvironment::addSpinBox	(	const wchar_t *	text,
		const core::rect< s32 > &	rectangle,
		bool	border = `true`,
		IGUIElement *	parent = `0`,
		s32	id = `-1`
	)

pure virtual

Adds a spin box.

An edit box with up and down buttons

Parameters

text	Text to be displayed. Can be altered after creation by setText().
rectangle	Rectangle specifying the borders of the spin box.
border	Set to true if the spin box should have a 3d border.
parent	Parent item of the element, e.g. a window. Set it to 0 to place the spin box directly in the environment.
id	The ID of the element.

Returns: Pointer to the created spin box. Returns 0 if an error occurred. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ addStaticText()

virtual IGUIStaticText * jpp::gui::IGUIEnvironment::addStaticText	(	const wchar_t *	text,
		const core::rect< s32 > &	rectangle,
		bool	border = `false`,
		bool	wordWrap = `true`,
		IGUIElement *	parent = `0`,
		s32	id = `-1`,
		bool	fillBackground = `false`
	)

pure virtual

Adds a static text.

Parameters

text	Text to be displayed. Can be altered after creation by SetText().
rectangle	Rectangle specifying the borders of the static text
border	Set to true if the static text should have a 3d border.
wordWrap	Enable if the text should wrap into multiple lines.
parent	Parent item of the element, e.g. a window.
id	The ID of the element.
fillBackground	Enable if the background shall be filled. Defaults to false.

Returns: Pointer to the created static text. Returns 0 if an error occurred. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ addTab()

virtual IGUITab * jpp::gui::IGUIEnvironment::addTab	(	const core::rect< s32 > &	rectangle,
		IGUIElement *	parent = `0`,
		s32	id = `-1`
	)

pure virtual

Adds tab to the environment.

You can use this element to group other elements. This is not used for creating tabs on tab controls, please use IGUITabControl::addTab() for this instead.

Parameters

rectangle	Rectangle specifying the borders of the tab.
parent	Parent item of the element, e.g. a window. Set it to 0 to place the tab directly in the environment.
id	An identifier for the tab.

Returns: Pointer to the created tab. Returns 0 if an error occurred. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ addTabControl()

virtual IGUITabControl * jpp::gui::IGUIEnvironment::addTabControl	(	const core::rect< s32 > &	rectangle,
		IGUIElement *	parent = `0`,
		bool	fillbackground = `false`,
		bool	border = `true`,
		s32	id = `-1`
	)

pure virtual

Adds a tab control to the environment.

Parameters

rectangle	Rectangle specifying the borders of the tab control.
parent	Parent item of the element, e.g. a window. Set it to 0 to place the tab control directly in the environment.
fillbackground	Specifies if the background of the tab control should be drawn.
border	Specifies if a flat 3d border should be drawn. This is usually not necessary unless you place the control directly into the environment without a window as parent.
id	An identifier for the tab control.

Returns: Pointer to the created tab control element. Returns 0 if an error occurred. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ addTable()

virtual IGUITable * jpp::gui::IGUIEnvironment::addTable	(	const core::rect< s32 > &	rectangle,
		IGUIElement *	parent = `0`,
		s32	id = `-1`,
		bool	drawBackground = `false`
	)

pure virtual

Adds a table to the environment.

Parameters

rectangle	Rectangle specifying the borders of the table.
parent	Parent item of the element, e.g. a window. Set it to 0 to place the element directly in the environment.
id	An identifier for the table.
drawBackground	Flag whether the background should be drawn.

Returns: Pointer to the created table. Returns 0 if an error occurred. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ addToDeletionQueue()

virtual void jpp::gui::IGUIEnvironment::addToDeletionQueue ( IGUIElement * element )

pure virtual

Adds a IGUIElement to deletion queue.

Queued elements will be removed at the end of each drawAll call. Or latest in the destructor of the GUIEnvironment. This can be used to allow an element removing itself safely in a function iterating over gui elements, like an overloaded IGUIElement::draw or IGUIElement::OnPostRender function. Note that in general just calling IGUIElement::remove() is enough. Unless you create your own GUI elements removing themselves you won't need it.

Parameters

element Element to remove

◆ addToolBar()

virtual IGUIToolBar * jpp::gui::IGUIEnvironment::addToolBar	(	IGUIElement *	parent = `0`,
		s32	id = `-1`
	)

pure virtual

Adds a toolbar to the environment.

It is like a menu that is always placed on top of its parent, and contains buttons.

Parameters

parent	Parent item of the element, e.g. a window. Set it to 0 to place the tool bar directly in the environment.
id	An identifier for the tool bar.

Returns: Pointer to the created tool bar. Returns 0 if an error occurred. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ addTreeView()

virtual IGUITreeView * jpp::gui::IGUIEnvironment::addTreeView	(	const core::rect< s32 > &	rectangle,
		IGUIElement *	parent = `0`,
		s32	id = `-1`,
		bool	drawBackground = `false`,
		bool	scrollBarVertical = `true`,
		bool	scrollBarHorizontal = `false`
	)

pure virtual

Adds a tree view element.

Parameters

rectangle	Position and dimension of list box.
parent	Parent gui element of the list box.
id	Id to identify the gui element.
drawBackground	Flag whether the background should be drawn.
scrollBarVertical	Flag whether a vertical scrollbar should be used
scrollBarHorizontal	Flag whether a horizontal scrollbar should be used

Returns: Pointer to the created list box. Returns 0 if an error occurred. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ addWindow()

virtual IGUIWindow * jpp::gui::IGUIEnvironment::addWindow	(	const core::rect< s32 > &	rectangle,
		bool	modal = `false`,
		const wchar_t *	text = `0`,
		IGUIElement *	parent = `0`,
		s32	id = `-1`
	)

pure virtual

Adds an empty window element.

Parameters

rectangle	Rectangle specifying the borders of the window.
modal	Defines if the dialog is modal. This means, that all other gui elements which were created before the window cannot be used until it is removed.
text	Text displayed as the window title.
parent	Parent gui element of the window.
id	Id with which the gui element can be identified.

Returns: Pointer to the created window. Returns 0 if an error occurred. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ createImageList()

virtual IGUIImageList * jpp::gui::IGUIEnvironment::createImageList	(	video::ITexture *	texture,
		core::dimension2d< s32 >	imageSize,
		bool	useAlphaChannel
	)

pure virtual

Creates the image list from the given texture.

Parameters

texture	Texture to split into images
imageSize	Dimension of each image
useAlphaChannel	Flag whether alpha channel of the texture should be honored.

Returns: Pointer to the font. Returns 0 if the font could not be loaded. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ createSkin()

virtual IGUISkin * jpp::gui::IGUIEnvironment::createSkin ( EGUI_SKIN_TYPE type )

pure virtual

Creates a new GUI Skin based on a template.

Use setSkin() to set the created skin.

Parameters

type	The type of the new skin.

Returns: Pointer to the created skin. If you no longer need it, you should call IGUISkin::drop(). See IReferenceCounted::drop() for more information.

◆ drawAll()

virtual void jpp::gui::IGUIEnvironment::drawAll ( bool useScreenSize = true )

pure virtual

Draws all gui elements by traversing the GUI environment starting at the root node.

Parameters

When	true ensure the GuiEnvironment (aka the RootGUIElement) has the same size as the current driver screensize. Can be set to false to control that size yourself, p.E when not the full size should be used for UI.

◆ getBuiltInFont()

virtual IGUIFont * jpp::gui::IGUIEnvironment::getBuiltInFont ( ) const

pure virtual

Returns the default built-in font.

Returns: Pointer to the default built-in font. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ getDefaultGUIElementFactory()

virtual IGUIElementFactory * jpp::gui::IGUIEnvironment::getDefaultGUIElementFactory ( ) const

pure virtual

Get the default element factory which can create all built-in elements.

Returns: Pointer to the factory. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ getFileSystem()

virtual io::IFileSystem * jpp::gui::IGUIEnvironment::getFileSystem ( ) const

pure virtual

Returns the file system.

Returns: Pointer to the file system.

◆ getFocus()

virtual IGUIElement * jpp::gui::IGUIEnvironment::getFocus ( ) const

pure virtual

Returns the element which holds the focus.

Returns: Pointer to the element with focus.

◆ getFocusBehavior()

virtual u32 jpp::gui::IGUIEnvironment::getFocusBehavior ( ) const

pure virtual

Get the way the gui does handle focus changes.

Returns: A bitmask which is a combination of EFOCUS_FLAG flags.

◆ getFont()

virtual IGUIFont * jpp::gui::IGUIEnvironment::getFont ( const io::path & filename )

pure virtual

Returns pointer to the font with the specified filename.

Loads the font if it was not loaded before.

Parameters

filename Filename of the Font.

Returns: Pointer to the font. Returns 0 if the font could not be loaded. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ getGUIElementFactory()

virtual IGUIElementFactory * jpp::gui::IGUIEnvironment::getGUIElementFactory ( u32 index ) const

pure virtual

Get a gui element factory by index.

Parameters

index Index of the factory.

Returns: Factory at given index, or 0 if no such factory exists.

◆ getHovered()

virtual IGUIElement * jpp::gui::IGUIEnvironment::getHovered ( ) const

pure virtual

Returns the element which was last under the mouse cursor.

NOTE: This information is updated after the user-eventreceiver received it's mouse-events. To find the hovered element while catching mouse events you have to use instead: IGUIEnvironment::getRootGUIElement()->getElementFromPoint(mousePos);

Returns: Pointer to the element under the mouse.

◆ getNextElement()

virtual IGUIElement * jpp::gui::IGUIEnvironment::getNextElement	(	bool	reverse = `false`,
		bool	group = `false`
	)

pure virtual

Find the next element which would be selected when pressing the tab-key.

If you set the focus for the result you can manually force focus-changes like they would happen otherwise by the tab-keys.

Parameters

reverse	When true it will search backward (toward lower TabOrder numbers, like shift+tab)
group	When true it will search for the next tab-group (like ctrl+tab)

◆ getOSOperator()

virtual IOSOperator * jpp::gui::IGUIEnvironment::getOSOperator ( ) const

pure virtual

returns a pointer to the OS operator

Returns: Pointer to the OS operator.

◆ getRegisteredGUIElementFactoryCount()

virtual u32 jpp::gui::IGUIEnvironment::getRegisteredGUIElementFactoryCount ( ) const

pure virtual

Get amount of registered gui element factories.

Returns: Amount of registered gui element factories.

◆ getRootGUIElement()

virtual IGUIElement * jpp::gui::IGUIEnvironment::getRootGUIElement ( )

pure virtual

Returns the root gui element.

This is the first gui element, the (direct or indirect) parent of all other gui elements. It is a valid IGUIElement, with dimensions the same size as the screen.

Returns: Pointer to the root element of the GUI. The returned pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ getSkin()

virtual IGUISkin * jpp::gui::IGUIEnvironment::getSkin ( ) const

pure virtual

Returns pointer to the current gui skin.

Returns: Pointer to the GUI skin.

◆ getSpriteBank()

virtual IGUISpriteBank * jpp::gui::IGUIEnvironment::getSpriteBank ( const io::path & filename )

pure virtual

Returns pointer to the sprite bank which was added with addEmptySpriteBank.

TODO: This should load files in the future, but not implemented so far.

Parameters

filename Name of a spritebank added with addEmptySpriteBank

Returns: Pointer to the sprite bank. Returns 0 if it could not be loaded. This pointer should not be dropped. See IReferenceCounted::drop() for more information.

◆ getVideoDriver()

virtual video::IVideoDriver * jpp::gui::IGUIEnvironment::getVideoDriver ( ) const

pure virtual

Returns the current video driver.

Returns: Pointer to the video driver.

◆ hasFocus()

virtual bool jpp::gui::IGUIEnvironment::hasFocus	(	const IGUIElement *	element,
		bool	checkSubElements = `false`
	)		const

pure virtual

Returns whether the element has focus.

Parameters

element	Pointer to the element which is tested.
checkSubElements	When true and focus is on a sub-element of element then it will still count as focused and return true

Returns: True if the element has focus, else false.

◆ loadGUI() [1/2]

virtual bool jpp::gui::IGUIEnvironment::loadGUI	(	const io::path &	filename,
		IGUIElement *	parent = `0`
	)

pure virtual

Loads the gui. Note that the current gui is not cleared before.

When a parent is set the elements will be added below the parent, the parent itself does not deserialize. When the file contains skin-settings from the gui-environment those are always serialized into the guienvironment independent of the parent setting.

Parameters

filename	Name of the file.
parent	Parent for the loaded GUI, root if 0.

Returns: True if loading succeeded, else false.

◆ loadGUI() [2/2]

virtual bool jpp::gui::IGUIEnvironment::loadGUI	(	io::IReadFile *	file,
		IGUIElement *	parent = `0`
	)

pure virtual

Loads the gui. Note that the current gui is not cleared before.

When a parent is set the elements will be added below the parent, the parent itself does not deserialize. When the file contains skin-settings from the gui-environment those are always serialized into the guienvironment independent of the parent setting.

Parameters

file	The file to load from.
parent	Parent for the loaded GUI, root if 0.

Returns: True if loading succeeded, else false.

◆ postEventFromUser()

virtual bool jpp::gui::IGUIEnvironment::postEventFromUser ( const SEvent & event )

pure virtual

Posts an input event to the environment.

Usually you do not have to use this method, it is used by the engine internally.

Parameters

event The event to post.

Returns: True if succeeded, else false.

◆ registerGUIElementFactory()

virtual void jpp::gui::IGUIEnvironment::registerGUIElementFactory ( IGUIElementFactory * factoryToAdd )

pure virtual

Adds an element factory to the gui environment.

Use this to extend the gui environment with new element types which it should be able to create automatically, for example when loading data from xml files.

Parameters

factoryToAdd Pointer to new factory.

◆ removeFocus()

virtual bool jpp::gui::IGUIEnvironment::removeFocus ( IGUIElement * element )

pure virtual

Removes the focus from an element.

Causes a EGET_ELEMENT_FOCUS_LOST event. If the event is absorbed then the focus will not be changed.

Parameters

element Pointer to the element which shall lose the focus.

Returns: True on success, false on failure

◆ saveGUI() [1/2]

virtual bool jpp::gui::IGUIEnvironment::saveGUI	(	const io::path &	filename,
		IGUIElement *	start = `0`
	)

pure virtual

Saves the current gui into a file.

Parameters

filename	Name of the file.
start	The GUIElement to start with. Root if 0.

Returns: True if saving succeeded, else false.

◆ saveGUI() [2/2]

virtual bool jpp::gui::IGUIEnvironment::saveGUI	(	io::IWriteFile *	file,
		IGUIElement *	start = `0`
	)

pure virtual

Saves the current gui into a file.

Parameters

file	The file to write to.
start	The GUIElement to start with. Root if 0.

Returns: True if saving succeeded, else false.

◆ setFocus()

virtual bool jpp::gui::IGUIEnvironment::setFocus ( IGUIElement * element )

pure virtual

Sets the focus to an element.

Causes a EGET_ELEMENT_FOCUS_LOST event followed by a EGET_ELEMENT_FOCUSED event. If someone absorbed either of the events, then the focus will not be changed.

Parameters

element Pointer to the element which shall get the focus.

Returns: True on success, false on failure

◆ setFocusBehavior()

virtual void jpp::gui::IGUIEnvironment::setFocusBehavior ( u32 flags )

pure virtual

Set the way the gui will handle automatic focus changes.

The default is (EFF_SET_ON_LMOUSE_DOWN | EFF_SET_ON_TAB). with the left mouse button. This does not affect the setFocus function itself - users can still call that whenever they want on any element.

Parameters

flags A bitmask which is a combination of EFOCUS_FLAG flags.

◆ setSkin()

virtual void jpp::gui::IGUIEnvironment::setSkin ( IGUISkin * skin )

pure virtual

Sets a new GUI Skin.

You can use this to change the appearance of the whole GUI Environment. You can set one of the built-in skins or implement your own class derived from IGUISkin and enable it using this method. To set for example the built-in Windows classic skin, use the following code:

gui::IGUISkin* newskin = environment->createSkin(gui::EGST_WINDOWS_CLASSIC);
environment->setSkin(newskin);
newskin->drop();

Parameters

skin	New skin to use.

◆ setUserEventReceiver()

virtual void jpp::gui::IGUIEnvironment::setUserEventReceiver ( IEventReceiver * evr )

pure virtual

This sets a new event receiver for gui events.

Usually you do not have to use this method, it is used by the engine internally.

Parameters

evr	Pointer to the new receiver.

The documentation for this class was generated from the following file:

include/jimcpp/core/engine/IGUIEnvironment.hpp

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ addButton()

◆ addCheckBox()

◆ addColorSelectDialog()

◆ addComboBox()

◆ addContextMenu()

◆ addEditBox()

◆ addEmptySpriteBank()

◆ addFileOpenDialog()

◆ addFont()

◆ addGUIElement()

◆ addImage() [1/2]

◆ addImage() [2/2]

◆ addInOutFader()

◆ addListBox()

◆ addMenu()

◆ addMeshViewer()

◆ addMessageBox()

◆ addModalScreen()

◆ addProfilerDisplay()

◆ addScrollBar()

◆ addSpinBox()

◆ addStaticText()

◆ addTab()

◆ addTabControl()

◆ addTable()

◆ addToDeletionQueue()

◆ addToolBar()

◆ addTreeView()

◆ addWindow()

◆ createImageList()

◆ createSkin()

◆ drawAll()

◆ getBuiltInFont()

◆ getDefaultGUIElementFactory()

◆ getFileSystem()

◆ getFocus()

◆ getFocusBehavior()

◆ getFont()

◆ getGUIElementFactory()

◆ getHovered()

◆ getNextElement()

◆ getOSOperator()

◆ getRegisteredGUIElementFactoryCount()

◆ getRootGUIElement()

◆ getSkin()

◆ getSpriteBank()

◆ getVideoDriver()

◆ hasFocus()

◆ loadGUI() [1/2]

◆ loadGUI() [2/2]

◆ postEventFromUser()

◆ registerGUIElementFactory()

◆ removeFocus()

◆ saveGUI() [1/2]

◆ saveGUI() [2/2]

◆ setFocus()

◆ setFocusBehavior()

◆ setSkin()

◆ setUserEventReceiver()