RealWin Function list (Page 2)

  Features shown in italics are new additions for version 2.0 of RealWin.
  Pixels Pixel Addressing Miscellaneous
  Colors Clipboard Interface  
  Graphics Objects Windows Help Page 1
Mouse Handling Registry Home


  You can inquire the current value and change the color value of one pixel at a time.
  Set_pixel -- Set the color value of a pixel.
Get_pixel -- Retrieve the current color value of a pixel.


  Choose_color -- This function pops up a dialog box that allows the user of the program to select any available color in his system. Subsequent uses of the color dialog box will remember previous selections and use them as defaults.
Rgb -- Build a color value from its primary components. The actual representation of a color is dependent upon the Windows configuration where it is displayed.


Graphics Objects  
  Delete_object -- The delete_object subroutine deletes an object such as a font, pen, brush, cursor, or bitmap. Deleting objects after you finish with them helps keep Windows from running low on memory and slowing down.
  Get_text_extent -- Find out how much space the given text will require when it is printed. This is useful when you have some rather delicate formatting to do. The dimensions returned are for text written in a normal, horizontal direction.
A Windows font is a combination of typeface, point size and a few other characteristics. The following functions return an INTEGER font handle that can be used wherever a font is required.
  Choose_font -- This function pops up a dialog box that allows the user of the program to select any available font on his system. Note that if the color argument is supplied, then the dialog box will also allow the user to select strikeout or underline for the font.
  Select_font -- This function selects a font based upon information provided by the programmer. If you select a font that isn’t available on the system the program runs on, the system font will be selected instead.
  New_font -- The new_font subroutine selects a new current font for a paint subroutine, deleting the font last selected by new_font. The font selection ends at the end of the paint subroutine.
Pens are used to draw lines and the outline of shapes. The current pen will be the default value at the beginning of a paint subroutine.
  New_pen -- The new_pen subroutine selects a new current pen for a paint subroutine, deleting the pen last selected by new_pen. The pen selection ends at the end of the paint subroutine.
Brushes are used to ‘paint’ backgrounds, fill shapes, etc
  New_brush -- The new_brush subroutine selects a new current brush for a paint subroutine, deleting the brush last selected by new_brush. The current brush fills any shapes that you draw. To draw unfilled shapes create a new_brush with the BS_NULL style. The brush selection ends at the end of the paint subroutine.
  Create_brush -- Create brush returns an INTEGER value that can be used wherever a brush is required. If you finish with the brush before terminating the program, delete it with delete_object. Use this instead of new brush when you will keep the brush for some time, as for a background brush for a window.
A mouse cursor is the bitmap that Windows displays on the screen to indicate the position of the mouse. An application can switch cursors to help the user understand various things about the program.
  Load_cursor -- Load a cursor resource from the executable file. You can pass it to create_window or create_main_window to set a new default cursor for the window. When you are done with the cursor, delete it with delete_object.
The icon associated with a window is displayed in the upper left corner on the system menu and on the task bar when the window is minimized. An icon is a special format of bitmap.
  Load_icon -- Load an icon resource from the executable file. You can pass it to create_window or create_main_window to set a new default icon for the window. When you are done with the icon, delete it with delete_object.
Bitmaps, an extremely important part of Windows programming, can be grouped into two categories: device independent and device dependent.

Device dependent bitmaps typically just exist in a Windows program while it is running. In RealWin, device dependent bitmap arguments are usually called "bitmap". They usually allow for quicker screen display because they are already customized to the display driver.

Device independent bitmap are often stored in files and can be easily moved from one application to another. While there are many different formats available in graphics programs and on the Internet, RealWin currently just uses the Windows-standard ".bmp" file. Many application will convert other types of picture files into ".bmp" files. In RealWin, device independent bitmap arguments are usually called "dib".

  Load_bitmap -- This function loads a device-dependent bitmap from a resource, directly from a device independent bitmap file, or captures the bitmap from the screen. You may only specify one of the following as the source of the bitmap: a resource, id, filename, window, or box. If none of these is specified, the a bitmap image of the whole screen will be captured. Bitmaps can be used for toolbar buttons or in draw_bitmap.
  Draw_bitmap -- The draw_bitmap subroutine outputs a bitmap image to a window, box, print job or another bitmap.
  Create_bitmap -- Create_bitmap creates a device-dependent bitmap of a particular size. If an initial array is not specified then the bitmap is initialized to the color white. If neither a palette nor palette size is specified, then the default application palette is used.
  Array_to_bitmap -- This function converts a two-dimensional INTEGER (1-byte kind) array into a device-dependent bitmap. You supply a palette to let RealWin know what colors to use.
  Load_dib -- This function loads a device-independent bitmap from a resource or directly from a device independent bitmap file.
  Bitmap_to_dib -- This function converts a device-dependent bitmap into a device-independent bitmap.
  Save_dib -- This function writes a device independent bitmap to a file. The usual extension for the filename is ".bmp".
When your display is configured for 256 colors or less, a palette is required for describing colors. In Windows, sometimes your background windows will take on funny colors. This is because the palette associated with the foreground window doesn't have the colors the background needs. For the most part, RealWin will handle palettes automatically, so you don't need to do anything with them.

A palette is a table of the available colors. The palette of the topmost window is the only one that is active at any particular time. Windows tries to match the colors in the other windows as best it can.

The only time you really need to explicitly handle palettes is when you want to do some advanced operations with bitmaps. Each loaded bitmap has a palette associated with it. Each RealWin window can have a palette associated.

A Windows palette is represented two different ways: as a structure containing RGB values and as a "handle". RealWin keeps both representations in a single structure and takes care of most of the management of the palette.

  Init_palette -- This procedure initializes a RealWin palette structure to prepare it for set_palette_item.
  Set_palette_item -- Use this routine to set the RGB colors in a palette.
Animate_palette -- This routine performs the Windows function of "animating" a palette. This will instantly change the colors in any associated windows. In order to use this procedure, you should specify all of your colors with the flags argument to the RGB function specified as PC_RESERVED. Palette animation only works if your Windows display is configured for 256 colors.


Mouse Handling  
  RealWin handles many of the most common uses of the mouse automatically: menu selection, dialog boxes, resizing and moving windows, scrolling, etc. This section describes how to use the mouse for other custom operations.

The capture_mouse_events subroutine gives the Fortran program notice about any or all mouse events, mouse movement and button up, down, click, and double-click on the left, right, and middle buttons. The middle button is seldom used in Windows applications, but is provided just in case you need it.

Drag operations are supported on the left and right buttons. A drag operation is pressing a mouse button, moving the mouse, then releasing the button. Drag operations have many uses in Windows programming. The following functions are supported by RealWin:

Rubber-band box - This a nice feature for use on a map; the user marks a rectangle on the map that can then be enlarged to cover the whole window. The point where you press the left button is one corner of a rectangle and the point where you release it is the diagonal corner. RealWin draws the rectangle and the ‘drag_proc’ decides what to do with it.

Rubber-band line - This can be used on a graph; the user clicks on a node then drags to another node. The program can then redraw the graph with the nodes connected. The point where you press the left button is the beginning of the line and the point where you release it is the end. RealWin draws the line but lets the ‘drag_proc’ decide what to do with the coordinates.

Drag and Drop - The point where you press the left button selects an object and the point where you release it is where the object will be placed. RealWin just gives the coordinates to the ‘drag_proc’ to do the actual selections and moving.

Most Fortran applications will probably only need the higher-level operations, click, double-click and drag. Trying to capture these high level operations and the lower-level ones in the same mouse procedure will work, but is not recommended.

Once you call capture_mouse_events, RealWin will call the procedure you specify whenever the mouse events you specify occur. The same flags you use to specify the mouse events you want to monitor will be returned in the mouse_proc argument ‘event’. Your mouse_proc procedure will continue to be called for each requested event until you turn it off with release_mouse_events or the window is destroyed.

Note that the mouse locations returned to the callback routines are in pixels. This is because the mouse handling routines need to operate as fast as possible due to the large number of messages they must process. RealWin provides procedures to convert the pixel values to proportional, if desired (see pixel addressing).

  Capture_mouse_events -- When you call capture_mouse_events, event flags indicate those mouse events for which you want to be notified regarding the specified window. You can combine the events by adding the elemental mouse event bits together. When the user provokes one of these mouse events, RealWin calls your mouse_proc. The event argument will contain one of the event bits. A SELECT CASE statement on the event argument is a good control structure for a mouse_proc that handles multiple events.
  Release_mouse_events -- Cancels any previous captures for this window.
  Cancel_drag_mark -- This subroutine removes any rubber-band box, rubber-band line, or text marking from the screen. This would typically be called when a paste or zoom is performed on a marked area.
Pixel_to_file_section -- This routine would typically be called after a mouse drag operation on scrolling text. All of the required values are available in the mouse_proc callback procedure.


Pixel Addressing  
  Proportional addressing works best for many situations because your whole display will shape itself to the shape of the window or box, but sometimes pixel addressing is needed. In a paint subroutine, you can use the get_rect procedure to give you the current pixel coordinates of the window or box. Mouse handling callback procedures receive pixel values. Also, RealWin paint functions will return the pixel coordinates of bounding rectangles, beginning and ending points of lines, etc.
  Get_rect -- The get_rect subroutine gets the coordinates of the window or box, in pixels. You may pass a userpaint, window, box, or bitmap argument. If none of those arguments are passed, then get_rect returns a rectangle representing the usable area of the whole screen.
  Conversion Subroutines and Functions
These routines are useful for situations where you need coordinates in a different form. The pixel to proportional routines are particularly useful in association with the mouse routines. The conversion involving inches and millimeters are particularly useful when formatting for the printer. The measurements should produce accurate results on a printer.

In general, if no userpaint, window or box is specified, then the conversions are based upon the whole screen. For best results make the conversions via a userpaint variable whenever possible.

  Point_to_portion -- The point_to_portion subroutine converts a pixel point to proportional coordinates of a window or box. It can be used on the values passed to mouse handling procedures.
  X_pixel_to_portion -- The x_pixel_to_portion function converts a horizontal pixel to a proportional coordinate of a window or box.
  Y_pixel_to_portion -- The y_pixel_to_portion function converts a vertical pixel to a proportional coordinate of a window or box
  X_portion_to_pixel -- The x_portion_to_pixel function converts a horizontal proportion of a window or box to a pixel address.
  Y_portion_to_pixel -- The y_portion_to_pixel function converts a vertical proportion of a window or box to a pixel address
  X_pixel_to_inches -- Convert horizontal pixels to inches on the screen or printer
  Y_pixel_to_inches -- Convert vertical pixels to inches on the screen or printer
  X_inches_to_pixel -- Convert inches on the screen or printer to horizontal pixels
  Y_inches_to_pixel -- Convert inches on the screen or printer to vertical pixels
  X_pixel_to_millimeters -- Convert horizontal pixels to millimeters on the screen or printer
  Y_pixel_to_millimeters -- Convert vertical pixels to millimeters on the screen or printer
  X_millimeters_to_pixel -- Convert millimeters on the screen or printer to horizontal pixels
Y_millimeters_to_pixel -- Convert millimeters on the screen or printer to vertical pixels


Clipboard Interface  
  The clipboard is a common way of transferring data between programs. While the data on the clipboard can be in many different formats, text is the most common. RealWin lets you put data in a file onto the clipboard, via filename or unit.
  Copy_to_clipboard -- This subroutine lets you put a variety of items on the clipboard.
Paste_from_clipboard -- This subroutine recovers data from the clipboard.


Windows Help  
  RealWin lets you invoke the Windows help system from your program. To create your own help file, however, you will need to use some other tool. If you need explanation of any of the terms in this section, refer to the documentation of the tool you use for creating help files.

If the F1 key is pressed when your program is running, RealWin calls RW_control with a command of idm_rw_help. If you return from RW_control with .FALSE., RealWin will invoke the help system with "help on help". If you define your help menu item with idm_rw_help, then it will behave the same as the F1 key.

  Start_win_help -- The start_win_help function starts the Windows help system with the name of a help file.
Stop_win_help -- This routine closes down the Windows Help session on the specified window. RealWin calls this routine automatically when it closes a window.


  The Windows Registry is a storehouse for great deal of information about applications. We don’t explain all of its uses or standards, but we do provide an interface to it.
  Get_registry_value -- Retrieve the value of an item in the Windows registry.
  Open_registry_key -- Open a registry key to take one step down the hierarchy.
Close_registry_key -- When you are done with a key that was opened with open_registry_key, close it with close_registry_key.


Misc Procedures  
  Set_timer -- Start a countdown timer that will generate a command to RW_control. If you want to perform some action after a delay or on a regular basis, use this subroutine. Once the number of seconds (or partial seconds) have expired, RealWin calls RW_control, passing the value in the "command" argument.
  Destroy_timer -- Destroy a "TIMER_MULTIPLE" timer created by set_timer.
  Sleep -- Stop the current execution flow for the given time.
  Beep -- Get the user's attention by making a noise.
  Flash_window -- Bring attention to a window by inverting the color values of a window, then restoring them. You can vary the behavior of the flash by setting invert=.FALSE., to control the speed or number of repetitions.
  Process_messages -- Invoke process_messages to allow screen updates and other operations to execute within compute-intensive code. The function returning .FALSE. means that the user has requested that the application terminate. In this case you should exit your compute-intensive code to allow the program to shut down.
  Add_bit -- Combines up to 10 bit flags.
  Bit_is_set -- Returns .TRUE. if any of the bit flags in ‘bit’ are set in field, and .FALSE. otherwise.
  Compare Rectangles -- You can check whether a pair of scalars of type rect_t are equal or not with the "==" or "/=" operators.
  Message_box -- Displays a message and waits for the user to select a button before proceeding.
  Copy_file -- The function copies a file to a new path name. It will over-write an existing file only if overwrite is specified ".TRUE.".
  Delete_file -- This function deletes the specified file from the file system.
  Get_current_directory -- Get the full path name of the current directory.
  Get_directory_list -- Get a listing of some or all of the files in a directory. Use the filter argument to select only part of the filenames. If you just want the names of the files, specify the file_names argument. If you want details about the files, specify the files argument.
  Set_current_directory -- This changes the current directory for this program.
  Get_windows_directory -- Get the full path name of the Windows directory. Help, executable, ini, pif, etc., files can be found in this directory.
  Get_environment_variable -- Get the value of a variable in your program's environment.
  Set_environment_variable -- Set the value of a variable in your program's environment. Note that this change is only for this program or any programs it spawns with the same environment.
  Get_temp_file_name -- Create a unique name for a temporary file. You can open a file with this name for use during your program's execution.
  Get_exe_name -- Get the full path name of the executable of the currently running program. This can be used to find associated data files that reside in the same directory as the .exe file.
  Set_file_time -- Set the creation, last access, or last written time of a file. The time array is identical to the array used by the Fortran 90 date_and_time subroutine.
  Get_file_time -- Set the creation, last access, or last written time of a file. The time array is identical to the array used by the Fortran 90 date_and_time subroutine.
  Get_volume_info -- The get_volume_info function returns information about the file system and volume whose root directory is specified.
  Get_device_caps -- The get_device_caps function provides direct access to capability parameters of Windows output devices. Indowsway Software does not provide information on the use of the majority of these values. A separate Windows reference is required.
  Get_system_metrics -- The get_system_metrics function provides direct access to parameters and configuration values of Windows. Indowsway Software does not provide information on the use of the majority of these values. A separate Windows reference is required.
  Get_text_metrics -- The get_text_metrics subroutine gets the complete specification of a font.
RealWin_knows_command -- This function tells whether a command passed to rw_control is known to RealWin. If so, then RealWin can handle default processing of the command..

Top of Page