×
Namespaces

Variants
Actions
(Difference between revisions)

StarMenu: custom QML component plugin

From Nokia Developer Wiki
Jump to: navigation, search
lildeimos (Talk | contribs)
m (Lildeimos - - Usage)
hamishwillee (Talk | contribs)
m (Hamishwillee - Tidy wiki text. Minor restructure)
Line 23: Line 23:
  
 
== Introduction ==
 
== Introduction ==
The {{Icode|StarMenu}} is a pop up menu that can be raised by clicking or tapping on an area defined like using {{Icode|MouseArea}} component. The {{Icode|StarMenu}}'s menu items are defined using {{Icode|StarItems}}. This plugin is been developed with Qt 4.7.4 and tested on linux, Nokia N900, Nokia C7-00,  Nokia N950 and Android Galaxy tab GT-7310 (with [https://sourceforge.net/p/necessitas/home/necessitas/ Necesistas] ).
+
The {{Icode|StarMenu}} is a QML contextual pop up menu that can be launched by clicking or tapping on a {{Icode|MouseArea}} element. The {{Icode|StarMenu}}'s menu items are defined using {{Icode|StarItems}}.  
 +
 
 +
[[File:StarMenu_two_starsubmenu.jpg|x220px|two sub menus]]
 +
 
 +
This plugin was developed with Qt 4.7.4 and tested on linux, Nokia N900, Nokia C7-00,  Nokia N950 and Android Galaxy tab GT-7310 (with [https://sourceforge.net/p/necessitas/home/necessitas/ Necesistas] ).
  
 
== Usage ==  
 
== Usage ==  
Line 30: Line 34:
  
 
.pro file must contains this:
 
.pro file must contains this:
 
 
<code java>
 
<code java>
 
contains(MEEGO_EDITION,harmattan) {
 
contains(MEEGO_EDITION,harmattan) {
Line 58: Line 61:
 
</code>
 
</code>
  
and before setSource() or setMainQmlFile() register the component with:
+
and before {{Icode|setSource()}} or {{Icode|setMainQmlFile()}} register the component with:
  
 
<code java>
 
<code java>
Line 69: Line 72:
 
import StarMenu 1.0
 
import StarMenu 1.0
 
</code>
 
</code>
 
 
[[File:StarMenu_two_starsubmenu.jpg|x220px|two sub menus]]
 
 
The {{Icode|StarMenu}} component displays a contextual menu in a declarative user interface.
 
  
 
{{Icode|StarMenu}} is hidden by default and opens in response to a user action. The purpose of {{Icode|StarMenu}} is to manage all {{Icode|StarItem}} childs. By default they are arrange in a circle shape and, in the center of it, it is painted a star polygon shape with as many spikes as the number of StarItems. It can be visible or not by setting the boolean {{Icode|starCenterVisible}} property.
 
{{Icode|StarMenu}} is hidden by default and opens in response to a user action. The purpose of {{Icode|StarMenu}} is to manage all {{Icode|StarItem}} childs. By default they are arrange in a circle shape and, in the center of it, it is painted a star polygon shape with as many spikes as the number of StarItems. It can be visible or not by setting the boolean {{Icode|starCenterVisible}} property.
The circle shape amplitude is given by {{Icode|radiusH} and {{Icode|radiusV} properties.
+
The circle shape amplitude is given by {{Icode|radiusH}} and {{Icode|radiusV}} properties.
 +
 
 
Clicking on the center of the current menu, will close it and goes back to parent.
 
Clicking on the center of the current menu, will close it and goes back to parent.
 +
 
It's possible to click on the center of the first menu to close all.
 
It's possible to click on the center of the first menu to close all.
visualParent property is used to bind the close menu action to a specified item, so, instead of clicking on center of {{Icode|StarMenu}, it's possible to set {{Icode|visualParent} to the main window and close menu everywhere on the screen.
+
 
When using {{Icode|visualParent}, it come handy the {{Icode|color} property to set a transparent color to the clickable area to close the menu.
+
{{Icode|visualParent}} property is used to bind the close menu action to a specified item, so, instead of clicking on center of {{Icode|StarMenu}}, it's possible to set {{Icode|visualParent}} to the main window and close menu everywhere on the screen.
Changing {{Icode|StarItem visible}} property, makes all {{Icode|StarItem}s position recalculated with only visible items.  
+
 
 +
When using {{Icode|visualParent}}, it come handy the {{Icode|color}} property to set a transparent color to the clickable area to close the menu.
 +
Changing {{Icode|StarItem visible}} property, makes all {{Icode|StarItem}}s position recalculated with only visible items.  
  
  
Line 144: Line 146:
 
[[File:StarMenu_shapes.jpg|x220px|other shapes]]  
 
[[File:StarMenu_shapes.jpg|x220px|other shapes]]  
  
{{Icode|StarItems}}s can be arranged in a {{Icode|spiral shape}}, in a {{Icode|grid shape}} or in a {{Icode|line shape}}.  
+
{{Icode|StarItems}} can be arranged in a {{Icode|spiral shape}}, in a {{Icode|grid shape}} or in a {{Icode|line shape}}.  
 
{{Icode|StarMenu}} {{Icode|shape}} property could have the following values:  
 
{{Icode|StarMenu}} {{Icode|shape}} property could have the following values:  
  
Line 152: Line 154:
 
* {{Icode|StarMenu.ShapeLine}}
 
* {{Icode|StarMenu.ShapeLine}}
  
 
+
Rows in grid shape are arranged centered by the mouse click and are spaced by {{Icode|spacingH}} and {{Icode|spacingV}} properties with columns count defined by {{Icode|columns}} property. Spiral shape takes care of {{Icode|startingRadius}} value to start drawing StarItems and {{Icode|radiusIncrement}} property to shape the spiral. Line shape has a {{Icode|startingAngle}}, {{Icode|radiusIncrement}} and {{Icode|startingRadius}} properties.
Rows in grid shape are arranged centered by the mouse click and are spaced by {{Icode|spacingH}} and {{Icode|spacingV}} properties with columns count defined by {{Icode|columns} property. Spiral shape takes care of {{Icode|startingRadius}} value to start drawing StarItems and {{Icode|radiusIncrement}} property to shape the spiral. Line shape has a {{Icode|startingAngle}}, {{Icode|radiusIncrement}} and {{Icode|startingRadius}} properties.
+
  
 
StarMenu has the center where user clicks. This centerproperty can be defined everywhere in scene coordinates by setting {{Icode|center}} property.
 
StarMenu has the center where user clicks. This centerproperty can be defined everywhere in scene coordinates by setting {{Icode|center}} property.
Line 195: Line 196:
 
''Used with {{Icode|ShapeGrid}} to space vertically StarItems.''
 
''Used with {{Icode|ShapeGrid}} to space vertically StarItems.''
 
* {{Icode|startingAngle}}: qreal
 
* {{Icode|startingAngle}}: qreal
''Used with {{Icode|ShapeLine} to define the direction of the StarItems.''
+
''Used with {{Icode|ShapeLine}} to define the direction of the StarItems.''
 
* {{Icode|starCenterVisible}}: bool
 
* {{Icode|starCenterVisible}}: bool
 
''Show the star at the center of StarMenu. The star shape has as many spikes as the number of StarItems.''
 
''Show the star at the center of StarMenu. The star shape has as many spikes as the number of StarItems.''
Line 203: Line 204:
 
''When true, the center of the StarMenu will be the center of parent StarMenu if exists.''
 
''When true, the center of the StarMenu will be the center of parent StarMenu if exists.''
 
* {{Icode|visualParent}}: Item
 
* {{Icode|visualParent}}: Item
''The Item in which the user will click to close the StarMenu. The default sensible area is the parent of StarMenu, with {{Icode|visualParent}, developers are able to redefine this area for example to the main application window.''
+
''The Item in which the user will click to close the StarMenu. The default sensible area is the parent of StarMenu, with {{Icode|visualParent}}, developers are able to redefine this area for example to the main application window.''
  
 
'''Signals'''
 
'''Signals'''

Revision as of 02:40, 27 March 2012

Note.pngNote: This is an entry in the Symbian Qt Quick Components Competition 2012Q1

This article introduces StarMenu, a QML pop up menu.

Article Metadata
Tested with
SDK: Nokia Qt SDK 1.1.4
Devices(s): Nokia C7-00, Nokia N900, Nokia N950, Galaxy tab 7310
Compatibility
Platform(s): Symbian^3 and later, Harmattan, linux, Windows
Symbian
Device(s): all
Article
Keywords: Menu, QDeclarativeItem, StarMenu
Created: lildeimos (18 Dec 2011)
Last edited: hamishwillee (27 Mar 2012)

Contents

Introduction

The StarMenu is a QML contextual pop up menu that can be launched by clicking or tapping on a MouseArea element. The StarMenu's menu items are defined using StarItems.

two sub menus

This plugin was developed with Qt 4.7.4 and tested on linux, Nokia N900, Nokia C7-00, Nokia N950 and Android Galaxy tab GT-7310 (with Necesistas ).

Usage

Note for Harmattan:

.pro file must contains this:

contains(MEEGO_EDITION,harmattan) {
DEFINES += MEEGO_EDITION_HARMATTAN
QT += dbus
}

To compile and install the plugin, just do:

qmake
make
make install

then in your .qml you will need to

import com.starMenu 1.0

To compile within your project: copy staritem.* and starmenu.* in your project directory and add them to the .pro file. Then in the main.cpp include the headers:

#include "starmenu.h"
#include "staritem.h"

and before setSource() or setMainQmlFile() register the component with:

qmlRegisterType<StarMenu>("StarMenu", 1, 0, "StarMenu");
qmlRegisterType<StarItem>("StarMenu", 1, 0, "StarItem");

then, in your .qml file, you will be able to:

import StarMenu 1.0

StarMenu is hidden by default and opens in response to a user action. The purpose of StarMenu is to manage all StarItem childs. By default they are arrange in a circle shape and, in the center of it, it is painted a star polygon shape with as many spikes as the number of StarItems. It can be visible or not by setting the boolean starCenterVisible property. The circle shape amplitude is given by radiusH and radiusV properties.

Clicking on the center of the current menu, will close it and goes back to parent.

It's possible to click on the center of the first menu to close all.

visualParent property is used to bind the close menu action to a specified item, so, instead of clicking on center of StarMenu, it's possible to set visualParent to the main window and close menu everywhere on the screen.

When using visualParent, it come handy the color property to set a transparent color to the clickable area to close the menu. Changing StarItem visible property, makes all StarItems position recalculated with only visible items.


StarMenu {
id: starMenu
anchors.fill: parent
radius: 130
 
StarItem {
width: 64; height: 64
Image {
anchors.fill: parent
[...]
}
}
StarItem {
[...]
StarMenu {
[...]
}
}
}


rotation scale delayed animation

It is possible to bind animations to StarItems. When a StarMenu is raised, the StarItems circle shape has the center located by the mouse click (or tap) position and their opacity, rotation, x, y property are set to 0. By doing this:

StarItem {
[...]
Behavior on x { NumberAnimation { duration: 1500; easing.type: Easing.OutBounce } }
Behavior on y { NumberAnimation { duration: 1500; easing.type: Easing.OutBounce } }
Behavior on opacity { NumberAnimation { duration: 2200; easing.type: Easing.OutBounce } }

StarItems are animated from center to their final position.

StarMenu has also a delayChangePos property. For example, when it is set to 100, the animation of the second StarItem is started after 100 ms, the third after 200 ms and so on. StarItem has also a delayChangePos property and if it is set, it take priority over the StarMenu delayChangePos property.

entries as components

StarItems can also contain any other component instead Image component used in these examples:

StarItem {
width: 320; height: 240
scale: 0.3
zoomHoverValue: 1
Behavior on scale { NumberAnimation { duration: 500; easing.type: Easing.OutQuad } }
Column {
Button { text: "Hello Qt" }
Switch { }
RadioButton { }
}
}

other shapes

StarItems can be arranged in a spiral shape, in a grid shape or in a line shape. StarMenu shape property could have the following values:

  • StarMenu.ShapeCircle (default value)
  • StarMenu.ShapeGrid
  • StarMenu.ShapeSpiral
  • StarMenu.ShapeLine

Rows in grid shape are arranged centered by the mouse click and are spaced by spacingH and spacingV properties with columns count defined by columns property. Spiral shape takes care of startingRadius value to start drawing StarItems and radiusIncrement property to shape the spiral. Line shape has a startingAngle, radiusIncrement and startingRadius properties.

StarMenu has the center where user clicks. This centerproperty can be defined everywhere in scene coordinates by setting center property.


Properties & signals

StarMenu

Properties

  • center: point

Center coordinates relative to the root scene.

  • color: color

Color of the sensible area to be clicked to close the menu. Useful if visualParent is defined.

  • columns: int

Columns when ShapeGrid is used.

  • delayChangePos: int

Delay between each StarItems positioning after the mouse click. If delayChangePos property of StarItem has priority over this.

  • open: bool

Set or get open state of StarMenu. The value is true only when the StarMenu is the current. Every parents and childs StarMenu have this property set to false. Usually the StarMenu is opened by user action.

  • radiusH: qreal

Horizontal radius of the circle shape.

  • radiusV: qreal

Vertical radius of the circle shape.

  • rotation: qreal

Rotation of StarItems. Only available with circle and spiral shapes.

  • radiusIncrement: qreal

Used with spiral and line shape to define spacing betweeen StarItems.

  • shape: enumeration

Shape to be used. The default is ShapeCircle.

   * StarMenu.ShapeCircle
   * StarMenu.ShapeGrid
   * StarMenu.ShapeSpiral
   * StarMenu.ShapeLine
  • spacingH: qreal

Used with ShapeGrid to space horizontally StarItems.

  • spacingV: qreal

Used with ShapeGrid to space vertically StarItems.

  • startingAngle: qreal

Used with ShapeLine to define the direction of the StarItems.

  • starCenterVisible: bool

Show the star at the center of StarMenu. The star shape has as many spikes as the number of StarItems.

  • startingRadius: qreal

Used with ShapeSpiral and with ShapeLine to define the distance from center of the first StarItem.

  • useParentMenuCenter: bool

When true, the center of the StarMenu will be the center of parent StarMenu if exists.

  • visualParent: Item

The Item in which the user will click to close the StarMenu. The default sensible area is the parent of StarMenu, with visualParent, developers are able to redefine this area for example to the main application window.

Signals

  • StarMenu::starMenuOpening()

Signal for detecting StarMenu opening.

  • StarMenu::starMenuClosing()

Signal for detecting StarMenu closing.


StarItem

Properties

  • zoomHoverValue: qreal

Zoom value when mouse enters.

  • delayChangePos: int

Delay between StarItem is positioned after the mouse click. If this property is set, it will take priority over the same StaMenu property.

Signals

  • StarItem::hoverItem()

Signal for detecting when mouse is hover.

  • StarItem::leaveItem()

Signal for detecting when mouse leaves.

  • StarItem::clicked()

Signal for detecting a mouse click.


Downloads

Here the home project link. You will find starMenu-plugin.zip which is the source of the plugin. There are aslo a deb package for Nokia N9/950 and a sis package for symbian Anna. Due to some issues with Qt Mobility, I have made two separate sources of the demo, the first for Harmattan and desktop with Qt Mobility installed and the other for symbian and desktop without Mobility.

StarMenu project

324 page views in the last 30 days.
×