cwidget 0.5.16
Classes | Functions | Variables

cwidget::toplevel Namespace Reference

The namespace containing functions to manage the global state of cwidget. More...

Classes

class  event
 An event in the global event queue. More...
class  slot_event
 An event based on sigc++ slots. More...

Functions

threads::mutexget_mutex ()
int get_suspend_count ()
void inc_suspend_count ()
widget_ref settoplevel (const widget_ref &w)
void post_event (event *ev)
 Post the given event to the main event queue.
int write (int fd, const char *s)
void init ()
 Initializes curses and the global state of the cwidget library.
void install_sighandlers ()
 Installs signal handlers to cleanly shut down cwidget.
void handleresize ()
void updatecursor ()
 Posts a request to update the cursor location; may be called from any thread.
void updatecursornow ()
void update ()
 Posts a request to redraw the screen; may be called from any thread.
void updatenow ()
void queuelayout ()
 Posts a request to recalculate every widget's layout and update the screen.
void layoutnow ()
 Immediately recalculates the layout of all widgets.
void tryupdate ()
 Executes any pending draws or redraws.
bool poll ()
 Dispatch any events in the event queue.
void mainloop (int synch=0)
 Start the main event loop.
void exitmain ()
void suspend_without_signals ()
 Hides all widgets and suspends Curses operation until resume() is called, but does NOT reset the SIGCONT and SIGTSTP handlers.
void suspend ()
 Hides all widgets and suspends Curses operation until resume() is called.
void shutdown ()
 Does the same thing as suspend, except that it also destroys the top-level widget.
void resume ()
 Returns to Curses mode after a suspend*, restoring any signal handlers that were modified by the suspend routine.
void redraw ()
int addtimeout (event *ev, int msecs)
 Invoke the given event in at least msecs from the current time.
void deltimeout (int id)
 Delete the event with the given identifier.
util::ref_ptr< widgets::widgetsettoplevel (const util::ref_ptr< widgets::widget > &widget)
 Sets the top-level widget to the new value, returning the old top-level widget.

Variables

sigc::signal0< void > main_hook
threads::recursive_mutex pending_updates_mutex
update_state pending_updates

Detailed Description

The namespace containing functions to manage the global state of cwidget.

Routines in this namespace handle initializing and shutting down cwidget, running its main loop, setting the top-level widget, and other functions related to the top-level control structures of the library.


Function Documentation

int cwidget::toplevel::addtimeout ( event *  ev,
int  msecs 
)

Invoke the given event in at least msecs from the current time.

Returns:
a numerical identifier of the new event; you can use this number to delete it.
void cwidget::toplevel::deltimeout ( int  id)

Delete the event with the given identifier.

int cwidget::toplevel::get_suspend_count ( ) [inline]
Returns:
the number of times that toplevel::suspend has been invoked since toplevel::init was invoked.

This can be used to detect when a suspend has occurred between when an event was posted and when it fired. For instance, the input thread generates events that actually read from stdin, but if one of them fires after a suspend, the thread will get confused about how many events are trying to read and end up reading too many times and blowing up.

void cwidget::toplevel::install_sighandlers ( )

Installs signal handlers to cleanly shut down cwidget.

This is always invoked by cwidget::toplevel::init(). However, you might want to invoke it manually if you have removed the cwidget signal handlers (for instance, in order to invoke an external program).

Installs signal handlers for TERM, INT, QUIT, SEGV, and ABRT which restore the terminal and exit the program.

Referenced by init().

void cwidget::toplevel::layoutnow ( )

Immediately recalculates the layout of all widgets.

Referenced by tryupdate().

void cwidget::toplevel::mainloop ( int  synch = 0)

Start the main event loop.

This routine repeatedly removes events from the global queue and invokes event::dispatch() on them. It terminates when exitmain() is invoked or when an exception is thrown. In particular, callers should be prepared to catch cwidget::util::Exception instances:

catch(cwidget::util::Exception &e) { }

If an exception is thrown, the caller is responsible for invoking cwidget::toplevel::shutdown() to restore the terminal state. A simple way of testing that your code catches exceptions correctly is to redirect stdin from /dev/null; this will throw an exception stating that the program cannot read from stdin.

Parameters:
synchIgnored; it is present for historical reasons and will be removed in a future release of cwidget.

References cwidget::threads::mutex::lock::acquire(), and cwidget::threads::mutex::lock::release().

bool cwidget::toplevel::poll ( )

Dispatch any events in the event queue.

This is deprecated in favor of the more reliable approach of using threads and post_event.

Returns:
true if pending input was found.
void cwidget::toplevel::post_event ( event *  ev)

Post the given event to the main event queue.

When the event comes off the queue, its dispatch method will be invoked and it will immediately be destroyed.

This method is thread-safe and is the main mechanism by which other threads should communicate with the main thread.

Referenced by queuelayout(), and update().

void cwidget::toplevel::queuelayout ( )

Posts a request to recalculate every widget's layout and update the screen.

May be called from any thread.

References post_event().

Referenced by cwidget::widgets::text_layout::append_fragment(), cwidget::widgets::editline::handle_key(), and cwidget::widgets::text_layout::set_fragment().

util::ref_ptr< widgets::widget > cwidget::toplevel::settoplevel ( const util::ref_ptr< widgets::widget > &  widget)

Sets the top-level widget to the new value, returning the old top-level widget.

If the top-level widget is to be destroyed, IT IS THE CALLER'S RESPONSIBILITY TO CALL destroy() BEFORE DISCARDING THE REFERENCE!

Referenced by init().

void cwidget::toplevel::shutdown ( )

Does the same thing as suspend, except that it also destroys the top-level widget.

Call this when the program is exiting.

References suspend().

void cwidget::toplevel::suspend ( )

Hides all widgets and suspends Curses operation until resume() is called.

In addition, sets SIGCONT and SIGTSTP to SIG_DFL (appropriate if you'll be running subprocesses); resume() will restore these handlers.

References suspend_without_signals().

Referenced by shutdown().

void cwidget::toplevel::tryupdate ( )

Executes any pending draws or redraws.

References layoutnow().

void cwidget::toplevel::update ( )