Home

Windows Controls

These procedures are used to create window controls within an AppGraphics window. While the library is currently limited, it does support buttons, menus, and text entry. Buttons and menu items will all have callback functions that allow the user to handle such actions. Users should be aware of possible cross-threading issues; please read the Threads section for more information.

addmenu

C int addmenu (title, parent)
Fortran function addmenu (title, parent)

Description

Creates a menu within a window. This routine can be used to create the root menu bar for a window or to add subsequent menus to the window’s menu bar by properly specifying the parent value.

Parameters

Parameter C Type Fortran Type Description
label const char * character(*) Text to display in a menu. Unused if the menu being created is the root menu bar for a window.
parent int integer The parent menu to which to add this menu. If omitted or specified as MENU_FOR_WINDOW, a menu bar will be added.

Return Value

C int
Fortran integer

An identifier of the menu. If a root menu is attempted to be added twice, this routine will return the error value MENU_ERROR rather than a menu identifier.

addmenuitem

C int addmenuitem (title, parent, callback)
Fortran function addmenuitem (title, parent, callback)

Description

Creates a menu within a window. This routine can be used to create the root menu bar for a window or to add subsequent menus to the window’s menu bar by properly specifying the parent value.

Parameters

Parameter C Type Fortran Type Description
title const char * character(*) Text to display for this menu item
parent int integer The parent menu to which to add this menu item
callback void callback( void ) subroutine callback() The procedure to call when the menu item is selected

Return Value

C int
Fortran integer

An identifier of the menu item.

beginradiogroup

C void beginradiogroup ( )
Fortran subroutine beginradiogroup ( )

Description

Initializes a group of radio buttons. All radio buttons created until the next call to beginradiogroup will be in the same group, meaning only one may be checked at a time.

checkboxischecked

C bool checkboxischecked (id)
Fortran function checkboxischecked (id)

Description

Returns the current state of a check box

Parameters

Parameter C Type Fortran Type Description
id int integer The id of the check box to query

Return Value

C bool
Fortran logical

True if checked, false otherwise.

checkboxsetchecked

C void checkboxsetchecked (id, state)
Fortran subroutine checkboxsetchecked (id, state)

Description

Sets the current state of a checkbox

Parameters

Parameter C Type Fortran Type Description
id int integer The id of the check box to set
state bool logical True to set checked, false to set unchecked

createbutton

C int createbutton (x, y, width, height, label, callback)
Fortran function createbutton (x, y, width, height, label, callback)

Description

Creates a button within a window.

Parameters

Parameter C Type Fortran Type Description
x int integer Leftmost position of the button
y int integer Topmost position of the button
width int integer Width of the button
height int integer Height of the button
label const char * character(*) Text to display on the button
callback void callback( void ) subroutine callback() The procedure to call when the button is clicked

Return Value

C int
Fortran integer

An identifier of the button

createcheckbox

C int createcheckbox (x, y, width, height, label, callback)
Fortran function createcheckbox (x, y, width, height, label, callback)

Description

Creates a check box within a window. The check box is automatically managed; when clicked, the checkbox state is flipped. The label will appear to the right of the actual check box on most systems.

Parameters

Parameter C Type Fortran Type Description
x int integer Leftmost position of the check box
y int integer Topmost position of the check box
width int integer Width of the check box
height int integer Height of the check box
label const char * character(*) Text to display on the check box
callback void callback( void ) subroutine callback()1 The procedure to call when the check box is clicked

Return Value

C int
Fortran integer

An identifier of the check box

createlistbox

C int createlistbox (x, y, width, height, callback)
Fortran function createlistbox (x, y, width, height, callback)

Description

Creates a list box within a window. This list box allows single selections. The callback procedure is called whenever the selection changes.

Parameters

Parameter C Type Fortran Type Description
x int integer Leftmost position of the list box
y int integer Topmost position of the list box
width int integer Width of the list box
height int integer Height of the list box
callback void callback( void ) subroutine callback()1 The procedure to call when the list box selection changes

Return Value

C int
Fortran integer

An identifier of the list box

createradiobutton

C int createradiobutton (x, y, width, height, label, callback)
Fortran function createradiobutton (x, y, width, height, label, callback)

Description

Creates a radio button within a window. Radio buttons, like check boxes, are either checked or clear. However, radio buttons may be in a group such that only one radio button may be enabled at any given time. The radio button is automatically managed; when clicked, the radio button state is flipped, and changes to other buttons in the radio button’s group will be made if applicable. The label will appear to the right of the actual radio button on most systems.

Parameters

Parameter C Type Fortran Type Description
x int integer Leftmost position of the radio button
y int integer Topmost position of the radio button
width int integer Width of the radio button
height int integer Height of the radio button
label const char * character(*) Text to display on the radio button
callback void callback( void ) subroutine callback()1 The procedure to call when the radio button is clicked

Return Value

C int
Fortran integer

An identifier of the radio button

createscrollbar

C int createscrollbar(x, y, width, height, direction, callback)
Fortran function createscrollbar (x, y, width, height, direction, callback)

Description

Creates a scroll bar within the window. The scroll bar can be either horizontal or vertical
depending on the value of direction, which may be either:

Value Description
SCROLL_HORIZONTAL A horizontal scroll bar
SCROLL_VERTICAL A vertical scroll bar

The resulting scroll bar is not tied to the window to allow scrolling automatically. Rather, the developer must provide a callback procedure that will be called with the scrollbar’s current position whenever the scrollbar moves. This callback may then taken action based on the scroll position provided.

Parameters

Parameter C Type Fortran Type Description
x int integer Leftmost position of the scroll bar
y int integer Topmost position of the scroll bar
width int integer Width of the scroll bar
height int integer Height of the scroll bar
direction int integer The direction of the scroll bar
callback void callback( int ) subroutine callback(integer) The procedure to call when the scroll position changes

Return Value

C int
Fortran integer

An identifier of the scroll bar

createtextbox

C int createtextbox (x, y, width, height)
Fortran function createtextbox (x, y, width, height)

Description

Creates an empty text box within a window. The user can edit the contents of this text box. The text will be justified according to the last call to settextjustify for the current window, and the text box’s justification cannot be changed after the text box is created.

Parameters

Parameter C Type Fortran Type Description
x int integer Leftmost position of the text box
y int integer Topmost position of the text box
width int integer Width of the text box
height int integer Height of the text box

Return Value

C int
Fortran integer

An identifier of the text box

enablebutton

C void enablebutton (id, enable)
Fortran subroutine enablebutton (id, enable)

Description

Enables or disables a specified button

Parameters

Parameter C Type Fortran Type Description
id int integer Identifier of the button
enable bool logical True to enable the button, false to disable

enablemenuitem

C void enablemenuitem (id, enable)
Fortran subroutine enablemenuitem (id, enable)

Description

Enables or disables a specified menu item

Parameters

Parameter C Type Fortran Type Description
id int integer Identifier of the menu item
enable bool logical True to enable the menu item, false to disable

enabletextbox

C void enabletextbox (id, enable)
Fortran subroutine enabletextbox (id, enable)

Description

Enables or disables a specified text box

Parameters

Parameter C Type Fortran Type Description
id int integer Identifier of the text box
enable bool logical True to enable the text box, false to disable

getbuttonposition

C bool getbuttonposition (int index, int *left, int *top, int *width, int *height)
Fortran function getbuttonposition (index, left, top, width, height)

Description

Retrieves the position and dimensions of the specified button

Parameters

Parameter C Type Fortran Type Description
index int integer The identifier for the button
left int * integer(intent=out) The horizontal position of the left side of the button
top int * integer(intent=out) The vertical position of the top of the button
width int * integer(intent=out) The width of the button
height int * integer(intent=out) The height of the button

Return Value

C bool
Fortran logical

True if the position was retrieved successfully, false otherwise.

getcheckboxposition

C bool getcheckboxposition (int index, int *left, int *top, int *width, int *height)
Fortran function getcheckboxposition (index, left, top, width, height)

Description

Retrieves the position and dimensions of the specified check box

Parameters

Parameter C Type Fortran Type Description
index int integer The identifier for the check box
left int * integer(intent=out) The horizontal position of the left side of the check box
top int * integer(intent=out) The vertical position of the top of the check box
width int * integer(intent=out) The width of the check box
height int * integer(intent=out) The height of the check box

Return Value

C bool
Fortran logical

True if the position was retrieved successfully, false otherwise.

getlistboxlength

C int getlistboxlength (index)
Fortran function getlistboxlength (index)

Description

Retrieves the number of entries in a list box.

Parameters

Parameter C Type Fortran Type Description
index int integer The list box of interest

Return Value

C int
Fortran integer

The number of entries in a list box.

getlistboxposition

C bool getlistboxposition (int index, int *left, int *top, int *width, int *height)
Fortran function getlistboxposition (index, left, top, width, height)

Description

Retrieves the position and dimensions of the specified list box

Parameters

Parameter C Type Fortran Type Description
index int integer The identifier for the list box
left int * integer(intent=out) The horizontal position of the left side of the list box
top int * integer(intent=out) The vertical position of the top of the list box
width int * integer(intent=out) The width of the list box
height int * integer(intent=out) The height of the list box

Return Value

C bool
Fortran logical

True if the position was retrieved successfully, false otherwise.

getlistboxselection

C int getlistboxselection (index)
Fortran function getlistboxselection (index)

Description

Retrieves the zero-based position of the seletced item in a list box. If there is no selection, a negative value is returned

Parameters

Parameter C Type Fortran Type Description
index int integer The list box of interest

Return Value

C int
Fortran integer

The zero-based position of the currently selected item in the list box.

getlistboxtext

C int getlistboxtext (index, position, text, text_length)
Fortran function getlistboxtext (index position, text)

Description

Retrieves the text for a specified item in a list box. If the text parameter is omitted or is NULL, this function will return the length of the text without a null terminating character. The text parameter must be sized properly to accept the text.

Parameters

Parameter C Type Fortran Type Description
index int integer The list box of interest
position int integer The position of the item in the list box
text char * character(*)1 The buffer to receive the text contents
text_length int N/A The length of the text buffer

Return Value

C int
Fortran integer

The length of the text at the position, CONTROLS_ERROR if a general error occurred, or CONTROLS_BUFFER_TOO_SMALL if the text buffer is too small.

getradiobuttonposition

C bool getradiobuttonposition (int index, int *left, int *top, int *width, int *height)
Fortran function getradiobuttonposition (index, left, top, width, height)

Description

Retrieves the position and dimensions of the specified radio button

Parameters

Parameter C Type Fortran Type Description
index int integer The identifier for the radio button
left int * integer(intent=out) The horizontal position of the left side of the radio button
top int * integer(intent=out) The vertical position of the top of the radio button
width int * integer(intent=out) The width of the radio button
height int * integer(intent=out) The height of the radio button

Return Value

C bool
Fortran logical

True if the position was retrieved successfully, false otherwise.

getscrollbarposition

C bool getscrollbarposition (int index, int *left, int *top, int *width, int *height)
Fortran function getscrollbarposition (index, left, top, width, height)

Description

Retrieves the position and dimensions of the specified scroll bar

Parameters

Parameter C Type Fortran Type Description
index int integer The identifier for the scroll bar
left int * integer(intent=out) The horizontal position of the left side of the scroll bar
top int * integer(intent=out) The vertical position of the top of the scroll bar
width int * integer(intent=out) The width of the scroll bar
height int * integer(intent=out) The height of the scroll bar

Return Value

C bool
Fortran logical

True if the position was retrieved successfully, false otherwise.

getscrollposition

C int getscrollposition (index)
Fortran function getscrollposition (index)

Description

Retrieves the position of the scroll bar.

Parameters

Parameter C Type Fortran Type Description
index int integer The scroll bar to query

Return Value

C int
Fortran integer

The scroll bar’s current position.

gettextboxcontents

C int gettextboxcontents (index, buffer, buflength)
Fortran function gettextboxcontents (index, buffer)

Description

Retrieves the contents of a text box. If the buffer is NULL, the return value is simply the length of text in the text box.

Parameters

Parameter C Type Fortran Type Description
index int integer The text box from which to retrieve text
buffer char * character(*) The buffer to receive the text box contents
buflength int N/A The size of the buffer to receive text

Return Value

C int
Fortran integer

The number of characters copied into the buffer from this call

gettextboxlength

C int gettextboxlength (index)
Fortran function gettextboxlength (index)

Description

Retrieves the length of the text currently in a text box. This routine can be useful for allocating a properly sized string to receive the text.

Parameters

Parameter C Type Fortran Type Description
index int integer The text box from which to retrieve text

Return Value

C int
Fortran integer

The length of the text currently in a text box

gettextboxposition

C bool gettextboxposition (int index, int *left, int *top, int *width, int *height)
Fortran function gettextboxposition (index, left, top, width, height)

Description

Retrieves the position and dimensions of the specified text box

Parameters

Parameter C Type Fortran Type Description
index int integer The identifier for the text box
left int * integer(intent=out) The horizontal position of the left side of the text box
top int * integer(intent=out) The vertical position of the top of the text box
width int * integer(intent=out) The width of the text box
height int * integer(intent=out) The height of the text box

Return Value

C bool
Fortran logical

True if the position was retrieved successfully, false otherwise.

insertlistboxentry

C int insertlistboxentry (index, position, text)
Fortran function insertlistboxentry (index, position, text)

Description

Inserts a string into a specified list box at the requested position in the list box. If the position is less than zero, the entry is appended to the end of the list. If an invalid position is provided, for example, a position that exceeds the current list length, the call will fail.

Parameters

Parameter C Type Fortran Type Description
index int integer The identifier if the list box
position int integer The position in the list where the string will be inserted, or less than zero to append to the list
text const char * character(*) The text to insert

Return Value

C int
Fortran integer

The number of entries in the list, or CONTROLS_ERROR if an error occurred.

radiobuttonischecked

C bool radiobuttonischecked (id)
Fortran function radiobuttonischecked (id)

Description

Returns the current state of a check box

Parameters

Parameter C Type Fortran Type Description
id int integer The id of the radio button to query

Return Value

C bool
Fortran logical

True if checked, false otherwise.

radiobuttonsetchecked

C void radiobuttonsetchecked (id, state)
Fortran subroutine radiobuttonsetchecked (id, state)

Description

Sets the current state of a radio button

Parameters

Parameter C Type Fortran Type Description
id int integer The id of the radio button to set
state bool logical True to set checked, false to set unchecked

removebutton

C void removebutton (index)
Fortran subroutine removebutton (index)

Description

Removes the specified button from the window

Parameters

Parameter C Type Fortran Type Description
index int integer The identifier for the button to remove.

removecheckbox

C void removecheckbox (index)
Fortran subroutine removecheckbox (index)

Description

Removes the specified check box from the window

Parameters

Parameter C Type Fortran Type Description
index int integer The identifier for the check box to remove.

removelistbox

C void removelistbox (index)
Fortran subroutine removelistbox (index)

Description

Removes the specified list box from the window

Parameters

Parameter C Type Fortran Type Description
index int integer The identifier for the list box to remove.

removelistboxentry

C int removelistboxentry (index, position)
Fortran function removelistboxentry (index, position)

Description

Removes a string from the specified list box.

Parameters

Parameter C Type Fortran Type Description
index int integer The identifier if the list box
position int integer The position in the list of the item to remove

Return Value

C int
Fortran integer

The number of entries in the list, or CONTROLS_ERROR if an error occurred.

removemenu

C void removemenu (index)
Fortran subroutine removemenu (index)

Description

Removes the specified menu from the window. This call will also remove all children of a given menu, including menu items and other menus.

Parameters

Parameter C Type Fortran Type Description
index int integer The identifier for the menu to remove.

removemenuitem

C void removemenuitem (index)
Fortran subroutine removemenuitem (index)

Description

Removes the specified menu item from the window.

Parameters

Parameter C Type Fortran Type Description
index int integer The identifier for the menu item to remove.

removeradiobutton

C void removeradiobutton (index)
Fortran subroutine removeradiobutton (index)

Description

Removes the specified radio button from the window

Parameters

Parameter C Type Fortran Type Description
index int integer The identifier for the radio button to remove.

removescrollbar

C void removescrollbar (index)
Fortran subroutine removescrollbar (index)

Description

Removes the specified scroll bar from the window.

Parameters

Parameter C Type Fortran Type Description
index int integer The identifier for the scroll bar to remove.

removetextbox

C void removetextbox (index)
Fortran subroutine removetextbox (index)

Description

Removes the specified text box from the window

Parameters

Parameter C Type Fortran Type Description
index int integer The identifier for the text box to remove.

setbuttonposition

C void setbuttonposition (int index, int left, int top, int width, int height)
Fortran subroutine setbuttonposition (index, left, top, width, height)

Description

Sets the position and size of the specified button

Parameters

Parameter C Type Fortran Type Description
index int integer The identifier for the button
left int integer The horizontal position of the left side of the button
top int integer The vertical position of the top of the button
width int integer The width of the button
height int integer The height of the button

setcheckboxposition

C void setcheckboxposition (int index, int left, int top, int width, int height)
Fortran subroutine setcheckboxposition (index, left, top, width, height)

Description

Sets the position and size of the specified check box

Parameters

Parameter C Type Fortran Type Description
index int integer The identifier for the check box
left int integer The horizontal position of the left side of the check box
top int integer The vertical position of the top of the check box
width int integer The width of the check box
height int integer The height of the check box

setlistboxposition

C void setlistboxposition (int index, int left, int top, int width, int height)
Fortran subroutine setlistboxposition (index, left, top, width, height)

Description

Sets the position and size of the specified list box

Parameters

Parameter C Type Fortran Type Description
index int integer The identifier for the list box
left int integer The horizontal position of the left side of the list box
top int integer The vertical position of the top of the list box
width int integer The width of the list box
height int integer The height of the list box

setradiobuttonposition

C void setradiobuttonposition (int index, int left, int top, int width, int height)
Fortran subroutine setradiobuttonposition (index, left, top, width, height)

Description

Sets the position and size of the specified radio button

Parameters

Parameter C Type Fortran Type Description
index int integer The identifier for the radio button
left int integer The horizontal position of the left side of the radio button
top int integer The vertical position of the top of the radio button
width int integer The width of the radio button
height int integer The height of the radio button

setscrollbarposition

C void setscrollbarposition (int index, int left, int top, int width, int height)
Fortran subroutine setscrollbarposition (index, left, top, width, height)

Description

Sets the position and size of the specified scroll bar

Parameters

Parameter C Type Fortran Type Description
index int integer The identifier for the scroll bar
left int integer The horizontal position of the left side of the scroll bar
top int integer The vertical position of the top of the scroll bar
width int integer The width of the scroll bar
height int integer The height of the scroll bar

setscrollposition

C void setscrollposition (index, pos)
Fortran subroutine setscrollposition (index, pos)

Description

Sets the current position of the scroll bar within its range. If the value is outside the range, it is rounded to the maximum or minimum value as appropriate.

Parameters

Parameter C Type Fortran Type Description
index int integer The identifier for the scroll bar
pos int integer The position of the scroll bar

setscrollrange

C void setscrollrange (index, minPos, maxPos)
Fortran subroutine setscrollrange (index, minPos, maxPos)

Description

Sets the range of values over which the scroll bar can scroll. The left- or top-most position will return minPos, and the right- or bottom-most position will return maxPos.

Parameters

Parameter C Type Fortran Type Description
index int integer The identifier for the scroll bar
minPos int integer The minimum position value of the scroll bar
maxPos int integer The maximum position value of the scroll bar

settextboxcontents

C void settextboxcontents (index, text)
Fortran subroutine settextboxcontents (index, text)

Description

Sets the text to be displayed in a specified text box.

Parameters

Parameter C Type Fortran Type Description
index int integer The identifier for the text box
text const char * character(*) The text to display in the box. Fortran strings will be trimmed when setting the contents.

settextboxposition

C void settextboxposition (int index, int left, int top, int width, int height)
Fortran subroutine settextboxposition (index, left, top, width, height)

Description

Sets the position and size of the specified text box

Parameters

Parameter C Type Fortran Type Description
index int integer The identifier for the text box
left int integer The horizontal position of the left side of the text box
top int integer The vertical position of the top of the text box
width int integer The width of the text box
height int integer The height of the text box

1 Optional named argument