NAME

SYNOPSIS

 use Win32::FFI::BrowseForFolder; 

 $bff = Win32::FFI::BrowseForFolder->new(   -initial => CSIDL_DESKTOP,   -folder  => "c:\\perl",   -title   => "TESt WiNdOw",   -text    => "This window is very useful for blah, blah, blah-blah  and much more.",   -width   => 400,   -height  => 250,   -status  => 1,   -regexp  => '^(?i)[cd]:',  ); 

 $bff->callback(\&mycallback);  $dir = $bff->show;  print "$dir\n"; 

ABSTRACT

The working FFI module is needed for this module to work - it could be found at CPAN but on Win32 you should have MSVC++ to compile it.

Note that if you just want a simple default view you should better use Win32::FileOp (http://jenda.krynicky.cz/) module that provides lots more features other then browsing for folder.

The current version of the module is available at:

  /guest/fno/perl/ 

DESCRIPTION

The ``BrowseForFolder'' dialog box consists of:

 - window's title  - text label that could be long and multilined; the current callback    function does not allow you to change it's content between    users clicks (class Static)  - small one-line status field (class Static)  - directory tree (class SysTreeView32)  - "OK" and "Cancel" buttons   . 

The current callback function will automatically adjust the fields that are in use (calculating texts length) to fit the specified dialog box width and height. And to look well, I hope.

new ( )

Basic constructor. It accepts named parameters both as a hash or a hash ref. I.e.

  $obj = Win32::FFI::BrowseForFolder->new(      -width   => 400,      -height  => 250,   ); 

or

  $param = {      -width   => 400,      -height  => 250,   };   $obj = Win32::FFI::BrowseForFolder->new( $param ); 

are equivalent calls.

The following keys have meaning (any or all of them could be omitted):

   -initial    -folder    -flags    -regexp    -status    -title    -text    -width    -height    -callback    -owner   версия для печати 

Values sent to the new() constructor could be changed later by using the correspondent methods. Each of the following methods accept exactly one parameter. If called with or without the parameter they return the current value.

initial ( )

One of the CSIDL_ constants specifying one of the system directories - ``root'' folder to browse from. Only the specified folder and its subfolders appear in the dialog box. If omitted the name space root (the desktop folder) is used.

CSIDL_BITBUCKET

Recycle bin --- file system directory containing file objects in the user's recycle bin. The location of this directory is not in the registry; it is marked with the hidden and system attributes to prevent the user from moving or deleting it.

CSIDL_CONTROLS

Control Panel --- virtual folder containing icons for the control panel applications.

CSIDL_DESKTOP

Windows desktop --- virtual folder at the root of the name space.

CSIDL_DESKTOPDIRECTORY

File system directory used to physically store file objects on the desktop (not to be confused with the desktop folder itself).

CSIDL_DRIVES

My Computer --- virtual folder containing everything on the local computer: storage devices, printers, and Control Panel. The folder may also contain mapped network drives.

CSIDL_FONTS

Virtual folder containing fonts.

CSIDL_NETHOOD

File system directory containing objects that appear in the network neighborhood.

CSIDL_NETWORK

Network Neighborhood --- virtual folder representing the top level of the network hierarchy.

CSIDL_PERSONAL

File system directory that serves as a common repository for documents.

CSIDL_PRINTERS

Printers folder --- virtual folder containing installed printers.

CSIDL_PROGRAMS

File system directory that contains the user's program groups (which are also file system directories).

CSIDL_RECENT

File system directory that contains the user's most recently used documents.

CSIDL_SENDTO

File system directory that contains Send To menu items.

CSIDL_STARTMENU

File system directory containing Start menu items.

CSIDL_STARTUP

File system directory that corresponds to the user's Startup program group.

CSIDL_TEMPLATES

File system directory that serves as a common repository for document templates.

folder ( )

Folder that is opened initially.

flags ( )

Value specifying the types of folders to be listed in the dialog box as well as other options. This member can include zero or more of the following values:

BIF_BROWSEFORCOMPUTER

Only returns computers. If the user selects anything other than a computer, the OK button is grayed.

BIF_BROWSEFORPRINTER

Only returns printers. If the user selects anything other than a printer, the OK button is grayed.

BIF_DONTGOBELOWDOMAIN Does not include network folders below the domain level in the tree view control.

BIF_RETURNFSANCESTORS

Only returns file system ancestors. If the user selects anything other than a file system ancestor, the OK button is grayed.

BIF_RETURNONLYFSDIRS

Only returns file system directories. If the user selects folders that are not part of the file system, the OK button is grayed.

BIF_STATUSTEXT

Includes a status area in the dialog box. The callback function can set the status text by sending messages to the dialog box.

regexp ( )

Regular expression that specifies pathes that could be selected. If the path does not match the ``OK'' button will be grayed.

The regexp is used ``as is'' i.e. if you want to match the beginning of the string use ^, for the end of the string use $. For case-insensitive match use (?i) etc.

If this parameter is omitted ``OK'' is never grayed.

status ( )

TRUE/FALSE (the default is FALSE). This value specifies whether the status line will be used or not. If yes BIF_STATUSTEXT would be added to the API call (but not to $object-flags>). So, you don't need to add it yourself.

If this parameter is TRUE the status_handler() method is used to produce the status line. See bellow.

title ( )

``BrowseForFolder'' window's title.

text ( )

The string (might be multilined) that would be displayed in the text-field.

width ( )

``BrowseForFolder'' window's width.

height ( )

``BrowseForFolder'' window's height.

callback ( )

Reference to the callback function.

Mainly you don't need to use this parameter because the module itself provides rather complex callback function that is highly adjustable by the other parameters.

If you are using your own callback function then only ``-initial'', ``-flags'' and ``-text'' parameters work. For more look at the Win32SDK for ``BrowseCallbackProc'' or use my function as an example.

Feel free to send me your functions to improve the module.

owner ( )

Handle of the owner window. If not defined the dialog box will be bound to the perl console window or to desktop (handle = 0) if console was closed.

show ( )

This method is used to show the dialog box. It returns the selected path or undef.

status_handler ( )

This method creates one string and sends it to the status line. It is being called from the callback function. Now it displays just the selected path if the selected item has the correct path, or empty line (for example for the ``Recycle Bin'').

In most cases you don't need to use this method explicitly but it's possible to override it with your own one to return something more complex.

Your method will receive 4 parameters:

  $parent_hwnd  - dialog box handle   $label_hwnd   - status window handle (class Static)   $pIDList      - pointer to the item identifier list for the                   currently selected folder   $path         - path corresponding to this IDList 

Sure it could make some other things also. For example may be it's a good idea to count characters width (see the CalcTextSize function inside) to be sure that the path fits the dialog box's width. Or to show ``(nn folders/nn files/nn Kb)'' also.

Or you can make it regexp-dependent etc.etc.

This method is being called at the end of the callback routine, so you can use it for some post-processing.

INSTALLATION

This module requires

FFI 0.01 by Paul Moore, gustav@morpheus.demon.co.uk

CAVEATS

CHANGES

 0.02  -owner parameter is added. Dialog could be bound now to any window.        Minor fixes. 

TODO

BUGS

VERSION

Jan 19, 2007.

AUTHOR

/guest/fno/perl/

SEE ALSO

COPYRIGHT

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