STK Simple ToolKit - documentation

STK v2.0 documentation

(2006-03-28)
by Dusan Halicky
dvh.tosomja@post.sk

Index

1. Introduction

1.1 About STK
1.2 Requirements
1.3 Compilation
1.4 Compatibility
1.5 Author

2. Components

2.1 StkComponent
2.2 StkWindow
2.3 StkLabel
2.4 StkButton
2.5 StkRadiobutton
2.6 StkCheckbox
2.7 StkImage
2.8 StkSlider
2.9 StkShortcut
2.10 StkMenuitem
2.11 StkEdit
2.12 StkPanel

3. Other parts

3.1 Constants
3.2 Functions
3.3 Display
3.4 Keyboard
3.5 Mouse
3.6 Fonts
3.7 Colors
3.8 Initialization
3.9 Bitmaps
3.10 Graphics
3.11 Callbacks
3.12 Components

4. Examples

4.1 Hello world

5. Appendix

5.1 Table of component's constructors

1. Introduction

This is main and official documentation of the STK project. All materials related to the STK included this documentation is free and open. You can redistrubute it. STK is distributed under GNU GPL licence (see file doc/COPYING for more details).

Terms and abbreviations:

STK - Simple ToolKit, version v2.0 (when not mentioned version)
toolkit - set of components such as label, button and rest of the application framework
X - X Window System

1.1 About STK

STK is a shortcut for Simple ToolKit. It is a very simple, light and fast toolkit written in C/C++ language for X Window System. STK is based on the the Xlib, the basic X library. STK contain few basic components such as label, button, checkbox and so on.

Main aims of STK are:

To be a C/C++ toolkit for X Window System under Linux
To be small and easy to understand
To be simple for using in programs for programmers
To be ergonomic for users
To be fast and light and not fritt with system resources
To be well documented
Not to be forwad nor backward compatible at any costs

1.2 Requirements

X Window System
Xlib library (X.h, Xlib.h, Xutil.h, keysymdef.h)
xpm library or Imlib library
GNU C Compiler (with c++ support)

1.3 Compilation

Currently, STK is distributed in a single tarball which contain directory "stksrc" which contain STK itself. There is shell script named "_make_libstk". Run it anytime you want to create static STK library "libstk.a". Then, when you compilig your project, whereever it is placed, you will need to tell compiler where to search for the stk library (assume that there is yourapp directory with yourapplication.cc and stksrc directory).

If you want to use Imlib (PNG, JPEG, GIF, XPM) insted of libxpm (XPM), you must define the STK_IMLIB_USED directive in the stk_constants.h this way:

#define STK_IMLIB_USED

STK application compilation example:

gcc -o yourapplication yourapplication.cc -L./stksrc/ -lstk -lXpm -lXext -lImlib

where:

-L./stksrc/ - path to STK (whole stksrc directory)
-lstk - tell compiler to include STK library /stksrc/libstk.a

Note: Running "./stksrc/_make_libstk" before compilation of your application is highly recomended.

1.4 Compatibility

STK was tested successfully on this platforms:

Fedora Core 4, kernel 2.6.11, gcc 4.0.0, bash 3.0.0, X Window System v6.8.2 (X11R6)
RedHat 7.2, kernel 2.4.7, gcc 2.96, X Window System v??? (X11R6)
SuSE linux, kernel 2.4.x, gcc 3.x, (only compiled)
Gentoo linux (compiled but no display images!)

1.5 Author

Original author of STK and this documentation is me, Dusan Halicky (dvh.tosomja@post.sk). Feel free to contact me via email if you have any question about STK or if you have any suggestion or ide how to improve STK, or if you want to participate on STK development. Contact me also if you find a bug in the STK. Finaly, if you have lots of money and you want to sponsor future development of STK send any small financial contribution. Thanks.

Dusan Halicky jr.
Wuppertalska 41
04023 Kosice
Slovakia

2. Components

Every single visual or invisible component in STK is inherited from basic stk component called StkComponent. It contain most basic attributes and methods which use all components. Every real component has theese attributes and methods inderited from StkComponent and has also other methods and attributes related only to that real component.

2.1 StkComponent

Description

StkComponent is basic component, it is ancestor of all components.

Constructor

StkComponent (Window parwin, int x, int y, int w, int h, int borderwidth, int bordercolor, int bgcolor, unsigned int eventmask);

Where:

parwin - parent component's window
x, y - position of the window in pixels from top-left corner of the parent component's window (parwin)
w, h - size of the component, must be nonzero
borderwidth - width of the component border in pixels, additive to (w,h), may be 0
bordercolor - index of color for the border in local palette
bgcolor - index of the window's color in local palette
eventmask - event mask for the window, may be logically or-ed by one or more of the following:

KeyPressMask, KeyReleaseMask - if you want to catch key press/release event
ButtonPressMask, ButtonReleaseMask - mouse button press/release event
PointerMotionMask - movement of the mouse cursor above component
ExposureMask - when covered component (by other window) is exposed and need redraw
EnterWindowMask, LeaveWindowMask - when mouse pointer move over component first time or if pointer leave window
StructureNotifyMask, SubstructureNotifyMask, PropertyChangeMask, FocuseChangeMask - recomended, internally required for some configuration events

Interface

type	attribute	Get	Set	Description
Window	window	GetWindow()	-	ID of the window, an rectangle described component, used for drawing and handling all events
GC	gc	GetGC()	-	ID of window's graphics context, used for drawings on component's window
StkComponent*	previous	GetPrevious()	SetPrevious(StkComponent *p)	previous component in the bidirectional linked list of components
StkComponent*	next	GetNext()	SetNext(StkComponent *p)	next component in the bidirectional linked list of components
int	left, top	GetPosition(int x,y) GetLeft(),GetTop()	SetPosition(int x,y)	position from left-top corner of parent component (window)
int	width, height	GetSize(int w,h) GetWidth(),GetHeight()	SetSize(int w,h)	size of component
int	border_width	-	-	border thicknes in pixels, 0 for no border
int	border_color	-	-	color indexes of component's border
int	background_color	GetColor()	SetColor(int)	color indexes of component's window
int	event_mask, event_mask_old	-	-	event mask for window, event_mask_old is for remember original mask when component is disabled but not removed from components list
bool	focus	GetFocus()	SetFocus(bool f)	Get or set focus to the component, component which has focus lost it and focus will be passed to this component, both component will be redrawn, only component which has focus can receiving keyboard events
bool	focusable	GetFocusable()	SetFocusable(bool fa)	true if component can get focus (e.g. button), false otherwise (e.g. label)
KeySym	shortcut	GetShortcut()	SetShortcut(KeySym s)	shortcut key for the component, keysyms are defined in keysymdef.h
unsigned int	modifiers	GetModifiers()	SetModifiers(uint m)	modifier keys such as CTRL, ALT, ... see constants
bool	visible	GetVisible()	Show(),Hide()	true if component is visible on the screen, components are usually automatically displayed after creation
bool	resizeable	GetResizeable()	SetResizeable(bool r)	true if component can be resized, most important for windows
int	penfgcolor	-	SetPenForeground(int i)	color for the line drawing on the component's window
bool	enabled	GetEnabled()	SetEnabled(bool b)	true if component is enabled (e.g. button can be pressed)
StkBasicCallback*	callback	-	CreateCallback(StkBasicCallback* bcb)	component's callback function, pointer to function which will be called after component is activated (e.g. button is pressed)
int	tag	-	SetTag(int i)	User-purpose ineger variable called "tag"

Events

Event	Attributes	Description
OnExpose	-	when component need to be redrawn
OnChangeFocus	bool f	when component get (f=true) or lost (f=false) focus, automatical redraw is NOT provided
OnMouseDown	int x, int y, int button, int state	when user click with mouse onto component at position (x,y) using mouse button button which has state state
OnMouseUp		when user release mouse button above component
OnMouseMove		when user move with mouse cursor above component
OnMouseOver		whenever user first time move the cursor above component
OnMouseOut		whenever user left the component with mouse cursor
OnKeyPress	KeySym keysym, unsigned int mods, char name, int namesize, bool change_focus	when user press keyboard key if component has a focus
OnKeyRelease	KeySym keysym, unsigned int mods, char name, int namesize, bool change_focus	when user release key if component has focus
OnShortcut	KeySym keysym, unsigned int mods, char *name, int namesize	when user press shortcut key specified to this component, no matter if component has or has not focus
OnClose	-	when component is closed (no longer active), it is most important for windows
OnShow	-	when component is shown first time
OnHide	-	when component is hidden
OnResize	int w, int h	when component is resized, (w,h) is new size, most important for windows

Notes:

not all real components use all these events!
change_focus in OnKeyPress/OnKeyRelease indicate if the currently pressed/release key will change focus. Variable change_focus CAN BE modified inside OnKeyPress/OnKeyRelease event. Some components (e.g. memo) may want to block focus change on som keys (e.g. TAB in memo will be used like normal TAB but not for focus changing)

Methods

Method	Attributes	Description
Create	Window parwin, int x, int y, int w, int h, int borderwidth, int bordercolor, int bgcolor, unsigned int eventmask	auxiliary method, contain most commom part of constructor for components which is often called (create window, set up event mask), attributes is the same as StkComponent's constructor
Redraw	-	this draw component on the screen (lines, strings, ...), it usually call one or more methods from shapes.
DrawLine	int x1,y2,x2,y2	draw line on the component's window with selected pen color
bool IsFocusable	-	return true if component has focusable=true and component is enabled (disabled component can't be focused)
CallBack	Object*,&Type::Method	Create callback for Object->Method, e.g. button1->CallBack(dialog1,&TMyDialog::Close);

2.2 StkWindow

Description

StkWindow is descendant of StkComponent but has special position in a set of components because it may contain other components. Every other real component has StkWindow as parent in their own constructor!

Constructor

StkWindow (Window parwin, int x, int y, int w, int h, const char *cap);

Where:

parwin - parent component's window
x, y, w, h - position and size of the window in pixels from top-left corner of parent window (parwin)
*cap - caption, string which will be displayed at the top of window and in the taskbar icon

Interface

type	attribute	Get	Set	Description
char*	caption	-	SetCaption(const char *cap)	set the window's caption, memory will be reallocated automaticaly
bool	closed	GetClosed()	Close()	true if component was closed by Close() or by user (hit [X] button on the window's top rail)
StkComponents*	components	-	-	interface to bidirectional linked list of components in this window, see components

Events

OnExpose, OnChangeFocus, OnMouseDown, OnMouseUp, OnMouseMove, OnMouseOver, OnMouseOut, OnKeyPress, OnKeyRelease, OnShortcut, OnClose, OnShow, OnHide, (OnResize) ... see StkComponent for details

Methods

Method	Attributes	Description
Minimize	-	minimize the window to the taskbar (depend on window manager implementation)

2.3 StkLabel

Description

StkLabel is most basic visual component. It provide only simple plain text in one line, but it will be automatically redrawn when required so programer must not take care of redrawing. It also may have associated shortcut key. Because label is no focusable component, it will forward focus to another component specified in focus_control attribute. Label can be also clicked by mouse.

Constructor

StkLabel (StkWindow *parwin, int x, y, w, h, char *cap, StkComponent *focuscontrol=NULL);

Where:

parwin - parent component's window (StkWindow)
x, y, w, h - position and size of component
*cap - caption of component, string, will be displayed as simple text, may be encoded by & to set up shortcut key (e.g. "H&ello" will set shortcut to "a" with ALT modifier - Alt+a, "&Hello" will set shortkut to Alt+h but NOT Alt+H)
focuscontrol - another (but focusable) component which will receive focus when user call label's shortcut or click onto label, this paremeter may be omitted

Interface

type	attribute	Get	Set	Description
char*	caption	-	SetCaption(char *cap, bool redraw=true)	- set the label's caption and automatically redraw it when it is changed

Events

OnExpose, OnMouseDown, OnMouseUp, OnMouseMove, OnMouseOver, OnMouseOut, OnShortcut, OnClose ... see StkComponent for details

Methods

Method	Attributes	Description
Redraw	-	redraw the label

2.4 StkButton

Description

StkButton is a basic clickable component. It seems like rectangular area with the label inside. User can click on it with a mouse cursor or take a focus to it with TAB or Ctrl+TAB key. If button has a focus, it may be pressed by Enter or Spacebar key. If button is disabled, it can NOT be pressed nor focused. When button is pressed, a callback is called. Button can also has "&" encoded label.

Constructor

StkButton (StkWindow *parwin, int x, int y, int w, int h, char *cap);

Where:

parwin - parent component's window (StkWindow)
x, y, w, h - position and size of component
*cap - caption of component, string, will be displayed as simple text, may be encoded by & to set up shortcut key (e.g. "H&ello" will set shortcut to "a" with ALT modifier - Alt+a, "&Hello" will set shortkut to Alt+h but NOT Alt+H)

Interface

type	attribute	Get	Set	Description
char*	caption	-	SetCaption(char *cap)	Sets the button's caption
bool	pressed	-	-	true if button is pressed (down)
int	underscore_start	-	-	position if the underscore ("&" encoded label)
int	underscore_length	-	-	length of the underscore

Events

OnExpose, OnChangeFocus, OnMouseDown, OnMouseUp, OnMouseMove, OnMouseOver, OnMouseOut, OnKeyPress, OnKeyRelease, OnShortcut, OnClose, OnShow, OnHide ... see StkComponent for details

Methods

Method	Attributes	Description
Redraw	-	draw the button on the screen

2.5 StkRadiobutton

Description

StkRadiobutton is component which seems like label but has small rectangle area in front of it. There is small picture indicated where radiobutton is checked or not. Label can be encoded, radiobutton can be disabled. Radiobutton is focusable component, it's state can be changed with enter or spacebar when radiobutton has focus.

Constructor

StkRadiobutton (StkWindow *parwin, int x, y, w, h, char *cap, int grp = 0, bool chckd = false);

Where:

parwin - parent component's window (StkWindow)
x, y, w, h - position and size of component
*cap - caption of component, string, will be displayed as simple text, may be encoded by & to set up shortcut key (e.g. "H&ello" will set shortcut to "a" with ALT modifier - Alt+a, "&Hello" will set shortkut to Alt+h but NOT Alt+H)
grp - group index, few radiobuttons can be grouped into groups, only one radiobutton can be checked in the group
chckd - true if radiobutton is checked

Interface

type	attribute	Get	Set	Description
bool	checked	GetChecked()	SetChecked()	get the state of checked attribute or set checked attribute to true, radiobutton cannot be unchecked!
int	group	GetGroup()	-	only one radiobutton in a set of radiobuttons with the same group can be checked

Events

OnChangeFocus, OnMouseDown, OnKeyPress, OnShortcut ... see StkComponent for details

Methods

Method	Attributes	Description
Redraw	-	draw the component on the screen

Inherited

StkRadiobutton is descendant of StkLabel.

2.6 StkCheckbox

Description

StkCheckbox is similar to StkRadiobutton but any checkbox can be checked at any time, because checkboxes are not divided into groups.

Constructor

StkCheckbox (StkWindow *parwin, int x, y, w, h, char *cap, bool chckd=false);

Where:

parwin - parent component's window (StkWindow)
x, y, w, h - position and size of component
*cap - caption of component, string, will be displayed as simple text, may be encoded by & to set up shortcut key (e.g. "H&ello" will set shortcut to "a" with ALT modifier - Alt+a, "&Hello" will set shortkut to Alt+h but NOT Alt+H)
chckd - true if checkbox is checked

Interface

type	attribute	Get	Set	Description
bool	checked	GetChecked()	SetChecked(bool b)	true if checkbox is checked, false if not

Events

OnChangeFocus, OnMouseDown, OnKeyPress, OnShortcut ... see StkComponent for details

Methods

Method	Attributes	Description
Redraw	-	draw component on the screen

Inherited

StkCheckbox is descendant of StkLabel.

2.7 StkImage

Description

StkImage is basic picture component. It can contain picture (bitmap), STK support two ways of image handlings. First way is only XPM support via libxpm. Second way is use of Imlib library by STK_IMLIB_USED directive in stk_constants.h. Imlib support PNG, JPEG, GIF, XPM and few others formats. The XPM images can be included in the source code or can be in external file, other files must be in external files.

Constructor

StkImage (StkWindow *parwin, int x, y, char **data); StkImage (StkWindow *parwin, int x, y, char *fname);

Where:

parwin - parent component's window (StkWindow)
x, y - position of component
**data - pointer to XPM data structure included in the source code (by #include "images/image.xpm")
*fname - string which contain filename of the image ("images/image.xpm")

Interface

type	attribute	Get	Set	Description
StkBitmap*	bmp	-	-	bitmap which store the image

Events

OnExpose, OnMouseDown, OnMouseUp, OnMouseMove, OnMouseOver, OnMouseOut ... see StkComponent for details

Methods

Method	Attributes	Description
Redraw	-	draw the image on the screen

2.8 StkSlider

Description

StkSlider is component for setting numerical values (such as audio volume) with a mouse cursor or with a keyboard arrow keys (it is focusable).

Constructor

StkSlider (Window parwin, int x, y, len, orient, val, rang, incr);

Where:

parwin - parent component's window (StkWindow)
x, y - position of component
len - pixel length of the slider (i.e. height for vertical and width for horizontal slider)
orient - slider orientation (STK_SLIDER_HORIZONTAL, STK_SLIDER_VERTICAL)
val - initial value of the slider (from left or top)
rang - range for the slider's value
incr - increment for the value, important only for keyboard adjustments

Interface

type	attribute	Get	Set	Description
int	value	GetValue	SetValue(int v)	set the value from left or from top
int	value	GetValueR	SetValueR(int v)	set the value "Reversaly" so from right or bottom

Events

OnExpose, OnChangeFocus, OnMouseDown, OnMouseUp, OnMouseMove, OnMouseOver, OnMouseOut, OnKeyPress, OnKeyRelease, OnShortcut ... see StkComponent for details

Methods

Method	Attributes	Description
Redraw	-	draw component on the screen

2.9 StkShortcut

Description

StkShortcut is nonvisual component which call the callbach function when user hit the specific keyboard key with selected modifiers.

Constructor

StkShortcut (StkWindow *parwin, KeySym key, int mods, StkComponent *focuscontrol = NULL);

Where:

parwin - parent component's window
key - shortcut key, see keysymdef.h for propper key codes (e.g. XK_F1, XK_space, XK_a, XK_B, XK_Escape, XK_Delete, ...)
mods - shortcut modifiers (e.g. STK_MODIFIER_ALT, see stk_constants)

Interface

type	attribute	Get	Set	Description
-	-	-	-	-

Events

OnShortcut ... see StkComponent for details

Methods

Method	Attributes	Description
-	-	-

2.10 StkMenuitem

Description

StkMenuitem is similar to button but it become blue when mouse is over it and it has no frame! Typical usage is in the popup and main menu. However, mainmenu and popupmenu component is not yet implemented in STK v2.0 alpha 3.

Constructor

StkMenuitem (StkWindow *parwin, left, top, width, height, caption, enabled=true);

Where:

parwin - parent component's window
left, top - position of the menu item
width, height - size of the menu item
caption - caption of the menu item, should be & encoded for shortcuts, if "-" it will be replaced with horizontal line
enabled - if true (default), menu item can be clicked, else it will be gray and disabled

Interface

type	attribute	Get	Set	Description
-	-	-	-	-

Events

OnClick ... see StkComponent for details

Methods

Method	Attributes	Description
-	-	-

2.11 StkEdit

Description

StkEdit is basic component for text input in STK. However, in STK v2.0 alpha 3 it is not yet fully implemented. It is usable only when text do not exceed width of edit.

Constructor

StkEdit (StkWindow *parwin, left, top, width, height, char* text);

Where:

parwin - parent component's window
left, top - position
width, height - size
text - initial text in edit

Interface

type	attribute	Get	Set	Description
-	-	-	-	-

Events

OnClick ... see StkComponent for details

Methods

Method	Attributes	Description
char* GetText()	-	return the text stored in the edit

2.12 StkPanel

Description

StkPanel is basic component for placing other component. Now, it has only border feature. Other things will be implemented later!

Constructor

StkPanel (StkWindow *parwin, left, top, width, height);

Where:

parwin - parent component's window
left, top - position
width, height - size

Interface

type	attribute	Get	Set	Description
TPanelBorder	border	GetBorder()	SetBorder(value)	Border specify the appearance of panel's border: pbNone, pbSingle, pbLowered, pbRaised, pbPressed, pbRelief

Events

see StkComponent for details

Methods

Method	Attributes	Description
-	-	-

3. Other parts

In this section will be described other part of the STK (non-components) which make core of the STK.

3.1 Constants

Files stk_constants.h and stk_constants.cc contain most basic constants of the STK, such as debugging constants (STK_something_DEBUG, used in #ifdef directive), mouse button constants, keyboard constants (modifiers), and some other STK constants.

3.2 Functions

Files stk_functions.h and stk_functions.cc contain some common and usefull functions.

Functions

Type	Function Name	Attributes	Description
-	stk_sleep	long ms	sleep for [ms] miliseconds from 0 up to 35 minutes
KeySym	stk_decode_caption_shortcut	char* caption	decode caption and return KeySym encoded by this caption with & character, e.g. &Hello will return XK_h (mean "h")
char*	stk_decode_caption	char* caption, char* c, char** cap_pref	decode &encoded caption, return encoded character (e.g. "h") in *c and allocate and set caption prefix (from caption start to first & character) into cap_pref string

Examples

stk_sleep(1000); 					// sleep for 1s
KeySym K = stk_decode_caption_shortcut("&Hello"); 	// set variable K to value XK_h
char c, *cp;						// local variables 
cap = stk_decode_caption("Butt&on", &c, &cp);		// decode caption

After last function call, variables will have these values: cap = "Button", c = "o", cp = "Butt"

3.3 Display

Files stk_display.h and stk_display.cc contain function and variables related to visual display (screen), such as handle for display and it's appearance, initialization functions and more.

Functions

Type	Function Name	Attributes	Description
Display*	stk_display_open	char* display_name	open display specified by name, default is NULL or ":0.0"
-	stk_display_init	-	initialize stk_display
-	stk_display_done	-	close stk_display

Variables

Type	Identifier	Description
Display*	stkdisplay	handle to the display, all X functions calls need this
int	stkdisplay_screen	handle for main screen of the display
int	stkdisplay_width, stkdisplay_height	size of the display (screen)
Window	stkdisplay_root	handle for the main (root) window ("desktop")

Examples

stkdisplay = stk_display_open(0);

3.4 Keyboard

Files stk_keys.h and stk_keys.cc contain keyboard handling routines and variables.

Functions

Type	Function Name	Attributes	Description
-	stk_keys_update	XKeyEvent ke, bool pressed	update all keyboard variables, such as modifiers

Variables

Type	Identifier	Description
KeySym	stkkeys_keysym	currently pressed keycode, see keysymdef.h for details
int	stkkeys_modifier	current modifiers (Shift, Alt, ...)
int	stkkeys_state	current modifiers
char*	stkkeys_name	key string name, e.g. "Space", "A", "b", ...
int	stkkeys_namesize	length of the stkkeys_name
bool	stkkeys_ctrl, stkkeys_ctrl_l, stkkeys_ctrl_r	CTRL modifiers (any, left, right)
bool	stkkeys_alt, stkkeys_alt_l, stkkeys_alt_r	ALT modifiers (any, left, right)
bool	stkkeys_shift, stkkeys_shift_l, stkkeys_shift_r	SHIFT modifiers (any, left, right)
bool	stkkeys_meta, stkkeys_meta_l, stkkeys_meta_r	META modifiers (any, left, right)

3.5 Mouse

Files stk_mouse.h and stk_mouse.cc contain mouse related variables and functions.

Functions

Type	Function Name	Attributes	Description
-	stk_get_mouse_root_position	-	get the mouse position in root window now and set stk_mouse_root_* variables

Variables

Type	Identifier	Description
int	stkevent_root_x, stkevent_root_y	mouse cursor position in root window

Examples

stk_get_mouse_root_position();
if (stkevent_root_x >= stkdisplay_width - 10)
  printf("Right screen edge!\n");

3.6 Fonts

Files stk_font.h and stk_font.cc contain interface to the default STK font.

Constants

Name	Description
STK_FONT_DEFAULT	font name for default font
STK_FONT_BOLD	font name for default bold font
STK_FONT_ITALIC	font name for default italic font

Functions

Type	Function Name	Attributes	Description
-	stk_font_init	-	initialize default font
-	stk_font_done	-	release default font
-	stk_font_clip_rect	XFontStruct* fs, char* s, int w, h, bool decode=false	calculate clipping rectangle for string "s", if decode is true decode string first, return width and height in w, h
XFontStruct*	stk_font_load	char* fontname	load font into stkfont variable, font is specified by fontname string

Variables

Type	Identifier	Description
XFontStruct*	stkfont	current (default) font
int	stkfont_cor	baseline correction for last loaded font

Examples

stkfont = stk_font_load(STK_FONT_DEFAULT);

3.7 Colors

Files stk_colors.h and stk_colors.cc contain default STK palette.

Constants

Name	Description
STK_COLOR_BLACK	black color (black)
STK_COLOR_WHITE	white color (white)
STK_COLOR_DARK_GRAY	dark gray color (dark gray)
STK_COLOR_GRAY	gray color (gray)
STK_COLOR_LIGHT_GRAY	light gray color (light gray)
STK_COLOR_RED	red color (red)
STK_COLOR_GREEN	green color (green)
STK_COLOR_BLUE	blue color (blue)
STK_COLOR_VERY_LIGHT_GRAY	very light gray color (very light gray)
STK_COLOR_YELLOW	yellow color (yellow)
STK_COLOR_MAGENTA	magenta color (magenta)
STK_COLOR_CYAN	cyan color (cyan)
STK_COLOR_DARK_RED	dark red color (dark red)
STK_COLOR_DARK_MAGENTA	dark magenta color (dark magenta)
STK_COLOR_DARK_BLUE	dark blue color (dark blue)
STK_COLOR_DARK_CYAN	dark cyan color (dark cyan)
STK_COLOR_DARK_GREEN	dark green color (dark green)
STK_COLOR_DARK_YELLOW	dark yellow color (dark yellow)
STK_COLOR_WINDOW	window color (window)
STK_COLOR_ACTIVE	active color (active)
STK_COLOR_LAST	last used color (with highest number)
STK_COLORS_COUNT	number of colors (last color + 1)

Functions

Type	Function Name	Attributes	Description
-	stk_colors_init	-	allocate and set up all colors defined in stkcolors[] array
-	stk_colors_done	-	release colors

Variables

Type	Identifier	Description
XColor	stkcolors[STK_COLORS_COUNT]	array of colors

Examples

XColor color = stkcolors[STK_COLOR_RED].pixel;

3.8 Initialization

Files stk_init.h and stk_init.cc contains STK initialization functions and some variables.

Functions

Type	Function Name	Attributes	Description
-	stk_init	-	initialize STK, must be first STK call in your application
-	stk_done	-	release STK, must be last STK call in your application

Variables

Type	Identifier	Description
Atom	WM_PROTOCOLS, WM_DELETE_WINDOW	window manager atoms used for correct close window
Window	stkmessage_window	contain handle of window (i.e. component) which receive the event
Atom	stkmessage_atom, stkmessage_state	additional window event attributes
bool	stkmessage_quit	true if main window is getting close, use your_window->Closed() instead

Examples

stk_init();
... any STK functions
stk_done();

3.9 Bitmaps

Files stk_bitmap.h and stk_bitmap.cc contain basic image handling object. If is used libxpm, only XPM images are supported. If is used Imlib, PNG, GIF, JPEG and XPM images are supported. If you only want to draw one picture on the window, use StkImage instead.

Constructor

StkComponent (Window parwin, char **data);
StkComponent (Window parwin, char *fname);

Where:

parwin - parent component's window
**data - pointer to XPM data structure included in source code (#include "image.xpm")
*fname - file name of the image on the disk

Interface

type	attribute	Get	Set	Description
Pixmap, GC	pixmap, mask, GC	bool Load(char *data),bool Load(char fname)	-	load image from source code or from external file, return true on success
int	width	GetWindth()	-	get loaded bitmap width
int	height	GetHeight()	-	get loaded bitmap height

Events

None, not a component!

Methods

Method	Attributes	Description
Load	char **data	load image from source code (XPM must be include in source code, e.g. #include "xpm/image.xpm")
Load	char *fname	load from external file e.g. "xpm/image.xpm"
Draw	int x,y	draw bitmap on the parent window at the position [x,y] measured from left-top corner

Examples

#include "xpm/image.xpm"						// include XPM file into source code
StkWindow *window1 = new StkWindow(...);				// create window1
StkBitmap *bmp1 = new StkBitmap(window1->GetWindow(), image_xpm);	// create the bitmap on the window1 from the source
StkBitmap *bmp2 = new StkBitmap(window1->GetWindow(), "xpm/image.xpm");	// create the bitmap on the window1 from the file
bmp1->Draw(10,10);							// draw bmp1 on window1
bmp2->Draw(100,10);							// draw bmp2 on window1

3.10 Graphics

Files stk_shapes.h and stk_shapes.cc contain all graphics of the STK components. If you want to change appearance of the components, simple change this files. STK doesn't support themes! (more appearances in one moment)

Functions

Type	Function Name	Attributes	Description
-	stk_draw_slider_button	Display* di, Drawable dr, GC gc, int x,y,w,h, orient, bool active	draw StkSlider button
-	stk_draw_frame	Display* di, Drawable dr, GC gc, int x,y,w,h, bool enabled	draw impressed white area (slider, edit, memo, ..)
-	stk_draw_label	Display* di, Drawable dr, GC gc, XFontStruct fs, int x,y,w,h,oldw,oldh, char caption, bool enabled,active,correction=true	draw label
-	stk_draw_radiobutton	Display* di, Drawable dr, GC gc, XFontStruct fs, int x,y,w,h,oldw,oldh,button_width, char caption, bool enabled,active,focused,checked	draw radiobutton (except bitmap)
-	stk_draw_button	Display* di, Drawable dr, GC gc, XFontStruct fs, int x,y,w,h, char caption, bool enabled,focused,pressed,active	draw button
-	stk_draw_rectangle	Display* di, Drawable dr, GC gc, int x,y,w,h, uint color	draw simple rectangle
-	stk_draw_focus_rectangle	Display* di, Drawable dr, GC gc, int x,y,w,h	draw focus rectangle (dotted)
-	stk_fill_rectangle	Display* di, Drawable dr, GC gc, int x,y,w,h, uint color	fill rectangle
-	stk_draw_slider_bg_horiz	Display *di, Drawable dr, GC gc, int x,y,w,h,a,b	draw the bacgrouund of slider
-	stk_draw_slider_bg_vert	Display *di, Drawable dr, GC gc, int x,y,w,h,a,b	draw the bacgrouund of slider

Examples

// from StkButton.Draw()
stk_draw_button(stkdisplay,window,gc,stkfont,0,0,width,height,caption,enabled,focused,pressed,active);

3.11 Callbacks

Files stk_callback.h and stk_callback.cc contain component's callback functions definitions and templates.

Objects

Name	Constructor	Description
StkBasicCallback	-	abstract class, parent of both callback methods
StkGlobalCallback	*function	callback for global functions
StkCallback	*object,&object::method	callback for object's method

Methods

Type	Method Name	Attributes	Description
-	Execute	-	call the callback

Examples

class SomeHigherClass 		// some object
{ 
 public: 
   StkButton *button1;		// button1
   void button1click(void) 	// button1 method callback
     { 
       printf("Method\n"); 
     };
};

void global1click() 		// button1 global callback
{ 
  printf("Global\n"); 
}			

...
SomeHigherClass *shc = new ...;		// create instance shc which "contain" few components and it's callbacks
shc->button1->CreateCallback
    (new StkCallback(&global1click));		   			      // set the global callback
shc->button1->CreateCallback
    (new StkCallback<SomeHigherClass>(shc,&SomeHigherClass::button1click));   // set the method callback

3.12 Components

Files stk_components.h and stk_components.cc contain object which handle array of all components in window throw bidirectional linked list and event handler implementation. Each component which may contain other component (e.g. window) has it's own instance of StkComponents class.

Functions

Type	Function Name	Attributes	Description
void	stk_next_event	-	wait for next keyboard/mouse/other event and set the stkevent and other variables

Variables

Type	Identifier	Description
XEvent	stkevent	current event from the X Server

Methods (of StkComponents class)

Method	Attributes	Description
Add	StkComponent*	add component into components list
Remove	StkComponent*	remove component from the list
SetFocus	StkComponent*	unset focus of focused component and set focus to the specified component
Update	-	update event handler and call the component events
StkComponent *Find	Window	find the component by the window which receive the event
Debug	-	display list of components
ECNF	Window	debug when Event Component Not Found
CallShortcut	-	check the shortcuts and call OnShortcut if it match

4. Examples

4.1 Hello world

Description

This example show popular "Hello world!" demo using STK toolkit.

Source

#include "../../stk.h"		// path to STK library

int main()
{
  // initialize STK
  stk_init(); 			
  
  // create the window1
  StkWindow *window1 = new StkWindow(stkdisplay_root, -1, -1, 150, 50, "Demo");
  
  // create label1 component
  StkLabel *label1 = new StkLabel(window1, 10, 10, -1, -1, "Hello world!");

  // main loop
  do {
    stk_next_event();
    window1->components->Update();
  } while (! (window1->Closed()) );
  
  // done STK
  stk_done();
}

5. Appendix

5.1 Table of component's constructors

StkLabel	StkWindow* parwin, int x,y,w,h, char* cap, StkComponent* focuscontrol
StkCheckbox	StkWindow* parwin, int x,y, char* cap, bool chckd=false
StkRadiobutton	StkWindow* parwin, int x,y, char* cap, int grp=0, bool chckd=false
StkButton	StkWindow* parwin, int x,y,w,h, char* cap
StkImage	StkWindow* parwin, int x,y,w,h, char** data StkWindow* parwin, int x,y,w,h, char* fname
StkSlider	StkWindow* parwin, int x,y,len, orient, val, rang, incr
StkShortcut	StkWindow* parwin, KeySym key, int mods, StkComponent* focuscontrol=null
StkMenuitem	StkWindow* parwin, left, top, width, height, char* cap, enabled=true
StkEdit	StkWindow* parwin, left, top, width, height, char* text
StkPanel	StkWindow *parwin, left, top, width, height