The AppUi class

File: inc\MyAppAppUi.h
File: src\MyAppAppUi.cpp
File: inc\MyApp.hrh
File: inc\MyApp.pan

The AppUi class, controls the User Interface of our application. It has no direct access to the screen or keyboard but only manages entities that have. There are three "strategies" to manage the UI under Series 60:

• With dialog boxes. The UI consists of a main window which opens some dialog boxes. That is how programs on the PC works. However on devices with such small screens as the Series 60 devices this is not recommended (even if technically possible)
• With controls. We are always showing a control that usually spans on the whole screen. If the user wants to move to another screen we create a new control and remove the old. Quite often we will also want to change the content of the Options menu and/or the softkeys. This have to be done manually. The AppUi that uses this inherits from CAknAppUi
• With view. It's like with control-based AppUi but here we have view objects that contains information about how to create the main control, options menu, softkeys etc. This makes it much more convenient than manually changing the controls. It is even possible to start a view of a foreign application and e.g. open the contacts application on a given contact. The AppUi that uses this inherits from CAppViewAppUi. There is one problem that this is a Series 60-only method so using it might make porting to UIQ harder.

In the application generated by the New Project Wizard the second method was chosen. It is implemented in inc\MyAppAppUi.h and src\MyAppAppUi.cpp.

As we see unlike the previous classes the constructors are not empty. In the second-phase constructor (ConstructL) begins with calling BaseConstructL. This function loads the Options menu and softkeys from the resources file. We will discuss the resources file laters.

Then we construct a control that will (at last) give us access to the screen. We construct it with the NewL static method and ask it to fill the whole client area (i.e. without the status pane at the top and the softkey pane at the bottom). Then we have to set the parent of the control. Without it some features will not work, e.g. the scroll bars. Then we push the control on the controls stack. This stack is used to pass keyboard events. The control on the top will receive the event first. If it don't consume this event, the event is passed to the next control down the stack. If it is not consumed it is passed to the next control etc.

The system-provided panes and the client area.

In the destructor we remove the control from the stack and delete it. We check if the control was actually created - if BaseConstructL leaves, it won't.

There is one more method in this class - HandleComandL. This function is called if a command is recieved. Sometimes commands are recieved from the system (e.g. the system want's you app to shut down) but the most often case is that the command is issued because the user have selected a softkey or have chosed a command from the Options menu. The content of the menu is specified in the resources file and was loaded by BaseConstructL. We will discuss the resources file later. We implement the exit command and a command that was added to the options menu. In the later case we displays a message popup. This code is very practical and can be copied&pasted to other programs. The meaning of the _LIT macro is described in the Strings section of the Symbian C++ concepts.

The last thing to note is how to generate a panic. As it was written Panics section of Symbian C++ concepts a panic is a reaction to an error which is a fault of the programmer. An unknown command is such a situation. Generating a panic instead of ignoring the command will simplify the debugging of the program. A panic is generated by User::Panic which takes two parameters. The first is the name of captegory of the panic. We use the application name. The other is and integer that should describe the reason of the panic. The define all our codes in a special include file with a .pan extension. In this file we have also an inline function that will simplify raising panics from our category.