RealWin Function List

UA-108350223-1

Bruce M. Bush

Software Solutions

RealWin Functions

RealWin Function list (Page 1)

	Features shown in italics are new additions for version 2.0 of RealWin.
	Windows	Boxes	Text Output
	Menus	Dialog Boxes	Lines/Shapes
	Status Bar	Painting/Printing	Page 2
	Toolbars	Printing	Home

Windows
	Create_main_window and create_window -- These procedures create windows. During execution you may create and destroy as many windows as you wish, using create_window and destroy_window. With optional arguments, you can specify a window name, menu, toolbar, class name, style, position and size proportionally or in pixels, "paint code", file name, text color, text font, owner, icon, cursor, background brush, show state, paint procedure, exit procedure, scroll procedure, and associated bitmap.
	Redefine_window -- Redefine_window allows you to change various characteristics of a window. The descriptions of the arguments are the same as for create_window and create_main_window.
	Update_window -- This routine forces a window to be repainted.
	Set_foreground -- This routine forces a window to the foreground.
	Window_exists -- This function returns .TRUE. if the value passed to the window argument is a current, valid window.
	Destroy_window -- Destroy_window has a single, required, argument, which is the handle of the window to destroy.

Menus
	Set_menu_item -- The menu bar and each drop-down menu are defined by an array of menu_t type, one element for each item or separator in the menu. Use set_menu_item to assign values to the array elements. Define your own command numbers for the menu items, then create a SELECT CASE construct in your RW_control procedure to act on the commands.
	Update_menu_item -- When you want to change the status of a menu item after you have created the menu, call update_menu_item. It lets you gray and disable items that are not currently valid, then enable them later.
	*Destroy_menu --* If you change the structure of a menu, call destroy_menu before using the menu array again. This will force RealWin to rebuild the menu in its new format.

Status Bar
	A status bar sits at the bottom of most good applications for Windows, displaying various things about the state of the program or the computer. Most of the items on the status bar will be maintained by RealWin once created. Your program can set fields of type STATUS_USER_TEXT throughout the program to inform your user of whatever you deem important. The status bar area also doubles as a place to display the help text for menus. The status bar will be overwritten by help text from the menus when menu items are selected.
	Set_status_item -- You specify the status bar items with an array of type status_t, which can be initialized by calling the subroutine set_status_item.
	Set_status_bar -- After you modify the status bar, call this subroutine to pass the new values to RealWin.
	Update_status_bar -- This routine redraws the status bar immediately.

Toolbars
	Toolbars are another necessity for a full-featured Windows application. A toolbar is a row of buttons that typically sits just below the menu. Toolbar items are usually synonyms for commonly-used menu selections. When the user clicks the toolbar item, RW_control is passed a menu-type command, e.g., idm_open.
	Set_tool_bitmap_item -- The buttons in a toolbar are created from bitmaps. RealWin creates toolbars from bitmaps that are predefined in Windows or toolbar bitmaps from files with the .bmp extension.
	Set_toolbar_item -- The set_toolbar_item subroutine sets up all of the values for given toolbar button.
	Update_toolbar_item -- The update_toolbar_item subroutine updates certain values for given toolbar button.
	Set_toolbar -- Add a toolbar to a window or update an existing toolbar. If you want to specify bitmap or button sizes, you must use this subroutine instead of passing the toolbar to a create window routine.

Boxes
	Boxes are a RealWin mechanism for dividing up screen real estate. When you want sections of a window to be independent of each other, you can define a box for each of the areas. The boxes can then be scrolled or painted as logical entities. Boxes can overlap; the boxes that are defined later in the program flow will write over the earlier ones. Define_box and redefine_box have almost the same argument list, but handle omitted arguments differently. Define_box has a default value for each argument, but the default for redefine_box is the current value for the box.
	Define_box & Redefine_box -- Define_box and redefine_box have almost the same argument list, but handle omitted arguments differently. Define_box has a default value for each argument, but the default for redefine_box is the current value for the box.
	Destroy_box -- Remove a box from its window.

Dialog Boxes
	Dialog boxes are the most common tool for getting user input in Windows. Often a menu selection will lead to a dialog box popping up to get more details about the operation that was selected. A dialog box contains ‘controls’ such as buttons and boxes that can be selected and modified by the user. Text, frames and rectangles are used to enhance the appearance and functionality of a dialog box.
	*Custom Edit Boxes* With RealWin, you can perform almost any custom validation of an edit field that you can think of. Specify the customizing feature in the 'custom' argument. RealWin includes built-in conversion routines for INTEGER, hexadecimal, octal, binary, REAL and DOUBLE PRECISION. If you need other custom fields, just write your own conversion in Fortran, following the template provided in 'custom.f90'. You can also specify a Fortran FORMAT string to the 'format' argument to control conversion from numeric variables and their display in the edit box. The built-in conversion routines validate the syntax of the field as it is being entered, and check to see that it is in range between the minimum and maximum values. If any of these checks fail, then a message box pops up to tell the user of the error. When the message box is OKed, the field gets the keyboard focus. The edit box can also be a 'spinner', which means that it contains a small scroll bar called an 'updown'. When the user clicks the up arrow, the field is incremented by the value in integer_increment, real_increment, or double_increment, depending upon the type of the result. The down arrow causes a similar decrement.
	Set_dialog_item -- Call set_dialog_item for each item in a dialog box, specifying only those entities that you need to; defaults will be supplied for any optional argument that is not supplied.
	Update_dialog_item -- Changes the characteristics of a dialog item. You can change whether a "control" in a dialog box is enabled and/or visible, and most other characteristics. This routine can be used on a modeless dialog box anywhere in your code, or on a modal dialog box in a callback routine from that dialog box.
	Dialog_box -- The dialog_box function creates a modal or modeless dialog box, depending on the modeless argument.
	*Dialog_one_item* -- The dialog_one_item function lets you place a single control (dialog item) on the screen. While it will function as a modeless dialog box, it will look like a stand-alone control. The width and heigth will be the same as the control.
	Get_open_file_name -- The get_open_file_name function allows the user to specify a file to open. The actual open can be performed in Fortran code. Get_open_file_name returns .TRUE. if a filename is selected.
	Get_save_file_name -- The get_save_file_name function allows the user to specify the name of a file in which to save something. The save can be performed in Fortran code with an open or close statement. Get_save_file_name returns .TRUE. if a filename is selected.

Painting and Printing
	In Windows, putting text and graphics into a window is called painting. Printing is, of course, doing the same onto paper. The same drawing and writing procedures work for printing and different forms of painting. Painting is done in callback procedures so that computation can be separated from screen updating and the user interface will operate cleanly. RealWin offers you the choice of using automatic painting routines or writing your own. If you just want to display scrolled text, then all you need to specify is what you want scrolled and RealWin takes care of the rest. If you want to create exotic displays, but you don’t want to reorganize your program, then ‘AUTO_PAINT’ will do the job for you. If you’re writing new code or just want the maximum in performance and capabilities, then you can write your own paint subroutine in Fortran.
	Userpaint structures Any output to the screen or a printer requires a variable of the derived type ‘userpaint’. RealWin uses the convention of naming userpaint structures ‘ups’. You don’t need to know what is in a userpaint structure to use it, but you can access the components if you want. Userpaint structures are only valid while the screen, autopaint, or print job is being created. A userpaint structure in a callback paint subroutine is created by RealWin before it calls the procedure and destroyed after the procedure returns. Start_autopaint and start_print initialize userpaint structures which are subsequently invalidated by end_autopaint and end_print, respectively. A valid userpaint structure must be passed to each RealWin drawing or writing procedure.
	Automatic Scrolling You can associate text or a bitmap image with a window or a box and then let RealWin take care of automatically scrolling it. The normal granularity for text scrolling is a character; for bitmaps it is a bit. By specifying a callback procedure to the scroll_procedure argument, you can take control of the scrolling process. For example, if the bitmap consists of rows and columns you could make a click of the down arrow go down one row, etc.
	*Write_scroll_line* -- Write a line of text to a scrolling window or box. The line is written to the associated file (a temporary file if none was specified), and displayed as the last line in the window or box.
	*Read_scroll_line* -- Read a line of text from a scrolling window or box. Whatever the user types while read_scroll_line is active is displayed as the last line in the window or box and is written to the associated file (a temporary file if none was specified). This routine is useful for making a user interface similar to DOS or UNIX, which can be a useful stage in porting to Windows. For some applications, this kind of input will work for a finished product.
	*Delete_scroll_lines* -- Delete lines from a file being displayed in a scrolling window. The from and to arguments represent the number of the line in the whole file being scrolled, not the number on the screen.
	*Set_scroll_position* -- Force the upper-left corner of a scrolling box or window to a specific line and/or column. If a bitmap is being scrolled, then line and column refer to pixels.
	*Get_scroll_position* -- Get the character postions in the scroll file of the first line, last line, first column and last column displayed on the screen. If the display font is of variable pitch, then the last column will not be reliable. This routine is useful for printing what is currently displayed in the scroll window. If a bitmap is being scrolled, then line and column refer to pixels.
	Automatic Painting This is powerful tool that allows you to get great Windows functionality without reorganizing your existing application. Create a userpaint structure by calling start_autopaint, draw your window with any RealWin paint functions, then finish up by calling end_autopaint. RealWin records the procedure calls, then executes them whenever Windows sends a paint message. If you want to add to a window or box that has already been auto-painted, call restart_autopaint, which also must be terminated with end_autopaint. You can use automatic painting to implement your final application or use it as step toward writing a Fortran paint subroutine.
	Start_autopaint, restart_autopaint -- The start_autopaint procedure starts recording autopaint calls. Restart_autopaint works like start_autopaint except that it doesn't delete what was previously written.
	End_autopaint -- The end_autopaint procedure terminates the recording of paint procedure calls and generates a paint message to cause the window or box to initially display.
	*Painting a bitmap* Painting to a bitmap facilitates a number of techniques in Windows programming. You can draw the image you want on the screen, even if it is bigger than the screen. Pass the bitmap to window or box creation routine and let RealWin take care of scrolling the image. The bitmap can even be printed or converted to a device-independent bitmap and stored in a file. You can create you own button faces for toolbars.
	*Start_bitmap_draw* -- Call start_bitmap_draw to start a drawing operation on a bitmap. This operation does not change what is already in the bitmap, so you can write on top of whatever was there.
	*End_bitmap_draw* -- A call to end_bitmap_draw disassociates the bitmap from the userpaint structure. It also allows the bitmap to be displayed, saved, or printed.
	Fortran Paint subroutines A Fortran paint subroutine lets your application take maximum advantage of RealWin paint functions. Specify the name of the subroutine to the paint_procedure argument and FORTRAN_PAINTS to the paint_code to create_window, create_main_window, define_box, or redefine_box. RealWin will call this procedure whenever the window or box needs updating.
	Current position Some RealWin drawing or writing functions use the current position as their default starting point and set a new current position based upon their finishing point. The current position at the beginning of a paint subroutine is the upper left corner of the rectangle to be painted. Text and graphics procedures use the same current position.
	*Set_current_position* -- Sets a new current postion for drawing operations. All RealWin drawing and text routines will also let you specify starting position.
	*Get_current_position* -- Retrieves the current position.

Printing
	RealWin provides printing capability through the Windows Print Manager. This means that you don’t have to deal with any particular device characteristics in your program. Most programs that support printing will also let the user set up the print job by calling page_setup_dialog. The setup will affect any subsequent printing by the program. To start a print job, call start_print. To move to another page, call next_print_page. To terminate a print job, call end_print. One way to print is to use the code that paints the screen to compose an image to print. After calling start_print, you can call any of the draw routines to create a page. You can use the same subroutine you specify as a paint_procedure to a window or box.
	Start_print -- The start_print function starts a print job, including calling the print dialog. The userpaint structure ‘ups’ must be declared in your code, and will be filled in for use by any of the RealWin drawing or writing functions.
	Next_print_page -- The next_print_page subroutine finishes one page of printing and gets ready for another.
	End_print -- The end_print subroutine must be called to complete a print job.
	Page_setup_dialog -- The page_setup_dialog function will normally be called in response to a menu item labeled "Page Setup". It gives the user control over the printer, margins, orientation, etc., of subsequent print jobs.
	Set_output_fit -- The set_output_fit subroutine sets the size and 'fitting' mode of a userpaint variable, typically for the printer. This allows you to place your printed output in a particular place on the page and set its size. You could even print several images on a single piece of paper, by creating frames with calls to set_output_fit. f you want to specify the sizes and locations in inches or millimeters, then use the conversion routines (y_millimeters_to_pixel, y_inches_to_pixel), passing the results to the pixel_… arguments. Specifying fit_code tells RealWin how to fit your output into the printed page. The ‘model’ shape is derived from the window or box, if specified, otherwise from the whole screen. If you specify locations and fit_code, then the ‘fitting’ is within the area you specified.
	Get_page_data -- The get_page_data subroutine gets information needed for printing text. The information pertains to the number of columns and lines that will fit on a page with the currently selected font, and information the user specified in the page setup dialog box. If you are using a fixed-width font then minimum_chars and average_chars will be the same.
	Start_dummy_userpaint -- Start a dummy userpaint structure compatible with the screen. This can be useful doing inquiry on the display when you are not actually painting.
	End_dummy_userpaint -- Release any resources associated with the dummy userpaint structure.

Text Output
	Write_text -- Write_text writes ASCII text to a window, box, or printer. If the location of the text is not specified, then the current position will be used. RealWin lets you write text in various fonts and colors, with rotation, italics, boldface, or underlining. Automatic formatting, margins, and tab stops are also available.
	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.

Lines and Shapes
	Lines and shapes use the current pen (See Pens). Shapes also use the current brush (See Brushes) to fill their interior. To draw unfilled shapes call new_brush with the BS_NULL style. Many line and shape procedures are based upon a bounding rectangle. The rectangle is defined by the Y-coordinates of its top and bottom, and the X-coordinates of its left and right sides. Ellipses are drawn within the bounding rectangle. Arcs, chords, and pies are created based on a part of an ellipse. All functions are capable of returning the actual pixel coordinates used by RealWin to draw the object.
	Draw_line -- The draw_line function draws a line using the current pen. If either of the beginning coordinates are not specified, then the current position is used. Coordinates can be specified proportionally or with pixels.
	Draw_polyline -- Draw_polyline is a powerful procedure that is useful for plotting as well as other drawing functions. It draws a line from the first point in the input array to the second point, then from the second point to the third point, continuing to the last point in the array. This subroutine allows you to specify the ranges of the x and y axes so that you can pass your actual data. Left_x is the value that will be plotted at the left of the output rectangle, top_y at the top, and so forth. You can use set_output_fit to reduce the output rectangle, or you can define a box in the window for a plot.
	Draw_ellipse -- Draw an ellipse within the bounding rectangle.
	Draw_circle -- Draw a circle based upon a center point and a radius.
	Draw_rectangle -- Draw a filled or empty rectangle according to proportional or pixel arguments. You can draw a squares by specifying only three of the four coordinates. If the right is omitted, the width is calculated to be the same as the height. If the bottom is omitted, the height is set the same as the width.
	Draw_arc and draw_chord -- A chord is a shape formed by an arc plus a line connecting its endpoints. An ellipse formed by the specified bounding rectangle defines the curve of the arc or chord. Two ‘radials’ define the beginning and end points of the arc. A radial is an invisible ray that starts at the center of the bounding rectangle and passes through its defining point. The arc begins where the beginning radial intersects the ellipse, extending counter-clockwise to the point where the end radial intersects the ellipse.
	Draw_polygon -- Draw a filled or empty polygon whose vertices are defined as points in an array. The points can be specified as either proportional or pixel.
	Draw_bezier -- Draw one or a series of cubic Bézier curves using the points in the "points" or "pixel_points" array. The first curve is drawn from the first point to the fourth point by using the second and third points as control points. Each subsequent curve in the sequence needs exactly three more points: the ending point of the previous curve is used as the starting point, the next two points in the sequence are control points, and the third is the ending point. Therefore, the number of points must be a multiple of three, plus one.