view release on metacpan or  search on metacpan

lib/IUP.pod  view on Meta::CPAN

All IUP elements are perl classes with C<new()> constructor. The are used in this way:

 my $button = IUP::Button->new( TITLE=>'Hello' ); # creating
 $button->SetAttribute('FGCOLOR', '255 128 128'); # calling a method

For more info see L<IUP::Manual::02_Elements|IUP::Manual::02_Elements>.
 
=head3 Using IUP in your perl program

By default, IUP doesn't import any other IUP related modules:

 # import IUP but don't import other modules
 use IUP;

You may, however, instruct IUP to import all modules by using the following syntax:

 # import IUP + all IUP::* modules - short, easy but memory consuming
 use IUP ':all';

Or you can import just basic elements (all except Matrix, Cells, Canvas, CanvasGL, PPlot, LayoutDialog, ElementPropertiesDialog)

 use IUP ':basic';

Or you can import just selected modules by using:

 # import IUP + IUP::Button and IUP::Menu
 use IUP qw(Button Menu);

Which is equivalent to:

 use IUP;
 use IUP::Button;
 use IUP::Menu;
 
B<IMPORTANT NOTE:> If you are the first time reader of this document at this point
you might wanna jumt to L<IUP::Manual::01_Introduction|IUP::Manual::01_Introduction>. The rest of this document is just
the reference list of all functions available in the main L<IUP|IUP> module.

=head1 GLOBAL FUNCTIONS

=head2 Handling IUP event loop

=head3 MainLoop()

=over

Executes the user interaction until a callback returns C<IUP_CLOSE>,
C<L<< IUP->ExitLoop|/"ExitLoop" >>> is called, or hiding the last visible dialog.

 IUP->MainLoop();

B<Returns:> Always C<IUP_NOERROR>

B<Notes:>

When this function is called, it will interrupt the program execution
until a callback returns C<IUP_CLOSE>, C<L<< IUP->ExitLoop|/"ExitLoop" >>> is called, 
or there are no visible dialogs.

If you cascade many calls to C<L<< IUP->MainLoop|/"MainLoop" >>> there must be a C<return
IUP_CLOSE> or C<L<< IUP->ExitLoop|/"ExitLoop" >>> call for each cascade level, hidding all
dialogs will close only one level. Call C<L<< IUP->MainLoopLevel|/"MainLoopLevel" >>>
to obtain the current level.

If C<L<< IUP->MainLoop|/"MainLoop" >>> is called without any visible dialogs and no active
timers, the application will hang and will not be possible to close the
main loop. The process will have to be interrupted by the system.

When the last visible dialog is hidden the C<L<< IUP->ExitLoop|/"ExitLoop" >>> function is
automatically called, causing the C<L<< IUP->MainLoop|/"MainLoop" >>> to return. To avoid
that set global attribute C<LOCKLOOP> to C<"YES"> before hiding the last dialog.

B<See Also:>
L<Open|/"Open()"> (global method),
L<Close|/"Close()"> (global method),
L<LoopStep|/"LoopStep()"> (global method),
L<ExitLoop|/"ExitLoop()"> (global method),
L<IDLE_ACTION|IUP::Manual::04_Callbacks/"IDLE_ACTION"> (callback),
L<LOCKLOOP|IUP::Manual::03_Attributes/"LOCKLOOP"> (attribute).
 
=back

=head3 MainLoopLevel()

=over

Returns the current cascade level of C<L<< IUP->MainLoop|/"MainLoop" >>>. 
When no calls were done, return value is 0.

 IUP->MainLoopLevel();

B<Returns:> the cascade level

B<Notes:>

You can use this function to check if C<L<< IUP->MainLoop|/"MainLoop" >>> was already called
and avoid calling it again.

A call to C<L<< $element->Popup|IUP::Manual::02_Elements/"Popup" >>> will increase one level.

B<See Also:>
L<Open|/"Open()"> (global function),
L<Close|/"Close()"> (global function),
L<LoopStep|/"LoopStep()"> (global function),
L<IDLE_ACTION|IUP::Manual::04_Callbacks/"IDLE_ACTION"> (callback),
L<LOCKLOOP|IUP::Manual::03_Attributes/"LOCKLOOP"> (attribute).

=back

=head3 LoopStep()

=over

 IUP->LoopStep();

See L<LoopStepWait|/"LoopStepWait()">.

=back

=head3 LoopStepWait()

=over

Runs one iteration of the message loop.

 IUP->LoopStepWait();

B<Returns:> C<IUP_CLOSE> or C<IUP_DEFAULT>

B<Notes:>

This function is useful for allowing a second message loop to be
managed by the application itself. This means that messages can be
intercepted and callbacks can be processed inside an application loop.

C<L<< IUP->LoopStep|/"LoopStep()" >>> returns immediately after processing any messages or if
there are no messages to process. C<L<< IUP->LoopStepWait|/"LoopStepWait()" >>> put the system in
idle until a message is processed .

If C<IUP_CLOSE> is returned the C<L<< IUP->MainLoop|/"MainLoop" >>> will not end because the
return code was already processed. If you want to end C<L<< IUP->MainLoop|/"MainLoop" >>>
when C<IUP_CLOSE> is returned by C<L<< IUP->LoopStep|/"LoopStep()" >>> then call C<L<< IUP->ExitLoop|/"ExitLoop()" >>>
after C<L<< IUP->LoopStep|/"LoopStep()" >>> returns.

An example of how to use this function is a counter that can be stopped
by the user. For such, the user has to interact with the system, which
is possible by calling the function periodically.

This way, this function replaces old mechanisms implemented using the
Idle callback.

Note that this function does not replace C<L<< IUP->MainLoop|/"MainLoop()" >>>.