1 /*

     2 * Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *

    16 */

    17 

    18 

    19 #ifndef _CHROMESNIPPETJSOBJECT_H_INCLUDED

    20 #define _CHROMESNIPPETJSOBJECT_H_INCLUDED

    21 

    22 #include "chromesnippet.h"

    23 #include "utilities.h"

    24 #include "visibilityanimator.h"

    25 #include "attentionanimator.h"

    26 

    27 /*! \brief Javascript wrapper for ChromeSnippets.  

    28  * The ChromeSnippetJSObject class is a Javascript wrapper for ChromeSnippets.

    29  * All signals, slots and properties of chrome snippets are accessible from javascript.  Snippets are children of the 

    30  * \c window.snippets object and as such can be accessed using their DOM element ids.

    31  * For example, given a snippet defined in HTML like this:

    32  * \code

    33  * <div class="GinebraSnippet" id="ExampleSnippet" name="example" 

    34  *      data-GinebraAnchor="AnchorTop" data-GinebraVisible="false">

    35  *      ...

    36  * </div>

    37  * \endcode

    38  * You can show it on-screen from Javascript like this:

    39  * \code

    40  * window.snippets.ExampleSnippet.show();

    41  * \endcode  

    42  */

    43 class ChromeSnippetJSObject : public QObject {

    44     Q_OBJECT

    45   public:

    46     ChromeSnippetJSObject(QObject *parent, ChromeSnippet &snippet, const QString &objName) 

    47 	  : QObject(parent),

    48 		m_snippet(snippet) {

    49         setObjectName(objName);

    50     }

    51     

    52   signals:

    53     // Sent when the snippet starts being dragged.

    54     void dragStarted();

    55 

    56     // Sent when the snippet has finished being dragged.

    57     void dragFinished();

    58     

    59     // Sent when the snippet is shown.

    60     void onShow();

    61 

    62     // Sent when the snippet is hidden.

    63     void onHide();

    64   

    65   public slots:

    66     // Show the snippet.  If useAnimation is true the animation set with

    67     // setVisibilityAnimator() will be used.

    68     // \sa setVisibilityAnimator

    69     void show(bool useAnimation = true) { m_snippet.show(useAnimation); }

    70 

    71     // Hide the snippet.  If useAnimation is true the animation set with

    72     // setVisibilityAnimator() will be used.

    73     // \sa setVisibilityAnimator

    74     void hide(bool useAnimation = true) { m_snippet.hide(useAnimation); }

    75 

    76     // Toggle the visibility of the snippet.  If it is hidden this function

    77     // will show it and vice versa.  Visibility animations will be used.

    78     void toggleVisibility() { m_snippet.toggleVisibility(); }

    79 

    80     // Toggle attention animation of the snippet.

    81     // \sa setAttentionAnimator

    82     void toggleAttention() { m_snippet.toggleAttention(); }

    83 

    84     // Starts an animation timer.  Returns an animation object that can rotate, move or fade the snippet.

    85     // 

    86     // \sa GraphicsItemAnimation

    87     QObject *animate(int duration) { return m_snippet.animate(duration); }

    88 

    89     // Set the position of the snippet's upper-left corner on the screen.

    90     // \sa position

    91     void setPosition(int x, int y) { m_snippet.setPosition(x, y); }

    92     QString getDisplayMode(){ return m_snippet.getDisplayMode(); }

    93     bool getContextMenuFlag(){ return ChromeSnippet::getContextMenuFlag();}

    94     

    95     // Set the animation that is triggered when the snippet is shown or hidden.

    96     // \param animatorName Possible values are:

    97     // \li "G_VISIBILITY_FLYOUT_ANIMATOR"

    98     // \li "G_VISIBILITY_FADE_ANIMATOR"

    99     // \li "G_VISIBILITY_SLIDE_ANIMATOR"

   100     // \li "G_VISIBILITY_MALSTROM_ANIMATOR"

   101     void setVisibilityAnimator(const QString &animatorName) { m_snippet.setVisibilityAnimator(animatorName); }

   102     

   103     // Set the animation that is triggered when the snippet wants attention.

   104     // \param animatorName Possible values are:

   105     // \li "G_ATTENTION_BOUNCE_ANIMATOR"

   106     // \li "G_ATTENTION_PULSE_ANIMATOR"

   107     void setAttentionAnimator(const QString &animatorName) { m_snippet.setAttentionAnimator(animatorName); }

   108 

   109     // return true if snippet graphicItem is visible

   110     bool isVisible() {return m_snippet.isVisible();}

   111     

   112     // Print info about the snippet to debug output.

   113     void dump() const { m_snippet.dump(); }

   114     

   115 

   116     // repaint the snippet

   117     void repaint() { m_snippet.repaint();}

   118 

   119   public:

   120     /*! The id of the DOM element of this snippet.  This is the value set in

   121      * the HTML id tag in the chrome file. 

   122      * In the example below "ExampleSnippet" is the id.

   123      * \code 

   124      * <div class="GinebraSnippet" id="ExampleSnippet" name="example" 

   125      *      data-GinebraAnchor="AnchorTop" data-GinebraVisible="true">

   126      * ...

   127      * </div>

   128      * \endcode

   129      */

   130     Q_PROPERTY(QString id READ getId)

   131     QString getId() const { return m_snippet.docElementId(); }

   132     

   133     /*! The snippet's screen geometry.

   134      * Example javascript code:

   135      * \code var width = window.snippets.ExampleSnippet.geometry.width;

   136      * \endcode

   137      */

   138     Q_PROPERTY(QObject * geometry READ getGeometry)

   139     // \sa geometry

   140     QObject *getGeometry() const { return m_snippet.getGeometry(); }

   141     

   142     /*! 

   143      * \property position

   144      * \brief The position of the snippet's top-left corner.

   145      * Example javascript code:

   146      * \code var x = window.snippets.ExampleSnippet.position.x;

   147      * \endcode

   148      */

   149     Q_PROPERTY(QObject * position READ getPosition)

   150     // \sa position

   151     QObject *getPosition() const { return m_snippet.getPosition(); }

   152     

   153     /*! 

   154      * \property draggable

   155      * \brief True if the snippet can be dragged with the mouse/touch.  Defaults to false.

   156      * \sa dragStarted

   157      * \sa dragFinished

   158      */    

   159     Q_PROPERTY(bool draggable READ getDraggable WRITE setDraggable)

   160     // \sa draggable

   161     bool getDraggable() const { return m_snippet.draggable(); }

   162     // \sa draggable

   163     void setDraggable(bool value) { m_snippet.setDraggable(value); }

   164     

   165     // The z-order value of the snippet.

   166     Q_PROPERTY(qreal zValue READ getZValue WRITE setZValue)

   167     // \sa zValue

   168     qreal getZValue() const { return m_snippet.zValue(); }

   169     // \sa zValue

   170     void setZValue(qreal value) { m_snippet.setZValue(value); }

   171 

   172     /*!

   173      * \property isHiding

   174      * \brief True if the snippet is hiding behind other snippets.

   175      */

   176     bool isHiding() const { return m_snippet.isHiding(); }

   177     void setHiding(bool value) { return m_snippet.setHiding(value); }

   178     Q_PROPERTY(int isHiding READ isHiding WRITE setHiding)

   179     

   180     // Determines where the snippet is displayed.  When "AnchorTop" or "AnchorBottom"

   181     // are used the size of the content viewport is reduced to allow the snippet to

   182     // fit in above or below it.  The default value is "AnchorNone".

   183     // Possible values are:

   184     // \li "AnchorTop"

   185     // \li "AnchorBottom"

   186     // \li "AnchorCenter"

   187     // \li "AnchorFullScreen"

   188     // \li "AnchorNone" - Position is determined by the \ref position property.

   189     Q_PROPERTY(QString anchor READ getAnchor WRITE setAnchor)

   190     // \sa anchor

   191     QString getAnchor() { return m_snippet.anchor(); }

   192     // \sa anchor

   193     void setAnchor(const QString& anchor) { m_snippet.setAnchor(anchor); }

   194     

   195     Q_PROPERTY(int anchorOffset READ getAnchorOffset WRITE setAnchorOffset)

   196     // \sa anchorOffset

   197     int getAnchorOffset() { return m_snippet.anchorOffset(); }

   198     // \sa anchorOffset

   199     void setAnchorOffset(int anchorOffset) { m_snippet.setAnchorOffset(anchorOffset); }

   200     

   201     // Set to true if the snippet should cover the content viewport.

   202     Q_PROPERTY(bool hidesContent READ getHidesContent WRITE setHidesContent)

   203     // \sa hidesContent

   204     bool getHidesContent(){ return m_snippet.hidesContent();}

   205     // \sa hidesContent

   206     void setHidesContent(bool hidesContent) { m_snippet.setHidesContent(hidesContent); }

   207     

   208   private:

   209     ChromeSnippet &m_snippet;

   210     

   211     friend class ChromeSnippet;

   212 };

   213 

   214 

   215 #endif  // _CHROMESNIPPETJSOBJECT_H_INCLUDED