| superclass(es) |
window |
| subclass(es) |
- |
| description |
The frame class is a window class that is a container for a panel window,
it can be compared to the frame of a painting. The frame window contains the border and
the menu but it's interior is empty. A class derived from panel is needed to fill the
interior. A frame window includes the top, bottom, left and right side borders of a
window, the menu bar and possibly a horizontal and/or vertical scrollbar. |
| remarks |
The frame class has methods for creating a panel inside it. The default
behavior of a frame window is to close itself if the user presses the ENTER key, this
behavior can be altered by the method putCloseOnENTER/1. |
| see also |
panel - control - sizer - menu
- icon |
| Creating a frame window consists of two steps. After an instance of the
frame class was allocated with new_obj or new_obja
the actual visible window must be created with one of the following methods: create/1, create/2 or create/6.
The style of the window created can be adjusted with the methods putCreateOptions/2, putToolFrameStyle/1
and putPopupFrameStyle/1.
A frame can be shown modeless (an user can switch to another window of the same
application) or it can be shown modal (all windows except the
current modal window are frozen and cannot be activated by the user.
The frame class has two method for creating default panels, the method CreateSinglePanel/2 creates a panel that fills the entire
frame and the method CreateDoublePanel/3 creates two
panels, one panel on the right side of the frame to place buttons on and another to fill
the remaining area of the frame window. Each frame instance can have an icon, the method PutIcon/1 can be used for that.
A frame has a version information window, you
can display this window by pressing on the right mouse button over the window and choosing
the menu option called 'Window Information...'. There is an example of such a window
below. If this menu option may not appear if the right mouse button is clicked the method putAllowDisplayInfo/1
of the window class must be called with the boolean value false
 The version information window displays the
program name, the version of the program, the name and version of the frame window. The
other buttons display information about the company that has released the product, any
(error) messages that the program has generated during execution, the settings of the
program and an about dialog of the application.
The name and version information about the frame window can be altered by
the methods putName/1 and putVersion/1. |
| The frame class also has methods for giving help about the frame window,
each frame class can store a help topic identifier and the name of a help file. Help topic
identifiers are useful for Windows Help files, each topic in such a help is identified by
an unique number. |
create(Output)
| func |
Create the frame window. |
| pre |
TRUE. |
| post |
A boolean value describing the result is put into or matched with the
value of Output. |
create(Parent, Output)
| func |
Create a (child) frame window, the argument Parent refers to the parent
window of the new window. |
| pre |
Parent must refer to a parent window, or contain 0. |
| post |
A boolean value describing the result is put into or matched with the
value of Output. |
create(Parent, X, Y, W, H, Output)
| func |
Create a (child) frame window, the argument Parent refers to the parent
window of the new window. The parameters X, Y, W, and H specify the position and dimension
of the new window |
| pre |
Parent must refer to a parent window, or contain 0. X and Y specify the
position of the upperleft corner and W and H specify the width and height of the window. |
| post |
A boolean value describing the result is put into or matched with the
value of Output. |
putCreateOptions(Resizable, SystemMenu)
| func |
Set several options before the frame has been created. The method has no
effect if a frame has already been created by one of the create methods. If Resizable is
false the frame cannot be resized by the user and if SystemMenu is false the frame window
will not have a system menu. |
| pre |
The parameters Resizable and SystemMenu must both contain a boolean value. |
| post |
The values of the parameters were stored. |
isResizable(Output)
| func |
Determine if the frame window can be resized by the user. |
| pre |
TRUE. |
| post |
If the frame window can be resized then was true assigned to Output, else
was false assigned to Output. |
hasSystemMenu(Output)
| func |
Determine if the frame window has a system menu or not. |
| pre |
TRUE. |
| post |
If the frame window has a system menu then was true assigned to Output,
else was false assigned to Output. |
putToolFrameStyle(YesNo)
| func |
Set or raise the tool window style. A window with this style has no system
menu and a smaller title bar than a normal window. This method changes the window style if
the window is not already created. |
| pre |
The parameter YesNo must contain true or false. |
| post |
If YesNo was true then the tool window style was raised, else it was
lowered. |
toolFrameStyle(Output)
| func |
Determine if the tool window style is on or off. |
| pre |
TRUE |
| post |
If Output was assigned true then the tool window style was raised, else it
was lowered. |
putPopupFrameStyle(YesNo)
| func |
Set or raise the popup window style. A window with this style has no
border, system menu and a title bar. This method changes the window style if the window is
not already created. |
| pre |
The parameter YesNo must contain true or false. |
| post |
If YesNo was true then the popup window style was raised, else it was
lowered. |
popupFrameStyle(Output)
| func |
Determine if the popup window style is on or off. |
| pre |
TRUE |
| post |
If Output was assigned true then the popup window style was raised, else
it was lowered. |
putThinBorderStyle(YesNo)
| func |
Set or raise the thin border window style. A window with this style has a
border that is 1 pixel wide, no system menu and no title bar. This method changes the
window style if the window is not already created. |
| pre |
The parameter YesNo must contain true or false. |
| post |
If YesNo was true then the thin border window style was raised, else it
was lowered. |
thinBorderStyle(Output)
| func |
Determine if the thin border window style is on or off. |
| pre |
TRUE |
| post |
If Output was unified with the value true then the window has the thin
border window style, else not. |
putMenu(Menu, Output)
| func |
Assign a menu to the frame window. |
| pre |
Menu must refer to an exiting menu instance. |
| post |
Output is assigned true if the method succeeds, else it is assigned false. |
 |
If a menu is assigned to a frame window then that frame becomes
responsible for the menu instance, if a frame is destroyed it also destroys it's menu. So
it is not necessary to delete the menu instance after it has been assigned to a frame
window. If a menu is changed after it has been assigned to a frame window then the frame
window must be redrawn to make the changes to the menu visible. |
menu(Output)
| func |
Return the menu of the window. |
| pre |
TRUE. |
| post |
Output is assigned the menu of the window, if the window has no menu then
the value of the variable is not changed. |
drawMenu
| func |
Redraw the entire menu of the frame window. |
| pre |
TRUE. |
| post |
The menu of the frame window was redrawn. |
|
If menu items were added or removed while the menu is visible it needs to
be redrawn to reflect the changes. |
createSinglePanel(ControlPanel, Output)
| func |
Create a single panel inside the frame window, the sizer of the panel
window is a client area sizer. The panel window will always occupy the entire client area
of the frame window. |
| pre |
TRUE. |
| post |
The variable ControlPanel is assigned the new created panel and if the
panel was successfully created true is assigned to Output, else is false assigned. |
|
When a control must be placed on the panel window the value of the
variable ControlPanel can be used. |
createDoublePanel(ControlPanel, ButtonPanel,
Output)
| func |
Create two panels inside the frame window, on the right side of the frame
window a panel is created for placing button controls on it, this panel (buttonpanel) will
always have the same width. The remaining area of the frame window is filled by another
panel, this panel (controlpanel) can be used for placing controls on it. |
| pre |
TRUE. |
| post |
The variable ControlPanel is assigned the panel on the left side of the
frame window, the variable ButtonPanel is assigned the panel on the right side of the
frame window that has a fixed width. If both panels were successfully created true is
assigned to Output, else is false assigned. |
|
When a control must be placed on the panel window the value of the
variable ControlPanel can be used, the buttonpanel is useful for placing the
"OK", "Cancel", etc. buttons on it. |
controlPanel(Output)
| func |
Return the control panel of the frame window. |
| pre |
TRUE. |
| post |
The control panel of the frame window is returned, if the frame window has
no control panel then no value is assigned to Output. |
|
A control panel is created by CreateSinglePanel/2
or CreateDoublePanel/3. |
buttonPanel(Output)
| func |
Return the button panel of the frame window. |
| pre |
TRUE. |
| post |
The button panel of the frame window is returned, if the frame window has
no button panel then no value is assigned to Output. |
|
A button panel is created by CreateDoublePanel/3. |
putControlPanel(Panel, Output)
| func |
Make a panel the so called "control panel" of a frame window.
This panel is meant for placing controls on that display or edit data. |
| pre |
Panel must refer to an instance of the class panel window. |
| post |
If the panel was made the "control panel" of the frame window
then true is assigned to Output, else if there was an error false is assigned. |
putButtonPanel(Panel, Output)
| func |
Make a panel the so called "button panel" of a frame window.
This panel is meant for placing the standard buttons like "OK",
"Cancel", etc. on it. |
| pre |
Panel must refer to an instance of the class panel window. |
| post |
If the panel was made the "button panel" of the frame window
then true is assigned to Output, else if there was an error false is assigned. |
putName(Input)
| func |
Set the name of the frame window, this name is used in the frame window information window. |
| pre |
The Input argument must be a string. |
| post |
The value of Input is the name of the frame window. |
name(Output)
| func |
Get the name of the frame window, this name is used in the frame window information window. |
| pre |
TRUE. |
| post |
The value of Output is the name of the frame window. |
putVersion(Input)
| func |
Set the version information of the frame window, this name is used in the frame window information window. |
| pre |
The Input argument must be a string. |
| post |
The value of Input is the version string of the frame window. |
version(Output)
| func |
Get the version of the frame window, the version string is used in the frame window information window. |
| pre |
TRUE. |
| post |
The value of Output is the version string of the frame window. |
putHelpTopic(TopicId)
| func |
Put the help topic identifier of the frame window, the help topic
identifier can be used if a Windows Help file is used, each topic in a Windows Help file
has an unique number. |
| pre |
The TopicId variable must contain an integer value. |
| post |
The value of TopicId was stored. |
|
Other kind of help files than Windows Help files can also be used. |
helpTopic(Output)
| func |
Get the help topic identifier of the frame window |
| pre |
TRUE. |
| post |
The value of frame help topic identifier is assigned to Output. |
putHelpFile(Name)
| func |
Put the name of the help file of the frame window. |
| pre |
The Name variable must contain a filepath for the helpfile. |
| post |
The value of Name was stored. |
|
The value of the Name variable must be a string enclosed by single quotes,
for instance 'c:\temp\hlp.html', if single quotes are used the value without the single
quotes is stored by the prolog interpreter because the prolog compiler removes the single
quotes, this is not the case if the string is enclosed by double quotes. |
helpFile(Output)
| func |
Get the name of the help file for the frame. |
| pre |
TRUE. |
| post |
The value of frame help file was assigned to Output. |
displayHelp
| func |
Display the topic of the help file associated with the frame window |
| pre |
TRUE. |
| post |
The help file was displayed. |
|
If the extension of the filename of the help file is not .HLP then the
topic identifier is ignored and the windows shell is commanded to open the specified file.
If for instance the name of the help file is HELP.HTML then the shell is commanded to open
the html file, if an internet browser is installed the browser the file will be displayed
by the browser. |
displayInfoWindow
| func |
Display the version information window of the frame window. This window is
also shown if the menu item "Window Information..." is selected from the
popupmenu, unless that menu item was not allowed to appear (see putAllowDisplayInfo/1
of the window class). |
| pre |
TRUE. |
| post |
The version information window is being displayed modal. |
|
For more information see version
information window. |
showModal(Output)
| func |
Show the frame window modal, all other windows of the application are
disabled. The window is shown in the center of the screen. |
| pre |
TRUE. |
| post |
The identifier of the button pressed to close the window is assigned to
the variable Output. |
|
see also putModalResult/1 |
showModal(Center, Hidden, Disable, Output)
| func |
Show the frame window modal, all other windows of the application are
disabled. If the parameter Center is true then the window is shown in the center of
the screen, else not. If Hidden is true then the frame window is hidden after showModal/4
returns, else not. If Disable is true then the frame window is disabled after showModal/4
returns, else not. |
| pre |
TRUE. |
| post |
The identifier of the button pressed to close the window is assigned to
the variable Output. |
|
see also putModalResult/1 |
isModal(Output)
| func |
Determine if the window is being shown modal or modeless. |
| pre |
TRUE. |
| post |
If the window is being shown modal then true is assigned to Output, else
Output will contain the value false. |
putModalResult(Value)
| func |
Assign the value that is returned if the modal window is closed. |
| pre |
The variable Value must contain an integer value. |
| post |
The value of Value was stored as the modal return value. |
modalResult(Output)
| func |
Return the value of the modal result code. |
| pre |
TRUE. |
| post |
The modal return value is assigned to Output. |
stopModal
| func |
Close a modal frame. |
| pre |
The frame to close must execute a modal message loop, see showModal/1. |
| post |
The modal message loop was stopped. |
|
It is better to use the method close/0 because this
method works for modal and for modeless frame windows. |
putCloseOnENTER(YesNo)
| func |
Determine if the window may close if any of it's child controls detects an
ENTER key from the keyboard. |
| pre |
The variable YesNo must contain true or false. |
| post |
The value of YesNo was stored. If YesNo was false the window will NOT
close if the user presses the ENTER key. |
closeOnENTER(Output)
| func |
Determine if the window may close itself if one of it's child controls
detects an ENTER key from the keyboard. |
| pre |
TRUE. |
| post |
If the window may close itself then Output is assigned the value true,
else it is assigned the value false. |
close
| func |
Close the window, even if the frame window is shown modal. |
| pre |
TRUE. |
| post |
The window has been closed. |
putIcon(Icon)
| func |
Assign the icon to the frame window. |
| pre |
Icon must refer to an instance of the class icon. |
| post |
If the variable Icon referred to an icon instance then the icon of the
frame was changed to the value of the variable Icon. |
|
After an icon instance was used to change the icon of a frame the same
instance can still be used for changing the icon of other frame windows. If a frame window
is destroyed it does not delete any icon instances! |
icon(Output)
| func |
Get the icon instance of the frame window. |
| pre |
TRUE. |
| post |
If the frame window has an icon then the icon instance was assigned to
Output. |
onGiveName(Sender, Output)
| func |
Compose a string that is used for displaying the name in the version
information window of the frame window. |
| pre |
The Sender argument refers to the window for which the frame information
window is being opened. |
| post |
Output contains the string that is displayed as the name of the window. |
onGiveVersion(Sender, Output)
| func |
Compose a string that is used for displaying the version in the version
information window of the frame window. |
| pre |
The Sender argument refers to the window for which the frame information
window is being opened. |
| post |
Output contains the string that is displayed as the name of the window. |