From wiki.ginstr.com
Jump to: navigation, search

Showcase (demo) app

This is a pre-made example of ginstr launcher functionality to better understand how to make ginstr apps using examples. This example also serves to test if all components are working as they should. For a designer to fully understand this application, the content of the app should be checked, XML files named code#filename.xml marker in the following text.

This application is a work in progress as new functionality is added so should new components be added to this application and this document.

ginstr launcher tests

App is divided into tests where each test focuses on showing the designer via XML how to reproduce some control or a behavior. Tests included in showcase app are :

1. Navigation tests
explains basic layout switching techniques and provides better understanding of global events code#navigation_menu.xml.
2. Container tests
explains basic positioning capabilities. How to use containers to achieve various layouts code#containers_menu.xml.
3. Google widget tests
tests on Android widgets that are working in ginstr launcher including those that are not working code#google_widgets_menu.xml. Also explained here is how to use google documentation to add more parameters.
4. Custom widget tests
tests on custom created widgets from ginstr. code#custom_widgets_menu.xml. To understand custom widgets look in the widget library while going through the XML file.
5. Orientation tests
tests on layouts and widget behavior while rotating the device. /layout/code#orientation_menu.xml and /layout-land/code#orientation_menu.xml . Those files are related and both used to describe this test.
6. Resources tests
tests and explanation of basic resource managing within app. Fall-back scenarios, alternative resources. code#resource_menu.xml, values/strings.xml , values-en/strings.xml

Navigation tests

Navigation is closely related to events and actions. Read that chapter before beginning this test. Navigation is achieved by using attributes mentioned in the events & actions chapter. To define a layout switch, it’s necessary to use an attribute for a desired event and as value set destination layout. code#naviation_menu.xml and example here: <Button ..other attributes.. gn:toLayoutSwipe="@+id/navigation0" />

Container tests

Containers help to position items better within a layout. Each container has certain attributes and with combinations of containers you can achieve any layout. code#containers_menu.xml.

Google widget tests

Android widgets are predefined widgets made by Google with certain functionalities, which are described on their website. To understand how to use an Android widget and to know which attributes it has and what can and cannot be done an example of the TextView widget will be explained. Each widget has its own attributes and inherited attributes. Own attributes are specific for only that widget. Check code#google_widgets_menu.xml for list of Android widgets that work in ginstr launcher and how to initiate them.

When you open an Android web page by clicking TextView, click [Expand All] at top right and look under headings XML Attributes and Inherited XML Attributes.

The tables XML Attributes and Inherited XML Attributes define all possible XML attributes that can be used and would automatically be recognized by ginstr launcher.

Each attribute has a name, method and description. Those that have name matching method (alpha = setAlpha, id = setId) will work automatically, others need to be entered by a developer on request if necessary.

For example look at android:lines attribute:

This will automatically work without intervention of developer because of the attribute matches method (lines = setLines). The designer has to put this attribute on TextView and then define the value. To check what value is requested click on method name setLines(int).
Description for this method states: “Makes the TextView exactly this many lines high. Note that setting this value overrides any other (minimum / maximum) number of lines or height setting. A single line TextView will set this value to one.”
From this explanation it is understood that a number needs to be entered which will make TextView that many lines high.

Custom widget tests

Custom widgets are made for specific purposes. At its base each custom widget is an Android widget. This means that it has all XML attributes of that Android widget in addition to what it’s built for. For example GnImageView has all the XML attributes of ImageView and all XML attributes of View plus the extra feature of setting rotation by attribute, this is inheritance.

If you want to add Android attributes to a widget use examples as in the previous heading. If you want to add custom attributes and view examples how they are used check the file code#custom_widgets_menu.xml.

All ginstr custom attributes look like gn:someAttribute=””

All custom widget attributes are listed in Widget Library for each widget.

Orientation tests

Test and how to guide to provide alternative layout for orientation. Files to check are layout/code#orientation_menu.xml and layout-land/code#orientation_menu.xml. If a different layout of the app in landscape mode is required, a resource folder layout-land needs to be created. Inside that folder a landscape layout that has the same top element id as its portrait layout top element needs to be provided. Compare the two files.

ginstr launcher will load an alternative layout just for layouts from portrait that have matching landscape layout in layout-land folder.

Another important aspect is passing values from portrait to landscape and opposite for widgets that can get user input. Only widgets that have the same id will copy their value from one layout to another. Check and compare the two files mentioned.

Resource tests

Resource tests are needed to have different resources for different app setups, for example local different resource files have to be provided. Relevant files are code#resource_menu.xml, values/strings.xml, values-en/strings.xml. A string example of the above mentioned text.

TextView in files mentioned has set for android:text=”@string/welcome_string”. In values/strings.xml exists string and in values-en as well. If the language of the app is changed to “EN”, the application will load string from values-en folder and not directly from values. If this string was not present in values-en then ginstr launcher would by default load a string that is in values/strings.xml. Images, arrays and other resources work on the same principle.