view release on metacpan or  search on metacpan

lib/Fl/InputChoice.pod  view on Meta::CPAN

class 'Fl::InputChoice';
isa 'Fl::Group';
include 'FL/Fl_Input_Choice.H';
widget_type 'Fl_Input_Choice';

=pod

=head1 NAME

Fl::InputChoice - Combination of the Input Widget and a Menu Button

=head1 Description

The Fl::InputChoice is a combination of the input widget and a menu button.

=for html <center><img src="http://www.fltk.org/doc-1.3/input_choice.jpg" /></center>

The user can either type into the input area, or use the menu button chooser
on the right to choose an item which loads the input area with the selected
text.

The application can directly access both the internal Fl::Input and
Fl::MenuButton widgets respectively using the input() and menubutton()
accessor methods.

A full example of this widget can be found in C<eg/input_choice.pl>

=head1 Methods

Fl::InputChoice inherits from Fl::Group and Fl::Widget. On top of that, it
exposes the following methods...

=head2 new(...)

    my $ic_a = Fl::InputChoice->new(0, 0, 250, 500, 'Important Stuff');
    my $ic_b = Fl::InputChoice->new(0, 0, 250, 500);

The constructor creates a new widget using the given position, size, and
label.

The destructor removes the widget.

=cut

xs {name        => 'new',
    definitions => [
            {required => [[qw[int x]], [qw[int y]], [qw[int w]], [qw[int h]]],
             optional => [['const char *', 'label', ' 0']],
             returns  => 'Fl_Input_Choice *'
            }
    ]
};
xs {name        => 'DESTROY',
    definitions => [{returns => 'void'}]
};
xs {name        => 'draw',
    definitions => [{returns  => 'void' }
    ]
};
xs {name        => 'handle',
    definitions => [{required => [[qw[int event]]], returns  => 'int'  }
    ]
};

=pod

=head2 add(...)

Add an item to the menu.

You can access the more complex C<<Fl::MenuButton->add()>> methods (setting
callbacks, userdata, etc.) via C<menubutton()>.

Example:

    my $choice = Fl::InputChoice->new(100,10,120,25,"Fonts");
    my $mb = $choice->menubutton(); # use Fl::InputChoice's Fl::MenuButton
    $mb->add("Helvetica", 0, \&MyFont_CB); # use Fl::MenuButton's add() methods
    $mb->add("Courier",   0, \&MyFont_CB);
    $mb->add("More..",    0, \&FontDialog_CB);

=cut

xs {name        => 'add',
    definitions => [
        {required => [['const char *', 's']]}
    ]
};

=pod

=head2 changed(...)

    my $changed = $ic_a->changed();

Returns the combined changed() state of the input and menu button widget.

=cut

xs {name        => 'changed',
    definitions => [
        {returns  => 'int'}
    ]
};

=pod

=head2 clear(...)

    $ic_a->clear( );

Removes all items from the menu.

=cut

xs {name        => 'clear',
    definitions => [
        {returns  => 'void'}
    ]
};

=pod

=head2 clear_changed(...)

    $ic_a->clear_changed( );

Clears the changed() state of both input and menu button widgets.

=cut

xs {name        => 'clear_changed',
    definitions => [
        {returns  => 'void'}
    ]
};

=pod

=head2 input(...)

    my $input = $ic_a->input( );

Returns a pointer to the internal Fl::Input widget.

This can be used to directly access all of the Fl::Input widget's methods.

=cut

xs {name        => 'input',
    definitions => [
        {returns  => 'Fl_Input *'}
    ]
};

=pod

=head2 menu(...)

    my $mn_item = $ic_a->menu( );
    $ic_b->menu( $mn_item );

Gets or sets the Fl_Menu_Item array used for the menu.

=cut

xs {name        => 'menu',
    definitions => [
        {c_args   => '(const Fl_Menu_Item *) mnu->cp_ctx',required  => [['Fl_Menu_Item *', 'mnu']]},
        {returns   => 'const Fl_Menu_Item *'}
    ]
};

=pod

=head2 menubutton( )

    my $mn_btn = $ic_a->menubutton( );

Returns a pointer to the internal Fl::MenuButton widget.

This can be used to access any of the methods of the menu button, e.g.

    my $choice = Fl::InputChoice->(100, 10, 120, 25, "Choice:");
    ...
    # Print all the items in the choice menu
    for ( my $t = 0; $t < $choice->menubutton()->size(); $t++ ) {
        my $item = $choice->menubutton->menu->[$t];
        printf("item %d -- label=%s\n", $t, $item->label ? $item->label : '(Null)');
    }

=cut

xs {name        => 'menubutton',
    definitions => [
        {returns=> 'Fl_Menu_Button *'}
    ]
};

=pod

=head2 resize( ... )

    $ic_a->menubutton( int x, int y, int w, int h );

Resizes the Fl::Group widget and all of its children.

The Fl::Group widget first resizes itself, and then it moves and resizes all
its children according to the rules documented for
C<<Fl::Group->resizable($widget)>>.

=cut

xs {name        => 'resize',
    definitions => [
        {required  => [[qw[int X]], [qw[int Y]], [qw[int W]], [qw[int H]]]},
    ]
};

=pod

=head2 set_changed( )

    $ic_a->set_changed( );

Sets the changed() state of both input and menu button widgets to the specfied
value.

=cut

xs {name        => 'set_changed',
    definitions => [
        {returns => 'void'}
    ]
};

=pod

=head2 value( ... )

    $ic_a->value( 1 );
    $ic_b->value( "One" );

Sets the Fl::Input text field's contents.

If this is a string, it does not affect the menu selection.

If this is an integer, item number $index is chosen in the menu and the
Fl::Input text field is set to that value. Any previous text is cleared.

=cut

xs {name        => 'value',
    definitions => [
        {required => [['int', 'val']], andif => 'SvIOK(ST(1))'},
        {required => [['const char *', 'val']]}