The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

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

INTRODUCTION

This page details the options that are common to all packages, and may be used in most object's new() and 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.

OPTIONS

-acceptfiles

-acceptfiles => 0/1

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

-addexstyle

-addexstyle => NUMBER

See -pushexstyle

-addstyle

-addstyle => NUMBER

See -pushstyle

-background

-background => COLOR

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

-caption

-caption => STRING

See -text

-class

-class => CLASS

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 Win32::GUI::Class object.

-container

-container => 0/1

[TBD]

-cursor

-cursor => CURSOR

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

-disabled

-disabled => 0/1

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.

-eventmodel

-eventmodel => STRING

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 -on* event handlers is used. Sets the NEM (new event model) where the -on* 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.

-events

-events => NUMBER

[TBD]

-exstyle

-exstyle => NUMBER

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

-font

-font => FONT

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

-foreground

-foreground => COLOR

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

-group

-group => 0/1

[TBD]

-height

-height => NUMBER

Specifies the height of the window or control in pixels.

-hscroll

-hscroll => 0/1

[TBD]

-instance

-instance => HINSTANCE

[TBD]

-left

-left => NUMBER

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.

-menu

-menu => MENU

Specifies a 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

-name

-name => STRING

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 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 {
        # ...
    }

-negexstyle

-negexstyle => NUMBER

See -popexstyle

-negstyle

-negstyle => NUMBER

See -popstyle

-notexstyle

-notexstyle => NUMBER

See -popexstyle

-notstyle

-notstyle => NUMBER

See -popstyle

-onEVENT

-onEVENT => SUB

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

SUB is a subroutine name or a reference to a subroutine.

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 -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"; },
  );
  ...

-parent

-parent => WINDOW

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.

-popexstyle

-popexstyle => NUMBER

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.

-popstyle

-popstyle => NUMBER

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

-pos

-pos => [ X, Y ]

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

-pushexstyle

-pushexstyle => NUMBER

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.

-pushstyle

-pushstyle => NUMBER

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

-remexstyle

-remexstyle => NUMBER

See -popexstyle

-remstyle

-remstyle => NUMBER

See -popstyle

-size

-size => [ X, Y ]

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

-style

-style => NUMBER

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

-tabstop

-tabstop => 0/1

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 -dialogui option set for this option to be effective.

-text

-text => STRING

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.

-tip

-tip => STRING

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 Win32::GUI::Tooltip.

-title

-title => STRING

See -text

-top

-top => NUMBER

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.

-visible

-visible => 0/1

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

-vscroll

-vscroll => 0/1

[TBD]

-width

-width => NUMBER

Specifies the width of the window or control in pixels.

VERSION

Documentation for Win32::GUI v1.08_09 created 04 Nov 2014

This document is autogenerated by the build process. Edits made here will be lost. Edit docs/GUI/Reference/Options.pod instead.

SUPPORT

Homepage: http://perl-win32-gui.sourceforge.net/.

For further support join the users mailing list from the website at http://lists.sourceforge.net/lists/listinfo/perl-win32-gui-users. There is a searchable list archive at http://sourceforge.net/p/perl-win32-gui/mailman/perl-win32-gui-users/.

COPYRIGHT and LICENCE

Copyright (c) 1997..2014 Aldo Calpini. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.