[Android Apps and Games] daxgirl:
Basic info and app structure

Basic info and app structure:

This application is Navigation Drawer application material design style. It uses app cpmpat in order to use the pager adapter. This can make theming alittle bit tricky, but we provided 2 themes for now which you can modify in styles.

Navigation drawer opens from the left and it contains for now example of navigation items list. For now we have 4 preference fragments and the last items is to set theme. You can add or remove fragments as you wish. The process will be fully explained.

The fragments in the main view container are being replaced based on a position of clicked item in the navigation drawer list. Remember (we will get back to it again), positions in any array begin from 0. That means that for now we have 0,1,2,3,4 items in the arrays that construct the navigation items list. When we add one, we will need to add a title and an icon (both in corresponding positions) and also add our new fragment to a special method which makes the selected items to show specific fragment. We will discuss it at lenght.

For now application contains only preference fragments. If you feel confident and know what you're doing, you can add all kinda fragments and navigation items (even more activities). We concentrate here on preference fragments, because this is the essence.

Each navigation fragment has a java class which extends PreferenceFragment and an xml file inside res/xml folder, where the preferences exist for each fragment. Once launched for the first time, each fragment will create a shared preferences file inside our "home" directory. Our directory is in /data/data/com.wubydax.romcontrol/. There you will find several files and dirs. One of them is called shared_prefs. Inside it each fragment will host it's preference xml file. The name of this file will be identical (by our design) to the name of the xml file for that fragment in /res/xml folder. Once the fragment displayed for the first time, the shared preferences file for it is created and being populated by the default values you set. We will explain later which preferences must have defaultValue set and which preferences MUST NOT.

If you open the java class for any PreferenceFragment, f.e. UIPrefsFragment.java, you will see that the code is very small. That is because we wanted to make things easier for you and we created a class called HandlePreferenceFragment.java, which manages all the work of the fragments.

When you create a new Preference Fragment using a template for android studio we provided, The fragment and it's xml file are created for you automatically. All you will have to do is add it to the item selector in the navigation drawer, of course give it a name and an icon, and you can gop ahead and populate the xml file with preferences. You will not need to touch java anymore if you don't want to.

We have the usual preferences that you know of, like SwitchPreference, CheckboxPreference, ListPreference etc, and we have our own "special" preferences to make your life easier. Those are IntentDialogPreference (to choose an app and write it's intent to the database for you to use in your mods to open apps), FilePreference (to control some booleans by creating and deleting file), we have 2 special kinds of PreferenceScreens: one for running shell scripts and one for creating intent to open apps from the control app. Those preferences will have special kind of keys, which we will demonstrate. You will not need to flash your scripts when flashing your rom. All your scripts will be managed in the assets folder and copied on run time to our home directory and executed from there. You don't need to worry about permissions, all is taken care of. Just place your scripts inside the assets folder before you compile the sources. Sae thing with opening apps as intents, all you need to do is put a main activity full name as PreferenceScreen key. Everything else is taken care of, including displaying icon. The preference will not show at all if the user doen's have an app installed. So no crashes upon clicking on non existing intents. They will just vanish from the list.

The preference files inside the project on github contains BOGUS preferences to use as an example. We will go over all of them (most contained inside first fragment - UIPrefsFragment). They are all active. But they should not trigger any mod, as you should not have those keys in your database. You can see f.e. that preference fragment "Useful apps" has like 5 preferences for app intent. some of them have bogus intent. They will not display when you run your app. They are therer to demonstrate that if the app doesn't exist, you should not worry about FC of Rom Control. It takes care of itself.

The first time the app boots it asks for root permissions. If the device is not rooted or permissions not granted, the app will never run. You all run rooted and modded roms, this app is not for stock. If you wish to disable this function, we will provide that option.

Reboot menu - on the right upper corner of the action bar you will see a reboot icon. Clicking it will show a display of 5 reboot actions: reboot, hotboot, reboot recovery, reboot download, reboot systemui. Youc an access those easily no matter what fragment you're in. Clicking outside of them or clicking back button will make the menu disappear. clicking on one of them will result in immidiate reboot function. Those are root related finctions. We can make them no root dependant once you all use an app in your /system/priv-app. Which, btw, is where we recommend it goes.

How does it work?

For the first time an app is opened (or any time an ap is opened), there is a special method inside HandlePreferenceFragment that is called initAllKeys();. This method goes over all the preferences contained inside the shared preferences for that fragment. One by one it checks their key name, checks if they are of type boolean (true or false), of tipe integer (number) or of type string (words). Then it checks what preference they belong to. It checks if the key for that preference exists in your settings storage database, if it does not - it creates all keys. If the key exists in the database but is different from what the app has - it replaces the one in the app preferences with what you have in your system. That is why it's important for most preferences to set the defaultValue that you wish to be the default, beucase the first time the app launches, it will create all the keys in the system database. once the process is done(you will not see or feel it), your preferences are yours to control. Once a user clicks on Checkbox, if it's selected (isChecked), it writes 1 to the key for that preference inside the Settings.System. and vice versa. Any change in the preferences is being registered immidiately. So your mods can be updated (provided you have observers, of course, or else you might need to reboot apps, just like you always did). Inside the class HandlePreferenceFragment there is a method updateDatabase. it is being called from a method that "wacthes"/"listens" to any change in preference.

That is, basically, all. This is how it works. Everything else is cosmetics made for your convinience and mostly based on your requests. F.e. running shell scripts, FilePreference, App picker preferences was requested by other developers to be included so we had to find a way to build in. Now you can all enjoy. Any further requests are welcome.

Overall structure in studio:

One you have opened the project in studio, you have the following structure tree on your left. Make sure you have chosen the "project" tab (far left edge of the screen) to see it:

Inside the libs folder we have the roottools jar made by the amazing [MENTION=1335872]Stericson[/MENTION] and the next folder that is of interest is the src/main. This is where the app as you know it (from apktool) is hosted. You can see inside the res folder all our resources.

If you need to change the icon for the app you need to place it inside mipmap folders. It's called ic_launcher.png. For nice app icons generator visit here . Inside the values-21 folder there is the styles.xml file that you need to edit if you want to change theme colors. Nice site for coherent material palette is here and google documentation is here.

In the main drawables folder you will find those:

As you can see there are two images there that are relevant to you: header_image and header_image_light (for both themes). Thopse are the header images for the navigation drawer. You can replace them with your own. The reference to them is inside /layout/fragment_navigation_drawer.xml as you can see here:

.

Here it's used as an attribute. You can read more about using attrs in android docs. Just replace the images and keep the names.

Inside of the resolution dependant drawable folders you can find the images for the items in the navigation drawer:

Here you can replace, move and add your own. Good resources for icons are: here and here and you can find many more out there.

Inside the assets folder we have a folder named scripts. It's important the name remains "scripts".

It's used in java code to copy the assets on runtime to our home dir. Inside scripts you put your shell scripts that you wish to run using the script running method. scripts have to be called with .sh in the end. When you create a PreferenceScreen that needs to run scripts, you give it a key like this: android:key = "script#nameofourscript". You do not add the .sh in the key. Look at the example inside ui_prefs.xml in PreferenceScreen with key android:key = "script#test". This runs the script that is currently found in assets. which basically writes into a file on your sdcard. Here you can put scripts as complex a you like. The code checkes for the exit code of the script. as long as it is 0, it will print a toast "executed successfully" upon clicking your preference. To try it run the app on your phone and click on a preference screen with summary "Click see what happens". Make sure your scripts are well formed and test them before including. Remember that you're under sudo. Linux shell will execute anything under sudo without asking.

Inside the /res/xml folder are our preference xml files. This will be your main playground. In those files we will be adding the preference items to appear in each of your fragments.

And finally for the java classes:

Here is where all the work is being done in real time. If you don't have expirience, you won't have to go there besides when you need to add the more nav drawer items.

Adding a new fragment and navigation drawer list item:

1. Provided you read the OP instructions and cloned the Rom Control Preference Fragment template repository into /your android adt directory/android-studio/plugins/android/lib/templates/other/, you need to restart android studio and we are ready to go.

2. Right click on the main java package of out application and navigate to New > Fragment > Fragment (6thGear Preference Fragment) like you can see on the picture below:

Once you click on adding the fragment the foloowing window will open:

As you can see the initial names are: for fragment - BlankFragment and for xml blank_prefs. You can change it as you like. BUT! Leave the word Fragment. Once you change the FIRST part of the fragment name, the first part of the prefs file name will be changed automatically. See the img below:

So we have chosen to create a new fragment called PowerMenuFragent and below that we have the preference xml name. the name is automatically generated as you put in your class name for the fragment. The java naming convention states that a class must begin with capital letter and all meaningful words in class name must also begin with capital letter. The xml name generator will split the word Fragment from your class name and make the other words into xml legal name form separated by under score and will add _prefs in the end. So it becomes power_menu_prefs.xml.

Click "finish" and you have a new fragment class and a new xml file for it inside /xml folder. The fragment will look like this:

You don't need to edit it. It's done in template. It instantiates the class called HandlePreferenceFragment and refers to it's main methods. For more infor you can read my annotations in the HPF class.

Your new xml file is now empty and contains an empty preference screen like so:

We will populate it with preferences later.

Now we need to make this new fragment REACHABLE for user. So we need to add an item to the navigation drawer sections. Let's do that:

1. Open /values/strings.xml and find an array of strings. we will add our new item name in a place we want. In this case I will add it after the Framework section (in blue):

<string-array name="nav_drawer_items">
<item>SystemUI Mods</item>
<item>Phone Mods</item>
<item>Framework and General</item>
[COLOR="Blue"][B]<item>Power Menu</item>[/B][/COLOR]
<item>Useful Apps</item>
<item>Set Theme</item>
</string-array>

2. Now you will need a new icon to appear to the left of the section name in nav drawer. You can add your own icon at this point. It's a good practice to add images for all resolutions. But who are we kidding? You're making a rom for one device. So to remind you, s4, note3, s5 are xxhdpi and note4, s6 are xxxhdpi. I will use existing icon called ic_reboot.png for this section.

3. Now we need to get our hands dirty and go into java alittle. Open MainViewActivity and find the following method. This method is well annotated for your use. So you can refer to it every time you add an item for reference of how-to. Observe the new blue item:

//Creates a list of NavItem objects to retrieve elements for the Navigation Drawer list of choices
public List<NavItem> getMenu() {
List<com.wubydax.romcontrol.NavItem> items = new ArrayList<>();
/*String array of item names is located in strings.xml under name nav_drawer_items
* If you wish to add more items you need to:
* 1. Add item to nav_drawer_items array
* 2. Add a valid material design icon/image to dir drawable
* 3. Add that image ID to the integer array below (int[] mIcons
* 4. The POSITION of your new item in the string array MUST CORRESPOND to the position of your image in the integer array mIcons
* 5. Create new PreferenceFragment or your own fragment or a method that you would like to invoke when a user clicks on your new item
* 6. Continue down this file to a method onNavigationDrawerItemSelected(int position) - next method
* 7. Add an action based on position. Remember that positions in array are beginning at 0. So if your item is number 6 in array, it will have a position of 5... etc
* 8. You need to add same items to the int array in NavigationDrawerFragment, which has the same method*/
String[] mTitles = getResources().getStringArray(R.array.nav_drawer_items);
int[] mIcons =
{R.drawable.ic_ui_mods,
R.drawable.ic_phone_mods,
R.drawable.ic_general_framework,
[B][COLOR="Blue"]R.drawable.ic_reboot,[/COLOR][/B]
R.drawable.ic_apps,
R.drawable.ic_settings};
for (int i = 0; i < mTitles.length && i < mIcons.length; i++) {
com.wubydax.romcontrol.NavItem current = new com.wubydax.romcontrol.NavItem();
current.setText(mTitles[i]);
current.setDrawable(mIcons[i]);
items.add(current);
}

return items;
}

As you can see I added a line R.drawable.ic_reboot. What is it? This is an equivalent to public id in smali. It is in fact an integer. So it appears inside integer array called mIcons. Our respurces in android are referenced by capital R. then we have the resource type, in this case - drawable, and then the item name (without extension). Note the order of the id in the array, I added my string after the framework string. So I also add the id for the drawable after the id of the framework drawable. This is vital to understand, as the list is being populated on runtime based on items positions. Items in an array are separated by comma.

4. Now open NavigationDrawerFragment class and you will find the same method there. Please add the same id in the same way there. You MUST do so in both classes every time.

5. Now we go back to the MainViewActivity and we find the following method. it will be right after the getMenu() method we just edited. The method is called onNavigationDrawerItemSelected(int position). This method is responsible for performing action based on which navigation drawer item is clicked by a user. Positions are the positions of items in the List of our objects. So we have so far 6 items out arrays (strings and drawable id integers). That means their positions are 0,1,2,3,4,5 respectively. Look at the method as it appears in the original code:

@Override
public void onNavigationDrawerItemSelected(int position) {
/* update the main content by replacing fragments
* See more detailed instructions on the thread or in annotations to the previous method*/

setTitle(getMenu().get(position).getText());
switch (position) {
case 0:
getFragmentManager().beginTransaction().addToBackStack(null).replace(R.id.container, new UIPrefsFragment()).commitAllowingStateLoss();
break;
case 1:
getFragmentManager().beginTransaction().addToBackStack(null).replace(R.id.container, new PhonePrefsFragment()).commitAllowingStateLoss();
break;
case 2:
getFragmentManager().beginTransaction().addToBackStack(null).replace(R.id.container, new FrameworksGeneralFragment()).commitAllowingStateLoss();
break;
case 3:
getFragmentManager().beginTransaction().addToBackStack(null).replace(R.id.container, new AppLinksFragment()).commitAllowingStateLoss();
break;
case 4:
showThemeChooserDialog();
break;

}

}

Here we have switch case based on position of an item. This is the same as saying: if the position of an item is 0, perform this action, else, if the position is 1, perform that action and so on. Only in this case we say: compiler, switch cases based on integer - in case 0: do something, in case 1: do something else. So we need to add an item after the framework section. Framework section has position of 2 (it's item number 3). So now we add our new fragment like so:

@Override
public void onNavigationDrawerItemSelected(int position) {
/* update the main content by replacing fragments
* See more detailed instructions on the thread or in annotations to the previous method*/

setTitle(getMenu().get(position).getText());
switch (position) {
case 0:
getFragmentManager().beginTransaction().addToBackStack(null).replace(R.id.container, new UIPrefsFragment()).commitAllowingStateLoss();
break;
case 1:
getFragmentManager().beginTransaction().addToBackStack(null).replace(R.id.container, new PhonePrefsFragment()).commitAllowingStateLoss();
break;
case 2:
getFragmentManager().beginTransaction().addToBackStack(null).replace(R.id.container, new FrameworksGeneralFragment()).commitAllowingStateLoss();
break;
[COLOR="blue"][B]case 3:
getFragmentManager().beginTransaction().addToBackStack(null).replace(R.id.container, new PowerMenuFragment()).commitAllowingStateLoss();
break;[/B][/COLOR]
case [COLOR="blue"][B]4[/B][/COLOR]:
getFragmentManager().beginTransaction().addToBackStack(null).replace(R.id.container, new AppLinksFragment()).commitAllowingStateLoss();
break;
case [COLOR="blue"][B]5[/B][/COLOR]:
showThemeChooserDialog();
break;

}

}

Note how the new case is now number 3 and the positions of the following cases need to be increased.

Now we can run our app and and there is our new section item:

That's it for this post. Post #3 we will talk about different preference kinds we have and how to use them.

Till then...

To be continued.....​