=for comment $Id: Options.pod,v 1.3 2006/04/12 20:00:06 robertemay Exp $

=head1 NAME

Win32::GUI::Reference::Options - Common Options

=head1 INTRODUCTION

This page details the options that are common to all 
packages, and may be used in most object's C<new()>
and L<Change()|Win32::GUI::Reference::Methods/Change>
mthods.

This document illustrates the options available when creating
an object (in particular, windows and controls).
Here you'll find the general options, the ones that apply to
every window class; for class-specific options, refer to that
package reference.

=head1 OPTIONS

=head2 -acceptfiles

=over

=item B<-acceptfiles> => 0/1

=back

Allow the window or control to act as a drop target for files
dragged from the shell.

=head2 -addexstyle

=over

=item B<-addexstyle> => NUMBER

=back

See L<-pushexstyle|/-pushexstyle>

=head2 -addstyle

=over

=item B<-addstyle> => NUMBER

=back

See L<-pushstyle|/-pushstyle>

=head2 -background

=over

=item B<-background> => COLOR

=back

Defines the background color for the control.
Note that not all controls support background and foreground
colors.

=head2 -caption

=over

=item B<-caption> => STRING

=back

See L<-text|/-text>

=head2 -class

=over

=item B<-class> => CLASS

=back

Specifies the window class (which is different
from the Perl's object class, eg. Win32::GUI::Button) for
the window; all the predefined objects have hardcoded class
names (eg. "BUTTON" for Win32::GUI::Button), so you shouldn't
want to pick a different one unless you are familiar with
window classes and you want to subclass an existing one.
This technique is documented in the Microsoft Platform SDK 
Reference.  The CLASS parameter can be either a name or a reference
to a L<Win32::GUI::Class|Win32::GUI::Class> object. 

=head2 -container

=over

=item B<-container> => 0/1

=back

[TBD]

=head2 -cursor

=over

=item B<-cursor> => CURSOR

=back

Defines the default cursor for the control; must be a L<Win32::GUI::Cursor|Win32::GUI::Cursor>
object, or a windows HCURSOR handle.

=head2 -disabled

=over

=item B<-disabled> => 0/1

=back

Sets the initial enabled state for the control; by default
this option is 0 (the control is enabled). Set it to 1
to create a control which is initially disabled.

=head2 -eventmodel

=over

=item B<-eventmodel> => STRING

=back

Sets the event model from the window or control. Can be one of the following
values:
  "byname" - the default.  Set the OEM (old event model) where events cause
             callback to the subroutine named OBJECTNAME_EVENTNAME()
  "byref"  - Set automatically when one of the L<-on*|/-onEVENT> event handlers is used.
             Sets the NEM (new event model) where the L<-on*|/-onEVENT> option
             is used to specify the callback subroutine explicitly.
  "both"   - Sets both OEM and NEM.  USeful if you want to handle one event with the NEM,
             and another event with OEM.

=head2 -events

=over

=item B<-events> => NUMBER

=back

[TBD]

=head2 -exstyle

=over

=item B<-exstyle> => NUMBER

=back

Sets the extended style for the window.  Use of this option is
deprecated.  Use L<-pushexstyle|/-pushexstyle> or L<-popexstyle|/-popexstyle>
(or one of their alternatives) instead.

=head2 -font

=over

=item B<-font> => FONT

=back

Defines the default font for the control; must be a L<Win32::GUI::Font|Win32::GUI::Font>
object, or a windows HFONT handle.

=head2 -foreground

=over

=item B<-foreground> => COLOR

=back

Defines the foreground color for the control.
Note that not all controls support background and foreground
colors.

=head2 -group

=over

=item B<-group> => 0/1

=back

[TBD]

=head2 -height

=over

=item B<-height> => NUMBER

=back

Specifies the height of the window or control in pixels.

=head2 -hscroll

=over

=item B<-hscroll> => 0/1

=back

[TBD]

=head2 -instance

=over

=item B<-instance> => HINSTANCE

=back

[TBD]

=head2 -left

=over

=item B<-left> => NUMBER

=back

Specifies the left position (X coordinate) for the window,
in pixels. For Windows and DialogBoxes is absolute (screen
position), while for controls is relative to the client
area of their parent window.

=head2 -menu

=over

=item B<-menu> => MENU

=back

Specifies a L<Win32::GUI::Menu|Win32::GUI::Menu> object or a
Windows HMENU handle for a window menu to be associated with the
window.  Only top-level windows can display window menus

=head2 -name

=over

=item B<-name> => STRING

=back

Defines the name for the window or control. The name is used to callback its events and 
to access its methods, so it is absolutely B<necessary> when using the OEM.
If not supplied, a system generated value will be used.  If supplied each
name must be unique in your application. 

Example: 

    $Window->AddButton(
        -name => "Button1",
        # ...
    );

    # methods...
    $Window->Button1->Hide();


    # events...
    sub Button1_Click {
        # ...
    }

=head2 -negexstyle

=over

=item B<-negexstyle> => NUMBER

=back

See L<-popexstyle|/-popexstyle>

=head2 -negstyle

=over

=item B<-negstyle> => NUMBER

=back

See L<-popstyle|/-popstyle>

=head2 -notexstyle

=over

=item B<-notexstyle> => NUMBER

=back

See L<-popexstyle|/-popexstyle>

=head2 -notstyle

=over

=item B<-notstyle> => NUMBER

=back

See L<-popstyle|/-popstyle>

=head2 -onEVENT

=over

=item B<-onEVENT> => SUB

=back

Sets the NEM (new event model) where the subroutine called when
an event occurs is explicitly given to this option.

B<SUB> is a subroutine name or a reference to a subroutine.

B<EVENT> is one of the events supported by the window/control.
(e.g. 'Click', 'Terminate', ...)

Setting this option prevents this control calling subroutines of the form
OBJECTNAME_EVENTNAME() - See L<-eventmodel|/-eventmodel>.

The first parameter passed to the subroutine is a reference to the object
on which the event occured.

Eample:

  ...
  my $button = Win32::GUI::Button->new(
    -text = "Click me!",
    -onClick => sub { print "Button Clicked\n"; },
  );
  ...

=head2 -parent

=over

=item B<-parent> => WINDOW

=back

Sets the parent window of the window/control being created.
WINDOW must be a Win32::GUI Window or Control object, or
a windows HWND handle.

=head2 -popexstyle

=over

=item B<-popexstyle> => NUMBER

=back

Remove the specified extended styles from the window's extended style mask.
This option can be repeated multiple times, or values can be
'or'ed together.

=head2 -popstyle

=over

=item B<-popstyle> => NUMBER

=back

Remove the specified styles from the window's style mask.
This option can be repeated multiple times, or values can be
'or'ed together.

=head2 -pos

=over

=item B<-pos> => [ X, Y ]

=back

Defines the position for the window or control; note that X and Y must be passed in an
array reference, eg:

    -pos => [ 100, 100 ],    # correct
    -pos =>   100, 100,      # WRONG
    -pos => @coords,         # WRONG
    -pos => \@coors,         # correct

=head2 -pushexstyle

=over

=item B<-pushexstyle> => NUMBER

=back

Add the specified extended styles to the window's extended style mask.
This option can be repeated multiple times, or values can be
'or'ed together.

=head2 -pushstyle

=over

=item B<-pushstyle> => NUMBER

=back

Add the specified styles to the window's style mask.
This option can be repeated multiple times, or values can be
'or'ed together.

=head2 -remexstyle

=over

=item B<-remexstyle> => NUMBER

=back

See L<-popexstyle|/-popexstyle>

=head2 -remstyle

=over

=item B<-remstyle> => NUMBER

=back

See L<-popstyle|/-popstyle>

=head2 -size

=over

=item B<-size> => [ X, Y ]

=back

Defines the size for the window; note that X and Y must be passed in an
array reference, eg:

    -size => [ 100, 100 ],    # correct
    -size =>   100, 100,      # WRONG
    -size => @coords,         # WRONG
    -size => \@coors,         # correct

=head2 -style

=over

=item B<-style> => NUMBER

=back

Sets the style for the window.  Use of this option is
deprecated.  Use L<-pushstyle|/-pushstyle> or L<-popstyle|/-popstyle>
(or one of their alternatives) instead.

=head2 -tabstop

=over

=item B<-tabstop> => 0/1

=back

If 1, the control can be enabled by pressing
the TAB key to switch between controls.
Note that this functionality is available
in dialog objects only,
so the control must be child of a DialogBox
or a Window with the C<-dialogui> option set
for this option to be effective.

=head2 -text

=over

=item B<-text> => STRING

=back

Specifies the STRING that will appear on
the window's caption or in the control's body (eg. a
Label text, a Button caption, a Textfield content, and
so on). Its use depends of course on the control type;
some controls, like ProgressBars, makes no use of it
at all.

=head2 -tip

=over

=item B<-tip> => STRING

=back

B<STRING> specifies the text that will appear in a tooltip when the
mouse hovers over the window/control.  This option provides a simple,
but non-flexible way to add tooltips to windows.  For better
flexibility see L<Win32::GUI::Tooltip|Win32::GUI::Tooltip>.

=head2 -title

=over

=item B<-title> => STRING

=back

See L<-text|/-text>

=head2 -top

=over

=item B<-top> => NUMBER

=back

Specifies the top position (Y coordinate) for the window,
in pixels. For Windows and DialogBoxes is absolute (screen
position), while for controls is relative to the client
area of their parent window.

=head2 -visible

=over

=item B<-visible> => 0/1

=back

Sets the visibility of a window/control (and its children).

=head2 -vscroll

=over

=item B<-vscroll> => 0/1

=back

[TBD]

=head2 -width

=over

=item B<-width> => NUMBER

=back

Specifies the width of the window or control in pixels.

__W32G_POSTAMBLE__