KRESLITKO Online Documentation

Contents:

What is KRESLITKO?

#include <kreslitko.h>
...
int  main ( void )
{
    kreslitko K ;
    K.open_graphics( ... ) ;
    K.line( 0.1,0.1,0.9,0.9 ) ;
    K.line( 0.1,0.9,0.9,0.1 ) ;
    ...
}

You can now do anything you want with this window, for example resize it - and it will resize itself correctly.
The whole code of this first example is included as 'example1.c'.

Note: KRESLITKO has a face of a C++ class; I decided to do it this way, because it is the most easy and most 'pleasant' way if you want to have more than one opened window. You simply create two or more instances of class kreslitko.

(Please, let me know if you started to use KRESLITKO for some purpose.)

Features:

• draw graphic items (lines,circles,arcs,rectangles,crosses,arrows)
• draw texts
• draw horizontal and vertical scales (rulers)
• draw marks (like crosses, rectangles, triangles)
• delete one or more drawn items
• hide and unhide one or more drawn items
• perform cached drawing
• be mouse sensitive
• create buttons that can send signals back to your application
• create text entries that your application will be able to gather values from them
• create status bar and write sentences to it
• set window caption
• resize the window and recompute all items to fill the new window
• count number of items
• draw with different colors
• set background color
• draw text with different fonts and sizes
• save drawn image as xpm,png and PostScript

Screenshots:

Here you can see the rich configuration of KRESLITKO: some lines of different colors in the viewport, the mouse 'cursor', one text entry widget and two buttons.
More screenshots will come later, when me or other people will create some nice pictures with it. (Please, if you are using KRESLITKO and you have some nice example, send it to me and I will paste it to this document.)

This is a simple usage of KRESLITKO: to draw a graph of some function. See example4.c for the source code how to create that picture.

Trial application 'grafeek' that is included in KRESLITKO distribution. See some documentation.

Using class (library) 'k3d' it is possible to generate 3d-pictures. See documentation of k3d.

3d function graph generated also using class (library) 'k3d'.

3d function graph of so called FSWE-Type 1 function (by Navarro) - also using 'k3d'.

Download:

How to install KRESLITKO:

Than, you can follow these steps:

1. You have archive kreslitko-xxxx.tgz. Unpack it using 'tar xzvf kreslitko-xxxx.tgz' in some directory like /usr/local/src/kreslitko.

2. Check if you have system variable QTDIR properly set. (You don't know how to do it? Try 'set | grep QTDIR'. If this command prints something on the screen, it is probably OK.) If you don't have this, you can:

• set this variable: you need to know, where Qt is (type 'locate libqt.so' and you get several lines such as '/usr/lib/qt-2.0.1/lib/libqt.so.2'; in this case, our desired path is '/usr/lib/qt-2.0.1'; so you can immediately type: 'export QTDIR=/usr/lib/qt-2.0.1'; remember that if the number after qt is not 2 but 1, it won't work - you must install newer version of Qt
• or you can modify my makefile: seek for line 'QTDIR=/usr/lib/qt2' and edit it properly (and uncomment it, of course)

           uncomment these 2 lines in makefile if you do have library libpng installed:
                     # HAVE_LIB_PNG = -D__HAVE_PNG__
                     # LD_LIB_PNG = -lpng

           uncomment these 2 lines in makefile if you do have library libgd-1.8.3 or newer installed:
                     # HAVE_LIB_GD = -D__HAVE_GD_183__
                     # LD_LIB_GD = -lgd -ljpeg

4. Go into KRESLITKO's directory and type 'make'. It creates both the shared library and the server.

5. Become root and type 'make install'. It installs files into their destinations. Maybe you disagree with my destination directories - than look at my 'makefile' and edit lines:  'INSTDIR_INCLUDE=...', 'INSTDIR_LIB=...' and 'INSTDIR_BIN=...'. I am sorry, but if you decide to change the 'INSTDIR_BIN' you must also edit the line '#define server "/usr/local/bin/kreslitko"' and recompile library. Well, I know that I should make this thing more friendly - I will do it in the next version.

6. If you don't like KRESLITKO, you can uninstall it by typing 'make uninstall' as root.

How to use KRESLITKO in your application:

    #include <kreslitko.h>

Kreslitko in your application lives as a C++ class, you must declare it somewhere before you use it for the first time:

     kreslitko K ;

Before drawing anything, you must open the graphic viewport - but if you want to create some buttons, text entries or status bar, you must do it now. So, for example:

    K.create_button( "Button1",1 ) ;
    K.create_button( "Button2",2 ) ;
    K.create_text_entry( 3,"What?" ) ;
    K.create_status_bar() ;

This means that you will have button with label 'Button1' and this button will send signal '1' each time it is pressed (how to gain this signal I will discuss later) and also button with label 'Button2' that will return signal '2'. Then you create text entry with label 'What?' and its value you will be able to access using id number '3'. And status bar, finally - it can be only one and so it has not any id number.
Well, if you want simply to draw, you dont't have to do such a thing and you can go straigh to next step - opening the graphic viewport.

    K.open_graphics( 0.0,0.0,1.0,1.0,300,300,0.1 ) ;

This call open graphic viewport. It has virtual size and real size. Real size is 300x300 pixels and virtual size is (0.0-1.0)x(0.0-1.0). You will draw all items using the virtual coordinates and KRESLITKO itself will recompute them into real coordinates. Note: real size is initial size of window and it also works as minimum size of the viewport. Last parameter is optional and means an oversize of the window (0.1 means that real size will be from -0.1 to 1.1 in both dimensions).

Now you can draw whatever you want. So, for example:

    K.line( 0.1,0.1,0.9,0.9 ) ;
    K.circle( 0.5,0.5,0.2 ) ;

and so on. Please look beside to function reference for all drawing functions. Note: Start point of coordinate system (0.0,0.0) is in the left bottom like on the paper.
Items you draw can have their id numbers. So you can for example call this:

    K.line( 0.1,0.9,0.9,0.1,301 ) ;

It creates a line with id number 301. Using these id numbers you can later delete, hide or redraw these items (see function reference). More than one item may have the same id number - in that case you will be able to delete, hide or redraw all items with the same id by one function call. Drawing texts you can this way:

    K.text( 0.2,0.2,"Hello world!",0 ) ;

It places text 'Hello world!' into virtual coordinates 0.2,0.2 and will use font number 0 - in KRESLITKO fonts have their own numbers and you assign fonts to these number using function assign_font (see function reference). Also texts can have theis id numbers - send it to function text as last (optional) parameter.
Sometimes you draw many many items one time and you don't need to see them appearing on the viewport one after one. This case you can use cached drawing. Open a cache using:

    K.begin_serial() ;

Than draw whatever you want and than close cache using:

    K.flush_serial() ;

KRESLITKO is able to be mouse sensitive (but in this version it is only a cosmetic property). Toggle it on using:

    K.mouse_sensitive( 1 ) ;

Function mouse_tracking toggles also writing virtual coordinates into top left angle of the viewport.
All items are drawn with so called 'actual' color. This color can be changed with function set_color. Colors have their numbers and you can assign a color (specified by red, green and blue values) using function assign_rgb_color. Background color can be specified using set_background_color (and it takes red, green and blue values). You may have maximum of a 128 colors on a viewport one time. Note: background color is 0, so if you assign some values to color 0, it is the same as if you set background color. System uses color 1 for mouse cursor and so on.
Picture drawn by your application can be saved as xpm (using save_as_xpm) or as png (using save_as_png) or exported (black-and-white version) to PostScript (using export_as_ps).

Buttons can be used par example for controling run of your process. They return signals which are given in function create_button and you can scan if they have come using functions:

        int wait_for_signal ( int osignal ) ;
        int peek_for_signal ( int osignal ) ;
        int receive_signal ( int &osignal ) ;
        int wait_and_receive_signal ( int &osignal ) ;

For detailed description see beside my NTE (Non-Trivial Example).

If you need a scale (a ruler) you can draw it on the screen using functions x_scale and y_scale. See function reference. Note, that scale itself will be drawn using actual color (by set_color), but text using actual text color (by set_text_color).

Compiling your application does not need any special switches. Linking requires '-lkreslitko'. Example 'example1.c' can be made by this:

    g++ -o example1 example1.c -lkreslitko

Function Reference:

• Constructor, destructor
• Creating buttons, text entries, status bar
• Opening graphic viewport, resizing, setting window caption
• Drawing items
• Drawing rastered items
• Drawing text items
• Drawing marks
• Deleting, hiding and redrawing items
• Managing fonts
• Cached drawing
• Being mouse sensitive
• Setting colors and pen thickness
• Saving and exporting picture
• Signals, values from text entries, printing to status bar
• How many items
• Drawing scales(rules)
• Display png and xpm images

 

Constructor, destructor:

                constructor; it runs server and opens a message queue

    kreslitko::~kreslitko ( void ) ;

                destructor; it stops server and deletes the message queue
 
 

Creating buttons, text entries, status bar:

                creates signal button with title 'oname' that will send signal 'osignal'

    int kreslitko::create_text_entry ( int oid , char *oname ) ;

                creates text entry with label 'oname'; values from it can be obtained through id number 'oid'; 'oid' is also a signal that will be sent by KRESLITKO if return is pressed over this entry

    int kreslitko::create_status_bar ( void ) ;

                creates status bar
 

Opening graphic viewport, resizing, setting window caption:

                opens graphics viewport vith virtual coordinates (ox1-ox2)x(oy1-oy2) and real coordinates (0-owidth)x(0-oheight); zero of coordinate system is in the left bottom; last parameter is optional and means an oversize of window (space around virtual viewport that is also displayed)

    int kreslitko::set_caption ( char *oname ) ;

                sets caption of kreslitko's screen to 'oname'

    int kreslitko::resize_viewport ( int owidth , int oheight ) ;

                resizes viewport size to (0-owidth)x(0-oheight)
 

Drawing items:

                draws pixel into coordinates (ox1,oy1); if you send last parameter, pixel will have id number 'oid'

    int kreslitko::line ( double ox1 , double oy1 , double ox2 , double oy2 , int oid=-1 ) ;

                draws line from point (ox1,oy1) to point (ox2,oy2) ; if you send last parameter, line will have id number 'oid'

    int kreslitko::circle ( double ox1 , double oy1 , double or , int oid=-1 ) ;

                draws circle with center (ox1,oy1) and radius 'or' ; if you send last parameter, circle will have id number 'oid'

    int kreslitko::cross ( double ox1 , double oy1 , double ow , int oid=-1 ) ;

                draws cross with center (ox1,oy1) and size 'ow' ; if you send last parameter, cross will have id number 'oid'

    int kreslitko::arc ( double ox1 , double oy1 , double or , double osa , double oea , int oid=-1 ) ;

                draws arc with center (ox1,oy1), radius 'or', start angle 'osa' and end angle 'oea' (angles are in degrees); if you send last parameter, arc will have id number 'oid'

    int kreslitko::ellipse ( double ox1 , double oy1 , double or1 , double or2 , int oid=-1 ) ;

                draws ellipse with center (ox1,oy1), radius 'or1' in x-direction and 'or2' in y-direction; if you send last parameter, arc will have id number 'oid'

    int kreslitko::rectangle ( double ox1 , double oy1 , double ow , double oh , int oid=-1 ) ;

                draws rectangle with one corner in (ox1,oy1) with width ow and height oh; if you send last parameter, rectangle will have id number 'oid'

    int kreslitko::arrow ( double ox1 , double oy1 , double oangle , double olen , int oid=-1 ) ;

                draws arrow from coordinates (ox1,oy1) points into direction given by 'oangle' and length 'olen' ; if you send last parameter, pixel will have id number 'oid'
 
 

Drawing rastered items:

         Note:  all rastered objects have parameter odensity that can be of value from 0.0 to 1.0 and represents how density of the raster.

    int kreslitko::rastered_rectangle ( double ox1 , double oy1 , double ow , double oh , double odensity , int oid=-1 ) ;

        the same thing as kreslitko::rectangle, but rastered

    int kreslitko::rastered_circle ( double ox1 , double oy1 , double or , double odensity , int oid=-1 ) ;

        the same thing as kreslitko::circle, but rastered

    int kreslitko::rastered_ellipse ( double ox1 , double oy1 , double or1 , double or2 , double odensity , int oid=-1 ) ;

        the same thing as kreslitko::ellipse, but rastered

    int kreslitko::rastered_chord ( double ox1 , double oy1 , double or , double osa , double oea , double odensity , int oid=-1 ) ;

        draws a chord; parameters are the same as for the kreslitko::are

    int kreslitko::rastered_pie ( double ox1 , double oy1 , double or , double osa , double oea , double odensity , int oid=-1 ) ;

        draws a pie; parameters are the same as for the kreslitko::pie

    int kreslitko::rastered_polygon ( double *ox , double *oy , int on , double odensity , int oid=-1 ) ;

        draws rastered polygon that has on nodes and their coordinates are stored in arrays ox and oy
 

Drawing text items:

                draws text 'otext' with left bottom (ox,oy) using font number 'ofont' ; if you send last parameter, pixel will have id number 'oid'

    int kreslitko::set_fp_format ( char *oformat ) ;

                sets format of floating point numbers - the same manner as using for example printf (so use something like "%10.10E " as 'oformat' )
 
 

Drawing marks:

                draws mark of type otype at a position on (ox,oy) with size osize given in pixels; marks types are given in the picture bellow (and see example11.c)

    int kreslitko::mark_percentual ( double ox , double oy , int otype , int osize , int oid=-1 ) ;

                draws mark of type otype at a position on (ox,oy) with size osize given in percents of a window size; marks types are given in the picture bellow (and see example11.c)
 

Deleting, hiding and redrawing items:

                redraws all items

    int kreslitko::redraw_items ( int oid ) ;

                redraws only items that have id number 'oid'

    int kreslitko::redraw_area ( double ox1 , double oy1 , double ox2 , double oy2 ) ;

                redraws area defined by rectangle given by coordinates ('ox1','oy1') and ('ox2','oy2')

    int kreslitko::delete_item ( int oid ) ;

                deletes one (first found) item with id number 'oid'

    int kreslitko::delete_items ( int oid ) ;

                deletes all items that have id number 'oid'

    int kreslitko::hide_items ( int oid ) ;

                hides items that have id number 'oid'; hidden items are not displayed until redraw with the same id number is called

Managing fonts:

                font number 'ofont' will be assigned with font of type 'otype' (use "Times","Courier","Palatino" etc.), size 'osize' - in points and if 'obold' is non-zero, font will be bold
 

Cached drawing:

                starts cached drawing; from the calling of this function everything will be drawn into cache and not to viewport

    int kreslitko::flush_serial ( void ) ;

                flushes cache into viewport (the same can be performed by resizing, moving or hiding and unhiding window all by calling redraw)
 

Being mouse sensitive:

                toggles kreslitko to being mouse sensitive (it will take mouse cursor and draw coordinate cross over all viewport); if 'onenabled' is non-zero, mouse sensitivity will be enabled

    int kreslitko::mouse_tracking ( int oenabled ) ;

                toggles on of off writing mouse coordinates into top left of viewport
 

Setting colors and pen thickness:

                sets background color to values given by (ored,ogreen,oblue)

    int kreslitko::assign_rgb_color ( int ocolor , int ored , int ogreen , int oblue ) ;

                assigns color given (ored,ogreen,oblue) to color number 'ocolor'

    int kreslitko::set_color ( int ocolor ) ;

                sets actual color to color number 'ocolor' which has previously assigned RGB values by assign_rgb_color; this color affects only non-text items

    int kreslitko::set_text_color ( int ocolor ) ;

                sets actual text color to color number 'ocolor' which has previously assigned RGB values by assign_rgb_color; this color affects only text items

    int kreslitko::set_pen_width ( int owidth ) ;

                sets actual pen_width ( in pixels )
 

Saving and exporting picture:

                saves drawn picture in resolution given by real size of viewport in format PNG into file 'ofname'; must have library libpng installed

    int kreslitko::save_as_xpm ( char *ofname ) ;

                saves drawn picture in resolution given by real size of viewport in format XPM into file 'ofname'; must have library libXpm installed

    int kreslitko::save_as_jpg ( char *ofname ) ;

                saves drawn picture in resolution given by real size of viewport in format JPG into file 'ofname'; must have libraries libjpeg and libgd-1.8.3 or newer installed

    int kreslitko::export_as_ps ( char *ofname , double oxcm , double oycm , int oorient=1 ) ;

                exports draws picture as PostScript into file 'ofname'; picture will have size (oxcm,oycm) and orientation given by 'oorient' (1 is portrait, 0 is landscape)
 

Signals, values from text entries, printing to status bar:

                waits until some button sends signal given by 'osignal'; other signals are ignored

    int kreslitko::peek_for_signal ( int osignal ) ;

                looks if some button have already send signal given by 'osignal'; other signals are ignored

    int kreslitko::receive_signal ( int &osignal ) ;

                looks if any button have sent a signal and if finds any, stores it into 'osignal'

    int kreslitko::wait_and_receive_signal ( int &osignal ) ;

                waits until any button sends any signal and then stores it into 'osignal'

    int kreslitko::text_entry_set_value ( int oid , int ovalue ) ;

                sets value of text entry with id number 'oid' to integer value 'ovalue'

    int kreslitko::text_entry_set_value ( int oid , double ovalue ) ;

                sets value of text entry with id number 'oid' to double value 'ovalue'

    int kreslitko::text_entry_set_value ( int oid , char *ovalue ) ;

                sets value of text entry with id number 'oid' to string value 'ovalue'

    int kreslitko::text_entry_get_value ( int oid , int &ovalue ) ;

                grabs value from text entry with id number 'oid' to 'ovalue' as integer

    int kreslitko::text_entry_get_value ( int oid , double &ovalue ) ;

                grabs value from text entry with id number 'oid' to 'ovalue' as double

    int kreslitko::text_entry_get_value ( int oid , char *ovalue ) ;

                grabs value from text entry with id number 'oid' to 'ovalue' as string

    int kreslitko::print_to_status_bar ( char *otext ) ;

                prints a sentence in 'otext' into status bar
 

How many items:

                grabs number of items drawn to kreslitko and stores it into 'onumber'; it includes also hidden items

    int kreslitko::display_number_of_items ( int oenable ) ;

                toggles if number of items will or will not be displayed into top right of viewport
 

Drawing scales(rules):

                draws horizontal scale in height 'oy' from x-coordinate 'ox1' to x-coordinate 'ox2' with division 'odiv'; text will be drawn using font 'ofont'

    int kreslitko::y_scale ( double ox , double oy1 , double oy2 , int ofont , int odiv , int oid=-1 ) ;

                draws vertical scale in width 'ox' from y-coordinate 'oy1' to y-coordinate 'oy2' with division 'odiv'; tex will be drawn using font 'ofont'
 

Displaying png and xpm images:

                loads a picture in png format from file ofname and stores it under an id number oid; using this id number picture may be recalled for displaying

    int kreslitko::load_picture_as_xpm ( int oid , char *ofname ) ;

                loads a picture in xpm format from file ofname and stores it under an id number oid; using this id number picture may be recalled for displaying

    int kreslitko::picture ( int opic_id , double ox , double oy , int oid=-1 ) ;

                displays picture that has been loaded previously with id number opic_id at coordinates (ox,oy); last parameter oid has the same meaning as for all other items (lines,circles etc.)

NTE (Non-Trivial Example):

#include <kreslitko.h>
#include <stdio.h>
#include <string.h>

#define SignalNext 1
#define SignalEnd 2

int main ( int oargc , char *oargv[] )
{
    // opening input file

    if ( oargc!=2 )
    {
        printf( "usage: example3 <filename>\n" ) ;
        exit( 0 ) ;
    }
    FILE *f ;
    f=fopen( oargv[1],"rt" ) ;
    if ( !f )
    {
        printf( "cannot open file %s\n",oargv[1] ) ;
        exit( 0 ) ;
    }

    // create kreslitko instance

    kreslitko K ;

    // create signal button that sends signal 'SignalNext'

    K.create_button( "Next",SignalNext ) ;

    // create signal button that sends signal 'SignalEnd'

    K.create_button( "End",SignalEnd ) ;

    // opening graphics viewport

    K.open_graphics( 0.0,0.0,1.0,1.0,300,300 ) ;

    int j ;

    // each line is in format:
    // some_command (like 'line' or 'circle') coordinates
    // first we will read command into string cmd, check what command it is and then read appropriate coordinates and draw appropriate item

    char cmd[32] ;
    double x1,x2,y1,y2,r ;

    while ( !feof( f ))
    {
        j=fscanf( f,"%s",&cmd ) ;
        if ( j!=-1 )
        {
            if ( !strcmp( cmd,"line" ))
            {
                fscanf( f,"%lf",&x1 ) ;
           fscanf( f,"%lf",&y1 ) ;
           fscanf( f,"%lf",&x2 ) ;
           fscanf( f,"%lf",&y2 ) ;
                K.line( x1,y1,x2,y2 ) ;
            }
            else
                if ( !strcmp( cmd,"circle" ))
                {
           fscanf( f,"%lf",&x1 ) ;
           fscanf( f,"%lf",&y1 ) ;
           fscanf( f,"%lf",&r ) ;
                    K.circle( x1,y1,r ) ;
                }
                else
                    if ( !strcmp( cmd,"cross" ))
                    {
           fscanf( f,"%lf",&x1 ) ;
           fscanf( f,"%lf",&y1 ) ;
           fscanf( f,"%lf",&r ) ;
                        K.cross( x1,y1,r ) ;
                    }
                    else
                        if ( !strcmp( cmd,"rectangle" ))
                        {
                            fscanf( f,"%lf",&x1 ) ;
                            fscanf( f,"%lf",&y1 ) ;
                            fscanf( f,"%lf",&x2 ) ;
                            fscanf( f,"%lf",&y2 ) ;
                            K.rectangle( x1,y1,x2,y2 ) ;
                        }
        }

        // here we are waiting for the user to press some button
        // the signal will be stored in variable 'j'

        K.wait_and_receive_signal( j ) ;

        // if received signal is 'SignalEnd' we won't continue

        if ( j==SignalEnd ) goto END ;

        // the only other signal can be 'SignalNext' so it is not necessary to check it
    }

END:
    fclose( f ) ;

    // no closing function - we have a destructor

}

Trial application 'grafeek'

What was new in...