M I D l e t P a s c a l
User interfaces

If you want to create a simple program that asks the user to enter his/hers name, and then displays that name on the display, you need something more powerful than GetKeyClicked or GetKeyPressed functions. The more powerful mechanism is called forms and you can create complex user interfaces using forms. Forms are very similar to dialog boxes in windows.


A simple form application

We'll just start by creating a simple program that uses a form to retrieve the user's name, and then writes 'Hello, <entered name>' on the screen. Here is the code for that program:


program HelloForm;

var itemId : integer;
     cmdNext : command;
     cmdQuit : command;
     name : string;

begin
  // switch to form mode from default canvas mode
  ShowForm;
   
  // add a text field to the form
  itemId := FormAddTextField('Enter your name', '', 20, TF_ANY);
   
  // create a command (button) 
  cmdNext := CreateCommand('Go!', CM_OK, 1);
  AddCommand(cmdNext);
   
  // wait until the user clickes on Go! command
  repeat until GetClickedCommand = cmdNext;
   
  // retrieve the entered name
  name := FormGetText(itemId);
   
  // switch back to canvas mode and draw the text
  ShowCanvas;
   
  DrawText('Hello, ' + name + '!', 0, 0);
  Repaint;
   
  // create a quit command
  cmdQuit := CreateCommand('Quit', CM_EXIT, 1);
  AddCommand(cmdQuit);
  repeat until GetClickedCommand = cmdQuit;   
end.



The program produces the following form:

form1-1
form1-2


There are few things to be noticed. First is, you must call ShowForm to switch to form mode before inserting elements to form. FormAddTextField creates a text field and returns its identifier. The same identifier is used later to retrieve the text from the text field.

Commands are interesting because they can be used both in form mode and in canvas mode. Exception to this are canvases while using full screen mode (more on fullscreen mode in chapter 6).

The forms can contain a title. To set the form title, use SetFormTitle procedure.



More form elements

In previous example we saw how to create a simple form. Now we will illustrate how to create a more complex form:


program HelloForm;

var 
  stringID, textID, passID, 
  imgID, gaugeID, choiceID, 
  maleID, femaleID: integer;

  cmdQuit, cmdResetName, clicked : command;

begin
  ShowForm;
   
  SetTicker('This is a ticker control');

    // add some elements   
    stringID := FormAddString('Just some title');
    textID := FormAddTextField('Enter name', 'Mr. Smith', 20, TF_ANY);
    passID := FormAddTextField('Enter password', '', 20, TF_PASSWORD);
    imgID := FormAddImage(LoadImage('/icon.png'));
    gaugeID := FormAddGauge('Choose your age', true, 100, 18);
    choiceID := FormAddChoice('Select your gender', CH_EXCLUSIVE );
  
    // set up the choice control
    maleID := ChoiceAppendString(choiceId, 'Male');
    femaleID := ChoiceAppendString(choiceId, 'Female');
   
    // create commands
    cmdQuit := CreateCommand('Quit', CM_EXIT, 1);
    AddCommand(cmdQuit);
    cmdResetName := CreateCommand('Reset', CM_SCREEN, 1);
    AddCommand(cmdResetName);
   
    repeat 
      clicked := GetClickedCommand;
      if clicked = cmdResetName then FormSetText(textID, '');
    until clicked = cmdQuit;
   
end.



form2-1
form2-2


To retrieve the data from the text field, use FormGetText function; to retrieve the value from the gauge control, use FormGetValue function. ChoiceIsSelected and ChoiceGetSelectedIndex functions are useful to find selected elements inside a choice list.

For more detailed information about forms, see Forms section in Procedure and function reference part of this manual.



Menus

Beside canvas and form mode, MIDletPascal supports few more modes. One of these modes is menu mode. The following code illustrates use of menu mode:


program Menu;

var tetris, minesweeper, snake : integer;
    play, clicked : command;   

begin
  ShowMenu('Select a game', CH_IMPLICIT);
    
  tetris := MenuAppendString('Tetris');
  minesweeper := MenuAppendString('Minesweeper');
  snake := MenuAppendStringImage('Snake', LoadImage('/icon.png'));

  play := CreateCommand('Play', CM_SCREEN, 1);
  AddCommand(play);

  repeat Delay(100); until GetClickedCommand = play;
    
  {
    do something like this:
    if menuGetSelectedIndex = tetris then playTetris;
    if menuGetSelectedIndex = minesweeper then playMinesweeper;
    if menuGetSelectedIndex = snake then playSnake;
    ...
  }
end.



form3-1


Alerts

Another mode is alert mode. Alerts are simple message boxes, as illustrated in the following example program:

program Alert;

begin
  ShowAlert('New message', 
            'You have just received a message from MrSmith',
            LoadImage('/icon.png'),
            ALERT_INFO
           );
  PlayAlertSound;

  Delay(2500);
end.



alert


Fullscreen text box

The final display mode is full screen text box. Unlike text field that is single-line, text box can contain multiple lines of text. Text box is useful when the user needs to enter large quantities of text, such as message text. The following example shows how to use full screen text box from within your application:


var cont  : command;
    quote : string;

begin
  ShowTextBox('Enter message', '', 200, TF_ANY);
  cont := CreateCommand('Send', CM_SCREEN, 1);
  AddCommand(cont);

  repeat
    delay(100);
  until GetClickedCommand <> EmptyCommand;

  quote := GetTextBoxString;

end.



textbox

In this chapter full of examples you learned how to use form, alert, menu and textbox display modes to create rich user interfaces. For more detailed information on specific controls, refer to Procedure and function reference part of this manual. The next chapter will teach you how to store persistent data on the mobile device.