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? (check the 240+ programs in the Demo folder; 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, many of which are listed in attribute.htm)

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

8. How do I handle "events"? (use setHandler procedure to create an event link)

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"? By calling setHandler(CtrlName,EvntName,routine_id("hndlr_routine_name"))

11. Where are the "event links" PLACED in the program? (either right after the handler routine, or at end of program)

12. How do I write into a window? (use the routines listed in font.htm and text.htm)

13. How do I draw in a window? (use the routines listed in graphic.htm)

14. How can I write data to a file, and then retrieve it to write into a window? (use getData(), getValue() or specialised routines)

15. How can I use special keys like up/down arrows in windows? (link a handler to the w32HKetdown or w32HKeyboard event)

16. How do I create and use a TIMER? (use setTimer() and link a handler to the w32HTimer event)

 

 

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:

  1. Write "include win32lib.ew" (without the quotes) at the beginning of your program ;
  2. 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;
  3. then you create routines (procedures & functions) to respond appropriately to the users use of the controls;
  4. then you create "event links" to make the users use of a control in fact activate the proper procedure or function;
  5. 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 statement which establishes a connection between some pre-defined event and the routine which is intended to respond to the event "on behalf of" the control. The statement is a procedure call to setHandler() with 3 arguments:

  1. the first argument is the identifier of the control which is listening for an event to take place, or a sequence of such to assign the same handler to several controls..
  2. the second argument references some particular kind of event which is innately recognized by the Win32Lib library (such as "w32HClick" the mouse on some control, "w32HKeyPress", etc). Like for control identifiers, you can lump together several events in a single sequence;
  3. the third argument references 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:

setHandler(CloseButton,w32HClick,routine_id( "onClick_CloseButton" ))

(top) (next)

 

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

Answer: To create an "event link",

  1. 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);
  2. then look in the list of events in the Win32Lib manual for the one you want to use (w32HClick,w32HKeyPress,w32HChange, w32HOpen, etc);
  3. write setHandler(
  4. followed by the name of the control which might be acted upon
  5. followed by a comma, and then the event name,
  6. write ", routine_id";
  7. write the name of the routine intended to handle the occurance of the event, placed inside parenthesis and *quotes*: ("routine_name");
  8. write another closing parenthese ")"

It should look like this in general:

setHandler(ControlName,EventName, 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:

setHandler(CloseButton,w32HClick,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.

  1. 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,
  2. 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" button:
global procedure onClick_CloseButton(integer id,integer event,sequence params)
closeWindow( TheWindow )
end procedure

-- an event link which tells Windows when to do what action on whom:
setHandler(CloseButton,w32HClick,routine_id( "onClick_CloseButton" ))

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

<begin>
<includes and control creation here>

procedure onOpen_Window1(integer id,integer event,sequence params)
-- do something
end procedure

procedure onClick_StartDisplay(integer id,integer event,sequence params)
-- do something
end procedure

<all other procedures here>

--EVENTS TO RESPOND TO IN THIS PROGRAM:
----------------------------------------------------------
setHandler(Window1,w32HOpen,routine_id("onOpen_Window1")
setHandler(StartDisplay,w32HClick, routine_id("onClick_StartDisplay"))
setHandler(StopDisplay,w32HClick, routine_id("onClick_StopDisplay"))
setHandler(Window1,w32HTimer, routine_id("Window1_onTimer"))
[setHandler(btnTestaSound,w32HClick, routine_id("onClick_btnTestaSound"))

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

(top) (next)

 

12. How to write into a window? (next) (prev) (top)

Answer: The most basic way to do it is using wPuts(aWindowName,aText). This will write aText in the upper left corner of the window the first time wPuts() is used on the window. If wPuts() had been used already on the window, it will pick up where it had left. If you want to move around a little, then you have to write wPuts({aWindowName,aXposition,aYposition},aText). Positions are in pixels.
The above uses the default font and color for the control and no formatting. Far more advanced possibilities are available.

IMPORTANT NOTE: Writing text is just another way of drawing in a window. As a consequence, it must be done at a time when the window is open. This is why drawing text is done in response to an event. If something has to be drawn before any user action, then link to the w32HActivate event for the window.
However, the text you write as the caption of a control, or the contents of a text edit field, label, etc do not need to be written inside an event handler. They are part of the creation data for the controls, and the OS sees to it that they display when appropriate.

Example:

include win32lib.ew
constant win=create(Window,"Writing",0,50, 50, 300, 300,
  w32AUTOCLOSE) -- clicking the window will close it
setWindowBackColor(win,Blue)
-- handler called as soon as the window is open
procedure onActivate_win(integer id,integer event,sequence params)
setTextColor(win,Yellow)
wPuts({win,40,100},"Hello World!")
end procedure
-- link event and routine for control
setHandler(win,w32HActivate,routine_id("onActivate_win"))
-- run program
WinMain(win,Normal)
If you remove the procedure, end procedure and setHandler lines, nothing will be written inside the window, but the "Writing" caption will still be there.

 

13. How do I draw in a window? (next) (prev) (top)

Answer: You will have to supply the window name on which to draw, the bounding box for the shape you draw and a flag which says whether the shape is filled or not. The bounding box is given as four integers:

  1. the upper left corner x
  2. the upper left corner y
  3. the lower right corner x
  4. the lower right corner y
, all in pixels and relative to the usable rectangle, aka client area, of the window. Additional parameters may be required for some shapes, like an angle for a circular arc.

IMPORTANT NOTE: Drawing in a window must be done at a time when the window is open. This is why drawing is done in response to an event. If something has to be drawn before any user action, then link to the w32HActivate event for the window.

Example:
include win32lib.ew
constant win=create(Window,"Writing",0,50, 50, 300, 300,
  w32AUTOCLOSE) -- clicking the window will close it
setWindowBackColor(win,Blue)
-- handler called as soon as the window is open
procedure onActivate_win(integer id,integer event,sequence params)
setPenColor(win,Yellow) -- line and borders color
setPenBrushColor(win,Red) -- fill color
drawRectangle(win,w32True,40,40,220,220) -- draw a large filled square
end procedure
-- link event and routine for control
setHandler(win,w32HActivate,routine_id("onActivate_win"))
-- run program
WinMain(win,Normal)
If you remove the procedure, end procedure and setHandler lines, nothing will be drawn on the window.

 

14. How can I write data to a file, and then retrieve it to write into a window? (next) (prev) (top)

Answer: Writing to files is done in the usual way, so the whole point is about how to retrieve and set control properties. attribute.htm lists the routines provided by the library that do this. The most general ones are getData() and getValue(). To set attributs according to data you retrieve from a file, use specialised routines like setIndex(), setText(), setCheck() and so on, depending on the control you want to act upon. Note that setText() changes the caption of a ontrol. This means the content of an edit field, but only the caption of a window.
Remember that, froł Windows' viewpoint, text drawn onto a window is simply some funny graphics, not text. Text drawn into edit fields or RichEdit controls is considered as text.
Advanced controls known as RichEdit controls have special routines, putStream() and getStream() to transfer contents from control to file and back.

 

15. How can I use special keys like up/down arrows in windows? (next) (prev) (top)

Answer: When keyboard keys are depressed and released, various events fire, received by the control which has the keyboard focus, if any:

The list of virtual key codes is to be found in w32Keys.e. For instance, you can hit "down arrow" in various ways (grey key, numeric keypad with or without shift, etc). The Windows keyboard driver will sort it out and issue a VK_DOWN virtual key code.
The shift state is the sum of four flags indicating whether a shift, control, alt or win shift key is being depressed.
Just set a handler for the keyboard event and control you want to monitor, and decide on what to do based on the reported key.

 

16. How do I create and use a TIMER? (next) (prev) (top)

Answer: Create a timer for a window by calling setTimer(window_name,timer_ID,,interval). timer_ID is an integer you choose. All timers for the same window must have different IDs. interval is the interval in milliseconds between firings of the w32HTimer event. It is an atom that will be rounded down to an integer.
If a window is too busy when a timer event fires, it will discard the Windows message and the event won't fire.
win32lib doesn't support high resolution timers, aka media timers, as of v0.70.3. You can add such support in your program, or consider enhancing the library and committing code.
When the timer ticks, the window will reeive the w32HTimer event, with a parameter sequence of {timer_ID}.
When done with the timer, call killTimer(windowname,timer_ID) to kill it.

(top)