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.).
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.
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:
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 )
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.
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.
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.
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.
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.
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:
Example: An event link might look like this:
setHandler(CloseButton,w32HClick,routine_id( "onClick_CloseButton" ))
10. How do I create an "event link"? (next) (prev) (top)
Answer: To create an "event link",
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" ))
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.
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 )
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:
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:
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.