ch.aplu.jaw

Class NativeHandler

java.lang.Object

ch.aplu.jaw.NativeHandler

public class NativeHandler
extends java.lang.Object

Class that provides the link between Java and native code for the JAW (Java Api Wrapper). Native code must reside in a Windows DLL, created with the distributed C++-library jaw.lib. Consult the distribution of the JAW package for more information and examples.

Strongly inspired from Tal Liron's article 'Enhance your Java application with Java Native Interface'

Field Summary

Fields

Modifier and Type	Field and Description
static long	WS_BORDER Creates a window that has a thin-line border.
static long	WS_CAPTION Creates a window that has a title bar (includes the WS_BORDER style).
static long	WS_DEFAULT Same as WS_SYSMENU | WS_MAXIMIZEBOX | WS_MINIMIZEBOX | WS_THICKFRAME | WS_CAPTION | WS_VISIBLE
static long	WS_DLGFRAME Creates a window that has a border of a style typically used with dialog boxes.
static long	WS_EX_TRANSPARENT Creates a window that is transparent (partially opaque).
static long	WS_HSCROLL Creates a window that has a horizontal scroll bar.
static long	WS_MAXIMIZE Creates a window that is initially maximized.
static long	WS_MAXIMIZEBOX Creates a window that has a Maximize button.
static long	WS_MINIMIZE Creates a window that is initially minimized.
static long	WS_MINIMIZEBOX Creates a window that has a Minimize button.
static long	WS_OVERLAPPED Creates an overlapped window.
static long	WS_OVERLAPPEDWINDOW Same as WS_OVERLAPPED | WS_CAPTION | WS_SYSMENU | WS_THICKFRAME | WS_MINIMIZEBOX | WS_MAXIMIZEBOX
static long	WS_POPUP Creates a pop-up window.
static long	WS_POPUPWINDOW Same as WS_POPUP | WS_BORDER | WS_SYSMENU
static long	WS_SYSMENU Creates a window that has a System-menu box in its title bar.
static long	WS_THICKFRAME Creates a window that has a sizing border.
static long	WS_VISIBLE Creates a window that is initially visible.
static long	WS_VSCROLL Creates a window that has a vertical scroll bar.

Constructor Summary

Constructors

Constructor and Description
NativeHandler(java.lang.String dllPath) Constructs a NativeHandler to be used without the native window.
NativeHandler(java.lang.String dllPath, int select) Constructs a NativeHandler to be used without the native window.
NativeHandler(java.lang.String dllPath, java.lang.Object exposedObj) Constructs a NativeHandler to be used without the native window.
NativeHandler(java.lang.String dllPath, java.lang.Object exposedObj, int select) Constructs a NativeHandler to be used without the native window.
NativeHandler(java.lang.String dllPath, java.lang.Object exposedObj, int select, java.lang.String title, int ulx, int uly, int width, int height, long windowStyle) Constructs a NativeHandler and creates a native window with given title, position, size and style.
NativeHandler(java.lang.String dllPath, java.lang.Object exposedObj, java.lang.String title, int ulx, int uly, int width, int height, long windowStyle) Same as NativeHandler(dllPath, exposedObj, select, title, ulx, uly, width, height, windowStyle) with select = 0.
NativeHandler(java.lang.String dllPath, java.lang.String title, int ulx, int uly, int width, int height, long windowStyle) Same as NativeHandler(dllPath, exposedObj, select, title, ulx, uly, width, height, windowStyle) with no exposed object and select = 0.

Method Summary

Methods

Modifier and Type	Method and Description
void	addTrayIconListener(TrayIconListener listener, int iconEventMask) Registers the given listener, in order to get mouse events when the mouse cursor is inside the tray icon.
int	countBuf() Returns the count of available (pending) elements in the native JNIBuffer.
void	createBuf(boolean[] ary) Same as createBuf(ary, bufSize) with bufSize = 1000.
void	createBuf(boolean[] ary, int bufSize) Creates a (native) JNIBuffer of given size and links the native buffer and the the given Java buffer.
void	createBuf(byte[] ary) Same as createBuf(byte[] ary, int bufSize) with bufSize = 1000.
void	createBuf(byte[] ary, int bufSize) Same as createBuf(boolean[] ary, int bufSize), but for a byte array.
void	createBuf(char[] ary) Same as createBuf(char[] ary, int bufSize) with bufSize = 1000.
void	createBuf(char[] ary, int bufSize) Same as createBuf(boolean[] ary, int bufSize), but for a char array.
void	createBuf(double[] ary) Same as createBuf(double[] ary, int bufSize) with bufSize = 1000.
void	createBuf(double[] ary, int bufSize) Same as createBuf(boolean[] ary, int bufSize), but for a double array.
void	createBuf(float[] ary) Same as createBuf(float[] ary, int bufSize) with bufSize = 1000.
void	createBuf(float[] ary, int bufSize) Same as createBuf(boolean[] ary, int bufSize), but for a float array.
void	createBuf(int[] ary) Same as createBuf(int[] ary, int bufSize) with bufSize = 1000.
void	createBuf(int[] ary, int bufSize) Same as createBuf(boolean[] ary, int bufSize), but for an int array.
void	createBuf(long[] ary) Same as createBuf(long[] ary, int bufSize) with bufSize = 1000.
void	createBuf(long[] ary, int bufSize) Same as createBuf(boolean[] ary, int bufSize), but for a long array.
void	createBuf(short[] ary) Same as createBuf(short[] ary, int bufSize) with bufSize = 1000.
void	createBuf(short[] ary, int bufSize) Same as createBuf(boolean[] ary, int bufSize), but for a short array.
void	destroy() Closes the native window and releases all native resources.
void	expose(java.lang.Object exposedObj) Allow the native code to have access to the given object.
void	flushBuf() Flushes the native JNIBuffer.
void	hideIcon() Hides the tray icon.
void	hideWindow() Hides the window, but does not release any resources.
int	invoke() Invokes the native function with value = 0.
int	invoke(int val) Invokes the native function with given value.
boolean	isBufOverflow(boolean reset) Checks for a possible overflow of the JNIBuffer.
int	readBuf(int count) Reads up to count elements from a native JNIBuffer into the previously created Java buffer.
void	setWindowPosition(int ulx, int uly) Moves the window to the given position (upper left corner).
void	setWindowSize(int width, int height) Resizes the window to given size (width, height).
void	showBalloonTooltip(java.lang.String title, java.lang.String text, int flag, int timeout) Shows a ballon tool tip at the tray icon that contains the given title and text for the given timeout time.
void	showIcon(java.lang.String iconPath) Same as showIcon(iconPath, tooltip), but no tool tip is shown.
void	showIcon(java.lang.String iconPath, java.lang.String tooltip) Shows tray icon given by iconPath.
void	showWindow() Shows the native window.
void	showWindow(int percent) Shows a transparent native window with given opacity.
void	showWindow(int percent, int red, int green, int blue) Shows a transparent native window with given opacity and RGB color for transparent areas.
void	startThread() Start a native high priority thread.
void	stopThread() Stop a native high priority thread.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

WS_OVERLAPPED

public static final long WS_OVERLAPPED

Creates an overlapped window. An overlapped window has a title bar and a border.

See Also:

Constant Field Values

WS_SYSMENU

public static final long WS_SYSMENU

Creates a window that has a System-menu box in its title bar. The WS_CAPTION style must also be specified.

See Also:

Constant Field Values

WS_BORDER

public static final long WS_BORDER

Creates a window that has a thin-line border.

See Also:

Constant Field Values

WS_POPUP

public static final long WS_POPUP

Creates a pop-up window.

See Also:

Constant Field Values

WS_MINIMIZEBOX

public static final long WS_MINIMIZEBOX

Creates a window that has a Minimize button.

See Also:

Constant Field Values

WS_MAXIMIZEBOX

public static final long WS_MAXIMIZEBOX

Creates a window that has a Maximize button.

See Also:

Constant Field Values

WS_THICKFRAME

public static final long WS_THICKFRAME

Creates a window that has a sizing border.

See Also:

Constant Field Values

WS_CAPTION

public static final long WS_CAPTION

Creates a window that has a title bar (includes the WS_BORDER style).

See Also:

Constant Field Values

WS_VISIBLE

public static final long WS_VISIBLE

Creates a window that is initially visible.

See Also:

Constant Field Values

WS_EX_TRANSPARENT

public static final long WS_EX_TRANSPARENT

Creates a window that is transparent (partially opaque).

See Also:

Constant Field Values

WS_MINIMIZE

public static final long WS_MINIMIZE

Creates a window that is initially minimized.

See Also:

Constant Field Values

WS_MAXIMIZE

public static final long WS_MAXIMIZE

Creates a window that is initially maximized.

See Also:

Constant Field Values

WS_DLGFRAME

public static final long WS_DLGFRAME

Creates a window that has a border of a style typically used with dialog boxes. A window with this style cannot have a title bar.

See Also:

Constant Field Values

WS_VSCROLL

public static final long WS_VSCROLL

Creates a window that has a vertical scroll bar.

See Also:

Constant Field Values

WS_HSCROLL

public static final long WS_HSCROLL

Creates a window that has a horizontal scroll bar.

See Also:

Constant Field Values

WS_DEFAULT

public static final long WS_DEFAULT

Same as WS_SYSMENU | WS_MAXIMIZEBOX | WS_MINIMIZEBOX | WS_THICKFRAME | WS_CAPTION | WS_VISIBLE

See Also:

Constant Field Values

WS_OVERLAPPEDWINDOW

public static final long WS_OVERLAPPEDWINDOW

Same as WS_OVERLAPPED | WS_CAPTION | WS_SYSMENU | WS_THICKFRAME | WS_MINIMIZEBOX | WS_MAXIMIZEBOX

See Also:

Constant Field Values

WS_POPUPWINDOW

public static final long WS_POPUPWINDOW

Same as WS_POPUP | WS_BORDER | WS_SYSMENU

See Also:

Constant Field Values

Constructor Detail

NativeHandler

public NativeHandler(java.lang.String dllPath,
             java.lang.Object exposedObj,
             int select,
             java.lang.String title,
             int ulx,
             int uly,
             int width,
             int height,
             long windowStyle)

Constructs a NativeHandler and creates a native window with given title, position, size and style. The given native library must be a valid windows DLL. If the fully qualified path (drive:\dir\filename.dll) is given, the specified file is loaded. If only the filename (without extension) is given, searches the current directory and then the environment path to load the filename.dll.
The given object reference will be used to 'expose' the object to the native code, i.e. to open access to (even private) instance variables and methods from the C/C++ code.
'select' makes the choice for one of several user-defined subclasses of class WindowHandler. It may have any value, if only one subclass is defined.
windowStyle determines the style of the native window as explained in the API documentation for CreateWindow(). It is an OR-combination of the static window-style-constants of this class. Not all styles are appropriate for JAW applications. If no style is appropriate, pass 0.
If window style contains WS_VISIBLE the window is immediately visible, otherwise showWindow() must be called.

Parameters:

dllPath - the path of the native library (DLL). If only the filename is given, searches in current directory and environment path

exposedObj - the object that opens access from native code

select - the selection of a subclass of WindowHandler

title - the window's title in the title bar

ulx - the x-coordinate of the window's upper left corner (in pixels)

uly - the y-coordinate of the window's upper left corner (in pixels)

width - the width of the window (in pixels)

height - the height of the window (in pixels)

windowStyle - the style of the window (OR-combination of style-constants)

Throws:

UnexpectedLinkError - if the given library cannot be loaded

NativeHandler

public NativeHandler(java.lang.String dllPath,
             java.lang.Object exposedObj,
             java.lang.String title,
             int ulx,
             int uly,
             int width,
             int height,
             long windowStyle)

Same as NativeHandler(dllPath, exposedObj, select, title, ulx, uly, width, height, windowStyle) with select = 0.

Parameters:

dllPath - the path of the native library (DLL). If only the filename is given, searches in current directory and environment path

exposedObj - the object that opens access from native code

title - the window's title in the title bar

ulx - the x-coordinate of the window's upper left corner (in pixels)

uly - the y-coordinate of the window's upper left corner (in pixels)

width - the width of the window (in pixels)

height - the height of the window (in pixels)

windowStyle - the style of the window (OR-combination of style-constants)

Throws:

UnexpectedLinkError - if the given library cannot be loaded

See Also:

NativeHandler(String dllPath, Object exposedObj, int select, String title, int ulx, int uly, int width, int height, long windowStyle)

NativeHandler

public NativeHandler(java.lang.String dllPath,
             java.lang.String title,
             int ulx,
             int uly,
             int width,
             int height,
             long windowStyle)

Same as NativeHandler(dllPath, exposedObj, select, title, ulx, uly, width, height, windowStyle) with no exposed object and select = 0.

Parameters:

dllPath - the path of the native library (DLL). If only the filename is given, searches in current directory and environment path

title - the window's title in the title bar

ulx - the x-coordinate of the window's upper left corner (in pixels)

uly - the y-coordinate of the window's upper left corner (in pixels)

width - the width of the window (in pixels)

height - the height of the window (in pixels)

windowStyle - the style of the window (OR-combination of style-constants)

Throws:

UnexpectedLinkError - if the given library cannot be loaded

See Also:

NativeHandler(String dllPath, Object exposedObj, int select, String title, int ulx, int uly, int width, int height, long windowStyle)

NativeHandler

public NativeHandler(java.lang.String dllPath,
             java.lang.Object exposedObj,
             int select)

Constructs a NativeHandler to be used without the native window.

Parameters:

dllPath - the path of the native library (DLL). If only the filename is given, searches in current directory and environment path

exposedObj - the object that opens access from native code

select - the selection of a subclass of WindowHandler

Throws:

UnexpectedLinkError - if the given library cannot be loaded

NativeHandler

public NativeHandler(java.lang.String dllPath,
             java.lang.Object exposedObj)

Constructs a NativeHandler to be used without the native window. Same as NativeHandler(dllPath, exposedObj, select) with select = 0

Parameters:

dllPath - the path of the native library (DLL). If only the filename is given, searches in current directory and environment path

exposedObj - the object that opens access from native code

Throws:

UnexpectedLinkError - if the given library cannot be loaded

See Also:

NativeHandler(String dllPath, Object exposedObj, int select)

NativeHandler

public NativeHandler(java.lang.String dllPath,
             int select)

Constructs a NativeHandler to be used without the native window. Same as NativeHandler(dllPath, exposedObj, select) with no exposed object

Parameters:

dllPath - the path of the native library (DLL). If only the filename is given, searches in current directory and environment path

select - the selection of a subclass of WindowHandler

Throws:

UnexpectedLinkError - if the given library cannot be loaded

See Also:

NativeHandler(String dllPath, Object exposedObj, int select)

NativeHandler

public NativeHandler(java.lang.String dllPath)

Constructs a NativeHandler to be used without the native window. Same as NativeHandler(dllPath, exposedObj, select) with no exposed object and select = 0

Parameters:

dllPath - the path of the native library (DLL). If only the filename is given, searches in current directory and environment path

Throws:

UnexpectedLinkError - if the given library cannot be loaded

See Also:

NativeHandler(String dllPath, Object exposedObj, int select)

Method Detail

expose

public void expose(java.lang.Object exposedObj)

Allow the native code to have access to the given object. Even private variables and methods are exposed.

Parameters:

exposedObj - the object that opens access from native code

showWindow

public void showWindow()

Shows the native window. Only allowed, if the NativeHandler instance was created with the appropriate windows options. For transparent windows (windows style WS_EX_TRANSPARENT) the window is shown completely opaque and RGB(255, 255, 255) is used as color for transparent areas

showWindow

public void showWindow(int percent)

Shows a transparent native window with given opacity. Only allowed, if the NativeHandler instance was created with the appropriate windows options, especially windows style WS_EX_TRANSPARENT. RGB(255, 255, 255) is used as color for transparent areas.

Parameters:

percent - the percentage of opacity in range 0..100

showWindow

public void showWindow(int percent,
              int red,
              int green,
              int blue)

Shows a transparent native window with given opacity and RGB color for transparent areas. Only allowed, if the NativeHandler instance was created with the appropriate windows options, especially windows style WS_EX_TRANSPARENT.

Parameters:

percent - the percentage of opacity in range 0..100

red - the red portion of the transparency color (0..255)

green - the green portion of the transparency color (0..255)

blue - the blue portion of the transparency color (0..255)

hideWindow

public void hideWindow()

Hides the window, but does not release any resources.

setWindowPosition

public void setWindowPosition(int ulx,
                     int uly)

Moves the window to the given position (upper left corner). If the window is visible, it will be put on top of all other windows.

Parameters:

ulx - the x-coordinate of the window's upper left corner (in pixels)

uly - the y-coordinate of the window's upper left corner (in pixels)

setWindowSize

public void setWindowSize(int width,
                 int height)

Resizes the window to given size (width, height). If the window is visible, it will be put on top of all other windows.

Parameters:

width - the width of the window (in pixels)

height - the height of the window (in pixels)

destroy

public void destroy()

Closes the native window and releases all native resources. Should be called whenever the program is about to terminate. Any further call to NativeHandler's methods will return immediatly.

invoke

public int invoke(int val)

Invokes the native function with given value.

Parameters:

val - the integer value to be passed to the native function

Returns:

the integer return value from the native function call

invoke

public int invoke()

Invokes the native function with value = 0.

Returns:

the integer return value from the native function call

createBuf

public void createBuf(boolean[] ary,
             int bufSize)

Creates a (native) JNIBuffer of given size and links the native buffer and the the given Java buffer. The native code initializes the elements of the Java buffer to 0.
Deletes any other JNIBuffer that has been created before (only one buffer can be allocated).
The JNIBuffer is organized as a circular FIFO buffer. In a typical application the native code fills it asynchronously to the Java thread. readBuf(int count) transfers up to count elements (or as many as all available) from the JNIBuffer to the Java buffer, where they ready to be used.

Example:

char[] values = new char[4];
createBuf(values, 6);

Native code fills JNIBuffer:
writeChar('A');
writeChar('B');
writeChar('C'):

JNIBuffer (circular) size 6
-------------------------
| A | B | C | | | |
-------------------------

Java code transfers up to 2 elements:
readBuf(2);

Java buffer size 4
-----------------
| A | B | | |
-----------------



Parameters:

ary - the Java array getting the native data

bufSize - the size (number of elements) of the native buffer.

See Also:

readBuf(int count)

createBuf

public void createBuf(boolean[] ary)

Same as createBuf(ary, bufSize) with bufSize = 1000.

See Also:

createBuf(boolean[] ary, int bufsize)

createBuf

public void createBuf(char[] ary,
             int bufSize)

Same as createBuf(boolean[] ary, int bufSize), but for a char array.

See Also:

createBuf(boolean[] ary, int bufsize)

createBuf

public void createBuf(char[] ary)

Same as createBuf(char[] ary, int bufSize) with bufSize = 1000.

See Also:

createBuf(boolean[] ary, int bufsize)

createBuf

public void createBuf(byte[] ary,
             int bufSize)

Same as createBuf(boolean[] ary, int bufSize), but for a byte array.

See Also:

createBuf(boolean[] ary, int bufsize)

createBuf

public void createBuf(byte[] ary)

Same as createBuf(byte[] ary, int bufSize) with bufSize = 1000.

See Also:

createBuf(boolean[] ary, int bufsize)

createBuf

public void createBuf(short[] ary,
             int bufSize)

Same as createBuf(boolean[] ary, int bufSize), but for a short array.

See Also:

createBuf(boolean[] ary, int bufsize)

createBuf

public void createBuf(short[] ary)

Same as createBuf(short[] ary, int bufSize) with bufSize = 1000.

See Also:

createBuf(boolean[] ary, int bufsize)

createBuf

public void createBuf(int[] ary,
             int bufSize)

Same as createBuf(boolean[] ary, int bufSize), but for an int array.

See Also:

createBuf(boolean[] ary, int bufsize)

createBuf

public void createBuf(int[] ary)

Same as createBuf(int[] ary, int bufSize) with bufSize = 1000.

See Also:

createBuf(boolean[] ary, int bufsize)

createBuf

public void createBuf(long[] ary,
             int bufSize)

Same as createBuf(boolean[] ary, int bufSize), but for a long array.

See Also:

createBuf(boolean[] ary, int bufsize)

createBuf

public void createBuf(long[] ary)

Same as createBuf(long[] ary, int bufSize) with bufSize = 1000.

See Also:

createBuf(boolean[] ary, int bufsize)

createBuf

public void createBuf(float[] ary,
             int bufSize)

Same as createBuf(boolean[] ary, int bufSize), but for a float array.

See Also:

createBuf(boolean[] ary, int bufsize)

createBuf

public void createBuf(float[] ary)

Same as createBuf(float[] ary, int bufSize) with bufSize = 1000.

See Also:

createBuf(boolean[] ary, int bufsize)

createBuf

public void createBuf(double[] ary,
             int bufSize)

Same as createBuf(boolean[] ary, int bufSize), but for a double array.

See Also:

createBuf(boolean[] ary, int bufsize)

createBuf

public void createBuf(double[] ary)

Same as createBuf(double[] ary, int bufSize) with bufSize = 1000.

See Also:

createBuf(boolean[] ary, int bufsize)

readBuf

public int readBuf(int count)

Reads up to count elements from a native JNIBuffer into the previously created Java buffer.

Parameters:

count - the maximal number of elements to fetch from the JNIBuffer

Returns:

the number of elements effectively copied, -1, if the JNIBuffer has not been created or count is less than 0 or greater than the Java array length

See Also:

createBuf(boolean[] ary, int bufsize)

flushBuf

public void flushBuf()

Flushes the native JNIBuffer. Does not modify the corresponding Java array, passed by createBuf() Resets a possible overflow error condition. Does nothing, if the JNIBuffer has not been created.

See Also:

createBuf(boolean[] ary, int bufsize)

countBuf

public int countBuf()

Returns the count of available (pending) elements in the native JNIBuffer. Does not modify neither the native JNIBuffer nor the corresponding Java array, passed by createBuf().

Returns:

the number of available elements, -1, if the JNIBuffer has not been created

See Also:

createBuf(boolean[] ary, int bufsize)

isBufOverflow

public boolean isBufOverflow(boolean reset)

Checks for a possible overflow of the JNIBuffer. This happens when the circular FIFO JNIBuffer is filled. New elements will be lost, but old elements are not overwritten. The error condition is reset by either calling isBufOverflow(true) or flushBuf(). Retrieving elements will cause the JNIBuffer to work normally, but the error condition is not reset.

Parameters:

reset - if true, resets a possible overflow condition, if false, the condition is unchanged

Returns:

true, for an overflow condition, otherwise false

See Also:

flushBuf(), createBuf(boolean[] ary, int bufsize)

startThread

public void startThread()

Start a native high priority thread. See: Documentation for native class WindowHandler

stopThread

public void stopThread()

Stop a native high priority thread. See: Documentation for native class WindowHandler

addTrayIconListener

public void addTrayIconListener(TrayIconListener listener,
                       int iconEventMask)

Registers the given listener, in order to get mouse events when the mouse cursor is inside the tray icon. The given iconEventMask is an OR-combination of the following static flags of class NativeMouse:
- left mouse button down: lPress
- left mouse button up: lRelease
- left mouse button clicked (fast down/up): lClick
- left mouse button double-clicked (fast down/up/down/up): lDClick
- same for right mouse button: rPress, rRelease, rClick, rDlick
- mouse moved (coordinates not retrievable): move

When a mouse event occurs, the implementation of TrayIconListener.iconEvent(TrayIcon icon) is called.

See Also:

NativeMouse, TrayIcon, TrayIconListener

showIcon

public void showIcon(java.lang.String iconPath,
            java.lang.String tooltip)

Shows tray icon given by iconPath. Size of icon is normally 32x32 bit with some transparent areas.
Windows 2000 supports icons of a color depth up to the current display mode.
Windows XP supports icons up to 32 BPP. When the mouse cursor is moved into the icon, a standard tool tip (rectangular shape) holding the given text is displayed.

Parameters:

iconPath - the filename of the icon file. If drive:\dir is missing, the directory of the Java class file is assumed

tooltip - the text to be displayed in the tool tip area. When empty, no tool tip is shown

showIcon

public void showIcon(java.lang.String iconPath)

Same as showIcon(iconPath, tooltip), but no tool tip is shown.

Parameters:

iconPath - the filename of the icon file. If drive:\dir is missing, the directory of the Java class file is assumed

See Also:

showIcon(String iconPath, String tooltip)

hideIcon

public void hideIcon()

Hides the tray icon. The allocated resources are not released.

See Also:

destroy()

showBalloonTooltip

public void showBalloonTooltip(java.lang.String title,
                      java.lang.String text,
                      int flag,
                      int timeout)

Shows a ballon tool tip at the tray icon that contains the given title and text for the given timeout time.
Minimum and maximum timeout is enforced by the operation system.
Given flag selects a small icon to the balloon. Values:
0: no icon
1: info icon (letter i)
2: warning icon (exclamation)
3: error icon (cross)

Parameters:

title - the title (up to 63 characters) shown bold in the tool tip. When empty, no title is shown

text - the text (up to 253 characters) to be displayed in the tool tip area. When empty, no text is shown

flag - an integer 0..3 selecting the type of a small icon

timeout - the time in milliseconds until the tool tip disappears