Otk - Open Tool Kit

https://sourceforge.net/projects/otk/                       February 17, 2014
Contents    

Introduction:
Otk is a portable widget library for making graphical user interfaces (GUI's) for application programs. It emphasizes simplicity without eliminating capability. Open graphics Tool Kit supports neutrally: Linux, Unix, Microsoft Windows, and Mac OSX. It is based on OpenGL, and C. Otk provides the following basic widgets:

A simple GUI-Builder is being developed for Otk.


News:
An explanation was added about how to embed icon images into your programs and display them at run-time. See Image2Code.

Jim Popken has developed Python bindings to Otk. The bindings enable Otk to be used from programs written in the Python language. Read more, and download the Python bindings.


Background:
Although initially intended for use with C programs, Otk can be accessed from, or extended to, other languages. Otk addresses several issues with previous graphics toolkits, such as X-Windows, X-Motif, MFC, Tcl/TK, Gtk, Awt, Swing, Glow, FLTK, etc..

Otk deviates from previous graphics environments in several important ways.

Example:

A quick test of a graphic environment's simplicity is to look at what it takes to do the simple helloworld example. Here is the Otk version of helloworld.c for comparison to other graphics toolkits.

#include "otk_lib/otk_lib.c"
main( int argc, char **argv )
{
  OtkInitWindow( 350, 140, argc, argv );
  OtkMakeButton( OtkOuterWindow, 10.0, 10.0, 80.0, 80.0, "Hello World !", 0, 0 );
  OtkMainLoop();
}


Coordinate System:

To simplify window design, all coordinates are expressed in percentages of the container window or widget. The upper left is 0.0%, the lower right is 100.0%. This enables automatic resizing without additional code in each application. (Alternatives would be to specify coordinates in pixels or other arbitrary coordinate systems such as points, cm, or inches. You are always free to convert any such coordinates into percent window size.) Background/foreground eclipsing is handled automatically by the underlying OpenGL functions. The Otk calls manage their own hierarchy and depth.


Window Hierarchy:

The outermost container window (the first window itself) is called, OtkOuterWindow. All subsequent windows are children (or children-of-children, etc.) of the OtkOuterWindow.


Colors:

The OtkColor record specifies r, g, b intensities ranging from 0.0 to 1.0. Zero is the darkest, while 1.0 is the brightest. The convenience function, OtkSetColor( r, g, b ) returns an OtkColor record. The function is formally defined as:


	OtkColor OtkSetColor( float r, float g, float b );

An example usage sets variable mycolor to gray, as follows::

	{
	 OtkColor mycolor;

	 mycolor = OtkSetColor( 0.5, 0.5, 0.5 );
	 ...

The following color macros are pre-defined for convenience:

	Otk_White     = OtkSetColor( 1.0, 1.0, 1.0 )
	Otk_Black     = OtkSetColor( 0.0, 0.0, 0.0 )
	Otk_LightGray = OtkSetColor( 0.75, 0.75, 0.75 )
	Otk_Gray      = OtkSetColor( 0.5, 0.5, 0.5 )
	Otk_DarkGray  = OtkSetColor( 0.25, 0.25, 0.25 )
	Otk_Red       = OtkSetColor( 1.0, 0.0, 0.0 )
	Otk_Green     = OtkSetColor( 0.0, 1.0, 0.0 )
	Otk_Blue      = OtkSetColor( 0.0, 0.0, 1.0 )
	Otk_Cyan      = OtkSetColor( 0.0, 1.0, 1.0 )
	Otk_Yellow    = OtkSetColor( 1.0, 1.0, 0.0 )
	Otk_Violet    = OtkSetColor( 1.0, 0.0, 1.0 )


Widgets:

The following sections list the Otk widget set, with explanations of the calling parameters.




OtkMakePanel( container, panel_type, color, left, top, width, height ); This function makes a rectangular panel, either flat, raised, or recessed, within the parent window or panel. The concept of the panel, also called a container widget, is a very important aspect of Otk. All other widgets and sub-panels must be placed on a container/panel. The OtkOuterWindow is the first container/panel, and is provided by default. Placing sub-panels on a panel provides a method of dividing-up the parent panel. Formal definition: OtkWidget OtkMakePanel( OtkWidget container, int panel_type, OtkColor color, float left, float top, float width, float height ); Returns OtkWidget. Container - is the parent container-panel, onto which the new panel is placed, and to whose frame the coordinates will be relative. Panel types currently include: Otk_Flat = Plan flat rectangle. Otk_Raised = Raised rectangle. Otk_Recessed = Recessed Rectangle. (In the future, more panel types could be added.) Color is an OtkColor record. The left, top, coordinates are relative to the parent window/container origin. All coordinates are in percentage of outer window size, where the upper left corner is (0.0,0.0) and the lower right corner is (100.0,100.0). The following related functions set additional attributes or change default settings: void Otk_Set_Object_Border_Thickness( OtkWidget panel, float thickness ) void Otk_Set_Default_Border_Thickness( float thickness ) void OtkResizePanel( OtkWidget panel, float left, float top, float horiz_size, float vert_size ) *Otk_Tabbed_Panel_New( parent, num, **names, color, left, top, width, height, button_height ); See Panel Functions for more on panel-related functions.
OtkMakeTextLabel( Panel, Text, fontcolor, fontscale, fontweight, x, y ); This function places text onto a panel or window. Formal definition: OtkWidget OtkMakeTextLabel( OtkWidget Panel, char *Text, OtkColor fontcolor, float fontscale, int fontweight, float x, float y ); Returns OtkWidget. Panel - is the container-panel, or parent widget, on which the label is attached/placed. And to whose frame the coordinates will be relative! Text - is the character string array to make the label out of. Fontcolor - an OtkColor record. fontsize - A float scaling factor. 1.0 is normal size, with each character being 12.0% high by 8.0% wide in Otk coordinates. fontweight - 1.0 is normal. 2.0 is bold (double-thick). x, y - Coordinates of the origin of the label. Upper left edge relative to containing panel's upper left origin. The following related functions set additional attributes or change default settings: Otk_Modify_Text( OtkWidget label, char *text ) Otk_Modify_Text_Aspect( OtkWidget label, float aspect ) Otk_Modify_Text_Scale( OtkWidget label, float scale ) Otk_Modify_Text_Color( OtkWidget label, OtkColor text_color ) Otk_Modify_Text_Slant( OtkWidget label, float slant ) Otk_Modify_Text_Thickness( OtkWidget label, float thickness ) Otk_Modify_Text_Position( OtkWidget label, float x, float y ) Otk_Set_Text_Aspect( float aspect ) Otk_Get_Character_Size( OtkWidget label, float *width, float *height ) Otk_Get_Text_Size( OtkWidget label, float *width, float *height ) Otk_FitTextInPanel( OtkWidget label ) See Text Functions for more on text-related functions.
OtkMakeButton( Panel, x, y, horiz_size, vert_size, text, CallBack, Callparam ); This function makes a push-button that will call the named user's function when pressed. Formal definition: OtkWidget OtkMakeButton( OtkWidget Panel, float x, float y, float horiz_size, float vert_size, char *text, void (*callBack)(void *x), void *CallParam ); Returns OtkWidget. Panel - is the container-panel, or parent widget, on which the button is attached/placed. And to whose frame the coordinates will be relative! x, y - Coordinates of the button's upper-left corner on the containing panel (in %). Relative to containing panel's upper left origin. horiz_size, vert_size - Horizontal and vertical size of the button, in % of the containing window's size. Text - is the character string array to put onto the button. CallBack - Function which gets called back when button is pressed. CallParam - Parameter passed to callback function. Additional functions for setting button attributes, such as color, border-thickness, and state can be found under: Related Button Functions.
OtkMakeTextFormBox( container, text, ncols, x, y, horiz_size, vert_size, callback, parameter ); This function places a text fill-in box on the panel. Initial text can be placed in the box, or it can be initialized blank (""). Your own call-back function is called when <Enter> is pressed. The text can also be read from the box by the Otk_Get_Text function below. Formal definition: OtkWidget OtkMakeTextFormBox( OtkWidget container, char *text, int ncols, float x, float y, float horiz_size, float vert_size, void (*callback)(char *s, void *x), void *parameter ) Returns OtkWidget handle. Where: container - is the container-panel, or parent widget, on which the form-box is attached/placed. And to whose frame the coordinates will be relative! text - any initial text to place in the fill-in box. Can be empty string, "". ncols - number of characters to fit in the box. (Note that the width of the box is specified by the horiz_size parameters, so the ncols really sets the horizontal size of the characters to fit in the box of that size.) x, y - Location of the fill-in box's upper-left corner on the containing panel (in %). Relative to containing panel's upper left origin. horiz_size, vert_size - The horizontal and vertical size of the fill-in box in percentage of the containing window. callback - Your function to call when <enter> is pressed. Example: myfunct( char *s, void *x) { printf("You entered %s\n", s); } parameter - arbitrary parameter to pass to your callback function. The following are related functions: void Otk_Modify_Text( OtkWidget textbox, char *text ) Places the specified text in the form box. void *Otk_Get_Text( OtkWidget textbox, char *text, int n ) Returns any text from the specified form-box into the character-array in the second parameter. The third parameter should be specified as the maximum length of the character array for safety.
OtkMakeTextEditBox( container, text, nrows, ncols, x, y, horiz_size, vert_size ); This function places a multi-row text-edit box on the panel. Initial text can be placed in the box, or it can be initialized blank (""). The text can be read from the box by the Otk_Get_Text function below. Much like the simple text-box above, but enables more than one row, and has no callback function, since <enter> is legal character to break lines in the edit-box. Read any entered text with the Otk_Get_Text (below), perhaps initiated by an "ok" button callback.. Formal definition: OtkWidget OtkMakeTextEditBox( OtkWidget container, char *text, int nrows, int ncols, float x, float y, float horiz_size, float vert_size ) Returns OtkWidget handle. Where: container - is the container-panel, or parent widget, on which the edit-box is attached/placed. And to whose frame the coordinates will be relative! text - any initial text to place in the edit-box. Can be empty string, "". ncols - number of character columns to fit in the box. (Note that the size of the box is specified by the horiz_size and vert_size parameters, so ncols and nrows really set the horizontal and vertical size of the characters to fit in the box.) nrows - number of character rows to fit in the box. x, y - Location of the edit-box's upper-left corner on the containing panel (in %). Relative to containing panel's upper left origin. horiz_size, vert_size - The horizontal and vertical size of the edit-box in percentage of the containing window. The following are related functions: void OtkAddTextScrollbar( OtkWidget container, float width ) void *Otk_Get_Text( OtkWidget textbox, char *text, int n )
OtkMakeToggleButton( container, x, y, horiz_size, vert_size, callback, parameter ); This function makes a simple toggle-button on the panel. When pressed, it toggles it's state, and calls the named user function while passing the given parameter. The parameter, such as an integer, can be used to identify which button was pressed. Formal definition: OtkWidget OtkMakeToggleButton( OtkWidget container, float x, float y, float horiz_size, float vert_size, void (*callback)(int state, void *x), void *parameter ) Returns OtkWidget handle. Where: container - is the container-panel, or parent widget, on which the button is attached/placed. And to whose frame the coordinates will be relative! x, y - Coordinates of the button's upper-left corner on the containing panel (in %). Relative to containing panel's upper left origin. horiz_size, vert_size - The horizontal and vertical size of the button in percentage of the containing window. callback - User function called when toggled. parameter - parameter passed to user function. The following are related functions: void Otk_Set_Button_State( OtkWidget button, int state ) Causes named button to assume the specified state of: 0 = not toggled, not depressed. 1 = toggled on, depressed. int Otk_Get_Button_State( OtkWidget button) Returns the named button's state as 0=not-depressed, or 1=depressed.
OtkMakeRadioButton( container, x, y, horiz_size, vert_size, callback, parameter ); This function places a radio-button onto the panel. The first radio-button of a set must name the parent-panel/window as the container. The remaining radio-buttons in a set must name one of the other buttons in the set as their parent-container. When pressed, the pressed radio button is set, and the others are un-set. Only one radio-button in a set has the depressed state at a time. The named user function is called when pressed, and the given parameter value is passed. The parameter, such as an integer, can be used to identify which button was pressed. Formal definition: OtkWidget OtkMakeRadioButton( OtkWidget container, float x, float y, float horiz_size, float vert_size, void (*callback)(void *x), void *parameter ) Returns OtkWidget handle. Where: container - is the container-panel, or parent widget, on which the button is attached/placed. And to whose frame the coordinates will be relative! x, y - Coordinates of the button's upper-left corner on the containing panel (in %). Relative to containing panel's upper left origin. horiz_size, vert_size - The horizontal and vertical size of the button in percentage of the containing window. callback - User function called when toggled. parameter - parameter passed to user function. The following are related functions: void Otk_SetRadioButton( OtkWidget radiobutton ) Causes named button to be depressed, while releasing all others in the set. int Otk_Get_Button_State( OtkWidget button) Returns the named button's state as 0=not-depressed, or 1=depressed.
OtkMakeSliderHorizontal( container, x, y, horiz_size, callback, parameter ) This function places a horizontal slider onto the named panel. The named user function is called when the slider is moved. The new slider position is passed as the first value in the range 0.0 to 1.0. The given parameter is passed as the second value. The parameter can be used for a variety of purposes, and it can be a pointer to a larger data structure. One usage of the parameter is to uniquely identify which slider moved, when a single call-back routine is used to handle multiple sliders. Formal definition: void OtkMakeSliderHorizontal( OtkWidget container, float x, float y, float horiz_size, void (*callback)(float v, void *x), void *parameter ) Example:
OtkMakeSliderVertical( container, x, y, vertical_size, callback, parameter ) This function places a vertical slider onto the named panel. See OtkMakeSliderHorizontal above. Formal definition: void OtkMakeSliderVertical( OtkWidget container, float x, float y, float vertical_size, void (*callback)(float v, void *x), void *parameter ) Otk_SetSliderKnob( slider, position, horiz_sz, vert_sz ) This function places the slider knob at the specified position, from 0.0 to 1.0. For vertical sliders, 0.0 is the bottom, and 1.0 is the top. For horizontal sliders, 0.0 is the left side, and 1.0 is the right side. These values also correspond to the values returned from the slider. This function can also sets the size of the slider knob. The horiz_sz parameter sets the knob's width, while the vert_sz parameters sets the knob's height. The default knob size is 1.0 in both directions. Formal definition: void Otk_SetSliderKnob( OtkWidget slider, float position, float knobwidth, float knowheight )
Otk_Make_Menu( container, x, y, horiz_size, vert_size, text ) This function creates a menu pull-down. This forms the top-level entry-point to a pull-down menu. Items are then added to the menu with the Otk_Add_Menu_Item and/or Otk_Add_SubMenu functions described below. Formal definition: OtkWidget Otk_Make_Menu( OtkWidget container, x, y, float horiz_size, float vert_size, char *text ) Otk_Add_Menu_Item( container, *text, callback, parameter ) This function adds a menu item to a pull-down menu. Formal definition: OtkWidget Otk_Add_Menu_Item( OtkWidget container, char *text, void (*callback)(void *x), void *parameter ) OtkWidget Otk_Add_SubMenu( OtkWidget container, char *text ) This function creates a sub-menu pull-down on an existing menu. Formal definition: OtkWidget Otk_Add_SubMenu( OtkWidget container, char *text ) Otk_Set_Menu_Selectable( menu_item, on_notoff ) This function deativates (0) or activates (1) a menu-item. Formal definition: void Otk_Set_Menu_Selectable( OtkWidget menu_item, int on_notoff )
Otk_Make_Selection_List( container, rows, cols, left, top, horiz_size, vert_size ) Formal definition: OtkWidget Otk_Make_Selection_List( OtkWidget container, int rows, int cols, float left, float top, float horiz_size, float vert_size ) This function creates a scrollable selection-list container at the specified location and size. Use Otk_Add_Selection_Item to add items to the list. If more than rows items are added, a scroll-bar is automatically added to the list. Otk_Add_Selection_Item( selectionlist, text, callback, parameter ) This function adds the specified text string to the referenced selection-list. If selected by the user, the named callback function will be called and the specified parameter will be passed. In actual usage, often, all entries are assigned a common callback function with parameters assigned sequentially to identify the selected item in the callback. Formal definition: void Otk_Add_Selection_Item( OtkWidget selectionlist, char *text, void (*callback)(void *x), void *parameter ) Otk_Coordinate_Selection_Lists( master_list, subordinate_list ) This function links multiple selection lists together, so that all are controlled by a single scroll-bar, and all scroll together. It is a convenient way to create multiple-column scrolling selection lists. This function is to be called after the list widgets have been created with Otk_Make_Selection_List, but before any items have been added to the lists. One list is designated as the master-list, since it will have the scroll-bar. Usually, all lists in a group are created next to each other, at equal height and size. The right-most list is usually designated as the master, since the scroll-bar attaches to the right side, when there are sufficient items in the list. It is assumed that all lists in such a group will always hold an equal number of items. See example application: multiple_selection_lists.c. Formal definition: void Otk_Coordinate_Selection_Lists( OtkWidget master_list, OtkWidget subordinate_list );
Otk_Add_Line( container, color, thickness, x1, y1, x2, y2 ) Often it is useful to add lines or separators to a GUI panel. General purpose lines can be added with the Otk_Add_Line function. Specify the window/container, line color, thickness, and the coordinates to draw the line from (x1,y1) and to (x2,y2). The coordinates are in percentages of the container-window. Boxes can be drawn as a set of four lines. Formal definition: OtkWidget Otk_Add_Line( OtkWidget container, OtkColor color, float thickness, float x1, float y1, float x2, float y2 ) Otk_Add_BoundingBox( container, color, thickness, x1, y1, x2, y2 ) Makes a rectangular separating boundary outline, whose upper left corner is (x1,y1) and lower right corner is (x2,y2). Formal definition: void Otk_Add_BoundingBox( OtkWidget container, OtkColor color, float thickness, float x1, float y1, float x2, float y2 )
OtkMakeWindow( panel_type, tab_color, panel_color, left, top, horiz_size, vert_size ) This function makes a floating sub-window which can be closed by the user. Widgets can then be added to this window, like any other container-window. Formal definition: OtkWidget OtkMakeWindow( int panel_type, OtkColor tab_color, OtkColor panel_color, float left, float top, float horiz_size, float vert_size ) Example: OtkWidget win1; win1 = OtkMakeWindow( Otk_Recessed, Otk_Blue, Otk_LightGray, 10, 10, 70, 80 ); OtkMakeTextLabel( win1, "This a new window.", Otk_Black, 3.0, 1.0, 5, 5 ); OtkSetWindowTitle( window, text_color, title ) This function sets a sub-window's title. It places text in the window title-bar. Formal definition: void OtkSetWindowTitle( OtkWidget window, OtkColor text_color, char *title ) Otk_RegisterWindowKillEventFunction( window, callback, parameter ) This function registers your own function to be called if the user closes the respective window by the X in the window's handle. (Note: Your application does not need to-, and should not attempt to-, remove the window or any of its Otk-objects. The window manager already removes the window, and attempting to remove it again will result in a double-free.) Formal definition: void Otk_RegisterWindowKillEventFunction( OtkWidget window, void (*callback)(void *x), void *parameter )
OtkInitWindow( WinWidth, WinHeight, argc, argv ) This function is one of the most important. It produces the initial outer window, called OtkOuterWindow, You specify the initial size of the window in pixels for width and height. You can pass command-line arguments as argc and argv. It must be called first, before any other Otk calls. OtkInitWindow is intended for stand-alone applications. Formal definition: void OtkInitWindow( int WinWidth, int WinHeight, int argc, char **argv ); OtkMakeOuterWindow() This function is the alternative to OtkInitWindow above, for applications that are part of another OpenGL application which already opened the outer-window. It initializes the Otk global variables and establishes the OtkOuterWindow widget within the existing window. It must be called first, before any other Otk calls. Often used with OtkUpdateCheck(). Formal definition: void OtkMakeOuterWindow() OtkMainLoop() This function is one of the most important. It is the Otk event-loop. It makes everything happen. You need to call this once, usually near the end of your application's main() routine. It does not return until the application exits. The OtkMainLoop routine is an infinite while loop that waits for keyboard or mouse input, then calls appropriate handlers, and then waits for more input. Otk is single-threaded. This function is called last, after the Otk calls which set up the initial window. Formal definition: void OtkMainLoop(); See also OtkUpdateCheck(). OtkMainLoop is equivalent to a while(1) loop around OtkUpdateCheck(). Otk_Set_Window_Name( name ) This function sets the outer-window's name in the window's title-bar. It must be called before calling: OtkInitWindow. Formal definition: void Otk_Set_Window_Name( char *name )

Additional / Special-Purpose Functions


Compiling Otk Applications

See: Compiling Otk Applications


Automated Testing of Otk Applications

OTK supports automatic GUI-testing with an ability to capture keyboard and mouse input into a test-stimulus file. The stimulus file can then be applied in future regression tests, as if you were manually operating the GUI. See: Automated Testing of Otk Applications


Downloading Otk

Download:
      otk_lib_0.96.tgz   February 17, 2014   (96-kB)
Or,
      otk_lib_0.96.zip   February 17, 2014   (96-kB)

Version History, and Release Notes

Optional External Font Reader
      SVG Font Reader

Testing Packages
      otk_Tests_1.0.tgz   Mar 23, 2006   (6-kB)
Or,
      otk_Tests_1.0.zip   Mar 23, 2006   (6-kB)

The test package contains a set of examples with scripts to sequentially compile and run them. Handy for regression testing. Download and Unpack the otk_lib under this package directory. (Or symbolic link to otk_lib. The programs will expect to find otk_lib in the directory.)

Simple GUI-Builder for Otk.

User submitted Python bindings to Otk.


 

SourceForge.net Logo