menu.js

javascript 很酷的类库

/*
 * Isomorphic SmartClient
 * Version 6.5 (2008-04-30)
 * Copyright(c) 1998-2007 Isomorphic Software, Inc. All rights reserved.
 * "SmartClient" is a trademark of Isomorphic Software, Inc.
 *
 * [e-mail]
 *
 * http://smartclient.com/license
 */

 






//>	@class	Menu
//
// The Menu widget class implements interactive menu widgets, with optional icons, submenus,
// and shortcut keys.
// <p>
// A Menu is initialized with an Array of items, specified as menu.data, each of which represents
// one row in the menu's display and specifies the action to take when that menu item is selected.
// <p>
// Generally to create a context menu for a component, provide a Menu instance for the 
// <code>contextMenu</code> property.  Note that some components have special context menu support
// because they have distinct regions or because they have a default set of context menu actions
// available.
// <p>
// If you want a button that pops up a menu when clicked, or a bar of such buttons, see the
// MenuButton and MenuBar classes.
//
// @see attr:Menu.data
// @see attr:Canvas.contextMenu
// @see class:MenuButton
// @see class:MenuBar
//  @treeLocation Client Reference/Control
//  @visibility external
// @example fullMenu
//<






// define us as a subclass of the ListGrid
isc.ClassFactory.defineClass("Menu", "ListGrid");


// add contants
isc.Menu.addClassProperties({
    
    //>@type    MenuFieldID
    // Simple string identifiers for standard menu fields.
    // @value   "icon"  Displays the icon field for the menu. This field contains the items
    //                  specified icon (if there is one), or if the item is checked, the 
    //                  checkmark icon for the item.
    // @value   "title" Displays the item's title 
    // @value   "key" Displays the key field for the menu. This field contains the name or
    //                title of any shortcut keys for this menu item.
    // @value   "subMenu" Field to display the submenu image for items that have a submenu.
    // @visibility external
    //<
    
    // support the developer specifying standard fields via simple names
    // (EG: ["key", "icon", "title"])
    standardFields : {
        icon:"ICON_FIELD",
        title:"TITLE_FIELD",
        key:"KEY_FIELD",
        subMenu:"SUBMENU_FIELD"
    },

    //=	@const	isc.Menu.ICON_FIELD		
	ICON_FIELD:{name:"icon",	    
                width:25, 
                getCellValue : function (list, item) { return list.getIcon(item) }
    },		
    //=	@const	isc.Menu.TITLE_FIELD		 		
	TITLE_FIELD:{name:"title",	
                 width:"*", 
                 getCellValue : function (list, item) { return list.getItemTitle(item) }
    },		
    //=	@const	isc.Menu.KEY_FIELD		
	KEY_FIELD:{name:"keys",
               width:35, 
               getCellValue : function (list, item) { return list.getKeyTitle(item) }
    },			
    //=	@const	isc.Menu.SUBMENU_FIELD		
	SUBMENU_FIELD:{name:"submenu",
                   width:18, 
                   getCellValue : function (list, item) { return list.getSubmenuImage(item) }
    },	
	
    //>	@classAttr	isc.Menu._openMenus		(attrtype : [] : IRWA)
	//			list of all menus that are currently open
	//<
	_openMenus:[],

	// user-displayable names for modifier key combinations
    // NOTE that on the Mac this is actually generally done with icons.
    //=	@const	isc.Menu.SHIFT
	SHIFT:(isc.Browser.isWin ? "Shift+" : "shift-"),
    //=	@const	isc.Menu.CTRL
	CTRL:(isc.Browser.isWin ? "Ctrl+" : "ctrl-"),
    //=	@const	isc.Menu.ALT	
	ALT:(isc.Browser.isWin ? "Alt+" : "option-"),
    //=	@const	isc.Menu.META
	META:(isc.Browser.isWin ? "Windows+" : "command-")

});


isc.Menu.addProperties({

	//>	@attr	menu.data		(Array of MenuItem : null : IRW)
	// An array of menuItem objects, specifying the menu items this menu should show.
	// @group	data
    // @visibility external
    // @example fullMenu
	//<
    
	//>	@attr	menu.items      (Array of MenuItem : null : IRW)
	// Synonym for +link{menu.data}
	// @group	data
    // @visibility external
	//<
    
    //> @attr   menu.fields     (Array of MenuFieldID | Array of ListGridFields : null : IRWA)
    // Array of columns to show for this menu.<br>
    // Standard menu fields may be included by specifying +link{type:MenuFieldID, MenuFieldIDs}
    // directly. Additional custom fields may be specifed as +link{ListGridField} objects.<br>
    // If this property is unset, default behavior will show the
    // +link{type:MenuFieldID, standard set of fields}, with the exception of any that have
    // been suppressed via +link{Menu.showIcons}, +link{Menu.showKeys} and +link{Menu.showSubmenus} 
    // @visibility external
    // @example menuColumns
    //<
    
    //> @object MenuItem
    // Menu items are specified are object literals, not class instances.  For example, when
    // developing in JavaScript, a typical initialization block for a Menu would look like
    // this:
    // <pre>
    // Menu.create({
    //     data: [
    //         {title: "item1", click: "alert(1)"},
    //         {title: "item2"}
    //     ]
    // });
    // </pre>
    // And in XML:
    // <pre>
    // &lt;Menu&gt;
    //    &lt;data&gt;
    //        &lt;MenuItem title="item1" click="alert(1)"/&gt;
    //        &lt;MenuItem title="item2"/&gt;
    //    &lt;/data&gt;
    // &lt;/Menu&gt;
    // </pre>
    //
    // @treeLocation Client Reference/Control/Menu
    // @visibility external
    //<

    //> @attr menuItem.title (HTML : null : IR)
    // The text displayed for the menu item
    // @group menuBasic
    // @visibility external
    //<

    //> @attr menuItem.submenu (Menu : null : IR)
    // A reference to another menu, to display as a submenu when the mouse cursor hovers over
    // this menu item.
    // @group menuBasic
    // @visibility external
    // @example subMenus
    //<

    //> @attr menuItem.isSeparator (boolean : false : IR)
    // When set to <code>true</code>, this menu item shows a horizontal separator instead of
    // the +link{menuItem.title} text.  Typically specified as the only property of a menu item,
    // since the separator will not respond to mouse events.
    // @group menuBasic
    // @visibility external
    // @example fullMenu
    //<

    //> @attr menuItem.enabled (boolean : true : IR)
    // Affects the visual style and interactivity of the menu item.  If set to
    // <code>false</code>, the menu item will not respond to mouse rollovers or clicks.
    // <p>
    // If you need to set this state dynamically, use +link{menuItem.enableIf} instead.
    // @group menuBasic
    // @visibility external
    //<

    //> @attr menuItem.checked (boolean : null : IR)
    // If true, this item displays a standard checkmark image to the left of its title.  You
    // can set the checkmark image URL by setting +link{menu.checkmarkImage}.
    // <p>
    // If you need to set this state dynamically, use +link{menuItem.checkIf} instead.
    // @group menuIcons
    // @visibility external
    // @example fullMenu
    //<

    //> @attr menuItem.icon (string : null : IR)
    // The base filename for this item's custom icon. If both this property and
    // +link{menuItem.checked} are both specified, only icon specified by this property will be
    // displayed. The path to the loaded skin directory and the skinImgDir are prepended to
    // this filename to form the full URL.
    // <p>
    // If you need to set this state dynamically, use +link{menuItem.dynamicIcon} instead.
    // @group menuIcons
    // @visibility external
    // @example fullMenu
    //<

    //> @attr menuItem.iconWidth (number : 16 : IR)
    // The width applied to this item's icon.  The default of <code>16</code> can be changed
    // for all MenuItems by overriding +link{Menu.iconWidth}.
    // @group menuIcons
    // @visibility external
    //<

    //> @attr menuItem.iconHeight (number: 16 : IR)
    // The height applied to this item's icon.  The default of <code>16</code> can be changed
    // for all MenuItems by overriding +link{Menu.iconHeight}.
    // @group menuIcons
    // @visibility external
    //<

    //> @attr menuItem.keys (KeyIdentifier | Array of KeyIdentifer : null : IR)
    // Shortcut key(s) to fire the menu item action. Each key can be defined as a +link{KeyIdentifier}.
    // To apply multiple shortcut keys to this item, set this property to an array of such key
    // identifiers. 
    //
    // @group menuKeys
    // @visibility external
    //<

    //> @attr menuItem.keyTitle (string : see below : IR)
    // A string to display in the shortcut-key column for this item. If not
    // specified, the first KeyName value in +link{menuItem.keys} will be used by default.
    // @group menuKeys
    // @visibility external
    // @example fullMenu
    //<

    //> @attr menuItem.enableIf (expression : null : IR)
    // A string of script that is evaluated to a boolean value for the item's enabled property
    // whenever the menu is shown or a shortcut key is pressed.
    // <p>
    // If you don't need to set this state dynamically, use +link{menuItem.enabled} instead.
    // @group dynamicMenuItem
    // @visibility external
    // @example menuDynamicItems
    //<

    //> @attr menuItem.checkIf (expression : null : IR)
    // A string of script that is evaluated to a boolean value for the item's checked property
    // whenever the menu is shown or a shortcut key is pressed.
    // <p>
    // If you don't need to set this state dynamically, use +link{menuItem.checked} instead.
    // @group dynamicMenuItem
    // @visibility external
    // @example menuDynamicItems
    //<

    //> @attr menuItem.dynamicTitle (expression : null : IR)
    // A string of script that is evaluated to a string value for the item's title property
    // whenever the menu is shown or a shortcut key is pressed.
    // <p>
    // If you don't need to set this state dynamically, use +link{menuItem.title} instead.
    // @group dynamicMenuItem
    // @visibility external
    // @example menuDynamicItems
    //<

    //> @attr menuItem.dynamicIcon (expression : null : IR)
    // A string of script that is evaluated to a string value for the item's icon property
    // whenever the menu is shown or a shortcut key is pressed.
    // <p>
    // If you don't need to set this state dynamically, use +link{menuItem.icon} instead.
    // @group dynamicMenuItem
    // @visibility external
    // @example menuDynamicItems
    //<

    //> @method menuItem.click()
    // Executed when this menu item is clicked by the user. The click handler must be specified
    // as a function or string of script.  Return false to suppress the +link{Menu.itemClick()}
    // handler if specified.
    //
    // @param target (Canvas) for a menu shown as a context menu, the Canvas the menu was shown
    //                        on.  Otherwise the +link{Menu} instance of which this
    //                        +link{MenuItem} is a member.
    // @param item   (MenuItem) The +link{MenuItem} that was clicked on.
    // @param menu   (Menu)     The +link{Menu} instance of which this +link{MenuItem} is a
    //                          member.
    // @param [colNum] (number) Index of the column the user clicked. May be null if the
    //                          user activated the menu via a keyboard event.
    // @group menuItemEvents
    // @visibility external
    //<
    
    // Also support menuItem.action, of type "Action"
    // Documentation is bare-bones at the moment. Has to be visible in order to show up
    // in Visual Builder.
    //> @method menuItem.action()
    // Action to fire when this menu is activated.
    // @group menuBasic
    // @visibility external
    //<

    //>	@attr	menu.styleName		(CSSStyleName : "normal" : IRW)
	//			css class for the layer's contents
	//		@group	appearance
	//<
    // don't use the default ListGrid component/body styles, which usually have partial borders 
	styleName:"normal",
    bodyStyleName:"normal",


    //>	@attr   menu.submenuDelay (integer : 200 : [IRWA])
    //  Number of milliseconds to delay before hiding/changing submenu
    //  NOTE: in Windows this is 400ms, but it's also an official Windows Annoyance.
    //<
	submenuDelay:200,

    // shift the submenu this many pixels right of the right border of the parent menu.
    submenuOffset: -4,

    //>	@attr	menu.defaultWidth		(number : 150 : [IRW])
    //          The default menu width.
    //      @visibility external
    //      @group  sizing
    //<
	defaultWidth:150,

    //>	@attr	menu.defaultHeight		(number : 20 : [IRW])
    //          The default menu height.
    //<
	defaultHeight:20,
    
    // enforceMaxHeight:
    // If a menu contains enough items that the height of the menu exceeds the result of
    // this.getMaxHeight() [overridden to default to page height if this.maxHeight is unset]
    // we want to introduce scrollbars so the user can access all menu items without 
    // scrolling the page.
    
    
    //> @attr   menu.enforceMaxHeight (boolean : true : [IRW])
    // If true, don't allow the menu to grow beyond +link{Menu.maxHeight} - or the height of the
    // page if this is unspecified.
    // If menu content exceeds this size, introduce scrollbars to allow the user to access
    // all menu items.
    // @see menu.maxHeight
    // @group sizing
    //<