Frequently Asked Questions about EUPHORIA

Frequently Asked Questions about Win32Lib

1. What is Win32Lib? ( a Windows routines library )

2. What do I need to know to program for Windows? (controls, attributes, events )

3. How do I make a program for Windows? (make controls, routines to handle events; or IDE)

4. How do I create a "control"? (use the "create" function)

5. What are the "attributes" of a control? (any property, like size, color, location, etc)

6. How can I see or set an attribute of a control? (use appropriate function or procedure)

7. What is an "event"? (any action able to be monitored by Windows)

8. How do I handle "events"? (link an event to a handler routine; or, use setHandler procedure)

9. What is an "event link"? (a connection between an event and a routine to handle the event)

10. How do I create an "event link"? EvntName[CtrlName]=routine_id("hndlr_routine_name")

11. Where are the "event links" PLACED in the program? (AFTER the routine to handle it)

12. What is the "setHandler" procedure? (newer way to connect an event to handler routine)

13. How to I use the "setHandler" procedure?

x. How do I write into a window?

x. How do I draw in a window?

x. How can I write data to a file, and then retrieve it to write into a window?

x. How can I use special keys like up/down arrows in windows?

x. How do I create and use a TIMER?

1. What is Win32Lib? (next) (top)

Answer: Win32Lib is a library of routines which makes a large number of Windows programming elements easily available to the programmer. It was originally created by David Cuny, and later expanded by Derek Parnell, with contributions from Matthew Lewis and others.

Using Win32Lib, you can create one or more windows, and a variety of other "controls" (like push-buttons, menus, text fields, etc.), as well as provide for the occurance of various common "events" (like clicking on a button, pressing a key, etc.).

(top) (next)

2. What do I need to know to program for Windows? (next) (prev) (top)

Answer: Programming for Windows is somewhat different than regular Dos programming in that Windows Programming is based on the use of "controls", which have "attributes", and, it is "event" oriented. There is also a defined main processing loop.

A "control" is basically any standard visual element available to be included in the program from a pre-existing library of controls, or a non-visual element such as a timer. They include the main & other windows, push buttons, list boxes, timers, etc. You can create them, query and change their Attributes, and respond to Events which happen to them.

An "attribute" is any property a control might have, such as the size or placement of the control, its font size, or font color, etc. Various routines are provided by Win32Lib to let you inspect and alter the attributes of controls.

An "event" is any action that is available to be monitored by Windows (such as clicking on a button, or a timer reaching a preset count, etc.), which is then linked by the programmer to some routine created by the programmer to respond appropriatly to that event .

The call to the main processing loop, "WinMain", is placed at the very end of the program, after all the controls have been declared , after all the routines you have written to handle all of the events you want to respond to in your program, and after all the event links.

(top) (next)

3.How do I make a program for Windows? (next) (prev) (top)

Answer: To make a program for Windows, you first define what you want it to do; then you:

Write "include win32lib.ew" (without the quotes) at the beginning of your program ;
Establish the look of the program by creating various "controls" (windows, push-buttons, text fields, list boxes, menus, etc) that would be employed by the program user to do various things;
then you create routines (procedures & functions) to respond appropriately to the users use of the controls;
then you create "event links" to make the users use of a control in fact activate the proper procedure or function;
then on the last line in your Windows program you write a statement which creates the main program loop ("WinMain( your_window_name, desired_window_style" ) .

Note: As an easier alternative to the above, there is an Integrated Development Environment program available from user contributions at RDS which utilizes Win32Lib to give Windows programmers the ability to easily create the visual elements of a Windows program by mouse clicks, like Visual Basic. It also allows event handlers to be easily created, and has a built-in editor.

Example of a Windows program using Win32Lib:

-- example4.exw
--
-- This opens a window with a single button.
-- Clicking the button closes the window.

include win32lib.ew

-- create a window, and a control (a button) in the window:
constant
TheWindow = create( Window, "Close Window", 0, Default, Default, 200, 100, 0 ),
CloseButton = create( DefPushButton, "Close Window", TheWindow, 40, 10, 120, 30, 0 )

-- routine that accomplishes the desired action:
global procedure onClick_CloseButton()
closeWindow( TheWindow )
end procedure

-- tell Windows when to do the action:
onClick[CloseButton] = routine_id( "onClick_CloseButton" )

-- hand control over to Windows:
WinMain( TheWindow, Normal )

(top) (next)

4. How do I create a "control"? (next) (prev) (top)

Answer: You make a "control" by using the "create" function. It has the form:

constant your_control_name = create( class, title, parent, x, y, cx, cy, flags)

class is the kind of control you wish to create (Window, PushButton, Menu, etc).
title is the text that will appear in the object's caption.
parent is the name of the control this control belongs to. The parent of the main window is 0.
x and y specify the position of the object, and cx and cy specify the width and height.
flags are optional additional attributes; place a 0 here if you don't know anything else to put.

Example:
The following will create a Window called MyWindow:

      -- create a window 
      constant MyWindow = create( Window,         -- the class 
                              "My Window",        -- the caption      
                              0,                  -- the parent 
                              Default, Default,   -- x and y position 
                              60, 40,             -- width and height 
                              0 )                 -- no special flags

The following will create a PushButton in MyWindow:

      -- create a pushbutton 
      constant MyButton = create( PushButton,     -- the class 
                                  "Push Me!",     -- the caption      
                                  MyWindow,      -- the parent 
                                  10, 10,         -- x and y position 
                                  60, 40,         -- width and height 
                                  0 )             -- no special flags

There is a list of controls in RunDemos, under "Constants", which allow a template for the creation of any of them to be copied to the clipboard, so you can paste it into your program.

(top) (next)

5. What are the "attributes" of a control? (next) (prev) (top)

An "attribute" is any property a control might have, such as the size or placement of the control, its font size, or font color, etc. The text on a button or in a label is an attribute, as is the condition of a checkBox being checked in or not, or whether a control is visible or not, or whether it is enabled or not.

(top) (next)

6. How can I see or set an attribute of a control? (next) (prev) (top)

Various routines are provided by Win32Lib to let you inspect and alter the attributes of controls.

Examples:

The following function gets the width and height of aButton:
sequence size
size = getCtlSize(aButton) -- size[1] = width of aButton, size[2] = height of aButton

The following procedure sets a check mark in aCheckBox:
setCheck(aCheckBox, 1) -- a value of "0" would make the CheckBox NOT be checked.

(top) (next)

7. What is an "event"? (next) (prev) (top)

An "event" is any action in an application which can be monitored by Windows, such as clicking on a button, or a timer reaching a preset count. Some other events are:
selecting an item in a listBox (onChange), closing or opening a window, dragging & dropping a file or data, moving the mouse or clicking a mouse button, changing the size of a window, and moving a scrollbar button.

(top) (next)

8. How do I handle "events"? (next) (prev) (top)

Answer: Events are handled by writing a statement which sets up a "link" between an "event trap" and some routine you have written to handle the event. The event handling routine you write must be placed before the event trap statement.

There are now two ways to do this. The first, original way, is with an "onSomeEvent" link statement, and the second, newer way, is with a "setHandler" event handler statement using "w32HsomeEvent" constants. You can choose whichever method you wish, though eventually the "onSomeEvent" method may be phased out from Win32Lib.

(top) (next)

9. What is an "event link"? (next) (prev) (top)

Answer: An "event link" is a two part statement which establishes a connection between some pre-defined event and the routine which is intended to respond to the event:

the first part references to some particular kind of event which is innately recognized by the Win32Lib library (such as "onClick" the mouse on some control, "onKeyPress", etc);
the second part references to some routine previously created in the program intended to do what you would want to have happen when that event occured.

Example: An event link might look like this:

onClick[CloseButton] = routine_id( "onClick_CloseButton" )

(top) (next)

10. How do I create an "event link"? (next) (prev) (top)

Answer: To create an "event link",

Determine what kind of event you want to make your program respond to (a click on a button, selection of an item in a list, timer reaching a preset, etc);
then look in the list of events in the Win32Lib manual for the one you want to use (onClick,onKeyPress,onChange, onOpen, etc);
write the event name,
followed by the name of the control which might be acted upon placed in brackets [controlName];
write an equals sign (=);
write "routine_id";
write the name of the routine intended to handle the occurance of the event, placed inside parenthesis and *quotes*: ("routine_name")

It should look like this in general:

EventName[ControlName] = routine_id("event_handler_routine_name")

NOTE: it helps to make the "event_handler_routine_name" reference in some way to the event and the control, like this:

onClick[CloseButton] = routine_id( "onClick_CloseButton" )

(top) (next)

11. Where are the "event links" PLACED in the program? (next) (prev) (top)

Answer: The "event links" must go AFTER the routine they point to.

They can be immediately after, so that every event handling routine has its own event trap/link right after it, (which is usually the easiest way to remember to create both of them), or,
they can all be written near the end of the program, just before the WinMain main processing loop. This can be helpful in a large program: after you have written a number of them in your program but before you are finished with the program, if you have consolidated them near the end, you can go down to them quickly, find the one you may be interested in, and then find its related routine by highlighting the routine name & doing a "search" with your editor.

Example 1, routine and event link together:

-- a routine to handle clicking on the "CloseButton":
global procedure onClick_CloseButton()
closeWindow( TheWindow )
end procedure

-- an event link which tells Windows when to do what action:
onClick[CloseButton] = routine_id( "onClick_CloseButton" )

Example 2, all event links grouped together (after the routines they point to):

procedure onOpen_Window1()
-- do something
end procedure

procedure onClick_StartDisplay()
-- do something
end procedure

--EVENTS TO RESPOND TO IN THIS PROGRAM:
----------------------------------------------------------
onOpen[Window1] = routine_id("onOpen_Window1")
onClick[StartDisplay] = routine_id("onClick_StartDisplay")
onClick[StopDisplay] = routine_id("StopDisplay_onClick")
onTimer[Window1] = routine_id("Window1_onTimer")
onClick[btnTestaSound] = routine_id("onClick_btnTestaSound")

-----------------------------------------------------------
-- MAIN PROCESSING LOOP: hand control over to Windows:
WinMain( Window1, Normal )

(top) (next)

12. What is the "setHandler" procedure? (next) (prev) (top)

Answer: The setHandler procedure is a new way to link an event with the routine written to handle the event. It looks like this:

setHandler(aControlName, a_w32Hevent, routine_id("event_handler_routine_name"))

(top) (next)

13. How to I use the "setHandler" procedure? (prev) (top)

Answer: When you have determined that you want to handle some event, like user clicking on some button, you:

1. write a routine to do whatever you want to have happen when that button is clicked on (read a file, open another window, etc).

That routine should have a parameters list to receive two integers & a sequence,
something like this:
procedure yourRoutine( integer self, integer event, sequence params)
-- your code here, to handle the event;
--can use or test "self", "event" or "params" from parameter list above
end procedure

2. call the setHandler procedure to link your routine to the event:

setHandler( object id, object htype, integer routine) ,

where
id is the ID of the control that the event applies to.
htype is the type of event to trap.
routine is the routine_id of the user written code that will handle the event.

That should look something like this:

setHandler(HelloWin, w32HPaint, routine_id( "onPaint_HelloWin" ))

A list of the various w32H events can be found in RunDemos, under "Constants", and clicking on any w32H event there will copy the general form of "setHandler" for that event to the clipboard so you can paste it into your program.

(top)