Meego Wiki
Views

Components Migration

From MeeGo wiki
Revision as of 22:21, 26 May 2011 by Cosmok (Talk | contribs)
Jump to: navigation, search

Contents

Migration of Components from MeeGo.Labs.Components to MeeGo.Components

PAGE UNDER CONSTRUCTION

Currently some UX components exists in multiple repositories (repo meego-ux-components / namespace MeeGo.Components, repo meegolabs-ux-components / namespace MeeGo.Labs.Components and repo meego-media-components / namespace MeeGo.Media). It is confusing and difficult to maintain various forked versions of code. The solution is to deprecate duplicate versions so that we have only a single copy of each component.

In many cases, this mean applications need to replace components from MeeGo.Labs.Components and MeeGo.Media with their counterparts from MeeGo.Components, making API changes as necessary. In some cases, code has been copied to MeeGo.Components prematurely and will be deprecated in favor of the MeeGo.Labs version.

Component migration will occur in three phases:

Component Migration Phase I

Done as of April 9th.

  • Deprecated MeeGo.Media pickers (image/video/music)
  • Deprecated MeeGo.Labs.Components Date and Time pickers
  • NB: Contacts picker will remain in MeeGo.Labs for the time being

Components Migration Phase II

This was originally scheduled to end April 22 but has been delayed to May 3rd

Since most of the meego-ux-components depend on signals from the new meego-ux-components Window.qml, some of them will have issues when being used with the meegolabs Window.qml. The ModalContextMenu is our main problem child here. We have added a Window2.qml to the meegolabs repo which is basically the meegolabs Window.qml, but with the orientation behaviour of the new meego-ux-components Window.qml. Just add the '2' behind Window to use it, no further API changes are necessary. The ModalContextmenu called in the content area will now stay on screen. Of course Window2.qml does not have the full functionality of the meego-ux-components Window.qml, so there will still be a few bugs until you switch to the meego-ux-components Window.qml. Bugs we found after a quick testing:

  • the book and action menu context menus will still leave the screen/ appear in the wrong position when the orientation changes while they are visible.
  • Some apps create their own status bar and tool bar:
    • the panels view has two status bars.
    • the photo apps detail page always shows its search bar.

These bugs should not be filed and will not be fixed since Window2.qml is only a preliminary solution for testing only!

Components Affected by Phase II

MeeGo Labs MeeGo-Ux-Components Changes
ActionMenu ActionMenu API changed
Button Button API and Design
CheckBox CheckBox API and Design
ContextMenu ModalContextMenu derived from ModalFog, API change
DropDown DropDown API and Design
EditPane TextField replace by TextField
ExpandingBox ExpandingBox API and Design
Fog ModalFog whole concept changed
IconButton IconButton API and Design
MessageBox ModalMesseageBox derived from ModalFog, API change
ModalDialog ModalDialog API and Design
ModalSurface ModalFog API and Design
PickerDialog ModalDialog -
PopupList PopupList API and Design
RadioButton RadioButton Design
RadioGroup.js RadioGroup.js Design
RadioGroup.qml RadioGroup.qml API and Design
Slider Slider API and Design
Spinner <same> ModalSpinner can be used for the full-screen use case
StatusBar StatusBar No changes
TextEntry TextEntry API and Design
ToggleButton ToggleButton API and Design
TopItem TopItem API
VerticalSlider VerticalSlider API and Design

Component Migration Phase III

Was scheduled to end April 29, now May 6th. In this phase we deprecate MeeGo.Labs Window and ApplicationPage components to be replace by MeeGo.Components Window and AppPage.

A general change in the meego-ux-components is the concept of how to use Window and AppPage in order to create a navigation path in your application. You can find the examples and the tutorial in the devel package to help you understand the concept.

IMPORTANT: When using the meego-ux-components Window.qml: the id of your Window.qml main page item must always be 'window'. This is necessary for the AppPages to set values (like title) in the Window.

Nonetheless some examples:

Example for a Page.qml

The AppPage is the content that's shown inside an apps window. Statusbar and toolbar are provided by the Window.qml as well as a default action menu. The pageTitle will appear in the Windows toolbar. 

AppPage {
   id: mainPage

   pageTitle: "My first page"

   actionMenuModel: [ "First choice", "Second choice" ]
   actionMenuPayload: [ 1, 2 ]

   onActionMenuTriggered: {
       // an action menu entry was clicked, action menu hidden
       // and '1' or '2' returned in selectedItem
   }
}

You can call addPage(<nextPageName>) to switch to the next page. 

AppPage {
(...)
Component { id: nextPage; SubPage{} }

onClicked: { addPage( nextPage ) }
(...)
}

The Window.qml provides a back button in the toolbar to get back to the previous page.

Example for a MainWindow.qml

The Window is the applications main item. It has a book menu to switch between main pages. 

Window {
   id: window

   bookMenuModel: [ qsTr("Page 1") , qsTr("Page 2") ]
   bookMenuPayload: [ book1Component,  book2Component ]

   Component.onCompleted: {
       console.log("load MainPage")
       switchBook( book1Component )
   }

   Component { id: book1Component; Page {} }
   Component { id: book2Component; Page2 {} }
}

Phase III major API changes for AppPage

Meegolabs ApplicationPage meego-ux-components AppPage
variant windowModel -
variant windowFilterPayload -
string title string pageTitle
item content -
bool fullContent bool fullContent
bool fullscreen bool fullScreen
bool showSearch -
bool disableSearch -
bool showToolbar -
bool hasBack -
int toolbarHeight -
bool moving -
variant applicationData -
int type -
alias menuContent variant actionMenuModel
alias menuItem variant actionMenuPayload
- string actionMenuTitle
alias menuWidth -
alias menuHeight -
function closeMenu() -
signal close() -
signal filterTriggered(int index, variant payload) signal actionMenuTriggered( variant selectedItem )
- signal actionMenuIconClicked( int mouseX, int mouseY )
signal addApplicationPage(variant component) -
signal search(string needle) -

Phase III major API changes for Window:

meegolabs Window meego-ux Window
bool foreground bool isActiveWindow
bool transparent -
string title string toolBarTitle
string[] filterModel string[] bookMenuModel
string[] filterPayload string[] bookMenuPayload
- string bookMenuTitle
- bool bookMenuHighlightSelection
- string[] actionMenuModel
- string[] actionMenuPayload
- string actionMenuTitle
- bool actionMenuHighlightSelection
int filterMenuWidth -
signal filterTriggered(int index, variant payload) -
- signal actionMenuTriggered( variant selectedItem )
- signal actionMenuIconClicked( int mouseX, int mouseY )
Component applicationPage -
alias currentApplication -
variant applicationData -
item content: innerContent -
item container: outerContent -
int orientation int orientation
bool orientationLocked bool isOrientationLocked
bool orientationTransitionEnabled -
- string lockOrientationIn
bool fullScreen bool fullScreen
bool fullContent bool fullContent
bool showtoolbar -
bool showsearch bool showToolBarSearch
signal search(string needle) signal search(string needle)
alias statusBar -
color backgroundColor -
color sidepanelBackgroundColor -
bool showStartupAnimation -

Migration from MouseArea to GestureMouseArea

Most components and Apps are using MouseAreas instead of GestureAreas right now. In order to help on the first step of migration one can use the new GestureMouseArea from the MeeGo.Labs.Components. This Component simulated (nearly) the API of a MouseArea, but using the GestureArea internally for recognition of gestures, with the advantage to have a certain fuzziness in the opposite to the MouseArea. This component will be deprecated once, because the goal is to use the GestureArea everywhere as standard for Gestures.

Differences in the API

There is basically one big difference in the API of GestureMouseArea: Instead of an MouseEvent object, all signals are pushing 3 paramter: int mouseX and int mouseY for the position and a bool wasHeld for regocnition of a TapAndHold Gesture

Migration Example

using the MouseArea: 

import Qt 4.7

MouseArea {
   id: mouseArea
   anchors.fill: parent

   onClicked: {
       aProperty = true
       aObject.x = mouse.x
       aObject.x = mouse.y
   }

   onPressAndHold: {
       aProperty = false
       aObject.x = mouse.x
       aObject.y = mouse.y
   }

}

using the GestureMouseArea: 

import Qt 4.7
import MeeGo.Labs.Components 0.1

GestureMouseArea {
   id: mouseArea
   anchors.fill: parent

   onClicked: {
       aProperty = true
       aObject.x = mouseX
       aObject.y = mouseY
   }

   onPressAndHold: {
       aProperty = false
       aObject.x = mouseX
       aObject.y = mouseY
   }
}
Retrieved from "http://wiki.meego.com/Components_Migration"
Personal tools