process.pm

source of perl for linux application,

the SystemAtomTable().

=over

=item	AddAtom($name, [$atomtable])

Returns the atom; increments the use count unless $name is a name of an
integer atom.

=item	FindAtom($name, [$atomtable])

Returns the atom if it exists, 0 otherwise (actually, croaks).

=item	DeleteAtom($name, [$atomtable])

Decrements the use count unless $name is a name of an integer atom.
When count goes to 0, association of the name to an integer is removed.
(Version with prepended underscore returns 0 on success.)

=item	AtomName($atom, [$atomtable])

Returns the name of the atom.  Integer atoms have names of format C<"#ddddd">
of variable length up to 7 chars.

=item	AtomLength($atom, [$atomtable])

Returns the length of the name of the atom.  Return of 0 means that no
such atom exists (but usually croaks in such a case).

Integer atoms always return length 6.

=item	AtomUsage($name, [$atomtable])

Returns the usage count of the atom.

=item	SystemAtomTable()

Returns central atom table accessible to any process.

=item	CreateAtomTable( [ $initial, [ $buckets ] ] )

Returns new per-process atom table.  See docs for WinCreateAtomTable(3).

=item	DestroyAtomTable($atomtable)

Dispose of the table. (Version with prepended underscore returns 0 on success.)


=back

=head2 Alerting the user

=over

=item Alarm([$type])

Audible alarm of type $type (defaults to C<WA_ERROR=2>).  Other useful
values are C<WA_WARNING=0>, C<WA_NOTE=1>.  (What is C<WA_CDEFALARMS=3>???)

The duration and frequency of the alarms can be changed by the 
OS2::SysValues_set(). The alarm frequency is defined to be in the range 0x0025
through 0x7FFF. The alarm is not generated if system value SV_ALARM is set
to FALSE. The alarms are dependent on the device capability.

=item FlashWindow($hwnd, $doFlash)

Starts/stops (depending on $doFlash being TRUE/FALSE) flashing the window
$hwnd's borders and titlebar.  First 5 flashes are accompanied by alarm beeps.

Example (for VIO applications):

  { my $morph = OS2::localMorphPM->new(0);
    print STDERR "Press ENTER!\n";
    FlashWindow(process_hwnd, 1);
    <>;
    FlashWindow(process_hwnd, 0);
  }

Since flashing window persists even when application ends, it is very
important to protect the switching off flashing from non-local exits.  Use
the class C<OS2::localFlashWindow> for this.  Creating the object of this
class starts flashing the window until the object is destroyed.  The above
example becomes:

  print STDERR "Press ENTER!\n";
  { my $flash = OS2::localFlashWindow->new( process_hwnd );
    <>;
  }

B<Notes from IBM docs:> Flashing a window brings the user's attention to a
window that is not the active window, where some important message or dialog
must be seen by the user. 

Note:  It should be used only for important messages, for example, where some
component of the system is failing and requires immediate attention to avoid
damage. 

=item MessageBox($text, [ $title, [$flags, ...] ])

Shows a simple messagebox with (optional) icon, message $text, and one or
more buttons to dismiss the box.  Returns the indicator of which action was
taken by the user.  If optional argument $title is not given,
the title is constructed from the application name.  The optional argument
$flags describes the appearance of the box; the default is to have B<Cancel>
button, I<INFO>-style icon, and a border for moving.  Flags should be
a combination of

 Buttons on the box: or Button Group
     MB_OK                 OK
     MB_OKCANCEL           both OK and CANCEL
     MB_CANCEL             CANCEL
     MB_ENTER              ENTER
     MB_ENTERCANCEL        both ENTER and CANCEL
     MB_RETRYCANCEL        both RETRY and CANCEL
     MB_ABORTRETRYIGNORE   ABORT, RETRY, and IGNORE
     MB_YESNO              both YES and NO
     MB_YESNOCANCEL        YES, NO, and CANCEL

 Color or Icon 
     MB_ICONHAND           a small red circle with a red line across it. 
     MB_ERROR              a small red circle with a red line across it. 
     MB_ICONASTERISK       an information (i) icon. 
     MB_INFORMATION        an information (i) icon. 
     MB_ICONEXCLAMATION    an exclamation point (!) icon. 
     MB_WARNING            an exclamation point (!) icon. 
     MB_ICONQUESTION       a question mark (?) icon. 
     MB_QUERY              a question mark (?) icon. 
     MB_NOICON             No icon.

 Default action (i.e., focussed button; default is MB_DEFBUTTON1)
     MB_DEFBUTTON1         The first button is the default selection.
     MB_DEFBUTTON2         The second button is the default selection. 
     MB_DEFBUTTON3         The third button is the default selection. 

 Modality indicator 
     MB_APPLMODAL                  Message box is application modal (default).
     MB_SYSTEMMODAL                Message box is system modal. 

 Mobility indicator 
     MB_MOVEABLE                   Message box is moveable. 

With C<MB_MOVEABLE> the message box is displayed with a title bar and a
system menu, which shows only the Move, Close, and Task Manager choices, 
which can be selected either by use of the pointing device or by
accelerator keys.  If the user selects Close, the message box is removed
and the usResponse is set to C<MBID_CANCEL>, whether or not a cancel button 
existed within the message box. 

C<Esc> key dismisses the dialogue only if C<CANCEL> button is present; the
return value is C<MBID_CANCEL>.

With C<MB_APPLMODAL> the owner of the dialogue is disabled; therefore, do not
specify the owner as the parent if this option is used.

Additionally, the following flag is possible, but probably not very useful:
  
 Help button 
     MB_HELP             a HELP button appears, which sends a WM_HELP
				 message is sent to the window procedure of the
				 message box. 

Other optional arguments: $parent window, $owner_window, $helpID (used with
C<WM_HELP> message if C<MB_HELP> style is given).

The return value is one of

  MBID_ENTER           ENTER was selected 
  MBID_OK              OK was selected 
  MBID_CANCEL          CANCEL was selected 
  MBID_ABORT           ABORT was selected 
  MBID_RETRY           RETRY was selected 
  MBID_IGNORE          IGNORE was selected 
  MBID_YES             YES was selected 
  MBID_NO              NO was selected 

  0		           Function not successful; an error occurred. 

B<BUGS???> keyboard transversal by pressing C<TAB> key does not work.
Do not appear in window list, so may be hard to find if covered by other
windows.

=item _MessageBox($text, [ $title, [$flags, ...] ])

Similar to MessageBox(), but the default $title does not depend on the name
of the script.

=item MessageBox2($text, [ $buttons_Icon, [$title, ...] ])

Similar to MessageBox(), but allows more flexible choice of button texts
and the icon. $buttons_Icon is a reference to an array with information about
buttons and the icon to use; the semantic of this array is the same as
for argument list of process_MB2_INFO().  The default value will show
one button B<Dismiss> which will return C<0x1000>.

Other optional arguments are the same as for MessageBox().

B<NOTE.> Remark about C<MBID_CANCEL> in presence of C<MB_MOVABLE> is
equally applicable to MessageBox() and MessageBox2().

Example:

  print MessageBox2
    'Foo prints 100, Bar 101, Baz 102',
    [['~Foo' => 100, 'B~ar' => 101, ['Ba~z'] => 102]],
    'Choose a number to print';

will show a messagebox with

=over 20

=item Title

B<Choose a number to print>,

=item Text

B<Foo prints 100, Bar 101, Baz 102>

=item Icon

INFORMATION ICON

=item Buttons

B<Foo>, B<Bar>, B<Baz>

=item Default button

B<Baz>

=item accelerator keys

B<F>, B<a>, and B<z>

=item return values

100, 101, and 102 correspondingly,

=back

Using

  print MessageBox2
    'Foo prints 100, Bar 101, Baz 102',
    [['~Foo' => 100, 'B~ar' => 101, ['Ba~z'] => 102], 'SP#22'],
    'Choose a number to print';

will show the 22nd system icon as the dialog icon (small folder icon).

=item _MessageBox2($text, $buttons_Icon_struct, [$title, ...])

low-level workhorse to implement MessageBox2().  Differs by the dafault
$title, and that $buttons_Icon_struct is required, and is a string with
low-level C struct.

=item process_MB2_INFO($buttons, [$iconID, [$flags, [$notifyWindow]]])

low-level workhorse to implement MessageBox2(); calculates the second
argument of _MessageBox2().  $buttons is a reference
to array of button descriptions.  $iconID is either an ID of icon for
the message box, or a string of the form C<"SP#number">; in the latter case
the number's system icon is chosen; this field is ignored unless
$flags contains C<MB_CUSTOMICON> flag.  $flags has the same meaning as mobility,
modality, and icon flags for MessageBox() with addition of extra flags

     MB_CUSTOMICON         Use a custom icon specified in hIcon. 
     MB_NONMODAL           Message box is nonmodal

$flags defaults to C<MB_INFORMATION> or C<MB_CUSTOMICON> (depending on whether
$iconID is non-0), combined with MB_MOVABLE.

Each button's description takes two elements of the description array,
appearance description, and the return value of MessageBox2() if this
button is selected.  The appearance description is either an array reference
of the form C<[$button_Text, $button_Style]>, or the same without
$button_Style (then style is C<BS_DEFAULT>, making this button the default)
or just $button_Text (with "normal" style).  E.g., the list

  Foo => 100, Bar => 101, [Baz] => 102

will show three buttons B<Foo>, B<Bar>, B<Baz> with B<Baz> being the default
button; pressing buttons return 100, 101, or 102 correspondingly.

In particular, exactly one button should have C<BS_DEFAULT> style (e.g.,
given as C<[$button_Name]>); otherwise the message box will not have keyboard
focus!  (The only exception is the case of one button; then C<[$button_Name]>
can be replaced (for convenience) with plain C<$button_Name>.)

If text of the button contains character C<~>, the following character becomes
the keyboard accelerator for this button.  One can also get the handle
of system icons directly, so C<'SP#22'> can be replaced by
C<OS2::Process::get_pointer(22)>; see also C<SPTR_*> constants.

B<NOTE> With C<MB_NONMODAL> the program continues after displaying the
nonmodal message box.  The message box remains visible until the owner window
destroys it. Two notification messages, WM_MSGBOXINIT and WM_MSGBOXDISMISS,
are used to support this non-modality. 

=item LoadPointer($id, [$module, [$hwnd]])

Loads a handle for the pointer $id from the resources of the module
$module on desktop $hwnd.  If $module is 0 (default), loads from the main
executable; otherwise from a DLL with the handle $module.

The pointer is owned by the process, and is destroyed by
DestroyPointer() call, or when the process terminates.

=item SysPointer($id, [$copy, [$hwnd]])

Gets a handle for (a copy of) the system pointer $id (the value should
be one of C<SPTR_*> constants).  A copy is made if $copy is TRUE (the
default).  $hwnd defaults to C<HWND_DESKTOP>.

=item get_pointer($id, [$copy, [$hwnd]])

Gets (and caches) a copy of the system pointer.

=back

=head2 Constants used by OS/2 APIs

Function C<os2constant($name)> returns the value of the constant; to
decrease the memory usage of this package, only the constants used by
APIs called by Perl functions in this package are made available.

For direct access, see also the L<"EXPORTS"> section; the latter way
may also provide some performance advantages, since the value of the
constant is cached.

=head1 OS2::localMorphPM, OS2::localFlashWindow, and OS2::localClipbrd classes

The class C<OS2::localMorphPM> morphs the process to PM for the duration of
the given scope.

  {
    my $h = OS2::localMorphPM->new(0);
    # Do something
  }

The argument has the same meaning as one to OS2::MorphPM().  Calls can
nest with internal ones being NOPs.

Likewise, C<OS2::localClipbrd> class opens the clipboard for the duration
of the current scope; if TRUE optional argument is given, it would not
morph the application into PM:

  {
    my $handle = OS2::localClipbrd->new(1);	# Do not morph into PM
    # Do something with clipboard here...
  }

C<OS2::localFlashWindow> behaves similarly; see
L<"FlashWindow($hwnd,$doFlash)">.

=head1 EXAMPLES

The test suite for this module contains an almost comprehensive collection
of examples of using the API of this module.

=head1 TODO

Add tests for:

	SwitchToProgram
	ClassName
	out_codepage
	out_codepage_set
	in_codepage
	in_codepage_set
	cursor
	cursor_set
	screen
	screen_set
	process_codepages
	QueryWindow
	EnumDlgItem
        WindowPtr
        WindowUShort
        SetWindowBits
        SetWindowPtr
        SetWindowULong
        SetWindowUShort
	my_type
	file_type
	scrsize
	scrsize_set

Document: InvalidateRect,
CreateFrameControls, kbdChar, kbdhChar,
kbdStatus, _kbdStatus_set, kbdhStatus, kbdhStatus_set,
vioConfig, viohConfig, vioMode, viohMode, viohMode_set, _vioMode_set,
_vioState, _vioState_set, vioFont, vioFont_set

Test: SetWindowULong/Short/Ptr, SetWindowBits. InvalidateRect,
CreateFrameControls, ClipbrdOwner_set, ClipbrdViewer_set, _ClipbrdData_set,
Alarm, FlashWindow, _MessageBox, MessageBox, _MessageBox2, MessageBox2,
LoadPointer, SysPointer, kbdChar, kbdhChar, kbdStatus, _kbdStatus_set,
kbdhStatus,  kbdhStatus_set, vioConfig, viohConfig, vioMode, viohMode,
viohMode_set, _vioMode_set, _vioState, _vioState_set, vioFont, vioFont_set

Implement SOMETHINGFROMMR.


  >But I wish to change the default button if the user enters some
  >text into an entryfield.  I can detect the entry ok, but can't
  >seem to get the button to change to default.
  >
  >No matter what message I send it, it's being ignored.

  You need to get the style of the buttons using WinQueryWindowULong/QWL_STYLE,
  set and reset the BS_DEFAULT bits as appropriate and then use
  WinSetWindowULong/QWL_STYLE to set the button style.
  Something like this:
    hwnd1 = WinWindowFromID (hwnd, id1);
    hwnd2 = WinWindowFromID (hwnd, id2);
    style1 = WinQueryWindowULong (hwnd1, QWL_STYLE);
    style2 = WinQueryWindowULong (hwnd2, QWL_STYLE);
    style1 |= style2 & BS_DEFAULT;
    style2 &= ~BS_DEFAULT;
    WinSetWindowULong (hwnd1, QWL_STYLE, style1);
    WinSetWindowULong (hwnd2, QWL_STYLE, style2);

 > How to do query and change a frame creation flags for existing window?

 Set the style bits that correspond to the FCF_* flag for the frame
 window and then send a WM_UPDATEFRAME message with the appropriate FCF_*
 flag in mp1.

 ULONG ulFrameStyle;
 ulFrameStyle = WinQueryWindowULong( WinQueryWindow(hwnd, QW_PARENT),
 QWL_STYLE );
 ulFrameStyle = (ulFrameStyle & ~FS_SIZEBORDER) | FS_BORDER;
 WinSetWindowULong(   WinQueryWindow(hwnd, QW_PARENT),
                      QWL_STYLE,
                      ulFrameStyle );
 WinSendMsg( WinQueryWindow(hwnd, QW_PARENT),
             WM_UPDATEFRAME,
             MPFROMP(FCF_SIZEBORDER),