omgui::ComboBox Class Reference

#include <omgui/combobox.h>

Detailed Description

A ComboBox is a control that provides a dropdown list from which the user can select a single item. The list is composed of strings and can additionally contain an image beside each string. The list can be automatically sorted, or can remain unsorted. A ComboBox can also be editable, which allows the user to type in a string they want for their selection even if the string does not exist in the list of choices.


Public Types
typedef omgui::api::ComboBox	api_type
typedef omgui::event_traits < Widget >	event_traits
typedef ComboBoxInitializer	Initializer
Public Member Functions
void	add_ref ()
	Increments the reference count for this Widget.
void	append (const ComboBoxItem &item, bool select=false)
void	clear ()
void	clear_selection ()
omgui::Connection	connect (event_id event, SlotBase *slot, int priority=SIGNAL_PRIORITY_NORMAL)
	Connects an event using this Widget's object_id. Calls omgui::Manager::connect with supplied arguments.
void	destroy ()
	Destroys this widget freeing all resources.
void	disable ()
void	enable (bool e)
	Enables or disables the widget. Disabled widgets cannot recieve user input.
void *	get_handle () const
object_id	get_id () const
api_type *	get_impl () const
ComboBoxItem	get_item (int index) const
int	get_item_count () const
omgui::Size	get_max_size () const
	Returns the maximum size of the Widget. A value of 0 for width or height indicates that there is no maximum size in that direction.
omgui::Size	get_min_size () const
	Returns the minimum size of the Widget. A value of 0 for width or height indicates that there is no minimum size in that direction.
omgui::Size	get_natural_size () const
Pointer< Panel >	get_parent () const
Pointer< Window >	get_parent_window () const
omgui::Point	get_position () const
omgui::Rect	get_rect () const
ComboBoxItem	get_selected_item () const
int	get_selection () const
omgui::Size	get_size () const
string	get_text () const
void	hide ()
void	insert (const ComboBoxItem &item, int index, bool select=false)
bool	is_editable () const
bool	is_enabled () const
	Determines whether or not the widget is enabled. If any of a widget's parents are disabled, the widget is considered disabled.
bool	is_hidden () const
	Returns whether or not this Widget has been hidden.
bool	is_shown () const
	Returns whether or not the Widget is visible on the screen. If the Widget and all of its parent Widgets are not hidden then the Widget is shown.
bool	is_sorted () const
void	prepend (const ComboBoxItem &item, bool select=false)
void	release ()
	Decrements the reference count for this Widget. Once the count reaches 0 the Widget will be deleted.
void	remove (int index)
void	set_max_size (const omgui::Size &s)
	Sets the maximum size of the widget. A value of 0 for width or height indicates that there is no maximum size in that direction.
void	set_min_size (const omgui::Size &s)
	Sets the minimum size of the Widget. A value of 0 for width or height indicates that there is no minimum size in that direction. If the Widget's current size is less than the newly specified minimum size, the object will be resized so that its size is equal to the newly specified minimum size.
void	set_natural_size (const omgui::Size &s)
void	set_position (const omgui::Point &p)
	Sets the position of a widget. If the widget is a TopLevel widget, the position value is in screen coordinates, otherwise it is client coordinates.
void	set_rect (const omgui::Rect &r)
	Sets both the position and the size of the widget. If the widget is a TopLevel widget, the value is in screen coordinates, otherwise it is client coordinates.
void	set_selection (int index)
void	set_size (const omgui::Size &s)
	Sets the absolute size of this widget. If the widget is a TopLevel widget, the value is in screen coordinates, otherwise it is client coordinates.
void	show (bool show=true, bool focus=false)
	Shows or hides a widget.
Static Public Member Functions
static Pointer< ComboBox >	create (const Initializer &initializer, object_id id=OBJECT_ID_ANY)
Protected Member Functions
	ComboBox (object_id id, api_type *impl)
	ComboBox (object_id id)
void	initialize (const Initializer &initializer)
	Constructs the native widget using the given initializer.
Private Attributes
api_type *	m_impl

Member Typedef Documentation

typedef omgui::api::ComboBox omgui::ComboBox::api_type

Reimplemented from omgui::Widget.

typedef omgui::event_traits<Widget> omgui::Widget::event_traits [inherited]

Reimplemented in omgui::Button, omgui::Notebook, omgui::TextWidget, and omgui::Window.

typedef ComboBoxInitializer omgui::ComboBox::Initializer

Constructor & Destructor Documentation

omgui::ComboBox::ComboBox ( object_id id ) [protected]

omgui::ComboBox::ComboBox	(	object_id	id,
		api_type *	impl
	)			`[protected]`

Member Function Documentation

void Widget::add_ref ( ) [virtual, inherited]

Increments the reference count for this Widget.

Implements omgui::RefCountable.

void omgui::ComboBox::append	(	const ComboBoxItem &	item,
		bool	select = `false`
	)

Appends an item to the end of the ComboBox list. If the ComboBox is sorted, the item will end up in its sorted position within the list.

Parameters:

	item	The ComboBoxItem to append
	select	If true, changes the selection to the new item

void omgui::ComboBox::clear ( )

Removes all items from the ComboBox and clears the current selection. Additionally, for an editable ComboBox, the contents of the editable area will be cleared.

void omgui::ComboBox::clear_selection ( )

Clears the current selection, if any. If the ComboBox is editable, this will also clear any custom text.

omgui::Connection Widget::connect	(	event_id	event,
		SlotBase *	slot,
		int	priority = `SIGNAL_PRIORITY_NORMAL`
	)			`[inherited]`

Connects an event using this Widget's object_id. Calls omgui::Manager::connect with supplied arguments.

Pointer< ComboBox > omgui::ComboBox::create	(	const Initializer &	initializer,
		object_id	id = `OBJECT_ID_ANY`
	)			`[static]`

Creates a ComboBox

void Widget::destroy ( ) [inherited]

Destroys this widget freeing all resources.

void Widget::disable ( ) [inherited]

void Widget::enable ( bool e ) [inherited]

Enables or disables the widget. Disabled widgets cannot recieve user input.

void * Widget::get_handle ( ) const [inherited]

Returns:: A native handle for the widget. This value is returned as a void*, and how you use this value is dependant on the port you are working with. For win32, simply casting the return value to a HWND is sufficient.

Todo:: Casting a pointer type to a type that isn't a pointer may not work under all circumstances

object_id omgui::Object::get_id ( ) const [inherited]

Returns:: This object's unique identifier

Reimplemented in omgui::MenuItem.

ComboBox::api_type * omgui::ComboBox::get_impl ( ) const

Reimplemented from omgui::Widget.

ComboBoxItem omgui::ComboBox::get_item ( int index ) const

Returns the ComboBoxItem at the given index.

Note:: Changing the members of the returned ComboBoxItem will not updated the contents of the ComboBox.

Returns:: The ComboBoxItem at the given index

Todo:: Should this method throw std::out_of_range or an omgui::exception when index is invalid?

int omgui::ComboBox::get_item_count ( ) const

Returns:: The number of ComboBoxItems in this ComboBox

omgui::Size Widget::get_max_size ( ) const [inherited]

Returns the maximum size of the Widget. A value of 0 for width or height indicates that there is no maximum size in that direction.

Returns:: Maximum size of the widget.

omgui::Size Widget::get_min_size ( ) const [inherited]

Returns the minimum size of the Widget. A value of 0 for width or height indicates that there is no minimum size in that direction.

Returns:: Minimum size of the widget.

omgui::Size Widget::get_natural_size ( ) const [inherited]

Returns:: Natural size of the widget. The natural size is used by layout managers to determine how large to make widgets which are not expanded. Unless a natural size is explicitly specified by a call to set_natural_size or through an inintializer, this value is a calculated value and can vary from widget to widget and from port to port.

Pointer< Panel > Widget::get_parent ( ) const [inherited]

This function returns the parent Panel of this Widget. In the case where this Widget is the Content Panel of a Window, this function will return an empty pointer.

Returns:: The parent of this widget

Pointer< Window > Widget::get_parent_window ( ) const [inherited]

This function returns the Window which this Widget is either directly or indirectly a child of. In the case where this Widget is a Window, this function returns the owner Window, or an empty pointer if the Window is unowned.

Returns:: The Window which contains this widget.

omgui::Point Widget::get_position ( ) const [inherited]

Returns:: Position of the widget. If the widget is a TLW TLW, the position is in screen coordinates. Otherwise, the position is in client coordinates.

omgui::Rect Widget::get_rect ( ) const [inherited]

Returns:: Position and Size of this widget as a rectangle.

ComboBoxItem omgui::ComboBox::get_selected_item ( ) const

Returns the ComboBoxItem corepsonding to the current selection. If there is no current selection, an exception is thrown.

Note:: Changing the members of the returned ComboBoxItem will not updated the contents of the ComboBox. To do this, see

Returns:: The ComboBoxItem for the current selection

int omgui::ComboBox::get_selection ( ) const

Returns the index of the current selection. If there is no selection, -1 is returned. An editable ComboBox is considered to have no selection if the user has entered text that does not corespond with a ComboBoxItem.

Returns:: The index of the current selection, or -1 if there is no selection.

omgui::Size Widget::get_size ( ) const [inherited]

Returns:: Absolute size of the widget

string omgui::ComboBox::get_text ( ) const

Returns the text currently displayed by the ComboBox. For editable ComboBoxes, this is the text, possibly entered by the user with no corresponding ComboBoxItem, displayed in the EntryBox. For non editable ComboBoxes, this is the text of the currently selected item.

Returns:: The text currently displayed by the ComboBox

void Widget::hide ( ) [inherited]

void omgui::ComboBox::initialize ( const Initializer & initializer ) [protected]

Constructs the native widget using the given initializer.

void omgui::ComboBox::insert	(	const ComboBoxItem &	item,
		int	index,
		bool	select = `false`
	)

Inserts an item at the specified index into the ComboBox list. If the ComboBox is sorted, the item will end up in its sorted position within the list.

Parameters:

	item	The ComboBoxItem to insert
	index	The position to insert the item. An index value of 0 will insert at the front of the list.
	select	If true, changes the selection to the new item

bool omgui::ComboBox::is_editable ( ) const

Returns:: Whether the ComboBox is editable

bool Widget::is_enabled ( ) const [inherited]

Determines whether or not the widget is enabled. If any of a widget's parents are disabled, the widget is considered disabled.

Returns:: Whether or not the widget is enabled

bool Widget::is_hidden ( ) const [inherited]

Returns whether or not this Widget has been hidden.

If show(true) has been called the Widget is considered not to be hidden. If show(false) or hide() have been called the Widget is considered hidden. A Widget is also considered hidden if it was created without specifying show in its initializer. The hidden state of the parent Widget has no effect on the hidden state of this Widget.

Note:: The return value is not equivilant to !is_shown().

Todo:: Implement for gtk2 and cocoa

bool Widget::is_shown ( ) const [inherited]

Returns whether or not the Widget is visible on the screen. If the Widget and all of its parent Widgets are not hidden then the Widget is shown.

Note:: The return value is not equivilant to !is_hidden().

Todo:: Verify the newly documented behavior for this function on gtk2 and cocoa ports

bool omgui::ComboBox::is_sorted ( ) const

Returns:: Whether the ComboBox list is sorted

void omgui::ComboBox::prepend	(	const ComboBoxItem &	item,
		bool	select = `false`
	)

Prepends an item to the beginning of the ComboBox list. If the ComboBox is sorted, the item will end up in its sorted position within the list.

Parameters:

	item	The ComboBoxItem to preappend
	select	If true, changes the selection to the new item

void Widget::release ( ) [virtual, inherited]

Decrements the reference count for this Widget. Once the count reaches 0 the Widget will be deleted.

Implements omgui::RefCountable.

void omgui::ComboBox::remove ( int index )

Removes an item from the ComboBox list at the given position.

Todo:: Should this method throw std::out_of_range or an omgui::exception when index is invalid?

void Widget::set_max_size ( const omgui::Size & s ) [inherited]

Sets the maximum size of the widget. A value of 0 for width or height indicates that there is no maximum size in that direction.

If the Widget's current size is greater than the newly specified maximum size, the object will be resized so that its size is equal to the newly specified maximum size.

void Widget::set_min_size ( const omgui::Size & s ) [inherited]

Sets the minimum size of the Widget. A value of 0 for width or height indicates that there is no minimum size in that direction. If the Widget's current size is less than the newly specified minimum size, the object will be resized so that its size is equal to the newly specified minimum size.

If a child of this Widget has a minimum size larger than the minimum size of this Widget, the minimum size of this Widget will be effectively equal to the minimum size of that child Widget. This has an important implication for Windows and their content panels. If a Window has a minimum size of X, and a Panel A with minimum size Y > X is specified as the Window's content panel, the minimum content size of the Window is effectively Y. If a new Panel B with minimum size Z < Y is specified as the Window's content panel, the effective minimum content size for the window will be Y.

If an Widget is specified with a minimum size that is larger than the Widgets maximum size, or if a maximum size is later specified which is smaller than an existing minimum size, the minimum size will always take precedence over the maximal size. A minimum size of (100,100) and a maximal size of (50,50) results in a minimum size of (100,100) and a maximum size of (100,100). If the minimum size is later changed to (25,25), the maximum size is again (50,50) and the minimum size is (25,25). This case also applies to Window's and their content panels. A content panel's minimum size always takes precedence over a Window's maximum content size.

void Widget::set_natural_size ( const omgui::Size & s ) [inherited]

Sets the natural size for this widget. The natural size is used by layout managers to determine how large to make widgets which are not expanded. The default natural size has a width and height of 0, which means that an acceptible natural size will be calculated for the width and height. You can override the calculated value by specifying your own value for the width and or height.

void Widget::set_position ( const omgui::Point & p ) [inherited]

Sets the position of a widget. If the widget is a TopLevel widget, the position value is in screen coordinates, otherwise it is client coordinates.

void Widget::set_rect ( const omgui::Rect & r ) [inherited]

Sets both the position and the size of the widget. If the widget is a TopLevel widget, the value is in screen coordinates, otherwise it is client coordinates.

void omgui::ComboBox::set_selection ( int index )

Sets the current selection

Todo:: Should this method throw std::out_of_range or an omgui::exception when index is invalid?

void Widget::set_size ( const omgui::Size & s ) [inherited]

Sets the absolute size of this widget. If the widget is a TopLevel widget, the value is in screen coordinates, otherwise it is client coordinates.

If the size value specified is smaller than the minimum size or larger than the maximum size, the size value actually set will be equal to the minimum size or maximum size respectively.

void Widget::show	(	bool	show = `true`,
		bool	focus = `false`
	)			`[inherited]`

Shows or hides a widget.

Note:: If this widget is a Panel which is currently functioning as a NotebookPage, this function will have no effect. Panel's which are NotebookPages are shown and hidden by the Notebook itself.

Reimplemented in omgui::TopLevel.

Member Data Documentation

api_type* omgui::ComboBox::m_impl [private]

Reimplemented from omgui::Widget.

omgui::ComboBox Class Reference

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Private Attributes

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation