navFormCreate (Function)

Top  Previous  Next

Architecture:

NX32 / NX32L

Device support:

MX2 turbo/encore/warp, AX9 turbo, NX-200, NX-400, NX-900

Firmware version:

4.70 / 1.30.00

Nav. API level:

12


This function will begin the construction of a custom form.

Each form can contain a maximum of 30 fields, added using the navFormAdd* functions, e.g. navFormAddText to add a text field.

When the form has been constructed, call navFormUpload to send it to the navigation device.

If the form is not to be used anyway, call navFormAbort to close the form.

 

The custom forms are stored on the navigation device and can be used by the user to fill out forms to report relevant information.

This can e.g. be used for tracking trips or for reporting errors.

The forms can be filled out and submitted also when the navigation device is not connected to the RTCU device, in which case the forms are queued and will be transmitted when connected again.

 

When the RTCU device receives the submitted forms, the "Form received" event is raised and the contents of the form can be read by using navFormReceive and the functions for reading the individual fields, e.g. navFormReceiveReadText.

 

Input:

id : DINT

Unique ID to identify the form.

Note: the ID of -1 is reserved and will result in an error.

 

title : STRING

The title of the form. Max. 40 characters.

 

position : INT (1..32767, default 1)

Used for sorting the forms.

 

version : DINT (1..2147483647, default 1)

The version number of the form. When the contents of the form are changed, this should be incremented.

 

 

Returns: INT

0

- Success.

-7

- Invalid ID

-8

- Invalid parameter.

-11

- Custom forms are not supported.

-12

- Navigation interface is busy.

 

Declaration:

FUNCTION navFormCreate : INT;
VAR_INPUT
  id       : DINT;
  title   : STRING;
  position : INT := 1;
  version : DINT := 1;
END_VAR;

 

Example:

//-----------------------------------------------------------------------------
// form.vpl, created 2018-11-28 14:45
//
//-----------------------------------------------------------------------------
INCLUDE rtcu.inc
 
//  Input variables that can be configured via the configuration dialog (These are global)
VAR_INPUT
 
END_VAR;
 
//  Output variables that can be configured via the configuration dialog (These are global)
VAR_OUTPUT
 
END_VAR;
 
//  These are the global variables of the program
VAR
  msgSts         : navMessageStatusReceive;
  msgAck         : navMessageReplyReceive;  
  msgRec         : navMessageReceiveX;
  etaRec         : navETAReceive;
  userStatus     : navUserStatusReceive;
  stopRcv        : navStopReceive;
  userID         : navUserIDReceiveX;
  gpiRcv         : navGPIProgressReceive;
  formReceive    : navFormReceive;
  speedAlert     : navSpeedLimitAlert;
  clock          : clockLinsecToTime;
END_VAR;
 
// Definition of the field IDs
#DEFINE ID_NAME     1
#DEFINE ID_AGE       2
#DEFINE ID_OPTIONS   3
#DEFINE ID_DATE     4
#DEFINE ID_TIME     5
#DEFINE ID_STOP     6
 
// Option IDs
#DEFINE ID_OPT_1     1
#DEFINE ID_OPT_2     2
 
FUNCTION TimeString : STRING;
VAR_INPUT
  linsec : DINT;
END_VAR;
  clock(linsec := linsec);
  TimeString := strFormat(format := "\1.\2.\3, ", v1 := clock.day, v2 := clock.month, v3 := clock.year);
  TimeString := TimeString + strFormat(format := "\1:\2:\3", v1 := clock.hour, v2 := clock.minute, v3 := clock.second);
END_FUNCTION;
 
 
FUNCTION ReadGPIProgress;
  gpiRcv();
  IF gpiRcv.ready THEN
    DebugMsg(message := "*** progress received ***");
    DebugFmt(message := "-status=  \1", v1 := gpiRcv.status);
    DebugFmt(message := "-progress=\1", v1 := gpiRcv.progress);
    DebugFmt(message := "-type=    \1", v1 := gpiRcv.type);
    DebugFmt(message := "-error=   \1", v1 := gpiRcv.error);
  END_IF;
END_FUNCTION;
 
FUNCTION createForm:INT;
VAR
  rc: INT;
END_VAR;
  // Begin constructing the form.
  rc := navFormCreate(id := 7, title:="Form", version := 1);
  DebugFmt(message := "Form create=\1", v1 := rc);
 
  // Add fields to the form:
  rc := navFormAddText(id := ID_NAME, title:="Name", desc:="Your name",
                      placeholder := "<Name>", required := TRUE);
  DebugFmt(message := "Add text=\1", v1 := rc);
 
  rc := navFormAddNumber(id:=ID_AGE, title:="Age", desc:="Your age", placeholder:="<years>",
                      min_val:=0, max_val := 120, max_length := 3);
  DebugFmt(message := "Add number=\1", v1 := rc);
 
  rc := navFormAddSelect(id := ID_OPTIONS, title:="Options", desc:="Select the options", multi:=TRUE);
  DebugFmt(message := "Add select=\1", v1 := rc);
 
  rc := navFormAddOption(id:=ID_OPT_1, select_id:=ID_OPTIONS, title:="Option 1");
  DebugFmt(message := "Add option=\1", v1 := rc);
 
  rc := navFormAddOption(id:=ID_OPT_2, select_id:=ID_OPTIONS, title:="Option 2");
  DebugFmt(message := "Add option=\1", v1 := rc);
 
  rc := navFormAddDate(id:=ID_DATE, title:="Date");
  DebugFmt(message := "Add date=\1", v1 := rc);
 
  rc := navFormAddTime(id:=ID_TIME, title:="Time");
  DebugFmt(message := "Add time=\1", v1 := rc);
 
  rc := navFormAddStop(id:=ID_STOP, title:="Stop", desc:="Select the stop");
  DebugFmt(message := "Add stop=\1", v1 := rc);
 
 
  // Upload the form to the navitagion device
  rc := navFormupload();
  DebugFmt(message := "Upload=\1", v1 := rc);
             
END_FUNCTION;
 
 
FUNCTION FormSubmit;
VAR
  rc    : INT;
  i     : INT;
  str   : STRING;
  n     : DINT;
  linsec: DINT := 0;
  stop  : INT;
END_VAR;
  formReceive();
  IF(formReceive.ready) THEN
      DebugMsg(message := "*** form received ***");
      DebugFmt(message := "-ID=      \4", v4 := formReceive.id);
      DebugFmt(message := "-sub id=  \4", v4 := formReceive.submit_id);
      DebugFmt(message := "-version= \4", v4 := formReceive.version);
      DebugFmt(message := "-time=    "+TimeString( linsec := formReceive.time));
       
    IF(formReceive.id <> 7) THEN
          DebugFmt(message:="Unknown form ID \4", v4:=formReceive.id);
          rc := navFormReceiveDone();
          DebugFmt(message:="navFormReceiveDone: \1", v1:=rc);
          RETURN;
    END_IF;
       
    IF(formReceive.version <> 1) THEN
          DebugFmt(message:="Unknown form version \4", v4:=formReceive.version);
          rc := navFormReceiveDone();
          DebugFmt(message:="navFormReceiveDone: \1", v1:=rc);
          RETURN;
    END_IF;
     
    rc := navFormReceiveReadText(id := ID_NAME, text := str);      
    DebugFmt(message:="Read text: \1", v1:=rc);
    IF rc = 0 THEN
        DebugFmt(message:=" Name: "+str);
    END_IF;
     
    rc := navFormReceiveReadNumber(id := ID_AGE, number := n);
    DebugFmt(message:="Read number: \1", v1:=rc);
    IF rc = 0 THEN
        DebugFmt(message:=" Age: \4", v4 := n);
    END_IF;
     
     
    FOR i := 1 TO 30 DO
        rc := navFormReceiveReadSelect(id := ID_OPTIONS, index:=i, option:=n);
        DebugFmt(message:="Read option \1: \2", v1:=i, v2:=rc);
        IF rc < 0 THEN
          EXIT;
        END_IF;
        IF n = ID_OPT_1 THEN
          DebugMsg(message:=" Option 1 selected");
        END_IF;
        IF n = ID_OPT_2 THEN
          DebugMsg(message:=" Option 2 selected");
        END_IF;
    END_FOR;
     
    rc := navFormReceiveReadDateTime(id := ID_DATE, linsec := n);
    DebugFmt(message:="Read date: \1", v1:=rc);
    IF rc = 0 THEN
        DebugFmt(message:=" Date: \4", v4 := n);
        linsec := linsec + n;
    END_IF;
     
    rc := navFormReceiveReadDateTime(id := ID_TIME, linsec := n);
    DebugFmt(message:="Read time: \1", v1:=rc);
    IF rc = 0 THEN
        DebugFmt(message:=" Time: \4", v4 := n);
        linsec := linsec + n;
    END_IF;
     
    IF linsec <> 0 THEN
        DebugMsg(message:="Date/Time: "+TimeString(linsec:=linsec));
    END_IF;
     
     
    rc := navFormReceiveReadStop(id := ID_STOP, stop := stop);
    DebugFmt(message:="Read stop: \1", v1:=rc);
    IF rc = 0 THEN
        DebugFmt(message:=" Stop: \1", v1 := stop);
    END_IF;
     
    // Done with the form      
    rc := navFormReceiveDone();
    DebugFmt(message:="navFormReceiveDone: \1", v1:=rc);
  END_IF;
 
 
END_FUNCTION;
 
 
THREAD_BLOCK navMonitor;
VAR
  event : INT := 0;
  rc    : INT;
END_VAR;
 
  WHILE event <> -1 DO
    event := navWaitEvent(timeout := -1);
    DebugFmt(message := "navWaitEvent - event=\1", v1 := event);
    CASE event OF
    1:
        msgAck();  
        IF msgAck.ready THEN  
          DebugMsg(message := "*** message reply received ***");  
          DebugFmt(message := "-msgid=\1", v1 := msgAck.ID);  
          DebugMsg(message := "-time= "+TimeString(linsec:=msgAck.time));
          CASE msgAck.reply OF  
              1: DebugMsg(message := "-reply=[OK]");  
              2: DebugMsg(message := "-reply=[YES]");  
              3: DebugMsg(message := "-reply=[NO]");  
          ELSE  
              DebugFmt(message := "-reply=\1", v1 := msgAck.reply);  
          END_CASE;  
        END_IF;  
    2:
        msgRec();
        IF msgRec.ready THEN  
          DebugMsg(message := "*** message received ***");  
          DebugMsg(message := "-time="+TimeString(linsec:=msgRec.time));
          DebugFmt(message := "-last=\1", v1 := msgRec.id);
          DebugMsg(message := "-text=" + msgRec.message);  
        END_IF;  
 
    3:
        msgSts();  
        IF msgSts.ready THEN  
          DebugMsg(message := "*** message status received ***");  
          DebugFmt(message := "-msgid=\1", v1 := msgSts.ID);  
          CASE msgSts.status OF  
              1: DebugMsg(message := "-status=Unread");  
              2: DebugMsg(message := "-status=Read");  
              3: DebugMsg(message := "-status=Deleted/Not found");  
          ELSE  
              DebugFmt(message := "-status=\1", v1 := msgSts.status);  
          END_CASE;  
        END_IF;  
    4:
        etaRec();  
        IF etaRec.ready THEN
          DebugMsg(message := "*** ETA received ***");
          DebugFmt(message := "-time=     \4", v4 := etaRec.time);
          DebugFmt(message := "-distance= \4", v4 := etaRec.distance);
          DebugFmt(message := "-stop=     \1", v1 := etaRec.id);
          DebugFmt(message := "-latitude= \4", v4 := etaRec.latitude);
          DebugFmt(message := "-longitude=\4", v4 := etaRec.longitude);
        END_IF;
 
    5:
        stopRcv();  
        IF stopRcv.ready THEN  
          DebugMsg(message := "*** stop status received ***");  
          DebugFmt(message := "-stop=\1", v1 := stopRcv.ID);  
          DebugFmt(message := "-index=\1", v1 := stopRcv.index);  
          CASE stopRcv.status OF  
              1: DebugMsg(message := "-state=Active");  
              2: DebugMsg(message := "-state=Done");  
              3: DebugMsg(message := "-state=Unread - inactive");  
              4: DebugMsg(message := "-state=Read - inactive");  
              5: DebugMsg(message := "-state=Deleted/Not found");  
          ELSE  
              DebugFmt(message := "-state=\1", v1 := stopRcv.status);  
          END_CASE;  
        END_IF;  
    6:
        userID();
        IF userID.status > 0 THEN
          DebugMsg(message := "*** user ID received ***");
          DebugFmt(message := "-time=\4: "+TimeString( linsec :=userID.time), v4 := userID.time);
          DebugFmt(message := "-idx= \1", v1 := userID.index);
          DebugMsg(message := "-user=" + userID.user);
          DebugMsg(message := "-pass=" + userID.password);
        END_IF;
        IF userID.status = 2 THEN
          navUserIDAuthenticate(accept := TRUE);
        END_IF;
    7:
        userStatus();
        IF userStatus.ready THEN
          DebugMsg(message := "*** user status received ***");
          DebugFmt(message := "-time=\4: "+TimeString( linsec := userStatus.time), v4 := userStatus.time);
          DebugFmt(message := "-status=\1", v1 := userStatus.status);
        END_IF;
 
    8: DebugMsg(message := "GPI ID: " + navGPIReceiveID());
    9: ReadGPIProgress();
         
    14:
        FormSubmit();
       
    15:
        speedAlert();
        IF speedAlert.ready THEN
          DebugMsg(message := "*** Speed limit alert received ***");
          DebugFmt(message := "-time=       \4: "+TimeString( linsec := speedAlert.time), v4 := speedAlert.time);
          DebugFmt(message := "-type=       \1", v1 := speedAlert.type);
          DebugFmt(message := "-lat=        \4", v4 := speedAlert.latitude);
          DebugFmt(message := "-lon=        \4", v4 := speedAlert.longitude);
          DebugFmt(message := "-speed=      \1", v1 := speedAlert.speed);
          DebugFmt(message := "-speed limit=\1", v1 := speedAlert.speed_limit);
          DebugFmt(message := "-max speed=  \1", v1 := speedAlert.max_speed);
           
        END_IF;
       
    129: DebugMsg(message := "Request for refresh of quick messages");
    130: DebugMsg(message := "Request for refresh of message replies");
    131: DebugMsg(message := "Request for refresh of user status");
    132:  
          DebugMsg(message := "Navigation device present");
          DebugFmt(message:="version = \1", v1:=navVersion ());
          DebugFmt(message:="API     = \1", v1:=navGetAPILevel ());
          // Delete all forms from the navigation device
          navDeleteData(type := 10);
          // Create custom form
          createForm();
                   
    133: DebugMsg(message := "Navigation device not present");
 
    ELSE
        DebugFmt(message := "navWaitEvent - event=\1", v1 := event);
    END_CASE;
  END_WHILE;
END_THREAD_BLOCK;
 
PROGRAM form;
// These are the local variables of the program block
VAR
 
  rc     : INT;
  navMon : navMonitor;
 
END_VAR;
  // The next code will only be executed once after the program starts
 
  rc:= navOpen(port:=1);
  DebugFmt(message:="navOpen = \1", v1:=rc);
 
  // Start monitor thread
  navMon();
 
BEGIN
// Code from this point until END will be executed repeatedly
 
 
END;
 
END_PROGRAM;