Module uwin [Version: v01]

[Documentation]

[Details]

[Wiki]

[Tests]

This documentation describes the Prokee module interface.

Static Methods:

main
int uwin::main(int argc,char **argv)

UWIN Startup Functions

run

int uwin::run(const char *title,int x,int y,int xx,int yy,int32_t(*guiCallbackFunction)(AbsThread *thisThread,AbsMsgItem *msg))

start_thread

AbsThread *uwin::start_thread(const char *title,int x,int y,int xx,int yy,int32_t(*guiCallbackFunction)(AbsThread *thisThread,AbsMsgItem *msg))

start_ex
int uwin::start_ex(const char *title,int x,int y,int xx,int yy,AbsThreadMan *tm)

Shutdown

close
int uwin::close()

Other Helper Functions

window_redim
void uwin::window_redim(uint16_t width,uint16_t height)

InvalidateAll
void uwin::InvalidateAll()

Manipulating Windows

ResizeWindow
void uwin::ResizeWindow(uint16_t width,uint16_t height)

MoveWindow
void uwin::MoveWindow(int16_t posX,int16_t posY)

Getting Window Properties

getWindowDimensions
uint64_t uwin::getWindowDimensions()

getWindowPosition
uint64_t uwin::getWindowPosition()

Updating the Client-Area of the Window

getImageData
ImageData uwin::getImageData()

putImage
void uwin::putImage()

putImagePadded
void uwin::putImagePadded()

putRegion
void uwin::putRegion(CRegion *r)

putImageData
void uwin::putImageData(ImageData img)

Getting Screen Properties

getScreenDpiX
uint16_t uwin::getScreenDpiX()

getScreenDpiY
uint16_t uwin::getScreenDpiY()

Motivation

This module provides minimal window management functions for the X-Window System and for the WinAPI.

How the communication with the window system works:
Module uwin receives window messages and user input events (as provided by X or by Windows) and postes them to the message queue of the gui-manager (see module guiman). The gui-manager has its own massage queue which allowes communication in both directions. Alternatively a callback function can be provided, to have the gui-manager run on the same thread as module uwin. (This is required, when building single threaded programs.)

Basic Setup Alternatives:

uwin::run()
Use this for single threaded programs. All user input events are immediatelly processed via a callback function.
uwin::start_thread()
This setup uses two threads one for uwin and and one for the gui manager (guiman).
uwin::start_ex()
This is the standard setup for multithreaded programs.
The application is controlled by three threads as follows:
- The uwin thread:
- The guiman thread:
- The main thread of the program:

Static Methods

main

This runs a demo.

Runs a test of the uwin module.

Signature:

int uwin::main(int argc,char **argv)

Parameters:

Type	Name	Direction	Description
int	argc		The number of command-line parameters.
char **	argv	[IN]	The command-line parameters.

Return value:
Exit status.

run

Starts the window-system on the current thread.
If a callback function is set, module uwin will call this function whenever a window event (user input) occurs.

Signature:

int uwin::run(const char *title,int x,int y,int xx,int yy,int32_t(*guiCallbackFunction)(AbsThread *thisThread,AbsMsgItem *msg))

Parameters:

Type

Name

Direction

Description

const char *

title

[IN]

Title of the main window.

int

x-position of the main window.

int

y-position of the main window.

int

Initial width of the main window.

int

Initial height of the main window.

int32_t(*guiCallbackFunction)
(
AbsThread *thisThread,
AbsMsgItem *msg
)

with typedef

Type	Name
guiCallbackFunction_t	guiCallbackFunction

[IN]

The callback function of the gui module.

Parameters

thisThread: Pointer to a AbsThread object.

msg: Pointer to a AbsMsgItem object.

Return value

Should return 0 on successful execution.

Return value:
Returns 0

start_thread

Starts the window-system in a new thread.
If a callback function is set, module uwin will call this function whenever a window event (user input) occurs.

Signature:

AbsThread *uwin::start_thread(const char *title,int x,int y,int xx,int yy,int32_t(*guiCallbackFunction)(AbsThread *thisThread,AbsMsgItem *msg))

Parameters:

Type

Name

Direction

Description

const char *

title

[IN]

Title of the main window.

int

x-position of the main window.

int

y-position of the main window.

int

Initial width of the main window.

int

Initial height of the main window.

int32_t(*guiCallbackFunction)
(
AbsThread *thisThread,
AbsMsgItem *msg
)

with typedef

Type	Name
guiCallbackFunction_t	guiCallbackFunction

[IN]

The callback function of the gui module.

Parameters

thisThread: Pointer to a AbsThread object.

msg: Pointer to a AbsMsgItem object.

Return value

Should return 0 on successful execution.

Return value:
Pointer to a AbsThread object.

start_ex

Starts the window-system in a new thread.
If this function is used, all user inputs (window events) result in Messages sent to the GUI-manager via the thread-manager tm.

Signature:

int uwin::start_ex(const char *title,int x,int y,int xx,int yy,AbsThreadMan *tm)

Parameters:

Type	Name	Direction	Description
const char *	title	[IN]	Title of the main window.
int	x		x-position of the main window.
int	y		y-position of the main window.
int	xx		Initial width of the main window.
int	yy		Initial height of the main window.
AbsThreadMan *	tm	[IN/OUT]	Pointer to a AbsThreadMan object.

Return value:
The ID of the new thread.

close

THIS DOES NOTING.
A shutdown should be initiated via the message system.

Signature:

int uwin::close()

Return value:
0

window_redim

Sets the window dimensions. This does not resize the window. This function is used to update the window dimensions stored in module uwin, after the window has already been resized and updated.

-- TODO -- rename this function.

Signature:

void uwin::window_redim(uint16_t width,uint16_t height)

Parameters:

Type	Name	Direction	Description
uint16_t	width		width of the window.
uint16_t	height		height of the window.

InvalidateAll

InvalidateAll ... call this after resizing. Does nothing on Linux.

-- TODO -- avoid or rename this function.

Signature:

void uwin::InvalidateAll()

ResizeWindow

Resizes the main window.

Signature:

void uwin::ResizeWindow(uint16_t width,uint16_t height)

Parameters:

Type	Name	Direction	Description
uint16_t	width		width of the window.
uint16_t	height		height of the window.

MoveWindow

Moves the main window.

Signature:

void uwin::MoveWindow(int16_t posX,int16_t posY)

Parameters:

Type	Name	Direction	Description
int16_t	posX		x-position of the main window.
int16_t	posY		y-position of the main window.

getWindowDimensions

Returns the width and height of the main window.

Signature:

uint64_t uwin::getWindowDimensions()

getWindowPosition

Returns the x- and y-coordinates of the main window.

Signature:

uint64_t uwin::getWindowPosition()

getImageData

Returns a image of the contents of the main window.

Signature:

ImageData uwin::getImageData()

putImage

Updates the contents of the main window.

Signature:

void uwin::putImage()

putImagePadded

Updates the contents of the main window.
If the window is larger than the image to display, the function draws a padding on the left side and on the bottom to fill the client area of the window.

Signature:

void uwin::putImagePadded()

putRegion

Updates a region within the main window.

Signature:

void uwin::putRegion(CRegion *r)

Parameters:

Type	Name	Direction	Description
CRegion *	r	[IN]	The region within the main window, that should be updated.

putImageData

This function was intended to update the main window.
NOT IMPLEMENTED! THE FUNCTION DOES NOTHING!
Use functions putImage() or putImagePadded() instead.

Signature:

void uwin::putImageData(ImageData img)

Parameters:

Type	Name	Direction	Description
ImageData	img	[IN]	The ImageData.

getScreenDpiX

Returns the horizontal screen resolution in dots per inch (dpi).

This value is set while startup and will not be updated later.

Signature:

uint16_t uwin::getScreenDpiX()

getScreenDpiY

Returns the vertical screen resolution in dots per inch (dpi).

This value is set while startup and will not be updated later.

Signature:

uint16_t uwin::getScreenDpiY()