cwidget  0.5.17
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. More...
 
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. More...
 
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. More...
 
void updatenow ()
 
void queuelayout ()
 Posts a request to recalculate every widget's layout and update the screen. More...
 
void layoutnow ()
 Immediately recalculates the layout of all widgets. More...
 
void tryupdate ()
 Executes any pending draws or redraws. More...
 
bool poll ()
 Dispatch any events in the event queue. More...
 
void mainloop (int synch=0)
 Start the main event loop. More...
 
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. More...
 
void shutdown ()
 Does the same thing as suspend, except that it also destroys the top-level widget. More...
 
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. More...
 
void deltimeout (int id)
 Delete the event with the given identifier. More...
 
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. More...
 

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

◆ addtimeout()

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.

References addtimeout().

Referenced by addtimeout().

◆ deltimeout()

void cwidget::toplevel::deltimeout ( int  id)

Delete the event with the given identifier.

References deltimeout().

Referenced by deltimeout().

◆ get_suspend_count()

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.

References get_suspend_count(), settoplevel(), and update().

Referenced by get_suspend_count(), and post_event().

◆ install_sighandlers()

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.

References install_sighandlers(), and tryupdate().

Referenced by init(), and install_sighandlers().

◆ layoutnow()

void cwidget::toplevel::layoutnow ( )

Immediately recalculates the layout of all widgets.

References layoutnow().

Referenced by layoutnow(), and tryupdate().

◆ mainloop()

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(), cwidget::threads::event_queue< T >::get(), mainloop(), cwidget::threads::mutex::lock::release(), and cwidget::threads::event_queue< T >::try_get().

Referenced by mainloop().

◆ poll()

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.

References poll(), and cwidget::threads::event_queue< T >::try_get().

Referenced by poll().

◆ post_event()

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.

References cwidget::threads::thread::cancel(), get_suspend_count(), cwidget::config::global_bindings, cwidget::threads::thread::join(), cwidget::config::keybindings::key_matches(), post_event(), cwidget::threads::event_queue< T >::put(), cwidget::threads::mutex::lock::release(), cwidget::util::sstrerror(), cwidget::threads::condition::timed_wait(), and cwidget::threads::condition::wait().

Referenced by post_event(), queuelayout(), and update().

◆ queuelayout()

void cwidget::toplevel::queuelayout ( )

◆ settoplevel()

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 get_suspend_count(), and init().

◆ shutdown()

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 cwidget::widgets::widget::destroy(), shutdown(), suspend(), and cwidget::threads::event_queue< T >::try_get().

Referenced by shutdown().

◆ 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(), and suspend_without_signals().

Referenced by shutdown(), and suspend().

◆ tryupdate()

void cwidget::toplevel::tryupdate ( )

Executes any pending draws or redraws.

References layoutnow(), and tryupdate().

Referenced by install_sighandlers(), and tryupdate().

◆ update()

void cwidget::toplevel::update ( )

Posts a request to redraw the screen; may be called from any thread.

References cwidget::widgets::widget::display(), cwidget::get_style(), post_event(), and update().

Referenced by cwidget::widgets::multiplex::add_widget(), cwidget::widgets::text_layout::append_fragment(), cwidget::widgets::button::button(), cwidget::widgets::stacked::destroy(), cwidget::widgets::minibuf_win::destroy(), cwidget::widgets::menubar::destroy(), get_suspend_count(), cwidget::widgets::tree::handle_key(), cwidget::widgets::menubar::handle_key(), cwidget::widgets::editline::handle_key(), cwidget::widgets::scrollbar::height_request(), cwidget::widgets::menubar::height_request(), cwidget::widgets::tree::height_request(), cwidget::widgets::menu::height_request(), cwidget::widgets::menu::menu(), cwidget::widgets::menu::move_selection_bottom(), cwidget::widgets::menu::move_selection_down(), cwidget::widgets::menu::move_selection_top(), cwidget::widgets::menu::move_selection_up(), cwidget::widgets::togglebutton::paint(), cwidget::widgets::menubar::paint(), cwidget::widgets::editline::paint(), cwidget::widgets::pager::scroll_bottom(), cwidget::widgets::pager::scroll_down(), cwidget::widgets::pager::scroll_left(), cwidget::widgets::pager::scroll_page(), cwidget::widgets::pager::scroll_right(), cwidget::widgets::pager::scroll_top(), cwidget::widgets::pager::scroll_up(), cwidget::widgets::table::set_colsep(), cwidget::widgets::table::set_rowsep(), cwidget::widgets::tree::set_selection(), cwidget::widgets::multiplex::show_all(), cwidget::widgets::tree::unhighlight_current(), and update().