Contents. Quick Downloads Documentation. (Select Java from drop-down menu) Example Code. Libraries. Getting Started with Android Java If you are new to writing code for Phidgets, we recommend starting by running, then modifying existing examples.
This will allow you to:. Make sure your libraries are properly linked. Go from source code to a test application as quickly as possible. Ensure your Phidget is hooked up properly Android Studio Use Our Examples In order to run the examples in Android Studio, all you need to do is download the the relevant example project for your device from:. Next, open Android Studio on your development machine.
Import the project using File-New-Import Project. When you are ready, the next step is configuring your project and writing your own code! Important Note The examples provided are designed to be incredibly simplistic in order to highlight the base requirements to run Phidgets on Android.
To this end, we opted to open and close the Phidgets in the onCreate and onDestroy handlers of the main activity respectively. This is likely a bad idea for implementing apps for any practical use, as the activity is prone to being destroyed and re-created for a wide variety of reasons, from closing the app, to rotating the screen. In order to ensure your Phidget remains attached through these events, we recommend running your Phidgets in a secondary service. Check the section for more information. Creating a New Project When you are building a project from scratch, or adding Phidget functionality to an existing project, you'll need to configure your development environment to properly link the Phidget Java libraries for Android Java.
To start, create a new project in Android Studio. Import com.phidget22.; The project now has access to Phidgets. Next, view the section located below. Write Code By following the instructions for your operating system and compiler above, you now have working examples and a project that is configured. This teaching section will help you understand how the examples were written so you can start writing your own code. Remember: your main reference for writing Android Java code will be the Manual and the.
Step One: Initialize and Open You will need to declare your Phidget object in your code. For example, we can declare a digital input object like this. //Disable USB connection to Phidgets com. Uninitialize ; Further Reading - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.
Learn about these two properties that control how much data comes in from your sensors. It can be difficult to figure out how to use more than one Phidget in your program. This page will guide you through the steps. Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application. Learn about all the tools you can use to debug your program. Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.
Common Problems, Solutions and Workarounds Issue: My Phidget detached when I rotated my phone You are likely using one of our examples, or handling the opening and closing of Phidgets in a similar way. In either case, chances are you are opening and closing Phidgets in your main activity. This is not recommended for practical applications, as the entire activity can be destroyed and re-created many times through its lifecycle due to configuration changes such as rotating the screen. This is a reality of the Android operating system, and must be addressed in whatever way best suits your application. A good option to keep your Phidgets connected would be to implement a or a, depending on your application, and open your Phidgets there.
Quickview. Use resource sets to create a localized app. Android loads the correct resource set for the user's language and locale. If localized resources are not available, Android loads your default resources. In this document. See also. Android runs on many devices in many regions.
To reach the most users, your application should handle text, audio files, numbers, currency, and graphics in ways appropriate to the locales where your application is used. This document describes best practices for localizing Android applications. You should already have a working knowledge of the Java programming language and be familiar with Android resource loading, the declaration of user interface elements in XML, development considerations such as Activity lifecycle, and general principles of internationalization and localization. It is good practice to use the Android resource framework to separate the localized aspects of your application as much as possible from the core Java-based functionality:.
You can put most or all of the contents of your application's user interface into resource files, as described in this document and in. The behavior of the user interface, on the other hand, is driven by your Java-based code. For example, if users input data that needs to be formatted or sorted differently depending on locale, then you would use the Java programming language to handle the data programmatically. This document doesn't cover how to localize your Java-based code.
Android Language Project Application Template
For a short guide to localizing strings in your app, see the training lesson,. Overview: Resource-Switching in Android Resources are text strings, layouts, sounds, graphics, and any other static data that your Android application needs. An application can include multiple sets of resources, each customized for a different device configuration. When a user runs the application, Android automatically selects and loads the resources that best match the device. (This document focuses on localization and locale.
For a complete description of resource-switching and all the types of configurations that you can specify — screen orientation, touchscreen type, and so on — see.) When you write your app, you create default and alternative resources for your app to use. When users run your app, the Android system selects which resources to load, based upon the device's locale.
To create resources, you place files within specially named subdirectories of the project's res/ directory. Why Default Resources Are Important Whenever the application runs in a locale for which you have not provided locale-specific text, Android loads the default strings from res/values/strings.xml. If this default file is absent, or if it's missing a string that your application needs, then your application doesn't run and shows an error.
The example below illustrates what can happen when the default text file is incomplete. Example: An application's Java-based code refers to just two strings, texta and textb. This application includes a localized resource file ( res/values-en/strings.xml) that defines texta and textb in English. This application also includes a default resource file ( res/values/strings.xml) that includes a definition for texta, but not for textb:. When this application is launched on a device with locale set to English, the application might run without a problem, because res/values-en/strings.xml contains both of the needed text strings. However, the user sees an error message and a Force Close button when this application is launched on a device set to a language other than English.
The application doesn't load. To prevent this situation, make sure that a res/values/strings.xml file exists and that it defines every needed string. The situation applies to all types of resources, not just strings: You need to create a set of default resource files containing all the resources that your application calls upon —layouts, drawables, animations, etc. For information about testing, see. Using Resources for Localization How to Create Default Resources Put the application's default text in a file with the following location and name: res/values/strings.xml (required directory) The text strings in res/values/strings.xml should use the default language, which is the language that you expect most of your application's users to speak. The default resource set must also include any default drawables and layouts, and can include other types of resources such as animations. Res/drawable/(required directory holding at least one graphic file, for the application's icon on Google Play) res/layout/ (required directory holding an XML file that defines the default layout) res/anim/ (required if you have any res/anim- folders) res/xml/ (required if you have any res/xml- folders) res/raw/ (required if you have any res/raw- folders) Tip: In your code, examine each reference to an Android resource.
Make sure that a default resource is defined for each one. Also make sure that the default string file is complete: A localized string file can contain a subset of the strings, but the default string file must contain them all. How to Create Alternative Resources A large part of localizing an application is providing alternative text for different languages. In some cases you also provide alternative graphics, sounds, layouts, and other locale-specific resources. An application can specify many res/ / directories, each with different qualifiers.
To create an alternative resource for a different locale, you use a qualifier that specifies a language or a language-region combination. (The name of a resource directory must conform to the naming scheme described in, or else your app cannot compile.) Example: Suppose that your application's default language is English. Suppose also that you want to localize all the text in your application to French, and most of the text in your application (everything except the application's title) to Japanese. In this case, you could create three alternative strings.xml files, each stored in a locale-specific resource directory:. res/values/strings.xml Contains English text for all the strings that the application uses, including text for a string named title. res/values-fr/strings.xml Contain French text for all the strings, including title. res/values-ja/strings.xml Contain Japanese text for all the strings except title.
If your Java-based code refers to R.string.title, here is what happens at runtime:. If the device is set to any language other than French, Android loads title from the res/values/strings.xml file. If the device is set to French, Android loads title from the res/values-fr/strings.xml file. Notice that if the device is set to Japanese, Android looks for title in the res/values-ja/strings.xml file. But because no such string is included in that file, Android falls back to the default, and loads title in English from the res/values/strings.xml file.
Which Resources Take Precedence? If multiple resource files match a device's configuration, Android follows a set of rules in deciding which file to use. Among the qualifiers that can be specified in a resource directory name, locale almost always takes precedence.
Example: Assume that an application includes a default set of graphics and two other sets of graphics, each optimized for a different device setup:. res/drawable/ Contains default graphics. res/drawable-small-land-stylus/ Contains graphics optimized for use with a device that expects input from a stylus and has a QVGA low-density screen in landscape orientation. res/drawable-ja/ Contains graphics optimized for use with Japanese. If the application runs on a device that is configured to use Japanese, Android loads graphics from res/drawable-ja/, even if the device happens to be one that expects input from a stylus and has a QVGA low-density screen in landscape orientation.
Exception: The only qualifiers that take precedence over locale in the selection process are MCC and MNC (mobile country code and mobile network code). Example: Assume that you have the following situation:. The application code calls for R.string.texta. Two relevant resource files are available:. res/values-mcc404/strings.xml, which includes texta in the application's default language, in this case English.
res/values-hi/strings.xml, which includes texta in Hindi. The application is running on a device that has the following configuration:. The SIM card is connected to a mobile network in India (MCC 404). The language is set to Hindi ( hi). Android loads texta from res/values-mcc404/strings.xml (in English), even if the device is configured for Hindi. That is because in the resource-selection process, Android prefers an MCC match over a language match. The selection process isn't always as straightforward as these examples suggest.
Please read for a more nuanced description of the process. All the qualifiers are described and listed in order of precedence in. Referring to Resources in Java-based code In your application's Java-based code, you refer to resources using the syntax R. Resourcename or android.R.
For more about this, see. Managing strings for localization Move all strings into strings.xml As you build your apps, don't hard code any string. Instead, declare all of your strings as resources in a default strings.xml file, which makes it easy to update and localize. Strings in the strings.xml file can then be easily extracted, translated, and integrated back into your app (with appropriate qualifiers) without any changes to the compiled code. If you generate images with text, put those strings in strings.xml as well, and regenerate the images after translation. Follow Android guidelines for UI strings As you design and develop your UIs, make sure that you pay close attention to how you talk to your user.
In general, use a that is friendly but brief, and use a consistent style throughout your UIs. Make sure that you read and follow the Material Design recommendations for. Doing so makes your apps appear more polished to the user and helps users understand your UI more quickly. Also, always use Android standard terminology wherever possible—such as for UI elements such as Action Bar, Options Menu, System Bar, Notifications, and so on. Using Android terms correctly and consistently makes translation easier and results in a better end-product for users. Provide sufficient context for declared strings As you declare strings in your strings.xml file, make sure to describe the context in which the string is used. This information is invaluable to the translator and result in better quality translation.
It also helps you manage your strings more effectively. Here is an example: Sign in Consider providing context information that may include:. What is this string for? When and where is it presented to the user?. Where is this in the layout?
For example, translations are less flexible in buttons than in text boxes. Mark message parts that should not be translated Often strings contain contain text that should not be translated into other languages. Common examples might be a piece of code, a placeholder for a value, a special symbol, or a name. As you prepare your strings for translation, look for and mark text that should remain as-is, without translation, so that the translator doesn't change it. To mark text that should not be translated, use an placeholder tag.
Here is an example tag that ensures the text '%1$s' isn't changed during translation (otherwise it could break the message):%1$suntil holiday When you declare a placeholder tag, always add an id attribute that explains what the placeholder is for. If your apps later replace the placeholder value, be sure to provide an example attribute to clarify the expected use. Here are some more examples of placeholder tags: Check out our 5 u2605 Visit us at Learn more at Game Group Please use the 'ABCDEFG' to get a discount. Localization Checklist For a complete overview of the process of localizing and distributing an Android application, see the document.
Localization Tips Design your application to work in any locale You cannot assume anything about the device on which a user runs your application. The device might have hardware that you were not anticipating, or it might be set to a locale that you did not plan for or that you cannot test.
Design your application so that it functions normally or fails gracefully no matter what device it runs on. Important: Make sure that your application includes a full set of default resources. Make sure to include res/drawable/ and a res/values/ folders (without any additional modifiers in the folder names) that contain all the images and text that your application needs.
If an application is missing even one default resource, it doesn't run on a device that is set to an unsupported locale. For example, the res/values/strings.xml default file might lack one string that the application needs: When the application runs in an unsupported locale and attempts to load res/values/strings.xml, the user sees an error message and a Force Close button.
For more information, see. Design a flexible layout If you need to rearrange your layout to fit a certain language (for example German with its long words), you can create an alternative layout for that language (for example res/layout-de/main.xml). However, doing this can make your application harder to maintain. It is better to create a single layout that is more flexible. Another typical situation is a language that requires something different in its layout. For example, you might have a contact form that should include two name fields when the application runs in Japanese, but three name fields when the application runs in some other language. You could handle this in either of two ways:.
Create one layout with a field that you can programmatically enable or disable, based on the language, or. Have the main layout include another layout that includes the changeable field. The second layout can have different configurations for different languages. Avoid creating more resource files and text strings than you need You probably don't need to create a locale-specific alternative for every resource in your application. For example, the layout defined in the res/layout/main.xml file might work in any locale, in which case there would be no need to create any alternative layout files. Also, you might not need to create alternative text for every string.
For example, assume the following:. Your application's default language is American English. Every string that the application uses is defined, using American English spellings, in res/values/strings.xml. For a few important phrases, you want to provide British English spelling. You want these alternative strings to be used when your application runs on a device in the United Kingdom. To do this, you could create a small file called res/values-en-rGB/strings.xml that includes only the strings that should be different when the application runs in the U.K. For all the rest of the strings, the application falls back to the defaults and use what is defined in res/values/strings.xml.
Use the Android Context object for manual locale lookup You can look up the locale using the object that Android makes available: String locale = context.getResources.getConfiguration.locale.getDisplayName; Use the App Translation Service The is integrated into the, and it is also accessible from. It is a quick and simple way to get an instant quote and place an order with a translation company. You can order translations into one or more languages for app UI strings, Play Store Listing text, IAP names, and ad campaign text. Testing Localized Applications Testing on a Device Keep in mind that the device you are testing may be significantly different from the devices available to consumers in other geographies. The locales available on your device may differ from those available on other devices. Also, the resolution and density of the device screen may differ, which could affect the display of strings and drawables in your UI.
To change the locale or language on a device, use the Settings application. Testing on an Emulator For details about using the emulator, see. Creating and using a custom locale A 'custom' locale is a language/region combination that the Android system image does not explicitly support. You can test how your application runs in a custom locale by creating a custom locale in the emulator. There are two ways to do this:.
Use the Custom Locale application, which is accessible from the Application tab. (After you create a custom locale, switch to it by pressing and holding the locale name.). Change to a custom locale from the adb shell, as described below. When you set the emulator to a locale that isn't available in the Android system image, the system itself displays in its default language. Your application, however, should localize properly. Changing the emulator locale from the adb shell To change the locale in the emulator by using the adb shell.
Pick the locale you want to test and determine its BCP-47 language tag, for example, Canadian French would be fr-CA. Launch an emulator. From a command-line shell on the host computer, run the following command: adb shell or if you have a device attached, specify that you want the emulator by adding the -e option: adb -e shell. At the adb shell prompt ( #), run this command: setprop persist.sys.locale BCP-47 language tag;stop;sleep 5;start Replace bracketed sections with the appropriate codes from Step 1. For instance, to test in Canadian French: setprop persist.sys.locale fr-CA;stop;sleep 5;start This causes the emulator to restart. (It looks like a full reboot, but it isn't.) Once the Home screen appears again, re-launch your application, and the application launches with the new locale.
Testing for Default Resources Here's how to test whether an application includes every string resource that it needs:. Set the emulator or device to a language that your application does not support. For example, if the application has French strings in res/values-fr/ but does not have any Spanish strings in res/values-es/, then set the emulator's locale to Spanish.
(You can use the Custom Locale application to set the emulator to an unsupported locale.). Run the application. If the application shows an error message and a Force Close button, it might be looking for a string that isn't available. Make sure that your res/values/strings.xml file includes a definition for every string that the application uses.
If the test is successful, repeat it for other types of configurations. For example, if the application has a layout file called res/layout-land/main.xml but does not contain a file called res/layout-port/main.xml, then set the emulator or device to portrait orientation and see if the application runs.