flexlib :: library Documentation | All Packages | All Classes | Index | Frames No Frames |
PopUpMenuButtonBase

Package | flexlib.baseClasses
Class | public class PopUpMenuButtonBase
Inheritance | PopUpMenuButtonBase mx.controls.PopUpButton
Subclasses | ScrollablePopUpMenuButton

PopUpMenuButtonBase is a copy/paste version of the original PopUpMenuButton class in the Flex framework.

The only modifications made to this class were to change some properties and methods from private to protected so we can override them in a subclass.

The PopUpMenuButton control creates a PopUpButton control with a main sub-button and a secondary sub-button. Clicking on the secondary (right) sub-button drops down a menu that can be popluated through a `dataProvider` property. Unlike the Menu and MenuBar controls, the PopUpMenuButton control supports only a single-level menu. This means that the menu cannot contain cascading submenus.

The main sub-button of the PopUpMenuButton control can have a text label, an icon, or both on its face. When a user selects an item from the drop-down menu or clicks the main button of the PopUpMenuButton control, the control dispatches an `itemClick` event. When a user clicks the main button of the control, the control also dispatches a `click` event. You can customize the look of a PopUpMenuButton control.

The PopUpMenuButton control has the following sizing characteristics:

Characteristic | Description
--- | ---
Default size | Sufficient to accommodate the label and any icon on the main button, and the icon on the pop-up button. The control does not reserve space for the menu.
Minimum size | 0 pixels.
Maximum size | 10000 by 10000.

MXML Syntax Show MXML Syntax
Hide MXML Syntax

The `<mx:PopUpMenuButton>` tag inherits all of the tag attributes of its superclass, and adds the following tag attributes:

      <mx:PopUpMenuButton
        Properties
        dataDescriptor="instance of DefaultDataDescriptor"
        dataProvider="undefined"
        iconField="icon"
        iconFunction="undefined"
        labelField="label"
        labelFunction="undefined"
        showRoot="false|true"

        Event
        change=No default
      />

See also

mx.controls.Menu
mx.controls.MenuBar

Public Properties

| Property | Defined By
--- | --- | ---
|  | dataDescriptor : IMenuDataDescriptor The data descriptor accesses and manipulates data in the data provider. | PopUpMenuButtonBase
|  | dataProvider : Object DataProvider for popUpMenu. | PopUpMenuButtonBase
|  | iconField : String Name of the field in the dataProvider Array that contains the icon to show for each menu item. | PopUpMenuButtonBase
|  | iconFunction : Function A function that determines the icon to display for each menu item. | PopUpMenuButtonBase
|  | labelField : String Name of the field in the dataProvider Array that contains the text to show for each menu item. | PopUpMenuButtonBase
|  | labelFunction : Function A function that determines the text to display for each menu item. | PopUpMenuButtonBase
|  | popUp : IUIComponent [override] [write-only] A reference to the pop-up Menu object. | PopUpMenuButtonBase
|  | showRoot : Boolean Specifies whether to display the top-level node or nodes of the data provider. | PopUpMenuButtonBase

Public Methods

| Method | Defined By
--- | --- | ---
|  | PopUpMenuButtonBase() Constructor. | PopUpMenuButtonBase

Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | itemClick | Dispatched when a user selects an item from the pop-up menu. | PopUpMenuButtonBase

Styles

| Style | Description | Defined By
--- | --- | --- | ---
|  | popUpStyleName | Type: String CSS Inheritance: no The name of a CSS style declaration used by the dropdown menu. This property allows you to control the appearance of the dropdown menu. The default value sets the `fontWeight` to `normal` and the `textAlign` to `left`. The default value is`"popUpMenu"`. | PopUpMenuButtonBase

Property Detail

dataDescriptor | property

`dataDescriptor:IMenuDataDescriptor`

The data descriptor accesses and manipulates data in the data provider.

When you specify this property as an attribute in MXML, you must use a reference to the data descriptor, not the string name of the descriptor. Use the following format for the property:

    <mx:PopUpMenuButton id="menubar" dataDescriptor="{new MyCustomDataDescriptor()}"/>

Alternatively, you can specify the property in MXML as a nested subtag, as the following example shows:

    <mx:PopUpMenuButton>
          <mx:dataDescriptor>
             <myCustomDataDescriptor>
          </mx:dataDescriptor>
          ...

The default value is an internal instance of the DefaultDataDescriptor class.

Implementation
`public function get dataDescriptor():IMenuDataDescriptor`
`public function set dataDescriptor(value:IMenuDataDescriptor):void`

dataProvider | property |

`dataProvider:Object`

DataProvider for popUpMenu.

The default value is `null`.

This property can be used as the source for data binding.

Implementation
`public function get dataProvider():Object`
`public function set dataProvider(value:Object):void`

iconField | property |

`iconField:String`

Name of the field in the `dataProvider` Array that contains the icon to show for each menu item. The `iconFunction` property, if set, overrides this property.

The renderers will look in the data provider object for a property of the name supplied as the iconField. If the value of the property is a Class, it will instantiate that class and expect it to be an instance of an IFlexDisplayObject. If the value of the property is a String, it will look to see if a Class exists with that name in the application, and if it can't find one, it will also look for a property on the document with that name and expect that property to map to a Class.

If the data provider is an E4X XML object, you must set this property explicitly; for example, use @icon to specify the `icon` attribute.

The default value is `"icon"`.

This property can be used as the source for data binding.

Implementation
`public function get iconField():String`
`public function set iconField(value:String):void`

iconFunction | property |

`iconFunction:Function`

A function that determines the icon to display for each menu item. If you omit this property, Flex uses the contents of the field or attribute determined by the `iconField` property. If you specify this property, Flex ignores any `iconField` property value. By default the menu does not try to display icons with the text in the rows. However, by specifying an icon function, you can specify a Class for a graphic that will be created and displayed as an icon in the row.

The iconFunction takes a single argument which is the item in the data provider and returns a Class.

The default value is `null`.

Implementation
`public function get iconFunction():Function`
`public function set iconFunction(value:Function):void`

labelField | property |

`labelField:String`

Name of the field in the `dataProvider` Array that contains the text to show for each menu item. The `labelFunction` property, if set, overrides this property. If the data provider is an Array of Strings, Flex uses each String value as the label. If the data provider is an E4X XML object, you must set this property explicitly; for example, use @label to specify the `label` attribute.

The default value is `"label"`.

This property can be used as the source for data binding.

Implementation
`public function get labelField():String`
`public function set labelField(value:String):void`

labelFunction | property |

`labelFunction:Function`

A function that determines the text to display for each menu item. If you omit this property, Flex uses the contents of the field or attribute determined by the `labelField` property. If you specify this property, Flex ignores any `labelField` property value.

If you specify this property, the label function must find the appropriate field or fields and return a displayable string. The `labelFunction` property is good for handling formatting and localization.

The label function must take a single argument which is the item in the dataProvider and return a String.

The default value is `null`.

Implementation
`public function get labelFunction():Function`
`public function set labelFunction(value:Function):void`

popUp | property |

`popUp:IUIComponent` [write-only] [override]

A reference to the pop-up Menu object.

This property is read-only, and setting it has no effect. Set the `dataProvider` property, instead. (The write-only indicator appears in the syntax summary because the property in the superclass is read-write and this class overrides the setter with an empty implementation.)

Implementation
`public function set popUp(value:IUIComponent):void`

showRoot | property |

`showRoot:Boolean`

Specifies whether to display the top-level node or nodes of the data provider. If this is set to `false`, the control displays only descendants of the first top-level node. Any other top-level nodes are ignored. You normally set this property to `false` for E4X format XML data providers, where the top-level node is the document object.

The default value is `true`.

Implementation
`public function get showRoot():Boolean`
`public function set showRoot(value:Boolean):void`
Constructor Detail

PopUpMenuButtonBase | () | Constructor

`public function PopUpMenuButtonBase()`

Constructor.

Event Detail

itemClick | Event

Event Object Type: `mx.events.MenuEvent`
MenuEvent.type property = `mx.events.MenuEvent.ITEM_CLICK`

Dispatched when a user selects an item from the pop-up menu.

Mercredi Juillet 4 2012, 09:36 PM +02:00