[MANUAL] - creating custom screen

[Menion]

SAMPLE PACK FROM LOCUS VERSION 1.8.2 - download here

So, simple and short description.

Recommended way ho to create this. This is very short explanation, sorry for that. Better will come later. Also this is mainly for people familiar with Android developing. If you're not, better is to use already created skins and look at them. To edit, use just simple NotePad! Much easier!!

1. download and install whole eclipse and Android SDK tools from here http://developer.android.com/sdk/index.html
2. after all works, create new android project. This will create base data structure. You'll not need anything program
3. project contains res/layout/main.xml file, that's our target. Learn with Eclipse GUI builder and edit this file
4. put resources (best to use 9-patch images) into res folders (supported, drawable, drawable-hdpi, drawable-mdpi, drawable-ldpi)
5. after compilation, take mail.xml file and image resources from compiled source (this is because of 9-patch images. If you want to use basic png files, you can add them directly into result. 9-patch have to be precompiled!).

You do not have to do previous steps. You can edit xml file directly in any editor. Previous steps are just recommended way for easy "Drag and drop" creating and also only way to support 9-patch images

And how to get actually all this works?
Locus/data/customScreen/   (root directory)

create ZIP file that containt this structure

MY ZIP

• /assets/ - for custom fonts
• /drawable/ - (9-patch, or universal)
• /drawable-hdpi/
• /drawable-ldpi/
• /drawable-mdpi/
• /layout/ - for layout specification (for landscape and portrait or ... below ... for separate by orientation)
• /layout-land/
• /layout-port/
• /values/ (supported colors.xml, styles.xml)

Place your main layout file into layout directory (or two files, one to layout-land, second to layout-port) and rename it to main.xml. That is important, because main.xml file is gate to whole layout, it have to be included!

also in root of you ZIP file, you can place these files (optional)

• icon.png - small (48x48px) logo of your skin
• info.html - HTML page that will contain description of you skin (some links, donate button or similar is possible)

Finally, place this zip file, into root directory described above!

Active Views, you can use (warning, only limited functionality on almost all items - still in develop) and Actions you can apply are described in topics below

[Menion]

SUPPORTED VIEWS

Containers

• LinearLayout
  
  • android:orientation
  • android:gravity
• RelativeLayout
  
• ScrollView
• TableLayout
• TableRow

Views

• TextView extends View
  
  • android:text - this contain ACTIONS below
  • android:textSize
  • android:textColor
  • android:gravity - full support on all values, also like "center_vertical|right"
  • android:lines
  • android:ellipsize
  • android:shadowColor - and optional android:shadowDx, android:shadowDy and android:shadowRadius
  • locus:textFormat (parametres should be {i}, {d}, {i.d}, {u} "integer part, double part, both, only units") - so for example - locus:textFormat="{i.d} - {u}". Can be applied to: speed, distance, altitude and accuracy now
  • locus:textFont - link to font stored in MySkin/assets directory
• Button extends TextView
  
  • locus:actionClick - allow to handle specific actions. This is way how to directly control some actions in Locus
  • locus:actionVisibility - allow to this button to show/hide other view by defined ID. So for example, you somewhere in xml define to any view android:id="@+id/myView", and then you can anywhere define this Button object, and give it attribute locus:actionVisibility="@+id/myView", which cause, that by tapping, you'll be hiding and showing View with this ID! (small tip: when you define to button locus:actionVisibility="@+id/locus_top_panel", this button will control whole top panel!!)
• ImageView extends View
  
  • android:src
• ImageButton extends ImageView
  
  • locus:actionClick - as Button
  • locus:actionVisibility - as Button
• MapScreenView (custom locus view) extends View
  
  • no custom parametres
• RotateView (custom locus view) extends View
  
  • locus:action - attach to which rotation action ... for example locus:action="{orient_course}"
  • locus:rotateImage - reference to drawable, actually centered and rotated around center by angle defined by action
  • locus:rotatePivotX - move rotation point by X value (+X to bottom)
  • locus:rotatePivotY - move rotation point by Y value (+Y to bottom)
  • locus:rotateStartAngle - angle at which is rotation start with rotateStartValue value (- value for counter-clockwise orientation)
  • locus:rotateStartValue - value for variable that starts at rotateStartAngle (in base units, so metres, second, ..)
  • locus:rotateEndAngle - angle at which is rotation ending with rotateEndValue value
  • locus:rotateEndValue - value for variable that ends at rotateEndValue
• SlideView (custom locus view) extends View
  
  • locus:action - attach to which slide action ... for example locus:action="{orient_course}"
  • locus:slideImage - reference to drawable used for slide
  • locus:slideStartPosition - position value of first image pixel (compare to SlideView). It means when you define SlideView width to 100dip, this value to 50dip and slideStartValue to 0, then for actual action value 0, image will start at center of view.
  • locus:slideStartValue - action value for slideStartPosition (in base units, so metres, second, ..)
  • locus:slideEndPosition - position value of last image pixel. Also (slideEndPosition - slideStartPosition) define width of image
  • locus:slideEndValue - action value for slideStartPosition
  • locus:slideInfinite - if slide image should be repeated to cover whole parent view (true/false) [false]
  
  On all View can be applied these attributes
  
  • android:id
  • android:layout_width
  • android:layout_height
  • android:layout_weight - if parent view is LinearLayout
  • RelativeLayout.LayoutParams - if parent view is RelativeLayout
  • android:layout_margin
  • android:layout_marginLeft
  • android:layout_marginRight
  • android:layout_marginTop
  • android:layout_marginBottom
  • android:padding
  • android:paddingLeft
  • android:paddingRight
  • android:paddingTop
  • android:paddingBottom
  • android:background (image, color in RGB, ARGB)

[Menion]

SUPPORTED ACTIONS - locus:actionClick

      "{track_record_start}"
      "{track_record_stop}"
      "{track_record_pause}"
      "{map_zoom_in}"
      "{map_zoom_out}"
      "{map_center}"

SUPPORTED ACTIONS - locus:actionVisibility

      "{lat_gps}", // GPS latitude (map center latitude if GPS off)
      "{lon_gps}", // GPS longitude (map center longitude if GPS off)
      "{altitude}", // GPS altitude (0 if GPS off)
      "{accuracy}", // GPS accuracy (0 if GPS off)
      "{gps_sats_used}", // actual used satellites for GPS fix
      "{gps_sats_all}", // all visible satellites
      "{declination}", // actual declination
      "{orient_course}", // course orientation (source depend on selection on GPS screen - GPS or internal compass)
      "{orient_course_opposit}", // course orientation (source depend on selection on GPS screen - GPS or internal compass)
      "{orient_pitch}", // pitch orientation
      "{orient_roll}", // roll orientation
      "{orient_gps_shift}", // orientation computed as bearing from previous to current GPS location
      "{orient_gps_angle}", // angle computed as {orient_gps_shift} - {orient_course}, so it's true moving direction.
      "{time}", // actual time
      "{speed}", // GPS speed (0 if GPS off)
      "{rec_dist}", // track recording - recorded sitance
      "{rec_dist_down}", // track recording - downhill distance
      "{rec_dist_up}", // track recording - uphill distance
      "{rec_alt_min}", // track recording - minimum altitude
      "{rec_alt_max}", // track recording - maximum altitude
      "{rec_alt_down}", // track recording - downhill altitude
      "{rec_alt_up}", // track recording - uphill altitude
      "{rec_alt_cumu}", // track recording - cumulated altitude
      "{rec_time}", // track recording - total record time
      "{rec_time_move}", // track recording - time only when move
      "{rec_speed_avg}", // track recording - speed average
      "{rec_speed_avg_move}", // track recording - speed average only when move
      "{rec_speed_max}", // track recording - speed maximum
      "{rec_points}", // track recording - num of recorded points
      "{rec_pace}", // track recording - num of recorded points
      "{map_center_lat}", // map center latitude
      "{map_center_lon}", // map center longitude
      "{map_rotate}", // map rotate value
      "{guide_wpt_name}", // guide target waypoint name
      "{guide_wpt_lat}", // guide target waypoint latitude
      "{guide_wpt_lon}", // guide target waypoint longitude
      "{guide_wpt_alt}", // guide target waypoint altitude
      "{guide_wpt_dist}", // guide target distance to waypoint
      "{guide_wpt_dist_to_finish}", // guide target distance to last waypoint of track
      "{guide_wpt_azim}", // guide target azimuth to waypoint
      "{guide_wpt_angle}", // guide target angle value (computed as {guide_wpt_azim} - {orient_course})
      "{guide_wpt_time}", // guide target time to waypoint
      "{guide_wpt_time_to_finish}" // guide target time to last waypoint of track

[Rob]

Help pls: with first simple skin, it worked. Now when clicking customer screen button, I always get errormessage:Cannot get main.xml layout file.
I copied the zip files into .. customerscreen without de-zipp. What am I doing wrong ?
Rob

[Menion]

ah sorry, that was a little old config files. I added link to download actual pack from 1.8.2 locus version (check first post). These are skins that are as default in application on market ...

PS: I know in skins is missing some better example of RotateView (like speedview) ... I'll add it later ...

[Rob]

Thx, I got it. Deleted all and copied just actual ones -works !

[jorgesomers]

Very nice manual it worked.
your custom screens have little problem of graphics size and text size it doesnt look like pictures posted here..

BR
Jorge Somers
Sao Paulo - Brazil

[Menion]

Thanks .. they need some more improvements. These are just an examples ...

[Paradroid09]

Hi,

thanks for this very nice Program, thanks for this nice new feature ;-)

I try to make my own today, but cant get it work like I want it to. There were always errors in textsize. The texts are rendered to small.
Then I try to repack your sample "Simple map.zip" and earned the same error. (see attachment)
The file was created with 7-zip.

What do I wrong?
Would you like to test the file on your machine?

Many thanks
Paradroid09

[daubor]

I think, the creation of own screens will be possible in future releases. Those sample's are just for an impression!

I tried it myself to create some custom screens, but nothing worked! Seems to be releated with zipping.
Because unpacking one of the samples and repacking it without any changes will corrupt it!
Locus is unable to find main.xml.

Anyway, when this is implemented, i will go for pro!

[Menion]

this is really weird because I do nothing special with data, just basic zipping! All samples should work fine in last market release!

[daubor]

Moah....i'm an idiot!

When unzipping via contextmenu in windows -> "Extract to folder <archiveName>" all contents of archive will be put in this folder!
After that i modified main.xml!
When finished, i selected this folder and created an archive of it! But the resulting structure is changed:
-> <archiveName>.zip/<archiveName>/layout/main.xml
must Be:  <archiveName>.zip/layout/main.xml

Usererror...

[jorgesomers]

You are zipping with full path...
Try this..
Open to folder simple Map
Select sub-folders assets,layout and the folders info.html and icon.png..
Right-click use option Zip (Im using zipgenius)
It will create a zip with 2 sub-folder and 2 files WITHOUT FULL PATH... !

Thats the problem!
btw YOU ARE NOT AN I... !!!

[jorgesomers]

hi,

I need some EXTRA instructions..
HOW TO ALIGN RIGHT all numbers in red .. ?

Attached I'm donating to the comunity my bike layout called Somers Sml (no so small)

If someone can make both numbers in red align to the right side I'll be very glad !

BR
Jorge Somers
Sao Paulo - Brazil !

[Menion]

Hi Jorge,
  nice attempt!

anyway for all:
- sample FONT used in samples isn't ideal. It was only a sample. I'm sure, you'll find much better ... try to look for example here http://www.1001freefonts.com/
- your skin is probably tested on your phone but on my HDPI resolution it looks bad ... look at screenshot. So Maybe you can descrease a little size of fonts, or I should create some mechanism for settings more then one size of text depend on resolution
- to align text in layout you can use "gravity" attribute on TextView object