Monthly Archives: December 2013

Make your App Social with BBM, Part II

Hier ist wieder @leaschnherr mit dem zweiten Teil, indem ich beschreibe wie dein BBM Profil via App verändert werden kann. Dafür muss die App zunächst bei BBM registriert sein. Eine Beschreibung der notwendigen Schritte ist hier zu finden, im ersten Teil dieser Serie. Um Zugriff auf das Profil zu bekommen und es zu ändern ist für jeden Parameter der gleiche Prozess notwendig. Manche Parameter können allerdings nur gelesen werden, aber nicht überschrieben werden. Der Status, die Status Nachricht und das Bild können über eine externe App geändert werden. Hierfür zeige ich die Vorgehensweise in einem Beispiel, welches dann für alle Parameter nach dem gleichen Prinzip durchgeführt werden kann.

Vor dem C++ Code müssen zwei einfach qml Dateien erstellt werden. Die erste zeigt einfach die aktuellen Profil Parameter. In diesem Beispiel werden nur der Name, die Status Nachricht und das Beschäftigt Flag verwendet. Hier ist der qml Code, der als Beispiel genutzt werden kann:

Wichtig ist nur die visible Property vom ImageView und die text Properties vom Name Label und Status Message Label. In diesen Zeilen bekommen die Komponenten die aktuellen Werte aus dem Profil. Es spielt später keine Rolle, welche Quelle die Werte ändert, die Properties werden automatisch aktualisiert.  _profile stammt aus dem C++ Code und wird weiter unten erläutert.

Auch wichtig ist, dass die ganze Page von einem navigationPane umgeben ist, damit über ein action item die nächste qml Datei gepusht werden kann. Dafür darf nicht vergessen werden diese Datei unter attachedObjects hinzuzufügen (hier update.qml genannt).

Diese zweite qml Datei wird dazu genutzt die Profil Daten zu ändern:

Es wird eine checkBox genutzt, um das Beschäftigt Flag zu ändern und ein TextField für die Status Nachricht. Diese Datei sieht sehr ähnlich aus wie die profile.qml, nur dass zusätzlich ein Button zum speichern benötigt wird. Dieser Button nutzt das onClicked() Signal um eine Funktion mit den Properties als Eingabe Parameter aufzurufen (Die Funktion wird später erklärt). Die zweite Zeile stellt sicher, dass zu profile.qml zurückgesprungen wird.

Nachdem die qml Dateien vorbereitet sind werden nur noch wenige Zeilen C++ Code benötigt. In der Profile.hpp werden Macros verwendet um die angezeigten Parameter automatisch zu ändern:

Der erste Wert ist immer der Name, der aus der qml Datei aufgerufen wird. Der nächste Parameter, nach READ, ist die dazugehörige getFunktion um den Wert der Variable zu liefern, welche in der selben Klasse definiert werden muss. Der letzte Parameter, nach NOTIFY, nutzt das Signal profileChanged(), welches in der Header Datei definiert sein muss (als public Signal). Diese Konstruktion sorgt dafür, dass die angezeigten Werte automatisch geändert werden, wenn das Signal profileChanged() aufgerufen wird.

Im ersten Teil dieser Serie wird ein Slot showProfile() aufgerufen. Das ist der Punkt, an dem profile.qml eingefügt wird:

Die Klasse UserProfile ist eine private Variable unserer Klasse, die das aktuelle BBM Profil beinhaltet. Die nächsten Zeilen sind sehr wichtig: Hier wird unser profileChanged() Signal aufgerufen, wenn sich die Parameter im BBM Profil geändert haben, die wir nutzten.

Dann wird die UI erstellt und angezeigt. Hier geben wir dem QmlDocument eine Referenz zu unserer Klasse mit. So ist diese als _profile in der qml Datei bekannt, wie sie zuvor schon genutzt wurde.

Der Button zum speichern update.qml nutzt einen public Slot der noch definiert werden muss:

In der Funktion werden die neuen Werte mit den alten Werten verglichen und für den Fall, dass sich ein Wert geändert hat wird ein Request zum ändern dieses Wertes aufgerufen. Der Vergleich der alten und neuen Werte sieht etwas kompliziert aus, da bevor der Wert tatsächlich geändert wird der Nutzer diese über eine Message Box bestätigen muss. Diese erscheint aus  der UserProfile Klasse. Um also zu vermeiden, dass eine solche Abfrage kommt, obwohl nichts geändert wurde werden in der if-Abfrage alle möglichen Kombination überprüft. Die Parameter werden jetzt im BBM Profil und in der App geändert.

Make your App Social with BBM, Part II

IMG_00000016This is @leaschnherr again, with the second part, where I describe how to modify your BBM Profile via an app. For that the app need to be registered at BBM. A description of the necessary steps can you find here in the first part of this series. To get access to the profile and change it, it is the same procedure for each parameter. Some parameters can only be read but not be overwritten. The status, personal message and the picture can be changed by an extern app. Therefore I show you the steps in an example, which can be duplicated for all parameters.

Before starting with the C++ code, we create two simple qml files. The first only shows your current Profile parameters. In this sample we only use the displayed name, the status message and the busy flag. Here is some qml code which you can use as pattern:

Important are only the visible property of the ImageView and the text properties of the Name Label and the status Message Label. In these lines you get the current values from the profile. Later it doesn’t matter which source change the values, the properties are updated automatically via  _profile, which comes from the C++ code and is explained later.

Important is also, that the whole page is wrapped by a navigationPane, cause we use an action item to push the second qml file. Therefore don’t forget to attach the other qml file (called update.qml).

The second qml file is used to change the profile datas:

A CheckBox is used to modify the busy flag and a TextField for the status message. It looks very similar to the profile.qml, but additionally a button is used to save the new values. This button uses the onClicked signal to call a method with the properties as input parameters  (This method is declared later). The second line in this signal ensures the jump back to the profile.qml.

After preparing the qml files only a few lines of code are required.  In the Profile.hpp macros are used to automatically change the displayed parameters:

The first value is always the parameter, which is called out of the qml file. The next parameter, after READ, is the associated getFunction to returns the variable  (need to be defined in your class). The last parameter, after NOTIFY, use the signal profileChanged() signal, which must be declared in this header file as public signal. This construction now automatically updates the properties in the qml file when the variable in the c++ code changed.  We only have to use the profileChanged() signal.

In the first part of this series a slot showProfile() was used. This is the point the new profile.qml is inserted:

The class UserProfile is a private variable of our class which includes the current BBM profile. The next lines are very important: Here we call our signal profileChanged() when the parameters we use are updated in the BBM profile, so that our displayed datas are changed. Next the UI is created. Here we give the pointer of our class to the QmlDocument. Now the class is known as  _profile in the qml file, which already is used, as you see.

The save button in the update.qml uses a slot which need to be declared as public slot:

Here the value from the input is compared with old value and, in case, a request to change the value is send. The comparison looks a little complicated, because before the profile actually is changed the user has to accept this in a message box, which appears out from the UserProfile class. To avoid the message box if the user changed nothing, the if-construction checks all possible combinations. The parameters are now changed in both, the BBM Profile and the app.