Collapse all Symbian^3 Application Developer Library

RSat::TMenuItemBaseV1 Class Reference

class RSat::TMenuItemBaseV1 : public RSat::TSatPCmdBase

Base class for menu item based classes.

The SET UP MENU and SELECT ITEM proactive commands both provide menus that are displayed to the user. When the user chooses one of the menu's options, you should tell the UICC which option was chosen.

In Symbian OS versions before 9.2, the proactive command contains menus in classes derived from RSat::TMenuItemBaseV1 . For SET UP MENU they are RSat::TSetUpMenuV1 , RSat::TSetUpMenuV2 etc. For SELECT ITEM these classes are RSat::TSelectItemV1 , RSat::TSelectItemV2 etc.

In Symbian OS version 9.2, the proactive command contains menus in classes derived from RSat::TMenuItemBaseV5 which itself derives from RSat::TMenuItemBaseV1 .

The description of the SET UP MENU and SELECT ITEM commands describes how to display the menu and what to do when the user makes a selection; see RSat::NotifySetUpMenuPCmd() and RSat::NotifySelectItemPCmd() .

RSat::TMenuItemBaseV1 provides methods to add and get the menu items, to return the number of items, and to get a description of the menu's content. RSat::TMenuItemBaseV5 extends the functionality provided by RSat::TMenuItemBaseV1 by providing methods that allow items with text attributes to be added and retrieved.

To read menu items:

Firstly, if you have received a SET UP MENU proactive command, call RSat::TMenuItemBaseV1::IsRemoveMenu() . If it returns ETrue then the SET UP MENU command does not contain a menu. Instead, the command indicates you should remove the menu provided by the previous command. (Note that the SELECT ITEM proactive command always contains a menu; there is no need to call RSat::TMenuItemBaseV1::IsRemoveMenu() .

If RSat::TMenuItemBaseV1::IsRemoveMenu() returns EFalse then the command contains a menu that replaces the previous menu. Find out how many items are in the menu by calling RSat::TMenuItemBaseV1::NumberOfItems()

Now call RSat::TMenuItemBaseV1::MenuContent() to find out about the menu items. All the items in each menu will have some text and an identifier. In some menus, items may have "text attributes", "next item indicators" and/or an icons.

Finally call RSat::TMenuItemBaseV1::GetItem() and RSat::TMenuItemBaseV1::GetItemIcon() for each item. These methods require an index number from 1 to X, where X is the number of items. Choose the appropriate version of GetItem() or GetItemIcon() to get the information you require. For Symbian OS version 9.2, it is also possible to call RSat::TMenuItemBaseV5::GetItem() and RSat::TMenuItemBaseV5::GetItemIcon() to get menu item information if the items contain text attributes.

RSat::TMenuItemBaseV5

Inherits from

RSat::TMenuItemBaseV1
- RSat::TSatPCmdBase
  - RSat::TSatBase

Public Member Functions
	TMenuItemBaseV1 ()
IMPORT_C TInt	AddItem (const TItem &)
IMPORT_C TInt	AddItem (const TItem &, TUint )
IMPORT_C TInt	AddItem (const TItem &, TUint , TUint )
IMPORT_C TInt	AddItemIcon (const TItem &, TUint )
IMPORT_C TInt	GetItem ( TUint , TItem &)
IMPORT_C TInt	GetItem ( TUint , TItem &, TInt &)
IMPORT_C TInt	GetItem ( TUint , TItem &, TInt &, TInt &)
IMPORT_C TInt	GetItemIcon ( TUint , TItem &, TInt &)
IMPORT_C TBool	IsRemoveMenu ()
IMPORT_C TInt	MenuContent ()
IMPORT_C TUint	NumberOfItems ()
IMPORT_C void	Reset ()

Protected Member Functions
TInt	FindItemInBuffer ( TUint , TInt &)

Inherited Functions
	RSat::TSatBase::ExtensionId()const
	RSat::TSatBase::TSatBase()
	RSat::TSatPCmdBase::PCmdNumber()const
	RSat::TSatPCmdBase::SetPCmdNumber(TUint8)
	RSat::TSatPCmdBase::TSatPCmdBase()

Protected Member Enumerations
enum	TBitMask { KLowerByte = 0x00FF, KUpperByte = 0xFF00 }
enum	TMenuItemHeader { KItemHeader = 0xAA00, KActionHeader = 0xBB00, KIconIdHeader = 0xCC00, KItemWithTextAttributeHeader = 0xDD00 }

Protected Attributes
TItemList	iBuf
TUint8	iMenuContent
TUint	iNumberOfItems

Inherited Attributes
	RSat::TSatBase::iExtensionId
	RSat::TSatPCmdBase::iPCmdNumber

Constructor & Destructor Documentation

TMenuItemBaseV1()

IMPORT_C

TMenuItemBaseV1

(

)

Default constructor.

Member Functions Documentation

AddItem(const TItem &)

IMPORT_C TInt

AddItem

(

const TItem &

aItem

)

This method adds a menu item to iBuf, which contains the menu item list. It is not needed by RSat clients, only the TSY.

Parameters

const TItem & aItem

Item to be added to iBuf.

AddItem(const TItem &, TUint)

IMPORT_C TInt	AddItem	(	const TItem &	aItem,
			TUint	aAction
		)

This method is an overloaded method of AddItem(TItem aItem) It adds the menu item next action as well as the specified menu item. It is not needed by RSat clients, only the TSY.

Parameters

const TItem & aItem	Item to be added to iBuf.
TUint aAction	Action associated with an item that is to be added to iBuf.

AddItem(const TItem &, TUint, TUint)

IMPORT_C TInt	AddItem	(	const TItem &	aItem,
			TUint	aAction,
			TUint	aIconId
		)

This method is an overloaded method of AddItem(TItem aItem) It adds the menu item next action and icon ID as well as the specified menu item It is not needed by RSat clients, only the TSY.

Parameters

const TItem & aItem	Item to be added to iBuf.
TUint aAction	Action associated with an item that is to be added to iBuf.
TUint aIconId	Icon identifier, associated with aItem, to be added to iBuf.

AddItemIcon(const TItem &, TUint)

IMPORT_C TInt	AddItemIcon	(	const TItem &	aItem,
			TUint	aIconId
		)

This method is an overloaded method of AddItem(TItem aItem) It adds the menu item icon ID as well as the specified menu item. It is not needed by RSat clients, only the TSY.

Parameters

const TItem & aItem	Item to be added to iBuf.
TUint aIconId	Icon identifier, associated with aItem, to be added to iBuf.

FindItemInBuffer(TUint, TInt &)

TInt	FindItemInBuffer	(	TUint	aIndex,
			TInt &	aOffset
		)	const [protected]

This method finds the position of the item designated by aIndex in iBuf (which contains the menu item list) The position of the item is returned in aOffset.

Actions and icons are optional, so the buffer could only be made of items or items&actions or items&icons or items&actions&icons.

In all of the above mentioned menu structures, the items themselves can consist of only the item text string or the item text string and associated text attribute information. If an item with text attributes is added to the menu, then all subsequent items must also contain text attribute information.

The structure of the buffer is as follows:

         |-------------|--------|------|--
 | item header | itemid | item | item header
 |-------------|--------|------|--

         |-------------|--------|------|---------------|--------|--
 | item header | itemid | item | action header | action | item header
 |-------------|--------|------|---------------|--------|--

         |-------------|--------|------|----------------|---------|--
 | item header | itemid | item | icon ID header | icon ID | item header
 |-------------|--------|------|----------------|---------|--

         |-------------|--------|------|---------------|--------|----------------|---------|--
 | item header | itemid | item | action header | action | icon ID header | icon ID | item header
 |-------------|--------|------|---------------|--------|----------------|---------|--

         In Symbian OS v9.2, support for these structures was added:

         |---------------------------------|--------|---------------------|------|-------
 | item with text attribute header | itemid | item text attribute | item | item with text attribute header
 |---------------------------------|--------|---------------------|------|-------

         |---------------------------------|--------|---------------------|------|---------------|--------|--
 | item with text attribute header | itemid | item text attribute | item | action header | action | item with text attribute header
 |---------------------------------|--------|---------------------|------|---------------|--------|--

         |---------------------------------|--------|---------------------|------|----------------|---------|--
 | item with text attribute header | itemid | item text attribute | item | icon ID header | icon ID | item with text attribute header
 |---------------------------------|--------|---------------------|------|----------------|---------|--

         |---------------------------------|--------|---------------------|------|---------------|--------|----------------|---------|--
 | item with text attribute header | itemid | item text attribute | item | action header | action | icon ID header | icon ID | item with text attribute header
 |---------------------------------|--------|---------------------|------|---------------|--------|----------------|---------|--

The header is two bytes:

the first byte is a tag corresponding to the associated object (item, action or icon).
the second byte is the length of the associated object.

Parameters

TUint aIndex	Index of the item to be found in the buffer.
TInt & aOffset	Position of the item in iBuf (offset from the start of iBuf).

GetItem(TUint, TItem &)

IMPORT_C TInt	GetItem	(	TUint	aIndex,
			TItem &	aItem
		)	const

This method returns the menu item, designated by aIndex.

Parameters

TUint aIndex	Index of the menu item. Index range starts at 1. RSat::TMenuItemBaseV1::NumberOfItems() returns the total number of items.
TItem & aItem	Item from the menu, designated by aIndex.

GetItem(TUint, TItem &, TInt &)

IMPORT_C TInt	GetItem	(	TUint	aIndex,
			TItem &	aItem,
			TInt &	aAction
		)	const

This method is an overloaded method of RSat::TMenuItemBaseV1::GetItem(TUint aIndex, TItem& aItem). It returns the menu item's "next action indicator" (if available) as well as the menu item itself. RSat::TMenuItemBaseV1::MenuContent() tells you whether a menu's items are accompanied by "next action indicators".

Parameters

TUint aIndex	Index of the menu item. Index range starts at 1. RSat::TMenuItemBaseV1::NumberOfItems() returns the total number of items.
TItem & aItem	Item from the menu, designated by aIndex.
TInt & aAction	Action associated with the item.

GetItem(TUint, TItem &, TInt &, TInt &)

IMPORT_C TInt	GetItem	(	TUint	aIndex,
			TItem &	aItem,
			TInt &	aAction,
			TInt &	aIconId
		)	const

This method is an overloaded method of RSat::TMenuItemBaseV1::GetItem(TUint aIndex, TItem& aItem). It returns the menu item's "next action indicator" and icon identifier (if they are available) as well as the requested menu item. RSat::TMenuItemBaseV1::MenuContent() tells you whether a menu's items are accompanied by icon identifiers and "next action indicators".

Parameters

TUint aIndex	Index of the menu item. Index range starts at 1. RSat::TMenuItemBaseV1::NumberOfItems() returns the total number of items.
TItem & aItem	Item from the menu, designated by aIndex.
TInt & aAction	Action associated with the item.
TInt & aIconId	Icon associated with the menu item.

GetItemIcon(TUint, TItem &, TInt &)

IMPORT_C TInt	GetItemIcon	(	TUint	aIndex,
			TItem &	aItem,
			TInt &	aIconId
		)	const

This method is an overloaded method of RSat::TMenuItemBaseV1::GetItem(TUint aIndex, TItem& aItem). It returns the menu item's icon identifier (if available) as well as the menu item itself. RSat::TMenuItemBaseV1::MenuContent() tells you whether a menu's items are accompanied by icon identifier.

Parameters

TUint aIndex	Index of the menu item. Index range starts at 1. RSat::TMenuItemBaseV1::NumberOfItems() returns the total number of items.
TItem & aItem	Item from the menu, designated by aIndex.
TInt & aIconId	Icon associated with the menu item.

IsRemoveMenu()

IMPORT_C TBool

IsRemoveMenu

(

)

const

This method returns ETrue if the SET UP MENU proactive command specifies that the existing SAT menu should be removed.

This method returns EFalse if the SET UP MENU proactive command specifies a new SAT menu to be added to the phone's menu system.

RSat::TMenuItemBaseV1 is used to contain both SET UP MENU and SELECT ITEM proactive commands. However, only call this method when handling a SET UP MENU command.

MenuContent()

IMPORT_C TInt

MenuContent

(

)

const

This method describes the menu's content by returning four flags. All menus contain a number of items which may also have an associated text attribute. Items are indicated by the RSat::KItems flag. The presence of text attribute information for these items is indicated by the RSat::KItemTextAttributes flag.

In addition, every item in a menu may be accompanied by an icon (indicated by RSat::KItemIconIds ) and/or a "next action indicator" ( RSat::KItemNextActions ).

In a menu, either ALL menu items will have an icon, or NONE of them will. Similarly, all menu items in a menu will also have text attribute information or none of them will. Also, all menu items in a menu will have a "next action indicator" or none of them will.

NumberOfItems()

IMPORT_C TUint

NumberOfItems

(

)

const

This method returns the number of items in the menu.

Reset()

IMPORT_C void

Reset

(

)

This method sets the iBuf length and content to zero. It is not needed by RSat clients, only the TSY.

Member Enumerations Documentation

Enum TBitMask

Enumerators

KLowerByte = 0x00FF
KUpperByte = 0xFF00

Enum TMenuItemHeader

Enumerators

KItemHeader = 0xAA00
KActionHeader = 0xBB00
KIconIdHeader = 0xCC00
KItemWithTextAttributeHeader = 0xDD00

Member Data Documentation

TItemList iBuf

TItemList

iBuf

[protected]

TUint8 iMenuContent

TUint8

iMenuContent

[protected]

TUint iNumberOfItems

TUint

iNumberOfItems

[protected]