ubit::UAppli Class Reference

The Application Context. More...

#include <uappli.hpp>

Inheritance diagram for ubit::UAppli:

List of all members.

Public Member Functions
	UAppli (int &argc, char **argv, UOption *command_line_options=null, const char *configuration_file=null)
	constructor for creating the Application Context.
virtual void	add (UWin &)
	adds a window (UFrame, UDialog) to the UAppli.
virtual void	remove (UWin &child, bool auto_delete)
	removes or deletes a window from the UAppli.
virtual void	updateAll (const UUpdate &upatemode=UUpdate::layoutAndPaint)
	updates all windows.
UNatAppli *	getNatAppli () const
	[impl] returns the Native Appli object.
UGroup *	getOpenedMenu ()
	[impl] returns the menu that is currently opened (null otherwise).
virtual bool	isRealized () const
	[impl] is the X data initialized?.
virtual void	realize ()
	[impl] allocates the graphical resources of the appli.
Static Public Member Functions
static bool	usingGL ()
	returns true if OpenGL is used for rendering.
static bool	using3D ()
	returns true if rendered in 3D (implies isUsingGL() = true).
static UAppli &	getApp () throw (UFatalError)
	returns the UAppli of the program.
static UFrame *	getMainFrame ()
	returns the Main Frame (if any, null otherwise).
static const UStr &	getName ()
	returns the name of the application (argv[0] by default).
static const char *	getVersion ()
	returns the PACKAGE_VERSION of the Ubit toolkit (for instance "5.0.0").
static void	setTitle (const UStr &title)
	changes the title of the Main Frame.
static const UStr &	getImaPath ()
static void	setImaPath (const UStr &pathname)
	get/set the default image path.
static USelection *	getSelection (int ID=0)
	returns the text selection.
static int	start ()
static int	mainLoop ()
	starts the event main loop of the application.
static void	quit (int status=0)
	quits the main loop of the application.
static bool	isRunning ()
static UTime	getTime ()
	returns the current time.
static void	setMotionLag (UTime app_lag, UTime nat_lag)
	changes the motion lag.
static void	error (const char *location, const char *format,...)
static void	warning (const char *location, const char *format,...)
static void	fatalError (const char *location, const char *format,...) throw (UFatalError)
	generate an error or a warning on the standard Error Flow .
static UStyleSheet &	getStyleSheet ()
	returns the style sheet of the application.
static const UStyle &	getDefaultStyle ()
	returns the default element style.
static void	postpone (UCall &callback)
	fire this callback when the main loop becomes idle.
static void	onTimeout (UTime msec_delay, int ntimes, UCall &callback)
	fire this callback after a given delay.
static void	onMessage (const UStr &port_name, UCall &callback)
	adds a callback that is fired when data is received on this port.
static UMessagePort &	getMessagePort (const UStr &name)
static UMessagePort *	findMessagePort (const UStr &name)
	Ubit Messages see onMessage() and class UMessagePort.
static const UDispList &	getDispList ()
static UDisp *	getDisp (int ID)
static UDisp *	openDisp (const UStr &display)
	opens a connection on another X display.
static void	closeDisp (UDisp *)
	closes a connection with another X display.
static const UFlowList &	getFlowList ()
	returns the list of all event flows on all displays (see getFlow()).
static UEventFlow *	getFlow (int ID)
	returns the Event Flow that have this ID (null if not found).
static bool	hasTelePointers ()
	[impl].
static bool	isTerminated ()
	[impl].
Static Public Attributes
static UConf	conf
	configuration of the application, must be set BEFORE the UAppli is created.
static UErrorLog	log
	the Error Log of the application.

---

Detailed Description

The Application Context.

A Ubit application must create one (and only one) UAppli object. This UAppli must be created as soon as the program is started by main() No Ubit function should be called before its creation nor after its deletion.

A UAppli can be parameterized:

• through command line options: see UAppli(argc, arv)
• by means of a UConf object: see UAppli(UConf&)

A UAppli can open windows on several Displays (that can be controlled by remote machines): see UAppli::openDisp()). Window children can be shared by windows that belong to different displays. These children are automatically replicated (and synchronized) on the corresponding displays.

A UAppli can manage 1 or several Event Flows that are comptelety separated. This is useful for Two-handed interaction or groupware (each user controlling his own pointer on the screen(s)). Alternate event flows are automatically created when the UMS (Ubit Mouse Server) is running (see the 'umsd' program in directory ubit/ums). The UMS can manage several sources of events and send them as separate event flows to the UAppli. These event sources can be produced by a mouse or a MIMIo on the serial port or by an application running on a remote machine (see the 'uremote' program in ubit/ums). Finally, Event flows can be uniquely identified in callback functions through the getFlow() method of their UEvent& argument.

Classes UTimer and UInput make it possible to fire callback functions after a given timeout or when the application receives data on a file source (such as a socket). UAppli::onTimeout() and UAppli::postpone() provide a simplified API for using timers. postpone() is used to fire CPU intensive methods when the event loop becomes idle.

Classes USocket and UServerSocket provide a simple mechanism to handle sockets. The are based on simple communication protocol that can be implemented in non Ubit programs. In addition, asynchronous messages can be exchanged between Ubit applications and the UMS server through the the UMessage protocol. See: UMessage, UAppli::onMessage() and UAppli::getMessagePort().

NOTE on colors: Ubit applications may not work properly on (obsolete) X11 displays that do not support True Colors. See UDisp::setTrueColors() and UDisp::setPseudoColors() for details.

See also the UDisp class for inherited methods.

---

Constructor & Destructor Documentation

ubit::UAppli::UAppli	(	int &	argc,
		char **	argv,
		UOption *	command_line_options = null,
		const char *	configuration_file = null
	)

constructor for creating the Application Context.

Arguments:

• 'argc' and 'argv' : the parameters of the main() function
• 'command_line_options' : optional command line options:

  See also:

  UConf for details

• 'configuration_file' : an optional configuration file:@see UConf for details

Exceptions:

• UError exception thrown if the X server can't be opened.

Command line options:

• see class UConf for details. Examples:

      $ myappli --help-x
      $ myappli --scale 0.75 --display hendrix.tsne.fr:0
  

  the first line prints out the help message. The second line specifies a rendering scale and a X server display name.

See also: UAppli::openDisp() and the man of classes UAppli and UDisp.

---

Member Function Documentation

void ubit::UAppli::add

(

UWin &

)

[virtual]

adds a window (UFrame, UDialog) to the UAppli.

notes:

• at least one Window (typically a UFrame) should be added to the Application Context.
• the "Main Frame" is the first UFrame that was added to the UAppli
• windows are initially hidden, their show() method must be called to make them visible
• window children should be added before calling the show() method (by default, window sizes won't change after this call) See also:
  • UGroup:add() and UGroup::addlist() for adding children
  • UWin:show() for showing windows
  • UWin:update() for updating geometry
  • the UWin, UFrame and UDialog classes.

Reimplemented from ubit::UDisp.

void ubit::UAppli::fatalError	(	const char *	location,
		const char *	format,
			...
	)			throw (UFatalError) [static]

generate an error or a warning on the standard Error Flow .

The default behavior of these functions is to display an error message on stderr except for fatalError that also throws a UError exception.

• 'location' = the location of the error (eg. "UBrick::addAttr")
• 'format' = a printf-like format
• '...' = a variadic list of arguments that correspond to 'format'. See also: UAppli::log.

UAppli & ubit::UAppli::getApp

(

)

throw (UFatalError) [static]

returns the UAppli of the program.

There is *only one* UAppli for a given program. Throws a UFatalError exception if the UAppli has not yet been created.

UEventFlow * ubit::UAppli::getFlow

(

int

ID

)

[static]

returns the Event Flow that have this ID (null if not found).

A UAppli can manage several separate Event Flows on 1 or multiple displays. This is useful for two-handed interaction or groupware.

See also:

UAppli for details.

Each event flow has a unique ID. 0 is the ID of the native event flow on the main display (ie. the default display of the UAppli). Don't confuse IDs with 'channels', which depend on displays (

See also:

UDisp::getDispFlow())

UFrame * ubit::UAppli::getMainFrame

(

)

[static]

returns the Main Frame (if any, null otherwise).

the main frame is the first UFrame that was added to the UAppli (if any)

USelection * ubit::UAppli::getSelection

(

int

ID = 0

)

[static]

returns the text selection.

return the text selection of the native event flow of the main display by default (ie. if ID = 0). However, an application may have several selections (it has as many selections as its number of event flows). The ID number then specifies the requested event flow.

See also:

: getFlow() for details

static int ubit::UAppli::mainLoop

(

)

[static]

starts the event main loop of the application.

returns the value given to UAppli::quit()

void ubit::UAppli::onMessage	(	const UStr &	port_name,
		UCall &	callback
	)			[static]

adds a callback that is fired when data is received on this port.

Ubit messages makes it simple to exchange data between applications. See class UMessagePort.

void ubit::UAppli::onTimeout	(	UTime	msec_delay,
		int	ntimes,
		UCall &	callback
	)			[static]

fire this callback after a given delay.

Args:

• 'delay' is in milliseconds. if 'delay' = 0, the timer is immediately fired when the main loop becomes idle.
• 'ntimes' specifies how many times the timer is fired (each time after the specified 'delay'). The timer will be fired repeatedly until the completion of the application if ntimes <= 0.
• 'callback' is a ucall<> expression (see UCall). It is destroyed after completion, except if "referenced elsewhere" (see UBrick). See also: postpone() and UTimer.

UDisp * ubit::UAppli::openDisp

(

const UStr &

display

)

[static]

opens a connection on another X display.

returns null if the connection failed. Otherwise, windows (UFrame, UDialog...) can be added to the returned UDisp by using its add() method.

• 'display' is the name of the X Window server. It follows the syntax: hostname[:display_no[:screen_no]] such as in: hendrix.tsne.fr:0.0
• window children can be shared by windows that belong to different displays. They are automatically replicated (and synchronized) on these displays.

void ubit::UAppli::postpone

(

UCall &

callback

)

[static]

fire this callback when the main loop becomes idle.

this function is useful:

• to postpone the execution of callbacks that take some time
• to request the execution of callbacks in the main thread from another thread 'callback' is a ucall<> expression (see UCall). It is destroyed after completion, except if "referenced elsewhere" (see UBrick). See also: onTimeout() and UTimer.

void ubit::UAppli::quit

(

int

status = 0

)

[static]

quits the main loop of the application.

UAppli::start() will return the 'status' value

void ubit::UAppli::remove	(	UWin &	child,
		bool	auto_delete
	)			[virtual]

removes or deletes a window from the UAppli.

arguments: see UGroup::remove() for details.

Reimplemented from ubit::UDisp.

void ubit::UAppli::setImaPath

(

const UStr &

pathname

)

[static]

get/set the default image path.

the default image pathn is prefixed to image file names that don't start with / or .

void ubit::UAppli::setMotionLag	(	UTime	app_lag,
		UTime	nat_lag
	)			[static]

changes the motion lag.

motion (drag, move) events are withdrawn if the time lag is hihgher than this value.

void ubit::UAppli::setTitle

(

const UStr &

title

)

[static]

changes the title of the Main Frame.

by default, the title of the Main Frame is the value of getName()

void ubit::UAppli::updateAll

(

const UUpdate &

upatemode = UUpdate::layoutAndPaint

)

[virtual]

updates all windows.

see UWin::update() for details.

---

Member Data Documentation

UConf ubit::UAppli::conf [static]

configuration of the application, must be set BEFORE the UAppli is created.

'conf' is an object that is created when the program is launched. Its fields:

• are initialized to default values by UConf::UConf()
• can be changed BEFORE the UAppli is created, typically in the main() function
• are modified when the UAppli instance is created, according to (argc, argv)

  See also:

  : UConf, UAppli::UAppli().

  also: UConf::parseOptions(), UConf::readConfFile().

UErrorLog ubit::UAppli::log [static]

the Error Log of the application.

see ULog::setHandler() to change its behavior. see also shortcuts UAppli::error(), UAppli::warning() etc. example:

   UAppli::log << UError("showData", "undefined data");

---

The documentation for this class was generated from the following files:

• uappli.hpp
• uappli.cpp

---