From wiki.ginstr.com
Jump to: navigation, search
m (Overview)
Line 6: Line 6:
 
ginstr widgets are based on Android widgets and their behaviour is similar. For information about Android widgets refer to [http://developer.android.com/reference/android/widget/package-summary.html Android Documentation].
 
ginstr widgets are based on Android widgets and their behaviour is similar. For information about Android widgets refer to [http://developer.android.com/reference/android/widget/package-summary.html Android Documentation].
  
Widgets can be divided in two groups:
+
Widgets can be divided into two groups:
::;1. Android widgets : all [http://developer.android.com/reference/android/widget/package-summary.html native Android widgets] (under heading '''“Classes”'''). Widgets are provided by Android system.
+
::;1. Android widgets : all [http://developer.android.com/reference/android/widget/package-summary.html native Android widgets] (see under '''“Classes”'''). Widgets are provided by Android system.
 
::;2. ginstr widgets : custom made widgets. They can be composite widgets that consist of multiple Android views or a single view with special functionality.
 
::;2. ginstr widgets : custom made widgets. They can be composite widgets that consist of multiple Android views or a single view with special functionality.
 
Each file in '''“layout”''' folder is called layout. Mandatory layouts are [[activity.xml]] and [[start.xml]]. These layouts consist of widgets. Layout can have one top element (widget) as mentioned [[Ginstr_app#Layout | here]].  
 
Each file in '''“layout”''' folder is called layout. Mandatory layouts are [[activity.xml]] and [[start.xml]]. These layouts consist of widgets. Layout can have one top element (widget) as mentioned [[Ginstr_app#Layout | here]].  
Line 20: Line 20:
 
Attributes define how each widget behaves and what it looks like. Android widgets have attributes described for each widget, for example <code>[http://developer.android.com/reference/android/widget/TextView.html TextView]</code>, <code>[http://developer.android.com/reference/android/widget/ImageView.html ImageView]</code>, <code>[http://developer.android.com/reference/android/widget/EditText.html EditText]</code> (look under '''XML attributes''' and '''Inherited XML attributes'''). Each attribute has a description what its function is. This is provided for all Android widgets in [http://developer.android.com/reference/android/widget/package-summary.html Android Documentation].
 
Attributes define how each widget behaves and what it looks like. Android widgets have attributes described for each widget, for example <code>[http://developer.android.com/reference/android/widget/TextView.html TextView]</code>, <code>[http://developer.android.com/reference/android/widget/ImageView.html ImageView]</code>, <code>[http://developer.android.com/reference/android/widget/EditText.html EditText]</code> (look under '''XML attributes''' and '''Inherited XML attributes'''). Each attribute has a description what its function is. This is provided for all Android widgets in [http://developer.android.com/reference/android/widget/package-summary.html Android Documentation].
  
::Example Android widget with attributes:  
+
Example Android widget with attributes:  
[[File:attributes_example.png|frame|center|16.Attributes example]]
+
<source lang="xml">
 +
<TextView
 +
    android:id="@+id/txtView1"
 +
    android:layout_width="match_parent"
 +
    android:layout_height="wrap_content"
 +
    android:layout_marginBottom="20dp"
 +
    android:layout_marginLeft="20dp"
 +
    android:layout_marginRight="20dp"
 +
    android:layout_marginTop="20dp"
 +
    android:autoLink="email"
 +
    android:singleLine="false"
 +
    android:text="@string/test_string"
 +
    android:textColor="#FFFFFF"
 +
    android:textColorLink="#82CAFA"
 +
    android:textSize="14sp"
 +
    android:textStyle="bold"
 +
    android:typeface="sans" />
 +
</source>
  
To use ginstr namespace attributes user has to define custom namespace in top (root) element (widget) of the layout. <code>xmlns:ek=http://schemas.ginstr.com/ginstr</code>. To define custom attribute following syntax is used, <code>gn:customAttributeName=“attributeValue“</code>
+
To use ginstr namespace attributes user has to define custom namespace in top (root) element (widget) of the layout. <code>xmlns:ek=http://schemas.ginstr.com/ginstr</code>. To define custom attributes, the following syntax is used <code>gn:customAttributeName=“attributeValue“</code>
  
::Example of a ginstr widget with attributes:
+
Example of a ginstr widget with attributes:
[[File:ginstr_widget_with_attributes.png|frame|center|17. ginstr widget with attributes]]
+
<source lang="xml">
 +
<de.einakoon.ag.widgets.EnPhoneAction
 +
    android:layout_width="50dp"
 +
    android:layout_height="50dp"
 +
    ek:s_email="example@email.com" />
 +
</source>
  
 
===Mandatory attributes===
 
===Mandatory attributes===
<span style="color:#FF0000">'''!IMPORTANT!'''</span> Each widget has to have <code>android:layout_width</code>, <code>android:layout_height</code> defined. Custom widgets need custom ginstr attribute defined to work properly, check layout configuration of each [[Widget_Library | widget]]. An attribute marked with asterisk (<code>*</code>) is a mandatory parameter when creating widget.
+
<span style="color:red">'''!IMPORTANT!'''</span> Each widget has to have <code>android:layout_width</code>, <code>android:layout_height</code> defined. Custom widgets need custom ginstr attribute defined to work properly, check layout configuration of each [[Widget_Library | widget]]. An attribute marked with asterisk (<span style="color:red"> '''*'''</span>) is a mandatory parameter when creating widget.
  
 
===Widgets positioning===
 
===Widgets positioning===
One of the most important things is how to handle widget positioning within container widgets. Positioning depends on each widget within a container which depends on the container which contains it. If a widget is contained for example in <code>[http://developer.android.com/reference/android/widget/LinearLayout.html LinearLayout]</code> it will not have the same positioning options as in <code>[http://developer.android.com/reference/android/widget/RelativeLayout.html RelativeLayout]</code>.
+
One of the most important things is how to handle widget positioning within container widgets. Positioning depends on each widget within a container, which in turn depends on the container which contains it. If a widget is contained for example in <code>[http://developer.android.com/reference/android/widget/LinearLayout.html LinearLayout]</code> it will not have the same positioning options as in <code>[http://developer.android.com/reference/android/widget/RelativeLayout.html RelativeLayout]</code>.
  
 
For an introduction on the two most common containers read [http://developer.android.com/reference/android/widget/LinearLayout.html this] (linear) and [http://developer.android.com/reference/android/widget/RelativeLayout.html this] (relative).
 
For an introduction on the two most common containers read [http://developer.android.com/reference/android/widget/LinearLayout.html this] (linear) and [http://developer.android.com/reference/android/widget/RelativeLayout.html this] (relative).
Line 42: Line 64:
  
 
===Widget data persistence===
 
===Widget data persistence===
<span style="color:#FF0000">'''!IMPORTANT!'''</span> To enable widgets that retrieve data from a user to retain data between orientation changes a unique id for widget within that layout has to be provided. Id has to be identical in both layouts (landscape/portrait). It is encouraged to use portrait only layout due to better visibility on phone Android devices.
+
<span style="color:red">'''!IMPORTANT!'''</span> To enable widgets that retrieve data from a user to retain data between orientation changes, a unique id must be provided for a widget within that layout. Id must be identical in both layouts (landscape/portrait). It is encouraged to use portrait mode only due to better visibility on Android phone devices.
  
::Example:
+
Example:
[[File:ID_for_persistence.png|frame|center|18. ID for persistence]]
+
<source lang="xml">
 +
<EditText
 +
    android:id="@+id/txtView1"
 +
    android:layout_width="match_parent"
 +
    android:layout_height="wrap_content"
 +
/>
 +
</source>
  
 
==Further Reading==
 
==Further Reading==
 
===[[Widget Library]]===
 
===[[Widget Library]]===

Revision as of 13:39, 24 June 2016

Overview

Widgets are building blocks of ginstr launcher. ginstr widgets have some internal functionality like taking a photo, calling a number.

ginstr widgets are based on Android widgets and their behaviour is similar. For information about Android widgets refer to Android Documentation.

Widgets can be divided into two groups:

1. Android widgets 
all native Android widgets (see under “Classes”). Widgets are provided by Android system.
2. ginstr widgets 
custom made widgets. They can be composite widgets that consist of multiple Android views or a single view with special functionality.

Each file in “layout” folder is called layout. Mandatory layouts are activity.xml and start.xml. These layouts consist of widgets. Layout can have one top element (widget) as mentioned here.

Widgets can be divided by nesting:

1. Container widgets (ViewGroups) 
those widgets are used as containers for other widgets. The purpose is positioning assistance and layout organization. The most important are: LinearLayout, RelativeLayout, ScrollView (can have one child), FrameLayout. More are mentioned here.
2. Action widgets 
widgets that can’t nest or contain widgets within them. These widgets are used for providing functionality to app (i.e. input text, display text, call phone, send text message…), some of those are (TextView, ImageView, EditText, GnEditText, GnMediaAction…)

Widget Library contains all custom ginstr widgets that contain features not provided out of the box by Android.

Attributes

Attributes define how each widget behaves and what it looks like. Android widgets have attributes described for each widget, for example TextView, ImageView, EditText (look under XML attributes and Inherited XML attributes). Each attribute has a description what its function is. This is provided for all Android widgets in Android Documentation.

Example Android widget with attributes: <source lang="xml"> <TextView

   android:id="@+id/txtView1"
   android:layout_width="match_parent"
   android:layout_height="wrap_content"
   android:layout_marginBottom="20dp"
   android:layout_marginLeft="20dp"
   android:layout_marginRight="20dp"
   android:layout_marginTop="20dp"
   android:autoLink="email"
   android:singleLine="false"
   android:text="@string/test_string"
   android:textColor="#FFFFFF"
   android:textColorLink="#82CAFA"
   android:textSize="14sp"
   android:textStyle="bold"
   android:typeface="sans" />

</source>

To use ginstr namespace attributes user has to define custom namespace in top (root) element (widget) of the layout. xmlns:ek=http://schemas.ginstr.com/ginstr. To define custom attributes, the following syntax is used gn:customAttributeName=“attributeValue“

Example of a ginstr widget with attributes: <source lang="xml"> <de.einakoon.ag.widgets.EnPhoneAction

   android:layout_width="50dp"
   android:layout_height="50dp"
   ek:s_email="example@email.com" />

</source>

Mandatory attributes

!IMPORTANT! Each widget has to have android:layout_width, android:layout_height defined. Custom widgets need custom ginstr attribute defined to work properly, check layout configuration of each widget. An attribute marked with asterisk ( *) is a mandatory parameter when creating widget.

Widgets positioning

One of the most important things is how to handle widget positioning within container widgets. Positioning depends on each widget within a container, which in turn depends on the container which contains it. If a widget is contained for example in LinearLayout it will not have the same positioning options as in RelativeLayout.

For an introduction on the two most common containers read this (linear) and this (relative).

Example: Widget in RelativeLayout has the ability to position itself relative to other views by attribute (example under positions widget containing this attribute to right of widget with id mentioned in attribute)
android:layout_toRightOf=”@+id/idOfAnotherElementInThisContainer”

Practice is needed to learn those few containers and their abilities. With combinations of containers any positioning can be achieved.

Widget data persistence

!IMPORTANT! To enable widgets that retrieve data from a user to retain data between orientation changes, a unique id must be provided for a widget within that layout. Id must be identical in both layouts (landscape/portrait). It is encouraged to use portrait mode only due to better visibility on Android phone devices.

Example: <source lang="xml"> <EditText

   android:id="@+id/txtView1"
   android:layout_width="match_parent"
   android:layout_height="wrap_content"

/> </source>

Further Reading

Widget Library