- AppGraphics Documentation
- Getting Started with AppGraphics
- Window Management
- Colors and Patterns
- Mouse Interactions
- Keyboard Interaction
- Graphics Shapes and Primitives
- Text Output
- Graphic Viewports
- Images
- Windows Controls
- Common Dialogs
- Clipboard Operations
- Threads, Thread Safety, and Idling
- AppGraphics License Agreement
Window Management
The following functions provide routines for managing the window, including opening the graphics device and closing the graphics window.
closewindow
C void closewindow (window_id)
Fortran subroutine closewindow (window_id)
Description
Closes the specified graphics window or, optionally, all windows. If window_id is not included (Fortran only), this call will close all windows. The window_id parameter should be the window’s id as referred to by initwindow or one of the following constants:
| Constant | Description |
| ALL_WINDOWS | All open graphics windows (default) |
| CURRENT_WINDOW | The current window |
| NO_CURRENT_WINDOW | All windows except the current window |
Parameters
| Parameter | C Type | Fortran Type | Description |
| window_id | int | integer1 | The id of the window to close or, optionally, a constant described above |
disableresize
C void disableresize ()
Fortran subroutine disableresize ()
Description
Disables resizing for the current window. By default, new windows are not resizeable.
enableresize
C void enableresize ( callback )
Fortran subroutine enableresize ( callback )
Description
Enables resizing for the current window. By default, new windows are not resizeable. The argument can specify a function to call whenever the window’s size changes.
Parameters
| Parameter | C Type | Fortran Type | Description |
| callback | void callback( void ) | subroutine callback()1 | The callback that responds to resize requests |
enablewindow
C void enablewindow ( window, enabled )
Fortran subroutine enablewindow ( window, enabled )
Description
Enables or disables an entire window. This routine can effectively be used to simulate a modal experience by disabling a background window. The background window will no longer be able to respond to clicks, messages, or mouse events once disabled.
Parameters
| Parameter | C Type | Fortran Type | Description |
| window | int | integer | The window id to disable or enable |
| enabled | int | logical | Either 1 in C or .TRUE. in Fortran to enable, or 0 or .FALSE. to disable |
getactivepage
C int getactivepage ( )
Fortran function getactivepage ( )
Description
Returns the page number of the graphics device where drawing is currently taking place. If double buffering is enabled, this will not necessarily be the visible page.
Return Value
C int
Fortran integer
The page that is currently being drawn.
getaspectratio
C void getaspectratio (xaspect, yaspect)
Fortran subroutine getaspectratio (xaspect, yaspect)
Description
Retrieves the aspect ratio for the current window. The values are returned via the two parameters. The yaspect parameter will always be normalized to 10,000, with xaspect scaled accordingly.
Parameters
| Parameter | C Type | Fortran Type | Description |
| xaspect | int * | integer | The screen width of one pixel on the device |
| yaspect | int * | integer | The screen height of one pixel on the device |
getcurrentwindow
C int getcurrentwindow ( )
Fortran function getcurrentwindow ( )
Description
Returns the current window used for all drawing operations.
Return Value
C int
Fortran integer
Returns the current window identifier
getmaxheight
C int getmaxheight ( )
Fortran function getmaxheight ( )
Description
Returns the largest possible height of a window such that it will fit on screen.
Return Value
C int
Fortran integer
The largest height of a window possible.
getmaxwidth
C int getmaxwidth ( )
Fortran function getmaxwidth ( )
Description
Returns the largest possible width of a window such that it will fit on screen.
Return Value
C int
Fortran integer
The largest width of a window possible.
getmaxx
C int getmaxx ( )
Fortran function getmaxx ( )
Description
Returns the largest possible x position within the current window.
Return Value
C int
Fortran integer
The largest horizontal position possible in the current window.
getmaxy
C int getmaxy ( )
Fortran function getmaxy ( )
Description
Returns the largest possible y position within the current window.
Return Value
C int
Fortran integer
The largest vertical position possible in the current window.
getrefreshing
C bool getrefreshing ( )
Fortran function getrefreshing ( )
Description
Retrieves the current state of automatic window refreshing. If True is returned, the window is automatically refreshed when needed. If False, the calling code must manually request refreshes.
Return Value
C bool
Fortran logical
The current state of automatic window refreshing
getsignallingwindow
C int getsignallingwindow ( )
Fortran function getsignallingwindow ( )
Description
From within a callback, this function will return the identifier of the window that triggered the callback. This function would conceptually allow developers to reuse the same callback handlers for multiple windows by allowing the retrieval of the window from which the callback originated. If called from outside a callback or subsequent child call, this function will return -1 as an error. For more about callbacks, see Windows Controls and Mouse Events and Queries where callbacks are normally used.
Return Value
C int
Fortran integer
The window that signalled the callback, or -1 if an error occurred.
getvisualpage
C int getvisualpage ( )
Fortran function getvisualpage ( )
Description
Returns the page number of the graphics device that is currently displayed on screen. If double buffering is enabled, this will not necessarily be the active page.
Return Value
C int
Fortran integer
The page that is currently being shown.
getwindowheight
C int getwindowheight ( )
Fortran function getwindowheight ( )
Description
Returns the current height in pixels of the current window.
Return Value
C int
Fortran integer
The height of the current window.
getwindowwidth
C int getwindowwidth ( )
Fortran function getwindowwidth ( )
Description
Returns the current width in pixels of the current window.
Return Value
C int
Fortran integer
The width of the current window.
getwin32handle
C HWND getwin32handle ( )
Description
Returns a handle to the current window for use with Windows API calls. Note that performing API calls on AppGraphics windows may be problematic and is generally considered unsupported.
Return Value
C HWND
A handle to the current window.
graphdefaults
C void graphdefaults ( )
Fortran subroutine graphdefaults ( )
Description
Return the graphics window to its default settings, including:
- sets the viewport to the entire window
- moves the current position to (0,0)
- sets the default palette colors, background color, and drawing color
- sets the default fill style and pattern
- sets the default text font and justification
graphresult
C int graphresult ( )
Fortran function graphresult ( )
Description
Returns the status of the last graphics operation.
Return Value
C int
Fortran integer
Ths return code will always be one of the following values:
| Constant | Description |
| grOk | No error |
| grNoInitGraph | (BGI) graphics not installed (use initgraph) |
| grNotDetected | Graphics hardware not detected |
| grFileNotFound | Device driver file not found |
| grInvalidDriver | Invalid device driver file |
| grNoLoadMem | Not enough memory to load driver |
| grNoScanMem | Out of memory in scan fill |
| grNoFloodMem | Out of memory in flood fill |
| grFontNotFound | Font file not found |
| grNoFontMem | Not enough memory to load font |
| grInvalidMode | Invalid graphics mode for selected driver |
| grError | Graphics error |
| grIOerror | Graphics I/O error |
| grInvalidFont | Invalid font file |
| grInvalidFontNum | Invalid font number |
| grInvalidDeviceNum | Invalid device number |
| grInvalidVersion | Invalid version number |
initwindow
C int initwindow (width, height, title, left, top, dbflag, closeflag)
Fortran function initwindow (width, height, title, left, top, dbflag, closeflag)
Description
Initializes and opens a window for graphics output. This routine is the recommended method for opening a graphics output device.
Parameters
| Parameter | C Type | Fortran Type | Description |
| width | int | integer | Width of the window |
| height | int | integer | Height of the window |
| title | char * | character(*)1 | Title to display in the titlebar |
| left | int | integer1 | Horizontal screen position of the window. Omitting the value or specifying DEFAULT_POSITION allows the operating system to determine position |
| top | int | integer1 | Vertical screen position of the window. Omitting the value or specifying DEFAULT_POSITION allows the operating system to determine position |
| dbflag | bool | logical1 | Enable double-buffering |
| closeflag | bool | logical1 | Kill program on window close |
Return Value
C int
Fortran integer
Unique identifier of the opened window
isvalidwindow
C bool isvalidwindow (window)
Fortran function isvalidwindow (window)
Description
Determines if the window identifier refers to a valid window
Parameters
| Parameter | C Type | Fortran Type | Description |
| window | int | integer | The identifier of the window to query |
Return Value
C bool
Fortran logical(kind=c_bool)
True if the window with the passed identifier exists, false otherwise
refreshall
C void refreshall ( )
Fortran subroutine refreshall ( )
Description
Refreshes the entire current window.
setactivepage
C void setactivepage (page)
Fortran subroutine setactivepage (page)
Description
Sets the specified page, normally a number returned by either getactivepage or getvisualpage, to the active page for drawing.
Parameters
| Parameter | C Type | Fortran Type | Description |
| page | int | integer | The page to act as the active page for drawing |
setapplicationdpiaware
C void setapplicationdpiaware ( )
Fortran subroutine setapplicationdpiaware ( )
Description
Notifies Windows that the application is aware of HiDPI monitors where the dots per inch rating of a particular monitor is greater than 96dpi. When Windows opens an application on a HiDPI monitor, sometimes referred to as a “4K monitor” or higher, the operating system may scale the application’s drawing operations to emulate 96dpi operation. By calling this procedure as the first call into AppGraphics, the operating system is notified that scaling should not be performed, allowing per-pixel operations and coordinates to refer to physical pixels rather than scaled pixels.
This routine corresponds directly to the SetProcessDPIAware Windows application programming interface call.
NOTE: This routine must be called as the first procedure call in an AppGraphics application.
setaspectratio
C void setaspectratio (xaspect, yaspect)
Fortran subroutine setaspectratio (xaspect, yaspect)
Description
Sets the aspect ratio for the current window. The aspect ratio is used for ensuring shapes are displayed properly. For example, it is used to ensure circles appear as such rather than elipses.
Parameters
| Parameter | C Type | Fortran Type | Description |
| xaspect | int | integer | The screen width of one pixel on the device |
| yaspect | int | integer | The screen height of one pixel on the device |
setcurrentwindow
C void setcurrentwindow (window_id)
Fortran subroutine setcurrentwindow (window_id)
Description
Selects the window of the specified id to be the current window and brings the window to the foreground (if the application is currently in the foreground). All subsequent graphics operations will be applied to the specified window until it is either closed or another window becomes the current window.
Parameters
| Parameter | C Type | Fortran Type | Description |
| window_id | int | integer | The window id |
setdialoghotkeys
C void setdialoghotkeys (enable)
Fortran subroutine setdialoghotkeys (enable)
Description
Enables or disables the use of Windows dialog-like hotkeys for navigation between possible Windows controls in the current window. For example, when enabled, the Tab and arrow keys will move the current keyboard focus between edit boxes, buttons, etc. present within the current window. When disabled, the application can continue to process all keystrokes itself.
Parameters
| Parameter | C Type | Fortran Type | Description |
| enable | bool | logical | True to enable dialog hotkeys, false (the default) to allow the application to handle all keystrokes |
setrefreshing
C void setrefreshing (value)
Fortran subroutine setrefreshing (value)
Description
Enables or disables screen refreshing for a period. Most drawing operations will refresh only the portion of the screen that has been modified. If disabled, multiple drawing operations can be completed faster.
Parameters
| Parameter | C Type | Fortran Type | Description |
| value | bool | logical | If True, automatic screen refreshing is enabled (the default) |
setvisualpage
C void setvisualpage (page)
Fortran subroutine setvisualpage (page)
Description
Sets the specified page, normally a number returned by either getactivepage or getvisualpage, to the page displayed on screen.
Parameters
| Parameter | C Type | Fortran Type | Description |
| page | int | integer | The page to act as the visual page for display |
setwindowclosecallback
C void setwindowclosecallback (callback)
Fortran subroutine setwindowclosecallback (callback)
Description
Sets a callback procedure to be called when the current window is closing. The window will still be valid when this routine is called, though it should not be drawn to, modified, or queried at this time. The callback is ignored if the window was created with closeflag set to true in the initwindow call.
Parameters
| Parameter | C Type | Fortran Type | Description |
| callback | void callback( void ) | subroutine callback() | The procedure to call when the window is closing |
setwindowlargeicon
C void setwindowlargeicon (icon)
Fortran subroutine setwindowlargeicon (icon)
Description
Sets the large icon, as may be possibly displayed in the Windows taskbar or task switcher, to the icon identified in a Windows resource file
Parameters
| Parameter | C Type | Fortran Type | Description |
| icon | int | integer(kind=c_int) | The identifier of the icon as defined in a resource file |
setwindowsmallicon
C void setwindowsmallicon (icon)
Fortran subroutine setwindowsmallicon (icon)
Description
Sets the small icon, as may be possibly displayed in the Windows taskbar or the system menu in the window’s title bar itself, to the icon identified in a Windows resource file
Parameters
| Parameter | C Type | Fortran Type | Description |
| icon | int | integer(kind=c_int) | The identifier of the icon as defined in a resource file |
setwindowsystemclosecallback
C void setwindowclosecallback (callback)
Fortran subroutine setwindowclosecallback (callback)
Description
Sets a callback procedure to be called when the user clicks the close button on a window (the “X” in the corner) or selects “Close” in the window’s system menu. The callback should be a simple function that returns 0 if the window kept open, or 1 if the window should close. This routine may be useful to ask the user if work should be saved prior to closing the window, as an example.
Parameters
| Parameter | C Type | Fortran Type | Description |
| callback | int callback( void ) | function callback() | The procedure to call when the window is closing |
setwindowtitle
C void setwindowtitle (title)
Fortran subroutine setwindowtitle (title)
Description
Sets the title of the current window to the specified string
Parameters
| Parameter | C Type | Fortran Type | Description |
| title | char * | character(len=*) | The new title of the window |
swapbuffers
C void swapbuffers ( )
Fortran subroutine swapbuffers ( )
Description
For double-buffered graphics, this routine will swap the currently visible graphics with the current in-memory buffer. It effectively swaps the visual and active pages.
1 Optional named argument
