.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "POE 3"
.TH POE 3 2023-07-25 "perl v5.38.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Curses::UI::POE \- A subclass makes Curses::UI POE Friendly.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& use Curses::UI::POE;
\&
\& my $cui = new Curses::UI::POE inline_states => {
\&     _start => sub {
\&         $_[HEAP]\->dialog("Hello!");
\&     },
\&
\&     _stop => sub {
\&         $_[HEAP]\->dialog("Good bye!");
\&     },
\& };
\&
\& $cui\->mainloop
.Ve
.SH INTRODUCTION
.IX Header "INTRODUCTION"
This is a subclass for Curses::UI that enables it to work with POE.
It is designed to simply slide over Curses::UI.  Keeping the API the
same and simply forcing Curses::UI to do all of its event handling
via POE, instead of internal to itself.  This allows you to use POE
behind the scenes for things like networking clients, without Curses::UI
breaking your programs' functionality.
.SH ADDITIONS
.IX Header "ADDITIONS"
This is a list of distinct changes between the Curses::UI API, and the
Curses::UI::POE API.  They should all be non-obstructive additions only,
keeping Curses::UI::POE a drop-in replacement for Curses::UI.
.SS "Constructor Options"
.IX Subsection "Constructor Options"
.IP inline_states 2
.IX Item "inline_states"
The inline_states constructor option allows insertion of inline states
into the Curses::UI::POE controlling session.  Since Curses::UI::POE is
implimented with a small session I figured it may be useful provide the
ability to the controlling session for all POE to Interface interaction.
.Sp
While Curses::UI events are still seamlessly forced to use POE, this allows
you to use it for a little bit more, such as catching responses from another
POE component that should be directly connected with output.  (See the IRC
client example).
.Sp
In this controlling session, however, the heap is predefined as the root
Curses::UI object, which is a hash reference.  In the Curses::UI object,
all private data is indexed by a key begining with "\-".  So if you wish
to use the heap to store other data, simply dont use the "\-" hash index
prefix to avoid conflicts.
.SH TIMERS
.IX Header "TIMERS"
The undocumented Curses::UI timers ($cui\->timer) will still work, and
they will be translated into POE delays.  I would suggest not using them,
however, as POE's internal alarms and delays are far more robust.
.SH DIALOGS
.IX Header "DIALOGS"
The Curses::UI::POE dialog methods contain thier own miniature event loop,
similar to the way Curses::UI's dialog methods worked.  However instead
of blocking and polling on readkeys, it incites its own custom miniature
POE Event loop until the dialog has completed, and then its result is
returned as per the Curses::UI specifications.
.SH MODALITY
.IX Header "MODALITY"
Curses::UI::POE builds its own internal modality structure.  This allows
Curses::UI to manage it, and POE to issue the (hopefully correct) events.
To do this it uses its own custom (smaller) event loop, which is reentrant
into the POE::Loop in use (In this case, usually POE::Loop::Select).  This
way there can be several recursed layers of event loops, forcing focus on
the current modal widget, without stopping other POE::Sessions from running.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
POE, Curses::UI.  Use of this module requires understanding of both
the Curses::UI widget set and the POE Framework.
.SH BUGS
.IX Header "BUGS"
.IP "Dialogs before \->\fBmainloop()\fR" 2
.IX Item "Dialogs before ->mainloop()"
Dialogs before Curses::UI::Mainloop
.PP
Find more?  Send them to me!  tag@cpan.org
.SH AUTHOR
.IX Header "AUTHOR"
.IP "Rocco Caputo (rcaputo@cpan.org)" 2
.IX Item "Rocco Caputo (rcaputo@cpan.org)"
Rocco has helped in an astronomical number of ways.  He helped me work out
a number of issues (including how to do this in the first place) and atleast
half the code if not more came from his fingertips.
.SH MAINTAINER
.IX Header "MAINTAINER"
.IP "Scott McCoy (tag@cpan.org)" 2
.IX Item "Scott McCoy (tag@cpan.org)"
This was my stupid idea.  I also got to maintain it, although the original
code (some of which may or may not still exist) came from Rocco.