Help: Events handling with the Form Designer

[Polo]

(draft help file for using events with the Form Designer, feel free to edit it, improve it etc.)

Main structure

Your application using the Form Designer should be structured this way:

Code: Select all

- one main file, which includes all form .pbf files (eg main.pb)
   - window 1 Purebasic Form file (eg form.pbf)
      - window 1 event Purebasic file (eg form.pb)
   - window 2 Purebasic Form file (eg form2.pbf)
      - window 2 event Purebasic file (eg form2.pb)

Assign an event file in the Form Designer

You need to assign a Purebasic file that will link the .pbf and handle its event. For that, select the window in the Form Designer, and select the .pb file that will contain the event procedures related to that window and its gadgets.



The .pbf file will now include the .pb file you have selected.

Create the event procedure

Open the .pb file, and create the procedures you will need for handling you events. You should follow the example below:

Procedure EventButtonOK(EventGadget, EventType)
MessageRequester("Form", "OK has been clicked on.")
EndProcedure

Assign the event procedure to a gadget

To assign a procedure which will be called once an event is fired on a gadget, select the gadget, and use the dropdown menu to select the procedure contained in the .pb file.



EventButtonOK() will now be called everytime an event occurs on the gadget.

Create the main Purebasic file

Your main file (main.pb in this example) will now need to include form.pbf (which itself includes form.pb). A simple example would look like this:

Code: Select all

IncludeFile "form.pbf"

; Open the window and the gadgets/menu/toolbar created in form.pbf 
InitWindow_0()

Repeat
  Event = WaitWindowEvent()

  ;Call the procedure generated in form.pbf, which handles all events for the window. It will call EventButtonOK().
  Window_0_Events(Event)

Until Event = #PB_Event_CloseWindow
End

[luciano]

Gaetan,
Thanks for the tutorial and the nice preview of Form Designer integrated into the IDE, by the way.

[Mindphazer]

Gaetan,
Thanks for the tutorial and the nice preview of Form Designer integrated into the IDE, by the way.

Yeah
But now, we are much more impatient to see it for real !!

[bembulak]

Your main file (main.pb in this example) will now need to include form.pbf (which itself includes form.pb). A simple example would look like this:

Code:
IncludeFile "form.pbf"

Repeat
Event = WaitWindowEvent()

;Call the procedure generated in form.pbf, which handles all events for the window. It will call EventButtonOK().
Window_0_Events(Event)

Until Event = #PB_Event_CloseWindow
End

Unfortunately the example fails, as there is no window opened when calling Repeat/Until. I had to lookup the *.pbf file first as source to see that there is an "InitWindow_0()" procedure. This forces one to switch between source code, form designer AND source of form designer.

Nevertheless: I like the basic idea, so please keep up the excellent work.
A more RAD-like approach would be a huge benefit for PureBasic.

[Polo]

Thanks bembulak, I forgot this line! It will be much easier to switch when everything is integrated

[nospam]

Just a few suggestions for when the documentation proper is being done... the first screenshot and the sample code might be confusing for new users. The image shows the name of the form in the title bar as "form.pbf" and the red rectangle calls attention to a file named "form.pb" for the events file. Perhaps fEvents.pb would be less confusing. Also event files aren't absolutely necessary as the bare GUI can be developed and the events managed in the code editor. Perhaps this would be simpler for some, and things like event files get treated as advanced features.

BTW, if you need help with reviewing and refining the help text from an experienced author and reviewer/editor, let me know.

Edit: typo fix

[Polo]

Thanks nospam, this is an advanced feature indeed, I started with it as it might not be obvious how to use it

[TI-994A]

Hi Polo. Great job with the Form Designer. I've put together a simple video guide for it (linked in this thread), and would really appreciate your comments. Probably not the best example, since it modifies the *.PBF file, but I couldn't find a way to include an empty ImageGadget().

Thank you.

[Lothar Schirm]

As can be seen in these help instructions and in the video created by TI-994A, creating the event file and creating the event procedures in the event file needs a lot of manual actions in the Form Designer and in the PB Editor, especially for forms with many gadgets. Is it not possible in the next version that the Form Designer creates the event file automatically after the filename and path has been defined in the property window of the form, and that all event procedures are written into the event file automatically by the Form Designer in the following way?

Code: Select all

Procedure Button_0(EventGadget, EventType)

EndProcedure

Procedure Button_1(EventGadget, EventType)

EndProcedure

The names of the procedures could also be created automatically by the Form Designer, using the variable names of the gadgets.

By this way, the PB Editor and the Form Designer would work very much like in Visual Basic and would be very comfortable to use, and it would not be necessary to write a lot of "Procedure ... EndProcedure", but just to write the code within the procedures.

[Polo]

Hi,

I thought about this, it could be nice indeed!

[Lothar Schirm]

One remark:
The .pbf file should not be edited, so it can be updated (overwritten) automatically by the Form Designer at any time if the design of the form is changed. But also if the event file and the event procedures are generated automatically, the event file must be edited, because code has to be written into the event procedures, and eventually other global variables and procedures will have to be placed into the event file which are used by the event procedures. Therefore, an automatic update of the event file seems not to be possible in a simple way. Perhaps the update of the event file should be done manually only.

Just an other question:
An event procedure is called in the event loop of a form with two parameters: EventGadget() and EventType(), though the procedure is called only after an event for the EventGadget has occured. So why is EventGadget() used as a parameter in the procedure? Can you please give an example?

[Polo]

An event procedure is called in the event loop of a form with two parameters: EventGadget() and EventType(), though the procedure is called only after an event for the EventGadget has occured. So why is EventGadget() used as a parameter in the procedure? Can you please give an example?

If you need to do something like GetGadgetState, you need the Gadget handle, which your procedure is not supposed to know if you're using pb_any for instance.

[Lothar Schirm]

A question to Polo:

should'nt this topic be removed? PB 5.10 and PB 5.11 use the form designer without event files and event procedures without EventGadget(). The help documentation contains a short description how the Form Designer works actually, so the help information in this topic is not valid any more.

[AndrewM]

Something is wrong.

I am using PB 5.20 LTS downloaded in Nov 2013 (Win64) and I can't create a form with event handlers. If I create a simple form, then switch to code and add some event handling code, this code is lost on compiling and I am back to the auto-generated code from the form designer GUI. Also, I no longer have the option of writing a separate file with event handlers as the option to do this has been removed.

[Fred]

This topic is deprecated and no more applicable to PB 5.20+