Win32::GUI methods

AbsLeft()

Returns the absolute (screen) window x coordinate; use this to get the onscreen position of a child window, eg. a button or a label. This method returns -1 on errors.

See also: "Left()"

Applies to: Animation, Button, Checkbox, Class, Combobox, ComboboxEx, DateTime, DialogBox, Graphic, Groupbox, Header, Label, Listbox, ListView, ProgressBar, RadioButton, Rebar, RichEdit, Slider, Splitter, StatusBar, TabStrip, Textfield, Toolbar, TreeView, UpDown, Window, Tooltip(*)

AbsTop()

Returns the absolute (screen) window y coordinate; use this to get the onscreen position of a child window, eg. a button or a label. This method returns -1 on errors.

See also: Top()

Add(STRING, STRING .. STRING)

Adds one or more items at the end of the control's list.

Applies to: Combobox, Listbox

AddString( STRING )

Adds an item at the end of the control's list.

Applies to: Combobox, Listbox

Arrange( [FLAG] )

Arranges items in the ListView; the optional FLAG parameter can be one of the following values:

0  uses the current alignment style (this is the default)
1  align items along the left edge of the window
2  align items along the top edge of the window
5  snaps icons to the nearest grid position

Applies to: ListView

BackColor( [COLOR] )

Sets the background color of the RichEdit control; if no COLOR is specified, the background color is reset to the default system color.

Applies to: RichEdit

BandCount()

Returns the number of bands in the Rebar control.

Applies to: Rebar

BringWindowToTop()

Brings the window to the foreground.

Applies to: DialogBox, Window

BrowseForFolder( OPTIONS )

Displays the standard "Browse For Folder" dialog box. Returns the selected item's name, or undef if no item was selected or an error occurred.

Note that BrowseForFolder must be called as a standalone function, not as a method.

Example:

$folder = Win32::GUI::BrowseForFolder(
	-root => "C:\\Program Files",
	-includefiles => 1,
);

Options: -computeronly, -domainonly, -driveonly, -editbox, -folderonly, -includefiles, -owner, -printeronly, -root, -title

Caption( [TEXT] )

See Text().

ChangeCursor( CURSOR )

Changes the default cursor for a window to CURSOR (a Win32::GUI::Cursor object). Returns the handle of the previous default cursor.

ChangeIcon( ICON )

Changes the default icon for a window to ICON (a Win32::GUI::Icon object). Returns the handle of the previous default icon.

See also: ChangeSmallIcon()

Applies to: DialogBox, Window

ChangeSmallIcon( ICON )

Changes the default small icon for a window to ICON (a Win32::GUI::Icon object). Returns the handle of the previous default small icon.

See also: ChangeIcon()

Applies to: DialogBox, Window

Clear()

See Reset().

ClipCursor( [LEFT, TOP, RIGHT, BOTTOM] )

Confines the cursor to the specified screen rectangle. Call it without parameters to release the cursor. Returns nonzero on success, zero on failure.

Close()

Closes the opened AVI file.

See also: Open()

Applies to: Animation

CloseWindow()

Minimizes a window.

Applies to: DialogBox, Window

CommDlgExtendedError()

Returns the last common dialog library error code.

Count()

Returns the number of items in the control.

Applies to: Combobox, Listbox

DeleteBand()

Deletes the zero-based INDEX band from the Rebar.

Applies to: Rebar

Dialog()

Enter the GUI dialog phase: the script halts, the user can interact with the created windows and events subroutines are triggered as necessary; note that this function must be called without ANY parameter or instantiation (eg. don't call it as method of a created object):

Win32::GUI::Dialog(); # correct
$Window->Dialog();    # !!!WRONG!!!

Disable()

Disables a window.

See also: Enable(), IsEnabled()

DoEvents()

Just like Dialog(), but returns when there are no more events to process.

DrawMenuBar()

Forces redrawing of the menu bar.

Applies to: DialogBox, Window

Enable( [FLAG] )

Enables a window (or disables it if FLAG is FALSE).

See also: Disable(), IsEnabled()

EnsureVisible( ITEM, [FLAG] )

For TreeView, ensures that the specified ITEM (a node handle) is visible in the control.

For ListView, ensures that the specified ITEM (zero-based index) is visible in the control (FLAG to be defined...).

Applies to: ListView, TreeView

Expand( NODE, [FLAG] )

Opens a NODE of the TreeView; the optional FLAG parameter can indicate different operations:

1 expand (this is the default)
2 collapse
3 toggle (expand if it was collapsed and collapse if it was expanded)

Applies to: TreeView

FindString( STRING, [INDEX] )

Searches the control for an item that begins with the specified STRING. The optional INDEX parameter tells to start the search from the specified position; if no parameter is given, the whole list is searched. Returns the zero-based index of the found item or -1 if no matching item was found.

See also: SelectString(), FindStringExact()

Applies to: Combobox, Listbox

FindStringExact( STRING, [INDEX] )

Searches the control for an item that exactly matches the specified STRING (case insensitively). The optional INDEX parameter tells to start the search from the specified position; if no parameter is given, the whole list is searched. Returns the zero-based index of the found item or -1 if no matching item was found.

See also: FindString()

Applies to: Combobox, Listbox

FindWindow( CLASSNAME, TITLE )

Returns the handle of the window whose class name and window title match the specified strings; both strings can be empty. Note that the function does not search child windows, only top level windows. If no matching windows is found, the return value is zero.

FirstVisible( [NODE] )

Gets or sets the first visible NODE in the TreeView; if a NODE is given, it is selected and, if possible, it becomes the first visible one; the return value is the handle of the previously first visible. If no NODE is given, returns the handle of the current first visible one.

Applies to: TreeView

FirstVisibleItem( [INDEX] )

Gets the zero-based index of the first visible item in the control, or sets it to the specified INDEX.

Applies to: Combobox, Listbox

GetActiveWindow()

Returns the handle of the active window.

GetClassName()

Returns the classname of the specified window, or undef on errors.

GetClientRect()

Returns a four elements array defining the windows client area rectangle (left, top, right, bottom) or undef on errors.

See also: GetWindowRect()

GetCursor()

Returns the handle of the current cursor.

GetCursorPos()

Returns a two elements array containing the x and y position of the cursor, or undef on errors.

See also: SetCursorPos()

GetFocus()

Returns the handle of the window that has the keyboard focus.

GetFont(FONT)

Gets the font of the window (returns an handle; use

$Font = $W->GetFont();
%details = Win32::GUI::Font::Info( $Font );

to get font details).

Applies to: Animation, Button, Checkbox, Combobox, ComboboxEx, DateTime, DialogBox, Graphic, Groupbox, Header, Label, Listbox, ListView, ProgressBar, RadioButton, Rebar, RichEdit, Slider, Splitter, StatusBar, TabStrip, Textfield, Toolbar, TreeView, UpDown, Window

GetFontName()

Returns the name of the font used in the window.

GetLastVisible()

Returns the handle of the last expanded node in the TreeView.

Applies to: TreeView

GetMenu()

Returns the handle of the menu associated with the window (note: the handle, not the Win32::GUI::Menu object).

Applies to: DialogBox, Window

GetMessage( [MIN, MAX] )

Retrieves a message sent to the window, optionally considering only messages identifiers in the range MIN..MAX; if a message is found, the function returns a 7 elements array containing:

the result code of the message
the message identifier
the wParam argument
the lParam argument
the time when message occurred
the x coordinate at which message occurred
the y coordinate at which message occurred

If the result code of the message was -1 the function returns undef. Note that this function should not be normally used unless you know very well what you're doing.

GetNextVisible( NODE )

Returns the handle of the next visible node for the given NODE.

Applies to: TreeView

GetOpenFileName( OPTIONS )

Displays the standard 'Open File' dialog box; the return value is the name of the choosen file or undef on errors.

Options: -directory, -file, -filter, -owner, -title

GetPerlWindow()

Returns the handle of the DOS Prompt window your perl script is running in; if called in an array context, returns the handle and the HINSTANCE of your perl process.

Example:

$DosPrompt = Win32::GUI::GetPerlWindow();
Win32::GUI::Hide( $DosPrompt );

# your program goes here...

Win32::GUI::Show( $DosPrompt );

GetPrevVisible(NODE)

Returns the handle of the previous visible node for the given NODE.

Applies to: TreeView

GetStockObject( OBJECT )

Returns the handle of the specified predefined system object (pen, brush or font). OBJECT can have one of the following values:

 0	WHITE_BRUSH
 1	GRAY_BRUSH
 2	LTGRAY_BRUSH
 3	DKGRAY_BRUSH
 4	BLACK_BRUSH
 5	NULL_BRUSH (also HOLLOW_BRUSH)
 6	WHITE_PEN
 7	BLACK_PEN
 8	NULL_PEN
10	OEM_FIXED_FONT
11	ANSI_FIXED_FONT
12	ANSI_VAR_FONT
13	SYSTEM_FONT
14	DEVICE_DEFAULT_FONT
15	DEFAULT_PALETTE
16	SYSTEM_FIXED_FONT
17	DEFAULT_GUI_FONT

The returned handle can be referenced as if it was a Win32::GUI object of the corresponding type (eg. a Win32::GUI::Brush or Win32::GUI::Font), but note that it is not blessed, so you can't directly invoke methods on it:

$Font = Win32::GUI::GetStockObject(17);    # DEFAULT_GUI_FONT
print $Font->GetMetrics();                 # !!!WRONG!!!
print Win32::GUI::Font::GetMetrics($Font); # correct
$Window->SetFont($Font);                   # correct

GetStringWidth( STRING )

Returns the width, in pixels, needed to display the specified STRING in the ListView area.

Applies to: ListView

GetTextExtentPoint32( STRING, [FONT] )

Returns a two elements array containing the x and y size of the specified STRING in the window (eventually with the speficied FONT), or undef on errors.

GetWindowRect()

Returns a four elements array defining the windows (external) rectangle (left, top, right, bottom) or undef on errors.

See also: GetClientRect()

Height( [HEIGHT] )

Gets or sets the window height.

See also: "Width"

Hide()

Hides a window.

HitTest( X, Y )

Checks if the specified point in the control area is occupied by an item; it returns the identifier of the found item or zero if none was found. If called in an array context, it returns an additional value containing more info about the position of the specified point [TBD].

Applies to: ListView, TreeView

Indent( [VALUE] )

Gets or sets the indentation width, in pixels, between parents and child nodes; if the VALUE is less than the system-defined minimum, it is set to the system-defined minimum.

Applies to: TreeView

InsertBand( OPTIONS )

Inserts a new band in the Rebar control.

#   -index => position or -1 to add it at the end, default -1
#   -image => index of an image from the associated ImageList
#   -bitmap => Win32::GUI::Bitmap object
#   -child => child control
#   -foreground => COLOR
#   -background  => COLOR
#   -width => pixels
#   -minwidth => pixels
#   -minheight => pixels
#   -text => string

Applies to: Rebar

Options: -background, -bitmap, -child, -foreground, -image, -index, -minheight, -minwidth, -text, -width

Interval( [ELAPSE] )

Changes the timeout value of the Timer to ELAPSE milliseconds, or returns the current timeout value if no parameter is specified. If ELAPSE is 0, the Timer is disabled; can also be used to resume a Timer after a Kill().

See also: Kill()

Applies to: Timer

InvalidateRect(...)

Forces a refresh of a window, or a rectangle of it. The parameters can be (FLAG) for the whole area of the window, or (LEFT, TOP, RIGHT, BOTTOM, [FLAG]) to specify a rectangle. If the FLAG parameter is set to TRUE, the background is erased before the window is refreshed (this is the default).

See also: Update()

InvertRect( LEFT, TOP, RIGHT, BOTTOM )

Inverts the content of the rectangle from LEFT, TOP to RIGHT, BOTTOM. Returns nonzero if succesful, zero on errors.

Applies to: DC

IsEnabled()

Returns TRUE if the window is enabled, FALSE otherwise.

IsIconic()

Returns TRUE if the window is minimized, FALSE otherwise.

Applies to: DialogBox, Window

IsVisible()

Returns TRUE if the window is visible, FALSE otherwise.

IsWindow()

Returns TRUE if the window is a window, FALSE otherwise.

IsZoomed()

Returns TRUE if the window is maximized, FALSE otherwise.

Applies to: DialogBox, Window

ItemCheck( ITEM, [VALUE] )

For TreeView, gets or sets the check state of the given ITEM (a node handle).

For ListView, gets the check state of the given item (zero-based index); ListView does not support setting check states, so you can't pass a VALUE.

In both cases is valid only if the control was created with the -checkboxes => 1 option.

Applies to: ListView, TreeView

ItemFromPoint( X, Y )

Returns the zero-based index of the item nearest to the specified point; if called in a list context, returns an additional element which is TRUE if the point is inside the control area, FALSE if it's outside.

Applies to: Listbox

ItemPosition( INDEX, [X, Y] )

Moves the specified zero-based INDEX item to the specified position, or returns its current X and Y position if X and Y are not given.

See also: MoveItem()

Applies to: ListView

Kill()

Disables the Timer.

See also: Interval()

Applies to: Timer

Left ( [LEFT] )

Gets or sets the window X coordinate. If the window is a top level window (a Window or a DialogBox) the value is relative to the screen (absolute), otherwise it is relative to the container of the control. To get the absolute (screen position) of a child control, use AbsLeft() instead.

See also: AbsLeft(), Top()

LineFromChar( INDEX )

Returns the line number (starting from zero) where the zero-based INDEX char appears.

Applies to: RichEdit, Textfield

ListIndex()

See SelectedItem()

Load( FILENAME, [FORMAT] )

Loads a file named FILENAME into the RichEdit control. By default the file is a RTF (Rich Text Format) file; if you want to load a plain text file, you can set FORMAT to 1.

Applies to: RichEdit

MaxLength( [CHARS] )

Limits the number of characters that the Textfield accept to CHARS, or returns the current limit if no argument is given. To remove the limit (eg. set it to the maximum allowed which is 32k for a single-line Textfield and 64k for a multiline one) set CHARS to 0.

Applies to: RichEdit, Textfield

Minimize()

See CloseWindow()

Modified( [FLAG] )

Gets or sets the modified flag on the control.

Applies to: RichEdit, Textfield

Move( X, Y )

Moves the window to the specified position.

MoveItem( INDEX, X, Y )

Moves the specified zero-based INDEX item to the specified position, if the ListView is in big or small icon view mode; X and Y coordinates are relative to the ListView client area.

See also: ItemPosition(), View()

Applies to: ListView

Open( FILE )

Opens the specified AVI file in the Animation control; note that the AVI file must not contain sound data.

See also: Close()

Applies to: Animation

OpenIcon()

Restores a minimized window.

Applies to: DialogBox, Window

PasswordChar( [CHAR] )

Gets or sets the character displayed in place of normal text; if the control has been created with the -password option, the default character is an asterisk (*). Note that by setting this value the text in the control will be redrawn using the specified character; if the character is set to zero instead, text will be redrawn as normal

Applies to: RichEdit, Textfield

Play( [FROM], [TO], [REPEAT] )

Plays the animation (eventually from the FROM frame to the TO frame) looping it REPEAT times. Defaults are FROM 0 (the first frame) to -1 (the last frame) and REPEAT -1 (loop forever).

Applies to: Animation

ReadOnly( [FLAG] )

Gets or sets the readonly flag on the control.

Applies to: RichEdit, Textfield

Rectangle( LEFT, TOP, RIGHT, BOTTOM )

Draws a rectangle from LEFT, TOP to RIGHT, BOTTOM; the rectangle is outlined with the current pen and filled with the current brush. Returns nonzero if succesful, zero on errors.

Applies to: DC

ReplaceSel( STRING, [FLAG] )

Replaces the current selection in the control with STRING.

Applies to: RichEdit, Textfield

Reset()

Deletes the content of the control.

Applies to: Combobox, Listbox

Resize( X, Y )

Resizes the window to the specified dimension.

Restore()

See OpenIcon()

RowCount()

Returns the number of rows in the Rebar control.

Applies to: Rebar

Save( FILENAME, [FORMAT] )

Saves the content of the RichEdit control in a file named FILENAME. By default the file is a RTF (Rich Text Format) file; if you want to save in a plain text file, you can set FORMAT to 1.

Applies to: RichEdit

ScaleHeight()

Returns the windows client area height.

See also: ScaleWidth()

ScaleWidth()

Returns the windows client area width.

See also: ScaleHeight()

Scroll( COMMAND | LINE | HORIZONTAL, VERTICAL )

Scrolls the text in the control; you have the following options:

COMMAND

the following commands are recognized (their meaning is self-explanatory):

up
down
pageup		
pagedown	
top
bottom

LINE

scrolls up or down the specified number of lines; use negative to scroll up and positive to scroll down.

HORIZONTAL, VERTICAL

scrolls VERTICAL lines vertically and HORIZONTAL characters horizontally; note that the RichEdit control does not support horizontal scroll.

Applies to: RichEdit, Textfield

Seek( FRAME )

Positions the AVI file to the specified FRAME.

Applies to: Animation

SelectAll()

Selects all the text.

Applies to: RichEdit, Textfield

SelectCount()

Returns the number of currently selected items.

For Listbox, the control must have been created with the -multisel option.

Applies to: Listbox, ListView

SelectString( STRING, [INDEX] )

Searches the control for an item that begins with the specified STRING and, if found, selects that item. The optional INDEX parameter tells to start the search from the specified position; if no parameter is given, the whole list is searched. Returns the zero-based index of the selected item or -1 if no matching item was found.

See also: FindString()

Applies to: Listbox

SelectedItem()

Returns the zero-based index of the currently selected item, or -1 if no item is selected.

Applies to: Combobox, Listbox

Selection()

Returns a two elements array containing the current selection start and end.

Applies to: RichEdit, Textfield

SetCursor( CURSOR )

Draws the specified CURSOR (a Win32::GUI::Cursor object). Returns the handle of the previously displayed cursor. Note that the cursor will change back to the default one as soon as the mouse moves or a system command is performed. To change the cursor stablily, use ChangeCursor() instead.

See also: ChangeCursor()

SetCursorPos( X, Y )

Moves the cursor to the specified coordinates.

See also: GetCursorPos()

SetRange( [MIN], MAX )

Sets the range of values (from MIN to MAX) for the control; if MIN is not specified, it defaults to 0.

Applies to: ProgressBar

Show( [COMMAND] )

Shows a window (or change its showing state to COMMAND); available COMMANDs are:

SW_HIDE
SW_MAXIMIZE
SW_MINIMIZE
SW_RESTORE
SW_SHOW
SW_SHOWDEFAULT
SW_SHOWMAXIMIZED
SW_SHOWMINIMIZED
SW_SHOWMINNOACTIVE
SW_SHOWNA
SW_SHOWNOACTIVATE
SW_SHOWNORMAL

The default COMMAND, if none specified, is SW_SHOWNORMAL.

Stop()

Stops the animation currently playing.

See also: Play()

Applies to: Animation

Text( [TEXT] )

Gets or sets the text of a window.

Applies to: Button, Checkbox, Combobox, ComboboxEx, DateTime, DialogBox, Groupbox, Header, Label, Listbox, RadioButton, RichEdit, StatusBar, Textfield, Toolbar, UpDown, Window

TextOut( X, Y, TEXT )

Draws the specified TEXT string at X, Y, using the currently selected font. Returns nonzero if succesful, zero on errors.

Applies to: DC

Top( [TOP] )

Gets or sets the window Y coordinate. If the window is a top level window (a Window or a DialogBox) the value is relative to the screen (absolute), otherwise it is relative to the container of the control. To get the absolute (screen position) of a child control, use AbsTop() instead.

See also: AbsTop(), "Left()"

Undo()

Undoes the last change in the control.

Applies to: RichEdit, Textfield

Update()

Refreshes the content of a window.

See also: InvalidateRect()

View( [MODE] )

Gets or sets the viewing mode of the ListView control; the returned or given MODE can have one of the following values:

0  big icons
1  details
2  small icons
3  list

Applies to: ListView

VisibleCount()

Returns the number of items that can be fully visible in a page of the control; for ListView, if the current view state is big or small icons, the function always returns the total number of items in the control.

Applies to: ListView, TreeView

Width( [WIDTH] )

Gets or sets the window width.

See also: "Height"

WindowFromPoint( X, Y )

Returns the handle of the window at the specified screen position.

To install Win32::GUI, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Win32::GUI

CPAN shell

perl -MCPAN -e shell
install Win32::GUI

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)