Welcome!

Welcome to the official BlackBerry Support Community Forums.

This is your resource to discuss support topics with your peers, and learn from each other.

inside custom component

Java Development

Reply
Highlighted
Developer
Posts: 2,268
Registered: ‎07-08-2009
My Device: various
My Carrier: various

MainScreen explained

This post is about the philosophy of the MainScreen - probably the most used Screen subclass by the BlackBerry developers. If you feel this post merits knowledge base inclusion (or that it is too basic and is not worth mentioning), please sound off in your replies.

I decided not to talk about the toolbar, available in OS 6.0 (see setToolbar(ToolbarManager toolbar) and getToolbar() methods).  On one hand, I'm not familiar enough with it. On the other hand, most developers now still need to support earlier versions of the phones.

 

Main Screen explained

Most BlackBerry applications begin by pushing a MainScreen or an extension of one onto the screen stack. However, you might not realize that in MainScreen you have a very fine instrument which can easily bite you in the back if you are not careful.


So, what can a MainScreen do for you? It pre-populates the menu with the system items - "Switch application" and "Close". It reacts to "Escape" key by closing (popping) itself, and, if it is the last screen on the stack, exiting the application. But that is far from all it can do.


Banner / Title / Status areas

One of the very useful possibilities provided by MainScreen is the ability to add two non-scrolling ("docked") areas to the otherwise scrolling screen.


Banner & Title

Banner and Title both reside at the top of the screen.

 

Banner

You create a banner using MainScreen.setBanner(Field banner) method. Since a Manager is also a Field, you can create quite a sophisticated banner this way.

The main idea behind the banner is to provide a universal top area which contains some constant items you always want to show - your company's logo and name, your application name, quick links to the most frequently used parts of your application, etc.


Title

Title also sits on top of the screen, just below the banner (if present).

You create a title using either MainScreen.setTitle(String title) or MainScreen.setTitle(Field title). Logically, title is used for the name of the current application "screen" - "Reports", "Your order", "Our School Soccer Team - Season 2010-2011", etc.


Interestingly enough, title has a different theme: by default, fields in title have black background and white foreground. Even if you override the colors in the Field you set as title, the title Manager (invisible by your code but present) has a bottom padding of 2, making sure that you always get at least a thin black line on top of the main area.


Status

Status is located at the bottom of the screen and is also always visible regardless of the main area scrolling position.

You create a status using MainScreen.setStatus(Field status). As usual, Manager is a Field, so you can have some sophisticated logic there. Some applications use status for messages ("Loading http://...", "Loading images - 13 of 15 completed", etc.), others - for buttons ("Submit order", "Cancel") and so on.

 

Main Area

The main area is managed by a VerticalFieldManager which gets most style bits from the MainScreen. This Manager is accessible via getMainManager(), and it is the one who becomes a parent of fields "added" to the MainScreen via its Screen.add(Field field) method. By default, the main manager is created with VERTICAL_SCROLL and VERTICAL_SCROLLBAR style bits.

 

All of the above can be illustrated by the following screenshots (notice the "scrollbar" triangles)

 

MainScreen with focus on the banner:

MainScreen_topfocus.png

 

MainScreen with focus in the main area, partially scrolled:

MainScreen_midfocus.png

 

MainScreen with focus in the status area:

MainScreen_statusfocus.png

 

MainScreen - using style bits for customization

You might have noticed that I've emphasized the fact that by default the main area of a MainScreen is scrollable and displays a scrollbar.  Why is it important?


Some applications want a very fine control over the screen. Developers achieve this by creating their own custom managers which usually have USE_ALL_HEIGHT and USE_ALL_WIDTH style bits (or the equivalent setExtent() in their custom sublayout() methods). Added to a FullScreen, such a custom manager will get the full screen dimensions. This is one of the ways to determine display size without using the signature-requiring Display.getWidth() and Display.getHeight() methods. It also lets the developers to decide whether their manager should be scrolling and manage that scroll internally - say, display a nice-looking scrollbar (see this knowledge base article for example). Developers of such applications usually add their custom Manager to the MainScreen and the rest of the fields to display to that Manager.

 

However, added to a default MainScreen, such a manager will get the height of ... 0x3FFFFFFF (Integer.MAX_VALUE >> 1)! It happens because a VerticalFieldManager created with VERTICAL_SCROLL style bit lets its children have a virtually unlimited height. In order to prevent this we need to create our MainScreen differently.

 

For those applications which use MainScreen directly, replace your

new MainScreen()

pieces of code with

new MainScreen(MainScreen.NO_VERTICAL_SCROLL).

Those classes which extend MainScreen will need to add

super(NO_VERTICAL_SCROLL)

as the first line of their constructors.

 

This NO_VERTICAL_SCROLL exercise hopefully raised your awareness of MainScreen(long style) constructor availability. Now that you know it's there you may play with different style bits, see which ones make sense and use them to enhance and beautify your application.

 

Good luck!

----------------------------------------------------------
please click 'Accept Solution' on posts that provide the solution to the question you've posted. Don't say "Thanks", press 'Like' button instead!
Developer
Posts: 16,992
Registered: ‎07-29-2008
My Device: Z10 LE, Z30, Passport
My Carrier: O2 Germany

Re: MainScreen explained

i would suggest that you just submit it to the knowledge base, looks like a well written article to me.

 

there are a few things i would add though.

 

mainscreens have a bug with setBackground for a long time. you can work around this by adding a vfm with use_all_height and using paintBackground (or setBackground on 4.6+) on it.

 

if you don't want to have the separator and spacing on the title area you can build your own title using another vfm

 

you could mention onsaveprompt to remvoe the save dialog (another feature of mainscreen btw)

 

just out of my head.

----------------------------------------------------------
feel free to press the like button on the right side to thank the user that helped you.
please mark posts as solved if you found a solution.
@SimonHain on twitter
Developer
Posts: 2,268
Registered: ‎07-08-2009
My Device: various
My Carrier: various

Re: MainScreen explained

Thanks for the suggestions, I'll incorporate those into the article.

 

I've started the draft already Smiley Happy

----------------------------------------------------------
please click 'Accept Solution' on posts that provide the solution to the question you've posted. Don't say "Thanks", press 'Like' button instead!