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

Edit box with an asociated item-menu. More...

Inheritance diagram for os::DropdownMenu:

List of all members.

Public Member Functions
	DropdownMenu (const Rect &cFrame, const String &cName, uint32 nResizeMask=CF_FOLLOW_LEFT|CF_FOLLOW_TOP, uint32 nFlags=WID_WILL_DRAW|WID_FULL_UPDATE_ON_RESIZE)
	DropdownMenu constructor.
	~DropdownMenu ()
void	SetEnable (bool bEnable=true)
bool	IsEnabled () const
void	SetReadOnly (bool bFlag=true)
	Change the "read-only" status.
bool	GetReadOnly () const
	Returns the read-only status.
void	AppendItem (const String &cString)
	Add a item to the end of the drop down list.
void	InsertItem (int nPosition, const String &cString)
	Insert and item at a given position.
bool	DeleteItem (int nPosition)
	Delete a item.
int	GetItemCount () const
	Get the item count.
void	Clear ()
	Delete all items.
const String &	GetItem (int nItem) const
	Get one of the item strings.
int	GetSelection () const
	Get the current selection.
void	SetSelection (int nItem, bool bNotify=true)
	Set current selection.
const String &	GetCurrentString () const
void	SetCurrentString (const String &cString)
void	SetMinPreferredSize (int nWidthChars)
int	GetMinPreferredSize () const
void	SetMaxPreferredSize (int nWidthChars)
int	GetMaxPreferredSize () const
void	SetSelectionMessage (Message *pcMsg)
	Set the message that will be sendt when the selection changes.
Message *	GetSelectionMessage () const
	Get a pointer to the current "SelectionChanged" message.
void	SetSendIntermediateMsg (bool bFlag)
bool	GetSendIntermediateMsg () const
void	SetEditMessage (Message *pcMsg)
	Set the message sendt when the user changes the content of the edit box.
Message *	GetEditMessage () const
	Get a pointer to the current "SelectionChanged" message.
virtual void	HandleMessage (Message *pcMessage)
	Handle events from sub components.
virtual void	Paint (const Rect &cUpdateRect)
	Called by the system update "damaged" areas of the view.
virtual Point	GetPreferredSize (bool bLargest) const
virtual void	FrameSized (const Point &cDelta)
	Virtual hook called by the system when the view is resized.
virtual void	MouseDown (const Point &cPosition, uint32 nButtons)
	Hook called by the system when a mouse button is pressed.
virtual void	KeyDown (const char *pzString, const char *pzRawString, uint32 nQualifiers)
	Hook called by the system when a key is pressed while the view has focus.
virtual void	AllAttached ()
virtual void	Activated (bool bIsActive)
	Hook called when the view gain or loose focus.
virtual void	SetTabOrder (int nOrder=NEXT_TAB_ORDER)
	Set the keyboard manouvering sorting order.
virtual void	WheelMoved (const Point &cDelta)
	Hook called by the system when the scroll-wheel is rotated.
Friends
class	DropdownView
class	DropdownTextView
Classes
class	DropdownTextView
class	DropdownTextView
class	DropdownView
class	DropdownView

---

Detailed Description

Description:

See also:

TextView, Invoker

Author:

Kurt Skauen ([email protected])

---

Constructor & Destructor Documentation

DropdownMenu::DropdownMenu	(	const Rect &	cFrame,
		const String &	cName,
		uint32	nResizeMask = CF_FOLLOW_LEFT | CF_FOLLOW_TOP,
		uint32	nFlags = WID_WILL_DRAW | WID_FULL_UPDATE_ON_RESIZE
	)

Parameters:

	cFrame	- The size and position of the edit box and it's associated button.
	pzName	- The identifier passed down to the Handler class (Never rendered)
	nResizeMask	- Flags deskribing which edge follows edges of the parent when the parent is resized (Se View::View())
	nFlags	- Various flags passed to the View::View() constructor.

See also:

os::View, os::Invoker

Author:

Kurt Skauen ([email protected])

DropdownMenu::~DropdownMenu

(

)

---

Member Function Documentation

void DropdownMenu::SetEnable

(

bool

bEnable = true

)

bool DropdownMenu::IsEnabled

(

)

const

void DropdownMenu::SetReadOnly

(

bool

bFlag = true

)

Description:

When the DropdownMenu is set in read-only mode the user will not be able to edit the contents of the edit box. It will also make the menu open when the user click inside the edit box.

Parameters:

bFlag

- Is true the menu will be read-only, if false it will be read/write.

See also:

GetReadOnly()

Author:

Kurt Skauen ([email protected])

bool DropdownMenu::GetReadOnly

(

)

const

Returns:

true if read only, false if read/write.

See also:

SetReadOnly()

Author:

Kurt Skauen ([email protected])

void DropdownMenu::AppendItem

(

const String &

cString

)

Parameters:

cString

- The string to be appended

See also:

InsertItem(), DeleteItem(), GetItemCount(), GetItem()

Author:

Kurt Skauen ([email protected])

void DropdownMenu::InsertItem	(	int	nPosition,
		const String &	cString
	)

: The new item is inserted before the nPosition'th item.

Parameters:

	nPosition	- Zero based index of the item to insert the string in front of
	pzString	- The string to be insert

See also:

AppendItem(), DeleteItem(), GetItemCount(), GetItem()

Author:

Kurt Skauen ([email protected])

bool DropdownMenu::DeleteItem

(

int

nPosition

)

Description:

Delete the item at the given position

Parameters:

nPosition

- The zero based index of the item to delete.

Returns:

true if an item was deleted, false if the index was out of range.

See also:

AppendItem(), InsertItem(), GetItemCount(), GetItem()

Author:

Kurt Skauen ([email protected])

int DropdownMenu::GetItemCount

(

)

const

Returns:

The number of items in the menu

See also:

GetItem(), AppendItem(), InsertItem(), DeleteItem()

Author:

Kurt Skauen ([email protected])

void DropdownMenu::Clear

(

)

Description:

Delete all the items in the menu

Parameters:

nPosition

- The zero based index of the item to delete.

Returns:

true if an item was deleted, false if the index was out of range.

See also:

AppendItem(), InsertItem(), GetItemCount(), GetItem()

Author:

Kurt Skauen ([email protected])

const String & DropdownMenu::GetItem

(

int

nItem

)

const

Description:

Returns one of the items encapsulated in a stl string.

Parameters:

nItem

- Zero based index of the item to return.

Returns:

const reference to an stl string containing the item string

See also:

GetItemCount(), AppendItem(), InsertItem(), DeleteItem()

Author:

Kurt Skauen ([email protected])

int DropdownMenu::GetSelection

(

)

const

Returns:

The index of the selected item, or -1 if no item is selected.

See also:

SetSelection(), SetSelectionMessage()

Author:

Kurt Skauen ([email protected])

void DropdownMenu::SetSelection	(	int	nItem,
		bool	bNotify = true
	)

Description:

The given item will be highlighted when the menu is opened and the item will be copyed into the edit box. If the bNotify parameter is true and the selection differs from the currend the "SelectionMessage" (see SetSelectionMessage()) will be sendt to the target set by SetTarget().

Parameters:

	nItem	- The new selection
	bNotify	- If true a notification will be sendt if the new selection differ from the current.

See also:

GetSelection(), SetSelectionMessage(), GetSelectionMessage(), Invoker::SetTarget()

Author:

Kurt Skauen ([email protected])

const String & DropdownMenu::GetCurrentString

(

)

const

void DropdownMenu::SetCurrentString

(

const String &

cString

)

void DropdownMenu::SetMinPreferredSize

(

int

nWidthChars

)

int DropdownMenu::GetMinPreferredSize

(

)

const

void DropdownMenu::SetMaxPreferredSize

(

int

nWidthChars

)

int DropdownMenu::GetMaxPreferredSize

(

)

const

void DropdownMenu::SetSelectionMessage

(

Message *

pcMsg

)

Description:

When the selection is changed eighter by the user or by calling SetSelection() with bNotify = true, the DropdownMenu() will clone off the message set with SetSelectionMessage() and send it to it's target by calling Invoker::Invoke().

Before sending the message the two fields "final" and "selection" are added. "final" is a boolean that is true when the user select (click's on) an item from the menu, or if the event was triggered by SetSelection(). "final" is false when the event was triggered by the user moving the mouse over the menu. "selection" is an int32 that contain the new selection.

In addition to those fields comes the fields added by Invoker::Invoke().

If pcMsg is NULL no event will be triggered by changing the selection.

Note:

The DropdownMenu overtake the ownership of the message. You should not delete or reference the message after SetSelectionMessage() returns.

Parameters:

pcMsg

- The message to be sendt when selection changes.

See also:

GetSelectionMessage(), SetEditMessage(), Invoker::SetTarget()

Author:

Kurt Skauen ([email protected])

Message * DropdownMenu::GetSelectionMessage

(

)

const

Description:

Return the pointer last set by SetSelectionMessage() or NULL if no message is assigned. If you change the message the changes will be reflected in the following "SelectionChanged" events.

Note:

The message is still owned by the DropdownMenu. You should not delete it.

Returns:

Pointer to the internel "SelectionChanged" message.

See also:

SetSelectionMessage(), Invoker::SetTarget()

Author:

Kurt Skauen ([email protected])

void DropdownMenu::SetSendIntermediateMsg

(

bool

bFlag

)

bool DropdownMenu::GetSendIntermediateMsg

(

)

const

void DropdownMenu::SetEditMessage

(

Message *

pcMsg

)

Description:

The message is sendt everytime the user changes the content of the edit box. Before the message is sendt a boolean member called "final" is added. This member is false when the user is typing into the edit box, and true for the last message sendt when the user hits <ENTER>.

The content of the edit box is not automatically copyed into the item-list. If you f.eks. want to add a new entry to the item list each time the user change the string and hits <ENTER>, you must listen to this message and read out the string with GetCurrentString() and add it to the list with AppendItem() or InsertItem() each time you receive a message with the "final" member equal "true".

Note:

The DropdownMenu overtake the ownership of the message. You should not delete or reference the message after SetSelectionMessage() returns.

Parameters:

pcMsg

- The message to be sendt when the edit box changes.

See also:

GetEditMessage(), SetSelectionMessage(), Invoker::SetTarget(), Invoker::Invoke()

Author:

Kurt Skauen ([email protected])

Message * DropdownMenu::GetEditMessage

(

)

const

Description:

Return the pointer last set by SetEditMessage() or NULL if no message is assigned. If you change the message the changes will be reflected in the following events sendt when the edit box is changed.

Note:

The message is still owned by the DropdownMenu. You should not delete is

Returns:

Pointer to the internel "string-changed" message.

See also:

SetSelectionMessage(), Invoker::SetTarget()

Author:

Kurt Skauen ([email protected])

void DropdownMenu::HandleMessage

(

Message *

pcMessage

)

[virtual]

Description:

DropdownMenu overloads Handler::HandleMessage() to be able to comunicate with it's sub components.

See also:

Handler::HandleMessage()

Author:

Kurt Skauen ([email protected])

Reimplemented from os::Handler.

void DropdownMenu::Paint

(

const Rect &

cUpdateRect

)

[virtual]

Description:

Note:

Warning:

Parameters:

cUpdateRect

A rectangle enclosing all damaged areas. This is just a rough "worst-case", further fine-grained clipping will be performed by the Application Server to avoid updating non-damaged pixels and make the update as fast and flicker-free as possible.

See also:

Invalidate(), Flush()

Author:

Kurt Skauen ([email protected])

Reimplemented from os::View.

Point DropdownMenu::GetPreferredSize

(

bool

bLargest

)

const [virtual]

Reimplemented from os::View.

void DropdownMenu::FrameSized

(

const Point &

cDelta

)

[virtual]

Description:

Overload this member if you need to know when the view is resized.

Note:

This member is called after the view is resized. If you need the old size you can subtract the cDelta calue from the current size.

Parameters:

cDelta

The distance the bottom/right corner was moved relative to the upper/left corner.

See also:

FrameMoved(), SetFrame, ResizeBy(), ResizeTo()

Author:

Kurt Skauen ([email protected])

Reimplemented from os::View.

void DropdownMenu::MouseDown	(	const Point &	cPosition,
		uint32	nButtons
	)			[virtual]

Description:

This member is called from the window thread whenever a mouse button is clicked above the view. You can overload this member if your view need to know about mouse-down events.

A view will not automatically take focus when clicked so if you want that behaviour you must call MakeFocus() from an overloaded version of this member.

The default implementation of this member will call MouseDown() on it's parent view if one exists.

Parameters:

	cPosition	Mouse position in the views coordinate system at the time the mouse was pressed.
	nButtons	Index of the pressed button. Buttons start at 1 for the left button, 2 for the right button, 3 for the middle button. Additional buttons might be supported by the mouse driver and will then be assigned numbers from 4 and up.

See also:

MouseUp(), MouseMove(), WheelMoved()

Author:

Kurt Skauen ([email protected])

Reimplemented from os::View.

void DropdownMenu::KeyDown	(	const char *	pzString,
		const char *	pzRawString,
		uint32	nQualifiers
	)			[virtual]

Description:

Overload this member if your view need to handle keyboard input. This member is called to allow the view to handle M_KEY_DOWN messages. The most common members are exctracted from the message and passed as parameters but you might need to obtain the raw message with os::Looper::GetCurrentMessage() and find some members yourself if you the data you needed are not passed in.

For example if you need the raw key-code for the pressed key you will have to lookup the "_raw_key" member from the message.

Parameters:

	pzString	String containing a single UTF-8 encoded character. This is the character generated by the pressed key according to the current keymap accounting for any qualifiers that might be pressed.
	pzRawString	Same as pzString except that the key is converted without accounting for qualifiers. Ie. if 'A' is pressed while pressing <SHIFT> pzString will contain 'A' and pzRawString will contain 'a'.
	nQualifiers	Bitmask describing which qualifiers that was active when the key was pressed.

See also:

KeyUp(), os::Looper::GetCurrentMessage()

Author:

Kurt Skauen ([email protected])

Reimplemented from os::View.

void DropdownMenu::AllAttached

(

)

[virtual]

Reimplemented from os::View.

void DropdownMenu::Activated

(

bool

bIsActive

)

[virtual]

Description:

This is a callback member that can be overloaded by derived classes to learn when the view is activated and when it is deactivated. The bIsActive parameter tell whether the focus was lost or gained.

The view has focus when it is the active view in the active window.

Note:

This is a hook function that is called by the system to notify about an event. You should never call this member yourself.

The window is locked when this member is called.

Parameters:

bIsActive

- true if the view gain and false if it loose focus.

See also:

MakeFocus(), WindowActivated()

Author:

Kurt Skauen ([email protected])

Reimplemented from os::View.

void DropdownMenu::SetTabOrder

(

int

nOrder = NEXT_TAB_ORDER

)

[virtual]

Description:

Set the value that will be returned by GetTabOrder().

Parameters:

nOrder

- The sorting order.

See also:

GetTabOrder()

Author:

Kurt Skauen ([email protected])

Reimplemented from os::View.

void DropdownMenu::WheelMoved

(

const Point &

cDelta

)

[virtual]

Description:

This member is called from the window thread whenever the user rotates the scroll wheel with the mouse pointer above this view.

The default implementation of this member will call WheelMoved() on it's parent view if one exists.

Since:

V0.3.7

Parameters:

cDelta

Delta movement. Normally only the y value is used but it is possible for the mouse driver to also support horizontal scroll wheel functionality. The delta value is normally +/- 1.0 for each "click" on the wheel.

See also:

MouseMove(), MouseDown(), MouseUp()

Author:

Kurt Skauen ([email protected])

Reimplemented from os::View.

---

Friends And Related Function Documentation

friend class DropdownView [friend]

friend class DropdownTextView [friend]

---