Toolbar and Menus"

From Documentation
m (Created page with '{{ZKDevelopersGuidePageHeader}} == Menu bars == Components: <tt>menubar</tt>, <tt>menupopup</tt>, <tt>menu</tt>, <tt>menuitem</tt> and <tt>menuseparator</tt>. A menu bar contai…')
 
m
 
(One intermediate revision by one other user not shown)
Line 1: Line 1:
 
{{ZKDevelopersGuidePageHeader}}
 
{{ZKDevelopersGuidePageHeader}}
  
== Menu bars ==
+
This section looks at ZK toolbars and menus.
Components: <tt>menubar</tt>, <tt>menupopup</tt>, <tt>menu</tt>, <tt>menuitem</tt> and <tt>menuseparator</tt>.
 
  
A menu bar contains a collection of menu items and sub menus with the sub menus containing a collection of menu items and other sub menus.
+
{{ZKDevelopersGuideHeadingToc}}
  
An example of menu bars is demonstrated below.
 
 
[[Image:10000000000001570000003F0A980060.png]]
 
 
<source lang="xml" >
 
<zk>
 
<menubar>
 
    <menu label="File">
 
        <menupopup>
 
            <menuitem label="New"/>
 
            <menuitem label="Open"/>
 
            <menuseparator/>
 
            <menuitem label="Exit"/>
 
        </menupopup>
 
    </menu>
 
    <menu label="Help">
 
        <menupopup>
 
            <menuitem label="Index"/>
 
            <menu label="About">
 
                <menupopup>
 
                    <menuitem label="About ZK"/>
 
                    <menuitem label="About Potix"/>
 
                </menupopup>
 
            </menu>
 
        </menupopup>
 
    </menu>
 
</menubar>
 
</zk>
 
</source>
 
 
* <tt>menubar</tt>: The topmost container for a collection of menu items (<tt>menuitem</tt>) and menus (<tt>menu</tt>).
 
* <tt>menu</tt>: The container of a popup menu. It also defines the label to be displayed on its’ parent. When user clicks on the label, the popup menu appears.
 
* <tt>menupopup</tt>: A container for a collection of menu items (<tt>menuitem</tt>) and menus (<tt>menu</tt>). It is a child of <tt>menu</tt> and appears when the label of <tt>menu</tt> is clicked.
 
 
* <tt>menuitem</tt>: A command present on a menu. This can be placed in a menu bar, or a popup menu.
 
 
* <tt>menuseparator</tt>: A separator bar on a menu which tends to be placed in a popup menu.
 
 
=== Execute a Menu Command ===
 
A menu command is associated with a menu item. There are two ways to associate a command to it: the <tt>onClick</tt> event and the <tt>href</tt> property. If a event listener is added for a menu item for the <tt>onClick</tt> event, the listener is invoked when the item is clicked.
 
 
<source lang="xml" >
 
<menuitem onClick="draft.save()"/>
 
</source>
 
 
You are also able to specify the <tt>href</tt> attribute to create hyperlink to the specified URL. When a user clicks the menu item then they will be taken to the URL using the browser.
 
 
<source lang="xml" >
 
<zk>
 
<menubar>
 
    <menu label="Links">
 
        <menupopup>
 
            <menuitem label="link1" href="/edit"/>
 
<menuitem label="link2" href="http://zk1.sourceforge.net"/>
 
        </menupopup>
 
    </menu>
 
</menubar>
 
</zk>
 
</source>
 
 
If the event listener and <tt>href</tt> are specified they will both be executed. However, when the event listener is executed in the server, the browser may have already navigated to the URL. Thus, all responses generated by the event listener will be ignored.
 
 
=== Use Menu Items as Check Boxes ===
 
A menu item can be used as a check box. The <tt>checked</tt> attribute denotes whether this menu item is checked. If checked is true, a checkbox appears in front of the menu item.
 
 
In addition to specifying the <tt>checked</tt> attribute, you can also set the <tt>autocheck</tt> attribute to <tt>true</tt>.  After setting the appropriate attributes, when the user clicks a menu item the <tt>checked</tt> attribute will be toggled automatically.
 
 
<source lang="xml" >
 
<zk>
 
<menubar>
 
    <menu label="Autocheck">
 
        <menupopup>
 
            <menuitem label="click me" autocheck="true"/>
 
        </menupopup>
 
    </menu>
 
</menubar>
 
</zk>
 
</source>
 
 
=== The autodrop Property ===
 
By default, the popup menu is opened when user clicks on it. You are able to change the behavior so the popup menu will appear when the user’s mouse moves over it. This is done by setting the <tt>autodrop</tt> attribute to true.
 
 
<source lang="xml" >
 
<menubar autodrop="true">
 
    ...
 
</menubar>
 
</source>
 
 
The autodrop=true make the popup menu appear on mouse over, and it disappears if you click elsewhere. However, if you want to close the popup menu when the mouse moves out, you can code something like this:
 
<source lang="xml" >
 
<zk xmlns:w="http://www.zkoss.org/2005/zk/client">
 
<menubar width="300px" autodrop="true">
 
<menu label="Project"
 
image="/img/Centigrade-Widget-Icons/Briefcase-16x16.png">
 
<menupopup>
 
<attribute w:name="doMouseOut_"><![CDATA[
 
function(evt){
 
this.$doMouseOut_(evt);
 
this.close();
 
}
 
]]></attribute>
 
<menuitem
 
image="/img/Centigrade-Widget-Icons/BriefcaseSpark-16x16.png"
 
label="New" onClick="alert(self.label)" />
 
</menupopup>
 
</menu>
 
</menubar>
 
</zk>
 
</source>
 
 
=== The onOpen Event ===
 
Just before a menupopup appears or disappears an <tt>onOpen</tt> event is sent to the menupopup for notification. For sophisticated applications, you can defer the creation of the content of the menupopup or manipulate the content dynamically when the <tt>onOpen</tt> event is received. Please refer to the '''Load on Demand''' section in the '''ZK User Interface Markup Language''' chapter for details.
 
 
=== More Menu Features ===
 
Just like the <tt>box</tt> component, you can control the orientation of a menu by using the <tt>orient</tt> attribute. By default, the orientation is <tt>horizontal</tt>.
 
 
Like other components, you can change the menu dynamically including properties and creating additional sub menus. Please refer to <tt>menu.zul</tt> under the <tt>test</tt> directory in the <tt>zkdemo</tt>.
 
 
== Context Menus ==
 
Components: <tt>popup</tt> and <tt>menupopup</tt>.
 
 
You can assign the ID of a <tt>popup</tt> or <tt>menupopup</tt> component to the <tt>context</tt> attribute of any XUL component. This enables the <tt>popup</tt> or <tt>menupopup</tt> component to open when a user right-clicks on a XUL component.
 
 
As depicted below, a context menu is enabled by assigning the <tt>popup/menupopup</tt> ID to the <tt>context</tt> property of a XUL component. Of course, the same ID can be assigned to multiple components.
 
 
<source lang="xml" >
 
<zk>
 
<menupopup id="editPopup">
 
    <menuitem label="Undo"/>
 
    <menuitem label="Redo"/>
 
   
 
    <menu label="Sort">
 
        <menupopup>
 
            <menuitem label="Sort by Name" autocheck="true"/>
 
            <menuitem label="Sort by Date" autocheck="true"/>
 
        </menupopup>
 
    </menu>
 
</menupopup>
 
 
<label value="Right Click Me!" context="editPopup"/>
 
<separator bar="true"/>
 
<label value="Right Click Me!" onRightClick="alert(self.value)"/>
 
</zk>
 
</source>
 
 
[[Image:100000000000017500000052E60F488A.png]]
 
 
 
Notice that the <tt>menupopup</tt> is not visible until a user right-clicks on a component that is associated with its’ ID.
 
 
'''Tip:''' If you want to disable browser's default context menu, you can set the <tt>context</tt> attribute of a component to a non-existent ID.
 
 
The <tt>popup</tt> component is generic popup and you are able to place any kind of components inside of popup. For example,
 
 
<source lang="xml" >
 
<zk>
 
<label value="Right Click Me!" context="any"/>
 
</zk>
 
</source>
 
 
 
<source lang="xml" >
 
<zk>
 
<label value="Right Click Me!" context="any"/>
 
 
<popup id="any" width="300px">
 
    <vbox>
 
        It can be anything.
 
        <toolbarbutton label="ZK" href="http://zk1.sourceforge.net"/>
 
    </vbox>
 
</popup>
 
</zk>
 
</source>
 
 
=== Customizable Tooltip and Popup Menus ===
 
 
In addition to opening a popup when a user right-clicks a component, ZK can display a popup under other circumstances.
 
 
 
{| border="1px"
 
! <center>Property</center>
 
! <center>Description</center>
 
 
|-
 
|  context
 
| When a user right clicks on a component which has an assigned <tt>context</tt> attribute, the relative <tt>popup</tt> or <tt>menupopup</tt> component will be displayed.
 
 
|-
 
|  tooltip
 
| When a user moves the mouse pointer over a component which has an assigned <tt>context</tt> attribute, the relative <tt>popup</tt> or <tt>menupopup</tt> component will be displayed.
 
 
|-
 
|  popup
 
| When user clicks on a component which has an assigned <tt>popup</tt> attribute, the relative <tt>popup</tt> or <tt>menupopup</tt> component will be displayed.
 
 
|}
 
For example,
 
 
<source lang="xml" >
 
<window title="Context Menu and Right Click" border="normal" width="360px">
 
    <label value="Move Mouse Over Me!" tooltip="editPopup"/>
 
    <separator bar="true"/>
 
    <label value="Tooptip for Another Popup" tooltip="any"/>
 
    <separator bar="true"/>
 
    <label value="Click Me!" popup="editPopup"/>
 
 
    <menupopup id="editPopup">
 
            <menuitem label="Undo"/>
 
            <menuitem label="Redo"/>
 
            <menu label="Sort">
 
        <menupopup>
 
            <menuitem label="Sort by Name" autocheck="true"/>
 
            <menuitem label="Sort by Date" autocheck="true"/>
 
        </menupopup>
 
            </menu>
 
    </menupopup>
 
    <popup id="any" width="300px">
 
        <vbox>
 
            ZK simply rich.
 
            <toolbarbutton label="ZK your killer Web application now!"                        href="[http://zk1.sourceforge.net/ http://zk1.sourceforge.net]"/>
 
        </vbox>
 
</popup>
 
</window>
 
</source>
 
 
Please note you can specify any identifier in the <tt>popup</tt>, <tt>tooltip</tt> and <tt>context</tt> attributes as long as they are within the same page. In other words, it is not confined by the ID space.
 
 
=== The onOpen Event ===
 
 
Just before a context menu, a tooltip or a popup appears or disappears an <tt>onOpen</tt> event is sent to the context, tooltip or popup menu for notification. The event is an instance of the <tt>org.zkoss.zk.ui.event.OpenEvent</tt> class. You can retrieve the component that caused the context menu, tooltip or popup to appear by calling the <tt>getReference</tt> method.
 
 
To improve the performance, you can defer the creation of the content until it becomes visible – i.e., until the <tt>onOpen</tt> event is received. The simplest way to defer the creation of the content is to use the <tt>fulfill</tt> attribute as shown below.
 
 
<source lang="xml" >
 
<popup id="any" width="300px" fulfill="onOpen">
 
  <button label="Hi"/><!-- whatever content -->
 
</popup>
 
</source>
 
 
Then, the content (the ''Hi'' button) won't be created when the page is loaded. Rather, the content is created when the <tt>onOpen</tt> event is received at the first time.
 
 
If you prefer to dynamically manipulate the content using Java, you can listen to the <tt>onOpen</tt> event as depicted below.
 
 
<source lang="xml" >
 
<zk>
 
<popup id="any" width="300px">
 
    <attribute name="onOpen">
 
    if (event.isOpen()) {
 
        if (self.getChildren().isEmpty()) {
 
            new Button("Hi").setParent(self);
 
           
 
        }
 
        if (event.getReference() instanceof Textbox) {
 
            //you can do component-dependent manipulation here
 
           
 
        }
 
    }
 
    </attribute>
 
</popup>
 
 
<label value="hello" context="any" />
 
</zk>
 
</source>
 
 
== See Also ==
 
From ZK Forum:
 
 
[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D6173%3BcategoryId%3D14%3B Popup window with ListCell does know show itself... ???]
 
  
 
{{ ZKDevelopersGuidePageFooter}}
 
{{ ZKDevelopersGuidePageFooter}}

Latest revision as of 03:13, 1 September 2010

Toolbar and Menus


Stop.png This documentation is for an older version of ZK. For the latest one, please click here.


This section looks at ZK toolbars and menus.





Last Update : 2010/09/01

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.