open_textwindow ( : : Row, Column, Width, Height, BorderWidth, BorderColor, BackgroundColor, FatherWindow, Mode, Machine : )

Opening of a textual window.

open_textwindow opens a new textual window, which can be used to perform textual input and output, as well as to perform output of images. The new window is going to be the current output window, i.e. all output (write_string, read_string, disp_region, etc.) is redirected to this window. Before you open more windows, it is necessary to keep in mind the logical number of the current window with the help of get_window. Thereby you are able to switch back to the original window afterwards by calling set_window.

Besides the mouse cursor textual windows possess also a textual cursor, which indicates the current writing position (more exactly: the lower left corner of the output string without consideration of descenders). Its position is indicated through an underscore or another type (the indication of this position may also be disabled (= default setting); cf. set_tshape). You may set or query the position by calling the procedures set_tposition or get_tposition.

After you opened a textual window the position of the cursor is set to (H,0). Whereby H significates the height of the default font less the descenders. But the cursor is not shown. Hence the output starts for writing in the upper left corner of the window.

You may query the colors of the background and the image edges by calling query_color. In the same way you may use query_color in a window of type 'invisible'. During output (write_string) you may set the clipping of text out of the window edges by calling set_check(::'~text':). This disables the creation of error messages, if text passes over the edge of the window.

The origin of the coordinate system of the window resides in the upper left corner (coordinates: (0,0)). The row index grows downward (maximal: Height-1), the column index grows to the right (maximal: Width-1).

The parameter Machine indicates the name of the computer, which has to open the window. In case of a X-window, TCP-IP only sets the name, DEC-Net sets in addition a colon behind the name. The "server" resp. the "screen" are not specified. If the empty string is passed, then the environment variable DISPLAY is used. It indicates the target computer. At this the name is indicated in common syntax <Host>:0.0.

Position and size of a window may change during runtime of a program. This may be achieved by calling set_window_extents, but also through external interferences (window manager). In the latter case the procedure set_window_extents is provided.

Opening a window causes the assignment of a so called default font. It is used in connection with procedures like write_string and you may overwrite it by performing set_font after calling open_textwindow. On the other hand you have the possibility to specify a default font by calling set_system(::'default_font',<Fontname>:) before opening a window (and all following windows; see also query_font).

You may set the color of the font (write_string, read_string) by calling set_color, set_rgb, set_hsi, set_grey or set_pixel. Calling set_insert specifies how the text (resp. the graphics) is combined with the content of the image repeat memory. Thereto you may achieve by calling e.g. set_insert(::'not':) to eliminate the font after writing text twice at the same position.

Normally every output (e.g. write_string, disp_region, disp_circle, etc.) in a window is terminated by a so called "flush". This causes the data to be fully visible on the display after termination of the output procedure. But this is not necessary in all cases, in particular if there are permanently output tasks or if there is a mouse procedure active. Therefore it is more favorable (i.e. more rapid) to store the data until sufficient data is available. You may stop this behavior by calling set_system(::'flush_graphic','false':).

The content of windows is saved (in case it is supported by special driver software); i.e. it is preserved, also if the window is hidden by other windows. But this is not necessary in all cases: If you use a textual window e.g. as a parent window for other windows, you may suppress the security mechanism for it and save the necessary memory at the same moment. You achieve this before opening the window by calling set_system(::'backing_store','false':).

Difference: graphical window - textual window
  - In contrast to graphical windows (open_window) you may specify more
    parameters (color, edge) for a textual window while opening it.
  - You may use textual windows only for input of user data
    (read_string).
  - Using textual windows, the output of images, regions and graphics 
    is "clipped" at the edges. Whereas during the use of graphical
    windows the edges are "zoomed".
  - The coordinate system (e.g. with 'get_mbutton' or 'get_mposition')
    consists of display coordinates independently of image size.
    The maximum coordinates are equal to the size of the window less 1.
    In contrast to this, graphical windows (open_window) use always a 
    coordinate system, which corresponds to the image format.
The parameter Mode specifies the mode of the window. It can have following values:

'visible'     Normal mode for textual windows:
              The window is created according to the parameters and all
              inputs and outputs are possible.

'invisible'   Invisible windows are not displayed in the display.
              Parameters like Row, Column, BorderWidth, BorderColor,
              BackgroundColor and FatherWindow do not have any meaning.
              Output to these windows has no effect. Input (read_string,
		mouse, etc.) is not possible.
		You may use these windows to query representation parameter
		for an output device without opening a (visible) window.
		Common queries are e.g. query_color and
		get_string_extents.

'transparent' These windows are transparent: the window itself is not
		visible (edge and background), but all the other operations
		are possible and all output is displayed.
		Parameters like BorderColor and BackgroundColor do not have
 		any meaning.
		A common use for this mode is the creation of mouse sensitive
		regions (which_window).

'buffer'      These are not visible windows, too. The output of images, 
		regions and graphics is not visible on the display, but is
		stored in memory. Parameters like Row, Column, BorderWidth,
		BorderColor, BackgroundColor and FatherWindow do not have
		any meaning. 
		You may use buffer windows, if you prepare output (in the
		background) and copy it finally with copy_rectangle in a
		visible window.
		Another usage might be the rapid processing of image regions
		during interactive manipulations.
		Textual input and mouse interaction are not possible in this
		mode.


Attention

You have to keep in mind that parameters like Row, Column, Width and Height are restricted through the output device. Is a father window (FatherWindow <> 'root') specified, then the coordinates are relative to this window.


Parameters

Row (input_control)
rectangle.origin.y -> integer
Row index of upper left corner.
Default value: 0
Range of values: 0 <= Row
Minimum increment: 1
Recommended increment: 1
Restriction: Row >= 0

Column (input_control)
rectangle.origin.x -> integer
Column index of upper left corner.
Default value: 0
Range of values: 0 <= Column
Minimum increment: 1
Recommended increment: 1
Restriction: Column >= 0

Width (input_control)
rectangle.extent.x -> integer
Window width.
Default value: 256
Range of values: 0 <= Width
Minimum increment: 1
Recommended increment: 1
Restriction: Width > 0

Height (input_control)
rectangle.extent.y -> integer
Window height.
Default value: 256
Range of values: 0 <= Height
Minimum increment: 1
Recommended increment: 1
Restriction: Height > 0

BorderWidth (input_control)
integer -> integer
Window border width.
Default value: 2
Range of values: 0 <= BorderWidth
Minimum increment: 1
Recommended increment: 1
Restriction: BorderWidth >= 0

BorderColor (input_control)
string -> string
Window border color.
Default value: 'white'

BackgroundColor (input_control)
string -> string
Background color.
Default value: 'black'

FatherWindow (input_control)
integer -> integer / string
Logical number of the father window. For the display as father you may specify 'root' or 0.
Default value: 0
Restriction: FatherWindow >= 0

Mode (input_control)
string -> string
Window mode.
Default value: 'visible'
List of values: 'visible', 'invisible', 'transparent', 'buffer'

Machine (input_control)
string -> string
Computer name, where the window has to be opened or empty string.
Default value: ''


Example
open_textwindow(::0,0,900,600,1,'black','slate blue','root','visible','':) >
get_window(:::Father) >
open_textwindow(::10,10,300,580,3,'red','blue',Father,'visible','':) >
get_window(:::Text) >
open_window(::10,320,570,580,Father,'visible','':) >
set_color(::'red':) >
get_window(:::Graphik) >
read_image(:Image:'affe':) >
disp_image(Image:::) >
repeat(:::) >
set_window(::Graphik:) >
get_mposition(:::Row,Column,Button) >
set_window(::Text:) >
get_greyval(Image::Row,Column,1:Grey) >
write_string(::['  Position (',Row,',',Column,')  ']:) >
write_string(::['Grey value (',Grey,')  ']:) >
new_line(:::) >
until(::Button = 4:) >
set_window(::Father:) >
close_window(:::) >
clear(Image:::).

Result

If the values of the specified parameters are correct, then open_textwindow returns TRUE. If necessary an exception is raised.


Possible Predecessors

init_horus


Possible Successors

get_window, set_window, set_color, query_window_type, get_window_type, set_window_type, which_window, get_mposition, set_tposition, set_tshape, set_window_extents, get_window_extents, query_color, set_check, set_system


Alternatives

open_window


See also

write_string, read_string, new_line, get_string_extents, get_tposition, get_window, set_window, set_color, query_window_type, get_window_type, set_window_type, which_window, get_mposition, set_tposition, set_tshape, set_window_extents, get_window_extents, query_color, set_check, set_system



Copyright © 1996-1997 MVTec Software GmbH