Using Multiple Windows (by Brad Manske)

I'd want to address issues dealing with the creation of multiple windows in your PPL programs. This is not a tutorial on creating windows. It is more a collection of tips for when you do create multiple windows. ShowMessage is the most simple way to create a second window. It is useful for debugging and simple informational pop-up windows.

ShowMessage("Hello World" + #13#10 + "and Country");

Take a look at the #13#10 added above. This is a Carriage Return/Line Feed added to produce a second line. By formatting the text, you can make this simple command very useful. The Windows MessageBox is the next step up in complexity. It allows you to set the owner, the text in the message box, the caption and some flags. In the example below, there is no owner, the question about saving, "Save" is placed into the caption bar, finally the "yes", "no" and "cancel" buttons are created inside the dialog box.

i$ = MessageBox(NULL, "Do you want to save " + FileName$ + "?", "Save", MB_YESNOCANCEL);

It is pretty obvious from the names below, which buttons get created when you use these constants.

MB_OK
MB_OKCANCEL
MB_ABORTRETRYIGNORE
MB_YESNOCANCEL
MB_YESNO
MB_RETRYCANCEL

You can also specify an Icon to be placed in the MessageBox from the list below. Simply use the "|" OR operator.

For example MB_YESNOCANCEL | MB_ICONQUESTION

MB_ICONHAND
MB_ICONQUESTION
MB_ICONEXCLAMATION
MB_ICONASTERISK
MB_ICONWARNING = MB_ICONEXCLAMATION
MB_ICONERROR = MB_ICONHAND
MB_ICONINFORMATION = MB_ICONASTERISK
MB_ICONSTOP = MB_ICONHAND

MessageBox has additional features. Refer to MSDN for all of them. MessageBox can return a value based when the button is pressed. These values are defined in Dialog.PPL.

#define IDOK 1
#define IDCANCEL 2
#define IDABORT 3
#define IDRETRY 4
#define IDIGNORE 5
#define IDYES 6
#define IDNO 7

I try to use these values when returning from displaying a dialog box. When using ShowModal to display a dialog any value less than 100 can be use for a button and it will return automatically, I try to avoid confusion and not change the meaning of the defined values. Going back to my MessageBox example from above, "Yes" and "No" are pretty clear answers, but what about "Cancel"? If you are asking to save the file in response to a command to exit the program, the program flow go like this. User selects the Exit menu item. The menu exit handler would send a
WM_CLOSE command. Then you need a handler for the close event. In the Close event handler, call the MessageBox function and if you receive the "Cancel" ID, then return a FALSE from the OnClose event to stop the program from closing. The operation of the OnClose event is a little different in windows than it is in PPL. Windows will only send you an OnClose event when the entire application is closing. PPL allows you to open multiple windows per application and will send you an OnClose event for each window. This makes it easy in PPL to implement the ability to "Cancel" for each window. The next step is having more than one fully functional window for your application. For each new window that you create with the Form Editor, you need to:

• Select the Generate Library option in the Form -> Options menu.
• Change the form name so that a new windows class is created.
• Give each control on the forms a unique name.
• Give each control on the forms a unique ID. (required if getting the handles from the IDs)

For most forms you will probably want to select the "FormDefault" property. This property enables the use of the SIP (Soft Input Panel) on the PPC. You may open several windows for your program at the same time, then manage input by selectively showing the window that is needed. To Hide or Show a window use:

ShowWindow(FormHandle$, SW_HIDE); // or SW_SHOW

In creating more complex windows, you need to be careful about which styles are selected. The example below is how I added styles in the creation code for a window. This was necessary because the WS_EX_CaptionOKBtn style prevented my window from displaying on the PC as it is a PPC only style. So if your window refuses to display at all, you should review the styles that you have used and isolate the trouble-maker.

ExStyles$ = GetWindowLong(SizeDlgHandle$, GWL_EXSTYLE);
#ifdef _WIN32_WCE
  // WS_EX_CAPTIONOKBTN is added here and not on the form because if added to
  // the form then the form will not display on the PC
  SetWindowLong(SizeDlgHandle$, GWL_EXSTYLE, ExStyles$ | WS_EX_CAPTIONOKBTN);
#else
  // WS_EX_TOOLWINDOW is added here for the same reason as above except it will
  // not show on the PPC if present.
  SetWindowLong(SizeDlgHandle$, GWL_EXSTYLE, ExStyles$ | WS_EX_TOOLWINDOW);
#endif

I hope that this collection of tips has helped.

Packages Come In All Sizes (by Eric Pankoke)

There will be very few instances where you will need to distribute an application without some sort of supporting file set. Whether you’re building a database system or a multimedia application, you might have one or more directories filled with extra material that you don’t necessarily want the user to see outside of the application itself. PPL provides a nice mechanism for this through the use of a Package file. A package file is a file that can contain one or more files of any type all bundled up together into one file with a .pkg extension. You can create a package file pro grammatically or you can use the Package Manager supplied with PPL to do so. Run the PPL console (it’s called PPL.EXE, and resides under the RUNTIME directory of your PPL install). From the File menu, select Package Manger. You can use this tool to view, create and manage package files. It’s pretty self explanatory, so I won’t really go into details here. Once you’ve created a package file, you’ll of course want to use it in your program. To open a package
file, you simply call:

handle$ = OpenPackage(AppPath$ + “mydata.pkg”, key$);

The first parameter is a full path and name to the file you wish to open, and the second parameter is the key used to unlock the package file. If a file with the name you’ve specified does not exist, OpenPackage will create it and use the value specified in key$ as the password. When creating a package file in the Package Manager you do not get the opportunity to supply a key, so key$ would be an empty string (“”). If you want a key, you will need to create the package pragmatically. You must be sure to keep track of the return value, as this is the handle that will be passed to all other package functions.

To retrieve the contents of a package file, call:

PackageFiles(&lst$, handle$);

This will provide you with a list containing the names of all of the files contained in the package. Of course, you will probably know all of these names already, so let’s get to the heart of the matter: extracting and using the files. There are currently two ways of retrieving a file. The quickest way is to call the following:

data$ = LoadPackageFile(handle$, “filename”);

This returns the contents of the file as a string in memory, which you can then display or manipulate however you choose. Currently, if the file is some sort of multimedia file or a database, this won’t be of much use to you. Starting in PPL v1.1, however, there are two new functions that will work in conjunction with LoadPackageFile called LoadSpriteFromMem and LoadSoundFromMem. These will be discussed more after 1.1 is released. For cases where you need to interact with the file in some way, you’ll want to call:

tmpfile$ = ExtractFileFromPackage(handle$, “filename”);

This function will retrieve the contents of the requested file and store it in a temporary file. The return value is the name of the temporary file where the data is stored. So let’s say you wanted to retrieve a database, do some work on it, then store the database back to the package. The code would look something like this:

dbfile$ = ExtractFileFromPackage(handle$, “MyData.db”);
dbhandle$ = sql_open(dbfile$);
if(dbhandle$ > 0)
  //Check out the October newsletter for an SQLite primer
end;

dbnew$ = ExtractFilePath(dbfile$) % "aviator.db";
MoveFile(dbfile$, dbnew$);
AddFileToPackage(package$, dbnew$);
DeleteFile(dbnew$);

If you will need to place the file back into the package after you’ve done your work with it, the 3 lines following end; are necessary. ExtractFileFromPackage creates a random name for the file, and AddFileToPackage takes the name of the file you’re adding and uses that as the name inside of the package. So, if you want to replace the file that exists in the package with the version your application has just modified, you need to rename it to match the name that exists in the package. ExtractFilePath returns the path portion of a path / file name string, so if you use that on the file path returned from ExtractFileFromPackage, then use the file name that was used to add the file to the package initially, you can rename the temp file so that it will be stored correctly in the package again. The final step to updating the package is:

AddFileToPackage(handle$, “filename”);

The first parameter is that wonderful handle that was retrieved on your call to OpenPackage. filename is a string containing the full path and name of the file you wish to add. As mentioned before, the actual name of the file (no path) will be used to reference the file within the package. If you call AddFileToPackage with a file that already exists in the package, the file in the package will be replaced with the one you are adding. Finally, when all of your work is done and you don’t need the package any more, simply call:

ClosePackage(handle$);

This will make sure that the contents of the package have been updated and the handle will be released from memory.

Arrays in structures.

We have seen that structures can be defined as arrays using the TDIM() function. But what about having one element of the structure being an array of values? PPL offers a transparent way to do just this using the DIM() function. It will create an array from Lets first start by defining our variable structure:

struct(s$, "a", "b");

Now lets dimension our element, in our case we will use s.a$:

dim(s.a$, 10);
s.a$[0] = 1;
s.a$[1] = 2;
s.b$ = 3;
ShowMessage(s.a$[0] % "," % s.a$[1] % "," % s.b$);

You can even use strings with your array element, don't forget to use the @ operator to convert array elements to string since they only point to a pointer:

s.a$[2] = "Hello World!";
ShowMessage(@s.a$[2]);

As you see, structures are very flexible and quite efficient too. They can support multiple type of data, even arrays of double type values and even strings.

Arrays of structures.

There comes a time when you need to store a series of data in the same format. Storing values in a structure will help clarify your code and your programming task as well. However, you might want to store more of the same data in multiple structures. This is where arrays of structures become very handy.

Lets first define our structure variable format:

struct(s$, "a", "b");

Next we will make this structure an array but keeping the structure information at the same time. Notice we use TDIM() and not the regular DIM() function? The TDIM() function is a special function that can be used with structures only.

tdim(s$, 10);
s.a$[0] = 1;
s.a$[1] = 2;
ShowMessage(s.a$[0] % "," % s.a$[1]);

Arrays of structures are very ressemblant to lists of structures but offers an a great alternative is lists are too complicated for you.

List of structures.

Now that we know about structures, how can we store multiple structures into one single variable? The best solution is either:

1. An array of structures
2. List of structures.

Let's take a look at list of structures and later array of structures. Everytime you add a new item to a linked-list, the variable type is initialized, therefore you need to restructure the item.

For (i$, 1, 10)
  Add(l$);
  struct(l$, "a", "b");
  l.a$ = i$;
  l.b$ = i$ + 10;
end;

ForEach(l$)
  ShowMessage(l.a$ % "," % l.b$);
end;

There is nothing more to add here other than the fact that you can define different types of structures for each list item. Powerful isn't it?

Structures revisited!

Structures offers enormous flexibility when you design a program. They allow to store information in a nice clean way into your variables. I like to explain structures as a single record database. A structure is like a series of fields that can be stored in one record (the variable). Take the following example:

struct (s$, "a", "b");

The variable s$ has two elements, a and b. Each element can contain a separate value. The default type for structure's elements is a TINT (4 bytes) value. You can also specify which value type the element will be holding.You have multiple choices here:

TBYTE 1 byte
TSHORT 2 bytes
TINT 4 bytes
TUINT 4 bytes (unsigned)
TWIDE 4 bytes (unicode character string)
TDOUBLE 8 bytes
TLONG 8 bytes (no decimal)

struct (s$, "a", tbyte, "b", tdouble);

The following structure s$ would be 9 bytes in size. 1 byte for element a and 8 bytes for element b. If you need to specify your own size in bytes you can also easily do it:

struct (s$, "a", tbyte, "b", 50);

Element b contains 50 bytes. Now how do you access the structure variable elements you ask? Noting is easier:

s.a$ = 10;
s.b$ = 20;

What about strings in structures? You will see that PPL is very flexible but can also be a little more complex to use in some cases. You will need to be careful when using strings in structures. PPL either stores a pointer of the string that is assigned to the structure's element in the case where the element size is TINT, TUINT, TWIDE, TDOUBLE or TLONG. If the element size is a user-defined length, then the string is copied directly to the structure's element memory location.

struct (s$, "a", "b", 50);
s.a$ = "Hello World!";
s.b$ = "Hello Again!";

The main difference here is that the string "Hello World!" is not stored in s.a$ but rather stored somewhere in memory and only its pointer address is stored in s.a$. "Hello Again!" is stored directly into s.b$.

ShowMessage(s.a$);

If we try to access s.a$ like the previous code, only its pointer address value will be printed. To access s.a$ as a string we need to use the @ operator to convert a pointer to a string.

ShowMessage(@s.a$);

Now "Hello World!" will be printed in the dialog message. To access s.b$ no need to do anything special.

ShowMessage(s.b$);

This will display "Hello Again!".

Introducing Arrays.

When it comes time to store multiple values into a single variable, we have two choices:

1. Use an array variable
2. Use a linked-list variable

We will use the array variable for now since we will review the linked-list variable type in a later tutorial. PPL offers many ways to work with array variables, including arrays of different sizes and arrays of strings.

Arrays can be defined on local or global variables. To define an array, PPL comes with multiple functions to help you do this.

Dim(var$, 10);

This will create an array of 10 elements of the default type TDOUBLE (8 bytes) for variable var$. To declare multi-dimensional arrays, do the following:

Dim(var$, 10, 10, 10);

You can later access arrays just like other variables by specifying an offset within brakets [].

Dim(var$, 10, 10);
var$[0, 0] = 102.24;
var$[9, 9] = 23.2873;

Notice that we use 0,0. Arrays offsets start at 0 and goes to the array size – 1. If your array size is 10, 10, then the minimum offset if 0,0 and the maximum offset is 9,9. To create arrays with custom element sizes, use SDIM().

SDIM(var$, TBYTE, 10, 10);

This will create an array of 10, 10 elements of type TBYTE (1 byte).

Now, what about strings? You will be happy to hear that PPL handles strings transparently with just a little twist. PPL stores only the string pointer address in the array's elements. Therefore the use of the @ operator is required to retrieve the string when accessing an array element.

Dim(var$, 10);
var$[2] = "Jack Bower";
var$[3] = "Joe Bloe";
ShowMessage(@var$[2] % " " % @var$[3]);

What are your origins?

The screen display can be moved around. The starting origins are at coordinates (0, 0). You can move the screen in any direction. All the sprites will move according to the screen origins. You can design maps with lots of sprites on them, then scroll the whole map just changing the origin values.

SetOriginX(10);
SetOriginY(-10);

If you need sprites such as interface icons to remain at certain physical screen coordinates (always visible), rather than coordinates that are relative to the origin, you will need to add the following options to the sprites:

SO_FIXED, SO_FIXEDX or SO_FIXEDY.

SO_FIXED will keep the sprite at the pixels they are assigned to, even if the origins of the screen are changed. SO_FIXEDX will keep the X axis of the sprite fixed while the SO_FIXEDY will keep the Y axis location of the sprite fixed.

Refresh your game with a sprite!

Now is the time to spice up your game knowledge and get into something really cool: Sprites. Remember the old days of the Nintendo (NES) or the Super Nintendo (SNES) video game consoles? Most games you played back then were using sprites. Sprites are basically just an image you can move around and animate. In PPL sprites are pretty advanced. You can stretch them, tint them, tile them, automatically animate them, and so much more...

Let’s first start by loading an image from disk as a sprite:

MySprite$ = LoadSprite(AppPath$ + "mysprite.bmp", G_RGB(255, 0, 255), 4, 150, NULL);

You always need to retrieve the sprite handle from the LoadSprite() function to be able to access it later on. The sprite handle is just a unique integer value.

The first parameter of the LoadSprite() function is the pathname of the image you wish to use. The image file can be a bitmap (.bmp), a jpeg (.jpg), a Portable Image (.png) or a gif (.gif). The image file can be made of multiple images grouped together in one image file.

The second parameter is the transparent color to use. Sprites can be drawn on the screen with a transparent background to make them blend with the scenery.

The third parameter is the number of frames (images) the image file has. The images must be sequential (one after the other) horizontally within the file, and they all must be the same width and height in pixels.

The fourth parameter is the speed in milliseconds at which the animation will be played. The default animation will swap between each frame one after the other from the left to the right.

The last parameter is the sprite procedure to use for the sprite. We will get into more advanced sprite handling in a later article.

The image is by default visible on the screen at position (0, 0). You can hide or show the sprite using the following:

DelSpriteOption(MySprite$, SO_VISIBLE); // Hide the sprite by removing the SO_VISIBLE flag from the sprite's options.
AddSpriteOption(MySprite$, SO_VISIBLE); // Show the sprite by adding the SO_VISIBLE flag to the sprite's options.

Each sprite has a series of special options that can be removed or added at any time.

Now let's move our sprite on the screen, to move the sprite all you need to do is call the MoveSprite() function and pass a new coordinate. In our case we will move the sprite to where the stylus touches the screen.

In the MainProc of our code we will add a WM_LBUTTONDOWN event that will be triggered whenever the stylus touches the screen:

WM_LBUTTONDOWN:
MoveSprite (MySprite$, wParam$ - (SpriteWidth(MySprite$) / 2), lParam$ - (SpriteHeight(MySprite$) / 2));

Here we center the sprite MySprite$ - which we should have made global at the time of loading (LoadSprite) - around the stylus position. SpriteWidth() returns the width in pixels of the sprite and SpriteHeight() return its height in pixels.

The WM_LBUTTONDOWN uses the wParam$ variable to store the X coordinate position and the lParam$ variable for the Y coordinate position the stylus was pointing to. You can write code for the following events:

WM_LBUTTONDOWN: The stylus is pressed.
WM_LBUTTONUP: The stylus is released from the screen.
WM_MOUSEMOVE: The stylus is being moved around while pressed.

You can stretch a sprite's display by doing the following:

SetSpriteWidth (MySprite$, 100); // Makes the sprite 100 pixels wide.
SetSpriteHeight (MySprite$, 200); // Makes the sprite 200 pixels high.

You can change the animation speed and sequence of a sprite, lets say you have frames for jumping at frame 6 to 10:

SetSpriteFrames (MySprite$, 6, 10, 250, true);

This will set the current animation for MySprite$ from frames 6 to 10, animating at 250 milliseconds. The last parameter specifies if PPL should wait for the current animation timer to expire before going to the new animation frames or change right away.

Draw me a picture I don't get it!

The GameAPI screen is represented by a series of pixels organized on an x and y axis. Position (0, 0) is the top left of the screen and (240, 320) is the bottom right for the typical QVGA display on a PocketPC and (480, 640) is the bottom right for a typical VGA display device.

Drawing to the screen is very simple with the GameAPI, you just need to know where to place the drawing code. Since the first part of our series of articles on the GameAPI talked about a basic code template to create a GameAPI program, we need to focus a little more on the WM_PAINT event here. The WM_PAINT event is called every frame the GameAPI needs to draw to the screen. The WM_PAINT is placed in the game procedure code, like this:

func GameProc(hWnd$, Msg$, wParam$, lParam$)
case (Msg$)
WM_PAINT:
G_Clear(0);
end;
end;

When you initialize the GameAPI you pass the GameProc pointer to the InitGameApiEx() function. PPL will then use this function to trigger custom events like WM_PAINT, WM_TIMER and WM_COLLIDE.

InitGameAPIEx(h$, &GameProc, 240, 320, false, 5, 60);

Inside the WM_PAINT code you can put any type of drawing code you want, like g_clear(0) to clear the screen with a color you like, g_textout() to draw informative text and g_fillrect() to draw a rectangle. PPL comes loaded with a ton of drawing functions. PPL clears the screen in black by default if no WM_PAINT event is defined.

What if you want to draw something on the screen outside the WM_PAINT event code? It’s easy, but you need to follow some guidelines. You need to prepare the screen to be drawn to and when done you need to update the screen. Here is simple code to draw a rectangle, wait 5 seconds and then return to normal drawing of the screen either by triggering the WM_PAINT code or by simply clearing the screen with black.

g_beginscene;
g_fillrect(10, 10, 100, 100, g_rgb(100, 100, 100));
g_update;
delay(5000);

Be careful not to call g_beginscene() without calling a corresponding g_update(). Follow this rule and you will never have any problems.

How to launch an executable from PPL (by Eric Pankoke)

For any number of reasons, you might want to launch an external program from your PPL application. It’s actually rather simple to do. First of all, if you’re not writing a GUI application, you need to include the following file:

#include "windows.ppl"

If you want to launch a program and have it open normally, here’s a quick function to do so:

proc LaunchProgram(path$)
#ifdef _WIN32_WCE
path$ = wide(path$);
verb$ = wide("open");
#else
verb$ = "open";
#endif

struct(info$, SHELLEXECUTEINFO);

info.cbSize$ = sizeof(info$);
info.lpFile$ = &path$;
info.nShow$ = SW_SHOWNORMAL;
info.fMask$ = SEE_MASK_NOCLOSEPROCESS;
info.lpVerb$ = &verb$;
result$ = ShellExecuteEx(&info$);
end;

For more details on how this works, look up the ShellExecuteEx() function on MSDN. To launch an application, you use “open” for the lpVerb member of the SHELLEXECUTEINFO structure. Other supported verbs are dependent on the program that you are attempting to launch, and it will be up to you to figure those out. Path$ should be a fully qualified path / file name combination. Below is a quick demonstration that you can use in a non-GUI application to see how this works:

func WinMain()
#ifdef _WIN32_WCE
LaunchProgram(GetWinDir() + "addrbook.exe");
#else
LaunchProgram(GetWinDir() + "\\notepad.exe");
#endif

return(false);
end;

The PPL Console (by Brad Manske)

A Console Program is a text only interface. It is still a windows program but it eschews the Graphical User Interface (GUI) and event oriented programming for the sake of simplicity. This is just the kind of program you want if your program just processes data and return results. In most cases, when testing the compiler it is quicker and simpler to use the PPL console than to write a Windows GUI program.

To see an example of a console program open the "PPL IDE" link in the PPL program group. Then select "Console..." from the file menu. The PPL console will evaluate what you type on the input line at the bottom and display the results in the output window.

Typing:

10+10

for example, will display 20

It will also work with variables. Try this example:

a$=10
b$=20
a$+b$

The output window will display

> a$=10
10
> b$=20
20
> a$+b$
30

The expressions that PPL can evaluate can be quite complex in this mode and it makes for a handy tool. The real value in the console is using it in your own code. "Hello World" looks like this for a console program:

#include "console.ppl"
func WinMain
InitConsole;
ShowConsole;

write("Hello World");

return (true);
end;

Notice that this is a windows program, so it begins with WinMain. The Console is created and then made visible on the screen. The Write() statement sends the string to the console to be displayed. A Writeln() command also exists that will start a new line after the string has printed. The program ends by returning "true" so that the Console window stays open until the user closes it.

All that remains is to add your code in place of the write statement and you have a way to do unit testing on small pieces of your code. Here are a few string handling operations to get you going:

Write - Send a string to the console
Writeln - Send a string to the console then start a new line
+ - Concatenate 2 strings if alphanumeric ("ab"+"12"="ab12")
+ - add the value of 2 strings if numeric ("10"+"10"="20")
% - Concatenate 2 strings ("ab"+"12"="ab12" or "10"+"10"="1010")
"\n" - advance to the next line on the console

If you want even more control over how the console displays your data, then consult the manual for the "sprintf" statement. C language programmers will recognize this powerful formatting statement. For example:

MyValue$ = 1234;
sprintf(tmpString$, "Value printed in an 8 char field %8d", MyValue$);
write(tmpString$); // " 1234"

If you've followed along so far, you get rewarded with the best tip for using the console, which I have saved for last. ShowMessage() is often used to show the state of the program at some point to help with debugging. But sometimes it doesn't work or you spend all day clicking "OK" because you have to go through a large amount of data before you get to the point in the data where it doesn't work. Instead of dealing with all of that hassle, use the Console.

Create your window, and after the User Interface has been created add InitConsole() & ShowConsole(). Write out the debug statements and before exiting save the console to a file. Now you can search for the case you’re interested in with a text editor.

You should enclose all of the Console calls in #ifdef statements so that they can easily be removed for a production build.

#undefine ProductionBuild // change to #define for no console

#ifndef ProductionBuild
#include "console.ppl"
#endif

func WinProc

// your code - create UI or call the form creation.

#ifndef ProductionBuild
InitConsole;
ShowConsole;
#endif

// your code

#ifndef ProductionBuild
Writeln("Show interesting data in your code.");
#endif

return(true);
end;

That is the quick run down on the console. I've never tried using the Console to log the progress inside a game. I'm hoping that some game designer out there will give this a try. If you do, please tell us all about it in the Forums at http://www.arianesoft.ca/forum.php.

Put some structure in your life!

Life can be a real succession of disorder sometimes. Don't let this way of life turn your programs into nightmares. Put some structure into your code. Variables are a great way to organize and store information, but you need to classify this information into clean and organized structures to be able to keep your code expandable for the future.

A typical variable can be declared and accessed quite easily in PPL. You declare its scope (local or global) if wanted and then you assign values into it. Nothing new here. What if you have a whole lot of information you want to store into variables? Are you going to create one variable for each value you need to store? If you have answered yes to this question, you need to read further as you will discover that structured variables will give you benefits you probably never considered.

Let’s pretend we need to write a simple three questions survey program. We need to gather user information first and then the user’s answers to three questions. You could do the following:

Name$ = "Alain Deschenes";
Address$ = "Somewhere somehow";
Tel$ = "555-555-5555";
Age$ = "32";
Occupation$ = "Too busy";

Question1$ = "His answer #1";
Question2$ = "His answer #2";
Question3$ = "His answer #3";

This will probably turn into a real nightmare when you reach 500 lines of code or more. What if you spell a variable wrong? What if you need to add user information and questions?

With structured variables (called structures), you can group a series of variables into what you might call categories. In our scenario here, we would need a user$ structure and a questions$ structure. Each structure will hold a series of variables.

struct(user$, "Name", "Address", "Tel", "Age", "Occupation");
struct(questions$, "Question1", "Question2", "Question3");

User.Name$ = "Alain Deschenes";
User.Address$ = "Somewhere somehow";
User.Tel$ = "555-555-5555";
User.Age$ = "32";
User.Occupation$ = "Too busy";

Questions.Question1$ = "His answer #1";
Questions.Question2$ = "His answer #2";
Questions.Question3$ = "His answer #3";

Yes it is longer to write but if you use this technique you are guaranteed to get great benefits in the long run.

You can declare as many structure elements as you want inside the Struct() function. Each element you declare is by default a double type variable that can hold pretty much any numerical value. However you can change the type of element you need. There are multiple variable types that PPL can support including:

TBYTE : 1 byte value. Range from 0 to 255.
TSHORT : 2 bytes value. Range from 0 to 65535.
TINT : 4 bytes value.
TUINT : 4 bytes unsigned value.
TDOUBLE : 8 bytes value. Support decimal point.

You can create a structure that will hold 4 bytes with 4 elements of 1 byte each.

struct(mystruct$, "a", tbyte, "b", tbyte, "c", tbyte, "d", tbyte);
mystruct.a$ = 1;
mystruct.b$ = 2;
mystruct.c$ = 3;
mystruct.d$ = 4;

You can also define a custom number of bytes the element will hold. You can then access each byte of the element variable using [x] array syntax.

struct(mystruct$, "element", 256);
mystruct.element$[34] = 20;

You can also copy one structure to another variable by doing the following:

newstruct$ = mystruct$;

You can also pass structures as parameters of funcs or procs like this:

proc MyProc (s$)
s.a$ = 10;
s.b$ = 20;
s.c$ = 30;
end;

proc main
struct(mystruct$, "a", "b", "c");
MyProc (&mystruct$);
ShowMessage(mystruct.a$ + ", " + mystruct.b$ + ", " + mystruct.c$);
end;

How do I get the list of files in a folder?

You need to extract all the possible information from a folder but don't know where to start? Look no further, PPL offers a great flexibility when it comes to using Windows API functions.

The following code will open up the console and output all the files that are contained in the C:\Program Files\PPL\Runtime\ folder.

A new list item is created to store all the filenames.

Imagine the possibilities... The fd$ structure contains important information about each file scanned, like: File attributes, Creation Time, Last Access Time, Last Write Time, File Size and Filename.

#include "console"

func WinMain
  InitConsole;
  ShowConsole;

  List(files$);

  struct(fd$, WIN32_FIND_DATA);
  i$ = FindFirstFile("c:\\Program Files\\PPL\\*.*", &fd$);
  if (i$ != INVALID_HANDLE_VALUE)
    repeat
      Add(files$, char(fd.cFilename$));
    until (FindNextFile(i$, &fd$) == false);
    FindClose(i$);
  end;

  ForEach(Files$);
    Writeln(Files$);
  end;

  return (true);
end;

Installing PPL manually on your PDA / Smartphone

The beauty of PPL is that it can run on most StrongARM or XScale powered devices running under PocketPC 2000, 2002, Windows Mobile 2003, 2003se and 2005. However the installer can give you a hard time if your device is not recognized.

There is a solution for you. Install PPL manually. Sounds complicated? Not at all. Here are the steps you will need to follow.

1. Install the latest version of PPL on your desktop PC.

2. Copy the files inside the RUNTIME folder over to your phone using ActiveSync. Copy all the files inside C:\Program Files\PPL\Runtime\*.* to \Program Files\PPL\.

3. Copy PPL.EXE from your PC at the location: C:\Program Files\PPL\PPC\WM2003\PPL.EXE to your phone at \Program Files\PPL\PPL.EXE

4. Now copy \Program Files\PPL\PPC\WM2005\gsgetfile.dll to \ProgramFiles\PPL\gsgetfile.dll

5. On your phone, go into the File Manager application and run \Program Files\PPL\PPL.EXE. The device might ask questions about whether to trust this application, answer yes. It will come up eventually and setup. When done, exit the application.

6. On your PC, start up the PIDE application. At the far right, there is a dropdown box for the target, set the target to Target->Pocket PC.

7. Now compile and run. Again, the first time (or few times) you do this, the device might complain about untrusted applications, continue to answer yes to running them. After answering yes you will see your application run.

If you want to make a standalone application that runs on your device, go to the menus in PIDE, and select
Run / Make Executable. This will make an executable of your project file into the \My Documents directory on your device. The first time you run it, you'll get the untrusted application message, but after that it will just run.

NOTE: The IDE does not run properly on the Motorola Q at this moment due to the screen size, in the meantime you can use the PIDE on your desktop.

Thanks to Rick Eesley for his instructions and patience!

Distributing your PPL applications.

You are now done testing and debugging your application. It is time to distribute it to your clients or sell it. PPL offers a multitude of ways to do this.

The first method of distribution is to create an executable file (.exe), pack all your files in a zip file and send it over. The second method is to distribute the PPL compiled file (.ppc) file. It is a compressed and encrypted bytecode version of your source code. If you do this you will need to distribute the PPL.EXE application that you can rename to your liking ex: MyApp.exe. You will now need to rename the MyApp.ppc file to Autorun.ppc. PPL looks for Autorun.ppl or Autorun.ppc file at launch time.

Let's review each method one by one:

Create an executable.

There are two ways to generate an executable file in PPL. First you need Pro version to do this. You can use the PIDE by selecting Run / Make Executable. You have a couple choices here:

1. Type of executable you want to generate.

Desktop PC executable.
PocketPC 2000, 2002 compatible executable.
Windows Mobile 2003, 2003se and 2005 compatible executable.

2. Icon file. Allow you to select an icon for your executable file.

3. Use compressed library. This will use the compressed libraries to build your executable. Compressed libraries are about 3 times smaller than normal library files but they can be a little slower to load on some machines.

The second way is to use the main PPL interface on the PocketPC. Here the options you can set:

1. Root file. This is the PPL file to create an executable with.

2. Exe type. Select the executable format to generate. These are the same settings as on the PIDE above.

3. Compressed runtimes. Same as the PIDE.

Once your executable is created you will need to include the external support files that will be used by your application. That is bitmap image files, sound files, text files, data files, etc... It is good practice to keep all files within the same folder or in seperate folders within the root folder of your application.

Extra files that will need to be distributed with your application:

gsgetfile.dll

If you plan on using the GetFile() or PutFile() functions, you might want to distrbute this file along with your application. This .dll file will provide a nice file dialog selection that is an improvement over the standard Windows Mobile or PocketPC OS default dialog.

sqlite_pc.dll or sqlite_ppc.dll

If you use any SQLite functions within your application, these two files will need to be included in the root folder of your application. Be careful because there are two seperate sqlite_dll.dll files. One is for the PC and the other is for the PocketPC. The SQL.PPL library file will load the correct one depending on the version of the executable. It's preferable to provide the correct one for each platform.

vgarom.fnt

This is the default font used by the GameAPI. If you make a game or an application that uses the GameAPI you will need to include this file in the root folder of your application else the FPS and default fonts won't appear on the screen.

Shortcut keys in the PIDE by Brad Manske

By now you've opened up PIDE and used it for a while. Hopefully everyone has noticed the
keyboard shortcuts placed in the menus. Here are a few that are very helpful, but not so
obvious.

In PIDE's Game Level Editor try + while a sprite is selected, this will
Create a new sprite copying the original sprites properties.

In PIDE's Visual Form Builder:

• The key will select the Form Control.
• If you need a little help, F1 will bring up VFB Help and +F1 will bring up the MSDN help for the selected control.
• Hold down the key and move the mouse over the form. This will show dashed lines from the mouse position to the ruler to help align controls on the form.
• Arrow keys can move a control by 1 pixel at a time to get things lined up perfectly.
• When editing controls that can use a list (GroupBox, ListBox, TabControl, etc...) select "Caption" in the properties and then press F5. You can enter values to preload into these control.
• If you need to select a color for the properties, use F4.
• If you need to select a filename for the properties, use F3.
• If you need to select a true/false value for properties, +T will enter true and +F will enter false.

For those of you that are not keyboard jockies, right click on the properties to bring up the context
menu with the options for the properties.

Here is a reference card for those who could use it

PIDE Editor ShortCut Keys:

  -N           New
  -O           Open
  -S           Save file
  -P           Print
  -Z           Undo
  -Z    Redo
  -X           Cut
  -C           Copy
  -V           Paste
          Delete
  -C    Comment Code
  -R           RGB color
  -D           Format Code
  -G           Goto Line Number
  -F           Find
  -F    Find in Files
  -F3          Find Again
  -H           Replace
  -F11         Find Definition
  -F11        Open Selected File
  -F8         Line Profile Result
  -F7          Run
  -F9          Dedicated Run
  F7                 Compile
  F5                 Debug
  F10                Step Over
  F11                Step Into
  -F10         Run to Cursor
  -F5         Stop
  F9                 Toggle Breakpoints
  -B           Breakpoint Window
  -F7          Watches Window
  -F12         File Manager
  F12                Visual Form Builder
  -G           Procedures List
  F4                 Goto Map...
   Clear a controls code.
  F1                 Help
  -F1          MSDN Help

PIDE VFB ShortCut Keys:

  F1                 VFB Help
  +F1          MSDN help on selected control
  F3                 Select FileName for properties
  F4                 Select Color for properties
  F5                 Edit List of values for control
                Focus on the Form Control
               Show Alignment lines
  +T           Enter True for properties
  +F           Enter False for properties
         Move selected control by one pixel.

PIDE Game Level Editor ShortCut Keys:

  +    create a copy of the selected sprite.